@1claw/sdk 0.44.3 → 0.46.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
 
@@ -86,14 +90,14 @@ await client.auth.verifyEmailChange({ code: "123456" });
 | `client.vault`     | `create`, `get`, `list`, `delete`, `enableMpc`, `disableMpc`                                                        |
 | `client.secrets`   | `set`, `get`, `delete`, `list`, `rotate`                                                                            |
 | `client.access`    | `grantHuman`, `grantAgent`, `update`, `revoke`, `listGrants`                                                        |
-| `client.agents`    | `enroll` (also `AgentsResource.enroll(baseUrl, …)` static), `create`, `getSelf`, `get`, `list`, `update`, `delete`, `rotateKey`, `generateEoa`, `createSmartAccount`, `deleteSmartAccount`, `rotateSigner`, `submitTransaction`, `signTransaction`, `getTransaction`, `listTransactions`, `simulateTransaction`, `simulateBundle`, `sign` |
+| `client.agents`    | `enroll` (also `AgentsResource.enroll(baseUrl, …)` static), `create`, `getSelf`, `get`, `list`, `update`, `delete`, `rotateKey`, `generateEoa`, `createSmartAccount`, `deleteSmartAccount`, `rotateSigner`, `submitTransaction`, `signTransaction`, `getTransaction`, `listTransactions`, `simulateTransaction`, `simulateBundle`, `sign`, `createDelegation`, `listDelegations`, `getDelegation`, `updateDelegation`, `revokeDelegation`, `getEffectiveDelegations` |
 | `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`, `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`                |
@@ -326,6 +330,39 @@ When `execution_require_tee` is true:
 
 Both require `intents_api_enabled` / `execution_intents_enabled` to be on first.
 
+### Agent-to-Agent Delegation
+
+Human-controlled authorization for inter-agent task delegation. Agents cannot delegate to other agents without an explicit delegation record created by a human.
+
+```typescript
+// Create a delegation (human-only)
+await client.agents.createDelegation(orchestratorId, {
+    delegate_id: subAgentId,
+    allowed_tools: ["delegate_task", "search_memory"],
+    max_daily_delegations: 100,
+    max_depth: 2,
+    delegation_mode: "caller",
+    expires_at: "2026-12-31T23:59:59Z",
+});
+
+// List delegations for an agent
+const delegations = await client.agents.listDelegations(agentId);
+
+// Get effective delegations (agent-callable — for runtime tool discovery)
+const effective = await client.agents.getEffectiveDelegations(agentId);
+
+// Update a delegation (human-only)
+await client.agents.updateDelegation(agentId, delegationId, {
+    max_daily_delegations: 200,
+    is_active: false,
+});
+
+// Revoke a delegation (human-only)
+await client.agents.revokeDelegation(agentId, delegationId);
+```
+
+Delegation modes: `caller` (delegate uses its own credentials), `target` (delegate uses target's config), `both` (either mode per invocation).
+
 ### Overhead Budget and Transaction Count Limits
 
 Protect against non-value drain attacks (ATA rent drain, XRP reserve exhaustion, Tron energy drain):
@@ -352,6 +389,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: