@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/billing-foundation/handlers/start-plan-checkout.write.js

@@ -2,30 +2,56 @@
 // the catalog while the tenant has no non-terminal subscription. Resolves
 // the tier's live price server-side and opens a hosted checkout for it.
 // Only registered when `createBillingFoundationFeature` gets a `catalog`.
-import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { FeatureDisabledError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { assertBillingEnabled, assertNoActiveSubscription, isNonEmptyStringArray, joinBaseUrl, openCheckout, resolveCatalogProvider, } from "../checkout-core.js";
+import { assertBillingEnabled, assertNoActiveSubscription, isNonEmptyStringArray, joinBaseUrl, listOfferedCatalogProviders, openCheckout, } from "../checkout-core.js";
 import { consentCheckoutFields, consentPayloadSchema, prepareConsent, recordConsent, } from "../consumer-protection/consent-gate.js";
 import { purchaseRolesOf, resolvePlanPrices } from "../plan-catalog.js";
+import { BILLING_FOUNDATION_FEATURE } from "../web/constants.js";
+/** The provider this checkout goes to: the named one if it is live, the only
+ *  live one if the buyer had no choice, otherwise a client error. */
+async function pickCheckoutProvider(ctx, catalog, requestedName) {
+    const offered = await listOfferedCatalogProviders(ctx, catalog);
+    if (requestedName !== undefined) {
+        const chosen = offered.find((provider) => provider.name === requestedName);
+        if (!chosen) {
+            throw new UnprocessableError("provider_not_offered", {
+                i18nKey: "billing-foundation.errors.providerNotOffered",
+                message: `subscription-foundation: provider "${requestedName}" is not offered by this catalog right now`,
+            });
+        }
+        return chosen;
+    }
+    const [only, second] = offered;
+    if (!only)
+        throw new FeatureDisabledError(BILLING_FOUNDATION_FEATURE, "start-plan-checkout");
+    if (second) {
+        throw new UnprocessableError("provider_required", {
+            i18nKey: "billing-foundation.errors.providerRequired",
+            message: "subscription-foundation: several providers are offered, name one as providerName",
+        });
+    }
+    return only;
+}
 export function createStartPlanCheckoutHandler(options, catalog) {
     const plans = catalog.plans;
     if (!isNonEmptyStringArray(plans)) {
         throw new Error("start-plan-checkout: catalog.plans must not be empty");
     }
     const consumerProtection = options.consumerProtection;
-    const tierSchema = z.object({ tier: z.enum(plans) });
+    const tierSchema = z.object({ tier: z.enum(plans), providerName: z.string().min(1).optional() });
     const schema = (consumerProtection
         ? tierSchema.extend({ consent: consentPayloadSchema.optional() })
         : tierSchema).strict();
     return {
         name: "start-plan-checkout",
-        description: "Starts a hosted checkout for a plan tier when the tenant has no active subscription; the server picks price and redirect URLs.",
+        description: "Starts a hosted checkout for a plan tier when the tenant has no active subscription; the server picks price and redirect URLs. Name the provider with providerName when the catalog offers several.",
         schema,
         access: { roles: purchaseRolesOf(catalog) },
         handler: async (event, ctx) => {
             // @cast-boundary engine-payload — dispatcher-zod-validated payload
             const payload = event.payload;
-            const { name: providerName, plugin } = resolveCatalogProvider(ctx, catalog, "start-plan-checkout");
+            const { name: providerName, plugin } = await pickCheckoutProvider(ctx, catalog, payload.providerName);
             await assertBillingEnabled(ctx, plugin, "start-plan-checkout");
             const existing = await assertNoActiveSubscription(ctx, options.now());
             const prices = await resolvePlanPrices(ctx, plugin, catalog);
@@ -61,6 +87,7 @@ export function createStartPlanCheckoutHandler(options, catalog) {
                     tier: payload.tier,
                     priceId: resolved.priceId,
                     price: resolved.price,
+                    providerName,
                 });
             }
             return { isSuccess: true, data: { url: result.url } };

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

@@ -1,3 +1,3 @@
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import type { BillingFoundationOptions, BillingPlanCatalog } from "../types.ts";
-export declare function createSwitchPlanHandler(options: BillingFoundationOptions, catalog: BillingPlanCatalog): WriteHandlerDef;
+import type { BillingPlanCatalog, ResolvedBillingFoundationOptions } from "../types.ts";
+export declare function createSwitchPlanHandler(options: ResolvedBillingFoundationOptions, catalog: BillingPlanCatalog): WriteHandlerDef;

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/projection.d.ts

@@ -1,3 +1,4 @@
+import { type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 export declare const subscriptionsProjectionTable: import("@cosmicdrift/kumiko-framework/db").EntityTable<import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
     readonly providerName: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
@@ -56,22 +57,25 @@ export declare const paymentsProjectionTable: import("@cosmicdrift/kumiko-framew
         required: true;
     };
 }, "tenant">>;
-/** subscription-created → UPSERT mit allen Feldern. PK = aggregateId =
- *  subscriptionAggregateId(tenantId), one row pro Tenant. UPSERT damit
- *  Disney+-Wechsel-Pattern (= zweiter Provider sendet create für selben
- *  Tenant) den existing row überschreibt statt PK-conflict. */
+export declare const subscriptionsProjectionMeta: EntityTableMeta;
+export declare const paymentsProjectionMeta: EntityTableMeta;
+/** subscription-created → UPSERT with all fields. PK = aggregateId =
+ *  subscriptionAggregateId(tenantId), with one row per tenant. UPSERT allows
+ *  the Disney+-change pattern (a second provider sends create for the same
+ *  tenant) to overwrite the existing row instead of causing a PK conflict. */
 export declare const applySubscriptionCreated: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
-/** subscription-updated → UPSERT mit allen Feldern. */
+/** subscription-updated → UPSERT with all fields. */
 export declare const applySubscriptionUpdated: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
 /** subscription-canceled → status/tier/currentPeriodEnd patchen. */
 export declare const applySubscriptionCanceled: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
-/** invoice-paid → state-update (status, tier, currentPeriodEnd).
- *  Invoice-history selbst lebt im event-store (= Replay-fähig). */
+/** invoice-paid → state update (status, tier, currentPeriodEnd).
+ *  The invoice history itself lives in the event store, so it remains
+ *  replayable. */
 export declare const applyInvoicePaid: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
-/** invoice-payment-failed → status (typisch past_due) + tier. tier-
- *  engine liest die row + entscheidet ob downgrade. currentPeriodEnd
- *  bewusst nicht — die Period ist noch nicht "vorbei", payment hat
- *  nur nicht geklappt. */
+/** invoice-payment-failed → status (typically past_due) + tier. The tier
+ *  engine reads the row and decides whether to downgrade. currentPeriodEnd is
+ *  intentionally unchanged: the period has not "ended"; payment simply
+ *  failed. */
 export declare const applyInvoicePaymentFailed: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
 /** payment-received → INSERT-once row keyed by a deterministic uuid derived
  *  from (tenantId, providerName, providerEventId) — NOT `event.id`, which is