@1claw/sdk 0.58.0 → 0.58.2

package/README.md

@@ -1,4 +1,4 @@
-# @1claw/sdk
+# @1claw/sdk (v0.58.2)
 
 TypeScript/JavaScript client for the 1Claw Vault API.
 
@@ -106,8 +106,19 @@ 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`, `rotateWebhookSecret`, `getAppStats`, `marketplace`, `createTemplate`, `listTemplates`, `upsertUser`, `listUsers`, `bootstrapUser`, `reissueClaim`, `claimPreview`, `claimRedeem`, `listConnectedApps`, `disconnectApp`, `grantAccess`, `listGrants`, `revokeGrant`, `createSpendPolicy`, `listSpendPolicies`, `setUserSpendPolicy`, `deleteSpendPolicy`, `updateConnectionDelegation`, **`siweChallenge`**, **`getConnection`**, **`getConnectionUsage`**, **`listEntitlements`**, **`refreshEntitlements`**, **`previewTemplate`** |
+| `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`, **`siweChallenge`**, **`getConnection`**, **`getConnectionUsage`**, **`listEntitlements`**, **`refreshEntitlements`**, **`previewTemplate`**, **`transferAppOwnership`**, **`getSpendPolicy`**, **`getConnectionSpendPolicy`**, **`listConnectionApprovals`**, **`getConnectionApproval`**, **`listConnectionPendingApprovals`** |
 | `client.treasuryWallets` | … **`getInferenceBudget`** (platform-connected users) |
+| `client.bindings`  | `create`, `list`, `get`, `update`, `delete`, `test`, `execute`, `rotateCredential`, `listExecutions` |
+| `client.chat`      | `sendMessage`, `sendMessageStream`, `listConversations`, `getConversation`, `deleteConversation` |
+| `client.channels`  | `create`, `list`, `update`, `delete`, `send`, `test`, `refreshWebhook`, `listMessages` |
+| `client.oauthConnect` | `listProviders`, `listConnections`, `connect`, `disconnect`, `saveAppCredentials`, `listAppCredentials`, `deleteAppCredentials` |
+| `client.cedarPolicies` | `create`, `list`, `get`, `delete`, `test` |
+| `client.opaPolicies` | `create`, `list`, `get`, `delete`, `test` |
+| `client.contractAbis` | `upload`, `list`, `delete` |
+| `client.pendingApprovals` | `list`, `get`, `approve`, `execute`, `cancel` |
+| `client.subOrgs`   | `create`, `list`, `get`, `delete`, `grantPermission`, `revokePermission`, `addUser`, `generateWallets` |
+| `client.portfolio` | `get` |
+| `client.cards`     | `order`, `orderGiftCard`, `searchGiftCards`, `list`, `get`, `reveal`, `update`, `void`, `refresh`, `import` |
 | `client.devices`   | `register`, `list`, `delete`, `challenge`, `attest`, `setPushToken`                                                 |
 | `client.passkeys`  | `list`, `registerBegin`, `registerComplete`, `assertBegin`, `assertComplete`, `delete`                               |
 | `client.risk`      | `listEvents`, `getVerdict`, `listVerdicts`, `createHoneytoken`, `listHoneytokens`, `deleteHoneytoken`                |
@@ -1017,6 +1028,41 @@ await client.platform.previewTemplate(appId, templateId, { parameters: { agent_n
 await client.treasuryWallets.getInferenceBudget();
 ```
 
+## v0.58 — Platform API control plane
+
+App-scoped reads, spend-policy idempotency, and ownership transfer (plt_ auth unless noted):
+
+```typescript
+await client.platform.transferAppOwnership(appId, {
+    target_org_id: "org-uuid",
+});
+await client.platform.getSpendPolicy(appId, policyId);
+await client.platform.getConnectionSpendPolicy(connectionId);
+await client.platform.listConnectionApprovals(connectionId);
+await client.platform.getConnectionApproval(connectionId, approvalId);
+await client.platform.listConnectionPendingApprovals(connectionId);
+await client.platform.getTemplate(appId, templateId);
+await client.platform.createConnectionRuntime(connectionId, {
+    name: "my-runtime",
+    agent_id: "agent-uuid",
+    preset: "small",
+    template: "openclaw",
+});
+await client.platform.connectionAgentChat(connectionId, agentId, {
+    message: "Hello",
+});
+await client.platform.decideConnectionPendingApproval(connectionId, approvalId, {
+    decision: "approve",
+    payload_hash: "...",
+    credential_type: "wallet_mandate",
+});
+await client.platform.decideConnectionApproval(connectionId, approvalId, {
+    decision: "approved",
+});
+await client.platform.deactivateConnectionSigningKey(connectionId, "ethereum", agentId);
+// setUserSpendPolicy(connectionId, data, { idempotencyKey: "..." }) — 24h replay protection
+```
+
 ## OpenAPI Types
 
 The SDK's request types are generated from the **OpenAPI 3.1** spec, published as [@1claw/openapi-spec](https://www.npmjs.com/package/@1claw/openapi-spec). Advanced users can access the raw generated types:

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

