@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

package/packages/bundled-features/src/template-resolver/handlers/toggle-status.write.ts

@@ -1,32 +1,63 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  defineWriteHandler,
+  type Registry,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type FieldIssue,
+  NotFoundError,
+  ValidationError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
 import type { TemplateResourceRow } from "../table.js";
 import { templateResourcesTable } from "../table.js";
 import { executor } from "./shared.js";
+import { publishGateIssues } from "./template-gates.js";
 
 type TemplateStatus = "active" | "archived";
+type StatusTarget = "own" | "system";
 
-function createStatusUpdateHandler(name: string, status: TemplateStatus, description: string) {
+function isRowOfTarget(row: TemplateResourceRow, target: StatusTarget, callerTenantId: string) {
+  return target === "system"
+    ? row.tenantId === SYSTEM_TENANT_ID && row.scope === "system"
+    : row.tenantId === callerTenantId && row.scope === "tenant";
+}
+
+function createStatusUpdateHandler(
+  name: string,
+  target: StatusTarget,
+  status: TemplateStatus,
+  description: string,
+  gate?: (registry: Registry, row: TemplateResourceRow) => readonly FieldIssue[],
+) {
   return defineWriteHandler({
     name,
     schema: z.object({ id: z.string().min(1) }),
-    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    access: { roles: target === "system" ? ["SystemAdmin"] : ["TenantAdmin", "SystemAdmin"] },
+    // A system template change reaches every tenant without an override.
+    ...(target === "system" ? { agent: { risk: "high" as const } } : {}),
     description,
     handler: async (event, ctx) => {
-      // ctx.db is tenant-scoped: a foreign tenant's id reads as absent → NotFound.
-      // Cross-tenant toggling needs SystemAdmin with tenantIdOverride.
-      const existing = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+      const scoped = target === "system" ? requireForTenant(ctx, SYSTEM_TENANT_ID) : null;
+      const db = scoped?.db ?? ctx.db;
+      // The tenant db also reads system rows; the row's own tenant must match
+      // the target or the executor would append to a foreign event stream.
+      const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
         id: event.payload.id,
       });
-      if (!existing) {
+      if (!existing || !isRowOfTarget(existing, target, event.user.tenantId)) {
         return writeFailure(new NotFoundError("template-resource", event.payload.id));
       }
+      const issues = gate?.(ctx.registry, existing) ?? [];
+      if (issues.length > 0) return writeFailure(new ValidationError({ fields: [...issues] }));
       const result = await executor.update(
         { id: existing.id, version: existing.version, changes: { status } },
         event.user,
-        ctx.db,
+        db,
+        scoped ? { streamTenantId: scoped.streamTenantId } : undefined,
       );
       if (!result.isSuccess) return result;
       return { isSuccess: true as const, data: { id: String(existing.id), status } };
@@ -36,11 +67,27 @@ function createStatusUpdateHandler(name: string, status: TemplateStatus, descrip
 
 export const archiveWrite = createStatusUpdateHandler(
   "archive",
+  "own",
   "archived",
   "Sets one template resource of the caller's tenant to archived so the resolver stops serving it while the row and its content survive; use it to retire a template reversibly instead of deleting it.",
 );
 export const publishWrite = createStatusUpdateHandler(
   "publish",
+  "own",
+  "active",
+  "Sets one template resource of the caller's tenant to active so the resolver starts serving it; use it to release a draft written by upsert-tenant, or to bring an archived template back; a mail template with unknown placeholders or unused required variables is refused.",
+  publishGateIssues,
+);
+export const archiveSystemWrite = createStatusUpdateHandler(
+  "archive-system",
+  "system",
+  "archived",
+  "Sets one system-default template to archived so the resolver stops serving it to every tenant that has no override; SystemAdmin only, reversible with publish-system.",
+);
+export const publishSystemWrite = createStatusUpdateHandler(
+  "publish-system",
+  "system",
   "active",
-  "Sets one template resource of the caller's tenant to active so the resolver starts serving it; use it to release a draft written by upsert-tenant, or to bring an archived template back.",
+  "Sets one system-default template to active so the resolver serves it again to every tenant that has no override; SystemAdmin only, a mail template with unknown placeholders or unused required variables is refused.",
+  publishGateIssues,
 );

package/packages/bundled-features/src/template-resolver/handlers/upsert-system.write.ts

@@ -1,13 +1,7 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import {
-  defineWriteHandler,
-  SYSTEM_TENANT_ID,
-  type TenantId,
-} from "@cosmicdrift/kumiko-framework/engine";
-import { requireForTenant } from "../../shared/index.js";
-import type { TemplateResourceRow } from "../table.js";
-import { templateResourcesTable } from "../table.js";
-import { executor, upsertPayloadSchema } from "./shared.js";
+import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveTemplateVariables } from "../template-validation.js";
+import { upsertPayloadSchema } from "./shared.js";
+import { writeTemplateRow } from "./template-write.js";
 
 // System-Template anlegen/updaten. Liegt unter SYSTEM_TENANT_ID,
 // scope='system'. Nur SystemAdmin (globale Rolle). TenantAdmin kann
@@ -18,65 +12,19 @@ export const upsertSystemWrite = defineWriteHandler({
   schema: upsertPayloadSchema,
   access: { roles: ["SystemAdmin"] },
   description:
-    "Creates or overwrites a system-default template under the system tenant with its full variable schema and linked resources, active straight away with no draft stage; SystemAdmin only, since tenants shadow these defaults through upsert-tenant instead.",
-  handler: async (event, ctx) => {
-    // @cast-boundary engine-payload — SYSTEM_TENANT_ID is a UUID literal,
-    // asserted to the branded TenantId (parseTenantId equivalent).
-    const tenantId = SYSTEM_TENANT_ID as TenantId;
-    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
-
-    const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
-      tenantId,
-      slug: event.payload.slug,
-      kind: event.payload.kind,
-      locale: event.payload.locale,
-    });
-
-    const fields = {
-      slug: event.payload.slug,
-      kind: event.payload.kind,
-      locale: event.payload.locale,
-      content: event.payload.content,
-      contentFormat: event.payload.contentFormat,
-      variableSchema: JSON.stringify(event.payload.variableSchema),
-      linkedResources: JSON.stringify(event.payload.linkedResources),
-      title: event.payload.title ?? null,
-      folder: event.payload.folder ?? null,
-      scope: "system" as const,
-      parentTemplateId: event.payload.parentTemplateId ?? null,
-      // System-Defaults sind sofort active (kein draft-Stage für seeds).
-      status: "active" as const,
-    };
-
-    if (existing) {
-      const result = await executor.update(
-        { id: existing.id, version: existing.version, changes: fields },
-        event.user,
-        db,
-        { streamTenantId },
-      );
-      if (!result.isSuccess) return result;
-      return {
-        isSuccess: true as const,
-        data: { id: String(existing.id), slug: event.payload.slug, isNew: false },
-      };
-    }
-
-    const result = await executor.create({ ...fields, tenantId }, event.user, db, {
-      streamTenantId,
-    });
-    if (!result.isSuccess) return result;
-    // @cast-boundary db-row — executor.create returnt Record-row aus
-    // INSERT RETURNING; shape { id } ist garantiert weil PK in der
-    // Returning-Klausel ist.
-    const createdRow = result.data as { id: string | number };
-    return {
-      isSuccess: true as const,
-      data: {
-        id: String(createdRow.id),
-        slug: event.payload.slug,
-        isNew: true,
-      },
-    };
-  },
+    "Creates or overwrites a system-default template under the system tenant with its full variable schema (resource files go through the resource upload), active straight away with no draft stage; SystemAdmin only, since tenants shadow these defaults through upsert-tenant instead.",
+  handler: (event, ctx) =>
+    writeTemplateRow({
+      ctx,
+      user: event.user,
+      tenantId: SYSTEM_TENANT_ID,
+      scope: "system",
+      status: "active",
+      variables: resolveTemplateVariables(
+        ctx.registry,
+        event.payload.slug,
+        event.payload.variableSchema,
+      ),
+      payload: event.payload,
+    }),
 });

package/packages/bundled-features/src/template-resolver/handlers/upsert-tenant.write.ts

@@ -1,15 +1,8 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import {
-  defineWriteHandler,
-  SYSTEM_TENANT_ID,
-  type TenantId,
-} from "@cosmicdrift/kumiko-framework/engine";
-import { AccessDeniedError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { requireForTenant } from "../../shared/index.js";
-import type { TemplateResourceRow } from "../table.js";
-import { templateResourcesTable } from "../table.js";
-import { executor, upsertPayloadSchema } from "./shared.js";
+import { resolveTemplateVariables } from "../template-validation.js";
+import { upsertPayloadSchema } from "./shared.js";
+import { writeTemplateRow } from "./template-write.js";
 
 // Tenant-Override anlegen/updaten. Liegt unter event.user.tenantId,
 // scope='tenant'. Default-Status='draft' — User publisht explizit
@@ -26,76 +19,22 @@ export const upsertTenantWrite = defineWriteHandler({
   description:
     "Creates or overwrites a tenant-scoped template override with its variable schema, landing as a draft that only publish makes live; it refuses a system-tenant target, which is what upsert-system is for.",
   handler: async (event, ctx) => {
-    const override = event.payload.tenantIdOverride;
-    // upsertTenant erzeugt scope='tenant'. SYSTEM_TENANT_ID-Override würde
-    // scope='tenant' unter SYSTEM_TENANT_ID schreiben → inkonsistenter Zustand
-    // (Resolver-Logik trennt sauber zwischen system+tenant). SystemAdmin muss
-    // upsertSystem für System-Defaults nutzen.
-    if (override === SYSTEM_TENANT_ID) {
-      return writeFailure(
-        new AccessDeniedError({
-          i18nKey: "templateResolver.errors.useUpsertSystemForSystemTenant",
-          details: { reason: "system_tenant_override_not_allowed_use_upsert_system" },
-        }),
-      );
-    }
     // @cast-boundary engine-payload — override aus Zod-parsed string,
     // event.user.tenantId schon TenantId-branded; union als TenantId casten
     // ist legit (override ist UUID-Format-validiert in schema).
-    const tenantId = (override ?? event.user.tenantId) as TenantId;
-    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
-
-    const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+    const tenantId = (event.payload.tenantIdOverride ?? event.user.tenantId) as TenantId;
+    return writeTemplateRow({
+      ctx,
+      user: event.user,
       tenantId,
-      slug: event.payload.slug,
-      kind: event.payload.kind,
-      locale: event.payload.locale,
-    });
-
-    const fields = {
-      slug: event.payload.slug,
-      kind: event.payload.kind,
-      locale: event.payload.locale,
-      content: event.payload.content,
-      contentFormat: event.payload.contentFormat,
-      variableSchema: JSON.stringify(event.payload.variableSchema),
-      linkedResources: JSON.stringify(event.payload.linkedResources),
-      title: event.payload.title ?? null,
-      folder: event.payload.folder ?? null,
-      scope: "tenant" as const,
-      parentTemplateId: event.payload.parentTemplateId ?? null,
+      scope: "tenant",
       status: event.payload.status,
-    };
-
-    if (existing) {
-      const result = await executor.update(
-        { id: existing.id, version: existing.version, changes: fields },
-        event.user,
-        db,
-        { streamTenantId },
-      );
-      if (!result.isSuccess) return result;
-      return {
-        isSuccess: true as const,
-        data: { id: String(existing.id), slug: event.payload.slug, isNew: false },
-      };
-    }
-
-    const result = await executor.create({ ...fields, tenantId }, event.user, db, {
-      streamTenantId,
+      variables: resolveTemplateVariables(
+        ctx.registry,
+        event.payload.slug,
+        event.payload.variableSchema,
+      ),
+      payload: event.payload,
     });
-    if (!result.isSuccess) return result;
-    // @cast-boundary db-row — executor.create returnt Record-row aus
-    // INSERT RETURNING; shape { id } ist garantiert weil PK in der
-    // Returning-Klausel ist.
-    const createdRow = result.data as { id: string | number };
-    return {
-      isSuccess: true as const,
-      data: {
-        id: String(createdRow.id),
-        slug: event.payload.slug,
-        isNew: true,
-      },
-    };
   },
 });

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

@@ -0,0 +1,17 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { TEMPLATE_KINDS } from "../constants.js";
+import { templateSlugSchema } from "../template-meta.js";
+import { collectTemplateUsage } from "../template-usage.js";
+
+export const usageQuery = defineQueryHandler({
+  name: "usage",
+  schema: z.object({ slug: templateSlugSchema, kind: z.enum(TEMPLATE_KINDS) }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Lists the code-registered notifications that use one template: a mail template is used by the notification whose qualified name is its slug, a mail layout by every mail notification that names it in its meta or falls back to the default layout; use it to show what a change to a template affects.",
+  handler: async (query, ctx) => {
+    const { slug, kind } = query.payload;
+    return { usedBy: collectTemplateUsage(ctx.registry, slug, kind) };
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/validate.query.ts

@@ -0,0 +1,116 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  defineQueryHandler,
+  type HandlerContext,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import type { ContentFormat, UpsertKind } from "../constants.js";
+import type { TemplateWriteScope } from "../layout-regions.js";
+import { imageResourceKeysOf } from "../linked-resources.js";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { resolveTemplateVariables, systemPlaceholdersFor } from "../template-validation.js";
+import { contentFormatSchema, kindSchema, localeSchema, templateSlugSchema } from "./shared.js";
+import { evaluateTemplateWrite } from "./template-gates.js";
+
+async function knownResourceKeys(
+  db: Parameters<typeof selectMany>[0],
+  where: {
+    readonly tenantId: string;
+    readonly slug: string;
+    readonly kind: string;
+    readonly scope: "tenant" | "system";
+    readonly locale: string | undefined;
+  },
+): Promise<string[]> {
+  const rows = await selectMany<TemplateResourceRow>(db, templateResourcesTable, {
+    tenantId: where.tenantId,
+    slug: where.slug,
+    kind: where.kind,
+    scope: where.scope,
+    ...(where.locale === undefined ? {} : { locale: where.locale }),
+    ...(where.scope === "system" ? { status: "active" } : {}),
+  });
+  return rows.flatMap((row) => imageResourceKeysOf(row.linkedResources));
+}
+
+type TemplateDraftInput = {
+  readonly slug: string;
+  readonly kind: UpsertKind;
+  readonly contentFormat: ContentFormat;
+  readonly content: string;
+  readonly meta?: unknown;
+  readonly variableSchema: Readonly<Record<string, unknown>>;
+  readonly locale?: string | undefined;
+  readonly scope: TemplateWriteScope;
+};
+
+// The dry run of the write pipeline; preview feeds on the evaluation, validate returns the response.
+export async function validateTemplateDraft(
+  ctx: HandlerContext,
+  user: SessionUser,
+  payload: TemplateDraftInput,
+) {
+  const variables = resolveTemplateVariables(ctx.registry, payload.slug, payload.variableSchema);
+  const { slug, kind, scope, locale } = payload;
+  const known = [
+    ...(await knownResourceKeys(ctx.db, {
+      tenantId: SYSTEM_TENANT_ID,
+      slug,
+      kind,
+      scope: "system",
+      locale,
+    })),
+    ...(scope === "tenant"
+      ? await knownResourceKeys(ctx.db, { tenantId: user.tenantId, slug, kind, scope, locale })
+      : []),
+  ];
+  const evaluation = evaluateTemplateWrite({
+    kind,
+    scope,
+    contentFormat: payload.contentFormat,
+    content: payload.content,
+    rawMeta: payload.meta,
+    variables,
+    resourceKeys: known,
+  });
+  const validation = evaluation.validation;
+  const response = {
+    canSave: evaluation.ok,
+    canPublish: evaluation.ok && evaluation.publishIssues.length === 0,
+    issues: evaluation.ok ? [] : [...evaluation.issues],
+    publishIssues: evaluation.ok ? [...evaluation.publishIssues] : [],
+    used: [...(validation?.used ?? [])],
+    unknown: [...(validation?.unknown ?? [])],
+    missingRequired: [...(validation?.missingRequired ?? [])],
+    warnings: (validation?.unknownResources ?? []).map((key) => ({
+      code: "resource_not_uploaded" as const,
+      detail: key,
+      i18nKey: "templateResolver.warnings.resourceNotUploaded" as const,
+    })),
+    variables,
+    systemPlaceholders: [...systemPlaceholdersFor(kind)].sort(),
+  };
+  return { response, evaluation };
+}
+
+export const validateQuery = defineQueryHandler({
+  name: "validate",
+  schema: z.object({
+    slug: templateSlugSchema,
+    kind: kindSchema,
+    contentFormat: contentFormatSchema,
+    content: z.string().max(200_000),
+    meta: z.unknown().optional(),
+    variableSchema: z.record(z.string(), z.unknown()).default({}),
+    /** Narrows the known resource keys to one locale's rows. */
+    locale: localeSchema.optional(),
+    scope: z.enum(["tenant", "system"]).default("tenant"),
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Dry-runs the write pipeline for a template draft without saving: reports whether it can be saved or published, the sanitizer and placeholder problems, which placeholders it uses, which are unknown, which required variables are missing, and the variables and system placeholders available for the kind; use it to give an editor live feedback.",
+  handler: async (query, ctx) =>
+    (await validateTemplateDraft(ctx, query.user, query.payload)).response,
+});

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

@@ -6,12 +6,23 @@ export {
   type TemplateResolverApi,
   type TemplateResource,
 } from "./api.js";
+export {
+  type CompileDocumentBodyOptions,
+  collectDocumentResourceKeys,
+  compileDocumentBodyToHandlebars,
+  toResourceDataUri,
+} from "./compile-document-body.js";
 export {
   CONTENT_FORMATS,
   type ContentFormat,
+  DEFAULT_MAIL_LAYOUT_SLUG,
+  DOCUMENT_HTML_KINDS,
+  type DocumentHtmlKind,
   FALLBACK_LOCALE,
   NON_RENDER_KINDS,
   type NonRenderKind,
+  PDF_PAGE_FORMATS,
+  type PdfPageFormat,
   RENDER_KINDS,
   type RenderKind,
   SYSTEM_TENANT_ID,
@@ -25,18 +36,107 @@ export {
   UPSERT_KINDS,
   type UpsertKind,
 } from "./constants.js";
+export {
+  type DocumentViolation,
+  type DocumentViolationCode,
+  documentViolationsToFieldIssues,
+  type SanitizeBodyResult,
+  type SanitizeHtmlResult,
+  sanitizeDocumentHtml,
+  sanitizeTemplateBody,
+} from "./document-sanitizer.js";
+export {
+  DOCUMENT_NODE_NAMES,
+  DOCUMENT_TEXT_ALIGNMENTS,
+  DocumentButton,
+  DocumentDivider,
+  DocumentLink,
+  DocumentPageBreak,
+  DocumentRepeatRow,
+  DocumentResource,
+  DocumentTable,
+  DocumentTableCell,
+  DocumentTableHeader,
+  DocumentTableRow,
+  DocumentTextAlign,
+  type DocumentTextAlignment,
+  DocumentVariable,
+  documentExtensions,
+  isAllowedDocumentLinkHref,
+  isDocumentPlaceholderHref,
+  isDocumentReferenceName,
+  isDocumentResourceKey,
+} from "./document-schema.js";
 export { createTemplateResolverFeature } from "./feature.js";
+export type { LayoutSourceResponse, LayoutSourceRow } from "./handlers/layout-source.query.js";
+export type {
+  OverviewKindGroup,
+  OverviewOrigin,
+  OverviewResponse,
+  OverviewRow,
+  OverviewUsage,
+} from "./handlers/overview.query.js";
+export { localeSchema } from "./handlers/shared.js";
+export {
+  type LayoutRegions,
+  readLayoutRegions,
+  type SanitizeLayoutResult,
+  sanitizeLayoutHtml,
+} from "./layout-regions.js";
+export {
+  fileAttachmentsOf,
+  imageLinksOf,
+  type LinkedResourceEntry,
+  parseLinkedResourceEntries,
+  pdfAttachmentLinksOf,
+  type TemplatePdfAttachmentLink,
+  templatePdfAttachmentLinkSchema,
+} from "./linked-resources.js";
+export { prepareDocumentForPrint } from "./print-document.js";
 export {
   TEMPLATE_RESOLVER_FEATURE,
   TemplateResolverErrors,
   TemplateResolverHandlers,
   TemplateResolverQueries,
 } from "./qualified-names.js";
+export { mapRecordToVariables } from "./record-mapping.js";
+export {
+  readTemplateResourceMaxBytes,
+  type StoredTemplateResource,
+  storeTemplateResource,
+} from "./store-template-resource.js";
 export {
   type TemplateResourceRow,
   templateResourceEntity,
   templateResourcesTable,
 } from "./table.js";
+export { type TemplateBundle, templateBundleSchema } from "./template-bundle.js";
+export {
+  isMailTemplateMeta,
+  type LayoutTemplateMeta,
+  MAIL_CATEGORIES,
+  type MailCategory,
+  type MailTemplateMeta,
+  type PdfTemplateMeta,
+  parseTemplateMeta,
+  pdfAttachmentFileNamePatternSchema,
+  readPdfTemplateMeta,
+  type TemplateMeta,
+  type TemplateMetaIssue,
+  type TemplateMetaResult,
+  templateSlugSchema,
+} from "./template-meta.js";
+export { type DocumentDraftOutcome, evaluateDocumentDraft } from "./template-preview.js";
+export { readTemplateResource, type TemplateResourceFile } from "./template-resources.js";
+export { collectTemplateUsage, type TemplateUsageEntry } from "./template-usage.js";
+export {
+  hasPlaceholderProblems,
+  resolveTemplateVariables,
+  SYSTEM_PLACEHOLDERS,
+  systemPlaceholdersFor,
+  type TemplateValidation,
+  validateTemplatePlaceholders,
+} from "./template-validation.js";
 export {
   type UserContentEntryRow,
   userContentEntriesTable,