@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,395 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+// 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.js";
+import { getSubscriptionForTenant } from "./get-subscription-for-tenant.js";
+import type { BillingPlanCatalog, SubscriptionProviderPlugin } from "./types.js";
+
+/** 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 `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: HandlerContext,
+  catalog: BillingPlanCatalog,
+): ResolvedProvider | null {
+  if (catalog.providerName) {
+    const found = findProviderPlugin(ctx, catalog.providerName);
+    if (!found) {
+      throw new UnconfiguredError({
+        feature: "billing-foundation",
+        key: "catalog.providerName",
+        hint: `provider "${catalog.providerName}" not registered`,
+      });
+    }
+    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 — `findProviderPlugin` +
+ *  `isPluginBillingEnabled`, re-exported from index.ts so an app-owner can
+ *  check billing readiness without reaching into checkout-core internals.
+ *  An unregistered provider is a "not live" state, not a config error here
+ *  (unlike `resolveProviderPlugin`'s throw) — a readiness probe should
+ *  answer false, not throw, for a provider that simply isn't mounted yet. */
+export async function isBillingEnabled(
+  ctx: HandlerContext,
+  providerName: string,
+): Promise<boolean> {
+  const found = findProviderPlugin(ctx, providerName);
+  if (!found) return false;
+  return isPluginBillingEnabled(ctx, found.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";
+  readonly consentId?: string;
+  readonly locale?: string;
+  readonly submitMessage?: string;
+};
+
+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 }),
+    ...(input.consentId && { consentId: input.consentId }),
+    ...(input.locale && { locale: input.locale }),
+    ...(input.submitMessage && { submitMessage: input.submitMessage }),
+  });
+  return { url: result.url, providerName: input.providerName };
+}

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

