@startsimpli/billing 0.4.23 → 0.4.25

package/src/components/__fixtures__/crochetProduct.ts

@@ -0,0 +1,172 @@
+/**
+ * The live crochets.site catalogue (GET /billing/products/crochet-patterns/,
+ * 2026-10-16), camelised the way the proxy hands it to the components.
+ * `tier` is not served yet, so the base fixture omits it on purpose: the
+ * picker has to pair Lite with Lite Annual without it.
+ */
+import type { BillingProduct, ProductOffer, SubscriptionInfo } from "../../types";
+
+const base = {
+  currency: "USD",
+  pricingModel: "flat" as const,
+  intervalCount: 1,
+  isRecurring: true,
+  isActive: true,
+  isFeatured: false,
+};
+
+const liteFeatures = [
+  { key: "ai_designs", name: "AI pattern designs", value: true },
+  { key: "ai_designs_per_month", name: "AI designs per month", value: 3 },
+  { key: "ai_refine", name: "AI chat to refine any pattern", value: true },
+  { key: "pdf_export", name: "Print-ready PDF export", value: true },
+  { key: "save_patterns", name: "Save patterns to your library", value: true },
+  { key: "track_progress", name: "Track your progress", value: true },
+  { key: "patterns_per_month", name: "Saved patterns per month", value: -1 },
+];
+
+const proFeatures = [
+  { key: "ai_designs", name: "AI pattern designs, made with our best model and checked by a design review", value: true },
+  { key: "patterns_per_month", name: "AI designs per month", value: -1 },
+  { key: "ai_refine", name: "AI chat to refine any pattern", value: true },
+  { key: "pdf_export", name: "Print-ready PDF export", value: true },
+  { key: "custom_sizing", name: "Custom sizing", value: true },
+  { key: "trial_note", name: "7-day free trial with AI designs included", value: true },
+];
+
+export const crochetFree: ProductOffer = {
+  ...base,
+  id: "free-id",
+  name: "Free",
+  slug: "crochet-free",
+  unitPrice: "0.00",
+  intervalUnit: "month",
+  intervalDisplay: "per month",
+  isFree: true,
+  features: [
+    { key: "ai_designs", name: "AI pattern designs", value: false },
+    { key: "browse_patterns", name: "Browse and buy patterns", value: true },
+    { key: "save_patterns", name: "Save patterns to your library", value: true },
+    { key: "track_progress", name: "Track your progress", value: true },
+    { key: "pdf_export", name: "Print-ready PDF export", limit: null, value: true },
+  ],
+  trialDays: 0,
+  sortOrder: 0,
+  ctaText: "Get Started",
+};
+
+export const crochetLite: ProductOffer = {
+  ...base,
+  id: "lite-id",
+  name: "Lite",
+  slug: "crochet-lite",
+  unitPrice: "2.99",
+  intervalUnit: "month",
+  intervalDisplay: "per month",
+  isFree: false,
+  features: liteFeatures,
+  trialDays: 0,
+  sortOrder: 1,
+  ctaText: "Get Lite",
+};
+
+export const crochetLiteAnnual: ProductOffer = {
+  ...base,
+  id: "lite-annual-id",
+  name: "Lite Annual",
+  slug: "crochet-lite-annual",
+  unitPrice: "29.00",
+  intervalUnit: "year",
+  intervalDisplay: "per year",
+  isFree: false,
+  features: liteFeatures,
+  trialDays: 0,
+  sortOrder: 1,
+  ctaText: "Get Lite",
+};
+
+export const crochetPro: ProductOffer = {
+  ...base,
+  id: "pro-id",
+  name: "Pro",
+  slug: "crochet-pro",
+  unitPrice: "9.00",
+  intervalUnit: "month",
+  intervalDisplay: "per month",
+  isFree: false,
+  features: proFeatures,
+  trialDays: 7,
+  sortOrder: 2,
+  ctaText: "Start Free Trial",
+};
+
+export const crochetProAnnual: ProductOffer = {
+  ...base,
+  id: "pro-annual-id",
+  name: "Pro Annual",
+  slug: "crochet-pro-annual",
+  unitPrice: "89.00",
+  intervalUnit: "year",
+  intervalDisplay: "per year",
+  isFree: false,
+  features: proFeatures,
+  trialDays: 7,
+  sortOrder: 2,
+  ctaText: "Start Free Trial",
+};
+
+/** What production serves today: no Pro Annual, no `tier`. */
+export const crochetProduct: BillingProduct = {
+  id: "034a56c9",
+  slug: "crochet-patterns",
+  name: "Crochet Patterns",
+  description: "AI-powered crochet pattern generator with step-by-step instructions.",
+  offers: [crochetFree, crochetLite, crochetLiteAnnual, crochetPro],
+};
+
+/** After the in-flight deploy: `tier` on every paid offer, plus Pro Annual. */
+export const crochetProductWithTiers: BillingProduct = {
+  ...crochetProduct,
+  offers: [
+    crochetFree,
+    { ...crochetLite, tier: "lite" },
+    { ...crochetLiteAnnual, tier: "lite" },
+    { ...crochetPro, tier: "pro" },
+    { ...crochetProAnnual, tier: "pro" },
+  ],
+};
+
+export function subscriptionTo(offer: ProductOffer, status: SubscriptionInfo["status"] = "active"): SubscriptionInfo {
+  return {
+    id: `sub-${offer.slug}`,
+    offer,
+    status,
+    currentPeriodStart: "2026-10-01T00:00:00Z",
+    currentPeriodEnd: "2026-11-01T00:00:00Z",
+    cancelAtPeriodEnd: false,
+    trialEnd: null,
+    viewerIsOwner: true,
+  };
+}
+
+/** A fetch that serves the product and the given subscription (null = 404). */
+export function crochetFetcher(
+  product: BillingProduct,
+  subscription: SubscriptionInfo | null,
+): typeof fetch {
+  return ((url: string) => {
+    if (url.includes("/billing/subscription/current/")) {
+      if (subscription === null) {
+        return Promise.resolve({ ok: false, status: 404, json: () => Promise.resolve({ detail: "none" }) });
+      }
+      return Promise.resolve({ ok: true, status: 200, json: () => Promise.resolve(subscription) });
+    }
+    if (url.includes("/billing/usage/")) {
+      return Promise.resolve({ ok: true, status: 200, json: () => Promise.resolve({}) });
+    }
+    if (url.includes("/billing/products/")) {
+      return Promise.resolve({ ok: true, status: 200, json: () => Promise.resolve(product) });
+    }
+    return Promise.resolve({ ok: false, status: 404, json: () => Promise.resolve({}) });
+  }) as unknown as typeof fetch;
+}

