worldliberty/agentpay-sdk/add-plugin

Add Plugin

Use this skill when the task is "add another plugin like Bitrefill" or "make plugin onboarding more reusable."

Ground Truth

• src/cli.ts is the main CLI entrypoint, but plugin-specific command trees should not be wired inline there.
• src/plugins/types.ts defines the shared CliPluginContext and the generic plugin registrar shape.
• src/plugins/index.ts is the registry for built-in plugins.
• src/plugins/bitrefill.ts is the reference implementation for a plugin that owns its own command tree.
• Plugin-specific HTTP or browser/bootstrap code belongs in src/lib/<plugin>.ts or src/lib/<plugin>/.
• Signing, policy checks, manual approval handling, and raw transaction broadcast plumbing stay on the existing AgentPay path exposed through CliPluginContext.

Default Architecture

1. Create src/plugins/<plugin>.ts.
2. Register the plugin in src/plugins/index.ts.
3. Keep plugin-local API normalization, transports, cookies, scraping, or challenge handling in src/lib/<plugin>*.
4. Keep src/cli.ts responsible only for assembling shared dependencies and calling registerBuiltinCliPlugins(...).
5. Reuse context.agent.runJson(...) plus context.broadcast.* for any payment flow that reaches the daemon.

Implementation Rules

• Do not add another large inline .command('<plugin>') block to src/cli.ts.
• Do not reimplement signing, nonce management, or policy logic in the plugin.
• If the plugin needs onchain payment, default to preview-first behavior and make live payment explicit with --broadcast.
• If the plugin only needs a quote plus an optional live payment path, prefer one buy-style command over a redundant separate price command.
• Keep plugin-specific error handling inside the plugin module when possible.
• If a remote API needs browser bootstrap, Cloudflare handling, or cookies, isolate that behind the plugin's transport/client layer instead of leaking it into the shared CLI.
• Pass only shared helpers through CliPluginContext; keep plugin business logic inside the plugin module.

Deterministic Workflow

1. Inspect src/plugins/bitrefill.ts to copy the current plugin structure and command style.
2. Add or extend the plugin client under src/lib/<plugin>*.
3. Add a new CliPlugin implementation under src/plugins/<plugin>.ts.
4. Register it in src/plugins/index.ts.
5. If the plugin needs signing or broadcast, use context.config, context.agent, and context.broadcast instead of shelling around the shared flow.
6. Add a focused CLI test file or extend the closest existing one under test/.
7. Run the plugin-focused tests and at least one agentpay <plugin> --help smoke check.

Testing Rule

• Prefer mocked CLI/integration tests over live third-party dependencies.
• Cover command registration, happy path output, unsupported modes, and any explicit challenge or approval state.
• If the plugin supports --broadcast, cover both preview-only and broadcast-backed flows.

References

• Read src/plugins/types.ts for the shared context contract.
• Read src/plugins/index.ts for plugin registration.
• Read src/plugins/bitrefill.ts for the current plugin pattern.
• Read the matching src/lib/<plugin>* module only when implementing that plugin's remote API behavior.