@tickernelz/paperclip-pro-plugin-sdk 2026.925.0

package/dist/.paperclip-build-complete

@@ -0,0 +1 @@
+{"sources":"a10c1d6ba303ebdf14ee2aa2a56fb59515084abb8cecd949308c605e7730d6b0","outputs":"63b53f567fb8d9ca7abd03addb239df711782929f06e7cae8ce60338389287b9"}

package/dist/bundlers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Bundling presets for Paperclip plugins.
+ *
+ * These helpers return plain config objects so plugin authors can use them
+ * with esbuild or rollup without re-implementing host contract defaults.
+ */
+export interface PluginBundlerPresetInput {
+    pluginRoot?: string;
+    manifestEntry?: string;
+    workerEntry?: string;
+    uiEntry?: string;
+    outdir?: string;
+    sourcemap?: boolean;
+    minify?: boolean;
+}
+export interface EsbuildLikeOptions {
+    entryPoints: string[];
+    outdir: string;
+    bundle: boolean;
+    format: "esm";
+    platform: "node" | "browser";
+    target: string;
+    sourcemap?: boolean;
+    minify?: boolean;
+    external?: string[];
+}
+export interface RollupLikeConfig {
+    input: string;
+    output: {
+        dir: string;
+        format: "es";
+        sourcemap?: boolean;
+        entryFileNames?: string;
+    };
+    external?: string[];
+    plugins?: unknown[];
+}
+export interface PluginBundlerPresets {
+    esbuild: {
+        worker: EsbuildLikeOptions;
+        ui?: EsbuildLikeOptions;
+        manifest: EsbuildLikeOptions;
+    };
+    rollup: {
+        worker: RollupLikeConfig;
+        ui?: RollupLikeConfig;
+        manifest: RollupLikeConfig;
+    };
+}
+/**
+ * Build esbuild/rollup baseline configs for plugin worker, manifest, and UI bundles.
+ *
+ * The presets intentionally externalize host/runtime deps (`react`, SDK packages)
+ * to match the Paperclip plugin loader contract.
+ */
+export declare function createPluginBundlerPresets(input?: PluginBundlerPresetInput): PluginBundlerPresets;
+//# sourceMappingURL=bundlers.d.ts.map

package/dist/bundlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundlers.d.ts","sourceRoot":"","sources":["../src/bundlers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE;QACN,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,IAAI,CAAC;QACb,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE;QACP,MAAM,EAAE,kBAAkB,CAAC;QAC3B,EAAE,CAAC,EAAE,kBAAkB,CAAC;QACxB,QAAQ,EAAE,kBAAkB,CAAC;KAC9B,CAAC;IACF,MAAM,EAAE;QACN,MAAM,EAAE,gBAAgB,CAAC;QACzB,EAAE,CAAC,EAAE,gBAAgB,CAAC;QACtB,QAAQ,EAAE,gBAAgB,CAAC;KAC5B,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,GAAE,wBAA6B,GAAG,oBAAoB,CAoGrG"}

package/dist/bundlers.js

