@technomoron/mail-magic-client 1.0.23

package/CHANGES

@@ -0,0 +1,4 @@
+Version 1.0.23 (2026-01-31)
+
+- Fixed the per-package release script name and tag format used to trigger
+  CI releases; no runtime changes.

package/README.md

@@ -0,0 +1,102 @@
+# mail-magic-client
+
+Client library and CLI for the mail-magic server.
+
+## Install
+
+```bash
+npm install @technomoron/mail-magic-client
+```
+
+## Client Usage
+
+```ts
+import TemplateClient from '@technomoron/mail-magic-client';
+
+const client = new TemplateClient('http://localhost:3000', 'username:token');
+
+await client.storeTxTemplate({
+	domain: 'example.test',
+	name: 'welcome',
+	sender: 'App <noreply@example.test>',
+	subject: 'Welcome',
+	template: '<p>Hello {{ name }}</p>'
+});
+
+await client.sendTxMessage({
+	domain: 'example.test',
+	name: 'welcome',
+	rcpt: 'user@example.test',
+	vars: { name: 'Sam' }
+});
+```
+
+## CLI
+
+The package ships `mm-cli`.
+
+### .mmcli-env
+
+Create `.mmcli-env` in your working directory to set defaults:
+
+```ini
+MMCLI_API=http://localhost:3000
+MMCLI_TOKEN=username:token
+# or, split token:
+MMCLI_USERNAME=username
+MMCLI_PASSWORD=token
+MMCLI_DOMAIN=example.test
+```
+
+### Template Commands
+
+Compile a template locally:
+
+```bash
+mm-cli compile --input ./templates --output ./templates-dist
+```
+
+Push a single transactional template (compile + upload):
+
+```bash
+mm-cli push --template tx-template/en/welcome --domain example.test --input ./templates
+```
+
+Dry-run a single template upload:
+
+```bash
+mm-cli push --template tx-template/en/welcome --domain example.test --input ./templates --dry-run
+```
+
+Push an entire config-style directory:
+
+```bash
+mm-cli push-dir --input ./data --domain example.test
+mm-cli push-dir --input ./data --domain example.test --dry-run
+mm-cli push-dir --input ./data --domain example.test --skip-assets
+```
+
+### Asset Uploads
+
+Upload stand-alone domain assets:
+
+```bash
+mm-cli assets --file ./logo.png --domain example.test
+```
+
+Dry-run an asset upload:
+
+```bash
+mm-cli assets --file ./logo.png --domain example.test --dry-run
+```
+
+Upload assets scoped to a template:
+
+```bash
+mm-cli assets --file ./hero.png --domain example.test --template-type tx --template welcome --locale en --path images
+```
+
+## Notes
+
+- `push-dir` expects a `init-data.json` and domain folders that match the server config layout.
+- Asset uploads use the server endpoint `POST /api/v1/assets`.

package/dist/cjs/mail-magic-client.d.ts

@@ -0,0 +1,82 @@
+interface templateData {
+    template: string;
+    domain: string;
+    sender?: string;
+    name?: string;
+    subject?: string;
+    locale?: string;
+    part?: boolean;
+}
+interface formTemplateData {
+    idname: string;
+    domain: string;
+    template: string;
+    sender: string;
+    recipient: string;
+    subject?: string;
+    locale?: string;
+    secret?: string;
+}
+interface sendTemplateData {
+    name: string;
+    rcpt: string;
+    domain: string;
+    locale?: string;
+    vars?: object;
+    replyTo?: string;
+    headers?: Record<string, string>;
+    attachments?: AttachmentInput[];
+}
+interface sendFormData {
+    formid: string;
+    secret?: string;
+    recipient?: string;
+    domain?: string;
+    locale?: string;
+    vars?: object;
+    replyTo?: string;
+    fields?: Record<string, unknown>;
+    attachments?: AttachmentInput[];
+}
+type AttachmentInput = {
+    path: string;
+    filename?: string;
+    contentType?: string;
+    field?: string;
+};
+type UploadAssetInput = string | AttachmentInput;
+interface uploadAssetsData {
+    domain: string;
+    files: UploadAssetInput[];
+    templateType?: 'tx' | 'form';
+    template?: string;
+    locale?: string;
+    path?: string;
+}
+declare class templateClient {
+    private baseURL;
+    private apiKey;
+    constructor(baseURL: string, apiKey: string);
+    request<T>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', command: string, body?: any): Promise<T>;
+    get<T>(command: string): Promise<T>;
+    post<T>(command: string, body: any): Promise<T>;
+    put<T>(command: string, body: any): Promise<T>;
+    delete<T>(command: string, body?: any): Promise<T>;
+    validateEmails(list: string): {
+        valid: string[];
+        invalid: string[];
+    };
+    private validateTemplate;
+    private validateSender;
+    private createAttachmentPayload;
+    private appendFields;
+    private postFormData;
+    storeTemplate(td: templateData): Promise<any>;
+    sendTemplate(std: sendTemplateData): Promise<any>;
+    storeTxTemplate(td: templateData): Promise<any>;
+    sendTxMessage(std: sendTemplateData): Promise<any>;
+    storeFormTemplate(data: formTemplateData): Promise<any>;
+    sendFormMessage(data: sendFormData): Promise<any>;
+    uploadAssets(data: uploadAssetsData): Promise<any>;
+}
+export default templateClient;

