@1claw/sdk 0.44.1 → 0.45.0

package/README.md

@@ -1,6 +1,10 @@
 # @1claw/sdk
 
-TypeScript SDK for **1Claw Vault** — HSM-backed secret management for AI agents and humans.
+TypeScript/JavaScript client for the 1Claw Vault API.
+
+This is the official SDK for Node.js, Next.js, and browser apps that call 1Claw over HTTP. It covers vaults, secrets, agents, policies, treasury, Intents API signing, execution bindings, platform apps, billing, and x402 payments. Types are generated from the OpenAPI spec, so request shapes stay in sync with the API.
+
+Agent keys auto-exchange for JWTs and refresh before expiry. If you're wiring an AI agent in Cursor or Claude Desktop, you probably want [@1claw/mcp](https://www.npmjs.com/package/@1claw/mcp) instead. If you're building a web app or backend service in TypeScript, start here.
 
 ## Install
 
@@ -93,7 +97,7 @@ await client.auth.verifyEmailChange({ code: "123456" });
 | `client.billing`   | `usage`, `history`, `llmTokenBilling`, `subscribeLlmTokenBilling`, `disableLlmTokenBilling` (LLM token billing / Stripe AI Gateway) |
 | `client.audit`     | `query`                                                                                                             |
 | `client.org`       | `listMembers`, `getAgentKeysVault`, `updateMemberRole`, `removeMember`                                              |
-| `client.auth`      | `login`, `signup`, `agentToken`, `apiKeyToken`, `google`, `socialLogin`, `sendEmailOtp`, `verifyEmailOtp`, `exchangeOAuthCode`, `changePassword`, `setPassword`, `changeEmail`, `verifyEmailChange`, `forgotPassword`, `resetPassword`, `exportData`, `exchangeFederatedToken`, `logout`, `getMe`, `updateMe`, `deleteMe` |
+| `client.auth`      | `login`, `signup`, `agentToken`, `apiKeyToken`, `google`, `socialLogin`, `sendEmailOtp`, `verifyEmailOtp`, `exchangeOAuthCode`, `revokeToken`, `revokeConsent`, `getUserInfo`, `changePassword`, `setPassword`, `changeEmail`, `verifyEmailChange`, `forgotPassword`, `resetPassword`, `exportData`, `exchangeFederatedToken`, `logout`, `getMe`, `updateMe`, `deleteMe` |
 | `client.apiKeys`   | `create`, `list`, `revoke`                                                                                          |
 | `client.treasury`  | `create`, `list`, `get`, `update`, `delete`, `addSigner`, `removeSigner`, `requestAccess`, `listAccessRequests`, `approveAccess`, `denyAccess`, `propose`, `listProposals`, `getProposal`, `signProposal`, `executeProposal` |
 | `client.treasuryWallets` | `generateWallets`, `listWallets`, `getWallet`, `getWalletBalance`, `sendFromWallet`, `swapFromWallet`, `exportWallet`, `rotateWallet`, `deactivateWallet`, `getEffectiveSpendPolicy` |
@@ -102,7 +106,7 @@ await client.auth.verifyEmailChange({ code: "123456" });
 | `client.fiat` | `createOnrampSession`, `initiateOfframp` |
 | `client.signingKeys` | `create`, `list`, `rotate`, `deactivate`, `export`                                                               |
 | `client.agents` (Bankr) | `leaseBankrKey`, `listBankrKeys`, `revokeBankrKey` — privileged; `api_key` omitted for agent JWTs (use Shroud) |
