@cosmicdrift/kumiko-samples 0.363.0 → 0.365.0

package/packages/bundled-features/src/personal-access-tokens/revoke-for-user.ts

@@ -1,10 +1,13 @@
-import { transaction, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  runnerCanBeginTransaction,
+  transaction,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { append } from "@cosmicdrift/kumiko-framework/event-store";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import {
   PAT_REVOKED_AGGREGATE_TYPE,
   PAT_REVOKED_EVENT_QN,
@@ -12,11 +15,6 @@ import {
 } from "./pat-revoked-event.js";
 import { apiTokenTable } from "./schema/api-token.js";
 
-// A pool has begin(); a tx/savepoint handle does not and is already atomic.
-function canBeginTransaction(db: DbRunner): boolean {
-  return typeof propertyOf(db, "begin") === "function";
-}
-
 // Cross-tenant revoke: password-change and MFA-enable/disable are account-
 // level security events, not scoped to one tenant. Mirrors sessions'
 // sessionMassRevoker (session-callbacks.ts) which passes the boot-time
@@ -24,7 +22,8 @@ function canBeginTransaction(db: DbRunner): boolean {
 export async function revokeAllPatTokensForUser(db: DbRunner, userId: string): Promise<number> {
   // Update and event commit together: otherwise a failed append leaves the
   // tokens revoked with no event, and a retry matches no live row.
-  return canBeginTransaction(db)
+  // A pool has begin(); a tx/savepoint handle does not and is already atomic.
+  return runnerCanBeginTransaction(db)
     ? transaction(db, (tx) => revokeAndAppend(tx, userId))
     : revokeAndAppend(db, userId);
 }

package/packages/bundled-features/src/renderer-foundation/types.ts

@@ -62,6 +62,8 @@ export type RenderResponse = (
       html: string;
       text: string;
       previewText?: string;
+      fromName?: string;
+      replyTo?: string;
       attachments?: readonly MailAttachmentRef[];
     }
   | {

package/packages/bundled-features/src/renderer-pdf/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "renderTablePdf rejects tables above 10000 rows, 30 columns or 5000 characters per cell",
+    "detail": "The table document schema now caps rows at 10000, columns at 30 and each cell string at 5000 characters. Larger input fails with invalid_payload instead of exhausting memory during layout."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "render-table-pdf validates input and paginates its intro",
+    "detail": "Table documents reject negative margins and unusable column widths, normalize CRLF and paginate the intro text and the first header row."
+  },
   {
     "version": "0.360.0",
     "type": "improvement",

package/packages/bundled-features/src/renderer-pdf/render-table-pdf.ts

@@ -1,52 +1,56 @@
 import { PDFDocument, type PDFFont, type PDFPage, rgb, StandardFonts } from "pdf-lib";
 import * as z from "zod";
 import { RendererError } from "../renderer-foundation/index.js";
-
-export const pdfTableDocumentSchema = z.object({
-  title: z.string(),
-  subtitle: z.string().optional(),
-  meta: z.array(z.object({ label: z.string(), value: z.string() })).optional(),
-  columns: z
-    .array(
-      z.object({
-        header: z.string(),
-        weight: z.number().positive().optional(),
-        align: z.enum(["left", "right"]).optional(),
-      }),
-    )
-    .min(1),
-  rows: z.array(z.array(z.string())),
-  emptyText: z.string().optional(),
-  footerText: z.string().optional(),
-  pageLabel: z.string().optional(),
-});
-
-export type PdfTableColumn = {
-  readonly header: string;
-  readonly weight?: number;
-  readonly align?: "left" | "right";
-};
-
-export type PdfTableDocument = {
-  readonly title: string;
-  readonly subtitle?: string;
-  readonly meta?: readonly { readonly label: string; readonly value: string }[];
-  readonly columns: readonly PdfTableColumn[];
-  readonly rows: readonly (readonly string[])[];
-  readonly emptyText?: string;
-  readonly footerText?: string;
-  /** Template with `{page}` and `{pages}`; default `"{page} / {pages}"`. */
-  readonly pageLabel?: string;
-};
+import type { PdfPageFormat } from "../template-resolver/index.js";
+
+// Upper bounds keep a hostile or runaway payload from exhausting memory and CPU in layout.
+const PDF_TABLE_MAX_ROWS = 10_000;
+const PDF_TABLE_MAX_COLUMNS = 30;
+const PDF_TABLE_MAX_CELL_LENGTH = 5_000;
+
+const pdfTableColumnSchema = z
+  .object({
+    header: z.string(),
+    weight: z.number().positive().optional(),
+    align: z.enum(["left", "right"]).optional(),
+  })
+  .readonly();
+
+export const pdfTableDocumentSchema = z
+  .object({
+    title: z.string(),
+    subtitle: z.string().optional(),
+    meta: z
+      .array(z.object({ label: z.string(), value: z.string() }).readonly())
+      .readonly()
+      .optional(),
+    columns: z.array(pdfTableColumnSchema).min(1).max(PDF_TABLE_MAX_COLUMNS).readonly(),
+    rows: z
+      .array(z.array(z.string().max(PDF_TABLE_MAX_CELL_LENGTH)).readonly())
+      .max(PDF_TABLE_MAX_ROWS)
+      .readonly(),
+    emptyText: z.string().optional(),
+    footerText: z.string().optional(),
+    // Template with `{page}` and `{pages}`; default `"{page} / {pages}"`.
+    pageLabel: z.string().optional(),
+  })
+  .readonly();
+
+export type PdfTableColumn = z.infer<typeof pdfTableColumnSchema>;
+export type PdfTableDocument = z.infer<typeof pdfTableDocumentSchema>;
+
+const marginMmSchema = z
+  .object({
+    top: z.number().nonnegative().optional(),
+    right: z.number().nonnegative().optional(),
+    bottom: z.number().nonnegative().optional(),
+    left: z.number().nonnegative().optional(),
+  })
+  .readonly();
 
 export type PdfTableOptions = {
-  readonly format?: "A4" | "Letter";
-  readonly marginMm?: {
-    readonly top?: number;
-    readonly right?: number;
-    readonly bottom?: number;
-    readonly left?: number;
-  };
+  readonly format?: PdfPageFormat;
+  readonly marginMm?: z.input<typeof marginMmSchema>;
 };
 
 export type PdfTableResult = { readonly pdfBytes: Uint8Array; readonly pageCount: number };
@@ -55,7 +59,7 @@ const POINTS_PER_MM = 72 / 25.4;
 const PAGE_SIZE_POINTS = {
   A4: { width: 595.28, height: 841.89 },
   Letter: { width: 612, height: 792 },
-} as const;
+} as const satisfies Record<PdfPageFormat, { readonly width: number; readonly height: number }>;
 const DEFAULT_MARGIN_MM = { top: 18, right: 15, bottom: 18, left: 15 } as const;
 
 const TITLE_SIZE = 16;
@@ -66,6 +70,7 @@ const LINE_HEIGHT_FACTOR = 1.3;
 const CELL_PADDING_X = 4;
 const CELL_PADDING_Y = 3;
 const FOOTER_RESERVE = 16;
+const MIN_COLUMN_WIDTH = 20;
 const META_LABEL_GAP = 10;
 const BLOCK_GAP = 10;
 const REPLACEMENT_CHAR = "?";
@@ -86,7 +91,7 @@ function createEncodableText(font: PDFFont): (text: string) => string {
   const supported = new Set(font.getCharacterSet());
   return (text) => {
     let result = "";
-    for (const char of text.replace(/\t/g, " ")) {
+    for (const char of text.replace(/\r\n?/g, "\n").replace(/\t/g, " ")) {
       const codePoint = char.codePointAt(0) ?? 0;
       result += codePoint === 0x0a || supported.has(codePoint) ? char : REPLACEMENT_CHAR;
     }
@@ -157,30 +162,43 @@ function assertRowShape(doc: PdfTableDocument): void {
   });
 }
 
-export async function renderTablePdf(
-  doc: PdfTableDocument,
-  options?: PdfTableOptions,
-): Promise<PdfTableResult> {
-  if (doc.columns.length === 0) {
-    throw new RendererError("table needs at least one column", "invalid_payload");
-  }
-  assertRowShape(doc);
-
-  const pdf = await PDFDocument.create({ updateMetadata: false });
-  const fonts: Fonts = {
-    regular: await pdf.embedFont(StandardFonts.Helvetica),
-    bold: await pdf.embedFont(StandardFonts.HelveticaBold),
+type TableLayout = {
+  readonly pageSize: { readonly width: number; readonly height: number };
+  readonly margin: {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
   };
-  const clean = createEncodableText(fonts.regular);
+  readonly contentWidth: number;
+  readonly contentBottom: number;
+  readonly columnWidths: readonly number[];
+  readonly bodyLineHeight: number;
+  readonly headerLines: readonly (readonly string[])[];
+  readonly headerHeight: number;
+};
 
+function resolveTableLayout(
+  doc: PdfTableDocument,
+  options: PdfTableOptions | undefined,
+  fonts: Fonts,
+  clean: (text: string) => string,
+): TableLayout {
+  const marginMm = marginMmSchema.safeParse(options?.marginMm ?? {});
+  if (!marginMm.success) {
+    throw new RendererError("margins must be non-negative numbers", "invalid_payload");
+  }
   const pageSize = PAGE_SIZE_POINTS[options?.format ?? "A4"];
   const margin = {
-    top: (options?.marginMm?.top ?? DEFAULT_MARGIN_MM.top) * POINTS_PER_MM,
-    right: (options?.marginMm?.right ?? DEFAULT_MARGIN_MM.right) * POINTS_PER_MM,
-    bottom: (options?.marginMm?.bottom ?? DEFAULT_MARGIN_MM.bottom) * POINTS_PER_MM,
-    left: (options?.marginMm?.left ?? DEFAULT_MARGIN_MM.left) * POINTS_PER_MM,
+    top: (marginMm.data.top ?? DEFAULT_MARGIN_MM.top) * POINTS_PER_MM,
+    right: (marginMm.data.right ?? DEFAULT_MARGIN_MM.right) * POINTS_PER_MM,
+    bottom: (marginMm.data.bottom ?? DEFAULT_MARGIN_MM.bottom) * POINTS_PER_MM,
+    left: (marginMm.data.left ?? DEFAULT_MARGIN_MM.left) * POINTS_PER_MM,
   };
   const contentWidth = pageSize.width - margin.left - margin.right;
+  if (contentWidth < MIN_COLUMN_WIDTH * doc.columns.length) {
+    throw new RendererError("margins leave no room for table columns", "invalid_payload");
+  }
   const contentBottom = margin.bottom + FOOTER_RESERVE;
   const columnWidths = resolveColumnWidths(doc.columns, contentWidth);
   const bodyLineHeight = lineHeightFor(BODY_SIZE);
@@ -200,6 +218,48 @@ export async function renderTablePdf(
   );
   const headerHeight =
     Math.max(...headerLines.map((lines) => lines.length)) * bodyLineHeight + 2 * CELL_PADDING_Y;
+  // A header this tall would leave every continuation page without room for a row.
+  if (rowSpaceOnEmptyPage - headerHeight < bodyLineHeight + 2 * CELL_PADDING_Y) {
+    throw new RendererError("table header leaves no room for rows", "invalid_payload");
+  }
+  return {
+    pageSize,
+    margin,
+    contentWidth,
+    contentBottom,
+    columnWidths,
+    bodyLineHeight,
+    headerLines,
+    headerHeight,
+  };
+}
+
+export async function renderTablePdf(
+  doc: PdfTableDocument,
+  options?: PdfTableOptions,
+): Promise<PdfTableResult> {
+  if (doc.columns.length === 0) {
+    throw new RendererError("table needs at least one column", "invalid_payload");
+  }
+  assertRowShape(doc);
+
+  const pdf = await PDFDocument.create({ updateMetadata: false });
+  const fonts: Fonts = {
+    regular: await pdf.embedFont(StandardFonts.Helvetica),
+    bold: await pdf.embedFont(StandardFonts.HelveticaBold),
+  };
+  const clean = createEncodableText(fonts.regular);
+
+  const {
+    pageSize,
+    margin,
+    contentWidth,
+    contentBottom,
+    columnWidths,
+    bodyLineHeight,
+    headerLines,
+    headerHeight,
+  } = resolveTableLayout(doc, options, fonts, clean);
 
   let page: PDFPage = pdf.addPage([pageSize.width, pageSize.height]);
   let cursorY = pageSize.height - margin.top;
@@ -227,29 +287,50 @@ export async function renderTablePdf(
     });
   }
 
+  function startBlankPage(): void {
+    page = pdf.addPage([pageSize.width, pageSize.height]);
+    cursorY = pageSize.height - margin.top;
+  }
+
+  function ensureRoom(height: number): void {
+    if (cursorY - height < contentBottom) startBlankPage();
+  }
+
+  // Line by line, so a block taller than one page continues on the next.
+  function flowLines(
+    lines: readonly string[],
+    font: PDFFont,
+    size: number,
+    left: number,
+    width: number,
+    color = TEXT_COLOR,
+  ): void {
+    const lineHeight = lineHeightFor(size);
+    for (const line of lines) {
+      ensureRoom(lineHeight);
+      drawLines([line], font, size, left, width, cursorY, "left", color);
+      cursorY -= lineHeight;
+    }
+  }
+
   function drawIntroBlock(): void {
-    const titleLines = wrapText(clean(doc.title), fonts.bold, TITLE_SIZE, contentWidth);
-    drawLines(titleLines, fonts.bold, TITLE_SIZE, margin.left, contentWidth, cursorY, "left");
-    cursorY -= titleLines.length * lineHeightFor(TITLE_SIZE);
+    flowLines(
+      wrapText(clean(doc.title), fonts.bold, TITLE_SIZE, contentWidth),
+      fonts.bold,
+      TITLE_SIZE,
+      margin.left,
+      contentWidth,
+    );
 
     if (doc.subtitle !== undefined) {
-      const subtitleLines = wrapText(
-        clean(doc.subtitle),
-        fonts.regular,
-        SUBTITLE_SIZE,
-        contentWidth,
-      );
-      drawLines(
-        subtitleLines,
+      flowLines(
+        wrapText(clean(doc.subtitle), fonts.regular, SUBTITLE_SIZE, contentWidth),
         fonts.regular,
         SUBTITLE_SIZE,
         margin.left,
         contentWidth,
-        cursorY,
-        "left",
         MUTED_COLOR,
       );
-      cursorY -= subtitleLines.length * lineHeightFor(SUBTITLE_SIZE);
     }
 
     const meta = doc.meta ?? [];
@@ -266,6 +347,7 @@ export async function renderTablePdf(
           BODY_SIZE,
           contentWidth - labelWidth,
         );
+        ensureRoom(bodyLineHeight);
         drawLines(
           [labels[index] ?? ""],
           fonts.bold,
@@ -275,16 +357,13 @@ export async function renderTablePdf(
           cursorY,
           "left",
         );
-        drawLines(
+        flowLines(
           valueLines,
           fonts.regular,
           BODY_SIZE,
           margin.left + labelWidth,
           contentWidth - labelWidth,
-          cursorY,
-          "left",
         );
-        cursorY -= valueLines.length * bodyLineHeight;
       });
     }
     cursorY -= BLOCK_GAP;
@@ -372,6 +451,7 @@ export async function renderTablePdf(
   }
 
   drawIntroBlock();
+  ensureRoom(headerHeight + bodyLineHeight + 2 * CELL_PADDING_Y);
   drawTableHeader();
 
   if (doc.rows.length === 0 && doc.emptyText !== undefined) {

package/packages/bundled-features/src/secrets/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "secrets delete no longer requires a declared key",
+    "detail": "secrets:write:delete used to answer 404 unknownKey for a key that no feature declares, so a row stored before the declaration gate existed could never be removed. Delete now skips the declaration check; writeRoles of a declared key or namespace still apply, and set keeps the gate."
+  },
+  {
+    "version": "0.364.0",
+    "type": "improvement",
+    "title": "SecretsContext.withRunner(tx) runs secret access on a given transaction",
+    "detail": "The OAuth refresh now reads and writes the refresh token on its advisory-lock transaction, so a refresh holds one pool connection instead of two and parallel refreshes cannot starve the pool. Custom SecretsContext implementations need a `withRunner` method."
+  },
   {
     "version": "0.343.0",
     "type": "improvement",

package/packages/bundled-features/src/secrets/feature.ts

@@ -83,21 +83,22 @@ export function requireSecretsContext(
         "createSecretsContext({db, masterKeyProvider, registry}) via extraContext.secrets at boot.",
     });
   }
-  const raw = ctx.secrets;
   const userId = ctx._userId;
   if (!userId) {
     throw new InternalError({
       message: `[${handlerName}] ctx._userId missing — cannot audit secret reads without a caller identity.`,
     });
   }
-  return {
+  const withAudit = (raw: SecretsContext): SecretsContext => ({
+    withRunner: (runner) => withAudit(raw.withRunner(runner)),
     get: (tenantId, key, overrideAudit) =>
       raw.get(tenantId, key, overrideAudit ?? { userId, handlerName }),
     // No audit injection: has() is metadata-only and never logs a read.
     has: raw.has.bind(raw),
     set: raw.set.bind(raw),
     delete: raw.delete.bind(raw),
-  };
+  });
+  return withAudit(ctx.secrets);
 }
 
 export type SecretsFeatureOptions = {

package/packages/bundled-features/src/secrets/handlers/delete.write.ts

@@ -18,7 +18,9 @@ export function createDeleteHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS)
     access,
     handler: async (event, ctx) => {
       const secrets = requireSecretsContext(ctx, "secrets:write:delete");
-      const gate = checkSecretKeyWrite(ctx.registry, event.user.roles, event.payload.key);
+      const gate = checkSecretKeyWrite(ctx.registry, event.user.roles, event.payload.key, {
+        allowUndeclared: true,
+      });
       if (!gate.ok) return gate.failure;
       const removed = await secrets.delete(event.user.tenantId, event.payload.key, {
         deletedBy: event.user.id,

package/packages/bundled-features/src/secrets/secrets-context.ts

@@ -17,6 +17,7 @@ import {
   createEventStoreExecutor,
   createTenantDb,
   type DbConnection,
+  type DbRunner,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, type WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
@@ -91,8 +92,20 @@ function resolveKey(keyOrHandle: string | { readonly name: string }): string {
 }
 
 export function createSecretsContext(opts: SecretsContextOptions): SecretsContext {
-  const { db, masterKeyProvider } = opts;
+  const { masterKeyProvider } = opts;
   const provider = withDekCache(masterKeyProvider, opts.dekCache ?? createDekCache());
+  return buildSecretsContext(opts, provider, opts.db, false);
+}
+
+// `runnerIsTransaction`: the runner is a caller-owned transaction, so audited reads join it
+// instead of opening a second connection (which would deadlock a small pool).
+function buildSecretsContext(
+  opts: SecretsContextOptions,
+  provider: MasterKeyProvider,
+  db: DbRunner,
+  runnerIsTransaction: boolean,
+): SecretsContext {
+  const { masterKeyProvider } = opts;
 
   type SecretLookupRow = {
     readonly id: string;
@@ -105,6 +118,10 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
   }
 
   return {
+    withRunner(runner) {
+      return buildSecretsContext(opts, provider, runner, true);
+    },
+
     async get(tenantId, keyOrHandle, auditCtx) {
       const key = resolveKey(keyOrHandle);
       // Atomic audit + read: a decrypt that "escaped" the audit trail
@@ -120,7 +137,7 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
         return createSecret(plaintext);
       }
 
-      const plaintext = await transaction(db, async (tx) => {
+      const readAndAudit = async (tx: DbRunner): Promise<string | undefined> => {
         // Inline select inside the TX via raw client — fetchOne's connection
         // type doesn't widen to the transaction object cleanly.
         const envelope = await selectTenantSecretEnvelope(tx, tenantId, key);
@@ -154,7 +171,10 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
           metadata,
         });
         return pt;
-      });
+      };
+      const plaintext = runnerIsTransaction
+        ? await readAndAudit(db)
+        : await transaction(db, readAndAudit);
 
       if (plaintext === undefined) return undefined;
       // Brand the plaintext only after audit committed. The response

package/packages/bundled-features/src/secrets/write-gate.ts

@@ -37,15 +37,21 @@ function namespaceAcceptsKey(namespace: SecretNamespaceDefinition, key: string):
 // Only keys declared via r.secret() or under a declared r.secretNamespace()
 // are writable through the API, so a tenant admin cannot plant arbitrary rows
 // next to the feature-owned ones. writeRoles narrows the handler access
-// further for a key or a whole namespace.
+// further for a key or a whole namespace. Delete passes allowUndeclared: it
+// creates nothing, and legacy rows under since-undeclared keys must stay removable.
 export function checkSecretKeyWrite(
   registry: Registry,
   userRoles: readonly string[],
   key: string,
+  options: { readonly allowUndeclared?: boolean } = {},
 ): SecretKeyWriteCheck {
   const keyDef = registry.getSecretKey(key);
   const namespace = keyDef ? undefined : registry.findSecretNamespace(key);
-  if (!keyDef && !(namespace && namespaceAcceptsKey(namespace, key))) {
+  if (
+    !keyDef &&
+    !(namespace && namespaceAcceptsKey(namespace, key)) &&
+    options.allowUndeclared !== true
+  ) {
     return unknownKeyFailure(key);
   }
   const writeRoles = keyDef?.writeRoles ?? namespace?.writeRoles;

package/packages/bundled-features/src/shared/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "improvement",
+    "title": "Mail template body helpers exported as `./shared/mail-template-body`",
+    "detail": "Apps that register their own notification templates can build the body with the same helpers the framework uses: `mailParagraph`, `mailHeading`, `mailRepeatedRows`, `mailTextWithSlotsHtml`, plus the new `mailButton`, `mailParagraphWithLink` and `mailSubject`. The subpath only depends on kumiko-headless and is safe on the server. Apps that copied these helpers can import them instead."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/shared/chunked-entity-migration.ts

@@ -33,6 +33,9 @@ export type ChunkedMigrationOptions<Row> = {
   readonly maxFailures: number;
   // Epoch ms; Number.POSITIVE_INFINITY for no time bound.
   readonly deadlineAt: number;
+  // Batches processed even when the deadline already passed. Callers whose setup before the
+  // loop can eat the whole budget set 1, so every run makes progress instead of timing out empty.
+  readonly minBatches?: number;
   readonly signal?: AbortSignal | undefined;
   readonly onRowError?: (row: Row, err: unknown) => void;
 };
@@ -51,7 +54,7 @@ export async function runChunkedMigration<Row>(
       stoppedReason = "signal";
       break;
     }
-    if (Date.now() >= opts.deadlineAt) {
+    if (batchesProcessed >= (opts.minBatches ?? 0) && Date.now() >= opts.deadlineAt) {
       stoppedReason = "timeout";
       break;
     }

package/packages/bundled-features/src/shared/index.ts

@@ -40,6 +40,14 @@ export {
 } from "./redact.js";
 export { REDACTED_PII_PLACEHOLDER, redactPiiCiphertext } from "./redact-pii-ciphertext.js";
 export { requireForTenant } from "./require-for-tenant.js";
+export {
+  extensionForResourceContentType,
+  isResourceImageContentType,
+  isResourceImageFormat,
+  RESOURCE_IMAGE_FORMATS,
+  type ResourceImageContentType,
+  type ResourceImageFormat,
+} from "./resource-image-formats.js";
 export {
   type RowBoundGrantResult,
   redeemRowBoundGrant,

package/packages/bundled-features/src/shared/mail-template-body.ts

@@ -19,7 +19,24 @@ export function mailHeading(text: string): string {
   return `<h2>${mailTextWithSlotsHtml(text)}</h2>`;
 }
 
+export function mailButton(label: string, linkVariable: string): string {
+  return `<p><a data-button href="{{${escapeHtmlAttr(linkVariable)}}}">${escapeHtml(label)}</a></p>`;
+}
+
+export function mailParagraphWithLink(
+  text: string,
+  linkLabel: string,
+  linkVariable: string,
+): string {
+  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: string, field: string): string {
   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: string): string {
+  return text.replace(SLOT_PATTERN, "{{$1}}");
+}

package/packages/bundled-features/src/shared/resource-image-formats.ts

@@ -0,0 +1,31 @@
+// Single source for the raster formats a template resource image may have: the normalizer, the
+// stored file extension, the data-URI embedding and the inline mail attachment name all derive
+// from it, so a new format cannot be accepted in one place and dropped in another.
+export const RESOURCE_IMAGE_FORMATS = {
+  png: { contentType: "image/png", extension: "png" },
+  jpeg: { contentType: "image/jpeg", extension: "jpg" },
+  gif: { contentType: "image/gif", extension: "gif" },
+  webp: { contentType: "image/webp", extension: "webp" },
+} as const;
+
+export type ResourceImageFormat = keyof typeof RESOURCE_IMAGE_FORMATS;
+export type ResourceImageContentType =
+  (typeof RESOURCE_IMAGE_FORMATS)[ResourceImageFormat]["contentType"];
+
+export function isResourceImageFormat(format: string | undefined): format is ResourceImageFormat {
+  return format !== undefined && Object.hasOwn(RESOURCE_IMAGE_FORMATS, format);
+}
+
+function formatForContentType(contentType: string) {
+  return Object.values(RESOURCE_IMAGE_FORMATS).find((entry) => entry.contentType === contentType);
+}
+
+export function isResourceImageContentType(
+  contentType: string,
+): contentType is ResourceImageContentType {
+  return formatForContentType(contentType) !== undefined;
+}
+
+export function extensionForResourceContentType(contentType: string): string | undefined {
+  return formatForContentType(contentType)?.extension;
+}