HTML body
', // Optional\n cc: ['cc@example.com'], // Optional\n bcc: [{ email: 'bcc@example.com' }], // Optional\n});\n\n// Get threads from inbox\nconst threads = await inbox.getThreads({\n is_read: false,\n is_archived: false,\n labels: ['important'],\n participant: 'user@example.com',\n limit: 20,\n offset: 0,\n});\n\n// Get a specific thread\nconst thread = await inbox.getThread('thread-uuid');\n\n// Update inbox\nawait inbox.update({\n display_name: 'Support Agent',\n agent_prompt: 'You are a helpful support agent...',\n});\n\n// Delete inbox\nawait inbox.delete();\n```\n\n### Threads (Fluent API)\n\n```typescript\nconst threads = await inbox.getThreads({ is_read: false });\nconst thread = threads.data[0];\n\n// Get all messages in a thread\nconst messages = await thread.getMessages();\n\n// Reply to thread (sends to all participants)\nawait thread.reply({\n text: 'Thanks for your email!',\n html: 'Thanks for your email!
',\n cc: 'manager@example.com', // Optional\n});\n\n// Thread actions\nawait thread.markAsRead();\nawait thread.markAsUnread();\nawait thread.archive();\nawait thread.unarchive();\n\n// Manage labels\nawait thread.addLabels(['urgent', 'follow-up']);\nawait thread.removeLabels(['urgent']);\nawait thread.update({ labels: ['resolved'] });\n\n// Delete thread\nawait thread.delete();\n```\n\n### Traditional API (Still Available)\n\n```typescript\n// List all inboxes\nconst inboxes = await client.inboxes.list();\n\n// Create an inbox\nconst inbox = await client.inboxes.create({\n username: 'support',\n name: 'Support Agent',\n webhook_url: 'https://example.com/webhook',\n});\n\n// Update inbox by ID\nawait client.inboxes.update('inbox-id', {\n display_name: 'Updated Name',\n});\n\n// Thread operations by ID\nconst threads = await client.threads.list('inbox-id', {\n limit: 20,\n is_read: false,\n});\n\nawait client.threads.markAsRead('inbox-id', 'thread-id');\nawait client.threads.archive('inbox-id', 'thread-id');\n\n// Send email by inbox ID\nawait client.emails.send('inbox-id', {\n to: [{ email: 'user@example.com', name: 'User' }],\n subject: 'Hello',\n text: 'Message body',\n});\n```\n\n### Labels\n\n```typescript\n// Organization-level labels\nconst labels = await client.labels.list();\nconst label = await client.labels.create({\n name: 'Important',\n color: '#FF5733',\n description: 'High priority items',\n});\nawait client.labels.update('label-id', { color: '#00FF00' });\nawait client.labels.delete('label-id');\n\n// Inbox-specific labels\nconst inboxLabels = await client.inboxLabels.list('inbox-id');\nawait client.inboxLabels.create('inbox-id', {\n name: 'Resolved',\n color: '#00FF00',\n});\n```\n\n### Documents (Knowledge Base)\n\n```typescript\n// List documents\nconst docs = await client.documents.list('inbox-id');\n\n// Upload a document (browser)\nconst file = new File(['content'], 'document.txt', { type: 'text/plain' });\nawait client.documents.upload('inbox-id', file, 'My Document');\n\n// Search documents\nconst results = await client.documents.search('inbox-id', 'refund policy');\n\n// Get AI context from documents\nconst context = await client.documents.getContext('inbox-id', 'How do I process refunds?', 5);\n\n// Delete document\nawait client.documents.delete('inbox-id', 'doc-id');\n```\n\n## Webhook Verification\n\nWhen you set up a webhook URL for an inbox, AIThreads signs all webhook payloads so you can verify they're authentic:\n\n```typescript\nimport { constructWebhookEvent, verifyWebhookSignature } from '@aithreads/sdk';\n\n// Express.js example\napp.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {\n try {\n const event = constructWebhookEvent(\n req.body,\n req.headers,\n process.env.WEBHOOK_SECRET!\n );\n\n console.log(`Received ${event.event} for email ${event.email_id}`);\n \n // Handle the event\n switch (event.event) {\n case 'email.received':\n // Process incoming email\n break;\n }\n\n res.json({ received: true });\n } catch (error) {\n console.error('Webhook verification failed:', error.message);\n res.status(401).json({ error: 'Invalid signature' });\n }\n});\n```\n\n### Verification Options\n\n```typescript\nimport { verifyWebhookSignature, verifyWebhook } from '@aithreads/sdk';\n\n// Option 1: Get result object (doesn't throw)\nconst result = verifyWebhookSignature(payload, signature, secret, {\n maxAge: 300, // Max age in seconds (default: 5 minutes)\n});\n\nif (result.valid) {\n console.log('Event:', result.payload.event);\n} else {\n console.error('Error:', result.error);\n}\n\n// Option 2: Throws on failure\ntry {\n const payload = verifyWebhook(body, signature, secret);\n console.log('Event:', payload.event);\n} catch (error) {\n console.error('Invalid:', error.message);\n}\n```\n\n### Webhook Payload\n\n```typescript\ninterface WebhookPayload {\n event: 'email.received' | 'email.sent' | 'thread.created';\n email_id: string;\n thread_id: string;\n inbox_id: string;\n subject: string;\n from: string;\n timestamp: string; // ISO 8601\n}\n```\n\n### Getting Your Webhook Secret\n\nWhen you create an inbox with a webhook URL, a webhook secret is automatically generated. You can retrieve or regenerate it:\n\n```typescript\n// Create inbox with webhook\nconst inbox = await client.inboxes.create({\n username: 'support',\n webhook_url: 'https://example.com/webhook',\n});\n// The webhook_secret is returned on creation\n\n// Regenerate webhook secret (via API)\n// POST /v1/organizations/:org_id/inboxes/:inbox_id/webhook-secret\n```\n\n## Error Handling\n\nThe SDK provides typed errors with type guards for easy handling:\n\n```typescript\nimport {\n AIThreadsError,\n NotFoundError,\n PaymentRequiredError,\n RateLimitError,\n // Type guards\n isNotFoundError,\n isPaymentRequiredError,\n isRateLimitError,\n} from '@aithreads/sdk';\n\ntry {\n await inbox.send({ to: 'user@example.com', subject: 'Hi', text: 'Hello' });\n} catch (error) {\n // Using type guards (recommended)\n if (isNotFoundError(error)) {\n console.log('Inbox not found');\n } else if (isPaymentRequiredError(error)) {\n console.log(`Upgrade required. Current plan: ${error.plan}`);\n } else if (isRateLimitError(error)) {\n console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);\n }\n\n // Or using instanceof\n if (error instanceof AIThreadsError) {\n console.log(`Error: ${error.message} (${error.code})`);\n console.log(`Status: ${error.status}`);\n console.log(`Details:`, error.details);\n }\n}\n```\n\n### Error Types\n\n| Error | Status | Description |\n|-------|--------|-------------|\n| `ValidationError` | 400 | Invalid request data |\n| `AuthenticationError` | 401 | Invalid or missing API key |\n| `PaymentRequiredError` | 402 | Plan limits exceeded or subscription issue |\n| `ForbiddenError` | 403 | Permission denied |\n| `NotFoundError` | 404 | Resource not found |\n| `ConflictError` | 409 | Resource conflict (e.g., duplicate) |\n| `RateLimitError` | 429 | Too many requests |\n| `ServerError` | 5xx | Server-side error |\n\n## TypeScript Support\n\nAll types are exported for full TypeScript support:\n\n```typescript\nimport type {\n // Inbox types\n Inbox,\n InboxResponse,\n InboxInstance,\n SimpleSendEmailOptions,\n // Thread types\n Thread,\n ThreadResponse,\n ThreadInstance,\n ThreadReplyOptions,\n // Email types\n Email,\n SendEmailRequest,\n SendEmailResponse,\n // Webhook types\n WebhookPayload,\n WebhookEventType,\n VerifyWebhookOptions,\n WebhookVerificationResult,\n // Common types\n PaginatedResponse,\n Label,\n} from '@aithreads/sdk';\n```\n\n## Requirements\n\n- Node.js 18+\n- Modern browser with Fetch API support\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-fb56f411eaa78d28d2baf7eb74dbc6ef"}