@cosmicdrift/kumiko-bundled-features 0.387.0 → 0.389.0

package/dist/billing-foundation/checkout-core.d.ts

@@ -17,20 +17,15 @@ export type ResolvedProvider = {
  *  entityName is registered. */
 export declare function findProviderPlugin(ctx: HandlerContext, providerName: string): ResolvedProvider | null;
 export declare function resolveProviderPlugin(ctx: HandlerContext, providerName: string): ResolvedProvider;
-/** Picks the catalog's provider — an explicit `catalog.providerName`, or the
- *  single registered provider exposing `priceToTier` when there is exactly
- *  one. Returns null when `providerName` is unset and no registered plugin
- *  exposes `priceToTier` — a state `billing-plans` renders as
- *  `enabled: false` instead of erroring. An explicit `providerName` that is
- *  not registered, or more than one candidate, is a config bug and throws
- *  `UnconfiguredError`. */
-export declare function findCatalogProvider(ctx: HandlerContext, catalog: BillingPlanCatalog): ResolvedProvider | null;
-/** `findCatalogProvider` for callers that require a provider to proceed —
- *  start-plan-checkout and switch-plan. `FeatureDisabledError` (not
- *  `UnconfiguredError`) when none is found: an unconfigured provider is
- *  the same "billing isn't live yet" state as `isPluginBillingEnabled`
- *  returning false, and the panel already renders both the same way. */
-export declare function resolveCatalogProvider(ctx: HandlerContext, catalog: BillingPlanCatalog, handlerName: string): ResolvedProvider;
+/** The providers a catalog sells through, in registration order: an explicit
+ *  `catalog.providerName` (only that one), otherwise every registered provider
+ *  exposing `priceToTier`. Empty when none qualifies, a state `billing-plans`
+ *  renders as `enabled: false` instead of erroring. An explicit `providerName`
+ *  that is not registered is a config bug and throws `UnconfiguredError`. */
+export declare function listCatalogProviders(ctx: HandlerContext, catalog: BillingPlanCatalog): readonly ResolvedProvider[];
+export declare function filterOfferedProviders(ctx: HandlerContext, providers: readonly ResolvedProvider[]): Promise<readonly ResolvedProvider[]>;
+/** The catalog providers that are live right now: what a buyer can choose from. */
+export declare function listOfferedCatalogProviders(ctx: HandlerContext, catalog: BillingPlanCatalog): Promise<readonly ResolvedProvider[]>;
 /** `plugin.isBillingEnabled?.(ctx) ?? true` — the one place this fallback is
  *  spelled out, so no call-site forgets to await the optional method before
  *  applying the `?? true` default. */

package/dist/billing-foundation/checkout-core.js

@@ -15,14 +15,18 @@ import { BILLING_FOUNDATION_FEATURE, isSubscriptionBlockingCheckout, SUBSCRIPTIO
 export function isNonEmptyStringArray(arr) {
     return arr.length > 0;
 }
+/** Every registered provider plugin, in registration order. */
+function listProviderPlugins(ctx) {
+    return ctx.registry.getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION).map((usage) => ({
+        name: usage.entityName,
+        // @cast-boundary engine-payload — extension-usage carries unknown options
+        plugin: usage.options,
+    }));
+}
 /** Non-throwing provider lookup by name — null when no plugin with that
  *  entityName is registered. */
 export function findProviderPlugin(ctx, providerName) {
-    const usage = ctx.registry
-        .getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION)
-        .find((u) => u.entityName === providerName);
-    // @cast-boundary engine-payload — extension-usage carries unknown options
-    return usage ? { name: providerName, plugin: usage.options } : null;
+    return listProviderPlugins(ctx).find((provider) => provider.name === providerName) ?? null;
 }
 export function resolveProviderPlugin(ctx, providerName) {
     const found = findProviderPlugin(ctx, providerName);
@@ -35,14 +39,12 @@ export function resolveProviderPlugin(ctx, providerName) {
     }
     return found;
 }
-/** Picks the catalog's provider — an explicit `catalog.providerName`, or the
- *  single registered provider exposing `priceToTier` when there is exactly
- *  one. Returns null when `providerName` is unset and no registered plugin
- *  exposes `priceToTier` — a state `billing-plans` renders as
- *  `enabled: false` instead of erroring. An explicit `providerName` that is
- *  not registered, or more than one candidate, is a config bug and throws
- *  `UnconfiguredError`. */
-export function findCatalogProvider(ctx, catalog) {
+/** The providers a catalog sells through, in registration order: an explicit
+ *  `catalog.providerName` (only that one), otherwise every registered provider
+ *  exposing `priceToTier`. Empty when none qualifies, a state `billing-plans`
+ *  renders as `enabled: false` instead of erroring. An explicit `providerName`
+ *  that is not registered is a config bug and throws `UnconfiguredError`. */
+export function listCatalogProviders(ctx, catalog) {
     if (catalog.providerName) {
         const found = findProviderPlugin(ctx, catalog.providerName);
         if (!found) {
@@ -52,34 +54,17 @@ export function findCatalogProvider(ctx, catalog) {
                 hint: `provider "${catalog.providerName}" not registered`,
             });
         }
-        return found;
-    }
-    const usages = ctx.registry.getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION);
-    const withPriceCatalog = usages.filter((u) => u.options.priceToTier !== undefined);
-    if (withPriceCatalog.length > 1) {
-        throw new UnconfiguredError({
-            feature: "billing-foundation",
-            key: "catalog.providerName",
-            hint: `ambiguous — ${withPriceCatalog.length} registered plugins expose priceToTier, set catalog.providerName explicitly`,
-        });
+        return [found];
     }
