@cosmicdrift/kumiko-samples 0.387.0 → 0.388.0

package/packages/bundled-features/src/billing-foundation/plan-catalog.ts

@@ -6,12 +6,14 @@
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { isPluginBillingEnabled } from "./checkout-core.ts";
 import { getSubscriptionForTenant } from "./get-subscription-for-tenant.ts";
-import type {
-  BillingPlanCatalog,
-  BillingPlansResult,
-  BillingPlanView,
-  ProviderPrice,
-  SubscriptionProviderPlugin,
+import {
+  type BillingPlanCatalog,
+  type BillingPlansResult,
+  type BillingPlanView,
+  canSwitchPlans,
+  canSwitchPlansInApp,
+  type ProviderPrice,
+  type SubscriptionProviderPlugin,
 } from "./types.ts";
 import {
   BillingPlanActions,
@@ -51,7 +53,7 @@ function invertPriceToTier(
   return byTier;
 }
 
-type ResolvedPlanPrice = { readonly priceId: string; readonly price: ProviderPrice } | null;
+export type ResolvedPlanPrice = { readonly priceId: string; readonly price: ProviderPrice } | null;
 
 /** Resolves one active, flat-amount price per plan tier. 0 or >1 active
  *  flat-amount prices for a tier is ambiguous — the caller can't tell which
@@ -120,7 +122,7 @@ function canSwitchToTier(
     isSwitchableSubscriptionStatus(subscription.status) &&
     tier !== subscription.tier &&
     subscription.cancelAt === null &&
-    plugin?.createPlanSwitchSession !== undefined
+    canSwitchPlans(plugin)
   );
 }
 
@@ -157,37 +159,60 @@ function resolvePlanAction(
     : BillingPlanActions.unavailable;
 }
 
-/** `plugin === null` — no provider is registered/resolvable for this
- *  catalog (see checkout-core's `findCatalogProvider`) — collapses onto the
- *  same "enabled: false" result a disabled provider produces, rather than
- *  a separate error shape the panel would need to special-case. */
-export async function buildBillingPlans(
+/** Tenant-level state every provider's plan list is measured against; loaded
+ *  once so a multi-provider result does not repeat the reads per provider. */
+export type BillingPlansBase = {
+  readonly currentTierValue: string;
+  readonly subscriptionView: Awaited<ReturnType<typeof getSubscriptionForTenant>>;
+  readonly subscription: BillingPlansResult["subscription"];
+  readonly blockingSubscription: boolean;
+  readonly canPurchase: boolean;
+};
+
+export async function loadBillingPlansBase(
   ctx: HandlerContext,
-  plugin: SubscriptionProviderPlugin | null,
   catalog: BillingPlanCatalog,
   now: () => Temporal.Instant,
-): Promise<BillingPlansResult> {
+): Promise<BillingPlansBase> {
   const currentTierValue = await catalog.resolveCurrentTier(ctx.db, ctx.user.tenantId);
-  const enabled = plugin !== null && (await isPluginBillingEnabled(ctx, plugin));
-  const resolvedPrices =
-    enabled && plugin
-      ? await resolvePlanPrices(ctx, plugin, catalog)
-      : new Map<string, ResolvedPlanPrice>(catalog.plans.map((tier) => [tier, null]));
-
   const subscriptionView = await getSubscriptionForTenant(ctx, ctx.user.tenantId);
-  const nowInstant = now();
+  const blockingSubscription =
+    subscriptionView !== null && isSubscriptionBlockingCheckout(subscriptionView, now());
   const subscription = subscriptionView
     ? {
         status: subscriptionView.status,
         tier: subscriptionView.tier,
-        terminal: !isSubscriptionBlockingCheckout(subscriptionView, nowInstant),
+        terminal: !blockingSubscription,
         currentPeriodEnd: subscriptionView.currentPeriodEnd.toString(),
         cancelAt: subscriptionView.cancelAt?.toString() ?? null,
       }
     : null;
+  const canPurchase = userHasAnyRole(ctx.user.roles, purchaseRolesOf(catalog));
+  return { currentTierValue, subscriptionView, subscription, blockingSubscription, canPurchase };
+}
+
+export type ProviderPlanViews = {
+  readonly enabled: boolean;
+  readonly inAppSwitch: boolean;
+  readonly plans: readonly BillingPlanView[];
+};
 
-  const purchaseRoles = purchaseRolesOf(catalog);
-  const canPurchase = userHasAnyRole(ctx.user.roles, purchaseRoles);
+/** `plugin === null` — no provider is registered/resolvable for this
+ *  catalog (see checkout-core's `listCatalogProviders`) — collapses onto the
+ *  same "enabled: false" result a disabled provider produces, rather than
+ *  a separate error shape the panel would need to special-case. */
+export async function buildProviderPlanViews(
+  ctx: HandlerContext,
+  plugin: SubscriptionProviderPlugin | null,
+  catalog: BillingPlanCatalog,
+  base: BillingPlansBase,
+): Promise<ProviderPlanViews> {
+  const { currentTierValue, subscription, canPurchase } = base;
+  const enabled = plugin !== null && (await isPluginBillingEnabled(ctx, plugin));
+  const resolvedPrices =
+    enabled && plugin
+      ? await resolvePlanPrices(ctx, plugin, catalog)
+      : new Map<string, ResolvedPlanPrice>(catalog.plans.map((tier) => [tier, null]));
 
   const plans: BillingPlanView[] = catalog.plans.map((tier) => {
     const isCurrent = tier === currentTierValue;
@@ -221,8 +246,17 @@ export async function buildBillingPlans(
     };
   });
 
+  return { enabled, inAppSwitch: plugin !== null && canSwitchPlansInApp(plugin), plans };
+}
+
+export function toBillingPlansResult(
+  catalog: BillingPlanCatalog,
+  base: BillingPlansBase,
+  views: ProviderPlanViews,
+): BillingPlansResult {
+  const { currentTierValue, subscription, canPurchase } = base;
   return {
-    enabled,
+    enabled: views.enabled,
     currentTier: {
       tier: currentTierValue,
       labelKey: catalog.tierLabelKey(currentTierValue),
@@ -230,7 +264,8 @@ export async function buildBillingPlans(
     },
     subscription,
     canPurchase,
-    plans,
+    plans: views.plans,
+    ...(views.inAppSwitch && { inAppPlanSwitch: true as const }),
     ...(catalog.contact !== undefined && { contact: catalog.contact }),
   };
 }

package/packages/bundled-features/src/billing-foundation/plan-switch.ts

@@ -0,0 +1,84 @@
+// Pre-checks shared by switch-plan and plan-switch-preview: both must agree on
+// which subscription, provider and target price a plan switch means.
+// Internal — not re-exported from index.ts.
+
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { ConflictError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  assertBillingEnabled,
+  findProviderPlugin,
+  listCatalogProviders,
+  type ResolvedProvider,
+} from "./checkout-core.ts";
+import { getSubscriptionForTenant, type SubscriptionView } from "./get-subscription-for-tenant.ts";
+import { type ResolvedPlanPrice, resolvePlanPrices } from "./plan-catalog.ts";
+import { type BillingPlanCatalog, canSwitchPlans } from "./types.ts";
+import { isSwitchableSubscriptionStatus } from "./web/constants.ts";
+
+export type PreparedPlanSwitch = {
+  readonly provider: ResolvedProvider;
+  readonly subscription: SubscriptionView;
+  readonly target: NonNullable<ResolvedPlanPrice>;
+  readonly allowedPriceIds: readonly string[];
+};
+
+export async function preparePlanSwitch(
+  ctx: HandlerContext,
+  catalog: BillingPlanCatalog,
+  tier: string,
+  handlerName: string,
+): Promise<PreparedPlanSwitch> {
+  const subscription = await getSubscriptionForTenant(ctx, ctx.user.tenantId);
+  if (!subscription || !isSwitchableSubscriptionStatus(subscription.status)) {
+    throw new ConflictError({
+      i18nKey: "billing-foundation.errors.noActiveSubscription",
+      message:
+        "tenant has no switchable subscription; use billing-foundation:write:start-plan-checkout to start one",
+    });
+  }
+  // providerSubscriptionId only exists at the subscription's own provider; a catalog that
+  // no longer sells through that provider cannot switch it.
+  const provider = findProviderPlugin(ctx, subscription.providerName);
+  const isCatalogProvider =
+    provider !== null &&
+    listCatalogProviders(ctx, catalog).some((candidate) => candidate.name === provider.name);
+  if (!provider || !isCatalogProvider) {
+    throw new ConflictError({
+      i18nKey: "billing-foundation.errors.providerMismatch",
+      message: `tenant's active subscription is on provider "${subscription.providerName}", which the plan catalog does not sell through — switch-plan cannot switch across providers`,
+    });
+  }
+  await assertBillingEnabled(ctx, provider.plugin, handlerName);
+  if (subscription.cancelAt !== null) {
+    throw new ConflictError({
+      i18nKey: "billing-foundation.errors.cancellationScheduled",
+      message:
+        "subscription has a scheduled cancellation; reactivate it via billing-foundation:write:create-portal-session before switching plans",
+    });
+  }
+  if (tier === subscription.tier) {
+    throw new ConflictError({
+      i18nKey: "billing-foundation.errors.alreadyOnPlan",
+      message: `tenant is already on plan "${tier}"`,
+    });
+  }
+  if (!canSwitchPlans(provider.plugin)) {
+    throw new UnprocessableError("plan_switch_not_supported", {
+      i18nKey: "billing-foundation.errors.planSwitchNotSupported",
+      message: `subscription-foundation: provider "${subscription.providerName}" supports neither createPlanSwitchSession nor previewPlanSwitch + applyPlanSwitch`,
+    });
+  }
+
+  const prices = await resolvePlanPrices(ctx, provider.plugin, catalog);
+  const target = prices.get(tier);
+  if (!target) {
+    throw new UnprocessableError("price_unavailable", {
+      i18nKey: "billing-foundation.errors.priceUnavailable",
+      message: `subscription-foundation: no live price resolved for tier "${tier}"`,
+    });
+  }
+  const allowedPriceIds = [...prices.values()]
+    .filter((p): p is NonNullable<typeof p> => p !== null)
+    .map((p) => p.priceId);
+  return { provider, subscription, target, allowedPriceIds };
+}

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

@@ -136,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
@@ -313,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`
@@ -330,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;
@@ -399,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;
@@ -429,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
@@ -490,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: {
@@ -506,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
@@ -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}