@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

package/packages/bundled-features/src/template-resolver/layout-regions.ts

@@ -0,0 +1,206 @@
+// Server-only (happy-dom). A structured layout is the editable frame around a
+// mail or PDF body: header, signature and footer regions plus one empty
+// content slot. Everything else is rejected so a layout can never carry markup
+// the renderer did not plan for.
+
+import type { Element as ScanElement } from "happy-dom";
+import type { ContentFormat } from "./constants.js";
+import {
+  type DocumentViolation,
+  type SanitizeBodyResult,
+  sanitizeDocumentHtml,
+  sanitizeTemplateBody,
+  violation,
+  withParsedDocument,
+} from "./document-sanitizer.js";
+
+const REGION_ATTRIBUTES = ["data-header", "data-content", "data-signature", "data-footer"] as const;
+type RegionAttribute = (typeof REGION_ATTRIBUTES)[number];
+
+const MAIL_LAYOUT_CONTENT_SLOT = /\{\{\{\s*content\s*\}\}\}/g;
+
+export type LayoutRegions = {
+  readonly header: string;
+  readonly signature: string;
+  readonly footer: string;
+};
+
+export type SanitizeLayoutResult =
+  | { readonly ok: true; readonly html: string }
+  | { readonly ok: false; readonly violations: readonly DocumentViolation[] };
+
+type ParsedRegions = {
+  readonly innerHtml: Partial<Record<RegionAttribute, string>>;
+  readonly contentIsEmpty: boolean;
+  readonly violations: DocumentViolation[];
+};
+
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+
+function regionAttributeOf(element: ScanElement): RegionAttribute | null {
+  if (element.tagName.toLowerCase() !== "div") return null;
+  const present = REGION_ATTRIBUTES.filter((name) => element.hasAttribute(name));
+  return present.length === 1 ? (present[0] ?? null) : null;
+}
+
+function parseRegions(html: string): ParsedRegions {
+  return withParsedDocument(html, (body) => {
+    const innerHtml: Partial<Record<RegionAttribute, string>> = {};
+    const violations: DocumentViolation[] = [];
+    let contentIsEmpty = true;
+    const invalid = (detail: string, message: string) =>
+      violations.push(violation("layout_invalid_structure", detail, message));
+    for (const node of Array.from(body.childNodes)) {
+      if (node.nodeType === ELEMENT_NODE) continue;
+      if (node.nodeType !== TEXT_NODE || (node.textContent ?? "").trim() !== "") {
+        invalid("text", "Text and comments outside the layout regions are not allowed");
+      }
+    }
+    for (const element of Array.from(body.children)) {
+      const region = regionAttributeOf(element);
+      if (region === null) {
+        invalid(
+          element.tagName.toLowerCase(),
+          "Only <div data-header>, <div data-content>, <div data-signature> and <div data-footer> are allowed at the top level",
+        );
+        continue;
+      }
+      if (innerHtml[region] !== undefined) {
+        invalid(region, `Layout region ${region} may appear only once`);
+        continue;
+      }
+      innerHtml[region] = element.innerHTML;
+      if (region === "data-content") {
+        contentIsEmpty = element.children.length === 0 && (element.textContent ?? "").trim() === "";
+      }
+    }
+    return { innerHtml, contentIsEmpty, violations };
+  });
+}
+
+export function sanitizeLayoutHtml(html: string): SanitizeLayoutResult {
+  const parsed = parseRegions(html);
+  const violations = [...parsed.violations];
+  if (parsed.innerHtml["data-content"] === undefined) {
+    violations.push(
+      violation(
+        "layout_missing_content_slot",
+        "data-content",
+        "A layout needs exactly one empty <div data-content></div> where the body is placed",
+      ),
+    );
+  } else if (!parsed.contentIsEmpty) {
+    violations.push(
+      violation(
+        "layout_invalid_structure",
+        "data-content",
+        "The data-content region must be empty",
+      ),
+    );
+  }
+  const cleanedHtml: Partial<Record<RegionAttribute, string>> = {};
+  for (const name of ["data-header", "data-signature", "data-footer"] as const) {
+    const inner = parsed.innerHtml[name];
+    if (inner === undefined || inner.trim() === "") continue;
+    const result = sanitizeDocumentHtml(inner);
+    if (result.ok) cleanedHtml[name] = result.html;
+    else violations.push(...result.violations);
+  }
+  if (violations.length > 0) return { ok: false, violations };
+  const part = (name: RegionAttribute) => {
+    const regionHtml = cleanedHtml[name];
+    return regionHtml === undefined ? "" : `<div ${name}>${regionHtml}</div>`;
+  };
+  return {
+    ok: true,
+    html: [
+      part("data-header"),
+      "<div data-content></div>",
+      part("data-signature"),
+      part("data-footer"),
+    ].join(""),
+  };
+}
+
+export function readLayoutRegions(html: string): LayoutRegions {
+  const { innerHtml } = parseRegions(html);
+  return {
+    header: innerHtml["data-header"] ?? "",
+    signature: innerHtml["data-signature"] ?? "",
+    footer: innerHtml["data-footer"] ?? "",
+  };
+}
+
+export type TemplateWriteScope = "system" | "tenant";
+
+function rejected(violationItem: DocumentViolation): SanitizeBodyResult {
+  return { ok: false, violations: [violationItem] };
+}
+
+function sanitizeMailLayout(
+  scope: TemplateWriteScope,
+  contentFormat: ContentFormat,
+  content: string,
+): SanitizeBodyResult {
+  if (contentFormat === "html") return fromLayoutResult(sanitizeLayoutHtml(content));
+  if (contentFormat !== "mjml") {
+    return rejected(
+      violation(
+        "layout_requires_mjml_format",
+        contentFormat,
+        `Templates of kind mail-layout require contentFormat mjml or html, got "${contentFormat}"`,
+      ),
+    );
+  }
+  if (scope !== "system") {
+    return rejected(
+      violation(
+        "layout_source_system_only",
+        "mjml",
+        "Only system layouts may use mjml source; tenant layouts use the structured html format",
+      ),
+    );
+  }
+  if ((content.match(MAIL_LAYOUT_CONTENT_SLOT) ?? []).length !== 1) {
+    return rejected(
+      violation(
+        "layout_missing_content_slot",
+        "{{{content}}}",
+        "A mjml layout must contain {{{content}}} exactly once",
+      ),
+    );
+  }
+  return { ok: true, content };
+}
+
+function fromLayoutResult(result: SanitizeLayoutResult): SanitizeBodyResult {
+  return result.ok ? { ok: true, content: result.html } : result;
+}
+
+// One entry for every write path: layout kinds follow the scope-dependent
+// layout rules, everything else the plain document sanitizer.
+export function sanitizeTemplateWriteBody(input: {
+  readonly kind: string;
+  readonly scope: TemplateWriteScope;
+  readonly contentFormat: ContentFormat;
+  readonly content: string | null;
+}): SanitizeBodyResult {
+  const { kind, scope, contentFormat, content } = input;
+  if (kind === "mail-layout" && content !== null) {
+    return sanitizeMailLayout(scope, contentFormat, content);
+  }
+  if (kind === "pdf-layout" && content !== null) {
+    if (contentFormat !== "html") {
+      return rejected(
+        violation(
+          "document_requires_html_format",
+          contentFormat,
+          `Templates of kind pdf-layout require contentFormat html, got "${contentFormat}"`,
+        ),
+      );
+    }
+    return fromLayoutResult(sanitizeLayoutHtml(content));
+  }
+  return sanitizeTemplateBody({ kind, contentFormat, content });
+}

