@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

package/packages/bundled-features/src/template-resolver/document-schema.ts

@@ -0,0 +1,323 @@
+// @runtime client
+// Canonical document model for template bodies (kinds mail, document-pdf).
+// Universal on purpose: the web editor and the server sanitizer load the same
+// extension list, so what the editor can produce is exactly what the server
+// keeps. No DOM access at module level, no happy-dom here.
+import { isOneOf, isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { Extension, type Extensions, Node } from "@tiptap/core";
+import { Link } from "@tiptap/extension-link";
+import { Table, TableCell, TableHeader, TableRow } from "@tiptap/extension-table";
+import StarterKit from "@tiptap/starter-kit";
+
+const PLACEHOLDER_HREF = /^\{\{[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*\}\}$/;
+const REFERENCE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+const RESOURCE_KEY = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+const ALLOWED_LINK_SCHEMES = ["https://", "http://", "mailto:", "tel:"] as const;
+
+export function isDocumentPlaceholderHref(href: string): boolean {
+  return PLACEHOLDER_HREF.test(href);
+}
+
+const UNSAFE_URL_CHARACTERS = new Set(["<", ">", '"']);
+const FORBIDDEN_REFERENCE_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+
+function hasUnsafeUrlCharacter(value: string): boolean {
+  return Array.from(value).some((character) => {
+    const code = character.charCodeAt(0);
+    return UNSAFE_URL_CHARACTERS.has(character) || code <= 0x1f || code === 0x7f;
+  });
+}
+
+function isParsableWebUrl(href: string, protocol: "https:" | "http:"): boolean {
+  try {
+    return new URL(href).protocol === protocol;
+  } catch {
+    return false;
+  }
+}
+
+function hasAllowedLinkScheme(href: string): boolean {
+  if (href.startsWith("https://")) return isParsableWebUrl(href, "https:");
+  if (href.startsWith("http://")) return isParsableWebUrl(href, "http:");
+  return ALLOWED_LINK_SCHEMES.some((scheme) => href.startsWith(scheme));
+}
+
+// Exact lowercase prefix on the unchanged value: no trim, no case folding, so
+// "JaVaScRiPt:", "HTTPS://" or a leading tab can never slip through as a
+// scheme variant. Markup and control characters are refused outright because
+// downstream parsers (MJML, PDF renderer) re-read the serialized attribute.
+export function isAllowedDocumentLinkHref(href: string): boolean {
+  if (hasUnsafeUrlCharacter(href)) return false;
+  return hasAllowedLinkScheme(href) || isDocumentPlaceholderHref(href);
+}
+
+// Segments that hit the prototype chain are refused: the renderer later walks
+// the dotted path into a data object.
+export function isDocumentReferenceName(value: string): boolean {
+  return (
+    REFERENCE_NAME.test(value) &&
+    !value.split(".").some((segment) => FORBIDDEN_REFERENCE_SEGMENTS.has(segment))
+  );
+}
+
+export function isDocumentResourceKey(value: string): boolean {
+  return RESOURCE_KEY.test(value);
+}
+
+export const DOCUMENT_NODE_NAMES = [
+  "variable",
+  "resource",
+  "button",
+  "divider",
+  "pageBreak",
+] as const;
+
+export const DocumentVariable = Node.create({
+  name: "variable",
+  group: "inline",
+  inline: true,
+  atom: true,
+  addAttributes() {
+    return { name: { default: null } };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: "span[data-variable]",
+        getAttrs: (element) => {
+          const name = element.getAttribute("data-variable");
+          return name !== null && isDocumentReferenceName(name) ? { name } : false;
+        },
+      },
+    ];
+  },
+  renderHTML({ node }) {
+    return ["span", { "data-variable": node.attrs["name"] }];
+  },
+});
+
+export const DocumentResource = Node.create({
+  name: "resource",
+  group: "block",
+  atom: true,
+  addAttributes() {
+    return { resource: { default: null }, alt: { default: null } };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: "img[data-resource]",
+        getAttrs: (element) => {
+          const resource = element.getAttribute("data-resource");
+          if (resource === null || !isDocumentResourceKey(resource)) return false;
+          return { resource, alt: element.getAttribute("alt") };
+        },
+      },
+    ];
+  },
+  // Never emits src: the renderer resolves the resource key at render time.
+  renderHTML({ node }) {
+    const alt = node.attrs["alt"];
+    return [
+      "img",
+      alt === null || alt === undefined
+        ? { "data-resource": node.attrs["resource"] }
+        : { "data-resource": node.attrs["resource"], alt },
+    ];
+  },
+});
+
+export const DocumentButton = Node.create({
+  name: "button",
+  group: "block",
+  content: "text*",
+  marks: "",
+  defining: true,
+  addAttributes() {
+    return { href: { default: null } };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: "a[data-button]",
+        // Must win against the Link mark's `a[href]` rule.
+        priority: 1000,
+        getAttrs: (element) => {
+          const href = element.getAttribute("href");
+          return href !== null && isDocumentPlaceholderHref(href) ? { href } : false;
+        },
+      },
+    ];
+  },
+  renderHTML({ node }) {
+    return ["a", { "data-button": "", href: node.attrs["href"] }, 0];
+  },
+});
+
+export const DocumentDivider = Node.create({
+  name: "divider",
+  group: "block",
+  atom: true,
+  parseHTML() {
+    return [{ tag: "hr" }];
+  },
+  renderHTML() {
+    return ["hr"];
+  },
+});
+
+export const DocumentPageBreak = Node.create({
+  name: "pageBreak",
+  group: "block",
+  atom: true,
+  parseHTML() {
+    return [{ tag: "div[data-page-break]" }];
+  },
+  renderHTML() {
+    return ["div", { "data-page-break": "" }];
+  },
+});
+
+// A repeat row is a table row carrying `each`: prosemirror-tables requires
+// the tableRow node type, so a separate node type is not an option.
+export const DocumentTableRow = TableRow.extend({
+  addAttributes() {
+    return {
+      each: {
+        default: null,
+        parseHTML: (element) => {
+          const each = element.getAttribute("data-each");
+          return each !== null && isDocumentReferenceName(each) ? each : null;
+        },
+        renderHTML: (attributes) => {
+          const each: unknown = attributes["each"];
+          return typeof each === "string" && each ? { "data-each": each } : {};
+        },
+      },
+      repeatHeader: {
+        default: false,
+        parseHTML: (element) => element.hasAttribute("data-repeat-header"),
+        renderHTML: (attributes) =>
+          attributes["repeatHeader"] ? { "data-repeat-header": "" } : {},
+      },
+    };
+  },
+});
+
+export const DocumentRepeatRow = DocumentTableRow;
+
+export const DocumentTable = Table.extend({
+  renderHTML() {
+    return ["table", ["tbody", 0]];
+  },
+});
+
+// Span attributes are rendered only when they differ from the default, and
+// colwidth (an editor-resize artefact) never, so `<td><p>x</p></td>` is the
+// canonical cell.
+function plainObjectOrEmpty(value: unknown): Record<string, unknown> {
+  return isPlainObject(value) ? value : {};
+}
+
+function canonicalCellAttributes(attributes: Record<string, unknown>) {
+  return {
+    ...attributes,
+    colspan: {
+      ...plainObjectOrEmpty(attributes["colspan"]),
+      renderHTML: (attrs: Record<string, unknown>) =>
+        attrs["colspan"] && attrs["colspan"] !== 1 ? { colspan: attrs["colspan"] } : {},
+    },
+    rowspan: {
+      ...plainObjectOrEmpty(attributes["rowspan"]),
+      renderHTML: (attrs: Record<string, unknown>) =>
+        attrs["rowspan"] && attrs["rowspan"] !== 1 ? { rowspan: attrs["rowspan"] } : {},
+    },
+    colwidth: {
+      ...plainObjectOrEmpty(attributes["colwidth"]),
+      renderHTML: () => ({}),
+    },
+  };
+}
+
+export const DocumentTableCell = TableCell.extend({
+  addAttributes() {
+    return canonicalCellAttributes(this.parent?.() ?? {});
+  },
+});
+
+export const DocumentTableHeader = TableHeader.extend({
+  addAttributes() {
+    return canonicalCellAttributes(this.parent?.() ?? {});
+  },
+});
+
+// Only href survives a parse: target, rel, class and title from the input would
+// otherwise be kept verbatim, and the renderer decides those itself.
+export const DocumentLink = Link.extend({
+  addAttributes() {
+    return { href: { default: null, parseHTML: (element) => element.getAttribute("href") } };
+  },
+});
+
+export const DOCUMENT_TEXT_ALIGNMENTS = ["left", "center", "right", "justify"] as const;
+export type DocumentTextAlignment = (typeof DOCUMENT_TEXT_ALIGNMENTS)[number];
+
+// Serialized as data-align, never as a style attribute: the sanitizer keeps
+// styles out of the model, and each renderer maps the value to its own CSS.
+export const DocumentTextAlign = Extension.create({
+  name: "documentTextAlign",
+  addGlobalAttributes() {
+    return [
+      {
+        types: ["paragraph", "heading"],
+        attributes: {
+          textAlign: {
+            default: null,
+            parseHTML: (element) => {
+              const align = element.getAttribute("data-align");
+              return isOneOf(DOCUMENT_TEXT_ALIGNMENTS, align) ? align : null;
+            },
+            renderHTML: (attributes) => {
+              const align: unknown = attributes["textAlign"];
+              return isOneOf(DOCUMENT_TEXT_ALIGNMENTS, align) ? { "data-align": align } : {};
+            },
+          },
+        },
+      },
+    ];
+  },
+});
+
+export const documentExtensions: Extensions = [
+  StarterKit.configure({
+    blockquote: false,
+    code: false,
+    codeBlock: false,
+    strike: false,
+    horizontalRule: false,
+    dropcursor: false,
+    gapcursor: false,
+    undoRedo: false,
+    trailingNode: false,
+    listKeymap: false,
+    heading: { levels: [1, 2, 3] },
+    link: false,
+  }),
+  DocumentLink.configure({
+    openOnClick: false,
+    autolink: false,
+    linkOnPaste: false,
+    HTMLAttributes: { target: null, rel: null, class: null },
+    isAllowedUri: (url) => isAllowedDocumentLinkHref(url),
+  }),
+  DocumentTable,
+  DocumentTableRow,
+  DocumentTableHeader,
+  DocumentTableCell,
+  DocumentVariable,
+  DocumentResource,
+  DocumentButton,
+  DocumentDivider,
+  DocumentPageBreak,
+  DocumentTextAlign,
+];

