@cosmicdrift/kumiko-samples 0.387.0 → 0.388.0

package/packages/bundled-features/src/billing-foundation/checkout-core.ts

@@ -36,17 +36,22 @@ export type ResolvedProvider = {
   readonly plugin: SubscriptionProviderPlugin;
 };
 
+/** Every registered provider plugin, in registration order. */
+function listProviderPlugins(ctx: HandlerContext): readonly ResolvedProvider[] {
+  return ctx.registry.getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION).map((usage) => ({
+    name: usage.entityName,
+    // @cast-boundary engine-payload — extension-usage carries unknown options
+    plugin: usage.options as SubscriptionProviderPlugin,
+  }));
+}
+
 /** Non-throwing provider lookup by name — null when no plugin with that
  *  entityName is registered. */
 export function findProviderPlugin(
   ctx: HandlerContext,
   providerName: string,
 ): ResolvedProvider | null {
-  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 as SubscriptionProviderPlugin } : null;
+  return listProviderPlugins(ctx).find((provider) => provider.name === providerName) ?? null;
 }
 
 export function resolveProviderPlugin(ctx: HandlerContext, providerName: string): ResolvedProvider {
@@ -64,17 +69,15 @@ export function resolveProviderPlugin(ctx: HandlerContext, providerName: string)
   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(
+/** 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: HandlerContext,
   catalog: BillingPlanCatalog,
-): ResolvedProvider | null {
+): readonly ResolvedProvider[] {
   if (catalog.providerName) {
     const found = findProviderPlugin(ctx, catalog.providerName);
     if (!found) {
@@ -84,40 +87,27 @@ export function findCatalogProvider(
         hint: `provider "${catalog.providerName}" not registered`,
       });
     }
-    return found;
+    return [found];
   }
-  const usages = ctx.registry.getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION);
-  const withPriceCatalog = usages.filter(
-    (u) => (u.options as SubscriptionProviderPlugin).priceToTier !== undefined,
+  return listProviderPlugins(ctx).filter(({ plugin }) => plugin.priceToTier !== undefined);
+}
+
+export async function filterOfferedProviders(
+  ctx: HandlerContext,
+  providers: readonly ResolvedProvider[],
+): Promise<readonly ResolvedProvider[]> {
+  const enabledFlags = await Promise.all(
+    providers.map(({ plugin }) => isPluginBillingEnabled(ctx, plugin)),
   );
-  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`,
-    });
-  }
-  const usage = withPriceCatalog[0];
-  if (!usage) return null;
-  // @cast-boundary engine-payload — extension-usage carries unknown options
-  return { name: usage.entityName, plugin: usage.options as SubscriptionProviderPlugin };
+  return providers.filter((_, index) => enabledFlags[index]);
 }
 
-/** `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(
+/** The catalog providers that are live right now: what a buyer can choose from. */
+export async function listOfferedCatalogProviders(
   ctx: HandlerContext,
   catalog: BillingPlanCatalog,
-  handlerName: string,
-): ResolvedProvider {
-  const found = findCatalogProvider(ctx, catalog);
-  if (!found) {
-    throw new FeatureDisabledError(BILLING_FOUNDATION_FEATURE, handlerName);
-  }
-  return found;
+): Promise<readonly ResolvedProvider[]> {
+  return filterOfferedProviders(ctx, listCatalogProviders(ctx, catalog));
 }
 
 /** `plugin.isBillingEnabled?.(ctx) ?? true` — the one place this fallback is

package/packages/bundled-features/src/billing-foundation/consumer-protection/confirmation-mail.ts

@@ -166,8 +166,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/packages/bundled-features/src/billing-foundation/consumer-protection/consent-gate.ts

@@ -79,6 +79,7 @@ export type ConsentPriceDetails = {
     "unitAmount" | "currency" | "interval" | "intervalCount"
   > | null;
   readonly orderItem?: OrderItem;
+  readonly providerName?: string;
 };
 
 export async function prepareConsent(
@@ -163,6 +164,7 @@ export async function recordConsent(
     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/packages/bundled-features/src/billing-foundation/consumer-protection/issue-confirmation.ts

@@ -12,6 +12,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.ts";
 import { requireTemplateResolver, TEXT_BLOCK_KIND } from "../../template-resolver/index.ts";
 import { UserQueries } from "../../user/index.ts";
 import { paymentAggregateId, subscriptionAggregateId } from "../aggregate-id.ts";
@@ -29,7 +30,6 @@ import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from
 import { CONTRACT_CONFIRMATION_NOTIFICATION_TYPE } from "../web/constants.ts";
 import { contractConfirmationVariables } from "./confirmation-mail.ts";
 import { resolveConsentLocale } from "./consent-text.ts";
-import { openStoredUserEmail } from "./stored-user-email.ts";
 
 export const issueContractConfirmationSchema = z
   .object({
@@ -58,6 +58,17 @@ function translatedOrUndefined(translation: string, key: string): string | undef
   return translation === key ? undefined : translation;
 }
 
+function vatNoteFor(
+  consumerProtection: ConsumerProtectionOptions,
+  providerName: string | undefined,
+): Readonly<Record<string, string>> {
+  const providerNote =
+    providerName === undefined
+      ? undefined
+      : consumerProtection.providerTexts?.[providerName]?.vatNote;
+  return providerNote ?? consumerProtection.vatNote;
+}
+
 function pickTimeZone(userZone: string | null | undefined, tenantZone: string): string {
   if (userZone && isValidIanaTimeZone(userZone)) return userZone;
   return isValidIanaTimeZone(tenantZone) ? tenantZone : "UTC";
@@ -145,7 +156,7 @@ export function createIssueContractConfirmationHandler(
       );
       const recipientEmail =
         recipient.success && recipient.data.isDeleted !== true
-          ? await openStoredUserEmail(
+          ? await decryptStoredUserEmail(
               recipient.data.email,
               "billing-foundation:issue-contract-confirmation",
             )
@@ -203,7 +214,7 @@ export function createIssueContractConfirmationHandler(
         ...(payload.currentPeriodEndIso !== undefined && {
           currentPeriodEndIso: payload.currentPeriodEndIso,
         }),
-        vatNote: consumerProtection.vatNote,
+        vatNote: vatNoteFor(consumerProtection, consent.providerName),
         operatorEmail: consumerProtection.operatorEmail,
         termsContent: terms.content,
       });

package/packages/bundled-features/src/billing-foundation/consumer-protection/mail-notifications.ts

@@ -69,10 +69,9 @@ export function terminationReceiptTemplate(): NotificationLocalizedTemplate {
         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/packages/bundled-features/src/billing-foundation/consumer-protection/termination-receipt-limit.ts

@@ -14,28 +14,34 @@ function receiptBucketKey(ctx: HandlerContext, email: string): string | undefine
   return digest === undefined ? undefined : `${RECEIPT_BUCKET_PREFIX}:${digest}`;
 }
 
+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 async 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 async function mayMailReceipt(
+  ctx: HandlerContext,
+  email: string,
+): Promise<ReceiptMailVerdict> {
   // skip: no rate limiter wired, nothing to count against
-  if (!ctx.rateLimit) return true;
+  if (!ctx.rateLimit) 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/packages/bundled-features/src/billing-foundation/consumer-protection/termination-record.ts

@@ -249,25 +249,8 @@ export function createRecordContractTerminationHandler(
 
       // 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 as const,
-          data: {
-            receivedAtIso: alreadyRecorded.receivedAtIso,
-            effectiveAtIso: alreadyRecorded.effectiveAtIso,
-            providerCancel: alreadyRecorded.providerCancel,
-            noticeReason: null,
-            withdrawalPeriodExpired: false,
-          } satisfies RecordContractTerminationResult,
-        };
-      }
+      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)) {
@@ -301,6 +284,13 @@ export function createRecordContractTerminationHandler(
         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, {
@@ -348,6 +338,32 @@ export function createRecordContractTerminationHandler(
   };
 }
 
+export function findRecordedTermination(
+  events: readonly { type: string; payload: unknown }[],
+  requestId: string,
+): ContractTerminationRequestedPayload | undefined {
+  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: ContractTerminationRequestedPayload) {
+  return {
+    isSuccess: true as const,
+    data: {
+      receivedAtIso: recorded.receivedAtIso,
+      effectiveAtIso: recorded.effectiveAtIso,
+      providerCancel: recorded.providerCancel,
+      noticeReason: null,
+      withdrawalPeriodExpired: false,
+    } satisfies RecordContractTerminationResult,
+  };
+}
+
 export function hasRevocation(
   events: readonly { type: string; payload: unknown }[],
   requestId: string,

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

@@ -13,6 +13,7 @@ import {
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
+import { decryptStoredUserEmail } from "../../shared/index.ts";
 import { TenantQueries } from "../../tenant/index.ts";
 import { UserQueries } from "../../user/index.ts";
 import {
@@ -31,10 +32,9 @@ import {
   SubscriptionFoundationQueries,
 } from "../web/constants.ts";
 import { resolveConsentLocale } from "./consent-text.ts";
-import { openStoredUserEmail } from "./stored-user-email.ts";
 import { type TerminationDeclaration, terminationReceiptVariables } from "./termination-mail.ts";
 import { notifyOperator, type OperatorNoticePlan, requireNotify } from "./termination-notify.ts";
-import { mayMailReceipt } from "./termination-receipt-limit.ts";
+import { mayMailReceipt, type ReceiptMailVerdict } from "./termination-receipt-limit.ts";
 import type { RecordContractTerminationResult } from "./termination-record.ts";
 import { createRevocationToken, revocationUrl } from "./termination-revoke.ts";
 import type { OperatorNoticeReason } from "./termination-texts.ts";
@@ -109,13 +109,19 @@ type TerminationMailPlan = OperatorNoticePlan & {
   readonly revokeUrl?: string;
 };
 
+function receiptWithheldReasons(verdict: ReceiptMailVerdict): readonly OperatorNoticeReason[] {
+  if (verdict === "limited") return ["receipt_rate_limited"];
+  if (verdict === "unavailable") return ["receipt_not_sent"];
+  return [];
+}
+
 async function sendTerminationMails(
   ctx: HandlerContext,
   consumerProtection: ConsumerProtectionOptions,
   plan: TerminationMailPlan,
 ): Promise<void> {
-  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({
@@ -133,9 +139,7 @@ async function sendTerminationMails(
       priority: "critical",
     });
   }
-  const reasons = receiptAllowed
-    ? plan.reasons
-    : [...plan.reasons, "receipt_rate_limited" as const];
+  const reasons = [...plan.reasons, ...receiptWithheldReasons(receiptVerdict)];
   // skip: no operator notice needed for this declaration
   if (reasons.length === 0) return;
   const { revokeUrl: _revokeUrl, ...noticePlan } = plan;
@@ -320,7 +324,7 @@ export function createTerminateContractHandler(
       );
       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/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));