@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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

@@ -1,18 +1,18 @@
-// create-checkout-session — Tenant-Admin klickt "Upgrade to Pro" (oder
-// wählt zwischen Karte/PayPal/Apple-Pay). Handler findet den
-// providerName aus der payload, lookuppt den Plugin, ruft
-// `plugin.createCheckoutSession(ctx, ...)`, returnt hosted-page-URL.
-// Tenant-Admin wird dorthin redirected.
+// create-checkout-session — Tenant admin clicks "Upgrade to Pro" (or
+// chooses between card/PayPal/Apple Pay). The handler reads providerName
+// from the payload, looks up the plugin, calls
+// `plugin.createCheckoutSession(ctx, ...)`, and returns the hosted-page URL.
+// The tenant admin is redirected there.
 //
-// **Multi-Provider-Pfad:** payload.providerName ist der entityName
-// eines registrierten Plugins ("stripe" / "paypal" / "mollie" / ...).
-// App-Builder zeigt eine UI-Liste der gemounteten provider, Endkunde
-// pickt einen, dieser handler dispatched zum richtigen Plugin.
+// **Multi-provider path:** payload.providerName is the entityName
+// of a registered plugin ("stripe" / "paypal" / "mollie" / ...).
+// The app builder shows a UI list of mounted providers; the customer
+// selects one, and this handler dispatches to the matching plugin.
 //
-// **Tenant-resolution:** ctx.user.tenantId wird als metadata an den
-// Provider mitgegeben. Beim subsequent webhook (subscription.created)
-// liest verifyAndParseWebhook das aus dem provider-payload zurück und
-// resolved den Tenant.
+// **Tenant resolution:** ctx.user.tenantId is passed to the provider as
+// metadata. On the subsequent webhook (subscription.created),
+// verifyAndParseWebhook reads it back from the provider payload and
+// resolves the tenant.
 //
 // **Hardening:** successUrl/cancelUrl must share `options.baseUrl`'s
 // origin; mode:"subscription" requires priceId to be a known price of the
