@cosmicdrift/kumiko-samples 0.363.0 → 0.365.0

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

@@ -4,13 +4,23 @@ import * as z from "zod";
 import { FALLBACK_LOCALE } from "../constants.js";
 import { type LayoutRegions, readLayoutRegions } from "../layout-regions.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import {
+  type ActiveInfo,
+  draftViewerTenantId,
+  isHiddenSystemDraft,
+  toWorkingRow,
+  type WorkingRow,
+} from "../template-draft.js";
+import { type MailLayoutMeta, readMailLayoutMeta } from "../template-meta.js";
 import { localeSchema, templateSlugSchema } from "./shared.js";
+import { parseStoredJson } from "./template-gates.js";
 
 export type LayoutSourceRow = {
   readonly id: string;
   readonly version: number;
   readonly status: string;
   readonly locale: string;
+  readonly active: ActiveInfo | null;
 };
 
 export type LayoutSourceResponse = {
@@ -19,6 +29,8 @@ export type LayoutSourceResponse = {
   readonly regions: LayoutRegions;
   readonly effectiveFormat: "html" | "mjml" | null;
   readonly mjmlSource: string | null;
+  /** Appearance of the effective mail layout; invalid stored meta reads as defaults (empty). */
+  readonly meta: MailLayoutMeta;
   readonly locale: string;
 };
 
@@ -38,33 +50,82 @@ function pickByLocale(
   );
 }
 