-| `client.platform`  | `createApp`, `listApps`, `getApp`, `updateApp`, `deleteApp`, `rotateKey`, `createTemplate`, `listTemplates`, `upsertUser`, `listUsers`, `bootstrapUser`, `reissueClaim`, `claimPreview`, `claimRedeem`, `listConnectedApps`, `disconnectApp`, `grantAccess`, `listGrants`, `revokeGrant`, `createSpendPolicy`, `listSpendPolicies`, `setUserSpendPolicy`, `deleteSpendPolicy`, `updateConnectionDelegation` |
+| `client.platform`  | `createApp`, `listApps`, `getApp`, `updateApp`, `deleteApp`, `rotateKey`, `rotateWebhookSecret`, `getAppStats`, `marketplace`, `createTemplate`, `listTemplates`, `upsertUser`, `listUsers`, `bootstrapUser`, `reissueClaim`, `claimPreview`, `claimRedeem`, `listConnectedApps`, `disconnectApp`, `grantAccess`, `listGrants`, `revokeGrant`, `createSpendPolicy`, `listSpendPolicies`, `setUserSpendPolicy`, `deleteSpendPolicy`, `updateConnectionDelegation` |
 | `client.devices`   | `register`, `list`, `delete`, `challenge`, `attest`, `setPushToken`                                                 |
 | `client.passkeys`  | `list`, `registerBegin`, `registerComplete`, `assertBegin`, `assertComplete`, `delete`                               |
 | `client.risk`      | `listEvents`, `getVerdict`, `listVerdicts`, `createHoneytoken`, `listHoneytokens`, `deleteHoneytoken`                |
@@ -352,6 +356,44 @@ console.log(agent.data?.tx_count_today);           // e.g. 42
 console.log(agent.data?.tx_overhead_today_by_chain); // e.g. { "solana": "0.12" }
 ```
 
+## OAuth2 / PKCE ("Sign in with 1Claw")
+
+The SDK provides helpers for implementing the full OAuth2 PKCE flow and managing tokens/consent:
+
+```typescript
+import { generatePKCE, buildAuthorizeUrl, createClient } from "@1claw/sdk";
+
+// 1. Generate PKCE pair
+const pkce = await generatePKCE();
+
+// 2. Build the authorize URL
+const authUrl = buildAuthorizeUrl("https://1claw.xyz", {
+    clientId: "your-platform-app-slug",
+    redirectUri: "https://yourapp.com/callback",
+    scopes: ["openid", "profile", "email"],
+    state: "random-state",
+    codeChallenge: pkce.codeChallenge,
+});
+
+// 3. After redirect, exchange the code for tokens
+const client = createClient({ baseUrl: "https://api.1claw.xyz" });
+const tokens = await client.auth.exchangeOAuthCode({
+    code: "authorization-code-from-callback",
+    client_id: "your-platform-app-slug",
+    redirect_uri: "https://yourapp.com/callback",
+    code_verifier: pkce.codeVerifier,
+});
+
+// 4. Fetch user info
+const userInfo = await client.auth.getUserInfo(tokens.data?.access_token);
+
+// 5. Revoke a token (RFC 7009)
+await client.auth.revokeToken({ token: "...", token_type_hint: "refresh_token" });
+
+// 6. Revoke consent for an app (invalidates all tokens)
+await client.auth.revokeConsent("platform-app-id");
+```
+
 ## OIDC Federation (Anthropic WIF, GCP STS, AWS STS)
 
 `https://api.1claw.xyz` is a fully OpenID Connect–compliant issuer. External relying parties — Anthropic Workload Identity Federation, GCP STS, AWS STS, Stytch, etc. — can validate 1claw-issued JWTs by fetching:

package/dist/generated/api-types.d.ts