package/packages/bundled-features/src/template-resolver/linked-resources.ts

@@ -0,0 +1,102 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import * as z from "zod";
+import type { FileAttachmentRef } from "../renderer-foundation/index.js";
+import { pdfAttachmentFileNamePatternSchema, templateSlugSchema } from "./template-meta.js";
+
+export const templatePdfAttachmentLinkSchema = z
+  .object({
+    kind: z.literal("rendered-pdf"),
+    templateSlug: templateSlugSchema,
+    fileName: pdfAttachmentFileNamePatternSchema,
+  })
+  .strict();
+
+// A PDF the mail renderer asks for at send time: the document template is rendered with the
+// mail's variables, so nothing is stored. `fileName` is a pattern that may hold {{placeholders}}.
+export type TemplatePdfAttachmentLink = z.infer<typeof templatePdfAttachmentLinkSchema>;
+
+// A string is an image the body embeds by key (the fileRef id); an object is a file attached to
+// the mail as-is or a PDF rendered from a document template. Images are the only thing a document
+// body can reference.
+export type LinkedResourceEntry = string | FileAttachmentRef | TemplatePdfAttachmentLink;
+
+export function isFileAttachmentEntry(entry: LinkedResourceEntry): entry is FileAttachmentRef {
+  return typeof entry !== "string" && entry.kind === "file";
+}
+
+export function isPdfAttachmentLink(
+  entry: LinkedResourceEntry,
+): entry is TemplatePdfAttachmentLink {
+  return typeof entry !== "string" && entry.kind === "rendered-pdf";
+}
+
+function toLinkedResourceEntry(raw: unknown): LinkedResourceEntry | null {
+  if (typeof raw === "string") return raw;
+  if (!isPlainObject(raw)) return null;
+  if (raw["kind"] === "rendered-pdf") {
+    const link = templatePdfAttachmentLinkSchema.safeParse(raw);
+    return link.success ? link.data : null;
+  }
+  const { fileRefId, fileName } = raw;
+  if (raw["kind"] !== "file" || typeof fileRefId !== "string" || typeof fileName !== "string") {
+    return null;
+  }
+  return { kind: "file", fileRefId, fileName };
+}
+
+export function parseLinkedResourceEntries(
+  raw: string | null,
+): Record<string, LinkedResourceEntry> {
+  if (!raw) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (!isPlainObject(parsed)) return {};
+  const entries: Record<string, LinkedResourceEntry> = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    const entry = toLinkedResourceEntry(value);
+    if (entry !== null) entries[key] = entry;
+  }
+  return entries;
+}
+
+export function imageLinksOf(
+  entries: Readonly<Record<string, LinkedResourceEntry>>,
+): Record<string, string> {
+  const images: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(entries)) {
+    if (typeof entry === "string") images[key] = entry;
+  }
+  return images;
+}
+
+export function fileAttachmentsOf(
+  entries: Readonly<Record<string, LinkedResourceEntry>>,
+): FileAttachmentRef[] {
+  return Object.entries(entries)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .flatMap(([, entry]) => (isFileAttachmentEntry(entry) ? [entry] : []));
+}
+
+export function pdfAttachmentLinksOf(
+  entries: Readonly<Record<string, LinkedResourceEntry>>,
+): TemplatePdfAttachmentLink[] {
+  return Object.entries(entries)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .flatMap(([, entry]) => (isPdfAttachmentLink(entry) ? [entry] : []));
+}
+
+export function attachmentEntriesOf(
+  entries: Readonly<Record<string, LinkedResourceEntry>>,
+): [string, FileAttachmentRef | TemplatePdfAttachmentLink][] {
+  return Object.entries(entries).flatMap(([key, entry]) =>
+    typeof entry === "string" ? [] : [[key, entry]],
+  );
+}
+
+export function imageResourceKeysOf(raw: string | null): string[] {
+  return Object.keys(imageLinksOf(parseLinkedResourceEntries(raw)));
+}

