@cosmicdrift/kumiko-samples 0.348.1 → 0.350.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.348.1",
+  "version": "0.350.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.348.1",
+  "version": "0.350.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/channel-email/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.350.0",
+    "type": "improvement",
+    "title": "Mails get a plain-text part (EmailMessage.text, NotificationRenderer.renderText, simple renderer and GDPR mails fill it)",
+    "detail": "Email text part\n`EmailMessage` gets an optional `text`. With it the SMTP transport sends `multipart/alternative` with a plain-text part. `NotificationRenderer` gets an optional `renderText`, which the email channel sends next to the HTML through the queued render and send jobs. `createSimpleRenderer` implements it from the template data (header, sections, footer, branding footer; buttons as `label: url`). The GDPR default mails return and send `text` as well. The PII guard checks and redacts `text` like the body."
+  },
   {
     "version": "0.348.1",
     "type": "fix",

package/packages/bundled-features/src/channel-email/email-channel.ts

@@ -106,13 +106,15 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
       title: message.title,
       body: message.body,
     };
-    const html = await renderer.render({
+    const rendererInput = {
       template: message.notificationType,
       variables,
       locale: message.locale,
-    });
+    };
+    const html = await renderer.render(rendererInput);
+    const text = renderer.renderText ? await renderer.renderText(rendererInput) : undefined;
     const subject = (variables["subject"] as string) ?? message.title; // @cast-boundary dynamic-key
-    return { html, subject };
+    return { html, subject, ...(text !== undefined && { text }) };
   }
 
   return {
@@ -132,9 +134,17 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
     },
 
     async send(address, message, _ctx, rendered) {
-      const { html, subject } = rendered ?? (await renderMessage(message));
+      const { html, subject, text } = rendered ?? (await renderMessage(message));
       const envelope = emailEnvelopeFrom(message.data);
-      await transport.send(guardEmailMessage({ to: address, subject, html, ...envelope }));
+      await transport.send(
+        guardEmailMessage({
+          to: address,
+          subject,
+          html,
+          ...(text !== undefined && { text }),
+          ...envelope,
+        }),
+      );
       return { status: "sent", address };
     },
   };

package/packages/bundled-features/src/channel-email/pii-guard.ts

@@ -36,7 +36,9 @@ export function guardEmailMessage(message: EmailMessage): EmailMessage {
     }
   }
   const leaking =
-    message.subject.includes(CIPHERTEXT_MARKER) || message.html.includes(CIPHERTEXT_MARKER);
+    message.subject.includes(CIPHERTEXT_MARKER) ||
+    message.html.includes(CIPHERTEXT_MARKER) ||
+    message.text?.includes(CIPHERTEXT_MARKER) === true;
   if (!leaking) return message;
   const detail =
     "[channel-email] mail subject/body contains a PII ciphertext " +
@@ -48,6 +50,9 @@ export function guardEmailMessage(message: EmailMessage): EmailMessage {
     ...message,
     subject: message.subject.replace(CIPHERTEXT_RE, "[pii-redacted]"),
     html: message.html.replace(CIPHERTEXT_RE, "[pii-redacted]"),
+    ...(message.text !== undefined && {
+      text: message.text.replace(CIPHERTEXT_RE, "[pii-redacted]"),
+    }),
   };
 }
 

package/packages/bundled-features/src/channel-email/smtp-transport.ts

@@ -92,6 +92,7 @@ export function createSmtpTransport(options: SmtpTransportOptions): EmailTranspo
         to: message.to,
         subject: message.subject,
         html: message.html,
+        ...(message.text !== undefined && { text: message.text }),
         ...(message.replyTo && { replyTo: message.replyTo }),
         ...(message.headers && { headers: message.headers }),
       });

package/packages/bundled-features/src/channel-email/types.ts

