@ewyn/client 0.1.0 → 0.3.0

package/README.md

@@ -22,12 +22,11 @@ yarn add @ewyn/client
 ### Basic Usage
 
 ```typescript
-import { Mailer } from '@ewyn/client';
+import { Ewyn } from '@ewyn/client';
 
-const client = new Mailer({
+const client = new Ewyn({
   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
@@ -46,7 +45,7 @@ await client.send({
 Get full TypeScript autocomplete and validation by copying your template config from the dashboard:
 
 ```typescript
-import { Mailer } from '@ewyn/client';
+import { Ewyn } from '@ewyn/client';
 
 // 1. Copy template config from dashboard (API Keys page)
 const config = {
@@ -71,7 +70,7 @@ const config = {
 } as const; // ← Important: use 'as const'
 
 // 2. Initialize with config
-const client = new Mailer({
+const client = new Ewyn({
   workspaceId: 'your-workspace-id',
   apiKey: 'your-api-key',
   templates: config,
@@ -91,7 +90,58 @@ await client.send({
 
 ## Getting Your Template Configuration
 
-### From Dashboard (Recommended)
+You can get your template config in three ways:
+
+1. **CLI (recommended)** – Run `npx @ewyn/client fetch-config` to download config and generate `ewynTemplates.ts` (see [Fetching template config (CLI)](#fetching-template-config-cli)).
+2. **Dashboard** – Copy JSON from the API Keys page.
+3. **API** – Call the templates config endpoint with curl or your own code.
+
+### Fetching template config (CLI)
+
+The easiest way to keep your template config in sync is to use the built-in CLI. From your project root (where you have an `ewyn.config.ts` or `ewyn.config.js`), run:
+
+```bash
+npx @ewyn/client fetch-config
+```
+
+This fetches your workspace’s template config from the API and writes a TypeScript file (e.g. `ewynTemplates.ts`) that you can import for type-safe sending.
+
+**Config file** (`ewyn.config.ts` in project root):
+
+- `workspaceId` (required): Your workspace UUID (e.g. `process.env.EWYN_WORKSPACE_ID`)
+- `apiKey` (required): Your API key (e.g. `process.env.EWYN_API_KEY`)
+- `configurationPath` (optional): Where to write the generated file (e.g. `./src/ewynTemplates.ts`). If omitted, the file is written as `./ewynTemplates.ts` in the current directory.
+
+Example `ewyn.config.ts`:
+
+```typescript
+import type { EwynFetchConfig } from '@ewyn/client';
+
+const config: EwynFetchConfig = {
+  workspaceId: process.env.EWYN_WORKSPACE_ID!,
+  apiKey: process.env.EWYN_API_KEY!,
+  configurationPath: './src/ewynTemplates.ts',  // optional
+};
+
+export default config;
+```
+
+After running `fetch-config`, import the generated config and pass it to the client:
+
+```typescript
+import { Ewyn } from '@ewyn/client';
+import { ewynTemplates } from './ewynTemplates';  // or from your configurationPath
+
+const client = new Ewyn({
+  workspaceId: process.env.EWYN_WORKSPACE_ID!,
+  apiKey: process.env.EWYN_API_KEY!,
+  templates: ewynTemplates,
+});
+```
+
+**Note:** Regenerate the config after creating or updating templates (re-run `npx @ewyn/client fetch-config`).
+
+### From Dashboard
 
 1. Go to your dashboard → **API Keys** page
 2. Scroll to **Template Configuration** section
@@ -103,7 +153,7 @@ const config = {
   // ... paste here
 } as const;
 
-const client = new Mailer({
+const client = new Ewyn({
   workspaceId: 'your-workspace-id',
   apiKey: 'your-api-key',
   templates: config, // Now fully type-safe!
@@ -119,23 +169,20 @@ curl -X GET https://www.ewyn.ai/api/v1/workspaces/YOUR_WORKSPACE_ID/templates/co
   -H "Authorization: Bearer YOUR_API_KEY"
 ```
 
-**Note:** Regenerate the config after creating or updating templates to keep it in sync.
-
 ## API Reference
 
-### `Mailer` Class
+### `Ewyn` Class
 
 #### Constructor
 
 ```typescript
-new Mailer(options: MailerOptions)
+new Ewyn(options: EwynOptions)
 ```
 
 **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)
@@ -168,20 +215,20 @@ Send an email using a template.
 
 **Throws:**
 
-- `MailerApiError`: If the API request fails
+- `EwynApiError`: If the API request fails
 - `Error`: If validation fails (missing template, missing variables, etc.)
 
 ### Error Handling
 
-The SDK throws `MailerApiError` for API errors:
+The SDK throws `EwynApiError` for API errors:
 
 ```typescript
-import { Mailer, MailerApiError } from '@ewyn/client';
+import { Ewyn, EwynApiError } from '@ewyn/client';
 
 try {
   await client.send({ /* ... */ });
 } catch (error) {
-  if (error instanceof MailerApiError) {
+  if (error instanceof EwynApiError) {
     console.error('API Error:', error.status, error.message);
     console.error('Details:', error.details);
     
@@ -235,6 +282,7 @@ 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
+- [ewyn.config example](./examples/ewyn.config.example.ts) - Example config for `fetch-config` CLI
 - [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

package/dist/__tests__/cli-fetch-config.test.d.ts

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

package/dist/__tests__/cli-fetch-config.test.d.ts.map

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

package/dist/__tests__/cli-fetch-config.test.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { runFetchConfig } from '../cli.js';
+const MOCK_TEMPLATES = {
+    welcome: {
+        id: 'version-uuid-1',
+        name: 'Welcome Email',
+        version: 1,
+        vars: {
+            firstName: { required: true },
+            lastName: { required: false },
+        },
+    },
+};
+describe('fetch-config CLI', () => {
+    let tempDir;
+    let originalFetch;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ewyn-cli-test-'));
+        originalFetch = globalThis.fetch;
+        globalThis.fetch = vi.fn().mockResolvedValue({
+            ok: true,
+            json: async () => ({ templates: MOCK_TEMPLATES }),
+            text: async () => '',
+        });
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        vi.restoreAllMocks();
+        try {
+            fs.rmSync(tempDir, { recursive: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+    it('writes ewynTemplates.ts with fetched config when using default path', async () => {
+        const configPath = path.join(tempDir, 'ewyn.config.js');
+        fs.writeFileSync(configPath, `export default {
+  workspaceId: 'test-workspace-id',
+  apiKey: 'test-api-key',
+};
+`, 'utf-8');
+        await runFetchConfig(tempDir);
+        const outputPath = path.join(tempDir, 'ewynTemplates.ts');
+        expect(fs.existsSync(outputPath)).toBe(true);
+        const content = fs.readFileSync(outputPath, 'utf-8');
+        expect(content).toContain('// Generated by @ewyn/client fetch-config');
+        expect(content).toContain('export const ewynTemplates = ');
+        expect(content).toContain('"welcome"');
+        expect(content).toContain('"version-uuid-1"');
+        expect(content).toContain(' as const;');
+    });
+    it('writes to configurationPath when set in config', async () => {
+        const configPath = path.join(tempDir, 'ewyn.config.js');
+        fs.writeFileSync(configPath, `export default {
+  workspaceId: 'ws-1',
+  apiKey: 'key-1',
+  configurationPath: './src/ewynTemplates.ts',
+};
+`, 'utf-8');
+        await runFetchConfig(tempDir);
+        const outputPath = path.join(tempDir, 'src', 'ewynTemplates.ts');
+        expect(fs.existsSync(outputPath)).toBe(true);
+        const content = fs.readFileSync(outputPath, 'utf-8');
+        expect(content).toContain('"welcome"');
+    });
+});

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

@@ -7,7 +7,7 @@
  * variables at compile time.
  */
 import { expectTypeOf, test } from 'vitest';
-import { Mailer } from '../index.js';
+import { Ewyn } from '../index.js';
 // Dashboard-shaped config: same structure as getConfig response (id, name, version, vars)
 const dashboardConfig = {
     welcome: {
@@ -29,7 +29,7 @@ const dashboardConfig = {
     },
 };
 test('client with dashboard config has typed send', () => {
-    const client = new Mailer({
+    const client = new Ewyn({
         workspaceId: 'ws',
         apiKey: 'key',
         templates: dashboardConfig,
@@ -38,7 +38,7 @@ test('client with dashboard config has typed send', () => {
     expectTypeOf(client.send).toBeFunction();
 });
 test('valid send: required var present, optional omitted', () => {
-    const client = new Mailer({
+    const client = new Ewyn({
         workspaceId: 'ws',
         apiKey: 'key',
         templates: dashboardConfig,
@@ -50,7 +50,7 @@ test('valid send: required var present, optional omitted', () => {
     }).toMatchTypeOf();
 });
 test('valid send: required and optional vars', () => {
-    const client = new Mailer({
+    const client = new Ewyn({
         workspaceId: 'ws',
         apiKey: 'key',
         templates: dashboardConfig,
@@ -62,7 +62,7 @@ test('valid send: required and optional vars', () => {
     }).toMatchTypeOf();
 });
 test('valid send: hyphenated template name', () => {
-    const client = new Mailer({
+    const client = new Ewyn({
         workspaceId: 'ws',
         apiKey: 'key',
         templates: dashboardConfig,
@@ -74,7 +74,7 @@ test('valid send: hyphenated template name', () => {
     }).toMatchTypeOf();
 });
 test('send return type is Promise<SendEmailResponse>', () => {
-    const client = new Mailer({
+    const client = new Ewyn({
         workspaceId: 'ws',
         apiKey: 'key',
         templates: dashboardConfig,
@@ -86,7 +86,7 @@ test('template name is constrained to config keys at type level', () => {
     expectTypeOf().toMatchTypeOf();
 });
 test('missing required variable is rejected by types', () => {
-    const client = new Mailer({
+    const client = new Ewyn({
         workspaceId: 'ws',
         apiKey: 'key',
         templates: dashboardConfig,

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

@@ -7,7 +7,7 @@
  * 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';
+import { Ewyn } from '../index.js';
 global.fetch = vi.fn();
 describe('Dashboard config (runtime)', () => {
     beforeEach(() => {
@@ -45,10 +45,9 @@ describe('Dashboard config (runtime)', () => {
         },
     };
     it('sends with dashboard-shaped config (only required vars)', async () => {
-        const client = new Mailer({
+        const client = new Ewyn({
             workspaceId: 'ws-1',
             apiKey: 'key-1',
-            baseUrl: 'https://api.test.com/api/v1',
             templates: configOnlyRequired,
             maxRetries: 1,
             timeout: 5000,
@@ -72,7 +71,7 @@ describe('Dashboard config (runtime)', () => {
             },
         });
         expect(result).toEqual(mockResponse);
-        expect(global.fetch).toHaveBeenCalledWith('https://api.test.com/api/v1/workspaces/ws-1/send', expect.objectContaining({
+        expect(global.fetch).toHaveBeenCalledWith('https://www.ewyn.ai/api/v1/workspaces/ws-1/send', expect.objectContaining({
             method: 'POST',
             body: expect.stringContaining('"templateId":"version-uuid-1"'),
         }));
@@ -81,10 +80,9 @@ describe('Dashboard config (runtime)', () => {
         expect(body.variables).toEqual({ firstName: 'Jane', lastName: 'Doe' });
     });
     it('sends with dashboard-shaped config (mixed required/optional, hyphenated key)', async () => {
-        const client = new Mailer({
+        const client = new Ewyn({
             workspaceId: 'ws-2',
             apiKey: 'key-2',
-            baseUrl: 'https://api.test.com/api/v1',
             templates: configMixedVars,
             maxRetries: 1,
             timeout: 5000,
@@ -117,10 +115,9 @@ describe('Dashboard config (runtime)', () => {
         });
     });
     it('sends with template that has empty vars (dashboard shape)', async () => {
-        const client = new Mailer({
+        const client = new Ewyn({
             workspaceId: 'ws-3',
             apiKey: 'key-3',
-            baseUrl: 'https://api.test.com/api/v1',
             templates: configEmptyVars,
             maxRetries: 1,
             timeout: 5000,
@@ -147,10 +144,9 @@ describe('Dashboard config (runtime)', () => {
         expect(body.variables).toEqual({});
     });
     it('throws when required variable is missing (dashboard config)', async () => {
-        const client = new Mailer({
+        const client = new Ewyn({
             workspaceId: 'ws-1',
             apiKey: 'key-1',
-            baseUrl: 'https://api.test.com/api/v1',
             templates: configOnlyRequired,
             maxRetries: 1,
             timeout: 5000,
@@ -165,10 +161,9 @@ describe('Dashboard config (runtime)', () => {
         })).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({
+        const client = new Ewyn({
             workspaceId: 'ws-1',
             apiKey: 'key-1',
-            baseUrl: 'https://api.test.com/api/v1',
             templates: configOnlyRequired,
             maxRetries: 1,
             timeout: 5000,

package/dist/__tests__/errors.test.js

@@ -1,24 +1,24 @@
-import { describe, it, expect } from 'vitest';
-import { MailerApiError } from '../errors.js';
-describe('MailerApiError', () => {
+import { describe, expect, it } from 'vitest';
+import { EwynApiError } from '../errors.js';
+describe('EwynApiError', () => {
     describe('constructor', () => {
         it('should create error with status code', () => {
-            const error = new MailerApiError(400);
+            const error = new EwynApiError(400);
             expect(error).toBeInstanceOf(Error);
-            expect(error).toBeInstanceOf(MailerApiError);
+            expect(error).toBeInstanceOf(EwynApiError);
             expect(error.status).toBe(400);
             expect(error.message).toBe('API request failed with status 400');
-            expect(error.name).toBe('MailerApiError');
+            expect(error.name).toBe('EwynApiError');
         });
         it('should create error with custom message', () => {
-            const error = new MailerApiError(400, 'INVALID_REQUEST', undefined, 'Invalid email address');
+            const error = new EwynApiError(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);
+            const error = new EwynApiError(400, 'VALIDATION_ERROR', details);
             expect(error.status).toBe(400);
             expect(error.code).toBe('VALIDATION_ERROR');
             expect(error.details).toEqual(details);
@@ -26,62 +26,62 @@ describe('MailerApiError', () => {
     });
     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);
+            expect(new EwynApiError(400).isClientError()).toBe(true);
+            expect(new EwynApiError(401).isClientError()).toBe(true);
+            expect(new EwynApiError(404).isClientError()).toBe(true);
+            expect(new EwynApiError(429).isClientError()).toBe(true);
+            expect(new EwynApiError(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);
+            expect(new EwynApiError(200).isClientError()).toBe(false);
+            expect(new EwynApiError(399).isClientError()).toBe(false);
+            expect(new EwynApiError(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);
+            expect(new EwynApiError(500).isServerError()).toBe(true);
+            expect(new EwynApiError(502).isServerError()).toBe(true);
+            expect(new EwynApiError(503).isServerError()).toBe(true);
+            expect(new EwynApiError(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);
+            expect(new EwynApiError(200).isServerError()).toBe(false);
+            expect(new EwynApiError(400).isServerError()).toBe(false);
+            expect(new EwynApiError(499).isServerError()).toBe(false);
         });
     });
     describe('isRetryable', () => {
         it('should return true for 429 rate limit', () => {
-            expect(new MailerApiError(429).isRetryable()).toBe(true);
+            expect(new EwynApiError(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);
+            expect(new EwynApiError(500).isRetryable()).toBe(true);
+            expect(new EwynApiError(502).isRetryable()).toBe(true);
+            expect(new EwynApiError(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);
+            expect(new EwynApiError(200).isRetryable()).toBe(false);
+            expect(new EwynApiError(400).isRetryable()).toBe(false);
+            expect(new EwynApiError(401).isRetryable()).toBe(false);
+            expect(new EwynApiError(404).isRetryable()).toBe(false);
         });
     });
     describe('error prototype chain', () => {
         it('should maintain correct prototype chain', () => {
-            const error = new MailerApiError(400);
+            const error = new EwynApiError(400);
             expect(error instanceof Error).toBe(true);
-            expect(error instanceof MailerApiError).toBe(true);
-            expect(Object.getPrototypeOf(error)).toBe(MailerApiError.prototype);
+            expect(error instanceof EwynApiError).toBe(true);
+            expect(Object.getPrototypeOf(error)).toBe(EwynApiError.prototype);
         });
         it('should work with try-catch instanceof checks', () => {
             try {
-                throw new MailerApiError(400, 'TEST_ERROR');
+                throw new EwynApiError(400, 'TEST_ERROR');
             }
             catch (error) {
-                expect(error instanceof MailerApiError).toBe(true);
+                expect(error instanceof EwynApiError).toBe(true);
                 expect(error instanceof Error).toBe(true);
-                if (error instanceof MailerApiError) {
+                if (error instanceof EwynApiError) {
                     expect(error.code).toBe('TEST_ERROR');
                 }
             }

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

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

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

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