@cosmicdrift/kumiko-bundled-features 0.387.0 → 0.388.0

package/dist/billing-foundation/consumer-protection/termination-record.d.ts

@@ -1,6 +1,6 @@
 import { type HandlerContext, type QueryHandlerDef, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { type ProviderCancelOutcome } from "../events.ts";
+import { type ContractTerminationRequestedPayload, type ProviderCancelOutcome } from "../events.ts";
 import { type SubscriptionView } from "../get-subscription-for-tenant.ts";
 import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.ts";
 import type { OperatorNoticeReason } from "./termination-texts.ts";
@@ -74,6 +74,10 @@ export declare const terminableSubscriptionSchema: z.ZodObject<{}, z.core.$stric
 export declare function createTerminableSubscriptionQuery(): QueryHandlerDef;
 export declare function createDeclareContractTerminationHandler(): WriteHandlerDef;
 export declare function createRecordContractTerminationHandler(options: ResolvedBillingFoundationOptions, consumerProtection: ConsumerProtectionOptions): WriteHandlerDef;
+export declare function findRecordedTermination(events: readonly {
+    type: string;
+    payload: unknown;
+}[], requestId: string): ContractTerminationRequestedPayload | undefined;
 export declare function hasRevocation(events: readonly {
     type: string;
     payload: unknown;

package/dist/billing-foundation/consumer-protection/termination-record.js

@@ -173,23 +173,9 @@ export function createRecordContractTerminationHandler(options, consumerProtecti
             });
             // The public job runs at least once: a second run must not call the
             // provider or append again.
-            const alreadyRecorded = stream.events
-                .map((e) => e.type === CONTRACT_TERMINATION_REQUESTED_EVENT_QN
-                ? contractTerminationRequestedPayloadSchema.safeParse(e.payload).data
-                : undefined)
-                .find((recordedPayload) => recordedPayload?.requestId === payload.requestId);
-            if (alreadyRecorded) {
-                return {
-                    isSuccess: true,
-                    data: {
-                        receivedAtIso: alreadyRecorded.receivedAtIso,
-                        effectiveAtIso: alreadyRecorded.effectiveAtIso,
-                        providerCancel: alreadyRecorded.providerCancel,
-                        noticeReason: null,
-                        withdrawalPeriodExpired: false,
-                    },
-                };
-            }
+            const alreadyRecorded = findRecordedTermination(stream.events, payload.requestId);
+            if (alreadyRecorded)
+                return recordedTerminationResult(alreadyRecorded);
             // A revoked public declaration never reaches the provider.
             if (hasRevocation(stream.events, payload.requestId)) {
                 return revokedRecordResult(receivedAtIso);
@@ -214,6 +200,11 @@ export function createRecordContractTerminationHandler(options, consumerProtecti
                 aggregateId: subscriptionAggregateId(tenantId),
                 aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
             });
+            // A concurrent run with the same requestId may have recorded while we were
+            // at the provider; a second append would duplicate the event and the notice.
+            const recordedMeanwhile = findRecordedTermination(streamAfterProviderCall.events, payload.requestId);
+            if (recordedMeanwhile)
+                return recordedTerminationResult(recordedMeanwhile);
             // A revocation that landed during the provider call found no cancel to take back.
             if (hasRevocation(streamAfterProviderCall.events, payload.requestId)) {
                 await takeBackLateRevokedCancel(ctx, consumerProtection, {
@@ -258,6 +249,25 @@ export function createRecordContractTerminationHandler(options, consumerProtecti
         },
     };
 }
+export function findRecordedTermination(events, requestId) {
+    return events
+        .map((e) => e.type === CONTRACT_TERMINATION_REQUESTED_EVENT_QN
+        ? contractTerminationRequestedPayloadSchema.safeParse(e.payload).data
+        : undefined)
+        .find((recordedPayload) => recordedPayload?.requestId === requestId);
+}
+function recordedTerminationResult(recorded) {
+    return {
+        isSuccess: true,
+        data: {
+            receivedAtIso: recorded.receivedAtIso,
+            effectiveAtIso: recorded.effectiveAtIso,
+            providerCancel: recorded.providerCancel,
+            noticeReason: null,
+            withdrawalPeriodExpired: false,
+        },
+    };
+}
 export function hasRevocation(events, requestId) {
     return events.some((e) => e.type === CONTRACT_TERMINATION_REVOKED_EVENT_QN &&
         contractTerminationRevokedPayloadSchema.safeParse(e.payload).data?.requestId === requestId);

package/dist/billing-foundation/consumer-protection/termination-request.js

@@ -6,13 +6,13 @@ import { createSystemUser, declareEscapeHatch, SYSTEM_TENANT_ID, } from "@cosmic
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
+import { decryptStoredUserEmail } from "../../shared/index.js";
 import { TenantQueries } from "../../tenant/index.js";
 import { UserQueries } from "../../user/index.js";
 import { CONTRACT_TERMINATION_DECLARATION_TYPES, CONTRACT_TERMINATION_KINDS, } from "../events.js";
 import { purchaseRolesOf } from "../plan-catalog.js";
 import { CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, SubscriptionCancelTimings, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, } from "../web/constants.js";
 import { resolveConsentLocale } from "./consent-text.js";
-import { openStoredUserEmail } from "./stored-user-email.js";
 import { terminationReceiptVariables } from "./termination-mail.js";
 import { notifyOperator, requireNotify } from "./termination-notify.js";
 import { mayMailReceipt } from "./termination-receipt-limit.js";
@@ -54,9 +54,16 @@ function needsOperatorNotice(declaration) {
         ...(declaration.terminationKind === "extraordinary" ? ["extraordinary"] : []),
     ];
 }
+function receiptWithheldReasons(verdict) {
+    if (verdict === "limited")
+        return ["receipt_rate_limited"];
+    if (verdict === "unavailable")
+        return ["receipt_not_sent"];
+    return [];
+}
 async function sendTerminationMails(ctx, consumerProtection, plan) {
-    const receiptAllowed = await mayMailReceipt(ctx, plan.declaration.email);
-    if (receiptAllowed) {
+    const receiptVerdict = await mayMailReceipt(ctx, plan.declaration.email);
+    if (receiptVerdict === "allowed") {
         await requireNotify(ctx)(CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, {
             route: { email: plan.declaration.email },
             data: terminationReceiptVariables({
@@ -74,9 +81,7 @@ async function sendTerminationMails(ctx, consumerProtection, plan) {
             priority: "critical",
         });
     }
-    const reasons = receiptAllowed
-        ? plan.reasons
-        : [...plan.reasons, "receipt_rate_limited"];
+    const reasons = [...plan.reasons, ...receiptWithheldReasons(receiptVerdict)];
     // skip: no operator notice needed for this declaration
     if (reasons.length === 0)
         return;
@@ -217,7 +222,7 @@ export function createTerminateContractHandler(options, consumerProtection) {
                 id: event.user.id,
             }));
             const callerEmail = caller.success && caller.data.email && caller.data.isDeleted !== true
-                ? await openStoredUserEmail(caller.data.email, "billing-foundation:terminate-contract")
+                ? await decryptStoredUserEmail(caller.data.email, "billing-foundation:terminate-contract")
                 : null;
             if (callerEmail === null) {
                 throw new InternalError({

package/dist/billing-foundation/consumer-protection/termination-revoke.js

@@ -7,11 +7,11 @@ import { access, createSystemUser, } from "@cosmicdrift/kumiko-framework/engine"
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id.js";
-import { CONTRACT_TERMINATION_DECLARED_EVENT_QN, CONTRACT_TERMINATION_REQUESTED_EVENT_QN, CONTRACT_TERMINATION_REVOKED_EVENT_QN, contractTerminationDeclaredPayloadSchema, contractTerminationRequestedPayloadSchema, SUBSCRIPTION_AGGREGATE_TYPE, } from "../events.js";
+import { CONTRACT_TERMINATION_DECLARED_EVENT_QN, CONTRACT_TERMINATION_REVOKED_EVENT_QN, contractTerminationDeclaredPayloadSchema, SUBSCRIPTION_AGGREGATE_TYPE, } from "../events.js";
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
 import { SubscriptionFoundationHandlers } from "../web/constants.js";
 import { notifyOperator } from "./termination-notify.js";
-import { hasRevocation, resumeAtProvider } from "./termination-record.js";
+import { findRecordedTermination, hasRevocation, resumeAtProvider } from "./termination-record.js";
 export const REVOCATION_PATHS = {
     de: "/legal/kuendigen/zuruecknehmen",
     en: "/legal/cancel/revoke",
@@ -102,10 +102,7 @@ export function createRecordContractTerminationRevocationHandler(options, consum
             }
             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();
@@ -122,6 +119,14 @@ export function createRecordContractTerminationRevocationHandler(options, consum
                 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 = {
                 requestId: payload.requestId,
                 revokedAtIso: now.toString(),
@@ -141,7 +146,7 @@ export function createRecordContractTerminationRevocationHandler(options, consum
                 },
                 reasons,
                 tenantId,
-                ...(requested !== undefined && { providerCancel: requested.providerCancel }),
+                ...(providerCancel !== undefined && { providerCancel }),
             });
             return outcome("revoked");
         },

package/dist/billing-foundation/consumer-protection/termination-texts.d.ts

@@ -74,6 +74,6 @@ export type RevokePageTexts = {
     readonly invalidTitle: string;
     readonly invalidBody: string;
 };
-export declare const OPERATOR_NOTICE_REASONS: readonly ["unmatched", "ambiguous", "withdrawal", "extraordinary", "provider_cannot_cancel", "provider_error", "no_active_subscription", "recording_failed", "withdrawal_period_expired", "receipt_rate_limited", "revoked", "revocation_resume_manual", "revocation_resume_failed"];
+export declare const OPERATOR_NOTICE_REASONS: readonly ["unmatched", "ambiguous", "withdrawal", "extraordinary", "provider_cannot_cancel", "provider_error", "no_active_subscription", "recording_failed", "withdrawal_period_expired", "receipt_rate_limited", "receipt_not_sent", "revoked", "revocation_resume_manual", "revocation_resume_failed"];
 export type OperatorNoticeReason = (typeof OPERATOR_NOTICE_REASONS)[number];
 export declare const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>>;

package/dist/billing-foundation/consumer-protection/termination-texts.js

@@ -9,6 +9,7 @@ export const OPERATOR_NOTICE_REASONS = [
     "recording_failed",
     "withdrawal_period_expired",
     "receipt_rate_limited",
+    "receipt_not_sent",
     "revoked",
     "revocation_resume_manual",
     "revocation_resume_failed",
@@ -55,6 +56,7 @@ export const TERMINATION_TEXTS = {
             recording_failed: "Die Erklärung konnte nicht gespeichert werden",
             withdrawal_period_expired: "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: "Die Kündigung beim Zahlungsanbieter bitte manuell zurücknehmen (keine Schnittstelle dafür)",
             revocation_resume_failed: "Die Kündigung beim Zahlungsanbieter konnte nicht zurückgenommen werden, bitte manuell zurücknehmen",
@@ -154,6 +156,7 @@ export const TERMINATION_TEXTS = {
             recording_failed: "The declaration could not be stored",
             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: "Undo the cancellation at the payment provider manually (no API for it)",
             revocation_resume_failed: "Undoing the cancellation at the payment provider failed, undo it manually",

package/dist/billing-foundation/consumer-protection/withdrawal-period.d.ts

@@ -4,7 +4,10 @@ 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 declare function isWithinWithdrawalPeriod(events: readonly PeriodStartEvent[], now: Temporal.Instant): boolean;
 export {};

package/dist/billing-foundation/consumer-protection/withdrawal-period.js

@@ -1,24 +1,23 @@
-import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_QN } from "../events.js";
+import { SUBSCRIPTION_CREATED_EVENT_QN } from "../events.js";
 // § 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 = new Set([
-    CHECKOUT_CONSENT_RECORDED_EVENT_QN,
-    SUBSCRIPTION_CREATED_EVENT_QN,
-]);
-/** 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, now) {
     let latestStart;
     for (const event of events) {
-        if (!PERIOD_START_EVENT_TYPES.has(event.type))
+        if (event.type !== SUBSCRIPTION_CREATED_EVENT_QN)
             continue;
         if (latestStart === undefined ||
             event.createdAt.epochMilliseconds > latestStart.epochMilliseconds) {
             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 });

package/dist/billing-foundation/events.d.ts

@@ -66,6 +66,7 @@ export declare const checkoutConsentRecordedPayloadSchema: z.ZodObject<{
     termsTemplateVersion: z.ZodNumber;
     locale: z.ZodString;
     actorUserId: z.ZodString;
+    providerName: z.ZodOptional<z.ZodString>;
     itemLabelKey: z.ZodOptional<z.ZodString>;
     itemLabelParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
 }, z.core.$strip>;

package/dist/billing-foundation/events.js

@@ -104,6 +104,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/dist/billing-foundation/feature.js

@@ -57,6 +57,7 @@ import { createBillingPlansQuery } from "./handlers/billing-plans.query.js";
 import { createCheckoutSessionHandler } from "./handlers/create-checkout-session.write.js";
 import { createPortalSessionHandler } from "./handlers/create-portal-session.write.js";
 import { listSubscriptionsQuery } from "./handlers/list-subscriptions.query.js";
+import { createPlanSwitchPreviewQuery } from "./handlers/plan-switch-preview.query.js";
 import { createProcessEventHandler } from "./handlers/process-event.write.js";
 import { processPaymentEventHandler } from "./handlers/process-payment-event.write.js";
 import { createStartPlanCheckoutHandler } from "./handlers/start-plan-checkout.write.js";
@@ -89,7 +90,7 @@ export function createBillingFoundationFeature(options = {}) {
         }),
     };
     return defineFeature(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.");
+        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, 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",
             category: "billing",
@@ -183,6 +184,7 @@ export function createBillingFoundationFeature(options = {}) {
         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/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;