@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/billing-foundation/projection.js

@@ -1,25 +1,25 @@
-// Inline-projection für `read_subscriptions`. Materialisiert die 5
-// subscription-events in eine row pro Tenant.
+// Inline projection for `read_subscriptions`. Materializes the 5
+// subscription events into one row per tenant.
 //
-// Apply läuft in derselben TX wie ctx.unsafeAppendEvent — Caller sieht
-// seinen Schreib-State sofort (kein dispatcher-tick nötig). PK = event.
-// aggregateId (= deterministic uuidv5 pro Tenant) → replays kollidieren
-// auf der PK statt doppelte rows zu erzeugen.
+// Apply runs in the same transaction as ctx.unsafeAppendEvent, so the caller
+// sees its write state immediately (no dispatcher tick required). The PK is
+// event.aggregateId (= deterministic uuidv5 per tenant), so replays collide
+// on the PK instead of creating duplicate rows.
 //
-// **Production-deployment caveat:** der Generator in
-// `samples/apps/platform/drizzle/generate.ts` scant `feature.entities` —
-// `subscriptionsProjectionTable` ist als raw drizzle-pgTable in der
-// projection registriert, NICHT als r.entity. Apps die subscription-
-// foundation production mounten müssen die Tabelle in ihre eigene
-// `drizzle/generate.ts` ergänzen (= via subscriptionsProjectionTable-
-// import). setupTestStack pusht sie automatisch via r.projection.table.
+// **Production-deployment caveat:** the generator in
+// `samples/apps/platform/drizzle/generate.ts` scans `feature.entities` —
+// `subscriptionsProjectionTable` is registered in the projection as a raw
+// drizzle-pgTable, NOT as r.entity. Apps mounting subscription-foundation in
+// production must add the table to their own `drizzle/generate.ts` (via an
+// import of subscriptionsProjectionTable). setupTestStack pushes it
+// automatically via r.projection.table.
 import { buildEntityTable, insertOnConflictDoNothing, requireEntityTableMeta, upsertOnConflict, } from "@cosmicdrift/kumiko-framework/db";
 import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
 import { paymentRowId } from "./aggregate-id.js";
 import { paymentEntity, subscriptionEntity } from "./entities.js";
-// Drizzle-table-instance aus dem entity-shape. Wird sowohl von der
-// projection-apply als auch von list-query / get-helper genutzt damit
-// alle drei Stellen denselben column-namespace teilen.
+// This Drizzle table instance is derived from the entity shape and is shared
+// by the projection apply, list query, and get helper so all three use the
+// same column namespace.
 export const subscriptionsProjectionTable = buildEntityTable("subscription", subscriptionEntity);
 // Same production-deployment caveat as subscriptionsProjectionTable above:
 // raw drizzle-pgTable, not an r.entity — apps mounting billing-foundation in
