@technomoron/mail-magic 1.0.40 → 1.0.41

package/examples/data/init-data.json

@@ -0,0 +1,213 @@
+{
+	"user": [
+		{
+			"user_id": 1,
+			"idname": "example",
+			"token": "example-token",
+			"name": "Example User",
+			"email": "noreply@example.test",
+			"domain": 1,
+			"locale": "en"
+		}
+	],
+	"domain": [
+		{
+			"domain_id": 1,
+			"user_id": 1,
+			"name": "example.test",
+			"sender": "Example <noreply@example.test>",
+			"locale": "en",
+			"is_default": true
+		}
+	],
+	"template": [
+		{
+			"template_id": 1,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "welcome",
+			"locale": "en",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Welcome"
+		},
+		{
+			"template_id": 2,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "confirm",
+			"locale": "en",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Confirm your account"
+		},
+		{
+			"template_id": 3,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "change-password",
+			"locale": "en",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Change password"
+		},
+		{
+			"template_id": 4,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "receipt",
+			"locale": "en",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Your receipt"
+		},
+		{
+			"template_id": 5,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "invoice",
+			"locale": "en",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Your invoice"
+		},
+		{
+			"template_id": 6,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "welcome",
+			"locale": "nb",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Velkommen"
+		},
+		{
+			"template_id": 7,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "confirm",
+			"locale": "nb",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Bekreft konto"
+		},
+		{
+			"template_id": 8,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "change-password",
+			"locale": "nb",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Endre passord"
+		},
+		{
+			"template_id": 9,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "receipt",
+			"locale": "nb",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Kvittering"
+		},
+		{
+			"template_id": 10,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "invoice",
+			"locale": "nb",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Faktura"
+		}
+	],
+	"form": [
+		{
+			"form_id": 1,
+			"form_key": "example-contact-en",
+			"user_id": 1,
+			"domain_id": 1,
+			"idname": "contact",
+			"locale": "en",
+			"sender": "Example Forms <forms@example.test>",
+			"recipient": "owner@example.test",
+			"subject": "Contact form",
+			"secret": "form-secret"
+		},
+		{
+			"form_id": 2,
+			"form_key": "example-welcome-signup-en",
+			"user_id": 1,
+			"domain_id": 1,
+			"idname": "welcome-signup",
+			"locale": "en",
+			"sender": "Example Forms <forms@example.test>",
+			"recipient": "owner@example.test",
+			"subject": "Welcome signup",
+			"secret": "form-secret"
+		},
+		{
+			"form_id": 3,
+			"form_key": "example-confirm-account-en",
+			"user_id": 1,
+			"domain_id": 1,
+			"idname": "confirm-account",
+			"locale": "en",
+			"sender": "Example Forms <forms@example.test>",
+			"recipient": "owner@example.test",
+			"subject": "Confirm account form",
+			"secret": "form-secret"
+		},
+		{
+			"form_id": 4,
+			"form_key": "example-change-password-en",
+			"user_id": 1,
+			"domain_id": 1,
+			"idname": "change-password",
+			"locale": "en",
+			"sender": "Example Forms <forms@example.test>",
+			"recipient": "owner@example.test",
+			"subject": "Change password form",
+			"secret": "form-secret"
+		},
+		{
+			"form_id": 5,
+			"form_key": "example-contact-nb",
+			"user_id": 1,
+			"domain_id": 1,
+			"idname": "contact",
+			"locale": "nb",
+			"sender": "Example Forms <forms@example.test>",
+			"recipient": "owner@example.test",
+			"subject": "Kontakt",
+			"secret": "form-secret"
+		},
+		{
+			"form_id": 6,
+			"form_key": "example-welcome-signup-nb",
+			"user_id": 1,
+			"domain_id": 1,
+			"idname": "welcome-signup",
+			"locale": "nb",
+			"sender": "Example Forms <forms@example.test>",
+			"recipient": "owner@example.test",
+			"subject": "Registrering",
+			"secret": "form-secret"
+		},
+		{
+			"form_id": 7,
+			"form_key": "example-confirm-account-nb",
+			"user_id": 1,
+			"domain_id": 1,
+			"idname": "confirm-account",
+			"locale": "nb",
+			"sender": "Example Forms <forms@example.test>",
+			"recipient": "owner@example.test",
+			"subject": "Bekreft konto form",
+			"secret": "form-secret"
+		},
+		{
+			"form_id": 8,
+			"form_key": "example-change-password-nb",
+			"user_id": 1,
+			"domain_id": 1,
+			"idname": "change-password",
+			"locale": "nb",
+			"sender": "Example Forms <forms@example.test>",
+			"recipient": "owner@example.test",
+			"subject": "Endre passord form",
+			"secret": "form-secret"
+		}
+	]
+}

