@technomoron/mail-magic 1.0.40 → 1.0.42

package/CHANGES

@@ -1,13 +1,56 @@
 CHANGES
 =======
 
-Unreleased (2026-02-22)
+Unreleased (2026-02-27)
+
+- chore(release): prepare release metadata for server package.
+- perf(forms): batch recipient resolution for `_mm_recipients` into scoped + fallback `IN` queries while preserving precedence and requested order.
+- test(forms): add coverage for multi-recipient resolution order with scoped-over-domain recipient precedence.
+- (Changes generated/assisted by Codex (profile: openai-gpt-5-codex/medium).)
+
+Version 1.0.42 (2026-02-27)
+
+- chore(deps): upgrade `@technomoron/api-server-base` from `2.0.0-beta.20` to `2.0.0-beta.24` (Express → Fastify migration).
+- feat(auth): enable API key authentication (`apiKeyEnabled: true`, `apiKeyPrefix: 'apikey-'`) in server config to restore API key auth broken by the beta.24 default change.
+- feat(ratelimit): replace local `FixedWindowRateLimiter` implementation with the one exported by `@technomoron/api-server-base`; re-export for consumers.
+- feat(validation): add Fastify JSON Schema validation (`schema`) to `/v1/tx/template`, `/v1/form/template`, and `/v1/form/recipient` routes; omit schema from multipart-capable routes where body is populated after Fastify's validation phase.
+- fix(assets): use a MIME type map to set correct `Content-Type` headers (e.g. `image/png`) instead of passing raw file extensions to `fastifyReply.type()`, which Fastify 5 does not convert automatically.
+- fix(assets): read asset files into a `Buffer` for `res.send()` since Fastify 5 stream piping through `fastify.routing()` does not flush to supertest-style clients.
+- fix(ratelimit): restore `Retry-After` response header on 429 rate-limit rejections by setting it on the underlying Fastify reply before throwing `ApiError`.
+- fix(uploads): update `UploadedFile` type to match `ApiUploadedFile` from beta.24 (`filepath?`/`buffer?` instead of `path`); update `store.ts`, `uploads.ts`, `mailer.ts`, `forms.ts` to handle both in-memory buffers and on-disk files.
+- fix(swagger): replace Express-typed handler signature with `ExtendedReq`/`ApiRequest['res']` from `@technomoron/api-server-base`.
+- fix(routes): change wildcard route from `/:domain/*path` to `/:domain/*` (find-my-way/Fastify does not support named wildcards).
+- docs(swagger): bump packaged OpenAPI spec version to 1.0.42.
+- (Changes generated/assisted by Claude Code (profile: anthropic-claude-sonnet-4-6/high).)
+
+Version 1.0.41 (2026-02-22)
 
 - chore(release): add package-level `release:check` script and wire `release` to shared publish script.
 - chore(scripts): replace `rm -rf` cleanup scripts with `rimraf`.
+- chore(examples): move example data, scripts, and `.env-dist` from standalone `packages/examples/` workspace into `packages/server/examples/`; add `examples` to the npm `files` list so they are shipped with the package.
+- chore(repo): rename admin package directory from `mail-magic-admin` to `admin` (npm package name unchanged).
 - test(logging): suppress noisy SQL/startup stdout in automated tests by default (`DB_LOG=false` in test setup; startup logs debug-only).
 - test(logging): quiet package test output by default (silent Vitest + silent sync step) and remove Node `DEP0170` warning in schema-drift test DB setup.
