@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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

@@ -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 type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
@@ -41,12 +41,12 @@ import {
 import type { ConsentLocale } from "./web/consumer-protection/consent-locale.ts";
 
 // =============================================================================
-// Normalisierter Webhook-Event
+// Normalized Webhook Event
 // =============================================================================
 //
-// Der Plugin parsed den raw provider-payload und liefert diese Form
-// zurück. Foundation kennt KEINE Stripe-/Mollie-types direkt — der
-// Plugin abstrahiert.
+// The plugin parses the raw provider payload and returns this shape.
+// Foundation has no direct knowledge of Stripe-/Mollie-types; the plugin
+// provides the abstraction.
 
 export type SubscriptionEvent = {
   /** Discriminator against PaymentEvent. Optional (instead of required) so
@@ -55,32 +55,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;
@@ -137,6 +136,9 @@ export type PaymentEvent = {
 // =============================================================================
 
 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
@@ -172,32 +174,32 @@ export type SubscriptionProviderPlugin = {
   ) => 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
@@ -215,17 +217,17 @@ export type SubscriptionProviderPlugin = {
   ) => Promise<{ 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,
@@ -236,10 +238,10 @@ export type SubscriptionProviderPlugin = {
   ) => Promise<{ 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,
@@ -314,6 +316,32 @@ 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`
@@ -331,6 +359,18 @@ export type SubscriptionProviderPlugin = {
   ) => 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;
@@ -400,7 +440,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;
@@ -430,6 +471,19 @@ 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
@@ -491,6 +545,23 @@ export type BillingPlanView = {
   readonly action: BillingPlanAction;
 };
 
+export type BillingProviderView = {
+  readonly name: string;
+  readonly displayName: string;
+  readonly note?: Readonly<Record<string, string>>;
+  readonly plans: readonly BillingPlanView[];
+};
+
+export function canSwitchPlansInApp(plugin: SubscriptionProviderPlugin): boolean {
+  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: SubscriptionProviderPlugin | null): boolean {
+  if (plugin === null) return false;
+  return plugin.createPlanSwitchSession !== undefined || canSwitchPlansInApp(plugin);
+}
+
 export type BillingPlansResult = {
   readonly enabled: boolean;
   readonly currentTier: {
@@ -507,6 +578,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/packages/bundled-features/src/billing-foundation/validate-options.ts

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

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

@@ -24,24 +24,13 @@ import {
   SubscriptionFoundationQueries,
   SubscriptionStatuses,
 } from "./constants.ts";
+import { resolveConsentLocale } from "./consumer-protection/consent-locale.ts";
 import { localizedParams } from "./localized-params.ts";
+import { cheapestPrice, intervalKey, pricesDiffer, renewalKey, tierPrices } from "./plan-price.ts";
+import { PlanSwitchConfirmDialog } from "./plan-switch-confirm-dialog.tsx";
 
 type UseTranslation = ReturnType<typeof useTranslation>;
 
-function intervalKey(price: BillingPlanView["price"]): string | undefined {
-  if (price === null || price.interval === null) return undefined;
-  return price.intervalCount !== null && price.intervalCount > 1
-    ? `billing-foundation.plans.everyInterval.${price.interval}`
-    : `billing-foundation.plans.perInterval.${price.interval}`;
-}
-
-function renewalKey(price: BillingPlanView["price"]): string | undefined {
-  if (price === null || price.interval === null) return undefined;
-  return price.intervalCount !== null && price.intervalCount > 1
-    ? `billing-foundation.consent.renewsEvery.${price.interval}`
-    : `billing-foundation.consent.renews.${price.interval}`;
-}
-
 /** Which action the plan "would" offer if it weren't blocked — mirrors
  *  plan-catalog.ts's own decision tree, since `unavailable` collapses both
  *  "would checkout" and "would switch" into one action and the disabled CTA
@@ -78,10 +67,10 @@ function manageOrReactivateAction(
   };
 }
 
-/** `!canPurchase` hides every CTA outright (spec: "keine CTAs, Hinweis
- *  purchaseNotAllowed") — distinct from the `unavailable` action's disabled
- *  CTA, which still shows a button (e.g. for a plan whose price failed to
- *  load) so this check runs before the general unavailable-fallback. */
+/** `!canPurchase` hides every CTA outright (see `purchaseNotAllowed`) — distinct
+ *  from the `unavailable` action's disabled CTA, which still shows a button
+ *  (for example, when a plan's price failed to load), so this check runs
+ *  before the general unavailable fallback. */
 
 function planCta(
   plan: BillingPlanView,
@@ -135,12 +124,25 @@ export function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode {
   const [redirecting, setRedirecting] = useState(false);
   const [consentTier, setConsentTier] = useState<string | null>(null);
   const [cancelOpen, setCancelOpen] = useState(false);
+  const [chosenProvider, setChosenProvider] = useState<string | null>(null);
+  const [switchTier, setSwitchTier] = useState<string | null>(null);
+  const [switchRequested, setSwitchRequested] = useState(false);
+
+  // Only present when the tenant can choose (several offered providers) or
+  // the single offered provider has a note; absent means the server decides.
+  const providers = query.data?.providers;
+  const activeProvider = providers?.find((p) => p.name === chosenProvider) ?? providers?.[0];
+  const providerArg = activeProvider ? { providerName: activeProvider.name } : {};
 
   async function orderWithConsent(
     tier: string,
-    consent: CheckoutConsentPayload,
+    consent: CheckoutConsentPayload | undefined,
   ): Promise<WriteResult<{ readonly url: string }>> {
-    const result = await checkoutMutation.mutate({ tier, consent });
+    const result = await checkoutMutation.mutate({
+      tier,
+      ...(consent !== undefined && { consent }),
+      ...providerArg,
+    });
     if (result.isSuccess) {
       setRedirecting(true);
       window.location.assign(result.data.url);
@@ -149,13 +151,23 @@ export function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode {
   }
 
   async function handleAction(tier: string, kind: "checkout" | "switch"): Promise<void> {
-    if (kind === "checkout" && query.data?.consumerProtection !== undefined) {
+    if (
+      kind === "checkout" &&
+      (query.data?.consumerProtection !== undefined || (providers?.length ?? 0) > 1)
+    ) {
+      setChosenProvider(null);
       setConsentTier(tier);
       return;
     }
+    if (kind === "switch" && query.data?.inAppPlanSwitch) {
+      setSwitchTier(tier);
+      return;
+    }
     setRedirecting(true);
-    const mutation = kind === "checkout" ? checkoutMutation : switchMutation;
-    const result = await mutation.mutate({ tier });
+    const result =
+      kind === "checkout"
+        ? await checkoutMutation.mutate({ tier, ...providerArg })
+        : await switchMutation.mutate({ tier });
     if (result.isSuccess) {
       window.location.assign(result.data.url);
     } else {
@@ -189,6 +201,9 @@ export function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode {
   }
   if (!query.data) return null;
   const result: BillingPlansResult = query.data;
+  // Cards show the first provider's price; the dialog then follows the chosen one.
+  const shownPlans = providers?.[0]?.plans ?? result.plans;
+  const dialogPlans = activeProvider?.plans ?? result.plans;
 
   // The consent dialog shows the checkout error itself.
   const mutationError =
@@ -199,7 +214,11 @@ export function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode {
     result.subscription !== null && !result.subscription.terminal && result.canPurchase;
 
   function toCardProps(plan: BillingPlanView) {
-    const key = intervalKey(plan.price);
+    const comparable =
+      providers !== undefined && providers.length > 1 ? tierPrices(providers, plan.tier) : [];
+    const fromPrice = pricesDiffer(comparable) ? cheapestPrice(comparable) : undefined;
+    const shownPrice = fromPrice ?? plan.price;
+    const key = intervalKey(shownPrice);
     return {
       title: t(plan.labelKey),
       description:
@@ -214,13 +233,14 @@ export function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode {
       price:
         !result.enabled && plan.isCurrent
           ? undefined
-          : plan.price === null
+          : shownPrice === null
             ? null
             : {
-                amount: formatMoney(plan.price.unitAmount, plan.price.currency, locale),
+                amount: formatMoney(shownPrice.unitAmount, shownPrice.currency, locale),
+                ...(fromPrice !== undefined && { prefix: t("billing-foundation.plans.priceFrom") }),
                 ...(key !== undefined && {
                   period: t(key, {
-                    count: new Intl.NumberFormat(locale).format(plan.price.intervalCount ?? 1),
+                    count: new Intl.NumberFormat(locale).format(shownPrice.intervalCount ?? 1),
                   }),
                 }),
               },
@@ -239,12 +259,41 @@ export function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode {
   // rendered plans is the current one, a synthetic current-tier card (no
   // price, no cta) keeps it visible regardless of enabled/disabled.
   const consentPlan =
-    consentTier !== null ? result.plans.find((plan) => plan.tier === consentTier) : undefined;
+    consentTier !== null ? dialogPlans.find((plan) => plan.tier === consentTier) : undefined;
+  const switchPlan =
+    switchTier !== null ? shownPlans.find((plan) => plan.tier === switchTier) : undefined;
   const consumerProtection = result.consumerProtection;
-  const currentTierInPlans = result.plans.some((plan) => plan.isCurrent);
-  const visiblePlans = result.enabled
-    ? result.plans
-    : result.plans.filter((plan) => plan.isCurrent);
+  const noteLocale = resolveConsentLocale(locale);
+  const noteOf = (provider: { readonly note?: Readonly<Record<string, string>> }) =>
+    provider.note?.[noteLocale] ?? provider.note?.["en"];
+  const singleProviderNote =
+    providers !== undefined && providers.length === 1 && providers[0] !== undefined
+      ? noteOf(providers[0])
+      : undefined;
+  function providerChoiceFor(tier: string) {
+    if (providers === undefined || providers.length < 2 || activeProvider === undefined) {
+      return undefined;
+    }
+    const prices = tierPrices(providers, tier);
+    const showPrices = pricesDiffer(prices);
+    return {
+      value: activeProvider.name,
+      onChange: setChosenProvider,
+      options: providers.map((provider) => {
+        const price = provider.plans.find((plan) => plan.tier === tier)?.price;
+        const note = noteOf(provider);
+        return {
+          value: provider.name,
+          title: provider.displayName,
+          ...(note !== undefined && { description: note }),
+          ...(showPrices &&
+            price && { aside: formatMoney(price.unitAmount, price.currency, locale) }),
+        };
+      }),
+    };
+  }
+  const currentTierInPlans = shownPlans.some((plan) => plan.isCurrent);
+  const visiblePlans = result.enabled ? shownPlans : shownPlans.filter((plan) => plan.isCurrent);
 
   return (
     <div className="flex flex-col gap-4" data-testid="billing-plans-panel">
@@ -258,6 +307,11 @@ export function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode {
           {t("billing-foundation.plans.purchaseNotAllowed")}
         </Banner>
       )}
+      {switchRequested && (
+        <Banner variant="info" testId="billing-plans-panel-switch-requested">
+          {t("billing-foundation.plans.planSwitchRequested")}
+        </Banner>
+      )}
       {mutationError !== null && (
         <Banner variant="error" testId="billing-plans-panel-mutation-error">
           {t(mutationError.i18nKey, mutationError.i18nParams)}
@@ -318,25 +372,43 @@ export function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode {
         ))}
         {result.contact !== undefined && <BillingContactPlan contact={result.contact} />}
       </PlanGrid>
-      {consumerProtection !== undefined &&
-        consentPlan !== undefined &&
-        consentPlan.price !== null && (
-          <CheckoutConsentDialog
-            open
-            onOpenChange={(open) => {
-              if (!open) setConsentTier(null);
-            }}
-            planName={t(consentPlan.labelKey)}
-            price={{
-              amount: formatMoney(consentPlan.price.unitAmount, consentPlan.price.currency, locale),
-              renewalKey: renewalKey(consentPlan.price),
-              count: new Intl.NumberFormat(locale).format(consentPlan.price.intervalCount ?? 1),
-            }}
-            consumerProtection={consumerProtection}
-            onOrder={(consent) => orderWithConsent(consentPlan.tier, consent)}
-            onConsentTextOutdated={() => void query.refetch()}
-          />
-        )}
+      {consentPlan !== undefined && consentPlan.price !== null && (
+        <CheckoutConsentDialog
+          open
+          onOpenChange={(open) => {
+            if (!open) setConsentTier(null);
+          }}
+          planName={t(consentPlan.labelKey)}
+          price={{
+            amount: formatMoney(consentPlan.price.unitAmount, consentPlan.price.currency, locale),
+            renewalKey: renewalKey(consentPlan.price),
+            count: new Intl.NumberFormat(locale).format(consentPlan.price.intervalCount ?? 1),
+          }}
+          consumerProtection={consumerProtection}
+          providerChoice={providerChoiceFor(consentPlan.tier)}
+          note={singleProviderNote}
+          onOrder={(consent) => orderWithConsent(consentPlan.tier, consent)}
+          onConsentTextOutdated={() => void query.refetch()}
+        />
+      )}
+      {switchPlan !== undefined && (
+        <PlanSwitchConfirmDialog
+          open
+          onOpenChange={(open) => {
+            if (!open) setSwitchTier(null);
+          }}
+          tier={switchPlan.tier}
+          fromPlanName={t(result.currentTier.labelKey)}
+          toPlanName={t(switchPlan.labelKey)}
+          consumerProtection={consumerProtection}
+          onApplied={() => {
+            setSwitchTier(null);
+            setSwitchRequested(true);
+            void query.refetch();
+          }}
+          onConsentTextOutdated={() => void query.refetch()}
+        />
+      )}
       {consumerProtection !== undefined && canManage && (
         <CancelContractDialog
           open={cancelOpen}