@cosmicdrift/kumiko-samples 0.387.0 → 0.389.0

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-revoke.ts

@@ -14,11 +14,9 @@ import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id.ts";
 import {
   CONTRACT_TERMINATION_DECLARED_EVENT_QN,
-  CONTRACT_TERMINATION_REQUESTED_EVENT_QN,
   CONTRACT_TERMINATION_REVOKED_EVENT_QN,
   type ContractTerminationRevokedPayload,
   contractTerminationDeclaredPayloadSchema,
-  contractTerminationRequestedPayloadSchema,
   SUBSCRIPTION_AGGREGATE_TYPE,
 } from "../events.ts";
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.ts";
@@ -26,7 +24,7 @@ import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from
 import { SubscriptionFoundationHandlers } from "../web/constants.ts";
 import type { ConsentLocale } from "./consent-text.ts";
 import { notifyOperator } from "./termination-notify.ts";
-import { hasRevocation, resumeAtProvider } from "./termination-record.ts";
+import { findRecordedTermination, hasRevocation, resumeAtProvider } from "./termination-record.ts";
 import type { OperatorNoticeReason } from "./termination-texts.ts";
 
 export const REVOCATION_PATHS: Readonly<Record<ConsentLocale, string>> = {
@@ -152,10 +150,7 @@ export function createRecordContractTerminationRevocationHandler(
       }
       if (hasRevocation(stream.events, payload.requestId)) return outcome("already-revoked");
 
-      const requested = stream.events
-        .filter((e) => e.type === CONTRACT_TERMINATION_REQUESTED_EVENT_QN)
-        .map((e) => contractTerminationRequestedPayloadSchema.safeParse(e.payload).data)
-        .find((candidate) => candidate?.requestId === payload.requestId);
+      const requested = findRecordedTermination(stream.events, payload.requestId);
       const subscription = await getSubscriptionForTenant(ctx, tenantId);
       const effectiveAtIso = requested?.effectiveAtIso ?? subscription?.currentPeriodEnd.toString();
       const now = options.now();
@@ -175,6 +170,17 @@ export function createRecordContractTerminationRevocationHandler(
         aggregateId: subscriptionAggregateId(tenantId),
         aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
       });
+      // A cancel recorded between the first fetch and now was never resumed above.
+      const requestedMeanwhile =
+        requested === undefined
+          ? findRecordedTermination(streamAfterProviderCall.events, payload.requestId)
+          : undefined;
+      if (requestedMeanwhile?.providerCancel === "period-end") {
+        reasons.push(
+          ...(await resumeAtProvider(ctx, await getSubscriptionForTenant(ctx, tenantId))),
+        );
+      }
+      const providerCancel = (requested ?? requestedMeanwhile)?.providerCancel;
       const revoked: ContractTerminationRevokedPayload = {
         requestId: payload.requestId,
         revokedAtIso: now.toString(),
@@ -194,7 +200,7 @@ export function createRecordContractTerminationRevocationHandler(
         },
         reasons,
         tenantId,
-        ...(requested !== undefined && { providerCancel: requested.providerCancel }),
+        ...(providerCancel !== undefined && { providerCancel }),
       });
       return outcome("revoked");
     },

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-texts.ts

@@ -91,6 +91,7 @@ export const OPERATOR_NOTICE_REASONS = [
   "recording_failed",
   "withdrawal_period_expired",
   "receipt_rate_limited",
+  "receipt_not_sent",
   "revoked",
   "revocation_resume_manual",
   "revocation_resume_failed",
@@ -145,6 +146,8 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
         "Widerruf nach Ablauf der Widerrufsfrist: zum Periodenende gekündigt, Anspruch prüfen",
       receipt_rate_limited:
         "Keine Eingangsbestätigung versendet: Limit pro Empfängeradresse erreicht",
+      receipt_not_sent:
+        "Keine Eingangsbestätigung versendet: Limit-Prüfung nicht verfügbar (Redis-Fehler oder fehlende Konfiguration)",
       revoked:
         "Die Erklärung wurde vom Postfachinhaber über „Diese Kündigung war ich nicht“ zurückgenommen",
       revocation_resume_manual:
@@ -256,6 +259,8 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       withdrawal_period_expired:
         "Withdrawal after the withdrawal period: cancelled at period end, review the claim",
       receipt_rate_limited: "No receipt mail sent: the per-recipient limit was reached",
+      receipt_not_sent:
+        "No receipt mail sent: the limit check was unavailable (limiter error or missing configuration)",
       revoked:
         'The declaration was taken back by the mailbox owner ("I did not request this cancellation")',
       revocation_resume_manual:

package/packages/bundled-features/src/billing-foundation/consumer-protection/withdrawal-period.ts

@@ -1,26 +1,24 @@
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_QN } from "../events.ts";
+import { SUBSCRIPTION_CREATED_EVENT_QN } from "../events.ts";
 
 // § 355 BGB: the withdrawal period is 14 days from conclusion of the contract.
 export const WITHDRAWAL_PERIOD_DAYS = 14;
 const HOURS_PER_DAY = 24;
 
