@cosmicdrift/kumiko-bundled-features 0.371.0 → 0.372.0

package/dist/shared/purge-row-file-refs.js

@@ -0,0 +1,152 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+const NO_FILE_FIELDS = { singleFields: [], multiFields: [] };
+// Same set as boot-validator/entity-handler.ts FILE_FIELD_TYPES; the single/multi split
+// matters here because only plural fields resolve through file_refs.
+export function planFileFields(fields, fieldNames) {
+    const singleFields = [];
+    const multiFields = [];
+    for (const [name, field] of Object.entries(fields)) {
+        if (fieldNames !== undefined && !fieldNames.includes(name))
+            continue;
+        if (field.type === "file" || field.type === "image")
+            singleFields.push(name);
+        else if (field.type === "files" || field.type === "images")
+            multiFields.push(name);
+    }
+    return singleFields.length > 0 || multiFields.length > 0
+        ? { singleFields, multiFields }
+        : NO_FILE_FIELDS;
+}
+// Every implicit entity table with file/image fields: an unbound fileRef
+// (POST /files without entityType/entityId) can sit in single fields of
+// several entity types, so the sharing check must look beyond the purged
+// row's own table.
+export function collectSingleFileHolders(registry) {
+    const holders = [];
+    for (const proj of registry.getAllProjections().values()) {
+        if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
+            continue;
+        const entity = registry.getEntity(proj.source);
+        if (!entity)
+            continue;
+        const { singleFields } = planFileFields(entity.fields);
+        if (singleFields.length === 0)
+            continue;
+        holders.push({
+            table: proj.table,
+            tableHasTenantId: propertyOf(proj.table, "tenantId") !== undefined,
+            singleFields,
+        });
+    }
+    return holders;
+}
+// Every fileRef-id a row's file-fields reference: single fields hold the id in
+// their own column, plural fields resolve via file_refs (tenantId, entityType,
+// entityId, fieldName).
+async function collectFileRefIds(db, tenantId, entityName, row, plan) {
+    const ids = new Set();
+    for (const field of plan.singleFields) {
+        const value = row[field];
+        if (typeof value === "string" && value.length > 0)
+            ids.add(value);
+    }
+    if (plan.multiFields.length > 0) {
+        const refRows = await selectMany(db, fileRefsTable, {
+            tenantId,
+            entityType: entityName,
+            entityId: String(row["id"]),
+            fieldName: { in: plan.multiFields },
+        });
+        for (const r of refRows)
+            ids.add(r.id);
+    }
+    return Array.from(ids);
+}
+// A fileRef is bound to a DIFFERENT entity/record (or, when only some fields are
+// purged, to another field of this row) than the one being purged — its binding,
+// not the row's own single-field column, decides ownership.
+function isFileRefBoundElsewhere(fileRef, entityName, rowId, fieldNames) {
+    const entityType = fileRef["entityType"];
+    const entityId = fileRef["entityId"];
+    const fieldName = fileRef["fieldName"];
+    if (typeof entityType === "string" && entityType !== entityName)
+        return true;
+    if (typeof entityId === "string" && entityId !== rowId)
+        return true;
+    if (fieldNames !== undefined &&
+        typeof fieldName === "string" &&
+        !fieldNames.includes(fieldName)) {
+        return true;
+    }
+    return false;
+}
+// A single-field fileRef-id can be shared by more than one row, in the SAME
+// table or in another entity's table; with a partial field set, also by another
+// field of the same row. Purging its bytes would corrupt the holder that stays.
+async function isFileRefSharedByOtherHolder(db, holders, ownTable, tenantId, rowId, fileRefId, fieldNames) {
+    for (const holder of holders) {
+        for (const field of holder.singleFields) {
+            const where = { [field]: fileRefId };
+            if (holder.table === ownTable) {
+                const fieldIsPurged = fieldNames === undefined || fieldNames.includes(field);
+                where["id"] = fieldIsPurged ? { ne: rowId } : rowId;
+            }
+            if (holder.tableHasTenantId)
+                where["tenantId"] = tenantId;
+            const others = await selectMany(db, holder.table, where, { limit: 1 });
+            if (others.length > 0)
+                return true;
+        }
+    }
+    return false;
+}
+// Deletes the un-shared fileRefs a row's file-fields reference: bytes (incl.
+// derivatives) first, then the fileRef rows — bytes before rows so a crash
+// mid-way leaves an orphaned fileRef pointing at already-gone bytes (a later
+// run's delete is idempotent) rather than a gone fileRef whose bytes leak forever.
+// The entity row itself is the caller's business. `fieldNames` narrows the purge
+// to those fields; without it every file-field of the entity is purged.
+export async function purgeRowFileRefs(args) {
+    const rowId = String(args.row["id"]);
+    const plan = planFileFields(args.entity.fields, args.fieldNames);
+    const fileRefIds = await collectFileRefIds(args.db, args.tenantId, args.entityName, args.row, plan);
+    if (fileRefIds.length === 0)
+        return "purged";
+    const fileRefRows = await selectMany(args.db, fileRefsTable, {
+        id: { in: fileRefIds },
+        tenantId: args.tenantId,
+    });
+    const toDelete = [];
+    for (const fileRef of fileRefRows) {
+        if (isFileRefBoundElsewhere(fileRef, args.entityName, rowId, args.fieldNames))
+            continue;
+        const shared = await isFileRefSharedByOtherHolder(args.db, args.fileHolders, args.table, args.tenantId, rowId, String(fileRef["id"]), args.fieldNames);
+        if (shared)
+            continue;
+        toDelete.push(fileRef);
+    }
+    if (toDelete.length === 0)
+        return "purged";
+    if (!args.deleteBytes)
+        return "missing_file_storage";
+    let anyFailed = false;
+    for (const fileRef of toDelete) {
+        const key = fileRef["storageKey"];
+        if (typeof key !== "string" || key.length === 0)
+            continue;
+        const failedKeys = await args.deleteBytes(key);
+        if (failedKeys.length > 0) {
+            anyFailed = true;
+            args.onBytesDeleteFailed?.(failedKeys);
+        }
+    }
+    if (anyFailed)
+        return "file_delete_failed";
+    for (const fileRef of toDelete) {
+        if (!(await args.fileRefForget(String(fileRef["id"]))))
+            return "file_delete_failed";
+    }
+    return "purged";
+}