@@ -4147,7 +4147,11 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /**
+         * Get a bootstrap template
+         * @description Returns the full template spec for a platform app. plt_ or user JWT.
+         */
+        get: operations["getPlatformTemplate"];
         put?: never;
         post?: never;
         /** Delete a bootstrap template */
@@ -5120,9 +5124,10 @@ export interface paths {
         get: operations["getConnectionSpendPolicy"];
         /**
          * Set per-user spend policy override
-         * @description Override the app-wide spend policy for a specific connected user. This
-         *     policy takes precedence over the app default. Remove by deleting the
-         *     connection-level policy.
+         * @description Replace the per-user spend policy for a connected user (deactivates the
+         *     previous active row, then inserts). Requires plt_ platform auth.
+         *     Optional `Idempotency-Key` header must cover the full request body — reusing
+         *     the same key with different parameters returns 409.
          */
         put: operations["setUserSpendPolicy"];
         post?: never;
@@ -5192,6 +5197,132 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/platform/connections/{connectionId}/pending-approvals/{approvalId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get a connection-scoped pending approval (with payload_hash) */
+        get: operations["getConnectionPendingApproval"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/platform/connections/{connectionId}/pending-approvals/{approvalId}/decide": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Decide a pending approval for a connection user
+         * @description Platform apps vote on behalf of the connected user after verifying intent
+         *     out-of-band (e.g. wallet mandate). Requires `payload_hash` matching the
+         *     pending row. Accepts `decision`: `approve` or `reject` (aliases `approved` /
+         *     `rejected`). plt_ auth only; scoped to agents on the connection.
+         */
+        post: operations["decideConnectionPendingApproval"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/platform/connections/{connectionId}/approvals/{approvalId}/decide": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Decide a mobile/agent approval for a connection user
+         * @description Platform apps decide agent approval requests on behalf of the connected user.
+         *     Accepts `decision`: `approved` or `rejected` (aliases `approve` / `reject`).
+         *     plt_ auth only.
+         */
+        post: operations["decideConnectionApproval"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/platform/connections/{connectionId}/signing-keys/{chain}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /**
+         * Deactivate a signing key for a connection agent
+         * @description Deactivates the signing key for an agent provisioned on the connection.
+         *     When multiple agents exist, pass `agent_id` query param. plt_ auth only.
+         */
+        delete: operations["deactivateConnectionSigningKey"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/platform/connections/{connectionId}/runtimes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create a runtime for a connection agent
+         * @description Creates a Cloud Runtime in the end-user's org for an agent on this connection.
+         *     Use instead of `POST /v1/runtimes` with a plt_ key (which resolves to the platform org).
+         *     App must verify user intent out-of-band (e.g. wallet mandate) before calling.
+         */
+        post: operations["createConnectionRuntime"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/platform/connections/{connectionId}/agents/{agentId}/chat": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Chat with a connection agent (plt_ scoped)
+         * @description Send a chat message to an agent provisioned on this connection, acting as the
+         *     connected end-user. Use instead of `POST /v1/agents/{id}/chat` with a plt_ key.
+         */
+        post: operations["connectionAgentChat"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/approvals": {
         parameters: {
             query?: never;
@@ -6190,6 +6321,29 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/agents/{agent_id}/automations": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create agent automation (agent-only)
+         * @description Agent-scoped create for simple manual or webhook automations from chat/runtime tools.
+         *     Allowed step types: log, notify, memory_get, memory_put, wait (max 10).
+         *     Cron, swap, http, and transaction steps require human dashboard setup.
+         *     Requires agent JWT; agent_id in path must match the caller.
+         */
+        post: operations["createAgentAutomation"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/runtimes": {
         parameters: {
             query?: never;
@@ -11120,6 +11274,8 @@ export interface components {
             wallet_address?: string | null;
             vault_ids: string[];
             agent_ids: string[];
+            runtime_ids?: string[];
+            automation_ids?: string[];
             /** Format: date-time */
             claimed_at?: string | null;
             claim: components["schemas"]["ClaimStatusResponse"];
@@ -11615,6 +11771,28 @@ export interface components {
                 [key: string]: unknown;
             };
         };
+        /**
+         * @description Agent-scoped automation create. Defaults to manual trigger.
+         *     workflow_spec must use only agent-allowed step types (log, notify, memory_get, memory_put, wait).
+         */
+        AgentCreateAutomationRequest: {
+            name: string;
+            /**
+             * @default manual
+             * @enum {string}
+             */
+            trigger_type: "manual" | "webhook";
+            workflow_spec: {
+                [key: string]: unknown;
+            }[] | {
+                [key: string]: unknown;
+            };
+            /**
+             * @description When true (manual trigger only), start a run immediately after creation
+             * @default false
+             */
+            auto_trigger: boolean;
+        };
         UpdateAutomationRequest: {
             name?: string;
             cron_expr?: string | null;
@@ -11660,6 +11838,11 @@ export interface components {
             success_rate?: number | null;
             /** @description Resolved agent display name (enriched list field) */
             agent_name?: string | null;
+            /**
+             * @description Whether the automation was created by a human or agent (chat-native create)
+             * @enum {string}
+             */
+            created_by_type?: "user" | "agent";
             /** Format: date-time */
             created_at: string;
             /** Format: date-time */
@@ -11731,6 +11914,25 @@ export interface components {
                 };
             }[];
         };
+        CreateConnectionRuntimeRequest: {
+            name: string;
+            /**
+             * Format: uuid
+             * @description Required when multiple agents on the connection; defaults to sole agent
+             */
+            agent_id?: string;
+            template?: string;
+            /** @default medium */
+            preset: string;
+            env_public?: {
+                [key: string]: unknown;
+            };
+            idle_timeout_secs?: number;
+            expose_http?: boolean;
+            slug?: string;
+            inbound_auth?: string;
+            startup_command?: string;
+        };
         CreateRuntimeRequest: {
             name: string;
             /** Format: uuid */
@@ -12738,7 +12940,7 @@ export interface components {
         };
         ApprovePendingApprovalRequest: {
             /** @enum {string} */
-            decision: "approve" | "reject";
+            decision: "approve" | "reject" | "approved" | "rejected";
             payload_hash: string;
             reason?: string;
             /**
@@ -19407,6 +19609,30 @@ export interface operations {
             404: components["responses"]["NotFound"];
         };
     };
+    getPlatformTemplate: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                appId: string;
+                template_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Template details */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PlatformTemplateResponse"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
     deletePlatformTemplate: {
         parameters: {
             query?: never;
@@ -19786,6 +20012,193 @@ export interface operations {
             404: components["responses"]["NotFound"];
         };
     };
+    getConnectionPendingApproval: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connectionId: string;
+                approvalId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Pending approval detail including action_payload and payload_hash */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PendingApprovalResponse"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    decideConnectionPendingApproval: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connectionId: string;
+                approvalId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ApprovePendingApprovalRequest"];
+            };
+        };
+        responses: {
+            /** @description Updated pending approval */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PendingApprovalResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description Already voted */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    decideConnectionApproval: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connectionId: string;
+                approvalId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @enum {string} */
+                    decision: "approved" | "rejected" | "approve" | "reject";
+                    reason?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Decided approval */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApprovalResponse"];
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description Already decided */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    deactivateConnectionSigningKey: {
+        parameters: {
+            query?: {
+                agent_id?: string;
+            };
+            header?: never;
+            path: {
+                connectionId: string;
+                chain: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Key deactivated */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Multiple agents — agent_id required */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    createConnectionRuntime: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connectionId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateConnectionRuntimeRequest"];
+            };
+        };
+        responses: {
+            /** @description Runtime created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RuntimeResponse"];
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    connectionAgentChat: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connectionId: string;
+                agentId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SendChatMessageRequest"];
+            };
+        };
+        responses: {
+            /** @description Message sent (JSON or SSE stream) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
     listApprovals: {
         parameters: {
             query?: {
@@ -21428,6 +21841,36 @@ export interface operations {
             };
         };
     };
+    createAgentAutomation: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                agent_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["AgentCreateAutomationRequest"];
+            };
+        };
+        responses: {
+            /** @description Automation created (includes one-time webhook credentials when trigger_type is webhook) */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AutomationCreatedResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
     listRuntimes: {
         parameters: {
             query?: never;