package/packages/bundled-features/src/template-resolver/feature.ts

@@ -1,5 +1,6 @@
 import {
   type ContentCollectionDefinition,
+  createSystemConfig,
   defineFeature,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { bySlugQuery } from "./handlers/by-slug.query.js";
@@ -7,12 +8,33 @@ import { byTenantQuery } from "./handlers/by-tenant.query.js";
 import { makeCollectionItemQuery } from "./handlers/collection-item.query.js";
 import { makeCollectionListQuery } from "./handlers/collection-list.query.js";
 import { makeCollectionSetWrite } from "./handlers/collection-set.write.js";
+import { copyLocaleWrite } from "./handlers/copy-locale.write.js";
+import { diffToSystemQuery } from "./handlers/diff-to-system.query.js";
+import { exportBundleQuery } from "./handlers/export-bundle.query.js";
 import { findByIdQuery } from "./handlers/find-by-id.query.js";
+import { importBundleWrite } from "./handlers/import-bundle.write.js";
+import { importBundleSystemWrite } from "./handlers/import-bundle-system.write.js";
+import { layoutSourceQuery } from "./handlers/layout-source.query.js";
 import { listQuery } from "./handlers/list.query.js";
+import { overviewQuery } from "./handlers/overview.query.js";
+import { previewQuery } from "./handlers/preview.query.js";
+import { resetToSystemWrite } from "./handlers/reset-to-system.write.js";
+import { resourceLinkPdfWrite } from "./handlers/resource-link-pdf.write.js";
+import { resourceRemoveWrite } from "./handlers/resource-remove.write.js";
+import { resourceUploadWrite } from "./handlers/resource-upload.write.js";
+import { sendTestWrite } from "./handlers/send-test.write.js";
 import { setWrite } from "./handlers/set.write.js";
-import { archiveWrite, publishWrite } from "./handlers/toggle-status.write.js";
+import { tenantOverridesQuery } from "./handlers/tenant-overrides.query.js";
+import {
+  archiveSystemWrite,
+  archiveWrite,
+  publishSystemWrite,
+  publishWrite,
+} from "./handlers/toggle-status.write.js";
 import { upsertSystemWrite } from "./handlers/upsert-system.write.js";
 import { upsertTenantWrite } from "./handlers/upsert-tenant.write.js";
+import { usageQuery } from "./handlers/usage.query.js";
+import { validateQuery } from "./handlers/validate.query.js";
 import { templateResourceEntity } from "./table.js";
 import { userContentEntryEntity } from "./user-content-table.js";
 
@@ -22,7 +44,7 @@ import { userContentEntryEntity } from "./user-content-table.js";
 //
 // Consumption paths:
 //   - Render time: ctx.templateResolver.resolveTemplate(...) (see api.ts)
-//   - Admin UI: write/query handlers (upsertSystem, upsertTenant, publish, archive, findById, list)
+//   - Admin UI: write/query handlers (upsertSystem, upsertTenant, publish, archive, publishSystem, archiveSystem, resetToSystem, findById, list, usage, tenantOverrides, diffToSystem)
 //   - Cross-feature: requireTemplateResolver(ctx, callerName)
 export type TemplateResolverOptions = {
   /** Content collections this app mounts. Declared here rather than inside the
@@ -43,11 +65,14 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
   return defineFeature("template-resolver", (r) => {
     r.describe(
       [
-        "Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail-html`, `document-pdf`, `ai-prompt`, `text-block`, `image-snapshot`).",
-        "Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers.",
+        "Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`).",
+        "Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`.",
         "Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation.",
         "How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning).",
         'A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side.',
+        "`validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only.",
+        "`preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted.",
+        'Images used by a template (`<img data-resource="logo">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: "attachment"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail\'s own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10.',
         "Replaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
       ].join("\n\n"),
     );
@@ -56,6 +81,11 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
       category: "notifications",
       recommended: false,
     });
+    r.config({
+      keys: {
+        resourceMaxBytes: createSystemConfig("number", { default: 2_097_152, bounds: { min: 1 } }),
+      },
+    });
     r.entity("template-resource", templateResourceEntity);
     // Only when the app actually mounts a user-owned collection: the entity's
     // `content` is `userOwned`, which makes it subject data — the boot guard
@@ -68,7 +98,17 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
       upsertTenant: r.writeHandler(upsertTenantWrite),
       publish: r.writeHandler(publishWrite),
       archive: r.writeHandler(archiveWrite),
+      publishSystem: r.writeHandler(publishSystemWrite),
+      archiveSystem: r.writeHandler(archiveSystemWrite),
+      resetToSystem: r.writeHandler(resetToSystemWrite),
       set: r.writeHandler(setWrite),
+      importBundle: r.writeHandler(importBundleWrite),
+      importBundleSystem: r.writeHandler(importBundleSystemWrite),
+      copyLocale: r.writeHandler(copyLocaleWrite),
+      resourceUpload: r.writeHandler(resourceUploadWrite),
+      resourceRemove: r.writeHandler(resourceRemoveWrite),
+      resourceLinkPdf: r.writeHandler(resourceLinkPdfWrite),
+      sendTest: r.writeHandler(sendTestWrite),
     };
 
     const queries = {
@@ -76,6 +116,14 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
       list: r.queryHandler(listQuery),
       bySlug: r.queryHandler(bySlugQuery),
       byTenant: r.queryHandler(byTenantQuery),
+      usage: r.queryHandler(usageQuery),
+      overview: r.queryHandler(overviewQuery),
+      layoutSource: r.queryHandler(layoutSourceQuery),
+      tenantOverrides: r.queryHandler(tenantOverridesQuery),
+      diffToSystem: r.queryHandler(diffToSystemQuery),
+      validate: r.queryHandler(validateQuery),
+      preview: r.queryHandler(previewQuery),
+      exportBundle: r.queryHandler(exportBundleQuery),
     };
 
     for (const collection of collections) {
@@ -88,10 +136,12 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
     // Visual-tree actions for the text-block content tree. The handle is
     // propagated through the setup export so other features can build
     // compile-time-typed cross-feature edit targets.
+    // r.treeActions keeps literal types (const generic); the args only declare string-typed slots.
+    const emptyString: string = "";
     const treeHandle = r.treeActions({
-      edit: { args: { slug: "" as string, locale: "" as string } },
+      edit: { args: { slug: emptyString, locale: emptyString } },
       list: {},
-      create: { args: { folder: "" as string } },
+      create: { args: { folder: emptyString } },
     });
 
     return { handlers, queries, treeHandle };

package/packages/bundled-features/src/template-resolver/handlers/bundle-import.ts

@@ -0,0 +1,188 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type {
+  HandlerContext,
+  SessionUser,
+  TenantId,
+  WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type FieldIssue,
+  ValidationError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { requireForTenant } from "../../shared/index.js";
+import type { TemplateWriteScope } from "../layout-regions.js";
+import type { LinkedResourceEntry } from "../linked-resources.js";
+import {
+  attachmentLimitFailure,
+  attachmentNeedsMailTemplate,
+  readTemplateResourceMaxBytes,
+  storeBundleAttachment,
+  storeTemplateResource,
+} from "../store-template-resource.js";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import type { TemplateBundle } from "../template-bundle.js";
+import { attachTemplateResources } from "../template-resources.js";
+import { resolveTemplateVariables } from "../template-validation.js";
+import { MAX_FILE_ATTACHMENTS_PER_TEMPLATE } from "./resource-shared.js";
+import { evaluateTemplateWrite } from "./template-gates.js";
+import {
+  refuseTenantScopeUnderSystemTenant,
+  type TemplateRowPayload,
+  writeTemplateRow,
+} from "./template-write.js";
+
+export function targetExistsIssue(locale: string): FieldIssue {
+  return {
+    path: "locale",
+    code: "target_exists",
+    i18nKey: "templateResolver.errors.template.targetExists",
+    params: { detail: locale },
+  };
+}
+
+type BundleImport = {
+  readonly ctx: HandlerContext;
+  readonly user: SessionUser;
+  readonly tenantId: TenantId;
+  readonly scope: TemplateWriteScope;
+  readonly bundle: TemplateBundle;
+  readonly overwrite: boolean;
+};
+
+type BundleImportStatus = "draft" | "active";
+
+async function collectBundleIssues(
+  args: BundleImport,
+  status: BundleImportStatus,
+): Promise<readonly FieldIssue[]> {
+  const { ctx, tenantId, scope, bundle, overwrite } = args;
+  const { db } = requireForTenant(ctx, tenantId);
+  const variables = resolveTemplateVariables(
+    ctx.registry,
+    bundle.slug,
+    bundle.variableSchema ?? {},
+  );
+  const issues: FieldIssue[] = [];
+  for (const [locale, entry] of Object.entries(bundle.locales)) {
+    const evaluated = evaluateTemplateWrite({
+      kind: bundle.kind,
+      scope,
+      contentFormat: bundle.contentFormat,
+      content: entry.body,
+      rawMeta: entry.meta,
+      variables,
+    });
+    const found = evaluated.ok
+      ? status === "active"
+        ? evaluated.publishIssues
+        : []
+      : evaluated.issues;
+    issues.push(...found.map((issue) => ({ ...issue, path: `locales.${locale}.${issue.path}` })));
+    if (!overwrite) {
+      const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+        tenantId,
+        slug: bundle.slug,
+        kind: bundle.kind,
+        locale,
+      });
+      if (existing) issues.push(targetExistsIssue(locale));
+    }
+  }
+  return issues;
+}
+
+async function storeBundleResources(
+  args: BundleImport,
+): Promise<WriteResult<Record<string, LinkedResourceEntry>>> {
+  const linked: Record<string, LinkedResourceEntry> = {};
+  const pdfLinks = Object.entries(args.bundle.pdfAttachments);
+  const attachmentCount =
+    Object.values(args.bundle.resources).filter((resource) => resource.purpose === "attachment")
+      .length + pdfLinks.length;
+  if (attachmentCount > 0 && args.bundle.kind !== "mail") return attachmentNeedsMailTemplate();
+  if (attachmentCount > MAX_FILE_ATTACHMENTS_PER_TEMPLATE) return attachmentLimitFailure();
+  // The document template is not looked up: a bundle may carry it later than the mail.
+  for (const [key, link] of pdfLinks) linked[key] = { kind: "rendered-pdf", ...link };
+  const maxBytes = await readTemplateResourceMaxBytes(args.ctx.config, args.ctx.registry);
+  // A bundle is untrusted input like an upload: the same re-encoding decides the stored
+  // content type, so a declared image/png can't smuggle SVG or HTML into a mail or PDF.
+  for (const [key, resource] of Object.entries(args.bundle.resources)) {
+    const bytes = Uint8Array.from(Buffer.from(resource.base64, "base64"));
+    if (resource.purpose === "attachment") {
+      const attachment = await storeBundleAttachment({
+        ctx: args.ctx,
+        user: args.user,
+        tenantId: args.tenantId,
+        bytes,
+        maxBytes,
+        key,
+        fileName: resource.fileName,
+      });
+      if (!attachment.isSuccess) return attachment;
+      linked[key] = attachment.data;
+      continue;
+    }
+    const stored = await storeTemplateResource({
+      ctx: args.ctx,
+      user: args.user,
+      tenantId: args.tenantId,
+      bytes,
+      maxBytes,
+      key,
+    });
+    if (!stored.isSuccess) return stored;
+    linked[key] = stored.data.fileRefId;
+  }
+  return { isSuccess: true, data: linked };
+}
+
+// Validates every locale first, stores the resource files, then writes one row
+// per locale, so a bad locale never leaves files or half a bundle behind. An image
+// that fails re-encoding stops the import before any row is written; files stored
+// for the resources before it stay as unlinked FileRefs, like a replaced upload.
+export async function importTemplateBundle(
+  args: BundleImport & { readonly status: BundleImportStatus },
+): Promise<WriteResult<{ ids: Record<string, string> }>> {
+  const refused = refuseTenantScopeUnderSystemTenant(args.scope, args.tenantId);
+  if (refused !== null) return refused;
+  const issues = await collectBundleIssues(args, args.status);
+  if (issues.length > 0) return writeFailure(new ValidationError({ fields: [...issues] }));
+
+  const linked = await storeBundleResources(args);
+  if (!linked.isSuccess) return linked;
+
+  const variableSchema = args.bundle.variableSchema ?? {};
+  const variables = resolveTemplateVariables(args.ctx.registry, args.bundle.slug, variableSchema);
+  const ids: Record<string, string> = {};
+  for (const [locale, entry] of Object.entries(args.bundle.locales)) {
+    const payload: TemplateRowPayload = {
+      slug: args.bundle.slug,
+      kind: args.bundle.kind,
+      locale,
+      content: entry.body,
+      contentFormat: args.bundle.contentFormat,
+      variableSchema,
+      meta: entry.meta,
+    };
+    const written = await writeTemplateRow({
+      ctx: args.ctx,
+      user: args.user,
+      tenantId: args.tenantId,
+      scope: args.scope,
+      status: args.status,
+      variables,
+      payload,
+    });
+    if (!written.isSuccess) return written;
+    const attached = await attachTemplateResources(args.ctx, {
+      user: args.user,
+      tenantId: args.tenantId,
+      templateId: written.data.id,
+      resources: linked.data,
+    });
+    if (!attached.isSuccess) return attached;
+    ids[locale] = written.data.id;
+  }
+  return { isSuccess: true, data: { ids } };
+}