@technomoron/mail-magic 1.0.40 → 1.0.42

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

@@ -0,0 +1,140 @@
+import { ApiRequest } from '@technomoron/api-server-base';
+import { api_form } from '../models/form.js';
+import { api_recipient } from '../models/recipient.js';
+import { ParsedFormSubmission } from './form-submission.js';
+import type { api_domain } from '../models/domain.js';
+import type { api_user } from '../models/user.js';
+import type { RequestMeta, UploadedFile } from '../types.js';
+export declare function parsePublicSubmissionOrThrow(apireq: ApiRequest): ParsedFormSubmission;
+export declare function enforceAttachmentPolicy(env: {
+    FORM_MAX_ATTACHMENTS: number;
+}, rawFiles: UploadedFile[]): void;
+export declare function filterSubmissionFields(rawFields: Record<string, unknown>, allowedFields: unknown): Record<string, unknown>;
+export declare function enforceCaptchaPolicy(params: {
+    vars: {
+        FORM_CAPTCHA_REQUIRED: boolean;
+        FORM_CAPTCHA_SECRET: string;
+        FORM_CAPTCHA_PROVIDER: string;
+    };
+    form: {
+        captcha_required: boolean;
+    };
+    captchaToken: string;
+    clientIp: string;
+}): Promise<void>;
+export declare function buildReplyToValue(form: {
+    replyto_email: string;
+    replyto_from_fields: boolean;
+}, fields: Record<string, unknown>): (string | {
+    name: string;
+    address: string;
+}) | undefined;
+export declare function parseIdnameList(value: unknown, field: string): string[];
+export type FormRecipientPayload = {
+    idnameRaw: string;
+    emailRaw: string;
+    nameRaw: string;
+    formKeyRaw: string;
+    formid: string;
+    localeRaw: string;
+};
+export declare function parseRecipientPayload(body: Record<string, unknown>): FormRecipientPayload;
+export declare function normalizeRecipientIdname(raw: string): string;
+export declare function normalizeRecipientEmail(raw: string): {
+    email: string;
+    mailbox: {
+        address: string;
+        name?: string | null;
+    };
+};
+export declare function normalizeRecipientName(raw: string, mailboxName?: string | null): string;
+export declare function resolveFormKeyForRecipient(params: {
+    formKeyRaw: string;
+    formid: string;
+    localeRaw: string;
+    user: api_user;
+    domain: api_domain;
+}): Promise<string>;
+export declare function parseAllowedFields(raw: unknown): string[];
+export type FormTemplateInput = {
+    template: string;
+    sender: string;
+    recipient: string;
+    idname: string;
+    subject: string;
+    locale: string;
+    secret: string;
+    replyto_email: string;
+    replyto_from_fields: boolean;
+    allowed_fields: string[];
+    captcha_required: boolean;
+};
+export declare function parseFormTemplatePayload(body: Record<string, unknown>): FormTemplateInput;
+export declare function validateFormTemplatePayload(payload: FormTemplateInput): void;
+export declare function buildFormTemplatePaths(params: {
+    user: api_user;
+    domain: api_domain;
+    idname: string;
+    locale: string;
+}): {
+    localeSlug: string;
+    slug: string;
+    filename: string;
+};
+export declare function resolveFormKeyForTemplate(params: {
+    user_id: number;
+    domain_id: number;
+    locale: string;
+    idname: string;
+}): Promise<string>;
+export declare function buildFormTemplateRecord(params: {
+    form_key: string;
+    user_id: number;
+    domain_id: number;
+    locale: string;
+    slug: string;
+    filename: string;
+    payload: FormTemplateInput;
+}): {
+    form_key: string;
+    user_id: number;
+    domain_id: number;
+    locale: string;
+    idname: string;
+    sender: string;
+    recipient: string;
+    subject: string;
+    template: string;
+    slug: string;
+    filename: string;
+    secret: string;
+    replyto_email: string;
+    replyto_from_fields: boolean;
+    allowed_fields: string[];
+    captcha_required: boolean;
+    files: never[];
+};
+export declare function resolveRecipients(form: api_form, recipientsRaw: unknown): Promise<api_recipient[]>;
+export declare function buildRecipientTo(form: api_form, recipients: api_recipient[]): string | (string | {
+    name: string;
+    address: string;
+})[];
+export declare function getPrimaryRecipientInfo(form: api_form, recipients: api_recipient[]): {
+    rcptEmail: string;
+    rcptName: string;
+    rcptIdname: string;
+    rcptIdnames: string[];
+};
+export declare function buildSubmissionContext(params: {
+    form_key: string;
+    localeRaw: string;
+    recipients: string[];
+    rcptEmail: string;
+    rcptName: string;
+    rcptIdname: string;
+    rcptIdnames: string[];
+    attachmentMap: Record<string, string>;
+    fields: Record<string, unknown>;
+    files: UploadedFile[];
+    meta: RequestMeta;
+}): Record<string, unknown>;

