@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/billing-foundation/handlers/sync-subscription.write.ts

@@ -0,0 +1,163 @@
+// sync-subscription — backfill handler for the `sync-subscriptions` job
+// (registered in feature.ts). Pulls the live provider-side state of the
+// tenant's subscription and appends it as a `subscription.updated` (or
+// `subscription.canceled`, when the snapshot's own status is terminal)
+// event when it has drifted from `read_subscriptions` — catches
+// provider-side changes (e.g. a `cancel_at` set on the provider's own
+// dashboard, or a cancellation) that never reached us as a webhook.
+//
+// SYSTEM_ROLE, not just "SystemAdmin": the `sync-subscriptions` job's own
+// systemUser only carries `roles: ["system"]` (createSystemUser(tenantId),
+// no extra roles — see job-runner.ts), unlike the webhook path's
+// dispatchSystemWrite which adds "SystemAdmin". Same access shape as
+// tenant/handlers/memberships.query.ts and active-tenant-ids.query.ts for
+// the same reason. A human SystemAdmin can still dispatch this directly.
+
+import { createHash } from "node:crypto";
+import { SYSTEM_ROLE, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+// Aliased — an un-aliased `Temporal` would shadow the ambient global
+// `Temporal` TYPE `SubscriptionView.currentPeriodEnd`/`.cancelAt` resolve
+// against, same reasoning as constants.ts's own import.
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import * as z from "zod";
+import { findProviderPlugin } from "../checkout-core.js";
+import { isTerminalSubscriptionStatus, SubscriptionEventTypes } from "../constants.js";
+import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
+import { appendSubscriptionEvent } from "./process-event.write.js";
+
+export const syncSubscriptionSchema = z.object({}).strict();
+
+export type SyncSubscriptionSkipReason =
+  | "no_live_subscription"
+  | "provider_cannot_retrieve"
+  | "not_found"
+  | "unchanged";
+
+export type SyncSubscriptionResult =
+  | { readonly synced: true }
+  | { readonly synced: false; readonly reason: SyncSubscriptionSkipReason };
+
+// Parses both sides fresh via the polyfill before comparing — tolerant of a
+// provider snapshot's ISO string using a different (but equivalent)
+// representation than `Temporal.Instant#toString()`'s canonical form
+// (offset spelling, sub-second precision, ...), unlike a plain `===` on the
+// raw strings.
+function isoInstantsEqual(a: string, b: string): boolean {
+  return (
+    TemporalPolyfill.Instant.compare(
+      TemporalPolyfill.Instant.from(a),
+      TemporalPolyfill.Instant.from(b),
+    ) === 0
+  );
+}
+
+// Deterministic per (snapshot-content, current stream head) — not per-call.
+// Folding in `lastChangedAt` (not just the snapshot's own fields) closes a
+// gap a content-only hash has: dashboard-cancel → sync(A) → dashboard-
+// reactivate → sync(B) → dashboard-cancel-again → sync would hash back to
+// A's already-seen providerEventId and get silently treated as a duplicate,
+// leaving the row stuck on B even though the provider is on A again.
+// `lastChangedAt` advances on every applied event, so the third sync's hash
+// differs from the first's even though the snapshot content matches.
+function syncProviderEventId(
+  snapshot: {
+    readonly providerSubscriptionId: string;
+    readonly status: string;
+    readonly tier: string;
+    readonly currentPeriodEnd: string;
+    readonly cancelAt: string | null;
+  },
+  lastChangedAt: string,
+): string {
+  const hashInput = [
+    snapshot.providerSubscriptionId,
+    snapshot.status,
+    snapshot.tier,
+    snapshot.currentPeriodEnd,
+    snapshot.cancelAt ?? "",
+    lastChangedAt,
+  ].join("|");
+  return `sync:${createHash("sha256").update(hashInput).digest("hex")}`;
+}
+
+export const syncSubscriptionHandler: WriteHandlerDef = {
+  name: "sync-subscription",
+  agent: { expose: false },
+  schema: syncSubscriptionSchema,
+  access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const tenantId = event.user.tenantId;
+    const sub = await getSubscriptionForTenant(ctx, tenantId);
+    if (!sub || isTerminalSubscriptionStatus(sub.status)) {
+      return {
+        isSuccess: true as const,
+        data: { synced: false, reason: "no_live_subscription" } satisfies SyncSubscriptionResult,
+      };
+    }
+
+    // Non-throwing — a provider deregistered since the subscription was
+    // created is the same "can't reconcile right now" outcome as a plugin
+    // that never implemented retrieveSubscription, not a hard failure.
+    const found = findProviderPlugin(ctx, sub.providerName);
+    if (!found?.plugin.retrieveSubscription) {
+      return {
+        isSuccess: true as const,
+        data: {
+          synced: false,
+          reason: "provider_cannot_retrieve",
+        } satisfies SyncSubscriptionResult,
+      };
+    }
+
+    const snapshot = await found.plugin.retrieveSubscription(ctx, sub.providerSubscriptionId);
+    if (!snapshot) {
+      return {
+        isSuccess: true as const,
+        data: { synced: false, reason: "not_found" } satisfies SyncSubscriptionResult,
+      };
+    }
+
+    const cancelAtUnchanged =
+      snapshot.cancelAt === null
+        ? sub.cancelAt === null
+        : sub.cancelAt !== null && isoInstantsEqual(snapshot.cancelAt, sub.cancelAt.toString());
+    const unchanged =
+      snapshot.status === sub.status &&
+      snapshot.tier === sub.tier &&
+      isoInstantsEqual(snapshot.currentPeriodEnd, sub.currentPeriodEnd.toString()) &&
+      cancelAtUnchanged;
+    if (unchanged) {
+      return {
+        isSuccess: true as const,
+        data: { synced: false, reason: "unchanged" } satisfies SyncSubscriptionResult,
+      };
+    }
+
+    const appendResult = await appendSubscriptionEvent(ctx, tenantId, {
+      providerEventId: syncProviderEventId(snapshot, sub.lastChangedAt.toString()),
+      providerName: sub.providerName,
+      // A snapshot that already landed on a terminal status (canceled on the
+      // provider's own dashboard, never arrived as a webhook) must append as
+      // a real `canceled` event, not `updated` — anything downstream that
+      // reads the event-log's own type (not just the projection's status
+      // column, which both apply-functions patch the same way) needs the
+      // accurate event-type to react to a cancellation.
+      type: isTerminalSubscriptionStatus(snapshot.status)
+        ? SubscriptionEventTypes.canceled
+        : SubscriptionEventTypes.updated,
+      providerCustomerId: snapshot.providerCustomerId,
+      providerSubscriptionId: snapshot.providerSubscriptionId,
+      status: snapshot.status,
+      tier: snapshot.tier,
+      currentPeriodEndIso: snapshot.currentPeriodEnd,
+      cancelAtIso: snapshot.cancelAt,
+    });
+
+    return {
+      isSuccess: true as const,
+      data: (appendResult.duplicate
+        ? { synced: false, reason: "unchanged" }
+        : { synced: true }) satisfies SyncSubscriptionResult,
+    };
+  },
+};

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

