@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

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

@@ -0,0 +1,114 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type {
+  HandlerContext,
+  SessionUser,
+  TenantId,
+  WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { createFileRefFromBytes, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { fileContextForTenant } from "../file-foundation/index.js";
+import { requireForTenant } from "../shared/index.js";
+import { executor } from "./handlers/shared.js";
+import type { LinkedResourceEntry } from "./linked-resources.js";
+import { type TemplateResourceRow, templateResourcesTable } from "./table.js";
+
+export type TemplateResourceFile = {
+  readonly fileName: string;
+  readonly contentType: string;
+  readonly bytes: Uint8Array;
+};
+
+type FileRefRow = {
+  readonly storageKey: string;
+  readonly fileName: string;
+  readonly mimeType: string;
+};
+
+// Reads the file behind a template resource. Null when the fileRef is unknown
+// to the caller's tenant or has no bytes.
+export async function readTemplateResource(
+  ctx: Pick<HandlerContext, "db" | "files" | "user">,
+  fileRefId: string,
+): Promise<TemplateResourceFile | null> {
+  if (!ctx.files) return null;
+  const row = await fetchOne<FileRefRow>(ctx.db, fileRefsTable, {
+    id: fileRefId,
+    isDeleted: false,
+  });
+  if (!row) return null;
+  const handle = ctx.files.refFromFileRef(row);
+  if (!(await handle.exists())) return null;
+  return { fileName: row.fileName, contentType: row.mimeType, bytes: await handle.read() };
+}
+
+// Gives the target tenant its own copy of every file behind the entries, so a template that was
+// copied from the system default keeps working once the tenant exports it or measures its
+// attachments. Rendered-PDF links carry no file and pass through. An entry whose source file is
+// gone is left out: it could not be resolved at render time either.
+export async function duplicateLinkedResourceFiles(
+  ctx: HandlerContext,
+  args: {
+    readonly user: SessionUser;
+    readonly tenantId: TenantId;
+    readonly resources: Readonly<Record<string, LinkedResourceEntry>>;
+  },
+): Promise<WriteResult<Record<string, LinkedResourceEntry>>> {
+  const { user, tenantId } = args;
+  const { db } = requireForTenant(ctx, tenantId);
+  const copies: Record<string, LinkedResourceEntry> = {};
+  for (const [key, entry] of Object.entries(args.resources)) {
+    if (typeof entry !== "string" && entry.kind === "rendered-pdf") {
+      copies[key] = entry;
+      continue;
+    }
+    const sourceFileRefId = typeof entry === "string" ? entry : entry.fileRefId;
+    const file = await readTemplateResource(ctx, sourceFileRefId);
+    // skip: the source file is gone, there is nothing to copy
+    if (file === null) continue;
+    const created = await createFileRefFromBytes(
+      {
+        db,
+        files: fileContextForTenant(ctx, ctx.user.tenantId, tenantId),
+        registry: ctx.registry,
+        user: { ...user, tenantId },
+      },
+      { fileName: file.fileName, mimeType: file.contentType, data: file.bytes },
+    );
+    if (!created.isSuccess) return created;
+    copies[key] =
+      typeof entry === "string" ? created.data.id : { ...entry, fileRefId: created.data.id };
+  }
+  return { isSuccess: true, data: copies };
+}
+
+// Replaces the whole key map of one row with files that are already stored (bundle import,
+// copy-locale). Single keys go through storeTemplateResource and resource-remove.
+export async function attachTemplateResources(
+  ctx: Pick<HandlerContext, "forTenant">,
+  args: {
+    readonly user: SessionUser;
+    readonly tenantId: TenantId;
+    readonly templateId: string;
+    readonly resources: Readonly<Record<string, LinkedResourceEntry>>;
+  },
+): Promise<WriteResult<null>> {
+  if (Object.keys(args.resources).length === 0) return { isSuccess: true, data: null };
+  const { db, streamTenantId } = requireForTenant(ctx, args.tenantId);
+  const row = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+    id: args.templateId,
+    tenantId: args.tenantId,
+  });
+  if (!row) return writeFailure(new NotFoundError("template-resource", args.templateId));
+  const result = await executor.update(
+    {
+      id: row.id,
+      version: row.version,
+      changes: { linkedResources: JSON.stringify(args.resources) },
+    },
+    args.user,
+    db,
+    { streamTenantId },
+  );
+  return result.isSuccess ? { isSuccess: true, data: null } : result;
+}

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

