@cosmicdrift/kumiko-samples 0.343.0 → 0.344.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.343.0",
+  "version": "0.344.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.343.0",
+  "version": "0.344.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/billing-foundation/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.344.0",
+    "type": "breaking",
+    "title": "Consumer-protection gaps - per-locale legal links, gate order, confirmation mail, exports",
+    "detail": "All changes below apply only when `createBillingFoundationFeature` gets `consumerProtection`. Apps without it behave as before.\n`ConsumerProtectionOptions.legalLinks` takes either one `LegalLinkSet` or one set per consent locale (`{ de, en }`, both required). `BillingPlansResult.consumerProtection.legalLinks` is now always `Record<\"de\" | \"en\", LegalLinkSet>`; a single set is returned for both locales. Code that reads `legalLinks.terms` from the billing-plans result must read `legalLinks[locale].terms`. `CheckoutConsentDialog` picks the set for the consent locale.\n`FALLBACK_CONSENT_LOCALE` is now `\"en\"` (was `\"de\"`). A locale other than de/en, or none, resolves to English in `resolveConsentLocale`, the consent gate, the confirmation mail's VAT note and the termination record.\n`create-checkout-session` with consumer protection now checks in this order: provider, billing enabled, redirect origins, price and subscription gates, then the live price (new `UnprocessableError` `price_unavailable` when the provider cannot return it), then the consent, then the provider call. A missing consent no longer hides a disabled provider, an existing subscription or an unknown price. Its payload schema is strict, so unknown fields are rejected. `assertCheckoutAllowed` and `startProviderCheckout` split `openCheckout` in checkout-core.\nNew option `ConsumerProtectionOptions.oneOffItemLabel(ctx, priceId)`: the server resolves the label of a one-off item (for example a credit pack). It is stored on the consent event as `itemLabelKey` / `itemLabelParams` and shown in the confirmation mail as \"Leistung\" / \"Item\". The client cannot set it.\nThe terms text block is read from the system tenant, not from the buyer's tenant, in the consent gate and the confirmation mail. A tenant-owned block with the same slug no longer changes `termsHash` or the mailed text.\nThe confirmation mail shows dates in the recipient's time zone (user zone, else tenant zone, else UTC) with the zone name, renders the terms as Markdown with real headings and shows the translated plan name (`catalog.tierLabelKey`, looked up through the registry i18n, so the key must be qualified with the registering feature; untranslated keys fall back to the raw tier). Its opening sentence starts with a capital letter.\nNew exports: `consentPayloadSchema`, `ConsentPayload`, `OrderItem`, `CONSENT_LOCALES`, `ConsentLocale`, `resolveConsentLocale`, `LegalLinkSet`. The `/web` entry adds `CheckoutConsentDialog`, `CheckoutConsentDialogProps`, `CheckoutConsentPayload`, `CONSENT_TEXT_OUTDATED_CODE`, `resolveConsentLocale`, `ConsentLocale` and `LegalLinkSet`. `CheckoutConsentDialog` `price.count` is optional, and the \"cancel at any time\" note only shows for a recurring price (`price.renewalKey` set).\nThe checkout and cancel dialogs no longer repeat the modal title as a heading, and the cancel-contract button is hidden once a cancellation is scheduled.",
+    "migration": "Only apps that pass consumerProtection are affected. BillingPlansResult.consumerProtection.legalLinks is now keyed by locale (legalLinks.de / legalLinks.en). FALLBACK_CONSENT_LOCALE changed from de to en. create-checkout-session rejects unknown payload fields when consumer protection is on."
+  },
   {
     "version": "0.341.0",
     "type": "improvement",

package/packages/bundled-features/src/billing-foundation/checkout-core.ts

@@ -329,17 +329,27 @@ function assertOneOffPriceAllowed(
   }
 }
 
-/** The one checkout entry-point create-checkout-session and
- *  start-plan-checkout both funnel through. `mode: "payment"` (one-off
- *  top-ups etc.) skips the price/subscription gates entirely — those apply
- *  to recurring subscriptions only. */
-export async function openCheckout(
+type CheckoutCapableProvider = SubscriptionProviderPlugin & {
+  readonly createCheckoutSession: NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>;
+};
+
+function canCreateCheckoutSession(
+  plugin: SubscriptionProviderPlugin,
+): plugin is CheckoutCapableProvider {
+  return plugin.createCheckoutSession !== undefined;
+}
+
+/** All gates that run before a provider checkout call: provider, billing
+ *  enabled, redirect origins, mode gates, foreign provider customer.
+ *  `mode: "payment"` (one-off top-ups etc.) skips the price/subscription
+ *  gates — those apply to recurring subscriptions only. */
+export async function assertCheckoutAllowed(
   ctx: HandlerContext,
   options: OpenCheckoutOptions,
   input: OpenCheckoutInput,
-): Promise<{ readonly url: string; readonly providerName: string }> {
+): Promise<CheckoutCapableProvider> {
   const { plugin } = resolveProviderPlugin(ctx, input.providerName);
-  if (!plugin.createCheckoutSession) {
+  if (!canCreateCheckoutSession(plugin)) {
     throw new Error(
       `subscription-foundation: provider "${input.providerName}" has no createCheckoutSession-method (e.g. Apple-IAP-only providers). Use the provider's native checkout flow.`,
     );
@@ -376,7 +386,14 @@ export async function openCheckout(
       });
     }
   }
+  return plugin;
+}
 
