@ewyn/client 0.1.0

package/dist/__tests__/mailer.test.js

@@ -0,0 +1,429 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { Mailer, MailerApiError } from '../index.js';
+// Mock fetch globally
+global.fetch = vi.fn();
+describe('Mailer SDK', () => {
+    let client;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        global.fetch.mockReset();
+        client = new Mailer({
+            workspaceId: 'test-workspace-id',
+            apiKey: 'test-api-key',
+            baseUrl: 'https://api.test.com/api/v1',
+            maxRetries: 2, // Allow 1 retry (attempt < maxRetries)
+            timeout: 5000,
+        });
+    });
+    describe('constructor', () => {
+        it('should create client with required options', () => {
+            expect(client).toBeInstanceOf(Mailer);
+        });
+        it('should use default base URL if not provided', () => {
+            const defaultClient = new Mailer({
+                workspaceId: 'test-workspace-id',
+                apiKey: 'test-api-key',
+            });
+            expect(defaultClient).toBeInstanceOf(Mailer);
+        });
+        it('should accept template config', () => {
+            const config = {
+                welcome: {
+                    id: 'version-uuid',
+                    name: 'Welcome',
+                    version: 1,
+                    vars: {
+                        firstName: { required: true },
+                    },
+                },
+            };
+            const configClient = new Mailer({
+                workspaceId: 'test-workspace-id',
+                apiKey: 'test-api-key',
+                templates: config,
+            });
+            expect(configClient).toBeInstanceOf(Mailer);
+        });
+    });
+    describe('send', () => {
+        it('should send email with template ID', async () => {
+            const mockResponse = {
+                messageId: 'msg-123',
+                status: 'queued',
+                queuedAt: '2024-01-01T00:00:00Z',
+            };
+            global.fetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => mockResponse,
+            });
+            const result = await client.send({
+                to: 'test@example.com',
+                templateId: 'template-uuid',
+                variables: {
+                    firstName: 'John',
+                },
+            });
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith('https://api.test.com/api/v1/workspaces/test-workspace-id/send', expect.objectContaining({
+                method: 'POST',
+                headers: expect.objectContaining({
+                    'Content-Type': 'application/json',
+                    'Authorization': 'Bearer test-api-key',
+                }),
+                body: JSON.stringify({
+                    to: 'test@example.com',
+                    templateId: 'template-uuid',
+                    variables: {
+                        firstName: 'John',
+                    },
+                }),
+            }));
+        });
+        it('should send email with template name when config provided', async () => {
+            const config = {
+                welcome: {
+                    id: 'version-uuid',
+                    name: 'Welcome',
+                    version: 1,
+                    vars: {
+                        firstName: { required: true },
+                    },
+                },
+            };
+            const configClient = new Mailer({
+                workspaceId: 'test-workspace-id',
+                apiKey: 'test-api-key',
+                templates: config,
+            });
+            const mockResponse = {
+                messageId: 'msg-123',
+                status: 'queued',
+                queuedAt: '2024-01-01T00:00:00Z',
+            };
+            global.fetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => mockResponse,
+            });
+            const result = await configClient.send({
+                to: 'test@example.com',
+                template: 'welcome',
+                variables: {
+                    firstName: 'John',
+                },
+            });
+            expect(result).toEqual(mockResponse);
+        });
+        it('should include version parameter if specified', async () => {
+            const mockResponse = {
+                messageId: 'msg-123',
+                status: 'queued',
+                queuedAt: '2024-01-01T00:00:00Z',
+            };
+            global.fetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => mockResponse,
+            });
+            await client.send({
+                to: 'test@example.com',
+                templateId: 'template-uuid',
+                version: 2,
+                variables: {
+                    firstName: 'John',
+                },
+            });
+            expect(global.fetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                body: expect.stringContaining('"version":2'),
+            }));
+        });
+        it('should include metadata if provided', async () => {
+            const mockResponse = {
+                messageId: 'msg-123',
+                status: 'queued',
+                queuedAt: '2024-01-01T00:00:00Z',
+            };
+            global.fetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => mockResponse,
+            });
+            await client.send({
+                to: 'test@example.com',
+                templateId: 'template-uuid',
+                metadata: {
+                    userId: 'user-123',
+                },
+            });
+            expect(global.fetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                body: expect.stringContaining('"metadata"'),
+            }));
+        });
+        it('should include idempotency key if provided', async () => {
+            const mockResponse = {
+                messageId: 'msg-123',
+                status: 'queued',
+                queuedAt: '2024-01-01T00:00:00Z',
+            };
+            global.fetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => mockResponse,
+            });
+            await client.send({
+                to: 'test@example.com',
+                templateId: 'template-uuid',
+                idempotencyKey: 'idempotency-key-123',
+            });
+            expect(global.fetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                body: expect.stringContaining('"idempotencyKey":"idempotency-key-123"'),
+            }));
+        });
+        it('should throw error if neither templateId nor template provided', async () => {
+            await expect(client.send({
+                to: 'test@example.com',
+                variables: {},
+            })).rejects.toThrow('Either templateId or template must be provided');
+        });
+        it('should throw error if template name provided without config', async () => {
+            await expect(client.send({
+                to: 'test@example.com',
+                template: 'welcome',
+                variables: {},
+            })).rejects.toThrow('Template name provided but no template config was provided');
+        });
+        it('should throw error if template not found in config', async () => {
+            const config = {
+                welcome: {
+                    id: 'version-uuid',
+                    name: 'Welcome',
+                    version: 1,
+                    vars: {},
+                },
+            };
+            const configClient = new Mailer({
+                workspaceId: 'test-workspace-id',
+                apiKey: 'test-api-key',
+                templates: config,
+            });
+            await expect(configClient.send({
+                to: 'test@example.com',
+                template: 'nonexistent',
+                variables: {},
+            })).rejects.toThrow('Template "nonexistent" not found in template config');
+        });
+    });
+    describe('variable validation', () => {
+        it('should validate required variables', async () => {
+            const config = {
+                welcome: {
+                    id: 'version-uuid',
+                    name: 'Welcome',
+                    version: 1,
+                    vars: {
+                        firstName: { required: true },
+                        lastName: { required: true },
+                    },
+                },
+            };
+            const configClient = new Mailer({
+                workspaceId: 'test-workspace-id',
+                apiKey: 'test-api-key',
+                templates: config,
+            });
+            await expect(configClient.send({
+                to: 'test@example.com',
+                template: 'welcome',
+                variables: {
+                    firstName: 'John',
+                    // lastName missing
+                },
+            })).rejects.toThrow('Missing required variables for template "welcome": lastName');
+        });
+        it('should allow optional variables to be omitted', async () => {
+            const config = {
+                welcome: {
+                    id: 'version-uuid',
+                    name: 'Welcome',
+                    version: 1,
+                    vars: {
+                        firstName: { required: true },
+                        lastName: { required: false },
+                    },
+                },
+            };
+            const configClient = new Mailer({
+                workspaceId: 'test-workspace-id',
+                apiKey: 'test-api-key',
+                templates: config,
+            });
+            const mockResponse = {
+                messageId: 'msg-123',
+                status: 'queued',
+                queuedAt: '2024-01-01T00:00:00Z',
+            };
+            global.fetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => mockResponse,
+            });
+            const result = await configClient.send({
+                to: 'test@example.com',
+                template: 'welcome',
+                variables: {
+                    firstName: 'John',
+                    // lastName omitted (optional)
+                },
+            });
+            expect(result).toEqual(mockResponse);
+        });
+    });
+    describe('error handling', () => {
+        it('should throw MailerApiError on 400 error', async () => {
+            const mock400Response = {
+                ok: false,
+                status: 400,
+                json: async () => ({
+                    error: 'Bad request',
+                    code: 'INVALID_REQUEST',
+                    details: { field: 'to' },
+                }),
+            };
+            global.fetch
+                .mockResolvedValueOnce(mock400Response)
+                .mockResolvedValueOnce(mock400Response);
+            await expect(client.send({
+                to: 'test@example.com',
+                templateId: 'template-uuid',
+            })).rejects.toThrow(MailerApiError);
+            try {
+                await client.send({
+                    to: 'test@example.com',
+                    templateId: 'template-uuid',
+                });
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(MailerApiError);
+                expect(error.status).toBe(400);
+                expect(error.code).toBe('INVALID_REQUEST');
+                expect(error.isClientError()).toBe(true);
+                expect(error.isServerError()).toBe(false);
+                expect(error.isRetryable()).toBe(false);
+            }
+        });
+        it('should throw MailerApiError on 429 rate limit', async () => {
+            global.fetch.mockResolvedValue({
+                ok: false,
+                status: 429,
+                json: async () => ({
+                    error: 'Too many requests',
+                    code: 'RATE_LIMITED',
+                }),
+            });
+            try {
+                await client.send({
+                    to: 'test@example.com',
+                    templateId: 'template-uuid',
+                });
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(MailerApiError);
+                expect(error.status).toBe(429);
+                expect(error.isRetryable()).toBe(true);
+            }
+            // Should have retried once (maxRetries: 1)
+            expect(global.fetch).toHaveBeenCalledTimes(2);
+        });
+        it('should throw MailerApiError on 500 server error', async () => {
+            global.fetch.mockResolvedValue({
+                ok: false,
+                status: 500,
+                json: async () => ({
+                    error: 'Internal server error',
+                }),
+            });
+            try {
+                await client.send({
+                    to: 'test@example.com',
+                    templateId: 'template-uuid',
+                });
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(MailerApiError);
+                expect(error.status).toBe(500);
+                expect(error.isServerError()).toBe(true);
+                expect(error.isRetryable()).toBe(true);
+            }
+            // Should have retried once
+            expect(global.fetch).toHaveBeenCalledTimes(2);
+        });
+        it('should handle network errors', async () => {
+            global.fetch.mockRejectedValue(new Error('Network error'));
+            await expect(client.send({
+                to: 'test@example.com',
+                templateId: 'template-uuid',
+            })).rejects.toThrow('Network error');
+            // Should have retried once
+            expect(global.fetch).toHaveBeenCalledTimes(2);
+        });
+        it('should handle timeout errors', async () => {
+            const abortError = new Error('The operation was aborted');
+            abortError.name = 'AbortError';
+            global.fetch.mockRejectedValueOnce(abortError);
+            try {
+                await client.send({
+                    to: 'test@example.com',
+                    templateId: 'template-uuid',
+                });
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(MailerApiError);
+                expect(error.status).toBe(408);
+                expect(error.code).toBe('TIMEOUT');
+            }
+        });
+    });
+    describe('retry logic', () => {
+        it('should retry on 5xx errors with exponential backoff', async () => {
+            const startTime = Date.now();
+            global.fetch
+                .mockResolvedValueOnce({
+                ok: false,
+                status: 500,
+                json: async () => ({ error: 'Server error' }),
+            })
+                .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    messageId: 'msg-123',
+                    status: 'queued',
+                    queuedAt: '2024-01-01T00:00:00Z',
+                }),
+            });
+            const result = await client.send({
+                to: 'test@example.com',
+                templateId: 'template-uuid',
+            });
+            const duration = Date.now() - startTime;
+            expect(result.messageId).toBe('msg-123');
+            expect(global.fetch).toHaveBeenCalledTimes(2);
+            // Should have waited ~1 second between attempts
+            expect(duration).toBeGreaterThanOrEqual(950);
+        });
+        it('should not retry on 4xx client errors', async () => {
+            global.fetch.mockResolvedValueOnce({
+                ok: false,
+                status: 404,
+                json: async () => ({ error: 'Not found' }),
+            });
+            await expect(client.send({
+                to: 'test@example.com',
+                templateId: 'template-uuid',
+            })).rejects.toThrow(MailerApiError);
+            // Should not retry
+            expect(global.fetch).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * API Error class for handling HTTP errors from the Mailer API
+ */
+export declare class MailerApiError extends Error {
+    status: number;
+    code?: string | undefined;
+    details?: unknown | undefined;
+    constructor(status: number, code?: string | undefined, details?: unknown | undefined, message?: string);
+    /**
+     * Check if the error is a client error (4xx)
+     */
+    isClientError(): boolean;
+    /**
+     * Check if the error is a server error (5xx)
+     */
+    isServerError(): boolean;
+    /**
+     * Check if the error is retryable (5xx or 429)
+     */
+    isRetryable(): boolean;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IAE9B,MAAM,EAAE,MAAM;IACd,IAAI,CAAC,EAAE,MAAM;IACb,OAAO,CAAC,EAAE,OAAO;gBAFjB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,OAAO,CAAC,EAAE,OAAO,YAAA,EACxB,OAAO,CAAC,EAAE,MAAM;IAOlB;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,WAAW,IAAI,OAAO;CAGvB"}

package/dist/errors.js

@@ -0,0 +1,34 @@
+/**
+ * API Error class for handling HTTP errors from the Mailer API
+ */
+export class MailerApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, details, message) {
+        super(message || `API request failed with status ${status}`);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = 'MailerApiError';
+        Object.setPrototypeOf(this, MailerApiError.prototype);
+    }
+    /**
+     * Check if the error is a client error (4xx)
+     */
+    isClientError() {
+        return this.status >= 400 && this.status < 500;
+    }
+    /**
+     * Check if the error is a server error (5xx)
+     */
+    isServerError() {
+        return this.status >= 500;
+    }
+    /**
+     * Check if the error is retryable (5xx or 429)
+     */
+    isRetryable() {
+        return this.status === 429 || this.isServerError();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import type { MailerOptions, MailerOptionsTyped, SendEmailOptions, SendEmailOptionsTyped, SendEmailResponse, TemplateConfig } from './types.js';
+/**
+ * Mailer SDK Client
+ *
+ * @example Basic usage without template config
+ * ```ts
+ * const client = new Mailer({
+ *   workspaceId: 'your-workspace-id',
+ *   apiKey: 'your-api-key',
+ * });
+ *
+ * await client.send({
+ *   to: 'user@example.com',
+ *   templateId: 'version-uuid',
+ *   variables: { firstName: 'John' }
+ * });
+ * ```
+ *
+ * @example Type-safe usage with template config
+ * ```ts
+ * const config = {
+ *   welcome: {
+ *     id: 'version-uuid',
+ *     name: 'Welcome Email',
+ *     version: 1,
+ *     vars: {
+ *       firstName: { required: true },
+ *       plan: { required: false }
+ *     }
+ *   }
+ * } as const;
+ *
+ * const client = new Mailer({
+ *   workspaceId: 'your-workspace-id',
+ *   apiKey: 'your-api-key',
+ *   templates: config
+ * });
+ *
+ * // Type-safe sending
+ * await client.send({
+ *   to: 'user@example.com',
+ *   template: 'welcome',  // Autocomplete available
+ *   variables: {
+ *     firstName: 'John'    // TypeScript enforces required vars
+ *   }
+ * });
+ * ```
+ */
+export declare class Mailer<TConfig extends TemplateConfig = TemplateConfig> {
+    private readonly workspaceId;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly templates?;
+    private readonly maxRetries;
+    private readonly timeout;
+    constructor(options: MailerOptions | MailerOptionsTyped<TConfig>);
+    /**
+     * Send an email using a template
+     *
+     * @param options - Email sending options
+     * @returns Promise resolving to the send response
+     * @throws {MailerApiError} If the API request fails
+     *
+     * @example With template ID
+     * ```ts
+     * await client.send({
+     *   to: 'user@example.com',
+     *   templateId: 'version-uuid',
+     *   variables: { firstName: 'John' }
+     * });
+     * ```
+     *
+     * @example With template name (requires config)
+     * ```ts
+     * await client.send({
+     *   to: 'user@example.com',
+     *   template: 'welcome',
+     *   version: 2,  // Optional: defaults to latest
+     *   variables: { firstName: 'John' }
+     * });
+     * ```
+     */
+    send(options: TConfig extends TemplateConfig ? SendEmailOptionsTyped<TConfig> | SendEmailOptions : SendEmailOptions): Promise<SendEmailResponse>;
+    /**
+     * Resolve template ID from either templateId or template name
+     */
+    private resolveTemplateId;
+    /**
+     * Validate that all required variables are provided
+     */
+    private validateVariables;
+    /**
+     * Make HTTP request with retry logic
+     */
+    private requestWithRetry;
+}
+export { MailerApiError } from './errors.js';
+export type { MailerOptions, MailerOptionsTyped, SendEmailOptions, SendEmailOptionsBase, SendEmailOptionsTyped, SendEmailResponse, TemplateConfig, TemplateConfigEntry, TemplateVariable } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,MAAM,CAAC,OAAO,SAAS,cAAc,GAAG,cAAc;IACjE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,aAAa,GAAG,kBAAkB,CAAC,OAAO,CAAC;IAShE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,IAAI,CACR,OAAO,EAAE,OAAO,SAAS,cAAc,GACnC,qBAAqB,CAAC,OAAO,CAAC,GAAG,gBAAgB,GACjD,gBAAgB,GACnB,OAAO,CAAC,iBAAiB,CAAC;IA8C7B;;OAEG;YACW,iBAAiB;IAyB/B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;OAEG;YACW,gBAAgB;CAuE/B;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,YAAY,CAAC"}