-const PERIOD_START_EVENT_TYPES: ReadonlySet<string> = new Set([
-  CHECKOUT_CONSENT_RECORDED_EVENT_QN,
-  SUBSCRIPTION_CREATED_EVENT_QN,
-]);
-
 type PeriodStartEvent = { readonly type: string; readonly createdAt: Temporal.Instant };
 
-/** The period runs from the latest consent or subscription start on the stream.
- *  A stream with neither has no provable start and counts as expired. */
+/** The period runs from the latest subscription start on the stream. A checkout
+ *  consent alone never restarts it: it is written before the buyer reaches the
+ *  provider, so an abandoned plan-change checkout would otherwise reopen the
+ *  period of a long-concluded contract. A stream without a subscription start
+ *  has no provable start and counts as expired. */
 export function isWithinWithdrawalPeriod(
   events: readonly PeriodStartEvent[],
   now: Temporal.Instant,
 ): boolean {
   let latestStart: Temporal.Instant | undefined;
   for (const event of events) {
-    if (!PERIOD_START_EVENT_TYPES.has(event.type)) continue;
+    if (event.type !== SUBSCRIPTION_CREATED_EVENT_QN) continue;
     if (
       latestStart === undefined ||
       event.createdAt.epochMilliseconds > latestStart.epochMilliseconds
@@ -28,7 +26,7 @@ export function isWithinWithdrawalPeriod(
       latestStart = event.createdAt;
     }
   }
-  // skip: no consent or subscription-created event, nothing proves a running period
+  // skip: no subscription-created event, nothing proves a running period
   if (latestStart === undefined) return false;
   const periodEnd = latestStart.add({ hours: WITHDRAWAL_PERIOD_DAYS * HOURS_PER_DAY });
   return now.epochMilliseconds <= periodEnd.epochMilliseconds;

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

@@ -141,6 +141,7 @@ export const checkoutConsentRecordedPayloadSchema = z.object({
   termsTemplateVersion: z.number(),
   locale: z.string().min(2).max(35),
   actorUserId: z.string().min(1),
+  providerName: z.string().min(1).max(100).optional(),
   itemLabelKey: z.string().min(1).max(200).optional(),
   itemLabelParams: z.record(z.string(), z.union([z.string().max(100), z.number()])).optional(),
 });

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

@@ -79,6 +79,7 @@ import { createBillingPlansQuery } from "./handlers/billing-plans.query.ts";
 import { createCheckoutSessionHandler } from "./handlers/create-checkout-session.write.ts";
 import { createPortalSessionHandler } from "./handlers/create-portal-session.write.ts";
 import { listSubscriptionsQuery } from "./handlers/list-subscriptions.query.ts";
+import { createPlanSwitchPreviewQuery } from "./handlers/plan-switch-preview.query.ts";
 import { createProcessEventHandler } from "./handlers/process-event.write.ts";
 import { processPaymentEventHandler } from "./handlers/process-payment-event.write.ts";
 import { createStartPlanCheckoutHandler } from "./handlers/start-plan-checkout.write.ts";
@@ -137,7 +138,7 @@ export function createBillingFoundationFeature<TTier extends string = string>(
     BILLING_FOUNDATION_FEATURE,
     (r) => {
       r.describe(
-        "Plugin host for subscription billing — manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers and a dormant billing-plans dashboard screen/panel from the catalog. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event — catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block — use `subscription-stripe` or `subscription-mollie` unless you are writing a new payment provider.",
+        "Plugin host for subscription billing. Manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers, a `plan-switch-preview` query and a dormant billing-plans dashboard screen/panel from the catalog. Several providers can be mounted at once: new checkouts are offered by every enabled provider (enabled means keys set and billingLive on, or simply mounted for plugins without `isBillingEnabled`), the customer picks one in the plan panel and `start-plan-checkout` takes a `providerName`. An existing subscription stays with the provider that stored it, so the plan list and every switch follow that provider. A plan switch is either hosted (`createPlanSwitchSession` answers a url) or in-app (`previewPlanSwitch` shows the proration, `applyPlanSwitch` runs after the customer confirms; `switch-plan` then answers `{ applied: true }` and records the consent). `consumerProtection.providerTexts` overrides the checkout note and the VAT note per provider. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event, which catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block: use `subscription-stripe`, `subscription-mollie` or `subscription-dodo` unless you are writing a new payment provider.",
       );
       r.uiHints({
         displayLabel: "Billing · Foundation",
@@ -239,6 +240,7 @@ export function createBillingFoundationFeature<TTier extends string = string>(
       if (widened.catalog) {
         const { catalog } = widened;
         r.queryHandler(createBillingPlansQuery(widened, catalog));
+        r.queryHandler(createPlanSwitchPreviewQuery(catalog));
         r.writeHandler(createStartPlanCheckoutHandler(widened, catalog));
         r.writeHandler(createSwitchPlanHandler(widened, catalog));
         r.screen(createBillingPlansScreen(catalog.viewRoles));

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,
         });
       }