@cosmicdrift/kumiko-bundled-features 0.387.0 → 0.388.0

package/dist/billing-foundation/handlers/switch-plan.write.js

@@ -1,83 +1,75 @@
 // 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`.
-import { ConflictError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+// 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 { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { assertBillingEnabled, assertRedirectOrigins, isNonEmptyStringArray, joinBaseUrl, resolveCatalogProvider, } from "../checkout-core.js";
-import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
-import { purchaseRolesOf, resolvePlanPrices } from "../plan-catalog.js";
-import { isSwitchableSubscriptionStatus } from "../web/constants.js";
+import { assertRedirectOrigins, isNonEmptyStringArray, joinBaseUrl } from "../checkout-core.js";
+import { consentPayloadSchema, prepareConsent, recordConsent, } from "../consumer-protection/consent-gate.js";
+import { purchaseRolesOf } from "../plan-catalog.js";
+import { preparePlanSwitch } from "../plan-switch.js";
 export function createSwitchPlanHandler(options, catalog) {
     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.",
+        description: "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;
-            const { name: catalogProviderName, plugin } = resolveCatalogProvider(ctx, catalog, "switch-plan");
-            await assertBillingEnabled(ctx, plugin, "switch-plan");
-            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",
+            const prepared = await preparePlanSwitch(ctx, catalog, payload.tier, "switch-plan");
+            const { plugin } = prepared.provider;
+            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, data: { url: result.url } };
             }