package/examples/scripts/mm-api.ts

@@ -0,0 +1,206 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import TemplateClient from '../../client/src/mail-magic-client.ts';
+
+type Command = 'template' | 'asset' | 'path';
+
+type Options = {
+	apiUrl?: string;
+	token?: string;
+	files: string[];
+	name?: string;
+	domain?: string;
+	sender?: string;
+	subject?: string;
+	locale?: string;
+	path?: string;
+	templateType?: 'tx' | 'form';
+	template?: string;
+};
+
+const DEFAULT_BASE_URL = 'http://127.0.0.1:3776';
+
+function usage(): void {
+	const text = `Usage:
+  mm-api.ts template --file <template.njk> --name <name> --domain <domain> [--sender "Name <email>"] [--subject <subject>] [--locale <locale>]
+  mm-api.ts asset --file <file> --domain <domain> [--path <subdir>] [--template-type tx|form] [--template <name>] [--locale <locale>]
+  mm-api.ts path --file <file> --domain <domain> --path <subdir> [--template-type tx|form] [--template <name>] [--locale <locale>]
+
+Environment:
+  MM_BASE_URL  Base API URL (default: http://127.0.0.1:3776)
+  MM_API_URL   Alternate API URL (if set, /api is stripped)
+  MM_TOKEN     API token (default: example-token)
+  MM_DOMAIN    Default domain
+`;
+	console.log(text);
+}
+
+function normalizeBaseUrl(value: string): string {
+	const trimmed = value.replace(/\/+$/, '');
+	if (trimmed.endsWith('/api')) {
+		return trimmed.slice(0, -4);
+	}
+	return trimmed;
+}
+
+function parseArgs(argv: string[]): { command: Command; options: Options } {
+	if (argv.length < 3) {
+		usage();
+		throw new Error('Missing command');
+	}
+	const command = argv[2] as Command;
+	if (command !== 'template' && command !== 'asset' && command !== 'path') {
+		usage();
+		throw new Error(`Unknown command: ${command}`);
+	}
+
+	const options: Options = { files: [] };
+	let index = 3;
+	while (index < argv.length) {
+		const key = argv[index];
+		const next = argv[index + 1];
+		if (!key.startsWith('--')) {
+			usage();
+			throw new Error(`Unknown argument: ${key}`);
+		}
+		switch (key) {
+			case '--file':
+				if (!next) {
+					throw new Error('Missing value for --file');
+				}
+				options.files.push(next);
+				index += 2;
+				break;
+			case '--name':
+				options.name = next;
+				index += 2;
+				break;
+			case '--domain':
+				options.domain = next;
+				index += 2;
+				break;
+			case '--sender':
+				options.sender = next;
+				index += 2;
+				break;
+			case '--subject':
+				options.subject = next;
+				index += 2;
+				break;
+			case '--locale':
+				options.locale = next;
+				index += 2;
+				break;
+			case '--path':
+				options.path = next;
+				index += 2;
+				break;
+			case '--template-type':
+				if (next !== 'tx' && next !== 'form') {
+					throw new Error('template-type must be tx or form');
+				}
+				options.templateType = next;
+				index += 2;
+				break;
+			case '--template':
+				options.template = next;
+				index += 2;
+				break;
+			case '--api':
+				options.apiUrl = next;
+				index += 2;
+				break;
+			case '--token':
+				options.token = next;
+				index += 2;
+				break;
+			case '--help':
+				usage();
+				process.exit(0);
+				break;
+			default:
+				usage();
+				throw new Error(`Unknown argument: ${key}`);
+		}
+	}
+
+	return { command, options };
+}
+
+function resolveFileList(files: string[]): string[] {
+	if (!files.length) {
+		throw new Error('At least one --file is required');
+	}
+	const resolved: string[] = [];
+	for (const file of files) {
+		const fullPath = path.resolve(file);
+		if (!fs.existsSync(fullPath)) {
+			throw new Error(`File not found: ${file}`);
+		}
+		resolved.push(fullPath);
+	}
+	return resolved;
+}
+
+async function runTemplate(client: TemplateClient, options: Options): Promise<void> {
+	if (!options.domain || !options.name) {
+		throw new Error('template requires --domain and --name');
+	}
+	const [file] = resolveFileList(options.files);
+	const template = fs.readFileSync(file, 'utf8');
+	await client.storeTxTemplate({
+		domain: options.domain,
+		name: options.name,
+		sender: options.sender,
+		subject: options.subject,
+		locale: options.locale,
+		template
+	});
+	console.log(`Stored template '${options.name}' for ${options.domain}`);
+}
+
+async function runAsset(client: TemplateClient, options: Options): Promise<void> {
+	if (!options.domain) {
+		throw new Error('asset requires --domain');
+	}
+	const files = resolveFileList(options.files);
+	await client.uploadAssets({
+		domain: options.domain,
+		files,
+		templateType: options.templateType,
+		template: options.template,
+		locale: options.locale,
+		path: options.path
+	});
+	console.log(`Uploaded ${files.length} asset(s) for ${options.domain}`);
+}
+
+async function main(): Promise<void> {
+	const { command, options } = parseArgs(process.argv);
+	const baseUrlRaw = options.apiUrl || DEFAULT_BASE_URL;
+	const baseUrl = normalizeBaseUrl(baseUrlRaw);
+	const token = options.token || 'example-token';
+	const domain = options.domain || 'example.test';
+
+	const client = new TemplateClient(baseUrl, token);
+	const mergedOptions: Options = { ...options, domain };
+
+	if (command === 'template') {
+		await runTemplate(client, mergedOptions);
+		return;
+	}
+
+	if (command === 'asset' || command === 'path') {
+		if (command === 'path' && !mergedOptions.path) {
+			throw new Error('path requires --path');
+		}
+		await runAsset(client, mergedOptions);
+		return;
+	}
+}
+
+main().catch((err) => {
+	console.error('Error:', err instanceof Error ? err.message : String(err));
+	process.exit(1);
+});