@@ -0,0 +1,106 @@
+/**
+ * Bundling presets for Paperclip plugins.
+ *
+ * These helpers return plain config objects so plugin authors can use them
+ * with esbuild or rollup without re-implementing host contract defaults.
+ */
+/**
+ * Build esbuild/rollup baseline configs for plugin worker, manifest, and UI bundles.
+ *
+ * The presets intentionally externalize host/runtime deps (`react`, SDK packages)
+ * to match the Paperclip plugin loader contract.
+ */
+export function createPluginBundlerPresets(input = {}) {
+    const uiExternal = [
+        "@tickernelz/paperclip-pro-plugin-sdk/ui",
+        "@tickernelz/paperclip-pro-plugin-sdk/ui/hooks",
+        "react",
+        "react-dom",
+        "react/jsx-runtime",
+    ];
+    const outdir = input.outdir ?? "dist";
+    const workerEntry = input.workerEntry ?? "src/worker.ts";
+    const manifestEntry = input.manifestEntry ?? "src/manifest.ts";
+    const uiEntry = input.uiEntry;
+    const sourcemap = input.sourcemap ?? true;
+    const minify = input.minify ?? false;
+    const esbuildWorker = {
+        entryPoints: [workerEntry],
+        outdir,
+        bundle: true,
+        format: "esm",
+        platform: "node",
+        target: "node24",
+        sourcemap,
+        minify,
+        external: ["react", "react-dom"],
+    };
+    const esbuildManifest = {
+        entryPoints: [manifestEntry],
+        outdir,
+        bundle: true,
+        format: "esm",
+        platform: "node",
+        target: "node24",
+        sourcemap,
+        external: ["@tickernelz/paperclip-pro-plugin-sdk"],
+    };
+    const esbuildUi = uiEntry
+        ? {
+            entryPoints: [uiEntry],
+            outdir: `${outdir}/ui`,
+            bundle: true,
+            format: "esm",
+            platform: "browser",
+            target: "es2022",
+            sourcemap,
+            minify,
+            external: uiExternal,
+        }
+        : undefined;
+    const rollupWorker = {
+        input: workerEntry,
+        output: {
+            dir: outdir,
+            format: "es",
+            sourcemap,
+            entryFileNames: "worker.js",
+        },
+        external: ["react", "react-dom"],
+    };
+    const rollupManifest = {
+        input: manifestEntry,
+        output: {
+            dir: outdir,
+            format: "es",
+            sourcemap,
+            entryFileNames: "manifest.js",
+        },
+        external: ["@tickernelz/paperclip-pro-plugin-sdk"],
+    };
+    const rollupUi = uiEntry
+        ? {
+            input: uiEntry,
+            output: {
+                dir: `${outdir}/ui`,
+                format: "es",
+                sourcemap,
+                entryFileNames: "index.js",
+            },
+            external: uiExternal,
+        }
+        : undefined;
+    return {
+        esbuild: {
+            worker: esbuildWorker,
+            manifest: esbuildManifest,
+            ...(esbuildUi ? { ui: esbuildUi } : {}),
+        },
+        rollup: {
+            worker: rollupWorker,
+            manifest: rollupManifest,
+            ...(rollupUi ? { ui: rollupUi } : {}),
+        },
+    };
+}
+//# sourceMappingURL=bundlers.js.map

package/dist/bundlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundlers.js","sourceRoot":"","sources":["../src/bundlers.ts"],"names":[],"mappings":"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"}

package/dist/define-plugin.d.ts

