@ewyn/client 0.1.0

package/README.md

@@ -0,0 +1,267 @@
+# @ewyn/client
+
+Official TypeScript SDK for the Ewyn email service with full type safety.
+
+## Installation
+
+```bash
+npm install @ewyn/client
+# or
+pnpm add @ewyn/client
+# or
+yarn add @ewyn/client
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- TypeScript 5.0+ (for type-safe features)
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { Mailer } from '@ewyn/client';
+
+const client = new Mailer({
+  workspaceId: 'your-workspace-id',
+  apiKey: 'your-api-key',
+  baseUrl: 'https://www.ewyn.ai/api/v1', // optional; omit to use production default
+});
+
+// Send an email using template version ID
+await client.send({
+  to: 'user@example.com',
+  templateId: 'template-version-uuid',
+  variables: {
+    firstName: 'John',
+    lastName: 'Doe',
+  },
+});
+```
+
+### Type-Safe Usage with Template Config
+
+Get full TypeScript autocomplete and validation by copying your template config from the dashboard:
+
+```typescript
+import { Mailer } from '@ewyn/client';
+
+// 1. Copy template config from dashboard (API Keys page)
+const config = {
+  welcome: {
+    id: 'version-uuid-1',
+    name: 'Welcome Email',
+    version: 1,
+    vars: {
+      firstName: { required: true },
+      lastName: { required: true },
+      plan: { required: false },
+    },
+  },
+  'password-reset': {
+    id: 'version-uuid-2',
+    name: 'Password Reset',
+    version: 1,
+    vars: {
+      resetUrl: { required: true },
+    },
+  },
+} as const; // ← Important: use 'as const'
+
+// 2. Initialize with config
+const client = new Mailer({
+  workspaceId: 'your-workspace-id',
+  apiKey: 'your-api-key',
+  templates: config,
+});
+
+// 3. Send with full type safety
+await client.send({
+  to: 'user@example.com',
+  template: 'welcome',     // ← Autocomplete available!
+  variables: {
+    firstName: 'John',     // ← TypeScript enforces required vars
+    lastName: 'Doe',
+    plan: 'Pro',           // ← Optional vars allowed
+  },
+});
+```
+
+## Getting Your Template Configuration
+
+### From Dashboard (Recommended)
+
+1. Go to your dashboard → **API Keys** page
+2. Scroll to **Template Configuration** section
+3. Click **Copy JSON** or **Download**
+4. Paste into your code with `as const`:
+
+```typescript
+const config = {
+  // ... paste here
+} as const;
+
+const client = new Mailer({
+  workspaceId: 'your-workspace-id',
+  apiKey: 'your-api-key',
+  templates: config, // Now fully type-safe!
+});
+```
+
+### Via API
+
+Alternatively, fetch the config programmatically:
+
+```bash
+curl -X GET https://www.ewyn.ai/api/v1/workspaces/YOUR_WORKSPACE_ID/templates/config \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+**Note:** Regenerate the config after creating or updating templates to keep it in sync.
+
+## API Reference
+
+### `Mailer` Class
+
+#### Constructor
+
+```typescript
+new Mailer(options: MailerOptions)
+```
+
+**Options:**
+
+- `workspaceId` (string, required): Your workspace UUID
+- `apiKey` (string, required): Your API key secret
+- `baseUrl` (string, optional): Base URL for the API (defaults to `https://www.ewyn.ai/api/v1`)
+- `templates` (TemplateConfig, optional): Template configuration for name-based sending
+- `maxRetries` (number, optional): Maximum retries for retryable errors (default: 3)
+- `timeout` (number, optional): Request timeout in milliseconds (default: 30000)
+
+#### Methods
+
+##### `send(options: SendEmailOptions): Promise<SendEmailResponse>`
+
+Send an email using a template.
+
+**Options:**
+
+- `to` (string, required): Recipient email address
+- `templateId` (string, optional): Template version UUID (required if `template` not provided)
+- `template` (string, optional): Template name (requires `templates` config)
+- `version` (number, optional): Major version number (use with template name, defaults to latest)
+- `variables` (Record<string, string>, optional): Variables to substitute in template
+- `metadata` (Record<string, unknown>, optional): Additional metadata to attach
+- `idempotencyKey` (string, optional): Key to prevent duplicate sends (valid for 24 hours)
+
+**Returns:**
+
+```typescript
+{
+  messageId: string;
+  status: 'queued';
+  queuedAt: string;
+}
+```
+
+**Throws:**
+
+- `MailerApiError`: If the API request fails
+- `Error`: If validation fails (missing template, missing variables, etc.)
+
+### Error Handling
+
+The SDK throws `MailerApiError` for API errors:
+
+```typescript
+import { Mailer, MailerApiError } from '@ewyn/client';
+
+try {
+  await client.send({ /* ... */ });
+} catch (error) {
+  if (error instanceof MailerApiError) {
+    console.error('API Error:', error.status, error.message);
+    console.error('Details:', error.details);
+    
+    if (error.isRetryable()) {
+      // Handle retryable error
+    }
+  }
+}
+```
+
+**Error Properties:**
+
+- `status` (number): HTTP status code
+- `code` (string, optional): Error code
+- `details` (unknown, optional): Additional error details
+- `message` (string): Error message
+
+**Error Methods:**
+
+- `isClientError()`: Returns `true` for 4xx errors
+- `isServerError()`: Returns `true` for 5xx errors
+- `isRetryable()`: Returns `true` for 429 or 5xx errors
+
+## Idempotency
+
+To prevent duplicate email sends, provide an `idempotencyKey`:
+
+```typescript
+await client.send({
+  to: 'user@example.com',
+  templateId: 'template-uuid',
+  idempotencyKey: 'unique-request-id-123',
+  variables: { /* ... */ },
+});
+```
+
+If the same `idempotencyKey` is used within 24 hours, the API will return the original response instead of sending a duplicate email.
+
+## Retry Logic
+
+The SDK automatically retries on:
+- 429 (Too Many Requests)
+- 5xx (Server Errors)
+- Network errors
+
+Retries use exponential backoff (1s, 2s, 4s) up to `maxRetries` (default: 3).
+
+## Examples
+
+Check out the [examples directory](./examples/) for comprehensive examples:
+
+- [Basic send](./examples/basic-send.ts) - Simple sending with template ID
+- [Type-safe usage](./examples/with-template-config.ts) - Full type safety with template config
+- [Error handling](./examples/error-handling.ts) - Comprehensive error handling patterns
+- [Idempotency](./examples/idempotency.ts) - Preventing duplicate sends
+- [Advanced patterns](./examples/advanced-usage.ts) - Batch sending, retries, and more
+
+## Testing
+
+```bash
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+```
+
+## Development
+
+```bash
+# Build the SDK
+pnpm build
+
+# Watch mode for development
+pnpm dev
+
+# Lint
+pnpm lint
+```
+
+## License
+
+MIT