@@ -0,0 +1,68 @@
+import {
+  type NotificationDefinition,
+  parseQn,
+  type Registry,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_MAIL_LAYOUT_SLUG, type TemplateKind } from "./constants.js";
+
+type UsageRole = "template" | "layout";
+
+export type TemplateUsageEntry = {
+  readonly qualifiedName: string;
+  readonly feature: string;
+  readonly notification: string;
+  readonly trigger: string | null;
+  readonly role: UsageRole;
+};
+
+/** Layout slug of the effective stored mail template, by notification qualified
+ *  name and locale. The renderer reads the layout from the stored row's meta,
+ *  so it wins over the code-registered notification meta. */
+export type EffectiveMailLayoutSlugs = ReadonlyMap<string, ReadonlyMap<string, string>>;
+
+function layoutSlugsOf(
+  qualifiedName: string,
+  notification: NotificationDefinition,
+  effectiveLayouts: EffectiveMailLayoutSlugs,
+): string[] {
+  const stored = effectiveLayouts.get(qualifiedName);
+  const locales = new Set([
+    ...Object.keys(notification.template ?? {}),
+    ...Object.keys(notification.meta ?? {}),
+    ...(stored?.keys() ?? []),
+  ]);
+  return [...locales].map(
+    (locale) =>
+      stored?.get(locale) ?? notification.meta?.[locale]?.layoutSlug ?? DEFAULT_MAIL_LAYOUT_SLUG,
+  );
+}
+
+export function collectTemplateUsage(
+  registry: Registry,
+  slug: string,
+  kind: TemplateKind,
+  effectiveLayouts: EffectiveMailLayoutSlugs = new Map(),
+): TemplateUsageEntry[] {
+  const usedBy: TemplateUsageEntry[] = [];
+  if (kind === "mail" || kind === "mail-layout") {
+    for (const [qualifiedName, notification] of registry.getAllNotifications()) {
+      const role: UsageRole = kind === "mail" ? "template" : "layout";
+      // Notifications without a code template are not rendered through the resolver.
+      const isUsed =
+        kind === "mail"
+          ? qualifiedName === slug && notification.template !== undefined
+          : layoutSlugsOf(qualifiedName, notification, effectiveLayouts).includes(slug);
+      if (!isUsed) continue;
+      const parsed = parseQn(qualifiedName);
+      usedBy.push({
+        qualifiedName,
+        feature: parsed.scope,
+        notification: parsed.name,
+        trigger: notification.trigger?.on ?? null,
+        role,
+      });
+    }
+  }
+  usedBy.sort((a, b) => a.qualifiedName.localeCompare(b.qualifiedName));
+  return usedBy;
+}

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

