@cosmicdrift/kumiko-bundled-features 0.317.0 → 0.319.0

package/src/billing-foundation/checkout-core.ts

@@ -0,0 +1,382 @@
+// Shared checkout plumbing for create-checkout-session, start-plan-checkout
+// and switch-plan — provider/catalog resolution, redirect-origin hardening,
+// and the price/subscription-state gate that turns a bare priceId-driven
+// checkout into a plan-aware one. Internal — not re-exported from index.ts.
+
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  ConflictError,
+  FeatureDisabledError,
+  UnconfiguredError,
+  UnprocessableError,
+} from "@cosmicdrift/kumiko-framework/errors";
+import {
+  BILLING_FOUNDATION_FEATURE,
+  isSubscriptionBlockingCheckout,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+} from "./constants";
+import { getSubscriptionForTenant } from "./get-subscription-for-tenant";
+import type { BillingPlanCatalog, SubscriptionProviderPlugin } from "./types";
+
+/** Narrows a `readonly string[]` to the non-empty tuple shape `z.enum`
+ *  needs. Callers only reach this with a catalog's `plans` — the feature
+ *  factory already rejected an empty `plans` array at mount time, so the
+ *  `false` branch is unreachable there; kept as a real type guard (not a
+ *  cast) so a future caller without that guarantee fails loudly instead of
+ *  producing a `z.enum([])`. */
+export function isNonEmptyStringArray(
+  arr: readonly string[],
+): arr is readonly [string, ...string[]] {
+  return arr.length > 0;
+}
+
+export type ResolvedProvider = {
+  readonly name: string;
+  readonly plugin: 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;
+}
+
+export function resolveProviderPlugin(ctx: HandlerContext, providerName: string): ResolvedProvider {
+  const found = findProviderPlugin(ctx, providerName);
+  if (!found) {
+    const known =
+      ctx.registry
+        .getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION)
+        .map((u) => u.entityName)
+        .join(", ") || "<none>";
+    throw new Error(
+      `subscription-foundation: provider "${providerName}" not registered. Known: ${known}.`,
+    );
+  }
+  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 no provider is available (unset `providerName` not
+ *  registered, or no registered plugin exposes `priceToTier`) — a config
+ *  state `billing-plans` renders as `enabled: false` instead of erroring.
+ *  More than one candidate is a config bug, not a "no provider yet" state,
+ *  and still throws `UnconfiguredError`. */
+export function findCatalogProvider(
+  ctx: HandlerContext,
+  catalog: BillingPlanCatalog,
+): ResolvedProvider | null {
+  if (catalog.providerName) {
+    const found = findProviderPlugin(ctx, catalog.providerName);
+    if (!found) {
+      ctx.log?.warn(
+        `billing-foundation: catalog.providerName "${catalog.providerName}" is not a registered subscriptionProvider — billing-plans renders as disabled`,
+      );
+    }
+    return found;
+  }
+  const usages = ctx.registry.getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION);
+  const withPriceCatalog = usages.filter(
+    (u) => (u.options as SubscriptionProviderPlugin).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`,
+    });
+  }
+  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 };
+}
+
+/** `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: HandlerContext,
+  catalog: BillingPlanCatalog,
+  handlerName: string,
+): ResolvedProvider {
+  const found = findCatalogProvider(ctx, catalog);
+  if (!found) {
+    throw new FeatureDisabledError(BILLING_FOUNDATION_FEATURE, handlerName);
+  }
+  return found;
+}
+
+/** `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. */
+export async function isPluginBillingEnabled(
+  ctx: HandlerContext,
+  plugin: SubscriptionProviderPlugin,
+): Promise<boolean> {
+  return (await plugin.isBillingEnabled?.(ctx)) ?? true;
+}
+
+/** Throws `FeatureDisabledError` unless the plugin reports billing enabled —
+ *  shared by every handler that must refuse to act while billing isn't live
+ *  (`openCheckout`, start-plan-checkout, switch-plan). */
+export async function assertBillingEnabled(
+  ctx: HandlerContext,
+  plugin: SubscriptionProviderPlugin,
+  handlerName: string,
+): Promise<void> {
+  const enabled = await isPluginBillingEnabled(ctx, plugin);
+  if (!enabled) {
+    throw new FeatureDisabledError(BILLING_FOUNDATION_FEATURE, handlerName);
+  }
+}
+
+/** Public readiness-probe for a named provider — `resolveProviderPlugin` +
+ *  `isPluginBillingEnabled`, re-exported from index.ts so an app-owner can
+ *  check billing readiness without reaching into checkout-core internals. */
+export async function isBillingEnabled(
+  ctx: HandlerContext,
+  providerName: string,
+): Promise<boolean> {
+  const { plugin } = resolveProviderPlugin(ctx, providerName);
+  return isPluginBillingEnabled(ctx, plugin);
+}
+
+/** `create-portal-session`'s returnUrl, built server-side (the client no
+ *  longer supplies one) — `catalog.returnPath` when set, else `baseUrl`
+ *  itself. Sharing `baseUrl`'s origin is guaranteed by construction
+ *  (`joinBaseUrl` only ever concatenates onto it), so no separate
+ *  `assertRedirectOrigins` call is needed here. */
+export function portalReturnUrl(options: {
+  readonly baseUrl?: string;
+  readonly catalog?: BillingPlanCatalog;
+}): string {
+  if (options.baseUrl === undefined) {
+    throw new UnconfiguredError({
+      feature: "billing-foundation",
+      key: "baseUrl",
+      hint: "pass createBillingFoundationFeature({ baseUrl }) so create-portal-session can build a returnUrl",
+    });
+  }
+  return joinBaseUrl(options.baseUrl, options.catalog?.returnPath ?? "");
+}
+
+/** Every redirect URL a checkout/portal call carries must share the origin
+ *  of the configured `baseUrl` — otherwise a caller could redirect a tenant
+ *  admin's browser (with a fresh Stripe session cookie) to an attacker-
+ *  controlled origin after checkout. Pure — no ctx, unit-testable. */
+export function assertRedirectOrigins(urls: readonly string[], baseUrl: string | undefined): void {
+  if (baseUrl === undefined) {
+    throw new UnconfiguredError({
+      feature: "billing-foundation",
+      key: "baseUrl",
+      hint: "pass createBillingFoundationFeature({ baseUrl })",
+    });
+  }
+  let allowedOrigin: string;
+  try {
+    allowedOrigin = new URL(baseUrl).origin;
+  } catch {
+    throw new UnconfiguredError({
+      feature: "billing-foundation",
+      key: "baseUrl",
+      hint: `"${baseUrl}" is not a parseable absolute URL`,
+    });
+  }
+  for (const url of urls) {
+    let origin: string;
+    try {
+      origin = new URL(url).origin;
+    } catch {
+      throw new UnprocessableError("redirect_origin_not_allowed", {
+        i18nKey: "billing-foundation.errors.redirectOriginNotAllowed",
+        message: `"${url}" is not a parseable absolute URL`,
+      });
+    }
+    if (origin !== allowedOrigin) {
+      throw new UnprocessableError("redirect_origin_not_allowed", {
+        i18nKey: "billing-foundation.errors.redirectOriginNotAllowed",
+        message: `redirect url "${url}" has origin "${origin}", expected "${allowedOrigin}"`,
+      });
+    }
+  }
+}
+
+/** Strips a single trailing "/" — a configured `baseUrl` and a plan path
+ *  both carrying a slash would otherwise concatenate into a protocol-
+ *  relative "//path". */
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+
+/** Builds an absolute plan-checkout/portal URL by concatenating a
+ *  normalized `baseUrl` with `path` — per `BillingFoundationOptions.baseUrl`'s
+ *  own doc comment this is string-concatenation on purpose (not
+ *  `new URL(path, baseUrl)`, which would drop a path prefix); normalizing
+ *  first stops a trailing "/" on `baseUrl` from producing "//path". */
+export function joinBaseUrl(baseUrl: string, path: string): string {
+  return normalizeBaseUrl(baseUrl) + path;
+}
+
+/** Shared "no non-terminal subscription yet" gate for `openCheckout`'s
+ *  mode:"subscription" branch and start-plan-checkout — both need the exact
+ *  same ConflictError so a bare-priceId caller and a catalog caller can't
+ *  diverge in wording. Returns the existing subscription (or null) so a
+ *  caller that needs it afterwards (start-plan-checkout's providerCustomerId
+ *  reuse) doesn't have to look it up twice. */
+export async function assertNoActiveSubscription(
+  ctx: HandlerContext,
+  now: Temporal.Instant,
+): Promise<Awaited<ReturnType<typeof getSubscriptionForTenant>>> {
+  const existing = await getSubscriptionForTenant(ctx, ctx.user.tenantId);
+  if (existing && isSubscriptionBlockingCheckout(existing, now)) {
+    throw new ConflictError({
+      i18nKey: "billing-foundation.errors.subscriptionExists",
+      message:
+        "tenant already has a non-terminal subscription; use billing-foundation:write:switch-plan",
+    });
+  }
+  return existing;
+}
+
+/** Pure predicate for `openCheckout`'s providerCustomerId guard — kept
+ *  standalone so it stays unit-testable without a `ctx`. */
+export function isOwnProviderCustomer(
+  ownSubscription: Awaited<ReturnType<typeof getSubscriptionForTenant>>,
+  providerName: string,
+  providerCustomerId: string,
+): boolean {
+  return (
+    ownSubscription !== null &&
+    ownSubscription.providerName === providerName &&
+    ownSubscription.providerCustomerId === providerCustomerId
+  );
+}
+
+export type OpenCheckoutOptions = {
+  readonly baseUrl?: string;
+  readonly catalog?: BillingPlanCatalog;
+  readonly now: () => Temporal.Instant;
+};
+
+export type OpenCheckoutInput = {
+  readonly providerName: string;
+  readonly priceId: string;
+  readonly successUrl: string;
+  readonly cancelUrl: string;
+  readonly providerCustomerId?: string;
+  readonly mode?: "subscription" | "payment";
+};
+
+function assertSubscriptionPriceAllowed(
+  plugin: SubscriptionProviderPlugin,
+  catalog: BillingPlanCatalog | undefined,
+  input: OpenCheckoutInput,
+): void {
+  if (!plugin.priceToTier) {
+    throw new UnprocessableError("provider_has_no_price_catalog", {
+      i18nKey: "billing-foundation.errors.providerHasNoPriceCatalog",
+      message: `subscription-foundation: provider "${input.providerName}" has no priceToTier — cannot verify priceId "${input.priceId}" belongs to a known plan`,
+    });
+  }
+  const tier = plugin.priceToTier[input.priceId];
+  if (!tier) {
+    throw new UnprocessableError("unknown_price", {
+      i18nKey: "billing-foundation.errors.unknownPrice",
+      message: `subscription-foundation: priceId "${input.priceId}" is not in provider "${input.providerName}"'s priceToTier`,
+    });
+  }
+  if (catalog && !catalog.plans.includes(tier)) {
+    throw new UnprocessableError("unknown_price", {
+      i18nKey: "billing-foundation.errors.unknownPrice",
+      message: `subscription-foundation: priceId "${input.priceId}" maps to tier "${tier}", which is not one of the catalog's plans`,
+    });
+  }
+}
+
+// Missing/empty oneOffPriceIds rejects every payment checkout: same
+// "no gate configured yet = closed" default as the priceToTier gate.
+function assertOneOffPriceAllowed(
+  plugin: SubscriptionProviderPlugin,
+  input: OpenCheckoutInput,
+): void {
+  const oneOffPriceIds = plugin.oneOffPriceIds ?? [];
+  if (!oneOffPriceIds.includes(input.priceId)) {
+    throw new UnprocessableError("unknown_price", {
+      i18nKey: "billing-foundation.errors.unknownPrice",
+      message: `subscription-foundation: priceId "${input.priceId}" is not in provider "${input.providerName}"'s oneOffPriceIds`,
+    });
+  }
+}
+
+/** The one checkout entry-point create-checkout-session and
+ *  start-plan-checkout both funnel through. `mode: "payment"` (one-off
+ *  top-ups etc.) skips the price/subscription gates entirely — those apply
+ *  to recurring subscriptions only. */
+export async function openCheckout(
+  ctx: HandlerContext,
+  options: OpenCheckoutOptions,
+  input: OpenCheckoutInput,
+): Promise<{ readonly url: string; readonly providerName: string }> {
+  const { plugin } = resolveProviderPlugin(ctx, input.providerName);
+  if (!plugin.createCheckoutSession) {
+    throw new Error(
+      `subscription-foundation: provider "${input.providerName}" has no createCheckoutSession-method (e.g. Apple-IAP-only providers). Use the provider's native checkout flow.`,
+    );
+  }
+
+  // Checked before the redirect-origin hardening for every mode — a
+  // disabled provider must reject a mode:"payment" checkout just as much
+  // as a mode:"subscription" one.
+  await assertBillingEnabled(ctx, plugin, "create-checkout-session");
+  assertRedirectOrigins([input.successUrl, input.cancelUrl], options.baseUrl);
+
+  const mode = input.mode ?? "subscription";
+  // Reused by the providerCustomerId check below to avoid a second lookup
+  // when mode:"subscription" already ran assertNoActiveSubscription.
+  let ownSubscription: Awaited<ReturnType<typeof getSubscriptionForTenant>> | undefined;
+
+  if (mode === "subscription") {
+    assertSubscriptionPriceAllowed(plugin, options.catalog, input);
+    ownSubscription = await assertNoActiveSubscription(ctx, options.now());
+  } else {
+    assertOneOffPriceAllowed(plugin, input);
+  }
+
+  // Rejects a foreign tenant's provider-customer id — otherwise the checkout
+  // would attach to that customer's stored payment methods and invoices.
+  if (input.providerCustomerId) {
+    if (ownSubscription === undefined) {
+      ownSubscription = await getSubscriptionForTenant(ctx, ctx.user.tenantId);
+    }
+    if (!isOwnProviderCustomer(ownSubscription, input.providerName, input.providerCustomerId)) {
+      throw new UnprocessableError("foreign_provider_customer", {
+        i18nKey: "billing-foundation.errors.foreignProviderCustomer",
+        message: `subscription-foundation: providerCustomerId "${input.providerCustomerId}" does not belong to this tenant's own subscription at provider "${input.providerName}"`,
+      });
+    }
+  }
+
+  const result = await plugin.createCheckoutSession(ctx, {
+    priceId: input.priceId,
+    tenantId: ctx.user.tenantId,
+    successUrl: input.successUrl,
+    cancelUrl: input.cancelUrl,
+    ...(input.providerCustomerId && { providerCustomerId: input.providerCustomerId }),
+    // Only forwarded when the caller set it explicitly — preserves the
+    // pre-hardening wire-contract for callers that never sent `mode`
+    // (create-checkout-session's own regression pin).
+    ...(input.mode && { mode: input.mode }),
+  });
+  return { url: result.url, providerName: input.providerName };
+}