+export async function startProviderCheckout(
+  ctx: HandlerContext,
+  plugin: CheckoutCapableProvider,
+  input: OpenCheckoutInput,
+): Promise<{ readonly url: string; readonly providerName: string }> {
   const result = await plugin.createCheckoutSession(ctx, {
     priceId: input.priceId,
     tenantId: ctx.user.tenantId,
@@ -393,3 +410,14 @@ export async function openCheckout(
   });
   return { url: result.url, providerName: input.providerName };
 }
+
+/** The one checkout entry-point start-plan-checkout, switch-plan and the
+ *  non-consumer-protection create-checkout-session funnel through. */
+export async function openCheckout(
+  ctx: HandlerContext,
+  options: OpenCheckoutOptions,
+  input: OpenCheckoutInput,
+): Promise<{ readonly url: string; readonly providerName: string }> {
+  const plugin = await assertCheckoutAllowed(ctx, options, input);
+  return startProviderCheckout(ctx, plugin, input);
+}

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

@@ -8,6 +8,7 @@ type ConfirmationLabels = {
   readonly subject: string;
   readonly intro: string;
   readonly plan: string;
+  readonly item: string;
   readonly oneOffPayment: string;
   readonly price: string;
   readonly oneOff: string;
@@ -25,8 +26,9 @@ const LABELS: Readonly<Record<ConsentLocale, ConfirmationLabels>> = {
   de: {
     subject: "Vertragsbestätigung",
     intro:
-      "vielen Dank für deine Bestellung. Hiermit bestätigen wir den Vertragsschluss mit folgendem Inhalt.",
+      "Vielen Dank für deine Bestellung. Hiermit bestätigen wir den Vertragsschluss mit folgendem Inhalt.",
     plan: "Tarif",
+    item: "Leistung",
     oneOffPayment: "Einmalzahlung",
     price: "Preis",
     oneOff: "einmalig",
@@ -47,8 +49,9 @@ const LABELS: Readonly<Record<ConsentLocale, ConfirmationLabels>> = {
   en: {
     subject: "Contract confirmation",
     intro:
-      "thank you for your order. We hereby confirm the conclusion of the contract with the following content.",
+      "Thank you for your order. We hereby confirm the conclusion of the contract with the following content.",
     plan: "Plan",
+    item: "Item",
     oneOffPayment: "One-off payment",
     price: "Price",
     oneOff: "one-off",
@@ -68,15 +71,25 @@ const LABELS: Readonly<Record<ConsentLocale, ConfirmationLabels>> = {
   },
 };
 
+export type ContractConfirmationSection =
+  | { readonly text: string }
+  | { readonly heading: string }
+  | { readonly markdown: string };
+
 export type ContractConfirmationContent = {
   readonly subject: string;
   readonly header: string;
-  readonly sections: readonly { readonly text: string }[];
+  readonly sections: readonly ContractConfirmationSection[];
   readonly footer: string;
 };
 
 export type RenderContractConfirmationArgs = {
   readonly consent: CheckoutConsentRecordedPayload;
+  readonly timeZone: string;
+  /** Translated plan name; falls back to the raw tier. */
+  readonly tierLabel?: string;
+  /** Translated purchased item for one-off payments; falls back to the generic label. */
+  readonly itemLabel?: string;
   readonly consentGivenAtIso: string;
   readonly contractStartIso: string;
   readonly currentPeriodEndIso?: string;
@@ -109,7 +122,7 @@ function formatPrice(consent: CheckoutConsentRecordedPayload, locale: ConsentLoc
   return count === 1 ? `${amount} / ${intervalText}` : `${amount}, ${intervalText}`;
 }
 
-function formatDate(iso: string, locale: ConsentLocale): string {
+function formatDate(iso: string, locale: ConsentLocale, timeZone: string): string {
   let epochMilliseconds: number;
   try {
     epochMilliseconds = Temporal.Instant.from(iso).epochMilliseconds;
@@ -117,20 +130,16 @@ function formatDate(iso: string, locale: ConsentLocale): string {
     return iso;
   }
   return new Intl.DateTimeFormat(locale, {
-    dateStyle: "long",
-    timeStyle: "short",
-    timeZone: "UTC",
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+    timeZone,
+    timeZoneName: "short",
   }).format(epochMilliseconds);
 }
 
-function paragraphs(text: string): readonly { readonly text: string }[] {
-  return text
-    .split(/\n{2,}/)
-    .map((part) => part.trim())
-    .filter((part) => part.length > 0)
-    .map((part) => ({ text: part }));
-}
-
 /** 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(
@@ -141,12 +150,17 @@ export function renderContractConfirmation(
   const texts = CONSENT_TEXTS[locale];
   const { consent } = 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 = [
-    `${labels.plan}: ${consent.tier ?? labels.oneOffPayment}`,
+    subjectLine,
     `${labels.price}: ${formatPrice(consent, locale)}`,
-    `${labels.contractStart}: ${formatDate(args.contractStartIso, locale)}`,
+    `${labels.contractStart}: ${formatDate(args.contractStartIso, locale, timeZone)}`,
     ...(args.currentPeriodEndIso !== undefined
-      ? [`${labels.currentPeriodEnd}: ${formatDate(args.currentPeriodEndIso, locale)}`]
+      ? [`${labels.currentPeriodEnd}: ${formatDate(args.currentPeriodEndIso, locale, timeZone)}`]
       : []),
   ];
   const vatNote = args.vatNote[locale] ?? args.vatNote[resolveConsentLocale()];
@@ -158,12 +172,12 @@ export function renderContractConfirmation(
       { text: labels.intro },
       ...contractLines.map((text) => ({ text })),
       ...(vatNote !== undefined ? [{ text: vatNote }] : []),
-      { text: labels.consentHeading },
+      { heading: labels.consentHeading },
       { text: texts.earlyPerformance },
       { text: texts.withdrawalLoss },
-      { text: `${labels.consentGivenAt}: ${formatDate(args.consentGivenAtIso, locale)}` },
-      { text: labels.termsHeading },
-      ...paragraphs(args.termsContent),
+      { text: `${labels.consentGivenAt}: ${formatDate(args.consentGivenAtIso, locale, timeZone)}` },
+      { heading: labels.termsHeading },
+      { markdown: args.termsContent },
     ],
     footer: `${labels.contact} ${args.operatorEmail}`,
   };

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

@@ -2,7 +2,7 @@
 // validate + prepare before the provider call, record only after it succeeded.
 
 import { createHash } from "node:crypto";
-import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { type HandlerContext, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
@@ -45,6 +45,11 @@ export type PreparedConsent = {
   readonly termsTemplateVersion: number;
 };
 
+export type OrderItem = {
+  readonly labelKey: string;
+  readonly params?: Readonly<Record<string, string | number>>;
+};
+
 export type ConsentPriceDetails = {
   readonly tier: string | null;
   readonly priceId: string;
@@ -52,6 +57,7 @@ export type ConsentPriceDetails = {
     ProviderPrice,
     "unitAmount" | "currency" | "interval" | "intervalCount"
   > | null;
+  readonly orderItem?: OrderItem;
 };
 
 export async function prepareConsent(
@@ -78,7 +84,7 @@ export async function prepareConsent(
   let terms: Awaited<ReturnType<typeof resolver.resolveTemplate>>;
   try {
     terms = await resolver.resolveTemplate({
-      tenantId: ctx.user.tenantId,
+      tenantId: SYSTEM_TENANT_ID,
       slug: options.termsTextBlock,
       kind: TEXT_BLOCK_KIND,
       locale,
@@ -136,6 +142,10 @@ export async function recordConsent(
     termsTemplateVersion: prepared.termsTemplateVersion,
     locale: prepared.locale,
     actorUserId: String(ctx.user.id),
+    ...(details.orderItem && {
+      itemLabelKey: details.orderItem.labelKey,
+      ...(details.orderItem.params && { itemLabelParams: details.orderItem.params }),
+    }),
   };
   const tenantId = ctx.user.tenantId;
   const isSubscription = prepared.mode === "subscription";

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

@@ -2,7 +2,7 @@
 // Crypto-free so the browser panel can share the locale rule with the server.
 export const CONSENT_LOCALES = ["de", "en"] as const;
 export type ConsentLocale = (typeof CONSENT_LOCALES)[number];
-export const FALLBACK_CONSENT_LOCALE: ConsentLocale = "de";
+export const FALLBACK_CONSENT_LOCALE: ConsentLocale = "en";
 
 function isConsentLocale(value: string): value is ConsentLocale {
   return CONSENT_LOCALES.some((locale) => locale === value);

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

@@ -5,9 +5,12 @@
 import {
   access,
   createSystemUser,
+  SYSTEM_TENANT_ID,
   type WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { createI18n } from "@cosmicdrift/kumiko-framework/i18n";
+import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
 import { requireTemplateResolver, TEXT_BLOCK_KIND } from "../../template-resolver/index.js";
 import { UserQueries } from "../../user/index.js";
@@ -46,8 +49,19 @@ export type IssueContractConfirmationResult =
 const recipientRowSchema = z.object({
   email: z.string().min(1),
   isDeleted: z.boolean().optional(),
+  timezone: z.string().nullish(),
 });
 
+// createI18n returns the key itself for an unknown key.
+function translatedOrUndefined(translation: string, key: string): string | undefined {
+  return translation === key ? undefined : translation;
+}
+
+function pickTimeZone(userZone: string | null | undefined, tenantZone: string): string {
+  if (userZone && isValidIanaTimeZone(userZone)) return userZone;
+  return isValidIanaTimeZone(tenantZone) ? tenantZone : "UTC";
+}
+
 export function createIssueContractConfirmationHandler(
   options: ResolvedBillingFoundationOptions,
   consumerProtection: ConsumerProtectionOptions,
@@ -143,7 +157,7 @@ export function createIssueContractConfirmationHandler(
 
       const locale = resolveConsentLocale(consent.locale);
       const terms = await requireTemplateResolver(ctx, "billing-foundation").resolveTemplate({
-        tenantId,
+        tenantId: SYSTEM_TENANT_ID,
         slug: consumerProtection.termsTextBlock,
         kind: TEXT_BLOCK_KIND,
         locale,
@@ -154,9 +168,28 @@ export function createIssueContractConfirmationHandler(
         );
       }
 
+      const i18n = createI18n(ctx.registry, { defaultLocale: "en" });
+      const tierLabel =
+        consent.tier !== null && options.catalog
+          ? translatedOrUndefined(
+              i18n.t(options.catalog.tierLabelKey(consent.tier), locale),
+              options.catalog.tierLabelKey(consent.tier),
+            )
+          : undefined;
+      const itemLabel =
+        consent.itemLabelKey !== undefined
+          ? translatedOrUndefined(
+              i18n.t(consent.itemLabelKey, locale, consent.itemLabelParams),
+              consent.itemLabelKey,
+            )
+          : undefined;
+
       const issuedAtIso = options.now().toString();
       const content = renderContractConfirmation({
         consent,
+        timeZone: pickTimeZone(recipient.data.timezone, ctx.tz.tenant),
+        ...(tierLabel !== undefined && { tierLabel }),
+        ...(itemLabel !== undefined && { itemLabel }),
         consentGivenAtIso: consentEvent.createdAt.toString(),
         contractStartIso: issuedAtIso,
         ...(payload.currentPeriodEndIso !== undefined && {

package/packages/bundled-features/src/billing-foundation/events.ts

@@ -138,6 +138,8 @@ export const checkoutConsentRecordedPayloadSchema = z.object({
   termsTemplateVersion: z.number(),
   locale: z.string().min(2).max(35),
   actorUserId: z.string().min(1),
+  itemLabelKey: z.string().min(1).max(200).optional(),
+  itemLabelParams: z.record(z.string(), z.union([z.string().max(100), z.number()])).optional(),
 });
 export type CheckoutConsentRecordedPayload = z.infer<typeof checkoutConsentRecordedPayloadSchema>;
 

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

@@ -11,10 +11,13 @@ import {
   consentTextVersion,
 } from "../consumer-protection/consent-text.js";
 import { buildBillingPlans } from "../plan-catalog.js";
-import type {
-  BillingPlanCatalog,
-  BillingPlansResult,
-  ResolvedBillingFoundationOptions,
+import {
+  type BillingPlanCatalog,
+  type BillingPlansResult,
+  type ConsumerProtectionOptions,
+  isLegalLinkSet,
+  type LegalLinkSet,
+  type ResolvedBillingFoundationOptions,
 } from "../types.js";
 
 const billingPlansSchema = z.object({}).strict();
@@ -41,13 +44,19 @@ export function createBillingPlansQuery(
             de: consentTextView("de"),
             en: consentTextView("en"),
           },
-          legalLinks: consumerProtection.legalLinks,
+          legalLinks: legalLinksPerLocale(consumerProtection.legalLinks),
         },
       };
     },
   };
 }
 
+function legalLinksPerLocale(
+  legalLinks: ConsumerProtectionOptions["legalLinks"],
+): Readonly<Record<(typeof CONSENT_LOCALES)[number], LegalLinkSet>> {
+  return isLegalLinkSet(legalLinks) ? { de: legalLinks, en: legalLinks } : legalLinks;
+}
+
 function consentTextView(locale: (typeof CONSENT_LOCALES)[number]) {
   const { earlyPerformance, withdrawalLoss } = CONSENT_TEXTS[locale];
   return { earlyPerformance, withdrawalLoss, consentTextVersion: consentTextVersion(locale) };

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

@@ -23,8 +23,14 @@
 // hand-picked priceId.
 
 import type { HandlerContext, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { findProviderPlugin, openCheckout } from "../checkout-core.js";
+import {
+  assertCheckoutAllowed,
+  type OpenCheckoutInput,
+  openCheckout,
+  startProviderCheckout,
+} from "../checkout-core.js";
 import {
   type ConsentPayload,
   consentCheckoutFields,
@@ -64,7 +70,7 @@ export function createCheckoutSessionHandler(
 ): WriteHandlerDef {
   const consumerProtection = options.consumerProtection;
   const schema = consumerProtection
-    ? createCheckoutSessionSchema.extend({ consent: consentPayloadSchema.optional() })
+    ? createCheckoutSessionSchema.extend({ consent: consentPayloadSchema.optional() }).strict()
     : createCheckoutSessionSchema;
   return {
     name: "create-checkout-session",
@@ -78,34 +84,43 @@ export function createCheckoutSessionHandler(
       // @cast-boundary engine-payload — dispatcher-zod-validated payload
       const payload = event.payload as CreateCheckoutSessionPayload;
 
-      const mode = payload.mode ?? "subscription";
-      const consent = consumerProtection
-        ? await prepareConsent(ctx, consumerProtection, payload.consent, mode)
-        : undefined;
-
-      const result = await openCheckout(
-        ctx,
-        { baseUrl: options.baseUrl, catalog: options.catalog, now: options.now },
-        {
-          providerName: payload.providerName,
-          priceId: payload.priceId,
-          successUrl: payload.successUrl,
-          cancelUrl: payload.cancelUrl,
-          ...(payload.providerCustomerId && { providerCustomerId: payload.providerCustomerId }),
-          ...(payload.mode && { mode: payload.mode }),
-          ...(consent && consentCheckoutFields(consent)),
-        },
-      );
+      const openOptions = { baseUrl: options.baseUrl, catalog: options.catalog, now: options.now };
+      const checkoutInput: OpenCheckoutInput = {
+        providerName: payload.providerName,
+        priceId: payload.priceId,
+        successUrl: payload.successUrl,
+        cancelUrl: payload.cancelUrl,
+        ...(payload.providerCustomerId && { providerCustomerId: payload.providerCustomerId }),
+        ...(payload.mode && { mode: payload.mode }),
+      };
 
-      if (consent) {
-        const plugin = findProviderPlugin(ctx, payload.providerName)?.plugin;
-        await recordConsent(ctx, consent, {
-          tier: mode === "subscription" ? (plugin?.priceToTier?.[payload.priceId] ?? null) : null,
-          priceId: payload.priceId,
-          price: await lookupPrice(ctx, plugin, payload.priceId),
-        });
+      if (!consumerProtection) {
+        const result = await openCheckout(ctx, openOptions, checkoutInput);
+        return {
+          isSuccess: true as const,
+          data: { url: result.url, providerName: result.providerName },
+        };
       }
 
+      const mode = payload.mode ?? "subscription";
+      const plugin = await assertCheckoutAllowed(ctx, openOptions, checkoutInput);
+      const price = await lookupPrice(ctx, plugin, payload.priceId);
+      const orderItem =
+        mode === "payment"
+          ? await consumerProtection.oneOffItemLabel?.(ctx, payload.priceId)
+          : undefined;
+      const consent = await prepareConsent(ctx, consumerProtection, payload.consent, mode);
+      const result = await startProviderCheckout(ctx, plugin, {
+        ...checkoutInput,
+        ...consentCheckoutFields(consent),
+      });
+      await recordConsent(ctx, consent, {
+        tier: mode === "subscription" ? (plugin.priceToTier?.[payload.priceId] ?? null) : null,
+        priceId: payload.priceId,
+        price,
+        ...(orderItem && { orderItem }),
+      });
+
       return {
         isSuccess: true as const,
         data: { url: result.url, providerName: result.providerName },
@@ -114,18 +129,28 @@ export function createCheckoutSessionHandler(
   };
 }
 
-// A failed price lookup must not lose a consent the buyer already gave at the
-// provider, so it degrades to null price fields.
+// The price is part of the consent record, so it must be known before the
+// buyer is sent to the provider.
 async function lookupPrice(
   ctx: HandlerContext,
-  plugin: SubscriptionProviderPlugin | undefined,
+  plugin: SubscriptionProviderPlugin,
   priceId: string,
-): Promise<ProviderPrice | null> {
-  if (!plugin?.retrievePrices) return null;
+): Promise<ProviderPrice> {
+  let price: ProviderPrice | undefined;
   try {
-    const prices = await plugin.retrievePrices(ctx, [priceId]);
-    return prices.find((p) => p.priceId === priceId) ?? null;
-  } catch {
-    return null;
+    const prices = (await plugin.retrievePrices?.(ctx, [priceId])) ?? [];
+    price = prices.find((p) => p.priceId === priceId);
+  } catch (cause) {
+    throw priceUnavailable(priceId, cause);
   }
+  if (!price) throw priceUnavailable(priceId);
+  return price;
+}
+
+function priceUnavailable(priceId: string, cause?: unknown): UnprocessableError {
+  return new UnprocessableError("price_unavailable", {
+    i18nKey: "billing-foundation.errors.priceUnavailable",
+    message: `billing-foundation: no live price resolved for priceId "${priceId}"`,
+    ...(cause instanceof Error && { cause }),
+  });
 }

package/packages/bundled-features/src/billing-foundation/index.ts

@@ -33,6 +33,16 @@ export {
   type SubscriptionStatus,
   SubscriptionStatuses,
 } from "./constants.js";
+export {
+  type ConsentPayload,
+  consentPayloadSchema,
+  type OrderItem,
+} from "./consumer-protection/consent-gate.js";
+export {
+  CONSENT_LOCALES,
+  type ConsentLocale,
+  resolveConsentLocale,
+} from "./consumer-protection/consent-locale.js";
 export {
   type ContractTerminationRoutesOptions,
   createContractTerminationRoutes,
@@ -79,6 +89,7 @@ export {
   type BillingPlanView,
   type ConsumerProtectionOptions,
   KNOWN_RECURRING_INTERVALS,
+  type LegalLinkSet,
   type PaymentEvent,
   type ProviderPrice,
   type ProviderSubscriptionSnapshot,

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

@@ -37,6 +37,8 @@ import {
   type SubscriptionStatus,
   type TerminationScope,
 } from "./constants.js";
+import type { OrderItem } from "./consumer-protection/consent-gate.js";
+import type { ConsentLocale } from "./consumer-protection/consent-locale.js";
 
 // =============================================================================
 // Normalisierter Webhook-Event
@@ -380,6 +382,18 @@ export type BillingPlanCatalog<TTier extends string = string> = {
   readonly providerName?: string;
 };
 
+export type LegalLinkSet = {
+  readonly terms: string;
+  readonly withdrawal: string;
+  readonly privacy: string;
+};
+
+export function isLegalLinkSet(
+  links: LegalLinkSet | Readonly<Record<ConsentLocale, LegalLinkSet>>,
+): links is LegalLinkSet {
+  return "terms" in links;
+}
+
 /** Consumer-protection consent gate (§ 312j / § 356 BGB style). When set,
  *  `start-plan-checkout` and `create-checkout-session` require a `consent`
  *  payload and record it as an event before the buyer reaches the provider. */
@@ -395,12 +409,16 @@ export type ConsumerProtectionOptions = {
    *  host that resolves none (the platform apex) — the declaration then runs
    *  without a request tenant and finds the contract by the declarant's email. */
   readonly terminationScope?: TerminationScope;
-  /** Root-relative paths or absolute https URLs. */
-  readonly legalLinks: {
-    readonly terms: string;
-    readonly withdrawal: string;
-    readonly privacy: string;
-  };
+  /** Names the item of a one-off payment (mode "payment") for the consent record
+   *  and the confirmation mail; the label key is resolved through the registry
+   *  i18n, so it must be qualified with the registering feature. */
+  readonly oneOffItemLabel?: (
+    ctx: HandlerContext,
+    priceId: string,
+  ) => Promise<OrderItem | undefined>;
+  /** Root-relative paths or absolute https URLs. One set for every locale, or
+   *  one set per consent locale (`de` and `en` required). */
+  readonly legalLinks: LegalLinkSet | Readonly<Record<ConsentLocale, LegalLinkSet>>;
 };
 
 export type BillingFoundationOptions<TTier extends string = string> = {
@@ -472,7 +490,7 @@ export type BillingPlansResult = {
         }
       >
     >;
-    readonly legalLinks: ConsumerProtectionOptions["legalLinks"];
+    readonly legalLinks: Readonly<Record<ConsentLocale, LegalLinkSet>>;
   };
 };
 

package/packages/bundled-features/src/billing-foundation/validate-options.ts

@@ -5,7 +5,13 @@
 
 import * as z from "zod";
 import { isTerminationScope, TERMINATION_SCOPES } from "./constants.js";
-import type { BillingFoundationOptions, ConsumerProtectionOptions } from "./types.js";
+import { CONSENT_LOCALES, type ConsentLocale } from "./consumer-protection/consent-locale.js";
+import {
+  type BillingFoundationOptions,
+  type ConsumerProtectionOptions,
+  isLegalLinkSet,
+  type LegalLinkSet,
+} from "./types.js";
 
 function isRootRelativePath(path: string): boolean {
   return path.startsWith("/") && !path.startsWith("//");
@@ -36,15 +42,42 @@ function validateConsumerProtection(cp: ConsumerProtectionOptions): void {
       `createBillingFoundationFeature: consumerProtection.operatorEmail "${cp.operatorEmail}" is not a valid email address.`,
     );
   }
+  if (cp.oneOffItemLabel !== undefined && typeof cp.oneOffItemLabel !== "function") {
+    throw new Error(
+      "createBillingFoundationFeature: consumerProtection.oneOffItemLabel must be a function.",
+    );
+  }
   if (cp.terminationScope !== undefined && !isTerminationScope(cp.terminationScope)) {
     throw new Error(
       `createBillingFoundationFeature: consumerProtection.terminationScope "${String(cp.terminationScope)}" must be one of ${TERMINATION_SCOPES.map((scope) => `"${scope}"`).join(", ")}.`,
     );
   }
-  for (const [key, link] of Object.entries(cp.legalLinks)) {
+  if (isLegalLinkSet(cp.legalLinks)) {
+    validateLegalLinkSet(cp.legalLinks, "legalLinks");
+  } else {
+    validatePerLocaleLegalLinks(cp.legalLinks);
+  }
+}
+
+function validatePerLocaleLegalLinks(
+  legalLinks: Readonly<Record<ConsentLocale, LegalLinkSet>>,
+): void {
+  for (const locale of CONSENT_LOCALES) {
+    const set = legalLinks[locale];
+    if (!set) {
+      throw new Error(
+        `createBillingFoundationFeature: consumerProtection.legalLinks needs a "${locale}" entry when given per locale.`,
+      );
+    }
+    validateLegalLinkSet(set, `legalLinks.${locale}`);
+  }
+}
+
+function validateLegalLinkSet(set: LegalLinkSet, path: string): void {
+  for (const [key, link] of Object.entries(set)) {
     if (!isRootRelativeOrHttpsUrl(link)) {
       throw new Error(
-        `createBillingFoundationFeature: consumerProtection.legalLinks.${key} "${link}" must be a root-relative path ("/..." not "//") or an absolute https URL.`,
+        `createBillingFoundationFeature: consumerProtection.${path}.${key} "${link}" must be a root-relative path ("/..." not "//") or an absolute https URL.`,
       );
     }
   }

package/packages/bundled-features/src/billing-foundation/web/billing-plans-panel.tsx

@@ -293,7 +293,7 @@ export function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode {
             {t("billing-foundation.plans.switchRequiresReactivation")}
           </Banner>
         )}
-      {consumerProtection !== undefined && canManage && (
+      {consumerProtection !== undefined && canManage && result.subscription?.cancelAt == null && (
         <div>
           <Button
             variant="secondary"

package/packages/bundled-features/src/billing-foundation/web/cancel-contract-dialog.tsx

@@ -40,7 +40,7 @@ export function CancelContractDialog({
 }: CancelContractDialogProps): ReactNode {
   const t = useTranslation();
   const locale = useLocale().locale();
-  const { Modal, Heading, Text, Field, Input, Button, Banner } = usePrimitives();
+  const { Modal, Text, Field, Input, Button, Banner } = usePrimitives();
   const terminate = useMutation<TerminateContractReceipt>(
     SubscriptionFoundationHandlers.terminateContract,
   );
@@ -78,7 +78,6 @@ export function CancelContractDialog({
       testId="cancel-contract-dialog"
     >
       <div className="flex flex-col gap-4">
-        <Heading variant="page">{t("billing-foundation.cancel.title")}</Heading>
         {step === "form" && (
           <>
             <Text variant="muted">{t("billing-foundation.cancel.declaration")}</Text>

package/packages/bundled-features/src/billing-foundation/web/checkout-consent-dialog.tsx

@@ -21,7 +21,11 @@ export type CheckoutConsentDialogProps = {
   readonly open: boolean;
   readonly onOpenChange: (open: boolean) => void;
   readonly planName: string;
-  readonly price: { readonly amount: string; readonly renewalKey?: string; readonly count: string };
+  readonly price: {
+    readonly amount: string;
+    readonly renewalKey?: string;
+    readonly count?: string;
+  };
   readonly consumerProtection: ConsumerProtectionView;
   readonly onOrder: (consent: CheckoutConsentPayload) => Promise<WriteResult<{ url: string }>>;
   readonly onConsentTextOutdated: () => void;
@@ -39,7 +43,7 @@ export function CheckoutConsentDialog({
 }: CheckoutConsentDialogProps): ReactNode {
   const t = useTranslation();
   const uiLocale = useLocale().locale();
-  const { Modal, Heading, Text, Field, Input, Button, Link, Banner } = usePrimitives();
+  const { Modal, Text, Field, Input, Button, Link, Banner } = usePrimitives();
   const [earlyPerformance, setEarlyPerformance] = useState(false);
   const [withdrawalLoss, setWithdrawalLoss] = useState(false);
   const [submitting, setSubmitting] = useState(false);
@@ -47,7 +51,7 @@ export function CheckoutConsentDialog({
 
   const consentLocale = resolveConsentLocale(uiLocale);
   const texts = consumerProtection.consentTexts[consentLocale];
-  const { legalLinks } = consumerProtection;
+  const legalLinks = consumerProtection.legalLinks[consentLocale];
 
   async function order(): Promise<void> {
     setSubmitting(true);
@@ -76,15 +80,21 @@ export function CheckoutConsentDialog({
       testId="checkout-consent-dialog"
     >
       <div className="flex flex-col gap-4">
-        <Heading variant="page">{t("billing-foundation.consent.title")}</Heading>
         <div className="flex flex-col gap-1" data-testid="checkout-consent-summary">
           <Text>
             {planName} — {price.amount}
           </Text>
           {price.renewalKey !== undefined && (
-            <Text variant="muted">{t(price.renewalKey, { count: price.count })}</Text>
+            <>
+              <Text variant="muted">
+                {t(
+                  price.renewalKey,
+                  price.count !== undefined ? { count: price.count } : undefined,
+                )}
+              </Text>
+              <Text variant="muted">{t("billing-foundation.consent.cancelAnytime")}</Text>
+            </>
           )}
-          <Text variant="muted">{t("billing-foundation.consent.cancelAnytime")}</Text>
         </div>
         <div className="flex flex-wrap gap-4">
           <Link href={legalLinks.terms} target="_blank">

package/packages/bundled-features/src/billing-foundation/web/index.ts

@@ -13,11 +13,23 @@ export {
   type SubscriptionStatus,
   SubscriptionStatuses,
 } from "../constants.js";
+export {
+  CONSENT_LOCALES,
+  type ConsentLocale,
+  resolveConsentLocale,
+} from "../consumer-protection/consent-locale.js";
 export type {
   BillingPlanBenefit,
   BillingPlanCatalog,
   BillingPlansResult,
   BillingPlanView,
+  LegalLinkSet,
 } from "../types.js";
 export { BillingPlansPanel } from "./billing-plans-panel.js";
+export {
+  CheckoutConsentDialog,
+  type CheckoutConsentDialogProps,
+  type CheckoutConsentPayload,
+  CONSENT_TEXT_OUTDATED_CODE,
+} from "./checkout-consent-dialog.js";
 export { type BillingFoundationClientOptions, billingFoundationClient } from "./client-plugin.js";

package/packages/bundled-features/src/legal-pages/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.344.0",
+    "type": "improvement",
+    "title": "Optional title heading on legal pages",
+    "detail": "`LegalPageRoute` has an optional `titleHeading` flag. When `true`, the page body starts with an `<h1>` holding the escaped page title. The default (`false`) leaves the body unchanged."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/legal-pages/constants.ts

@@ -10,6 +10,8 @@ export type LegalPageRoute = {
   readonly slug: string;
   readonly lang: string;
   readonly titleFallback: string;
+  /** Prepend the page title as `<h1>` to the rendered body. Default false. */
+  readonly titleHeading?: boolean;
 };
 
 // Shape of one boot-check-required block — the type behind

package/packages/bundled-features/src/legal-pages/feature.ts

@@ -4,6 +4,7 @@ import {
   type FeatureDefinition,
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { escapeHtml } from "@cosmicdrift/kumiko-headless";
 import {
   cachedSecurePageResponse,
   type PublicPageWrapLayout,
@@ -87,7 +88,7 @@ export type LegalPagesOptions = {
 
 export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDefinition {
   const wrapLayout = opts.wrapLayout ?? wrapInLayout;
-  const routes = opts.routes ?? LEGAL_ROUTES;
+  const routes: readonly LegalPageRoute[] = opts.routes ?? LEGAL_ROUTES;
   const requiredBlocks = opts.requiredBlocks ?? LEGAL_REQUIRED_BLOCKS;
   validateRoutes(routes);
   if (opts.routes !== undefined && opts.routes.length > 0 && opts.requiredBlocks === undefined) {
@@ -172,9 +173,13 @@ export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDe
             });
           }
 
+          const title = data.title || route.titleFallback;
+          const renderedBody = renderMarkdownToHtml(data.content);
           const html = wrapLayout({
-            title: data.title || route.titleFallback,
-            bodyHtml: renderMarkdownToHtml(data.content),
+            title,
+            bodyHtml: route.titleHeading
+              ? `<h1>${escapeHtml(title)}</h1>${renderedBody}`
+              : renderedBody,
             lang: route.lang,
             slug: route.slug,
           });

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.344.0",
+    "type": "improvement",
+    "title": "Heading and Markdown sections in the simple mail renderer",
+    "detail": "`createSimpleRenderer` accepts two more section kinds: `{ heading: string }` (rendered as an escaped `<h2>`) and `{ markdown: string }` (rendered with the hardened Markdown renderer; raw HTML is escaped and unsafe link targets are replaced by `#`). Existing section kinds render as before."
+  },
   {
     "version": "0.341.0",
     "type": "improvement",

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

@@ -1,5 +1,6 @@
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import type { NotificationRenderer } from "../delivery/index.js";
+import { renderSafeMarkdown } from "../page-render/index.js";
 
 export type MailBranding = {
   /** Shown as text when there is no logo, and as the logo alt text. */
@@ -141,6 +142,8 @@ function renderBrandingFooter(
 
 type Section =
   | { readonly text: string }
+  | { readonly heading: string }
+  | { readonly markdown: string }
   | { readonly button: { readonly label: string; readonly url: string } };
 
 type EmailTemplateData = {
@@ -157,6 +160,13 @@ 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>`;
   }
+  if ("heading" in section) {
+    return `<h2 style="margin:24px 0 12px;color:#111;font-size:16px;font-weight:600">${escapeHtml(section.heading)}</h2>`;
+  }
+  if ("markdown" in section) {
+    const markdownHtml = renderSafeMarkdown(section.markdown);
+    return `<div style="color:#333;font-size:14px;line-height:1.5">${markdownHtml}</div>`;
+  }
   if ("button" in section) {
     return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:${escapeHtmlAttr(primaryColor)};color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
   }

package/samples/apps/use-all-bundled/e2e-billing-gallery/gallery-features.ts

@@ -69,8 +69,8 @@ export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition
     baseUrl,
     catalog: {
       plans: ["starter", "pro"],
-      tierLabelKey: (tier) => `gallery.plan.${tier}.label`,
-      benefits: (tier) => [{ labelKey: `gallery.plan.${tier}.benefit` }],
+      tierLabelKey: (tier) => `gallery-screens:plan.${tier}.label`,
+      benefits: (tier) => [{ labelKey: `gallery-screens:plan.${tier}.benefit` }],
       resolveCurrentTier,
       viewRoles: ["TenantAdmin", "SystemAdmin"],
       successPath: GALLERY_PLAN_PATH,
@@ -83,9 +83,8 @@ export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition
       operatorEmail: GALLERY_OPERATOR_EMAIL,
       terminationScope: "platform",
       legalLinks: {
-        terms: "/legal/terms",
-        withdrawal: "/legal/withdrawal",
-        privacy: "/legal/privacy",
+        de: { terms: "/legal/terms", withdrawal: "/legal/withdrawal", privacy: "/legal/privacy" },
+        en: { terms: "/legal/terms", withdrawal: "/legal/withdrawal", privacy: "/legal/privacy" },
       },
     },
   });
@@ -140,12 +139,12 @@ export const galleryScreensFeature: FeatureDefinition = defineFeature("gallery-s
   r.translations({
     keys: {
       "gallery:nav.billing": { de: "Abrechnung", en: "Billing" },
-      "gallery.plan.free.label": { de: "Free", en: "Free" },
-      "gallery.plan.starter.label": { de: "Starter", en: "Starter" },
-      "gallery.plan.pro.label": { de: "Pro", en: "Pro" },
-      "gallery.plan.starter.benefit": { de: "Für kleine Teams", en: "For small teams" },
-      "gallery.plan.pro.benefit": { de: "Für wachsende Teams", en: "For growing teams" },
-      "gallery.plan.free.benefit": { de: "Zum Ausprobieren", en: "To try things out" },
+      "gallery-screens:plan.free.label": { de: "Free", en: "Free" },
+      "gallery-screens:plan.starter.label": { de: "Starter", en: "Starter" },
+      "gallery-screens:plan.pro.label": { de: "Pro", en: "Pro" },
+      "gallery-screens:plan.starter.benefit": { de: "Für kleine Teams", en: "For small teams" },
+      "gallery-screens:plan.pro.benefit": { de: "Für wachsende Teams", en: "For growing teams" },
+      "gallery-screens:plan.free.benefit": { de: "Zum Ausprobieren", en: "To try things out" },
     },
   });
   return {};

package/samples/apps/use-all-bundled/e2e-billing-gallery/server.ts

@@ -42,8 +42,8 @@ const features = [
 ];
 
 const TERMS_TEXT: Readonly<Record<string, string>> = {
-  de: "## Allgemeine Geschäftsbedingungen\n\nDiese Bedingungen gelten für alle Verträge über die Plattform.",
-  en: "## Terms and conditions\n\nThese terms apply to every contract concluded through the platform.",
+  de: "Diese Bedingungen gelten für alle Verträge über die Plattform.",
+  en: "These terms apply to every contract concluded through the platform.",
 };
 
 const seedTerms: SeedFn = async (stack) => {