@cobo/agentic-wallet 0.1.5 → 0.1.7

package/README.md

@@ -21,6 +21,14 @@ Instead of giving an agent a private key, Cobo Agentic Wallet gives it a control
 [![npm version](https://img.shields.io/npm/v/@cobo/agentic-wallet)](https://www.npmjs.com/package/@cobo/agentic-wallet)
 [![License](https://img.shields.io/github/license/CoboGlobal/cobo-agentic-wallet-typescript-sdk)](https://github.com/CoboGlobal/cobo-agentic-wallet-typescript-sdk/blob/master/LICENSE)
 
+## AI coding agent support
+
+If you are building with an AI coding agent (Claude Code, Cursor, Windsurf, etc.), install the CAW developer skill to give it context on the SDK and CLI:
+
+```bash
+npx skills add CoboGlobal/cobo-agentic-wallet --skill cobo-agentic-wallet-developer --yes --global
+```
+
 ## Related repositories
 
 - [CAW Python SDK](https://github.com/CoboGlobal/cobo-agentic-wallet-python-sdk)
@@ -33,142 +41,203 @@ Instead of giving an agent a private key, Cobo Agentic Wallet gives it a control
 
 ## Get Started
 
-### 1. Install the `caw` CLI
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/CoboGlobal/cobo-agentic-wallet/master/install.sh | bash
-```
-
-Then add `caw` to your PATH:
-
-```bash
-export PATH="$HOME/.cobo-agentic-wallet/bin:$PATH"
-```
-
-Verify the installation:
-
-```bash
-caw --version
-```
-
-### 2. Onboard and pair with the wallet owner
-
-Run the interactive onboarding wizard. You will need an invitation code from the wallet owner.
-
-```bash
-caw onboard --wait --invitation-code <invitation-code>
-```
-
-The wizard runs through several phases until wallet `status` becomes `active`.
-
-Once the wallet is active, generate a pairing token for the wallet owner:
-
-```bash
-caw wallet pair --code-only
-```
-
-The wallet owner enters the token in the Cobo Agentic Wallet app to complete ownership pairing.
+Before using this SDK, follow the [Get Started guide](https://github.com/CoboGlobal/cobo-agentic-wallet#get-started) in the main repo to install the `caw` CLI, onboard, and get your credentials.
 
-### 3. Claim testnet tokens from the faucet
-
-```bash
-# List addresses for the wallet
-caw address list
-
-# Request native Sepolia ETH
-caw faucet deposit --token-id SETH --address <your-seth-address>
-```
-
-Check the balance with `caw wallet balance`.
-
-### 4. Get credentials
-
-```bash
-caw wallet current --show-api-key
-```
-
-Set the output values as environment variables:
-
-```bash
-export AGENT_WALLET_API_URL=https://api.agenticwallet.cobo.com
-export AGENT_WALLET_API_KEY=your-agent-api-key
-export AGENT_WALLET_WALLET_ID=your-wallet-uuid
-```
-
-### 5. Install the SDK
+### 1. Install the SDK
 
 ```bash
 npm install @cobo/agentic-wallet
 ```
 
-### 6. Submit a pact and run a transfer
+### 2. Submit a pact and run a transfer
 
 ```typescript
-import { Configuration, PactsApi, TransactionsApi } from '@cobo/agentic-wallet';
+import {
+  AuditApi,
+  Configuration,
+  PactsApi,
+  TransactionsApi,
+} from '@cobo/agentic-wallet';
 
 const CHAIN_ID = 'SETH';
 const TOKEN_ID = 'SETH';
-const DESTINATION = '0x1111111111111111111111111111111111111111';
 const ALLOWED_AMOUNT = '0.001';
+const DENIED_AMOUNT = '0.005';
 const DENY_THRESHOLD = '0.002';
 
-async function main() {
-    const apiUrl = process.env.AGENT_WALLET_API_URL!;
-    const apiKey = process.env.AGENT_WALLET_API_KEY!;
-    const walletId = process.env.AGENT_WALLET_WALLET_ID!;
-
-    const config = new Configuration({ basePath: apiUrl, apiKey });
-    const pactsApi = new PactsApi(config);
-
-    // Submit a pact requesting transfer permissions
-    const pactResp = await pactsApi.submitPact({
-        wallet_id: walletId,
-        intent: 'Transfer tokens for testing',
-        spec: {
-            policies: [
-                {
-                    name: 'max-tx-limit',
-                    type: 'transfer',
-                    rules: {
-                        effect: 'allow',
-                        when: { chain_in: [CHAIN_ID] },
-                        deny_if: { amount_gt: DENY_THRESHOLD },
-                    },
-                },
-            ],
-            completion_conditions: [{ type: 'time_elapsed', threshold: '86400' }],
-        },
-    } as any);
-    const pactId = pactResp.data.pact_id;
-    console.log(`Pact submitted: ${pactId}`);
-
-    // Poll until the owner approves the pact
-    while (true) {
-        const pact = (await pactsApi.getPact(pactId)).data;
-        if (pact.status === 'active') break;
-        if (['rejected', 'expired', 'revoked', 'completed'].includes(pact.status as string)) {
-            throw new Error(`Pact ended: ${pact.status}`);
-        }
-        await new Promise(r => setTimeout(r, 5000));
-    }
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
 
-    const pact = (await pactsApi.getPact(pactId)).data;
+interface ApiErrorPayload {
+  error?: { code?: string; reason?: string; details?: Record<string, string> };
+  suggestion?: string;
+}
+
+function parseApiError(err: unknown): { http: number | string; payload: ApiErrorPayload } {
+  const response = (err as { response?: { status?: number; data?: unknown } }).response;
+  const http = response?.status ?? '-';
+  const data = response?.data;
+  const payload: ApiErrorPayload =
+    data && typeof data === 'object' ? (data as ApiErrorPayload) : {};
+  return { http, payload };
+}
 
-    // Execute a transfer using the pact-scoped API key
-    const pactConfig = new Configuration({ basePath: apiUrl, apiKey: pact.api_key as string });
-    const pactTxApi = new TransactionsApi(pactConfig);
+async function main(): Promise<void> {
+  const basePath = process.env.AGENT_WALLET_API_URL!;
+  const apiKey = process.env.AGENT_WALLET_API_KEY!;
+  const walletId = process.env.AGENT_WALLET_WALLET_ID!;
+  const destination =
+    process.env.CAW_DESTINATION ?? '0x1111111111111111111111111111111111111111';
+
+  const ownerConfig = new Configuration({ apiKey, basePath });
+  const pactsApi = new PactsApi(ownerConfig);
+  const auditApi = new AuditApi(ownerConfig);
+
+  // Step 1: Submit a pact requesting transfer permissions for 24 hours.
+  console.log(
+    `[1/6] Submitting pact (allow ${CHAIN_ID}/${TOKEN_ID} transfers, ` +
+      `deny if amount > ${DENY_THRESHOLD})...`,
+  );
+  const pactResp = await pactsApi.submitPact({
+    wallet_id: walletId,
+    intent: 'Transfer tokens for integration testing',
+    spec: {
+      policies: [
+        {
+          name: 'max-tx-limit',
+          type: 'transfer',
+          rules: {
+            effect: 'allow',
+            when: {
+              chain_in: [CHAIN_ID],
+              token_in: [{ chain_id: CHAIN_ID, token_id: TOKEN_ID }],
+            },
+            deny_if: { amount_gt: DENY_THRESHOLD },
+          },
+        },
+      ],
+      completion_conditions: [{ type: 'time_elapsed', threshold: '86400' }],
+    },
+  });
+  const pactId = pactResp.data.result.pact_id;
+  console.log(`      pact submitted: id=${pactId}`);
+
+  // Step 2: Poll until the owner approves the pact.
+  console.log('[2/6] Waiting for owner approval in the Cobo Agentic Wallet app...');
+  const started = Date.now();
+  let pactApiKey: string | undefined;
+  let lastStatus: string | undefined;
+  while (!pactApiKey) {
+    const pact = (await pactsApi.getPact(pactId)).data.result;
+    const status = pact.status ?? '';
+    if (status !== lastStatus) {
+      const elapsed = Math.floor((Date.now() - started) / 1000);
+      console.log(`      pact status -> ${status} (elapsed ${elapsed}s)`);
+      lastStatus = status;
+    }
+    if (status === 'active') {
+      pactApiKey = pact.api_key;
+      break;
+    }
+    if (['rejected', 'expired', 'revoked', 'completed'].includes(status)) {
+      throw new Error(`Pact reached terminal status before use: ${status}`);
+    }
+    await sleep(5000);
+  }
+
+  // Step 3: Use the pact-scoped API key for all subsequent calls.
+  console.log('[3/6] Pact is active; switching to pact-scoped API key.');
+  const pactConfig = new Configuration({ apiKey: pactApiKey, basePath });
+  const txApi = new TransactionsApi(pactConfig);
+
+  // Step 4: Execute an allowed transfer (within the deny threshold).
+  console.log(
+    `[4/6] Submitting allowed transfer: ${ALLOWED_AMOUNT} ${TOKEN_ID} -> ${destination}`,
+  );
+  const allowed = (
+    await txApi.transferTokens(walletId, {
+      chain_id: CHAIN_ID,
+      dst_addr: destination,
+      token_id: TOKEN_ID,
+      amount: ALLOWED_AMOUNT,
+    })
+  ).data.result;
+  console.log(
+    `      ALLOWED: tx_id=${allowed.id} status=${allowed.status} (${allowed.status_display ?? '-'}) ` +
+      `request_id=${allowed.request_id} hash=${allowed.transaction_hash ?? '-'}`,
+  );
+
+  // Step 5: Trigger a policy denial (amount exceeds the deny threshold),
+  // then follow the denial guidance and retry with a compliant amount.
+  console.log(
+    `[5/6] Submitting transfer that should be blocked: ` +
+      `${DENIED_AMOUNT} ${TOKEN_ID} -> ${destination}`,
+  );
+  try {
+    await txApi.transferTokens(walletId, {
+      chain_id: CHAIN_ID,
+      dst_addr: destination,
+      token_id: TOKEN_ID,
+      amount: DENIED_AMOUNT,
+    });
+  } catch (error) {
+    const { http, payload } = parseApiError(error);
+    const err = payload.error ?? {};
+    console.log(
+      `      DENIED as expected: http=${http} ` +
+        `code=${err.code ?? '-'} reason=${err.reason ?? '-'}`,
+    );
+    if (err.details) {
+      console.log(`      details: ${JSON.stringify(err.details)}`);
+    }
+    if (payload.suggestion) {
+      console.log(`      suggestion: ${payload.suggestion}`);
+    }
 
-    const tx = await pactTxApi.transferTokens({
-        wallet_id: walletId,
+    console.log(
+      `      retrying with compliant amount ${ALLOWED_AMOUNT} ${TOKEN_ID}...`,
+    );
+    const retry = (
+      await txApi.transferTokens(walletId, {
         chain_id: CHAIN_ID,
-        dst_addr: DESTINATION,
+        dst_addr: destination,
         token_id: TOKEN_ID,
         amount: ALLOWED_AMOUNT,
-    } as any);
-    console.log(`Transfer submitted: ${tx.data.id}`);
+      })
+    ).data.result;
+    console.log(
+      `      RETRY ALLOWED: tx_id=${retry.id} status=${retry.status} (${retry.status_display ?? '-'}) ` +
+        `request_id=${retry.request_id} hash=${retry.transaction_hash ?? '-'}`,
+    );
+  }
+
+  // Step 6: Verify allowed and denied events in audit logs.
+  console.log('[6/6] Fetching recent audit entries for this wallet...');
+  const logs = await auditApi.listAuditLogs(
+    walletId,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    20,
+  );
+  const items = (logs.data.result as { items?: Array<{ result?: string }> })?.items ?? [];
+  const allowedCount = items.filter(item => item.result === 'allowed').length;
+  const deniedCount = items.filter(item => item.result === 'denied').length;
+  console.log(
+    `      audit (last ${items.length} entries): allowed=${allowedCount}, denied=${deniedCount}`,
+  );
 }
 
-main().catch(console.error);
+main().catch(error => {
+  console.error(error);
+  process.exit(1);
+});
 ```
 
 ## Contributing

package/dist/api/audit-api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/audit-api.js

@@ -2,7 +2,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/balance-api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/balance-api.js

@@ -2,7 +2,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/coin-price-api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/coin-price-api.js

@@ -2,7 +2,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/faucet-api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/faucet-api.js

@@ -2,7 +2,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/health-api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/health-api.js

@@ -2,7 +2,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/identity-api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/identity-api.js

@@ -2,7 +2,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/meta-api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/meta-api.js

@@ -2,7 +2,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/metadata-api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/metadata-api.js

@@ -2,7 +2,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/pacts-api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/pacts-api.js

@@ -2,7 +2,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/pending-operations-api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech

package/dist/api/pending-operations-api.js

@@ -2,7 +2,7 @@
 /**
  * Cobo Agentic Wallet Service
  *
- * The version of the OpenAPI document: 1.1.0
+ * The version of the OpenAPI document: 1.3.0
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
  * https://openapi-generator.tech