package/src/billing-foundation/constants.ts

@@ -1,3 +1,12 @@
+// @runtime client
+// temporal-polyfill is a plain npm dependency (not a framework runtime
+// module), so importing it here doesn't break browser bundles. Aliased —
+// same reason as event-store.ts's own import: the un-aliased name would
+// shadow the ambient global `Temporal` TYPE every `Temporal.Instant`
+// annotation in this file (and its callers, e.g. StoredEvent.createdAt)
+// resolves against, see #1438.
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+
 // Feature name
 export const BILLING_FOUNDATION_FEATURE = "billing-foundation" as const;
 
@@ -26,6 +35,15 @@ export const SubscriptionFoundationHandlers = {
    *  (payment-aggregate), separate from the subscription-aggregate — a
    *  payment is not a subscription-state transition. */
   processPaymentEvent: "billing-foundation:write:process-payment-event",
+  /** Tenant-Admin/purchase-role picks a plan tier from the catalog with no
+   *  existing non-terminal subscription — starts a hosted checkout for the
+   *  matching price. Only registered when `createBillingFoundationFeature`
+   *  gets a `catalog`. */
+  startPlanCheckout: "billing-foundation:write:start-plan-checkout",
+  /** Tenant-Admin/purchase-role switches an existing non-terminal
+   *  subscription to another plan tier via the provider's confirmation
+   *  page. Only registered when a `catalog` is configured. */
+  switchPlan: "billing-foundation:write:switch-plan",
 } as const;
 
 // Qualified query handler names.