package/src/components/index.ts

@@ -16,3 +16,5 @@ export { CurrentPlanCard } from "./CurrentPlanCard";
 export type { CurrentPlanCardProps } from "./CurrentPlanCard";
 export { LimitNudge } from "./LimitNudge";
 export type { LimitNudgeProps } from "./LimitNudge";
+export { PlanChangeConfirm, planChangeCopy } from "./PlanChangeConfirm";
+export type { PlanChangeConfirmProps } from "./PlanChangeConfirm";

package/src/hooks/index.ts

@@ -6,3 +6,5 @@ export { usePortal } from "./usePortal";
 export { useSubscription } from "./useSubscription";
 export { useSuccessSync } from "./useSuccessSync";
 export { useUsage, notifyUsageChanged, USAGE_CHANGED_EVENT } from "./useUsage";
+export { usePlanChange } from "./usePlanChange";
+export type { PlanChangeContext, PlanChangeConfirmState, PlanChangeProceed, UsePlanChangeResult } from "./usePlanChange";

package/src/hooks/usePlanChange.ts

@@ -0,0 +1,144 @@
+/**
+ * usePlanChange — choose a plan, confirming first when the click changes or
+ * ends a plan the viewer already has (crochet_patterns-anw61, -kigcj, -lr7mj).
+ *
+ * A new buyer choosing a paid plan goes straight on: the provider's checkout
+ * page is their confirmation. Anyone already paying, or choosing a free plan,
+ * is asked first, with what the backend says will happen (charged now and how
+ * much, or the date it changes, or that an unlisted plan ends for good).
+ *
+ * While a preview or the change itself is in flight `busy` is true, so
+ * callers disable their plan buttons — a second click used to start a second
+ * checkout (crochet_patterns-9e9o).
+ *
+ * `proceed(offer, preview)` does the change (checkout, subscribe-free, …).
+ * Return "navigating" when it has sent the browser away, so the buttons stay
+ * disabled until the page unloads. Throw to show the message.
+ */
+
+import { useCallback, useRef, useState } from "react";
+import type { PlanChangePreview, ProductOffer } from "../types";
+import { useBillingContext } from "./BillingProvider";
+
+export type PlanChangeProceed = (
+  offer: ProductOffer,
+  preview: PlanChangePreview | null,
+) => Promise<unknown> | unknown;
+
+export interface PlanChangeContext {
+  /** The viewer pays for a running plan (isPayingSubscription). */
+  paying: boolean;
+  /** The viewer's plan is not one of the offers for sale (a complimentary plan). */
+  leavingUnlisted?: boolean;
+  /** The viewer's plan, for the dialog copy when the preview can't be had. */
+  currentOffer?: ProductOffer | null;
+}
+
+export interface PlanChangeConfirmState {
+  offer: ProductOffer;
+  preview: PlanChangePreview | null;
+  currentName: string | null;
+  leavingUnlisted: boolean;
+}
+
+export interface UsePlanChangeResult {
+  choose: (offer: ProductOffer, context: PlanChangeContext) => Promise<void>;
+  confirm: () => Promise<void>;
+  cancel: () => void;
+  /** Open when the viewer must confirm. */
+  pending: PlanChangeConfirmState | null;
+  busy: boolean;
+  /** The confirm step itself is running. */
+  confirming: boolean;
+  error: string | null;
+  clearError: () => void;
+}
+
+export function usePlanChange(proceed: PlanChangeProceed): UsePlanChangeResult {
+  const { client } = useBillingContext();
+  const [pending, setPending] = useState<PlanChangeConfirmState | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [confirming, setConfirming] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const inFlight = useRef(false);
+
+  const run = useCallback(
+    async (offer: ProductOffer, preview: PlanChangePreview | null) => {
+      try {
+        const outcome = await proceed(offer, preview);
+        if (outcome !== "navigating") {
+          inFlight.current = false;
+          setBusy(false);
+        }
+        return true;
+      } catch (e) {
+        inFlight.current = false;
+        setBusy(false);
+        setError(e instanceof Error ? e.message : "Something went wrong. Please try again.");
+        return false;
+      }
+    },
+    [proceed],
+  );
+
+  const choose = useCallback(
+    async (offer: ProductOffer, context: PlanChangeContext) => {
+      if (inFlight.current) return;
+      inFlight.current = true;
+      setBusy(true);
+      setError(null);
+
+      const leavingUnlisted = !!context.leavingUnlisted;
+      // Not paying yet (free, or an unbilled complimentary plan) and choosing a
+      // paid plan: that is a checkout, and its page is the confirmation.
+      if (!context.paying && !offer.isFree) {
+        await run(offer, null);
+        return;
+      }
+
+      let preview: PlanChangePreview | null = null;
+      try {
+        preview = await client.previewPlanChange(offer.id);
+      } catch {
+        preview = null; // still confirm, with the copy we can stand behind
+      }
+      if (preview?.mode === "current") {
+        inFlight.current = false;
+        setBusy(false);
+        return;
+      }
+      if (preview?.mode === "checkout") {
+        await run(offer, preview);
+        return;
+      }
+      setPending({
+        offer,
+        preview,
+        currentName: preview?.currentOffer?.name ?? context.currentOffer?.name ?? null,
+        leavingUnlisted: preview?.currentOffer ? !preview.currentOffer.isListed : leavingUnlisted,
+      });
+    },
+    [client, run],
+  );
+
+  const confirm = useCallback(async () => {
+    if (!pending || confirming) return;
+    setConfirming(true);
+    setError(null);
+    const ok = await run(pending.offer, pending.preview);
+    setConfirming(false);
+    if (ok) setPending(null);
+  }, [pending, confirming, run]);
+
+  const cancel = useCallback(() => {
+    if (confirming) return;
+    setPending(null);
+    setError(null);
+    inFlight.current = false;
+    setBusy(false);
+  }, [confirming]);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  return { choose, confirm, cancel, pending, busy, confirming, error, clearError };
+}

