@cosmicdrift/kumiko-bundled-features 0.317.0 → 0.319.0

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

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "bun:test";
+import { UnconfiguredError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+// Aliased — an un-aliased `Temporal` would shadow the ambient global
+// `Temporal` TYPE `SubscriptionView.lastChangedAt` resolves against.
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import {
+  assertRedirectOrigins,
+  isNonEmptyStringArray,
+  isOwnProviderCustomer,
+  joinBaseUrl,
+} from "../checkout-core";
+import type { SubscriptionView } from "../get-subscription-for-tenant";
+
+function subscriptionView(overrides: Partial<SubscriptionView> = {}): SubscriptionView {
+  return {
+    tier: "pro",
+    status: "canceled",
+    providerName: "mock",
+    providerCustomerId: "cus_own",
+    providerSubscriptionId: "sub_own",
+    // @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal.Instant
+    // at runtime — SubscriptionView.lastChangedAt is typed against the
+    // ambient Temporal global; temporal-polyfill's own nominal Instant type
+    // differs across the two .d.ts sources.
+    currentPeriodEnd: TemporalPolyfill.Instant.from(
+      "2024-02-01T00:00:00Z",
+    ) as unknown as Temporal.Instant,
+    cancelAt: null,
+    lastChangedAt: TemporalPolyfill.Instant.from(
+      "2024-01-01T00:00:00Z",
+    ) as unknown as Temporal.Instant,
+    ...overrides,
+  };
+}
+
+describe("assertRedirectOrigins", () => {
+  test("throws UnconfiguredError when baseUrl is undefined, regardless of urls", () => {
+    expect(() => assertRedirectOrigins(["https://example.com/success"], undefined)).toThrow(
+      UnconfiguredError,
+    );
+  });
+
+  test("throws UnconfiguredError when baseUrl is not a parseable absolute URL", () => {
+    expect(() => assertRedirectOrigins(["https://example.com/success"], "not-a-url")).toThrow(
+      UnconfiguredError,
+    );
+  });
+
+  test("passes when every url shares baseUrl's origin", () => {
+    expect(() =>
+      assertRedirectOrigins(
+        ["https://example.com/success", "https://example.com/cancel"],
+        "https://example.com",
+      ),
+    ).not.toThrow();
+  });
+
+  test("passes when baseUrl carries a path prefix — only the origin is compared", () => {
+    expect(() =>
+      assertRedirectOrigins(["https://example.com/success"], "https://example.com/tenant-x"),
+    ).not.toThrow();
+  });
+
+  test("throws UnprocessableError('redirect_origin_not_allowed') for a different origin", () => {
+    expect(() =>
+      assertRedirectOrigins(["https://attacker.example/success"], "https://example.com"),
+    ).toThrow(UnprocessableError);
+  });
+
+  test("throws UnprocessableError for a lookalike host that merely starts with baseUrl's host", () => {
+    expect(() =>
+      assertRedirectOrigins(["https://example.com.evil.com/success"], "https://example.com"),
+    ).toThrow(UnprocessableError);
+  });
+
+  test("throws UnprocessableError for a different scheme on an otherwise-matching host", () => {
+    expect(() =>
+      assertRedirectOrigins(["http://example.com/success"], "https://example.com"),
+    ).toThrow(UnprocessableError);
+  });
+
+  test("throws UnprocessableError for a different port", () => {
+    expect(() =>
+      assertRedirectOrigins(["https://example.com:8443/success"], "https://example.com"),
+    ).toThrow(UnprocessableError);
+  });
+
+  test("throws UnprocessableError for a url that isn't a parseable absolute URL", () => {
+    expect(() => assertRedirectOrigins(["/relative/path"], "https://example.com")).toThrow(
+      UnprocessableError,
+    );
+  });
+
+  test("empty urls list never throws, even with baseUrl set", () => {
+    expect(() => assertRedirectOrigins([], "https://example.com")).not.toThrow();
+  });
+});
+
+describe("joinBaseUrl", () => {
+  test("concatenates baseUrl and path as-is when baseUrl has no trailing slash", () => {
+    expect(joinBaseUrl("https://app.example.com", "/billing/success")).toBe(
+      "https://app.example.com/billing/success",
+    );
+  });
+
+  test("strips a trailing slash on baseUrl so the result never becomes protocol-relative", () => {
+    expect(joinBaseUrl("https://app.example.com/", "/billing/success")).toBe(
+      "https://app.example.com/billing/success",
+    );
+  });
+
+  test("preserves a path-prefix baseUrl (tenant subdirectory)", () => {
+    expect(joinBaseUrl("https://app.example.com/tenant-x", "/billing/success")).toBe(
+      "https://app.example.com/tenant-x/billing/success",
+    );
+  });
+
+  test("preserves a path-prefix baseUrl with a trailing slash, without doubling the slash", () => {
+    expect(joinBaseUrl("https://app.example.com/tenant-x/", "/billing/success")).toBe(
+      "https://app.example.com/tenant-x/billing/success",
+    );
+  });
+});
+
+describe("isNonEmptyStringArray", () => {
+  test("true for a non-empty array", () => {
+    expect(isNonEmptyStringArray(["pro"])).toBe(true);
+  });
+
+  test("false for an empty array", () => {
+    expect(isNonEmptyStringArray([])).toBe(false);
+  });
+});
+
+describe("isOwnProviderCustomer", () => {
+  test("false when the tenant has no subscription at all", () => {
+    expect(isOwnProviderCustomer(null, "mock", "cus_own")).toBe(false);
+  });
+
+  test("false for a subscription at a different provider", () => {
+    expect(
+      isOwnProviderCustomer(subscriptionView({ providerName: "stripe" }), "mock", "cus_own"),
+    ).toBe(false);
+  });
+
+  test("false for a different customer id at the same provider", () => {
+    expect(isOwnProviderCustomer(subscriptionView(), "mock", "cus_other_tenant")).toBe(false);
+  });
+
+  test("true for the tenant's own customer id at the same provider, even canceled", () => {
+    expect(isOwnProviderCustomer(subscriptionView(), "mock", "cus_own")).toBe(true);
+  });
+});

package/src/billing-foundation/__tests__/constants.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+// Aliased — an un-aliased `Temporal` would shadow the ambient global
+// `Temporal` TYPE isSubscriptionBlockingCheckout's `now`/`lastChangedAt`
+// params resolve against.
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import {
+  isSubscriptionBlockingCheckout,
+  STALE_INCOMPLETE_AFTER,
+  SubscriptionStatuses,
+} from "../constants";
+
+// @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal.Instant at
+// runtime — `isSubscriptionBlockingCheckout`'s params are typed against the
+// ambient Temporal global; temporal-polyfill's own nominal Instant type
+// differs across the two .d.ts sources.
+const LAST_CHANGED = TemporalPolyfill.Instant.from(
+  "2024-01-01T00:00:00Z",
+) as unknown as Temporal.Instant;
+
+describe("isSubscriptionBlockingCheckout", () => {
+  test("STALE_INCOMPLETE_AFTER is 24 hours", () => {
+    expect(STALE_INCOMPLETE_AFTER.total("hours")).toBe(24);
+  });
+
+  test("a canceled subscription never blocks, regardless of age", () => {
+    expect(
+      isSubscriptionBlockingCheckout(
+        { status: SubscriptionStatuses.canceled, lastChangedAt: LAST_CHANGED },
+        LAST_CHANGED,
+      ),
+    ).toBe(false);
+  });
+
+  test("an active subscription always blocks", () => {
+    expect(
+      isSubscriptionBlockingCheckout(
+        { status: SubscriptionStatuses.active, lastChangedAt: LAST_CHANGED },
+        LAST_CHANGED.add({ hours: 1000 }),
+      ),
+    ).toBe(true);
+  });
+
+  test("a fresh incomplete subscription (23h59) still blocks", () => {
+    const now = LAST_CHANGED.add(TemporalPolyfill.Duration.from({ hours: 23, minutes: 59 }));
+    expect(
+      isSubscriptionBlockingCheckout(
+        { status: SubscriptionStatuses.incomplete, lastChangedAt: LAST_CHANGED },
+        now,
+      ),
+    ).toBe(true);
+  });
+
+  test("a stale incomplete subscription (24h01) no longer blocks", () => {
+    const now = LAST_CHANGED.add(TemporalPolyfill.Duration.from({ hours: 24, minutes: 1 }));
+    expect(
+      isSubscriptionBlockingCheckout(
+        { status: SubscriptionStatuses.incomplete, lastChangedAt: LAST_CHANGED },
+        now,
+      ),
+    ).toBe(false);
+  });
+
+  test("an incomplete subscription exactly at the cutoff no longer blocks", () => {
+    const now = LAST_CHANGED.add(STALE_INCOMPLETE_AFTER);
+    expect(
+      isSubscriptionBlockingCheckout(
+        { status: SubscriptionStatuses.incomplete, lastChangedAt: LAST_CHANGED },
+        now,
+      ),
+    ).toBe(false);
+  });
+});

package/src/billing-foundation/__tests__/feature.test.ts

@@ -4,12 +4,27 @@ import { describe, expect, test } from "bun:test";
 import { paymentAggregateId, paymentRowId, subscriptionAggregateId } from "../aggregate-id";
 import {
   BILLING_FOUNDATION_FEATURE,
+  BILLING_PLANS_SCREEN_ID,
   SUBSCRIPTION_PROVIDER_EXTENSION,
   SubscriptionEventTypes,
   SubscriptionFoundationHandlers,
   SubscriptionStatuses,
 } from "../constants";
-import { billingFoundationFeature } from "../feature";
+import { billingFoundationFeature, createBillingFoundationFeature } from "../feature";
+import type { BillingPlanCatalog } from "../types";
+
+function catalog(overrides: Partial<BillingPlanCatalog> = {}): BillingPlanCatalog {
+  return {
+    plans: ["basic", "pro"],
+    tierLabelKey: (tier) => `plan.${tier}.label`,
+    benefits: () => [],
+    resolveCurrentTier: async () => "basic",
+    viewRoles: ["TenantAdmin", "SystemAdmin"],
+    successPath: "/billing/success",
+    cancelPath: "/billing/cancel",
+    ...overrides,
+  };
+}
 
 describe("billingFoundationFeature — shape", () => {
   test("has the expected name", () => {
@@ -116,3 +131,126 @@ describe("normalized constants — provider-agnostic event-types + statuses", ()
     ]);
   });
 });
