@technomoron/mail-magic 1.0.40 → 1.0.41

package/dist/esm/util/uploads.d.ts

@@ -0,0 +1,10 @@
+import type { UploadedFile } from '../types.js';
+export declare function buildAttachments(rawFiles: UploadedFile[]): {
+    attachments: Array<{
+        filename: string;
+        path: string;
+    }>;
+    attachmentMap: Record<string, string>;
+};
+export declare function cleanupUploadedFiles(files: UploadedFile[]): Promise<void>;
+export declare function moveUploadedFiles(files: UploadedFile[], targetDir: string): Promise<void>;

package/dist/esm/util/utils.d.ts

@@ -0,0 +1,27 @@
+import { api_domain } from '../models/domain.js';
+import { api_user } from '../models/user.js';
+import type { RequestMeta } from '../types.js';
+import type { Response } from 'express';
+/**
+ * Normalize a string into a safe identifier for slugs, filenames, etc.
+ *
+ * - Lowercases all characters
+ * - Replaces any character that is not `a-z`, `0-9`, `-`, '.' or `_` with `-`
+ * - Collapses multiple consecutive dashes into one
+ * - Trims leading and trailing dashes
+ *
+ * Examples:
+ *   normalizeSlug("Hello World!")    -> "hello-world"
+ *   normalizeSlug("  Áccêntš  ")     -> "cc-nt"
+ *   normalizeSlug("My--Slug__Test")  -> "my-slug__test"
+ */
+export declare function normalizeSlug(input: string): string;
+export declare function user_and_domain(domain_id: number): Promise<{
+    user: api_user;
+    domain: api_domain;
+}>;
+export declare function buildRequestMeta(rawReq: unknown): RequestMeta;
+export declare function decodeComponent(value: string | string[] | undefined): string;
+export declare function getBodyValue(body: Record<string, unknown>, ...keys: string[]): string;
+export declare function normalizeBoolean(value: unknown): boolean;
+export declare function sendFileAsync(res: Pick<Response, 'sendFile'>, file: string, options?: Parameters<Response['sendFile']>[1]): Promise<void>;

package/dist/esm/util.d.ts

@@ -0,0 +1,7 @@
+export * from './util/utils.js';
+export * from './util/email.js';
+export * from './util/paths.js';
+export * from './util/uploads.js';
+export * from './util/form-replyto.js';
+export * from './util/form-submission.js';
+export * from './util/forms.js';

package/docs/swagger/openapi.json

@@ -2,7 +2,7 @@
 	"openapi": "3.1.0",
 	"info": {
 		"title": "Mail Magic API",
-		"version": "1.0.33",
+		"version": "1.0.41",
 		"description": "OpenAPI definition for the Mail Magic server. Authenticated endpoints require an API key provided as `Authorization: Bearer apikey-<token>`."
 	},
 	"servers": [
@@ -897,7 +897,7 @@
 				"properties": {
 					"domain": {
 						"type": "string",
-						"description": "Domain name owned by the API key user."
+						"description": "Optional. Domain name. If omitted, the API key's default domain is used."
 					},
 					"name": {
 						"type": "string",
@@ -920,13 +920,14 @@
 						"default": ""
 					}
 				},
-				"required": ["domain", "name", "template"]
+				"required": ["name", "template"]
 			},
 			"TxSendRequest": {
 				"type": "object",
 				"properties": {
 					"domain": {
-						"type": "string"
+						"type": "string",
+						"description": "Optional. Domain name. If omitted, the API key's default domain is used."
 					},
 					"name": {
 						"type": "string",
@@ -969,14 +970,15 @@
 						"description": "Custom email headers."
 					}
 				},
-				"required": ["domain", "name", "rcpt"]
+				"required": ["name", "rcpt"]
 			},
 			"TxSendMultipartRequest": {
 				"type": "object",
 				"description": "Multipart version of TxSendRequest. Attach files in any multipart field; `files` is a conventional field name.",
 				"properties": {
 					"domain": {
-						"type": "string"
+						"type": "string",
+						"description": "Optional. Domain name. If omitted, the API key's default domain is used."
 					},
 					"name": {
 						"type": "string"
@@ -1012,7 +1014,7 @@
 						}
 					}
 				},