@@ -0,0 +1,230 @@
+import type {
+  Registry,
+  TemplateScalarVariableDef,
+  TemplateVariableDef,
+  TemplateVariables,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { Element as ScanElement } from "happy-dom";
+import * as z from "zod";
+import { withParsedDocument } from "./document-sanitizer.js";
+import { isDocumentPlaceholderHref, isDocumentReferenceName } from "./document-schema.js";
+import type { TemplateMeta } from "./template-meta.js";
+
+export const SYSTEM_PLACEHOLDERS: ReadonlySet<string> = new Set([
+  "tenantName",
+  "signature",
+  "imprint",
+  "unsubscribeUrl",
+]);
+
+const PAGE_PLACEHOLDERS = ["page", "pages"] as const;
+const PAGED_KINDS: ReadonlySet<string> = new Set(["document-pdf", "pdf-layout"]);
+
+export function systemPlaceholdersFor(kind: string): ReadonlySet<string> {
+  return PAGED_KINDS.has(kind)
+    ? new Set([...SYSTEM_PLACEHOLDERS, ...PAGE_PLACEHOLDERS])
+    : SYSTEM_PLACEHOLDERS;
+}
+
+const BASE_RESOURCE_KEYS = ["logo"] as const;
+
+export type TemplateValidation = {
+  readonly unknown: readonly string[];
+  readonly missingRequired: readonly string[];
+  readonly used: readonly string[];
+  /** data-resource keys with no uploaded file; a warning, never a blocker. */
+  readonly unknownResources: readonly string[];
+};
+
+// Mirrors TemplateVariableDef: a stored or draft schema keeps its label and example, which the
+// preview uses as sample values.
+const variableCommon = {
+  label: z.string().optional(),
+  required: z.boolean().optional(),
+};
+const textLikeExample = z.string().optional();
+
+const scalarVariableSchema = z.discriminatedUnion("type", [
+  z.object({ ...variableCommon, type: z.literal("text"), example: textLikeExample }),
+  z.object({ ...variableCommon, type: z.literal("link"), example: textLikeExample }),
+  z.object({ ...variableCommon, type: z.literal("richText"), example: textLikeExample }),
+  z.object({
+    ...variableCommon,
+    type: z.literal("money"),
+    example: z
+      .union([z.number(), z.object({ amount: z.number(), currency: z.string() })])
+      .optional(),
+  }),
+  z.object({ ...variableCommon, type: z.literal("date"), example: textLikeExample }),
+]);
+
+const variableDefSchema = z.union([
+  scalarVariableSchema,
+  z.object({
+    ...variableCommon,
+    type: z.literal("list"),
+    item: z.record(z.string(), scalarVariableSchema),
+    example: z.array(z.record(z.string(), z.unknown())).optional(),
+  }),
+]);
+
+// A stored variableSchema value is either a bare string (legacy "this is a text
+// variable") or a TemplateVariableDef object; anything else is not declared and
+// therefore shows up as an unknown placeholder instead of being guessed at.
+function toVariableDef(raw: unknown): TemplateVariableDef | null {
+  if (typeof raw === "string") return { type: "text" };
+  const parsed = variableDefSchema.safeParse(raw);
+  return parsed.success ? parsed.data : null;
+}
+
+export function resolveTemplateVariables(
+  registry: Registry,
+  slug: string,
+  variableSchema: Readonly<Record<string, unknown>>,
+): TemplateVariables {
+  const declared = registry.getAllNotifications().get(slug)?.variables;
+  return declared ?? variablesFromSchema(variableSchema);
+}
+
+export function variablesFromSchema(
+  variableSchema: Readonly<Record<string, unknown>>,
+): TemplateVariables {
+  const variables: Record<string, TemplateVariableDef> = {};
+  for (const [name, raw] of Object.entries(variableSchema)) {
+    const def = toVariableDef(raw);
+    if (def !== null) variables[name] = def;
+  }
+  return variables;
+}
+
+type Resolution = { readonly known: boolean; readonly used: string };
+
+function rootName(name: string): string {
+  return name.split(".")[0] ?? name;
+}
+
+type PlaceholderScope = {
+  readonly variables: TemplateVariables;
+  readonly systemPlaceholders: ReadonlySet<string>;
+  readonly resourceKeys: ReadonlySet<string>;
+  readonly used: Set<string>;
+  readonly unknown: Set<string>;
+  readonly unknownResources: Set<string>;
+};
+
+function listItemFields(
+  variables: TemplateVariables,
+  listName: string | null,
+): Readonly<Record<string, TemplateScalarVariableDef>> {
+  const def =
+    listName !== null && Object.hasOwn(variables, listName) ? variables[listName] : undefined;
+  return def?.type === "list" ? def.item : {};
+}
+
+function isKnownName(
+  name: string,
+  scope: PlaceholderScope,
+  itemFields: Readonly<Record<string, unknown>>,
+): Resolution {
+  const { variables } = scope;
+  const root = rootName(name);
+  if (Object.hasOwn(itemFields, name) || Object.hasOwn(itemFields, root)) {
+    return { known: true, used: "" };
+  }
+  if (scope.systemPlaceholders.has(root)) return { known: true, used: "" };
+  if (Object.hasOwn(variables, name)) return { known: true, used: name };
+  if (Object.hasOwn(variables, root)) return { known: true, used: root };
+  return { known: false, used: "" };
+}
+
+function recordName(
+  name: string,
+  itemFields: Readonly<Record<string, unknown>>,
+  scope: PlaceholderScope,
+) {
+  const resolution = isKnownName(name, scope, itemFields);
+  if (!resolution.known) scope.unknown.add(name);
+  else if (resolution.used !== "") scope.used.add(resolution.used);
+}
+
+function enclosingEachName(element: ScanElement): string | null {
+  return element.closest("tr[data-each]")?.getAttribute("data-each") ?? null;
+}
+
+function scanBodyPlaceholders(body: string, scope: PlaceholderScope): void {
+  withParsedDocument(body, (root) => {
+    for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
+      const listName = element.getAttribute("data-each") ?? "";
+      const def = Object.hasOwn(scope.variables, listName) ? scope.variables[listName] : undefined;
+      if (def?.type === "list") scope.used.add(listName);
+      else scope.unknown.add(listName);
+    }
+    for (const element of Array.from(
+      root.querySelectorAll("span[data-variable], a[href], img[data-resource]"),
+    )) {
+      const itemFields = listItemFields(scope.variables, enclosingEachName(element));
+      const tag = element.tagName.toLowerCase();
+      if (tag === "span") {
+        recordName(element.getAttribute("data-variable") ?? "", itemFields, scope);
+      } else if (tag === "a") {
+        const href = element.getAttribute("href") ?? "";
+        if (isDocumentPlaceholderHref(href)) recordName(href.slice(2, -2), itemFields, scope);
+      } else {
+        const key = element.getAttribute("data-resource") ?? "";
+        if (!scope.resourceKeys.has(key)) scope.unknownResources.add(key);
+      }
+    }
+  });
+}
+
+const HANDLEBARS_EXPRESSION = /\{\{([^{}]*)\}\}/g;
+
+// Meta text supports only plain `{{name}}` / `{{name.field}}`; every other
+// Handlebars construct is reported as unknown so it can never reach the compiler.
+function scanMetaPlaceholders(text: string, scope: PlaceholderScope): void {
+  const leftover = text.replace(HANDLEBARS_EXPRESSION, (_match, inner: string) => {
+    const name = inner.trim();
+    if (isDocumentReferenceName(name)) recordName(name, {}, scope);
+    else scope.unknown.add(`{{${inner}}}`);
+    return "";
+  });
+  if (/[{}]/.test(leftover)) scope.unknown.add("{");
+}
+
+function metaTexts(meta: TemplateMeta | null): readonly string[] {
+  if (meta === null || !("subject" in meta)) return [];
+  return [meta.subject, ...(meta.previewText === undefined ? [] : [meta.previewText])];
+}
+
+export function validateTemplatePlaceholders(input: {
+  readonly kind: string;
+  readonly body: string;
+  readonly meta: TemplateMeta | null;
+  readonly variables: TemplateVariables;
+  /** data-resource keys with an uploaded file besides the built-in `logo`. */
+  readonly resourceKeys?: readonly string[];
+}): TemplateValidation {
+  const scope: PlaceholderScope = {
+    variables: input.variables,
+    systemPlaceholders: systemPlaceholdersFor(input.kind),
+    resourceKeys: new Set([...BASE_RESOURCE_KEYS, ...(input.resourceKeys ?? [])]),
+    used: new Set(),
+    unknown: new Set(),
+    unknownResources: new Set(),
+  };
+  scanBodyPlaceholders(input.body, scope);
+  for (const text of metaTexts(input.meta)) scanMetaPlaceholders(text, scope);
+  const missingRequired = Object.entries(input.variables)
+    .filter(([name, def]) => def.required === true && !scope.used.has(name))
+    .map(([name]) => name);
+  return {
+    unknown: [...scope.unknown].sort(),
+    missingRequired: missingRequired.sort(),
+    used: [...scope.used].sort(),
+    unknownResources: [...scope.unknownResources].sort(),
+  };
+}
+
+export function hasPlaceholderProblems(validation: TemplateValidation): boolean {
+  return validation.unknown.length > 0 || validation.missingRequired.length > 0;
+}

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

