cilantro-sdk 0.0.13 → 0.0.15

package/README.md

@@ -1,316 +1,540 @@
-# Cilantro Smart SDK
-
-A TypeScript/JavaScript SDK for interacting with the Cilantro Smart API - A Solana wallet management system.
-
-## Installation
-
-```bash
-npm install cilantro-sdk
-```
-
-## Quick Start
-
-### Option 1: Using API Key (Recommended for Server-Side)
-
-```typescript
-import { configure } from 'cilantro-sdk';
-import { sendSOL } from 'cilantro-sdk/wallet';
-
-// Configure SDK with your API key
-configure({ 
-  apiKey: 'your-api-key-here'
-});
-
-// Make authenticated requests
-const result = await sendSOL('wallet-id', {
-  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
-  amountLamports: 1000000000
-});
-```
-
-### Option 2: Using Login (For User Authentication)
-
-```typescript
-import { loginAndSetAuth } from 'cilantro-sdk/auth';
-import { sendSOL } from 'cilantro-sdk/wallet';
-
-// Login and set authentication automatically
-await loginAndSetAuth({
-  usernameOrEmail: 'user@example.com',
-  password: 'SecurePass123!'
-});
-
-// Make authenticated requests
-const result = await sendSOL('wallet-id', {
-  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
-  amountLamports: 1000000000
-});
-```
-
-### Option 3: Manual Authentication Control
-
-```typescript
-import { setAuth } from 'cilantro-sdk';
-import { login } from 'cilantro-sdk/auth';
-import { sendSOL } from 'cilantro-sdk/wallet';
-
-// Login without automatically setting auth
-const authResult = await login({
-  usernameOrEmail: 'user@example.com',
-  password: 'password123'
-});
-
-// Manually set authentication
-setAuth({ jwt: authResult.data.jwt });
-
-// Make authenticated requests
-const result = await sendSOL('wallet-id', {
-  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
-  amountLamports: 1000000000
-});
-```
-
-### CommonJS
-
-```javascript
-const { configure } = require('cilantro-sdk');
-const { sendSOL } = require('cilantro-sdk/wallet');
-
-// Configure with API key
-configure({ apiKey: 'your-api-key' });
-
-// Make authenticated requests
-const result = await sendSOL('wallet-id', { ... });
-```
-
-## Helpers Module - Device Keys & Signer Management
-
-The SDK includes a comprehensive helpers module for device key management and signer operations. This simplifies working with email/phone signers and provides automatic device key resolution, validation, and caching.
-
-### Quick Example
-
-```typescript
-import { 
-  createEmailSignerHelper,
-  getEmailSignerKeypair,
-  createLocalStorageAdapter 
-} from 'cilantro-sdk/helpers';
-
-// Create storage for device keys
-const storage = createLocalStorageAdapter();
-
-// Create email signer (device key generated automatically)
-const signer = await createEmailSignerHelper('wallet-id', {
-  email: 'user@example.com',
-  deviceKeyManager: storage
-});
-
-// Get keypair - SDK automatically:
-// 1. Fetches signer from API
-// 2. Extracts devicePublicKey and deviceId
-// 3. Resolves device key from storage
-// 4. Validates device key matches API
-const keypair = await getEmailSignerKeypair(
-  'wallet-id',
-  signer.signerId,
-  { 
-    deviceKeyManager: storage
-  }
-);
-```
-
-### Key Features
-
-- ✅ **Fully Automatic Resolution** - Automatically fetches signer, extracts device info, and resolves device keys
-- ✅ **Automatic Caching** - Keypair derivation is cached to avoid redundant operations
-- ✅ **Device Key Validation** - Prevents mismatches between storage and API
-- ✅ **Multi-Device Support** - Handle multiple devices per signer
-- ✅ **Cross-Platform** - Works in browser and Node.js
-- ✅ **Storage Adapters** - localStorage, filesystem, or memory storage
-- ✅ **Type-Safe** - Full TypeScript support
-- ✅ **Functional** - No classes, pure functions
-
-### Available Helpers
-
-**Device Key Management:**
-- `getDevicePublicKey()` - Get or create device key with caching
-- `generateDeviceKeyPair()` - Generate new device key pair
-- `rotateDeviceKey()` - Rotate device keys
-- `clearDeviceKeyCache()` - Clear cache
-- `findDeviceKeyByPublicKey()` - Find device key by public key
-- `listAllDeviceKeys()` - List all device keys with metadata
-
-**Email Signer Helpers:**
-- `createEmailSignerHelper()` - Create email signer with automatic device key generation
-- `getEmailSignerKeypair()` - Get keypair with automatic device key resolution
-- `signWithEmailSigner()` - Sign messages with email signer
-- `getEmailSignerByEmail()` - Find email signer by email address
-
-**Phone Signer Helpers:**
-- `createPhoneSignerHelper()` - Create phone signer with automatic device key generation
-- `getPhoneSignerKeypair()` - Get keypair with automatic device key resolution
-- `signWithPhoneSigner()` - Sign messages with phone signer
-- `getPhoneSignerByPhone()` - Find phone signer by phone number
-
-**Device Key Validation & Resolution:**
-- `getSignerDeviceKeys()` - Get all device keys for a signer from API
-- `validateDeviceKey()` - Validate device key matches API
-- `resolveDeviceKey()` - Automatically find matching device key
-- `getBestDeviceIdentity()` - Get most recently used device identity
-
-**Device Identity Management:**
-- `addDeviceIdentityToSigner()` - Add new device to existing signer
-- `replaceDeviceIdentity()` - Replace existing device identity
-- `addNewDeviceToSigner()` - Convenience function for adding new device
-- `canAddDeviceToSigner()` - Check if device can be added
-
-**Storage Adapters:**
-- `createLocalStorageAdapter()` - Browser localStorage adapter
-- `createFileSystemAdapter()` - Node.js filesystem adapter
-- `createMemoryAdapter()` - In-memory adapter (for testing)
-- `getDefaultStorageAdapter()` - Get platform-appropriate adapter
-
-For detailed documentation on device key management, see [DEVICE_KEY_MANAGEMENT.md](./DEVICE_KEY_MANAGEMENT.md).
-
-## Configuration
-
-### `configure(config)`
-
-Initialize the SDK with configuration options.
-
-```typescript
-import { configure } from 'cilantro-sdk';
-
-configure({ 
-  apiKey: 'your-api-key',
-  jwt: 'your-jwt-token', // Optional
-  baseURL: 'https://api.cilantro.gg' // Optional: Custom API base URL
-});
-```
-
-### `setAuth(auth)`
-
-Update authentication credentials after initialization.
-
-```typescript
-import { setAuth } from 'cilantro-sdk';
-
-setAuth({ 
-  jwt: 'your-jwt-token',
-  apiKey: 'your-api-key' 
-});
-```
-
-### `clearAuth()`
-
-Clear all authentication credentials.
-
-```typescript
-import { clearAuth } from 'cilantro-sdk';
-
-clearAuth();
-```
-
-### Authentication Types
-
-The SDK supports two types of authentication:
-
-1. **API Key Authentication**: For server-side applications and platform-level access
-2. **JWT Token Authentication**: For user-specific operations after login
-
-You can use either or both simultaneously. The SDK will automatically include the appropriate headers in all requests.
-
-## Module Structure
-
-The SDK is organized into modules for better code organization:
-
-- **Platform** (`cilantro-sdk/platform`) - Platform management and user operations
-- **User** (`cilantro-sdk/user`) - User account operations
-- **Wallet** (`cilantro-sdk/wallet`) - Wallet and blockchain operations
-- **Admin** (`cilantro-sdk/admin`) - Administrative operations
-- **Auth** (`cilantro-sdk/auth`) - Universal authentication
-- **Utils** (`cilantro-sdk/utils`) - Utility functions
-- **Helpers** (`cilantro-sdk/helpers`) - Device key management and signer helpers
-
-### Quick Reference
-
-**Platform Module:**
-- Basic: `create`, `findAll`, `findOne`, `update`, `remove`, `getOwnProfile`, `updateOwnProfile`
-- Users: `getUsers`, `createUser`, `updateUser`, `removeUser`, `toggleUserActive`
-- Wallets: `getWallets` (read-only)
-
-**User Module:**
-- `create`, `findOne`, `update`
-
-**Wallet Module:**
-- Basic: `create`, `findAll`, `findOne`, `update`, `remove`, `findByAddress`, `getTotalBalance`
-- Status: `activate`, `deactivate`
-- Transactions: `sendSOL`, `sendSPL`, `sendTransaction`, `simulateTransaction`
-- Batch: `batchCreate`, `batchSendSOL`, `batchSendSPL`
-- NFTs & Tokens: `mintNFT`, `mintNFTSimple`, `mintToken`
-- Assets: `getAssets`, `syncAssets`
-- Signers: Email, phone, external, API key, and passkey signer management
-
-**Auth Module:**
-- `login` - Login and get JWT token
-- `loginAndSetAuth` - Login and automatically set authentication
-
-**Helpers Module:**
-- Device key management, signer helpers, validation, and storage adapters (see above)
-
-## Error Handling
-
-The SDK provides custom error classes for better error handling:
-
-```typescript
-import { 
-  SDKError,
-  DeviceKeyMismatchError,
-  DeviceKeyNotFoundError,
-  NoDeviceIdentitiesError,
-  MultipleDeviceIdentitiesError
-} from 'cilantro-sdk';
-
-try {
-  const keypair = await getEmailSignerKeypair(walletId, signerId, { deviceKeyManager });
-} catch (error) {
-  if (error instanceof DeviceKeyNotFoundError) {
-    // Handle device key not found
-    console.error('Device key not found:', error.devicePublicKey);
-  } else if (error instanceof DeviceKeyMismatchError) {
-    // Handle device key mismatch
-    console.error('Device key mismatch:', error.expectedDeviceKey, error.actualDeviceKey);
-  } else {
-    // Handle other errors
-    console.error('Error:', error.message);
-  }
-}
-```
-
-## TypeScript Support
-
-The SDK is written in TypeScript and provides full type definitions:
-
-```typescript
-import type { 
-  DeviceKeyPair,
-  DeviceKeyStorage,
-  SignerInfo,
-  Keypair,
-  EmailSignerOptions,
-  PhoneSignerOptions
-} from 'cilantro-sdk/helpers';
-```
-
-## Cross-Platform Support
-
-The SDK works in both browser and Node.js environments:
-
-- **Browser**: Uses Web Crypto API and localStorage
-- **Node.js**: Uses Node.js crypto module and filesystem
-
-Storage adapters automatically detect the environment and use the appropriate implementation.
-
-## License
-
-ISC
+# Cilantro Smart SDK
+
+A TypeScript/JavaScript SDK for interacting with the Cilantro Smart API - A Solana wallet management system.
+
+## Installation
+
+```bash
+npm install cilantro-sdk
+```
+
+## Quick Start
+
+### Option 1: Using API Key (Recommended for Server-Side)
+
+```typescript
+import { configure } from 'cilantro-sdk';
+import { sendSOL } from 'cilantro-sdk/wallet';
+
+// Configure SDK with your API key
+configure({ 
+  apiKey: 'your-api-key-here'
+});
+
+// Make authenticated requests
+const result = await sendSOL('wallet-id', {
+  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
+  amountLamports: 1000000000
+});
+```
+
+### Option 2: Using Login (For User Authentication)
+
+```typescript
+import { loginAndSetAuth } from 'cilantro-sdk/auth';
+import { sendSOL } from 'cilantro-sdk/wallet';
+
+// Login and set authentication automatically
+await loginAndSetAuth({
+  usernameOrEmail: 'user@example.com',
+  password: 'SecurePass123!'
+});
+
+// Make authenticated requests
+const result = await sendSOL('wallet-id', {
+  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
+  amountLamports: 1000000000
+});
+```
+
+### Option 3: Manual Authentication Control
+
+```typescript
+import { setAuth } from 'cilantro-sdk';
+import { login } from 'cilantro-sdk/auth';
+import { sendSOL } from 'cilantro-sdk/wallet';
+
+// Login without automatically setting auth
+const authResult = await login({
+  usernameOrEmail: 'user@example.com',
+  password: 'password123'
+});
+
+// Manually set authentication
+setAuth({ jwt: authResult.data.jwt });
+
+// Make authenticated requests
+const result = await sendSOL('wallet-id', {
+  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
+  amountLamports: 1000000000
+});
+```
+
+### CommonJS
+
+```javascript
+const { configure } = require('cilantro-sdk');
+const { sendSOL } = require('cilantro-sdk/wallet');
+
+// Configure with API key
+configure({ apiKey: 'your-api-key' });
+
+// Make authenticated requests
+const result = await sendSOL('wallet-id', { ... });
+```
+
+## Helpers Module - Device Keys & Signer Management
+
+The SDK includes a comprehensive helpers module for device key management and signer operations. This simplifies working with email/phone signers and provides automatic device key resolution, validation, and caching.
+
+### Quick Example
+
+```typescript
+import { 
+  createEmailSignerHelper,
+  getEmailSignerKeypair,
+  createLocalStorageAdapter 
+} from 'cilantro-sdk/helpers';
+
+// Create storage for device keys
+const storage = createLocalStorageAdapter();
+
+// Create email signer (device key generated automatically)
+const signer = await createEmailSignerHelper('wallet-id', {
+  email: 'user@example.com',
+  deviceKeyManager: storage
+});
+
+// Get keypair - SDK automatically:
+// 1. Fetches signer from API
+// 2. Extracts devicePublicKey and deviceId
+// 3. Resolves device key from storage
+// 4. Validates device key matches API
+const keypair = await getEmailSignerKeypair(
+  'wallet-id',
+  signer.signerId,
+  { 
+    deviceKeyManager: storage
+  }
+);
+```
+
+### Key Features
+
+- ✅ **Fully Automatic Resolution** - Automatically fetches signer, extracts device info, and resolves device keys
+- ✅ **Automatic Caching** - Keypair derivation is cached to avoid redundant operations
+- ✅ **Device Key Validation** - Prevents mismatches between storage and API
+- ✅ **Multi-Device Support** - Handle multiple devices per signer
+- ✅ **Cross-Platform** - Works in browser and Node.js
+- ✅ **Storage Adapters** - localStorage, filesystem, or memory storage
+- ✅ **Type-Safe** - Full TypeScript support
+- ✅ **Functional** - No classes, pure functions
+
+### Available Helpers
+
+**Device Key Management:**
+- `getDevicePublicKey()` - Get or create device key with caching
+- `generateDeviceKeyPair()` - Generate new device key pair
+- `rotateDeviceKey()` - Rotate device keys
+- `clearDeviceKeyCache()` - Clear cache
+- `findDeviceKeyByPublicKey()` - Find device key by public key
+- `listAllDeviceKeys()` - List all device keys with metadata
+
+**Email Signer Helpers:**
+- `createEmailSignerHelper()` - Create email signer with automatic device key generation
+- `getEmailSignerKeypair()` - Get keypair with automatic device key resolution
+- `signWithEmailSigner()` - Sign messages with email signer
+- `getEmailSignerByEmail()` - Find email signer by email address
+
+**Phone Signer Helpers:**
+- `createPhoneSignerHelper()` - Create phone signer with automatic device key generation
+- `getPhoneSignerKeypair()` - Get keypair with automatic device key resolution
+- `signWithPhoneSigner()` - Sign messages with phone signer
+- `getPhoneSignerByPhone()` - Find phone signer by phone number
+
+**Device Key Validation & Resolution:**
+- `getSignerDeviceKeys()` - Get all device keys for a signer from API
+- `validateDeviceKey()` - Validate device key matches API
+- `resolveDeviceKey()` - Automatically find matching device key
+- `getBestDeviceIdentity()` - Get most recently used device identity
+
+**Device Identity Management:**
+- `addDeviceIdentityToSigner()` - Add new device to existing signer
+- `replaceDeviceIdentity()` - Replace existing device identity
+- `addNewDeviceToSigner()` - Convenience function for adding new device
+- `canAddDeviceToSigner()` - Check if device can be added
+
+**Storage Adapters:**
+- `createLocalStorageAdapter()` - Browser localStorage adapter
+- `createFileSystemAdapter()` - Node.js filesystem adapter
+- `createMemoryAdapter()` - In-memory adapter (for testing)
+- `getDefaultStorageAdapter()` - Get platform-appropriate adapter
+
+For detailed documentation on device key management, see [DEVICE_KEY_MANAGEMENT.md](./DEVICE_KEY_MANAGEMENT.md).
+
+## Configuration
+
+### `configure(config)`
+
+Initialize the SDK with configuration options.
+
+```typescript
+import { configure } from 'cilantro-sdk';
+
+configure({ 
+  apiKey: 'your-api-key',
+  jwt: 'your-jwt-token', // Optional
+  baseURL: 'https://api.cilantro.gg' // Optional: Custom API base URL
+});
+```
+
+### `setAuth(auth)`
+
+Update authentication credentials after initialization.
+
+```typescript
+import { setAuth } from 'cilantro-sdk';
+
+setAuth({ 
+  jwt: 'your-jwt-token',
+  apiKey: 'your-api-key' 
+});
+```
+
+### `clearAuth()`
+
+Clear all authentication credentials.
+
+```typescript
+import { clearAuth } from 'cilantro-sdk';
+
+clearAuth();
+```
+
+### Authentication Types
+
+The SDK supports two types of authentication:
+
+1. **API Key Authentication**: For server-side applications and platform-level access
+2. **JWT Token Authentication**: For user-specific operations after login
+
+You can use either or both simultaneously. The SDK will automatically include the appropriate headers in all requests.
+
+## Module Structure
+
+The SDK is organized into modules for better code organization:
+
+- **Platform** (`cilantro-sdk/platform`) - Platform management and user operations
+- **User** (`cilantro-sdk/user`) - User account operations
+- **Wallet** (`cilantro-sdk/wallet`) - Wallet and blockchain operations
+- **Admin** (`cilantro-sdk/admin`) - Administrative operations
+- **Auth** (`cilantro-sdk/auth`) - Universal authentication
+- **Subscriptions** (`cilantro-sdk/subscriptions`) - Subscription management operations
+- **Plans** (`cilantro-sdk/plans`) - Subscription plan management operations
+- **Transactions** (`cilantro-sdk/transactions`) - Transaction history and status queries
+- **Delegated Keys** (`cilantro-sdk/delegated-keys`) - Temporary key management for session-based signing
+- **Webhooks** (`cilantro-sdk/webhooks`) - Webhook endpoint management for event notifications
+- **Utils** (`cilantro-sdk/utils`) - Utility functions
+- **Helpers** (`cilantro-sdk/helpers`) - Device key management and signer helpers
+
+### Quick Reference
+
+**Platform Module:**
+- Basic: `create`, `findAll`, `findOne`, `update`, `remove`, `getOwnProfile`, `updateOwnProfile`
+- Users: `getUsers`, `createUser`, `updateUser`, `removeUser`, `toggleUserActive`
+- Wallets: `getWallets` (read-only)
+
+**User Module:**
+- `create`, `findOne`, `update`
+
+**Wallet Module:**
+- Basic: `create`, `findAll`, `findOne`, `update`, `remove`, `findByAddress`, `getTotalBalance`
+- Status: `activate`, `deactivate`
+- Transactions: `sendSOL`, `sendSPL`, `sendTransaction`, `simulateTransaction`
+- Batch: `batchCreate`, `batchSendSOL`, `batchSendSPL`
+- NFTs & Tokens: `mintNFT`, `mintNFTSimple`, `mintToken`
+- Assets: `getAssets`, `syncAssets`
+- Signers: Email, phone, external, API key, and passkey signer management
+
+**Auth Module:**
+- `login` - Login and get JWT token
+- `loginAndSetAuth` - Login and automatically set authentication
+
+**Subscriptions Module:**
+- Basic: `create`, `findAll`, `findOne`, `getPlatformSubscription`
+- Management: `upgrade`, `downgrade`, `cancel`, `renew`
+- History: `getHistory` - Get subscription audit trail
+
+**Plans Module:**
+- Basic: `findAll`, `findOne`, `update`, `remove`
+- Assignment: `assignToPlatform`, `assignToUser`
+
+**Subscriptions Module:**
+- Basic: `create`, `findAll`, `findOne`, `getPlatformSubscription`
+- Management: `upgrade`, `downgrade`, `cancel`, `renew`
+- History: `getHistory` - Get subscription audit trail
+
+**Plans Module:**
+- Basic: `findAll`, `findOne`, `update`, `remove`
+- Assignment: `assignToPlatform`, `assignToUser`
+
+**Transactions Module:**
+- `getWalletTransactions` - Get paginated transaction history for a wallet
+- `getTransactionStatus` - Get transaction status by Solana signature
+
+**Delegated Keys Module:**
+- `create` - Create temporary delegated key for wallet
+- `findAll` - List all delegated keys for a wallet
+- `findOne` - Get delegated key by ID
+- `update` - Update delegated key configuration
+- `remove` - Revoke delegated key
+
+**Webhooks Module:**
+- `create` - Register new webhook endpoint
+- `findAll` - List all webhooks for platform
+- `findOne` - Get webhook by ID
+- `update` - Update webhook configuration
+- `remove` - Delete webhook
+
+**Helpers Module:**
+- Device key management, signer helpers, validation, and storage adapters (see above)
+
+## Examples
+
+### Subscriptions Module
+
+```typescript
+import { configure } from 'cilantro-sdk';
+import { subscriptions } from 'cilantro-sdk';
+
+// Configure SDK
+configure({ apiKey: 'your-api-key' });
+
+// Create a new subscription
+const newSubscription = await subscriptions.create({
+  platformId: 'platform-id',
+  planId: 'plan-id',
+  billingCycle: 'monthly',
+  trialDays: 7
+});
+
+// Get all subscriptions with filters
+const allSubscriptions = await subscriptions.findAll({
+  status: 'active',
+  platformId: 'platform-id'
+});
+
+// Get subscription by ID
+const subscription = await subscriptions.findOne('subscription-id');
+
+// Get platform's active subscription
+const platformSubscription = await subscriptions.getPlatformSubscription('platform-id');
+
+// Upgrade subscription
+await subscriptions.upgrade('subscription-id', {
+  newPlanId: 'premium-plan-id',
+  effectiveDate: '2024-01-01T00:00:00Z'
+});
+
+// Downgrade subscription
+await subscriptions.downgrade('subscription-id', {
+  newPlanId: 'basic-plan-id'
+});
+
+// Cancel subscription
+await subscriptions.cancel('subscription-id', {
+  cancelAtPeriodEnd: true
+});
+
+// Renew subscription
+await subscriptions.renew('subscription-id', {
+  extendByDays: 30
+});
+
+// Get subscription history
+const history = await subscriptions.getHistory('subscription-id');
+```
+
+### Plans Module
+
+```typescript
+import { configure } from 'cilantro-sdk';
+import { plans } from 'cilantro-sdk';
+
+// Configure SDK
+configure({ apiKey: 'your-api-key' });
+
+// Get all plans
+const allPlans = await plans.findAll();
+
+// Get plan by ID
+const plan = await plans.findOne('plan-id');
+
+// Update plan
+await plans.update('plan-id', {
+  planName: 'Updated Plan Name',
+  description: 'New description',
+  isActive: true
+});
+
+// Remove (deactivate) a plan
+await plans.remove('plan-id');
+
+// Assign plan to platform
+await plans.assignToPlatform('plan-id', 'platform-id', {
+  startDate: '2024-01-01T00:00:00Z',
+  billingCycle: 'monthly'
+});
+
+// Assign plan to user
+await plans.assignToUser('plan-id', 'user-id', {
+  startDate: '2024-01-01T00:00:00Z',
+  billingCycle: 'monthly'
+});
+```
+
+### Transactions Module
+
+```typescript
+import { configure } from 'cilantro-sdk';
+import { getWalletTransactions, getTransactionStatus } from 'cilantro-sdk/transactions';
+
+// Configure SDK
+configure({ apiKey: 'your-api-key' });
+
+// Get transaction history for a wallet
+const transactions = await getWalletTransactions('wallet-id', {
+  page: 1,
+  limit: 20,
+  type: 'transfer', // Optional: filter by type (transfer, mint, burn, etc.)
+  status: 'confirmed' // Optional: filter by status (pending, confirmed, failed)
+});
+
+// Get transaction status by Solana signature
+const status = await getTransactionStatus('transaction-signature-here');
+console.log('Transaction status:', status);
+```
+
+### Delegated Keys Module
+
+```typescript
+import { configure } from 'cilantro-sdk';
+import { create, findAll, update, remove } from 'cilantro-sdk/delegated-keys';
+
+// Configure SDK
+configure({ apiKey: 'your-api-key' });
+
+// Create a temporary delegated key for session-based signing
+const delegatedKey = await create('wallet-id', {
+  publicKey: 'delegated-public-key-here',
+  expiresAt: '2024-12-31T23:59:59Z',
+  permissions: {
+    canTransfer: true,
+    maxAmount: 1000000000, // 1 SOL in lamports
+    allowedPrograms: ['program-id-1', 'program-id-2']
+  }
+});
+
+// List all delegated keys for a wallet
+const keys = await findAll('wallet-id');
+console.log('Delegated keys:', keys);
+
+// Update delegated key permissions
+await update('wallet-id', 'key-id', {
+  permissions: {
+    canTransfer: false,
+    maxAmount: 500000000
+  }
+});
+
+// Revoke a delegated key
+await remove('wallet-id', 'key-id');
+```
+
+### Webhooks Module
+
+```typescript
+import { configure } from 'cilantro-sdk';
+import { create, findAll, update, remove } from 'cilantro-sdk/webhooks';
+
+// Configure SDK with your API key
+configure({ apiKey: 'your-api-key' });
+
+// Register a new webhook endpoint
+const webhook = await create({
+  url: 'https://your-domain.com/webhooks/cilantro',
+  events: ['wallet.created', 'transaction.confirmed', 'transaction.failed'],
+  description: 'Production webhook for transaction events',
+  isActive: true
+});
+
+// List all webhooks for your platform
+const webhooks = await findAll();
+console.log('Registered webhooks:', webhooks);
+
+// Update webhook configuration
+await update('webhook-id', {
+  events: ['wallet.created', 'transaction.confirmed'],
+  isActive: false // Temporarily disable
+});
+
+// Delete a webhook
+await remove('webhook-id');
+```
+
+## Error Handling
+
+The SDK provides custom error classes for better error handling:
+
+```typescript
+import { 
+  SDKError,
+  DeviceKeyMismatchError,
+  DeviceKeyNotFoundError,
+  NoDeviceIdentitiesError,
+  MultipleDeviceIdentitiesError
+} from 'cilantro-sdk';
+
+try {
+  const keypair = await getEmailSignerKeypair(walletId, signerId, { deviceKeyManager });
+} catch (error) {
+  if (error instanceof DeviceKeyNotFoundError) {
+    // Handle device key not found
+    console.error('Device key not found:', error.devicePublicKey);
+  } else if (error instanceof DeviceKeyMismatchError) {
+    // Handle device key mismatch
+    console.error('Device key mismatch:', error.expectedDeviceKey, error.actualDeviceKey);
+  } else {
+    // Handle other errors
+    console.error('Error:', error.message);
+  }
+}
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import type { 
+  DeviceKeyPair,
+  DeviceKeyStorage,
+  SignerInfo,
+  Keypair,
+  EmailSignerOptions,
+  PhoneSignerOptions
+} from 'cilantro-sdk/helpers';
+```
+
+## Cross-Platform Support
+
+The SDK works in both browser and Node.js environments:
+
+- **Browser**: Uses Web Crypto API and localStorage
+- **Node.js**: Uses Node.js crypto module and filesystem
+
+Storage adapters automatically detect the environment and use the appropriate implementation.
+
+## License
+
+ISC