@@ -0,0 +1,133 @@
+// English-only, per convention (see cap-overview/i18n.ts) — de/es coverage
+// lives exclusively in the locale-de/locale-es packages' harvested
+// strings.ts + en-catalog.ts, not inline here.
+type LocalizedString = { readonly en: string };
+
+export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:billing-plans.title": { en: "Billing" },
+  "billing-foundation.plans.billingDisabled": {
+    en: "Billing is not active yet. Your current plan stays in place.",
+  },
+  "billing-foundation.plans.currentPlan": { en: "Current plan" },
+  "billing-foundation.plans.perInterval.day": { en: "/ day" },
+  "billing-foundation.plans.perInterval.week": { en: "/ week" },
+  "billing-foundation.plans.perInterval.month": { en: "/ month" },
+  "billing-foundation.plans.perInterval.year": { en: "/ year" },
+  "billing-foundation.plans.everyInterval.day": { en: "every {count} days" },
+  "billing-foundation.plans.everyInterval.week": { en: "every {count} weeks" },
+  "billing-foundation.plans.everyInterval.month": { en: "every {count} months" },
+  "billing-foundation.plans.everyInterval.year": { en: "every {count} years" },
+  "billing-foundation.plans.choose": { en: "Choose {plan}" },
+  "billing-foundation.plans.switch": { en: "Switch to {plan}" },
+  "billing-foundation.plans.manage": { en: "Manage subscription" },
+  "billing-foundation.plans.reactivate": { en: "Reactivate subscription" },
+  "billing-foundation.plans.cancelScheduled": {
+    en: "Your subscription is scheduled to end on {date}.",
+  },
+  "billing-foundation.plans.switchRequiresReactivation": {
+    en: "Reactivate your subscription before switching plans.",
+  },
+  "billing-foundation.plans.paymentPending": {
+    en: "Payment is still being completed.",
+  },
+  "billing-foundation.plans.pastDue": {
+    en: "Your last payment failed. Update your payment method to avoid interruption.",
+  },
+  "billing-foundation.plans.priceUnavailable": { en: "Price not available" },
+  "billing-foundation.plans.purchaseNotAllowed": {
+    en: "Only administrators can change the plan.",
+  },
+  "billing-foundation.plans.subscriptionPending": {
+    en: "Your plan change is being processed.",
+  },
+  "billing-foundation.consent.title": { en: "Review your order" },
+  "billing-foundation.consent.cancelAnytime": {
+    en: "You can cancel at any time, effective at the end of the current period.",
+  },
+  "billing-foundation.consent.renews.day": { en: "Renews every day until cancelled." },
+  "billing-foundation.consent.renews.week": { en: "Renews every week until cancelled." },
+  "billing-foundation.consent.renews.month": { en: "Renews every month until cancelled." },
+  "billing-foundation.consent.renews.year": { en: "Renews every year until cancelled." },
+  "billing-foundation.consent.renewsEvery.day": {
+    en: "Renews every {count} days until cancelled.",
+  },
+  "billing-foundation.consent.renewsEvery.week": {
+    en: "Renews every {count} weeks until cancelled.",
+  },
+  "billing-foundation.consent.renewsEvery.month": {
+    en: "Renews every {count} months until cancelled.",
+  },
+  "billing-foundation.consent.renewsEvery.year": {
+    en: "Renews every {count} years until cancelled.",
+  },
+  "billing-foundation.consent.link.terms": { en: "Terms" },
+  "billing-foundation.consent.link.withdrawal": { en: "Withdrawal policy" },
+  "billing-foundation.consent.link.privacy": { en: "Privacy policy" },
+  "billing-foundation.consent.order": { en: "Order with obligation to pay" },
+  "billing-foundation.consent.back": { en: "Back" },
+  "billing-foundation.cancel.open": { en: "Cancel contract here" },
+  "billing-foundation.cancel.title": { en: "Cancel contract" },
+  "billing-foundation.cancel.declaration": { en: "Declaration" },
+  "billing-foundation.cancel.declaration.termination": { en: "Termination" },
+  "billing-foundation.cancel.declaration.withdrawal": { en: "Withdrawal" },
+  "billing-foundation.cancel.withdrawalHint": {
+    en: "A withdrawal is only possible within the statutory withdrawal period.",
+  },
+  "billing-foundation.cancel.kind": { en: "Type of termination" },
+  "billing-foundation.cancel.kind.ordinary": { en: "Ordinary" },
+  "billing-foundation.cancel.kind.extraordinary": { en: "Extraordinary (for cause)" },
+  "billing-foundation.cancel.reason": { en: "Reason" },
+  "billing-foundation.cancel.continue": { en: "Continue" },
+  "billing-foundation.cancel.back": { en: "Back" },
+  "billing-foundation.cancel.close": { en: "Close" },
+  "billing-foundation.cancel.confirmQuestion": {
+    en: "Do you want to submit this declaration now? Declaration: {declaration}, type: {kind}.",
+  },
+  "billing-foundation.cancel.submit": { en: "Cancel now" },
+  "billing-foundation.cancel.receivedAt": { en: "We received your declaration on {date}." },
+  "billing-foundation.cancel.effectiveAt": { en: "It takes effect on {date}." },
+  "billing-foundation.cancel.effectiveUnknown": {
+    en: "We will confirm the effective date by email.",
+  },
+  "billing-foundation.cancel.emailConfirmation": {
+    en: "You will receive a confirmation by email.",
+  },
+  "billing-foundation.errors.redirectOriginNotAllowed": {
+    en: "This redirect URL is not allowed for this app.",
+  },
+  "billing-foundation.errors.providerHasNoPriceCatalog": {
+    en: "This provider has no known prices configured.",
+  },
+  "billing-foundation.errors.unknownPrice": { en: "This price is not recognized." },
+  "billing-foundation.errors.foreignProviderCustomer": {
+    en: "This customer account does not belong to your tenant.",
+  },
+  "billing-foundation.errors.subscriptionExists": {
+    en: "This tenant already has an active subscription. Switch plans instead.",
+  },
+  "billing-foundation.errors.noActiveSubscription": {
+    en: "This tenant has no active subscription to switch.",
+  },
+  "billing-foundation.errors.cancellationScheduled": {
+    en: "This subscription is scheduled to end. Reactivate it before switching plans.",
+  },
+  "billing-foundation.errors.alreadyOnPlan": { en: "This tenant is already on that plan." },
+  "billing-foundation.errors.planSwitchNotSupported": {
+    en: "This provider does not support switching plans.",
+  },
+  "billing-foundation.errors.planTiersShareProduct": {
+    en: "Each plan needs its own Stripe product. Contact support.",
+  },
+  "billing-foundation.errors.providerMismatch": {
+    en: "This tenant's subscription is on a different provider than the plan catalog. Contact support to migrate.",
+  },
+  "billing-foundation.errors.priceUnavailable": {
+    en: "This plan's price is temporarily unavailable.",
+  },
+  "billing-foundation.errors.consentTextOutdated": {
+    en: "The consent text has changed. Reload the page and confirm again.",
+  },
+  "billing-foundation.errors.termsUnavailable": {
+    en: "The terms are temporarily unavailable. Please try again later.",
+  },
+};

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

