@1claw/sdk 0.15.2 → 0.16.0

package/README.md

@@ -73,11 +73,11 @@ await client.auth.google({ id_token: "..." });
 | `client.vault`     | `create`, `get`, `list`, `delete`                                                                                   |
 | `client.secrets`   | `set`, `get`, `delete`, `list`, `rotate`                                                                            |
 | `client.access`    | `grantHuman`, `grantAgent`, `update`, `revoke`, `listGrants`                                                        |
-| `client.agents`    | `create`, `getSelf`, `get`, `list`, `update`, `delete`, `rotateKey`, `submitTransaction`, `getTransaction`, `listTransactions`, `simulateTransaction`, `simulateBundle` |
+| `client.agents`    | `create`, `getSelf`, `get`, `list`, `update`, `delete`, `rotateKey`, `submitTransaction`, `signTransaction`, `getTransaction`, `listTransactions`, `simulateTransaction`, `simulateBundle` |
 | `client.chains`    | `list`, `get`, `adminList`, `create`, `update`, `delete`                                                            |
 | `client.sharing`   | `create`, `access`, `listOutbound`, `listInbound`, `accept`, `decline`, `revoke`                                    |
 | `client.approvals` | `request`, `list`, `approve`, `deny`, `check`, `subscribe`                                                          |
-| `client.billing`   | `usage`, `history`                                                                                                  |
+| `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`, `changePassword`, `logout`, `getMe`, `updateMe`, `deleteMe` |
@@ -191,6 +191,26 @@ The backend fetches the signing key from the vault, signs the EIP-155 transactio
 
 The SDK automatically generates an `Idempotency-Key` header (UUID v4) on each `submitTransaction` call, providing replay protection. Duplicate requests within 24 hours return the cached response instead of re-signing.
 
+### Sign-only mode (BYORPC)
+
+Use `signTransaction` when you want the server to sign but **not** broadcast — for example, to submit via your own RPC (Flashbots, MEV protection, custom relayers):
+
+```typescript
+const signRes = await client.agents.signTransaction(agentId, {
+    to: "0x000000000000000000000000000000000000dEaD",
+    value: "0.01",
+    chain: "base",
+});
+
+console.log(signRes.data?.signed_tx); // raw signed tx hex
+console.log(signRes.data?.tx_hash);   // precomputed keccak hash
+console.log(signRes.data?.from);      // derived sender address
+
+// Broadcast yourself via ethers, viem, or raw JSON-RPC
+```
+
+All agent guardrails (allowlists, value caps, daily limits) are enforced exactly as for submit. The transaction is recorded for audit and daily-limit tracking with `status: "sign_only"`.
+
 Key properties:
 
 - **Disabled by default** — a human must explicitly enable per-agent