-    const usage = withPriceCatalog[0];
-    if (!usage)
-        return null;
-    // @cast-boundary engine-payload — extension-usage carries unknown options
-    return { name: usage.entityName, plugin: usage.options };
+    return listProviderPlugins(ctx).filter(({ plugin }) => plugin.priceToTier !== undefined);
 }
-/** `findCatalogProvider` for callers that require a provider to proceed —
- *  start-plan-checkout and switch-plan. `FeatureDisabledError` (not
- *  `UnconfiguredError`) when none is found: an unconfigured provider is
- *  the same "billing isn't live yet" state as `isPluginBillingEnabled`
- *  returning false, and the panel already renders both the same way. */
-export function resolveCatalogProvider(ctx, catalog, handlerName) {
-    const found = findCatalogProvider(ctx, catalog);
-    if (!found) {
-        throw new FeatureDisabledError(BILLING_FOUNDATION_FEATURE, handlerName);
-    }
-    return found;
+export async function filterOfferedProviders(ctx, providers) {
+    const enabledFlags = await Promise.all(providers.map(({ plugin }) => isPluginBillingEnabled(ctx, plugin)));
+    return providers.filter((_, index) => enabledFlags[index]);
+}
+/** The catalog providers that are live right now: what a buyer can choose from. */
+export async function listOfferedCatalogProviders(ctx, catalog) {
+    return filterOfferedProviders(ctx, listCatalogProviders(ctx, catalog));
 }
 /** `plugin.isBillingEnabled?.(ctx) ?? true` — the one place this fallback is
  *  spelled out, so no call-site forgets to await the optional method before

package/dist/billing-foundation/consumer-protection/confirmation-mail.js

@@ -112,8 +112,14 @@ inlineHtmlMarkdown.use({
         blockquote({ tokens }) {
             return this.parser.parse(tokens);
         },
-        list({ items }) {
-            return items.map((item) => this.parser.parse(item.tokens)).join("");
+        list({ items, ordered, start }) {
+            const firstNumber = typeof start === "number" ? start : 1;
+            return items
+                .map((item, index) => {
+                const marker = ordered ? `${firstNumber + index}. ` : "";
+                return `${marker}${this.parser.parse(item.tokens)}`;
+            })
+                .join("");
         },
         hr: () => "",
         space: () => "",

package/dist/billing-foundation/consumer-protection/consent-gate.d.ts

@@ -30,6 +30,7 @@ export type ConsentPriceDetails = {
     readonly priceId: string;
     readonly price: Pick<ProviderPrice, "unitAmount" | "currency" | "interval" | "intervalCount"> | null;
     readonly orderItem?: OrderItem;
+    readonly providerName?: string;
 };
 export declare function prepareConsent(ctx: HandlerContext, options: ConsumerProtectionOptions, consent: ConsentPayload | undefined, mode: CheckoutMode): Promise<PreparedConsent>;
 export declare function consentCheckoutFields(prepared: PreparedConsent): {

package/dist/billing-foundation/consumer-protection/consent-gate.js

@@ -104,6 +104,7 @@ export async function recordConsent(ctx, prepared, details) {
         termsTemplateVersion: prepared.termsTemplateVersion,
         locale: prepared.locale,
         actorUserId: String(ctx.user.id),
+        ...(details.providerName !== undefined && { providerName: details.providerName }),
         ...(details.orderItem && {
             itemLabelKey: details.orderItem.labelKey,
             ...(details.orderItem.params && { itemLabelParams: details.orderItem.params }),

package/dist/billing-foundation/consumer-protection/issue-confirmation.js

@@ -6,6 +6,7 @@ import { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework
 import { createI18n } from "@cosmicdrift/kumiko-framework/i18n";
 import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
+import { decryptStoredUserEmail } from "../../shared/index.js";
 import { requireTemplateResolver, TEXT_BLOCK_KIND } from "../../template-resolver/index.js";
 import { UserQueries } from "../../user/index.js";
 import { paymentAggregateId, subscriptionAggregateId } from "../aggregate-id.js";
@@ -13,7 +14,6 @@ import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, CONTRACT_CONFIRMATION_ISSUED_EVENT_
 import { CONTRACT_CONFIRMATION_NOTIFICATION_TYPE } from "../web/constants.js";
 import { contractConfirmationVariables } from "./confirmation-mail.js";
 import { resolveConsentLocale } from "./consent-text.js";
-import { openStoredUserEmail } from "./stored-user-email.js";
 export const issueContractConfirmationSchema = z
     .object({
     consentId: z.string().min(1).max(100),
@@ -31,6 +31,12 @@ const recipientRowSchema = z.object({
 function translatedOrUndefined(translation, key) {
     return translation === key ? undefined : translation;
 }
+function vatNoteFor(consumerProtection, providerName) {
+    const providerNote = providerName === undefined
+        ? undefined
+        : consumerProtection.providerTexts?.[providerName]?.vatNote;
+    return providerNote ?? consumerProtection.vatNote;
+}
 function pickTimeZone(userZone, tenantZone) {
     if (userZone && isValidIanaTimeZone(userZone))
         return userZone;
@@ -102,7 +108,7 @@ export function createIssueContractConfirmationHandler(options, consumerProtecti
                 id: consent.actorUserId,
             }));
             const recipientEmail = recipient.success && recipient.data.isDeleted !== true
-                ? await openStoredUserEmail(recipient.data.email, "billing-foundation:issue-contract-confirmation")
+                ? await decryptStoredUserEmail(recipient.data.email, "billing-foundation:issue-contract-confirmation")
                 : null;
             if (!recipient.success || recipientEmail === null) {
                 ctx.log?.warn(`[billing-foundation:issue-contract-confirmation] recipient of consent ${payload.consentId} not found; no mail sent`);
@@ -142,7 +148,7 @@ export function createIssueContractConfirmationHandler(options, consumerProtecti
                 ...(payload.currentPeriodEndIso !== undefined && {
                     currentPeriodEndIso: payload.currentPeriodEndIso,
                 }),
-                vatNote: consumerProtection.vatNote,
+                vatNote: vatNoteFor(consumerProtection, consent.providerName),
                 operatorEmail: consumerProtection.operatorEmail,
                 termsContent: terms.content,
             });

package/dist/billing-foundation/consumer-protection/mail-notifications.js

@@ -44,7 +44,9 @@ export function terminationReceiptTemplate() {
                 mailRepeatedRows("details", "text"),
                 mailParagraph(texts.receiptNextSteps),
                 mailParagraph(texts.receiptRevoke(OPERATOR_EMAIL_SLOT)),
-                mailParagraphWithLink(texts.receiptNotMe, texts.receiptNotMeLink, "revokeUrl").replace("<p>", '<p data-if="revokeUrl">'),
+                mailParagraphWithLink(texts.receiptNotMe, texts.receiptNotMeLink, "revokeUrl", {
+                    showIf: "revokeUrl",
+                }),
                 mailParagraph(`${texts.contact} {operatorEmail}`),
             ].join(""),
         };

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

@@ -1,6 +1,8 @@
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 export declare const RECEIPT_MAILS_PER_RECIPIENT = 3;
 export declare const RECEIPT_WINDOW_SECONDS: number;
+export type ReceiptMailVerdict = "allowed" | "limited" | "unavailable";
 /** Consumes one receipt token for the recipient. Fails closed when the limiter
- *  errors or no digest key is wired: the declaration is already recorded, a missing receipt is the lesser harm. */
-export declare function mayMailReceipt(ctx: HandlerContext, email: string): Promise<boolean>;
+ *  errors or no digest key is wired ("unavailable"): the declaration is already
+ *  recorded, a missing receipt is the lesser harm. */
+export declare function mayMailReceipt(ctx: HandlerContext, email: string): Promise<ReceiptMailVerdict>;

package/dist/billing-foundation/consumer-protection/termination-receipt-limit.js

@@ -10,25 +10,26 @@ function receiptBucketKey(ctx, email) {
     return digest === undefined ? undefined : `${RECEIPT_BUCKET_PREFIX}:${digest}`;
 }
 /** Consumes one receipt token for the recipient. Fails closed when the limiter
- *  errors or no digest key is wired: the declaration is already recorded, a missing receipt is the lesser harm. */
+ *  errors or no digest key is wired ("unavailable"): the declaration is already
+ *  recorded, a missing receipt is the lesser harm. */
 export async function mayMailReceipt(ctx, email) {
     // skip: no rate limiter wired, nothing to count against
     if (!ctx.rateLimit)
-        return true;
+        return "allowed";
     try {
         const bucketKey = receiptBucketKey(ctx, email);
         if (bucketKey === undefined) {
             ctx.log?.warn("[billing-foundation:termination] no rate-limit digest available, receipt mail withheld");
-            return false;
+            return "unavailable";
         }
         const decision = await ctx.rateLimit.check(bucketKey, {
             limit: RECEIPT_MAILS_PER_RECIPIENT,
             windowSeconds: RECEIPT_WINDOW_SECONDS,
         });
-        return decision.allowed;
+        return decision.allowed ? "allowed" : "limited";
     }
     catch (error) {
         ctx.log?.warn(`[billing-foundation:termination] receipt rate limiter failed: ${error instanceof Error ? error.message : String(error)}`);
-        return false;
+        return "unavailable";
     }
 }

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