@@ -3,6 +3,9 @@ export type EmailMessage = {
   readonly to: string;
   readonly subject: string;
   readonly html: string;
+  // Plain-text alternative to `html`. Set → the mail goes out as
+  // multipart/alternative, and clients without HTML show this part.
+  readonly text?: string;
   // Per-message From override. Absent → the transport's configured From (the
   // app-wide default). Set when one send must originate from a specific
   // mailbox — a reply from the address the original mail reached, not noreply@.

package/packages/bundled-features/src/delivery/jobs.ts

@@ -47,7 +47,9 @@ const renderJobPayloadSchema = z.object({
 });
 
 const sendJobPayloadSchema = renderJobPayloadSchema.extend({
-  rendered: z.object({ html: z.string(), subject: z.string() }).optional(),
+  rendered: z
+    .object({ html: z.string(), subject: z.string(), text: z.string().optional() })
+    .optional(),
 });
 
 type RenderJobPayload = z.infer<typeof renderJobPayloadSchema>;

package/packages/bundled-features/src/delivery/types.ts

@@ -48,6 +48,7 @@ export type ChannelResult = {
 export type RenderedMessage = {
   readonly html: string;
   readonly subject: string;
+  readonly text?: string;
 };
 
 // `mode` decides how the delivery-service dispatches a channel:
@@ -83,6 +84,8 @@ export type RendererInput = {
 export type NotificationRenderer = {
   readonly name: string;
   render(input: RendererInput): Promise<string>;
+  /** Plain-text version of the same mail; the email channel sends it as the text part of a multipart/alternative mail. */
+  renderText?(input: RendererInput): Promise<string>;
 };
 
 // --- Delivery Log Entry ---

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.349.0",
+    "type": "improvement",
+    "title": "Metrics accept payload filters that narrow the aggregate without replacing the tenant scope",
+    "detail": "metrics: payload filters on a metric\n`MetricDefinition.filters` maps payload keys to source columns, e.g. `{ folderId: \"folderId\" }`. The metric query then accepts that key and narrows the aggregate to the value, for the current and previous window and for groups, stacks and series. The tenant scope is applied last, so a filter value from another tenant yields 0, never that tenant's numbers. `\"\"`, `null` and a missing key mean no filter. The value type follows the column (uuid, numeric, text); an invalid value is a 400. Definitions are rejected at boot for non-camelCase keys, the reserved keys `range`/`timeZone`/`tenantId`, unknown columns, the tenant column, columns already fixed by `where`, and column types other than uuid, text and numeric.\nA filter can also be a resolver `{ column, resolve(value, ctx), valueKind? }`: the payload value (e.g. a folder id) is mapped to the allowed values of `column` through the tenant handler context (IN filter, empty result = no rows), for assignments that live in another table. Resolvers are rejected on metrics with scope `system`."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/metrics/compute.ts

@@ -22,6 +22,8 @@ export type MetricRunParams = {
   readonly range: MetricRange;
   readonly timeZone: string;
   readonly now: Temporal.Instant;
+  /** Payload-driven narrowing (MetricDefinition.filters); scopeWhere wins on conflicts. */
+  readonly filterWhere: WhereObject;
   /** Extra filter that narrows the source to the caller's scope. */
   readonly scopeWhere: WhereObject;
 };
@@ -68,9 +70,10 @@ type MetricAggregates = {
 function buildWheres(
   metric: MetricDefinition,
   window: MetricWindow | undefined,
+  filterWhere: WhereObject,
   scopeWhere: WhereObject,
 ): MetricWheres {
-  const baseWhere: WhereObject = { ...metric.where, ...scopeWhere };
+  const baseWhere: WhereObject = { ...metric.where, ...filterWhere, ...scopeWhere };
   const { timeField } = metric;
   if (timeField === undefined || window === undefined) {
     return { current: baseWhere, previous: undefined };
@@ -200,7 +203,7 @@ export async function runMetric(
       ? { field: timeField, bucket, timeZone: params.timeZone }
       : undefined;
 
-  const wheres = buildWheres(metric, window, params.scopeWhere);
+  const wheres = buildWheres(metric, window, params.filterWhere, params.scopeWhere);
   const aggregates = await fetchAggregates(db, metric, wheres, bucketDimension);
 
   const value = aggregates.total[0]?.value ?? null;

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

@@ -15,6 +15,11 @@ import {
   METRICS_SYSTEM_FEATURE,
   type MetricScope,
 } from "./constants.js";
+import {
+  metricFilterPayloadShape,
+  metricFilterWhere,
+  resolveMetricFilterWhere,
+} from "./filters.js";
 import { METRICS_I18N } from "./i18n.js";
 import type { MetricDefinition, MetricsFeatureOptions } from "./types.js";
 import { metricHasTenantColumn, validateMetrics } from "./validate.js";
@@ -33,13 +38,21 @@ const invalidTimeZone = {
   message: "Unknown IANA time zone",
 };
 
-const tenantPayloadSchema = z
-  .object(windowFields)
-  .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+function tenantPayloadSchema(metric: MetricDefinition) {
+  return z
+    .object({ ...metricFilterPayloadShape(metric), ...windowFields })
+    .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+}
 
-const systemPayloadSchema = z
-  .object({ ...windowFields, tenantId: z.uuid().optional() })
-  .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+function systemPayloadSchema(metric: MetricDefinition) {
+  return z
+    .object({
+      ...metricFilterPayloadShape(metric),
+      ...windowFields,
+      tenantId: z.uuid().optional(),
+    })
+    .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+}
 
 const defaultClock = (): Temporal.Instant => Temporal.Now.instant();
 
@@ -64,13 +77,14 @@ function createTenantMetricQuery(
   return defineQueryHandler({
     name: metric.id,
     description: metric.description,
-    schema: tenantPayloadSchema,
+    schema: tenantPayloadSchema(metric),
     access: { roles: access.admin },
-    handler: (query, ctx) =>
+    handler: async (query, ctx) =>
       runMetric(ctx.db, metric, {
         range: query.payload.range,
         timeZone: query.payload.timeZone,
         now: now(),
+        filterWhere: await resolveMetricFilterWhere(metric, query.payload, ctx),
         // ctx.db already reads own-tenant + SYSTEM reference rows; this narrows to own-tenant only.
         scopeWhere: { tenantId: query.user.tenantId },
       }),
@@ -84,7 +98,7 @@ function createSystemMetricQuery(
   return defineQueryHandler({
     name: metric.id,
     description: metric.description,
-    schema: systemPayloadSchema,
+    schema: systemPayloadSchema(metric),
     access: { roles: access.systemAdmin },
     handler: (query, ctx) => {
       if (!ctx.systemDb) {
@@ -111,6 +125,7 @@ function createSystemMetricQuery(
         range: query.payload.range,
         timeZone: query.payload.timeZone,
         now: now(),
+        filterWhere: metricFilterWhere(metric, query.payload),
         scopeWhere: tenantId === undefined ? {} : { tenantId },
       });
     },

package/packages/bundled-features/src/metrics/filters.ts

@@ -0,0 +1,100 @@
+import { extractTableInfo, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import type { MetricDefinition, MetricFilterResolver } from "./types.js";
+
+export const RESERVED_PAYLOAD_KEYS: readonly string[] = ["range", "timeZone", "tenantId"];
+
+// Dashboard select options always send strings.
+const NUMERIC_STRING = /^-?\d+(\.\d+)?$/;
+const MAX_FILTER_STRING_LENGTH = 200;
+const NUMERIC_PG_TYPES: ReadonlySet<string> = new Set([
+  "integer",
+  "int4",
+  "smallint",
+  "int2",
+  "bigint",
+  "serial",
+  "bigserial",
+  "double precision",
+]);
+
+export type FilterValueKind = "uuid" | "number" | "string";
+
+/** Undefined = the column type cannot be filtered by a payload value without risking a Postgres cast error. */
+export function filterValueKindOf(pgType: string | undefined): FilterValueKind | undefined {
+  if (pgType === undefined) return undefined;
+  if (pgType === "uuid") return "uuid";
+  if (pgType === "text") return "string";
+  if (NUMERIC_PG_TYPES.has(pgType) || pgType.startsWith("numeric")) return "number";
+  return undefined;
+}
+
+export type MetricFilterEntry = {
+  readonly payloadKey: string;
+  readonly column: string;
+  readonly resolver?: MetricFilterResolver;
+};
+
+export function metricFilterEntries(metric: MetricDefinition): readonly MetricFilterEntry[] {
+  return Object.entries(metric.filters ?? {}).map(([payloadKey, spec]) =>
+    typeof spec === "string"
+      ? { payloadKey, column: spec }
+      : { payloadKey, column: spec.column, resolver: spec },
+  );
+}
+
+function filterValueSchema(kind: FilterValueKind): z.ZodType {
+  if (kind === "uuid") return z.uuid();
+  if (kind === "number")
+    return z.union([z.number(), z.string().regex(NUMERIC_STRING).transform(Number)]);
+  return z.string().min(1).max(MAX_FILTER_STRING_LENGTH);
+}
+
+/** "" and null mean "no filter" (the dashboard's "(all)" option). */
+export function metricFilterPayloadShape(metric: MetricDefinition): Record<string, z.ZodType> {
+  const info = extractTableInfo(metric.source);
+  const shape: Record<string, z.ZodType> = {};
+  for (const { payloadKey, column, resolver } of metricFilterEntries(metric)) {
+    const kind =
+      resolver !== undefined
+        ? (resolver.valueKind ?? "string")
+        : filterValueKindOf(info.pgTypeOf(info.columnOf(column)));
+    if (kind === undefined) continue;
+    shape[payloadKey] = z.union([z.literal(""), z.null(), filterValueSchema(kind)]).optional();
+  }
+  return shape;
+}
+
+function activeFilterValue(payload: Readonly<Record<string, unknown>>, key: string): unknown {
+  const value = payload[key];
+  return value === undefined || value === null || value === "" ? undefined : value;
+}
+
+/** Column-equality filters only; resolver filters need resolveMetricFilterWhere. */
+export function metricFilterWhere(
+  metric: MetricDefinition,
+  payload: Readonly<Record<string, unknown>>,
+): WhereObject {
+  const where: WhereObject = {};
+  for (const { payloadKey, column, resolver } of metricFilterEntries(metric)) {
+    const value = activeFilterValue(payload, payloadKey);
+    if (resolver === undefined && value !== undefined) where[column] = value;
+  }
+  return where;
+}
+
+export async function resolveMetricFilterWhere(
+  metric: MetricDefinition,
+  payload: Readonly<Record<string, unknown>>,
+  ctx: HandlerContext,
+): Promise<WhereObject> {
+  const where = metricFilterWhere(metric, payload);
+  for (const { payloadKey, column, resolver } of metricFilterEntries(metric)) {
+    const value = activeFilterValue(payload, payloadKey);
+    if (resolver === undefined || (typeof value !== "string" && typeof value !== "number"))
+      continue;
+    where[column] = await resolver.resolve(value, ctx);
+  }
+  return where;
+}

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

@@ -24,6 +24,7 @@ export { METRICS_I18N } from "./i18n.js";
 export {
   defineMetric,
   type MetricDefinition,
+  type MetricFilterResolver,
   type MetricPoint,
   type MetricResult,
   type MetricRow,

package/packages/bundled-features/src/metrics/types.ts

@@ -1,4 +1,5 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import type {
   AggregateMeasure,
   AggregateTimeBucket,
@@ -8,6 +9,17 @@ import type { WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
 import type { Temporal } from "temporal-polyfill";
 import type { MetricRange, MetricScope } from "./constants.js";
 
+/** Maps a payload value (e.g. a folder id) to the values `column` may have (e.g. the folder and its subfolders' loan ids). Runs with the tenant handler context, so reads stay tenant-scoped; the result only narrows. An empty result yields no rows. */
+export type MetricFilterResolver = {
+  readonly column: string;
+  readonly resolve: (
+    value: string | number,
+    ctx: HandlerContext,
+  ) => Promise<readonly (string | number)[]>;
+  /** Type of the payload value, not of `column`. Default "string". */
+  readonly valueKind?: "uuid" | "number" | "string";
+};
+
 export type MetricDefinition = {
   readonly id: string;
   readonly description: string;
@@ -16,6 +28,8 @@ export type MetricDefinition = {
   readonly requires?: string;
   readonly measure: AggregateMeasure;
   readonly where?: WhereObject;
+  /** Payload key → source column (equality) or a resolver (IN). e.g. `{ folderId: "folderId" }`. Narrows the result only; the tenant scope is always applied on top and never replaced. Resolvers need a metric without scope "system". */
+  readonly filters?: Readonly<Record<string, string | MetricFilterResolver>>;
   /** timestamptz column; without it the metric is a snapshot with no window. */
   readonly timeField?: string;
   /** Fixed window, ignores the payload range. */

package/packages/bundled-features/src/metrics/validate.ts

@@ -1,8 +1,10 @@
 import { extractTableInfo, isTimestamptzType } from "@cosmicdrift/kumiko-framework/bun-db";
 import { METRIC_RANGES } from "./constants.js";
+import { filterValueKindOf, metricFilterEntries, RESERVED_PAYLOAD_KEYS } from "./filters.js";
 import type { MetricDefinition } from "./types.js";
 
 const KEBAB_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const FILTER_PAYLOAD_KEY = /^[a-z][a-zA-Z0-9]*$/;
 const TENANT_ID_FIELD = "tenantId";
 
 export function metricHasTenantColumn(metric: MetricDefinition): boolean {
@@ -32,6 +34,7 @@ function validateMetric(metric: MetricDefinition): void {
 
   const info = extractTableInfo(metric.source);
   validateColumns(metric, info, fail);
+  validateFilters(metric, info, fail);
   validateTimeSettings(metric, info, fail);
   validateShape(metric, fail);
   if (metric.scopes.includes("tenant") && !metricHasTenantColumn(metric)) {
@@ -50,6 +53,37 @@ function validateColumns(metric: MetricDefinition, info: TableInfo, fail: Fail):
   if (metric.timeField !== undefined) requireColumn(metric.timeField, "timeField");
 }
 
+function validateFilters(metric: MetricDefinition, info: TableInfo, fail: Fail): void {
+  const baseWhereColumns = new Set(Object.keys(metric.where ?? {}).map((f) => info.columnOf(f)));
+  for (const { payloadKey, column: field, resolver } of metricFilterEntries(metric)) {
+    if (resolver !== undefined && metric.scopes.includes("system")) {
+      fail(
+        `filter "${payloadKey}" uses a resolver, which runs with the tenant context and cannot be combined with scope "system"`,
+      );
+    }
+    if (!FILTER_PAYLOAD_KEY.test(payloadKey)) {
+      fail(`has filter key "${payloadKey}" that is not a camelCase identifier`);
+    }
+    if (RESERVED_PAYLOAD_KEYS.includes(payloadKey)) {
+      fail(`has filter key "${payloadKey}" that is reserved by the metric payload`);
+    }
+    if (!info.hasColumn(field))
+      fail(`filter "${payloadKey}" column "${field}" is not a column of ${info.name}`);
+    const column = info.columnOf(field);
+    if (column === info.columnOf(TENANT_ID_FIELD)) {
+      fail(`filter "${payloadKey}" targets the tenant column, which only the scope may set`);
+    }
+    if (baseWhereColumns.has(column)) {
+      fail(`filter "${payloadKey}" column "${field}" is already fixed by the metric where`);
+    }
+    if (filterValueKindOf(info.pgTypeOf(column)) === undefined) {
+      fail(
+        `filter "${payloadKey}" column "${field}" has type ${info.pgTypeOf(column)}, only uuid, text and numeric columns can be filtered`,
+      );
+    }
+  }
+}
+
 function validateTimeSettings(metric: MetricDefinition, info: TableInfo, fail: Fail): void {
   const { timeField } = metric;
   if (timeField === undefined) {

package/packages/bundled-features/src/renderer-simple/simple-renderer.ts

@@ -117,21 +117,35 @@ function renderBrandingHeader(
   return `<div style="margin:0 0 24px;padding:0 0 16px;border-bottom:3px solid ${escapeHtmlAttr(primaryColor)}">${logo}</div>`;
 }
 
-function renderBrandingFooter(
-  branding: MailBranding | undefined,
+type ResolvedBrandingFooter = {
+  readonly footerText: string | undefined;
+  readonly links: readonly { readonly label: string; readonly url: string }[];
+};
+
+function resolveBrandingFooter(
+  branding: MailBranding,
   locale: string | undefined,
-): string {
-  if (!branding) return "";
+): ResolvedBrandingFooter {
   const pick = (value: LocalizedText | undefined): string | undefined =>
     resolveLocalized(value, locale, branding.defaultLocale);
   const links = (branding.footerLinks ?? []).flatMap((link) => {
     const url = pick(link.url);
     if (url === undefined || !isHttpUrl(url)) return [];
-    return [
-      `<a href="${escapeHtmlAttr(url)}" style="color:#999">${escapeHtml(pick(link.label) ?? "")}</a>`,
-    ];
+    return [{ label: pick(link.label) ?? "", url }];
   });
-  const footerText = pick(branding.footerText);
+  return { footerText: pick(branding.footerText), links };
+}
+
+function renderBrandingFooter(
+  branding: MailBranding | undefined,
+  locale: string | undefined,
+): string {
+  if (!branding) return "";
+  const { footerText, links: resolvedLinks } = resolveBrandingFooter(branding, locale);
+  const links = resolvedLinks.map(
+    (link) =>
+      `<a href="${escapeHtmlAttr(link.url)}" style="color:#999">${escapeHtml(link.label)}</a>`,
+  );
   const footerPartsHtml = [footerText ? escapeHtml(footerText) : "", links.join(" · ")].filter(
     (part) => part !== "",
   );
@@ -140,6 +154,18 @@ function renderBrandingFooter(
   return `<p style="margin:16px 0 0;color:#999;font-size:12px">${footerHtml}</p>`;
 }
 
+function brandingFooterLines(
+  branding: MailBranding | undefined,
+  locale: string | undefined,
+): readonly string[] {
+  if (!branding) return [];
+  const { footerText, links } = resolveBrandingFooter(branding, locale);
+  return [
+    ...(footerText ? [footerText] : []),
+    ...links.map((link) => (link.label ? `${link.label}: ${link.url}` : link.url)),
+  ];
+}
+
 type Section =
   | { readonly text: string }
   | { readonly heading: string }
@@ -156,6 +182,29 @@ type EmailTemplateData = {
   readonly body?: string;
 };
 
+function templateContent(variables: Readonly<Record<string, unknown>>): {
+  readonly header: string | undefined;
+  readonly sections: readonly Section[] | undefined;
+  readonly footer: string | undefined;
+} {
+  const data = variables as EmailTemplateData; // @cast-boundary render-helper
+  // Without structured fields, title + body become the header and a single text section.
+  return {
+    header: data.header ?? data.title,
+    sections: data.sections ?? (data.body ? [{ text: data.body }] : undefined),
+    footer: data.footer,
+  };
+}
+
+// Markdown stays as written: its source is already readable plain text.
+function sectionText(section: Section): string {
+  if ("text" in section) return section.text;
+  if ("heading" in section) return section.heading;
+  if ("markdown" in section) return section.markdown;
+  if ("button" in section) return `${section.button.label}: ${section.button.url}`;
+  return "";
+}
+
 function renderSection(section: Section, primaryColor: string): string {
   if ("text" in section) {
     return `<p style="margin:0 0 16px;color:#333;font-size:14px;line-height:1.5">${escapeHtml(section.text)}</p>`;
@@ -183,11 +232,7 @@ export function createSimpleRenderer(branding?: MailBranding): NotificationRende
     name: "simple",
 
     async render(input) {
-      const data = input.variables as EmailTemplateData; // @cast-boundary render-helper
-
-      // Fallback: if no structured fields, use title + body as header + single text section
-      const header = data.header ?? data.title;
-      const sections = data.sections ?? (data.body ? [{ text: data.body }] : undefined);
+      const { header, sections, footer } = templateContent(input.variables);
 
       const parts: string[] = [];
       parts.push('<!DOCTYPE html><html><body style="margin:0;padding:0;font-family:sans-serif">');
@@ -206,9 +251,9 @@ export function createSimpleRenderer(branding?: MailBranding): NotificationRende
         }
       }
 
-      if (data.footer) {
+      if (footer) {
         parts.push(
-          `<p style="margin:24px 0 0;color:#999;font-size:12px;border-top:1px solid #eee;padding-top:16px">${escapeHtml(data.footer)}</p>`,
+          `<p style="margin:24px 0 0;color:#999;font-size:12px;border-top:1px solid #eee;padding-top:16px">${escapeHtml(footer)}</p>`,
         );
       }
 
@@ -216,6 +261,14 @@ export function createSimpleRenderer(branding?: MailBranding): NotificationRende
       parts.push("</div></body></html>");
       return parts.join("");
     },
+
+    async renderText(input) {
+      const { header, sections, footer } = templateContent(input.variables);
+      const brandingFooter = brandingFooterLines(branding, input.locale).join("\n");
+      return [header, ...(sections ?? []).map(sectionText), footer, brandingFooter]
+        .filter((block): block is string => block !== undefined && block !== "")
+        .join("\n\n");
+    },
   };
 }
 

package/packages/bundled-features/src/user-data-rights/email-templates.ts

@@ -44,6 +44,7 @@ registerMailTranslations("en", GDPR_MAIL_EN);
 export type RenderedEmail = {
   readonly subject: string;
   readonly html: string;
+  readonly text: string;
 };
 
 export type RenderExportReadyEmailArgs = {
@@ -89,7 +90,13 @@ export function renderExportReadyEmail(args: RenderExportReadyEmailArgs): Render
     <p style="margin: 0 0 24px;">${renderButton({ url: args.downloadUrl, label: t(locale, "gdpr.mail.exportReady.button") })}</p>
     <p style="margin: 0 0 8px; font-size: 13px; color: #555;">${escapeHtml(t(locale, "gdpr.mail.exportReady.expiry", { when: formatTimestamp(args.expiresAt) }))}</p>
     ${renderFallbackUrl({ url: args.downloadUrl, label: t(locale, "gdpr.mail.fallbackUrl") })}`;
-  return { subject, html: renderShell({ title: subject, bodyHtml: wrapCell(body), locale }) };
+  const text = plainTextBody([
+    t(locale, "gdpr.mail.greeting"),
+    t(locale, "gdpr.mail.exportReady.intro", { app }),
+    `${t(locale, "gdpr.mail.exportReady.button")}: ${args.downloadUrl}`,
+    t(locale, "gdpr.mail.exportReady.expiry", { when: formatTimestamp(args.expiresAt) }),
+  ]);
+  return { subject, html: renderShell({ title: subject, bodyHtml: wrapCell(body), locale }), text };
 }
 
 export function renderExportFailedEmail(args: RenderExportFailedEmailArgs): RenderedEmail {
@@ -99,7 +106,11 @@ export function renderExportFailedEmail(args: RenderExportFailedEmailArgs): Rend
   const body = `
     <p style="margin: 0 0 16px; font-size: 16px;">${escapeHtml(t(locale, "gdpr.mail.greeting"))}</p>
     <p style="margin: 0; font-size: 14px; line-height: 1.5;">${escapeHtml(t(locale, "gdpr.mail.exportFailed.intro", { app }))}</p>`;
-  return { subject, html: renderShell({ title: subject, bodyHtml: wrapCell(body), locale }) };
+  const text = plainTextBody([
+    t(locale, "gdpr.mail.greeting"),
+    t(locale, "gdpr.mail.exportFailed.intro", { app }),
+  ]);
+  return { subject, html: renderShell({ title: subject, bodyHtml: wrapCell(body), locale }), text };
 }
 
 export function renderDeletionRequestedEmail(
@@ -113,7 +124,12 @@ export function renderDeletionRequestedEmail(
     <p style="margin: 0 0 16px; font-size: 16px;">${escapeHtml(t(locale, "gdpr.mail.greeting"))}</p>
     <p style="margin: 0 0 16px; font-size: 14px; line-height: 1.5;">${escapeHtml(t(locale, "gdpr.mail.deletionRequested.intro", { app, when }))}</p>
     <p style="margin: 0; font-size: 13px; color: #555;">${escapeHtml(t(locale, "gdpr.mail.deletionRequested.cancel"))}</p>`;
-  return { subject, html: renderShell({ title: subject, bodyHtml: wrapCell(body), locale }) };
+  const text = plainTextBody([
+    t(locale, "gdpr.mail.greeting"),
+    t(locale, "gdpr.mail.deletionRequested.intro", { app, when }),
+    t(locale, "gdpr.mail.deletionRequested.cancel"),
+  ]);
+  return { subject, html: renderShell({ title: subject, bodyHtml: wrapCell(body), locale }), text };
 }
 
 export function renderDeletionExecutedEmail(args: RenderDeletionExecutedEmailArgs): RenderedEmail {
@@ -124,7 +140,15 @@ export function renderDeletionExecutedEmail(args: RenderDeletionExecutedEmailArg
   const body = `
     <p style="margin: 0 0 16px; font-size: 16px;">${escapeHtml(t(locale, "gdpr.mail.greeting"))}</p>
     <p style="margin: 0; font-size: 14px; line-height: 1.5;">${escapeHtml(t(locale, "gdpr.mail.deletionExecuted.intro", { app, when }))}</p>`;
-  return { subject, html: renderShell({ title: subject, bodyHtml: wrapCell(body), locale }) };
+  const text = plainTextBody([
+    t(locale, "gdpr.mail.greeting"),
+    t(locale, "gdpr.mail.deletionExecuted.intro", { app, when }),
+  ]);
+  return { subject, html: renderShell({ title: subject, bodyHtml: wrapCell(body), locale }), text };
+}
+
+function plainTextBody(paragraphs: readonly string[]): string {
+  return paragraphs.join("\n\n");
 }
 
 function wrapCell(bodyHtml: string): string {

package/packages/bundled-features/src/user-data-rights/lib/default-mailers.ts

@@ -57,13 +57,13 @@ export function makeDefaultExportReadyEmail(
 ): SendExportReadyEmailFn {
   return async (args) => {
     const transport = await resolveTransport(args.tenantId);
-    const { subject, html } = renderExportReadyEmail({
+    const { subject, html, text } = renderExportReadyEmail({
       downloadUrl: args.downloadUrl,
       expiresAt: args.expiresAt,
       locale: localeFor(args.userLocale, defaults),
       appName: defaults.appName,
     });
-    await transport.send({ to: args.userEmail, subject, html });
+    await transport.send({ to: args.userEmail, subject, html, text });
   };
 }
 
@@ -73,11 +73,11 @@ export function makeDefaultExportFailedEmail(
 ): SendExportFailedEmailFn {
   return async (args) => {
     const transport = await resolveTransport(args.tenantId);
-    const { subject, html } = renderExportFailedEmail({
+    const { subject, html, text } = renderExportFailedEmail({
       locale: localeFor(args.userLocale, defaults),
       appName: defaults.appName,
     });
-    await transport.send({ to: args.userEmail, subject, html });
+    await transport.send({ to: args.userEmail, subject, html, text });
   };
 }
 
@@ -87,12 +87,12 @@ export function makeDefaultDeletionRequestedEmail(
 ): SendDeletionRequestedEmailFn {
   return async (args) => {
     const transport = await resolveTransport(args.tenantId);
-    const { subject, html } = renderDeletionRequestedEmail({
+    const { subject, html, text } = renderDeletionRequestedEmail({
       gracePeriodEnd: args.gracePeriodEnd,
       locale: localeFor(args.userLocale, defaults),
       appName: defaults.appName,
     });
-    await transport.send({ to: args.userEmail, subject, html });
+    await transport.send({ to: args.userEmail, subject, html, text });
   };
 }
 
@@ -110,11 +110,11 @@ export function makeDefaultDeletionExecutedEmail(
       return;
     }
     const transport = await resolveTransport(tenantId);
-    const { subject, html } = renderDeletionExecutedEmail({
+    const { subject, html, text } = renderDeletionExecutedEmail({
       executedAt: args.executedAt,
       locale: localeFor(args.userLocale, defaults),
       appName: defaults.appName,
     });
-    await transport.send({ to: args.userEmail, subject, html });
+    await transport.send({ to: args.userEmail, subject, html, text });
   };
 }