@@ -27,8 +27,8 @@ export const subscriptionsProjectionTable = buildEntityTable("subscription", sub
 export const paymentsProjectionTable = buildEntityTable("payment", paymentEntity);
 // Unbranded metas: the apply functions below ARE the executor of these
 // projections, so they may write through the typed helpers.
-const subscriptionsProjectionMeta = requireEntityTableMeta(subscriptionsProjectionTable, "subscription");
-const paymentsProjectionMeta = requireEntityTableMeta(paymentsProjectionTable, "payment");
+export const subscriptionsProjectionMeta = requireEntityTableMeta(subscriptionsProjectionTable, "subscription");
+export const paymentsProjectionMeta = requireEntityTableMeta(paymentsProjectionTable, "payment");
 // =============================================================================
 // Shared helpers
 // =============================================================================
@@ -63,10 +63,10 @@ function cancelAtSetFromPayload(p) {
  *  `getSubscriptionForTenant`'s `lastChangedAt` (staleness check for
  *  incomplete subscriptions) depends on that determinism. */
 async function upsert(tx, event, set, fullPayload) {
-    // INSERT-fallback braucht ALL fields (NOT NULL constraints). Wenn
-    // jemand nur teil-felder updated (z.B. invoice-payment-failed nur
-    // status+tier), nutzen wir trotzdem den vollen payload für den
-    // INSERT-Pfad und nur den teil-`set` für ON CONFLICT.
+    // The INSERT fallback requires ALL fields because of NOT NULL constraints.
+    // If an update changes only some fields (for example, invoice-payment-failed
+    // changes only status+tier), the full payload is still used for the INSERT
+    // path, while only the partial `set` is used for ON CONFLICT.
     const insertCols = {
         id: event.aggregateId,
         tenantId: event.tenantId,
@@ -86,21 +86,21 @@ async function upsert(tx, event, set, fullPayload) {
     });
 }
 // =============================================================================
-// Apply-functions — eine pro event-typ
+// Apply functions — one per event type
 //
-// Alle UPSERT für defensive consistency: ein out-of-order event
-// (z.B. rebuild-from-events) kann in jeder Reihenfolge ankommen
-// und die row korrekt materialisieren.
+// All use UPSERT for defensive consistency: an out-of-order event (for
+// example, during a rebuild-from-events) can arrive in any order and still
+// materialize the row correctly.
 // =============================================================================
-/** subscription-created → UPSERT mit allen Feldern. PK = aggregateId =
- *  subscriptionAggregateId(tenantId), one row pro Tenant. UPSERT damit
- *  Disney+-Wechsel-Pattern (= zweiter Provider sendet create für selben
- *  Tenant) den existing row überschreibt statt PK-conflict. */
+/** subscription-created → UPSERT with all fields. PK = aggregateId =
+ *  subscriptionAggregateId(tenantId), with one row per tenant. UPSERT allows
+ *  the Disney+-change pattern (a second provider sends create for the same
+ *  tenant) to overwrite the existing row instead of causing a PK conflict. */
 export const applySubscriptionCreated = defineApply(async (event, tx) => {
     const full = fullSetFromPayload(event.payload);
     await upsert(tx, event, { ...full, ...cancelAtSetFromPayload(event.payload) }, event.payload);
 });
-/** subscription-updated → UPSERT mit allen Feldern. */
+/** subscription-updated → UPSERT with all fields. */
 export const applySubscriptionUpdated = defineApply(async (event, tx) => {
     const full = fullSetFromPayload(event.payload);
     await upsert(tx, event, { ...full, ...cancelAtSetFromPayload(event.payload) }, event.payload);
@@ -115,8 +115,9 @@ export const applySubscriptionCanceled = defineApply(async (event, tx) => {
         ...cancelAtSetFromPayload(p),
     }, p);
 });
-/** invoice-paid → state-update (status, tier, currentPeriodEnd).
- *  Invoice-history selbst lebt im event-store (= Replay-fähig). */
+/** invoice-paid → state update (status, tier, currentPeriodEnd).
+ *  The invoice history itself lives in the event store, so it remains
+ *  replayable. */
 export const applyInvoicePaid = defineApply(async (event, tx) => {
     const p = event.payload;
     await upsert(tx, event, {
@@ -126,10 +127,10 @@ export const applyInvoicePaid = defineApply(async (event, tx) => {
         ...cancelAtSetFromPayload(p),
     }, p);
 });
-/** invoice-payment-failed → status (typisch past_due) + tier. tier-
- *  engine liest die row + entscheidet ob downgrade. currentPeriodEnd
- *  bewusst nicht — die Period ist noch nicht "vorbei", payment hat
- *  nur nicht geklappt. */
+/** invoice-payment-failed → status (typically past_due) + tier. The tier
+ *  engine reads the row and decides whether to downgrade. currentPeriodEnd is
+ *  intentionally unchanged: the period has not "ended"; payment simply
+ *  failed. */
 export const applyInvoicePaymentFailed = defineApply(async (event, tx) => {
     const p = event.payload;
     await upsert(tx, event, { status: p.status, tier: p.tier, ...cancelAtSetFromPayload(p) }, p);

package/dist/billing-foundation/subscription-tier-sync.js

@@ -1,7 +1,7 @@
 // Generic Stripe/PayPal-webhook → tier-engine sync route. Extracted from the
-// near-identical webhook-route.ts app copies in show-pony and publicstatus
-// (infra#446) — the only per-app variables were the TierName union/default,
-// so it is now a factory parameter.
+// near-identical webhook-route.ts app copies in show-pony and publicstatus — the
+// only per-app variables were the TierName union/default, so it is now a factory
+// parameter.
 import { isTierAssignmentSource, TierAssignmentSources, TierEngineHandlers, TierEngineQueries, tierAssignmentAggregateId, } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { subscriptionAggregateId } from "./aggregate-id.js";

package/dist/billing-foundation/tenant-destroy-hook.d.ts

@@ -1,12 +1,12 @@
 import { type TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
 export declare const SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON = "tenant-destroy looks up the compliance profile and archives the subscription event-stream before the projection row is redacted/deleted";
 export declare const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON = "tenant-destroy looks up the compliance profile and archives the payment event-stream before the projection rows are redacted/deleted";
-/** Tenant-destroy hook for billing PII (#800). HGB retains the accounting
+/** Tenant-destroy hook for billing PII. HGB retains the accounting
  *  row but redacts the two provider-subject PII fields; other profiles
  *  hard-delete the row. Either way the subscription stream is archived so a
  *  future projection rebuild can't resurrect what was erased. */
 export declare function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void>;
-/** Tenant-destroy hook for payment PII (#800). Unlike subscriptionTenantDestroyHook
+/** Tenant-destroy hook for payment PII. Unlike subscriptionTenantDestroyHook
  *  (one row per tenant, targeted by `id`), a tenant can have many payment
  *  rows — the predicate here is `tenantId`, not `id`. The payment-stream
  *  itself is still one stream per tenant (paymentAggregateId), so

package/dist/billing-foundation/tenant-destroy-hook.js

@@ -3,7 +3,7 @@ import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
 import { resolveProfileForTenant } from "../compliance-profiles/index.js";
 import { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id.js";
 import { PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE } from "./events.js";
-import { paymentsProjectionTable, subscriptionsProjectionTable } from "./projection.js";
+import { paymentsProjectionMeta, subscriptionsProjectionMeta } from "./projection.js";
 // providerCustomerId/providerSubscriptionId are `personal: "tenant"` on the
 // entity (envelope-encrypted with the tenant subject key, see entities.ts) —
 // eraseSubjectKeys crypto-shreds them for tenants that hard-delete. HGB
@@ -13,7 +13,7 @@ const REDACTED_PII_VALUE = "[erased]";
 // Compliance-profile lookup and event-stream archive both sit outside TenantDb's own methods — need the escape hatch.
 export const SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON = "tenant-destroy looks up the compliance profile and archives the subscription event-stream before the projection row is redacted/deleted";
 export const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON = "tenant-destroy looks up the compliance profile and archives the payment event-stream before the projection rows are redacted/deleted";
-/** Tenant-destroy hook for billing PII (#800). HGB retains the accounting
+/** Tenant-destroy hook for billing PII. HGB retains the accounting
  *  row but redacts the two provider-subject PII fields; other profiles
  *  hard-delete the row. Either way the subscription stream is archived so a
  *  future projection rebuild can't resurrect what was erased. */
@@ -25,10 +25,10 @@ export async function subscriptionTenantDestroyHook(ctx) {
     });
     const aggregateId = subscriptionAggregateId(ctx.tenantId);
     if (profile.key === "de-hr-dsgvo-hgb") {
-        await ctx.db.updateMany(subscriptionsProjectionTable, { providerCustomerId: REDACTED_PII_VALUE, providerSubscriptionId: REDACTED_PII_VALUE }, { id: aggregateId });
+        await ctx.db.updateMany(subscriptionsProjectionMeta, { providerCustomerId: REDACTED_PII_VALUE, providerSubscriptionId: REDACTED_PII_VALUE }, { id: aggregateId });
     }
     else {
-        await ctx.db.deleteMany(subscriptionsProjectionTable, { id: aggregateId });
+        await ctx.db.deleteMany(subscriptionsProjectionMeta, { id: aggregateId });
     }
     await archiveStream(ctx.db.unsafeRaw(), {
         tenantId: ctx.tenantId,
@@ -38,7 +38,7 @@ export async function subscriptionTenantDestroyHook(ctx) {
         reason: "tenant_destroy",
     });
 }
-/** Tenant-destroy hook for payment PII (#800). Unlike subscriptionTenantDestroyHook
+/** Tenant-destroy hook for payment PII. Unlike subscriptionTenantDestroyHook
  *  (one row per tenant, targeted by `id`), a tenant can have many payment
  *  rows — the predicate here is `tenantId`, not `id`. The payment-stream
  *  itself is still one stream per tenant (paymentAggregateId), so
@@ -51,10 +51,10 @@ export async function paymentTenantDestroyHook(ctx) {
     });
     const aggregateId = paymentAggregateId(ctx.tenantId);
     if (profile.key === "de-hr-dsgvo-hgb") {
-        await ctx.db.updateMany(paymentsProjectionTable, { providerCustomerId: REDACTED_PII_VALUE }, { tenantId: ctx.tenantId });
+        await ctx.db.updateMany(paymentsProjectionMeta, { providerCustomerId: REDACTED_PII_VALUE }, { tenantId: ctx.tenantId });
     }
     else {
-        await ctx.db.deleteMany(paymentsProjectionTable, {
+        await ctx.db.deleteMany(paymentsProjectionMeta, {
             tenantId: ctx.tenantId,
         });
     }

package/dist/billing-foundation/types.d.ts

@@ -12,32 +12,31 @@ export type SubscriptionEvent = {
      *  `parsed.kind === BillingEventKinds.payment` correctly, because only
      *  PaymentEvent["kind"] can take that value. */
     readonly kind?: typeof BillingEventKinds.subscription;
-    /** Provider-eigene Event-ID — UNIQUE-key für Idempotency.
-     *  Stripe: "evt_..."; Mollie: payment-id oder subscription-id. */
+    /** Provider-owned event ID — UNIQUE key for idempotency.
+     *  Stripe: "evt_..."; Mollie: payment-id or subscription-id. */
     readonly providerEventId: string;
     /** Discriminator — welcher Plugin diesen Event geliefert hat. */
     readonly providerName: string;
     /** Normalisierter Event-Type. Plugin filtert provider-spezifische
      *  Sub-Types raus (Stripe hat ~80 Event-types, wir kennen 5). */
     readonly type: SubscriptionEventType;
-    /** Plattform-Tenant-ID (provider-customer-metadata oder lookup
-     *  via providerCustomerId). Plugin macht die resolution. */
+    /** Platform tenant ID (provider-customer metadata or lookup via
+     *  providerCustomerId). The plugin performs the resolution. */
     readonly tenantId: string;
     /** Consent id echoed back from checkout metadata; omitted when absent or
      *  malformed. */
     readonly consentId?: string;
-    /** Provider-eigene customer-id für späteren Lookup bei events
-     *  ohne metadata. */
+    /** Provider-owned customer ID for later lookup when events lack
+     *  metadata. */
     readonly providerCustomerId: string;
     /** Provider-eigene subscription-id. */
     readonly providerSubscriptionId: string;
     /** Normalisierter status. */
     readonly status: SubscriptionStatus;
-    /** Resolved tier — Plugin liest die price-id aus dem event und
-     *  mapped via plugin-eigenem `<plugin>:config:price-to-tier` auf
-     *  einen tier-name. Wenn der price-id im Mapping fehlt, returnt
-     *  der Plugin null aus verifyAndParseWebhook (= "unknown event,
-     *  ignore"). */
+    /** Resolved tier — the plugin reads the price ID from the event and
+     *  maps it through the plugin's `<plugin>:config:price-to-tier` to a
+     *  tier name. If the price ID is absent from the mapping, the plugin
+     *  returns null from verifyAndParseWebhook (= "unknown event, ignore"). */
     readonly tier: string;
     /** ISO-timestamp wann die aktuelle Billing-Period endet. */
     readonly currentPeriodEnd: string;
@@ -76,6 +75,8 @@ export type PaymentEvent = {
     readonly priceId: string;
 };
 export type SubscriptionProviderPlugin = {
+    /** Human-readable provider name for the plan panel's provider switch. */
+    readonly displayName?: string;
     /**
      * Verify webhook signature + parse provider-event into normalized
      * form. **Pre-tenant-resolution** — no HandlerContext, because at
@@ -106,30 +107,30 @@ export type SubscriptionProviderPlugin = {
      */
     readonly verifyAndParseWebhook: (rawBody: string, headers: Record<string, string>, systemSecrets?: SecretsContext) => Promise<SubscriptionEvent | PaymentEvent | null>;
     /**
-     * **Post-tenant-resolution** — wird aus dem
-     * `create-checkout-session`-write-handler gerufen. Plugin baut
-     * eine provider-eigene checkout-session und returnt die hosted-
-     * page-URL — Tenant-Admin wird dorthin redirected, schließt den
-     * Bezahl-Flow ab, Provider sendet `subscription.created`-webhook
-     * mit `metadata.tenantId` zurück.
+     * **Post-tenant-resolution** — called from the
+     * `create-checkout-session` write handler. The plugin builds a
+     * provider-specific checkout session and returns its hosted-page URL;
+     * the tenant admin is redirected there to complete payment, and the
+     * provider sends a `subscription.created` webhook with
+     * `metadata.tenantId`.
      *
-     * Optional: Apple-IAP hat keinen Web-Checkout (alles in der App).
-     * Apps die ausschließlich Apple-IAP nutzen lassen das weg.
+     * Optional: Apple-IAP has no web checkout (everything happens in the app).
+     * Apps that use only Apple-IAP omit this field.
      */
     readonly createCheckoutSession?: (ctx: HandlerContext, options: {
-        /** Provider-eigene price/plan-ID die der Endkunde abonniert. */
+        /** Provider-owned price/plan ID that the customer subscribes to. */
         readonly priceId: string;
-        /** Plattform-Tenant-ID — landet als metadata im checkout-session
-         *  damit der subsequent webhook den tenant resolved (siehe
-         *  `verifyAndParseWebhook`'s metadata.tenantId-lookup). */
+        /** Platform tenant ID — stored as metadata in the checkout session
+         *  so the subsequent webhook can resolve the tenant (see the
+         *  `verifyAndParseWebhook` metadata.tenantId lookup). */
         readonly tenantId: string;
-        /** Wo der Endkunde nach erfolgreichem checkout landed. */
+        /** Where the customer lands after a successful checkout. */
         readonly successUrl: string;
-        /** Wo der Endkunde landed wenn er abbricht. */
+        /** Where the customer lands if they cancel. */
         readonly cancelUrl: string;
-        /** Optional: existierende provider-customer-id wenn der Tenant
-         *  schon einen Account beim Provider hat. Sonst legt der Provider
-         *  beim checkout einen neuen customer an. */
+        /** Optional: existing provider customer ID when the tenant already
+         *  has an account with the provider. Otherwise, the provider
+         *  creates a new customer during checkout. */
         readonly providerCustomerId?: string;
         /** Checkout mode. `"subscription"` (default) starts a recurring
          *  billing flow; `"payment"` a one-off checkout (e.g. pay-per-use
@@ -147,17 +148,17 @@ export type SubscriptionProviderPlugin = {
         readonly url: string;
     }>;
     /**
-     * **Post-tenant-resolution** — wird aus einem write-handler gerufen
-     * mit voll-aufgelöstem ctx. Erstellt einen self-service Portal-Link.
+     * **Post-tenant-resolution** — called from a write handler with a
+     * fully resolved ctx. Creates a self-service Portal link.
      * Stripe: customer-portal-session, Mollie: hosted-management-page.
-     * Tenant-Admin klickt darauf um Subscription selbst zu verwalten
-     * (cancel, payment-method, ...).
+     * The tenant admin uses it to manage the subscription themselves
+     * (cancel, payment method, ...).
      *
-     * Optional weil nicht jeder Provider einen Portal-Pattern hat
-     * (Apple-IAP managed Subs in der Apple-App, kein Web-Portal).
-     * Plugin der das nicht supported kann das Field weglassen — foundation
-     * returnt dann "portal_not_supported"-error wenn ein Tenant-Admin
-     * den Portal-Link anfordert.
+     * Optional because not every provider has a Portal pattern
+     * (Apple-IAP subscriptions are managed in the Apple app, with no web
+     * Portal). A plugin that does not support this can omit the field;
+     * the foundation then returns a "portal_not_supported" error when a
+     * tenant admin requests the Portal link.
      */
     readonly createPortalSession?: (ctx: HandlerContext, options: {
         readonly providerCustomerId: string;
@@ -166,10 +167,10 @@ export type SubscriptionProviderPlugin = {
         readonly url: string;
     }>;
     /**
-     * Optional: Cancel-aus-der-App-API. Wenn nicht implementiert, kann
-     * der Tenant nur über den Customer-Portal-Link cancellen (oder gar
-     * nicht, wenn auch createPortalSession fehlt — dann ist
-     * Cancel-Flow Provider-Dashboard-only).
+     * Optional: in-app cancellation API. If not implemented, the tenant
+     * can cancel only through the Customer Portal link (or not at all if
+     * createPortalSession is also missing — the cancellation flow is then
+     * provider-dashboard-only).
      */
     readonly cancelSubscription?: (ctx: HandlerContext, options: {
         readonly providerSubscriptionId: string;
@@ -229,6 +230,24 @@ export type SubscriptionProviderPlugin = {
     }) => Promise<{
         readonly url: string;
     }>;
+    /**
+     * In-app plan switch, step 1: what the switch would cost right now. Together
+     * with `applyPlanSwitch` an alternative to the hosted `createPlanSwitchSession`.
+     */
+    readonly previewPlanSwitch?: (ctx: HandlerContext, options: {
+        readonly providerSubscriptionId: string;
+        readonly targetPriceId: string;
+    }) => Promise<PlanSwitchPreview>;
+    /**
+     * In-app plan switch, step 2: performs the switch at the provider. The
+     * state change itself arrives later through the webhook.
+     */
+    readonly applyPlanSwitch?: (ctx: HandlerContext, options: {
+        readonly providerSubscriptionId: string;
+        readonly targetPriceId: string;
+        readonly tenantId: string;
+        readonly consentId?: string;
+    }) => Promise<void>;
     /**
      * Fetches the live provider-side state of one subscription, for the
      * `sync-subscriptions` backfill job — catches drift (e.g. a `cancel_at`
@@ -242,6 +261,17 @@ export type SubscriptionProviderPlugin = {
      */
     readonly retrieveSubscription?: (ctx: HandlerContext, providerSubscriptionId: string) => Promise<ProviderSubscriptionSnapshot | null>;
 };
+export type PlanSwitchPreview = {
+    /** Charged immediately, smallest currency unit, tax included. */
+    readonly amountDueNow: number;
+    /** Tax part of `amountDueNow`; null when the provider reports none. */
+    readonly tax: number | null;
+    /** Lower-case ISO currency code. */
+    readonly currency: string;
+    /** Credit for the unused time on the old plan, smallest currency unit. */
+    readonly credit: number;
+    readonly effectiveAt: string;
+};
 export type ProviderSubscriptionSnapshot = {
     readonly providerCustomerId: string;
     readonly providerSubscriptionId: string;
@@ -297,7 +327,8 @@ export type BillingPlanCatalog<TTier extends string = string> = {
      *  `baseUrl` itself when unset) and by `switch-plan` after a plan switch
      *  (defaults to `successPath` there instead). */
     readonly returnPath?: string;
-    /** Defaults to the only registered provider exposing `priceToTier`. */
+    /** Restricts the catalog to one provider; defaults to every registered
+     *  provider exposing `priceToTier`. */
     readonly providerName?: string;
     /** Rendered as the last card, no price, visible to `viewRoles` regardless of `purchaseRoles`. */
     readonly contact?: BillingPlanContactCard;
@@ -320,6 +351,14 @@ export type ConsumerProtectionOptions = {
     readonly termsTextBlock: string;
     /** Per-locale VAT note; must carry at least `de` and `en`. */
     readonly vatNote: Readonly<Record<string, string>>;
+    /** Per-provider texts keyed by provider name, e.g. for a merchant-of-record
+     *  provider that issues the invoice and VAT itself. `vatNote` here replaces
+     *  the global one in that provider's confirmation mail; `checkoutNote` is
+     *  shown under the provider choice. de and en are required for each text. */
+    readonly providerTexts?: Readonly<Record<string, {
+        readonly vatNote?: Readonly<Record<string, string>>;
+        readonly checkoutNote?: Readonly<Record<string, string>>;
+    }>>;
     readonly operatorEmail: string;
     /** Where the public § 312k declaration is reachable. `"tenant-host"`
      *  (default): on a host that resolves a tenant. `"platform"`: also on a
@@ -373,6 +412,15 @@ export type BillingPlanView = {
     readonly isCurrent: boolean;
     readonly action: BillingPlanAction;
 };
+export type BillingProviderView = {
+    readonly name: string;
+    readonly displayName: string;
+    readonly note?: Readonly<Record<string, string>>;
+    readonly plans: readonly BillingPlanView[];
+};
+export declare function canSwitchPlansInApp(plugin: SubscriptionProviderPlugin): boolean;
+/** A provider switches plans via a hosted session or via in-app preview + apply. */
+export declare function canSwitchPlans(plugin: SubscriptionProviderPlugin | null): boolean;
 export type BillingPlansResult = {
     readonly enabled: boolean;
     readonly currentTier: {
@@ -389,6 +437,13 @@ export type BillingPlansResult = {
     } | null;
     readonly canPurchase: boolean;
     readonly plans: readonly BillingPlanView[];
+    /** Present when more than one provider is offered, or the single offered
+     *  provider has a `providerTexts` checkout note. `plans` above are the first
+     *  entry's plans. */
+    readonly providers?: readonly BillingProviderView[];
+    /** True when the subscription's provider switches plans in-app (preview +
+     *  confirm) instead of on a hosted page. */
+    readonly inAppPlanSwitch?: true;
     /** Present only when `catalog.contact` is configured. */
     readonly contact?: BillingPlanContactCard;
     /** Present only when `consumerProtection` is configured. */

package/dist/billing-foundation/types.js

@@ -1,29 +1,29 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-// Plugin-Contract + Domain-Types der subscription-foundation. Provider-
-// Plugins (subscription-stripe, subscription-mollie, ...) implementieren
-// `SubscriptionProviderPlugin` und registrieren via
+// Plugin contract and domain types for subscription-foundation. Provider
+// plugins (subscription-stripe, subscription-mollie, ...) implement
+// `SubscriptionProviderPlugin` and register via
 // `r.useExtension("subscriptionProvider", "<name>", { build })`.
 //
 // **Two-phase plugin contract:**
-//   1. **Pre-tenant-resolution:** `verifyAndParseWebhook` läuft BEVOR
-//      ein Tenant aus dem Event aufgelöst ist — kein HandlerContext
-//      verfügbar. Das **Webhook-secret ist app-wide** (App-Owner's
-//      Stripe-/PayPal-Account, nicht Tenant-Sache). Damit ein Plugin den
-//      secret ZUR LAUFFZEIT aus dem secrets-Feature lesen kann (statt aus
-//      einem mount-time-Closure), reicht der webhook-handler einen
-//      optionalen system-scoped `SecretsContext` als 3. Arg durch — der
-//      Plugin liest seine app-wide-Secrets daraus un-audited unter
-//      SYSTEM_TENANT_ID. Plugins, die ihre Keys weiter aus einem Closure
-//      halten (z.B. mollie), ignorieren den Param → backward-compatible.
+//   1. **Pre-tenant-resolution:** `verifyAndParseWebhook` runs BEFORE
+//      a tenant is resolved from the event, so no HandlerContext is
+//      available. The **webhook secret is app-wide** (the App Owner's
+//      Stripe-/PayPal-account, not tenant-specific). To let a plugin read
+//      the secret from the secrets feature AT RUNTIME (instead of a
+//      mount-time closure), the webhook handler passes an optional
+//      system-scoped `SecretsContext` as the third argument. The plugin
+//      reads its app-wide secrets from it without auditing under
+//      SYSTEM_TENANT_ID. Plugins that keep their keys in a closure
+//      (e.g. mollie) ignore the parameter → backward-compatible.
 //   2. **Post-tenant-resolution:** `createPortalSession` +
-//      `cancelSubscription` werden aus regulären write-handlern
-//      gerufen mit voll-aufgelöstem HandlerContext. Plugin kann
-//      hier ctx.config + ctx.secrets nutzen für tenant-spezifische
-//      Konfiguration (z.B. tenant-eigene customer-id-mapping).
+//      `cancelSubscription` are called from regular write handlers with
+//      a fully resolved HandlerContext. The plugin can use ctx.config +
+//      ctx.secrets for tenant-specific configuration (e.g. tenant-owned
+//      customer-id mappings).
 //
-// Foundation nutzt nur den common-subset der Provider-Funktionalität —
-// proration, multi-currency, coupons etc. bleiben provider-spezifisch
-// und sind über den Customer-Portal-Link erreichbar.
+// Foundation uses only the common subset of provider functionality;
+// proration, multi-currency, coupons, etc. remain provider-specific and
+// are available through the Customer Portal link.
 import { SUBSCRIPTION_PROVIDER_EXTENSION, } from "./web/constants.js";
 // =============================================================================
 // Provider price + billing-plans catalog
@@ -33,3 +33,12 @@ export const KNOWN_RECURRING_INTERVALS = ["day", "week", "month", "year"];
 export function isLegalLinkSet(links) {
     return "terms" in links;
 }
+export function canSwitchPlansInApp(plugin) {
+    return plugin.previewPlanSwitch !== undefined && plugin.applyPlanSwitch !== undefined;
+}
+/** A provider switches plans via a hosted session or via in-app preview + apply. */
+export function canSwitchPlans(plugin) {
+    if (plugin === null)
+        return false;
+    return plugin.createPlanSwitchSession !== undefined || canSwitchPlansInApp(plugin);
+}

package/dist/billing-foundation/validate-options.js

@@ -20,6 +20,22 @@ function isRootRelativeOrHttpsUrl(link) {
         return false;
     }
 }
+function validateProviderTexts(cp) {
+    for (const [providerName, texts] of Object.entries(cp.providerTexts ?? {})) {
+        for (const [textName, text] of [
+            ["vatNote", texts.vatNote],
+            ["checkoutNote", texts.checkoutNote],
+        ]) {
+            if (text === undefined)
+                continue;
+            for (const locale of ["de", "en"]) {
+                if (!text[locale]?.trim()) {
+                    throw new Error(`createBillingFoundationFeature: consumerProtection.providerTexts.${providerName}.${textName} needs a non-empty "${locale}" entry.`);
+                }
+            }
+        }
+    }
+}
 function validateConsumerProtection(cp) {
     if (cp.termsTextBlock.trim() === "") {
         throw new Error("createBillingFoundationFeature: consumerProtection.termsTextBlock is empty.");
@@ -29,6 +45,7 @@ function validateConsumerProtection(cp) {
             throw new Error(`createBillingFoundationFeature: consumerProtection.vatNote needs a non-empty "${locale}" entry.`);
         }
     }
+    validateProviderTexts(cp);
     if (!z.email().safeParse(cp.operatorEmail).success) {
         throw new Error(`createBillingFoundationFeature: consumerProtection.operatorEmail "${cp.operatorEmail}" is not a valid email address.`);
     }