package/packages/bundled-features/src/template-resolver/preview-display-html.ts

@@ -0,0 +1,36 @@
+import type { InlineAttachmentRef } from "../renderer-foundation/index.js";
+
+export const PREVIEW_IMAGE_BUDGET_BYTES = 5 * 1024 * 1024;
+
+const DISPLAYABLE_IMAGE_TYPES: ReadonlySet<string> = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+]);
+
+export type PreviewAttachmentReader = (
+  ref: InlineAttachmentRef,
+) => Promise<{ readonly content: Uint8Array; readonly contentType: string } | null>;
+
+// The preview shows images the mail client would resolve by Content-ID; a browser cannot, so each
+// resolved image becomes a data URI. `html` itself stays untouched because the send path needs the cids.
+export async function buildDisplayHtml(
+  html: string,
+  inline: readonly InlineAttachmentRef[],
+  readAttachment: PreviewAttachmentReader,
+): Promise<string> {
+  let displayHtml = html;
+  let usedBytes = 0;
+  for (const ref of inline) {
+    const needle = `src="cid:${ref.cid}"`;
+    if (!displayHtml.includes(needle)) continue;
+    const found = await readAttachment(ref);
+    if (found === null || !DISPLAYABLE_IMAGE_TYPES.has(found.contentType)) continue;
+    if (usedBytes + found.content.length > PREVIEW_IMAGE_BUDGET_BYTES) continue;
+    usedBytes += found.content.length;
+    const dataUri = `src="data:${found.contentType};base64,${Buffer.from(found.content).toString("base64")}"`;
+    displayHtml = displayHtml.replaceAll(needle, () => dataUri);
+  }
+  return displayHtml;
+}

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