-- (Changes generated/assisted by Codex (profile: chatgpt-5.3-codex/medium).)
+- fix(forms): replace global `nunjucks.configure()` call in `postSendForm` with a scoped `nunjucks.Environment` instance, matching the pattern already used in `post_send`.
+- fix(forms): add plain-text email part to form submissions via `html-to-text` (was HTML-only, harming deliverability).
+- fix(forms): derive `recipients` template variable from already-resolved DB records instead of re-parsing the raw input with a second `parseIdnameList` call.
+- fix(forms): remove silent `catch` in `resolveFormKeyForTemplate` so DB errors propagate instead of being silently treated as "no existing form".
+- fix(forms): extract `buildFormSlugAndFilename` into `util/paths.ts` to eliminate duplicated slug/filename generation between the API upload path and the DB upsert path.
+- fix(models): filter `allowed_fields` JSON getter to string elements only; previously returned non-string values (numbers, nulls) typed as `string[]`.
+- fix(smtp): make `requireTLS` configurable via `SMTP_REQUIRE_TLS` env var (default `true`, preserving existing behaviour); allows disabling STARTTLS for servers such as MailHog.
+- fix(smtp): change `SMTP_TLS_REJECT` default from `false` to `true` so TLS certificates are validated in production by default.
+- fix(smtp): correct `SMTP_TLS_REJECT` description (previously described the inverse of what the option does).
+- fix(config): change `DB_SYNC_ALTER` default from `true` to `false` to prevent automatic DDL on production startups.
+- fix(config): add `mysql` and `postgres` to the `DB_TYPE` allowed-values list to match what the connection code already supports.
+- fix(ratelimit): skip rate limiting when the client IP cannot be resolved, rather than bucketing all unresolvable IPs under a shared `unknown` key.
+- fix(captcha): throw an explicit error for unknown CAPTCHA providers instead of silently falling back to Turnstile.
+- fix(auth): make `domain` optional in `assert_domain_and_user`; when absent from the request body, fall back to the authenticated user's default domain (`api_user.domain`).
+- fix(build): remove `noImplicitAny: false` override from `tsconfig/tsconfig.esm.json`; the root tsconfig already enables `strict`, which includes `noImplicitAny`.
+- fix(build): add `declaration: true` to `tsconfig/tsconfig.esm.json` to emit `.d.ts` files; generate `dist/cjs/index.d.ts` re-exporting ESM types; add `types` condition to package exports; extract `STARTUP_ERROR_MESSAGE` from compiled ESM output instead of hardcoding it in the CJS shim script.
+- fix(scripts): remove `--ext` flags from all `lint`/`lintfix` npm scripts — ESLint v9 flat config silently ignores these flags; file coverage is already provided by the glob patterns in `eslint.config.mjs`.
+- docs(swagger): remove `domain` from the `required` array in all authenticated request schemas (`TxTemplateUpsertRequest`, `TxSendRequest`, `TxSendMultipartRequest`, `FormRecipientUpsertRequest`, `FormTemplateUpsertRequest`); mark property descriptions as optional; bump spec version to 1.0.41.
+- docs(readme): add `SMTP_REQUIRE_TLS` to quick-start `.env` example and configuration reference.
+- (Changes generated/assisted by Claude Code (profile: anthropic-claude-sonnet-4-6/high).)
 
 Version 1.0.40 (2026-02-22)
 

package/README.md

@@ -60,6 +60,7 @@ API_URL=http://127.0.0.1:3776
 SMTP_HOST=127.0.0.1
 SMTP_PORT=1025
 SMTP_SECURE=false