package/dist/cjs/mail-magic-client.js

@@ -0,0 +1,281 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const email_addresses_1 = __importDefault(require("email-addresses"));
+const nunjucks_1 = __importDefault(require("nunjucks"));
+class templateClient {
+    constructor(baseURL, apiKey) {
+        this.baseURL = baseURL;
+        this.apiKey = apiKey;
+        if (!apiKey || !baseURL) {
+            throw new Error('Apikey/api-url required');
+        }
+    }
+    async request(method, command, body) {
+        const url = `${this.baseURL}${command}`;
+        const options = {
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer apikey-${this.apiKey}`
+            },
+            body: body ? JSON.stringify(body) : '{}'
+        };
+        //        console.log(JSON.stringify({ options, url }));
+        const response = await fetch(url, options);
+        const j = await response.json();
+        if (response.ok) {
+            return j;
+        }
+        // console.log(JSON.stringify(j, undefined, 2));
+        if (j && j.message) {
+            throw new Error(`FETCH FAILED: ${response.status} ${j.message}`);
+        }
+        else {
+            throw new Error(`FETCH FAILED: ${response.status} ${response.statusText}`);
+        }
+    }
+    async get(command) {
+        return this.request('GET', command);
+    }
+    async post(command, body) {
+        return this.request('POST', command, body);
+    }
+    async put(command, body) {
+        return this.request('PUT', command, body);
+    }
+    async delete(command, body) {
+        return this.request('DELETE', command, body);
+    }
+    validateEmails(list) {
+        const valid = [], invalid = [];
+        const emails = list
+            .split(',')
+            .map((email) => email.trim())
+            .filter((email) => email !== '');
+        emails.forEach((email) => {
+            const parsed = email_addresses_1.default.parseOneAddress(email);
+            if (parsed && parsed.address) {
+                valid.push(parsed.address);
+            }
+            else {
+                invalid.push(email);
+            }
+        });
+        return { valid, invalid };
+    }
+    validateTemplate(template) {
+        try {
+            const env = new nunjucks_1.default.Environment(new nunjucks_1.default.FileSystemLoader(['./templates']));
+            const t = env.renderString(template, {});
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Template validation failed: ${error.message}`);
+            }
+            else {
+                throw new Error('Template validation failed with an unknown error');
+            }
+        }
+    }
+    validateSender(sender) {
+        const exp = /^[^<>]+<[^<>]+@[^<>]+\.[^<>]+>$/;
+        if (!exp.test(sender)) {
+            throw new Error('Invalid sender format. Expected "Name <email@example.com>"');
+        }
+    }
+    createAttachmentPayload(attachments) {
+        const formData = new FormData();
+        const usedFields = [];
+        for (const attachment of attachments) {
+            if (!attachment?.path) {
+                throw new Error('Attachment path is required');
+            }
+            const raw = fs_1.default.readFileSync(attachment.path);
+            const filename = attachment.filename || path_1.default.basename(attachment.path);
+            const blob = new Blob([raw], attachment.contentType ? { type: attachment.contentType } : undefined);
+            const field = attachment.field || 'attachment';
+            formData.append(field, blob, filename);
+            usedFields.push(field);
+        }
+        return { formData, usedFields };
+    }
+    appendFields(formData, fields) {
+        for (const [key, value] of Object.entries(fields)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            if (typeof value === 'string') {
+                formData.append(key, value);
+            }
+            else if (typeof value === 'number' || typeof value === 'boolean') {
+                formData.append(key, String(value));
+            }
+            else {
+                formData.append(key, JSON.stringify(value));
+            }
+        }
+    }
+    async postFormData(command, formData) {
+        const url = `${this.baseURL}${command}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer apikey-${this.apiKey}`
+            },
+            body: formData
+        });
+        const j = await response.json();
+        if (response.ok) {
+            return j;
+        }
+        if (j && j.message) {
+            throw new Error(`FETCH FAILED: ${response.status} ${j.message}`);
+        }
+        throw new Error(`FETCH FAILED: ${response.status} ${response.statusText}`);
+    }
+    async storeTemplate(td) {
+        if (!td.template) {
+            throw new Error('No template data provided');
+        }
+        this.validateTemplate(td.template);
+        if (td.sender) {
+            this.validateSender(td.sender);
+        }
+        return this.storeTxTemplate(td);
+    }
+    async sendTemplate(std) {
+        if (!std.name || !std.rcpt) {
+            throw new Error('Invalid request body; name/rcpt required');
+        }
+        return this.sendTxMessage(std);
+    }
+    async storeTxTemplate(td) {
+        if (!td.template) {
+            throw new Error('No template data provided');
+        }
+        this.validateTemplate(td.template);
+        if (td.sender) {
+            this.validateSender(td.sender);
+        }
+        return this.post('/api/v1/tx/template', td);
+    }
+    async sendTxMessage(std) {
+        if (!std.name || !std.rcpt) {
+            throw new Error('Invalid request body; name/rcpt required');
+        }
+        const { valid, invalid } = this.validateEmails(std.rcpt);
+        if (invalid.length > 0) {
+            throw new Error('Invalid email address(es): ' + invalid.join(','));
+        }
+        // this.validateTemplate(template);
+        const body = {
+            name: std.name,
+            rcpt: std.rcpt,
+            domain: std.domain || '',
+            locale: std.locale || '',
+            vars: std.vars || {},
+            replyTo: std.replyTo,
+            headers: std.headers
+        };
+        // console.log(JSON.stringify(body, undefined, 2));
+        if (std.attachments && std.attachments.length > 0) {
+            if (std.headers) {
+                throw new Error('Headers are not supported with attachment uploads');
+            }
+            const { formData } = this.createAttachmentPayload(std.attachments);
+            this.appendFields(formData, {
+                name: std.name,
+                rcpt: std.rcpt,
+                domain: std.domain || '',
+                locale: std.locale || '',
+                vars: JSON.stringify(std.vars || {}),
+                replyTo: std.replyTo
+            });
+            return this.postFormData('/api/v1/tx/message', formData);
+        }
+        return this.post('/api/v1/tx/message', body);
+    }
+    async storeFormTemplate(data) {
+        if (!data.template) {
+            throw new Error('No template data provided');
+        }
+        if (!data.idname) {
+            throw new Error('Missing form identifier');
+        }
+        if (!data.sender) {
+            throw new Error('Missing sender address');
+        }
+        if (!data.recipient) {
+            throw new Error('Missing recipient address');
+        }
+        this.validateTemplate(data.template);
+        this.validateSender(data.sender);
+        return this.post('/api/v1/form/template', data);
+    }
+    async sendFormMessage(data) {
+        if (!data.formid) {
+            throw new Error('Invalid request body; formid required');
+        }
+        const fields = data.fields || {};
+        const baseFields = {
+            formid: data.formid,
+            secret: data.secret,
+            recipient: data.recipient,
+            domain: data.domain,
+            locale: data.locale,
+            vars: data.vars || {},
+            replyTo: data.replyTo,
+            ...fields
+        };
+        if (data.attachments && data.attachments.length > 0) {
+            const { formData } = this.createAttachmentPayload(data.attachments);
+            this.appendFields(formData, {
+                formid: data.formid,
+                secret: data.secret,
+                recipient: data.recipient,
+                domain: data.domain,
+                locale: data.locale,
+                vars: JSON.stringify(data.vars || {}),
+                replyTo: data.replyTo
+            });
+            this.appendFields(formData, fields);
+            return this.postFormData('/api/v1/form/message', formData);
+        }
+        return this.post('/api/v1/form/message', baseFields);
+    }
+    async uploadAssets(data) {
+        if (!data.domain) {
+            throw new Error('domain is required');
+        }
+        if (!data.files || data.files.length === 0) {
+            throw new Error('At least one asset file is required');
+        }
+        if (data.templateType && !data.template) {
+            throw new Error('template is required when templateType is provided');
+        }
+        if (data.template && !data.templateType) {
+            throw new Error('templateType is required when template is provided');
+        }
+        const attachments = data.files.map((input) => {
+            if (typeof input === 'string') {
+                return { path: input, field: 'asset' };
+            }
+            return { ...input, field: input.field || 'asset' };
+        });
+        const { formData } = this.createAttachmentPayload(attachments);
+        this.appendFields(formData, {
+            domain: data.domain,
+            templateType: data.templateType,
+            template: data.template,
+            locale: data.locale,
+            path: data.path
+        });
+        return this.postFormData('/api/v1/assets', formData);
+    }
+}
+exports.default = templateClient;

