@cosmicdrift/kumiko-samples 0.377.0 → 0.378.0

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

@@ -11,6 +11,7 @@ import {
   parseTemplateDraft,
   servedVersionOf,
 } from "../template-draft.ts";
+import { mayEditTemplate, type TemplateEditPolicy } from "../template-edit-policy.ts";
 import { isSystemOnlyTemplateHiddenFrom } from "../template-system-only.ts";
 import { collectTemplateUsage, type EffectiveMailLayoutSlugs } from "../template-usage.ts";
 import { storedRecord } from "./template-gates.ts";
@@ -271,68 +272,71 @@ const filterSchema = z.object({
   value: z.array(z.string()),
 });
 
-export const overviewQuery = defineQueryHandler({
-  name: "overview",
-  schema: z.object({
-    search: z.string().optional(),
-    filters: z.array(filterSchema).optional(),
-    layoutSlug: z.string().optional(),
-    sort: z.string().optional(),
-    sortDirection: z.enum(["asc", "desc"]).optional(),
-    limit: z.number().int().min(1).max(200).default(50),
-    offset: z.number().int().min(0).optional(),
-    totalCount: z.boolean().optional(),
-  }),
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  description:
-    "Lists mail, PDF and layout templates as one row per slug and kind for the caller's tenant (optionally only the mails and PDFs using one layout slug): where the effective version comes from (own override or system), its locales, status and version (the served one; `draftVersion` is set when an unpublished draft waits beside it, `activeSince` says since when the served version applies), the system version it overrides, the layout it uses and which notifications or templates use it; templates of notifications registered with `systemOnly` are listed for SystemAdmins only; use it to browse and filter all templates at a glance.",
-  handler: async (query, ctx) => {
-    const payload = query.payload;
-    const fetchedRows = await selectMany<TemplateResourceRow>(
-      ctx.db,
-      templateResourcesTable,
-      { kind: { in: [...OVERVIEW_KINDS] } },
-      { orderBy: { col: "id", direction: "asc" }, limit: OVERVIEW_ROW_LIMIT + 1 },
-    );
-    const truncated = fetchedRows.length > OVERVIEW_ROW_LIMIT;
-    const rows = truncated ? fetchedRows.slice(0, OVERVIEW_ROW_LIMIT) : fetchedRows;
-    if (truncated) {
-      ctx.log?.warn("template overview: row limit reached, result is incomplete", {
-        limit: OVERVIEW_ROW_LIMIT,
-      });
-    }
+export function makeOverviewQuery(policy: TemplateEditPolicy) {
+  return defineQueryHandler({
+    name: "overview",
+    schema: z.object({
+      search: z.string().optional(),
+      filters: z.array(filterSchema).optional(),
+      layoutSlug: z.string().optional(),
+      sort: z.string().optional(),
+      sortDirection: z.enum(["asc", "desc"]).optional(),
+      limit: z.number().int().min(1).max(200).default(50),
+      offset: z.number().int().min(0).optional(),
+      totalCount: z.boolean().optional(),
+    }),
+    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    description:
+      "Lists mail, PDF and layout templates as one row per slug and kind for the caller's tenant (optionally only the mails and PDFs using one layout slug): where the effective version comes from (own override or system), its locales, status and version (the served one; `draftVersion` is set when an unpublished draft waits beside it, `activeSince` says since when the served version applies), the system version it overrides, the layout it uses and which notifications or templates use it; templates of notifications registered with `systemOnly` are listed for SystemAdmins only, and a TenantAdmin sees only the templates the app lists in tenantEditable; use it to browse and filter all templates at a glance.",
+    handler: async (query, ctx) => {
+      const payload = query.payload;
+      const fetchedRows = await selectMany<TemplateResourceRow>(
+        ctx.db,
+        templateResourcesTable,
+        { kind: { in: [...OVERVIEW_KINDS] } },
+        { orderBy: { col: "id", direction: "asc" }, limit: OVERVIEW_ROW_LIMIT + 1 },
+      );
+      const truncated = fetchedRows.length > OVERVIEW_ROW_LIMIT;
+      const rows = truncated ? fetchedRows.slice(0, OVERVIEW_ROW_LIMIT) : fetchedRows;
+      if (truncated) {
+        ctx.log?.warn("template overview: row limit reached, result is incomplete", {
+          limit: OVERVIEW_ROW_LIMIT,
+        });
+      }
 
-    const visibleRows = rows.filter(
-      (row) =>
-        !isHiddenSystemDraft(query.user, row) &&
-        !isSystemOnlyTemplateHiddenFrom(query.user, ctx.registry, row),
-    );
-    const { drafts, layoutSlugByDocument } = buildDrafts(
-      groupBySlugAndKind(visibleRows),
-      query.user,
-    );
-    const effectiveLayouts = effectiveMailLayoutSlugs(visibleRows);
-    const overviewRows = drafts.map((draft) =>
-      withUsage(draft, layoutSlugByDocument, ctx.registry, effectiveLayouts),
-    );
-    const filtered = filterRows(
-      overviewRows,
-      payload.search,
-      payload.filters ?? [],
-      payload.layoutSlug,
-    );
+      const visibleRows = rows.filter(
+        (row) =>
+          !isHiddenSystemDraft(query.user, row) &&
+          !isSystemOnlyTemplateHiddenFrom(query.user, ctx.registry, row) &&
+          mayEditTemplate(policy, query.user, row),
+      );
+      const { drafts, layoutSlugByDocument } = buildDrafts(
+        groupBySlugAndKind(visibleRows),
+        query.user,
+      );
+      const effectiveLayouts = effectiveMailLayoutSlugs(visibleRows);
+      const overviewRows = drafts.map((draft) =>
+        withUsage(draft, layoutSlugByDocument, ctx.registry, effectiveLayouts),
+      );
+      const filtered = filterRows(
+        overviewRows,
+        payload.search,
+        payload.filters ?? [],
+        payload.layoutSlug,
+      );
 
-    const sortField: SortField =
-      payload.sort !== undefined && isSortField(payload.sort) ? payload.sort : "modifiedAt";
-    const direction = (payload.sortDirection ?? "desc") === "desc" ? -1 : 1;
-    filtered.sort((a, b) => direction * compareBy(sortField, a, b) || a.id.localeCompare(b.id));
+      const sortField: SortField =
+        payload.sort !== undefined && isSortField(payload.sort) ? payload.sort : "modifiedAt";
+      const direction = (payload.sortDirection ?? "desc") === "desc" ? -1 : 1;
+      filtered.sort((a, b) => direction * compareBy(sortField, a, b) || a.id.localeCompare(b.id));
 
-    const offset = payload.offset ?? 0;
-    return {
-      rows: filtered.slice(offset, offset + payload.limit),
-      nextCursor: null,
-      total: filtered.length,
-      truncated,
-    } satisfies OverviewResponse;
-  },
-});
+      const offset = payload.offset ?? 0;
+      return {
+        rows: filtered.slice(offset, offset + payload.limit),
+        nextCursor: null,
+        total: filtered.length,
+        truncated,
+      } satisfies OverviewResponse;
+    },
+  });
+}

