@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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

@@ -14,11 +14,9 @@ import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id.ts";
 import {
   CONTRACT_TERMINATION_DECLARED_EVENT_QN,
-  CONTRACT_TERMINATION_REQUESTED_EVENT_QN,
   CONTRACT_TERMINATION_REVOKED_EVENT_QN,
   type ContractTerminationRevokedPayload,
   contractTerminationDeclaredPayloadSchema,
-  contractTerminationRequestedPayloadSchema,
   SUBSCRIPTION_AGGREGATE_TYPE,
 } from "../events.ts";
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.ts";
@@ -26,7 +24,7 @@ import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from
 import { SubscriptionFoundationHandlers } from "../web/constants.ts";
 import type { ConsentLocale } from "./consent-text.ts";
 import { notifyOperator } from "./termination-notify.ts";
-import { hasRevocation, resumeAtProvider } from "./termination-record.ts";
+import { findRecordedTermination, hasRevocation, resumeAtProvider } from "./termination-record.ts";
 import type { OperatorNoticeReason } from "./termination-texts.ts";
 
 export const REVOCATION_PATHS: Readonly<Record<ConsentLocale, string>> = {
@@ -152,10 +150,7 @@ export function createRecordContractTerminationRevocationHandler(
       }
       if (hasRevocation(stream.events, payload.requestId)) return outcome("already-revoked");
 
-      const requested = stream.events
-        .filter((e) => e.type === CONTRACT_TERMINATION_REQUESTED_EVENT_QN)
-        .map((e) => contractTerminationRequestedPayloadSchema.safeParse(e.payload).data)
-        .find((candidate) => candidate?.requestId === payload.requestId);
+      const requested = findRecordedTermination(stream.events, payload.requestId);
       const subscription = await getSubscriptionForTenant(ctx, tenantId);
       const effectiveAtIso = requested?.effectiveAtIso ?? subscription?.currentPeriodEnd.toString();
       const now = options.now();
@@ -175,6 +170,17 @@ export function createRecordContractTerminationRevocationHandler(
         aggregateId: subscriptionAggregateId(tenantId),
         aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
       });
+      // A cancel recorded between the first fetch and now was never resumed above.
+      const requestedMeanwhile =
+        requested === undefined
+          ? findRecordedTermination(streamAfterProviderCall.events, payload.requestId)
+          : undefined;
+      if (requestedMeanwhile?.providerCancel === "period-end") {
+        reasons.push(
+          ...(await resumeAtProvider(ctx, await getSubscriptionForTenant(ctx, tenantId))),
+        );
+      }
+      const providerCancel = (requested ?? requestedMeanwhile)?.providerCancel;
       const revoked: ContractTerminationRevokedPayload = {
         requestId: payload.requestId,
         revokedAtIso: now.toString(),
@@ -194,7 +200,7 @@ export function createRecordContractTerminationRevocationHandler(
         },
         reasons,
         tenantId,
-        ...(requested !== undefined && { providerCancel: requested.providerCancel }),
+        ...(providerCancel !== undefined && { providerCancel }),
       });
       return outcome("revoked");
     },

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

@@ -91,6 +91,7 @@ export const OPERATOR_NOTICE_REASONS = [
   "recording_failed",
   "withdrawal_period_expired",
   "receipt_rate_limited",
+  "receipt_not_sent",
   "revoked",
   "revocation_resume_manual",
   "revocation_resume_failed",
@@ -145,6 +146,8 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
         "Widerruf nach Ablauf der Widerrufsfrist: zum Periodenende gekündigt, Anspruch prüfen",
       receipt_rate_limited:
         "Keine Eingangsbestätigung versendet: Limit pro Empfängeradresse erreicht",
+      receipt_not_sent:
+        "Keine Eingangsbestätigung versendet: Limit-Prüfung nicht verfügbar (Redis-Fehler oder fehlende Konfiguration)",
       revoked:
         "Die Erklärung wurde vom Postfachinhaber über „Diese Kündigung war ich nicht“ zurückgenommen",
       revocation_resume_manual:
@@ -256,6 +259,8 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       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",
+      receipt_not_sent:
+        "No receipt mail sent: the limit check was unavailable (limiter error or missing configuration)",
       revoked:
         'The declaration was taken back by the mailbox owner ("I did not request this cancellation")',
       revocation_resume_manual:

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

@@ -1,26 +1,24 @@
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_QN } from "../events.ts";
+import { SUBSCRIPTION_CREATED_EVENT_QN } from "../events.ts";
 
 // § 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. */
