@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

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/register-termination.ts

@@ -52,9 +52,19 @@ export function registerContractTermination(
   // request: matched and unmatched requests then do the same work and the
   // response time does not tell whether the email belongs to a customer.
   // The tenant comes from the stored trigger event (the job's system user).
+  // Every declaration appends to the same subscription stream, so parallel runs
+  // and a declaration arriving mid-run hit version conflicts. Sequential runs
+  // rule out the first; a retry re-reads the stream and the requestId check in
+  // record-contract-termination keeps it from recording twice.
   r.job(
     "cancel-on-public-termination-declared",
-    { trigger: { on: CONTRACT_TERMINATION_DECLARED_EVENT_QN }, runIn: "worker" },
+    {
+      trigger: { on: CONTRACT_TERMINATION_DECLARED_EVENT_QN },
+      runIn: "worker",
+      concurrency: "sequential",
+      retries: 3,
+      backoff: "exponential",
+    },
     async (payload, ctx) => {
       const declared = contractTerminationDeclaredPayloadSchema.safeParse(payload);
       // skip: trigger event carries no usable declaration

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,38 +79,36 @@ function declarationLines(
   return lines.map((text) => ({ text }));
 }
 
-export type RenderTerminationReceiptArgs = {
+/** The receipt carries enum fields only: free text from an anonymous caller
+ *  must not be echoed to an arbitrary address. */
+export type ReceiptDeclaration = Pick<
+  TerminationDeclaration,
+  "declarationType" | "terminationKind"
+>;
+
+export type TerminationReceiptArgs = {
   readonly locale: ConsentLocale;
   readonly requestId: string;
   readonly receivedAtIso: string;
-  readonly declaration: TerminationDeclaration;
+  readonly declaration: ReceiptDeclaration;
   readonly operatorEmail: string;
 };
 
-/** 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 {
+/** The content must not depend on whether (or how) the declaration matched a contract. */
+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 +120,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 +137,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-receipt-limit.ts

@@ -0,0 +1,41 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { normalizePayloadBucketValue } from "@cosmicdrift/kumiko-framework/pipeline";
+
+// The declaration itself is a statutory duty and is never refused. Only the
+// receipt mail is capped, so the endpoint cannot be used to mail one inbox
+// from the operator's sender domain.
+export const RECEIPT_MAILS_PER_RECIPIENT = 3;
+export const RECEIPT_WINDOW_SECONDS = 24 * 60 * 60;
+
+const RECEIPT_BUCKET_PREFIX = "termination-receipt";
+
+function receiptBucketKey(ctx: HandlerContext, email: string): string | undefined {
+  const digest = ctx.rateLimitDigest?.(normalizePayloadBucketValue(email, "email"));
+  return digest === undefined ? undefined : `${RECEIPT_BUCKET_PREFIX}:${digest}`;
+}
+
+/** Consumes one receipt token for the recipient. Fails closed when the limiter
+ *  errors or no digest key is wired: the declaration is already recorded, a missing receipt is the lesser harm. */
+export async function mayMailReceipt(ctx: HandlerContext, email: string): Promise<boolean> {
+  // skip: no rate limiter wired, nothing to count against
+  if (!ctx.rateLimit) return true;
+  try {
+    const bucketKey = receiptBucketKey(ctx, email);
+    if (bucketKey === undefined) {
+      ctx.log?.warn(
+        "[billing-foundation:termination] no rate-limit digest available, receipt mail withheld",
+      );
+      return false;
+    }
+    const decision = await ctx.rateLimit.check(bucketKey, {
+      limit: RECEIPT_MAILS_PER_RECIPIENT,
+      windowSeconds: RECEIPT_WINDOW_SECONDS,
+    });
+    return decision.allowed;
+  } catch (error) {
+    ctx.log?.warn(
+      `[billing-foundation:termination] receipt rate limiter failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return false;
+  }
+}

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

@@ -35,6 +35,7 @@ import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from
 import { CONSENT_LOCALES, FALLBACK_CONSENT_LOCALE } from "./consent-locale.js";
 import { notifyOperator } from "./termination-notify.js";
 import type { OperatorNoticeReason } from "./termination-texts.js";
+import { isWithinWithdrawalPeriod } from "./withdrawal-period.js";
 
 const REQUESTED_CANCEL_TIMINGS = [
   SubscriptionCancelTimings.periodEnd,
@@ -74,6 +75,8 @@ export type RecordContractTerminationResult = {
     OperatorNoticeReason,
     "provider_cannot_cancel" | "provider_error" | "no_active_subscription"
   > | null;
+  /** An account withdrawal arrived after the period: cancelled at period end instead. */
+  readonly withdrawalPeriodExpired: boolean;
 };
 
 export const recordUnmatchedContractTerminationSchema = z
@@ -210,14 +213,19 @@ export function createRecordContractTerminationHandler(
             effectiveAtIso: alreadyRecorded.effectiveAtIso,
             providerCancel: alreadyRecorded.providerCancel,
             noticeReason: null,
+            withdrawalPeriodExpired: false,
           } satisfies RecordContractTerminationResult,
         };
       }
 
+      const withdrawalPeriodExpired =
+        payload.declarationType === "withdrawal" &&
+        payload.when === SubscriptionCancelTimings.immediately &&
+        !isWithinWithdrawalPeriod(stream.events, options.now());
       const { providerCancel, effectiveAtIso, noticeReason } = await cancelAtProvider(
         ctx,
         tenantId,
-        payload.when,
+        withdrawalPeriodExpired ? SubscriptionCancelTimings.periodEnd : payload.when,
         receivedAtIso,
       );
 
@@ -260,6 +268,7 @@ export function createRecordContractTerminationHandler(
           effectiveAtIso,
           providerCancel,
           noticeReason,
+          withdrawalPeriodExpired,
         } satisfies RecordContractTerminationResult,
       };
     },

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

@@ -31,12 +31,12 @@ 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 { mayMailReceipt } from "./termination-receipt-limit.js";
 import type { RecordContractTerminationResult } from "./termination-record.js";
 import type { OperatorNoticeReason } from "./termination-texts.js";
 
-const TENANT_ADMIN_ROLE = "TenantAdmin";
 const EXTRAORDINARY_REASON_MESSAGE = "reason is required for an extraordinary termination";
 
 const authUserRowSchema = z.object({
@@ -109,28 +109,38 @@ async function sendTerminationMails(
   consumerProtection: ConsumerProtectionOptions,
   plan: TerminationMailPlan,
 ): Promise<void> {
-  await requireNotify(ctx)(CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, {
-    route: { email: plan.declaration.email },
-    data: renderTerminationReceipt({
+  const receiptAllowed = await mayMailReceipt(ctx, plan.declaration.email);
+  if (receiptAllowed) {
+    await requireNotify(ctx)(CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, {
+      route: { email: plan.declaration.email },
+      data: terminationReceiptVariables({
+        locale: plan.locale,
+        requestId: plan.requestId,
+        receivedAtIso: plan.receivedAtIso,
+        declaration: {
+          declarationType: plan.declaration.declarationType,
+          terminationKind: plan.declaration.terminationKind,
+        },
+        operatorEmail: consumerProtection.operatorEmail,
+      }),
       locale: plan.locale,
-      requestId: plan.requestId,
-      receivedAtIso: plan.receivedAtIso,
-      declaration: plan.declaration,
-      operatorEmail: consumerProtection.operatorEmail,
-    }),
-    locale: plan.locale,
-    priority: "critical",
-  });
+      priority: "critical",
+    });
+  }
+  const reasons = receiptAllowed
+    ? plan.reasons
+    : [...plan.reasons, "receipt_rate_limited" as const];
   // skip: no operator notice needed for this declaration
-  if (plan.reasons.length === 0) return;
-  await notifyOperator(ctx, consumerProtection, plan);
+  if (reasons.length === 0) return;
+  await notifyOperator(ctx, consumerProtection, { ...plan, reasons });
 }
 
 // Tenants the entered email can terminate a contract for: tenants where the
-// user is TenantAdmin and the subscription is not terminal. Every identity
+// user holds a purchase role and the subscription is not terminal. Every identity
 // below comes from the trusted lookups, never from the payload.
 async function findTerminableTenantIds(
   ctx: HandlerContext,
+  options: ResolvedBillingFoundationOptions,
   requestTenantId: string,
   email: string,
 ): Promise<readonly string[]> {
@@ -148,10 +158,11 @@ async function findTerminableTenantIds(
     }),
   );
   if (!memberships.success) return [];
+  const purchaseRoles = purchaseRolesOf(options.catalog);
   const adminTenantIds = [
     ...new Set(
       memberships.data
-        .filter((membership) => membership.roles.includes(TENANT_ADMIN_ROLE))
+        .filter((membership) => membership.roles.some((role) => purchaseRoles.includes(role)))
         .map((membership) => membership.tenantId),
     ),
   ];
@@ -180,7 +191,6 @@ export function createRequestContractTerminationHandler(
     schema: requestContractTerminationSchema,
     access: { roles: ["anonymous"] },
     rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 600 },
-    additionalRateLimits: [{ per: { payloadField: "email" }, limit: 3, windowSeconds: 86400 }],
     ...(consumerProtection.terminationScope === "platform" && { tenantlessAnonymous: true }),
     escapeHatch: {
       reason:
@@ -196,7 +206,12 @@ export function createRequestContractTerminationHandler(
       const locale = resolveConsentLocale(payload.locale);
       let matchedTenantId: string | undefined;
 
-      const candidates = await findTerminableTenantIds(ctx, event.user.tenantId, payload.email);
+      const candidates = await findTerminableTenantIds(
+        ctx,
+        options,
+        event.user.tenantId,
+        payload.email,
+      );
       const [onlyCandidate] = candidates;
       if (candidates.length === 1 && onlyCandidate !== undefined) {
         matchedTenantId = onlyCandidate;
@@ -257,7 +272,7 @@ export function createTerminateContractHandler(
   return {
     name: "terminate-contract",
     description:
-      "Terminates the tenant's subscription at the end of the billing period, or withdraws from the contract and cancels it immediately; sends a receipt to the caller's email.",
+      "Terminates the tenant's subscription at the end of the billing period, or withdraws from the contract and cancels it immediately within the 14-day withdrawal period (at period end after it); sends a receipt to the caller's email.",
     schema: terminateContractSchema,
     access: { roles: purchaseRolesOf(options.catalog) },
     escapeHatch: {
@@ -313,6 +328,7 @@ export function createTerminateContractHandler(
         },
         reasons: [
           ...(data.noticeReason !== null ? [data.noticeReason] : []),
+          ...(data.withdrawalPeriodExpired ? (["withdrawal_period_expired"] as const) : []),
           ...needsOperatorNotice(payload),
         ],
         tenantId,

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

@@ -72,6 +72,8 @@ export const OPERATOR_NOTICE_REASONS = [
   "provider_error",
   "no_active_subscription",
   "recording_failed",
+  "withdrawal_period_expired",
+  "receipt_rate_limited",
 ] as const;
 export type OperatorNoticeReason = (typeof OPERATOR_NOTICE_REASONS)[number];
 
@@ -116,6 +118,10 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       provider_error: "Die Kündigung beim Zahlungsanbieter ist fehlgeschlagen",
       no_active_subscription: "Keine laufende Subscription beim Anbieter",
       recording_failed: "Die Erklärung konnte nicht gespeichert werden",
+      withdrawal_period_expired:
+        "Widerruf nach Ablauf der Widerrufsfrist: zum Periodenende gekündigt, Anspruch prüfen",
+      receipt_rate_limited:
+        "Keine Eingangsbestätigung versendet: Limit pro Empfängeradresse erreicht",
     },
     noticeReasons: "Grund der Benachrichtigung",
     channel: "Kanal",
@@ -199,6 +205,9 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       provider_error: "Cancelling at the payment provider failed",
       no_active_subscription: "No running subscription at the provider",
       recording_failed: "The declaration could not be stored",
+      withdrawal_period_expired:
+        "Withdrawal after the withdrawal period: cancelled at period end, review the claim",
+      receipt_rate_limited: "No receipt mail sent: the per-recipient limit was reached",
     },
     noticeReasons: "Reason for this notice",
     channel: "Channel",

package/packages/bundled-features/src/billing-foundation/consumer-protection/withdrawal-period.ts

@@ -0,0 +1,35 @@
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_QN } from "../events.js";
+
+// § 355 BGB: the withdrawal period is 14 days from conclusion of the contract.
+export const WITHDRAWAL_PERIOD_DAYS = 14;
+const HOURS_PER_DAY = 24;
+
+const PERIOD_START_EVENT_TYPES: ReadonlySet<string> = new Set([
+  CHECKOUT_CONSENT_RECORDED_EVENT_QN,
+  SUBSCRIPTION_CREATED_EVENT_QN,
+]);
+
+type PeriodStartEvent = { readonly type: string; readonly createdAt: Temporal.Instant };
+
+/** The period runs from the latest consent or subscription start on the stream.
+ *  A stream with neither has no provable start and counts as expired. */
+export function isWithinWithdrawalPeriod(
+  events: readonly PeriodStartEvent[],
+  now: Temporal.Instant,
+): boolean {
+  let latestStart: Temporal.Instant | undefined;
+  for (const event of events) {
+    if (!PERIOD_START_EVENT_TYPES.has(event.type)) continue;
+    if (
+      latestStart === undefined ||
+      event.createdAt.epochMilliseconds > latestStart.epochMilliseconds
+    ) {
+      latestStart = event.createdAt;
+    }
+  }
+  // skip: no consent or subscription-created event, nothing proves a running period
+  if (latestStart === undefined) return false;
+  const periodEnd = latestStart.add({ hours: WITHDRAWAL_PERIOD_DAYS * HOURS_PER_DAY });
+  return now.epochMilliseconds <= periodEnd.epochMilliseconds;
+}

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-checkout-session.write.ts

@@ -23,7 +23,7 @@
 // hand-picked priceId.
 
 import type { HandlerContext, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import {
   assertCheckoutAllowed,
@@ -32,6 +32,7 @@ import {
   startProviderCheckout,
 } from "../checkout-core.js";
 import {
+  assertValidOrderItem,
   type ConsentPayload,
   consentCheckoutFields,
   consentPayloadSchema,
@@ -104,11 +105,12 @@ export function createCheckoutSessionHandler(
 
       const mode = payload.mode ?? "subscription";
       const plugin = await assertCheckoutAllowed(ctx, openOptions, checkoutInput);
-      const price = await lookupPrice(ctx, plugin, payload.priceId);
+      const price = await lookupPrice(ctx, plugin, payload.providerName, payload.priceId);
       const orderItem =
         mode === "payment"
           ? await consumerProtection.oneOffItemLabel?.(ctx, payload.priceId)
           : undefined;
+      assertValidOrderItem(orderItem, payload.priceId);
       const consent = await prepareConsent(ctx, consumerProtection, payload.consent, mode);
       const result = await startProviderCheckout(ctx, plugin, {
         ...checkoutInput,
@@ -134,11 +136,17 @@ export function createCheckoutSessionHandler(
 async function lookupPrice(
   ctx: HandlerContext,
   plugin: SubscriptionProviderPlugin,
+  providerName: string,
   priceId: string,
 ): Promise<ProviderPrice> {
+  if (!plugin.retrievePrices) {
+    throw new InternalError({
+      message: `billing-foundation: provider "${providerName}" lacks retrievePrices, required by consumerProtection`,
+    });
+  }
   let price: ProviderPrice | undefined;
   try {
-    const prices = (await plugin.retrievePrices?.(ctx, [priceId])) ?? [];
+    const prices = await plugin.retrievePrices(ctx, [priceId]);
     price = prices.find((p) => p.priceId === priceId);
   } catch (cause) {
     throw priceUnavailable(priceId, cause);

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

@@ -21,6 +21,7 @@ import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id.js";
 import {
   isSubscriptionBlockingCheckout,
+  isSwitchableSubscriptionStatus,
   SubscriptionEventTypes,
   SubscriptionStatuses,
 } from "../constants.js";
@@ -167,8 +168,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,
@@ -199,19 +200,24 @@ export async function appendSubscriptionEvent(
 // Tenant-Admin direkt.
 // One subscription aggregate exists per tenant, but a tenant can legitimately hold two provider
 // subscriptions over time (a stale `incomplete` one superseded by a fresh checkout). A late or
-// retried event of the old subscription must not overwrite the row of the live one, so only a
-// `created` event may replace a blocking row that belongs to a different provider subscription.
+// retried event of the old subscription must not overwrite the row of the live one, so an event of a
+// different provider subscription only replaces a row that no longer blocks a checkout. The exception
+// is a `created` of a subscription that is itself live (a provider switch); a late `created` of a
+// never-completed `incomplete` one stays stale, since delivery order is not guaranteed.
 function isStaleSubscriptionEvent(
   current: SubscriptionView | null,
   payload: ProcessEventPayload,
   now: Temporal.Instant,
 ): boolean {
   if (current === null) return false;
-  if (payload.type === SubscriptionEventTypes.created) return false;
   const sameSubscription =
     current.providerName === payload.providerName &&
     current.providerSubscriptionId === payload.providerSubscriptionId;
-  return !sameSubscription && isSubscriptionBlockingCheckout(current, now);
+  if (sameSubscription || !isSubscriptionBlockingCheckout(current, now)) return false;
+  const supersedesCurrent =
+    payload.type === SubscriptionEventTypes.created &&
+    isSwitchableSubscriptionStatus(payload.status);
+  return !supersedesCurrent;
 }
 
 export function createProcessEventHandler(now: () => Temporal.Instant): WriteHandlerDef {

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/i18n.ts

@@ -95,6 +95,9 @@ export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>>
   "billing-foundation.errors.redirectOriginNotAllowed": {
     en: "This redirect URL is not allowed for this app.",
   },
+  "billing-foundation.errors.providerCustomerUnknown": {
+    en: "The billing account for this subscription no longer exists. Subscribe again to continue.",
+  },
   "billing-foundation.errors.providerHasNoPriceCatalog": {
     en: "This provider has no known prices configured.",
   },