@@ -51,12 +51,13 @@ const createCheckoutSessionSchema = z.object({
   providerName: z.string().min(1).max(50),
   /** Provider-eigene price/plan-ID. */
   priceId: z.string().min(1).max(200),
-  /** Wo der Endkunde nach erfolgreichem checkout landed. */
+  /** Where the customer lands after a successful checkout. */
   successUrl: z.string().url(),
-  /** Wo der Endkunde landed wenn er abbricht. */
+  /** Where the customer lands if they cancel. */
   cancelUrl: z.string().url(),
-  /** Optional: existierender provider-customer wenn der Tenant schon
-   *  einen account beim Provider hat (= Plan-Wechsel statt Neuregistrierung). */
+  /** Optional: existing provider customer when the tenant already
+   *  has an account with the provider (= plan change instead of a new
+   *  registration). */
   providerCustomerId: z.string().max(200).optional(),
   /** Optional: `"payment"` for a one-off checkout (e.g. credit top-up)
    *  instead of a recurring subscription. Defaults to `"subscription"`. */
@@ -120,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/create-portal-session.write.ts

@@ -1,17 +1,16 @@
-// create-portal-session — Tenant-Admin klickt "Manage Subscription".
-// Handler findet die current subscription des Tenants, lookuppt den
-// passenden Plugin (= subscription.providerName-Spalte), ruft
-// `plugin.createPortalSession(ctx, ...)`, returnt hosted-portal-URL.
+// create-portal-session — Tenant admin clicks "Manage Subscription".
+// The handler finds the tenant's current subscription, looks up the matching
+// plugin (= the `subscription.providerName` column), calls
+// `plugin.createPortalSession(ctx, ...)`, and returns the hosted portal URL.
 //
-// **Provider-resolution:** anders als create-checkout-session (= der
-// Tenant wählt einen NEUEN Provider beim Subscribe) ist hier der
-// Provider durch die existing subscription-row festgelegt — Tenant
-// kann nicht zum Portal eines OTHER Providers, weil der ihn nicht
-// kennt.
+// **Provider resolution:** unlike create-checkout-session (where the tenant
+// chooses a NEW provider when subscribing), the provider here is fixed by the
+// existing subscription row. The tenant cannot access another provider's
+// portal because the subscription does not belong to that provider.
 //
-// **returnUrl:** computed server-side via `portalReturnUrl` (catalog's
-// returnPath, or baseUrl itself) — the client no longer supplies one, so
-// there is no client-controlled redirect to harden against.
+// **returnUrl:** computed server-side via `portalReturnUrl` (the catalog's
+// returnPath, or baseUrl itself). The client no longer supplies one, so there
+// is no client-controlled redirect to harden against.
 
 import {
   configuredPiiSubjectKms,

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

@@ -1,7 +1,7 @@
-// list-subscriptions — sysadmin-cross-tenant list-query auf der
-// `read_subscriptions`-projection. Tenant-Admins lesen ihre eigene
-// subscription via getSubscriptionForTenant-helper (= ctx.db ist
-// tenant-scoped, gibt automatisch nur die row des Callers zurück).
+// list-subscriptions — sysadmin cross-tenant list query on the
+// `read_subscriptions` projection. Tenant admins read their own
+// subscription through the getSubscriptionForTenant helper (= ctx.db is
+// tenant-scoped and automatically returns only the caller's row).
 import {
   configuredPiiSubjectKms,
   decryptPiiFieldValues,

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

@@ -1,16 +1,16 @@
-// process-event — programmatic write-handler den der webhook-handler
-// (createSubscriptionWebhookRoute) aufruft NACHDEM Plugin den raw-body
-// verifiziert + zu SubscriptionEvent normalisiert hat.
+// process-event — programmatic write handler called by the webhook handler
+// (createSubscriptionWebhookRoute) AFTER the plugin has verified the raw body
+// and normalized it into a SubscriptionEvent.
 //
-// **ES-Pattern:**
-//   1. Idempotency-check: lädt subscription-stream + scannt nach
-//      bereits gesehenem `metadata.providerEventId`. Provider-Replay
-//      (Stripe-Retry-Storm) sieht denselben event-id → duplicate=true,
-//      kein zweiter append.
-//   2. Type-mapping: SubscriptionEvent.type (= normalisiert vom Plugin)
-//      → einer der 5 ES-event-typen.
-//   3. ctx.unsafeAppendEvent — Inline-projection materialisiert die
-//      `read_subscriptions`-row in derselben TX.
+// **ES pattern:**
+//   1. Idempotency check: loads the subscription stream and scans for an
+//      already-seen `metadata.providerEventId`. A provider replay
+//      (Stripe retry storm) has the same event ID → duplicate=true,
+//      with no second append.
+//   2. Type mapping: SubscriptionEvent.type (= normalized by the plugin)
+//      → one of the 5 ES event types.
+//   3. ctx.unsafeAppendEvent — the inline projection materializes the
+//      `read_subscriptions` row in the same TX.
 
 import {
   configuredPiiSubjectKms,
@@ -42,9 +42,9 @@ import {
 } from "../web/constants.ts";
 
 // =============================================================================
-// Input-Schema = der normalisierte SubscriptionEvent (ohne tenantId, der
-// kommt aus event.user.tenantId — der webhook-handler setzt den
-// programmatic-user mit der vom Plugin aufgelösten tenantId).
+// Input schema = the normalized SubscriptionEvent (without tenantId, which
+// comes from event.user.tenantId — the webhook handler sets the
+// programmatic user with the tenantId resolved by the plugin).
 // =============================================================================
 
 const eventTypeSchema = z.enum([
@@ -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;
     }
@@ -208,9 +215,9 @@ export async function appendSubscriptionEvent(
   //    read_subscriptions row with a single call. The subject is the
   //    TENANT (tenantOwned) — tenant-destroy's subject-keys stage
   //    (eraseSubjectKeys) erases exactly this key, so both copies become
-  //    genuinely unreadable (#800) once that stage runs, not just
+  //    genuinely unreadable once that stage runs, not just
   //    "encrypted at rest". No adapter configured = engine off (fields
-  //    stay plaintext, pre-#724-phase-C behavior) — mirrors how the
+  //    stay plaintext) — mirrors how the
   //    event-store-executor treats an absent piiKms().
   // ---------------------------------------------------------------
   const piiKms = configuredPiiSubjectKms();
@@ -268,9 +275,9 @@ export async function appendSubscriptionEvent(
 // Handler
 // =============================================================================
 //
-// SystemAdmin-only: dieser handler wird ausschließlich vom programmatic
-// webhook-handler aufgerufen (mit einem internal SystemUser), nie vom
-// Tenant-Admin direkt.
+// SystemAdmin-only: this handler is called exclusively by the programmatic
+// webhook handler (with an internal SystemUser), never directly by the
+// tenant admin.
 // One subscription aggregate exists per tenant, but a tenant can legitimately hold two provider
 // subscriptions over time (a stale `incomplete` one superseded by a fresh checkout). A late or
 // retried event of the old subscription must not overwrite the row of the live one, so an event of a

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,