-				"required": ["domain", "name", "rcpt"]
+				"required": ["name", "rcpt"]
 			},
 			"TxSendResponseData": {
 				"type": "object",
@@ -1031,7 +1033,8 @@
 				"type": "object",
 				"properties": {
 					"domain": {
-						"type": "string"
+						"type": "string",
+						"description": "Optional. Domain name. If omitted, the API key's default domain is used."
 					},
 					"idname": {
 						"type": "string",
@@ -1053,7 +1056,7 @@
 						"type": "string"
 					}
 				},
-				"required": ["domain", "idname", "email"]
+				"required": ["idname", "email"]
 			},
 			"FormRecipientUpsertResponseData": {
 				"type": "object",
@@ -1075,7 +1078,8 @@
 				"type": "object",
 				"properties": {
 					"domain": {
-						"type": "string"
+						"type": "string",
+						"description": "Optional. Domain name. If omitted, the API key's default domain is used."
 					},
 					"idname": {
 						"type": "string",
@@ -1131,7 +1135,7 @@
 						"type": "boolean"
 					}
 				},
-				"required": ["domain", "idname", "template", "sender", "recipient"]
+				"required": ["idname", "template", "sender", "recipient"]
 			},
 			"FormTemplateUpsertResponseData": {
 				"type": "object",
@@ -1262,7 +1266,7 @@
 			},
 			"FormMessageResponseData": {
 				"type": "object",
-				"description": "On success, data is usually an empty object. Some internal failures may return an object with an `error` string.",
+				"description": "On success, data is an empty object.",
 				"additionalProperties": true
 			},
 			"AssetsUploadMultipartRequest": {

package/examples/.env-dist

@@ -0,0 +1,21 @@
+NODE_ENV=development
+API_PORT=3776
+API_HOST=127.0.0.1
+API_URL=http://127.0.0.1:3776/api
+API_BASE_PATH=/api
+ASSET_ROUTE=/asset
+CONFIG_PATH=./data
+DB_TYPE=sqlite
+DB_NAME=./maildata.db
+DB_FORCE_SYNC=true
+DB_AUTO_RELOAD=false
+DB_SYNC_ALTER=false
+DB_LOG=false
+DEBUG=false
+AUTOESCAPE_HTML=true
+UPLOAD_PATH=./{domain}/uploads
+SMTP_HOST=127.0.0.1
+SMTP_PORT=1025
+SMTP_SECURE=false
+SMTP_TLS_REJECT=false
+API_TOKEN_PEPPER=example-token-pepper-value

package/examples/README.md

@@ -0,0 +1,74 @@
+# Mail Magic Examples
+
+The canonical example setup for Mail Magic. Shipped inside the `@technomoron/mail-magic` package so it is
+accessible without a private repo clone:
+
+```bash
+ls node_modules/@technomoron/mail-magic/examples/
+```
+
+It contains:
+
+- `data/` — runnable server config: `init-data.json` + `example.test/` domain with transactional and form templates
+- `scripts/` — helper TypeScript scripts for sending messages and testing the API
+- `.env-dist` — example environment file for local development
+
+Template families: welcome, confirm, change-password, receipt, invoice (tx) and contact, welcome-signup,
+confirm-account, change-password (form). Locale variants: `en`, `nb`.
+
+## Run The Example Server
+
+From repo root:
+
+```bash
+pnpm examples
+```
+
+This runs the `mail-magic` server bin with:
+
+- env file: `packages/server/examples/.env-dist`
+- config dir: `packages/server/examples/data`
+- default API host: `http://127.0.0.1:3776`
+
+## Default Demo Credentials
+
+Defined in `data/init-data.json`:
+
+- domain: `example.test`
+- token: `example-token`
+
+```text
+Authorization: Bearer apikey-example-token
+```
+
+## Validate Templates With `mm-cli compile`
+
+From repo root:
+
+```bash
+node packages/cli/dist/cli.js compile \
+  --input ./packages/server/examples/data \
+  --output /tmp/mm-compiled-examples \
+  --domain example.test
+```
+
+## Helper Scripts
+
+From repo root (requires `tsx`):
+
+```bash
+tsx packages/server/examples/scripts/send-messages.ts
+tsx packages/server/examples/scripts/public-form.ts
+tsx packages/server/examples/scripts/mm-api.ts template \
+  --file packages/server/examples/data/example.test/tx-template/en/welcome.njk \
+  --name welcome --domain example.test
+```
+
+## Production Adaptation
+
+Copy the `data/` directory and `.env-dist` to your project and adapt:
+
+1. `.env-dist` → `.env`: set `API_TOKEN_PEPPER`, SMTP settings, `API_URL`, DB path.
+2. `data/init-data.json`: users, domains, tokens, sender/recipient addresses.
+3. `data/<your-domain>/tx-template/*`: brand, content, locale text, assets.
+4. `data/<your-domain>/form-template/*`: subjects, recipient routing, exposed fields.

package/examples/data/example.test/form-template/base.njk

@@ -0,0 +1,4 @@
+{% include 'partials/header.njk' %}
+<h1>{{ title or 'Form message' }}</h1>
+{% block content %}{% endblock %}
+<p style="font-size: 12px; color: #666;">Generated at {{ _meta_.ts or '' }}</p>

package/examples/data/example.test/form-template/en/base.njk

@@ -0,0 +1 @@
+{% extends '../base.njk' %}

package/examples/data/example.test/form-template/en/change-password.njk

@@ -0,0 +1,5 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <p>Password change form submission.</p>
+  {% include 'partials/fields.njk' %}
+{% endblock %}

package/examples/data/example.test/form-template/en/confirm-account.njk

@@ -0,0 +1,5 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <p>New account confirmation request.</p>
+  {% include 'partials/fields.njk' %}
+{% endblock %}

package/examples/data/example.test/form-template/en/contact.njk

@@ -0,0 +1,5 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <p>New contact submission.</p>
+  {% include 'partials/fields.njk' %}
+{% endblock %}

package/examples/data/example.test/form-template/en/partials/fields.njk

@@ -0,0 +1,5 @@
+<ul>
+  {% for key, value in _fields_ %}
+  <li><strong>{{ key }}</strong>: {{ value }}</li>
+  {% endfor %}
+</ul>

package/examples/data/example.test/form-template/en/welcome-signup.njk

@@ -0,0 +1,5 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <p>New welcome signup.</p>
+  {% include 'partials/fields.njk' %}
+{% endblock %}

package/examples/data/example.test/form-template/nb/base.njk

@@ -0,0 +1 @@
+{% extends '../base.njk' %}

package/examples/data/example.test/form-template/nb/change-password.njk

@@ -0,0 +1,5 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <p>Skjema for passordendring.</p>
+  {% include 'partials/fields.njk' %}
+{% endblock %}

package/examples/data/example.test/form-template/nb/confirm-account.njk

@@ -0,0 +1,5 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <p>Ny bekreft-konto foresporsel.</p>
+  {% include 'partials/fields.njk' %}
+{% endblock %}

package/examples/data/example.test/form-template/nb/contact.njk

@@ -0,0 +1,5 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <p>Ny kontakthenvendelse.</p>
+  {% include 'partials/fields.njk' %}
+{% endblock %}

package/examples/data/example.test/form-template/nb/partials/fields.njk

@@ -0,0 +1,5 @@
+<ul>
+  {% for key, value in _fields_ %}
+  <li><strong>{{ key }}</strong>: {{ value }}</li>
+  {% endfor %}
+</ul>

package/examples/data/example.test/form-template/nb/welcome-signup.njk

@@ -0,0 +1,5 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <p>Ny registrering.</p>
+  {% include 'partials/fields.njk' %}
+{% endblock %}

package/examples/data/example.test/form-template/partials/header.njk

@@ -0,0 +1 @@
+<p><strong>{{ brand_name or 'Mail Magic Forms' }}</strong></p>

package/examples/data/example.test/tx-template/base.njk

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="{{ locale or 'en' }}">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <title>{{ subject or 'Mail Magic' }}</title>
+</head>
+<body style="font-family: Arial, Helvetica, sans-serif; color: #102030;">
+  {% include 'partials/header.njk' %}
+  <main>
+    {% block content %}{% endblock %}
+  </main>
+  <hr />
+  <p style="font-size: 12px; color: #666;">{{ company_name or 'Example Inc.' }} - {{ support_email or 'support@example.test' }}</p>
+</body>
+</html>

package/examples/data/example.test/tx-template/en/base.njk

@@ -0,0 +1 @@
+{% extends '../base.njk' %}

package/examples/data/example.test/tx-template/en/change-password.njk

@@ -0,0 +1,7 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <h1>Change your password</h1>
+  <p>Use this secure link to set a new password:</p>
+  <p><a href="{{ reset_url }}">Reset password</a></p>
+  <p style="font-size: 12px; color: #666;">Link expires in {{ expires_minutes or 30 }} minutes.</p>
+{% endblock %}

package/examples/data/example.test/tx-template/en/confirm.njk

@@ -0,0 +1,6 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <h1>Confirm your email</h1>
+  <p>Hi {{ name }}, click below to confirm your account.</p>
+  <p><a href="{{ confirm_url }}">Confirm account</a></p>
+{% endblock %}

package/examples/data/example.test/tx-template/en/invoice.njk

@@ -0,0 +1,8 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <h1>Invoice {{ invoice_no }}</h1>
+  <p>Hello {{ name }}, here is your invoice summary.</p>
+  {% include 'partials/line-items.njk' %}
+  <p><strong>Total:</strong> {{ currency or 'USD' }} {{ total }}</p>
+  <p>Due: {{ due_date }}</p>
+{% endblock %}

package/examples/data/example.test/tx-template/en/partials/header.njk

@@ -0,0 +1 @@
+{% include '../../partials/header.njk' %}

package/examples/data/example.test/tx-template/en/partials/line-items.njk

@@ -0,0 +1,14 @@
+<table role="presentation" width="100%" cellpadding="6" cellspacing="0" style="border-collapse: collapse; margin-top: 12px;">
+  <tr style="background: #f5f7fb;">
+    <th align="left">Item</th>
+    <th align="right">Qty</th>
+    <th align="right">Price</th>
+  </tr>
+  {% for item in items or [] %}
+  <tr>
+    <td>{{ item.name }}</td>
+    <td align="right">{{ item.qty }}</td>
+    <td align="right">{{ currency or 'USD' }} {{ item.price }}</td>
+  </tr>
+  {% endfor %}
+</table>

package/examples/data/example.test/tx-template/en/receipt.njk

@@ -0,0 +1,7 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <h1>Payment receipt {{ receipt_no }}</h1>
+  <p>Thanks for your payment, {{ name }}.</p>
+  <p>Amount: {{ currency or 'USD' }} {{ amount }}</p>
+  <p>Date: {{ paid_at }}</p>
+{% endblock %}

package/examples/data/example.test/tx-template/en/welcome.njk

@@ -0,0 +1,5 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <h1>Welcome, {{ name }}!</h1>
+  <p>Your account is ready. You can now sign in and start using {{ brand_name or 'Mail Magic' }}.</p>
+{% endblock %}

package/examples/data/example.test/tx-template/nb/base.njk

@@ -0,0 +1 @@
+{% extends '../base.njk' %}

package/examples/data/example.test/tx-template/nb/change-password.njk

@@ -0,0 +1,6 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <h1>Endre passord</h1>
+  <p>Bruk lenken under for a sette nytt passord:</p>
+  <p><a href="{{ reset_url }}">Nullstill passord</a></p>
+{% endblock %}

package/examples/data/example.test/tx-template/nb/confirm.njk

@@ -0,0 +1,6 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <h1>Bekreft e-post</h1>
+  <p>Hei {{ name }}, klikk under for a bekrefte kontoen din.</p>
+  <p><a href="{{ confirm_url }}">Bekreft konto</a></p>
+{% endblock %}

package/examples/data/example.test/tx-template/nb/invoice.njk

@@ -0,0 +1,7 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <h1>Faktura {{ invoice_no }}</h1>
+  <p>Hei {{ name }}, her er fakturaen din.</p>
+  <p><strong>Sum:</strong> {{ currency or 'NOK' }} {{ total }}</p>
+  <p>Forfall: {{ due_date }}</p>
+{% endblock %}

package/examples/data/example.test/tx-template/nb/partials/header.njk

@@ -0,0 +1 @@
+{% include '../../partials/header.njk' %}

package/examples/data/example.test/tx-template/nb/receipt.njk

@@ -0,0 +1,6 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <h1>Kvittering {{ receipt_no }}</h1>
+  <p>Takk for betalingen, {{ name }}.</p>
+  <p>Belop: {{ currency or 'NOK' }} {{ amount }}</p>
+{% endblock %}

package/examples/data/example.test/tx-template/nb/welcome.njk

@@ -0,0 +1,5 @@
+{% extends 'base.njk' %}
+{% block content %}
+  <h1>Velkommen, {{ name }}!</h1>
+  <p>Kontoen din er klar, og du kan begynne med en gang.</p>
+{% endblock %}

package/examples/data/example.test/tx-template/partials/header.njk

@@ -0,0 +1,7 @@
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="margin-bottom: 24px;">
+  <tr>
+    <td style="padding: 12px 0; border-bottom: 2px solid #dbe2ea;">
+      <strong>{{ brand_name or 'Mail Magic' }}</strong>
+    </td>
+  </tr>
+</table>