This is a test email
',\n text: 'This is a test email'\n});\n\nif (result.success) {\n console.log('Email sent:', result.messageId);\n}\n```\n\n## Configuration\n\n```typescript\ninterface EmailManagerClientConfig {\n baseUrl: string; // Required: Backend API base URL\n apiKey?: string; // Optional: API key for authentication\n timeout?: number; // Optional: Request timeout in ms (default: 30000)\n headers?: RecordDon\\'t forget!
' },\n new Date('2025-03-01T09:00:00Z')\n);\n// => { success: true, scheduleId: 'sch_xyz', scheduledFor: '2025-03-01T09:00:00.000Z', emailId: '...', status: 'scheduled' }\n```\n\n#### `cancelScheduledEmail(scheduleId)`\n\n```typescript\nconst result = await client.cancelScheduledEmail('sch_xyz');\n// => { success: true, message: 'Scheduled email cancelled' }\n```\n\n#### `getScheduledEmail(scheduleId)` / `listScheduledEmails(options?)`\n\n```typescript\nconst email = await client.getScheduledEmail('sch_xyz');\nconst emails = await client.listScheduledEmails({ page: 1, pageSize: 20 });\n```\n\n---\n\n### Calendar Methods\n\n#### `sendCalendarInvite(event, recipients, options?)`\n\nSend a calendar invitation (iCal/ICS) to recipients.\n\n```typescript\nconst result = await client.sendCalendarInvite(\n {\n title: 'Sprint Planning',\n description: 'Weekly sprint planning session',\n start: '2025-02-01T14:00:00Z',\n end: '2025-02-01T15:00:00Z',\n location: 'Conference Room A',\n organizer: { email: 'team-lead@example.com', name: 'Team Lead' },\n attendees: [\n { email: 'dev1@example.com', name: 'Developer 1' },\n { email: 'dev2@example.com', name: 'Developer 2' }\n ]\n },\n ['dev1@example.com', 'dev2@example.com'],\n { subject: 'You are invited: Sprint Planning' }\n);\n// => { success: true, messageId: 'msg_cal_001', eventUid: 'evt_abc123' }\n```\n\n#### `cancelCalendarEvent(eventUid, organizer, attendees)`\n\nCancel a previously sent calendar event and notify all attendees.\n\n```typescript\nconst result = await client.cancelCalendarEvent(\n 'evt_abc123',\n { email: 'team-lead@example.com', name: 'Team Lead' },\n [{ email: 'dev1@example.com' }, { email: 'dev2@example.com' }]\n);\n// => { success: true, eventUid: 'evt_abc123' }\n```\n\n---\n\n### Batch Sending\n\n#### `sendBatch(emails, options?)`\n\nSend multiple emails in a single operation with configurable concurrency and failure handling.\n\n```typescript\nconst result = await client.sendBatch(\n [\n { to: 'user1@example.com', subject: 'Update', html: 'News for you
' },\n { to: 'user2@example.com', subject: 'Update', html: 'News for you
' },\n { to: 'user3@example.com', subject: 'Update', html: 'News for you
' }\n ],\n {\n concurrency: 5,\n rateLimit: { maxPerSecond: 10, maxPerMinute: 300 },\n failureStrategy: 'continue', // 'continue' | 'abort-on-first' | 'abort-on-threshold'\n failureThreshold: 0.5 // Abort if 50% fail (used with 'abort-on-threshold')\n }\n);\n// => {\n// total: 3,\n// succeeded: 2,\n// failed: 1,\n// results: [\n// { recipient: 'user1@example.com', success: true, messageId: 'msg_1', attempts: 1 },\n// { recipient: 'user2@example.com', success: true, messageId: 'msg_2', attempts: 1 },\n// { recipient: 'user3@example.com', success: false, error: 'Invalid address', attempts: 2 }\n// ],\n// duration: 1234,\n// aborted: false\n// }\n```\n\n**Failure strategies:**\n\n| Strategy | Behavior |\n|----------|----------|\n| `continue` | Send all emails regardless of individual failures |\n| `abort-on-first` | Stop immediately on the first failure |\n| `abort-on-threshold` | Stop when the failure rate exceeds `failureThreshold` |\n\n---\n\n### Template Management\n\n#### `createTemplate(template)` / `getTemplate(id)` / `updateTemplate(id, template)` / `deleteTemplate(id)`\n\n```typescript\nconst result = await client.createTemplate({\n name: 'welcome',\n subject: 'Welcome, {{name}}!',\n htmlTemplate: '{{missing}}
' });\n// => { isValid: false, errors: ['Unknown variable: missing'] }\n```\n\n---\n\n### Provider Management\n\n#### `addProvider(provider)` / `getProvider(id)` / `updateProvider(id, provider)` / `deleteProvider(id)`\n\n```typescript\nconst result = await client.addProvider({\n name: 'Primary SendGrid',\n type: 'sendgrid',\n config: { apiKey: '...' },\n isActive: true,\n priority: 1,\n rateLimit: { maxPerMinute: 100, maxPerHour: 3000, maxPerDay: 50000 }\n});\n```\n\n#### `listProviders()` / `getProviderStatus(id)` / `testProvider(id)`\n\n```typescript\nconst providers = await client.listProviders();\n// => { providers: [...], total: 3 }\n\nconst status = await client.getProviderStatus('prov_123');\n// => { id: 'prov_123', isActive: true, isHealthy: true, lastHealthCheck: '...', currentUsage: { minute: 5, hour: 120, day: 2400 } }\n\nconst test = await client.testProvider('prov_123');\n// => { success: true, message: 'Connection successful' }\n```\n\n---\n\n### Analytics\n\n#### `getEmailStats(emailId)` / `getDeliveryReport(options?)` / `getBounceReport(options?)`\n\n```typescript\nconst stats = await client.getEmailStats('msg_abc');\n// => { emailId: 'msg_abc', sent: 1000, delivered: 985, opened: 450, clicked: 120, bounced: 15, deliveryRate: 0.985, openRate: 0.45, clickRate: 0.12 }\n\nconst report = await client.getDeliveryReport({\n startDate: '2025-01-01T00:00:00Z',\n endDate: '2025-01-31T23:59:59Z',\n provider: 'sendgrid'\n});\n\nconst bounces = await client.getBounceReport({\n startDate: '2025-01-01T00:00:00Z',\n endDate: '2025-01-31T23:59:59Z'\n});\n```\n\n---\n\n### Subscription Management\n\n#### `createSubscriberList(name, description?)`\n\nCreate a new subscriber list for organizing recipients.\n\n```typescript\nconst list = await client.createSubscriberList('Weekly Newsletter', 'Subscribers to our weekly digest');\n// => { id: 'list_abc', name: 'Weekly Newsletter', description: '...', subscriberCount: 0, createdAt: '...', updatedAt: '...' }\n```\n\n#### `listSubscriberLists(options?)`\n\n```typescript\nconst result = await client.listSubscriberLists({ limit: 20, offset: 0 });\n// => { items: [{ id: 'list_abc', name: 'Weekly Newsletter', subscriberCount: 150, ... }], total: 3 }\n```\n\n#### `deleteSubscriberList(listId)`\n\n```typescript\nconst result = await client.deleteSubscriberList('list_abc');\n// => { success: true, message: 'List deleted' }\n```\n\n#### `addSubscriber(listId, subscriber)`\n\n```typescript\nawait client.addSubscriber('list_abc', {\n email: 'reader@example.com',\n name: 'Jane Reader'\n});\n```\n\n#### `removeSubscriber(listId, email)`\n\n```typescript\nawait client.removeSubscriber('list_abc', 'reader@example.com');\n```\n\n#### `getSubscriber(listId, email)`\n\n```typescript\nconst subscriber = await client.getSubscriber('list_abc', 'reader@example.com');\n// => { email: 'reader@example.com', name: 'Jane Reader', status: 'active', subscribedAt: '2025-01-10T...' }\n// Returns null if the subscriber is not found on the list.\n```\n\n---\n\n### Unsubscribe\n\n#### `generateUnsubscribeUrl(email, listId)`\n\nGenerate a secure, tokenized unsubscribe URL for inclusion in email footers.\n\n```typescript\nconst { url } = await client.generateUnsubscribeUrl('reader@example.com', 'list_abc');\n// => { url: 'https://api.example.com/unsubscribe?token=eyJhbGciOi...' }\n```\n\n#### `processUnsubscribe(token)`\n\nProcess an unsubscribe request using the token extracted from the URL.\n\n```typescript\nawait client.processUnsubscribe('eyJhbGciOi...');\n// Removes the subscriber from the associated list. No return value.\n```\n\n---\n\n### Suppression Management\n\nThe suppression list prevents emails from being sent to specific addresses, regardless of their subscription status. Suppressions can be scoped globally or to a specific list.\n\n#### `getSuppressions(options?)`\n\n```typescript\nconst result = await client.getSuppressions({ reason: 'hard_bounce' });\n// => {\n// items: [\n// { email: 'bounced@example.com', reason: 'hard_bounce', scope: 'global', createdAt: '2025-01-05T...' }\n// ],\n// total: 1\n// }\n```\n\n#### `addSuppression(email, reason, scope?)`\n\n```typescript\nawait client.addSuppression('spam-reporter@example.com', 'complaint', 'global');\n```\n\n#### `removeSuppression(email, scope?)`\n\n```typescript\nconst result = await client.removeSuppression('rehabilitated@example.com', 'global');\n// => { success: true }\n```\n\n#### `isSuppressed(email, listId?)`\n\nCheck whether an email address is on the suppression list before attempting to send.\n\n```typescript\nconst suppressed = await client.isSuppressed('user@example.com');\n// => true | false\n\nconst suppressedOnList = await client.isSuppressed('user@example.com', 'list_abc');\n// => true | false\n```\n\n---\n\n### Webhook Processing\n\n#### `processWebhookEvent(provider, payload)`\n\nForward incoming webhook payloads from email providers to the backend for processing. The backend will normalize the provider-specific format and update delivery statuses.\n\n```typescript\n// SendGrid webhook\nawait client.processWebhookEvent('sendgrid', [\n { event: 'delivered', email: 'user@example.com', timestamp: 1706000000, sg_message_id: 'msg_123' },\n { event: 'open', email: 'user@example.com', timestamp: 1706000060, sg_message_id: 'msg_123' }\n]);\n\n// Mailgun webhook\nawait client.processWebhookEvent('mailgun', {\n signature: { timestamp: '1706000000', token: 'abc', signature: 'def' },\n 'event-data': { event: 'delivered', recipient: 'user@example.com' }\n});\n\n// Postmark webhook\nawait client.processWebhookEvent('postmark', {\n RecordType: 'Delivery',\n MessageID: 'msg_456',\n Recipient: 'user@example.com',\n DeliveredAt: '2025-01-23T12:00:00Z'\n});\n```\n\n---\n\n## Capability Matrix\n\nThe client package exports types for working with the capability matrix and routing metadata that the backend includes in API responses.\n\n### Capability Types\n\n```typescript\nimport type {\n ClientCapabilitySource, // 'provider' | 'platform' | 'enhanced'\n ClientCapabilityEntry, // Individual capability entry with source, description, limitations\n ClientDegradationInfo, // Degradation strategy and description\n ClientRoutingMetadata, // Routing info attached to SendResult\n ClientProviderName, // 'sendgrid' | 'mailgun' | 'postmark' | 'ses' | 'smtp'\n ClientFeatureName, // String key from the capability matrix\n} from '@bernierllc/email-manager-client';\n```\n\n### ClientCapabilityEntry\n\nDescribes how a specific provider supports a feature:\n\n```typescript\ninterface ClientCapabilityEntry {\n source: ClientCapabilitySource; // 'provider' | 'platform' | 'enhanced'\n description: string; // Human-readable description\n limitations?: string; // Known limitations\n degradation?: ClientDegradationInfo | null;\n overridable: boolean; // Whether this entry can be overridden at runtime\n}\n\ninterface ClientDegradationInfo {\n strategy: string; // e.g., 'platform-managed', 'sequential-batch'\n description: string; // What the degradation means\n docUrl?: string; // Link to degradation documentation\n}\n```\n\n### RoutingMetadata in HTTP Responses\n\nWhen the backend has capability-aware routing enabled, the `SendResult` returned from `sendEmail()` includes a `routing` field:\n\n```typescript\nconst result = await client.sendEmail({\n to: 'user@example.com',\n subject: 'Hello',\n html: 'Hello
',\n});\n\nif (result.routing) {\n console.log('Feature:', result.routing.feature);\n console.log('Provider:', result.routing.selectedProvider);\n console.log('Source:', result.routing.source); // 'provider' | 'platform' | 'enhanced'\n console.log('Degraded:', result.routing.degraded); // true if platform polyfill was used\n console.log('Alternatives:', result.routing.alternativeProviders);\n console.log('Resolved at:', result.routing.resolvedAt);\n\n if (result.routing.degradation) {\n console.log('Degradation strategy:', result.routing.degradation.strategy);\n console.log('Degradation detail:', result.routing.degradation.description);\n }\n}\n```\n\n### ClientRoutingMetadata Interface\n\n```typescript\ninterface ClientRoutingMetadata {\n feature: string; // The feature that was routed (e.g., 'sendEmail')\n selectedProvider: string; // Provider ID that handled the request\n source: ClientCapabilitySource; // How the provider supports this feature\n degraded: boolean; // Whether the feature was degraded\n degradation?: ClientDegradationInfo | null;\n alternativeProviders: string[]; // Other providers that could handle this feature\n resolvedAt: string; // ISO date string of when routing was resolved\n}\n```\n\nThe `routing` field is only present when the backend has routing enabled. If the backend does not use capability-aware routing, `result.routing` will be `undefined`.\n\n---\n\n## Error Handling\n\nThe client uses a hierarchy of typed error classes with ES2022 `Error.cause` support for full error chain preservation.\n\n### Error Classes\n\n| Class | Code | Retryable | Description |\n|-------|------|-----------|-------------|\n| `EmailManagerClientError` | varies | varies | Base error for all API errors |\n| `NetworkError` | `NETWORK_ERROR` | yes | Network connectivity failure |\n| `TimeoutError` | `TIMEOUT_ERROR` | yes | Request exceeded timeout |\n| `RateLimitError` | `RATE_LIMITED` | yes | Too many requests (429) |\n| `UnauthorizedError` | `UNAUTHORIZED` | no | Invalid or missing API key (401) |\n| `NotFoundError` | `NOT_FOUND` | no | Resource does not exist (404) |\n\n### Error Codes\n\nAll errors carry a machine-readable `code` property:\n\n- `NETWORK_ERROR` - Network failure\n- `TIMEOUT_ERROR` - Request timed out\n- `API_ERROR` - General API error\n- `BAD_REQUEST` - Invalid request (400)\n- `UNAUTHORIZED` - Authentication failure (401)\n- `FORBIDDEN` - Insufficient permissions (403)\n- `NOT_FOUND` - Resource not found (404)\n- `RATE_LIMITED` - Rate limit exceeded (429)\n- `SERVER_ERROR` - Server-side error (5xx)\n\n### Usage\n\n```typescript\nimport {\n EmailManagerClient,\n EmailManagerClientError,\n NetworkError,\n TimeoutError,\n RateLimitError,\n NotFoundError\n} from '@bernierllc/email-manager-client';\n\ntry {\n await client.sendEmail(emailData);\n} catch (error) {\n if (error instanceof EmailManagerClientError) {\n console.error('Code:', error.code); // e.g. 'RATE_LIMITED'\n console.error('Status:', error.statusCode); // e.g. 429\n console.error('Context:', error.context); // Additional details\n\n // Check retryability\n if (error.isRetryable()) {\n const retryAfter = error.getRetryAfter(); // Suggested delay in ms\n console.log(`Retry after ${retryAfter}ms`);\n }\n\n // Inspect error chain\n if (error.cause) {\n console.error('Caused by:', (error.cause as Error).message);\n }\n }\n}\n```\n\n### Retry Pattern\n\n```typescript\nasync function sendWithRetry(client: EmailManagerClient, email: EmailData, maxRetries = 3) {\n for (let attempt = 1; attempt <= maxRetries; attempt++) {\n try {\n return await client.sendEmail(email);\n } catch (error) {\n if (error instanceof EmailManagerClientError && error.isRetryable() && attempt < maxRetries) {\n const delay = error.getRetryAfter() ?? (1000 * Math.pow(2, attempt));\n await new Promise(resolve => setTimeout(resolve, delay));\n continue;\n }\n throw error;\n }\n }\n}\n```\n\n---\n\n## TypeScript Types\n\nAll types are exported for use in your application:\n\n```typescript\nimport type {\n // Configuration\n EmailManagerClientConfig,\n\n // Email\n EmailData,\n SendResult,\n ScheduleResult,\n ScheduledEmail,\n CancelResult,\n\n // Templates\n EmailTemplate,\n TemplateResult,\n TemplateList,\n ValidationResult,\n\n // Providers\n EmailProvider,\n ProviderResult,\n ProviderList,\n ProviderStatus,\n TestResult,\n\n // Analytics\n EmailStats,\n DeliveryReport,\n BounceReport,\n ReportOptions,\n ListOptions,\n DeleteResult,\n\n // Calendar\n ClientCalendarEvent,\n CalendarInviteResult,\n CalendarCancelResult,\n\n // Batch\n ClientBatchSendOptions,\n ClientBatchResult,\n\n // Subscriptions\n ClientSubscriberList,\n ClientSubscriber,\n ClientSuppression,\n\n // Errors\n EmailManagerClientErrorOptions,\n EmailManagerClientErrorCodeType,\n} from '@bernierllc/email-manager-client';\n```\n\n---\n\n## Browser Compatibility\n\nThis package uses the native `fetch` API, which is available in:\n- Modern browsers (Chrome, Firefox, Safari, Edge)\n- Node.js 18+ (with native fetch)\n- For older environments, use a fetch polyfill\n\n## Differences from email-manager\n\n1. **No Node.js dependencies** - Can be bundled for browser\n2. **HTTP-based** - Makes API calls instead of direct function calls\n3. **Date handling** - Uses ISO date strings instead of Date objects in some places\n4. **Attachments** - Uses base64 strings instead of Buffer objects\n5. **Requires backend** - Needs a server running email-manager\n\n## Examples\n\nRunnable example files are available in the [`examples/`](./examples/) directory:\n\n- [`calendar-workflow.ts`](./examples/calendar-workflow.ts) - Send invites and cancel events\n- [`batch-operations.ts`](./examples/batch-operations.ts) - Batch send with failure strategies\n- [`subscription-lifecycle.ts`](./examples/subscription-lifecycle.ts) - Lists, subscribers, suppressions, unsubscribe\n- [`webhook-handler.ts`](./examples/webhook-handler.ts) - Process webhook events from providers\n\n## License\n\nBernier LLC - Restricted License\n","readmeFilename":"README.md"}