package/dist/cli-env.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCliEnv = loadCliEnv;
+exports.resolveToken = resolveToken;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function stripQuotes(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function loadCliEnv(cwd = process.cwd()) {
+    const envPath = node_path_1.default.join(cwd, '.mmcli-env');
+    if (!node_fs_1.default.existsSync(envPath)) {
+        return {};
+    }
+    const raw = node_fs_1.default.readFileSync(envPath, 'utf8');
+    const values = {};
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const index = trimmed.indexOf('=');
+        if (index === -1) {
+            continue;
+        }
+        const key = trimmed.slice(0, index).trim();
+        const value = stripQuotes(trimmed.slice(index + 1));
+        if (key) {
+            values[key] = value;
+        }
+    }
+    return {
+        api: values.MMCLI_API || values.API,
+        token: values.MMCLI_TOKEN,
+        username: values.MMCLI_USERNAME || values.MMCLI_USER,
+        password: values.MMCLI_PASSWORD || values.MMCLI_PASS,
+        domain: values.MMCLI_DOMAIN
+    };
+}
+function resolveToken(defaults) {
+    if (defaults.token) {
+        return defaults.token;
+    }
+    if (defaults.username && defaults.password) {
+        return `${defaults.username}:${defaults.password}`;
+    }
+    return undefined;
+}