-function toSourceRow(row: TemplateResourceRow): LayoutSourceRow {
-  return { id: String(row.id), version: row.version, status: row.status, locale: row.locale };
+function toSourceRow(row: WorkingRow): LayoutSourceRow {
+  return {
+    id: String(row.id),
+    version: row.version,
+    status: row.status,
+    locale: row.locale,
+    active: row.active,
+  };
 }
 
-function layoutFormat(row: TemplateResourceRow): "html" | "mjml" | null {
+function layoutFormat(row: WorkingRow): "html" | "mjml" | null {
   return row.contentFormat === "html" || row.contentFormat === "mjml" ? row.contentFormat : null;
 }
 
 function pickEditedRows(
   rows: readonly TemplateResourceRow[],
-  isSystemAdmin: boolean,
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
   locale: string | undefined,
 ): {
-  readonly tenantRow: TemplateResourceRow | null;
-  readonly systemRow: TemplateResourceRow | null;
+  readonly tenantRow: WorkingRow | null;
+  readonly systemRow: WorkingRow | null;
 } {
-  const tenantRow = isSystemAdmin
+  const tenantRow = user.roles.includes("SystemAdmin")
     ? null
     : pickByLocale(
         rows.filter((row) => row.scope === "tenant"),
         locale,
       );
   const systemRow = pickByLocale(
-    rows.filter((row) => row.scope === "system"),
+    rows.filter((row) => row.scope === "system" && !isHiddenSystemDraft(user, row)),
     locale,
   );
-  return { tenantRow, systemRow };
+  return {
+    tenantRow: tenantRow && toWorkingRow(tenantRow, user.tenantId),
+    // Only a SystemAdmin works on the system draft; a tenant sees the served system version.
+    systemRow: systemRow && toWorkingRow(systemRow, draftViewerTenantId(user, systemRow)),
+  };
+}
+
+function readEffectiveRegions(
+  effective: WorkingRow | null,
+  effectiveFormat: "html" | "mjml" | null,
+): LayoutRegions {
+  return effective !== null && effectiveFormat === "html"
+    ? readLayoutRegions(effective.content ?? "")
+    : EMPTY_REGIONS;
+}
+
+function readMjmlSource(systemRow: WorkingRow | null, isSystemAdmin: boolean): string | null {
+  const exposesMjml = isSystemAdmin && systemRow !== null && layoutFormat(systemRow) === "mjml";
+  return exposesMjml ? (systemRow.content ?? "") : null;
+}
+
+function buildLayoutSource(input: {
+  readonly kind: "mail-layout" | "pdf-layout";
+  readonly locale: string | undefined;
+  readonly isSystemAdmin: boolean;
+  readonly tenantRow: WorkingRow | null;
+  readonly systemRow: WorkingRow | null;
+}): LayoutSourceResponse {
+  const { kind, locale, isSystemAdmin, tenantRow, systemRow } = input;
+  const effective = tenantRow ?? systemRow;
+  const effectiveFormat = effective === null ? null : layoutFormat(effective);
+  return {
+    tenant: tenantRow === null ? null : toSourceRow(tenantRow),
+    system:
+      systemRow === null
+        ? null
+        : { ...toSourceRow(systemRow), contentFormat: systemRow.contentFormat },
+    regions: readEffectiveRegions(effective, effectiveFormat),
+    effectiveFormat,
+    mjmlSource: readMjmlSource(systemRow, isSystemAdmin),
+    meta:
+      kind === "mail-layout" ? readMailLayoutMeta(parseStoredJson(effective?.meta ?? null)) : {},
+    locale: effective?.locale ?? locale ?? FALLBACK_LOCALE,
+  };
 }
 
 export const layoutSourceQuery = defineQueryHandler({
@@ -76,7 +137,7 @@ export const layoutSourceQuery = defineQueryHandler({
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   description:
-    "Reads the layout the caller edits: the tenant's own version and the system version of one layout slug, the header, signature and footer regions of the effective html version, and the locale a save has to use; a SystemAdmin edits the system version and also receives its mjml source. Use it to load the layout editor.",
+    "Reads the layout the caller edits: the tenant's own version and the system version of one layout slug (each the open draft if there is one, else the stored version, with `active` naming the served version), the header, signature and footer regions of the effective html version, and the locale a save has to use; a SystemAdmin edits the system version and also receives its mjml source. Use it to load the layout editor.",
   handler: async (query, ctx): Promise<LayoutSourceResponse> => {
     const { kind, slug, locale } = query.payload;
     const isSystemAdmin = query.user.roles.includes("SystemAdmin");
@@ -84,25 +145,7 @@ export const layoutSourceQuery = defineQueryHandler({
       kind,
       slug,
     });
-    const { tenantRow, systemRow } = pickEditedRows(rows, isSystemAdmin, locale);
-    const effective = tenantRow ?? systemRow;
-    const effectiveFormat = effective === null ? null : layoutFormat(effective);
-    return {
-      tenant: tenantRow === null ? null : toSourceRow(tenantRow),
-      system:
-        systemRow === null
-          ? null
-          : { ...toSourceRow(systemRow), contentFormat: systemRow.contentFormat },
-      regions:
-        effective !== null && effectiveFormat === "html"
-          ? readLayoutRegions(effective.content ?? "")
-          : EMPTY_REGIONS,
-      effectiveFormat,
-      mjmlSource:
-        isSystemAdmin && systemRow !== null && layoutFormat(systemRow) === "mjml"
-          ? (systemRow.content ?? "")
-          : null,
-      locale: effective?.locale ?? locale ?? FALLBACK_LOCALE,
-    };
+    const { tenantRow, systemRow } = pickEditedRows(rows, query.user, locale);
+    return buildLayoutSource({ kind, locale, isSystemAdmin, tenantRow, systemRow });
   },
 });

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

@@ -3,6 +3,7 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { TEMPLATE_KINDS, TEMPLATE_STATUSES } from "../constants.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { isHiddenSystemDraft } from "../template-draft.js";
 
 // ctx.db is tenant-scoped even for SystemAdmin: every caller sees its own
 // tenant's rows plus the system defaults, never another tenant's rows.
@@ -43,16 +44,18 @@ export const listQuery = defineQueryHandler({
       limit: 500,
     })) as TemplateResourceRow[];
 
-    return rows.map((row) => ({
-      id: String(row.id),
-      tenantId: row.tenantId,
-      slug: row.slug,
-      kind: row.kind,
-      locale: row.locale,
-      scope: row.scope,
-      status: row.status,
-      contentFormat: row.contentFormat,
-      modifiedAt: row.modifiedAt,
-    }));
+    return rows
+      .filter((row) => !isHiddenSystemDraft(query.user, row))
+      .map((row) => ({
+        id: String(row.id),
+        tenantId: row.tenantId,
+        slug: row.slug,
+        kind: row.kind,
+        locale: row.locale,
+        scope: row.scope,
+        status: row.status,
+        contentFormat: row.contentFormat,
+        modifiedAt: row.modifiedAt,
+      }));
   },
 });

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

