@cosmicdrift/kumiko-samples 0.387.0 → 0.389.0

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

@@ -1,109 +1,99 @@
 // switch-plan — a tenant-admin/purchase-role switches an existing,
-// non-terminal subscription to a different plan tier via the provider's
-// own confirmation page. Only registered when `createBillingFoundationFeature`
-// gets a `catalog`.
+// non-terminal subscription to a different plan tier. A provider with a hosted
+// switch session answers `{ url }`; a provider that switches in-app (preview +
+// apply) applies the switch right here and answers `{ applied: true }`.
+// Only registered when `createBillingFoundationFeature` gets a `catalog`.
 
-import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import { ConflictError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import type { HandlerContext, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { assertRedirectOrigins, isNonEmptyStringArray, joinBaseUrl } from "../checkout-core.ts";
 import {
-  assertBillingEnabled,
-  assertRedirectOrigins,
-  isNonEmptyStringArray,
-  joinBaseUrl,
-  resolveCatalogProvider,
-} from "../checkout-core.ts";
-import { getSubscriptionForTenant } from "../get-subscription-for-tenant.ts";
-import { purchaseRolesOf, resolvePlanPrices } from "../plan-catalog.ts";
-import type { BillingFoundationOptions, BillingPlanCatalog } from "../types.ts";
-import { isSwitchableSubscriptionStatus } from "../web/constants.ts";
+  type ConsentPayload,
+  consentPayloadSchema,
+  prepareConsent,
+  recordConsent,
+} from "../consumer-protection/consent-gate.ts";
+import { purchaseRolesOf } from "../plan-catalog.ts";
+import { type PreparedPlanSwitch, preparePlanSwitch } from "../plan-switch.ts";
+import type { BillingPlanCatalog, ResolvedBillingFoundationOptions } from "../types.ts";
 
 export function createSwitchPlanHandler(
-  options: BillingFoundationOptions,
+  options: ResolvedBillingFoundationOptions,
   catalog: BillingPlanCatalog,
 ): WriteHandlerDef {
   const plans = catalog.plans;
   if (!isNonEmptyStringArray(plans)) {
     throw new Error("switch-plan: catalog.plans must not be empty");
   }
-  const schema = z.object({ tier: z.enum(plans) }).strict();
+  const consumerProtection = options.consumerProtection;
+  const tierSchema = z.object({ tier: z.enum(plans) });
+  const schema = (
+    consumerProtection
+      ? tierSchema.extend({ consent: consentPayloadSchema.optional() })
+      : tierSchema
+  ).strict();
 
   return {
     name: "switch-plan",
     description:
-      "Opens the provider's confirmation page for switching the existing subscription to another plan tier.",
+      "Switches the existing subscription to another plan tier: opens the provider's confirmation page (answers { url }), or applies the switch in-app for providers that preview and apply themselves (answers { applied: true }; send consent when consumer protection is configured).",
     schema,
     access: { roles: purchaseRolesOf(catalog) },
     handler: async (event, ctx) => {
       // @cast-boundary engine-payload — dispatcher-zod-validated payload
-      const payload = event.payload as { tier: string };
-      const { name: catalogProviderName, plugin } = resolveCatalogProvider(
-        ctx,
-        catalog,
-        "switch-plan",
-      );
-      await assertBillingEnabled(ctx, plugin, "switch-plan");
+      const payload = event.payload as { tier: string; consent?: ConsentPayload };
+      const prepared = await preparePlanSwitch(ctx, catalog, payload.tier, "switch-plan");
+      const { plugin } = prepared.provider;
 
-      const sub = await getSubscriptionForTenant(ctx, event.user.tenantId);
-      if (!sub || !isSwitchableSubscriptionStatus(sub.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",
-        });
-      }
-      if (sub.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 (payload.tier === sub.tier) {
-        throw new ConflictError({
-          i18nKey: "billing-foundation.errors.alreadyOnPlan",
-          message: `tenant is already on plan "${payload.tier}"`,
-        });
-      }
-      // providerSubscriptionId only exists at the subscription's own provider; after a
-      // provider migration the catalog provider can differ, which is not a plan switch.
-      if (sub.providerName !== catalogProviderName) {
-        throw new ConflictError({
-          i18nKey: "billing-foundation.errors.providerMismatch",
-          message: `tenant's active subscription is on provider "${sub.providerName}", the catalog resolves provider "${catalogProviderName}" — switch-plan cannot switch across providers`,
-        });
-      }
-      if (!plugin.createPlanSwitchSession) {
-        throw new UnprocessableError("plan_switch_not_supported", {
-          i18nKey: "billing-foundation.errors.planSwitchNotSupported",
-          message: `subscription-foundation: provider "${sub.providerName}" has no createPlanSwitchSession-method`,
+      if (plugin.createPlanSwitchSession) {
+        const baseUrl = options.baseUrl ?? "";
+        const returnUrl = joinBaseUrl(baseUrl, catalog.returnPath ?? catalog.successPath);
+        assertRedirectOrigins([returnUrl], options.baseUrl);
+        const result = await plugin.createPlanSwitchSession(ctx, {
+          providerSubscriptionId: prepared.subscription.providerSubscriptionId,
+          targetPriceId: prepared.target.priceId,
+          allowedPriceIds: prepared.allowedPriceIds,
+          returnUrl,
         });
+        return { isSuccess: true as const, data: { url: result.url } };
       }
 
-      const prices = await resolvePlanPrices(ctx, plugin, catalog);
-      const target = prices.get(payload.tier);
-      if (!target) {
-        throw new UnprocessableError("price_unavailable", {
-          i18nKey: "billing-foundation.errors.priceUnavailable",
-          message: `subscription-foundation: no live price resolved for tier "${payload.tier}"`,
-        });
-      }
-      const allowedPriceIds = [...prices.values()]
-        .filter((p): p is NonNullable<typeof p> => p !== null)
-        .map((p) => p.priceId);
-
-      const baseUrl = options.baseUrl ?? "";
-      const returnUrl = joinBaseUrl(baseUrl, catalog.returnPath ?? catalog.successPath);
-      assertRedirectOrigins([returnUrl], options.baseUrl);
-
-      const result = await plugin.createPlanSwitchSession(ctx, {
-        providerSubscriptionId: sub.providerSubscriptionId,
-        targetPriceId: target.priceId,
-        allowedPriceIds,
-        returnUrl,
-      });
-
-      return { isSuccess: true as const, data: { url: result.url } };
+      return applyInApp(prepared, payload, ctx, options);
     },
   };
 }
+
+// Consent is recorded before the provider call: the apply carries the consentId
+// as provider metadata, and a failing apply rolls the whole handler back.
+async function applyInApp(
+  prepared: PreparedPlanSwitch,
+  payload: { readonly tier: string; readonly consent?: ConsentPayload },
+  ctx: HandlerContext,
+  options: ResolvedBillingFoundationOptions,
+) {
+  const { plugin, name: providerName } = prepared.provider;
+  if (!plugin.applyPlanSwitch) {
+    throw new InternalError({
+      message: `billing-foundation: provider "${providerName}" has neither createPlanSwitchSession nor applyPlanSwitch`,
+    });
+  }
+  const consent = options.consumerProtection
+    ? await prepareConsent(ctx, options.consumerProtection, payload.consent, "subscription")
+    : undefined;
+  if (consent) {
+    await recordConsent(ctx, consent, {
+      tier: payload.tier,
+      priceId: prepared.target.priceId,
+      price: prepared.target.price,
+      providerName,
+    });
+  }
+  await plugin.applyPlanSwitch(ctx, {
+    providerSubscriptionId: prepared.subscription.providerSubscriptionId,
+    targetPriceId: prepared.target.priceId,
+    tenantId: ctx.user.tenantId,
+    ...(consent && { consentId: consent.consentId }),
+  });
+  return { isSuccess: true as const, data: { applied: true as const } };
+}

package/packages/bundled-features/src/billing-foundation/handlers/sync-subscription.write.ts

@@ -72,6 +72,18 @@ function syncProviderEventId(
   return `sync:${createHash("sha256").update(hashInput).digest("hex")}`;
 }
 
+// The retrieval time stands in for the provider's event time, so a webhook emitted before
+// this snapshot cannot roll the synced state back later. Provider webhook times are
+// whole-second and come from the provider's clock, so the stamp is floored and shifted back:
+// a genuine webhook right after the sync must not look older than the snapshot.
+const SYNC_SNAPSHOT_EVENT_TIME_MARGIN_SECONDS = 5;
+
+function snapshotEventTime(): Temporal.Instant {
+  return Temporal.Now.instant()
+    .round({ smallestUnit: "second", roundingMode: "floor" })
+    .subtract({ seconds: SYNC_SNAPSHOT_EVENT_TIME_MARGIN_SECONDS });
+}
+
 export const syncSubscriptionHandler: WriteHandlerDef = {
   name: "sync-subscription",
   agent: { expose: false },
@@ -143,11 +155,12 @@ export const syncSubscriptionHandler: WriteHandlerDef = {
       tier: snapshot.tier,
       currentPeriodEndIso: snapshot.currentPeriodEnd,
       cancelAtIso: snapshot.cancelAt,
+      providerEventAtIso: snapshotEventTime().toString(),
     });
 
     return {
       isSuccess: true as const,
-      data: (appendResult.duplicate
+      data: (appendResult.duplicate || appendResult.stale
         ? { synced: false, reason: "unchanged" }
         : { synced: true }) satisfies SyncSubscriptionResult,
     };

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

@@ -25,6 +25,20 @@ export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>>
   "billing-foundation.plans.everyInterval.year": { en: "every {count} years" },
   "billing-foundation.plans.choose": { en: "Choose {plan}" },
   "billing-foundation.plans.switch": { en: "Switch to {plan}" },
+  "billing-foundation.plans.planSwitchRequested": {
+    en: "Plan switch requested. It becomes active once the payment is confirmed.",
+  },
+  "billing-foundation.planSwitch.title": { en: "Confirm plan switch" },
+  "billing-foundation.planSwitch.summary": { en: "{from} to {to}" },
+  "billing-foundation.planSwitch.dueNow": { en: "Due now: {amount}" },
+  "billing-foundation.planSwitch.includesTax": { en: "including {tax} VAT" },
+  "billing-foundation.planSwitch.credit": { en: "Credit for the unused time: {amount}" },
+  "billing-foundation.planSwitch.recurring": { en: "New recurring price: {amount}" },
+  "billing-foundation.planSwitch.effective": { en: "Effective immediately" },
+  "billing-foundation.planSwitch.pendingNote": {
+    en: "The switch becomes active after payment confirmation.",
+  },
+  "billing-foundation.planSwitch.order": { en: "Switch with obligation to pay" },
   "billing-foundation.plans.manage": { en: "Manage subscription" },
   "billing-foundation.plans.reactivate": { en: "Reactivate subscription" },
   "billing-foundation.plans.cancelScheduled": {
@@ -70,6 +84,8 @@ export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>>
   "billing-foundation.consent.link.withdrawal": { en: "Withdrawal policy" },
   "billing-foundation.consent.link.privacy": { en: "Privacy policy" },
   "billing-foundation.consent.order": { en: "Order with obligation to pay" },
+  "billing-foundation.plans.priceFrom": { en: "from" },
+  "billing-foundation.consent.chooseProvider": { en: "Payment provider" },
   "billing-foundation.consent.back": { en: "Back" },
   "billing-foundation.cancel.open": { en: "Cancel contract here" },
   "billing-foundation.cancel.title": { en: "Cancel contract" },
@@ -130,6 +146,12 @@ export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>>
   "billing-foundation.errors.providerMismatch": {
     en: "This tenant's subscription is on a different provider than the plan catalog. Contact support to migrate.",
   },
+  "billing-foundation.errors.providerNotOffered": {
+    en: "This payment provider is not available right now.",
+  },
+  "billing-foundation.errors.providerRequired": {
+    en: "Choose a payment provider to continue.",
+  },
   "billing-foundation.errors.priceUnavailable": {
     en: "This plan's price is temporarily unavailable.",
   },

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

@@ -62,10 +62,12 @@ export {
   type BillingPlanPrice,
   type BillingPlansResult,
   type BillingPlanView,
+  type BillingProviderView,
   type ConsumerProtectionOptions,
   KNOWN_RECURRING_INTERVALS,
   type LegalLinkSet,
   type PaymentEvent,
+  type PlanSwitchPreview,
   type ProviderPrice,
   type ProviderSubscriptionSnapshot,
   type RecurringInterval,

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.`,