package/examples/scripts/public-form.ts

@@ -0,0 +1,100 @@
+import TemplateClient from '../../client/src/mail-magic-client.ts';
+
+const baseUrl = 'http://127.0.0.1:3776';
+const token = 'example-token';
+const domain = 'example.test';
+
+type ApiEnvelope<T> = {
+	success: boolean;
+	code: number;
+	message?: string;
+	data: T;
+	errors?: Record<string, unknown>;
+};
+
+type FormTemplateUpsertData = {
+	Status: string;
+	created: boolean;
+	form_key: string;
+};
+
+function extractApiMessage(payload: unknown): string | undefined {
+	if (!payload || typeof payload !== 'object') {
+		return undefined;
+	}
+	const message = (payload as { message?: unknown }).message;
+	if (typeof message === 'string' && message.trim()) {
+		return message.trim();
+	}
+	return undefined;
+}
+
+async function postJson<T>(
+	url: string,
+	body: Record<string, unknown>,
+	headers: Record<string, string> = {}
+): Promise<T> {
+	const res = await fetch(url, {
+		method: 'POST',
+		headers: {
+			'content-type': 'application/json',
+			...headers
+		},
+		body: JSON.stringify(body)
+	});
+
+	const json = (await res.json().catch(() => null)) as unknown;
+	if (!res.ok) {
+		const message = extractApiMessage(json) || res.statusText;
+		throw new Error(`Request failed: ${res.status} ${message}`);
+	}
+	return json as T;
+}
+
+async function main(): Promise<void> {
+	const client = new TemplateClient(baseUrl, token);
+
+	// Store a form template (authenticated). Capture `form_key` for public submissions.
+	const stored = (await client.storeFormTemplate({
+		domain,
+		idname: 'journalist-contact',
+		sender: 'Example Forms <forms@example.test>',
+		recipient: 'default@example.test',
+		subject: 'Journalist Contact',
+		template: '<p>Hello {{ _fields_.msg }}</p>'
+	})) as ApiEnvelope<FormTemplateUpsertData>;
+
+	const form_key = String(stored?.data?.form_key ?? '');
+	if (!form_key) {
+		throw new Error('Expected data.form_key in the form template response');
+	}
+
+	// Configure recipient allowlist (authenticated).
+	await postJson(
+		`${baseUrl}/api/v1/form/recipient`,
+		{
+			domain,
+			form_key,
+			idname: 'desk',
+			email: 'News Desk <desk@example.test>'
+		},
+		{
+			Authorization: `Bearer apikey-${token}`
+		}
+	);
+
+	// Submit the form publicly (no auth required).
+	await postJson(`${baseUrl}/api/v1/form/message`, {
+		_mm_form_key: form_key,
+		_mm_recipients: ['desk'],
+		msg: 'Hello from the public form example'
+	});
+
+	console.log('Created/updated form: journalist-contact');
+	console.log(`Public form_key: ${form_key}`);
+}
+
+main().catch((err: unknown) => {
+	console.error('Error:', err instanceof Error ? err.message : String(err));
+	process.exit(1);
+});

