@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.364.0

package/dist/shared/attachment-file-name.js

@@ -0,0 +1,35 @@
+import * as z from "zod";
+const MAX_FILE_NAME_LENGTH = 255;
+function hasControlCharacter(value) {
+    return value.split("").some((char) => {
+        const code = char.charCodeAt(0);
+        return code <= 0x1f || code === 0x7f;
+    });
+}
+export const attachmentFileNameSchema = z
+    .string()
+    .min(1)
+    .max(MAX_FILE_NAME_LENGTH)
+    .refine((name) => !name.includes("/") && !name.includes("\\") && !hasControlCharacter(name), {
+    message: "file name must not contain path separators or control characters",
+});
+const PDF_FILE_NAME_MAX_LENGTH = 200;
+const PDF_EXTENSION = ".pdf";
+// Shared by everything that names a rendered PDF, so a mail attachment and a download of the same
+// template get the same name. The cut leaves room for the extension: the attachment schema caps
+// rendered-pdf names, and a name that only fits without ".pdf" would fail it.
+export function sanitizePdfAttachmentFileName(raw, templateSlug) {
+    const cleaned = raw
+        .split("")
+        .filter((char) => !hasControlCharacter(char))
+        .join("")
+        .replace(/[/\\";]/g, "-")
+        .replaceAll("..", "-")
+        .trim()
+        .slice(0, PDF_FILE_NAME_MAX_LENGTH - PDF_EXTENSION.length)
+        .trim();
+    const lastSegment = templateSlug.split(":").pop() ?? templateSlug;
+    if (cleaned === "")
+        return `${lastSegment}${PDF_EXTENSION}`;
+    return cleaned.toLowerCase().endsWith(PDF_EXTENSION) ? cleaned : `${cleaned}${PDF_EXTENSION}`;
+}

package/dist/shared/chunked-entity-migration.d.ts

@@ -12,6 +12,7 @@ export type ChunkedMigrationOptions<Row> = {
     readonly migrateRow: (row: Row) => Promise<MigrationRowOutcome>;
     readonly maxFailures: number;
     readonly deadlineAt: number;
+    readonly minBatches?: number;
     readonly signal?: AbortSignal | undefined;
     readonly onRowError?: (row: Row, err: unknown) => void;
 };

package/dist/shared/chunked-entity-migration.js

@@ -25,7 +25,7 @@ export async function runChunkedMigration(opts) {
             stoppedReason = "signal";
             break;
         }
-        if (Date.now() >= opts.deadlineAt) {
+        if (batchesProcessed >= (opts.minBatches ?? 0) && Date.now() >= opts.deadlineAt) {
             stoppedReason = "timeout";
             break;
         }

package/dist/shared/index.d.ts

@@ -1,5 +1,6 @@
 export { collectErasureFailure, throwIfErasureFailed } from "./assert-erased.js";
 export { assertNoWhereRuleInOwnershipWrite } from "./assert-no-where-rule-in-ownership-write.js";
+export { attachmentFileNameSchema, sanitizePdfAttachmentFileName, } from "./attachment-file-name.js";
 export { type ChunkedMigrationOptions, type ChunkedMigrationResult, type ChunkedMigrationStopReason, type MigrationRowOutcome, runChunkedMigration, } from "./chunked-entity-migration.js";
 export { classifyStoredEnvelope, type StoredEnvelopeClassification, } from "./classify-stored-envelope.js";
 export { decryptStoredPii } from "./decrypt-stored-pii.js";
@@ -9,6 +10,7 @@ export { isWithinGracePeriod } from "./grace-period.js";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash.js";
 export { isTenantDb } from "./is-tenant-db.js";
 export { createLockoutCounter, type LockoutCounterState } from "./lockout-counter.js";
+export { mailHeading, mailParagraph, mailRepeatedRows } from "./mail-template-body.js";
 export { mapWithConcurrency } from "./map-with-concurrency.js";
 export { denyUnlessJoinRowParentVisible, hostRowIsGone, joinRowParentIsVisible, parentRowIsVisible, } from "./parent-visibility.js";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing.js";
@@ -20,6 +22,7 @@ export { type RowBoundGrantResult, redeemRowBoundGrant, signRowBoundGrant, } fro
 export { runInSubTransaction } from "./run-in-sub-transaction.js";
 export { registrationLocaleFromRequest, sessionLocaleField } from "./session-locale-field.js";
 export { sessionTimezoneField } from "./session-timezone-field.js";
+export { assertNotSvg, MAX_INPUT_PIXELS, SHARP_INPUT_OPTIONS } from "./sharp-input-limits.js";
 export { peekTokenSubject, signToken, TokenPurpose, type VerifyResult, verifyToken, } from "./signed-token.js";
 export { EXT_SIGNUP_HANDOVER, findSignupHandoverProvider, isSignupHandoverProvider, SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE, type SignupHandoverBinding, type SignupHandoverProvider, } from "./signup-handover.js";
 export { createSingleUseTokenStore, hashSingleUseToken } from "./single-use-token-store.js";

package/dist/shared/index.js

@@ -1,5 +1,6 @@
 export { collectErasureFailure, throwIfErasureFailed } from "./assert-erased.js";
 export { assertNoWhereRuleInOwnershipWrite } from "./assert-no-where-rule-in-ownership-write.js";
+export { attachmentFileNameSchema, sanitizePdfAttachmentFileName, } from "./attachment-file-name.js";
 export { runChunkedMigration, } from "./chunked-entity-migration.js";
 export { classifyStoredEnvelope, } from "./classify-stored-envelope.js";
 export { decryptStoredPii } from "./decrypt-stored-pii.js";
@@ -9,6 +10,7 @@ export { isWithinGracePeriod } from "./grace-period.js";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash.js";
 export { isTenantDb } from "./is-tenant-db.js";
 export { createLockoutCounter } from "./lockout-counter.js";
+export { mailHeading, mailParagraph, mailRepeatedRows } from "./mail-template-body.js";
 export { mapWithConcurrency } from "./map-with-concurrency.js";
 export { denyUnlessJoinRowParentVisible, hostRowIsGone, joinRowParentIsVisible, parentRowIsVisible, } from "./parent-visibility.js";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing.js";
@@ -20,6 +22,7 @@ export { redeemRowBoundGrant, signRowBoundGrant, } from "./row-bound-grant.js";
 export { runInSubTransaction } from "./run-in-sub-transaction.js";
 export { registrationLocaleFromRequest, sessionLocaleField } from "./session-locale-field.js";
 export { sessionTimezoneField } from "./session-timezone-field.js";
+export { assertNotSvg, MAX_INPUT_PIXELS, SHARP_INPUT_OPTIONS } from "./sharp-input-limits.js";
 export { peekTokenSubject, signToken, TokenPurpose, verifyToken, } from "./signed-token.js";
 export { EXT_SIGNUP_HANDOVER, findSignupHandoverProvider, isSignupHandoverProvider, SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE, } from "./signup-handover.js";
 export { createSingleUseTokenStore, hashSingleUseToken } from "./single-use-token-store.js";

package/dist/shared/is-tenant-db.js

@@ -3,5 +3,5 @@
 // Shared so retention/compliance-profile resolvers that accept either (bulk cron
 // vs. per-hook TenantDb) branch through one predicate instead of duplicating it.
 export function isTenantDb(db) {
-    return typeof db.unsafeRaw === "function";
+    return "unsafeRaw" in db && typeof db.unsafeRaw === "function";
 }

package/dist/shared/mail-template-body.d.ts

@@ -0,0 +1,7 @@
+export declare function mailTextWithSlotsHtml(text: string): string;
+export declare function mailParagraph(text: string): string;
+export declare function mailHeading(text: string): string;
+export declare function mailButton(label: string, linkVariable: string): string;
+export declare function mailParagraphWithLink(text: string, linkLabel: string, linkVariable: string): string;
+export declare function mailRepeatedRows(listName: string, field: string): string;
+export declare function mailSubject(text: string): string;

package/dist/shared/mail-template-body.js

@@ -0,0 +1,27 @@
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+const SLOT_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+// Author text uses `{name}` slots. The text is escaped first and the slots are
+// swapped for variable nodes afterwards, so a slot can never smuggle markup.
+export function mailTextWithSlotsHtml(text) {
+    return escapeHtml(text).replace(SLOT_PATTERN, (_, name) => `<span data-variable="${escapeHtmlAttr(name)}"></span>`);
+}
+export function mailParagraph(text) {
+    return `<p>${mailTextWithSlotsHtml(text)}</p>`;
+}
+export function mailHeading(text) {
+    return `<h2>${mailTextWithSlotsHtml(text)}</h2>`;
+}
+export function mailButton(label, linkVariable) {
+    return `<p><a data-button href="{{${escapeHtmlAttr(linkVariable)}}}">${escapeHtml(label)}</a></p>`;
+}
+export function mailParagraphWithLink(text, linkLabel, linkVariable) {
+    return `<p>${mailTextWithSlotsHtml(text)} <a href="{{${escapeHtmlAttr(linkVariable)}}}">${escapeHtml(linkLabel)}</a></p>`;
+}
+// One table row per list entry; the cell shows the entry's `field`.
+export function mailRepeatedRows(listName, field) {
+    return `<table><tbody><tr data-each="${escapeHtmlAttr(listName)}"><td><p><span data-variable="${escapeHtmlAttr(field)}"></span></p></td></tr></tbody></table>`;
+}
+// Subjects are Handlebars text, so the same `{name}` slots become `{{name}}`.
+export function mailSubject(text) {
+    return text.replace(SLOT_PATTERN, "{{$1}}");
+}

package/dist/shared/sharp-input-limits.d.ts

@@ -0,0 +1,6 @@
+export declare const MAX_INPUT_PIXELS = 100000000;
+export declare const SHARP_INPUT_OPTIONS: {
+    readonly limitInputPixels: 100000000;
+    readonly sequentialRead: true;
+};
+export declare function assertNotSvg(format: string | undefined): void;

package/dist/shared/sharp-input-limits.js

@@ -0,0 +1,22 @@
+// Sharp-free so callers can import the limits without loading the native binding.
+// Above this, a decoded pixel buffer runs into hundreds of MB before any
+// resize even happens — sharp's own default (~268MP) is still large enough
+// to be an OOM primitive for a single request.
+export const MAX_INPUT_PIXELS = 100_000_000;
+// sequentialRead trades random pixel access for lower peak memory on
+// streamed formats — applied at every decode entry point below since none
+// of them need non-sequential access to the *original* bytes (extract runs
+// against a single already-buffered region per call).
+export const SHARP_INPUT_OPTIONS = {
+    limitInputPixels: MAX_INPUT_PIXELS,
+    sequentialRead: true,
+};
+// Shared trust boundary for every image byte source this renderer decodes —
+// the original upload (renderImage) and an overlay layer's bytes (applyOverlays)
+// alike: a base64 string in a field declaration isn't more trustworthy than
+// an upload just because it came from app code.
+export function assertNotSvg(format) {
+    if (format === "svg") {
+        throw new Error("derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.");
+    }
+}

package/dist/shared/signup-handover.js

@@ -10,6 +10,7 @@
 // The grant itself never crosses this boundary: verifyGrant returns only
 // the { entityType, rowId, sourceTenantId } binding, and mintClaim returns a
 // freshly signed short-lived token rather than handing back the original.
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 export const EXT_SIGNUP_HANDOVER = "signupHandover";
 // Part of the contract: a provider's minted claim write may reject two
 // different ways. Benign — this code, nothing was written (forged,
@@ -20,8 +21,7 @@ export const EXT_SIGNUP_HANDOVER = "signupHandover";
 // together with it, never treat that as a skippable no-op.
 export const SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE = "invalid_or_expired_grant";
 export function isSignupHandoverProvider(options) {
-    return (typeof options === "object" &&
-        options !== null &&
+    return (isPlainObject(options) &&
         typeof options["verifyGrant"] === "function" &&
         typeof options["mintClaim"] === "function");
 }

package/dist/subscription-stripe/plugin-methods.js

@@ -75,9 +75,7 @@ export function mapAppLocaleToStripeLocale(locale) {
     return knownLocales.find((known) => known === language) ?? "auto";
 }
 function isUnknownCustomerStripeError(error) {
-    return (isResourceMissingStripeError(error) &&
-        error instanceof Stripe.errors.StripeInvalidRequestError &&
-        error.param === "customer");
+    return isResourceMissingStripeError(error) && error.param === "customer";
 }
 export function createStripeCheckoutSession(runtime, { paymentInvoiceCreation = true } = {}) {
     return async (ctx, options) => {
@@ -147,11 +145,23 @@ export function createStripeCheckoutSession(runtime, { paymentInvoiceCreation =
 export function createStripePortalSession(runtime) {
     return async (ctx, options) => {
         const stripe = await runtime.clientForCtx(ctx);
-        const session = await stripe.billingPortal.sessions.create({
-            customer: options.providerCustomerId,
-            return_url: options.returnUrl,
-        });
-        return { url: session.url };
+        try {
+            const session = await stripe.billingPortal.sessions.create({
+                customer: options.providerCustomerId,
+                return_url: options.returnUrl,
+            });
+            return { url: session.url };
+        }
+        catch (error) {
+            // A portal needs an existing customer, so unlike checkout there is no retry without one.
+            if (!isUnknownCustomerStripeError(error))
+                throw error;
+            throw new UnprocessableError("provider_customer_unknown", {
+                i18nKey: "billing-foundation.errors.providerCustomerUnknown",
+                message: `subscription-stripe: Stripe does not know customer "${options.providerCustomerId}" (account switch or customer deleted).`,
+                cause: error,
+            });
+        }
     };
 }
 export function createStripeCancelSubscription(runtime) {

package/dist/subscription-stripe/verify-webhook.d.ts

@@ -3,7 +3,7 @@ import { type SubscriptionEventType, type SubscriptionStatus } from "@cosmicdrif
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import Stripe from "stripe";
 import type { StripeWebhookRuntime } from "./runtime.js";
-export declare function isResourceMissingStripeError(error: unknown): boolean;
+export declare function isResourceMissingStripeError(error: unknown): error is Stripe.errors.StripeInvalidRequestError;
 export type StripeWebhookOptions = {
     /** Price-to-tier-Map. Plugin liest die price-id aus dem event und
      *  mapped auf tier-name. Fehlt die price-id im Mapping → null. App-

package/dist/tags/handlers/assign-tag.write.js

@@ -1,4 +1,5 @@
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { denyUnlessJoinRowParentVisible } from "../../shared/index.js";
 import { tagAssignmentAggregateId } from "../aggregate-id.js";
 import { DEFAULT_TAG_ACCESS } from "../constants.js";
@@ -49,7 +50,8 @@ export function createAssignTagHandler(access = DEFAULT_TAG_ACCESS, assignmentEx
             // above and this restore() call, so restore() correctly refuses with
             // "not_deleted" — but the desired end state is already true. Converge
             // like the create() race below instead of surfacing a spurious error.
-            if (restored.error.details?.reason === "not_deleted") {
+            if (isPlainObject(restored.error.details) &&
+                restored.error.details["reason"] === "not_deleted") {
                 return { isSuccess: true, data: { id } };
             }
             if (restored.error.code !== "not_found")

package/dist/tags/web/tag-chip.js

@@ -14,6 +14,8 @@ function hexToRgb(color) {
     if (match === null)
         return null;
     const short = match[1];
+    if (short === undefined)
+        return null;
     const hex = short.length === 3
         ? `${short[0]}${short[0]}${short[1]}${short[1]}${short[2]}${short[2]}`
         : short;

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

@@ -1,7 +1,10 @@
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import type { FileAttachmentRef } from "../renderer-foundation/index.js";
 import type { ContentFormat, TemplateKind } from "./constants.js";
+import { type TemplatePdfAttachmentLink } from "./linked-resources.js";
+import { type TemplateMeta } from "./template-meta.js";
 export type TemplateResource = {
     readonly id: string;
     readonly version: number;
@@ -14,7 +17,15 @@ export type TemplateResource = {
     readonly content: string;
     readonly contentFormat: ContentFormat;
     readonly variableSchema: Record<string, unknown>;
+    /** Embeddable images: resource key -> fileRef id. */
     readonly linkedResources: Record<string, string>;
+    /** Files attached to every mail rendered from this template, ordered by key. */
+    readonly fileAttachments?: readonly FileAttachmentRef[];
+    /** PDFs rendered from document templates and attached at send time, ordered by key. */
+    readonly pdfAttachmentLinks?: readonly TemplatePdfAttachmentLink[];
+    /** Parsed per kind; null when absent or when the stored JSON no longer
+     *  matches the kind's schema (the renderer then fails with a clear error). */
+    readonly meta: TemplateMeta | null;
     readonly scope: "system" | "tenant";
     readonly parentTemplateId: string | null;
     readonly status: "draft" | "active" | "archived";
@@ -26,6 +37,13 @@ export type ResolveRequest = {
     readonly kind: TemplateKind;
     readonly locale: string;
 };
+export type LayoutKind = "mail-layout" | "pdf-layout";
+export type ResolveLayoutRequest = {
+    readonly tenantId: TenantId;
+    readonly slug: string;
+    readonly kind: LayoutKind;
+    readonly locale: string;
+};
 export type TemplateResolverApi = {
     /**
      * Findet ein konkretes Template by (tenantId, slug, kind, locale).
@@ -60,8 +78,18 @@ export type TemplateResolverApi = {
      * User cross-tenant Templates abfragen (Tenant-Isolation gebrochen).
      */
     readonly resolveTemplate: (args: ResolveRequest) => Promise<TemplateResource>;
+    /**
+     * Layouts are locale-neutral in the product (the layout editor saves under the locale of the
+     * row it loaded), so the locale chain is wider than resolveTemplate: tenant (requested,
+     * FALLBACK_LOCALE, any active locale), then system (same). Only active rows count; among
+     * "any" the highest version wins, then the alphabetically first locale, so the pick is stable.
+     * Throws TemplateNotFoundError when neither scope has an active row.
+     *
+     * **Caller invariant:** `tenantId` must come from the server, as for `resolveTemplate`.
+     */
+    readonly resolveLayout: (args: ResolveLayoutRequest) => Promise<TemplateResource>;
 };
-export declare function createTemplateResolverApi(db: DbRunner): TemplateResolverApi;
+export declare function createTemplateResolverApi(db: DbRunner | TenantDb): TemplateResolverApi;
 export declare class TemplateNotFoundError extends Error {
     readonly query: {
         slug: string;

package/dist/template-resolver/api.js

@@ -4,7 +4,10 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { FALLBACK_LOCALE, SYSTEM_TENANT_ID } from "./constants.js";
+import { fileAttachmentsOf, imageLinksOf, parseLinkedResourceEntries, pdfAttachmentLinksOf, } from "./linked-resources.js";
 import { templateResourcesTable } from "./table.js";
+import { activeVersionOf, servedVersionOf } from "./template-draft.js";
+import { parseTemplateMeta } from "./template-meta.js";
 export function createTemplateResolverApi(db) {
     return {
         findExact: async ({ tenantId, slug, kind, locale, scope }) => {
@@ -31,8 +34,30 @@ export function createTemplateResolverApi(db) {
             }
             throw new TemplateNotFoundError({ slug, kind, locale });
         },
+        resolveLayout: async ({ tenantId, slug, kind, locale }) => {
+            for (const tid of [tenantId, SYSTEM_TENANT_ID]) {
+                const rows = await selectMany(db, templateResourcesTable, {
+                    tenantId: tid,
+                    slug,
+                    kind,
+                });
+                const row = pickActiveLayoutRow(rows, locale);
+                if (row !== null)
+                    return toPublic(row);
+            }
+            throw new TemplateNotFoundError({ slug, kind, locale });
+        },
     };
 }
+function pickActiveLayoutRow(rows, locale) {
+    const active = rows
+        .filter((row) => row.status === "active")
+        .sort((a, b) => activeVersionOf(b) - activeVersionOf(a) || a.locale.localeCompare(b.locale));
+    return (active.find((row) => row.locale === locale) ??
+        active.find((row) => row.locale === FALLBACK_LOCALE) ??
+        active[0] ??
+        null);
+}
 async function fetchTemplate(db, tenantId, slug, kind, locale) {
     const rows = await selectMany(db, templateResourcesTable, { tenantId, slug, kind, locale }, { limit: 1 });
     // @cast-boundary db-row — db.select returnt unbenanntes unknown[],
@@ -43,7 +68,6 @@ function toPublic(row) {
     // @cast-boundary db-row — Drizzle-Schema typisiert kind/contentFormat/
     // scope/status als generic text. CHECK-Constraints in der DB schränken
     // sie auf die Union-Types ein; Cast assertet das Schema-Wissen.
-    // linkedResources ist ein text-column mit JSON-payload (string→string map).
     const kind = row.kind;
     // @cast-boundary db-row — siehe kind.
     const contentFormat = row.contentFormat;
@@ -51,12 +75,10 @@ function toPublic(row) {
     const scope = row.scope;
     // @cast-boundary db-row — siehe kind.
     const status = row.status;
-    // @cast-boundary db-row — parseJson returnt Record<string, unknown>;
-    // linkedResources-Spalte enthält per Schema {key: signedUrl}-Map.
-    const linkedResources = parseJson(row.linkedResources);
+    const linkedEntries = parseLinkedResourceEntries(row.linkedResources);
     return {
         id: String(row.id),
-        version: row.version,
+        version: servedVersionOf(row),
         tenantId: row.tenantId,
         slug: row.slug,
         kind,
@@ -66,13 +88,27 @@ function toPublic(row) {
         content: row.content ?? "",
         contentFormat,
         variableSchema: parseJson(row.variableSchema),
-        linkedResources,
+        linkedResources: imageLinksOf(linkedEntries),
+        fileAttachments: fileAttachmentsOf(linkedEntries),
+        pdfAttachmentLinks: pdfAttachmentLinksOf(linkedEntries),
+        meta: parseStoredMeta(kind, row.meta),
         scope,
         parentTemplateId: row.parentTemplateId,
         status,
         modifiedAt: row.modifiedAt,
     };
 }
+function parseStoredMeta(kind, raw) {
+    if (!raw)
+        return null;
+    try {
+        const result = parseTemplateMeta(kind, JSON.parse(raw));
+        return result.ok ? result.meta : null;
+    }
+    catch {
+        return null;
+    }
+}
 function parseJson(raw) {
     if (!raw)
         return {};

package/dist/template-resolver/compile-document-body.d.ts

@@ -0,0 +1,12 @@
+import type { TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
+export type CompileDocumentBodyOptions = {
+    readonly resourceSrc?: (key: string) => string | undefined;
+    readonly resourceImageMaxWidthPx?: number;
+    readonly alignmentAsInlineStyle?: boolean;
+    readonly buttonAsInlineStyle?: boolean;
+    readonly tableAsInlineStyle?: boolean;
+    readonly buttonInlineStyle?: string;
+};
+export declare function collectDocumentResourceKeys(html: string): readonly string[];
+export declare function toResourceDataUri(contentType: string, bytes: Uint8Array): string;
+export declare function compileDocumentBodyToHandlebars(html: string, variables: TemplateVariables, options?: CompileDocumentBodyOptions): string;

package/dist/template-resolver/compile-document-body.js

@@ -0,0 +1,205 @@
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { withParsedDocument } from "./document-sanitizer.js";
+import { DOCUMENT_TEXT_ALIGNMENTS, isAllowedDocumentLinkHref, isDocumentPlaceholderHref, isDocumentReferenceName, isDocumentResourceKey, } from "./document-schema.js";
+// Private-use characters mark where a Handlebars expression goes. Author text
+// is scrubbed of them first and every `{`/`}` is entity-encoded before the
+// markers are swapped for real expressions, so the only Handlebars syntax in
+// the output is the syntax this module wrote.
+const EXPRESSION_OPEN = "\uE000";
+const EXPRESSION_CLOSE = "\uE001";
+const MARKER_PATTERN = /\uE000(\d+)\uE001/g;
+function marker(state, expression) {
+    state.expressions.push(expression);
+    return `${EXPRESSION_OPEN}${state.expressions.length - 1}${EXPRESSION_CLOSE}`;
+}
+function ownVariable(variables, name) {
+    return Object.hasOwn(variables, name) ? variables[name] : undefined;
+}
+function itemFieldsOf(variables, listName) {
+    const def = ownVariable(variables, listName);
+    return def?.type === "list" ? def.item : null;
+}
+function rowScopeOf(element, state) {
+    const listName = element.closest("tr[data-each]")?.getAttribute("data-each") ?? null;
+    if (listName === null)
+        return null;
+    const itemFields = itemFieldsOf(state.variables, listName);
+    return itemFields === null ? null : { listName, itemFields };
+}
+function resolveReference(name, scope, variables) {
+    if (scope !== null && ownVariable(scope.itemFields, name) !== undefined) {
+        return { path: name, def: ownVariable(scope.itemFields, name) };
+    }
+    return { path: scope === null ? name : `@root.${name}`, def: ownVariable(variables, name) };
+}
+function valueExpression(path, def) {
+    if (def?.type === "money")
+        return `{{money ${path}}}`;
+    if (def?.type === "date")
+        return `{{date ${path}}}`;
+    if (def?.type === "richText")
+        return `{{richText ${path}}}`;
+    return `{{${path}}}`;
+}
+function rewriteVariable(element, state) {
+    const name = element.getAttribute("data-variable") ?? "";
+    const replacement = element.ownerDocument.createTextNode(isDocumentReferenceName(name)
+        ? marker(state, valueExpression(...pathAndDef(name, element, state)))
+        : "");
+    element.replaceWith(replacement);
+}
+function pathAndDef(name, element, state) {
+    const { path, def } = resolveReference(name, rowScopeOf(element, state), state.variables);
+    return [path, def];
+}
+function rewriteLink(element, state) {
+    const href = element.getAttribute("href") ?? "";
+    if (isDocumentPlaceholderHref(href)) {
+        const name = href.slice(2, -2);
+        if (isDocumentReferenceName(name)) {
+            const [path] = pathAndDef(name, element, state);
+            element.setAttribute("href", marker(state, `{{link ${path}}}`));
+        }
+        else {
+            element.setAttribute("href", "#");
+        }
+    }
+    else if (!isAllowedDocumentLinkHref(href)) {
+        element.setAttribute("href", "#");
+    }
+}
+function rewriteRepeatRow(row, state) {
+    const listName = row.getAttribute("data-each") ?? "";
+    const document = row.ownerDocument;
+    if (itemFieldsOf(state.variables, listName) === null || !isDocumentReferenceName(listName)) {
+        row.remove();
+    }
+    else {
+        row.before(document.createTextNode(marker(state, `{{#each ${listName}}}`)));
+        row.after(document.createTextNode(marker(state, "{{/each}}")));
+        row.removeAttribute("data-each");
+        row.removeAttribute("data-repeat-header");
+    }
+}
+function stripActiveContent(element) {
+    for (const attribute of Array.from(element.attributes)) {
+        if (/^on/i.test(attribute.name))
+            element.removeAttribute(attribute.name);
+    }
+}
+function neutralizeBraces(html) {
+    return html.replace(/[{}]/g, (brace) => (brace === "{" ? "{" : "}"));
+}
+const MAIL_BUTTON_STYLE = "display:inline-block;padding:10px 20px;border-radius:6px;background-color:#1f5468;color:#ffffff;font-weight:600;text-decoration:none";
+const MAIL_TABLE_STYLE = "width:100%;border-collapse:collapse";
+const MAIL_TABLE_CELL_STYLE = "padding:6px 12px;vertical-align:top;border-bottom:1px solid #e5e5e5";
+const MAIL_TABLE_HEAD_STYLE = "font-size:12px;font-weight:600;color:#6b7280;text-align:left";
+const MAIL_SMALL_STYLE = "font-size:12px;color:#6b7280";
+// Appended after an existing style (data-align) so the alignment survives.
+function appendStyle(element, style) {
+    const existing = element.getAttribute("style");
+    element.setAttribute("style", existing === null ? style : `${existing};${style}`);
+}
+const RESOURCE_IMAGE_CONTENT_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+]);
+// Unique valid resource keys in document order.
+export function collectDocumentResourceKeys(html) {
+    return withParsedDocument(html, (root) => {
+        const keys = new Set();
+        for (const element of Array.from(root.querySelectorAll("img[data-resource]"))) {
+            const key = element.getAttribute("data-resource") ?? "";
+            if (isDocumentResourceKey(key))
+                keys.add(key);
+        }
+        return [...keys];
+    });
+}
+export function toResourceDataUri(contentType, bytes) {
+    if (!RESOURCE_IMAGE_CONTENT_TYPES.has(contentType)) {
+        throw new Error(`resource content type "${contentType}" cannot be embedded as an image`);
+    }
+    return `data:${contentType};base64,${Buffer.from(bytes).toString("base64")}`;
+}
+function rewriteAlignment(element) {
+    const align = element.getAttribute("data-align");
+    element.removeAttribute("data-align");
+    if (isOneOf(DOCUMENT_TEXT_ALIGNMENTS, align))
+        element.setAttribute("style", `text-align:${align}`);
+}
+function rewriteResourceImage(element, resourceSrc, maxWidthPx) {
+    const key = element.getAttribute("data-resource") ?? "";
+    const src = isDocumentResourceKey(key) ? resourceSrc?.(key) : undefined;
+    if (src === undefined) {
+        element.remove();
+        // skip: an unresolved resource key drops the image
+        return;
+    }
+    element.setAttribute("src", src);
+    element.removeAttribute("data-resource");
+    if (maxWidthPx !== undefined)
+        element.setAttribute("style", `max-width:${maxWidthPx}px;height:auto`);
+}
+function stripScriptsAndActiveContent(root, options) {
+    for (const element of Array.from(root.querySelectorAll("script")))
+        element.remove();
+    for (const element of Array.from(root.querySelectorAll("img[data-resource]"))) {
+        rewriteResourceImage(element, options.resourceSrc, options.resourceImageMaxWidthPx);
+    }
+    for (const element of Array.from(root.querySelectorAll("*")))
+        stripActiveContent(element);
+}
+function applyAlignmentInlineStyles(root) {
+    for (const element of Array.from(root.querySelectorAll("[data-align]"))) {
+        rewriteAlignment(element);
+    }
+    for (const element of Array.from(root.querySelectorAll("[data-size]"))) {
+        element.removeAttribute("data-size");
+        appendStyle(element, MAIL_SMALL_STYLE);
+    }
+}
+function applyTableInlineStyles(root) {
+    for (const table of Array.from(root.querySelectorAll("table"))) {
+        appendStyle(table, MAIL_TABLE_STYLE);
+    }
+    for (const cell of Array.from(root.querySelectorAll("td, th"))) {
+        appendStyle(cell, MAIL_TABLE_CELL_STYLE);
+    }
+    for (const head of Array.from(root.querySelectorAll("th"))) {
+        appendStyle(head, MAIL_TABLE_HEAD_STYLE);
+    }
+}
+function rewriteLinks(root, state, options) {
+    for (const element of Array.from(root.querySelectorAll("a[href]"))) {
+        rewriteLink(element, state);
+        if (options.buttonAsInlineStyle === true && element.hasAttribute("data-button")) {
+            element.setAttribute("style", options.buttonInlineStyle ?? MAIL_BUTTON_STYLE);
+        }
+    }
+}
+// Turns a sanitized document body into Handlebars source. Rows and links are
+// rewritten in document order; list rows last so their placeholders still see
+// the `tr[data-each]` ancestor.
+export function compileDocumentBodyToHandlebars(html, variables, options = {}) {
+    const state = { variables, expressions: [] };
+    const scrubbed = html.replaceAll(EXPRESSION_OPEN, "").replaceAll(EXPRESSION_CLOSE, "");
+    const compiled = withParsedDocument(scrubbed, (root) => {
+        stripScriptsAndActiveContent(root, options);
+        if (options.alignmentAsInlineStyle === true)
+            applyAlignmentInlineStyles(root);
+        if (options.tableAsInlineStyle === true)
+            applyTableInlineStyles(root);
+        for (const element of Array.from(root.querySelectorAll("span[data-variable]"))) {
+            rewriteVariable(element, state);
+        }
+        rewriteLinks(root, state, options);
+        for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
+            rewriteRepeatRow(element, state);
+        }
+        return root.innerHTML;
+    });
+    return neutralizeBraces(compiled).replace(MARKER_PATTERN, (_match, index) => state.expressions[Number(index)] ?? "");
+}