@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

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

@@ -1,27 +1,38 @@
-// Default send*Email-Callbacks fuer die GDPR-Notifications, backed by einem
-// mail-transport (mail-foundation). Damit muss eine App keinen Callback-Code
-// schreiben: sie mountet mail-foundation + einen mail-transport-* und setzt
-// fuer Export-Mails appExportDownloadUrl — fertig. Uebergibt sie eigene
-// send*Email-Opts, greifen diese Defaults nicht (Opt-Override im feature.ts).
+// Default send*Email callbacks for the GDPR notifications. The app writes no
+// callback code: it mounts delivery + channel-email (+ the template stack) and
+// sets appExportDownloadUrl for export mails. Own send*Email options win over
+// these defaults (opt-override in feature.ts).
 //
-// Jeder Callback rendert das Template (email-templates.ts) und versendet ueber
-// den per-Tenant aufgeloesten EmailTransport. `resolveTransport` kommt im Job-
-// Lane aus makeTenantMailTransportResolver, im Request-Lane direkt aus
-// createTransportForTenant(ctx, ...).
+// Export-ready/-failed and deletion-requested go through ctx.notify addressed
+// to the user, so delivery resolves the address and the attempt row carries
+// the recipientId the forget path erases. Deletion-executed cannot: the user
+// is gone by then, and an attempt row written after the erasure would be new
+// personal data. It renders the seeded template and sends over the tenant's
+// mail transport, with no delivery log.
 
 import type { EmailTransport } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import { MAIL_TRANSPORT_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
-import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
-import { hasMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type {
+  ConfigAccessor,
+  NotifyFn,
+  NotifyOptions,
+  Registry,
+  TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { hasMailTranslations, mailT } from "@cosmicdrift/kumiko-framework/i18n";
+import { DELIVERY_CHANNEL_EXTENSION } from "../../delivery/index.js";
 import {
+  collectRendererPlugins,
+  createRendererFoundationApi,
+} from "../../renderer-foundation/index.js";
+import {
+  formatGdprMailTimestamp,
   type GdprMailLocale,
   normalizeGdprMailLocale,
-  renderDeletionExecutedEmail,
-  renderDeletionRequestedEmail,
-  renderExportFailedEmail,
-  renderExportReadyEmail,
 } from "../email-templates.js";
 import type { SendDeletionRequestedEmailFn } from "../handlers/request-deletion.write.js";
+import { GdprMailNotificationTypes, gdprMailTemplateLocale } from "../mail-notifications.js";
 import type { SendExportFailedEmailFn, SendExportReadyEmailFn } from "../run-export-jobs.js";
 import type { SendDeletionExecutedEmailFn } from "../run-forget-cleanup.js";
 
@@ -30,74 +41,116 @@ export type GdprMailDefaults = {
   readonly appName?: string;
 };
 
-// mail-foundation ist eine Soft-Dep von user-data-rights. Die Default-Mailer
-// greifen nur wenn mindestens ein mail-transport-* registriert ist — sonst
-// kann ohnehin nichts versendet werden und die App bleibt beim bisherigen
-// "kein Callback → keine Email"-Verhalten.
+// The notify-based defaults need the delivery pipeline with an email channel.
+export function isGdprMailDeliveryAvailable(registry: Registry): boolean {
+  return registry
+    .getExtensionUsages(DELIVERY_CHANNEL_EXTENSION)
+    .some((usage) => usage.entityName === "email");
+}
+
 export function isMailTransportAvailable(registry: Registry): boolean {
   return registry.getExtensionUsages(MAIL_TRANSPORT_EXTENSION).length > 0;
 }
 
-type TransportResolver = (tenantId: string) => Promise<EmailTransport>;
+export function isMailRendererAvailable(registry: Registry): boolean {
+  return collectRendererPlugins(registry).some((plugin) => plugin.kinds.includes("mail"));
+}
+
+export type NotifyForTenant = (tenantId: TenantId) => NotifyFn;
 
 // Per-recipient locale wins (user.locale); mailDefaults.locale is the fallback
-// for unknown/unsupported user.locale values; the template itself defaults to en.
-function localeFor(
+// for unknown/unsupported user.locale values; a locale without a template for
+// this notification falls back to en.
+function mailLocaleFor(
+  notificationType: string,
   userLocale: string | null,
   defaults: GdprMailDefaults,
-): GdprMailLocale | undefined {
+): string {
   const user = normalizeGdprMailLocale(userLocale);
-  if (user !== undefined && hasMailTranslations(user)) return user;
-  return defaults.locale;
+  const preferred = user !== undefined && hasMailTranslations(user) ? user : defaults.locale;
+  return gdprMailTemplateLocale(notificationType, preferred ?? "en");
+}
+
+function appNameFor(locale: string, defaults: GdprMailDefaults): string {
+  return defaults.appName ?? mailT(locale, "gdpr.mail.appNameDefault");
+}
+
+// Delivery failures come back as results, not throws; the callers' best-effort
+// handling only sees them if they throw.
+async function notifyImmediately(
+  notify: NotifyFn,
+  notificationType: string,
+  options: NotifyOptions,
+): Promise<void> {
+  const result = await notify(notificationType, { ...options, immediate: true });
+  const failed = result.deliveries.find((delivery) => delivery.status === "failed");
+  if (failed) {
+    throw new Error(`${notificationType} delivery failed: ${failed.error ?? "unknown"}`);
+  }
 }
 
 export function makeDefaultExportReadyEmail(
-  resolveTransport: TransportResolver,
+  notifyFor: NotifyForTenant,
   defaults: GdprMailDefaults = {},
 ): SendExportReadyEmailFn {
   return async (args) => {
-    const transport = await resolveTransport(args.tenantId);
-    const { subject, html, text } = renderExportReadyEmail({
-      downloadUrl: args.downloadUrl,
-      expiresAt: args.expiresAt,
-      locale: localeFor(args.userLocale, defaults),
-      appName: defaults.appName,
+    const type = GdprMailNotificationTypes.exportReady;
+    const locale = mailLocaleFor(type, args.userLocale, defaults);
+    // immediate: the plain magic-link token must not land in a delivery job payload.
+    await notifyImmediately(notifyFor(args.tenantId), type, {
+      to: args.userId,
+      locale,
+      data: {
+        appName: appNameFor(locale, defaults),
+        actionUrl: args.downloadUrl,
+        validUntil: formatGdprMailTimestamp(args.expiresAt),
+      },
     });
-    await transport.send({ to: args.userEmail, subject, html, text });
   };
 }
 
 export function makeDefaultExportFailedEmail(
-  resolveTransport: TransportResolver,
+  notifyFor: NotifyForTenant,
   defaults: GdprMailDefaults = {},
 ): SendExportFailedEmailFn {
   return async (args) => {
-    const transport = await resolveTransport(args.tenantId);
-    const { subject, html, text } = renderExportFailedEmail({
-      locale: localeFor(args.userLocale, defaults),
-      appName: defaults.appName,
+    const type = GdprMailNotificationTypes.exportFailed;
+    const locale = mailLocaleFor(type, args.userLocale, defaults);
+    await notifyImmediately(notifyFor(args.tenantId), type, {
+      to: args.userId,
+      locale,
+      data: { appName: appNameFor(locale, defaults) },
     });
-    await transport.send({ to: args.userEmail, subject, html, text });
   };
 }
 
 export function makeDefaultDeletionRequestedEmail(
-  resolveTransport: TransportResolver,
+  notify: NotifyFn,
   defaults: GdprMailDefaults = {},
 ): SendDeletionRequestedEmailFn {
   return async (args) => {
-    const transport = await resolveTransport(args.tenantId);
-    const { subject, html, text } = renderDeletionRequestedEmail({
-      gracePeriodEnd: args.gracePeriodEnd,
-      locale: localeFor(args.userLocale, defaults),
-      appName: defaults.appName,
+    const type = GdprMailNotificationTypes.deletionRequested;
+    const locale = mailLocaleFor(type, args.userLocale, defaults);
+    await notify(type, {
+      to: args.userId,
+      locale,
+      data: {
+        appName: appNameFor(locale, defaults),
+        deletionDate: formatGdprMailTimestamp(args.gracePeriodEnd),
+      },
     });
-    await transport.send({ to: args.userEmail, subject, html, text });
   };
 }
 
+export type DeletionExecutedMailDeps = {
+  readonly registry: Registry;
+  readonly db: DbConnection;
+  readonly resolveTransport: (tenantId: string) => Promise<EmailTransport>;
+  readonly configFor: (tenantId: TenantId) => ConfigAccessor | undefined;
+};
+
 export function makeDefaultDeletionExecutedEmail(
-  resolveTransport: TransportResolver,
+  deps: DeletionExecutedMailDeps,
   defaults: GdprMailDefaults = {},
 ): SendDeletionExecutedEmailFn {
   return async (args) => {
@@ -109,12 +162,40 @@ export function makeDefaultDeletionExecutedEmail(
       // skip: orphan user has no tenant whose transport could send the mail
       return;
     }
-    const transport = await resolveTransport(tenantId);
-    const { subject, html, text } = renderDeletionExecutedEmail({
-      executedAt: args.executedAt,
-      locale: localeFor(args.userLocale, defaults),
-      appName: defaults.appName,
+    const type = GdprMailNotificationTypes.deletionExecuted;
+    const locale = mailLocaleFor(type, args.userLocale, defaults);
+    const plugin = createRendererFoundationApi(
+      collectRendererPlugins(deps.registry),
+    ).createRendererForTenant({ tenantId, kind: "mail" });
+    const config = deps.configFor(tenantId);
+    const rendered = await plugin.render(
+      {
+        kind: "mail",
+        payload: {
+          slug: type,
+          locale,
+          variables: {
+            appName: appNameFor(locale, defaults),
+            executedAt: formatGdprMailTimestamp(args.executedAt),
+          },
+        },
+      },
+      {
+        db: deps.db,
+        registry: deps.registry,
+        tenantId,
+        ...(config !== undefined && { config }),
+      },
+    );
+    if (rendered.kind !== "mail") {
+      throw new Error(`deletion-executed mail: renderer answered with kind "${rendered.kind}"`);
+    }
+    const transport = await deps.resolveTransport(tenantId);
+    await transport.send({
+      to: args.userEmail,
+      subject: rendered.subject,
+      html: rendered.html,
+      text: rendered.text,
     });
-    await transport.send({ to: args.userEmail, subject, html, text });
   };
 }

package/packages/bundled-features/src/user-data-rights/lib/update-user-lifecycle.ts

@@ -92,12 +92,12 @@ export type BackfillResult = {
 };
 
 export async function backfillUserLifecycleEvents(conn: DbRunner): Promise<BackfillResult> {
-  const rows = (await selectMany(conn, userTable, {})) as Array<{
+  const rows = await selectMany<{
     id: string;
     status: string;
     gracePeriodEnd: unknown;
     pendingDeletionRequestId: unknown;
-  }>;
+  }>(conn, userTable, {});
 
   let backfilled = 0;
   const failed: Array<{ id: string; error: string }> = [];

package/packages/bundled-features/src/user-data-rights/mail-notifications.ts

@@ -0,0 +1,157 @@
+import {
+  type FeatureRegistrar,
+  type NotificationLocalizedTemplate,
+  QnTypes,
+  qn,
+  type TemplateVariables,
+  templateVariable,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  hasMailTranslationKey,
+  listMailLocales,
+  mailT,
+  resolveMailLocale,
+} from "@cosmicdrift/kumiko-framework/i18n";
+import { escapeHtml } from "@cosmicdrift/kumiko-headless";
+import { mailParagraph } from "../shared/index.js";
+import { USER_DATA_RIGHTS_FEATURE } from "./constants.js";
+
+const ALL_GDPR_MAIL_KINDS = [
+  "exportReady",
+  "exportFailed",
+  "deletionRequested",
+  "deletionExecuted",
+] as const;
+
+export type GdprMailKind = (typeof ALL_GDPR_MAIL_KINDS)[number];
+
+export const GDPR_MAIL_KINDS: Readonly<
+  Record<GdprMailKind, { readonly name: string; readonly translationKey: string }>
+> = {
+  exportReady: { name: "export-ready", translationKey: "exportReady" },
+  exportFailed: { name: "export-failed", translationKey: "exportFailed" },
+  deletionRequested: { name: "deletion-requested", translationKey: "deletionRequested" },
+  deletionExecuted: { name: "deletion-executed", translationKey: "deletionExecuted" },
+};
+
+export const GdprMailNotificationTypes: Readonly<Record<GdprMailKind, string>> = {
+  exportReady: gdprMailType("exportReady"),
+  exportFailed: gdprMailType("exportFailed"),
+  deletionRequested: gdprMailType("deletionRequested"),
+  deletionExecuted: gdprMailType("deletionExecuted"),
+};
+
+function gdprMailType(kind: GdprMailKind): string {
+  return qn(USER_DATA_RIGHTS_FEATURE, QnTypes.notify, GDPR_MAIL_KINDS[kind].name);
+}
+
+function subjectKey(kind: GdprMailKind): string {
+  return `gdpr.mail.${GDPR_MAIL_KINDS[kind].translationKey}.subject`;
+}
+
+const SUBJECT_KEY_BY_TYPE: ReadonlyMap<string, string> = new Map(
+  ALL_GDPR_MAIL_KINDS.map((kind) => [GdprMailNotificationTypes[kind], subjectKey(kind)]),
+);
+
+// A registered locale whose bundle lacks the subject key has no template (see
+// gdprMailLocalizedTemplate); the renderer has no locale fallback, so the
+// sender must pick a locale that has one or the mail would not go out at all.
+export function gdprMailTemplateLocale(notificationType: string, requestedLocale: string): string {
+  const locale = resolveMailLocale(requestedLocale);
+  const key = SUBJECT_KEY_BY_TYPE.get(notificationType);
+  return key !== undefined && hasMailTranslationKey(locale, key) ? locale : "en";
+}
+
+const appName = () => templateVariable.text({ required: true });
+
+export const GDPR_MAIL_VARIABLES: Readonly<Record<GdprMailKind, TemplateVariables>> = {
+  exportReady: {
+    appName: appName(),
+    actionUrl: templateVariable.link({ required: true }),
+    validUntil: templateVariable.text({ required: true }),
+  },
+  exportFailed: { appName: appName() },
+  deletionRequested: {
+    appName: appName(),
+    deletionDate: templateVariable.text({ required: true }),
+  },
+  deletionExecuted: { appName: appName(), executedAt: templateVariable.text({ required: true }) },
+};
+
+// Translation placeholder -> template variable per kind.
+const PLACEHOLDER_SLOTS: Readonly<Record<GdprMailKind, Readonly<Record<string, string>>>> = {
+  exportReady: { app: "{appName}", when: "{validUntil}" },
+  exportFailed: { app: "{appName}" },
+  deletionRequested: { app: "{appName}", when: "{deletionDate}" },
+  deletionExecuted: { app: "{appName}", when: "{executedAt}" },
+};
+
+function paragraph(kind: GdprMailKind, locale: string, part: string): string {
+  const { translationKey } = GDPR_MAIL_KINDS[kind];
+  return mailParagraph(
+    mailT(locale, `gdpr.mail.${translationKey}.${part}`, PLACEHOLDER_SLOTS[kind]),
+  );
+}
+
+function greeting(locale: string): string {
+  return mailParagraph(mailT(locale, "gdpr.mail.greeting"));
+}
+
+function mailBody(kind: GdprMailKind, locale: string): string {
+  switch (kind) {
+    case "exportReady":
+      return [
+        greeting(locale),
+        paragraph(kind, locale, "intro"),
+        `<p><a data-button href="{{actionUrl}}">${escapeHtml(mailT(locale, "gdpr.mail.exportReady.button"))}</a></p>`,
+        paragraph(kind, locale, "expiry"),
+      ].join("");
+    case "exportFailed":
+      return [greeting(locale), paragraph(kind, locale, "intro")].join("");
+    case "deletionRequested":
+      return [
+        greeting(locale),
+        paragraph(kind, locale, "intro"),
+        paragraph(kind, locale, "cancel"),
+      ].join("");
+    case "deletionExecuted":
+      return [greeting(locale), paragraph(kind, locale, "intro")].join("");
+  }
+}
+
+// Evaluated when the registry is built, after every locale feature has
+// registered its mail translations. English always ships; another locale only
+// gets a template when it has its own subject, so a missing translation never
+// silently becomes an English mail in that locale's slot.
+export function gdprMailLocalizedTemplate(kind: GdprMailKind): () => NotificationLocalizedTemplate {
+  const kindSubjectKey = subjectKey(kind);
+  return () => {
+    const locales = [
+      "en",
+      ...listMailLocales().filter(
+        (locale) => locale !== "en" && hasMailTranslationKey(locale, kindSubjectKey),
+      ),
+    ];
+    return Object.fromEntries(
+      locales.map((locale) => [
+        locale,
+        {
+          body: mailBody(kind, locale),
+          meta: {
+            subject: mailT(locale, kindSubjectKey, { app: "{{appName}}" }),
+            category: "transactional" as const,
+          },
+        },
+      ]),
+    );
+  };
+}
+
+export function registerGdprMails(r: FeatureRegistrar): void {
+  for (const kind of ALL_GDPR_MAIL_KINDS) {
+    r.notification(GDPR_MAIL_KINDS[kind].name, {
+      variables: GDPR_MAIL_VARIABLES[kind],
+      localizedTemplate: gdprMailLocalizedTemplate(kind),
+    });
+  }
+}

package/packages/bundled-features/src/user-data-rights/run-forget-cleanup.ts

@@ -254,7 +254,7 @@ export async function runForgetCleanup(
 
   // Step 1: Find users with expired grace period.
   const dueUsers = await selectUsersDueForForgetCleanup(
-    db as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+    db,
     USER_STATUS.DeletionRequested,
     now.toString(),
   );

package/packages/bundled-features/src/user-data-rights/web/privacy-center-screen.tsx

@@ -17,6 +17,7 @@ import {
   useTranslation,
 } from "@cosmicdrift/kumiko-renderer";
 import { postWithDownload } from "@cosmicdrift/kumiko-renderer-web";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { type ReactNode, useEffect, useState } from "react";
 import {
   EXPORT_JOB_STATUS,
@@ -49,7 +50,7 @@ type SectionStatus =
 // Dispatcher-Failures tragen i18nKey nur wenn der Handler einen setzt —
 // Boundary-Read mit generischem Fallback.
 function failureKey(error: unknown): string {
-  const key = (error as { i18nKey?: unknown } | null)?.i18nKey; // @cast-boundary dispatcher-error
+  const key = propertyOf(error, "i18nKey");
   return typeof key === "string" ? key : "userDataRights.privacyCenter.errors.generic";
 }
 

package/packages/bundled-features/src/user-profile/web/profile-screen.tsx

@@ -13,6 +13,7 @@ import {
   usePrimitives,
   useTranslation,
 } from "@cosmicdrift/kumiko-renderer";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { type ReactNode, useState } from "react";
 import { AuthHandlers } from "../../auth-email-password/constants.js";
 import { requestEmailVerification } from "../../auth-email-password/web/index.js";
@@ -27,7 +28,7 @@ type SectionStatus =
 // Dispatcher failures carry an i18nKey only when the handler sets one —
 // boundary read with a generic fallback.
 function failureKey(error: unknown): string {
-  const key = (error as { i18nKey?: unknown } | null)?.i18nKey; // @cast-boundary dispatcher-error
+  const key = propertyOf(error, "i18nKey");
   return typeof key === "string" ? key : "profile.errors.generic";
 }
 

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

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "Waitlist confirmation and admin notice use template variables",
+    "detail": "The confirmation and admin-notice mails are r.notification declarations (waitlist:notify:confirmation, waitlist:notify:admin-notice) with variables and localized templates. The notify data is the variable object; the confirmation wording is computed in code and passed as variables. The admin notice subject is the submitter name.",
+    "migration": "Update delivery preferences and tests that referenced the old types or read the sections data. An app that mounts it without includeBundled needs template-resolver, renderer-foundation and @cosmicdrift/kumiko-renderer-mail-html at boot (composeRendererStack() from dev-server mounts all of them), plus a delivery with the channel-email feature; apps without the template tables need a schema migration (`kumiko schema generate`)."
+  },
   {
     "version": "0.342.0",
     "type": "improvement",

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

@@ -12,6 +12,13 @@ import { rejectHandler } from "./handlers/reject.write.js";
 import { createSubmitHandler } from "./handlers/submit.write.js";
 import { WAITLIST_I18N } from "./i18n.js";
 import { adminAccess } from "./lib.js";
+import {
+  WAITLIST_ADMIN_NOTICE_RECORD,
+  WAITLIST_ADMIN_NOTICE_VARIABLES,
+  WAITLIST_CONFIRMATION_VARIABLES,
+  waitlistAdminNoticeTemplate,
+  waitlistConfirmationTemplate,
+} from "./mail.js";
 import type { WaitlistOptions } from "./options.js";
 import { waitlistListScreen } from "./screens.js";
 import { waitlistEntryDeleteHook, waitlistEntryExportHook } from "./user-data-hooks.js";
@@ -26,6 +33,16 @@ export function createWaitlistFeature(opts: WaitlistOptions = {}): FeatureDefini
     r.requires("tenant", "auth-email-password", "user-data-rights");
     r.translations({ keys: WAITLIST_I18N });
 
+    r.notification("confirmation", {
+      variables: WAITLIST_CONFIRMATION_VARIABLES,
+      localizedTemplate: waitlistConfirmationTemplate,
+    });
+    r.notification("admin-notice", {
+      variables: WAITLIST_ADMIN_NOTICE_VARIABLES,
+      record: WAITLIST_ADMIN_NOTICE_RECORD,
+      localizedTemplate: waitlistAdminNoticeTemplate,
+    });
+
     r.entity("waitlistEntry", waitlistEntryEntity);
     r.writeHandler(createSubmitHandler(opts));
     r.writeHandler(createInviteHandler(opts.invite));

package/packages/bundled-features/src/waitlist/handlers/submit.write.ts

@@ -10,10 +10,10 @@ import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { WAITLIST_NOTIFICATION_TYPES, WAITLIST_STATUS } from "../constants.js";
 import { normalizeEmail, platformActor, waitlistDb, waitlistExecutor } from "../lib.js";
 import {
-  renderWaitlistAdminNoticeEmail,
-  renderWaitlistConfirmationEmail,
   resolveWaitlistAdminMailLocale,
   resolveWaitlistMailLocale,
+  waitlistAdminNoticeVariables,
+  waitlistConfirmationVariables,
 } from "../mail.js";
 import {
   DEFAULT_SUBMIT_EMAIL_RATE_LIMITS,
@@ -130,7 +130,7 @@ export function createSubmitHandler(opts: WaitlistOptions) {
       await sendBestEffort(ctx, "confirmation", (notify) =>
         notify(WAITLIST_NOTIFICATION_TYPES.confirmation, {
           route: { email },
-          data: renderWaitlistConfirmationEmail({
+          data: waitlistConfirmationVariables({
             locale: payload.locale,
             appName: opts.appName,
           }),
@@ -145,12 +145,11 @@ export function createSubmitHandler(opts: WaitlistOptions) {
         if (!adminRecipient) return;
         await notify(WAITLIST_NOTIFICATION_TYPES.adminNotice, {
           route: { email: adminRecipient },
-          data: renderWaitlistAdminNoticeEmail({
+          data: waitlistAdminNoticeVariables({
             name: payload.name,
             email,
             company: payload.company,
             message: payload.message,
-            adminLocale: ctx.locale,
           }),
           priority: "normal",
           locale: resolveWaitlistAdminMailLocale(ctx.locale),

package/packages/bundled-features/src/waitlist/mail.ts

@@ -1,4 +1,10 @@
-import type { AuthMailContent } from "../auth-email-password/index.js";
+import {
+  type NotificationLocalizedTemplate,
+  type NotificationRecordMapping,
+  type TemplateVariables,
+  templateVariable,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { mailHeading, mailParagraph, mailRepeatedRows } from "../shared/index.js";
 
 export type WaitlistMailLocale = "en" | "de" | "es";
 
@@ -72,43 +78,88 @@ export function resolveWaitlistMailLocale(locale: string | undefined): WaitlistM
   return isConfirmationLocale(language) ? language : "en";
 }
 
+export const WAITLIST_CONFIRMATION_VARIABLES: TemplateVariables = {
+  subject: templateVariable.text({ required: true }),
+  intro: templateVariable.text({ required: true }),
+  footer: templateVariable.text({ required: true }),
+};
+
+// Only `name` is a plain entry field; the details rows are composed from several fields.
+export const WAITLIST_ADMIN_NOTICE_RECORD: NotificationRecordMapping = {
+  entity: "waitlistEntry",
+  map: { name: "name" },
+};
+
+export const WAITLIST_ADMIN_NOTICE_VARIABLES: TemplateVariables = {
+  name: templateVariable.text({ required: true }),
+  details: templateVariable.list(
+    { text: templateVariable.text({ required: true }) },
+    { required: true },
+  ),
+};
+
+// The app name is optional, so the sentences that mention it are computed in
+// code and handed over as variables; the template keeps heading and structure.
 // The submitter's name stays out: the address is unverified, so any text in
 // this mail could be planted by whoever typed someone else's email.
-export function renderWaitlistConfirmationEmail(args: {
+export function waitlistConfirmationVariables(args: {
   readonly locale: string | undefined;
   readonly appName?: string | undefined;
-}): AuthMailContent {
+}): { readonly subject: string; readonly intro: string; readonly footer: string } {
   const t = CONFIRMATION_STRINGS[resolveWaitlistMailLocale(args.locale)];
   return {
     subject: t.subject(args.appName),
-    header: t.header,
-    sections: [{ text: t.intro(args.appName) }],
+    intro: t.intro(args.appName),
     footer: t.footer(args.appName),
   };
 }
 
+export function waitlistConfirmationTemplate(): NotificationLocalizedTemplate {
+  return Object.fromEntries(
+    Object.entries(CONFIRMATION_STRINGS).map(([locale, t]) => [
+      locale,
+      {
+        body: [mailHeading(t.header), mailParagraph("{intro}"), mailParagraph("{footer}")].join(""),
+        meta: { subject: "{{subject}}", category: "transactional" as const },
+      },
+    ]),
+  );
+}
+
 // Operator-facing, so the entrant's locale does not apply: en/de, en default.
 export function resolveWaitlistAdminMailLocale(adminLocale: string | undefined): "en" | "de" {
   return languageOf(adminLocale) === "de" ? "de" : "en";
 }
 
-export function renderWaitlistAdminNoticeEmail(args: {
+export function waitlistAdminNoticeVariables(args: {
   readonly name: string;
   readonly email: string;
   readonly company: string | undefined;
   readonly message: string | undefined;
-  readonly adminLocale: string | undefined;
-}): AuthMailContent {
-  const t = ADMIN_NOTICE_STRINGS[resolveWaitlistAdminMailLocale(args.adminLocale)];
-  const details = [
-    `${args.name} <${args.email}>`,
-    ...(args.company ? [args.company] : []),
-    ...(args.message ? [args.message] : []),
-  ];
+}): { readonly name: string; readonly details: readonly { readonly text: string }[] } {
   return {
-    subject: t.subject(args.name),
-    header: t.header,
-    sections: [{ text: t.intro }, { text: details.join("\n") }],
-    footer: t.footer,
+    name: args.name,
+    details: [
+      `${args.name} <${args.email}>`,
+      ...(args.company ? [args.company] : []),
+      ...(args.message ? [args.message] : []),
+    ].map((text) => ({ text })),
   };
 }
+
+export function waitlistAdminNoticeTemplate(): NotificationLocalizedTemplate {
+  return Object.fromEntries(
+    Object.entries(ADMIN_NOTICE_STRINGS).map(([locale, t]) => [
+      locale,
+      {
+        body: [
+          mailHeading(t.header),
+          mailParagraph(t.intro),
+          mailRepeatedRows("details", "text"),
+          mailParagraph(t.footer),
+        ].join(""),
+        meta: { subject: t.subject("{{name}}"), category: "transactional" as const },
+      },
+    ]),
+  );
+}