@cosmicdrift/kumiko-samples 0.361.0 → 0.363.0

package/packages/bundled-features/src/billing-foundation/consumer-protection/confirmation-mail.ts

@@ -1,6 +1,6 @@
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { CheckoutConsentRecordedPayload } from "../events.js";
-import { CONSENT_TEXTS, type ConsentLocale, resolveConsentLocale } from "./consent-text.js";
+import { type ConsentLocale, resolveConsentLocale } from "./consent-text.js";
 
 // Inline de/en like the consent texts: the confirmation repeats the legal
 // wording the buyer agreed to, so it cannot follow the en-only i18n convention.
@@ -22,7 +22,7 @@ type ConfirmationLabels = {
   readonly every: string;
 };
 
-const LABELS: Readonly<Record<ConsentLocale, ConfirmationLabels>> = {
+export const CONFIRMATION_LABELS: Readonly<Record<ConsentLocale, ConfirmationLabels>> = {
   de: {
     subject: "Vertragsbestätigung",
     intro:
@@ -71,19 +71,17 @@ const LABELS: Readonly<Record<ConsentLocale, ConfirmationLabels>> = {
   },
 };
 
-export type ContractConfirmationSection =
-  | { readonly text: string }
-  | { readonly heading: string }
-  | { readonly markdown: string };
+type TextRow = { readonly text: string };
 
-export type ContractConfirmationContent = {
-  readonly subject: string;
-  readonly header: string;
-  readonly sections: readonly ContractConfirmationSection[];
-  readonly footer: string;
+/** Variables of the contract confirmation template. */
+export type ContractConfirmationVariables = {
+  readonly contractLines: readonly TextRow[];
+  readonly consentGivenAt: string;
+  readonly termsParagraphs: readonly TextRow[];
+  readonly operatorEmail: string;
 };
 
-export type RenderContractConfirmationArgs = {
+export type ContractConfirmationArgs = {
   readonly consent: CheckoutConsentRecordedPayload;
   readonly timeZone: string;
   /** Translated plan name; falls back to the raw tier. */
@@ -99,7 +97,7 @@ export type RenderContractConfirmationArgs = {
 };
 
 function formatPrice(consent: CheckoutConsentRecordedPayload, locale: ConsentLocale): string {
-  const labels = LABELS[locale];
+  const labels = CONFIRMATION_LABELS[locale];
   if (consent.unitAmount === null || consent.currency === null) return "-";
   let amount: string;
   try {
@@ -140,45 +138,41 @@ function formatDate(iso: string, locale: ConsentLocale, timeZone: string): strin
   }).format(epochMilliseconds);
 }
 
-/** Structured mail content (header/sections/footer) for the email channel's
- *  renderer; the renderer owns HTML escaping, this only builds plain text. */
-export function renderContractConfirmation(
-  args: RenderContractConfirmationArgs,
-): ContractConfirmationContent {
+// The mail template only knows plain text variables, so the Markdown terms
+// become one row per paragraph; heading markers are dropped.
+function termsParagraphsOf(markdown: string): readonly TextRow[] {
+  return markdown
+    .split(/\n\s*\n/)
+    .map((paragraph) => paragraph.replace(/^#{1,6}\s+/gm, "").trim())
+    .filter((paragraph) => paragraph.length > 0)
+    .map((text) => ({ text }));
+}
+
+export function contractConfirmationVariables(
+  args: ContractConfirmationArgs,
+): ContractConfirmationVariables {
   const locale = resolveConsentLocale(args.consent.locale);
-  const labels = LABELS[locale];
-  const texts = CONSENT_TEXTS[locale];
-  const { consent } = args;
+  const labels = CONFIRMATION_LABELS[locale];
+  const { consent, timeZone } = args;
 
-  const { timeZone } = args;
   const subjectLine =
     consent.mode === "payment"
       ? `${labels.item}: ${args.itemLabel ?? labels.oneOffPayment}`
       : `${labels.plan}: ${args.tierLabel ?? consent.tier ?? labels.oneOffPayment}`;
-  const contractLines = [
-    subjectLine,
-    `${labels.price}: ${formatPrice(consent, locale)}`,
-    `${labels.contractStart}: ${formatDate(args.contractStartIso, locale, timeZone)}`,
-    ...(args.currentPeriodEndIso !== undefined
-      ? [`${labels.currentPeriodEnd}: ${formatDate(args.currentPeriodEndIso, locale, timeZone)}`]
-      : []),
-  ];
   const vatNote = args.vatNote[locale] ?? args.vatNote[resolveConsentLocale()];
 
   return {
-    subject: labels.subject,
-    header: labels.subject,
-    sections: [
-      { text: labels.intro },
-      ...contractLines.map((text) => ({ text })),
-      ...(vatNote !== undefined ? [{ text: vatNote }] : []),
-      { heading: labels.consentHeading },
-      { text: texts.earlyPerformance },
-      { text: texts.withdrawalLoss },
-      { text: `${labels.consentGivenAt}: ${formatDate(args.consentGivenAtIso, locale, timeZone)}` },
-      { heading: labels.termsHeading },
-      { markdown: args.termsContent },
-    ],
-    footer: `${labels.contact} ${args.operatorEmail}`,
+    contractLines: [
+      subjectLine,
+      `${labels.price}: ${formatPrice(consent, locale)}`,
+      `${labels.contractStart}: ${formatDate(args.contractStartIso, locale, timeZone)}`,
+      ...(args.currentPeriodEndIso !== undefined
+        ? [`${labels.currentPeriodEnd}: ${formatDate(args.currentPeriodEndIso, locale, timeZone)}`]
+        : []),
+      ...(vatNote !== undefined ? [vatNote] : []),
+    ].map((text) => ({ text })),
+    consentGivenAt: formatDate(args.consentGivenAtIso, locale, timeZone),
+    termsParagraphs: termsParagraphsOf(args.termsContent),
+    operatorEmail: args.operatorEmail,
   };
 }

package/packages/bundled-features/src/billing-foundation/consumer-protection/issue-confirmation.ts

@@ -27,7 +27,7 @@ import {
   SUBSCRIPTION_AGGREGATE_TYPE,
 } from "../events.js";
 import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.js";
-import { renderContractConfirmation } from "./confirmation-mail.js";
+import { contractConfirmationVariables } from "./confirmation-mail.js";
 import { resolveConsentLocale } from "./consent-text.js";
 
 export const issueContractConfirmationSchema = z
@@ -185,7 +185,7 @@ export function createIssueContractConfirmationHandler(
           : undefined;
 
       const issuedAtIso = options.now().toString();
-      const content = renderContractConfirmation({
+      const variables = contractConfirmationVariables({
         consent,
         timeZone: pickTimeZone(recipient.data.timezone, ctx.tz.tenant),
         ...(tierLabel !== undefined && { tierLabel }),
@@ -220,7 +220,7 @@ export function createIssueContractConfirmationHandler(
 
       await ctx.notify(CONTRACT_CONFIRMATION_NOTIFICATION_TYPE, {
         route: { email: recipient.data.email },
-        data: content,
+        data: variables,
         locale,
         priority: "critical",
       });

package/packages/bundled-features/src/billing-foundation/consumer-protection/mail-notifications.ts

@@ -0,0 +1,115 @@
+import {
+  type FeatureRegistrar,
+  type NotificationLocalizedTemplate,
+  type TemplateVariables,
+  templateVariable,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { mailHeading, mailParagraph, mailRepeatedRows } from "../../shared/index.js";
+import { CONFIRMATION_LABELS } from "./confirmation-mail.js";
+import { CONSENT_LOCALES, CONSENT_TEXTS, type ConsentLocale } from "./consent-text.js";
+import { TERMINATION_TEXTS } from "./termination-texts.js";
+
+// Slot syntax for the translated texts: `{name}` becomes a template variable.
+const OPERATOR_EMAIL_SLOT = "{operatorEmail}";
+
+const textRows = (): TemplateVariables[string] =>
+  templateVariable.list({ text: templateVariable.text({ required: true }) }, { required: true });
+
+export const TERMINATION_RECEIPT_VARIABLES: TemplateVariables = {
+  subject: templateVariable.text({ required: true }),
+  receivedAt: templateVariable.text({ required: true }),
+  requestId: templateVariable.text({ required: true }),
+  details: textRows(),
+  operatorEmail: templateVariable.text({ required: true }),
+};
+
+export const OPERATOR_NOTICE_VARIABLES: TemplateVariables = {
+  subject: templateVariable.text({ required: true }),
+  lines: textRows(),
+  operatorEmail: templateVariable.text({ required: true }),
+};
+
+export const CONTRACT_CONFIRMATION_VARIABLES: TemplateVariables = {
+  contractLines: textRows(),
+  consentGivenAt: templateVariable.text({ required: true }),
+  termsParagraphs: textRows(),
+  operatorEmail: templateVariable.text({ required: true }),
+};
+
+function perLocale(
+  build: (locale: ConsentLocale) => { body: string; subject: string },
+): NotificationLocalizedTemplate {
+  return Object.fromEntries(
+    CONSENT_LOCALES.map((locale) => {
+      const { body, subject } = build(locale);
+      return [locale, { body, meta: { subject, category: "transactional" as const } }];
+    }),
+  );
+}
+
+export function terminationReceiptTemplate(): NotificationLocalizedTemplate {
+  return perLocale((locale) => {
+    const texts = TERMINATION_TEXTS[locale];
+    return {
+      subject: "{{subject}}",
+      body: [
+        mailParagraph(texts.receiptGreeting),
+        mailParagraph(texts.receiptIntro),
+        mailParagraph(`${texts.receivedAt}: {receivedAt}`),
+        mailParagraph(`${texts.requestId}: {requestId}`),
+        mailRepeatedRows("details", "text"),
+        mailParagraph(texts.receiptNextSteps),
+        mailParagraph(texts.receiptRevoke(OPERATOR_EMAIL_SLOT)),
+        mailParagraph(`${texts.contact} {operatorEmail}`),
+      ].join(""),
+    };
+  });
+}
+
+export function operatorNoticeTemplate(): NotificationLocalizedTemplate {
+  return perLocale((locale) => ({
+    subject: "{{subject}}",
+    body: [
+      mailParagraph(TERMINATION_TEXTS[locale].operatorIntro),
+      mailRepeatedRows("lines", "text"),
+      mailParagraph("{operatorEmail}"),
+    ].join(""),
+  }));
+}
+
+export function contractConfirmationTemplate(): NotificationLocalizedTemplate {
+  return perLocale((locale) => {
+    const labels = CONFIRMATION_LABELS[locale];
+    const consent = CONSENT_TEXTS[locale];
+    return {
+      subject: labels.subject,
+      body: [
+        mailParagraph(labels.intro),
+        mailRepeatedRows("contractLines", "text"),
+        mailHeading(labels.consentHeading),
+        mailParagraph(consent.earlyPerformance),
+        mailParagraph(consent.withdrawalLoss),
+        mailParagraph(`${labels.consentGivenAt}: {consentGivenAt}`),
+        mailHeading(labels.termsHeading),
+        mailRepeatedRows("termsParagraphs", "text"),
+        mailParagraph(`${labels.contact} {operatorEmail}`),
+      ].join(""),
+    };
+  });
+}
+
+// The registered notification names are the tail of the QN types in constants.ts.
+export function registerConsumerProtectionMails(r: FeatureRegistrar): void {
+  r.notification("contract-confirmation", {
+    variables: CONTRACT_CONFIRMATION_VARIABLES,
+    localizedTemplate: contractConfirmationTemplate,
+  });
+  r.notification("contract-termination-receipt", {
+    variables: TERMINATION_RECEIPT_VARIABLES,
+    localizedTemplate: terminationReceiptTemplate,
+  });
+  r.notification("contract-termination-operator-notice", {
+    variables: OPERATOR_NOTICE_VARIABLES,
+    localizedTemplate: operatorNoticeTemplate,
+  });
+}

package/packages/bundled-features/src/billing-foundation/consumer-protection/register-consent.ts

@@ -13,6 +13,7 @@ import {
 } from "../events.js";
 import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.js";
 import { createIssueContractConfirmationHandler } from "./issue-confirmation.js";
+import { registerConsumerProtectionMails } from "./mail-notifications.js";
 import { registerContractTermination } from "./register-termination.js";
 
 type ConfirmationTrigger = {
@@ -46,6 +47,7 @@ export function registerConsumerProtection(
   consumerProtection: ConsumerProtectionOptions,
 ): void {
   r.requires("template-resolver", "delivery", "user", "tenant");
+  registerConsumerProtectionMails(r);
   registerContractTermination(r, options, consumerProtection);
   r.defineEvent(CHECKOUT_CONSENT_RECORDED_EVENT_SHORT, checkoutConsentRecordedPayloadSchema, {
     piiFields: "none",

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-mail.ts

@@ -7,11 +7,22 @@ import type {
 import type { ConsentLocale } from "./consent-text.js";
 import { type OperatorNoticeReason, TERMINATION_TEXTS } from "./termination-texts.js";
 
-export type TerminationMailContent = {
+type TextRow = { readonly text: string };
+
+/** Variables of the termination receipt template. */
+export type TerminationReceiptVariables = {
   readonly subject: string;
-  readonly header: string;
-  readonly sections: readonly { readonly text: string }[];
-  readonly footer: string;
+  readonly receivedAt: string;
+  readonly requestId: string;
+  readonly details: readonly TextRow[];
+  readonly operatorEmail: string;
+};
+
+/** Variables of the operator notice template. */
+export type OperatorNoticeVariables = {
+  readonly subject: string;
+  readonly lines: readonly TextRow[];
+  readonly operatorEmail: string;
 };
 
 /** What the declarant entered; the only input of the receipt. */
@@ -53,7 +64,7 @@ export function formatReceivedAt(iso: string, locale: ConsentLocale): string {
 function declarationLines(
   declaration: OperatorNoticeDeclaration,
   locale: ConsentLocale,
-): readonly { readonly text: string }[] {
+): readonly TextRow[] {
   const texts = TERMINATION_TEXTS[locale];
   const lines = [
     `${texts.declarationType}: ${texts.declarationTypeLabel[declaration.declarationType]}`,
@@ -68,7 +79,7 @@ function declarationLines(
   return lines.map((text) => ({ text }));
 }
 
-export type RenderTerminationReceiptArgs = {
+export type TerminationReceiptArgs = {
   readonly locale: ConsentLocale;
   readonly requestId: string;
   readonly receivedAtIso: string;
@@ -78,28 +89,20 @@ export type RenderTerminationReceiptArgs = {
 
 /** Built from the declarant's own input only: the content must not depend on
  *  whether (or how) the declaration matched a contract. */
-export function renderTerminationReceipt(
-  args: RenderTerminationReceiptArgs,
-): TerminationMailContent {
+export function terminationReceiptVariables(
+  args: TerminationReceiptArgs,
+): TerminationReceiptVariables {
   const texts = TERMINATION_TEXTS[args.locale];
-  const subject = texts.receiptSubject[args.declaration.declarationType];
   return {
-    subject,
-    header: subject,
-    sections: [
-      { text: texts.receiptGreeting },
-      { text: texts.receiptIntro },
-      { text: `${texts.receivedAt}: ${formatReceivedAt(args.receivedAtIso, args.locale)}` },
-      { text: `${texts.requestId}: ${args.requestId}` },
-      ...declarationLines(args.declaration, args.locale),
-      { text: texts.receiptNextSteps },
-      { text: texts.receiptRevoke(args.operatorEmail) },
-    ],
-    footer: `${texts.contact} ${args.operatorEmail}`,
+    subject: texts.receiptSubject[args.declaration.declarationType],
+    receivedAt: formatReceivedAt(args.receivedAtIso, args.locale),
+    requestId: args.requestId,
+    details: declarationLines(args.declaration, args.locale),
+    operatorEmail: args.operatorEmail,
   };
 }
 
-export type RenderOperatorNoticeArgs = {
+export type OperatorNoticeArgs = {
   readonly locale: ConsentLocale;
   readonly requestId: string;
   readonly receivedAtIso: string;
@@ -111,14 +114,11 @@ export type RenderOperatorNoticeArgs = {
   readonly operatorEmail: string;
 };
 
-export function renderOperatorNotice(args: RenderOperatorNoticeArgs): TerminationMailContent {
+export function operatorNoticeVariables(args: OperatorNoticeArgs): OperatorNoticeVariables {
   const texts = TERMINATION_TEXTS[args.locale];
-  const subject = texts.operatorSubject[args.declaration.declarationType];
   return {
-    subject,
-    header: subject,
-    sections: [
-      { text: texts.operatorIntro },
+    subject: texts.operatorSubject[args.declaration.declarationType],
+    lines: [
       ...args.reasons.map((reason) => ({
         text: `${texts.noticeReasons}: ${texts.operatorReasons[reason]}`,
       })),
@@ -131,6 +131,6 @@ export function renderOperatorNotice(args: RenderOperatorNoticeArgs): Terminatio
         : []),
       ...declarationLines(args.declaration, args.locale),
     ],
-    footer: args.operatorEmail,
+    operatorEmail: args.operatorEmail,
   };
 }

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-notify.ts

@@ -4,7 +4,7 @@ import { CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE } from "../constants.js
 import type { ProviderCancelOutcome } from "../events.js";
 import type { ConsumerProtectionOptions } from "../types.js";
 import type { ConsentLocale } from "./consent-text.js";
-import { type OperatorNoticeDeclaration, renderOperatorNotice } from "./termination-mail.js";
+import { type OperatorNoticeDeclaration, operatorNoticeVariables } from "./termination-mail.js";
 import type { OperatorNoticeReason } from "./termination-texts.js";
 
 export type OperatorNoticePlan = {
@@ -35,7 +35,7 @@ export async function notifyOperator(
 ): Promise<void> {
   await requireNotify(ctx)(CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE, {
     route: { email: consumerProtection.operatorEmail },
-    data: renderOperatorNotice({
+    data: operatorNoticeVariables({
       ...plan,
       operatorEmail: consumerProtection.operatorEmail,
     }),

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-pages.ts

@@ -3,6 +3,7 @@
 
 import { type AnonymousExtraRoute, getSessionCookies } from "@cosmicdrift/kumiko-framework/api";
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import type { Context } from "hono";
 import { getCookie } from "hono/cookie";
 import {
@@ -98,10 +99,6 @@ function htmlResponse(
   );
 }
 
-function isOneOf<T extends string>(options: readonly T[], value: string): value is T {
-  return (options as readonly string[]).includes(value);
-}
-
 async function readForm(c: Context): Promise<{ step: string; values: FormValues }> {
   const body = await c.req.parseBody();
   const text = (key: string): string => {

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-request.ts

@@ -31,7 +31,7 @@ import {
 import { purchaseRolesOf } from "../plan-catalog.js";
 import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.js";
 import { resolveConsentLocale } from "./consent-text.js";
-import { renderTerminationReceipt, type TerminationDeclaration } from "./termination-mail.js";
+import { type TerminationDeclaration, terminationReceiptVariables } from "./termination-mail.js";
 import { notifyOperator, type OperatorNoticePlan, requireNotify } from "./termination-notify.js";
 import type { RecordContractTerminationResult } from "./termination-record.js";
 import type { OperatorNoticeReason } from "./termination-texts.js";
@@ -111,7 +111,7 @@ async function sendTerminationMails(
 ): Promise<void> {
   await requireNotify(ctx)(CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, {
     route: { email: plan.declaration.email },
-    data: renderTerminationReceipt({
+    data: terminationReceiptVariables({
       locale: plan.locale,
       requestId: plan.requestId,
       receivedAtIso: plan.receivedAtIso,

package/packages/bundled-features/src/billing-foundation/get-subscription-for-tenant.ts

@@ -40,10 +40,10 @@ export async function getSubscriptionForTenant(
   if (!row) return null;
   const piiKms = configuredPiiSubjectKms();
   const decrypted = piiKms
-    ? await decryptPiiFieldValues(row as Record<string, unknown>, SUBSCRIPTION_PII_FIELDS, piiKms, {
+    ? await decryptPiiFieldValues(row, SUBSCRIPTION_PII_FIELDS, piiKms, {
         requestId: `billing-foundation:get-subscription:${tenantId}`,
       })
-    : (row as Record<string, unknown>);
+    : row;
   // @cast-boundary db-row — drizzle-row carries column-as-unknown
   return {
     tier: decrypted["tier"] as string,

package/packages/bundled-features/src/billing-foundation/handlers/create-portal-session.write.ts

@@ -52,15 +52,10 @@ export function createPortalSessionHandler(options: BillingFoundationOptions): W
       }
       const piiKms = configuredPiiSubjectKms();
       const decrypted = piiKms
-        ? await decryptPiiFieldValues(
-            row as Record<string, unknown>,
-            SUBSCRIPTION_PII_FIELDS,
-            piiKms,
-            {
-              requestId: `billing-foundation:create-portal-session:${tenantId}`,
-            },
-          )
-        : (row as Record<string, unknown>);
+        ? await decryptPiiFieldValues(row, SUBSCRIPTION_PII_FIELDS, piiKms, {
+            requestId: `billing-foundation:create-portal-session:${tenantId}`,
+          })
+        : row;
       const providerName = row["providerName"] as string; // @cast-boundary db-row
       const providerCustomerId = decrypted["providerCustomerId"] as string; // @cast-boundary db-row
 

package/packages/bundled-features/src/billing-foundation/handlers/list-subscriptions.query.ts

@@ -27,7 +27,7 @@ export const listSubscriptionsQuery: QueryHandlerDef = {
     if (!piiKms) return { rows };
     const decryptedRows = await Promise.all(
       rows.map((row) =>
-        decryptPiiFieldValues(row as Record<string, unknown>, SUBSCRIPTION_PII_FIELDS, piiKms, {
+        decryptPiiFieldValues(row, SUBSCRIPTION_PII_FIELDS, piiKms, {
           requestId: `billing-foundation:list-subscriptions:${ctx.user.tenantId}`,
         }),
       ),

package/packages/bundled-features/src/billing-foundation/handlers/process-event.write.ts

@@ -167,8 +167,8 @@ export async function appendSubscriptionEvent(
   // ---------------------------------------------------------------
   const eventPayload: SubscriptionEventPayload = {
     providerName: payload.providerName,
-    providerCustomerId: encryptedFields["providerCustomerId"] as string,
-    providerSubscriptionId: encryptedFields["providerSubscriptionId"] as string,
+    providerCustomerId: encryptedFields.providerCustomerId,
+    providerSubscriptionId: encryptedFields.providerSubscriptionId,
     status: payload.status,
     tier: payload.tier,
     currentPeriodEndIso: payload.currentPeriodEndIso,

package/packages/bundled-features/src/billing-foundation/handlers/process-payment-event.write.ts

@@ -95,7 +95,7 @@ export const processPaymentEventHandler: WriteHandlerDef = {
     // ---------------------------------------------------------------
     const eventPayload: PaymentEventPayload = {
       providerName: payload.providerName,
-      providerCustomerId: encryptedFields["providerCustomerId"] as string,
+      providerCustomerId: encryptedFields.providerCustomerId,
       priceId: payload.priceId,
       ...(payload.consentId !== undefined && { consentId: payload.consentId }),
     };

package/packages/bundled-features/src/billing-foundation/subscription-tier-sync.ts

@@ -14,6 +14,7 @@ import type {
   SignatureExtraRouteDeps,
 } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { subscriptionAggregateId } from "./aggregate-id.js";
 import { SubscriptionFoundationQueries, SubscriptionStatuses } from "./constants.js";
 import { createSubscriptionWebhookRoute } from "./webhook-handler.js";
@@ -52,12 +53,8 @@ export function effectiveTierFromSubscription<TTier extends string>(
 // (handler bug, or the handlerQn resolving to a non-list query) fails
 // loudly instead of crashing on `.find` against `undefined`.
 function asRows(result: unknown): ReadonlyArray<Record<string, unknown>> {
-  if (
-    typeof result === "object" &&
-    result !== null &&
-    Array.isArray((result as { rows?: unknown }).rows)
-  ) {
-    return (result as { rows: ReadonlyArray<Record<string, unknown>> }).rows;
+  if (isPlainObject(result) && Array.isArray(result["rows"])) {
+    return result["rows"];
   }
   throw new Error("expected a { rows: [...] } list-query result");
 }

package/packages/bundled-features/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -7,6 +7,7 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { subscriptionsProjectionTable } from "../../billing-foundation/index.js";
 import type { CapLimitContext } from "../../cap-counter/index.js";
@@ -79,7 +80,7 @@ async function resolveLimitsByTenantAndCap(
 }
 
 function isSortableField(field: string): field is SortableField {
-  return (SORTABLE_FIELDS as readonly string[]).includes(field);
+  return isOneOf(SORTABLE_FIELDS, field);
 }
 
 // tier is a plain string with no defined ordering — lt/gt have no meaning

package/packages/bundled-features/src/cap-overview/web/cap-usage-cell.tsx

@@ -1,17 +1,19 @@
 // @runtime client
+
 import type { ColumnRendererProps } from "@cosmicdrift/kumiko-renderer";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import type { ReactNode } from "react";
 import type { CapUsage } from "../types.js";
 import { CapUsageBar } from "./cap-usage-bar.js";
 
 function isCapUsage(value: unknown): value is CapUsage {
-  if (typeof value !== "object" || value === null) return false;
-  const used = (value as { used?: unknown }).used;
-  const limit = (value as { limit?: unknown }).limit;
+  if (!isPlainObject(value)) return false;
+  const used = value["used"];
+  const limit = value["limit"];
   return (
     (typeof used === "number" || used === null) &&
     (typeof limit === "number" || limit === null) &&
-    typeof (value as { fraction?: unknown }).fraction === "number"
+    typeof value["fraction"] === "number"
   );
 }
 

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

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "A notification without a mail template fails on the email channel",
+    "detail": "The renderer option of createChannelEmailFeature is removed. A notification routed to the email channel without template + meta fails its delivery permanently with \"has no mail template, declare template + meta on r.notification\". r.notification declares no channels, so this is not checked at boot; an app's own mail tests over the inmemory transport catch it.",
+    "migration": "Drop the renderer option. Declare template + meta (or localizedTemplate) and variables on every r.notification that reaches the email channel, or accept that its email delivery fails. Run the app's notification tests after the bump: every email notification without a template now fails there."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Email channel sends rendered-pdf attachments",
+    "detail": "The channel resolves rendered-pdf entries from notify data next to file entries; without a locale the message locale is used. A render failure fails the send job, so the retry runs it again."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Email channel sends file attachments and inline cid images",
+    "detail": "EmailMessage.attachments is sent through the SMTP transport (inline images with Content-ID). notify data.attachments with kind file entries are resolved through the file store; the PII guard rejects ciphertext file names."
+  },
   {
     "version": "0.350.0",
     "type": "improvement",