@ewyn/client 0.1.0

package/dist/index.js

@@ -0,0 +1,211 @@
+import { MailerApiError } from './errors.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 class Mailer {
+    workspaceId;
+    apiKey;
+    baseUrl;
+    templates;
+    maxRetries;
+    timeout;
+    constructor(options) {
+        this.workspaceId = options.workspaceId;
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl || 'https://www.ewyn.ai/api/v1';
+        this.templates = options.templates;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.timeout = options.timeout ?? 30000;
+    }
+    /**
+     * 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' }
+     * });
+     * ```
+     */
+    async send(options) {
+        // Validate and resolve template
+        const templateId = await this.resolveTemplateId(options);
+        // Validate variables if template config is provided
+        if (this.templates && options.template) {
+            this.validateVariables(options.template, options.variables || {});
+        }
+        // Build request body
+        const body = {
+            to: options.to,
+            templateId,
+        };
+        if (options.variables) {
+            body.variables = options.variables;
+        }
+        if (options.metadata) {
+            body.metadata = options.metadata;
+        }
+        if (options.idempotencyKey) {
+            body.idempotencyKey = options.idempotencyKey;
+        }
+        // Add version if specified
+        if ('version' in options && options.version !== undefined) {
+            body.version = options.version;
+        }
+        // Make request with retries
+        return this.requestWithRetry(`/workspaces/${this.workspaceId}/send`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    /**
+     * Resolve template ID from either templateId or template name
+     */
+    async resolveTemplateId(options) {
+        if (options.templateId) {
+            return options.templateId;
+        }
+        if (options.template) {
+            if (!this.templates) {
+                throw new Error('Template name provided but no template config was provided to the client');
+            }
+            const template = this.templates[options.template];
+            if (!template) {
+                throw new Error(`Template "${options.template}" not found in template config`);
+            }
+            return template.id;
+        }
+        throw new Error('Either templateId or template must be provided');
+    }
+    /**
+     * Validate that all required variables are provided
+     */
+    validateVariables(templateName, variables) {
+        if (!this.templates) {
+            return;
+        }
+        const template = this.templates[templateName];
+        if (!template) {
+            return;
+        }
+        const missing = [];
+        for (const [varName, varDef] of Object.entries(template.vars)) {
+            if (varDef?.required && !(varName in variables)) {
+                missing.push(varName);
+            }
+        }
+        if (missing.length > 0) {
+            throw new Error(`Missing required variables for template "${templateName}": ${missing.join(', ')}`);
+        }
+    }
+    /**
+     * Make HTTP request with retry logic
+     */
+    async requestWithRetry(path, init, attempt = 1) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(url, {
+                ...init,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            const data = await response.json().catch(() => ({}));
+            if (!response.ok) {
+                const error = new MailerApiError(response.status, data.code, data.details || data, data.error || data.message);
+                // Retry on retryable errors
+                if (error.isRetryable() && attempt < this.maxRetries) {
+                    // Exponential backoff: 1s, 2s, 4s
+                    const delay = Math.pow(2, attempt - 1) * 1000;
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    return this.requestWithRetry(path, init, attempt + 1);
+                }
+                throw error;
+            }
+            return data;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof MailerApiError) {
+                throw error;
+            }
+            // Handle network errors or timeouts
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new MailerApiError(408, 'TIMEOUT', undefined, `Request timed out after ${this.timeout}ms`);
+            }
+            // Retry on network errors if we have attempts left
+            if (attempt < this.maxRetries) {
+                const delay = Math.pow(2, attempt - 1) * 1000;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                return this.requestWithRetry(path, init, attempt + 1);
+            }
+            throw new MailerApiError(500, 'NETWORK_ERROR', undefined, error instanceof Error ? error.message : 'Unknown network error');
+        }
+    }
+}
+export { MailerApiError } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Template variable definition
+ */
+export interface TemplateVariable {
+    required: boolean;
+}
+/**
+ * Template configuration entry
+ */
+export interface TemplateConfigEntry {
+    /** Template version ID (UUID) - used for sending */
+    id: string;
+    /** Human-readable template name */
+    name: string;
+    /** Major version number */
+    version: number;
+    /** Variable definitions */
+    vars: Record<string, TemplateVariable>;
+}
+/**
+ * Template configuration object
+ * Maps template names to their configuration
+ */
+export type TemplateConfig = Record<string, TemplateConfigEntry>;
+/**
+ * Extract required variable names from a template config entry
+ */
+type RequiredVars<T extends TemplateConfigEntry> = {
+    [K in keyof T['vars']]: T['vars'][K] extends {
+        required: true;
+    } ? K : never;
+}[keyof T['vars']];
+/**
+ * Extract optional variable names from a template config entry
+ */
+type OptionalVars<T extends TemplateConfigEntry> = {
+    [K in keyof T['vars']]: T['vars'][K] extends {
+        required: false;
+    } ? K : never;
+}[keyof T['vars']];
+/**
+ * Build a variables object type from template config
+ */
+type VariablesFromConfig<T extends TemplateConfigEntry> = RequiredVars<T> extends never ? {
+    [K in OptionalVars<T>]?: string;
+} : {
+    [K in RequiredVars<T>]: string;
+} & {
+    [K in OptionalVars<T>]?: string;
+};
+/**
+ * Options for sending an email without template config
+ */
+export interface SendEmailOptionsBase {
+    /** Recipient email address */
+    to: string;
+    /** Template version ID (UUID) - required if template not provided */
+    templateId?: string;
+    /** Template name (requires template config to be provided) */
+    template?: string;
+    /** Major version number (use with template name) */
+    version?: number;
+    /** Variables to substitute in the template */
+    variables?: Record<string, string>;
+    /** Additional metadata to attach to the message */
+    metadata?: Record<string, unknown>;
+    /** Idempotency key to prevent duplicate sends */
+    idempotencyKey?: string;
+}
+/**
+ * Type-safe options when using template config
+ */
+export type SendEmailOptionsTyped<TConfig extends TemplateConfig, TName extends keyof TConfig = keyof TConfig> = {
+    /** Recipient email address */
+    to: string;
+    /** Template name from config */
+    template: TName;
+    /** Major version number (optional, defaults to latest) */
+    version?: TConfig[TName]['version'];
+    /** Type-safe variables based on template config */
+    variables: VariablesFromConfig<TConfig[TName]>;
+    /** Additional metadata to attach to the message */
+    metadata?: Record<string, unknown>;
+    /** Idempotency key to prevent duplicate sends */
+    idempotencyKey?: string;
+};
+/**
+ * Options for sending an email (generic version)
+ */
+export type SendEmailOptions = SendEmailOptionsBase;
+/**
+ * Response from sending an email
+ */
+export interface SendEmailResponse {
+    messageId: string;
+    status: 'queued';
+    queuedAt: string;
+}
+/**
+ * Configuration options for the Mailer client (base)
+ */
+export interface MailerOptionsBase {
+    /** Workspace ID (UUID) */
+    workspaceId: string;
+    /** API key secret */
+    apiKey: string;
+    /** Base URL for the API (defaults to production) */
+    baseUrl?: string;
+    /** Maximum number of retries for retryable errors (default: 3) */
+    maxRetries?: number;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Configuration options with typed template config
+ */
+export type MailerOptionsTyped<TConfig extends TemplateConfig> = MailerOptionsBase & {
+    /** Template configuration for type-safe sending */
+    templates: TConfig;
+};
+/**
+ * Configuration options for the Mailer client (generic version)
+ */
+export type MailerOptions = MailerOptionsBase & {
+    /** Template configuration for name-based sending and validation */
+    templates?: TemplateConfig;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ewyn/client",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for Ewyn email service with full type safety",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "ewyn",
+    "email",
+    "sdk"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "prepublishOnly": "pnpm build",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@workspace/eslint-config": "workspace:*",
+    "@workspace/typescript-config": "workspace:*",
+    "typescript": "^5.7.3",
+    "vitest": "^1.2.0"
+  }
+}