@@ -0,0 +1,237 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+// @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;
+
+// Extension-point name fuer Provider-Plugins (subscription-stripe,
+// subscription-mollie, ...).
+export const SUBSCRIPTION_PROVIDER_EXTENSION = "subscriptionProvider" as const;
+
+/** delivery notification type of the § 312f contract confirmation mail. */
+export const CONTRACT_CONFIRMATION_NOTIFICATION_TYPE =
+  "billing-foundation:contract-confirmation" as const;
+
+/** delivery notification types of the § 312k termination receipt and the
+ *  operator notice. */
+export const CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE =
+  "billing-foundation:contract-termination-receipt" as const;
+export const CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE =
+  "billing-foundation:contract-termination-operator-notice" as const;
+
+// Qualified write handler names (QN format: scope:type:name).
+export const SubscriptionFoundationHandlers = {
+  /** Programmatic entry-point für den webhook-handler. Receives the
+   *  parsed SubscriptionEvent (vom Plugin schon verifiziert) + macht
+   *  insert-event + upsert-subscription + tier-sync atomic. */
+  processEvent: "billing-foundation:write:process-event",
+  /** Tenant-Admin klickt "Upgrade to Pro" → handler findet den
+   *  gewählten provider-plugin + ruft seine createCheckoutSession-
+   *  Methode + returnt die hosted-page-URL. Tenant-Admin wird dorthin
+   *  redirected, der subsequent provider-webhook erstellt die
+   *  subscription. */
+  createCheckoutSession: "billing-foundation:write:create-checkout-session",
+  /** Tenant-Admin klickt "Manage Subscription" → handler findet
+   *  current subscription, ruft plugin.createPortalSession, returnt
+   *  hosted-portal-URL. */
+  createPortalSession: "billing-foundation:write:create-portal-session",
+  /** Programmatic entry-point for the webhook-handler on a one-off-payment
+   *  (checkout mode "payment"). Its own per-tenant aggregate-stream
+   *  (payment-aggregate), separate from the subscription-aggregate — a
+   *  payment is not a subscription-state transition. */
+  processPaymentEvent: "billing-foundation:write:process-payment-event",
+  /** System-only: sends the § 312f contract confirmation mail for a recorded
+   *  checkout consent (consumerProtection only). */
+  issueContractConfirmation: "billing-foundation:write:issue-contract-confirmation",
+  /** System-only: records a termination/withdrawal on the tenant's
+   *  subscription stream and asks the provider to cancel (consumerProtection
+   *  only). */
+  recordContractTermination: "billing-foundation:write:record-contract-termination",
+  /** System-only: records a public declaration no single tenant could be
+   *  matched to, on a system-tenant stream (consumerProtection only). */
+  recordUnmatchedContractTermination:
+    "billing-foundation:write:record-unmatched-contract-termination",
+  /** Anonymous § 312k cancellation/withdrawal declaration (consumerProtection
+   *  only). */
+  requestContractTermination: "billing-foundation:write:request-contract-termination",
+  /** Tenant-Admin terminates or withdraws from the contract of their own
+   *  tenant (consumerProtection only). */
+  terminateContract: "billing-foundation:write:terminate-contract",
+  /** 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",
+  /** Backfill entry-point for the `sync-subscriptions` job (and any
+   *  SystemAdmin that wants an on-demand reconciliation). Pulls the live
+   *  provider-side state via the plugin's `retrieveSubscription` and
+   *  appends drift as a `subscription.updated` event. `agent.expose: false`
+   *  — programmatic only. */
+  syncSubscription: "billing-foundation:write:sync-subscription",
+} as const;
+
+// Qualified query handler names.
+export const SubscriptionFoundationQueries = {
+  /** Sysadmin-cross-tenant + tenant-scoped self-list auf der
+   *  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",
+  /** System-only probe: does the caller tenant hold a non-terminal
+   *  subscription (consumerProtection only). */
+  terminableSubscription: "billing-foundation:query:terminable-subscription",
+} as const;
+
+// Normalized subscription-event types — provider-agnostic.
+// Alle Provider-Plugins normalisieren ihre eigenen event-types auf einen
+// dieser. Whitelist: was die Foundation kennt; alles andere muss der
+// Plugin filtern und null returnen aus verifyAndParseWebhook.
+export const SubscriptionEventTypes = {
+  created: "subscription.created",
+  updated: "subscription.updated",
+  canceled: "subscription.canceled",
+  invoicePaid: "invoice.paid",
+  invoicePaymentFailed: "invoice.payment-failed",
+} as const;
+export type SubscriptionEventType =
+  (typeof SubscriptionEventTypes)[keyof typeof SubscriptionEventTypes];
+
+// Normalized subscription-status values — provider-agnostic.
+// Stripe + Mollie haben verschiedene Status-Sets; Plugin mapped auf
+// diesen common-subset.
+export const SubscriptionStatuses = {
+  active: "active",
+  trialing: "trialing",
+  pastDue: "past_due",
+  canceled: "canceled",
+  incomplete: "incomplete",
+} as const;
+export type SubscriptionStatus = (typeof SubscriptionStatuses)[keyof typeof SubscriptionStatuses];
+
+// Discriminator for verifyAndParseWebhook's return union. `subscription` is
+// optional on SubscriptionEvent (kept backward-compatible for plugins like
+// subscription-mollie that pre-date this field) and required on
+// PaymentEvent — TS narrows `parsed.kind === BillingEventKinds.payment`
+// correctly either way since only PaymentEvent's `kind` can equal it.
+export const BillingEventKinds = {
+  subscription: "subscription",
+  payment: "payment",
+} as const;
+export type BillingEventKind = (typeof BillingEventKinds)[keyof typeof BillingEventKinds];
+
+export const SubscriptionCancelTimings = {
+  periodEnd: "period-end",
+  immediately: "immediately",
+} as const;
+export type SubscriptionCancelTiming =
+  (typeof SubscriptionCancelTimings)[keyof typeof SubscriptionCancelTimings];
+
+// consentId is echoed back by the provider (checkout metadata), so it is
+// untrusted input: bounded length, id-ish charset only.
+const CONSENT_ID_PATTERN = /^[A-Za-z0-9_-]{1,100}$/;
+
+export function parseProviderConsentId(raw: unknown): string | undefined {
+  return typeof raw === "string" && CONSENT_ID_PATTERN.test(raw) ? raw : undefined;
+}
+
+// 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/
+// Apple-Pay/Klarna/SEPA (Disney+-Pattern). Welcher Provider die
+// aktuelle subscription des Tenants gerade hält steht in
+// subscription.providerName, kommt aus dem checkout-flow.
+//
+// price-to-tier-Map ist KEIN foundation-config — pro-Plugin, weil
+// Stripe-priceIds vs PayPal-plan-ids vs Apple-product-ids
+// unterschiedliche IDs sind. Jeder Plugin definiert seinen eigenen
+// `<plugin-name>:config:price-to-tier`-Key.