@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

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

@@ -5,6 +5,7 @@ import {
   createSelectField,
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
+import type { EntityEventMigration } from "@cosmicdrift/kumiko-types/fields";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import {
   CONTENT_FORMATS,
@@ -13,6 +14,13 @@ import {
   TEMPLATE_STATUSES,
 } from "./constants.js";
 
+// Stored v1 events name the kind "mail-html", which is now "mail".
+const renameMailHtmlKind: EntityEventMigration = {
+  fromVersion: 1,
+  toVersion: 2,
+  transform: (fields) => (fields["kind"] === "mail-html" ? { ...fields, kind: "mail" } : fields),
+};
+
 // TemplateResource — strukturierte Template-Definition mit Tenant-
 // Override-Hierarchie, Locale-Fallback und Resource-Linking via
 // file-foundation. Pro (tenantId, slug, kind, locale) genau eine Row;
@@ -44,6 +52,9 @@ export const templateResourceEntity = createEntity({
     contentFormat: createSelectField({ required: true, options: [...CONTENT_FORMATS] }),
     variableSchema: createLongTextField({ personal: false, reason: "technical_reference" }),
     linkedResources: createLongTextField({ personal: false, reason: "technical_reference" }),
+    // Per-kind JSON (mail: subject, preview text, layout slug, ...), validated
+    // against template-meta.ts on write. Authored by TenantAdmin/Operator.
+    meta: createLongTextField({ personal: false, reason: "is_business_data" }),
     scope: createSelectField({ required: true, options: [...TEMPLATE_SCOPES] }),
     parentTemplateId: createTextField({ personal: false, reason: "technical_reference" }),
     status: createSelectField({ required: true, options: [...TEMPLATE_STATUSES] }),
@@ -55,6 +66,8 @@ export const templateResourceEntity = createEntity({
       name: "read_template_resources_unique",
     },
   ],
+  eventVersion: 2,
+  eventMigrations: [renameMailHtmlKind],
 });
 
 export const templateResourcesTable = buildEntityTable("template-resource", templateResourceEntity);
@@ -84,6 +97,7 @@ export type TemplateResourceRow = {
   readonly contentFormat: string;
   readonly variableSchema: string | null;
   readonly linkedResources: string | null;
+  readonly meta: string | null;
   readonly scope: string;
   readonly parentTemplateId: string | null;
   readonly status: string;

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

@@ -0,0 +1,79 @@
+import * as z from "zod";
+import { CONTENT_FORMATS, UPSERT_KINDS } from "./constants.js";
+import { isDocumentResourceKey } from "./document-schema.js";
+import { templatePdfAttachmentLinkSchema } from "./linked-resources.js";
+import { templateSlugSchema } from "./template-meta.js";
+
+const MAX_RESOURCES = 20;
+const MAX_RESOURCE_BYTES = 2 * 1024 * 1024;
+const MAX_BASE64_LENGTH = Math.ceil(MAX_RESOURCE_BYTES / 3) * 4;
+
+const STRICT_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+const CONTENT_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i;
+const UNSAFE_FILE_NAME_CHARACTERS = /[/\\";]|\p{Cc}/u;
+
+const bundleLocaleSchema = z
+  .string()
+  .min(2)
+  .max(8)
+  .regex(/^[a-z]{2}(-[a-z]{2})?$/i, "locale must be ISO 639-1 (e.g. de, en, en-us)");
+
+const bundleFileNameSchema = z
+  .string()
+  .min(1)
+  .max(200)
+  .refine((name) => !UNSAFE_FILE_NAME_CHARACTERS.test(name) && !name.includes(".."), {
+    message: 'file name must not contain / \\ " ; control characters or ".."',
+  });
+
+const bundleResourceSchema = z
+  .object({
+    fileName: bundleFileNameSchema,
+    contentType: z.string().max(100).regex(CONTENT_TYPE, "content type must be type/subtype"),
+    base64: z.string().max(MAX_BASE64_LENGTH).regex(STRICT_BASE64, "base64 is not valid"),
+    // Absent means an image the body embeds; "attachment" is a file attached to the mail.
+    purpose: z.enum(["attachment"]).optional(),
+  })
+  .strict();
+
+const pdfAttachmentLinkBodySchema = templatePdfAttachmentLinkSchema.omit({ kind: true });
+
+const bundleLocaleEntrySchema = z
+  .object({ body: z.string().max(200_000), meta: z.unknown().optional() })
+  .strict();
+
+export const templateBundleSchema = z
+  .object({
+    slug: templateSlugSchema,
+    kind: z.enum(UPSERT_KINDS),
+    contentFormat: z.enum(CONTENT_FORMATS),
+    variableSchema: z.record(z.string(), z.unknown()).optional(),
+    locales: z
+      .record(bundleLocaleSchema, bundleLocaleEntrySchema)
+      .refine((locales) => Object.keys(locales).length >= 1, {
+        message: "a bundle needs at least one locale",
+      }),
+    resources: z
+      .record(
+        z.string().refine(isDocumentResourceKey, { message: "not a valid resource key" }),
+        bundleResourceSchema,
+      )
+      .refine((resources) => Object.keys(resources).length <= MAX_RESOURCES, {
+        message: `a bundle holds at most ${MAX_RESOURCES} resources`,
+      })
+      .default({}),
+    // PDFs rendered from document templates at send time; nothing to store, so no bytes.
+    pdfAttachments: z
+      .record(
+        z.string().refine(isDocumentResourceKey, { message: "not a valid resource key" }),
+        pdfAttachmentLinkBodySchema,
+      )
+      .default({}),
+  })
+  .strict()
+  .refine(
+    (bundle) => Object.keys(bundle.pdfAttachments).every((key) => !(key in bundle.resources)),
+    { message: "a key is used by a resource and a PDF attachment", path: ["pdfAttachments"] },
+  );
+
+export type TemplateBundle = z.infer<typeof templateBundleSchema>;

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

@@ -0,0 +1,78 @@
+import { withParsedDocument } from "./document-sanitizer.js";
+
+export type TemplateDiffChange = "same" | "added" | "removed";
+
+export type TemplateDiffBlock = { readonly change: TemplateDiffChange; readonly content: string };
+
+// Beyond this the quadratic LCS table is not worth it for a preview.
+const MAX_LCS_CELLS = 1_000_000;
+
+function splitHtmlBlocks(content: string): string[] {
+  return withParsedDocument(content, (body) => {
+    const blocks: string[] = [];
+    for (const node of Array.from(body.childNodes)) {
+      const markup =
+        "outerHTML" in node && typeof node.outerHTML === "string" ? node.outerHTML : "";
+      const text = markup === "" ? (node.textContent ?? "").trim() : markup;
+      if (text !== "") blocks.push(text);
+    }
+    return blocks;
+  });
+}
+
+export function splitTemplateBlocks(content: string, contentFormat: string): string[] {
+  if (contentFormat === "html") return splitHtmlBlocks(content);
+  return content
+    .split(/\r?\n[ \t]*\r?\n/)
+    .map((block) => block.trim())
+    .filter((block) => block !== "");
+}
+
+// "removed" = only in the system template, "added" = only in the tenant version.
+export function diffTemplateBlocks(
+  system: readonly string[],
+  tenant: readonly string[],
+): TemplateDiffBlock[] {
+  if (system.length * tenant.length > MAX_LCS_CELLS) {
+    return [
+      ...system.map((content) => ({ change: "removed" as const, content })),
+      ...tenant.map((content) => ({ change: "added" as const, content })),
+    ];
+  }
+  const rows = system.length;
+  const cols = tenant.length;
+  const width = cols + 1;
+  // lengths[i * width + j] = LCS length of system[i..] and tenant[j..]
+  const lengths = new Uint32Array((rows + 1) * width);
+  const lengthAt = (i: number, j: number): number => lengths[i * width + j] ?? 0;
+  for (let i = rows - 1; i >= 0; i--) {
+    for (let j = cols - 1; j >= 0; j--) {
+      lengths[i * width + j] =
+        system[i] === tenant[j]
+          ? lengthAt(i + 1, j + 1) + 1
+          : Math.max(lengthAt(i + 1, j), lengthAt(i, j + 1));
+    }
+  }
+  const result: TemplateDiffBlock[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < rows || j < cols) {
+    const systemBlock = system[i];
+    const tenantBlock = tenant[j];
+    if (systemBlock !== undefined && systemBlock === tenantBlock) {
+      result.push({ change: "same", content: systemBlock });
+      i++;
+      j++;
+    } else if (
+      systemBlock !== undefined &&
+      (tenantBlock === undefined || lengthAt(i + 1, j) >= lengthAt(i, j + 1))
+    ) {
+      result.push({ change: "removed", content: systemBlock });
+      i++;
+    } else if (tenantBlock !== undefined) {
+      result.push({ change: "added", content: tenantBlock });
+      j++;
+    }
+  }
+  return result;
+}

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

@@ -0,0 +1,129 @@
+import * as z from "zod";
+import { PDF_PAGE_FORMATS, type TemplateKind } from "./constants.js";
+
+// One or more kebab segments joined by ":" — notification templates are seeded
+// under their qualified name `feature:notify:name`.
+export const templateSlugSchema = z
+  .string()
+  .min(1)
+  .max(120)
+  .regex(
+    /^[a-z0-9]+(-[a-z0-9]+)*(:[a-z0-9]+(-[a-z0-9]+)*)*$/,
+    "slug must be kebab-case segments joined by ':'",
+  );
+
+export const MAIL_CATEGORIES = ["transactional", "marketing"] as const;
+export type MailCategory = (typeof MAIL_CATEGORIES)[number];
+
+// Header values: a CR/LF would let an author inject extra mail headers.
+const singleLine = (max: number) =>
+  z
+    .string()
+    .max(max)
+    .refine((value) => !/[\r\n]/.test(value), "must not contain line breaks");
+
+const mailMetaSchema = z
+  .object({
+    subject: singleLine(200).min(1),
+    previewText: singleLine(200).optional(),
+    layoutSlug: templateSlugSchema.optional(),
+    category: z.enum(MAIL_CATEGORIES).optional(),
+    sender: z
+      .string()
+      .max(60)
+      .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "sender must be a kebab-case key")
+      .optional(),
+  })
+  .strict();
+
+const PDF_ORIENTATIONS = ["portrait", "landscape"] as const;
+
+const marginMm = z.number().finite().min(0).max(100).optional();
+
+// The file name ends up in a Content-Disposition header and on disk.
+const FORBIDDEN_FILE_NAME = /[/\\";]|\.\./;
+
+// Name of a PDF rendered into a mail; {{placeholders}} are filled at render time.
+export const pdfAttachmentFileNamePatternSchema = singleLine(200)
+  .min(1)
+  .refine((value) => !FORBIDDEN_FILE_NAME.test(value), 'must not contain / \\ " ; or ..')
+  .refine((value) => value.toLowerCase().endsWith(".pdf"), "must end with .pdf");
+
+const pdfMetaSchema = z
+  .object({
+    layoutSlug: templateSlugSchema.optional(),
+    pageFormat: z.enum(PDF_PAGE_FORMATS).optional(),
+    orientation: z.enum(PDF_ORIENTATIONS).optional(),
+    printBackground: z.boolean().optional(),
+    layoutHeaderFooter: z.boolean().optional(),
+    margins: z
+      .object({ top: marginMm, right: marginMm, bottom: marginMm, left: marginMm })
+      .strict()
+      .optional(),
+    fileName: singleLine(200)
+      .min(1)
+      .refine((value) => !FORBIDDEN_FILE_NAME.test(value), 'must not contain / \\ " ; or ..')
+      .optional(),
+    metadata: z
+      .object({ title: singleLine(200).optional(), author: singleLine(200).optional() })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+const layoutMetaSchema = z.object({}).strict();
+
+export type MailTemplateMeta = z.infer<typeof mailMetaSchema>;
+export type PdfTemplateMeta = z.infer<typeof pdfMetaSchema>;
+export type LayoutTemplateMeta = z.infer<typeof layoutMetaSchema>;
+export type TemplateMeta = MailTemplateMeta | PdfTemplateMeta | LayoutTemplateMeta;
+
+export function isMailTemplateMeta(meta: TemplateMeta | null): meta is MailTemplateMeta {
+  return meta !== null && "subject" in meta;
+}
+
+export function readPdfTemplateMeta(meta: TemplateMeta | null): PdfTemplateMeta | null {
+  const parsed = pdfMetaSchema.safeParse(meta);
+  return parsed.success ? parsed.data : null;
+}
+
+export type TemplateMetaIssue = { readonly path: string; readonly message: string };
+
+export type TemplateMetaResult =
+  | { readonly ok: true; readonly meta: TemplateMeta | null }
+  | { readonly ok: false; readonly issues: readonly TemplateMetaIssue[] };
+
+function schemaForKind(kind: TemplateKind) {
+  switch (kind) {
+    case "mail":
+      return mailMetaSchema;
+    case "document-pdf":
+      return pdfMetaSchema;
+    case "mail-layout":
+    case "pdf-layout":
+      return layoutMetaSchema;
+    default:
+      return null;
+  }
+}
+
+// Kinds without a meta schema must not carry meta at all; mail needs it,
+// layouts and PDFs may omit it.
+export function parseTemplateMeta(kind: TemplateKind, raw: unknown): TemplateMetaResult {
+  const schema = schemaForKind(kind);
+  if (schema === null) {
+    return raw === undefined || raw === null
+      ? { ok: true, meta: null }
+      : { ok: false, issues: [{ path: "meta", message: `kind ${kind} does not take meta` }] };
+  }
+  if ((raw === undefined || raw === null) && kind !== "mail") return { ok: true, meta: null };
+  const parsed = schema.safeParse(raw ?? undefined);
+  if (parsed.success) return { ok: true, meta: parsed.data };
+  return {
+    ok: false,
+    issues: parsed.error.issues.map((issue) => ({
+      path: ["meta", ...issue.path.map(String)].join("."),
+      message: issue.message,
+    })),
+  };
+}