package/packages/bundled-features/src/template-resolver/handlers/patch-draft.write.ts

@@ -10,6 +10,11 @@ import * as z from "zod";
 import { DOCUMENT_HTML_KINDS } from "../constants.ts";
 import { applyDocumentOps, documentOpsSchema } from "../document-ops.ts";
 import { parseDocumentJson, serializeDocumentJson } from "../document-sanitizer.ts";
+import {
+  refuseTemplateEdit,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
 import { resolveTemplateVariables } from "../template-validation.ts";
 import { loadDocumentBase } from "./document-base.ts";
 import { localeSchema, templateSlugSchema } from "./shared.ts";
@@ -20,106 +25,110 @@ function validationFailure(issue: FieldIssue) {
   return writeFailure(new ValidationError({ fields: [issue] }));
 }
 
-export const patchDraftWrite = defineWriteHandler({
-  name: "patch-draft",
-  schema: z.object({
-    slug: templateSlugSchema,
-    kind: z.enum(DOCUMENT_HTML_KINDS),
-    locale: localeSchema,
-    base: z.object({
-      scope: z.enum(["tenant", "system"]),
-      version: z.number().int().nonnegative(),
+export function makePatchDraftWrite(policy: TemplateEditPolicy) {
+  return defineWriteHandler({
+    name: "patch-draft",
+    schema: z.object({
+      slug: templateSlugSchema,
+      kind: z.enum(DOCUMENT_HTML_KINDS),
+      locale: localeSchema,
+      base: z.object({
+        scope: z.enum(["tenant", "system"]),
+        version: z.number().int().nonnegative(),
+      }),
+      ops: documentOpsSchema,
     }),
-    ops: documentOpsSchema,
-  }),
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  description:
-    "Changes a mail or PDF document template with structured operations instead of a full rewrite and saves the result as the caller's tenant draft (never published, an active version keeps being served until publish): insertBlock after a block id (null = at the start; paragraph, heading, image, button, divider, pageBreak), replaceText inside one block (the text must occur exactly once), removeBlock, setResource on an image block, setMeta (flat merge, null removes a key) and setVariable (adds, replaces or with null removes a variable definition; refused when a notification declares the variables). Block ids and base come from document-blocks and refer to the state that was read; if the template changed since, the call fails with version_conflict and nothing is written. A patch that removes a required placeholder is refused. Returns the written row.",
-  handler: async (event, ctx) => {
-    const { slug, kind, locale, base, ops } = event.payload;
-    const loaded = await loadDocumentBase(ctx, event.user, { slug, kind, locale });
-    if (loaded === null) return writeFailure(new NotFoundError("template-resource", slug));
-    if (loaded.base.scope !== base.scope || loaded.base.version !== base.version) {
-      return writeFailure(
-        new VersionConflictError({
-          entityId: loaded.rowId,
-          expectedVersion: base.version,
-          currentVersion: loaded.base.version,
-        }),
-      );
-    }
+    access: templateEditAccess(policy.tenantEditable),
+    description:
+      "Changes a mail or PDF document template with structured operations instead of a full rewrite and saves the result as the caller's tenant draft (never published, an active version keeps being served until publish): insertBlock after a block id (null = at the start; paragraph, heading, image, button, divider, pageBreak), replaceText inside one block (the text must occur exactly once), removeBlock, setResource on an image block, setMeta (flat merge, null removes a key) and setVariable (adds, replaces or with null removes a variable definition; refused when a notification declares the variables). Block ids and base come from document-blocks and refer to the state that was read; if the template changed since, the call fails with version_conflict and nothing is written. A patch that removes a required placeholder is refused. A TenantAdmin may patch only templates the app lists in tenantEditable, otherwise SystemAdmin only. Returns the written row.",
+    handler: async (event, ctx) => {
+      const { slug, kind, locale, base, ops } = event.payload;
+      const refused = refuseTemplateEdit(policy, event.user, { slug, kind });
+      if (refused !== null) return refused;
+      const loaded = await loadDocumentBase(ctx, event.user, { slug, kind, locale });
+      if (loaded === null) return writeFailure(new NotFoundError("template-resource", slug));
+      if (loaded.base.scope !== base.scope || loaded.base.version !== base.version) {
+        return writeFailure(
+          new VersionConflictError({
+            entityId: loaded.rowId,
+            expectedVersion: base.version,
+            currentVersion: loaded.base.version,
+          }),
+        );
+      }
+
+      const variableOpIndex = ops.findIndex((op) => op.op === "setVariable");
+      if (
+        variableOpIndex !== -1 &&
+        ctx.registry.getAllNotifications().get(slug)?.variables !== undefined
+      ) {
+        return validationFailure({
+          path: `ops.${variableOpIndex}`,
+          code: "variables_declared_by_feature",
+          i18nKey: "templateResolver.errors.patch.variablesDeclaredByFeature",
+          params: { slug },
+        });
+      }
 
-    const variableOpIndex = ops.findIndex((op) => op.op === "setVariable");
-    if (
-      variableOpIndex !== -1 &&
-      ctx.registry.getAllNotifications().get(slug)?.variables !== undefined
-    ) {
-      return validationFailure({
-        path: `ops.${variableOpIndex}`,
-        code: "variables_declared_by_feature",
-        i18nKey: "templateResolver.errors.patch.variablesDeclaredByFeature",
-        params: { slug },
+      const applied = applyDocumentOps({
+        doc: parseDocumentJson(loaded.content),
+        meta: loaded.meta,
+        variableSchema: loaded.variableSchema,
+        kind,
+        ops,
       });
-    }
+      if (!applied.ok) return writeFailure(new ValidationError({ fields: applied.issues }));
+      const content = serializeDocumentJson(applied.doc);
 
-    const applied = applyDocumentOps({
-      doc: parseDocumentJson(loaded.content),
-      meta: loaded.meta,
-      variableSchema: loaded.variableSchema,
-      kind,
-      ops,
-    });
-    if (!applied.ok) return writeFailure(new ValidationError({ fields: applied.issues }));
-    const content = serializeDocumentJson(applied.doc);
+      const draftOf = (
+        draftContent: string,
+        meta: unknown,
+        variableSchema: Record<string, unknown>,
+      ) =>
+        validateTemplateDraft(ctx, event.user, {
+          slug,
+          kind,
+          contentFormat: "html",
+          content: draftContent,
+          meta,
+          variableSchema,
+          locale,
+          scope: "tenant",
+        });
+      const before = await draftOf(loaded.content, loaded.meta, loaded.variableSchema);
+      const after = await draftOf(content, applied.meta, applied.variableSchema);
+      const alreadyMissing = new Set(before.response.missingRequired);
+      const removed = after.response.missingRequired.filter((name) => !alreadyMissing.has(name));
+      if (removed.length > 0) {
+        return validationFailure({
+          path: "ops",
+          code: "required_placeholder_removed",
+          i18nKey: "templateResolver.errors.patch.requiredPlaceholderRemoved",
+          params: { names: removed },
+        });
+      }
 
-    const draftOf = (
-      draftContent: string,
-      meta: unknown,
-      variableSchema: Record<string, unknown>,
-    ) =>
-      validateTemplateDraft(ctx, event.user, {
-        slug,
-        kind,
-        contentFormat: "html",
-        content: draftContent,
-        meta,
-        variableSchema,
-        locale,
+      return writeTemplateRow({
+        ctx,
+        user: event.user,
+        tenantId: event.user.tenantId,
         scope: "tenant",
+        status: "draft",
+        variables: resolveTemplateVariables(ctx.registry, slug, applied.variableSchema),
+        payload: {
+          slug,
+          kind,
+          locale,
+          content,
+          contentFormat: "html",
+          variableSchema: applied.variableSchema,
+          meta: applied.meta,
+          title: loaded.title,
+          folder: loaded.folder,
+          parentTemplateId: loaded.parentTemplateId,
+        },
+        expectedVersion: loaded.base.scope === "tenant" ? loaded.base.version : null,
       });
-    const before = await draftOf(loaded.content, loaded.meta, loaded.variableSchema);
-    const after = await draftOf(content, applied.meta, applied.variableSchema);
-    const alreadyMissing = new Set(before.response.missingRequired);
-    const removed = after.response.missingRequired.filter((name) => !alreadyMissing.has(name));
-    if (removed.length > 0) {
-      return validationFailure({
-        path: "ops",
-        code: "required_placeholder_removed",
-        i18nKey: "templateResolver.errors.patch.requiredPlaceholderRemoved",
-        params: { names: removed },
-      });
-    }
-
-    return writeTemplateRow({
-      ctx,
-      user: event.user,
-      tenantId: event.user.tenantId,
-      scope: "tenant",
-      status: "draft",
-      variables: resolveTemplateVariables(ctx.registry, slug, applied.variableSchema),
-      payload: {
-        slug,
-        kind,
-        locale,
-        content,
-        contentFormat: "html",
-        variableSchema: applied.variableSchema,
-        meta: applied.meta,
-        title: loaded.title,
-        folder: loaded.folder,
-        parentTemplateId: loaded.parentTemplateId,
-      },
-      expectedVersion: loaded.base.scope === "tenant" ? loaded.base.version : null,
-    });
-  },
-});
+    },
+  });
+}

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

@@ -4,55 +4,68 @@ import { NotFoundError, ValidationError, writeFailure } from "@cosmicdrift/kumik
 import * as z from "zod";
 import type { TemplateResourceRow } from "../table.ts";
 import { templateResourcesTable } from "../table.ts";
+import {
+  refuseMissingTemplate,
+  refuseTemplateEdit,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
 import { executor } from "./shared.ts";
 
-export const resetToSystemWrite = defineWriteHandler({
-  name: "reset-to-system",
-  schema: z.object({ id: z.string().min(1) }),
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  description:
-    "Retires a tenant override by archiving it so the resolver serves the active system template again; the override and its content survive and can be published again. Refused when there is no active system template to fall back to.",
-  handler: async (event, ctx) => {
-    const existing = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
-      id: event.payload.id,
-    });
-    if (!existing || existing.tenantId !== event.user.tenantId || existing.scope !== "tenant") {
-      return writeFailure(new NotFoundError("template-resource", event.payload.id));
-    }
-    const systemRow = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
-      tenantId: SYSTEM_TENANT_ID,
-      slug: existing.slug,
-      kind: existing.kind,
-      locale: existing.locale,
-      status: "active",
-    });
-    if (!systemRow) {
-      return writeFailure(
-        new ValidationError({
-          fields: [
-            {
-              path: "id",
-              code: "no_system_template",
-              i18nKey: "templateResolver.errors.noSystemTemplate",
-            },
-          ],
-        }),
+export function makeResetToSystemWrite(policy: TemplateEditPolicy) {
+  return defineWriteHandler({
+    name: "reset-to-system",
+    schema: z.object({ id: z.string().min(1) }),
+    access: templateEditAccess(policy.tenantEditable),
+    description:
+      "Retires a tenant override by archiving it so the resolver serves the active system template again; the override and its content survive and can be published again. Refused when there is no active system template to fall back to. Outside the templates the app lists in tenantEditable only a SystemAdmin may use it.",
+    handler: async (event, ctx) => {
+      const existing = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+        id: event.payload.id,
+      });
+      if (!existing || existing.tenantId !== event.user.tenantId || existing.scope !== "tenant") {
+        return (
+          refuseMissingTemplate(policy, event.user) ??
+          writeFailure(new NotFoundError("template-resource", event.payload.id))
+        );
+      }
+      const refused = refuseTemplateEdit(policy, event.user, existing);
+      if (refused !== null) return refused;
+      const systemRow = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+        tenantId: SYSTEM_TENANT_ID,
+        slug: existing.slug,
+        kind: existing.kind,
+        locale: existing.locale,
+        status: "active",
+      });
+      if (!systemRow) {
+        return writeFailure(
+          new ValidationError({
+            fields: [
+              {
+                path: "id",
+                code: "no_system_template",
+                i18nKey: "templateResolver.errors.noSystemTemplate",
+              },
+            ],
+          }),
+        );
+      }
+      const response = {
+        isSuccess: true as const,
+        data: {
+          id: String(existing.id),
+          status: "archived" as const,
+          systemTemplateId: String(systemRow.id),
+        },
+      };
+      if (existing.status === "archived") return response;
+      const result = await executor.update(
+        { id: existing.id, version: existing.version, changes: { status: "archived" } },
+        event.user,
+        ctx.db,
       );
-    }
-    const response = {
-      isSuccess: true as const,
-      data: {
-        id: String(existing.id),
-        status: "archived" as const,
-        systemTemplateId: String(systemRow.id),
-      },
-    };
-    if (existing.status === "archived") return response;
-    const result = await executor.update(
-      { id: existing.id, version: existing.version, changes: { status: "archived" } },
-      event.user,
-      ctx.db,
-    );
-    return result.isSuccess ? response : result;
-  },
-});
+      return result.isSuccess ? response : result;
+    },
+  });
+}

package/packages/bundled-features/src/template-resolver/handlers/resource-link-pdf.write.ts

@@ -1,34 +1,49 @@
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { linkTemplatePdfAttachment } from "../store-template-resource.ts";
+import {
+  refuseTemplateEditById,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
 import { resourceKeySchema, resourceTargetTenantId } from "./resource-shared.ts";
 
-export const resourceLinkPdfWrite = defineWriteHandler({
-  name: "resource-link-pdf",
-  schema: z.object({
-    templateId: z.string().min(1),
-    key: resourceKeySchema,
-    /** Slug of a document-pdf template of the tenant or the system. */
-    templateSlug: z.string().min(1),
-    /** Name pattern of the attached PDF; may hold {{placeholders}}, must end with .pdf. */
-    fileName: z.string().min(1),
-    /** Cross-tenant target — SystemAdmin only. */
-    tenantIdOverride: z.string().min(1).optional(),
-  }),
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  description:
-    "Links a PDF rendered from a document-pdf template into a mail template under the key. Every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale; nothing is uploaded or stored. fileName is a pattern that may use the mail's {{placeholders}} and must end with .pdf. The document template must exist for the tenant or the system. Counts toward the 10 attachments per mail template together with uploaded files.",
-  handler: async (event, ctx) => {
-    const { templateId, key, templateSlug, fileName } = event.payload;
-    const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
-    return linkTemplatePdfAttachment({
-      ctx,
-      user: event.user,
-      tenantId,
-      templateId,
-      key,
-      templateSlug,
-      fileName,
-    });
-  },
-});
+export function makeResourceLinkPdfWrite(policy: TemplateEditPolicy) {
+  return defineWriteHandler({
+    name: "resource-link-pdf",
+    schema: z.object({
+      templateId: z.string().min(1),
+      key: resourceKeySchema,
+      /** Slug of a document-pdf template of the tenant or the system. */
+      templateSlug: z.string().min(1),
+      /** Name pattern of the attached PDF; may hold {{placeholders}}, must end with .pdf. */
+      fileName: z.string().min(1),
+      /** Cross-tenant target — SystemAdmin only. */
+      tenantIdOverride: z.string().min(1).optional(),
+    }),
+    access: templateEditAccess(policy.tenantEditable),
+    description:
+      "Links a PDF rendered from a document-pdf template into a mail template under the key. Every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale; nothing is uploaded or stored. fileName is a pattern that may use the mail's {{placeholders}} and must end with .pdf. The document template must exist for the tenant or the system. Counts toward the 10 attachments per mail template together with uploaded files. Outside the templates the app lists in tenantEditable only a SystemAdmin may use it.",
+    handler: async (event, ctx) => {
+      const { templateId, key, templateSlug, fileName } = event.payload;
+      const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
+      const refused = await refuseTemplateEditById(
+        ctx.db,
+        policy,
+        event.user,
+        tenantId,
+        templateId,
+      );
+      if (refused !== null) return refused;
+      return linkTemplatePdfAttachment({
+        ctx,
+        user: event.user,
+        tenantId,
+        templateId,
+        key,
+        templateSlug,
+        fileName,
+      });
+    },
+  });
+}