package/dist/__tests__/config-types.test-d.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type-safety tests for dashboard-copied template configs.
+ *
+ * Config shape and assertions mirror what users get when they copy
+ * "Template Configuration" from the dashboard (API Keys page). Ensures
+ * that typed send() options enforce template names and required/optional
+ * variables at compile time.
+ */
+export {};
+//# sourceMappingURL=config-types.test-d.d.ts.map

package/dist/__tests__/config-types.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-types.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/config-types.test-d.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/__tests__/config-types.test-d.js

@@ -0,0 +1,96 @@
+/**
+ * Type-safety tests for dashboard-copied template configs.
+ *
+ * Config shape and assertions mirror what users get when they copy
+ * "Template Configuration" from the dashboard (API Keys page). Ensures
+ * that typed send() options enforce template names and required/optional
+ * variables at compile time.
+ */
+import { expectTypeOf, test } from 'vitest';
+import { Mailer } from '../index.js';
+// Dashboard-shaped config: same structure as getConfig response (id, name, version, vars)
+const dashboardConfig = {
+    welcome: {
+        id: 'version-uuid-1',
+        name: 'Welcome Email',
+        version: 1,
+        vars: {
+            firstName: { required: true },
+            plan: { required: false },
+        },
+    },
+    'reset-password': {
+        id: 'version-uuid-2',
+        name: 'Reset Password',
+        version: 2,
+        vars: {
+            resetUrl: { required: true },
+        },
+    },
+};
+test('client with dashboard config has typed send', () => {
+    const client = new Mailer({
+        workspaceId: 'ws',
+        apiKey: 'key',
+        templates: dashboardConfig,
+    });
+    expectTypeOf(client).toHaveProperty('send');
+    expectTypeOf(client.send).toBeFunction();
+});
+test('valid send: required var present, optional omitted', () => {
+    const client = new Mailer({
+        workspaceId: 'ws',
+        apiKey: 'key',
+        templates: dashboardConfig,
+    });
+    expectTypeOf({
+        to: 'x@example.com',
+        template: 'welcome',
+        variables: { firstName: 'J' },
+    }).toMatchTypeOf();
+});
+test('valid send: required and optional vars', () => {
+    const client = new Mailer({
+        workspaceId: 'ws',
+        apiKey: 'key',
+        templates: dashboardConfig,
+    });
+    expectTypeOf({
+        to: 'x@example.com',
+        template: 'welcome',
+        variables: { firstName: 'J', plan: 'Pro' },
+    }).toMatchTypeOf();
+});
+test('valid send: hyphenated template name', () => {
+    const client = new Mailer({
+        workspaceId: 'ws',
+        apiKey: 'key',
+        templates: dashboardConfig,
+    });
+    expectTypeOf({
+        to: 'x@example.com',
+        template: 'reset-password',
+        variables: { resetUrl: 'https://example.com/reset' },
+    }).toMatchTypeOf();
+});
+test('send return type is Promise<SendEmailResponse>', () => {
+    const client = new Mailer({
+        workspaceId: 'ws',
+        apiKey: 'key',
+        templates: dashboardConfig,
+    });
+    expectTypeOf(client.send).returns.toEqualTypeOf();
+});
+test('template name is constrained to config keys at type level', () => {
+    expectTypeOf().toMatchTypeOf();
+    expectTypeOf().toMatchTypeOf();
+});
+test('missing required variable is rejected by types', () => {
+    const client = new Mailer({
+        workspaceId: 'ws',
+        apiKey: 'key',
+        templates: dashboardConfig,
+    });
+    expectTypeOf().toMatchTypeOf();
+    expectTypeOf().toMatchTypeOf();
+});

