@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/billing-foundation/billing-info-query.ts

@@ -0,0 +1,95 @@
+// Generic billing-info query-handler-config factory. Extracted from the
+// near-identical billing-info.query.ts app copies in show-pony and
+// publicstatus — the only per-app variables were the
+// TTier union/resolver, the allowed roles, and how Stripe prices are read
+// off the app's extraContext.
+//
+// Deliberately does NOT call defineQueryHandler itself: apps use different
+// wrappers around it (publicstatus's `@app/define`, which adds
+// `agent: { expose: false }`; show-pony's plain framework
+// `defineQueryHandler`). Calling defineQueryHandler here would bypass
+// whatever an app's own wrapper does. Instead this factory returns just the
+// handler-config object — name/schema/access/handler — and each app spreads
+// it into its own defineQueryHandler call, adding app-specific fields
+// (like `agent`) on top.
+
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { QnTypes, qn, SYSTEM_TENANT_ID, toKebab } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+// kumiko-lint-ignore cross-feature-import SUBSCRIPTION_STRIPE_FEATURE is a plain string const in constants.ts (no imports); the barrel import (../subscription-stripe) would create a module cycle with billing-foundation via feature.ts → verify-webhook.ts, because billing-foundation/index.ts now re-exports billing-info-query.ts.
+import { SUBSCRIPTION_STRIPE_FEATURE } from "../subscription-stripe/constants.js";
+import { subscriptionAggregateId } from "./aggregate-id.js";
+import { subscriptionsProjectionTable } from "./projection.js";
+
+// subscription-stripe addresses its credentials + the live flag as config
+// keys (api-key via backing:"secrets" in the secrets store, billingLive
+// plain). We only READ them here to surface billing readiness on the
+// customer screen — the write-side UI is the feature's auto-derived
+// sysadmin settings screen.
+const stripeFeature = toKebab(SUBSCRIPTION_STRIPE_FEATURE);
+const STRIPE_API_KEY_CONFIG_QN = qn(stripeFeature, QnTypes.config, "api-key");
+const STRIPE_BILLING_LIVE_CONFIG_QN = qn(stripeFeature, QnTypes.config, toKebab("billingLive"));
+
+export type BillingInfo<TTier extends string> = {
+  readonly enabled: boolean;
+  readonly tier: TTier;
+  readonly subscription: {
+    readonly status: string;
+    readonly tier: string;
+    readonly providerName: string;
+  } | null;
+  readonly prices: Readonly<Partial<Record<string, string>>>;
+};
+
+export type BillingInfoQueryDeps<TTier extends string> = {
+  readonly roles: readonly string[];
+  readonly resolveTier: (db: TenantDb, tenantId: TenantId) => Promise<TTier>;
+  // ctx is the same HandlerContext the returned handler receives — app
+  // implementations read app-specific extraContext fields off it (e.g.
+  // publicstatus/show-pony's getBillingPrices(ctx) reads `billingPrices`),
+  // so they type their own ctx param as `unknown` and cast internally.
+  readonly getBillingPrices: (
+    ctx: HandlerContext,
+  ) => Readonly<Partial<Record<string, string>>> | null;
+};
+
+export function createBillingInfoQueryConfig<TTier extends string>(
+  deps: BillingInfoQueryDeps<TTier>,
+) {
+  return {
+    name: "billing-info",
+    schema: z.object({}),
+    access: { roles: deps.roles },
+    async handler(_event: unknown, ctx: HandlerContext): Promise<BillingInfo<TTier>> {
+      const tier = await deps.resolveTier(ctx.db, ctx.user.tenantId);
+      const prices = deps.getBillingPrices(ctx);
+      if (!prices) return { enabled: false, tier, subscription: null, prices: {} };
+
+      const billingLive = ctx.config
+        ? (await ctx.config(STRIPE_BILLING_LIVE_CONFIG_QN)) === true
+        : false;
+      const apiKeySet = ctx.secrets
+        ? await ctx.secrets.has(SYSTEM_TENANT_ID, STRIPE_API_KEY_CONFIG_QN)
+        : false;
+
+      const sub = await ctx.db.fetchOne<{
+        status?: unknown;
+        tier?: unknown;
+        providerName?: unknown;
+      }>(subscriptionsProjectionTable, { id: subscriptionAggregateId(ctx.user.tenantId) });
+      return {
+        enabled: billingLive && apiKeySet,
+        tier,
+        subscription:
+          sub &&
+          typeof sub.status === "string" &&
+          typeof sub.tier === "string" &&
+          typeof sub.providerName === "string"
+            ? { status: sub.status, tier: sub.tier, providerName: sub.providerName }
+            : null,
+        prices,
+      };
+    },
+  };
+}