@@ -0,0 +1,49 @@
+import type { TemplateResourceRow } from "../table.js";
+import { diffTemplateBlocks, splitTemplateBlocks } from "../template-diff.js";
+import { servedVersionOf } from "../template-draft.js";
+
+function parseStoredMeta(raw: string | null): Readonly<Record<string, unknown>> {
+  if (raw === null) return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? Object.fromEntries(Object.entries(parsed))
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function diffMeta(
+  system: Readonly<Record<string, unknown>>,
+  tenant: Readonly<Record<string, unknown>>,
+) {
+  const keys = [...new Set([...Object.keys(system), ...Object.keys(tenant)])].sort();
+  return keys
+    .filter((key) => JSON.stringify(system[key]) !== JSON.stringify(tenant[key]))
+    .map((key) => ({ key, tenant: tenant[key], system: system[key] }));
+}
+
+// Shared by the tenant's own diff and the SystemAdmin's per-tenant diff in the overrides drawer.
+export function buildOverrideDiff(tenantRow: TemplateResourceRow, systemRow: TemplateResourceRow) {
+  const blocks = diffTemplateBlocks(
+    splitTemplateBlocks(systemRow.content ?? "", systemRow.contentFormat),
+    splitTemplateBlocks(tenantRow.content ?? "", tenantRow.contentFormat),
+  );
+  const meta = diffMeta(parseStoredMeta(systemRow.meta), parseStoredMeta(tenantRow.meta));
+  return {
+    tenant: {
+      templateId: String(tenantRow.id),
+      templateVersion: servedVersionOf(tenantRow),
+      contentFormat: tenantRow.contentFormat,
+    },
+    system: {
+      templateId: String(systemRow.id),
+      templateVersion: servedVersionOf(systemRow),
+      contentFormat: systemRow.contentFormat,
+    },
+    identical: meta.length === 0 && blocks.every((block) => block.change === "same"),
+    blocks,
+    meta,
+  };
+}

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

@@ -3,7 +3,15 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { DEFAULT_MAIL_LAYOUT_SLUG, FALLBACK_LOCALE, type TemplateStatus } from "../constants.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
-import { collectTemplateUsage } from "../template-usage.js";
+import {
+  activeSinceOf,
+  activeVersionOf,
+  draftViewerTenantId,
+  isHiddenSystemDraft,
+  parseTemplateDraft,
+  servedVersionOf,
+} from "../template-draft.js";
+import { collectTemplateUsage, type EffectiveMailLayoutSlugs } from "../template-usage.js";
 import { storedRecord } from "./template-gates.js";
 
 const OVERVIEW_KINDS = ["mail", "document-pdf", "mail-layout", "pdf-layout"] as const;
@@ -31,6 +39,8 @@ export type OverviewRow = {
   readonly locales: readonly string[];
   readonly status: TemplateStatus;
   readonly version: number;
+  readonly draftVersion: number | null;
+  readonly activeSince: string | null;
   readonly systemVersion: number | null;
   readonly layoutSlug: string | null;
   readonly modifiedAt: string;
@@ -42,6 +52,8 @@ export type OverviewResponse = {
   readonly rows: readonly OverviewRow[];
   readonly nextCursor: null;
   readonly total: number;
+  /** True when the tenant has more template rows than the overview reads; rows and total are then incomplete. */
+  readonly truncated: boolean;
 };
 
 const SORT_FIELDS = ["title", "slug", "kind", "origin", "status", "modifiedAt"] as const;
@@ -89,6 +101,27 @@ function effectiveRowsOf(rows: readonly TemplateResourceRow[]): EffectiveRows |
   return tenantRows.length > 0 ? { origin: "tenant", rows: tenantRows } : null;
 }
 
+export function effectiveMailLayoutSlugs(
+  rows: readonly TemplateResourceRow[],
+): EffectiveMailLayoutSlugs {
+  const byLocale = new Map<string, TemplateResourceRow[]>();
+  for (const row of rows) {
+    if (row.kind !== "mail") continue;
+    const key = `${row.slug}\u0000${row.locale}`;
+    byLocale.set(key, [...(byLocale.get(key) ?? []), row]);
+  }
+  const bySlug = new Map<string, Map<string, string>>();
+  for (const group of byLocale.values()) {
+    const effective = effectiveRowsOf(group)?.rows[0];
+    // All-archived: the renderer falls back to the code-registered template.
+    if (effective === undefined || effective.status === "archived") continue;
+    const locales = bySlug.get(effective.slug) ?? new Map<string, string>();
+    locales.set(effective.locale, layoutSlugOf(effective));
+    bySlug.set(effective.slug, locales);
+  }
+  return bySlug;
+}
+
 function modifiedAtOf(row: TemplateResourceRow): string {
   return (row.modifiedAt ?? row.insertedAt).toString();
 }
@@ -126,7 +159,37 @@ function groupBySlugAndKind(
   return groups;
 }
 
-function buildDrafts(groups: ReadonlyMap<string, readonly TemplateResourceRow[]>): {
+// Another tenant's draft, including a system draft seen by a tenant, is never announced.
+function draftVersionFor(
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
+  row: TemplateResourceRow,
+): number | null {
+  const isOwnRow = row.tenantId === draftViewerTenantId(user, row);
+  return isOwnRow && parseTemplateDraft(row.draft) !== null ? row.version : null;
+}
+
+// Version columns of one overview row: the served version, a waiting draft and the system version it overrides.
+function versionFieldsOf(
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
+  preferred: TemplateResourceRow,
+  groupRows: readonly TemplateResourceRow[],
+): Pick<OverviewDraft, "version" | "draftVersion" | "activeSince" | "systemVersion"> {
+  const isActive = preferred.status === "active";
+  const systemSameLocale = groupRows.find(
+    (row) => row.scope === "system" && row.locale === preferred.locale,
+  );
+  return {
+    version: servedVersionOf(preferred),
+    draftVersion: draftVersionFor(user, preferred),
+    activeSince: isActive ? activeSinceOf(preferred).toString() : null,
+    systemVersion: systemSameLocale === undefined ? null : activeVersionOf(systemSameLocale),
+  };
+}
+
+function buildDrafts(
+  groups: ReadonlyMap<string, readonly TemplateResourceRow[]>,
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
+): {
   readonly drafts: OverviewDraft[];
   readonly layoutSlugByDocument: Map<string, string>;
 } {
@@ -137,9 +200,6 @@ function buildDrafts(groups: ReadonlyMap<string, readonly TemplateResourceRow[]>
     const preferred = effective === null ? undefined : preferredRow(effective.rows);
     if (effective === null || preferred === undefined) continue;
     if (!isOverviewKind(preferred.kind) || !isTemplateStatus(preferred.status)) continue;
-    const systemSameLocale = groupRows.find(
-      (row) => row.scope === "system" && row.locale === preferred.locale,
-    );
     const isDocument = preferred.kind === "mail" || preferred.kind === "document-pdf";
     const layoutSlug = isDocument ? layoutSlugOf(preferred) : null;
     if (layoutSlug !== null && preferred.kind === "document-pdf") {
@@ -154,8 +214,7 @@ function buildDrafts(groups: ReadonlyMap<string, readonly TemplateResourceRow[]>
       origin: effective.origin,
       locales: [...new Set(effective.rows.map((row) => row.locale))].sort(),
       status: preferred.status,
-      version: preferred.version,
-      systemVersion: systemSameLocale?.version ?? null,
+      ...versionFieldsOf(user, preferred, groupRows),
       layoutSlug,
       modifiedAt: modifiedAtOf(preferred),
     });
@@ -167,15 +226,18 @@ function withUsage(
   draft: OverviewDraft,
   layoutSlugByDocument: ReadonlyMap<string, string>,
   registry: Parameters<typeof collectTemplateUsage>[0],
+  effectiveLayouts: EffectiveMailLayoutSlugs,
 ): OverviewRow {
   let usedBy: OverviewUsage[] = [];
   if (draft.kind === "mail" || draft.kind === "mail-layout") {
-    usedBy = collectTemplateUsage(registry, draft.slug, draft.kind).map((entry) => ({
-      qualifiedName: entry.qualifiedName,
-      feature: entry.feature,
-      notification: entry.notification,
-      trigger: entry.trigger,
-    }));
+    usedBy = collectTemplateUsage(registry, draft.slug, draft.kind, effectiveLayouts).map(
+      (entry) => ({
+        qualifiedName: entry.qualifiedName,
+        feature: entry.feature,
+        notification: entry.notification,
+        trigger: entry.trigger,
+      }),
+    );
   } else if (draft.kind === "pdf-layout") {
     usedBy = [...layoutSlugByDocument]
       .filter(([, layoutSlug]) => layoutSlug === draft.slug)
@@ -192,9 +254,11 @@ function filterRows(
   rows: readonly OverviewRow[],
   search: string | undefined,
   filters: readonly OverviewFilter[],
+  layoutSlug: string | undefined,
 ): OverviewRow[] {
   const needle = search?.trim().toLowerCase() ?? "";
   return rows.filter((row) => {
+    if (layoutSlug !== undefined && row.layoutSlug !== layoutSlug) return false;
     if (needle !== "" && !`${row.title} ${row.slug}`.toLowerCase().includes(needle)) return false;
     return filters.every((filter) => filter.value.includes(String(row[filter.field])));
   });
@@ -211,6 +275,7 @@ export const overviewQuery = defineQueryHandler({
   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),
@@ -219,21 +284,38 @@ export const overviewQuery = defineQueryHandler({
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   description:
-    "Lists mail, PDF and layout templates as one row per slug and kind for the caller's tenant: where the effective version comes from (own override or system), its locales, status and version, the system version it overrides, the layout it uses and which notifications or templates use it; use it to browse and filter all templates at a glance.",
+    "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; use it to browse and filter all templates at a glance.",
   handler: async (query, ctx) => {
     const payload = query.payload;
-    const rows = await selectMany<TemplateResourceRow>(
+    const fetchedRows = await selectMany<TemplateResourceRow>(
       ctx.db,
       templateResourcesTable,
       { kind: { in: [...OVERVIEW_KINDS] } },
-      { limit: OVERVIEW_ROW_LIMIT },
+      { 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 { drafts, layoutSlugByDocument } = buildDrafts(groupBySlugAndKind(rows));
+    const visibleRows = rows.filter((row) => !isHiddenSystemDraft(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),
+      withUsage(draft, layoutSlugByDocument, ctx.registry, effectiveLayouts),
+    );
+    const filtered = filterRows(
+      overviewRows,
+      payload.search,
+      payload.filters ?? [],
+      payload.layoutSlug,
     );
-    const filtered = filterRows(overviewRows, payload.search, payload.filters ?? []);
 
     const sortField: SortField =
       payload.sort !== undefined && isSortField(payload.sort) ? payload.sort : "modifiedAt";
@@ -245,6 +327,7 @@ export const overviewQuery = defineQueryHandler({
       rows: filtered.slice(offset, offset + payload.limit),
       nextCursor: null,
       total: filtered.length,
+      truncated,
     } satisfies OverviewResponse;
   },
 });

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

@@ -1,4 +1,8 @@
-import { defineWriteHandler, type WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type BeforeTransactionResult,
+  defineWriteHandler,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
 import {
   NotFoundError,
   UnprocessableError,
@@ -13,11 +17,14 @@ import {
 import { attachmentFileNameSchema } from "../../shared/index.js";
 import { TemplateResolverErrors } from "../qualified-names.js";
 import {
+  type PreparedTemplateFile,
+  prepareTemplateAttachmentBeforeTransaction,
+  prepareTemplateResourceBeforeTransaction,
   readTemplateResourceMaxBytes,
   type StoredTemplateAttachment,
   type StoredTemplateResource,
-  storeTemplateAttachment,
-  storeTemplateResource,
+  storePreparedTemplateAttachment,
+  storePreparedTemplateResource,
 } from "../store-template-resource.js";
 import { RESOURCE_PURPOSES, resourceKeySchema, resourceTargetTenantId } from "./resource-shared.js";
 
@@ -66,10 +73,7 @@ export const resourceUploadWrite = defineWriteHandler({
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   description:
     "Turns a file uploaded via POST /api/files (multipart, no entityType) into a template resource. With purpose image (default) the upload is checked against the resource-max-bytes cap, re-encoded to a supported image format and stored as a new file; with templateId and key it is linked into that template under the key, without them only the file is created. With purpose attachment, templateId, key and fileName are required: a PDF, PNG or JPEG is stored unchanged and linked into a mail template as a file attached to every mail sent from it, at most 10 per template. A cap above the files route's maxUploadSize has no effect.",
-  handler: async (
-    event,
-    ctx,
-  ): Promise<WriteResult<StoredTemplateResource | StoredTemplateAttachment>> => {
+  beforeTransaction: async (event, ctx): Promise<BeforeTransactionResult<PreparedTemplateFile>> => {
     const { templateId, key, sourceFileRefId, purpose, fileName } = event.payload;
     const attachmentTarget =
       purpose === "attachment" ? attachmentTargetOf({ templateId, key, fileName }) : null;
@@ -91,7 +95,7 @@ export const resourceUploadWrite = defineWriteHandler({
     try {
       source = await readFileRefContent({
         db: ctx.db,
-        filesForTenant: (tid) => fileContextForTenant(ctx, tid),
+        filesForTenant: (tid) => fileContextForTenant(ctx, ctx.user.tenantId, tid),
         fileRefId: sourceFileRefId,
         allowedTenantIds: [event.user.tenantId],
         unclaimedUploadOf: event.user.id,
@@ -113,7 +117,7 @@ export const resourceUploadWrite = defineWriteHandler({
     // The source upload stays as an unclaimed file: bundled-features cannot reach the fileRef executor to delete it.
     const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
     if (attachmentTarget !== null) {
-      return storeTemplateAttachment({
+      return prepareTemplateAttachmentBeforeTransaction({
         ctx,
         user: event.user,
         tenantId,
@@ -122,7 +126,7 @@ export const resourceUploadWrite = defineWriteHandler({
         ...attachmentTarget,
       });
     }
-    return storeTemplateResource({
+    return prepareTemplateResourceBeforeTransaction({
       ctx,
       user: event.user,
       tenantId,
@@ -132,4 +136,39 @@ export const resourceUploadWrite = defineWriteHandler({
       ...(key !== undefined && { key }),
     });
   },
+  handler: async (
+    event,
+    ctx,
+  ): Promise<WriteResult<StoredTemplateResource | StoredTemplateAttachment>> => {
+    const { templateId, key } = event.payload;
+    const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
+    const { prepared } = event;
+    if (prepared.kind === "attachment") {
+      // The phase accepts attachments only with a complete target, so these are set.
+      if (templateId === undefined || key === undefined) {
+        return writeFailure(
+          new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
+            i18nKey: "templateResolver.errors.attachment.invalid",
+            details: { code: "target_required" },
+          }),
+        );
+      }
+      return storePreparedTemplateAttachment({
+        ctx,
+        user: event.user,
+        tenantId,
+        prepared,
+        templateId,
+        key,
+      });
+    }
+    return storePreparedTemplateResource({
+      ctx,
+      user: event.user,
+      tenantId,
+      prepared,
+      ...(templateId !== undefined && { templateId }),
+      ...(key !== undefined && { key }),
+    });
+  },
 });

package/packages/bundled-features/src/template-resolver/handlers/send-test.write.ts

@@ -28,6 +28,11 @@ function testMailFailed(code: "channel_error" | "not_sent") {
   );
 }
 
+function errorCodeOf(error: unknown): string | undefined {
+  const code = error instanceof Error ? Reflect.get(error, "code") : undefined;
+  return typeof code === "string" ? code : undefined;
+}
+
 // The only recipient is the caller's own address, resolved server-side, so the handler can never mail a third party.
 export const sendTestWrite = defineWriteHandler({
   name: "send-test",
@@ -37,18 +42,24 @@ export const sendTestWrite = defineWriteHandler({
     content: z.string().max(200_000).optional(),
     meta: z.unknown().optional(),
     variableSchema: z.record(z.string(), z.unknown()).default({}),
+    includeAttachments: z.boolean().default(true),
+    prefixSubject: z.boolean().default(true),
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   rateLimit: { per: "user+handler", ...TEST_MAIL_RATE_LIMIT },
   description:
-    "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST], carrying the inline images and the files attached to the template; there is no recipient input, the sample values come from the declared variable examples, and a draft that fails the write rules is rejected without sending.",
+    "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST] unless prefixSubject is false, carrying the inline images and, unless includeAttachments is false, the files attached to the template; there is no recipient input, the sample values come from the declared variable examples, and a draft that fails the write rules is rejected without sending.",
   handler: async (event, ctx) => {
+    const { includeAttachments, prefixSubject, ...previewPayload } = event.payload;
     const outcome = await renderTemplatePreview(ctx, event.user, {
-      ...event.payload,
+      ...previewPayload,
       kind: "mail",
     });
     if (!outcome.ok) return writeFailure(outcome.error);
-    const { preview, mailAttachments } = outcome;
+    const { preview, sender } = outcome;
+    const mailAttachments = includeAttachments
+      ? outcome.mailAttachments
+      : outcome.mailAttachments.filter((ref) => ref.kind === "inline");
 
     const channel = emailChannelOf(ctx.registry);
     if (channel === undefined) {
@@ -69,7 +80,7 @@ export const sendTestWrite = defineWriteHandler({
         ctx.registry,
         event.user.tenantId,
         ctx.config,
-        (tenantId) => fileContextForTenant(ctx, tenantId),
+        (tenantId) => fileContextForTenant(ctx, ctx.user.tenantId, tenantId),
       ),
     };
     const address = (await channel.resolve?.(event.user.id, channelContext)) ?? null;
@@ -81,8 +92,8 @@ export const sendTestWrite = defineWriteHandler({
       );
     }
 
-    const subject = `${TEST_MAIL_SUBJECT_PREFIX}${preview.subject ?? ""}`;
-    let sent: boolean;
+    const subject = `${prefixSubject ? TEST_MAIL_SUBJECT_PREFIX : ""}${preview.subject ?? ""}`;
+    let sentStatus: string;
     try {
       const result = await channel.send(
         address,
@@ -94,13 +105,31 @@ export const sendTestWrite = defineWriteHandler({
           locale: event.payload.locale,
         },
         channelContext,
-        { subject, html: preview.html, text: preview.text ?? "", attachments: mailAttachments },
+        {
+          subject,
+          html: preview.html,
+          text: preview.text ?? "",
+          ...sender,
+          attachments: mailAttachments,
+        },
       );
-      sent = result.status === "sent";
-    } catch {
+      sentStatus = result.status;
+    } catch (error) {
+      // Class and code only: the message can carry the address or a provider response body.
+      ctx.log?.warn("template test mail: channel threw", {
+        tenantId: event.user.tenantId,
+        errorClass: error instanceof Error ? error.name : typeof error,
+        errorCode: errorCodeOf(error),
+      });
       return testMailFailed("channel_error");
     }
-    if (!sent) return testMailFailed("not_sent");
+    if (sentStatus !== "sent") {
+      ctx.log?.warn("template test mail: channel did not send", {
+        tenantId: event.user.tenantId,
+        status: sentStatus,
+      });
+      return testMailFailed("not_sent");
+    }
     return { isSuccess: true as const, data: { subject, checks: preview.checks } };
   },
 });