@@ -0,0 +1,92 @@
+// Public API of the subscription-foundation bundled-feature.
+
+export { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id.js";
+export {
+  type BillingInfo,
+  type BillingInfoQueryDeps,
+  createBillingInfoQueryConfig,
+} from "./billing-info-query.js";
+export {
+  isBillingEnabled,
+  type ResolvedProvider,
+  resolveProviderPlugin,
+} from "./checkout-core.js";
+export {
+  BILLING_FOUNDATION_FEATURE,
+  BILLING_PLANS_PANEL_COMPONENT,
+  BILLING_PLANS_SCREEN_ID,
+  type BillingEventKind,
+  BillingEventKinds,
+  type BillingPlanAction,
+  BillingPlanActions,
+  DEFAULT_PURCHASE_ROLES,
+  isSwitchableSubscriptionStatus,
+  isTerminalSubscriptionStatus,
+  parseProviderConsentId,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+  type SubscriptionCancelTiming,
+  SubscriptionCancelTimings,
+  type SubscriptionEventType,
+  SubscriptionEventTypes,
+  SubscriptionFoundationHandlers,
+  SubscriptionFoundationQueries,
+  type SubscriptionStatus,
+  SubscriptionStatuses,
+} from "./constants.js";
+export {
+  type ContractTerminationRoutesOptions,
+  createContractTerminationRoutes,
+} from "./consumer-protection/termination-pages.js";
+export { paymentEntity, subscriptionEntity } from "./entities.js";
+export {
+  INVOICE_PAID_EVENT_QN,
+  INVOICE_PAID_EVENT_SHORT,
+  INVOICE_PAYMENT_FAILED_EVENT_QN,
+  INVOICE_PAYMENT_FAILED_EVENT_SHORT,
+  PAYMENT_AGGREGATE_TYPE,
+  PAYMENT_RECEIVED_EVENT_QN,
+  PAYMENT_RECEIVED_EVENT_SHORT,
+  type PaymentEventHeaders,
+  type PaymentEventPayload,
+  paymentEventPayloadSchema,
+  SUBSCRIPTION_AGGREGATE_TYPE,
+  SUBSCRIPTION_CANCELED_EVENT_QN,
+  SUBSCRIPTION_CANCELED_EVENT_SHORT,
+  SUBSCRIPTION_CREATED_EVENT_QN,
+  SUBSCRIPTION_CREATED_EVENT_SHORT,
+  SUBSCRIPTION_UPDATED_EVENT_QN,
+  SUBSCRIPTION_UPDATED_EVENT_SHORT,
+  type SubscriptionEventHeaders,
+  type SubscriptionEventPayload,
+  subscriptionEventPayloadSchema,
+} from "./events.js";
+export { billingFoundationFeature, createBillingFoundationFeature } from "./feature.js";
+export { getSubscriptionForTenant, type SubscriptionView } from "./get-subscription-for-tenant.js";
+export { paymentsProjectionTable, subscriptionsProjectionTable } from "./projection.js";
+export { billingPlansPanel, createBillingPlansScreen } from "./screens.js";
+export {
+  createSubscriptionTierSync,
+  effectiveTierFromSubscription,
+  SUBSCRIPTION_WEBHOOK_PATH,
+  type SubscriptionTierSyncDeps,
+} from "./subscription-tier-sync.js";
+export {
+  type BillingFoundationOptions,
+  type BillingPlanBenefit,
+  type BillingPlanCatalog,
+  type BillingPlanPrice,
+  type BillingPlansResult,
+  type BillingPlanView,
+  type ConsumerProtectionOptions,
+  KNOWN_RECURRING_INTERVALS,
+  type PaymentEvent,
+  type ProviderPrice,
+  type ProviderSubscriptionSnapshot,
+  type RecurringInterval,
+  type SubscriptionEvent,
+  type SubscriptionProviderPlugin,
+} from "./types.js";
+export {
+  createSubscriptionWebhookRoute,
+  type SubscriptionWebhookRouteOptions,
+} from "./webhook-handler.js";

package/packages/bundled-features/src/billing-foundation/plan-catalog.ts

@@ -0,0 +1,235 @@
+// Builds the BillingPlansResult a tenant-admin's billing-plans screen
+// renders — resolves live provider prices for every catalog tier, the
+// caller's current tier + subscription, and the action available per plan.
+// Internal — not re-exported from index.ts.
+
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { isPluginBillingEnabled } from "./checkout-core.js";
+import {
+  BillingPlanActions,
+  DEFAULT_PURCHASE_ROLES,
+  isSubscriptionBlockingCheckout,
+  isSwitchableSubscriptionStatus,
+  SubscriptionStatuses,
+} from "./constants.js";
+import { getSubscriptionForTenant } from "./get-subscription-for-tenant.js";
+import type {
+  BillingPlanCatalog,
+  BillingPlansResult,
+  BillingPlanView,
+  ProviderPrice,
+  SubscriptionProviderPlugin,
+} from "./types.js";
+
+function userHasAnyRole(userRoles: readonly string[], allowedRoles: readonly string[]): boolean {
+  return allowedRoles.some((role) => userRoles.includes(role));
+}
+
+/** `catalog?.purchaseRoles ?? DEFAULT_PURCHASE_ROLES` — the one place this
+ *  fallback is spelled out; plan-catalog.ts and the start-plan-checkout/
+ *  switch-plan/create-portal-session handlers all call this instead of
+ *  repeating the literal. Accepts `undefined` so create-portal-session
+ *  (mounted with or without a catalog) doesn't need its own fallback. */
+export function purchaseRolesOf(
+  catalog: Pick<BillingPlanCatalog, "purchaseRoles"> | undefined,
+): readonly string[] {
+  return catalog?.purchaseRoles ?? DEFAULT_PURCHASE_ROLES;
+}
+
+function invertPriceToTier(
+  priceToTier: Readonly<Record<string, string>>,
+): ReadonlyMap<string, readonly string[]> {
+  const byTier = new Map<string, string[]>();
+  for (const [priceId, tier] of Object.entries(priceToTier)) {
+    const existing = byTier.get(tier);
+    if (existing) {
+      existing.push(priceId);
+    } else {
+      byTier.set(tier, [priceId]);
+    }
+  }
+  return byTier;
+}
+
+type ResolvedPlanPrice = { readonly priceId: string; readonly price: ProviderPrice } | null;
+
+/** Resolves one active, flat-amount price per plan tier. 0 or >1 active
+ *  flat-amount prices for a tier is ambiguous — the caller can't tell which
+ *  one the plan means — and resolves to null with a warning instead of an
+ *  arbitrary pick. */
+export async function resolvePlanPrices(
+  ctx: HandlerContext,
+  plugin: SubscriptionProviderPlugin,
+  catalog: BillingPlanCatalog,
+): Promise<ReadonlyMap<string, ResolvedPlanPrice>> {
+  const result = new Map<string, ResolvedPlanPrice>();
+  for (const tier of catalog.plans) result.set(tier, null);
+  if (!plugin.retrievePrices || !plugin.priceToTier) return result;
+
+  const byTier = invertPriceToTier(plugin.priceToTier);
+  const allPriceIds = catalog.plans.flatMap((tier) => byTier.get(tier) ?? []);
+  if (allPriceIds.length === 0) return result;
+
+  let prices: readonly ProviderPrice[];
+  try {
+    prices = await plugin.retrievePrices(ctx, allPriceIds);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    ctx.log?.warn("billing-foundation: retrievePrices threw, all plan prices unavailable", {
+      message,
+    });
+    return result;
+  }
+  const byPriceId = new Map(prices.map((p) => [p.priceId, p] as const));
+
+  for (const tier of catalog.plans) {
+    const priceIds = byTier.get(tier) ?? [];
+    const active = priceIds
+      .map((id) => byPriceId.get(id))
+      .filter((p): p is ProviderPrice => p?.active === true && p.unitAmount !== null);
+    if (active.length === 1) {
+      const chosen = active[0];
+      if (chosen) result.set(tier, { priceId: chosen.priceId, price: chosen });
+    } else if (active.length > 1) {
+      ctx.log?.warn(
+        `billing-foundation: tier "${tier}" has ${active.length} active flat-amount prices — expected exactly one, price stays unavailable`,
+      );
+    }
+  }
+  return result;
+}
+
+type ActiveSubscription = {
+  readonly status: string;
+  readonly tier: string;
+  readonly terminal: boolean;
+  readonly cancelAt: string | null;
+};
+
+/** Whether an existing subscription can move to `tier` via the provider's
+ *  plan-switch session — pulled out of resolvePlanAction so that function
+ *  stays under the guard's complexity budget. A pending cancellation
+ *  (`cancelAt` set) must be reactivated via create-portal-session before a
+ *  switch is allowed — same gate `switch-plan.write.ts` enforces server-side. */
+function canSwitchToTier(
+  tier: string,
+  subscription: ActiveSubscription,
+  plugin: SubscriptionProviderPlugin | null,
+): boolean {
+  return (
+    isSwitchableSubscriptionStatus(subscription.status) &&
+    tier !== subscription.tier &&
+    subscription.cancelAt === null &&
+    plugin?.createPlanSwitchSession !== undefined
+  );
+}
+
+/** One plan-row's action — pulled out of `buildBillingPlans`' map callback so
+ *  that function's own complexity stays under the guard's budget. paymentPending
+ *  is checked before the general unavailable-fallback: the tier a not-yet-
+ *  confirmed checkout targets isn't `isCurrent` yet (tier sync only happens
+ *  once Stripe confirms payment), so without this branch it would otherwise
+ *  show a disabled/checkout CTA instead of the "still completing" hint. */
+function resolvePlanAction(
+  tier: string,
+  isCurrent: boolean,
+  price: unknown,
+  enabled: boolean,
+  canPurchase: boolean,
+  subscription: ActiveSubscription | null,
+  plugin: SubscriptionProviderPlugin | null,
+): (typeof BillingPlanActions)[keyof typeof BillingPlanActions] {
+  if (isCurrent) return BillingPlanActions.current;
+
+  const isPaymentPendingForTier =
+    subscription !== null &&
+    !subscription.terminal &&
+    subscription.status === SubscriptionStatuses.incomplete &&
+    tier === subscription.tier;
+  if (isPaymentPendingForTier) return BillingPlanActions.paymentPending;
+
+  if (!enabled || !canPurchase || price === null) return BillingPlanActions.unavailable;
+
+  if (!subscription || subscription.terminal) return BillingPlanActions.checkout;
+
+  return canSwitchToTier(tier, subscription, plugin)
+    ? BillingPlanActions.switch
+    : BillingPlanActions.unavailable;
+}
+
+/** `plugin === null` — no provider is registered/resolvable for this
+ *  catalog (see checkout-core's `findCatalogProvider`) — collapses onto the
+ *  same "enabled: false" result a disabled provider produces, rather than
+ *  a separate error shape the panel would need to special-case. */
+export async function buildBillingPlans(
+  ctx: HandlerContext,
+  plugin: SubscriptionProviderPlugin | null,
+  catalog: BillingPlanCatalog,
+  now: () => Temporal.Instant,
+): Promise<BillingPlansResult> {
+  const currentTierValue = await catalog.resolveCurrentTier(ctx.db, ctx.user.tenantId);
+  const enabled = plugin !== null && (await isPluginBillingEnabled(ctx, plugin));
+  const resolvedPrices =
+    enabled && plugin
+      ? await resolvePlanPrices(ctx, plugin, catalog)
+      : new Map<string, ResolvedPlanPrice>(catalog.plans.map((tier) => [tier, null]));
+
+  const subscriptionView = await getSubscriptionForTenant(ctx, ctx.user.tenantId);
+  const nowInstant = now();
+  const subscription = subscriptionView
+    ? {
+        status: subscriptionView.status,
+        tier: subscriptionView.tier,
+        terminal: !isSubscriptionBlockingCheckout(subscriptionView, nowInstant),
+        currentPeriodEnd: subscriptionView.currentPeriodEnd.toString(),
+        cancelAt: subscriptionView.cancelAt?.toString() ?? null,
+      }
+    : null;
+
+  const purchaseRoles = purchaseRolesOf(catalog);
+  const canPurchase = userHasAnyRole(ctx.user.roles, purchaseRoles);
+
+  const plans: BillingPlanView[] = catalog.plans.map((tier) => {
+    const isCurrent = tier === currentTierValue;
+    const resolved = resolvedPrices.get(tier) ?? null;
+    const price = resolved
+      ? {
+          unitAmount: resolved.price.unitAmount ?? 0,
+          currency: resolved.price.currency,
+          interval: resolved.price.interval,
+          intervalCount: resolved.price.intervalCount,
+        }
+      : null;
+
+    const action = resolvePlanAction(
+      tier,
+      isCurrent,
+      price,
+      enabled,
+      canPurchase,
+      subscription,
+      plugin,
+    );
+
+    return {
+      tier,
+      labelKey: catalog.tierLabelKey(tier),
+      price,
+      benefits: catalog.benefits(tier),
+      isCurrent,
+      action,
+    };
+  });
+
+  return {
+    enabled,
+    currentTier: {
+      tier: currentTierValue,
+      labelKey: catalog.tierLabelKey(currentTierValue),
+      benefits: catalog.benefits(currentTierValue),
+    },
+    subscription,
+    canPurchase,
+    plans,
+  };
+}