@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/billing-foundation/events.js

@@ -1,22 +1,22 @@
-// 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.js";
 import { CONSENT_LOCALES } from "./web/consumer-protection/consent-locale.js";
-// 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";
-// 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";
 export const SUBSCRIPTION_UPDATED_EVENT_SHORT = "subscription-updated";
 export const SUBSCRIPTION_CANCELED_EVENT_SHORT = "subscription-canceled";
@@ -27,7 +27,7 @@ export const SUBSCRIPTION_UPDATED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:even
 export const SUBSCRIPTION_CANCELED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${SUBSCRIPTION_CANCELED_EVENT_SHORT}`;
 export const INVOICE_PAID_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${INVOICE_PAID_EVENT_SHORT}`;
 export const INVOICE_PAYMENT_FAILED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${INVOICE_PAYMENT_FAILED_EVENT_SHORT}`;
-// 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,
@@ -35,10 +35,11 @@ const statusEnum = z.enum([
     SubscriptionStatuses.canceled,
     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
@@ -103,6 +104,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/dist/billing-foundation/feature.js

@@ -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, EXT_TENANT_DATA, } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { registerConsumerProtection } from "./consumer-protection/register-consent.js";
@@ -58,6 +57,7 @@ import { createBillingPlansQuery } from "./handlers/billing-plans.query.js";
 import { createCheckoutSessionHandler } from "./handlers/create-checkout-session.write.js";
 import { createPortalSessionHandler } from "./handlers/create-portal-session.write.js";
 import { listSubscriptionsQuery } from "./handlers/list-subscriptions.query.js";
+import { createPlanSwitchPreviewQuery } from "./handlers/plan-switch-preview.query.js";
 import { createProcessEventHandler } from "./handlers/process-event.write.js";
 import { processPaymentEventHandler } from "./handlers/process-payment-event.write.js";
 import { createStartPlanCheckoutHandler } from "./handlers/start-plan-checkout.write.js";
@@ -90,7 +90,7 @@ export function createBillingFoundationFeature(options = {}) {
         }),
     };
     return defineFeature(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.");
+        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, 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",
             category: "billing",
@@ -147,18 +147,18 @@ export function createBillingFoundationFeature(options = {}) {
                 [PAYMENT_RECEIVED_EVENT_QN]: applyPaymentReceived,
             },
         });
-        // 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));
@@ -184,6 +184,7 @@ export function createBillingFoundationFeature(options = {}) {
         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/dist/billing-foundation/get-subscription-for-tenant.d.ts

@@ -15,7 +15,7 @@ export type SubscriptionView = {
      *  apply-function started stamping it from `event.createdAt`. */
     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 declare function getSubscriptionForTenant(ctx: HandlerContext, tenantId: string): Promise<SubscriptionView | null>;

package/dist/billing-foundation/get-subscription-for-tenant.js

@@ -1,13 +1,11 @@
 /// <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, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { subscriptionAggregateId } from "./aggregate-id.js";
 import { SUBSCRIPTION_PII_FIELDS } from "./entities.js";
 import { subscriptionsProjectionTable } from "./projection.js";
-/** 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, tenantId) {
     const aggId = subscriptionAggregateId(tenantId);
     const rows = await ctx.db.selectMany(subscriptionsProjectionTable, { id: aggId }, { limit: 1 });

package/dist/billing-foundation/handlers/billing-plans.query.js

@@ -2,20 +2,20 @@
 // benefits, the caller's current tier and per-plan action. Only registered
 // when `createBillingFoundationFeature` gets a `catalog`.
 import * as z from "zod";
-import { findCatalogProvider } from "../checkout-core.js";
+import { filterOfferedProviders, listCatalogProviders, } from "../checkout-core.js";
 import { CONSENT_TEXTS, consentTextVersion, } from "../consumer-protection/consent-text.js";
-import { buildBillingPlans } from "../plan-catalog.js";
+import { buildProviderPlanViews, loadBillingPlansBase, toBillingPlansResult, } from "../plan-catalog.js";
 import { isLegalLinkSet, } from "../types.js";
 const billingPlansSchema = z.object({}).strict();
 export function createBillingPlansQuery(options, catalog) {
     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.",
+        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. With several live providers it also lists each provider's own plans under `providers`.",
         schema: billingPlansSchema,
         access: { roles: catalog.viewRoles },
         handler: async (_query, ctx) => {
-            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;
@@ -32,6 +32,36 @@ export function createBillingPlansQuery(options, catalog) {
         },
     };
 }
+// 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, options, catalog, base) {
+    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, catalog, base, provider, providerTexts, known) {
+    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) {
     return isLegalLinkSet(legalLinks) ? { de: legalLinks, en: legalLinks } : legalLinks;
 }

package/dist/billing-foundation/handlers/create-checkout-session.write.js

@@ -1,18 +1,18 @@
-// create-checkout-session — Tenant-Admin klickt "Upgrade to Pro" (oder
-// wählt zwischen Karte/PayPal/Apple-Pay). Handler findet den
-// providerName aus der payload, lookuppt den Plugin, ruft
-// `plugin.createCheckoutSession(ctx, ...)`, returnt hosted-page-URL.
-// Tenant-Admin wird dorthin redirected.
+// create-checkout-session — Tenant admin clicks "Upgrade to Pro" (or
+// chooses between card/PayPal/Apple Pay). The handler reads providerName
+// from the payload, looks up the plugin, calls
+// `plugin.createCheckoutSession(ctx, ...)`, and returns the hosted-page URL.
+// The tenant admin is redirected there.
 //
-// **Multi-Provider-Pfad:** payload.providerName ist der entityName
-// eines registrierten Plugins ("stripe" / "paypal" / "mollie" / ...).
-// App-Builder zeigt eine UI-Liste der gemounteten provider, Endkunde
-// pickt einen, dieser handler dispatched zum richtigen Plugin.
+// **Multi-provider path:** payload.providerName is the entityName
+// of a registered plugin ("stripe" / "paypal" / "mollie" / ...).
+// The app builder shows a UI list of mounted providers; the customer
+// selects one, and this handler dispatches to the matching plugin.
 //
-// **Tenant-resolution:** ctx.user.tenantId wird als metadata an den
-// Provider mitgegeben. Beim subsequent webhook (subscription.created)
-// liest verifyAndParseWebhook das aus dem provider-payload zurück und
-// resolved den Tenant.
+// **Tenant resolution:** ctx.user.tenantId is passed to the provider as
+// metadata. On the subsequent webhook (subscription.created),
+// verifyAndParseWebhook reads it back from the provider payload and
+// resolves the tenant.
 //
 // **Hardening:** successUrl/cancelUrl must share `options.baseUrl`'s
 // origin; mode:"subscription" requires priceId to be a known price of the
@@ -31,12 +31,13 @@ const createCheckoutSessionSchema = z.object({
     providerName: z.string().min(1).max(50),
     /** Provider-eigene price/plan-ID. */
     priceId: z.string().min(1).max(200),
-    /** Wo der Endkunde nach erfolgreichem checkout landed. */
+    /** Where the customer lands after a successful checkout. */
     successUrl: z.string().url(),
-    /** Wo der Endkunde landed wenn er abbricht. */
+    /** Where the customer lands if they cancel. */
     cancelUrl: z.string().url(),
-    /** Optional: existierender provider-customer wenn der Tenant schon
-     *  einen account beim Provider hat (= Plan-Wechsel statt Neuregistrierung). */
+    /** Optional: existing provider customer when the tenant already
+     *  has an account with the provider (= plan change instead of a new
+     *  registration). */
     providerCustomerId: z.string().max(200).optional(),
     /** Optional: `"payment"` for a one-off checkout (e.g. credit top-up)
      *  instead of a recurring subscription. Defaults to `"subscription"`. */
@@ -89,6 +90,7 @@ export function createCheckoutSessionHandler(options) {
                 tier: mode === "subscription" ? (plugin.priceToTier?.[payload.priceId] ?? null) : null,
                 priceId: payload.priceId,
                 price,
+                providerName: payload.providerName,
                 ...(orderItem && { orderItem }),
             });
             return {

package/dist/billing-foundation/handlers/create-portal-session.write.js

@@ -1,17 +1,16 @@
-// create-portal-session — Tenant-Admin klickt "Manage Subscription".
-// Handler findet die current subscription des Tenants, lookuppt den
-// passenden Plugin (= subscription.providerName-Spalte), ruft
-// `plugin.createPortalSession(ctx, ...)`, returnt hosted-portal-URL.
+// create-portal-session — Tenant admin clicks "Manage Subscription".
+// The handler finds the tenant's current subscription, looks up the matching
+// plugin (= the `subscription.providerName` column), calls
+// `plugin.createPortalSession(ctx, ...)`, and returns the hosted portal URL.
 //
-// **Provider-resolution:** anders als create-checkout-session (= der
-// Tenant wählt einen NEUEN Provider beim Subscribe) ist hier der
-// Provider durch die existing subscription-row festgelegt — Tenant
-// kann nicht zum Portal eines OTHER Providers, weil der ihn nicht
-// kennt.
+// **Provider resolution:** unlike create-checkout-session (where the tenant
+// chooses a NEW provider when subscribing), the provider here is fixed by the
+// existing subscription row. The tenant cannot access another provider's
+// portal because the subscription does not belong to that provider.
 //
-// **returnUrl:** computed server-side via `portalReturnUrl` (catalog's
-// returnPath, or baseUrl itself) — the client no longer supplies one, so
-// there is no client-controlled redirect to harden against.
+// **returnUrl:** computed server-side via `portalReturnUrl` (the catalog's
+// returnPath, or baseUrl itself). The client no longer supplies one, so there
+// is no client-controlled redirect to harden against.
 import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import * as z from "zod";

package/dist/billing-foundation/handlers/list-subscriptions.query.js

@@ -1,7 +1,7 @@
-// list-subscriptions — sysadmin-cross-tenant list-query auf der
-// `read_subscriptions`-projection. Tenant-Admins lesen ihre eigene
-// subscription via getSubscriptionForTenant-helper (= ctx.db ist
-// tenant-scoped, gibt automatisch nur die row des Callers zurück).
+// list-subscriptions — sysadmin cross-tenant list query on the
+// `read_subscriptions` projection. Tenant admins read their own
+// subscription through the getSubscriptionForTenant helper (= ctx.db is
+// tenant-scoped and automatically returns only the caller's row).
 import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import * as z from "zod";
 import { SUBSCRIPTION_PII_FIELDS } from "../entities.js";

package/dist/billing-foundation/handlers/plan-switch-preview.query.d.ts

@@ -0,0 +1,13 @@
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type { BillingPlanCatalog, PlanSwitchPreview } from "../types.ts";
+export type PlanSwitchPreviewResult = {
+    readonly preview: PlanSwitchPreview;
+    readonly target: {
+        readonly tier: string;
+        readonly unitAmount: number;
+        readonly currency: string;
+        readonly interval: "day" | "week" | "month" | "year" | null;
+        readonly intervalCount: number | null;
+    };
+};
+export declare function createPlanSwitchPreviewQuery(catalog: BillingPlanCatalog): QueryHandlerDef;

package/dist/billing-foundation/handlers/plan-switch-preview.query.js

@@ -0,0 +1,48 @@
+// plan-switch-preview — what switching to a tier would cost right now, for
+// providers that switch plans in-app (previewPlanSwitch + applyPlanSwitch).
+// Only registered when `createBillingFoundationFeature` gets a `catalog`.
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { isNonEmptyStringArray } from "../checkout-core.js";
+import { purchaseRolesOf } from "../plan-catalog.js";
+import { preparePlanSwitch } from "../plan-switch.js";
+export function createPlanSwitchPreviewQuery(catalog) {
+    const plans = catalog.plans;
+    if (!isNonEmptyStringArray(plans)) {
+        throw new Error("plan-switch-preview: catalog.plans must not be empty");
+    }
+    const schema = z.object({ tier: z.enum(plans) }).strict();
+    return {
+        name: "plan-switch-preview",
+        description: "Previews what switching the existing subscription to another plan tier costs right now (amount due, tax, credit, effective date) plus the target plan's recurring price. Only for providers that switch plans in-app.",
+        schema,
+        access: { roles: purchaseRolesOf(catalog) },
+        handler: async (query, ctx) => {
+            // @cast-boundary engine-payload — dispatcher-zod-validated payload
+            const { tier } = query.payload;
+            const prepared = await preparePlanSwitch(ctx, catalog, tier, "plan-switch-preview");
+            const { plugin } = prepared.provider;
+            if (!plugin.previewPlanSwitch || !plugin.applyPlanSwitch) {
+                throw new UnprocessableError("plan_switch_not_supported", {
+                    i18nKey: "billing-foundation.errors.planSwitchNotSupported",
+                    message: `subscription-foundation: provider "${prepared.provider.name}" switches plans on a hosted page and has no in-app preview`,
+                });
+            }
+            const preview = await plugin.previewPlanSwitch(ctx, {
+                providerSubscriptionId: prepared.subscription.providerSubscriptionId,
+                targetPriceId: prepared.target.priceId,
+            });
+            const { price } = prepared.target;
+            return {
+                preview,
+                target: {
+                    tier,
+                    unitAmount: price.unitAmount ?? 0,
+                    currency: price.currency,
+                    interval: price.interval,
+                    intervalCount: price.intervalCount,
+                },
+            };
+        },
+    };
+}

package/dist/billing-foundation/handlers/process-event.write.d.ts

@@ -27,6 +27,12 @@ export declare const processEventSchema: z.ZodObject<{
     consentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ProcessEventPayload = z.infer<typeof processEventSchema>;
+export declare function isLateStateEvent(storedEvents: readonly {
+    readonly payload: unknown;
+    readonly metadata: {
+        readonly headers?: Record<string, unknown>;
+    };
+}[], payload: ProcessEventPayload): boolean;
 export declare function clampProviderEventAt(payload: ProcessEventPayload, now: Temporal.Instant): ProcessEventPayload;
 export declare function appendSubscriptionEvent(ctx: HandlerContext, tenantId: string, rawPayload: ProcessEventPayload, now?: Temporal.Instant): Promise<{
     readonly duplicate: boolean;

package/dist/billing-foundation/handlers/process-event.write.js

@@ -1,16 +1,16 @@
-// process-event — programmatic write-handler den der webhook-handler
-// (createSubscriptionWebhookRoute) aufruft NACHDEM Plugin den raw-body
-// verifiziert + zu SubscriptionEvent normalisiert hat.
+// process-event — programmatic write handler called by the webhook handler
+// (createSubscriptionWebhookRoute) AFTER the plugin has verified the raw body
+// and normalized it into a SubscriptionEvent.
 //
-// **ES-Pattern:**
-//   1. Idempotency-check: lädt subscription-stream + scannt nach
-//      bereits gesehenem `metadata.providerEventId`. Provider-Replay
-//      (Stripe-Retry-Storm) sieht denselben event-id → duplicate=true,
-//      kein zweiter append.
-//   2. Type-mapping: SubscriptionEvent.type (= normalisiert vom Plugin)
-//      → einer der 5 ES-event-typen.
-//   3. ctx.unsafeAppendEvent — Inline-projection materialisiert die
-//      `read_subscriptions`-row in derselben TX.
+// **ES pattern:**
+//   1. Idempotency check: loads the subscription stream and scans for an
+//      already-seen `metadata.providerEventId`. A provider replay
+//      (Stripe retry storm) has the same event ID → duplicate=true,
+//      with no second append.
+//   2. Type mapping: SubscriptionEvent.type (= normalized by the plugin)
+//      → one of the 5 ES event types.
+//   3. ctx.unsafeAppendEvent — the inline projection materializes the
+//      `read_subscriptions` row in the same TX.
 import { configuredPiiSubjectKms, encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
@@ -21,9 +21,9 @@ import { INVOICE_PAID_EVENT_QN, INVOICE_PAYMENT_FAILED_EVENT_QN, SUBSCRIPTION_AG
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
 import { BILLING_SUBSCRIPTION_LOCK_NAMESPACE, isSubscriptionBlockingCheckout, isSwitchableSubscriptionStatus, SubscriptionEventTypes, SubscriptionStatuses, } from "../web/constants.js";
 // =============================================================================
-// Input-Schema = der normalisierte SubscriptionEvent (ohne tenantId, der
-// kommt aus event.user.tenantId — der webhook-handler setzt den
-// programmatic-user mit der vom Plugin aufgelösten tenantId).
+// Input schema = the normalized SubscriptionEvent (without tenantId, which
+// comes from event.user.tenantId — the webhook handler sets the
+// programmatic user with the tenantId resolved by the plugin).
 // =============================================================================
 const eventTypeSchema = z.enum([
     SubscriptionEventTypes.created,
@@ -65,7 +65,7 @@ const STATE_EVENT_TYPES = new Set([
     SubscriptionEventTypes.updated,
     SubscriptionEventTypes.canceled,
 ]);
-function isLateStateEvent(storedEvents, payload) {
+export function isLateStateEvent(storedEvents, payload) {
     if (payload.providerEventAtIso === undefined || !STATE_EVENT_TYPES.has(payload.type)) {
         return false;
     }
@@ -79,7 +79,13 @@ function isLateStateEvent(storedEvents, payload) {
         // A stored value that does not parse can never prove a newer event; skip it instead of
         // failing every later delivery of this tenant's stream.
         try {
-            return Temporal.Instant.compare(Temporal.Instant.from(storedAt), incoming) > 0;
+            const order = Temporal.Instant.compare(Temporal.Instant.from(storedAt), incoming);
+            if (order !== 0)
+                return order > 0;
+            // Provider timestamps have second resolution: on a tie a stored cancellation wins over
+            // a non-terminal state, so a reordered same-second `updated` cannot revive a canceled one.
+            return (propertyOf(stored.payload, "status") === SubscriptionStatuses.canceled &&
+                payload.status !== SubscriptionStatuses.canceled);
         }
         catch {
             return false;
@@ -153,9 +159,9 @@ export async function appendSubscriptionEvent(ctx, tenantId, rawPayload, now = T
     //    read_subscriptions row with a single call. The subject is the
     //    TENANT (tenantOwned) — tenant-destroy's subject-keys stage
     //    (eraseSubjectKeys) erases exactly this key, so both copies become
-    //    genuinely unreadable (#800) once that stage runs, not just
+    //    genuinely unreadable once that stage runs, not just
     //    "encrypted at rest". No adapter configured = engine off (fields
-    //    stay plaintext, pre-#724-phase-C behavior) — mirrors how the
+    //    stay plaintext) — mirrors how the
     //    event-store-executor treats an absent piiKms().
     // ---------------------------------------------------------------
     const piiKms = configuredPiiSubjectKms();
@@ -203,9 +209,9 @@ export async function appendSubscriptionEvent(ctx, tenantId, rawPayload, now = T
 // Handler
 // =============================================================================
 //
-// SystemAdmin-only: dieser handler wird ausschließlich vom programmatic
-// webhook-handler aufgerufen (mit einem internal SystemUser), nie vom
-// Tenant-Admin direkt.
+// SystemAdmin-only: this handler is called exclusively by the programmatic
+// webhook handler (with an internal SystemUser), never directly by the
+// tenant admin.
 // 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 an event of a