@cosmicdrift/kumiko-samples 0.349.0 → 0.350.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.349.0",
+  "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.349.0",
+  "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/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 });
   };
 }