@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.364.0

package/dist/template-resolver/record-mapping.js

@@ -0,0 +1,21 @@
+function readPath(row, path) {
+    let current = row;
+    for (const segment of path.split(".")) {
+        if (typeof current !== "object" || current === null || !Object.hasOwn(current, segment)) {
+            return undefined;
+        }
+        current = Object.getOwnPropertyDescriptor(current, segment)?.value;
+    }
+    return current;
+}
+// Variables whose path is missing on the row are left out, so the template
+// renders them empty instead of printing "undefined".
+export function mapRecordToVariables(mapping, row) {
+    const variables = {};
+    for (const [variable, path] of Object.entries(mapping.map)) {
+        const value = readPath(row, path);
+        if (value !== undefined)
+            variables[variable] = value;
+    }
+    return variables;
+}

package/dist/template-resolver/resource-image.d.ts

@@ -0,0 +1,15 @@
+declare const CONTENT_TYPE_BY_FORMAT: {
+    readonly png: "image/png";
+    readonly jpeg: "image/jpeg";
+    readonly gif: "image/gif";
+    readonly webp: "image/webp";
+};
+type ResourceImageFormat = keyof typeof CONTENT_TYPE_BY_FORMAT;
+export type NormalizedResourceImage = {
+    readonly data: Uint8Array;
+    readonly contentType: (typeof CONTENT_TYPE_BY_FORMAT)[ResourceImageFormat];
+    readonly width: number;
+    readonly height: number;
+};
+export declare function normalizeResourceImage(data: Uint8Array): Promise<NormalizedResourceImage>;
+export {};

package/dist/template-resolver/resource-image.js

@@ -0,0 +1,34 @@
+import { assertNotSvg, SHARP_INPUT_OPTIONS } from "../shared/index.js";
+const MAX_RESOURCE_WIDTH = 1200;
+const CONTENT_TYPE_BY_FORMAT = {
+    png: "image/png",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+};
+function isResourceImageFormat(format) {
+    return format !== undefined && Object.hasOwn(CONTENT_TYPE_BY_FORMAT, format);
+}
+// Re-encodes an uploaded image: the stored content type comes from the decoded format, never
+// from the client, and re-encoding drops metadata and anything appended to the file.
+// sharp is imported lazily because every app loads template-resolver, few of them need an image decoder.
+export async function normalizeResourceImage(data) {
+    const { default: sharp } = await import("sharp");
+    const metadata = await sharp(data, SHARP_INPUT_OPTIONS).metadata();
+    assertNotSvg(metadata.format);
+    if (!isResourceImageFormat(metadata.format)) {
+        throw new Error(`unsupported image format "${metadata.format ?? "unknown"}"`);
+    }
+    const format = metadata.format;
+    const pipeline = sharp(data, SHARP_INPUT_OPTIONS)
+        .rotate()
+        .resize({ width: MAX_RESOURCE_WIDTH, withoutEnlargement: true })
+        .toFormat(format);
+    const { data: output, info } = await pipeline.toBuffer({ resolveWithObject: true });
+    return {
+        data: new Uint8Array(output),
+        contentType: CONTENT_TYPE_BY_FORMAT[format],
+        width: info.width,
+        height: info.height,
+    };
+}

package/dist/template-resolver/seeding.d.ts