+SMTP_REQUIRE_TLS=false
 SMTP_TLS_REJECT=false
 ```
 
@@ -144,6 +145,10 @@ Commonly used variables:
     - `FORM_RATE_LIMIT_WINDOW_SEC`, `FORM_RATE_LIMIT_MAX`
     - `FORM_MAX_ATTACHMENTS`, `FORM_KEEP_UPLOADS`
     - `FORM_CAPTCHA_PROVIDER`, `FORM_CAPTCHA_SECRET`, `FORM_CAPTCHA_REQUIRED`
+- SMTP:
+    - `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`
+    - `SMTP_REQUIRE_TLS` (default `true`; set to `false` for local dev servers like MailHog that don't support STARTTLS)
+    - `SMTP_TLS_REJECT` (default `true`; set to `false` to accept self-signed certificates)
 - Swagger/OpenAPI:
     - `SWAGGER_ENABLED`, `SWAGGER_PATH`
 

package/dist/cjs/index.d.ts

@@ -0,0 +1 @@
+export * from '../esm/index.js';

package/dist/cjs/index.js

@@ -3,7 +3,7 @@
 const load = () => import('../esm/index.js');
 
 module.exports = {
-  STARTUP_ERROR_MESSAGE: 'Failed to start mail-magic:',
+  STARTUP_ERROR_MESSAGE: "Failed to start mail-magic:",
   createMailMagicServer: async (...args) => (await load()).createMailMagicServer(...args),
   startMailMagicServer: async (...args) => (await load()).startMailMagicServer(...args)
 };

package/dist/esm/api/assets.d.ts

@@ -0,0 +1,11 @@
+import { ApiModule, ApiRoute } from '@technomoron/api-server-base';
+import { mailApiServer } from '../server.js';
+import type { ApiRequest, ExtendedReq } from '@technomoron/api-server-base';
+type ApiRes = ApiRequest['res'];
+export declare class AssetAPI extends ApiModule<mailApiServer> {
+    private resolveTemplateDir;
+    private postAssets;
+    defineRoutes(): ApiRoute[];
+}
+export declare function createAssetHandler(server: mailApiServer): (req: ExtendedReq, res: ApiRes, next?: (error?: unknown) => void) => Promise<void>;
+export {};

package/dist/esm/api/assets.js

@@ -6,12 +6,36 @@ import { api_txmail } from '../models/txmail.js';
 import { SEGMENT_PATTERN, normalizeSubdir } from '../util/paths.js';
 import { moveUploadedFiles } from '../util/uploads.js';
 import { getBodyValue } from '../util/utils.js';
-import { decodeComponent, sendFileAsync } from '../util.js';
+import { decodeComponent } from '../util.js';
 import { assert_domain_and_user } from './auth.js';
 const DOMAIN_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
+const MIME_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.json': 'application/json',
+    '.txt': 'text/plain',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.pdf': 'application/pdf',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.eot': 'application/vnd.ms-fontobject'
+};
+function getMimeType(ext) {
+    return MIME_TYPES[ext.toLowerCase()] ?? 'application/octet-stream';
+}
 export class AssetAPI extends ApiModule {
     async resolveTemplateDir(apireq) {
-        const body = apireq.req.body ?? {};
+        const body = (apireq.req.body ?? {});
         const templateTypeRaw = getBodyValue(body, 'templateType', 'template_type', 'type');
         const templateName = getBodyValue(body, 'template', 'name', 'idname', 'formid');
         const locale = getBodyValue(body, 'locale');
@@ -65,7 +89,7 @@ export class AssetAPI extends ApiModule {
         if (!rawFiles.length) {
             throw new ApiError({ code: 400, message: 'No files uploaded' });
         }
-        const body = apireq.req.body ?? {};
+        const body = (apireq.req.body ?? {});
         const subdir = normalizeSubdir(getBodyValue(body, 'path', 'dir'));
         const templateType = getBodyValue(body, 'templateType', 'template_type', 'type');
         let targetRoot;
@@ -101,15 +125,15 @@ export function createAssetHandler(server) {
                 next();
                 return;
             }
-            res.status(405).end();
+            res.status(405).send(null);
             return;
         }
-        const domain = decodeComponent(req?.params?.domain);
+        const domain = decodeComponent(req?.params?.['domain']);
         if (!domain || !DOMAIN_PATTERN.test(domain)) {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
-        const rawPathParam = req?.params?.path ?? req?.params?.[0];
+        const rawPathParam = req.params?.['path'] ?? req.params?.['*'];
         const rawSegments = Array.isArray(rawPathParam)
             ? rawPathParam
             : typeof rawPathParam === 'string'
@@ -117,12 +141,12 @@ export function createAssetHandler(server) {
                 : [];
         const segments = rawSegments.map((segment) => decodeComponent(typeof segment === 'string' ? segment : ''));
         if (!segments.length || segments.some((segment) => !SEGMENT_PATTERN.test(segment))) {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
         const assetsRoot = path.join(server.storage.configpath, domain, 'assets');
         if (!fs.existsSync(assetsRoot)) {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
         const resolvedRoot = fs.realpathSync(assetsRoot);
@@ -131,12 +155,12 @@ export function createAssetHandler(server) {
         try {
             const stats = await fs.promises.stat(candidate);
             if (!stats.isFile()) {
-                res.status(404).end();
+                res.status(404).send(null);
                 return;
             }
         }
         catch {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
         let realCandidate;
@@ -144,23 +168,29 @@ export function createAssetHandler(server) {
             realCandidate = await fs.promises.realpath(candidate);
         }
         catch {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
         if (!realCandidate.startsWith(normalizedRoot)) {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
-        res.type(path.extname(realCandidate));
+        const ext = path.extname(realCandidate);
+        // Access the underlying Fastify reply to set content-type and cache-control headers.
+        // ApiResponse does not expose arbitrary header-setting methods.
+        const fastifyReply = res.reply;
+        if (fastifyReply) {
+            fastifyReply.type(getMimeType(ext));
+            fastifyReply.header('cache-control', 'public, max-age=300');
+        }
         try {
-            // Express' `sendFile()` sets Cache-Control based on `maxAge` (in ms). Setting the header
-            // before calling `sendFile()` can be overwritten by Express defaults.
-            await sendFileAsync(res, realCandidate, { maxAge: 300_000 });
+            const content = await fs.promises.readFile(realCandidate);
+            res.send(content);
         }
         catch (err) {
             server.storage.print_debug(`Failed to serve asset ${domain}/${segments.join('/')}: ${err instanceof Error ? err.message : String(err)}`);
             if (!res.headersSent) {
-                res.status(500).end();
+                res.status(500).send(null);
             }
         }
     };

package/dist/esm/api/auth.d.ts

@@ -0,0 +1,2 @@
+import type { mailApiRequest } from '../types.js';
+export declare function assert_domain_and_user(apireq: mailApiRequest): Promise<void>;

package/dist/esm/api/auth.js

@@ -3,12 +3,9 @@ import { api_domain } from '../models/domain.js';
 import { api_user } from '../models/user.js';
 import { getBodyValue } from '../util/utils.js';
 export async function assert_domain_and_user(apireq) {
-    const body = apireq.req.body ?? {};
-    const domain = getBodyValue(body, 'domain');
+    const body = (apireq.req.body ?? {});
+    const domainRaw = getBodyValue(body, 'domain');
     const locale = getBodyValue(body, 'locale');
-    if (!domain) {
-        throw new ApiError({ code: 401, message: 'Missing domain' });
-    }
     const rawUid = apireq.getRealUid();
     const uid = rawUid === null ? null : Number(rawUid);
     if (!uid || Number.isNaN(uid)) {
@@ -18,12 +15,24 @@ export async function assert_domain_and_user(apireq) {
     if (!user) {
         throw new ApiError({ code: 401, message: 'Invalid/Unknown API Key/Token' });
     }
-    const dbdomain = await api_domain.findOne({ where: { name: domain } });
-    if (!dbdomain) {
-        throw new ApiError({ code: 401, message: `Unable to look up the domain ${domain}` });
+    let dbdomain;
+    if (domainRaw) {
+        dbdomain = await api_domain.findOne({ where: { name: domainRaw } });
+        if (!dbdomain) {
+            throw new ApiError({ code: 401, message: `Unable to look up the domain ${domainRaw}` });
+        }
+    }
+    else if (user.domain != null) {
+        dbdomain = await api_domain.findByPk(user.domain);
+        if (!dbdomain) {
+            throw new ApiError({ code: 401, message: 'Unable to resolve default domain for this user' });
+        }
+    }
+    else {
+        throw new ApiError({ code: 401, message: 'Missing domain' });
     }
     if (dbdomain.user_id !== user.user_id) {
-        throw new ApiError({ code: 403, message: `Domain ${domain} is not owned by this user` });
+        throw new ApiError({ code: 403, message: `Domain ${dbdomain.name} is not owned by this user` });
     }
     apireq.domain = dbdomain;
     apireq.user = user;

package/dist/esm/api/forms.d.ts

@@ -0,0 +1,9 @@
+import { ApiRoute, ApiModule } from '@technomoron/api-server-base';
+import { mailApiServer } from '../server.js';
+export declare class FormAPI extends ApiModule<mailApiServer> {
+    private readonly rateLimiter;
+    private postFormRecipient;
+    private postFormTemplate;
+    private postSendForm;
+    defineRoutes(): ApiRoute[];
+}

package/dist/esm/api/forms.js

@@ -1,11 +1,12 @@
 import { ApiModule, ApiError } from '@technomoron/api-server-base';
+import { convert } from 'html-to-text';
 import { nanoid } from 'nanoid';
 import nunjucks from 'nunjucks';
 import { UniqueConstraintError } from 'sequelize';
 import { api_domain } from '../models/domain.js';
 import { api_form } from '../models/form.js';
 import { api_recipient } from '../models/recipient.js';
-import { buildFormTemplateRecord, buildFormTemplatePaths, buildRecipientTo, buildReplyToValue, buildSubmissionContext, enforceAttachmentPolicy, enforceCaptchaPolicy, filterSubmissionFields, getPrimaryRecipientInfo, normalizeRecipientEmail, normalizeRecipientIdname, normalizeRecipientName, parseIdnameList, parseFormTemplatePayload, parseRecipientPayload, parsePublicSubmissionOrThrow, resolveFormKeyForTemplate, resolveFormKeyForRecipient, resolveRecipients, validateFormTemplatePayload } from '../util/forms.js';
+import { buildFormTemplateRecord, buildFormTemplatePaths, buildRecipientTo, buildReplyToValue, buildSubmissionContext, enforceAttachmentPolicy, enforceCaptchaPolicy, filterSubmissionFields, getPrimaryRecipientInfo, normalizeRecipientEmail, normalizeRecipientIdname, normalizeRecipientName, parseFormTemplatePayload, parseRecipientPayload, parsePublicSubmissionOrThrow, resolveFormKeyForTemplate, resolveFormKeyForRecipient, resolveRecipients, validateFormTemplatePayload } from '../util/forms.js';
 import { FixedWindowRateLimiter, enforceFormRateLimit } from '../util/ratelimit.js';
 import { buildAttachments, cleanupUploadedFiles } from '../util/uploads.js';
 import { getBodyValue } from '../util/utils.js';
@@ -61,7 +62,7 @@ export class FormAPI extends ApiModule {
     }
     async postFormTemplate(apireq) {
         await assert_domain_and_user(apireq);
-        const payload = parseFormTemplatePayload(apireq.req.body ?? {});
+        const payload = parseFormTemplatePayload((apireq.req.body ?? {}));
         validateFormTemplatePayload(payload);
         const user = apireq.user;
         const domain = apireq.domain;
@@ -139,7 +140,7 @@ export class FormAPI extends ApiModule {
             const clientIp = apireq.getClientIp() ?? '';
             await enforceCaptchaPolicy({ vars: env, form, captchaToken, clientIp });
             const resolvedRecipients = await resolveRecipients(form, recipientsRaw);
-            const recipients = parseIdnameList(recipientsRaw, 'recipients');
+            const recipients = resolvedRecipients.map((r) => r.idname ?? '').filter(Boolean);
             const { rcptEmail, rcptName, rcptIdname, rcptIdnames } = getPrimaryRecipientInfo(form, resolvedRecipients);
             const domainRecord = await api_domain.findOne({ where: { domain_id: form.domain_id } });
             await this.server.storage.relocateUploads(domainRecord?.name ?? null, rawFiles);
@@ -171,13 +172,15 @@ export class FormAPI extends ApiModule {
                 files: rawFiles,
                 meta
             });
-            nunjucks.configure({ autoescape: this.server.storage.vars.AUTOESCAPE_HTML });
-            const html = nunjucks.renderString(form.template, context);
+            const njkEnv = new nunjucks.Environment(null, { autoescape: this.server.storage.vars.AUTOESCAPE_HTML });
+            const html = njkEnv.renderString(form.template, context);
+            const text = convert(html);
             const mailOptions = {
                 from: form.sender,
                 to,
                 subject: form.subject,
                 html,
+                text,
                 attachments: allAttachments,
                 ...(replyToValue ? { replyTo: replyToValue } : {})
             };
@@ -204,13 +207,45 @@ export class FormAPI extends ApiModule {
                 method: 'post',
                 path: '/v1/form/recipient',
                 handler: (req) => this.postFormRecipient(req),
-                auth: { type: 'yes', req: 'any' }
+                auth: { type: 'yes', req: 'any' },
+                schema: {
+                    body: {
+                        type: 'object',
+                        required: ['email', 'idname'],
+                        properties: {
+                            email: { type: 'string' },
+                            idname: { type: 'string' },
+                            name: { type: 'string' },
+                            form_key: { type: 'string' },
+                            formid: { type: 'string' },
+                            locale: { type: 'string' },
+                            domain: { type: 'string' }
+                        },
+                        additionalProperties: true
+                    }
+                }
             },
             {
                 method: 'post',
                 path: '/v1/form/template',
                 handler: (req) => this.postFormTemplate(req),
-                auth: { type: 'yes', req: 'any' }
+                auth: { type: 'yes', req: 'any' },
+                schema: {
+                    body: {
+                        type: 'object',
+                        required: ['idname', 'template', 'sender', 'recipient'],
+                        properties: {
+                            idname: { type: 'string' },
+                            template: { type: 'string' },
+                            sender: { type: 'string' },
+                            recipient: { type: 'string' },
+                            subject: { type: 'string' },
+                            locale: { type: 'string' },
+                            domain: { type: 'string' }
+                        },
+                        additionalProperties: true
+                    }
+                }
             },
             {
                 method: 'post',

package/dist/esm/api/mailer.d.ts

@@ -0,0 +1,11 @@
+import { ApiModule, ApiRoute } from '@technomoron/api-server-base';
+import { mailApiServer } from '../server.js';
+export declare class MailerAPI extends ApiModule<mailApiServer> {
+    validateEmails(list: string): {
+        valid: string[];
+        invalid: string[];
+    };
+    private post_template;
+    private post_send;
+    defineRoutes(): ApiRoute[];
+}

package/dist/esm/api/mailer.js

@@ -31,7 +31,12 @@ export class MailerAPI extends ApiModule {
     // Store a template in the database
     async post_template(apireq) {
         await assert_domain_and_user(apireq);
-        const { template, sender = '', name, subject = '', locale = '' } = apireq.req.body;
+        const body = apireq.req.body;
+        const template = String(body.template ?? '');
+        const sender = String(body.sender ?? '');
+        const name = String(body.name ?? '');
+        const subject = String(body.subject ?? '');
+        const locale = String(body.locale ?? '');
         if (!template) {
             throw new ApiError({ code: 400, message: 'Missing template data' });
         }
@@ -63,10 +68,17 @@ export class MailerAPI extends ApiModule {
     }
     // Send a template using posted arguments.
     async post_send(apireq) {
-        const { name, rcpt, domain = '', locale = '', vars = {}, replyTo, reply_to, headers } = apireq.req.body;
+        const body = apireq.req.body;
+        const name = String(body.name ?? '');
+        const rcpt = String(body.rcpt ?? '');
+        const locale = String(body.locale ?? '');
+        const vars = body.vars ?? {};
+        const replyTo = body.replyTo;
+        const reply_to = body.reply_to;
+        const headers = body.headers;
         await assert_domain_and_user(apireq);
-        if (!name || !rcpt || !domain) {
-            throw new ApiError({ code: 400, message: 'name/rcpt/domain required' });
+        if (!name || !rcpt) {
+            throw new ApiError({ code: 400, message: 'name/rcpt required' });
         }
         let parsedVars = vars ?? {};
         if (typeof vars === 'string') {
@@ -98,7 +110,7 @@ export class MailerAPI extends ApiModule {
         if (!template) {
             throw new ApiError({
                 code: 404,
-                message: `Template "${name}" not found for any locale in domain "${domain}"`
+                message: `Template "${name}" not found for any locale in domain "${apireq.domain.name}"`
             });
         }
         const sender = template.sender || apireq.domain.sender || apireq.user.email;
@@ -116,7 +128,7 @@ export class MailerAPI extends ApiModule {
             })),
             ...rawFiles.map((file) => ({
                 filename: file.originalname,
-                path: file.path
+                ...(file.buffer ? { content: file.buffer } : { path: file.filepath })
             }))
         ];
         const attachmentMap = {};
@@ -162,7 +174,7 @@ export class MailerAPI extends ApiModule {
                 const sendargs = {
                     from: sender,
                     to: recipient,
-                    subject: template.subject || apireq.req.body.subject || '',
+                    subject: template.subject || body.subject || '',
                     html,
                     text,
                     attachments,
@@ -186,13 +198,30 @@ export class MailerAPI extends ApiModule {
                 method: 'post',
                 path: '/v1/tx/message',
                 handler: this.post_send.bind(this),
+                // No schema: this route accepts multipart/form-data; Fastify validates request.body
+                // before the multipart parsing hook populates it, so schema required-fields would
+                // reject valid multipart requests. Validation is handled in the route handler.
                 auth: { type: 'yes', req: 'any' }
             },
             {
                 method: 'post',
                 path: '/v1/tx/template',
                 handler: this.post_template.bind(this),
-                auth: { type: 'yes', req: 'any' }
+                auth: { type: 'yes', req: 'any' },
+                schema: {
+                    body: {
+                        type: 'object',
+                        required: ['name', 'template'],
+                        properties: {
+                            name: { type: 'string' },
+                            template: { type: 'string' },
+                            sender: { type: 'string' },
+                            subject: { type: 'string' },
+                            locale: { type: 'string' }
+                        },
+                        additionalProperties: true
+                    }
+                }
             }
         ];
     }

package/dist/esm/bin/mail-magic.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/esm/index.d.ts

@@ -0,0 +1,12 @@
+import { mailApiServer } from './server.js';
+import { MailStoreVars, mailStore } from './store/store.js';
+import type { ApiServerConf } from '@technomoron/api-server-base';
+export type MailMagicServerOptions = Partial<ApiServerConf>;
+export type MailMagicServerBootstrap = {
+    server: mailApiServer;
+    store: mailStore;
+    vars: MailStoreVars;
+};
+export declare const STARTUP_ERROR_MESSAGE = "Failed to start mail-magic:";
+export declare function createMailMagicServer(overrides?: MailMagicServerOptions, envOverrides?: Partial<MailStoreVars>): Promise<MailMagicServerBootstrap>;
+export declare function startMailMagicServer(overrides?: MailMagicServerOptions, envOverrides?: Partial<MailStoreVars>): Promise<MailMagicServerBootstrap>;

package/dist/esm/index.js

@@ -25,6 +25,8 @@ function buildServerConfig(store, overrides) {
         apiBasePath: normalizeRoute(env.API_BASE_PATH, '/api'),
         swaggerEnabled: env.SWAGGER_ENABLED,
         swaggerPath: env.SWAGGER_PATH,
+        apiKeyEnabled: true,
+        apiKeyPrefix: 'apikey-',
         ...overrides
     };
 }
@@ -71,10 +73,9 @@ export async function createMailMagicServer(overrides = {}, envOverrides = {}) {
         assetMounts.add(`${apiBasePrefix}${assetPrefix}`);
     }
     for (const prefix of assetMounts) {
-        // Express 5 (path-to-regexp v8) requires wildcard params to be named.
-        // Use ApiServer.useExpress() so mounts under `apiBasePath` are installed on the API router
-        // (and remain reachable before the API 404 handler).
-        server.useExpress(`${prefix}/:domain/*path`, assetHandler);
+        // Use ApiServer.useExpress() so mounts under `apiBasePath` are installed before the API
+        // 404 handler. Fastify (find-my-way) requires the wildcard to be an unnamed `*`.
+        server.useExpress(`${prefix}/:domain/*`, assetHandler);
     }
     if (store.vars.ADMIN_ENABLED) {
         await enableAdminFeatures(server, store, adminUiPath);

package/dist/esm/models/db.d.ts

@@ -0,0 +1,5 @@
+import { Sequelize } from 'sequelize';
+import { mailStore } from '../store/store.js';
+export declare function usesSqlitePragmas(db: Pick<Sequelize, 'getDialect'>): boolean;
+export declare function init_api_db(db: Sequelize, store: mailStore): Promise<void>;
+export declare function connect_api_db(store: mailStore): Promise<Sequelize>;

package/dist/esm/models/domain.d.ts

@@ -0,0 +1,24 @@
+import { Sequelize, Model } from 'sequelize';
+import { z } from 'zod';
+export declare const api_domain_schema: z.ZodObject<{
+    domain_id: z.ZodNumber;
+    user_id: z.ZodNumber;
+    name: z.ZodString;
+    sender: z.ZodDefault<z.ZodString>;
+    locale: z.ZodDefault<z.ZodString>;
+    is_default: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type api_domain_input = z.input<typeof api_domain_schema>;
+export type api_domain_type = z.output<typeof api_domain_schema>;
+export type api_domain_creation_type = Omit<api_domain_input, 'domain_id'> & {
+    domain_id?: number;
+};
+export declare class api_domain extends Model<api_domain_type, api_domain_creation_type> {
+    domain_id: number;
+    user_id: number;
+    name: string;
+    sender: string;
+    locale: string;
+    is_default: boolean;
+}
+export declare function init_api_domain(api_db: Sequelize): Promise<typeof api_domain>;

package/dist/esm/models/form.d.ts

@@ -0,0 +1,50 @@
+import { Sequelize, Model } from 'sequelize';
+import { z } from 'zod';
+import { StoredFile } from '../types.js';
+export declare const api_form_schema: z.ZodObject<{
+    form_id: z.ZodNumber;
+    form_key: z.ZodDefault<z.ZodString>;
+    user_id: z.ZodNumber;
+    domain_id: z.ZodNumber;
+    locale: z.ZodDefault<z.ZodString>;
+    idname: z.ZodString;
+    sender: z.ZodString;
+    recipient: z.ZodString;
+    subject: z.ZodString;
+    template: z.ZodDefault<z.ZodString>;
+    filename: z.ZodDefault<z.ZodString>;
+    slug: z.ZodDefault<z.ZodString>;
+    secret: z.ZodDefault<z.ZodString>;
+    replyto_email: z.ZodDefault<z.ZodString>;
+    replyto_from_fields: z.ZodDefault<z.ZodBoolean>;
+    allowed_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    captcha_required: z.ZodDefault<z.ZodBoolean>;
+    files: z.ZodDefault<z.ZodArray<z.ZodType<StoredFile, unknown, z.core.$ZodTypeInternals<StoredFile, unknown>>>>;
+}, z.core.$strip>;
+export type api_form_input = z.input<typeof api_form_schema>;
+export type api_form_type = z.output<typeof api_form_schema>;
+export type api_form_creation_type = Omit<api_form_input, 'form_id'> & {
+    form_id?: number;
+};
+export declare class api_form extends Model<api_form_type, api_form_creation_type> {
+    form_id: number;
+    form_key: string;
+    user_id: number;
+    domain_id: number;
+    locale: string;
+    idname: string;
+    sender: string;
+    recipient: string;
+    subject: string;
+    template: string;
+    filename: string;
+    slug: string;
+    secret: string;
+    replyto_email: string;
+    replyto_from_fields: boolean;
+    allowed_fields: string[];
+    captcha_required: boolean;
+    files: StoredFile[];
+}
+export declare function init_api_form(api_db: Sequelize): Promise<typeof api_form>;
+export declare function upsert_form(record: api_form_type): Promise<api_form>;