@technomoron/mail-magic 1.0.32 → 1.0.34

package/dist/index.js

@@ -4,6 +4,7 @@ import { FormAPI } from './api/forms.js';
 import { MailerAPI } from './api/mailer.js';
 import { mailApiServer } from './server.js';
 import { mailStore } from './store/store.js';
+import { installMailMagicSwagger } from './swagger.js';
 function normalizeRoute(value, fallback = '') {
     if (!value) {
         return fallback;
@@ -26,7 +27,7 @@ function mergeStaticDirs(base, override) {
     return merged;
 }
 function buildServerConfig(store, overrides) {
-    const env = store.env;
+    const env = store.vars;
     return {
         apiHost: env.API_HOST,
         apiPort: env.API_PORT,
@@ -39,14 +40,14 @@ function buildServerConfig(store, overrides) {
         ...overrides
     };
 }
-export async function createMailMagicServer(overrides = {}) {
-    const store = await new mailStore().init();
+export async function createMailMagicServer(overrides = {}, envOverrides = {}) {
+    const store = await new mailStore().init(envOverrides);
     if (typeof overrides.apiBasePath === 'string') {
-        store.env.API_BASE_PATH = overrides.apiBasePath;
+        store.vars.API_BASE_PATH = overrides.apiBasePath;
     }
     const baseStaticDirs = {};
     let adminUiPath = null;
-    if (store.env.ADMIN_ENABLED) {
+    if (store.vars.ADMIN_ENABLED) {
         adminUiPath = await resolveAdminUiPath(store);
         if (adminUiPath) {
             baseStaticDirs['/'] = adminUiPath;
@@ -57,11 +58,22 @@ export async function createMailMagicServer(overrides = {}) {
         staticDirs: mergeStaticDirs(baseStaticDirs, overrides.staticDirs)
     };
     const config = buildServerConfig(store, mergedOverrides);
-    const server = new mailApiServer(config, store).api(new MailerAPI()).api(new FormAPI()).api(new AssetAPI());
+    // ApiServerBase's built-in swagger handler loads from process.cwd(); install our own handler so
+    // SWAGGER_ENABLED works regardless of where the .env lives (mail-magic CLI chdir's to the env dir).
+    const { swaggerEnabled, swaggerPath } = config;
+    const serverConfig = { ...config, swaggerEnabled: false, swaggerPath: '' };
+    const server = new mailApiServer(serverConfig, store).api(new MailerAPI()).api(new FormAPI()).api(new AssetAPI());
+    installMailMagicSwagger(server, {
+        apiBasePath: String(config.apiBasePath || '/api'),
+        assetRoute: String(store.vars.ASSET_ROUTE || '/asset'),
+        apiUrl: String(store.vars.API_URL || ''),
+        swaggerEnabled,
+        swaggerPath
+    });
     // Serve domain assets from a public route with traversal protection and caching.
-    const assetRoute = normalizeRoute(store.env.ASSET_ROUTE, '/asset');
+    const assetRoute = normalizeRoute(store.vars.ASSET_ROUTE, '/asset');
     const assetPrefix = assetRoute === '/' ? '' : assetRoute;
-    const apiBasePath = normalizeRoute(store.env.API_BASE_PATH, '/api');
+    const apiBasePath = normalizeRoute(store.vars.API_BASE_PATH, '/api');
     const apiBasePrefix = apiBasePath === '/' ? '' : apiBasePath;
     const assetHandler = createAssetHandler(server);
     const assetMounts = new Set();
@@ -76,23 +88,23 @@ export async function createMailMagicServer(overrides = {}) {
         // (and remain reachable before the API 404 handler).
         server.useExpress(`${prefix}/:domain/*path`, assetHandler);
     }
-    if (store.env.ADMIN_ENABLED) {
+    if (store.vars.ADMIN_ENABLED) {
         await enableAdminFeatures(server, store, adminUiPath);
     }
     else {
         store.print_debug('Admin UI/API disabled via ADMIN_ENABLED');
     }
-    return { server, store, env: store.env };
+    return { server, store, vars: store.vars };
 }
-export async function startMailMagicServer(overrides = {}) {
-    const bootstrap = await createMailMagicServer(overrides);
+export async function startMailMagicServer(overrides = {}, envOverrides = {}) {
+    const bootstrap = await createMailMagicServer(overrides, envOverrides);
     await bootstrap.server.start();
     return bootstrap;
 }
 async function bootMailMagic() {
     try {
-        const { env } = await startMailMagicServer();
-        console.log(`mail-magic server listening on ${env.API_HOST}:${env.API_PORT}`);
+        const { vars } = await startMailMagicServer();
+        console.log(`mail-magic server listening on ${vars.API_HOST}:${vars.API_PORT}`);
     }
     catch (err) {
         console.error('Failed to start FormMailer:', err);
@@ -117,7 +129,7 @@ async function resolveAdminUiPath(store) {
     try {
         const mod = (await import('@technomoron/mail-magic-admin'));
         if (typeof mod?.resolveAdminDist === 'function') {
-            return mod.resolveAdminDist(store.env.ADMIN_APP_PATH, (message) => store.print_debug(message));
+            return mod.resolveAdminDist(store.vars.ADMIN_APP_PATH, (message) => store.print_debug(message));
         }
     }
     catch (err) {
@@ -130,9 +142,9 @@ async function enableAdminFeatures(server, store, adminUiPath) {
         const mod = (await import('@technomoron/mail-magic-admin'));
         if (typeof mod?.registerAdmin === 'function') {
             await mod.registerAdmin(server, {
-                apiBasePath: normalizeRoute(store.env.API_BASE_PATH, '/api'),
-                assetRoute: normalizeRoute(store.env.ASSET_ROUTE, '/asset'),
-                appPath: adminUiPath ?? store.env.ADMIN_APP_PATH,
+                apiBasePath: normalizeRoute(store.vars.API_BASE_PATH, '/api'),
+                assetRoute: normalizeRoute(store.vars.ASSET_ROUTE, '/asset'),
+                appPath: adminUiPath ?? store.vars.ADMIN_APP_PATH,
                 logger: (message) => store.print_debug(message),
                 staticFallback: Boolean(adminUiPath)
             });

package/dist/models/db.js

@@ -72,13 +72,13 @@ export async function init_api_db(db, store) {
         as: 'domain'
     });
     await db.query('PRAGMA foreign_keys = OFF');
-    const alter = Boolean(store.env.DB_SYNC_ALTER);
-    store.print_debug(`DB sync: alter=${alter} force=${store.env.DB_FORCE_SYNC}`);
-    await db.sync({ alter, force: store.env.DB_FORCE_SYNC });
+    const alter = Boolean(store.vars.DB_SYNC_ALTER);
+    store.print_debug(`DB sync: alter=${alter} force=${store.vars.DB_FORCE_SYNC}`);
+    await db.sync({ alter, force: store.vars.DB_FORCE_SYNC });
     await db.query('PRAGMA foreign_keys = ON');
     await importData(store);
     try {
-        const { migrated, cleared } = await migrateLegacyApiTokens(store.env.API_TOKEN_PEPPER);
+        const { migrated, cleared } = await migrateLegacyApiTokens(store.vars.API_TOKEN_PEPPER);
         if (migrated || cleared) {
             store.print_debug(`Migrated ${migrated} legacy API token(s) and cleared ${cleared} plaintext token(s).`);
         }
@@ -90,7 +90,7 @@ export async function init_api_db(db, store) {
 }
 export async function connect_api_db(store) {
     console.log('DB INIT');
-    const env = store.env;
+    const env = store.vars;
     const dbparams = {
         logging: false, // env.DB_LOG ? console.log : false,
         dialect: env.DB_TYPE,

package/dist/models/domain.js

@@ -1,14 +1,22 @@
 import { Model, DataTypes } from 'sequelize';
 import { z } from 'zod';
 const DOMAIN_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
-export const api_domain_schema = z.object({
-    domain_id: z.number().int().nonnegative(),
-    user_id: z.number().int().nonnegative(),
-    name: z.string().min(1).regex(DOMAIN_PATTERN, 'Invalid domain name'),
-    sender: z.string().default(''),
-    locale: z.string().default(''),
-    is_default: z.boolean().default(false)
-});
+export const api_domain_schema = z
+    .object({
+    domain_id: z.number().int().nonnegative().describe('Database primary key for the domain record.'),
+    user_id: z.number().int().nonnegative().describe('Owning user ID.'),
+    name: z
+        .string()
+        .min(1)
+        .regex(DOMAIN_PATTERN, 'Invalid domain name')
+        .describe('Domain name (config identifier).'),
+    sender: z.string().default('').describe('Default sender address for this domain.'),
+    locale: z.string().default('').describe('Default locale for this domain.'),
+    is_default: z.boolean().default(false).describe('If true, this is the default domain for the user.')
+})
+    .describe('Domain configuration record.');
+// Sequelize typing pattern: merge the Zod-inferred attribute type onto the model instance type.
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class api_domain extends Model {
 }
 export async function init_api_domain(api_db) {

package/dist/models/form.js

@@ -1,31 +1,75 @@
 import path from 'path';
 import { nanoid } from 'nanoid';
-import { Model, DataTypes } from 'sequelize';
+import { Model, DataTypes, UniqueConstraintError } from 'sequelize';
 import { z } from 'zod';
+import { assertSafeRelativePath } from '../util/paths.js';
 import { user_and_domain, normalizeSlug } from '../util.js';
-export const api_form_schema = z.object({
-    form_id: z.number().int().nonnegative(),
-    form_key: z.string().min(1).nullable().optional(),
-    user_id: z.number().int().nonnegative(),
-    domain_id: z.number().int().nonnegative(),
-    locale: z.string().default(''),
-    idname: z.string().min(1),
-    sender: z.string().min(1),
-    recipient: z.string().min(1),
-    subject: z.string(),
-    template: z.string().default(''),
-    filename: z.string().default(''),
-    slug: z.string().default(''),
-    secret: z.string().default(''),
-    captcha_required: z.boolean().default(false),
+const stored_file_schema = z
+    .object({
+    filename: z.string().describe('Asset filename (relative to the domain assets directory).'),
+    path: z.string().describe('Absolute path on disk where the asset is stored.'),
+    cid: z.string().optional().describe('Content-ID used for inline attachments (cid:...) when set.')
+})
+    .describe('A stored file/asset referenced by a template.');
+export const api_form_schema = z
+    .object({
+    form_id: z.number().int().nonnegative().describe('Database primary key for the form configuration record.'),
+    form_key: z
+        .string()
+        .trim()
+        .min(1)
+        .default(() => nanoid())
+        .describe('Public form key required by the unauthenticated form submission endpoint (globally unique).'),
+    user_id: z.number().int().nonnegative().describe('Owning user ID.'),
+    domain_id: z.number().int().nonnegative().describe('Owning domain ID.'),
+    locale: z
+        .string()
+        .default('')
+        .describe('Locale for this form configuration (used for lookup/rendering and template path generation).'),
+    idname: z.string().min(1).describe('Form identifier within the domain (slug-like).'),
+    sender: z.string().min(1).describe('Email From header used when delivering form submissions.'),
+    recipient: z
+        .string()
+        .min(1)
+        .describe('Default email recipient (To) used when delivering form submissions (unless recipients are overridden).'),
+    subject: z.string().describe('Email subject used when delivering form submissions.'),
+    template: z
+        .string()
+        .default('')
+        .describe('Nunjucks template content used to render the outbound email body for this form.'),
+    filename: z
+        .string()
+        .default('')
+        .describe('Relative path (within the config tree) of the source .njk template file for this form.'),
+    slug: z.string().default('').describe('Generated slug for this form record (domain + locale + idname).'),
+    secret: z
+        .string()
+        .default('')
+        .describe('Legacy form secret (stored for compatibility; not part of the public form submission contract).'),
+    replyto_email: z
+        .string()
+        .default('')
+        .describe('Optional forced Reply-To email address used when reply-to extraction is disabled or fails.'),
+    replyto_from_fields: z
+        .boolean()
+        .default(false)
+        .describe('If true, attempt to extract Reply-To from submitted form fields (email + name).'),
+    allowed_fields: z
+        .array(z.string())
+        .default([])
+        .describe('Optional allowlist of submitted field names that are exposed to templates as _fields_. When empty, all non-system fields are exposed.'),
+    captcha_required: z
+        .boolean()
+        .default(false)
+        .describe('If true, require a captcha token for public submissions to this form (in addition to any server-level requirement).'),
     files: z
-        .array(z.object({
-        filename: z.string(),
-        path: z.string(),
-        cid: z.string().optional()
-    }))
+        .array(stored_file_schema)
         .default([])
-});
+        .describe('Derived list of template-referenced assets (inline cids and external links) resolved during preprocessing/import.')
+})
+    .describe('Form configuration and template used by the public form submission endpoint.');
+// Sequelize typing pattern: merge the Zod-inferred attribute type onto the model instance type.
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class api_form extends Model {
 }
 export async function init_api_form(api_db) {
@@ -38,8 +82,7 @@ export async function init_api_form(api_db) {
         },
         form_key: {
             type: DataTypes.STRING,
-            allowNull: true,
-            defaultValue: null
+            allowNull: false
         },
         user_id: {
             type: DataTypes.INTEGER,
@@ -110,6 +153,29 @@ export async function init_api_form(api_db) {
             allowNull: false,
             defaultValue: ''
         },
+        replyto_email: {
+            type: DataTypes.STRING,
+            allowNull: false,
+            defaultValue: ''
+        },
+        replyto_from_fields: {
+            type: DataTypes.BOOLEAN,
+            allowNull: false,
+            defaultValue: false
+        },
+        allowed_fields: {
+            type: DataTypes.TEXT,
+            allowNull: false,
+            defaultValue: '[]',
+            get() {
+                // This column is stored as JSON text but exposed as `string[]` via getter/setter.
+                const raw = this.getDataValue('allowed_fields');
+                return raw ? JSON.parse(raw) : [];
+            },
+            set(value) {
+                this.setDataValue('allowed_fields', JSON.stringify(value ?? []));
+            }
+        },
         captcha_required: {
             type: DataTypes.BOOLEAN,
             allowNull: false,
@@ -120,6 +186,7 @@ export async function init_api_form(api_db) {
             allowNull: false,
             defaultValue: '[]',
             get() {
+                // This column is stored as JSON text but exposed as `StoredFile[]` via getter/setter.
                 const raw = this.getDataValue('files');
                 return raw ? JSON.parse(raw) : [];
             },
@@ -145,24 +212,13 @@ export async function init_api_form(api_db) {
     });
     return api_form;
 }
-function assertSafeRelativePath(filename, label) {
-    const normalized = path.normalize(filename);
-    if (path.isAbsolute(normalized)) {
-        throw new Error(`${label} path must be relative`);
-    }
-    if (normalized.split(path.sep).includes('..')) {
-        throw new Error(`${label} path cannot include '..' segments`);
-    }
-    return normalized;
-}
 export async function upsert_form(record) {
     const { user, domain } = await user_and_domain(record.domain_id);
-    const idname = normalizeSlug(user.idname);
     const dname = normalizeSlug(domain.name);
     const name = normalizeSlug(record.idname);
     const locale = normalizeSlug(record.locale || domain.locale || user.locale || '');
     if (!record.slug) {
-        record.slug = `${idname}-${dname}${locale ? '-' + locale : ''}-${name}`;
+        record.slug = `${dname}${locale ? '-' + locale : ''}-${name}`;
     }
     if (!record.filename) {
         const parts = [dname, 'form-template'];
@@ -181,16 +237,31 @@ export async function upsert_form(record) {
     let instance = null;
     instance = await api_form.findByPk(record.form_id);
     if (instance) {
-        if (!instance.form_key && !record.form_key) {
+        // Existing forms should always have a form_key. If not, repair it.
+        if (!String(instance.form_key ?? '').trim()) {
             record.form_key = nanoid();
         }
         await instance.update(record);
     }
     else {
-        if (!record.form_key) {
-            record.form_key = nanoid();
+        // form_key must be globally unique; retry on collisions.
+        for (let attempt = 0; attempt < 10; attempt++) {
+            record.form_key = String(record.form_key ?? '').trim() || nanoid();
+            try {
+                instance = await api_form.create(record);
+                break;
+            }
+            catch (err) {
+                if (err instanceof UniqueConstraintError) {
+                    const conflicted = err.errors?.some((e) => e.path === 'form_key');
+                    if (conflicted) {
+                        record.form_key = nanoid();
+                        continue;
+                    }
+                }
+                throw err;
+            }
         }
-        instance = await api_form.create(record);
     }
     if (!instance) {
         throw new Error(`Unable to update/create form ${record.form_id}`);

package/dist/models/init.js

@@ -2,79 +2,27 @@ import fs from 'fs';
 import path from 'path';
 import { Unyuck } from '@technomoron/unyuck';
 import { z } from 'zod';
+import { buildAssetUrl } from '../util/paths.js';
 import { user_and_domain } from '../util.js';
 import { api_domain, api_domain_schema } from './domain.js';
 import { api_form_schema, upsert_form } from './form.js';
 import { api_txmail_schema, upsert_txmail } from './txmail.js';
 import { apiTokenToHmac, api_user, api_user_schema } from './user.js';
+function buildInlineAssetCid(urlPath) {
+    // Many mail clients are picky about Content-ID values. Keep it stable and avoid path separators.
+    // Use a sanitized urlPath so nested assets remain unique without embedding `/` in the CID.
+    const normalized = String(urlPath || '')
+        .trim()
+        .replace(/\\/g, '/');
+    const safe = normalized.replace(/[^A-Za-z0-9._-]/g, '_').replace(/_+/g, '_');
+    return (safe || 'asset').slice(0, 200);
+}
 const init_data_schema = z.object({
     user: z.array(api_user_schema).default([]),
     domain: z.array(api_domain_schema).default([]),
     template: z.array(api_txmail_schema).default([]),
     form: z.array(api_form_schema).default([])
 });
-/**
- * Resolve an asset file within ./config/<domain>/assets
- */
-function resolveAsset(basePath, domainName, assetName) {
-    const assetsRoot = path.join(basePath, domainName, 'assets');
-    if (!fs.existsSync(assetsRoot)) {
-        return null;
-    }
-    const resolvedRoot = fs.realpathSync(assetsRoot);
-    const normalizedRoot = resolvedRoot.endsWith(path.sep) ? resolvedRoot : resolvedRoot + path.sep;
-    const candidate = path.resolve(assetsRoot, assetName);
-    if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
-        return null;
-    }
-    const realCandidate = fs.realpathSync(candidate);
-    if (!realCandidate.startsWith(normalizedRoot)) {
-        return null;
-    }
-    return realCandidate;
-}
-function buildAssetUrl(baseUrl, route, domainName, assetPath) {
-    const trimmedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
-    const normalizedRoute = route ? (route.startsWith('/') ? route : `/${route}`) : '';
-    const encodedDomain = encodeURIComponent(domainName);
-    const encodedPath = assetPath
-        .split('/')
-        .filter((segment) => segment.length > 0)
-        .map((segment) => encodeURIComponent(segment))
-        .join('/');
-    const trailing = encodedPath ? `/${encodedPath}` : '';
-    return `${trimmedBase}${normalizedRoute}/${encodedDomain}${trailing}`;
-}
-function extractAndReplaceAssets(html, opts) {
-    const regex = /src=["']asset\(['"]([^'"]+)['"](?:,\s*(true|false|[01]))?\)["']/g;
-    const assets = [];
-    const replacedHtml = html.replace(regex, (_m, relPath, inlineFlag) => {
-        const fullPath = resolveAsset(opts.basePath, opts.domainName, relPath);
-        if (!fullPath) {
-            throw new Error(`Missing asset "${relPath}"`);
-        }
-        const isInline = inlineFlag === 'true' || inlineFlag === '1';
-        const storedFile = {
-            filename: relPath,
-            path: fullPath,
-            cid: isInline ? relPath : undefined
-        };
-        assets.push(storedFile);
-        if (isInline) {
-            return `src="cid:${relPath}"`;
-        }
-        const domainAssetsRoot = path.join(opts.basePath, opts.domainName, 'assets');
-        const relativeToAssets = path.relative(domainAssetsRoot, fullPath);
-        if (!relativeToAssets || relativeToAssets.startsWith('..')) {
-            throw new Error(`Asset path escapes domain assets directory: ${fullPath}`);
-        }
-        const normalizedAssetPath = relativeToAssets.split(path.sep).join('/');
-        const baseUrl = opts.assetBaseUrl?.trim() ? opts.assetBaseUrl : opts.apiUrl;
-        const assetUrl = buildAssetUrl(baseUrl, opts.assetRoute, opts.domainName, normalizedAssetPath);
-        return `src="${assetUrl}"`;
-    });
-    return { html: replacedHtml, assets };
-}
 async function _load_template(store, filename, pathname, user, domain, locale, type) {
     const rootDir = path.join(store.configpath, domain.name, type);
     let relFile = filename;
@@ -97,20 +45,42 @@ async function _load_template(store, filename, pathname, user, domain, locale, t
     }
     try {
         const baseConfigPath = store.configpath;
-        const templateKey = path.relative(baseConfigPath, absPath);
-        if (!templateKey) {
+        const domainRoot = path.join(baseConfigPath, domain.name);
+        const templateKey = path.relative(domainRoot, absPath);
+        if (!templateKey || templateKey.startsWith('..')) {
             throw new Error(`Unable to resolve template path for "${absPath}"`);
         }
-        const processor = new Unyuck({ basePath: baseConfigPath });
-        const merged = processor.flattenNoAssets(templateKey);
-        const { html, assets } = extractAndReplaceAssets(merged, {
-            basePath: baseConfigPath,
-            domainName: domain.name,
-            apiUrl: store.env.API_URL,
-            assetBaseUrl: store.env.ASSET_PUBLIC_BASE,
-            assetRoute: store.env.ASSET_ROUTE
+        const assetBaseUrl = store.vars.ASSET_PUBLIC_BASE?.trim() ? store.vars.ASSET_PUBLIC_BASE : store.vars.API_URL;
+        const assetRoute = store.vars.ASSET_ROUTE;
+        const processor = new Unyuck({
+            basePath: domainRoot,
+            baseUrl: assetBaseUrl,
+            collectAssets: true,
+            assetFormatter: (ctx) => buildAssetUrl(assetBaseUrl, assetRoute, domain.name, ctx.urlPath)
+        });
+        const { html: mergedHtml, assets } = processor.flattenWithAssets(templateKey);
+        let html = mergedHtml;
+        const mappedAssets = assets.map((asset) => {
+            const rel = asset.filename.replace(/\\/g, '/');
+            const urlPath = rel.startsWith('assets/') ? rel.slice('assets/'.length) : rel;
+            return {
+                filename: urlPath,
+                path: asset.path,
+                cid: asset.cid ? buildInlineAssetCid(urlPath) : undefined
+            };
         });
-        return { html, assets };
+        for (const asset of assets) {
+            if (!asset.cid) {
+                continue;
+            }
+            const rel = asset.filename.replace(/\\/g, '/');
+            const urlPath = rel.startsWith('assets/') ? rel.slice('assets/'.length) : rel;
+            const desiredCid = buildInlineAssetCid(urlPath);
+            if (asset.cid !== desiredCid) {
+                html = html.replaceAll(`cid:${asset.cid}`, `cid:${desiredCid}`);
+            }
+        }
+        return { html, assets: mappedAssets };
     }
     catch (err) {
         throw new Error(`Template "${absPath}" failed to preprocess: ${err.message}`);
@@ -149,7 +119,7 @@ export async function importData(store) {
                     resolvedTokenHmac = token_hmac;
                 }
                 else if (typeof token === 'string' && token) {
-                    resolvedTokenHmac = apiTokenToHmac(token, store.env.API_TOKEN_PEPPER);
+                    resolvedTokenHmac = apiTokenToHmac(token, store.vars.API_TOKEN_PEPPER);
                 }
                 else {
                     throw new Error(`User ${record.user_id} is missing token or token_hmac`);

package/dist/models/recipient.js

@@ -1,14 +1,18 @@
 import { Model, DataTypes } from 'sequelize';
 import { z } from 'zod';
-export const api_recipient_schema = z.object({
-    recipient_id: z.number().int().nonnegative(),
-    domain_id: z.number().int().nonnegative(),
+export const api_recipient_schema = z
+    .object({
+    recipient_id: z.number().int().nonnegative().describe('Database primary key for the recipient record.'),
+    domain_id: z.number().int().nonnegative().describe('Owning domain ID.'),
     // Empty string means "domain-wide"; otherwise scope to a specific form_key.
-    form_key: z.string().default(''),
-    idname: z.string().min(1),
-    email: z.string().min(1),
-    name: z.string().default('')
-});
+    form_key: z.string().default('').describe('Form key scope. Empty string means domain-wide recipient.'),
+    idname: z.string().min(1).describe('Recipient identifier within the scope.'),
+    email: z.string().min(1).describe('Recipient email address.'),
+    name: z.string().default('').describe('Optional recipient display name.')
+})
+    .describe('Recipient routing record for form submissions.');
+// Sequelize typing pattern: merge the Zod-inferred attribute type onto the model instance type.
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class api_recipient extends Model {
 }
 export async function init_api_recipient(api_db) {

package/dist/models/txmail.js

@@ -1,46 +1,42 @@
 import path from 'path';
 import { Model, DataTypes } from 'sequelize';
 import { z } from 'zod';
+import { assertSafeRelativePath } from '../util/paths.js';
 import { user_and_domain, normalizeSlug } from '../util.js';
-export const api_txmail_schema = z.object({
-    template_id: z.number().int().nonnegative(),
-    user_id: z.number().int().nonnegative(),
-    domain_id: z.number().int().nonnegative(),
-    name: z.string().min(1),
-    locale: z.string().default(''),
-    template: z.string().default(''),
-    filename: z.string().default(''),
-    sender: z.string().min(1),
-    subject: z.string(),
-    slug: z.string().default(''),
+export const api_txmail_schema = z
+    .object({
+    template_id: z.number().int().nonnegative().describe('Database primary key for the template record.'),
+    user_id: z.number().int().nonnegative().describe('Owning user ID.'),
+    domain_id: z.number().int().nonnegative().describe('Owning domain ID.'),
+    name: z.string().min(1).describe('Template name within the domain.'),
+    locale: z.string().default('').describe('Locale for this template configuration.'),
+    template: z.string().default('').describe('Nunjucks template content used for rendering.'),
+    filename: z.string().default('').describe('Relative path of the source .njk template file.'),
+    sender: z.string().min(1).describe('Email From header used when delivering this template.'),
+    subject: z.string().describe('Email subject used when delivering this template.'),
+    slug: z.string().default('').describe('Generated slug for this template record (domain + locale + name).'),
+    part: z.boolean().default(false).describe('If true, template is a partial (not a standalone send).'),
     files: z
         .array(z.object({
-        filename: z.string(),
-        path: z.string(),
-        cid: z.string().optional()
+        filename: z.string().describe('Asset filename (relative to the domain assets directory).'),
+        path: z.string().describe('Absolute path on disk where the asset is stored.'),
+        cid: z.string().optional().describe('Content-ID used for inline attachments when set.')
     }))
         .default([])
-});
+        .describe('Derived list of template-referenced assets resolved during preprocessing/import.')
+})
+    .describe('Transactional email template configuration.');
+// Sequelize typing pattern: merge the Zod-inferred attribute type onto the model instance type.
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class api_txmail extends Model {
 }
-function assertSafeRelativePath(filename, label) {
-    const normalized = path.normalize(filename);
-    if (path.isAbsolute(normalized)) {
-        throw new Error(`${label} path must be relative`);
-    }
-    if (normalized.split(path.sep).includes('..')) {
-        throw new Error(`${label} path cannot include '..' segments`);
-    }
-    return normalized;
-}
 export async function upsert_txmail(record) {
     const { user, domain } = await user_and_domain(record.domain_id);
-    const idname = normalizeSlug(user.idname);
     const dname = normalizeSlug(domain.name);
     const name = normalizeSlug(record.name);
     const locale = normalizeSlug(record.locale || domain.locale || user.locale || '');
     if (!record.slug) {
-        record.slug = `${idname}-${dname}${locale ? '-' + locale : ''}-${name}`;
+        record.slug = `${dname}${locale ? '-' + locale : ''}-${name}`;
     }
     if (!record.filename) {
         const parts = [dname, 'tx-template'];
@@ -158,7 +154,7 @@ export async function init_api_txmail(api_db) {
         const dname = normalizeSlug(domain.name);
         const name = normalizeSlug(template.name);
         const locale = normalizeSlug(template.locale || domain.locale || user.locale || '');
-        template.slug ||= `${normalizeSlug(user.idname)}-${dname}${locale ? '-' + locale : ''}-${name}`;
+        template.slug ||= `${dname}${locale ? '-' + locale : ''}-${name}`;
         if (!template.filename) {
             const parts = [dname, 'tx-template'];
             if (locale)