@@ -318,6 +338,11 @@ const { data } = await client.agents.create({
         pii_policy: "redact",           // block | redact | warn | allow
         injection_threshold: 0.7,
 
+        // Model restrictions
+        allowed_models: ["gpt-4o-mini", "claude-sonnet-4"],  // Whitelist specific models
+        denied_models: ["gpt-3.5-turbo"],                   // Blacklist models
+        allowed_providers: ["openai", "anthropic"],          // Restrict providers
+
         // Threat detection
         unicode_normalization: {
             enabled: true,
@@ -351,10 +376,41 @@ await client.agents.update(agentId, {
     shroud_config: {
         command_injection_detection: { enabled: true, action: "block" },
         social_engineering_detection: { enabled: true, action: "block" },
+        allowed_models: ["gpt-4o-mini"],  // Restrict to cost-effective models
     },
 });
 ```
 
+### Specifying Models in Requests
+
+When making LLM requests to Shroud, specify the model in one of two ways:
+
+**Option 1: Header**
+```typescript
+const res = await fetch("https://shroud.1claw.xyz/v1/chat/completions", {
+  method: "POST",
+  headers: {
+    "X-Shroud-Agent-Key": `${agentId}:${agentApiKey}`,
+    "X-Shroud-Provider": "openai",
+    "X-Shroud-Model": "gpt-4o-mini",  // ← Model in header
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    messages: [{ role: "user", content: "Hello" }],
+  }),
+});
+```
+
+**Option 2: Request Body** (for OpenAI-style providers)
+```typescript
+body: JSON.stringify({
+  model: "gpt-4o-mini",  // ← Model in body
+  messages: [{ role: "user", content: "Hello" }],
+})
+```
+
+Shroud enforces the agent's `allowed_models` and `denied_models` restrictions automatically — requests using unauthorized models return **403 Forbidden**.
+
 See the [Shroud Security Guide](https://docs.1claw.xyz/docs/guides/shroud) for full configuration options.
 
 ## OpenAPI Types
@@ -369,7 +425,7 @@ type Vault = ApiSchemas["VaultResponse"];
 type Agent = ApiSchemas["AgentResponse"];
 ```
 
-Regenerate types after spec changes: `npm run generate`
+Regenerate types after spec changes (from the monorepo): `cd packages/sdk && npm run generate` — reads [`../openapi-spec/openapi.yaml`](../openapi-spec/openapi.yaml) via `openapi-typescript`.
 
 ## MCP Integration (AI Agents)
 

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

@@ -735,6 +735,32 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/agents/{agent_id}/transactions/sign": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Sign a transaction without broadcasting
+         * @description Signs a transaction inside the server (or TEE when using Shroud) but does
+         *     **not** broadcast it. The caller receives the raw `signed_tx` hex and
+         *     `tx_hash` so it can submit to any RPC of its choosing.
+         *
+         *     All agent guardrails (allowlists, value caps, daily limits) are enforced
+         *     exactly as for the submit endpoint. The signed transaction is recorded for
+         *     audit and daily-limit tracking with `status: "sign_only"`.
+         */
+        post: operations["signTransaction"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/agents/{agent_id}/transactions/simulate": {
         parameters: {
             query?: never;
@@ -1150,6 +1176,66 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/billing/llm-token-billing": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get LLM token billing status
+         * @description Returns whether LLM token billing is enabled for the caller's org.
+         */
+        get: operations["getLlmTokenBilling"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/billing/llm-token-billing/subscribe": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Subscribe to LLM token billing
+         * @description Creates a Stripe Checkout session for the LLM token billing pricing plan. Returns a checkout URL to redirect the user. After the user completes checkout, a webhook activates LLM billing for the org.
+         */
+        post: operations["subscribeLlmTokenBilling"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/billing/llm-token-billing/disable": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Disable LLM token billing
+         * @description Disables LLM token billing for the org and cancels all active Stripe subscriptions for the LLM pricing plan. Agents will fall back to direct provider routing. You can re-enable it at any time.
+         */
+        post: operations["disableLlmTokenBilling"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/billing/overage-method": {
         parameters: {
             query?: never;
@@ -1553,8 +1639,11 @@ export interface components {
             refresh_token?: string;
         };
         AgentTokenRequest: {
-            /** Format: uuid */
-            agent_id: string;
+            /**
+             * Format: uuid
+             * @description Optional when using key-only auth (ocv_ keys auto-resolve agent)
+             */
+            agent_id?: string;
             api_key: string;
         };
         UserApiKeyTokenRequest: {
@@ -1603,6 +1692,11 @@ export interface components {
         };
         DeviceCodeRequest: {
             client_id: string;
+            /**
+             * Format: email
+             * @description Account email; only that user may approve the code in the dashboard.
+             */
+            email: string;
         };
         DeviceCodeResponse: {
             device_code?: string;
@@ -2187,6 +2281,48 @@ export interface components {
             max_priority_fee_per_gas?: string;
             /** @default false */
             simulate_first: boolean;
+            /**
+             * @description Transaction mode
+             * @default eoa
+             * @enum {string}
+             */
+            mode: "eoa" | "smart_account";
+        };
+        SignTransactionRequest: {
+            /** @description Destination address (0x-prefixed) */
+            to: string;
+            /** @description Value in ETH */
+            value: string;
+            /** @description Chain name or numeric ID */
+            chain: string;
+            /** @description Hex-encoded calldata */
+            data?: string;
+            signing_key_path?: string;
+            nonce?: number;
+            gas_price?: string;
+            gas_limit?: number;
+            max_fee_per_gas?: string;
+            max_priority_fee_per_gas?: string;
+            /** @default false */
+            simulate_first: boolean;
+        };
+        SignTransactionResponse: {
+            /** @description Raw signed transaction hex (always included) */
+            signed_tx?: string;
+            tx_hash?: string;
+            /** @description Derived sender address */
+            from?: string;
+            to?: string;
+            chain?: string;
+            chain_id?: number;
+            nonce?: number;
+            value_wei?: string;
+            /** @enum {string} */
+            status?: "sign_only";
+            simulation_id?: string;
+            simulation_status?: string;
+            max_fee_per_gas?: string;
+            max_priority_fee_per_gas?: string;
         };
         SimulateTransactionRequest: {
             to: string;
@@ -2209,8 +2345,8 @@ export interface components {
             to?: string;
             value_wei?: string;
             /** @enum {string} */
-            status?: "pending" | "signed" | "broadcast" | "failed" | "simulation_failed";
-            /** @description Raw signed transaction hex. Omitted (null) by default to reduce exfiltration risk. Pass `include_signed_tx=true` query param on GET endpoints to include it. Always returned on the initial POST submission response. */
+            status?: "pending" | "signed" | "sign_only" | "broadcast" | "failed" | "simulation_failed";
+            /** @description Raw signed transaction hex. On GET list and GET by id, this property is omitted by default (absent from the response). Pass `include_signed_tx=true` on those endpoints to include it. Always present on the initial POST submit response. */
             signed_tx?: string | null;
             tx_hash?: string;
             error_message?: string;
@@ -2451,6 +2587,18 @@ export interface components {
             used?: number;
             limit?: number;
         };
+        LlmTokenBillingStatus: {
+            enabled?: boolean;
+            /** @enum {string} */
+            subscription_status?: "active" | "inactive";
+        };
+        LlmCheckoutResponse: {
+            /** Format: uri */
+            checkout_url?: string;
+        };
+        LlmDisableResponse: {
+            enabled?: boolean;
+        };
         CreditBalanceResponse: {
             balance_cents?: number;
             balance_usd?: string;
@@ -2721,7 +2869,7 @@ export interface components {
         SecretPath: string;
         AgentId: string;
         PolicyId: string;
-        /** @description Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values "true" or "1" enable inclusion; any other value or omission returns responses without signed_tx. */
+        /** @description Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values "true" or "1" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}. */
         IncludeSignedTx: boolean;
     };
     requestBodies: never;
@@ -3986,7 +4134,7 @@ export interface operations {
     listTransactions: {
         parameters: {
             query?: {
-                /** @description Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values "true" or "1" enable inclusion; any other value or omission returns responses without signed_tx. */
+                /** @description Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values "true" or "1" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}. */
                 include_signed_tx?: components["parameters"]["IncludeSignedTx"];
             };
             header?: never;
@@ -4069,7 +4217,7 @@ export interface operations {
     getTransaction: {
         parameters: {
             query?: {
-                /** @description Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values "true" or "1" enable inclusion; any other value or omission returns responses without signed_tx. */
+                /** @description Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values "true" or "1" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}. */
                 include_signed_tx?: components["parameters"]["IncludeSignedTx"];
             };
             header?: never;
@@ -4093,6 +4241,35 @@ export interface operations {
             404: components["responses"]["NotFound"];
         };
     };
+    signTransaction: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                agent_id: components["parameters"]["AgentId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SignTransactionRequest"];
+            };
+        };
+        responses: {
+            /** @description Transaction signed successfully (not broadcast) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SignTransactionResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            402: components["responses"]["PaymentRequired"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
     simulateTransaction: {
         parameters: {
             query?: never;
@@ -4726,6 +4903,66 @@ export interface operations {
             };
         };
     };
+    getLlmTokenBilling: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description LLM token billing status */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LlmTokenBillingStatus"];
+                };
+            };
+        };
+    };
+    subscribeLlmTokenBilling: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Stripe Checkout URL */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LlmCheckoutResponse"];
+                };
+            };
+        };
+    };
+    disableLlmTokenBilling: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description LLM billing disabled */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LlmDisableResponse"];
+                };
+            };
+        };
+    };
     billingOverageMethod: {
         parameters: {
             query?: never;