package/src/hooks/useSuccessSync.ts

@@ -16,7 +16,7 @@ import type { CachedSubscriptionState } from "../types";
 import { useBillingContext } from "./BillingProvider";
 
 interface UseSuccessSyncResult {
-  sync: () => Promise<CachedSubscriptionState | null>;
+  sync: (params?: { sessionId?: string | null; productSlug?: string | null }) => Promise<CachedSubscriptionState | null>;
   data: CachedSubscriptionState | null;
   loading: boolean;
   error: Error | null;
@@ -28,11 +28,11 @@ export function useSuccessSync(): UseSuccessSyncResult {
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
-  const sync = useCallback(async () => {
+  const sync = useCallback(async (params?: { sessionId?: string | null; productSlug?: string | null }) => {
     setLoading(true);
     setError(null);
     try {
-      const result = await client.successSync();
+      const result = await client.successSync(params);
       setData(result);
       return result;
     } catch (e) {

package/src/index.ts

@@ -19,10 +19,11 @@ export {
   useSubscription,
   useSuccessSync,
   useUsage,
+  usePlanChange,
   notifyUsageChanged,
   USAGE_CHANGED_EVENT,
 } from "./hooks";
-export type { BillingProviderProps } from "./hooks";
+export type { BillingProviderProps, PlanChangeContext, PlanChangeConfirmState, PlanChangeProceed, UsePlanChangeResult } from "./hooks";
 
 // Types
 export type {
@@ -34,13 +35,14 @@ export type {
   CachedSubscriptionState,
   FreeSubscriptionResult,
   PaymentMethod,
+  PlanChangePreview,
   PortalResult,
   SubscriptionInfo,
   UsageMap,
 } from "./types";
 
 // Components
-export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager, PlanGate, CurrentPlanCard, LimitNudge } from "./components";
+export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager, PlanGate, CurrentPlanCard, LimitNudge, PlanChangeConfirm, planChangeCopy } from "./components";
 export type {
   PricingPageProps,
   PricingSectionProps,
@@ -51,11 +53,28 @@ export type {
   PlanGateProps,
   CurrentPlanCardProps,
   LimitNudgeProps,
+  PlanChangeConfirmProps,
 } from "./components";
 
 // API client (for advanced usage)
 export { BillingApiClient } from "./utils/api";
 
 // Pure helpers
-export { isPaidSubscription, getFeatureLimit, resolvePlanEntitlement, resolveUsageWindow } from "./utils/plan";
-export type { PlanEntitlement, ResolvePlanEntitlementOptions, UsageWindow } from "./utils/plan";
+export {
+  isPaidSubscription,
+  isPayingSubscription,
+  isUnlistedOffer,
+  getFeatureLimit,
+  resolvePlanEntitlement,
+  resolveUsageWindow,
+  resolveCurrentOfferId,
+  resolveCurrentOffer,
+  planDirection,
+  planCtaLabel,
+  trialApplies,
+  TRIAL_NOTE_FEATURE_KEY,
+} from "./utils/plan";
+export type { PlanEntitlement, ResolvePlanEntitlementOptions, UsageWindow, CurrentPlanState, PlanDirection } from "./utils/plan";
+export { formatPrice, formatFeatureLabel } from "./utils/format";
+export { groupOffersByTier, offersForInterval, hasIntervalChoice, annualSavings, tierOffer } from "./utils/tiers";
+export type { BillingInterval, OfferTier } from "./utils/tiers";

package/src/types/index.ts

@@ -23,6 +23,10 @@ export interface ProductOffer {
   trialDays: number;
   sortOrder: number;
   ctaText: string;
+  /** Plan tier shared by an offer's monthly and annual prices ("lite",
+   * "pro"). Optional: older payloads omit it and the picker pairs by
+   * features / name instead. */
+  tier?: string | null;
 }
 
 export interface OfferFeature {
@@ -48,14 +52,43 @@ export interface BillingProduct {
   offers: ProductOffer[];
 }
 
+/**
+ * What choosing an offer will do, from POST /billing/plan-change-preview/
+ * (crochet_patterns-anw61):
+ * - "current"       already on it
+ * - "immediate"     changes now; a paid offer is charged `amountDue` now
+ *                   (null when it could not be priced) and never trials;
+ *                   a free offer ends an unbilled plan now
+ * - "at_period_end" changes on `effectiveAt`; nothing is charged now
+ * - "checkout"      a new checkout, with `trialDays`
+ */
+export interface PlanChangePreview {
+  mode: "current" | "immediate" | "at_period_end" | "checkout";
+  offerId: string;
+  amountDue: string | null;
+  currency: string;
+  effectiveAt: string | null;
+  trialDays: number;
+  /** The plan being left; `isListed` false = not for sale, cannot be chosen again. */
+  currentOffer: { slug: string; name: string; isListed: boolean } | null;
+}
+
 export interface CheckoutResult {
   sessionId: string;
   url: string;
+  /** Set when the offer was a change to a plan already paid for (no checkout):
+   * "immediate", "at_period_end", "payment_required", "pending_change_cancelled".
+   * The backend sends it as `plan_change`. */
+  plan_change?: string;
+  planChange?: string;
 }
 
 export interface FreeSubscriptionResult {
   subscriptionId: string;
   status: string;
+  /** Leaving a paid plan: it ends at `effective_at` instead of now. */
+  scheduled_downgrade?: boolean;
+  effective_at?: string | null;
 }
 
 export interface PortalResult {

package/src/utils/api.ts

@@ -8,6 +8,7 @@ import type {
   CachedSubscriptionState,
   CheckoutResult,
   FreeSubscriptionResult,
+  PlanChangePreview,
   PortalResult,
   SubscriptionInfo,
   UsageMap,
@@ -104,11 +105,47 @@ export class BillingApiClient {
    * Eagerly sync subscription state after Stripe checkout redirect.
    * Call this from your success_url page to avoid waiting for the webhook.
    */
-  async successSync(): Promise<CachedSubscriptionState | null> {
+  /** What choosing an offer will do, without doing it (crochet_patterns-anw61). */
+  async previewPlanChange(offerId: string): Promise<PlanChangePreview> {
+    const url = `${this.config.apiBaseUrl}/billing/plan-change-preview/`;
+    const resp = await this.fetcher(url, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({ offer_id: offerId }),
+    });
+    if (!resp.ok) {
+      const data = await resp.json().catch(() => ({}));
+      throw new Error(billingErrorMessage(data, `Plan preview failed: ${resp.status}`));
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const raw: any = await resp.json();
+    const cur = raw.current_offer ?? raw.currentOffer ?? null;
+    return {
+      mode: raw.mode,
+      offerId: raw.offer_id ?? raw.offerId ?? offerId,
+      amountDue: raw.amount_due ?? raw.amountDue ?? null,
+      currency: raw.currency ?? "usd",
+      effectiveAt: raw.effective_at ?? raw.effectiveAt ?? null,
+      trialDays: raw.trial_days ?? raw.trialDays ?? 0,
+      currentOffer: cur
+        ? { slug: cur.slug, name: cur.name, isListed: (cur.is_listed ?? cur.isListed) !== false }
+        : null,
+    };
+  }
+
+  /** `sessionId` is the checkout session from the success URL
+   * ({CHECKOUT_SESSION_ID}): it sends the sync straight to the checkout that
+   * was paid, not to whichever customer the team resolves to first
+   * (crochet_patterns-eq11). */
+  async successSync(params: { sessionId?: string | null; productSlug?: string | null } = {}): Promise<CachedSubscriptionState | null> {
     const url = `${this.config.apiBaseUrl}/billing/success-sync/`;
+    const body: Record<string, string> = {};
+    if (params.sessionId) body.session_id = params.sessionId;
+    if (params.productSlug) body.product_slug = params.productSlug;
     const resp = await this.fetcher(url, {
       method: "POST",
       headers: this.headers,
+      ...(Object.keys(body).length > 0 && { body: JSON.stringify(body) }),
     });
     if (resp.status === 404) {
       return null;

package/src/utils/format.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Price and feature-label formatting shared by every plan card
+ * (crochet_patterns-34n7).
+ */
+import { describe, it, expect } from "vitest";
+import { formatPrice, formatFeatureLabel } from "./format";
+
+describe("formatPrice", () => {
+  it("keeps the cents: 2.99 is $2.99, not $2", () => {
+    expect(formatPrice("2.99")).toBe("$2.99");
+  });
+
+  it("drops .00 on whole amounts", () => {
+    expect(formatPrice("9.00")).toBe("$9");
+    expect(formatPrice("29.00")).toBe("$29");
+    expect(formatPrice("199.00")).toBe("$199");
+  });
+
+  it("pads a single cent digit", () => {
+    expect(formatPrice("2.5")).toBe("$2.50");
+  });
+
+  it("accepts numbers and other currencies", () => {
+    expect(formatPrice(2.42)).toBe("$2.42");
+    expect(formatPrice("10.00", "EUR")).toBe("€10");
+  });
+
+  it("treats junk as zero rather than NaN", () => {
+    expect(formatPrice("")).toBe("$0");
+  });
+});
+
+describe("formatFeatureLabel", () => {
+  it("keeps acronyms capitalised in a capped allowance", () => {
+    expect(formatFeatureLabel({ key: "ai_designs_per_month", name: "AI designs per month", value: 3 }))
+      .toBe("Up to 3 AI designs per month");
+  });
+
+  it("does not say per month for an unlimited allowance", () => {
+    expect(formatFeatureLabel({ key: "patterns_per_month", name: "Saved patterns per month", value: -1 }))
+      .toBe("Unlimited saved patterns");
+    expect(formatFeatureLabel({ key: "patterns_per_month", name: "AI designs per month", value: -1 }))
+      .toBe("Unlimited AI designs");
+  });
+
+  it("prefers limit over value", () => {
+    expect(formatFeatureLabel({ key: "seats", name: "Team seats", value: 1, limit: 5 }))
+      .toBe("Up to 5 team seats");
+  });
+
+  it("leaves capabilities and string values as their name", () => {
+    expect(formatFeatureLabel({ key: "pdf_export", name: "Print-ready PDF export", value: true }))
+      .toBe("Print-ready PDF export");
+    expect(formatFeatureLabel({ key: "projects", name: "Projects", value: "Unlimited" }))
+      .toBe("Projects");
+  });
+});

package/src/utils/format.ts

@@ -0,0 +1,54 @@
+/**
+ * Display formatting shared by every plan card, so a price or a feature line
+ * reads the same on /pricing, the billing settings page and the upgrade modal
+ * (crochet_patterns-34n7).
+ */
+import type { OfferFeature } from "../types";
+
+/**
+ * "$2.99", "$9", "€10". Cents are kept when there are any and dropped when
+ * the amount is whole — truncating with Math.floor turned $2.99 into $2.
+ */
+export function formatPrice(amount: string | number, currency = "USD"): string {
+  const n = typeof amount === "number" ? amount : parseFloat(amount);
+  const value = Number.isFinite(n) ? n : 0;
+  const whole = Math.abs(value - Math.round(value)) < 0.005;
+  try {
+    return new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: currency || "USD",
+      minimumFractionDigits: whole ? 0 : 2,
+      maximumFractionDigits: whole ? 0 : 2,
+    }).format(value);
+  } catch {
+    return `$${whole ? Math.round(value) : value.toFixed(2)}`;
+  }
+}
+
+/** Lower-case the first letter for mid-sentence use, unless the first word is
+ * an acronym ("AI designs" stays "AI designs", "Team seats" → "team seats"). */
+function midSentence(name: string): string {
+  const firstWord = name.split(/\s+/)[0] ?? "";
+  if ((firstWord.match(/[A-Z]/g) ?? []).length >= 2) return name;
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+/** "Saved patterns per month" → "Saved patterns": an unlimited allowance has
+ * no period. */
+function withoutPeriod(name: string): string {
+  return name.replace(/\s+(per|a|each|\/)\s*(day|week|month|year)$/i, "");
+}
+
+/**
+ * The line a plan card shows for one feature. Numeric allowances read as
+ * "Up to 3 AI designs per month" / "Unlimited saved patterns"; capabilities
+ * and string values are shown by name. Callers decide what to do with a
+ * feature whose value is `false`.
+ */
+export function formatFeatureLabel(feature: OfferFeature): string {
+  const { name, value, limit } = feature;
+  const n = typeof limit === "number" ? limit : typeof value === "number" ? value : null;
+  if (n === -1) return `Unlimited ${midSentence(withoutPeriod(name))}`;
+  if (n !== null && n > 0) return `Up to ${n} ${midSentence(name)}`;
+  return name;
+}