+
+describe("createBillingFoundationFeature — factory validation", () => {
+  test("mounts with no options at all", () => {
+    expect(() => createBillingFoundationFeature()).not.toThrow();
+  });
+
+  test("mounts with only baseUrl, no catalog", () => {
+    expect(() => createBillingFoundationFeature({ baseUrl: "https://example.com" })).not.toThrow();
+  });
+
+  test("throws when baseUrl is not a parseable absolute URL", () => {
+    expect(() => createBillingFoundationFeature({ baseUrl: "not-a-url" })).toThrow(
+      /not a parseable absolute URL/,
+    );
+  });
+
+  test("throws when baseUrl uses a non-http(s) scheme", () => {
+    expect(() => createBillingFoundationFeature({ baseUrl: "ftp://example.com" })).toThrow(
+      /must use http or https/,
+    );
+  });
+
+  test("accepts https and http baseUrls", () => {
+    expect(() => createBillingFoundationFeature({ baseUrl: "https://example.com" })).not.toThrow();
+    expect(() =>
+      createBillingFoundationFeature({ baseUrl: "http://localhost:3000" }),
+    ).not.toThrow();
+  });
+
+  test("throws when catalog is set without baseUrl", () => {
+    expect(() => createBillingFoundationFeature({ catalog: catalog() })).toThrow(
+      /catalog requires baseUrl/,
+    );
+  });
+
+  test("mounts when catalog and baseUrl are both set", () => {
+    expect(() =>
+      createBillingFoundationFeature({ baseUrl: "https://example.com", catalog: catalog() }),
+    ).not.toThrow();
+  });
+
+  test("throws when catalog.plans is empty", () => {
+    expect(() =>
+      createBillingFoundationFeature({
+        baseUrl: "https://example.com",
+        catalog: catalog({ plans: [] }),
+      }),
+    ).toThrow(/catalog.plans must not be empty/);
+  });
+
+  test("throws when catalog.plans has a duplicate tier", () => {
+    expect(() =>
+      createBillingFoundationFeature({
+        baseUrl: "https://example.com",
+        catalog: catalog({ plans: ["pro", "pro"] }),
+      }),
+    ).toThrow(/duplicate tier "pro"/);
+  });
+
+  test("throws when successPath doesn't start with /", () => {
+    expect(() =>
+      createBillingFoundationFeature({
+        baseUrl: "https://example.com",
+        catalog: catalog({ successPath: "billing/success" }),
+      }),
+    ).toThrow(/successPath "billing\/success" must start with "\/"/);
+  });
+
+  test("throws when cancelPath is protocol-relative (//)", () => {
+    expect(() =>
+      createBillingFoundationFeature({
+        baseUrl: "https://example.com",
+        catalog: catalog({ cancelPath: "//evil.example.com" }),
+      }),
+    ).toThrow(/cancelPath/);
+  });
+
+  test("throws when returnPath is set and invalid", () => {
+    expect(() =>
+      createBillingFoundationFeature({
+        baseUrl: "https://example.com",
+        catalog: catalog({ returnPath: "not-root-relative" }),
+      }),
+    ).toThrow(/returnPath/);
+  });
+
+  test("accepts a valid returnPath", () => {
+    expect(() =>
+      createBillingFoundationFeature({
+        baseUrl: "https://example.com",
+        catalog: catalog({ returnPath: "/billing/return" }),
+      }),
+    ).not.toThrow();
+  });
+
+  test("throws when viewRoles is empty", () => {
+    expect(() =>
+      createBillingFoundationFeature({
+        baseUrl: "https://example.com",
+        catalog: catalog({ viewRoles: [] }),
+      }),
+    ).toThrow(/viewRoles must not be empty/);
+  });
+});
+
+describe("billingFoundationFeature — dormant billing-plans screen (#3316 P9)", () => {
+  test("not registered without a catalog", () => {
+    const feature = createBillingFoundationFeature({ baseUrl: "https://example.com" });
+    expect(feature.screens[BILLING_PLANS_SCREEN_ID]).toBeUndefined();
+  });
+
+  test("not registered with no options at all", () => {
+    expect(billingFoundationFeature.screens[BILLING_PLANS_SCREEN_ID]).toBeUndefined();
+  });
+
+  test("registered once a catalog is configured", () => {
+    const feature = createBillingFoundationFeature({
+      baseUrl: "https://example.com",
+      catalog: catalog(),
+    });
+    expect(feature.screens[BILLING_PLANS_SCREEN_ID]).toBeDefined();
+  });
+});

package/src/billing-foundation/changes.json

@@ -1,4 +1,58 @@
 [
+  {
+    "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",