@@ -79,7 +79,7 @@ export async function assertConsumerHandlesNotFound(
     await consumer.resolve({
       tenantId,
       slug,
-      kind: "mail-html",
+      kind: "mail",
       locale: "de",
     });
   } catch (e) {
@@ -105,7 +105,7 @@ export async function assertConsumerRespectsLocaleFallback(
   await seedTemplate(db, {
     tenantId: SYSTEM_TENANT_ID,
     slug,
-    kind: "notification",
+    kind: "document-pdf",
     locale: FALLBACK_LOCALE,
     scope: "system",
     content: "conformance-fallback-content",
@@ -113,7 +113,7 @@ export async function assertConsumerRespectsLocaleFallback(
   const result = await consumer.resolve({
     tenantId,
     slug,
-    kind: "notification",
+    kind: "document-pdf",
     locale: "tr",
   });
   if (result.locale !== FALLBACK_LOCALE) {
@@ -143,7 +143,7 @@ export async function assertConsumerHandlesMissingResourceKeys(
   await seedTemplate(db, {
     tenantId: SYSTEM_TENANT_ID,
     slug,
-    kind: "mail-html",
+    kind: "mail",
     locale: "de",
     scope: "system",
     linkedResources: { logo: "file_missing" },
@@ -151,7 +151,7 @@ export async function assertConsumerHandlesMissingResourceKeys(
   const template = await consumer.resolve({
     tenantId,
     slug,
-    kind: "mail-html",
+    kind: "mail",
     locale: "de",
   });
 

package/packages/bundled-features/src/template-resolver/web/client-plugin.tsx

@@ -40,6 +40,8 @@ import {
   TemplateResolverHandlers,
   TemplateResolverQueries,
 } from "../qualified-names.js";
+import { DocumentBlocksContext, DocumentContentEditor } from "./document-editor.js";
+import { documentBlocksForKind } from "./document-toolbar-blocks.js";
 import { defaultTranslations } from "./i18n.js";
 
 // Exported for the unit test — groupBlocksByFolder is a pure function.
@@ -256,21 +258,22 @@ type TextBlock = {
   readonly modifiedAt: string | null;
 };
 
-// The collection's declared contentFormat ("plain" | "rich" | "markdown",
-// see ContentCollectionDefinition.contentFormat) uses a different vocabulary
+// The collection's declared contentFormat ("plain" | "rich" | "markdown" |
+// "document", see ContentCollectionDefinition.contentFormat) uses a different vocabulary
 // than the stored entry's contentFormat ("plain" | "html" | "markdown" |
-// "mjml", see CONTENT_FORMATS) — "rich" always stores HTML. Without this,
+// "mjml", see CONTENT_FORMATS) — "rich" and "document" always store HTML. Without this,
 // handleSave omitting contentFormat let the write schema's
 // contentFormatSchema.default("markdown") silently stamp every save as
 // markdown, clobbering e.g. a "plain" entry. Undefined (no collection, or
 // the collection didn't declare a format) keeps whatever was already saved
 // instead of guessing.
-function resolveWriteContentFormat(
+// Exported for the unit test — resolveWriteContentFormat is a pure function.
+export function resolveWriteContentFormat(
   collectionContentFormat: string | undefined,
   loadedContentFormat: string | undefined,
 ): string | undefined {
   if (collectionContentFormat === "plain") return "plain";
-  if (collectionContentFormat === "rich") return "html";
+  if (collectionContentFormat === "rich" || collectionContentFormat === "document") return "html";
   if (collectionContentFormat === "markdown") return "markdown";
   return loadedContentFormat;
 }
@@ -309,6 +312,7 @@ function TextBlockEditor({
   const contentFormat = findContentFormat(features, collectionId);
   const variableExamples = findVariableExamples(features, collectionId);
   const variables = Object.keys(variableExamples);
+  const documentBlocks = documentBlocksForKind(findCollection(features, collectionId)?.kind);
   const ContentEditor = useContentEditor(contentFormat);
   const canWrite =
     user?.roles.includes("TenantAdmin") === true || user?.roles.includes("SystemAdmin") === true;
@@ -446,13 +450,15 @@ function TextBlockEditor({
             contentFormat={contentFormat}
           />
         ) : (
-          <ContentEditor
-            id={contentEditorId}
-            value={content}
-            onChange={setContent}
-            variables={variables}
-            readOnly={disabled}
-          />
+          <DocumentBlocksContext.Provider value={documentBlocks}>
+            <ContentEditor
+              id={contentEditorId}
+              value={content}
+              onChange={setContent}
+              variables={variables}
+              readOnly={disabled}
+            />
+          </DocumentBlocksContext.Provider>
         )}
       </Field>
       {saveError !== null && <Banner variant="error">{saveError}</Banner>}
@@ -499,12 +505,13 @@ export function textBlocksClient(opts?: {
     resolvers: {
       "template-resolver:edit": TextBlockEditor,
     },
-    // The default for every "plain" collection (ai-prompt, mail-html without
+    // The default for every "plain" collection (ai-prompt, mail without
     // an explicit rich override) — an app-registered "plain" editor on
     // another clientFeature still wins, last-wins same as columnRenderers.
     contentEditors: {
       plain: PlainContentEditor,
       rich: RichContentEditor,
+      document: DocumentContentEditor,
       // ponytail: same textarea+chips as "plain" — markdown is stored as
       // text either way. Shares PlainContentEditor's fixed-DOM-id ceiling
       // (see its own file comment); swap for a live-preview widget or a