@@ -34,6 +52,10 @@ export const SubscriptionFoundationQueries = {
    *  read_subscriptions-projection. Tenant-Admin sieht via ctx.db
    *  tenant-scoping nur die eigene row. */
   listSubscriptions: "billing-foundation:query:subscription:list",
+  /** Lists the catalog's plans with live price, benefits, the caller's
+   *  current tier and per-plan action. Only registered when a `catalog` is
+   *  configured. */
+  billingPlans: "billing-foundation:query:billing-plans",
 } as const;
 
 // Normalized subscription-event types — provider-agnostic.
@@ -73,6 +95,82 @@ export const BillingEventKinds = {
 } as const;
 export type BillingEventKind = (typeof BillingEventKinds)[keyof typeof BillingEventKinds];
 
+// Billing-plans screen/panel identifiers — the dormant dashboard app-builders
+// mount their own catalog-derived nav entry onto.
+export const BILLING_PLANS_SCREEN_ID = "billing-plans" as const;
+export const BILLING_PLANS_PANEL_COMPONENT = "BillingPlansPanel" as const;
+
+// Per-plan action a tenant-admin can take on the billing-plans query result.
+export const BillingPlanActions = {
+  checkout: "checkout",
+  switch: "switch",
+  current: "current",
+  unavailable: "unavailable",
+  /** A young `incomplete` subscription for this tier — checkout was started
+   *  but Stripe hasn't confirmed payment yet. No CTA; the panel shows a
+   *  "still completing" hint instead. */
+  paymentPending: "paymentPending",
+} as const;
+export type BillingPlanAction = (typeof BillingPlanActions)[keyof typeof BillingPlanActions];
+
+// A canceled subscription is terminal — the tenant has no more billing
+// relationship with the provider and a plan pick starts a fresh checkout
+// instead of a plan-switch. Every other status (including past_due) still
+// has a live provider subscription-object to switch.
+export const TERMINAL_SUBSCRIPTION_STATUSES: ReadonlySet<string> = new Set([
+  SubscriptionStatuses.canceled,
+]);
+export function isTerminalSubscriptionStatus(status: string): boolean {
+  return TERMINAL_SUBSCRIPTION_STATUSES.has(status);
+}
+
+// Stripe auto-expires an "incomplete" subscription (payment never completed)
+// after roughly 23 hours; without a matching staleness cutoff on our side, a
+// stale incomplete row would block that tenant from ever starting a new
+// checkout, since the projection has no expiry-triggered event of its own.
+export const STALE_INCOMPLETE_AFTER = TemporalPolyfill.Duration.from({ hours: 24 });
+
+/** Time-aware terminal check for the checkout gate: a canceled subscription
+ *  is terminal (see `isTerminalSubscriptionStatus`), and so is an
+ *  `incomplete` one once it's older than `STALE_INCOMPLETE_AFTER` — every
+ *  other status (including a fresh `incomplete`) still blocks a new
+ *  checkout. */
+export function isSubscriptionBlockingCheckout(
+  sub: { readonly status: string; readonly lastChangedAt: Temporal.Instant },
+  now: Temporal.Instant,
+): boolean {
+  if (isTerminalSubscriptionStatus(sub.status)) return false;
+  if (sub.status !== SubscriptionStatuses.incomplete) return true;
+  const staleAt = sub.lastChangedAt.add(STALE_INCOMPLETE_AFTER);
+  // @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal.Instant
+  // at runtime — row types resolve against ambient Temporal; polyfill Instant
+  // is a separate nominal type across the two .d.ts sources.
+  return (
+    TemporalPolyfill.Instant.compare(
+      now as unknown as InstanceType<typeof TemporalPolyfill.Instant>,
+      staleAt as unknown as InstanceType<typeof TemporalPolyfill.Instant>,
+    ) < 0
+  );
+}
+
+// A subscription in one of these statuses can be switched to a different
+// plan tier via the provider's confirmation page (Stripe portal
+// subscription_update_confirm and equivalents) — incomplete subscriptions
+// never activated and are excluded.
+export const SWITCHABLE_SUBSCRIPTION_STATUSES: ReadonlySet<string> = new Set([
+  SubscriptionStatuses.active,
+  SubscriptionStatuses.trialing,
+  SubscriptionStatuses.pastDue,
+]);
+export function isSwitchableSubscriptionStatus(status: string): boolean {
+  return SWITCHABLE_SUBSCRIPTION_STATUSES.has(status);
+}
+
+// Default purchase-roles for a billing-plans catalog when the app doesn't
+// override `purchaseRoles` — matches create-checkout-session's existing
+// TenantAdmin/SystemAdmin-only access.
+export const DEFAULT_PURCHASE_ROLES = ["TenantAdmin", "SystemAdmin"] as const;
+
 // **Multi-Provider von Tag 1:** subscription-foundation hat KEIN
 // `provider`-config-key. Alle gemounteten Plugins sind aktiv parallel —
 // der Endkunde wählt beim Subscribe-Klick zwischen Karte/PayPal/

