@cosmicdrift/kumiko-bundled-features 0.387.0 → 0.389.0

package/dist/billing-foundation/handlers/billing-plans.query.js

@@ -2,20 +2,20 @@
 // benefits, the caller's current tier and per-plan action. Only registered
 // when `createBillingFoundationFeature` gets a `catalog`.
 import * as z from "zod";
-import { findCatalogProvider } from "../checkout-core.js";
+import { filterOfferedProviders, listCatalogProviders, } from "../checkout-core.js";
 import { CONSENT_TEXTS, consentTextVersion, } from "../consumer-protection/consent-text.js";
-import { buildBillingPlans } from "../plan-catalog.js";
+import { buildProviderPlanViews, loadBillingPlansBase, toBillingPlansResult, } from "../plan-catalog.js";
 import { isLegalLinkSet, } from "../types.js";
 const billingPlansSchema = z.object({}).strict();
 export function createBillingPlansQuery(options, catalog) {
     return {
         name: "billing-plans",
-        description: "Lists the purchasable plans with live price, benefits, the caller's current tier and which action (checkout | switch | current | unavailable | paymentPending) each plan offers, plus the optional price-less contact card.",
+        description: "Lists the purchasable plans with live price, benefits, the caller's current tier and which action (checkout | switch | current | unavailable | paymentPending) each plan offers, plus the optional price-less contact card. With several live providers it also lists each provider's own plans under `providers`.",
         schema: billingPlansSchema,
         access: { roles: catalog.viewRoles },
         handler: async (_query, ctx) => {
-            const found = findCatalogProvider(ctx, catalog);
-            const result = await buildBillingPlans(ctx, found?.plugin ?? null, catalog, options.now);
+            const base = await loadBillingPlansBase(ctx, catalog, options.now);
+            const result = await resolveProviderPlans(ctx, options, catalog, base);
             const { consumerProtection } = options;
             if (!consumerProtection)
                 return result;
@@ -32,6 +32,36 @@ export function createBillingPlansQuery(options, catalog) {
         },
     };
 }
+// A tenant with a blocking subscription sees only the provider holding it
+// (a second provider's prices would be a checkout it cannot start); otherwise
+// every live provider is offered.
+async function resolveProviderPlans(ctx, options, catalog, base) {
+    const candidates = listCatalogProviders(ctx, catalog);
+    if (base.blockingSubscription && base.subscriptionView) {
+        const holder = candidates.find((c) => c.name === base.subscriptionView?.providerName);
+        return toBillingPlansResult(catalog, base, await buildProviderPlanViews(ctx, holder?.plugin ?? null, catalog, base));
+    }
+    const offered = await filterOfferedProviders(ctx, candidates);
+    const first = offered[0] ?? candidates[0] ?? null;
+    const firstViews = await buildProviderPlanViews(ctx, first?.plugin ?? null, catalog, base);
+    const result = toBillingPlansResult(catalog, base, firstViews);
+    const providerTexts = options.consumerProtection?.providerTexts;
+    const hasNote = first !== null && providerTexts?.[first.name]?.checkoutNote !== undefined;
+    if (offered.length <= 1 && !(offered.length === 1 && hasNote))
+        return result;
+    const providers = await Promise.all(offered.map((provider, index) => providerView(ctx, catalog, base, provider, providerTexts, index === 0 ? firstViews : null)));
+    return { ...result, providers };
+}
+async function providerView(ctx, catalog, base, provider, providerTexts, known) {
+    const views = known ?? (await buildProviderPlanViews(ctx, provider.plugin, catalog, base));
+    const note = providerTexts?.[provider.name]?.checkoutNote;
+    return {
+        name: provider.name,
+        displayName: provider.plugin.displayName ?? provider.name,
+        ...(note !== undefined && { note }),
+        plans: views.plans,
+    };
+}
 function legalLinksPerLocale(legalLinks) {
     return isLegalLinkSet(legalLinks) ? { de: legalLinks, en: legalLinks } : legalLinks;
 }

package/dist/billing-foundation/handlers/create-checkout-session.write.js

@@ -90,6 +90,7 @@ export function createCheckoutSessionHandler(options) {
                 tier: mode === "subscription" ? (plugin.priceToTier?.[payload.priceId] ?? null) : null,
                 priceId: payload.priceId,
                 price,
+                providerName: payload.providerName,
                 ...(orderItem && { orderItem }),
             });
             return {

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

@@ -0,0 +1,13 @@
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type { BillingPlanCatalog, PlanSwitchPreview } from "../types.ts";
+export type PlanSwitchPreviewResult = {
+    readonly preview: PlanSwitchPreview;
+    readonly target: {
+        readonly tier: string;
+        readonly unitAmount: number;
+        readonly currency: string;
+        readonly interval: "day" | "week" | "month" | "year" | null;
+        readonly intervalCount: number | null;
+    };
+};
+export declare function createPlanSwitchPreviewQuery(catalog: BillingPlanCatalog): QueryHandlerDef;

package/dist/billing-foundation/handlers/plan-switch-preview.query.js

@@ -0,0 +1,48 @@
+// plan-switch-preview — what switching to a tier would cost right now, for
+// providers that switch plans in-app (previewPlanSwitch + applyPlanSwitch).
+// Only registered when `createBillingFoundationFeature` gets a `catalog`.
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { isNonEmptyStringArray } from "../checkout-core.js";
+import { purchaseRolesOf } from "../plan-catalog.js";
+import { preparePlanSwitch } from "../plan-switch.js";
+export function createPlanSwitchPreviewQuery(catalog) {
+    const plans = catalog.plans;
+    if (!isNonEmptyStringArray(plans)) {
+        throw new Error("plan-switch-preview: catalog.plans must not be empty");
+    }
+    const schema = z.object({ tier: z.enum(plans) }).strict();
+    return {
+        name: "plan-switch-preview",
+        description: "Previews what switching the existing subscription to another plan tier costs right now (amount due, tax, credit, effective date) plus the target plan's recurring price. Only for providers that switch plans in-app.",
+        schema,
+        access: { roles: purchaseRolesOf(catalog) },
+        handler: async (query, ctx) => {
+            // @cast-boundary engine-payload — dispatcher-zod-validated payload
+            const { tier } = query.payload;
+            const prepared = await preparePlanSwitch(ctx, catalog, tier, "plan-switch-preview");
+            const { plugin } = prepared.provider;
+            if (!plugin.previewPlanSwitch || !plugin.applyPlanSwitch) {
+                throw new UnprocessableError("plan_switch_not_supported", {
+                    i18nKey: "billing-foundation.errors.planSwitchNotSupported",
+                    message: `subscription-foundation: provider "${prepared.provider.name}" switches plans on a hosted page and has no in-app preview`,
+                });
+            }
+            const preview = await plugin.previewPlanSwitch(ctx, {
+                providerSubscriptionId: prepared.subscription.providerSubscriptionId,
+                targetPriceId: prepared.target.priceId,
+            });
+            const { price } = prepared.target;
+            return {
+                preview,
+                target: {
+                    tier,
+                    unitAmount: price.unitAmount ?? 0,
+                    currency: price.currency,
+                    interval: price.interval,
+                    intervalCount: price.intervalCount,
+                },
+            };
+        },
+    };
+}

package/dist/billing-foundation/handlers/process-event.write.d.ts

@@ -27,6 +27,12 @@ export declare const processEventSchema: z.ZodObject<{
     consentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ProcessEventPayload = z.infer<typeof processEventSchema>;
+export declare function isLateStateEvent(storedEvents: readonly {
+    readonly payload: unknown;
+    readonly metadata: {
+        readonly headers?: Record<string, unknown>;
+    };
+}[], payload: ProcessEventPayload): boolean;
 export declare function clampProviderEventAt(payload: ProcessEventPayload, now: Temporal.Instant): ProcessEventPayload;
 export declare function appendSubscriptionEvent(ctx: HandlerContext, tenantId: string, rawPayload: ProcessEventPayload, now?: Temporal.Instant): Promise<{
     readonly duplicate: boolean;

package/dist/billing-foundation/handlers/process-event.write.js

@@ -65,7 +65,7 @@ const STATE_EVENT_TYPES = new Set([
     SubscriptionEventTypes.updated,
     SubscriptionEventTypes.canceled,
 ]);
-function isLateStateEvent(storedEvents, payload) {
+export function isLateStateEvent(storedEvents, payload) {
     if (payload.providerEventAtIso === undefined || !STATE_EVENT_TYPES.has(payload.type)) {
         return false;
     }
@@ -79,7 +79,13 @@ function isLateStateEvent(storedEvents, payload) {
         // A stored value that does not parse can never prove a newer event; skip it instead of
         // failing every later delivery of this tenant's stream.
         try {
-            return Temporal.Instant.compare(Temporal.Instant.from(storedAt), incoming) > 0;
+            const order = Temporal.Instant.compare(Temporal.Instant.from(storedAt), incoming);
+            if (order !== 0)
+                return order > 0;
+            // Provider timestamps have second resolution: on a tie a stored cancellation wins over
+            // a non-terminal state, so a reordered same-second `updated` cannot revive a canceled one.
+            return (propertyOf(stored.payload, "status") === SubscriptionStatuses.canceled &&
+                payload.status !== SubscriptionStatuses.canceled);
         }
         catch {
             return false;

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>;