package/packages/bundled-features/src/billing-foundation/changes.json

@@ -0,0 +1,162 @@
+[
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "Contract confirmation mail after a recorded checkout consent",
+    "detail": "With `consumerProtection`, four event-triggered jobs (`confirm-on-subscription-created`, `confirm-on-subscription-updated`, `confirm-on-invoice-paid`, `confirm-on-payment-received`) call the system-only `billing-foundation:write:issue-contract-confirmation` (`consentId`, `sourceAggregateId`, optional `currentPeriodEndIso`) for events carrying a `consentId`; subscription events only count with status `active` or `trialing`. The handler only reads the caller tenant's own subscription or payment stream, finds the `checkout-consent-recorded` event, appends `contract-confirmation-issued` (`consentId`, `issuedAtIso`, `locale`, `termsTemplateVersion`) at the fetched stream version and then notifies `billing-foundation:contract-confirmation` (critical priority) to the consenting user's email. A second run returns `{ issued: false, reason: \"already_issued\" }` or fails with a version conflict; an unknown consent returns `consent_not_found` and sends nothing. The mail is rendered in German or English (fallback German) as structured header/sections content for the email channel's renderer.",
+    "migration": "Enabling `consumerProtection` additionally requires the `user` feature, and an email channel plus renderer must be mounted for the mail to go out."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "Optional consumer-protection consent gate on checkout",
+    "detail": "`BillingFoundationOptions.consumerProtection` (`termsTextBlock`, `vatNote` with `de` and `en`, `operatorEmail`, `legalLinks`) requires `baseUrl` and additionally requires the `template-resolver` and `delivery` features. When set, `start-plan-checkout` and `create-checkout-session` take a strict `consent` object (`earlyPerformanceRequested: true`, `withdrawalLossAcknowledged: true`, `consentTextVersion`, `locale`); a missing or unchecked consent fails validation (400). The consent texts and their version (first 16 hex characters of the SHA-256 of the early-performance and withdrawal-loss texts) are owned by the framework in German and English. After the provider returned the checkout URL, `checkout-consent-recorded` is appended (no email, no IP). `billing-plans` returns `consumerProtection: { consentTexts, legalLinks }` so a client can render and echo the version.",
+    "migration": "No code change needed unless you enable consumerProtection; then callers of start-plan-checkout/create-checkout-session must send `consent`."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "Consent dialog and cancel-contract button in the billing panel",
+    "detail": "The checkout CTA opens `CheckoutConsentDialog` when `billing-plans` returns `consumerProtection`; `start-plan-checkout` then receives `consent: { earlyPerformanceRequested, withdrawalLossAcknowledged, consentTextVersion, locale }`. The locale rule (`resolveConsentLocale`) moved to the crypto-free `consumer-protection/consent-locale.ts` and is still re-exported from `consent-text.ts`. `CancelContractDialog` calls `billing-foundation:write:terminate-contract`. New English i18n keys under `billing-foundation.consent.*` and `billing-foundation.cancel.*`.",
+    "migration": "No action. Apps that translate the panel add the new `billing-foundation.consent.*` and `billing-foundation.cancel.*` keys to their locale bundles."
+  },
+  {
+    "version": "0.338.0",
+    "type": "breaking",
+    "title": "SubscriptionProviderPlugin.cancelSubscription takes { providerSubscriptionId, when }",
+    "detail": "`cancelSubscription(ctx, { providerSubscriptionId, when })` replaces the positional `providerSubscriptionId` argument. `when` is `SubscriptionCancelTimings.periodEnd` (`\"period-end\"`, the subscription runs to the end of the paid period) or `SubscriptionCancelTimings.immediately` (`\"immediately\"`). `createCheckoutSession` options gain optional `consentId`, `locale` and `submitMessage`; `SubscriptionEvent` and `PaymentEvent` gain an optional `consentId`, validated by `parseProviderConsentId` (max 100 characters of `A-Z a-z 0-9 _ -`), and `subscription` / `payment` event payloads store it.",
+    "migration": "Custom provider plugins that implement `cancelSubscription` change the signature to `(ctx, { providerSubscriptionId, when })` and honor `when`. A provider that can only cancel immediately may treat both values the same or leave the method out. Callers pass `{ providerSubscriptionId, when: SubscriptionCancelTimings.immediately }` to keep the old behavior."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "§ 312k cancellation pages and handlers with consumerProtection",
+    "detail": "`contract-termination-requested` (on the tenant's subscription stream: `requestId`, `declarationType` termination|withdrawal, `terminationKind` ordinary|extraordinary, `channel` public|account, `receivedAtIso`, `effectiveAtIso`, `providerCancel` period-end|immediately|none) and `contract-termination-unmatched` (system-tenant stream, `matchResult` none|ambiguous) are appended by the system-only `record-contract-termination` and `record-unmatched-contract-termination` handlers. `billing-foundation:write:request-contract-termination` is anonymous and answers `{ requestId, receivedAtIso }` for every outcome; `billing-foundation:write:terminate-contract` (purchase roles) answers `{ requestId, receivedAtIso, effectiveAtIso, providerCancel }`. Provider errors or a provider without `cancelSubscription` still record the declaration (`providerCancel: none`) and notify the operator. `consumerProtection` now also requires the `tenant` and `user` features.",
+    "migration": "Add `createContractTerminationRoutes()` from billing-foundation to the app's `extraRoutes`, make sure `anonymousAccess` is configured, and link `/legal/kuendigen` (or `/legal/cancel`) in the page footer."
+  },
+  {
+    "version": "0.338.0",
+    "type": "breaking",
+    "title": "Remove rawPayload from provider events and event headers",
+    "detail": "`rawPayload` is removed from `SubscriptionEvent`, `PaymentEvent`, `ProviderSubscriptionSnapshot`, the `process-event` and `process-payment-event` schemas and `SubscriptionEventHeaders` / `PaymentEventHeaders`. New events carry `providerEventId` and `providerName` in their headers; payment events also carry the optional `providerCheckoutId` (Stripe checkout session id).",
+    "migration": "Custom subscription provider plugins must stop returning `rawPayload`; TypeScript flags the removed field. Code that read the checkout session id out of `headers.rawPayload` reads `headers.providerCheckoutId` instead. Events already stored keep their old `rawPayload` header; this release does not rewrite stored events."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "late events of a superseded provider subscription no longer overwrite the live row",
+    "detail": "billing-foundation: `process-event` drops a non-`created` provider event that belongs to a different subscription than the one the tenant's row currently tracks, while that row still blocks checkout. A late webhook retry of a superseded subscription can no longer flip the live subscription to `canceled`. The webhook answers 200 with `stale: true`.",
+    "migration": "No action needed: events of the tracked subscription and `created` events behave as before."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "Unregistered catalog.providerName fails unconfigured; switch-plan checks provider mismatch before lookup",
+    "detail": "`billing-plans` now fails with an `unconfigured` error when `catalog.providerName` names a provider that is not registered, instead of rendering billing as disabled. Billing renders as disabled only when no `providerName` is set and no provider is mounted. `switch-plan` answers a subscription on an unmounted provider with the `providerMismatch` conflict instead of a 500.",
+    "migration": "If `catalog.providerName` names a provider that is not mounted, billing-plans now fails with `unconfigured` instead of rendering billing as disabled; mount the provider or remove `providerName`."
+  },
+  {
+    "version": "0.330.0",
+    "type": "fix",
+    "title": "The switch-plan error for a subscription with a scheduled cancellation says \"scheduled to end\", matching the plan badge",
+    "detail": "The error for switching plans on a subscription with a scheduled cancellation now says \"scheduled to end\", like the plan badge, and the invalid-credentials message reads the same in every source that registers it."
+  },
+  {
+    "version": "0.321.0",
+    "type": "breaking",
+    "title": "switch-plan rejects a subscription with a scheduled cancellation",
+    "detail": "`billing-foundation:write:switch-plan` now throws a `409 ConflictError`\n(`billing-foundation.errors.cancellationScheduled`) when the tenant's\nsubscription already has `cancelAt` set — switching plans mid-cancellation\npreviously silently proceeded and could leave the new plan itself\nscheduled to cancel. `billing-foundation:query:billing-plans` now resolves every\nnon-current plan's `action` to `unavailable` (instead of `switch`) while a\ncancellation is scheduled, and the billing-plans panel shows a\n`switchRequiresReactivation` message alongside the existing\n`cancelScheduled` banner.",
+    "migration": "A tenant that switches plans while their subscription is scheduled to\ncancel now gets a 409 instead of a successful switch. Callers driving\n`switch-plan` directly (not through the bundled panel) must reactivate the\nsubscription first (`create-portal-session` / the provider's own\nreactivation flow) before retrying the switch."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "past_due banner on the billing-plans panel; sync-subscription backfill for provider-side drift",
+    "detail": "`billing-plans-panel` renders a `past_due`-status warning banner\n(`billing-foundation.plans.pastDue`) alongside the existing\npayment-pending/cancel-scheduled ones. `SubscriptionProviderPlugin` gained\nan optional `retrieveSubscription(ctx, providerSubscriptionId)` method\nreturning a `ProviderSubscriptionSnapshot`; the new\n`billing-foundation:write:sync-subscription` handler (`agent.expose:\nfalse`, `SYSTEM_ROLE`/`SystemAdmin`-only — the `sync-subscriptions` job's\nown systemUser only carries `SYSTEM_ROLE`) compares the live snapshot\nagainst `read_subscriptions` and appends a `subscription.updated` (or\n`subscription.canceled`, when the snapshot's own status is terminal)\nevent with a deterministic `sync:<sha256>` providerEventId when it has\ndrifted, a no-op otherwise. The `sync-subscriptions` job (manual-trigger +\nrunOnBoot, perTenant) dispatches it and is registered unconditionally.\n`isBillingEnabled(ctx, providerName)` returns `false` instead of throwing\nwhen `providerName` isn't registered.",
+    "migration": "No action needed — every part is additive. Apps on `subscription-stripe`\nautomatically get `retrieveSubscription` wired; a custom provider plugin\nwithout one makes `sync-subscription` report\n`{ synced: false, reason: \"provider_cannot_retrieve\" }` instead of syncing.\nOn the next deploy, `sync-subscriptions`' `runOnBoot` fires once per Redis\ndataset (not once per replica) with one provider API call per tenant that\nhas a live subscription. If that run is interrupted (deploy killed\nmid-fan-out, Redis restart), it is not re-run automatically on the next\nboot — trigger it manually via `billing-foundation:job:sync-subscriptions`\n(`jobs:write:trigger`) to catch up."
+  },
+  {
+    "version": "0.319.0",
+    "type": "improvement",
+    "title": "billing-plans no longer throws when no provider is mounted",
+    "detail": "billing-plans now resolves the catalog's provider through a new\n`findCatalogProvider` (returns `null` instead of throwing) and returns\n`{ enabled: false, ... }` when none is mounted, instead of failing the\nwhole query with UnconfiguredError. Apps that mounted Stripe with an\nempty price map purely to keep this query alive can drop that\nworkaround. An ambiguous catalog (more than one matching provider\nmounted) still throws UnconfiguredError — that case didn't change."
+  },
+  {
+    "version": "0.319.0",
+    "type": "breaking",
+    "title": "start-plan-checkout and switch-plan reject with FeatureDisabledError, not UnconfiguredError, when no provider is mounted",
+    "migration": "start-plan-checkout and switch-plan now reject with FeatureDisabledError\n(code \"feature_disabled\", HTTP 403) instead of UnconfiguredError (code\n\"unconfigured\", HTTP 422) when no provider is mounted for the catalog. A\ncaller that specifically catches UnconfiguredError from these two\nhandlers, or branches on the 422 status, must catch FeatureDisabledError\n/ branch on 403 instead."
+  },
+  {
+    "version": "0.319.0",
+    "type": "breaking",
+    "title": "billing-plans now reports a scheduled cancellation and the panel offers reactivation",
+    "migration": "SubscriptionView and BillingPlansResult.subscription gain two REQUIRED\nfields: `currentPeriodEnd` (a `Temporal.Instant`, ISO string on\nBillingPlansResult) and `cancelAt` (`Temporal.Instant | null`, ISO\nstring or null on BillingPlansResult). Any test fake that constructs a\nSubscriptionView object literal directly must add both fields.\nBillingPlansResult.currentTier also gains a `benefits` field\n(via `catalog.benefits(currentTier)`), computed even when currentTier is\noutside `catalog.plans` (e.g. a legacy/free tier).\n\nThe Stripe provider now maps `subscription.cancel_at` (or\n`current_period_end` when only `cancel_at_period_end` is set) into a new\n`cancelAtIso` event payload field; process-event applies it with\nset/clear/leave-unchanged semantics, so an event without the field never\nwipes a previously recorded value.\n\nBillingPlansPanel shows an info banner (\"Your subscription is scheduled\nto end on {date}\") whenever `subscription.cancelAt` is set and the\nsubscription isn't terminal, and swaps the manage-subscription button's\nlabel to \"Reactivate subscription\" in the same case. The synthetic\ncurrent-tier card (a tier outside `catalog.plans`, e.g. a legacy/free\ntier) now also renders `catalog.benefits(currentTier)` and the same\nmanage/reactivate action as a catalog card, via a shared helper — no\naction needed unless an app relied on that card being action-less.\n\n`read_subscriptions` gains a nullable `cancel_at` column. Every app that\nmounts billing-foundation — including a plain `billingFoundationFeature()`\nwith no catalog (e.g. kumiko-studio) — must run\n`bun kumiko-schema generate <name>` (offlot-app wraps it as\n`bun run schema:generate <name>`) and commit the resulting migration. Skipping this leaves\nthe app's own `read_subscriptions` table without the column, so the\nprojection's `apply` fails at the next subscription webhook. The column\nis additive and nullable — no rebuild, existing rows keep it `null`\nuntil their next subscription webhook."
+  },
+  {
+    "version": "0.319.0",
+    "type": "improvement",
+    "title": "billing-foundation exports resolveProviderPlugin, isBillingEnabled and the /web QN constants",
+    "detail": "The server barrel now exports `resolveProviderPlugin`, `isBillingEnabled`\nand the `ResolvedProvider` type, built on internal\n`isPluginBillingEnabled`/`assertBillingEnabled` helpers already used by\nevery handler that gates on billing being enabled. An app that\nduplicated this provider-lookup-plus-cast itself (offlot did) can call\n`resolveProviderPlugin`/`isBillingEnabled` instead and drop the cast.\n\nThe `/web` barrel now exports `SubscriptionFoundationHandlers`,\n`SubscriptionFoundationQueries`, `BillingPlanActions`,\n`SubscriptionStatuses`, `BILLING_PLANS_SCREEN_ID` and the\n`BillingPlanBenefit`/`BillingPlanCatalog`/`BillingPlansResult`/\n`BillingPlanView` types. An app that hand-copied these QN constants\n(publicstatus did) can import them from `/web` instead."
+  },
+  {
+    "version": "0.319.0",
+    "type": "breaking",
+    "title": "create-checkout-session's mode:\"payment\" now requires a declared one-off-price allowlist",
+    "migration": "SubscriptionProviderPlugin gains an `oneOffPriceIds` field (a readonly\nstring array, defaulting to empty). create-checkout-session's\nmode:\"payment\" branch now rejects any priceId that isn't in the\nresolved provider's `oneOffPriceIds` with an UnprocessableError whose\ndetails.reason is \"unknown_price\" (same shape as the existing\nsubscription-mode price check) — previously any priceId was accepted,\nso a TenantAdmin could start a one-off checkout against an arbitrary\nStripe price. mode:\"payment\" also now goes through the same\nisBillingEnabled gate as mode:\"subscription\", before the redirect-origin\ncheck, and fails with FeatureDisabledError when billing isn't enabled.\n\nEvery provider mount that offers one-off purchases (credit packs,\ntop-ups, ...) must list their priceIds explicitly. offlot-app's\nstart-pack-checkout.write.ts mounts Stripe for credit-pack purchases via\nmode:\"payment\" and needs its pack priceIds added, e.g.:\n`createSubscriptionStripeFeature({ priceToTier, oneOffPriceIds: configuredPackPriceIds() })`\n(or the equivalent option on its provider plugin), or every pack\ncheckout starts failing with \"unknown_price\" after this release.\n`oneOffPriceIds` is validated at mount time — an empty-string entry or a\nduplicate priceId now throws instead of silently widening/narrowing the\nallowlist."
+  },
+  {
+    "version": "0.319.0",
+    "type": "breaking",
+    "title": "create-portal-session now computes returnUrl server-side and honors the catalog's purchase roles",
+    "migration": "create-portal-session's payload schema is now `z.object({}).strict()` — a\nclient that still sends `{ returnUrl }` gets a 400 instead of the URL\nbeing honored. The server now computes returnUrl itself from\n`catalog.returnPath` (joined onto `baseUrl`) or, without a catalog or\nreturnPath, from `baseUrl` directly; a foundation mounted without\n`baseUrl` fails the call with UnconfiguredError on the \"baseUrl\" key,\nsame as create-checkout-session. Update any client call to\n`portalMutation.mutate({})` — BillingPlansPanel already does this and no\nlonger reads `window.location.href`, which used to trigger\nredirect_origin_not_allowed on a `www.`-prefixed origin. A server-internal\ncaller like offlot-app's open-portal.write.ts, which currently does\n`ctx.write(SubscriptionFoundationHandlers.createPortalSession, { returnUrl })`,\nmust drop the `returnUrl` field from that call and instead set the return\ntarget via `catalog.returnPath` (or, without a catalog, the target is\nsimply `baseUrl`).\n\nAccess control also changed: with a catalog configured, the handler's\nallowed roles are now `catalog.purchaseRoles` (falling back to the\ncatalog's default purchase roles) instead of the hardcoded\nTenantAdmin/SystemAdmin pair. An app that lets e.g. a plain Admin role\npurchase plans must add that role to `catalog.purchaseRoles` to keep\nportal access working; conversely, a role that isn't in\n`purchaseRoles` now gets a 403 where it previously reached the handler.\n\nSet `catalog.returnPath` to the app's billing page (e.g.\n\"/host/billing\", or offlot's `${APP_BASE_PATH}/${MY_BILLING_SCREEN_ID}`),\notherwise the portal sends the user back to the bare `baseUrl`."
+  },
+  {
+    "version": "0.318.0",
+    "type": "improvement",
+    "title": "Add a shared billing-plans catalog (start-plan-checkout, switch-plan, BillingPlansPanel)",
+    "detail": "BillingFoundationOptions gains an optional catalog: BillingPlanCatalog<TTier>, describing the app's purchasable tiers, benefits, current-tier resolution and view/purchase roles. Two new write handlers, start-plan-checkout and switch-plan, and a billing-plans query resolve prices via the provider's retrievePrices, decide checkout vs. switch per tier, and enforce viewRoles/purchaseRoles. BillingPlansPanel (web) renders the catalog via the new PlanCard/PlanGrid widgets, handling loading/error/disabled/read-only states and disabling every CTA while a checkout/switch/portal mutation is in flight."
+  },
+  {
+    "version": "0.318.0",
+    "type": "breaking",
+    "title": "create-checkout-session and create-portal-session are now hardened: origin-checked redirects, known-price validation, plan-switch conflicts",
+    "migration": "Mount the foundation via createBillingFoundationFeature({ baseUrl }) (a\npath prefix is fine, e.g. \"https://app.example.com/tenant-x\"). Without\nbaseUrl, every create-checkout-session call now fails with an\nUnconfiguredError on the \"baseUrl\" key, including mode:\"payment\" checkouts.\n\ncreate-checkout-session: successUrl/cancelUrl must share baseUrl's origin,\nor the call fails with an UnprocessableError whose details.reason is\n\"redirect_origin_not_allowed\". For mode:\"subscription\" (the default when\nmode is omitted), priceId must be a price the resolved provider's\npriceToTier map actually knows about, and, if a catalog is configured,\nmust map to one of catalog.plans, or the call fails with reason\n\"unknown_price\". A tenant with an existing non-terminal subscription can\nno longer open a second subscription checkout. A ConflictError with\ni18nKey \"billing-foundation.errors.subscriptionExists\" fires instead; call\nbilling-foundation:write:switch-plan to change plans. mode:\"payment\"\n(one-off top-ups etc.) is exempt from both the price and the\nsubscription-conflict check and keeps working on an active subscription\nunchanged.\n\nProvider plugins written before this release should add a priceToTier map\non their SubscriptionProviderPlugin; without one, every mode:\"subscription\"\ncheckout is rejected with reason \"provider_has_no_price_catalog\".\n\nDirect-priceId callers of create-checkout-session should migrate to a\ncatalog plus billing-foundation:write:start-plan-checkout /\nbilling-foundation:write:switch-plan (or the BillingPlansPanel widget),\nwhich pick the price server-side and never expose a raw priceId to the\nclient.\n\ncreate-portal-session: when baseUrl is set, the payload's returnUrl must\nalso share its origin, or the same redirect_origin_not_allowed error\nfires. Unchanged when baseUrl is not configured.\n\ncreate-checkout-session: an optional providerCustomerId is now only\naccepted if it belongs to the tenant's own subscription at the same\nprovider, including a canceled one. Otherwise the call fails with an\nUnprocessableError whose details.reason is \"foreign_provider_customer\".\nThis closes a gap where a TenantAdmin could pass another tenant's\nprovider customer id and have the checkout attach to that customer's\nstored payment methods and invoices. Checked in both mode:\"subscription\"\nand mode:\"payment\"."
+  },
+  {
+    "version": "0.318.0",
+    "type": "improvement",
+    "title": "billing-foundation's checkout gate no longer blocks forever on a stale incomplete subscription",
+    "detail": "A stale `incomplete` subscription (older than 24h) no longer counts as an active subscription for the checkout gate, so a tenant whose Stripe checkout was abandoned can start a fresh one. `SubscriptionView.lastChangedAt` (required) and `BillingPlanActions.paymentPending` are new; a consumer with an exhaustive switch over `BillingPlanAction` needs a `paymentPending` case. Known limit: two checkouts started in parallel before the provider's first webhook arrives can still create two subscriptions, since the gate only sees subscriptions already projected."
+  },
+  {
+    "version": "0.306.0",
+    "type": "fix",
+    "title": "Tenant destroy no longer fails on subscription and payment rows",
+    "detail": "The subscription and payment tenant-destroy hooks passed the tenant-scoped TenantDb they receive into raw DbRunner helpers, so the app-data stage failed and the tenant ended in destroyFailed. They now use ctx.db methods and declare an escapeHatch for the compliance-profile lookup and the event-stream archive."
+  },
+  {
+    "version": "0.301.0",
+    "type": "breaking",
+    "title": "billing-foundation no longer exports SystemWriteResult (removed in 0.298.0 without a changelog note)",
+    "migration": "SystemWriteResult was exported from @cosmicdrift/kumiko-bundled-features/billing-foundation up to 0.297.0 and was dropped in 0.298.0 together with the dispatchSystemWrite dep of createSubscriptionTierSync; there is no alias. Code that still imports it fails with \"has no exported member 'SystemWriteResult'\". If the type is only used for a dispatchSystemWrite dep passed to createSubscriptionTierSync, drop that dep and the type together (see the 0.298.0 webhook-wiring migration: extraRoutes: [createSubscriptionTierSync({ ... }).createWebhookRoute()]). Where a system-write result type is still needed, import type { WriteResult } from \"@cosmicdrift/kumiko-framework/engine\" and use WriteResult<unknown>; it is a discriminated union ({ isSuccess: true; data } | WriteFailure), so narrow on isSuccess before reading data or error."
+  },
+  {
+    "version": "0.298.0",
+    "type": "breaking",
+    "title": "Billing webhook wiring moves from a raw handler to createSubscriptionWebhookRoute()/createWebhookRoute()",
+    "migration": "createSubscriptionWebhookHandler(...) is replaced by createSubscriptionWebhookRoute({ path?, afterDispatch? }), which returns an ExtraRouteDefinition for the extraRoutes array instead of a manually-mounted handler; the route path still defaults to /webhooks/subscription/:providerName. createSubscriptionTierSync(...) deps drop db, registry, dispatchSystemWrite and tierAssignmentTable - it now exposes .createWebhookRoute(), which produces the signature-verified ExtraRouteDefinition to add to extraRoutes. A webhook previously wired as extraRoutes: (app, deps) => { app.post(\"/webhooks/subscription/:providerName\", createSubscriptionWebhookHandler(...)) } becomes extraRoutes: [createSubscriptionTierSync({ ... }).createWebhookRoute()] (or createSubscriptionWebhookRoute({...}) for the lower-level handler), with db/registry/dispatchSystemWrite no longer passed in - the route's signature-entry deps (systemQuery, dispatchSystemWrite, dispatchSystemQuery) cover the read/write access the old handler needed."
+  },
+  {
+    "version": "0.288.0",
+    "type": "improvement",
+    "title": "add onSyncError option to createSubscriptionTierSync",
+    "detail": "`SubscriptionTierSyncDeps<TTier>` gets an optional `onSyncError?: \"log\" | \"fail-webhook\"`\n(default `\"log\"`, matching prior behavior exactly). `\"fail-webhook\"` makes a tier-sync\nfailure also fail the webhook response, so an idempotent-retry caller (whose retry\nno-ops the already-committed primary write) gets another attempt at the sync step."
+  },
+  {
+    "version": "0.286.0",
+    "type": "improvement",
+    "title": "Add createBillingInfoQueryConfig factory for the billing-info query handler",
+    "detail": "Extracted from the near-identical app copies in show-pony and publicstatus. Returns a handler-config object rather than calling defineQueryHandler itself, so apps can pass it through their own wrapper."
+  }
+]