-            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`,
-                });
-            }
-            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 !== 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, 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, payload, ctx, options) {
+    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, data: { applied: true } };
+}

package/dist/billing-foundation/handlers/sync-subscription.write.js

@@ -48,6 +48,16 @@ function syncProviderEventId(snapshot, lastChangedAt) {
     ].join("|");
     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() {
+    return Temporal.Now.instant()
+        .round({ smallestUnit: "second", roundingMode: "floor" })
+        .subtract({ seconds: SYNC_SNAPSHOT_EVENT_TIME_MARGIN_SECONDS });
+}
 export const syncSubscriptionHandler = {
     name: "sync-subscription",
     agent: { expose: false },
@@ -113,10 +123,11 @@ export const syncSubscriptionHandler = {
             tier: snapshot.tier,
             currentPeriodEndIso: snapshot.currentPeriodEnd,
             cancelAtIso: snapshot.cancelAt,
+            providerEventAtIso: snapshotEventTime().toString(),
         });
         return {
             isSuccess: true,
-            data: (appendResult.duplicate
+            data: (appendResult.duplicate || appendResult.stale
                 ? { synced: false, reason: "unchanged" }
                 : { synced: true }),
         };

package/dist/billing-foundation/i18n.js

@@ -20,6 +20,20 @@ export const BILLING_FOUNDATION_I18N = {
     "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": {
@@ -65,6 +79,8 @@ export const BILLING_FOUNDATION_I18N = {
     "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" },
@@ -125,6 +141,12 @@ export const BILLING_FOUNDATION_I18N = {
     "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/dist/billing-foundation/index.d.ts

@@ -10,7 +10,7 @@ export { getSubscriptionForTenant, type SubscriptionView } from "./get-subscript
 export { paymentsProjectionTable, subscriptionsProjectionTable } from "./projection.ts";
 export { billingPlansPanel, createBillingPlansScreen } from "./screens.ts";
 export { createSubscriptionTierSync, effectiveTierFromSubscription, SUBSCRIPTION_WEBHOOK_PATH, type SubscriptionTierSyncDeps, type TierSyncResult, } from "./subscription-tier-sync.ts";
-export { type BillingFoundationOptions, type BillingPlanBenefit, type BillingPlanCatalog, type BillingPlanContactCard, type BillingPlanPrice, type BillingPlansResult, type BillingPlanView, type ConsumerProtectionOptions, KNOWN_RECURRING_INTERVALS, type LegalLinkSet, type PaymentEvent, type ProviderPrice, type ProviderSubscriptionSnapshot, type RecurringInterval, type SubscriptionEvent, type SubscriptionProviderPlugin, } from "./types.ts";
+export { type BillingFoundationOptions, type BillingPlanBenefit, type BillingPlanCatalog, type BillingPlanContactCard, 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, type SubscriptionEvent, type SubscriptionProviderPlugin, } from "./types.ts";
 export { BILLING_FOUNDATION_FEATURE, BILLING_PLANS_PANEL_COMPONENT, BILLING_PLANS_SCREEN_ID, type BillingEventKind, BillingEventKinds, type BillingPlanAction, BillingPlanActions, DEFAULT_PURCHASE_ROLES, isSwitchableSubscriptionStatus, isTerminalSubscriptionStatus, parseProviderConsentId, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, SubscriptionCancelTimings, type SubscriptionEventType, SubscriptionEventTypes, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, type SubscriptionStatus, SubscriptionStatuses, } from "./web/constants.ts";
 export { CONSENT_LOCALES, type ConsentLocale, resolveConsentLocale, } from "./web/consumer-protection/consent-locale.ts";
 export { createSubscriptionWebhookRoute, type SubscriptionWebhookRouteOptions, } from "./webhook-handler.ts";

package/dist/billing-foundation/plan-catalog.d.ts

@@ -1,12 +1,13 @@
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
-import type { BillingPlanCatalog, BillingPlansResult, ProviderPrice, SubscriptionProviderPlugin } from "./types.ts";
+import { getSubscriptionForTenant } from "./get-subscription-for-tenant.ts";
+import { type BillingPlanCatalog, type BillingPlansResult, type BillingPlanView, type ProviderPrice, type SubscriptionProviderPlugin } from "./types.ts";
 /** `catalog?.purchaseRoles ?? DEFAULT_PURCHASE_ROLES` — the one place this
  *  fallback is spelled out; plan-catalog.ts and the start-plan-checkout/
  *  switch-plan/create-portal-session handlers all call this instead of
  *  repeating the literal. Accepts `undefined` so create-portal-session
  *  (mounted with or without a catalog) doesn't need its own fallback. */
 export declare function purchaseRolesOf(catalog: Pick<BillingPlanCatalog, "purchaseRoles"> | undefined): readonly string[];
-type ResolvedPlanPrice = {
+export type ResolvedPlanPrice = {
     readonly priceId: string;
     readonly price: ProviderPrice;
 } | null;
@@ -15,9 +16,24 @@ type ResolvedPlanPrice = {
  *  one the plan means — and resolves to null with a warning instead of an
  *  arbitrary pick. */
 export declare function resolvePlanPrices(ctx: HandlerContext, plugin: SubscriptionProviderPlugin, catalog: BillingPlanCatalog): Promise<ReadonlyMap<string, ResolvedPlanPrice>>;
+/** 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 declare function loadBillingPlansBase(ctx: HandlerContext, catalog: BillingPlanCatalog, now: () => Temporal.Instant): Promise<BillingPlansBase>;
+export type ProviderPlanViews = {
+    readonly enabled: boolean;
+    readonly inAppSwitch: boolean;
+    readonly plans: readonly BillingPlanView[];
+};
 /** `plugin === null` — no provider is registered/resolvable for this
- *  catalog (see checkout-core's `findCatalogProvider`) — collapses onto the
+ *  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 declare function buildBillingPlans(ctx: HandlerContext, plugin: SubscriptionProviderPlugin | null, catalog: BillingPlanCatalog, now: () => Temporal.Instant): Promise<BillingPlansResult>;
-export {};
+export declare function buildProviderPlanViews(ctx: HandlerContext, plugin: SubscriptionProviderPlugin | null, catalog: BillingPlanCatalog, base: BillingPlansBase): Promise<ProviderPlanViews>;
+export declare function toBillingPlansResult(catalog: BillingPlanCatalog, base: BillingPlansBase, views: ProviderPlanViews): BillingPlansResult;

package/dist/billing-foundation/plan-catalog.js

@@ -4,6 +4,7 @@
 // Internal — not re-exported from index.ts.
 import { isPluginBillingEnabled } from "./checkout-core.js";
 import { getSubscriptionForTenant } from "./get-subscription-for-tenant.js";
+import { canSwitchPlans, canSwitchPlansInApp, } from "./types.js";
 import { BillingPlanActions, DEFAULT_PURCHASE_ROLES, isSubscriptionBlockingCheckout, isSwitchableSubscriptionStatus, SubscriptionStatuses, } from "./web/constants.js";
 function userHasAnyRole(userRoles, allowedRoles) {
     return allowedRoles.some((role) => userRoles.includes(role));
@@ -80,7 +81,7 @@ function canSwitchToTier(tier, subscription, plugin) {
     return (isSwitchableSubscriptionStatus(subscription.status) &&
         tier !== subscription.tier &&
         subscription.cancelAt === null &&
-        plugin?.createPlanSwitchSession !== undefined);
+        canSwitchPlans(plugin));
 }
 /** One plan-row's action — pulled out of `buildBillingPlans`' map callback so
  *  that function's own complexity stays under the guard's budget. paymentPending
@@ -105,29 +106,32 @@ function resolvePlanAction(tier, isCurrent, price, enabled, canPurchase, subscri
         ? BillingPlanActions.switch
         : 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(ctx, plugin, catalog, now) {
+export async function loadBillingPlansBase(ctx, catalog, now) {
     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(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 purchaseRoles = purchaseRolesOf(catalog);
-    const canPurchase = userHasAnyRole(ctx.user.roles, purchaseRoles);
+    const canPurchase = userHasAnyRole(ctx.user.roles, purchaseRolesOf(catalog));
+    return { currentTierValue, subscriptionView, subscription, blockingSubscription, canPurchase };
+}
+/** `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, plugin, catalog, base) {
+    const { currentTierValue, subscription, canPurchase } = base;
+    const enabled = plugin !== null && (await isPluginBillingEnabled(ctx, plugin));
+    const resolvedPrices = enabled && plugin
+        ? await resolvePlanPrices(ctx, plugin, catalog)
+        : new Map(catalog.plans.map((tier) => [tier, null]));
     const plans = catalog.plans.map((tier) => {
         const isCurrent = tier === currentTierValue;
         const resolved = resolvedPrices.get(tier) ?? null;
@@ -149,8 +153,12 @@ export async function buildBillingPlans(ctx, plugin, catalog, now) {
             action,
         };
     });
+    return { enabled, inAppSwitch: plugin !== null && canSwitchPlansInApp(plugin), plans };
+}
+export function toBillingPlansResult(catalog, base, views) {
+    const { currentTierValue, subscription, canPurchase } = base;
     return {
-        enabled,
+        enabled: views.enabled,
         currentTier: {
             tier: currentTierValue,
             labelKey: catalog.tierLabelKey(currentTierValue),
@@ -158,7 +166,8 @@ export async function buildBillingPlans(ctx, plugin, catalog, now) {
         },
         subscription,
         canPurchase,
-        plans,
+        plans: views.plans,
+        ...(views.inAppSwitch && { inAppPlanSwitch: true }),
         ...(catalog.contact !== undefined && { contact: catalog.contact }),
     };
 }

package/dist/billing-foundation/plan-switch.d.ts

@@ -0,0 +1,12 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { type ResolvedProvider } from "./checkout-core.ts";
+import { type SubscriptionView } from "./get-subscription-for-tenant.ts";
+import { type ResolvedPlanPrice } from "./plan-catalog.ts";
+import { type BillingPlanCatalog } from "./types.ts";
+export type PreparedPlanSwitch = {
+    readonly provider: ResolvedProvider;
+    readonly subscription: SubscriptionView;
+    readonly target: NonNullable<ResolvedPlanPrice>;
+    readonly allowedPriceIds: readonly string[];
+};
+export declare function preparePlanSwitch(ctx: HandlerContext, catalog: BillingPlanCatalog, tier: string, handlerName: string): Promise<PreparedPlanSwitch>;

package/dist/billing-foundation/plan-switch.js

@@ -0,0 +1,60 @@
+// 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 { ConflictError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { assertBillingEnabled, findProviderPlugin, listCatalogProviders, } from "./checkout-core.js";
+import { getSubscriptionForTenant } from "./get-subscription-for-tenant.js";
+import { resolvePlanPrices } from "./plan-catalog.js";
+import { canSwitchPlans } from "./types.js";
+import { isSwitchableSubscriptionStatus } from "./web/constants.js";
+export async function preparePlanSwitch(ctx, catalog, tier, handlerName) {
+    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 !== null)
+        .map((p) => p.priceId);
+    return { provider, subscription, target, allowedPriceIds };
+}

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

@@ -75,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
@@ -228,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`
@@ -241,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;
@@ -296,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;
@@ -319,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
@@ -372,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: {
@@ -388,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

@@ -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.`);
     }