@@ -3221,6 +3221,46 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/platform/apps/{appId}/stats": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get platform app statistics
+         * @description Returns aggregate statistics about a platform app's connected users, bootstraps, and grants.
+         */
+        get: operations["getPlatformAppStats"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/platform/apps/{appId}/rotate-webhook-secret": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Rotate webhook secret
+         * @description Generate a new webhook signing secret for the platform app. The old secret is immediately invalidated. Returns the new secret (one-time).
+         */
+        post: operations["rotatePlatformWebhookSecret"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/platform/apps/{appId}/templates": {
         parameters: {
             query?: never;
@@ -4406,6 +4446,48 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/oauth/revoke": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Revoke an OAuth token (RFC 7009)
+         * @description Revokes an access token or refresh token. The authorization server
+         *     invalidates the token so it can no longer be used. Follows RFC 7009.
+         */
+        post: operations["revokeOAuthToken"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/oauth/consents/{app_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /**
+         * Revoke consent for a platform app
+         * @description Revokes the user's previously granted OAuth consent for a specific platform app.
+         *     All active tokens issued to the app are invalidated and the consent record is deleted.
+         */
+        delete: operations["revokeOAuthConsent"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/risk/events": {
         parameters: {
             query?: never;
@@ -5227,6 +5309,28 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/agents/org-directory": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List org agents
+         * @description List agents within the caller's organization for sub-agent discovery.
+         *     Returns agents with their capabilities, enabling agent-to-agent
+         *     coordination and discovery within an org. Requires authentication.
+         */
+        get: operations["listOrgDirectory"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/agents/{agent_id}/discovery": {
         parameters: {
             query?: never;
@@ -5253,7 +5357,7 @@ export interface paths {
         };
         /**
          * Public marketplace
-         * @description Browse the public platform marketplace of agents and apps.
+         * @description Browse the public platform marketplace of listed apps and agents. Returns approved platform apps with category, tags, pricing summaries, and screenshots.
          */
         get: operations["listMarketplace"];
         put?: never;
@@ -5277,6 +5381,11 @@ export interface paths {
          * Send chat message
          * @description Send a message to an agent and receive a response via Shroud LLM.
          *     Supports SSE streaming when Accept: text/event-stream is set.
+         *
+         *     Agents can call this endpoint on other agents within the same
+         *     organization for inter-agent communication (agent-to-agent chat).
+         *     The caller must be authenticated and belong to the same org as
+         *     the target agent.
          */
         post: operations["sendChatMessage"];
         delete?: never;
@@ -8211,6 +8320,8 @@ export interface components {
                 vault_id?: string | null;
                 /** Format: uuid */
                 agent_id?: string | null;
+                /** @description All agent IDs provisioned by the template (when multiple agents are defined) */
+                agent_ids?: string[];
                 policy_ids?: string[];
                 /** @description Chains with provisioned signing keys */
                 signing_key_chains?: string[];
@@ -8231,6 +8342,32 @@ export interface components {
                 automation_ids?: string[];
             };
         };
+        PlatformAppStatsResponse: {
+            /** @description Total number of user connections (all statuses) */
+            total_connections: number;
+            /** @description Number of active connections */
+            active_connections: number;
+            /** @description Number of claimed connections */
+            claimed_connections: number;
+            /** @description Total bootstrap operations performed */
+            total_bootstraps: number;
+            /** @description Total resource grants issued */
+            total_grants: number;
+        };
+        MarketplaceResponse: {
+            apps?: {
+                /** Format: uuid */
+                id?: string;
+                name?: string;
+                slug?: string;
+                description?: string;
+                logo_url?: string | null;
+                category?: string | null;
+                listing_tags?: string[];
+                listing_screenshots?: string[];
+                pricing_summary?: string | null;
+            }[];
+        };
         ConnectedAppResponse: {
             /** Format: uuid */
             connection_id?: string;
@@ -8436,6 +8573,8 @@ export interface components {
             token_type: "Bearer";
             /** @description Token lifetime in seconds */
             expires_in: number;
+            /** @description Refresh token for obtaining new access tokens (when offline_access scope was granted) */
+            refresh_token?: string | null;
             /** @description OIDC ID token (when openid scope was granted) */
             id_token?: string | null;
             scope: string;
@@ -9057,6 +9196,25 @@ export interface components {
             page: number;
             per_page: number;
         };
+        OrgDirectoryAgent: {
+            /** Format: uuid */
+            id: string;
+            name: string;
+            public_description?: string | null;
+            public_tags?: string[];
+            a2a_url?: string | null;
+            mcp_url?: string | null;
+            intents_api_enabled: boolean;
+            execution_intents_enabled: boolean;
+            memory_enabled: boolean;
+            shroud_enabled: boolean;
+        };
+        OrgDirectoryResponse: {
+            agents: components["schemas"]["OrgDirectoryAgent"][];
+            total: number;
+            page: number;
+            page_size: number;
+        };
         UpdateDiscoveryRequest: {
             discoverable?: boolean;
             public_description?: string;
@@ -9125,6 +9283,14 @@ export interface components {
             config: {
                 [key: string]: string;
             };
+            /** @description Enable slash commands on this channel */
+            slash_commands_enabled?: boolean;
+            /** @description Enable voice message transcription */
+            voice_transcription_enabled?: boolean;
+            /** @description List of allowed sender IDs */
+            sender_allowlist?: string[];
+            /** @description Enable auto-respond */
+            auto_respond_enabled?: boolean;
         };
         UpdateChannelRequest: {
             channel_name?: string;
@@ -9132,6 +9298,10 @@ export interface components {
             config?: {
                 [key: string]: string;
             };
+            slash_commands_enabled?: boolean;
+            voice_transcription_enabled?: boolean;
+            sender_allowlist?: string[];
+            auto_respond_enabled?: boolean;
         };
         ChannelResponse: {
             /** Format: uuid */
@@ -9154,6 +9324,21 @@ export interface components {
             config?: {
                 [key: string]: unknown;
             } | null;
+            /** @description Whether slash commands are enabled for this channel */
+            slash_commands_enabled?: boolean;
+            /** @description Whether voice message transcription is enabled */
+            voice_transcription_enabled?: boolean;
+            /**
+             * Format: uuid
+             * @description ID linking this channel to a unified cross-platform conversation
+             */
+            unified_conversation_id?: string | null;
+            /** @description Whether this is the agent's home platform channel */
+            is_home_platform?: boolean;
+            /** @description List of allowed sender IDs for auto-respond */
+            sender_allowlist?: string[] | null;
+            /** @description Whether auto-respond is enabled for this channel */
+            auto_respond_enabled?: boolean;
             /** Format: date-time */
             created_at?: string;
             /** Format: date-time */
@@ -9181,6 +9366,17 @@ export interface components {
             sender_name?: string;
             content?: string;
             media_url?: string;
+            /** @description Whether this message was a voice message */
+            is_voice_message?: boolean;
+            /** @description Telegram voice file ID */
+            voice_file_id?: string | null;
+            /** @description Duration of voice message in seconds */
+            voice_duration_secs?: number | null;
+            /**
+             * @description Status of voice transcription
+             * @enum {string|null}
+             */
+            transcription_status?: "pending" | "completed" | "failed" | null;
             /** Format: date-time */
             created_at?: string;
         };
@@ -14072,6 +14268,64 @@ export interface operations {
             };
         };
     };
+    getPlatformAppStats: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                appId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description App statistics */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PlatformAppStatsResponse"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    rotatePlatformWebhookSecret: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                appId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description New webhook secret generated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @description The new webhook signing secret (shown once) */
+                        webhook_secret: string;
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            /** @description Only human users can rotate webhook secrets */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
     deletePlatformTemplate: {
         parameters: {
             query?: never;
@@ -15003,6 +15257,71 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
         };
     };
+    revokeOAuthToken: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description The token to revoke (access_token or refresh_token) */
+                    token: string;
+                    /**
+                     * @description Hint about the type of token being revoked
+                     * @enum {string}
+                     */
+                    token_type_hint?: "access_token" | "refresh_token";
+                };
+            };
+        };
+        responses: {
+            /** @description Token revoked successfully (or was already invalid) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @example true */
+                        revoked?: boolean;
+                    };
+                };
+            };
+        };
+    };
+    revokeOAuthConsent: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The platform app ID whose consent to revoke */
+                app_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Consent revoked */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @example true */
+                        revoked?: boolean;
+                        /** Format: uuid */
+                        app_id?: string;
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
     listRiskEvents: {
         parameters: {
             query?: {
@@ -16375,6 +16694,34 @@ export interface operations {
             };
         };
     };
+    listOrgDirectory: {
+        parameters: {
+            query?: {
+                /** @description Search query to filter agents by name or description */
+                q?: string;
+                /** @description Comma-separated tag filter */
+                tags?: string;
+                page?: number;
+                page_size?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Org agent directory listing */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgDirectoryResponse"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+        };
+    };
     updateDiscoverySettings: {
         parameters: {
             query?: never;
@@ -16411,6 +16758,8 @@ export interface operations {
                 per_page?: number;
                 /** @description Search query */
                 q?: string;
+                /** @description Filter by app category */
+                category?: string;
             };
             header?: never;
             path?: never;
@@ -16424,7 +16773,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["DirectoryResponse"];
+                    "application/json": components["schemas"]["MarketplaceResponse"];
                 };
             };
         };