@@ -0,0 +1,396 @@
+/**
+ * `definePlugin` — the top-level helper for authoring a Paperclip plugin.
+ *
+ * Plugin authors call `definePlugin()` and export the result as the default
+ * export from their worker entrypoint. The host imports the worker module,
+ * calls `setup()` with a `PluginContext`, and from that point the plugin
+ * responds to events, jobs, webhooks, and UI requests through the context.
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ *
+ * @example
+ * ```ts
+ * // dist/worker.ts
+ * import { definePlugin } from "@tickernelz/paperclip-pro-plugin-sdk";
+ *
+ * export default definePlugin({
+ *   async setup(ctx) {
+ *     ctx.logger.info("Linear sync plugin starting");
+ *
+ *     // Subscribe to events
+ *     ctx.events.on("issue.created", async (event) => {
+ *       const companyId = event.companyId;
+ *       const config = await ctx.config.get(companyId);
+ *       const apiKey = await ctx.secrets.resolve(config.apiKeyRef, { companyId, configPath: "apiKeyRef" });
+ *       await ctx.http.fetch(`https://api.linear.app/...`, {
+ *         method: "POST",
+ *         headers: { Authorization: `Bearer ${apiKey}` },
+ *         body: JSON.stringify({ title: event.payload.title }),
+ *       });
+ *     });
+ *
+ *     // Register a job handler
+ *     ctx.jobs.register("full-sync", async (job) => {
+ *       ctx.logger.info("Running full-sync job", { runId: job.runId });
+ *       // ... sync logic
+ *     });
+ *
+ *     // Register data for the UI
+ *     ctx.data.register("sync-health", async ({ companyId }) => {
+ *       const state = await ctx.state.get({
+ *         scopeKind: "company",
+ *         scopeId: String(companyId),
+ *         stateKey: "last-sync",
+ *       });
+ *       return { lastSync: state };
+ *     });
+ *   },
+ * });
+ * ```
+ */
+import type { PluginContext } from "./types.js";
+import type { PluginEnvironmentAcquireLeaseParams, PluginEnvironmentDestroyLeaseParams, PluginEnvironmentExecuteParams, PluginEnvironmentExecuteResult, PluginEnvironmentRunnerIngressEndpointParams, PluginEnvironmentRunnerIngressEndpoint, PluginEnvironmentSyncInParams, PluginEnvironmentSyncOutParams, PluginEnvironmentSyncResult, PluginEnvironmentStartInteractiveSetupParams, PluginEnvironmentInteractiveSetupSession, PluginEnvironmentGetInteractiveSetupParams, PluginEnvironmentCaptureTemplateParams, PluginEnvironmentCaptureTemplateResult, PluginEnvironmentCancelInteractiveSetupParams, PluginEnvironmentCancelInteractiveSetupResult, PluginEnvironmentDeleteTemplateParams, PluginEnvironmentDeleteTemplateResult, PluginEnvironmentLease, PluginEnvironmentProbeParams, PluginEnvironmentProbeResult, PluginEnvironmentRealizeWorkspaceParams, PluginEnvironmentRealizeWorkspaceResult, PluginEnvironmentReleaseLeaseParams, PluginEnvironmentTerminationReceipt, PluginEnvironmentResumeLeaseParams, PluginEnvironmentValidateConfigParams, PluginEnvironmentValidationResult, DetectExternalObjectsParams, DetectExternalObjectsResult, ResolveExternalObjectParams, PluginExternalObjectResolveResult, RefreshExternalObjectsParams, RefreshExternalObjectsResult, PluginLoginPtyOpenParams, PluginLoginPtyOpenResult, PluginLoginPtyInputParams, PluginLoginPtyStopParams, PluginLoginPtyCloseParams, PluginLoginPtyCloseResult, PluginDuplexChannelOpenParams, PluginDuplexChannelOpenResult, PluginDuplexChannelWriteParams, PluginDuplexChannelStopParams, PluginDuplexChannelCloseParams, PluginDuplexChannelCloseResult } from "./protocol.js";
+/**
+ * Optional plugin-reported diagnostics returned from the `health()` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.2 — `health`
+ */
+export interface PluginHealthDiagnostics {
+    /** Machine-readable status: `"ok"` | `"degraded"` | `"error"`. */
+    status: "ok" | "degraded" | "error";
+    /** Human-readable description of the current health state. */
+    message?: string;
+    /** Plugin-reported key-value diagnostics (e.g. connection status, queue depth). */
+    details?: Record<string, unknown>;
+}
+/**
+ * Result returned from the `validateConfig()` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.3 — `validateConfig`
+ */
+export interface PluginConfigValidationResult {
+    /** Whether the config is valid. */
+    ok: boolean;
+    /** Non-fatal warnings about the config. */
+    warnings?: string[];
+    /** Validation errors (populated when `ok` is `false`). */
+    errors?: string[];
+}
+/**
+ * Input received by the plugin worker's `handleWebhook` handler.
+ *
+ * @see PLUGIN_SPEC.md §13.7 — `handleWebhook`
+ */
+export interface PluginWebhookInput {
+    /** Endpoint key matching the manifest declaration. */
+    endpointKey: string;
+    /** Inbound request headers. */
+    headers: Record<string, string | string[]>;
+    /** Raw request body as a UTF-8 string. */
+    rawBody: string;
+    /** Parsed JSON body (if applicable and parseable). */
+    parsedBody?: unknown;
+    /** Unique request identifier for idempotency checks. */
+    requestId: string;
+}
+export interface PluginApiRequestInput {
+    routeKey: string;
+    method: string;
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    body: unknown;
+    actor: {
+        actorType: "user" | "agent";
+        actorId: string;
+        agentId?: string | null;
+        userId?: string | null;
+        runId?: string | null;
+    };
+    companyId: string;
+    headers: Record<string, string>;
+}
+export interface PluginApiResponse {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+/**
+ * Scope metadata delivered alongside a `configChanged` RPC so the worker knows
+ * *which company's* configuration changed.
+ *
+ * The host→worker `configChanged` message has always carried the company scope,
+ * but the SDK historically dropped it before invoking `onConfigChanged`, leaving
+ * proactive plugins to keep a single worker-global config. That is safe for a
+ * single-tenant plugin but silently collapses a multi-company plugin onto
+ * whichever company's config was delivered last. Threading the scope through
+ * lets a `multiCompanyConfig` plugin maintain per-company state.
+ *
+ * @see PLUGIN_SPEC.md §13.4 — `configChanged`
+ */
+export interface PluginConfigChangeContext {
+    /**
+     * The company whose configuration changed, or `null` for an instance/global
+     * save that is not bound to a specific company.
+     */
+    companyId: string | null;
+}
+/**
+ * The plugin definition shape passed to `definePlugin()`.
+ *
+ * The only required field is `setup`, which receives the `PluginContext` and
+ * is where the plugin registers its handlers (events, jobs, data, actions,
+ * tools, etc.).
+ *
+ * All other lifecycle hooks are optional. If a hook is not implemented the
+ * host applies default behaviour (e.g. restarting the worker on config change
+ * instead of calling `onConfigChanged`).
+ *
+ * @see PLUGIN_SPEC.md §13 — Host-Worker Protocol
+ */
+export interface PluginDefinition {
+    /**
+     * Called once when the plugin worker starts up, after `initialize` completes.
+     *
+     * This is where the plugin registers all its handlers: event subscriptions,
+     * job handlers, data/action handlers, and tool registrations. Registration
+     * must be synchronous after `setup` resolves — do not register handlers
+     * inside async callbacks that may resolve after `setup` returns.
+     *
+     * @param ctx - The full plugin context provided by the host
+     */
+    setup(ctx: PluginContext): Promise<void>;
+    /**
+     * Called when the host wants to know if the plugin is healthy.
+     *
+     * The host polls this on a regular interval and surfaces the result in the
+     * plugin health dashboard. If not implemented, the host infers health from
+     * worker process liveness.
+     *
+     * @see PLUGIN_SPEC.md §13.2 — `health`
+     */
+    onHealth?(): Promise<PluginHealthDiagnostics>;
+    /**
+     * When true, this plugin's worker correctly serves configuration from more
+     * than one company inside a single worker process — for example by keying its
+     * state on `context.companyId` in `onConfigChanged` and running one connection
+     * / subscription set per company.
+     *
+     * When false or omitted (the default), the plugin is treated as single-tenant.
+     * The host then **fails closed** if `configChanged` would ever deliver a
+     * second, distinct company's configuration to the same worker: instead of
+     * silently collapsing the worker onto whichever company arrived last (a
+     * cross-tenant identity/secret confusion bug), the delivery is rejected with
+     * `PLUGIN_RPC_ERROR_CODES.CROSS_TENANT_CONFIG`. Re-delivering an unchanged
+     * config for a different company (idempotent replay) is still allowed.
+     */
+    multiCompanyConfig?: boolean;
+    /**
+     * Called when the operator updates this plugin's company-scoped configuration
+     * at runtime, without restarting the worker.
+     *
+     * If not implemented, the host restarts the worker to apply the new config.
+     *
+     * @param newConfig - The newly resolved configuration
+     * @param context - Scope of the change. `context.companyId` identifies the
+     *   company whose config changed (null for an instance/global save). A
+     *   multi-company plugin (`multiCompanyConfig: true`) MUST key its per-company
+     *   state on this value rather than assuming a single global config.
+     * @see PLUGIN_SPEC.md §13.4 — `configChanged`
+     */
+    onConfigChanged?(newConfig: Record<string, unknown>, context?: PluginConfigChangeContext): Promise<void>;
+    /**
+     * Called when the host is about to shut down the plugin worker.
+     *
+     * The worker has at most 10 seconds (configurable via plugin config) to
+     * finish in-flight work and resolve this promise. After the deadline the
+     * host sends SIGTERM, then SIGKILL.
+     *
+     * @see PLUGIN_SPEC.md §12.5 — Graceful Shutdown Policy
+     */
+    onShutdown?(): Promise<void>;
+    /**
+     * Called to validate the current plugin configuration.
+     *
+     * The host calls this:
+     * - after the plugin starts (to surface config errors immediately)
+     * - after the operator saves a new config (to validate before persisting)
+     * - via the "Test Connection" button in the settings UI
+     *
+     * @param config - The configuration to validate
+     * @see PLUGIN_SPEC.md §13.3 — `validateConfig`
+     */
+    onValidateConfig?(config: Record<string, unknown>): Promise<PluginConfigValidationResult>;
+    /**
+     * Called to handle an inbound webhook delivery.
+     *
+     * The host routes `POST /api/plugins/:pluginId/webhooks/:endpointKey` to
+     * this handler. The plugin is responsible for signature verification using
+     * a resolved secret ref.
+     *
+     * If not implemented but webhooks are declared in the manifest, the host
+     * returns HTTP 501 for webhook deliveries.
+     *
+     * @param input - Webhook delivery metadata and payload
+     * @see PLUGIN_SPEC.md §13.7 — `handleWebhook`
+     */
+    onWebhook?(input: PluginWebhookInput): Promise<void>;
+    /**
+     * Called for manifest-declared scoped JSON API routes under
+     * `/api/plugins/:pluginId/api/*` after the host has enforced auth, company
+     * access, capabilities, and checkout policy.
+     */
+    onApiRequest?(input: PluginApiRequestInput): Promise<PluginApiResponse>;
+    /**
+     * Called when Paperclip scans issue/comment/document content and asks this
+     * plugin whether any sanitized URL candidates belong to its external object
+     * providers. The host has already stripped URL userinfo, query strings, and
+     * fragments unless provider-safe identity components were explicitly hashed.
+     *
+     * Requires `external.objects.detect`.
+     */
+    onDetectExternalObjects?(params: DetectExternalObjectsParams): Promise<DetectExternalObjectsResult>;
+    /**
+     * Called when Paperclip needs the current normalized status for one external
+     * object owned by a manifest-declared provider.
+     *
+     * Requires `external.objects.read`.
+     */
+    onResolveExternalObject?(params: ResolveExternalObjectParams): Promise<PluginExternalObjectResolveResult>;
+    /**
+     * Optional batch resolver used by providers that can refresh many objects
+     * more efficiently than individual `onResolveExternalObject` calls.
+     *
+     * Requires `external.objects.refresh`.
+     */
+    onRefreshExternalObjects?(params: RefreshExternalObjectsParams): Promise<RefreshExternalObjectsResult>;
+    /**
+     * Called to validate provider-specific configuration for a plugin-hosted
+     * environment driver.
+     */
+    onEnvironmentValidateConfig?(params: PluginEnvironmentValidateConfigParams): Promise<PluginEnvironmentValidationResult>;
+    /** Called to test reachability or readiness of a plugin-hosted environment. */
+    onEnvironmentProbe?(params: PluginEnvironmentProbeParams): Promise<PluginEnvironmentProbeResult>;
+    /** Called before a run starts to acquire a provider lease. */
+    onEnvironmentAcquireLease?(params: PluginEnvironmentAcquireLeaseParams): Promise<PluginEnvironmentLease>;
+    /** Called to reconnect to a previously acquired provider lease. */
+    onEnvironmentResumeLease?(params: PluginEnvironmentResumeLeaseParams): Promise<PluginEnvironmentLease>;
+    /** Called when a run finishes and the provider lease can be released. */
+    onEnvironmentReleaseLease?(params: PluginEnvironmentReleaseLeaseParams): Promise<PluginEnvironmentTerminationReceipt | void>;
+    /** Called when the host needs to force-destroy provider state. */
+    onEnvironmentDestroyLease?(params: PluginEnvironmentDestroyLeaseParams): Promise<PluginEnvironmentTerminationReceipt | void>;
+    /** Called to materialize the run workspace inside the provider lease. */
+    onEnvironmentRealizeWorkspace?(params: PluginEnvironmentRealizeWorkspaceParams): Promise<PluginEnvironmentRealizeWorkspaceResult>;
+    /** Called to execute a command inside the provider lease. */
+    onEnvironmentExecute?(params: PluginEnvironmentExecuteParams): Promise<PluginEnvironmentExecuteResult>;
+    /** Return an authenticated private WebSocket ingress for runnerd. */
+    onEnvironmentRunnerIngressEndpoint?(params: PluginEnvironmentRunnerIngressEndpointParams): Promise<PluginEnvironmentRunnerIngressEndpoint>;
+    /**
+     * Optional, opt-in: called before execution to place host files/directories at
+     * target sandbox paths using a provider-native transport instead of the default
+     * base64-over-exec fallback. Defining this hook (together with
+     * `onEnvironmentSyncOut`) advertises `environmentSyncIn`; leaving it undefined
+     * keeps the byte-identical fallback. See `doc/plugins/SANDBOX_FILE_SYNC_HOOKS.md`.
+     */
+    onEnvironmentSyncIn?(params: PluginEnvironmentSyncInParams): Promise<PluginEnvironmentSyncResult>;
+    /**
+     * Optional, opt-in: called after execution to copy sandbox files/directories
+     * back to target host paths using a provider-native transport. Defining this
+     * hook (together with `onEnvironmentSyncIn`) advertises `environmentSyncOut`.
+     * See `doc/plugins/SANDBOX_FILE_SYNC_HOOKS.md`.
+     */
+    onEnvironmentSyncOut?(params: PluginEnvironmentSyncOutParams): Promise<PluginEnvironmentSyncResult>;
+    /** Called to start an interactive setup sandbox and return redacted connection metadata. */
+    onEnvironmentStartInteractiveSetup?(params: PluginEnvironmentStartInteractiveSetupParams): Promise<PluginEnvironmentInteractiveSetupSession>;
+    /** Called to read setup status and, when authorized, a one-time connection payload. */
+    onEnvironmentGetInteractiveSetup?(params: PluginEnvironmentGetInteractiveSetupParams): Promise<PluginEnvironmentInteractiveSetupSession>;
+    /** Called to capture a reusable provider template from a live setup sandbox. */
+    onEnvironmentCaptureTemplate?(params: PluginEnvironmentCaptureTemplateParams): Promise<PluginEnvironmentCaptureTemplateResult>;
+    /** Called to cancel and clean up a setup sandbox without promoting a template. */
+    onEnvironmentCancelInteractiveSetup?(params: PluginEnvironmentCancelInteractiveSetupParams): Promise<PluginEnvironmentCancelInteractiveSetupResult>;
+    /** Called for optional best-effort cleanup of a captured provider template. */
+    onEnvironmentDeleteTemplate?(params: PluginEnvironmentDeleteTemplateParams): Promise<PluginEnvironmentDeleteTemplateResult>;
+    /**
+     * Called to open one live Claude `setup-token` login pseudo-terminal.
+     * The worker registers the terminal under the host route identifier and returns a
+     * worker session identifier for the output notification binding only. The worker
+     * streams output and the exit through `ctx.loginPty`, never as a reply.
+     * Defining the four `onLoginPty*` hooks advertises the four methods.
+     */
+    onLoginPtyOpen?(params: PluginLoginPtyOpenParams): Promise<PluginLoginPtyOpenResult>;
+    /** Called to write delayed input to an open login pseudo-terminal, keyed by the worker session identifier. */
+    onLoginPtyInput?(params: PluginLoginPtyInputParams): Promise<void>;
+    /** Called to stop an open login pseudo-terminal child, keyed by the worker session identifier. */
+    onLoginPtyStop?(params: PluginLoginPtyStopParams): Promise<void>;
+    /**
+     * Called to close an open login pseudo-terminal by the host route identifier. The
+     * worker closes the exact terminal registered under that identifier and returns a
+     * close acknowledgement that carries the same identifier.
+     */
+    onLoginPtyClose?(params: PluginLoginPtyCloseParams): Promise<PluginLoginPtyCloseResult>;
+    /**
+     * Called to open one persistent duplex channel. The worker registers the
+     * channel under the host route identifier and returns a worker session
+     * identifier for the data notification binding only. The worker streams data
+     * and the exit through worker→host notifications, never as a reply. Defining
+     * the four `onDuplexChannel*` hooks advertises the four methods. The host reads
+     * the open verb to gate the `duplexCommandStream` capability.
+     *
+     * HTTP/2 is the preferred transport. `queue_v1` is the soft-deprecated fallback.
+     */
+    onDuplexChannelOpen?(params: PluginDuplexChannelOpenParams): Promise<PluginDuplexChannelOpenResult>;
+    /** Called to write raw input to an open duplex channel, keyed by the worker session identifier. */
+    onDuplexChannelWrite?(params: PluginDuplexChannelWriteParams): Promise<void>;
+    /** Called to stop an open duplex channel child, keyed by the worker session identifier. */
+    onDuplexChannelStop?(params: PluginDuplexChannelStopParams): Promise<void>;
+    /**
+     * Called to close an open duplex channel by the host route identifier. The
+     * worker closes the exact channel registered under that identifier and returns
+     * a close acknowledgement that carries the same identifier.
+     */
+    onDuplexChannelClose?(params: PluginDuplexChannelCloseParams): Promise<PluginDuplexChannelCloseResult>;
+}
+/**
+ * The sealed plugin object returned by `definePlugin()`.
+ *
+ * Plugin authors export this as the default export from their worker
+ * entrypoint. The host imports it and calls the lifecycle methods.
+ *
+ * @see PLUGIN_SPEC.md §14 — SDK Surface
+ */
+export interface PaperclipPlugin {
+    /** The original plugin definition passed to `definePlugin()`. */
+    readonly definition: PluginDefinition;
+}
+/**
+ * Define a Paperclip plugin.
+ *
+ * Call this function in your worker entrypoint and export the result as the
+ * default export. The host will import the module and call lifecycle methods
+ * on the returned object.
+ *
+ * @param definition - Plugin lifecycle handlers
+ * @returns A sealed `PaperclipPlugin` object for the host to consume
+ *
+ * @example
+ * ```ts
+ * import { definePlugin } from "@tickernelz/paperclip-pro-plugin-sdk";
+ *
+ * export default definePlugin({
+ *   async setup(ctx) {
+ *     ctx.logger.info("Plugin started");
+ *     ctx.events.on("issue.created", async (event) => {
+ *       // handle event
+ *     });
+ *   },
+ *
+ *   async onHealth() {
+ *     return { status: "ok" };
+ *   },
+ * });
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ */
+export declare function definePlugin(definition: PluginDefinition): PaperclipPlugin;
+//# sourceMappingURL=define-plugin.d.ts.map

package/dist/define-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-plugin.d.ts","sourceRoot":"","sources":["../src/define-plugin.ts"],"names":[],"mappings":"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"}

package/dist/define-plugin.js

@@ -0,0 +1,87 @@
+/**
+ * `definePlugin` — the top-level helper for authoring a Paperclip plugin.
+ *
+ * Plugin authors call `definePlugin()` and export the result as the default
+ * export from their worker entrypoint. The host imports the worker module,
+ * calls `setup()` with a `PluginContext`, and from that point the plugin
+ * responds to events, jobs, webhooks, and UI requests through the context.
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ *
+ * @example
+ * ```ts
+ * // dist/worker.ts
+ * import { definePlugin } from "@tickernelz/paperclip-pro-plugin-sdk";
+ *
+ * export default definePlugin({
+ *   async setup(ctx) {
+ *     ctx.logger.info("Linear sync plugin starting");
+ *
+ *     // Subscribe to events
+ *     ctx.events.on("issue.created", async (event) => {
+ *       const companyId = event.companyId;
+ *       const config = await ctx.config.get(companyId);
+ *       const apiKey = await ctx.secrets.resolve(config.apiKeyRef, { companyId, configPath: "apiKeyRef" });
+ *       await ctx.http.fetch(`https://api.linear.app/...`, {
+ *         method: "POST",
+ *         headers: { Authorization: `Bearer ${apiKey}` },
+ *         body: JSON.stringify({ title: event.payload.title }),
+ *       });
+ *     });
+ *
+ *     // Register a job handler
+ *     ctx.jobs.register("full-sync", async (job) => {
+ *       ctx.logger.info("Running full-sync job", { runId: job.runId });
+ *       // ... sync logic
+ *     });
+ *
+ *     // Register data for the UI
+ *     ctx.data.register("sync-health", async ({ companyId }) => {
+ *       const state = await ctx.state.get({
+ *         scopeKind: "company",
+ *         scopeId: String(companyId),
+ *         stateKey: "last-sync",
+ *       });
+ *       return { lastSync: state };
+ *     });
+ *   },
+ * });
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// definePlugin — top-level factory
+// ---------------------------------------------------------------------------
+/**
+ * Define a Paperclip plugin.
+ *
+ * Call this function in your worker entrypoint and export the result as the
+ * default export. The host will import the module and call lifecycle methods
+ * on the returned object.
+ *
+ * @param definition - Plugin lifecycle handlers
+ * @returns A sealed `PaperclipPlugin` object for the host to consume
+ *
+ * @example
+ * ```ts
+ * import { definePlugin } from "@tickernelz/paperclip-pro-plugin-sdk";
+ *
+ * export default definePlugin({
+ *   async setup(ctx) {
+ *     ctx.logger.info("Plugin started");
+ *     ctx.events.on("issue.created", async (event) => {
+ *       // handle event
+ *     });
+ *   },
+ *
+ *   async onHealth() {
+ *     return { status: "ok" };
+ *   },
+ * });
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ */
+export function definePlugin(definition) {
+    return Object.freeze({ definition });
+}
+//# sourceMappingURL=define-plugin.js.map