@cosmicdrift/kumiko-samples 0.387.0 → 0.388.0

package/packages/bundled-features/src/billing-foundation/handlers/billing-plans.query.ts

@@ -2,18 +2,29 @@
 // benefits, the caller's current tier and per-plan action. Only registered
 // when `createBillingFoundationFeature` gets a `catalog`.
 
-import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type { HandlerContext, QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { findCatalogProvider } from "../checkout-core.ts";
+import {
+  filterOfferedProviders,
+  listCatalogProviders,
+  type ResolvedProvider,
+} from "../checkout-core.ts";
 import {
   type CONSENT_LOCALES,
   CONSENT_TEXTS,
   consentTextVersion,
 } from "../consumer-protection/consent-text.ts";
-import { buildBillingPlans } from "../plan-catalog.ts";
+import {
+  type BillingPlansBase,
+  buildProviderPlanViews,
+  loadBillingPlansBase,
+  type ProviderPlanViews,
+  toBillingPlansResult,
+} from "../plan-catalog.ts";
 import {
   type BillingPlanCatalog,
   type BillingPlansResult,
+  type BillingProviderView,
   type ConsumerProtectionOptions,
   isLegalLinkSet,
   type LegalLinkSet,
@@ -29,12 +40,12 @@ export function createBillingPlansQuery(
   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.",
+      "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): Promise<BillingPlansResult> => {
-      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;
       return {
@@ -51,6 +62,60 @@ export function createBillingPlansQuery(
   };
 }
 
+// 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: HandlerContext,
+  options: ResolvedBillingFoundationOptions,
+  catalog: BillingPlanCatalog,
+  base: BillingPlansBase,
+): Promise<BillingPlansResult> {
+  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: HandlerContext,
+  catalog: BillingPlanCatalog,
+  base: BillingPlansBase,
+  provider: ResolvedProvider,
+  providerTexts: ConsumerProtectionOptions["providerTexts"],
+  known: ProviderPlanViews | null,
+): Promise<BillingProviderView> {
+  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: ConsumerProtectionOptions["legalLinks"],
 ): Readonly<Record<(typeof CONSENT_LOCALES)[number], LegalLinkSet>> {

package/packages/bundled-features/src/billing-foundation/handlers/create-checkout-session.write.ts

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

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

@@ -0,0 +1,65 @@
+// 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 type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { isNonEmptyStringArray } from "../checkout-core.ts";
+import { purchaseRolesOf } from "../plan-catalog.ts";
+import { preparePlanSwitch } from "../plan-switch.ts";
+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 function createPlanSwitchPreviewQuery(catalog: BillingPlanCatalog): QueryHandlerDef {
+  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): Promise<PlanSwitchPreviewResult> => {
+      // @cast-boundary engine-payload — dispatcher-zod-validated payload
+      const { tier } = query.payload as { tier: string };
+      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/packages/bundled-features/src/billing-foundation/handlers/process-event.write.ts

@@ -93,7 +93,7 @@ const STATE_EVENT_TYPES: ReadonlySet<string> = new Set([
   SubscriptionEventTypes.canceled,
 ]);
 
-function isLateStateEvent(
+export function isLateStateEvent(
   storedEvents: readonly {
     readonly payload: unknown;
     readonly metadata: { readonly headers?: Record<string, unknown> };
@@ -111,7 +111,14 @@ function isLateStateEvent(
     // 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/packages/bundled-features/src/billing-foundation/handlers/start-plan-checkout.write.ts

@@ -3,16 +3,17 @@
 // the tier's live price server-side and opens a hosted checkout for it.
 // Only registered when `createBillingFoundationFeature` gets a `catalog`.
 
-import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import type { HandlerContext, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { FeatureDisabledError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import {
   assertBillingEnabled,
   assertNoActiveSubscription,
   isNonEmptyStringArray,
   joinBaseUrl,
+  listOfferedCatalogProviders,
   openCheckout,
-  resolveCatalogProvider,
+  type ResolvedProvider,
 } from "../checkout-core.ts";
 import {
   type ConsentPayload,
@@ -23,6 +24,36 @@ import {
 } from "../consumer-protection/consent-gate.ts";
 import { purchaseRolesOf, resolvePlanPrices } from "../plan-catalog.ts";
 import type { BillingPlanCatalog, ResolvedBillingFoundationOptions } from "../types.ts";
+import { BILLING_FOUNDATION_FEATURE } from "../web/constants.ts";
+
+/** 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: HandlerContext,
+  catalog: BillingPlanCatalog,
+  requestedName: string | undefined,
+): Promise<ResolvedProvider> {
+  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: ResolvedBillingFoundationOptions,
@@ -33,7 +64,7 @@ export function createStartPlanCheckoutHandler(
     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() })
@@ -43,16 +74,20 @@ export function createStartPlanCheckoutHandler(
   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.",
+      "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 as { tier: string; consent?: ConsentPayload };
-      const { name: providerName, plugin } = resolveCatalogProvider(
+      const payload = event.payload as {
+        tier: string;
+        providerName?: string;
+        consent?: ConsentPayload;
+      };
+      const { name: providerName, plugin } = await pickCheckoutProvider(
         ctx,
         catalog,
-        "start-plan-checkout",
+        payload.providerName,
       );
       await assertBillingEnabled(ctx, plugin, "start-plan-checkout");
 
@@ -98,6 +133,7 @@ export function createStartPlanCheckoutHandler(
           tier: payload.tier,
           priceId: resolved.priceId,
           price: resolved.price,
+          providerName,
         });
       }
 

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

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

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

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

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

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

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

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