@reclaimprotocol/client 0.1.34 → 0.1.35

package/lib/routes.gen.d.ts

@@ -3,6 +3,10 @@ export declare const ROUTES: {
         readonly method: "post";
         readonly path: "/orgs/{orgId}/invite";
     };
+    readonly AcknowledgeCallbackEvents: {
+        readonly method: "post";
+        readonly path: "/verifications/callback-events/acknowledge";
+    };
     readonly AddOrgMember: {
         readonly method: "post";
         readonly path: "/orgs/{orgId}/members";
@@ -91,6 +95,10 @@ export declare const ROUTES: {
         readonly method: "post";
         readonly path: "/admin/orgs/{orgId}/credits/{grantId}/void";
     };
+    readonly AgentInstallationMarkdown: {
+        readonly method: "get";
+        readonly path: "/docs/agent-installation.md";
+    };
     readonly AppleAppSiteAssociation: {
         readonly method: "get";
         readonly path: "/.well-known/apple-app-site-association";
@@ -391,6 +399,10 @@ export declare const ROUTES: {
         readonly method: "get";
         readonly path: "/verifications/callback-dlq";
     };
+    readonly ListCallbackEvents: {
+        readonly method: "get";
+        readonly path: "/verifications/callback-events";
+    };
     readonly ListCallbackSubscriptions: {
         readonly method: "get";
         readonly path: "/verifications/callback-subscriptions";
@@ -495,6 +507,10 @@ export declare const ROUTES: {
         readonly method: "post";
         readonly path: "/admin/billing/transactions/{txId}/refund";
     };
+    readonly ReleaseCallbackListener: {
+        readonly method: "post";
+        readonly path: "/verifications/callback-listener/release";
+    };
     readonly RemoveOrgMember: {
         readonly method: "delete";
         readonly path: "/orgs/{orgId}/members/{memberId}";

package/lib/routes.gen.js

@@ -1,10 +1,11 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:e2db795ab15c).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:de7373741e35).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.
 export const ROUTES = {
     "AcceptOrgInvite": { "method": "post", "path": "/orgs/{orgId}/invite" },
+    "AcknowledgeCallbackEvents": { "method": "post", "path": "/verifications/callback-events/acknowledge" },
     "AddOrgMember": { "method": "post", "path": "/orgs/{orgId}/members" },
     "AddProviderContributionComment": { "method": "post", "path": "/providers/{providerId}/contributions/{campaignId}/comments" },
     "AddStaffMember": { "method": "post", "path": "/admin/staff" },
@@ -27,6 +28,7 @@ export const ROUTES = {
     "AdminUsers": { "method": "get", "path": "/admin/users" },
     "AdminVerificationClients": { "method": "get", "path": "/admin/verification-clients" },
     "AdminVoidOrgCredit": { "method": "post", "path": "/admin/orgs/{orgId}/credits/{grantId}/void" },
+    "AgentInstallationMarkdown": { "method": "get", "path": "/docs/agent-installation.md" },
     "AppleAppSiteAssociation": { "method": "get", "path": "/.well-known/apple-app-site-association" },
     "AssetLinksJson": { "method": "get", "path": "/.well-known/assetlinks.json" },
     "BindVerificationSessionTeeNonce": { "method": "put", "path": "/verifications/sessions/{sessionId}/tee-nonce" },
@@ -102,6 +104,7 @@ export const ROUTES = {
     "JwksJson": { "method": "get", "path": "/.well-known/jwks.json" },
     "ListBillingPlans": { "method": "get", "path": "/billing/plans" },
     "ListCallbackDlq": { "method": "get", "path": "/verifications/callback-dlq" },
+    "ListCallbackEvents": { "method": "get", "path": "/verifications/callback-events" },
     "ListCallbackSubscriptions": { "method": "get", "path": "/verifications/callback-subscriptions" },
     "ListFeatureFlagRevisions": { "method": "get", "path": "/admin/feature-flags/{flagKey}/revisions" },
     "ListOrgCallbackSubscriptions": { "method": "get", "path": "/orgs/{orgId}/callback-subscriptions" },
@@ -128,6 +131,7 @@ export const ROUTES = {
     "PublishProviderVersion": { "method": "post", "path": "/providers/{providerId}/versions/{version}/publish" },
     "RefreshBillingPlans": { "method": "post", "path": "/admin/billing/plans/refresh" },
     "RefundTransaction": { "method": "post", "path": "/admin/billing/transactions/{txId}/refund" },
+    "ReleaseCallbackListener": { "method": "post", "path": "/verifications/callback-listener/release" },
     "RemoveOrgMember": { "method": "delete", "path": "/orgs/{orgId}/members/{memberId}" },
     "RemoveStaffMember": { "method": "delete", "path": "/admin/staff/{email}" },
     "ReportClaimant": { "method": "post", "path": "/v/{sessionId}/claimant" },

package/lib/types/openapi.gen.d.ts

@@ -1347,6 +1347,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/docs/agent-installation.md": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Agent installation instructions
+         * @description How to install the Reclaim MCP server in each supported coding agent, as Markdown for a coding agent to read: the exact commands or configuration per agent, how to verify the installation, and troubleshooting. It tells the agent to follow only the section for the client it runs in. Public.
+         */
+        get: operations["AgentInstallationMarkdown"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/login": {
         parameters: {
             query?: never;
@@ -2492,12 +2512,26 @@ export interface paths {
         /**
          * Register a callback subscription
          * @description Registers a destination for verification results on the organization
-         *     the presented `OrgToken` resolves to. The body is just `callbackUrl`
-         *     and `events`. At least one subscription must exist for the org before a
-         *     verification session can be created. Delivery is scoped by org: terminal
-         *     results are ECIES-encrypted to the org's eth public key when its
-         *     `canEncryptResult` is enabled (see `PUT /orgs/{orgId}/keypair`), else
-         *     delivered as plaintext.
+         *     the presented `OrgToken` resolves to. At least one subscription must
+         *     exist for the org before you can create a verification session.
+         *     Delivery is scoped by org: terminal results are ECIES-encrypted to the
+         *     org's eth public key when its `canEncryptResult` is enabled (see
+         *     `PUT /orgs/{orgId}/keypair`), else delivered as plaintext.
+         *
+         *     To receive results at a URL, send `callbackUrl` and `events`. Builder
+         *     POSTs each delivery to that URL.
+         *
+         *     To read results without a public URL during local development, send
+         *     `deliveryMode: "pull"`. Builder keeps the deliveries and you read them
+         *     with `GET /verifications/callback-events`. A pull subscription is a
+         *     90-second lease: it receives events and satisfies the session-creation
+         *     check only while the lease is unexpired. Send the same request about
+         *     every 30 seconds to renew it, and call
+         *     `POST /verifications/callback-listener/release` when you stop. Production
+         *     needs a webhook subscription. An org has at most one pull subscription.
+         *     If it already exists, Builder renews it and returns it with status 200.
+         *     If the body includes `events`, they replace the subscription's events;
+         *     if it omits them, the existing events are kept.
          */
         post: operations["CreateCallbackSubscription"];
         delete?: never;
@@ -2506,6 +2540,86 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/verifications/callback-listener/release": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Release the pull listener
+         * @description Expires the organization's pull subscription lease immediately, so it stops receiving events and no longer satisfies the session-creation check. Stored events stay readable. Call it when the coding agent stops. It succeeds when no pull subscription exists or the lease has already expired.
+         */
+        post: operations["ReleaseCallbackListener"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/verifications/callback-events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List events from the pull subscription
+         * @description Lists the deliveries of the organization's pull subscription, oldest
+         *     first. Use it to read verification results without a public URL.
+         *     Create the pull subscription with `POST /verifications/callback-subscriptions`
+         *     and `deliveryMode: "pull"`.
+         *
+         *     Each item's `envelope` is the body that Builder POSTs to a webhook
+         *     subscription, so you handle both the same way. For a pull
+         *     subscription, `envelope.timestamp` is the time Builder created the
+         *     delivery.
+         *
+         *     To poll, pass the previous response's `next` as `after`. `next` is
+         *     always set, and equals `after` when no new events exist. Treat cursors
+         *     as opaque. A cursor read is not complete: a delivery that commits after
+         *     a later one can be missed, because the cursor has already moved past
+         *     it. The reliable path is `pending=true` plus
+         *     `POST /verifications/callback-events/acknowledge`: acknowledge each
+         *     event you handled, and read `pending=true` without `after` so anything
+         *     missed shows up on the next read.
+         *
+         *     Builder keeps result payloads for seven days. Acknowledged events stay
+         *     readable until then.
+         */
+        get: operations["ListCallbackEvents"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/verifications/callback-events/acknowledge": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Acknowledge events from the pull subscription
+         * @description Marks pull deliveries as `delivered` so `GET /verifications/callback-events` with `pending=true` stops returning them. Builder keeps the payloads until the seven-day retention limit. Ids that are unknown, belong to another organization, or are already acknowledged are ignored.
+         */
+        post: operations["AcknowledgeCallbackEvents"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/verifications/callback-subscriptions/{subscriptionId}": {
         parameters: {
             query?: never;
@@ -2541,7 +2655,8 @@ export interface paths {
         put?: never;
         /**
          * Register a callback subscription on an organization
-         * @description Registers a destination for verification results on the organization. Caller must be an active member of the org. The body is just `callbackUrl` and `events`; delivery is scoped to the org and encrypted as an ECIES ciphertext (base64url) to the org's encryption credential when set, else delivered as plaintext.
+         * @description Registers a destination for verification results on the organization. Caller must be an active member of the org. Delivery is scoped to the org and encrypted as an ECIES ciphertext (base64url) to the org's encryption credential when set, else delivered as plaintext.
+         *     Send `callbackUrl` and `events` to receive results at a URL. Send `deliveryMode: "pull"` to keep results for reading with `GET /verifications/callback-events`. A pull subscription works only while its 90-second lease is unexpired, and each repeated request renews it. An org has at most one pull subscription. If it already exists, Builder returns it with status 200.
          */
         post: operations["CreateOrgCallbackSubscription"];
         delete?: never;
@@ -5798,24 +5913,59 @@ export interface components {
              * @description The organization that owns this callback subscription.
              */
             orgId: string;
-            /** @description HTTP(S) endpoint that receives the event. It may contain `{{sessionId}}` and top-level session-context placeholders such as `{{orderId}}`. The Builder URI-encodes each value and stores the expanded URL when it creates the delivery. */
-            callbackUrl: string;
+            deliveryMode: components["schemas"]["CallbackDeliveryMode"];
+            /** @description HTTP(S) endpoint that receives the event. It may contain `{{sessionId}}` and top-level session-context placeholders such as `{{orderId}}`. The Builder URI-encodes each value and stores the expanded URL when it creates the delivery. Absent when `deliveryMode` is `pull`. */
+            callbackUrl?: string;
+            /** @description Present when `deliveryMode` is `pull`. The pull subscription receives events and satisfies the session-creation check only until this time. Renew it by repeating the create request. */
+            listenerExpiresAt?: components["schemas"]["Timestamp"];
             /** @description Events this subscription wants delivered — any subset of `VerificationEvent`. Builder terminal events are `verification_success`, `verification_rejected`, `verification_error`, `verification_cancelled`, and `session_expired`. Terminal result deliveries contain the signed result when one is available; non-terminal events deliver a plaintext notification. */
             events: components["schemas"]["VerificationEvent"][];
             createdAt: components["schemas"]["Timestamp"];
             updatedAt: components["schemas"]["Timestamp"];
         };
-        /** @description Body for `POST /verifications/callback-subscriptions`. The owning organization is resolved from the presented `OrgToken`; delivery is scoped to that org and encrypted to its credential when set. */
-        CreateCallbackSubscriptionRequest: {
+        /**
+         * @description How Builder delivers events. `webhook` POSTs each one to `callbackUrl`. `pull` keeps them for you to read with `GET /verifications/callback-events`.
+         * @enum {string}
+         */
+        CallbackDeliveryMode: "webhook" | "pull";
+        /** @description A subscription that Builder POSTs each delivery to. */
+        WebhookCallbackSubscriptionRequest: {
+            /**
+             * @description Omit it or send `webhook`.
+             * @enum {string}
+             */
+            deliveryMode?: "webhook";
             /** @description Callback URL or template. Supported placeholders are `{{sessionId}}` and top-level scalar context keys. */
             callbackUrl: string;
             events: components["schemas"]["VerificationEvent"][];
         };
-        /** @description Body for `POST /orgs/{orgId}/callback-subscriptions`. The owning organization comes from the path; bearer-authenticated and gated on org membership. Delivery is scoped to the org and encrypted to its credential when set. */
-        CreateOrgCallbackSubscriptionRequest: {
-            /** @description Callback URL or template. Supported placeholders are `{{sessionId}}` and top-level scalar context keys. */
-            callbackUrl: string;
-            events: components["schemas"]["VerificationEvent"][];
+        /** @description A subscription whose deliveries wait for you to read them. It has no URL. An org has at most one. */
+        PullCallbackSubscriptionRequest: {
+            /** @enum {string} */
+            deliveryMode: "pull";
+            /** @description Not allowed. A pull subscription has no URL. */
+            callbackUrl?: unknown;
+            /** @description Events to keep. Defaults to every event. */
+            events?: components["schemas"]["VerificationEvent"][];
+        };
+        /** @description Body for `POST /verifications/callback-subscriptions`. The owning organization is resolved from the presented `OrgToken`; delivery is scoped to that org and encrypted to its credential when set. Send `callbackUrl` for a webhook, or `deliveryMode: "pull"` for a subscription you read. */
+        CreateCallbackSubscriptionRequest: components["schemas"]["WebhookCallbackSubscriptionRequest"] | components["schemas"]["PullCallbackSubscriptionRequest"];
+        /** @description Body for `POST /orgs/{orgId}/callback-subscriptions`. The owning organization comes from the path; bearer-authenticated and gated on org membership. Delivery is scoped to the org and encrypted to its credential when set. Send `callbackUrl` for a webhook, or `deliveryMode: "pull"` for a subscription you read. */
+        CreateOrgCallbackSubscriptionRequest: components["schemas"]["WebhookCallbackSubscriptionRequest"] | components["schemas"]["PullCallbackSubscriptionRequest"];
+        /** @description One delivery waiting on the organization's pull subscription. */
+        CallbackEvent: {
+            /**
+             * Format: uuid
+             * @description Pass it to `POST /verifications/callback-events/acknowledge`.
+             */
+            id: string;
+            subscriptionId: components["schemas"]["SubscriptionID"];
+            sessionId: components["schemas"]["SessionID"];
+            event: components["schemas"]["VerificationEvent"];
+            /** @description `pending` until you acknowledge the event, then `delivered`. */
+            deliveryStatus: components["schemas"]["CallbackDeliveryStatus"];
+            createdAt: components["schemas"]["Timestamp"];
+            envelope: components["schemas"]["VerificationResultDelivery"];
         };
         /** @description Present only when the session's `mode` is `SANDBOX`. */
         SandboxLimits: {
@@ -6216,7 +6366,7 @@ export interface components {
                 signature: string;
             }[];
         };
-        /** @description The JSON envelope POSTed to a callback subscription's `callbackUrl` (see the `verificationResult` webhook). `sessionId`, `event` and `timestamp` are unauthenticated plaintext routing hints; branch on `event` for the shape of `data`. **Terminal result events** carry the signed result — an ECIES ciphertext (base64url, secp256k1 + AES-256-GCM) wrapping the signed JWS when the org has an encryption credential, else the plaintext signed JWS — act only on the signature-verified contents. **Non-terminal events** carry a plaintext, **unsigned** progress notification — advisory only; the signed terminal result is the source of truth. */
+        /** @description The JSON envelope POSTed to a callback subscription's `callbackUrl` (see the `verificationResult` webhook), and returned as `envelope` by `GET /verifications/callback-events` for a pull subscription. `sessionId`, `event` and `timestamp` are unauthenticated plaintext routing hints; branch on `event` for the shape of `data`. **Terminal result events** carry the signed result — an ECIES ciphertext (base64url, secp256k1 + AES-256-GCM) wrapping the signed JWS when the org has an encryption credential, else the plaintext signed JWS — act only on the signature-verified contents. **Non-terminal events** carry a plaintext, **unsigned** progress notification — advisory only; the signed terminal result is the source of truth. */
         VerificationResultDelivery: {
             sessionId: components["schemas"]["SessionID"];
             /** @description The event that produced this delivery. */
@@ -6364,8 +6514,11 @@ export interface components {
         VerificationDelivery: {
             subscriptionId: components["schemas"]["SubscriptionID"];
             event: components["schemas"]["VerificationEvent"];
-            /** Format: uri */
-            callbackUrl: string;
+            /**
+             * Format: uri
+             * @description Absent for deliveries to a pull subscription.
+             */
+            callbackUrl?: string;
             deliveryStatus: components["schemas"]["CallbackDeliveryStatus"];
             attempts: number;
             lastAttemptAt?: components["schemas"]["Timestamp"];
@@ -8515,6 +8668,27 @@ export interface operations {
             default: components["responses"]["ProblemResponse"];
         };
     };
+    AgentInstallationMarkdown: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The guide as Markdown. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/markdown": string;
+                };
+            };
+            default: components["responses"]["ProblemResponse"];
+        };
+    };
     LoginPage: {
         parameters: {
             query?: {
@@ -8860,9 +9034,12 @@ export interface operations {
                 tab?: "overview" | "connect" | "integrate" | "providers" | "members" | "themes" | "settings" | "sessions" | "billing";
                 /** @description Integrate tab only. Which integration path to show: a coding agent over MCP, the client package, or plain HTTP. */
                 track?: "agent" | "sdk" | "http";
-                /** @description Integrate tab, agent track only. Which coding agent's install command to show. */
+                /**
+                 * @deprecated
+                 * @description Ignored.
+                 */
                 agent?: "claude" | "copilot" | "cursor" | "omp" | "opencode" | "codex" | "antigravity" | "others";
-                /** @description Integrate tab, agent track only. What users prove, as typed into the prompt's goal field; kept when another agent is picked. */
+                /** @description Integrate tab, agent track only. What users prove, as typed into the prompt's goal field. */
                 goal?: string;
                 /** @description Integrate tab: the providers to show in the examples in place of placeholder ids, for example when arriving from a provider page or a build page. Repeat to pass several. Dashboard tab: scopes the report to sessions that ran this provider (the first one); options come from `GET /orgs/{orgId}/providers/used`. */
                 providerId?: components["schemas"]["ProviderID"][];
@@ -10677,6 +10854,15 @@ export interface operations {
             };
         };
         responses: {
+            /** @description The org's existing pull subscription */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CallbackSubscription"];
+                };
+            };
             /** @description Subscription created */
             201: {
                 headers: {
@@ -10689,6 +10875,85 @@ export interface operations {
             default: components["responses"]["ProblemResponse"];
         };
     };
+    ReleaseCallbackListener: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Released */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            default: components["responses"]["ProblemResponse"];
+        };
+    };
+    ListCallbackEvents: {
+        parameters: {
+            query?: {
+                /** @description Cursor from the `next` field of a previous response. Returns only events after it. Omit it to start from the oldest event. */
+                after?: string;
+                /** @description Maximum number of events to return. Defaults to 50. */
+                limit?: number;
+                /** @description Returns only events of this verification session. */
+                sessionId?: components["schemas"]["SessionID"];
+                /** @description When `true`, returns only events you have not acknowledged. Defaults to `false`. */
+                pending?: boolean;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Ok */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        items: components["schemas"]["CallbackEvent"][];
+                        /** @description Cursor to pass as `after` on the next request. Equals `after` when `items` is empty, and `0` when you passed no `after`. */
+                        next: string;
+                    };
+                };
+            };
+            default: components["responses"]["ProblemResponse"];
+        };
+    };
+    AcknowledgeCallbackEvents: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description The `id` of each `CallbackEvent` to acknowledge. */
+                    ids: string[];
+                };
+            };
+        };
+        responses: {
+            /** @description Acknowledged */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            default: components["responses"]["ProblemResponse"];
+        };
+    };
     DeleteCallbackSubscription: {
         parameters: {
             query?: never;
@@ -10753,6 +11018,15 @@ export interface operations {
             };
         };
         responses: {
+            /** @description The org's existing pull subscription */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CallbackSubscription"];
+                };
+            };
             /** @description Subscription created */
             201: {
                 headers: {
@@ -11027,7 +11301,7 @@ export interface operations {
                     "application/problem+json": components["schemas"]["Problem"];
                 };
             };
-            /** @description No callback subscription exists for the organization. Register one first via `POST /verifications/callback-subscriptions` (or `POST /orgs/{orgId}/callback-subscriptions`). */
+            /** @description No callback subscription exists for the organization. Register one first via `POST /verifications/callback-subscriptions` (or `POST /orgs/{orgId}/callback-subscriptions`). A pull subscription satisfies this check only while its listener lease is unexpired. */
             409: {
                 headers: {
                     [name: string]: unknown;

package/lib/types/openapi.gen.js

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/openapi-typegen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:e2db795ab15c).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:de7373741e35).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/client",
 	"title": "Reclaim Client",
-	"version": "0.1.34",
+	"version": "0.1.35",
 	"description": "Typed SDK/HTTP client SDK for the Reclaim Protocol — the programmatic way to use Reclaim Protocol to verify **data points** about your users (a follower count, an account balance, an order). Can be directly integrated by apps to request verification for their users using Reclaim Protocol and verify the results.",
 	"type": "module",
 	"sideEffects": false,

package/src/routes.gen.ts

@@ -1,11 +1,12 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:e2db795ab15c).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:de7373741e35).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.
 
 export const ROUTES = {
 	"AcceptOrgInvite": {"method":"post","path":"/orgs/{orgId}/invite"},
+	"AcknowledgeCallbackEvents": {"method":"post","path":"/verifications/callback-events/acknowledge"},
 	"AddOrgMember": {"method":"post","path":"/orgs/{orgId}/members"},
 	"AddProviderContributionComment": {"method":"post","path":"/providers/{providerId}/contributions/{campaignId}/comments"},
 	"AddStaffMember": {"method":"post","path":"/admin/staff"},
@@ -28,6 +29,7 @@ export const ROUTES = {
 	"AdminUsers": {"method":"get","path":"/admin/users"},
 	"AdminVerificationClients": {"method":"get","path":"/admin/verification-clients"},
 	"AdminVoidOrgCredit": {"method":"post","path":"/admin/orgs/{orgId}/credits/{grantId}/void"},
+	"AgentInstallationMarkdown": {"method":"get","path":"/docs/agent-installation.md"},
 	"AppleAppSiteAssociation": {"method":"get","path":"/.well-known/apple-app-site-association"},
 	"AssetLinksJson": {"method":"get","path":"/.well-known/assetlinks.json"},
 	"BindVerificationSessionTeeNonce": {"method":"put","path":"/verifications/sessions/{sessionId}/tee-nonce"},
@@ -103,6 +105,7 @@ export const ROUTES = {
 	"JwksJson": {"method":"get","path":"/.well-known/jwks.json"},
 	"ListBillingPlans": {"method":"get","path":"/billing/plans"},
 	"ListCallbackDlq": {"method":"get","path":"/verifications/callback-dlq"},
+	"ListCallbackEvents": {"method":"get","path":"/verifications/callback-events"},
 	"ListCallbackSubscriptions": {"method":"get","path":"/verifications/callback-subscriptions"},
 	"ListFeatureFlagRevisions": {"method":"get","path":"/admin/feature-flags/{flagKey}/revisions"},
 	"ListOrgCallbackSubscriptions": {"method":"get","path":"/orgs/{orgId}/callback-subscriptions"},
@@ -129,6 +132,7 @@ export const ROUTES = {
 	"PublishProviderVersion": {"method":"post","path":"/providers/{providerId}/versions/{version}/publish"},
 	"RefreshBillingPlans": {"method":"post","path":"/admin/billing/plans/refresh"},
 	"RefundTransaction": {"method":"post","path":"/admin/billing/transactions/{txId}/refund"},
+	"ReleaseCallbackListener": {"method":"post","path":"/verifications/callback-listener/release"},
 	"RemoveOrgMember": {"method":"delete","path":"/orgs/{orgId}/members/{memberId}"},
 	"RemoveStaffMember": {"method":"delete","path":"/admin/staff/{email}"},
 	"ReportClaimant": {"method":"post","path":"/v/{sessionId}/claimant"},

package/src/types/openapi.gen.ts

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/openapi-typegen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:e2db795ab15c).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:de7373741e35).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.
@@ -1353,6 +1353,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/docs/agent-installation.md": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Agent installation instructions
+         * @description How to install the Reclaim MCP server in each supported coding agent, as Markdown for a coding agent to read: the exact commands or configuration per agent, how to verify the installation, and troubleshooting. It tells the agent to follow only the section for the client it runs in. Public.
+         */
+        get: operations["AgentInstallationMarkdown"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/login": {
         parameters: {
             query?: never;
@@ -2498,12 +2518,26 @@ export interface paths {
         /**
          * Register a callback subscription
          * @description Registers a destination for verification results on the organization
-         *     the presented `OrgToken` resolves to. The body is just `callbackUrl`
-         *     and `events`. At least one subscription must exist for the org before a
-         *     verification session can be created. Delivery is scoped by org: terminal
-         *     results are ECIES-encrypted to the org's eth public key when its
-         *     `canEncryptResult` is enabled (see `PUT /orgs/{orgId}/keypair`), else
-         *     delivered as plaintext.
+         *     the presented `OrgToken` resolves to. At least one subscription must
+         *     exist for the org before you can create a verification session.
+         *     Delivery is scoped by org: terminal results are ECIES-encrypted to the
+         *     org's eth public key when its `canEncryptResult` is enabled (see
+         *     `PUT /orgs/{orgId}/keypair`), else delivered as plaintext.
+         *
+         *     To receive results at a URL, send `callbackUrl` and `events`. Builder
+         *     POSTs each delivery to that URL.
+         *
+         *     To read results without a public URL during local development, send
+         *     `deliveryMode: "pull"`. Builder keeps the deliveries and you read them
+         *     with `GET /verifications/callback-events`. A pull subscription is a
+         *     90-second lease: it receives events and satisfies the session-creation
+         *     check only while the lease is unexpired. Send the same request about
+         *     every 30 seconds to renew it, and call
+         *     `POST /verifications/callback-listener/release` when you stop. Production
+         *     needs a webhook subscription. An org has at most one pull subscription.
+         *     If it already exists, Builder renews it and returns it with status 200.
+         *     If the body includes `events`, they replace the subscription's events;
+         *     if it omits them, the existing events are kept.
          */
         post: operations["CreateCallbackSubscription"];
         delete?: never;
@@ -2512,6 +2546,86 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/verifications/callback-listener/release": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Release the pull listener
+         * @description Expires the organization's pull subscription lease immediately, so it stops receiving events and no longer satisfies the session-creation check. Stored events stay readable. Call it when the coding agent stops. It succeeds when no pull subscription exists or the lease has already expired.
+         */
+        post: operations["ReleaseCallbackListener"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/verifications/callback-events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List events from the pull subscription
+         * @description Lists the deliveries of the organization's pull subscription, oldest
+         *     first. Use it to read verification results without a public URL.
+         *     Create the pull subscription with `POST /verifications/callback-subscriptions`
+         *     and `deliveryMode: "pull"`.
+         *
+         *     Each item's `envelope` is the body that Builder POSTs to a webhook
+         *     subscription, so you handle both the same way. For a pull
+         *     subscription, `envelope.timestamp` is the time Builder created the
+         *     delivery.
+         *
+         *     To poll, pass the previous response's `next` as `after`. `next` is
+         *     always set, and equals `after` when no new events exist. Treat cursors
+         *     as opaque. A cursor read is not complete: a delivery that commits after
+         *     a later one can be missed, because the cursor has already moved past
+         *     it. The reliable path is `pending=true` plus
+         *     `POST /verifications/callback-events/acknowledge`: acknowledge each
+         *     event you handled, and read `pending=true` without `after` so anything
+         *     missed shows up on the next read.
+         *
+         *     Builder keeps result payloads for seven days. Acknowledged events stay
+         *     readable until then.
+         */
+        get: operations["ListCallbackEvents"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/verifications/callback-events/acknowledge": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Acknowledge events from the pull subscription
+         * @description Marks pull deliveries as `delivered` so `GET /verifications/callback-events` with `pending=true` stops returning them. Builder keeps the payloads until the seven-day retention limit. Ids that are unknown, belong to another organization, or are already acknowledged are ignored.
+         */
+        post: operations["AcknowledgeCallbackEvents"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/verifications/callback-subscriptions/{subscriptionId}": {
         parameters: {
             query?: never;
@@ -2547,7 +2661,8 @@ export interface paths {
         put?: never;
         /**
          * Register a callback subscription on an organization
-         * @description Registers a destination for verification results on the organization. Caller must be an active member of the org. The body is just `callbackUrl` and `events`; delivery is scoped to the org and encrypted as an ECIES ciphertext (base64url) to the org's encryption credential when set, else delivered as plaintext.
+         * @description Registers a destination for verification results on the organization. Caller must be an active member of the org. Delivery is scoped to the org and encrypted as an ECIES ciphertext (base64url) to the org's encryption credential when set, else delivered as plaintext.
+         *     Send `callbackUrl` and `events` to receive results at a URL. Send `deliveryMode: "pull"` to keep results for reading with `GET /verifications/callback-events`. A pull subscription works only while its 90-second lease is unexpired, and each repeated request renews it. An org has at most one pull subscription. If it already exists, Builder returns it with status 200.
          */
         post: operations["CreateOrgCallbackSubscription"];
         delete?: never;
@@ -5804,24 +5919,59 @@ export interface components {
              * @description The organization that owns this callback subscription.
              */
             orgId: string;
-            /** @description HTTP(S) endpoint that receives the event. It may contain `{{sessionId}}` and top-level session-context placeholders such as `{{orderId}}`. The Builder URI-encodes each value and stores the expanded URL when it creates the delivery. */
-            callbackUrl: string;
+            deliveryMode: components["schemas"]["CallbackDeliveryMode"];
+            /** @description HTTP(S) endpoint that receives the event. It may contain `{{sessionId}}` and top-level session-context placeholders such as `{{orderId}}`. The Builder URI-encodes each value and stores the expanded URL when it creates the delivery. Absent when `deliveryMode` is `pull`. */
+            callbackUrl?: string;
+            /** @description Present when `deliveryMode` is `pull`. The pull subscription receives events and satisfies the session-creation check only until this time. Renew it by repeating the create request. */
+            listenerExpiresAt?: components["schemas"]["Timestamp"];
             /** @description Events this subscription wants delivered — any subset of `VerificationEvent`. Builder terminal events are `verification_success`, `verification_rejected`, `verification_error`, `verification_cancelled`, and `session_expired`. Terminal result deliveries contain the signed result when one is available; non-terminal events deliver a plaintext notification. */
             events: components["schemas"]["VerificationEvent"][];
             createdAt: components["schemas"]["Timestamp"];
             updatedAt: components["schemas"]["Timestamp"];
         };
-        /** @description Body for `POST /verifications/callback-subscriptions`. The owning organization is resolved from the presented `OrgToken`; delivery is scoped to that org and encrypted to its credential when set. */
-        CreateCallbackSubscriptionRequest: {
+        /**
+         * @description How Builder delivers events. `webhook` POSTs each one to `callbackUrl`. `pull` keeps them for you to read with `GET /verifications/callback-events`.
+         * @enum {string}
+         */
+        CallbackDeliveryMode: "webhook" | "pull";
+        /** @description A subscription that Builder POSTs each delivery to. */
+        WebhookCallbackSubscriptionRequest: {
+            /**
+             * @description Omit it or send `webhook`.
+             * @enum {string}
+             */
+            deliveryMode?: "webhook";
             /** @description Callback URL or template. Supported placeholders are `{{sessionId}}` and top-level scalar context keys. */
             callbackUrl: string;
             events: components["schemas"]["VerificationEvent"][];
         };
-        /** @description Body for `POST /orgs/{orgId}/callback-subscriptions`. The owning organization comes from the path; bearer-authenticated and gated on org membership. Delivery is scoped to the org and encrypted to its credential when set. */
-        CreateOrgCallbackSubscriptionRequest: {
-            /** @description Callback URL or template. Supported placeholders are `{{sessionId}}` and top-level scalar context keys. */
-            callbackUrl: string;
-            events: components["schemas"]["VerificationEvent"][];
+        /** @description A subscription whose deliveries wait for you to read them. It has no URL. An org has at most one. */
+        PullCallbackSubscriptionRequest: {
+            /** @enum {string} */
+            deliveryMode: "pull";
+            /** @description Not allowed. A pull subscription has no URL. */
+            callbackUrl?: unknown;
+            /** @description Events to keep. Defaults to every event. */
+            events?: components["schemas"]["VerificationEvent"][];
+        };
+        /** @description Body for `POST /verifications/callback-subscriptions`. The owning organization is resolved from the presented `OrgToken`; delivery is scoped to that org and encrypted to its credential when set. Send `callbackUrl` for a webhook, or `deliveryMode: "pull"` for a subscription you read. */
+        CreateCallbackSubscriptionRequest: components["schemas"]["WebhookCallbackSubscriptionRequest"] | components["schemas"]["PullCallbackSubscriptionRequest"];
+        /** @description Body for `POST /orgs/{orgId}/callback-subscriptions`. The owning organization comes from the path; bearer-authenticated and gated on org membership. Delivery is scoped to the org and encrypted to its credential when set. Send `callbackUrl` for a webhook, or `deliveryMode: "pull"` for a subscription you read. */
+        CreateOrgCallbackSubscriptionRequest: components["schemas"]["WebhookCallbackSubscriptionRequest"] | components["schemas"]["PullCallbackSubscriptionRequest"];
+        /** @description One delivery waiting on the organization's pull subscription. */
+        CallbackEvent: {
+            /**
+             * Format: uuid
+             * @description Pass it to `POST /verifications/callback-events/acknowledge`.
+             */
+            id: string;
+            subscriptionId: components["schemas"]["SubscriptionID"];
+            sessionId: components["schemas"]["SessionID"];
+            event: components["schemas"]["VerificationEvent"];
+            /** @description `pending` until you acknowledge the event, then `delivered`. */
+            deliveryStatus: components["schemas"]["CallbackDeliveryStatus"];
+            createdAt: components["schemas"]["Timestamp"];
+            envelope: components["schemas"]["VerificationResultDelivery"];
         };
         /** @description Present only when the session's `mode` is `SANDBOX`. */
         SandboxLimits: {
@@ -6222,7 +6372,7 @@ export interface components {
                 signature: string;
             }[];
         };
-        /** @description The JSON envelope POSTed to a callback subscription's `callbackUrl` (see the `verificationResult` webhook). `sessionId`, `event` and `timestamp` are unauthenticated plaintext routing hints; branch on `event` for the shape of `data`. **Terminal result events** carry the signed result — an ECIES ciphertext (base64url, secp256k1 + AES-256-GCM) wrapping the signed JWS when the org has an encryption credential, else the plaintext signed JWS — act only on the signature-verified contents. **Non-terminal events** carry a plaintext, **unsigned** progress notification — advisory only; the signed terminal result is the source of truth. */
+        /** @description The JSON envelope POSTed to a callback subscription's `callbackUrl` (see the `verificationResult` webhook), and returned as `envelope` by `GET /verifications/callback-events` for a pull subscription. `sessionId`, `event` and `timestamp` are unauthenticated plaintext routing hints; branch on `event` for the shape of `data`. **Terminal result events** carry the signed result — an ECIES ciphertext (base64url, secp256k1 + AES-256-GCM) wrapping the signed JWS when the org has an encryption credential, else the plaintext signed JWS — act only on the signature-verified contents. **Non-terminal events** carry a plaintext, **unsigned** progress notification — advisory only; the signed terminal result is the source of truth. */
         VerificationResultDelivery: {
             sessionId: components["schemas"]["SessionID"];
             /** @description The event that produced this delivery. */
@@ -6370,8 +6520,11 @@ export interface components {
         VerificationDelivery: {
             subscriptionId: components["schemas"]["SubscriptionID"];
             event: components["schemas"]["VerificationEvent"];
-            /** Format: uri */
-            callbackUrl: string;
+            /**
+             * Format: uri
+             * @description Absent for deliveries to a pull subscription.
+             */
+            callbackUrl?: string;
             deliveryStatus: components["schemas"]["CallbackDeliveryStatus"];
             attempts: number;
             lastAttemptAt?: components["schemas"]["Timestamp"];
@@ -8521,6 +8674,27 @@ export interface operations {
             default: components["responses"]["ProblemResponse"];
         };
     };
+    AgentInstallationMarkdown: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The guide as Markdown. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/markdown": string;
+                };
+            };
+            default: components["responses"]["ProblemResponse"];
+        };
+    };
     LoginPage: {
         parameters: {
             query?: {
@@ -8866,9 +9040,12 @@ export interface operations {
                 tab?: "overview" | "connect" | "integrate" | "providers" | "members" | "themes" | "settings" | "sessions" | "billing";
                 /** @description Integrate tab only. Which integration path to show: a coding agent over MCP, the client package, or plain HTTP. */
                 track?: "agent" | "sdk" | "http";
-                /** @description Integrate tab, agent track only. Which coding agent's install command to show. */
+                /**
+                 * @deprecated
+                 * @description Ignored.
+                 */
                 agent?: "claude" | "copilot" | "cursor" | "omp" | "opencode" | "codex" | "antigravity" | "others";
-                /** @description Integrate tab, agent track only. What users prove, as typed into the prompt's goal field; kept when another agent is picked. */
+                /** @description Integrate tab, agent track only. What users prove, as typed into the prompt's goal field. */
                 goal?: string;
                 /** @description Integrate tab: the providers to show in the examples in place of placeholder ids, for example when arriving from a provider page or a build page. Repeat to pass several. Dashboard tab: scopes the report to sessions that ran this provider (the first one); options come from `GET /orgs/{orgId}/providers/used`. */
                 providerId?: components["schemas"]["ProviderID"][];
@@ -10683,6 +10860,15 @@ export interface operations {
             };
         };
         responses: {
+            /** @description The org's existing pull subscription */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CallbackSubscription"];
+                };
+            };
             /** @description Subscription created */
             201: {
                 headers: {
@@ -10695,6 +10881,85 @@ export interface operations {
             default: components["responses"]["ProblemResponse"];
         };
     };
+    ReleaseCallbackListener: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Released */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            default: components["responses"]["ProblemResponse"];
+        };
+    };
+    ListCallbackEvents: {
+        parameters: {
+            query?: {
+                /** @description Cursor from the `next` field of a previous response. Returns only events after it. Omit it to start from the oldest event. */
+                after?: string;
+                /** @description Maximum number of events to return. Defaults to 50. */
+                limit?: number;
+                /** @description Returns only events of this verification session. */
+                sessionId?: components["schemas"]["SessionID"];
+                /** @description When `true`, returns only events you have not acknowledged. Defaults to `false`. */
+                pending?: boolean;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Ok */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        items: components["schemas"]["CallbackEvent"][];
+                        /** @description Cursor to pass as `after` on the next request. Equals `after` when `items` is empty, and `0` when you passed no `after`. */
+                        next: string;
+                    };
+                };
+            };
+            default: components["responses"]["ProblemResponse"];
+        };
+    };
+    AcknowledgeCallbackEvents: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description The `id` of each `CallbackEvent` to acknowledge. */
+                    ids: string[];
+                };
+            };
+        };
+        responses: {
+            /** @description Acknowledged */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            default: components["responses"]["ProblemResponse"];
+        };
+    };
     DeleteCallbackSubscription: {
         parameters: {
             query?: never;
@@ -10759,6 +11024,15 @@ export interface operations {
             };
         };
         responses: {
+            /** @description The org's existing pull subscription */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CallbackSubscription"];
+                };
+            };
             /** @description Subscription created */
             201: {
                 headers: {
@@ -11033,7 +11307,7 @@ export interface operations {
                     "application/problem+json": components["schemas"]["Problem"];
                 };
             };
-            /** @description No callback subscription exists for the organization. Register one first via `POST /verifications/callback-subscriptions` (or `POST /orgs/{orgId}/callback-subscriptions`). */
+            /** @description No callback subscription exists for the organization. Register one first via `POST /verifications/callback-subscriptions` (or `POST /orgs/{orgId}/callback-subscriptions`). A pull subscription satisfies this check only while its listener lease is unexpired. */
             409: {
                 headers: {
                     [name: string]: unknown;