package/dist/tags/entity.d.ts

@@ -1,6 +1,6 @@
 import { type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
 export declare const tagEntity: EntityDefinition<{
-    name: {
+    readonly name: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -23,7 +23,7 @@ export declare const tagEntity: EntityDefinition<{
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    color: {
+    readonly color: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -46,7 +46,7 @@ export declare const tagEntity: EntityDefinition<{
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    scope: {
+    readonly scope: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -71,7 +71,7 @@ export declare const tagEntity: EntityDefinition<{
     };
 }, "tenant">;
 export declare function createTagAssignmentEntity(access?: EntityDefinition["access"], parents?: readonly string[]): EntityDefinition<{
-    tagId: {
+    readonly tagId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -94,7 +94,7 @@ export declare function createTagAssignmentEntity(access?: EntityDefinition["acc
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    entityType: {
+    readonly entityType: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -117,7 +117,7 @@ export declare function createTagAssignmentEntity(access?: EntityDefinition["acc
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    entityId: {
+    readonly entityId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -142,7 +142,7 @@ export declare function createTagAssignmentEntity(access?: EntityDefinition["acc
     };
 }, "tenant">;
 export declare const tagAssignmentEntity: EntityDefinition<{
-    tagId: {
+    readonly tagId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -165,7 +165,7 @@ export declare const tagAssignmentEntity: EntityDefinition<{
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    entityType: {
+    readonly entityType: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -188,7 +188,7 @@ export declare const tagAssignmentEntity: EntityDefinition<{
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    entityId: {
+    readonly entityId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;

package/dist/tags/executor.d.ts

@@ -1,4 +1,32 @@
 import { type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
-export declare const tagExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
-export declare const tagAssignmentExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
+export declare const tagExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor<{
+    readonly id: string;
+    readonly tenantId: string;
+    readonly version: number;
+    readonly insertedAt: Temporal.Instant;
+    readonly modifiedAt: Temporal.Instant | null;
+    readonly insertedById: string | null;
+    readonly modifiedById: string | null;
+    readonly isDeleted?: boolean | undefined;
+    readonly deletedAt?: Temporal.Instant | null | undefined;
+    readonly deletedById?: string | null | undefined;
+    readonly color: string | null;
+    readonly name: string;
+    readonly scope: string | null;
+}>;
+export declare const tagAssignmentExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor<{
+    readonly id: string;
+    readonly tenantId: string;
+    readonly version: number;
+    readonly insertedAt: Temporal.Instant;
+    readonly modifiedAt: Temporal.Instant | null;
+    readonly insertedById: string | null;
+    readonly modifiedById: string | null;
+    readonly isDeleted?: boolean | undefined;
+    readonly deletedAt?: Temporal.Instant | null | undefined;
+    readonly deletedById?: string | null | undefined;
+    readonly entityId: string;
+    readonly entityType: string;
+    readonly tagId: string;
+}>;
 export declare function createTagAssignmentExecutor(ownership: EntityDefinition["access"] | undefined): typeof tagAssignmentExecutor;

package/dist/template-resolver/handlers/shared.d.ts

@@ -1,6 +1,33 @@
 import * as z from "zod";
 import { templateSlugSchema } from "../template-meta.ts";
-export declare const executor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
+export declare const executor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor<{
+    readonly id: string;
+    readonly tenantId: string;
+    readonly version: number;
+    readonly insertedAt: Temporal.Instant;
+    readonly modifiedAt: Temporal.Instant | null;
+    readonly insertedById: string | null;
+    readonly modifiedById: string | null;
+    readonly isDeleted?: boolean | undefined;
+    readonly deletedAt?: Temporal.Instant | null | undefined;
+    readonly deletedById?: string | null | undefined;
+    readonly activeSince: Temporal.Instant | null;
+    readonly activeVersion: number | null;
+    readonly content: string | null;
+    readonly contentFormat: string;
+    readonly draft: string | null;
+    readonly folder: string | null;
+    readonly kind: string;
+    readonly linkedResources: string | null;
+    readonly locale: string;
+    readonly meta: string | null;
+    readonly parentTemplateId: string | null;
+    readonly scope: string;
+    readonly slug: string;
+    readonly status: string;
+    readonly title: string | null;
+    readonly variableSchema: string | null;
+}>;
 export declare const slugSchema: z.ZodString;
 export { templateSlugSchema };
 export declare const localeSchema: z.ZodString;

package/dist/template-resolver/table.d.ts

@@ -1,6 +1,6 @@
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    slug: {
+    readonly slug: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -23,7 +23,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    kind: {
+    readonly kind: {
         readonly type: "select";
         readonly description?: string;
         readonly options: readonly ["mail", "document-pdf", "image-snapshot", "notification", "text-block", "snippet", "ai-prompt", "mail-layout", "pdf-layout"];
@@ -52,7 +52,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    locale: {
+    readonly locale: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -75,7 +75,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    title: {
+    readonly title: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -98,7 +98,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    folder: {
+    readonly folder: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -121,7 +121,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    content: {
+    readonly content: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -137,7 +137,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    contentFormat: {
+    readonly contentFormat: {
         readonly type: "select";
         readonly description?: string;
         readonly options: readonly ["markdown", "mjml", "html", "plain"];
@@ -161,7 +161,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    variableSchema: {
+    readonly variableSchema: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -177,7 +177,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    linkedResources: {
+    readonly linkedResources: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -193,7 +193,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    meta: {
+    readonly meta: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -209,7 +209,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    scope: {
+    readonly scope: {
         readonly type: "select";
         readonly description?: string;
         readonly options: readonly ["system", "tenant"];
@@ -231,7 +231,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    parentTemplateId: {
+    readonly parentTemplateId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -254,7 +254,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    status: {
+    readonly status: {
         readonly type: "select";
         readonly description?: string;
         readonly options: readonly ["draft", "active", "archived"];
@@ -277,7 +277,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    draft: {
+    readonly draft: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -293,7 +293,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    activeVersion: {
+    readonly activeVersion: {
         readonly type: "number";
         readonly description?: string;
         readonly required?: boolean;
@@ -312,7 +312,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    activeSince: {
+    readonly activeSince: {
         readonly type: "timestamp";
         readonly description?: string;
         readonly required?: boolean;
@@ -329,7 +329,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
     };
 }, "tenant">;
 export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framework/db").EntityTable<import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    slug: {
+    readonly slug: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -352,7 +352,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    kind: {
+    readonly kind: {
         readonly type: "select";
         readonly description?: string;
         readonly options: readonly ["mail", "document-pdf", "image-snapshot", "notification", "text-block", "snippet", "ai-prompt", "mail-layout", "pdf-layout"];
@@ -381,7 +381,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    locale: {
+    readonly locale: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -404,7 +404,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    title: {
+    readonly title: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -427,7 +427,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    folder: {
+    readonly folder: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -450,7 +450,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    content: {
+    readonly content: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -466,7 +466,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    contentFormat: {
+    readonly contentFormat: {
         readonly type: "select";
         readonly description?: string;
         readonly options: readonly ["markdown", "mjml", "html", "plain"];
@@ -490,7 +490,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    variableSchema: {
+    readonly variableSchema: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -506,7 +506,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    linkedResources: {
+    readonly linkedResources: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -522,7 +522,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    meta: {
+    readonly meta: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -538,7 +538,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    scope: {
+    readonly scope: {
         readonly type: "select";
         readonly description?: string;
         readonly options: readonly ["system", "tenant"];
@@ -560,7 +560,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    parentTemplateId: {
+    readonly parentTemplateId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -583,7 +583,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    status: {
+    readonly status: {
         readonly type: "select";
         readonly description?: string;
         readonly options: readonly ["draft", "active", "archived"];
@@ -606,7 +606,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    draft: {
+    readonly draft: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -622,7 +622,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    activeVersion: {
+    readonly activeVersion: {
         readonly type: "number";
         readonly description?: string;
         readonly required?: boolean;
@@ -641,7 +641,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: false;
     };
-    activeSince: {
+    readonly activeSince: {
         readonly type: "timestamp";
         readonly description?: string;
         readonly required?: boolean;

package/dist/template-resolver/template-preview.js

@@ -20,9 +20,15 @@ import { isMailTemplateMeta, parseTemplateMeta, readPdfTemplateMeta, } from "./t
 const SAMPLE_LINK = "https://example.com";
 const SAMPLE_DATE = "2026-01-15";
 const SAMPLE_LIST_ROWS = 3;
+function isTranslatableExample(def, example) {
+    return (def.type === "text" || def.type === "richText") && typeof example === "string";
+}
+function exampleFor(def, example, labelText) {
+    return isTranslatableExample(def, example) ? labelText(example) : example;
+}
 function sampleScalar(name, def, labelText) {
     if (def.example !== undefined)
-        return def.example;
+        return exampleFor(def, def.example, labelText);
     const label = def.label === undefined ? name : labelText(def.label);
     switch (def.type) {
         case "text":
@@ -41,9 +47,12 @@ function sampleScalar(name, def, labelText) {
 }
 function sampleRow(item, labelText, given = {}) {
     const row = {};
-    for (const [name, def] of Object.entries(item))
-        row[name] = sampleScalar(name, def, labelText);
-    return { ...row, ...given };
+    for (const [name, def] of Object.entries(item)) {
+        row[name] = Object.hasOwn(given, name)
+            ? exampleFor(def, given[name], labelText)
+            : sampleScalar(name, def, labelText);
+    }
+    return { ...given, ...row };
 }
 function sampleList(def, labelText) {
     const rows = (def.example ?? [])