@@ -1,7 +1,8 @@
 import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { type SessionUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type Registry, type SessionUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
 import { type ContentFormat, type UpsertKind } from "./constants.js";
+import type { TemplateBundle } from "./template-bundle.js";
 export type SeedSystemTemplateOptions = {
     readonly slug: string;
     readonly kind: UpsertKind;
@@ -9,7 +10,10 @@ export type SeedSystemTemplateOptions = {
     readonly content: string;
     readonly contentFormat: ContentFormat;
     readonly variableSchema?: Record<string, unknown>;
+    /** Omitted: links on an existing row stay untouched, so a re-seed on boot keeps images a
+     *  system admin uploaded through resource-upload. */
     readonly linkedResources?: Record<string, string>;
+    readonly meta?: unknown;
     readonly parentTemplateId?: string | null;
     readonly by?: SessionUser;
     readonly ifExists?: SeedIfExists;
@@ -17,6 +21,15 @@ export type SeedSystemTemplateOptions = {
 export declare function seedSystemTemplate(db: DbConnection, opts: SeedSystemTemplateOptions): Promise<{
     id: string;
 }>;
+export type SeedSystemTemplateBundleOptions = {
+    readonly by?: SessionUser;
+    readonly ifExists?: SeedIfExists;
+};
+export declare function seedSystemTemplateBundle(db: DbConnection, bundle: TemplateBundle, opts?: SeedSystemTemplateBundleOptions): Promise<{
+    ids: Record<string, string>;
+}>;
+export declare function hasNotificationTemplates(registry: Registry): boolean;
+export declare function seedNotificationTemplates(db: DbConnection, registry: Registry): Promise<void>;
 export type SeedTextBlockOptions = {
     readonly tenantId: TenantId;
     readonly slug: string;

package/dist/template-resolver/seeding.js

@@ -1,13 +1,13 @@
-// Boot-/Seed-Helper für App-Authors. Schreibt System-Templates (tenantId=
-// SYSTEM_TENANT_ID, scope=system, status=active) idempotent in die DB —
-// gleicher Projection-Pfad wie upsertSystem-Handler, ohne Access-Check.
+// Boot/seed helper for app authors. Writes system templates (tenantId=
+// SYSTEM_TENANT_ID, scope=system, status=active) idempotently — same projection
+// path as the upsertSystem handler, without the access check.
 //
-// **Wann nutzen?** runProdApp-seeds / TenantCreated-Hooks die Welcome-,
-// Incident- oder Feature-Mail-Slugs installieren, damit renderer-simple
-// (oder mail-html) sie per template-resolver auflösen kann.
+// Use it from runProdApp seeds or TenantCreated hooks that install the welcome,
+// incident or feature mail slugs, so the mail renderer can resolve them
+// through the template-resolver.
 //
-// Default ifExists="skip". `createSystemUser(SYSTEM_TENANT_ID)` als Actor —
-// bewusst nicht TestUsers (Prod-Seeds ≠ Test-Utilities).
+// Default ifExists="skip". The actor is `createSystemUser(SYSTEM_TENANT_ID)`,
+// deliberately not TestUsers (prod seeds are not test utilities).
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createTenantDb, deleteMany, } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemUser, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
@@ -15,7 +15,12 @@ import { getStreamVersion, getUnscopedStreamMaxVersionForSeed, } from "@cosmicdr
 import { runEventStoreSeed } from "@cosmicdrift/kumiko-framework/seeding";
 import { TEXT_BLOCK_KIND } from "./constants.js";
 import { executor } from "./handlers/shared.js";
+import { evaluateTemplateWrite } from "./handlers/template-gates.js";
+import { TEMPLATE_RESOLVER_FEATURE } from "./qualified-names.js";
 import { templateResourcesTable } from "./table.js";
+import { activeStampChanges, servedStampChanges } from "./template-draft.js";
+import { templateSlugSchema } from "./template-meta.js";
+import { variablesFromSchema } from "./template-validation.js";
 /** Drop projection orphans (no events anywhere) so boot seeds can recreate. */
 async function resolveExistingForEventStoreSeed(db, tdb, existingRow, tenantId) {
     if (existingRow == null)
@@ -39,6 +44,23 @@ export async function seedSystemTemplate(db, opts) {
     const tenantId = SYSTEM_TENANT_ID;
     const by = opts.by ?? createSystemUser(tenantId);
     const tdb = createTenantDb(db, tenantId, "system");
+    const label = `seedSystemTemplate ${opts.slug}/${opts.kind}/${opts.locale}`;
+    const slug = templateSlugSchema.safeParse(opts.slug);
+    if (!slug.success)
+        throw new Error(`${label} rejected: ${slug.error.issues[0]?.message}`);
+    const evaluated = evaluateTemplateWrite({
+        kind: opts.kind,
+        scope: "system",
+        contentFormat: opts.contentFormat,
+        content: opts.content,
+        rawMeta: opts.meta,
+        variables: variablesFromSchema(opts.variableSchema ?? {}),
+        resourceKeys: Object.keys(opts.linkedResources ?? {}),
+    });
+    const issues = evaluated.ok ? evaluated.publishIssues : evaluated.issues;
+    if (!evaluated.ok || issues.length > 0) {
+        throw new Error(`${label} rejected: ${issues.map((issue) => `${issue.code} (${issue.params?.["detail"] ?? issue.path})`).join("; ")}`);
+    }
     const existingRow = await fetchOne(db, templateResourcesTable, {
         tenantId,
         slug: opts.slug,
@@ -47,24 +69,40 @@ export async function seedSystemTemplate(db, opts) {
     });
     const existing = await resolveExistingForEventStoreSeed(db, tdb, existingRow ? { id: existingRow.id, version: existingRow.version } : null, tenantId);
     const variableSchema = JSON.stringify(opts.variableSchema ?? {});
-    const linkedResources = JSON.stringify(opts.linkedResources ?? {});
+    const meta = evaluated.metaJson;
+    const linkedResources = opts.linkedResources === undefined ? undefined : JSON.stringify(opts.linkedResources);
     const parentTemplateId = opts.parentTemplateId ?? null;
     const rowFields = {
         slug: opts.slug,
         kind: opts.kind,
         locale: opts.locale,
-        content: opts.content,
+        content: evaluated.content,
         contentFormat: opts.contentFormat,
         variableSchema,
-        linkedResources,
+        ...(linkedResources !== undefined && { linkedResources }),
+        meta,
         title: null,
         folder: null,
         scope: "system",
         parentTemplateId,
         status: "active",
     };
-    const applyUpdate = async (row) => {
-        const result = await executor.update({ id: row.id, version: row.version, changes: rowFields }, by, tdb);
+    const applyUpdate = async (row, current) => {
+        // Skip no-op updates so re-seeding on every pod boot does not bump
+        // version/modifiedAt or grow the event store.
+        if (current?.content === rowFields.content &&
+            current?.contentFormat === rowFields.contentFormat &&
+            current?.title === rowFields.title &&
+            current?.variableSchema === rowFields.variableSchema &&
+            current?.meta === rowFields.meta &&
+            (linkedResources === undefined || current?.linkedResources === linkedResources)) {
+            return { id: String(row.id) };
+        }
+        const result = await executor.update({
+            id: row.id,
+            version: row.version,
+            changes: { ...rowFields, ...activeStampChanges(row) },
+        }, by, tdb);
         if (!result.isSuccess) {
             throw new Error(`seedSystemTemplate update failed: ${JSON.stringify(result)}`);
         }
@@ -74,7 +112,13 @@ export async function seedSystemTemplate(db, opts) {
         existing,
         ifExists: opts.ifExists,
         create: async () => {
-            const result = await executor.create({ ...rowFields, tenantId }, by, tdb);
+            const result = await executor.create({
+                ...rowFields,
+                ...activeStampChanges(null),
+                draft: null,
+                linkedResources: linkedResources ?? "{}",
+                tenantId,
+            }, by, tdb);
             if (!result.isSuccess) {
                 // Parallel boot pods can both delete the orphan and race on create —
                 // unique on (tenantId, slug, kind, locale) → resolve winner and update.
@@ -94,7 +138,7 @@ export async function seedSystemTemplate(db, opts) {
                         existing: resolved,
                         ifExists: opts.ifExists,
                         create: () => Promise.reject(new Error("seedSystemTemplate: unreachable create")),
-                        update: applyUpdate,
+                        update: (row) => applyUpdate(row, again),
                     });
                 }
                 throw new Error(`seedSystemTemplate create failed: ${JSON.stringify(result)}`);
@@ -105,9 +149,66 @@ export async function seedSystemTemplate(db, opts) {
             }
             return { id: String(data.id) };
         },
-        update: applyUpdate,
+        update: (row) => applyUpdate(row, existingRow),
     });
 }
+// Seeds one system row per bundle locale. Bundled resources need a file
+// provider and the system tenant's file space, which a boot seed does not
+// have, so those go through the import-bundle-system write instead.
+export async function seedSystemTemplateBundle(db, bundle, opts = {}) {
+    if (Object.keys(bundle.resources).length > 0) {
+        throw new Error(`seedSystemTemplateBundle ${bundle.slug}/${bundle.kind}: bundles with resources cannot be seeded; use the import-bundle-system write`);
+    }
+    const ids = {};
+    for (const [locale, entry] of Object.entries(bundle.locales)) {
+        const seeded = await seedSystemTemplate(db, {
+            slug: bundle.slug,
+            kind: bundle.kind,
+            locale,
+            content: entry.body,
+            contentFormat: bundle.contentFormat,
+            variableSchema: bundle.variableSchema ?? {},
+            meta: entry.meta,
+            ...(opts.by !== undefined ? { by: opts.by } : {}),
+            ...(opts.ifExists !== undefined ? { ifExists: opts.ifExists } : {}),
+        });
+        ids[locale] = seeded.id;
+    }
+    return { ids };
+}
+export function hasNotificationTemplates(registry) {
+    return Array.from(registry.getAllNotifications().values()).some((notification) => notification.template !== undefined);
+}
+// Boot seed for notifications that ship their mail text with the code
+// (`r.notification({ template, meta, variables })`). The code is authoritative,
+// so existing system rows are updated; tenant overrides are untouched.
+export async function seedNotificationTemplates(db, registry) {
+    const hasTemplates = hasNotificationTemplates(registry);
+    if (hasTemplates && registry.getFeature(TEMPLATE_RESOLVER_FEATURE) === undefined) {
+        throw new Error(`Notifications declare a mail template but the "${TEMPLATE_RESOLVER_FEATURE}" feature is not mounted`);
+    }
+    if (hasTemplates) {
+        // Dynamic: renderer-foundation imports this feature's barrel, a static import would cycle.
+        const { collectRendererPlugins } = await import("../renderer-foundation/index.js");
+        if (!collectRendererPlugins(registry).some((plugin) => plugin.kinds.includes("mail"))) {
+            throw new Error('Notifications declare a mail template but no renderer plugin for kind "mail" is registered (mount renderer-foundation and @cosmicdrift/kumiko-renderer-mail-html)');
+        }
+    }
+    for (const [slug, notification] of registry.getAllNotifications()) {
+        for (const [locale, { body }] of Object.entries(notification.template ?? {})) {
+            await seedSystemTemplate(db, {
+                slug,
+                kind: "mail",
+                locale,
+                content: body,
+                contentFormat: "html",
+                meta: notification.meta?.[locale],
+                variableSchema: notification.variables,
+                ifExists: "update",
+            });
+        }
+    }
+}
 // Boot/test seed for kind=text-block. Same projection path as set.write,
 // without the access check. Default ifExists="skip".
 export async function seedTextBlock(db, opts) {
@@ -145,7 +246,13 @@ export async function seedTextBlock(db, opts) {
         const result = await executor.update({
             id: row.id,
             version: row.version,
-            changes: { title: fields.title, content: fields.content, folder: fields.folder },
+            changes: {
+                title: fields.title,
+                content: fields.content,
+                folder: fields.folder,
+                // A re-seed must not revive an archived block; only a served one gets a new served version.
+                ...(current?.status === "active" && servedStampChanges(row)),
+            },
         }, by, tdb);
         if (!result.isSuccess) {
             throw new Error(`seedTextBlock update failed: ${JSON.stringify(result)}`);
@@ -156,7 +263,7 @@ export async function seedTextBlock(db, opts) {
         existing,
         ifExists: opts.ifExists,
         create: async () => {
-            const result = await executor.create({ ...fields, tenantId: opts.tenantId }, by, tdb);
+            const result = await executor.create({ ...fields, ...activeStampChanges(null), draft: null, tenantId: opts.tenantId }, by, tdb);
             if (!result.isSuccess) {
                 if (result.error?.code === "unique_violation") {
                     const again = await fetchOne(db, templateResourcesTable, {

package/dist/template-resolver/store-template-resource.d.ts

@@ -0,0 +1,64 @@
+import type { ConfigAccessor, HandlerContext, Registry, SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileAttachmentRef } from "../renderer-foundation/index.js";
+import { type LinkedResourceEntry } from "./linked-resources.js";
+export declare function readTemplateResourceMaxBytes(config: ConfigAccessor | undefined, registry: Registry): Promise<number>;
+export type StoredTemplateResource = {
+    readonly fileRefId: string;
+    readonly key?: string;
+    readonly contentType: string;
+    readonly width: number;
+    readonly height: number;
+    readonly size: number;
+};
+export declare function storeTemplateResource(args: {
+    readonly ctx: HandlerContext;
+    readonly user: SessionUser;
+    readonly tenantId: TenantId;
+    readonly bytes: Uint8Array;
+    readonly maxBytes: number;
+    readonly templateId?: string;
+    readonly key?: string;
+}): Promise<WriteResult<StoredTemplateResource>>;
+export type StoredTemplateAttachment = {
+    readonly fileRefId: string;
+    readonly key: string;
+    readonly fileName: string;
+    readonly contentType: string;
+    readonly size: number;
+};
+export declare function attachmentNeedsMailTemplate(): WriteResult<never>;
+export declare function attachmentLimitFailure(): WriteResult<never>;
+export declare function otherAttachmentCount(linked: Readonly<Record<string, LinkedResourceEntry>>, key: string): number;
+export declare function storeBundleAttachment(args: {
+    readonly ctx: HandlerContext;
+    readonly user: SessionUser;
+    readonly tenantId: TenantId;
+    readonly bytes: Uint8Array;
+    readonly maxBytes: number;
+    readonly key: string;
+    readonly fileName: string;
+}): Promise<WriteResult<FileAttachmentRef>>;
+export declare function storeTemplateAttachment(args: {
+    readonly ctx: HandlerContext;
+    readonly user: SessionUser;
+    readonly tenantId: TenantId;
+    readonly bytes: Uint8Array;
+    readonly maxBytes: number;
+    readonly templateId: string;
+    readonly key: string;
+    readonly fileName: string;
+}): Promise<WriteResult<StoredTemplateAttachment>>;
+export type LinkedTemplatePdfAttachment = {
+    readonly key: string;
+    readonly templateSlug: string;
+    readonly fileName: string;
+};
+export declare function linkTemplatePdfAttachment(args: {
+    readonly ctx: HandlerContext;
+    readonly user: SessionUser;
+    readonly tenantId: TenantId;
+    readonly templateId: string;
+    readonly key: string;
+    readonly templateSlug: string;
+    readonly fileName: string;
+}): Promise<WriteResult<LinkedTemplatePdfAttachment>>;

package/dist/template-resolver/store-template-resource.js

@@ -0,0 +1,264 @@
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { NotFoundError, UnprocessableError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import { createFileRefFromBytes } from "@cosmicdrift/kumiko-framework/files";
+import { fileContextForTenant } from "../file-foundation/index.js";
+import { requireForTenant } from "../shared/index.js";
+import { SYSTEM_TENANT_ID } from "./constants.js";
+import { DEFAULT_RESOURCE_MAX_BYTES, MAX_FILE_ATTACHMENTS_PER_TEMPLATE, RESOURCE_MAX_BYTES_CONFIG_KEY, } from "./handlers/resource-shared.js";
+import { executor } from "./handlers/shared.js";
+import { attachmentEntriesOf, parseLinkedResourceEntries, templatePdfAttachmentLinkSchema, } from "./linked-resources.js";
+import { TemplateResolverErrors } from "./qualified-names.js";
+import { normalizeResourceImage } from "./resource-image.js";
+import { templateResourcesTable } from "./table.js";
+const EXTENSION_BY_CONTENT_TYPE = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+};
+export async function readTemplateResourceMaxBytes(config, registry) {
+    if (config === undefined || registry.getConfigKey(RESOURCE_MAX_BYTES_CONFIG_KEY) === undefined) {
+        return DEFAULT_RESOURCE_MAX_BYTES;
+    }
+    const value = await config(RESOURCE_MAX_BYTES_CONFIG_KEY);
+    return typeof value === "number" ? value : DEFAULT_RESOURCE_MAX_BYTES;
+}
+// Normalizes the image, stores it as a file ref of the target tenant and, with templateId + key,
+// links it into that tenant's template. The caller is responsible for authorization; the function trusts tenantId.
+export async function storeTemplateResource(args) {
+    const { ctx, user, tenantId, bytes, maxBytes, templateId, key } = args;
+    if (bytes.length > maxBytes) {
+        return writeFailure(new UnprocessableError(TemplateResolverErrors.resourceTooLarge, {
+            i18nKey: "templateResolver.errors.resource.tooLarge",
+            details: { maxBytes, size: bytes.length },
+        }));
+    }
+    let image;
+    try {
+        image = await normalizeResourceImage(Buffer.from(bytes));
+    }
+    catch (cause) {
+        return writeFailure(new UnprocessableError(TemplateResolverErrors.resourceUnsupportedImage, {
+            i18nKey: "templateResolver.errors.resource.unsupportedImage",
+            cause: cause instanceof Error ? cause : undefined,
+        }));
+    }
+    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
+    let row;
+    if (templateId !== undefined) {
+        row = await fetchOne(db, templateResourcesTable, {
+            tenantId,
+            id: templateId,
+        });
+        if (row === undefined)
+            return writeFailure(new NotFoundError("template-resource", templateId));
+    }
+    const created = await createFileRefFromBytes({
+        db,
+        files: fileContextForTenant(ctx, ctx.user.tenantId, tenantId),
+        registry: ctx.registry,
+        user: { ...user, tenantId },
+    }, {
+        // Neutral name: the source's file name may be personal data.
+        fileName: `${key ?? "resource"}.${EXTENSION_BY_CONTENT_TYPE[image.contentType] ?? "bin"}`,
+        mimeType: image.contentType,
+        data: image.data,
+    });
+    if (!created.isSuccess)
+        return created;
+    if (row !== undefined && key !== undefined) {
+        // The replaced FileRef stays: copy-locale and tenant overrides can share ids and
+        // there is no reference count to tell when the last user is gone.
+        const linkedResources = {
+            ...parseLinkedResourceEntries(row.linkedResources),
+            [key]: created.data.id,
+        };
+        const updated = await executor.update({
+            id: row.id,
+            version: row.version,
+            changes: { linkedResources: JSON.stringify(linkedResources) },
+        }, user, db, { streamTenantId });
+        if (!updated.isSuccess)
+            return updated;
+    }
+    return {
+        isSuccess: true,
+        data: {
+            fileRefId: created.data.id,
+            ...(key !== undefined && { key }),
+            contentType: image.contentType,
+            width: image.width,
+            height: image.height,
+            size: image.data.length,
+        },
+    };
+}
+const PDF_MAGIC = [0x25, 0x50, 0x44, 0x46, 0x2d];
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const JPEG_MAGIC = [0xff, 0xd8, 0xff];
+const ATTACHMENT_TYPES = [
+    { contentType: "application/pdf", extension: "pdf", magic: PDF_MAGIC },
+    { contentType: "image/png", extension: "png", magic: PNG_MAGIC },
+    { contentType: "image/jpeg", extension: "jpg", magic: JPEG_MAGIC },
+];
+function detectAttachmentType(bytes) {
+    return ATTACHMENT_TYPES.find(({ magic }) => magic.every((byte, index) => bytes[index] === byte));
+}
+export function attachmentNeedsMailTemplate() {
+    return writeFailure(new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
+        i18nKey: "templateResolver.errors.attachment.invalid",
+        details: { code: "mail_only" },
+    }));
+}
+export function attachmentLimitFailure() {
+    return writeFailure(new UnprocessableError(TemplateResolverErrors.attachmentLimit, {
+        i18nKey: "templateResolver.errors.attachment.limit",
+        i18nParams: { max: MAX_FILE_ATTACHMENTS_PER_TEMPLATE },
+        details: { max: MAX_FILE_ATTACHMENTS_PER_TEMPLATE },
+    }));
+}
+// Files and rendered PDFs share one cap; the entry being replaced under `key` does not count.
+export function otherAttachmentCount(linked, key) {
+    return attachmentEntriesOf(linked).filter(([linkedKey]) => linkedKey !== key).length;
+}
+function inspectAttachmentBytes(bytes, maxBytes) {
+    if (bytes.length > maxBytes) {
+        return {
+            failure: writeFailure(new UnprocessableError(TemplateResolverErrors.resourceTooLarge, {
+                details: { maxBytes, size: bytes.length },
+            })),
+        };
+    }
+    const type = detectAttachmentType(bytes);
+    if (type === undefined) {
+        return {
+            failure: writeFailure(new UnprocessableError(TemplateResolverErrors.attachmentUnsupportedType, {
+                i18nKey: "templateResolver.errors.attachment.unsupportedType",
+            })),
+        };
+    }
+    return { type };
+}
+// Stores the bytes unchanged as a file of the target tenant, without linking it anywhere.
+async function createAttachmentFileRef(args) {
+    const { ctx, user, tenantId, bytes, key, type } = args;
+    const { db } = requireForTenant(ctx, tenantId);
+    const created = await createFileRefFromBytes({
+        db,
+        files: fileContextForTenant(ctx, ctx.user.tenantId, tenantId),
+        registry: ctx.registry,
+        user: { ...user, tenantId },
+    }, {
+        // Neutral stored name: the admin's file name may be personal data and lives in the link entry.
+        fileName: `${key}.${type.extension}`,
+        mimeType: type.contentType,
+        data: bytes,
+    });
+    return created.isSuccess ? { isSuccess: true, data: { id: created.data.id } } : created;
+}
+// Stores a PDF/PNG/JPEG for a bundle import: validated like an upload, linked later by the importer.
+export async function storeBundleAttachment(args) {
+    const inspected = inspectAttachmentBytes(args.bytes, args.maxBytes);
+    if ("failure" in inspected)
+        return inspected.failure;
+    const created = await createAttachmentFileRef({ ...args, type: inspected.type });
+    if (!created.isSuccess)
+        return created;
+    return {
+        isSuccess: true,
+        data: { kind: "file", fileRefId: created.data.id, fileName: args.fileName },
+    };
+}
+// Stores a PDF/PNG/JPEG byte-for-byte (no re-encoding, the recipient gets what the admin uploaded)
+// and links it under `key` in a mail template of the target tenant. The caller authorizes tenantId.
+export async function storeTemplateAttachment(args) {
+    const { ctx, user, tenantId, bytes, maxBytes, templateId, key, fileName } = args;
+    const inspected = inspectAttachmentBytes(bytes, maxBytes);
+    if ("failure" in inspected)
+        return inspected.failure;
+    const { type } = inspected;
+    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
+    const row = await fetchOne(db, templateResourcesTable, {
+        tenantId,
+        id: templateId,
+    });
+    if (row === undefined)
+        return writeFailure(new NotFoundError("template-resource", templateId));
+    if (row.kind !== "mail")
+        return attachmentNeedsMailTemplate();
+    const linked = parseLinkedResourceEntries(row.linkedResources);
+    if (otherAttachmentCount(linked, key) >= MAX_FILE_ATTACHMENTS_PER_TEMPLATE) {
+        return attachmentLimitFailure();
+    }
+    const created = await createAttachmentFileRef({ ctx, user, tenantId, bytes, key, type });
+    if (!created.isSuccess)
+        return created;
+    const entry = { kind: "file", fileRefId: created.data.id, fileName };
+    const updated = await executor.update({
+        id: row.id,
+        version: row.version,
+        changes: { linkedResources: JSON.stringify({ ...linked, [key]: entry }) },
+    }, user, db, { streamTenantId });
+    if (!updated.isSuccess)
+        return updated;
+    return {
+        isSuccess: true,
+        data: {
+            fileRefId: created.data.id,
+            key,
+            fileName,
+            contentType: type.contentType,
+            size: bytes.length,
+        },
+    };
+}
+function pdfAttachmentInvalid(code) {
+    return writeFailure(new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
+        i18nKey: "templateResolver.errors.attachment.invalid",
+        details: { code },
+    }));
+}
+// Links a PDF that is rendered from a document template at send time into a mail template of the
+// target tenant. Nothing is stored besides the link entry. The caller authorizes tenantId.
+export async function linkTemplatePdfAttachment(args) {
+    const { ctx, user, tenantId, templateId, key } = args;
+    const link = templatePdfAttachmentLinkSchema.safeParse({
+        kind: "rendered-pdf",
+        templateSlug: args.templateSlug,
+        fileName: args.fileName,
+    });
+    if (!link.success)
+        return pdfAttachmentInvalid("invalid_pdf_link");
+    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
+    const row = await fetchOne(db, templateResourcesTable, {
+        tenantId,
+        id: templateId,
+    });
+    if (row === undefined)
+        return writeFailure(new NotFoundError("template-resource", templateId));
+    if (row.kind !== "mail")
+        return attachmentNeedsMailTemplate();
+    const linked = parseLinkedResourceEntries(row.linkedResources);
+    if (otherAttachmentCount(linked, key) >= MAX_FILE_ATTACHMENTS_PER_TEMPLATE) {
+        return attachmentLimitFailure();
+    }
+    const visibleTemplates = await selectMany(db, templateResourcesTable, { tenantId: [tenantId, SYSTEM_TENANT_ID], slug: link.data.templateSlug, kind: "document-pdf" }, { limit: 1 });
+    if (visibleTemplates.length === 0) {
+        return writeFailure(new UnprocessableError(TemplateResolverErrors.attachmentPdfTemplateMissing, {
+            i18nKey: "templateResolver.errors.attachment.pdfTemplateMissing",
+            i18nParams: { slug: link.data.templateSlug },
+            details: { templateSlug: link.data.templateSlug },
+        }));
+    }
+    const updated = await executor.update({
+        id: row.id,
+        version: row.version,
+        changes: { linkedResources: JSON.stringify({ ...linked, [key]: link.data }) },
+    }, user, db, { streamTenantId });
+    if (!updated.isSuccess)
+        return updated;
+    return {
+        isSuccess: true,
+        data: { key, templateSlug: link.data.templateSlug, fileName: link.data.fileName },
+    };
+}