package/src/billing-foundation/entities.ts

@@ -27,11 +27,12 @@ import {
 //   - tier: "free" / "pro" / ... — vom tier-engine konsumiert. Aus
 //     price-to-tier-Map resolved im Plugin.
 //   - currentPeriodEnd: wann läuft die aktuelle Billing-Period aus.
+//   - cancelAt: when a scheduled cancellation ends the subscription;
+//     nullable because a renewing subscription has none.
 //
 // **Was hier NICHT ist:**
 //   - invoice-history, payment-method, line-items, tax-info → all das
 //     fetcht der Tenant via customer-portal-session direkt vom Provider.
-//   - cancelAt, cancelAtPeriodEnd → Provider-Sache.
 //
 // **Audit/event-history:** lebt im event-store unter dem `subscription`-
 // stream — KEIN eigene `subscription-event`-Tabelle mehr (= ES ist die
@@ -79,6 +80,7 @@ export const subscriptionEntity = createEntity({
       reason: "catalog_label",
     }),
     currentPeriodEnd: createTimestampField({ required: true }),
+    cancelAt: createTimestampField({ required: false }),
   },
 });
 

package/src/billing-foundation/events.ts

@@ -60,6 +60,11 @@ export const subscriptionEventPayloadSchema = z.object({
   status: statusEnum,
   tier: z.string().min(1).max(50),
   currentPeriodEndIso: z.string().min(1),
+  // Optional (not required): existing events (Mollie-style providers, or
+  // events appended before this field existed) stay valid without an
+  // upcaster. null = the subscription renews; undefined = the provider
+  // doesn't report cancelAt at all — projection.ts tells the two apart.
+  cancelAtIso: z.string().min(1).nullable().optional(),
 });
 export type SubscriptionEventPayload = z.infer<typeof subscriptionEventPayloadSchema>;