package/dist/__tests__/dashboard-config.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runtime tests for dashboard-shaped template configs.
+ *
+ * Config fixtures mirror the exact shape returned by the dashboard
+ * (API Keys page → Template Configuration → Copy JSON), which comes from
+ * templates.getConfig (templates router). Ensures configs "copied from
+ * the dashboard" work with the SDK and that runtime validation behaves correctly.
+ */
+export {};
+//# sourceMappingURL=dashboard-config.test.d.ts.map

package/dist/__tests__/dashboard-config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-config.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/dashboard-config.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/__tests__/dashboard-config.test.js

@@ -0,0 +1,182 @@
+/**
+ * Runtime tests for dashboard-shaped template configs.
+ *
+ * Config fixtures mirror the exact shape returned by the dashboard
+ * (API Keys page → Template Configuration → Copy JSON), which comes from
+ * templates.getConfig (templates router). Ensures configs "copied from
+ * the dashboard" work with the SDK and that runtime validation behaves correctly.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { Mailer } from '../index.js';
+global.fetch = vi.fn();
+describe('Dashboard config (runtime)', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    // Shape matches getConfig response: id, name, version, vars: Record<string, { required: boolean }>
+    const configOnlyRequired = {
+        welcome: {
+            id: 'version-uuid-1',
+            name: 'Welcome Email',
+            version: 1,
+            vars: {
+                firstName: { required: true },
+                lastName: { required: true },
+            },
+        },
+    };
+    const configMixedVars = {
+        'reset-password': {
+            id: 'version-uuid-2',
+            name: 'Reset Password',
+            version: 2,
+            vars: {
+                resetUrl: { required: true },
+                expiresIn: { required: false },
+            },
+        },
+    };
+    const configEmptyVars = {
+        notification: {
+            id: 'version-uuid-3',
+            name: 'Simple Notification',
+            version: 1,
+            vars: {},
+        },
+    };
+    it('sends with dashboard-shaped config (only required vars)', async () => {
+        const client = new Mailer({
+            workspaceId: 'ws-1',
+            apiKey: 'key-1',
+            baseUrl: 'https://api.test.com/api/v1',
+            templates: configOnlyRequired,
+            maxRetries: 1,
+            timeout: 5000,
+        });
+        const mockResponse = {
+            messageId: 'msg-1',
+            status: 'queued',
+            queuedAt: '2024-01-01T00:00:00Z',
+        };
+        global.fetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => mockResponse,
+        });
+        const result = await client.send({
+            to: 'user@example.com',
+            template: 'welcome',
+            variables: {
+                firstName: 'Jane',
+                lastName: 'Doe',
+            },
+        });
+        expect(result).toEqual(mockResponse);
+        expect(global.fetch).toHaveBeenCalledWith('https://api.test.com/api/v1/workspaces/ws-1/send', expect.objectContaining({
+            method: 'POST',
+            body: expect.stringContaining('"templateId":"version-uuid-1"'),
+        }));
+        const call = global.fetch.mock.calls[0];
+        const body = JSON.parse(call?.[1]?.body ?? '{}');
+        expect(body.variables).toEqual({ firstName: 'Jane', lastName: 'Doe' });
+    });
+    it('sends with dashboard-shaped config (mixed required/optional, hyphenated key)', async () => {
+        const client = new Mailer({
+            workspaceId: 'ws-2',
+            apiKey: 'key-2',
+            baseUrl: 'https://api.test.com/api/v1',
+            templates: configMixedVars,
+            maxRetries: 1,
+            timeout: 5000,
+        });
+        const mockResponse = {
+            messageId: 'msg-2',
+            status: 'queued',
+            queuedAt: '2024-01-01T00:00:00Z',
+        };
+        global.fetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => mockResponse,
+        });
+        const result = await client.send({
+            to: 'user@example.com',
+            template: 'reset-password',
+            variables: {
+                resetUrl: 'https://example.com/reset?token=abc',
+                expiresIn: '1 hour',
+            },
+        });
+        expect(result).toEqual(mockResponse);
+        const call = global.fetch.mock.calls[0];
+        const body = JSON.parse(call?.[1]?.body ?? '{}');
+        expect(body.templateId).toBe('version-uuid-2');
+        expect(body.variables).toEqual({
+            resetUrl: 'https://example.com/reset?token=abc',
+            expiresIn: '1 hour',
+        });
+    });
+    it('sends with template that has empty vars (dashboard shape)', async () => {
+        const client = new Mailer({
+            workspaceId: 'ws-3',
+            apiKey: 'key-3',
+            baseUrl: 'https://api.test.com/api/v1',
+            templates: configEmptyVars,
+            maxRetries: 1,
+            timeout: 5000,
+        });
+        const mockResponse = {
+            messageId: 'msg-3',
+            status: 'queued',
+            queuedAt: '2024-01-01T00:00:00Z',
+        };
+        global.fetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => mockResponse,
+        });
+        const result = await client.send({
+            to: 'user@example.com',
+            template: 'notification',
+            variables: {},
+        });
+        expect(result).toEqual(mockResponse);
+        const call = global.fetch.mock.calls[0];
+        const body = JSON.parse(call?.[1]?.body ?? '{}');
+        expect(body.templateId).toBe('version-uuid-3');
+        expect(body.variables).toEqual({});
+    });
+    it('throws when required variable is missing (dashboard config)', async () => {
+        const client = new Mailer({
+            workspaceId: 'ws-1',
+            apiKey: 'key-1',
+            baseUrl: 'https://api.test.com/api/v1',
+            templates: configOnlyRequired,
+            maxRetries: 1,
+            timeout: 5000,
+        });
+        await expect(client.send({
+            to: 'user@example.com',
+            template: 'welcome',
+            variables: {
+                firstName: 'Jane',
+                // lastName missing
+            },
+        })).rejects.toThrow('Missing required variables for template "welcome": lastName');
+    });
+    it('throws when template name is not in config (dashboard config)', async () => {
+        const client = new Mailer({
+            workspaceId: 'ws-1',
+            apiKey: 'key-1',
+            baseUrl: 'https://api.test.com/api/v1',
+            templates: configOnlyRequired,
+            maxRetries: 1,
+            timeout: 5000,
+        });
+        await expect(client.send({
+            to: 'user@example.com',
+            template: 'nonexistent',
+            variables: { firstName: 'J', lastName: 'D' },
+        })).rejects.toThrow('Template "nonexistent" not found in template config');
+    });
+});

package/dist/__tests__/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/__tests__/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/errors.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/errors.test.js

@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'vitest';
+import { MailerApiError } from '../errors.js';
+describe('MailerApiError', () => {
+    describe('constructor', () => {
+        it('should create error with status code', () => {
+            const error = new MailerApiError(400);
+            expect(error).toBeInstanceOf(Error);
+            expect(error).toBeInstanceOf(MailerApiError);
+            expect(error.status).toBe(400);
+            expect(error.message).toBe('API request failed with status 400');
+            expect(error.name).toBe('MailerApiError');
+        });
+        it('should create error with custom message', () => {
+            const error = new MailerApiError(400, 'INVALID_REQUEST', undefined, 'Invalid email address');
+            expect(error.status).toBe(400);
+            expect(error.code).toBe('INVALID_REQUEST');
+            expect(error.message).toBe('Invalid email address');
+        });
+        it('should create error with details', () => {
+            const details = { field: 'to', reason: 'Invalid email format' };
+            const error = new MailerApiError(400, 'VALIDATION_ERROR', details);
+            expect(error.status).toBe(400);
+            expect(error.code).toBe('VALIDATION_ERROR');
+            expect(error.details).toEqual(details);
+        });
+    });
+    describe('isClientError', () => {
+        it('should return true for 4xx errors', () => {
+            expect(new MailerApiError(400).isClientError()).toBe(true);
+            expect(new MailerApiError(401).isClientError()).toBe(true);
+            expect(new MailerApiError(404).isClientError()).toBe(true);
+            expect(new MailerApiError(429).isClientError()).toBe(true);
+            expect(new MailerApiError(499).isClientError()).toBe(true);
+        });
+        it('should return false for non-4xx errors', () => {
+            expect(new MailerApiError(200).isClientError()).toBe(false);
+            expect(new MailerApiError(399).isClientError()).toBe(false);
+            expect(new MailerApiError(500).isClientError()).toBe(false);
+        });
+    });
+    describe('isServerError', () => {
+        it('should return true for 5xx errors', () => {
+            expect(new MailerApiError(500).isServerError()).toBe(true);
+            expect(new MailerApiError(502).isServerError()).toBe(true);
+            expect(new MailerApiError(503).isServerError()).toBe(true);
+            expect(new MailerApiError(599).isServerError()).toBe(true);
+        });
+        it('should return false for non-5xx errors', () => {
+            expect(new MailerApiError(200).isServerError()).toBe(false);
+            expect(new MailerApiError(400).isServerError()).toBe(false);
+            expect(new MailerApiError(499).isServerError()).toBe(false);
+        });
+    });
+    describe('isRetryable', () => {
+        it('should return true for 429 rate limit', () => {
+            expect(new MailerApiError(429).isRetryable()).toBe(true);
+        });
+        it('should return true for 5xx errors', () => {
+            expect(new MailerApiError(500).isRetryable()).toBe(true);
+            expect(new MailerApiError(502).isRetryable()).toBe(true);
+            expect(new MailerApiError(503).isRetryable()).toBe(true);
+        });
+        it('should return false for other errors', () => {
+            expect(new MailerApiError(200).isRetryable()).toBe(false);
+            expect(new MailerApiError(400).isRetryable()).toBe(false);
+            expect(new MailerApiError(401).isRetryable()).toBe(false);
+            expect(new MailerApiError(404).isRetryable()).toBe(false);
+        });
+    });
+    describe('error prototype chain', () => {
+        it('should maintain correct prototype chain', () => {
+            const error = new MailerApiError(400);
+            expect(error instanceof Error).toBe(true);
+            expect(error instanceof MailerApiError).toBe(true);
+            expect(Object.getPrototypeOf(error)).toBe(MailerApiError.prototype);
+        });
+        it('should work with try-catch instanceof checks', () => {
+            try {
+                throw new MailerApiError(400, 'TEST_ERROR');
+            }
+            catch (error) {
+                expect(error instanceof MailerApiError).toBe(true);
+                expect(error instanceof Error).toBe(true);
+                if (error instanceof MailerApiError) {
+                    expect(error.code).toBe('TEST_ERROR');
+                }
+            }
+        });
+    });
+});

package/dist/__tests__/mailer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mailer.test.d.ts.map

package/dist/__tests__/mailer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailer.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/mailer.test.ts"],"names":[],"mappings":""}