+/** The period runs from the latest subscription start on the stream. A checkout
+ *  consent alone never restarts it: it is written before the buyer reaches the
+ *  provider, so an abandoned plan-change checkout would otherwise reopen the
+ *  period of a long-concluded contract. A stream without a subscription start
+ *  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 (event.type !== SUBSCRIPTION_CREATED_EVENT_QN) continue;
     if (
       latestStart === undefined ||
       event.createdAt.epochMilliseconds > latestStart.epochMilliseconds
@@ -28,7 +26,7 @@ export function isWithinWithdrawalPeriod(
       latestStart = event.createdAt;
     }
   }
-  // skip: no consent or subscription-created event, nothing proves a running period
+  // skip: no 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/entities.ts

@@ -4,39 +4,39 @@ import {
   createTextField,
   createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
-// `subscription` — current state pro Plattform-Tenant (= Read-Model)
+// `subscription` — current state per platform tenant (= read model)
 // =============================================================================
 //
-// Inline-Projection-Target. Geschrieben vom `subscription`-projection-
-// apply (siehe feature.ts), NIE direkt vom handler. Source-of-truth ist
-// der event-store stream `subscription` mit aggregate-id =
+// Inline projection target. Written by the `subscription` projection-
+// apply (see feature.ts), NEVER directly by the handler. Source of truth is
+// the event-store stream `subscription` with aggregate-id =
 // uuidv5(SUBSCRIPTION_NAMESPACE, tenantId).
 //
-// EINE Row pro Plattform-Tenant. Aggregate-ID ist deterministic, damit
-// Webhook-Replays (Stripe sendet bei Hängern bis zu 5x in 4h) auf
-// denselben Stream schreiben statt zwei Rows zu erzeugen.
+// ONE row per platform tenant. The aggregate ID is deterministic so that
+// webhook replays (Stripe sends up to 5 times in 4 hours when delivery is
+// stalled) write to the same stream instead of creating two rows.
 //
-// **Felder:**
-//   - providerName: "stripe" / "mollie" — welcher Provider die
-//     Subscription hält. Provider-Wechsel = neuer event auf demselben
-//     Stream, projection überschreibt.
-//   - providerCustomerId / providerSubscriptionId: provider-eigene
-//     IDs.
+// **Fields:**
+//   - providerName: "stripe" / "mollie" — the provider holding the
+//     subscription. A provider change is a new event on the same stream;
+//     the projection overwrites the value.
+//   - providerCustomerId / providerSubscriptionId: provider-specific IDs.
 //   - status: active / past_due / canceled / trialing / incomplete —
-//     normalisiert über provider-grenzen hinweg.
-//   - tier: "free" / "pro" / ... — vom tier-engine konsumiert. Aus
-//     price-to-tier-Map resolved im Plugin.
-//   - currentPeriodEnd: wann läuft die aktuelle Billing-Period aus.
+//     normalized across providers.
+//   - tier: "free" / "pro" / ... — consumed by the tier engine. Resolved
+//     from the price-to-tier map in the plugin.
+//   - currentPeriodEnd: when the current billing period ends.
 //   - cancelAt: when a scheduled cancellation ends the subscription;
 //     nullable because a renewing subscription has none.
 //
-// **Was hier NICHT ist:**
-//   - invoice-history, payment-method, line-items, tax-info → all das
-//     fetcht der Tenant via customer-portal-session direkt vom Provider.
+// **Not included here:**
+//   - invoice-history, payment-method, line-items, tax-info — the tenant
+//     fetches all of these directly from the provider via a
+//     customer-portal-session.
 //
-// **Audit/event-history:** lebt im event-store unter dem `subscription`-
-// stream — KEIN eigene `subscription-event`-Tabelle mehr (= ES ist die
-// audit-truth, replay-fähig durch upcasters).
+// **Audit/event history:** lives in the event store under the `subscription`
+// stream — there is NO separate `subscription-event` table (= ES is the
+// audit source of truth and can be replayed through upcasters).
 export const subscriptionEntity = createEntity({
   table: "read_subscriptions",
   fields: {
@@ -47,10 +47,10 @@ export const subscriptionEntity = createEntity({
       reason: "technical_reference",
     }),
     // `personal: "tenant"` (not `encrypted`): the field must crypto-shred when
-    // eraseSubjectKeys erases the tenant's subject key on tenant-destroy
-    // (#800). `encrypted: true` uses the app-wide master key instead — that
+    // eraseSubjectKeys erases the tenant's subject key on tenant-destroy.
+    // `encrypted: true` uses the app-wide master key instead — that
     // key is never erased per-tenant, so it would only add encryption-at-
-    // rest, not the erasure guarantee #800 actually asks for.
+    // rest, not the erasure guarantee.
     // maxLength 1000, not 200: the stored value is PII-ciphertext
     // (`kumiko-pii:v1:<subject>:<blob>`), not the raw provider id — a
     // 200-char plaintext id becomes ~300+ chars of ciphertext. Matches
@@ -112,7 +112,7 @@ export const paymentEntity = createEntity({
       reason: "technical_reference",
     }),
     // Same `personal: "tenant"` rationale as subscriptionEntity above —
-    // crypto-shreds on tenant-destroy (#800) via eraseSubjectKeys.
+    // crypto-shreds on tenant-destroy via eraseSubjectKeys.
     providerCustomerId: createTextField({
       required: true,
       maxLength: 1000,

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

@@ -1,25 +1,25 @@
-// Domain-events für subscription-foundation.
+// Domain events for subscription-foundation.
 //
-// **Pattern:** event-sourced — jeder Provider-Webhook (nach Plugin-
-// verify) wird zu einem domain-event auf dem subscription-stream
-// (= ein stream pro Tenant via subscriptionAggregateId(tenantId)).
-// Read-model = inline projection in `subscriptions`-Tabelle.
+// **Pattern:** event-sourced — each provider webhook (after plugin
+// verification) becomes a domain event on the subscription stream
+// (= one stream per tenant via subscriptionAggregateId(tenantId)).
+// The read model is an inline projection in the `subscriptions` table.
 //
-// 5 fine-grained event-typen statt einem generic "webhook-received"-
-// bucket — events sind business-facts: future-consumer (billing-history,
-// accounting-export, churn-analytics) listenen direkt auf den event-
-// type ohne payload-discriminator.
+// Five fine-grained event types instead of a generic "webhook-received"
+// bucket — events are business facts: future consumers (billing-history,
+// accounting-export, churn-analytics) listen directly for the event type
+// without a payload discriminator.
 
 import * as z from "zod";
 import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./web/constants.ts";
 import { CONSENT_LOCALES } from "./web/consumer-protection/consent-locale.ts";
 
-// Aggregate-type für den event-store. Eine subscription pro Tenant ist
-// ein stream; der subscriptionAggregateId-helper liefert die stream-id.
+// Aggregate type for the event store. One subscription per tenant is
+// one stream; the subscriptionAggregateId helper provides the stream ID.
 export const SUBSCRIPTION_AGGREGATE_TYPE = "subscription" as const;
 
-// Event-name-Konstanten — short-form (für r.defineEvent) + qualifizierte
-// FQN (für ctx.unsafeAppendEvent + projection-apply-keys).
+// Event-name constants — short form (for r.defineEvent) and qualified
+// FQN (for ctx.unsafeAppendEvent and projection-apply keys).
 export const SUBSCRIPTION_CREATED_EVENT_SHORT = "subscription-created" as const;
 export const SUBSCRIPTION_UPDATED_EVENT_SHORT = "subscription-updated" as const;
 export const SUBSCRIPTION_CANCELED_EVENT_SHORT = "subscription-canceled" as const;
@@ -37,7 +37,7 @@ export const INVOICE_PAID_EVENT_QN =
 export const INVOICE_PAYMENT_FAILED_EVENT_QN =
   `${BILLING_FOUNDATION_FEATURE}:event:${INVOICE_PAYMENT_FAILED_EVENT_SHORT}` as const;
 
-// Status-enum für event-payloads (= subscription-state-snapshot vom Provider).
+// Status enum for event payloads (= the provider's subscription-state snapshot).
 const statusEnum = z.enum([
   SubscriptionStatuses.active,
   SubscriptionStatuses.trialing,
@@ -46,10 +46,11 @@ const statusEnum = z.enum([
   SubscriptionStatuses.incomplete,
 ]);
 
-// Common payload — alle 5 events tragen denselben subscription-state-
-// snapshot. Event-type tagged was passiert ist, payload den state-after.
+// Common payload — all five events carry the same subscription-state
+// snapshot. The event type identifies what happened; the payload contains
+// the resulting state.
 // The raw provider event is deliberately not stored: it carries plaintext
-// PII and event headers are not crypto-shreddable.
+// PII, and event headers cannot be crypto-shredded.
 export const subscriptionEventPayloadSchema = z.object({
   providerName: z.string().min(1).max(50),
   // 1000, not 200: these two are `tenantOwned: true` on the entity (see
@@ -72,10 +73,10 @@ export const subscriptionEventPayloadSchema = z.object({
 });
 export type SubscriptionEventPayload = z.infer<typeof subscriptionEventPayloadSchema>;
 
-// Headers-shape — wird im event-store als event.metadata.headers
-// persistiert (open-shape jsonb-column, primitives only).
-// Idempotency-anchor: providerEventId pro provider, foundation checked
-// vor append ob bereits gesehen.
+// Header shape — persisted in the event store as event.metadata.headers
+// (an open-shape JSONB column containing primitives only).
+// Idempotency anchor: providerEventId is checked per provider before append
+// to determine whether it has already been seen.
 export type SubscriptionEventHeaders = {
   readonly providerEventId: string;
   readonly providerName: string;
@@ -140,6 +141,7 @@ export const checkoutConsentRecordedPayloadSchema = z.object({
   termsTemplateVersion: z.number(),
   locale: z.string().min(2).max(35),
   actorUserId: z.string().min(1),
+  providerName: z.string().min(1).max(100).optional(),
   itemLabelKey: z.string().min(1).max(200).optional(),
   itemLabelParams: z.record(z.string(), z.union([z.string().max(100), z.number()])).optional(),
 });

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

@@ -1,54 +1,53 @@
 // kumiko-feature-version: 1
 //
-// subscription-foundation als Kumiko bundled feature (Plugin-Host).
+// subscription-foundation as a Kumiko bundled feature (plugin host).
 //
-// **Multi-Provider von Tag 1** — der App-Builder kann mehrere Plugins
-// parallel mounten (subscription-stripe + subscription-paypal +
-// subscription-apple-iap + ...) und der Endkunde wählt beim Subscribe-
-// Klick zwischen Karte/PayPal/Apple-Pay/Klarna/SEPA (Disney+-Pattern).
-// KEIN globaler `provider`-config-key — alle gemounteten Plugins sind
-// aktiv.
+// **Multi-provider from day one** — the app builder can mount multiple plugins
+// in parallel (subscription-stripe + subscription-paypal +
+// subscription-apple-iap + ...), and the end user chooses between
+// card/PayPal/Apple Pay/Klarna/SEPA at checkout (Disney+ pattern).
+// There is no global `provider` config key — all mounted plugins are active.
 //
-// **Was diese Foundation liefert:**
-//   1. **Plugin-API** für Subscription-Provider via `r.extendsRegistrar(
+// **What this foundation provides:**
+//   1. **Plugin API** for subscription providers via `r.extendsRegistrar(
 //      "subscriptionProvider", ...)`.
-//   2. **5 Domain-Events** auf dem `subscription`-stream (eine
-//      stream-id pro Tenant): created/updated/canceled/invoice-paid/
-//      invoice-payment-failed. Audit-history kommt frei vom event-store.
-//   3. **Inline-Projection** auf `read_subscriptions` (= current state
-//      pro Tenant). Apply läuft in derselben TX wie der event-append
+//   2. **5 domain events** on the `subscription` stream (one stream ID per
+//      tenant): created/updated/canceled/invoice-paid/invoice-payment-failed.
+//      Audit history is provided automatically by the event store.
+//   3. **Inline projection** onto `read_subscriptions` (current state per
+//      tenant). Apply runs in the same TX as the event append
 //      → read-your-own-write semantics.
-//   4. **process-event-handler**: programmatic write-handler den der
-//      webhook-handler aufruft, dispatcht zu type-passendem appendEvent.
+//   4. **process-event handler**: a programmatic write handler called by the
+//      webhook handler that dispatches to the type-matched appendEvent.
 //   5. **createSubscriptionWebhookRoute**: factory for the `entry:"signature"`
 //      extraRoute `/api/subscription/webhook/:providerName`.
-//   6. **payment-received event + read_payments projection**: one-off-
-//      payments (checkout mode "payment") get their own event, own
-//      per-tenant aggregate, and own `process-payment-event` write-handler
-//      — not a sixth SubscriptionEventTypes value (fw#2791).
+//   6. **payment-received event + read_payments projection**: one-off payments
+//      (checkout mode "payment") get their own event, per-tenant aggregate,
+//      and `process-payment-event` write handler — not a sixth
+//      SubscriptionEventTypes value.
 //   7. **Optional billing-plans catalog** (`createBillingFoundationFeature({
 //      baseUrl, catalog })`): a `billing-foundation:query:billing-plans`
-//      query plus `start-plan-checkout`/`switch-plan` write-handlers and a
+//      query plus `start-plan-checkout`/`switch-plan` write handlers and a
 //      dormant `billing-plans` dashboard screen/panel, all derived from the
-//      one `catalog` option — no separate per-app price wiring.
+//      single `catalog` option — no separate per-app price wiring.
 //
-// **Was diese Foundation NICHT macht:**
-//   - Kein r.entity für `subscription`. Die Tabelle ist eine reine
-//     Read-Projection — kein CRUD-Pfad. Schreibt wird ausschließlich
-//     via projection-apply, getriggert von einem der 5 events.
-//   - Kein Tier-Sync zum tier-engine. App-Owner liest die subscription-
-//     row via `getSubscriptionForTenant(ctx, tenantId)` wenn er möchte.
-//   - Keine provider-spezifischen Configs.
-//   - Kein Marketplace-Use-Case (App-Tenant billed Endkunden via
-//     Stripe Connect). Kommt als separate `marketplace-foundation`.
+// **What this foundation does NOT do:**
+//   - No r.entity for `subscription`. The table is a read-only projection —
+//     there is no CRUD path. It is written exclusively via projection-apply,
+//     triggered by one of the 5 events.
+//   - No tier sync with tier-engine. App owners can read the subscription row
+//     via `getSubscriptionForTenant(ctx, tenantId)` if needed.
+//   - No provider-specific configs.
+//   - No marketplace use case (the app tenant bills end customers via Stripe
+//     Connect). That comes later as a separate `marketplace-foundation`.
 //
-// **Provider-Wechsel:** Disney+-Pattern (= Tenant cancelt Stripe-sub,
-// startet neue mit PayPal) wird heute als zweiter `subscription-created`-
-// event modelliert. UPSERT in der projection-apply überschreibt den
-// existing row mit dem neuen providerName. Reicht für MVP. Wenn das
-// business-fact "Provider-Wechsel" ein eigenes domain-event braucht
-// (z.B. für analytics: "wie viele Wechsel im Monat?"), kommt ein
-// `subscription-provider-changed`-event-type später.
+// **Provider changes:** The Disney+ pattern (the tenant cancels a Stripe
+// subscription and starts a new one with PayPal) is currently modeled as a
+// second `subscription-created` event. UPSERT in projection-apply overwrites
+// the existing row with the new providerName. This is sufficient for the MVP.
+// If the business fact "provider change" needs its own domain event (for
+// example, for analytics such as "how many changes per month?"), a
+// `subscription-provider-changed` event type can be added later.
 
 import {
   defineFeature,
@@ -80,6 +79,7 @@ import { createBillingPlansQuery } from "./handlers/billing-plans.query.ts";
 import { createCheckoutSessionHandler } from "./handlers/create-checkout-session.write.ts";
 import { createPortalSessionHandler } from "./handlers/create-portal-session.write.ts";
 import { listSubscriptionsQuery } from "./handlers/list-subscriptions.query.ts";
+import { createPlanSwitchPreviewQuery } from "./handlers/plan-switch-preview.query.ts";
 import { createProcessEventHandler } from "./handlers/process-event.write.ts";
 import { processPaymentEventHandler } from "./handlers/process-payment-event.write.ts";
 import { createStartPlanCheckoutHandler } from "./handlers/start-plan-checkout.write.ts";
@@ -138,7 +138,7 @@ export function createBillingFoundationFeature<TTier extends string = string>(
     BILLING_FOUNDATION_FEATURE,
     (r) => {
       r.describe(
-        "Plugin host for subscription billing — manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers and a dormant billing-plans dashboard screen/panel from the catalog. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event — catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block — use `subscription-stripe` or `subscription-mollie` unless you are writing a new payment provider.",
+        "Plugin host for subscription billing. Manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers, a `plan-switch-preview` query and a dormant billing-plans dashboard screen/panel from the catalog. Several providers can be mounted at once: new checkouts are offered by every enabled provider (enabled means keys set and billingLive on, or simply mounted for plugins without `isBillingEnabled`), the customer picks one in the plan panel and `start-plan-checkout` takes a `providerName`. An existing subscription stays with the provider that stored it, so the plan list and every switch follow that provider. A plan switch is either hosted (`createPlanSwitchSession` answers a url) or in-app (`previewPlanSwitch` shows the proration, `applyPlanSwitch` runs after the customer confirms; `switch-plan` then answers `{ applied: true }` and records the consent). `consumerProtection.providerTexts` overrides the checkout note and the VAT note per provider. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event, which catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block: use `subscription-stripe`, `subscription-mollie` or `subscription-dodo` unless you are writing a new payment provider.",
       );
       r.uiHints({
         displayLabel: "Billing · Foundation",
@@ -199,19 +199,19 @@ export function createBillingFoundationFeature<TTier extends string = string>(
         },
       });
 
-      // Plugin extension-point. Provider-Plugins registrieren sich hier.
+      // Plugin extension point. Provider plugins register here.
       r.extendsRegistrar(SUBSCRIPTION_PROVIDER_EXTENSION, {
         onRegister: () => {
           // No side-effects at register-time.
         },
       });
 
-      // Custom write-handlers:
-      //   - process-event: programmatic entry-point vom webhook-handler;
-      //     dispatcht zu type-passendem appendEvent
+      // Custom write handlers:
+      //   - process-event: programmatic entry point called by the webhook
+      //     handler; dispatches to the type-matched appendEvent
       //   - create-checkout-session: bare priceId-driven checkout (hardened,
       //     see checkout-core)
-      //   - create-portal-session: Tenant-Admin "Manage Subscription"-flow
+      //   - create-portal-session: Tenant Admin "Manage Subscription" flow
       r.writeHandler(createProcessEventHandler(widened.now));
       r.writeHandler(createCheckoutSessionHandler(widened));
       r.writeHandler(createPortalSessionHandler(widened));
@@ -240,6 +240,7 @@ export function createBillingFoundationFeature<TTier extends string = string>(
       if (widened.catalog) {
         const { catalog } = widened;
         r.queryHandler(createBillingPlansQuery(widened, catalog));
+        r.queryHandler(createPlanSwitchPreviewQuery(catalog));
         r.writeHandler(createStartPlanCheckoutHandler(widened, catalog));
         r.writeHandler(createSwitchPlanHandler(widened, catalog));
         r.screen(createBillingPlansScreen(catalog.viewRoles));

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

@@ -1,6 +1,4 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-// Resolver-helper: liest die current subscription-row für einen Tenant
-// aus der read_subscriptions-projection.
 
 import {
   configuredPiiSubjectKms,
@@ -27,9 +25,9 @@ export type SubscriptionView = {
   readonly lastChangedAt: Temporal.Instant;
 };
 
-/** Liefert die einzige subscription-row für den Tenant (deterministic
- *  aggregate-id), oder null wenn der Tenant nie subscribed hat. Status
- *  kann active/canceled/past_due/etc sein — Caller entscheidet was tun. */
+/** Returns the tenant's only subscription row (deterministic
+ *  aggregate ID), or null if the tenant has never subscribed. The status
+ *  may be active/canceled/past_due/etc.; the caller decides what to do. */
 export async function getSubscriptionForTenant(
   ctx: HandlerContext,
   tenantId: string,

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

@@ -2,18 +2,29 @@
 // benefits, the caller's current tier and per-plan action. Only registered
 // when `createBillingFoundationFeature` gets a `catalog`.
 
-import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type { HandlerContext, QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { findCatalogProvider } from "../checkout-core.ts";
+import {
+  filterOfferedProviders,
+  listCatalogProviders,
+  type ResolvedProvider,
+} from "../checkout-core.ts";
 import {
   type CONSENT_LOCALES,
   CONSENT_TEXTS,
   consentTextVersion,
 } from "../consumer-protection/consent-text.ts";
-import { buildBillingPlans } from "../plan-catalog.ts";
+import {
+  type BillingPlansBase,
+  buildProviderPlanViews,
+  loadBillingPlansBase,
+  type ProviderPlanViews,
+  toBillingPlansResult,
+} from "../plan-catalog.ts";
 import {
   type BillingPlanCatalog,
   type BillingPlansResult,
+  type BillingProviderView,
   type ConsumerProtectionOptions,
   isLegalLinkSet,
   type LegalLinkSet,
@@ -29,12 +40,12 @@ export function createBillingPlansQuery(
   return {
     name: "billing-plans",
     description:
-      "Lists the purchasable plans with live price, benefits, the caller's current tier and which action (checkout | switch | current | unavailable | paymentPending) each plan offers, plus the optional price-less contact card.",
+      "Lists the purchasable plans with live price, benefits, the caller's current tier and which action (checkout | switch | current | unavailable | paymentPending) each plan offers, plus the optional price-less contact card. With several live providers it also lists each provider's own plans under `providers`.",
     schema: billingPlansSchema,
     access: { roles: catalog.viewRoles },
     handler: async (_query, ctx): Promise<BillingPlansResult> => {
-      const found = findCatalogProvider(ctx, catalog);
-      const result = await buildBillingPlans(ctx, found?.plugin ?? null, catalog, options.now);
+      const base = await loadBillingPlansBase(ctx, catalog, options.now);
+      const result = await resolveProviderPlans(ctx, options, catalog, base);
       const { consumerProtection } = options;
       if (!consumerProtection) return result;
       return {
@@ -51,6 +62,60 @@ export function createBillingPlansQuery(
   };
 }
 
+// A tenant with a blocking subscription sees only the provider holding it
+// (a second provider's prices would be a checkout it cannot start); otherwise
+// every live provider is offered.
+async function resolveProviderPlans(
+  ctx: HandlerContext,
+  options: ResolvedBillingFoundationOptions,
+  catalog: BillingPlanCatalog,
+  base: BillingPlansBase,
+): Promise<BillingPlansResult> {
+  const candidates = listCatalogProviders(ctx, catalog);
+  if (base.blockingSubscription && base.subscriptionView) {
+    const holder = candidates.find((c) => c.name === base.subscriptionView?.providerName);
+    return toBillingPlansResult(
+      catalog,
+      base,
+      await buildProviderPlanViews(ctx, holder?.plugin ?? null, catalog, base),
+    );
+  }
+
+  const offered = await filterOfferedProviders(ctx, candidates);
+  const first = offered[0] ?? candidates[0] ?? null;
+  const firstViews = await buildProviderPlanViews(ctx, first?.plugin ?? null, catalog, base);
+  const result = toBillingPlansResult(catalog, base, firstViews);
+
+  const providerTexts = options.consumerProtection?.providerTexts;
+  const hasNote = first !== null && providerTexts?.[first.name]?.checkoutNote !== undefined;
+  if (offered.length <= 1 && !(offered.length === 1 && hasNote)) return result;
+
+  const providers = await Promise.all(
+    offered.map((provider, index) =>
+      providerView(ctx, catalog, base, provider, providerTexts, index === 0 ? firstViews : null),
+    ),
+  );
+  return { ...result, providers };
+}
+
+async function providerView(
+  ctx: HandlerContext,
+  catalog: BillingPlanCatalog,
+  base: BillingPlansBase,
+  provider: ResolvedProvider,
+  providerTexts: ConsumerProtectionOptions["providerTexts"],
+  known: ProviderPlanViews | null,
+): Promise<BillingProviderView> {
+  const views = known ?? (await buildProviderPlanViews(ctx, provider.plugin, catalog, base));
+  const note = providerTexts?.[provider.name]?.checkoutNote;
+  return {
+    name: provider.name,
+    displayName: provider.plugin.displayName ?? provider.name,
+    ...(note !== undefined && { note }),
+    plans: views.plans,
+  };
+}
+
 function legalLinksPerLocale(
   legalLinks: ConsumerProtectionOptions["legalLinks"],
 ): Readonly<Record<(typeof CONSENT_LOCALES)[number], LegalLinkSet>> {