@aura-payments/sdk 2.1.0

package/README.md

@@ -0,0 +1,489 @@
+# @aura-payments/sdk
+
+TypeScript SDK for the Aura Payments Platform API. Build payment flows with multi-party escrows, Circle wallets, and real-time webhooks.
+
+## Installation
+
+```bash
+npm install @aura-payments/sdk
+# or
+yarn add @aura-payments/sdk
+# or
+pnpm add @aura-payments/sdk
+```
+
+## Quick Start
+
+```typescript
+import { AuraClient } from '@aura-payments/sdk'
+
+const client = new AuraClient({
+  apiKey: process.env.AURA_API_KEY!,
+})
+
+// Create a multi-party escrow
+const escrow = await client.escrows.create({
+  orderId: 'order-123',
+  amountUsdc: '100.00',
+  splits: {
+    vendorEntityId: 'vendor-1',
+    sellerEntityId: 'seller-1',
+    platformEntityId: 'platform-1',
+    vendorPercentage: 70,
+    sellerPercentage: 20,
+    platformPercentage: 10,
+  },
+  adminSafeAddress: '0x...',
+})
+
+console.log(`Escrow created: ${escrow.escrowId}`)
+console.log(`Vault address: ${escrow.vaultAddress}`)
+```
+
+## Features
+
+- **Type-Safe** - Full TypeScript support with comprehensive type definitions
+- **Dual Module Support** - Works with ESM and CommonJS
+- **Automatic Retries** - Exponential backoff with jitter for failed requests
+- **Idempotency** - Automatic idempotency key generation for safe retries
+- **Error Handling** - Typed error classes with type guards
+- **Webhook Validation** - HMAC-SHA256 signature verification
+
+## Configuration
+
+```typescript
+import { AuraClient } from '@aura-payments/sdk'
+
+const client = new AuraClient({
+  // Required: Your API key from the Aura dashboard
+  apiKey: 'ak_live_...',
+
+  // Optional: API base URL (default: https://api.aura-payments.com)
+  baseUrl: 'https://api.aura-payments.com',
+
+  // Optional: Request timeout in ms (default: 30000)
+  timeout: 30000,
+
+  // Optional: Max retry attempts (default: 3)
+  maxRetries: 3,
+
+  // Optional: Auto-generate idempotency keys (default: true)
+  autoIdempotency: true,
+})
+```
+
+## API Reference
+
+### Escrows
+
+Escrows enable secure multi-party payments with configurable splits and release conditions.
+
+#### Create Escrow
+
+```typescript
+const escrow = await client.escrows.create({
+  orderId: 'order-123',
+  amountUsdc: '100.00',
+  splits: {
+    vendorEntityId: 'vendor-uuid',
+    sellerEntityId: 'seller-uuid',
+    platformEntityId: 'platform-uuid',
+    vendorPercentage: 70,
+    sellerPercentage: 20,
+    platformPercentage: 10,
+  },
+  adminSafeAddress: '0x...',
+  unlock: {
+    type: 'timeout', // 'oracle' | 'timeout' | 'hybrid' | 'manual'
+    days: 14,
+  },
+  items: [
+    {
+      orderItemId: 'item-1',
+      description: 'Premium Widget',
+      amountUsdc: '100.00',
+    },
+  ],
+})
+```
+
+#### Get Escrow
+
+```typescript
+const escrow = await client.escrows.get('escrow-id')
+```
+
+#### List Escrows
+
+```typescript
+const { data, pagination } = await client.escrows.list({
+  page: 1,
+  limit: 20,
+  status: 'funded', // 'pending' | 'funded' | 'locked' | 'released' | 'refunded' | 'disputed'
+  orderId: 'order-123',
+})
+```
+
+#### Fund Escrow
+
+```typescript
+const funded = await client.escrows.fund({
+  escrowId: 'escrow-id',
+  fromEntityId: 'buyer-entity-id',
+  amountUsdc: '100.00',
+})
+```
+
+#### Release Escrow
+
+```typescript
+// Full release
+const released = await client.escrows.release({
+  escrowId: 'escrow-id',
+})
+
+// Partial release
+const partialRelease = await client.escrows.release({
+  escrowId: 'escrow-id',
+  partial: {
+    itemIds: ['item-1', 'item-2'],
+  },
+})
+
+// With multisig signature
+const signedRelease = await client.escrows.release({
+  escrowId: 'escrow-id',
+  signature: {
+    digest: '0x...',
+    signature: '0x...',
+  },
+})
+```
+
+#### Refund Escrow
+
+```typescript
+const refunded = await client.escrows.refund({
+  escrowId: 'escrow-id',
+  reason: 'vendor_reject', // 'vendor_reject' | 'sla_breach' | 'manual' | 'dispute_resolved'
+  toEntityId: 'buyer-entity-id',
+  amountUsdc: '50.00', // Optional: partial refund
+})
+```
+
+#### Disputes
+
+```typescript
+// Open a dispute
+const dispute = await client.escrows.createDispute({
+  escrowId: 'escrow-id',
+  openedByEntityId: 'buyer-entity-id',
+  reason: 'Item not as described',
+  evidenceUrl: 'https://...',
+})
+
+// Get dispute details
+const disputeDetails = await client.escrows.getDispute('escrow-id', 'dispute-id')
+```
+
+### Wallets
+
+Manage Circle Developer-Controlled Wallets for your entities.
+
+#### Create Wallet
+
+```typescript
+const wallet = await client.wallets.create({
+  entityId: 'entity-uuid',
+  chain: 'ARC', // 'ARC' | 'ARB' | 'BASE' | 'ETH' | 'MATIC' | 'SOL'
+  type: 'developer_controlled', // 'developer_controlled' | 'user_controlled'
+})
+```
+
+#### Get Wallet
+
+```typescript
+const wallet = await client.wallets.get('wallet-id')
+```
+
+#### List Wallets
+
+```typescript
+const { data, pagination } = await client.wallets.list({
+  entityId: 'entity-uuid',
+  chain: 'ARC',
+  type: 'developer_controlled',
+  page: 1,
+  limit: 20,
+})
+```
+
+#### Get Balance
+
+```typescript
+const balance = await client.wallets.getBalance('wallet-id')
+// Returns: { walletId, address, chain, balances: [{ token, amount, decimals, symbol }] }
+```
+
+#### Transfer Funds
+
+```typescript
+const transfer = await client.wallets.transfer({
+  fromWalletId: 'wallet-id',
+  toAddress: '0x...',
+  amount: '50.00',
+  token: 'USDC',
+})
+
+// Check transfer status
+const status = await client.wallets.getTransfer('wallet-id', transfer.id)
+```
+
+### Webhooks
+
+Configure webhook endpoints to receive real-time payment events.
+
+#### Configure Webhook
+
+```typescript
+const config = await client.webhooks.configure({
+  url: 'https://your-app.com/webhooks/aura',
+  events: [
+    'escrow.created',
+    'escrow.funded',
+    'escrow.released',
+    'escrow.refunded',
+    'escrow.disputed',
+    'wallet.created',
+    'transfer.completed',
+    'transfer.failed',
+    'dispute.opened',
+    'dispute.resolved',
+  ],
+})
+```
+
+#### Get Webhook Config
+
+```typescript
+const config = await client.webhooks.getConfig()
+```
+
+#### Delete Webhook
+
+```typescript
+await client.webhooks.delete()
+```
+
+#### Validate Webhook Signature
+
+```typescript
+import { Webhooks } from '@aura-payments/sdk'
+
+// In your webhook handler
+app.post('/webhooks/aura', (req, res) => {
+  const signature = req.headers['x-aura-signature'] as string
+  const secret = process.env.AURA_WEBHOOK_SECRET!
+
+  const result = Webhooks.validateSignature({
+    payload: req.body,
+    signature,
+    secret,
+  })
+
+  if (!result.valid) {
+    console.error('Invalid webhook signature:', result.error)
+    return res.status(401).send('Invalid signature')
+  }
+
+  const event = result.event!
+
+  switch (event.type) {
+    case 'escrow.funded':
+      console.log('Escrow funded:', event.data)
+      break
+    case 'escrow.released':
+      console.log('Escrow released:', event.data)
+      break
+    case 'transfer.completed':
+      console.log('Transfer completed:', event.data)
+      break
+  }
+
+  res.status(200).send('OK')
+})
+```
+
+## Error Handling
+
+The SDK provides typed error classes for different failure scenarios:
+
+```typescript
+import {
+  AuraError,
+  AuraAPIError,
+  AuraNetworkError,
+  AuraTimeoutError,
+  AuraValidationError,
+  AuraAuthenticationError,
+  AuraNotFoundError,
+  AuraRateLimitError,
+  isAuraError,
+  isRetryableError,
+} from '@aura-payments/sdk'
+
+try {
+  await client.escrows.get('invalid-id')
+} catch (error) {
+  if (error instanceof AuraNotFoundError) {
+    console.log('Escrow not found')
+  } else if (error instanceof AuraValidationError) {
+    console.log('Validation failed:', error.details)
+  } else if (error instanceof AuraAuthenticationError) {
+    console.log('Invalid API key')
+  } else if (error instanceof AuraRateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter}s`)
+  } else if (error instanceof AuraNetworkError) {
+    console.log('Network error:', error.cause)
+  } else if (error instanceof AuraTimeoutError) {
+    console.log('Request timed out')
+  } else if (isAuraError(error)) {
+    console.log(`API error: ${error.message} (${error.code})`)
+  }
+
+  // Check if error is retryable
+  if (isRetryableError(error)) {
+    // Implement retry logic
+  }
+}
+```
+
+### Error Types
+
+| Error Class | Status Code | Description |
+|-------------|-------------|-------------|
+| `AuraValidationError` | 400 | Invalid request parameters |
+| `AuraAuthenticationError` | 401 | Invalid or missing API key |
+| `AuraNotFoundError` | 404 | Resource not found |
+| `AuraRateLimitError` | 429 | Rate limit exceeded |
+| `AuraTimeoutError` | 408 | Request timeout |
+| `AuraNetworkError` | - | Network connectivity issue |
+| `AuraAPIError` | 5xx | Server error |
+
+## TypeScript Types
+
+All types are exported for use in your application:
+
+```typescript
+import type {
+  // Client
+  AuraClientConfig,
+
+  // Escrow types
+  Escrow,
+  EscrowStatus,
+  EscrowSplit,
+  UnlockType,
+  DisputeStatus,
+  Dispute,
+  CreateEscrowParams,
+  CreateEscrowResponse,
+  FundEscrowParams,
+  ReleaseEscrowParams,
+  RefundEscrowParams,
+  CreateDisputeParams,
+  ListEscrowsParams,
+  ListEscrowsResponse,
+
+  // Wallet types
+  Wallet,
+  WalletBalance,
+  TokenBalance,
+  Chain,
+  WalletType,
+  CreateWalletParams,
+  TransferParams,
+  Transfer,
+  ListWalletsParams,
+  ListWalletsResponse,
+
+  // Webhook types
+  WebhookEvent,
+  WebhookEventType,
+  WebhookConfig,
+  ConfigureWebhookParams,
+  WebhookValidationResult,
+  ValidateWebhookSignatureOptions,
+
+  // Shared types
+  PaginationParams,
+  PaginatedResponse,
+} from '@aura-payments/sdk'
+```
+
+## Utilities
+
+The SDK exports utility functions for advanced use cases:
+
+```typescript
+import {
+  generateIdempotencyKey,
+  retryWithBackoff,
+  withTimeout,
+  calculateBackoff,
+} from '@aura-payments/sdk'
+
+// Generate a unique idempotency key
+const key = generateIdempotencyKey()
+// Returns: "1703001234567-abc123def456"
+
+// Retry a function with exponential backoff
+const result = await retryWithBackoff(
+  () => someAsyncOperation(),
+  3 // max retries
+)
+
+// Add timeout to any promise
+const result = await withTimeout(
+  fetch('https://api.example.com'),
+  5000 // timeout in ms
+)
+```
+
+## Idempotency
+
+All state-changing operations (POST/PUT) automatically include idempotency keys to ensure safe retries. You can provide your own:
+
+```typescript
+// Auto-generated idempotency key (default)
+await client.escrows.create(params)
+
+// Custom idempotency key
+await client.escrows.create(params, 'my-unique-key-123')
+
+// Disable auto-generation globally
+const client = new AuraClient({
+  apiKey: '...',
+  autoIdempotency: false,
+})
+```
+
+## Supported Chains
+
+| Chain | Identifier | Network |
+|-------|------------|---------|
+| Arc | `ARC` | Arc Testnet / Mainnet |
+| Arbitrum | `ARB` | Arbitrum Sepolia / One |
+| Base | `BASE` | Base Sepolia / Mainnet |
+| Ethereum | `ETH` | Ethereum Mainnet |
+| Polygon | `MATIC` | Polygon Mainnet |
+| Solana | `SOL` | Solana Mainnet |
+
+## Requirements
+
+- Node.js 18+ (for native `fetch` support)
+- TypeScript 5.x (for best type inference)
+
+## License
+
+MIT