@@ -0,0 +1,58 @@
+// Server-only (happy-dom). Prepares a rendered document body for the browser
+// that prints it: repeating table headers become real <thead> rows, and
+// everything that would make the browser fetch something external is removed.
+
+import type { Element as ScanElement } from "happy-dom";
+import { withParsedDocument } from "./document-sanitizer.js";
+
+const REPEAT_HEADER_ATTRIBUTE = "data-repeat-header";
+const FETCHING_ELEMENTS =
+  "script, link, iframe, object, embed, video, audio, source, meta, base, style";
+const FETCHING_ATTRIBUTES = ["src", "srcset", "poster", "background", "data"] as const;
+// Anchors only navigate; on svg image/use/feImage an href fetches.
+const HREF_ATTRIBUTES = ["href", "xlink:href"] as const;
+const EXTERNAL_STYLE_REFERENCE = /url\(|@import/i;
+
+function isEmbeddedValue(value: string): boolean {
+  return value.trim().toLowerCase().startsWith("data:");
+}
+
+function moveRepeatHeadersIntoThead(table: ScanElement): void {
+  const rows = Array.from(table.querySelectorAll("tr")).filter(
+    (row) => row.closest("table") === table,
+  );
+  const leading: ScanElement[] = [];
+  for (const row of rows) {
+    if (!row.hasAttribute(REPEAT_HEADER_ATTRIBUTE)) break;
+    leading.push(row);
+  }
+  // skip: a table without leading repeat-header rows keeps its structure as written
+  if (leading.length === 0) return;
+  const thead = table.ownerDocument.createElement("thead");
+  for (const row of leading) {
+    row.removeAttribute(REPEAT_HEADER_ATTRIBUTE);
+    thead.appendChild(row);
+  }
+  table.insertBefore(thead, table.firstChild);
+}
+
+export function prepareDocumentForPrint(html: string): string {
+  return withParsedDocument(html, (body) => {
+    for (const table of Array.from(body.querySelectorAll("table"))) {
+      moveRepeatHeadersIntoThead(table);
+    }
+    for (const element of Array.from(body.querySelectorAll(FETCHING_ELEMENTS))) element.remove();
+    for (const element of Array.from(body.querySelectorAll("*"))) {
+      for (const name of FETCHING_ATTRIBUTES) {
+        const value = element.getAttribute(name);
+        if (value !== null && !isEmbeddedValue(value)) element.removeAttribute(name);
+      }
+      if (element.tagName.toLowerCase() !== "a") {
+        for (const name of HREF_ATTRIBUTES) element.removeAttribute(name);
+      }
+      const style = element.getAttribute("style");
+      if (style !== null && EXTERNAL_STYLE_REFERENCE.test(style)) element.removeAttribute("style");
+    }
+    return body.innerHTML;
+  });
+}

package/packages/bundled-features/src/template-resolver/qualified-names.ts

@@ -7,12 +7,30 @@ export const TemplateResolverHandlers = {
   upsertTenant: "template-resolver:write:upsert-tenant",
   publish: "template-resolver:write:publish",
   archive: "template-resolver:write:archive",
+  publishSystem: "template-resolver:write:publish-system",
+  archiveSystem: "template-resolver:write:archive-system",
+  resetToSystem: "template-resolver:write:reset-to-system",
   set: "template-resolver:write:set",
+  importBundle: "template-resolver:write:import-bundle",
+  importBundleSystem: "template-resolver:write:import-bundle-system",
+  copyLocale: "template-resolver:write:copy-locale",
+  resourceUpload: "template-resolver:write:resource-upload",
+  resourceRemove: "template-resolver:write:resource-remove",
+  resourceLinkPdf: "template-resolver:write:resource-link-pdf",
+  sendTest: "template-resolver:write:send-test",
 } as const;
 
 export const TemplateResolverQueries = {
   findById: "template-resolver:query:find-by-id",
   list: "template-resolver:query:list",
+  usage: "template-resolver:query:usage",
+  overview: "template-resolver:query:overview",
+  layoutSource: "template-resolver:query:layout-source",
+  tenantOverrides: "template-resolver:query:tenant-overrides",
+  diffToSystem: "template-resolver:query:diff-to-system",
+  validate: "template-resolver:query:validate",
+  preview: "template-resolver:query:preview",
+  exportBundle: "template-resolver:query:export-bundle",
   // Public pair — anonymous-reachable, kind pinned to text-block.
   bySlug: "template-resolver:query:by-slug",
   byTenant: "template-resolver:query:by-tenant",
@@ -37,4 +55,16 @@ export const TemplateResolverErrors = {
   systemAdminRequired: "system_admin_required",
   alreadyActive: "template_already_active",
   alreadyArchived: "template_already_archived",
+  targetExists: "target_exists",
+  systemResourcesNeedSystemTenant: "system_resources_need_system_tenant",
+  resourceTooLarge: "template_resource_too_large",
+  resourceUnsupportedImage: "template_resource_unsupported_image",
+  attachmentUnsupportedType: "template_attachment_unsupported_type",
+  attachmentLimit: "template_attachment_limit",
+  attachmentInvalid: "template_attachment_invalid",
+  attachmentPdfTemplateMissing: "template_attachment_pdf_template_missing",
+  previewRenderFailed: "template_preview_render_failed",
+  testMailNoChannel: "template_test_mail_no_channel",
+  testMailNoAddress: "template_test_mail_no_address",
+  testMailFailed: "template_test_mail_failed",
 } as const;

package/packages/bundled-features/src/template-resolver/record-mapping.ts

@@ -0,0 +1,26 @@
+import type { NotificationRecordMapping } from "@cosmicdrift/kumiko-framework/engine";
+
+function readPath(row: Readonly<Record<string, unknown>>, path: string): unknown {
+  let current: unknown = 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: NotificationRecordMapping,
+  row: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const variables: Record<string, unknown> = {};
+  for (const [variable, path] of Object.entries(mapping.map)) {
+    const value = readPath(row, path);
+    if (value !== undefined) variables[variable] = value;
+  }
+  return variables;
+}

package/packages/bundled-features/src/template-resolver/resource-image.ts

@@ -0,0 +1,47 @@
+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",
+} as const;
+
+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;
+};
+
+function isResourceImageFormat(format: string | undefined): format is ResourceImageFormat {
+  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: Uint8Array): Promise<NormalizedResourceImage> {
+  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,
+  };
+}