shadowkey-agent-sdk 1.1.0 → 1.2.0

package/README.md

@@ -1,15 +1,18 @@
 # ShadowKey Agent SDK
 
-Official SDK for integrating AI agents with ShadowKey's privacy-preserving data vault.
+Official SDK for integrating AI agents with [ShadowKey](https://shadowkey-ai.vercel.app)'s privacy-preserving data vault on Base.
+
+[![npm](https://img.shields.io/npm/v/shadowkey-agent-sdk?style=flat-square&logo=npm&color=CB3837)](https://www.npmjs.com/package/shadowkey-agent-sdk) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE) [![Node](https://img.shields.io/badge/Node-%3E%3D18-339933?style=flat-square&logo=node.js)](https://nodejs.org) [![TypeScript](https://img.shields.io/badge/TypeScript-First-3178C6?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
 
 ## Features
 
-- 🔐 Secure API key authentication with request signing
-- 🔄 Automatic retry logic with exponential backoff
-- ⏱️ Configurable timeouts and polling
-- 🎯 TypeScript-first with full type definitions
-- 🪶 Zero dependencies for minimal bundle size
-- 🔍 Debug mode for development
+- **HMAC-SHA256 Request Signing** — Every request is cryptographically signed to prevent replay attacks
+- **Automatic Retry** — Exponential backoff on server errors (skips retries on 4xx client errors)
+- **Approval Polling** — Built-in `waitForApproval()` with configurable timeout and interval
+- **Node.js 18+ & Browser** — Works in both environments using `globalThis.crypto`
+- **TypeScript-First** — Full type definitions included (CJS + ESM + `.d.ts`)
+- **Zero Dependencies** — No external deps, minimal bundle size (4.8 KB ESM)
+- **Debug Mode** — Logs requests/responses with automatic redaction of sensitive fields
 
 ## Installation
 
@@ -24,31 +27,55 @@ import { ShadowKeyClient } from 'shadowkey-agent-sdk';
 
 const client = new ShadowKeyClient({
   apiUrl: 'https://your-project.supabase.co/functions/v1',
-  apiKey: 'your-api-key',
-  debug: true // Enable logging during development
+  apiKey: 'sk_your_api_key_here',
+  debug: true,
 });
 
-// Request access to user data
+// 1. Request access to user's vault data
 const response = await client.requestAccess({
-  agentId: 'shopping-assistant-001',
+  agentId: 'shopping-bot-001',
   agentName: 'Smart Shopping Assistant',
-  requestedFields: ['creditCard', 'shippingAddress'],
-  purpose: 'Complete your purchase of wireless headphones',
-  category: 'shopping'
+  requestedFields: ['shipping_address', 'billing_name', 'card_last4'],
+  purpose: 'Complete purchase of wireless headphones ($89.99)',
+  category: 'payment',
 });
 
 console.log('Request ID:', response.requestId);
+// → User receives notification in their ShadowKey dashboard
 
-// Wait for user approval (with timeout)
-const result = await client.waitForApproval(response.requestId, 300000);
+// 2. Wait for user to approve/deny (polls every 2s, max 5 min)
+const result = await client.waitForApproval(response.requestId);
 
 if (result.status === 'approved') {
-  console.log('Access granted!', result.grantedData);
+  console.log('Scoped access granted:', result.grantedFields);
+  console.log('Data:', result.grantedData);
+  // → Only the fields the user approved — nothing more
 } else {
   console.log('Access denied:', result.message);
 }
 ```
 
+## How It Works
+
+```
+Your Agent                    ShadowKey SDK                  User's Vault
+    |                              |                              |
+    |-- requestAccess() ---------> |                              |
+    |                              |-- POST /sdk-access-request ->|
+    |                              |     (HMAC-signed)            |
+    |                              |<---- requestId, pending -----|
+    |<---- requestId --------------|                              |
+    |                              |                              |
+    |-- waitForApproval() -------> |                              |
+    |                              |-- GET /sdk-access-status --> |
+    |                              |     (polls every 2s)         |
+    |                              |                    User approves fields
+    |                              |<---- approved, grantedData --|
+    |<---- grantedData ------------|                              |
+    |                              |                              |
+    | Only approved fields received. Denied fields never leave the vault.
+```
+
 ## API Reference
 
 ### Constructor
@@ -57,121 +84,135 @@ if (result.status === 'approved') {
 new ShadowKeyClient(config: ShadowKeyConfig)
 ```
 
-**Config Options:**
-- `apiUrl` (required): Your Supabase project URL + `/functions/v1`
-- `apiKey` (required): API key generated from ShadowKey settings
-- `timeout` (optional): Request timeout in ms (default: 30000)
-- `retryAttempts` (optional): Number of retry attempts (default: 3)
-- `debug` (optional): Enable debug logging (default: false)
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiUrl` | `string` | *required* | Supabase project URL + `/functions/v1` |
+| `apiKey` | `string` | *required* | API key from ShadowKey Settings page |
+| `timeout` | `number` | `30000` | Request timeout in ms |
+| `retryAttempts` | `number` | `3` | Max retries on server errors |
+| `debug` | `boolean` | `false` | Enable debug logging (redacts sensitive fields) |
 
-### Methods
+### `requestAccess(request): Promise<AccessResponse>`
+
+Request scoped access to a user's vault data. Creates a pending disclosure request that the vault owner must approve.
+
+```typescript
+const response = await client.requestAccess({
+  agentId: 'my-agent-001',        // Your agent's unique ID
+  agentName: 'My AI Assistant',    // Human-readable name (shown to user)
+  requestedFields: ['email', 'phone'], // Fields you need
+  purpose: 'Send order confirmation',  // Why (shown to user)
+  category: 'identity',           // Optional: payment, identity, health, etc.
+  expiresIn: 300,                 // Optional: seconds until request expires (default 300)
+});
+```
 
-#### `requestAccess(request: AccessRequest): Promise<AccessResponse>`
+### `checkStatus(requestId): Promise<DisclosureStatus>`
 
-Request access to user's vault data.
+Check the current status of an access request.
 
-**Parameters:**
 ```typescript
-{
-  agentId: string;          // Unique identifier for your agent
-  agentName: string;        // Human-readable agent name
-  requestedFields: string[]; // Array of field names to request
-  purpose: string;          // Clear explanation of why you need access
-  category?: string;        // Optional category (shopping, travel, etc)
-  expiresIn?: number;       // Optional expiration time in seconds
-}
+const status = await client.checkStatus(response.requestId);
+// status.status → 'pending' | 'approved' | 'denied' | 'expired'
 ```
 
-**Returns:**
+### `waitForApproval(requestId, maxWaitMs?, pollIntervalMs?): Promise<AccessResponse>`
+
+Poll for user approval with automatic timeout.
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `requestId` | *required* | From `requestAccess()` |
+| `maxWaitMs` | `300000` (5 min) | Max time to wait |
+| `pollIntervalMs` | `2000` (2s) | Time between polls |
+
 ```typescript
-{
-  requestId: string;        // Use this to check status
-  status: 'pending' | 'approved' | 'denied' | 'expired';
-  grantedData?: Record<string, any>; // Present if approved
-  expiresAt?: string;       // ISO timestamp
-  message?: string;
-}
+const result = await client.waitForApproval(response.requestId, 120000, 3000);
 ```
 
-#### `checkStatus(requestId: string): Promise<DisclosureStatus>`
+### `submitReverseDisclosure(request): Promise<ReverseDisclosureResponse>`
 
-Check the current status of an access request.
+Submit data to a user's vault (reverse data flow — services sending data to users).
 
-#### `waitForApproval(requestId: string, maxWaitMs?: number, pollIntervalMs?: number): Promise<AccessResponse>`
+```typescript
+const receipt = await client.submitReverseDisclosure({
+  serviceId: 'acme-corp',
+  serviceName: 'Acme Corporation',
+  dataOffered: [
+    { field: 'loyalty_points', value: '4,250', category: 'preferences' },
+    { field: 'member_since', value: '2024-01-15', category: 'identity' },
+  ],
+  purpose: 'Share your loyalty program data',
+});
+```
 
-Poll for approval with automatic retries.
+## Integration Examples
 
-**Parameters:**
-- `requestId`: The ID returned from `requestAccess()`
-- `maxWaitMs`: Maximum time to wait (default: 300000 = 5 minutes)
-- `pollIntervalMs`: Time between polls (default: 2000 = 2 seconds)
+Both examples import directly from `shadowkey-agent-sdk`:
 
-#### `submitReverseDisclosure(request: ReverseDisclosureRequest): Promise<ReverseDisclosureResponse>`
+### OpenRouter AI Agent (`/examples/openrouter/`)
 
-Submit data to user's vault (reverse data flow).
+An AI shopping agent that uses OpenRouter's free models with 4-model automatic failover:
 
-**Parameters:**
-```typescript
-{
-  serviceId: string;
-  serviceName: string;
-  dataOffered: Array<{
-    field: string;
-    value: string;
-    category: string;
-  }>;
-  purpose: string;
-}
+```javascript
+import { ShadowKeyClient } from 'shadowkey-agent-sdk';
+
+const shadowKey = new ShadowKeyClient({
+  apiUrl: `${process.env.SUPABASE_URL}/functions/v1`,
+  apiKey: process.env.SHADOWKEY_API_KEY,
+});
+
+// AI determines needed fields → SDK requests access → user approves → AI completes task
 ```
 
-## Examples
+### Express.js Server (`/examples/node-express/`)
 
-See the `/examples` directory for complete integration examples:
+A REST API backend that wraps the SDK for multi-agent architectures:
 
-- `openrouter/` - AI agent using OpenRouter free models
-- `node-express/` - Express.js server with webhook handling
-- `langchain/` - LangChain tool integration
-- `python/` - Python SDK wrapper
+```javascript
+import { ShadowKeyClient } from 'shadowkey-agent-sdk';
+
+const shadowKey = new ShadowKeyClient({ ... });
+
+app.post('/api/request-data', async (req, res) => {
+  const response = await shadowKey.requestAccess({ ... });
+  res.json(response);
+});
+```
 
 ## Error Handling
 
 ```typescript
 try {
-  const response = await client.requestAccess({...});
+  const response = await client.requestAccess({ ... });
 } catch (error) {
   if (error.message.includes('timeout')) {
-    console.error('Request timed out');
+    // Request timed out — check network or increase timeout
   } else if (error.message.includes('401')) {
-    console.error('Invalid API key');
+    // Invalid or expired API key
+  } else if (error.message.includes('404')) {
+    // No vault found for this API key's user
   } else {
-    console.error('Request failed:', error.message);
+    // Server error — SDK auto-retried and all attempts failed
   }
 }
 ```
 
-## Security Best Practices
-
-1. **Never expose your API key** in client-side code
-2. **Use environment variables** to store credentials
-3. **Rotate keys regularly** using the ShadowKey dashboard
-4. **Set appropriate rate limits** for your use case
-5. **Validate all data** received from the vault
-6. **Use HTTPS** for all requests (enforced by default)
-
-## Rate Limits
-
-Default rate limits per API key:
-- 100 requests per minute
-- 1000 requests per hour
-- 10000 requests per day
+## Security
 
-Contact support for enterprise limits.
+- **HMAC-SHA256 signing** — Every request includes timestamp, nonce, and signature headers
+- **5-minute timestamp window** — Rejects requests with stale timestamps (prevents replay attacks)
+- **Sensitive field redaction** — Debug logs automatically redact `grantedData`, `grantedFields`, and `response_data`
+- **No secrets in transit** — SDK receives only the fields the user approved, never the full vault
 
-## Support
+## Links
 
-- Documentation: https://shadowkey.dev/docs
-- Issues: https://github.com/shadowkey/agent-sdk/issues
-- Discord: https://discord.gg/shadowkey
+- **npm:** [shadowkey-agent-sdk](https://www.npmjs.com/package/shadowkey-agent-sdk)
+- **Live Demo:** [shadowkey-ai.vercel.app/agent-demo](https://shadowkey-ai.vercel.app/agent-demo)
+- **Dashboard:** [shadowkey-ai.vercel.app](https://shadowkey-ai.vercel.app)
+- **Smart Contract:** [Basescan (Verified)](https://basescan.org/address/0xC739f98B438620A9326Ddb7548201Bcd78a3DBAd#code)
+- **GitHub:** [kimboltpro3-create/shadowkey](https://github.com/kimboltpro3-create/shadowkey)
+- **Issues:** [GitHub Issues](https://github.com/kimboltpro3-create/shadowkey/issues)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadowkey-agent-sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Official SDK for integrating AI agents with ShadowKey privacy vault",
   "main": "dist/index.js",
   "module": "dist/index.mjs",