package/examples/scripts/send-messages.ts

@@ -0,0 +1,114 @@
+import TemplateClient from '../../client/src/mail-magic-client.ts';
+
+type Mode = 'tx' | 'form' | 'both';
+
+const baseUrl = 'http://127.0.0.1:3776';
+const token = 'example-token';
+const domain = 'example.test';
+
+const txName = 'welcome';
+const formId = 'contact';
+const locale = 'en';
+
+const rcpt = 'user@example.test';
+const sender = 'Example <noreply@example.test>';
+const formSender = 'Example Forms <forms@example.test>';
+const formRecipient = 'owner@example.test';
+const formSecret = 'form-secret';
+
+type ApiEnvelope<T> = {
+	success: boolean;
+	code: number;
+	message?: string;
+	data: T;
+	errors?: Record<string, unknown>;
+};
+
+type FormTemplateUpsertData = {
+	Status: string;
+	created: boolean;
+	form_key: string;
+};
+
+async function postJson(url: string, body: Record<string, unknown>): Promise<void> {
+	const res = await fetch(url, {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		body: JSON.stringify(body)
+	});
+	if (!res.ok) {
+		const msg = (await res.text().catch(() => res.statusText)) || res.statusText;
+		throw new Error(`Request failed: ${res.status} ${msg}`);
+	}
+}
+
+const modeArg = (process.argv[2] || 'both') as Mode;
+const mode: Mode = modeArg === 'tx' || modeArg === 'form' ? modeArg : 'both';
+
+async function sendTx(client: TemplateClient): Promise<void> {
+	await client.storeTxTemplate({
+		domain,
+		name: txName,
+		sender,
+		subject: 'Welcome from mail-magic',
+		locale,
+		template: '<p>Hello {{ name }}!</p>'
+	});
+
+	await client.sendTxMessage({
+		domain,
+		name: txName,
+		locale,
+		rcpt,
+		vars: { name: 'Example' }
+	});
+
+	console.log(`Sent tx template '${txName}' to ${rcpt}`);
+}
+
+async function sendForm(client: TemplateClient): Promise<void> {
+	const stored = (await client.storeFormTemplate({
+		domain,
+		idname: formId,
+		sender: formSender,
+		recipient: formRecipient,
+		subject: 'Example form submission',
+		locale,
+		secret: formSecret,
+		template: '<p>Contact from {{ _fields_.name }} ({{ _fields_.email }})</p>'
+	})) as ApiEnvelope<FormTemplateUpsertData>;
+
+	const form_key = String(stored?.data?.form_key ?? '').trim();
+	if (!form_key) {
+		throw new Error('Expected data.form_key in the form template response');
+	}
+
+	// Public form submission endpoint (no auth): requires `_mm_form_key`.
+	await postJson(`${baseUrl}/api/v1/form/message`, {
+		_mm_form_key: form_key,
+		name: 'Example User',
+		email: rcpt,
+		message: 'Hello from the example script.'
+	});
+
+	console.log(`Sent form message '${formId}' to ${formRecipient}`);
+}
+
+async function main(): Promise<void> {
+	const client = new TemplateClient(baseUrl, token);
+	if (mode === 'tx') {
+		await sendTx(client);
+		return;
+	}
+	if (mode === 'form') {
+		await sendForm(client);
+		return;
+	}
+	await sendTx(client);
+	await sendForm(client);
+}
+
+main().catch((err: unknown) => {
+	console.error('Error:', err instanceof Error ? err.message : String(err));
+	process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@technomoron/mail-magic",
-  "version": "1.0.40",
+  "version": "1.0.41",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "exports": {
     ".": {
+      "types": "./dist/cjs/index.d.ts",
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.js"
     }
@@ -16,6 +17,7 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "README.md",
     "CHANGES"
   ],
@@ -66,7 +68,7 @@
   "scripts": {
     "start": "node dist/esm/index.js",
     "dev": "NODE_ENV=development nodemon --watch 'src/**/*.ts' --watch 'config/**/*.*' --watch '.env' --exec 'tsx' src/index.ts",
-    "run": "NODE_ENV=production npm run start",
+    "run": "NODE_ENV=production run-s start",
     "sync:shared": "node ../../scripts/sync-shared-code.cjs >/dev/null",
     "build:esm": "tsc --project tsconfig/tsconfig.esm.json",
     "build:cjs": "node scripts/add-shebang.cjs --cjs-only",
@@ -76,8 +78,8 @@
     "test": "run-s --silent sync:shared test:unit",
     "test:watch": "vitest",
     "scrub": "rimraf ./node_modules/ ./dist/ pnpm-lock.yaml package-lock.json yarn.lock",
-    "lint": "node ../../node_modules/eslint/bin/eslint.js --config ../../eslint.config.mjs --no-error-on-unmatched-pattern --ext .js,.cjs,.mjs,.ts,.mts,.tsx,.vue,.json ./",
-    "lintfix": "node ../../node_modules/eslint/bin/eslint.js --config ../../eslint.config.mjs --fix --no-error-on-unmatched-pattern --ext .js,.cjs,.mjs,.ts,.mts,.tsx,.vue,.json ./",
+    "lint": "node ../../node_modules/eslint/bin/eslint.js --config ../../eslint.config.mjs --no-error-on-unmatched-pattern ./",
+    "lintfix": "node ../../node_modules/eslint/bin/eslint.js --config ../../eslint.config.mjs --fix --no-error-on-unmatched-pattern ./",
     "pretty": "node ../../node_modules/prettier/bin/prettier.cjs --config ../../.prettierrc --write \"**/*.{js,jsx,cjs,mjs,ts,tsx,mts,vue,json,md}\"",
     "format": "run-s lintfix pretty",
     "cleanbuild": "run-s clean:dist format build",