package/dist/esm/util/forms.js

@@ -1,11 +1,12 @@
-import path from 'path';
 import { ApiError } from '@technomoron/api-server-base';
+import { Op } from 'sequelize';
 import { api_form } from '../models/form.js';
 import { api_recipient } from '../models/recipient.js';
 import { verifyCaptcha } from './captcha.js';
 import { parseMailbox } from './email.js';
 import { extractReplyToFromSubmission } from './form-replyto.js';
 import { parseFormSubmissionInput } from './form-submission.js';
+import { buildFormSlugAndFilename } from './paths.js';
 import { normalizeBoolean, normalizeSlug } from './utils.js';
 export function parsePublicSubmissionOrThrow(apireq) {
     try {
@@ -297,36 +298,24 @@ export function validateFormTemplatePayload(payload) {
     }
 }
 export function buildFormTemplatePaths(params) {
-    const domainSlug = normalizeSlug(params.domain.name);
-    const formSlug = normalizeSlug(params.idname);
-    const localeSlug = normalizeSlug(params.locale || params.domain.locale || params.user.locale || '');
-    const slug = `${domainSlug}${localeSlug ? '-' + localeSlug : ''}-${formSlug}`;
-    const filenameParts = [domainSlug, 'form-template'];
-    if (localeSlug) {
-        filenameParts.push(localeSlug);
-    }
-    filenameParts.push(formSlug);
-    let filename = path.join(...filenameParts);
-    if (!filename.endsWith('.njk')) {
-        filename += '.njk';
-    }
-    return { localeSlug, slug, filename };
+    return buildFormSlugAndFilename({
+        domainName: params.domain.name,
+        domainLocale: params.domain.locale,
+        userLocale: params.user.locale,
+        idname: params.idname,
+        locale: params.locale
+    });
 }
 export async function resolveFormKeyForTemplate(params) {
-    try {
-        const existing = await api_form.findOne({
-            where: {
-                user_id: params.user_id,
-                domain_id: params.domain_id,
-                locale: params.locale,
-                idname: params.idname
-            }
-        });
-        return existing?.form_key || '';
-    }
-    catch {
-        return '';
-    }
+    const existing = await api_form.findOne({
+        where: {
+            user_id: params.user_id,
+            domain_id: params.domain_id,
+            locale: params.locale,
+            idname: params.idname
+        }
+    });
+    return existing?.form_key || '';
 }
 export function buildFormTemplateRecord(params) {
     return {
@@ -354,22 +343,36 @@ export async function resolveRecipients(form, recipientsRaw) {
     if (!scopeFormKey) {
         throw new ApiError({ code: 500, message: 'Form is missing a form_key' });
     }
-    const resolveRecipient = async (idname) => {
-        const scoped = await api_recipient.findOne({
-            where: { domain_id: form.domain_id, form_key: scopeFormKey, idname }
-        });
-        if (scoped) {
-            return scoped;
-        }
-        return api_recipient.findOne({ where: { domain_id: form.domain_id, form_key: '', idname } });
-    };
     const recipients = parseIdnameList(recipientsRaw, 'recipients');
     if (recipients.length > 25) {
         throw new ApiError({ code: 400, message: 'Too many recipients requested' });
     }
+    if (recipients.length === 0) {
+        return [];
+    }
+    const scopedMatches = await api_recipient.findAll({
+        where: {
+            domain_id: form.domain_id,
+            form_key: scopeFormKey,
+            idname: { [Op.in]: recipients }
+        }
+    });
+    const scopedByIdname = new Map(scopedMatches.map((entry) => [entry.idname, entry]));
+    const unresolved = recipients.filter((idname) => !scopedByIdname.has(idname));
+    let fallbackByIdname = new Map();
+    if (unresolved.length > 0) {
+        const fallbackMatches = await api_recipient.findAll({
+            where: {
+                domain_id: form.domain_id,
+                form_key: '',
+                idname: { [Op.in]: unresolved }
+            }
+        });
+        fallbackByIdname = new Map(fallbackMatches.map((entry) => [entry.idname, entry]));
+    }
     const resolvedRecipients = [];
     for (const idname of recipients) {
-        const record = await resolveRecipient(idname);
+        const record = scopedByIdname.get(idname) ?? fallbackByIdname.get(idname) ?? null;
         if (!record) {
             throw new ApiError({ code: 404, message: `Unknown recipient identifier "${idname}"` });
         }

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

@@ -0,0 +1,15 @@
+export declare const SEGMENT_PATTERN: RegExp;
+export declare function normalizeSubdir(value: string): string;
+export declare function assertSafeRelativePath(filename: string, label: string): string;
+export declare function buildFormSlugAndFilename(params: {
+    domainName: string;
+    domainLocale: string;
+    userLocale: string;
+    idname: string;
+    locale: string;
+}): {
+    localeSlug: string;
+    slug: string;
+    filename: string;
+};
+export declare function buildAssetUrl(baseUrl: string, route: string, domainName: string, assetPath: string): string;

package/dist/esm/util/paths.js

@@ -1,5 +1,6 @@
 import path from 'path';
 import { ApiError } from '@technomoron/api-server-base';
+import { normalizeSlug } from './utils.js';
 export const SEGMENT_PATTERN = /^[a-zA-Z0-9._-]+$/;
 export function normalizeSubdir(value) {
     if (!value) {
@@ -27,6 +28,22 @@ export function assertSafeRelativePath(filename, label) {
     }
     return normalized;
 }
+export function buildFormSlugAndFilename(params) {
+    const domainSlug = normalizeSlug(params.domainName);
+    const formSlug = normalizeSlug(params.idname);
+    const localeSlug = normalizeSlug(params.locale || params.domainLocale || params.userLocale || '');
+    const slug = `${domainSlug}${localeSlug ? '-' + localeSlug : ''}-${formSlug}`;
+    const filenameParts = [domainSlug, 'form-template'];
+    if (localeSlug) {
+        filenameParts.push(localeSlug);
+    }
+    filenameParts.push(formSlug);
+    let filename = path.join(...filenameParts);
+    if (!filename.endsWith('.njk')) {
+        filename += '.njk';
+    }
+    return { localeSlug, slug, filename };
+}
 export function buildAssetUrl(baseUrl, route, domainName, assetPath) {
     const trimmedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
     const normalizedRoute = route ? (route.startsWith('/') ? route : `/${route}`) : '';

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

@@ -0,0 +1,7 @@
+import { ApiRequest, FixedWindowRateLimiter } from '@technomoron/api-server-base';
+export { FixedWindowRateLimiter };
+export type { RateLimitDecision } from '@technomoron/api-server-base';
+export declare function enforceFormRateLimit(limiter: FixedWindowRateLimiter, env: {
+    FORM_RATE_LIMIT_WINDOW_SEC: number;
+    FORM_RATE_LIMIT_MAX: number;
+}, apireq: ApiRequest): void;

package/dist/esm/util/ratelimit.js

@@ -1,48 +1,17 @@
-import { ApiError } from '@technomoron/api-server-base';
-export class FixedWindowRateLimiter {
-    maxKeys;
-    buckets = new Map();
-    constructor(maxKeys = 10_000) {
-        this.maxKeys = maxKeys;
-    }
-    check(key, max, windowMs) {
-        if (!key || max <= 0 || windowMs <= 0) {
-            return { allowed: true, retryAfterSec: 0 };
-        }
-        const now = Date.now();
-        const bucket = this.buckets.get(key);
-        if (!bucket || now - bucket.windowStartMs >= windowMs) {
-            this.buckets.delete(key);
-            this.buckets.set(key, { windowStartMs: now, count: 1 });
-            this.prune();
-            return { allowed: true, retryAfterSec: 0 };
-        }
-        bucket.count += 1;
-        // Refresh insertion order to keep active entries at the end for pruning.
-        this.buckets.delete(key);
-        this.buckets.set(key, bucket);
-        if (bucket.count <= max) {
-            return { allowed: true, retryAfterSec: 0 };
-        }
-        const retryAfterSec = Math.max(1, Math.ceil((bucket.windowStartMs + windowMs - now) / 1000));
-        return { allowed: false, retryAfterSec };
-    }
-    prune() {
-        while (this.buckets.size > this.maxKeys) {
-            const oldest = this.buckets.keys().next().value;
-            if (!oldest) {
-                break;
-            }
-            this.buckets.delete(oldest);
-        }
-    }
-}
+import { ApiError, FixedWindowRateLimiter } from '@technomoron/api-server-base';
+export { FixedWindowRateLimiter };
 export function enforceFormRateLimit(limiter, env, apireq) {
     const clientIp = apireq.getClientIp() ?? '';
+    if (!clientIp) {
+        // Cannot rate-limit without a resolvable client IP; skip to avoid collapsing
+        // all IP-unknown requests into a single shared bucket.
+        return;
+    }
     const windowMs = Math.max(0, env.FORM_RATE_LIMIT_WINDOW_SEC) * 1000;
-    const decision = limiter.check(`form-message:${clientIp || 'unknown'}`, env.FORM_RATE_LIMIT_MAX, windowMs);
+    const decision = limiter.check(`form-message:${clientIp}`, env.FORM_RATE_LIMIT_MAX, windowMs);
     if (!decision.allowed) {
-        apireq.res.set('Retry-After', String(decision.retryAfterSec));
+        const fastifyReply = apireq.res.reply;
+        fastifyReply?.header('retry-after', String(decision.retryAfterSec));
         throw new ApiError({ code: 429, message: 'Too many form submissions; try again later' });
     }
 }

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

@@ -0,0 +1 @@
+export declare function normalizeRoute(value: string, fallback?: string): string;

package/dist/esm/util/shared-template-flatten.d.ts

@@ -0,0 +1,17 @@
+export type FlattenedAsset = {
+    filename: string;
+    path: string;
+    cid?: string;
+};
+export type FlattenWithAssetsOptions = {
+    domainRoot: string;
+    templateKey: string;
+    baseUrl: string;
+    assetFormatter: (urlPath: string) => string;
+    normalizeInlineCid?: (urlPath: string) => string;
+};
+export type FlattenWithAssetsResult = {
+    html: string;
+    assets: FlattenedAsset[];
+};
+export declare function flattenTemplateWithAssets(options: FlattenWithAssetsOptions): FlattenWithAssetsResult;

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

@@ -0,0 +1,11 @@
+import type { UploadedFile } from '../types.js';
+export declare function buildAttachments(rawFiles: UploadedFile[]): {
+    attachments: Array<{
+        filename: string;
+        path?: string;
+        content?: Buffer;
+    }>;
+    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/uploads.js

@@ -5,7 +5,7 @@ import { SEGMENT_PATTERN } from './paths.js';
 export function buildAttachments(rawFiles) {
     const attachments = rawFiles.map((file) => ({
         filename: file.originalname,
-        path: file.path
+        ...(file.buffer ? { content: file.buffer } : { path: file.filepath })
     }));
     const attachmentMap = {};
     for (const file of rawFiles) {
@@ -15,11 +15,11 @@ export function buildAttachments(rawFiles) {
 }
 export async function cleanupUploadedFiles(files) {
     await Promise.all(files.map(async (file) => {
-        if (!file?.path) {
+        if (!file?.filepath) {
             return;
         }
         try {
-            await fs.promises.unlink(file.path);
+            await fs.promises.unlink(file.filepath);
         }
         catch {
             // best effort cleanup
@@ -34,15 +34,20 @@ export async function moveUploadedFiles(files, targetDir) {
             throw new ApiError({ code: 400, message: `Invalid filename "${file.originalname}"` });
         }
         const destination = path.join(targetDir, filename);
-        if (destination === file.path) {
-            continue;
+        if (file.buffer) {
+            await fs.promises.writeFile(destination, file.buffer);
         }
-        try {
-            await fs.promises.rename(file.path, destination);
-        }
-        catch {
-            await fs.promises.copyFile(file.path, destination);
-            await fs.promises.unlink(file.path);
+        else if (file.filepath) {
+            if (destination === file.filepath) {
+                continue;
+            }
+            try {
+                await fs.promises.rename(file.filepath, destination);
+            }
+            catch {
+                await fs.promises.copyFile(file.filepath, destination);
+                await fs.promises.unlink(file.filepath);
+            }
         }
     }
 }

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

@@ -0,0 +1,25 @@
+import { api_domain } from '../models/domain.js';
+import { api_user } from '../models/user.js';
+import type { RequestMeta } from '../types.js';
+/**
+ * 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;

package/dist/esm/util/utils.js

@@ -131,21 +131,3 @@ export function normalizeBoolean(value) {
         .toLowerCase();
     return ['true', '1', 'yes', 'on'].includes(normalized);
 }
-export function sendFileAsync(res, file, options) {
-    return new Promise((resolve, reject) => {
-        const cb = (err) => {
-            if (err) {
-                reject(err instanceof Error ? err : new Error(String(err)));
-            }
-            else {
-                resolve();
-            }
-        };
-        if (options !== undefined) {
-            // Express will set Cache-Control based on `maxAge` etc; callers can still override.
-            res.sendFile(file, options, cb);
-            return;
-        }
-        res.sendFile(file, cb);
-    });
-}

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.42",
 		"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