Develop and package a Raydo plugin

Create a standalone plugin, verify its contract, and produce a deterministic Raydo archive.

This guide takes a developer from an empty directory to an installable dist/plugin.raydo.zip archive.

Current public versions

The Developer Preview uses create-raydo-plugin@0.1.2 and @raydoai/plugin-sdk@0.2.0. Start through the next tag so the official preview channel can advance without implying GA.

What the two npm packages do

Package	Responsibility
`create-raydo-plugin`	Creates a standalone TypeScript project, fixed scripts, a capability fixture, and the default App Connection template.
`@raydoai/plugin-sdk`	Defines plugin manifests, contributions, capabilities, schemas, permissions, fixtures, validation, testing, and deterministic packaging.

Most developers start with the scaffolder. The generated project already declares the SDK dependency.

Five-command quickstart

npm create raydo-plugin@next my-raydo-plugin -- --plugin-id acme.documents --display-name "Acme Documents" --connector-id notion
cd my-raydo-plugin
npm install
npm run verify
npm run pack

The create command is non-interactive. It does not install dependencies, send telemetry, contact Raydo, or write Raydo application state.

Generated project

The default project contains:

File	Purpose
`plugin.ts`	Typed plugin manifest, App Connection contribution, and capability contract.
`contract-fixture.ts`	Deterministic fixture output for every declared capability.
`package.json`	Fixed build, validation, test, verification, and packaging commands.
`tsconfig.json`	Standalone NodeNext TypeScript build configuration.
`README.md`	Project-local development and ownership boundaries.
`.gitignore`	Build, dependency, and archive exclusions.
`LICENSE`	MIT license for the generated project.

The default template is read-only. Add --write to the create command only when the plugin needs a reviewed write capability. The write template keeps approval and idempotency requirements enabled.

Development loop

Edit plugin.ts and keep every declared capability represented in contract-fixture.ts.

Use reviewed JSON Schema fields only. Unknown keywords, duplicate required fields, excessive nesting, and unbounded values fail validation.

Run npm run validate while changing manifests, schemas, permissions, or packaging inputs.

Run npm test to execute the declared capability fixtures.

Run npm run verify before creating a distributable archive.

Run npm run pack and retain the printed manifest and package digests with the archive.

Command reference

Command	Result
`npm run validate`	Builds the plugin and validates manifest, capability, permission, schema, portability, size, and private-material rules.
`npm test`	Builds the plugin and runs its declared contract fixture.
`npm run verify`	Runs validation followed by contract testing.
`npm run pack`	Produces `dist/plugin.raydo.zip` and prints its exact digests. It does not publish the plugin to npm or Raydo Hub.

Package identity and review

npm run pack emits two identities:

manifestDigest binds the reviewed manifest and contribution contract;
packageDigest binds the exact archive content.

Do not edit the archive after review. Any manifest or package change creates a new identity and must return to review in Raydo.

Security boundary

Never place API keys, access tokens, cookies, private signing material, raw provider bodies, or production credentials in source, fixtures, README examples, or archives.
Declare required permissions and external effects precisely.
A plugin may request a connection-backed capability; it never owns the user's credential or grant.
Plugin output must stay bounded and match its reviewed output schema.
Write capabilities retain Raydo approval and idempotency enforcement.

Continue with Distribute, install, and use a plugin.