@startsimpli/billing 0.4.33 → 0.4.35

package/src/credits/types.ts

@@ -0,0 +1,17 @@
+import type { PatternCreditHistoryEntry, PatternCreditOffer, PatternCreditsSyncResult } from "@startsimpli/api";
+
+/** The credit state the components render. `usePatternCredits()` from @startsimpli/hooks returns exactly this. */
+export interface CreditsView {
+  status: "loading" | "ready" | "error" | "disabled";
+  balance: number;
+  offers: PatternCreditOffer[];
+  history: PatternCreditHistoryEntry[];
+  error: string | null;
+  /** Offer id whose checkout is opening, else null. */
+  buying: string | null;
+  refresh: () => Promise<void>;
+  buy: (offerId: string) => Promise<void>;
+  sync: (sessionId: string) => Promise<PatternCreditsSyncResult>;
+}
+
+export type { PatternCreditHistoryEntry, PatternCreditOffer };

package/src/hooks/index.ts

@@ -8,3 +8,7 @@ export { useSuccessSync } from "./useSuccessSync";
 export { useUsage, notifyUsageChanged, USAGE_CHANGED_EVENT } from "./useUsage";
 export { usePlanChange } from "./usePlanChange";
 export type { PlanChangeContext, PlanChangeConfirmState, PlanChangeProceed, UsePlanChangeResult } from "./usePlanChange";
+export { useOfferCheckout } from "./useOfferCheckout";
+export type { UseOfferCheckoutOptions } from "./useOfferCheckout";
+export { useAutoCheckout } from "./useAutoCheckout";
+export type { UseAutoCheckoutOptions } from "./useAutoCheckout";

package/src/hooks/useAutoCheckout.test.tsx

@@ -0,0 +1,34 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useAutoCheckout } from "./useAutoCheckout";
+import type { ProductOffer } from "../types";
+
+const offers = [{ slug: "pro" }, { slug: "lite" }] as unknown as ProductOffer[];
+const q = (s: string) => new URLSearchParams(s);
+
+describe("useAutoCheckout", () => {
+  it("starts the requested plan once when signed in and loaded", () => {
+    const select = vi.fn();
+    const { rerender, result } = renderHook((p) => useAutoCheckout(p), {
+      initialProps: { signedIn: true, offers, params: q("checkout=auto&plan=pro"), selectOffer: select },
+    });
+    expect(result.current).toBe(true);
+    expect(select).toHaveBeenCalledTimes(1);
+    expect(select.mock.calls[0][0].slug).toBe("pro");
+    rerender({ signedIn: true, offers: [...offers], params: q("checkout=auto&plan=pro"), selectOffer: select });
+    expect(select).toHaveBeenCalledTimes(1);
+  });
+
+  it("waits for sign-in and for offers, and ignores non-auto urls", () => {
+    const select = vi.fn();
+    const { rerender, result } = renderHook((p) => useAutoCheckout(p), {
+      initialProps: { signedIn: false, offers, params: q("checkout=auto&plan=pro"), selectOffer: select },
+    });
+    expect(select).not.toHaveBeenCalled();
+    rerender({ signedIn: true, offers: undefined, params: q("checkout=auto&plan=pro"), selectOffer: select });
+    expect(select).not.toHaveBeenCalled();
+    rerender({ signedIn: true, offers, params: q("plan=pro"), selectOffer: select });
+    expect(result.current).toBe(false);
+    expect(select).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useAutoCheckout.ts

@@ -0,0 +1,31 @@
+/**
+ * useAutoCheckout — back from sign-up on `?checkout=auto&plan=<slug>`: start
+ * that plan's checkout once, as soon as the person is signed in and the
+ * product's offers are loaded. Never fires twice, never when signed out.
+ */
+
+import { useEffect, useRef } from "react";
+import type { ProductOffer } from "../types";
+import { autoCheckoutOffer } from "../utils/return-urls";
+
+export interface UseAutoCheckoutOptions {
+  signedIn: boolean;
+  /** The product's offers; undefined/empty until loaded (from `useProduct`). */
+  offers: ProductOffer[] | undefined;
+  params: URLSearchParams;
+  /** The same `selectOffer` the plan buttons use (`useOfferCheckout`). */
+  selectOffer: (offer: ProductOffer) => void | Promise<unknown>;
+}
+
+/** Returns whether the URL asked for auto checkout, so the page can explain a signed-out stall. */
+export function useAutoCheckout({ signedIn, offers, params, selectOffer }: UseAutoCheckoutOptions): boolean {
+  const started = useRef(false);
+  useEffect(() => {
+    if (started.current || !signedIn || !offers?.length) return;
+    const offer = autoCheckoutOffer(offers, params);
+    if (!offer) return;
+    started.current = true;
+    void selectOffer(offer);
+  }, [signedIn, offers, params, selectOffer]);
+  return params.get("checkout") === "auto";
+}

package/src/hooks/useOfferCheckout.test.tsx

@@ -0,0 +1,73 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import React from "react";
+import { BillingProvider } from "./BillingProvider";
+import { useOfferCheckout } from "./useOfferCheckout";
+import type { ProductOffer } from "../types";
+
+const offer = (over: Partial<ProductOffer> = {}) =>
+  ({ id: "o1", slug: "pro", name: "Pro", isFree: false, unitPrice: "9", currency: "usd", ...over }) as ProductOffer;
+
+function setup(opts: { authed?: boolean; json?: unknown; ok?: boolean } = {}) {
+  const fetcher = vi.fn().mockResolvedValue({ ok: opts.ok ?? true, json: () => Promise.resolve(opts.json ?? {}) });
+  const navigate = vi.fn();
+  const onSignedOut = vi.fn();
+  const onBeginCheckout = vi.fn();
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <BillingProvider apiBaseUrl="/api/v1" fetcher={fetcher as unknown as typeof fetch}>{children}</BillingProvider>
+  );
+  const hook = renderHook(
+    () =>
+      useOfferCheckout({
+        isAuthenticated: opts.authed ?? true,
+        cancelPath: "/pricing",
+        returnUrl: (p) => `https://app.test${p}`,
+        navigate,
+        onSignedOut,
+        onBeginCheckout,
+      }),
+    { wrapper },
+  );
+  return { ...hook, fetcher, navigate, onSignedOut, onBeginCheckout };
+}
+
+describe("useOfferCheckout", () => {
+  it("signed out: hands the offer to onSignedOut and does not call the server", async () => {
+    const t = setup({ authed: false });
+    let r: unknown;
+    await act(async () => { r = await t.result.current.selectOffer(offer()); });
+    expect(r).toBe("navigating");
+    expect(t.onSignedOut).toHaveBeenCalledWith(expect.objectContaining({ slug: "pro" }));
+    expect(t.fetcher).not.toHaveBeenCalled();
+  });
+
+  it("free offer: enrols and goes to billing success", async () => {
+    const t = setup({ json: { subscriptionId: "s1", status: "active" } });
+    await act(async () => { await t.result.current.selectOffer(offer({ isFree: true })); });
+    expect(t.navigate).toHaveBeenCalledWith("/settings/billing?status=success");
+  });
+
+  it("free offer leaving a paid plan: scheduled", async () => {
+    const t = setup({ json: { subscriptionId: "s1", status: "active", scheduled_downgrade: true } });
+    await act(async () => { await t.result.current.selectOffer(offer({ isFree: true })); });
+    expect(t.navigate).toHaveBeenCalledWith("/settings/billing?status=scheduled");
+  });
+
+  it("paid offer: posts checkout with session placeholder + cancel url, then goes to Stripe", async () => {
+    const t = setup({ json: { sessionId: "cs_1", url: "https://stripe.test/pay" } });
+    await act(async () => { await t.result.current.selectOffer(offer()); });
+    const body = JSON.parse((t.fetcher.mock.calls[0][1] as RequestInit).body as string);
+    expect(body.success_url).toBe("https://app.test/settings/billing?status=success&session_id={CHECKOUT_SESSION_ID}");
+    expect(body.cancel_url).toBe("https://app.test/pricing");
+    expect(t.onBeginCheckout).toHaveBeenCalled();
+    expect(t.navigate).toHaveBeenCalledWith("https://stripe.test/pay");
+  });
+
+  it("a failed checkout shows the error and re-enables the buttons", async () => {
+    const t = setup({ ok: false, json: { detail: "no card" } });
+    await act(async () => { await t.result.current.selectOffer(offer()); });
+    expect(t.navigate).not.toHaveBeenCalled();
+    expect(t.result.current.error).toBeTruthy();
+    expect(t.result.current.loading).toBe(false);
+  });
+});

package/src/hooks/useOfferCheckout.ts

@@ -0,0 +1,82 @@
+/**
+ * useOfferCheckout — what a plan button does, wherever plans are listed
+ * (pricing page, upgrade modal, billing settings):
+ *   signed out  → onSignedOut(offer) (the app sends them to sign up and back)
+ *   free plan   → enrol, then billing ("scheduled" when it ends a paid plan)
+ *   paid plan   → hosted checkout, or an in-place change (afterCheckout)
+ *
+ * Returns "navigating" once the browser is being sent away, so plan buttons
+ * stay disabled until the page unloads. Must be inside a <BillingProvider>.
+ */
+
+import { useCallback, useState } from "react";
+import type { PlanChangePreview, ProductOffer } from "../types";
+import { afterCheckout, withSessionPlaceholder, type CheckoutPaths } from "../utils/checkout-flow";
+import { useCheckout } from "./useCheckout";
+
+export interface UseOfferCheckoutOptions {
+  isAuthenticated: boolean;
+  /** Same-origin path to land on after paying (already through safeNextPath). */
+  nextPath?: string | null;
+  /** Path to come back to when checkout is cancelled. */
+  cancelPath: string;
+  /** Absolute return URL for a path, using the app's public origin. */
+  returnUrl: (path: string) => string;
+  /** Default `window.location.assign`. */
+  navigate?: (url: string) => void;
+  /** Signed out: send the person to sign up and back to this offer. */
+  onSignedOut: (offer: ProductOffer) => void;
+  /** A paid checkout is about to start (analytics). */
+  onBeginCheckout?: (offer: ProductOffer) => void;
+  /** Defaults: /settings/billing[?status=success|scheduled]. */
+  paths?: Partial<CheckoutPaths>;
+}
+
+export function useOfferCheckout(options: UseOfferCheckoutOptions) {
+  const { isAuthenticated, nextPath = null, cancelPath, returnUrl, navigate, onSignedOut, onBeginCheckout } = options;
+  const billingPath = options.paths?.billingPath ?? "/settings/billing";
+  const successPath = options.paths?.successPath ?? `${billingPath}?status=success`;
+  const scheduledPath = options.paths?.scheduledPath ?? `${billingPath}?status=scheduled`;
+  const { checkout, subscribeFree } = useCheckout();
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const selectOffer = useCallback(
+    async (offer: ProductOffer, _preview?: PlanChangePreview | null): Promise<"navigating" | void> => {
+      const go = navigate ?? ((u: string) => window.location.assign(u));
+      if (!isAuthenticated) {
+        onSignedOut(offer);
+        return "navigating";
+      }
+      setError(null);
+      setLoading(true);
+      try {
+        if (offer.isFree) {
+          const result = await subscribeFree(offer.id);
+          go(result?.scheduled_downgrade ? scheduledPath : successPath);
+          return "navigating";
+        }
+        onBeginCheckout?.(offer);
+        const result = await checkout({
+          offerId: offer.id,
+          successUrl: nextPath ? returnUrl(nextPath) : withSessionPlaceholder(returnUrl(successPath)),
+          cancelUrl: returnUrl(cancelPath),
+        });
+        const destination = afterCheckout(result, nextPath, { billingPath, successPath, scheduledPath });
+        if (destination) {
+          go(destination);
+          return "navigating";
+        }
+        setError("Unable to start checkout. Please try again.");
+        setLoading(false);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Something went wrong. Please try again.");
+        setLoading(false);
+      }
+    },
+    [isAuthenticated, nextPath, cancelPath, returnUrl, navigate, onSignedOut, onBeginCheckout,
+      billingPath, successPath, scheduledPath, checkout, subscribeFree],
+  );
+
+  return { selectOffer, error, loading };
+}

package/src/index.ts

@@ -18,12 +18,14 @@ export {
   usePortal,
   useSubscription,
   useSuccessSync,
+  useOfferCheckout,
+  useAutoCheckout,
   useUsage,
   usePlanChange,
   notifyUsageChanged,
   USAGE_CHANGED_EVENT,
 } from "./hooks";
-export type { BillingProviderProps, PlanChangeContext, PlanChangeConfirmState, PlanChangeProceed, UsePlanChangeResult } from "./hooks";
+export type { BillingProviderProps, UseOfferCheckoutOptions, UseAutoCheckoutOptions, PlanChangeContext, PlanChangeConfirmState, PlanChangeProceed, UsePlanChangeResult } from "./hooks";
 
 // Types
 export type {
@@ -42,7 +44,7 @@ export type {
 } from "./types";
 
 // Components
-export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager, PlanGate, CurrentPlanCard, LimitNudge, PlanChangeConfirm, planChangeCopy } from "./components";
+export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager, PlanGate, CurrentPlanCard, LimitNudge, PlanChangeConfirm, planChangeCopy, UsageMeters } from "./components";
 export type {
   PricingPageProps,
   PricingSectionProps,
@@ -54,6 +56,8 @@ export type {
   CurrentPlanCardProps,
   LimitNudgeProps,
   PlanChangeConfirmProps,
+  UsageMetersProps,
+  UsageMetersCopy,
 } from "./components";
 
 // API client (for advanced usage)
@@ -77,5 +81,22 @@ export {
 } from "./utils/plan";
 export type { PlanEntitlement, ResolvePlanEntitlementOptions, UsageWindow, CurrentPlanState, PlanDirection } from "./utils/plan";
 export { formatPrice, formatFeatureLabel } from "./utils/format";
+export { afterCheckout, checkoutSessionIdFrom, safeNextPath, withSessionPlaceholder } from "./utils/checkout-flow";
+export type { CheckoutPaths } from "./utils/checkout-flow";
 export { groupOffersByTier, offersForInterval, hasIntervalChoice, annualSavings, tierOffer } from "./utils/tiers";
 export type { BillingInterval, OfferTier } from "./utils/tiers";
+
+// Return-URL / hand-off helpers, credit-pack math, usage meters
+export {
+  autoCheckoutOffer,
+  billingReturnUrl,
+  creditReturnUrls,
+  creditSessionFrom,
+  signUpReturnUrl,
+  statusMessageFrom,
+} from "./utils/return-urls";
+export type { CreditReturnPaths, PlanStatusMessage } from "./utils/return-urls";
+export { formatPackPrice, pricePerCredit, savingsPercent } from "./utils/credit-math";
+export type { PackPrice } from "./utils/credit-math";
+export { meterRows } from "./utils/usage-meters";
+export type { MeterRow, MeterState } from "./utils/usage-meters";

package/src/utils/checkout-flow.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { afterCheckout, checkoutSessionIdFrom, safeNextPath, withSessionPlaceholder } from "./checkout-flow";
+
+const PATHS = { billingPath: "/settings/billing", successPath: "/settings/billing?status=success", scheduledPath: "/settings/billing?status=scheduled" };
+
+describe("afterCheckout", () => {
+  it("nothing back is no destination", () => {
+    expect(afterCheckout(null, null, PATHS)).toBeNull();
+  });
+  it("a new checkout goes to its page", () => {
+    expect(afterCheckout({ sessionId: "cs_1", url: "https://stripe.test/x" }, null, PATHS)).toBe("https://stripe.test/x");
+  });
+  it("a change at period end says scheduled, not activated", () => {
+    expect(afterCheckout({ sessionId: "", url: "", plan_change: "at_period_end" }, null, PATHS)).toBe(PATHS.scheduledPath);
+  });
+  it("an unpaid upgrade goes to the invoice, else billing success", () => {
+    expect(afterCheckout({ sessionId: "", url: "https://inv", planChange: "payment_required" }, null, PATHS)).toBe("https://inv");
+    expect(afterCheckout({ sessionId: "", url: "", plan_change: "payment_required" }, null, PATHS)).toBe(PATHS.successPath);
+  });
+  it("a cancelled pending change goes to plain billing", () => {
+    expect(afterCheckout({ sessionId: "", url: "", plan_change: "pending_change_cancelled" }, null, PATHS)).toBe("/settings/billing");
+  });
+  it("an immediate in-place change goes to next, else billing success", () => {
+    expect(afterCheckout({ sessionId: "", url: "", plan_change: "immediate" }, "/create", PATHS)).toBe("/create");
+    expect(afterCheckout({ sessionId: "", url: "", plan_change: "immediate" }, null, PATHS)).toBe(PATHS.successPath);
+  });
+});
+
+describe("checkoutSessionIdFrom", () => {
+  it("accepts a real Stripe session id only", () => {
+    expect(checkoutSessionIdFrom("cs_test_a1B2")).toBe("cs_test_a1B2");
+    expect(checkoutSessionIdFrom("{CHECKOUT_SESSION_ID}")).toBeNull();
+    expect(checkoutSessionIdFrom(null)).toBeNull();
+    expect(checkoutSessionIdFrom("")).toBeNull();
+  });
+});
+
+describe("safeNextPath", () => {
+  it("keeps same-origin paths", () => {
+    expect(safeNextPath("/create?x=1")).toBe("/create?x=1");
+  });
+  it("drops anything that could leave the site", () => {
+    for (const bad of ["https://evil.test", "//evil.test", "/\\evil.test", "javascript:alert(1)", "create", "", null, undefined]) {
+      expect(safeNextPath(bad as string | null | undefined)).toBeNull();
+    }
+  });
+});
+
+describe("withSessionPlaceholder", () => {
+  it("appends Stripe's placeholder after the query, braces unencoded", () => {
+    expect(withSessionPlaceholder("https://app.test/settings/billing?status=success")).toBe(
+      "https://app.test/settings/billing?status=success&session_id={CHECKOUT_SESSION_ID}",
+    );
+    expect(withSessionPlaceholder("https://app.test/x")).toBe("https://app.test/x?session_id={CHECKOUT_SESSION_ID}");
+  });
+});

package/src/utils/checkout-flow.ts

@@ -0,0 +1,55 @@
+/**
+ * Where the browser goes after a checkout call, and the small guards around it.
+ * Pure: no React, no window. Used by useOfferCheckout.
+ */
+
+import type { CheckoutResult } from "../types";
+
+export interface CheckoutPaths {
+  /** The billing settings page, e.g. "/settings/billing". */
+  billingPath: string;
+  /** Billing after paying, e.g. "/settings/billing?status=success". */
+  successPath: string;
+  /** Billing after a change that takes effect at period end. */
+  scheduledPath: string;
+}
+
+/**
+ * Where the browser goes after a checkout call, from what the backend did:
+ * a new checkout goes to its page; a plan already paid for changed in place
+ * goes to `next` (or billing success); a change at period end says "scheduled",
+ * not "activated"; an unpaid upgrade goes to the invoice.
+ */
+export function afterCheckout(
+  result: CheckoutResult | null | undefined,
+  nextPath: string | null,
+  paths: CheckoutPaths,
+): string | null {
+  if (!result) return null;
+  const change = result.plan_change ?? result.planChange;
+  if (!change) return result.url || null;
+  if (change === "at_period_end") return paths.scheduledPath;
+  if (change === "payment_required") return result.url || paths.successPath;
+  if (change === "pending_change_cancelled") return paths.billingPath;
+  return nextPath ?? paths.successPath;
+}
+
+/** A real Stripe checkout session id, not the unfilled {CHECKOUT_SESSION_ID}
+ * an in-place plan change returns verbatim. */
+export function checkoutSessionIdFrom(raw: string | null | undefined): string | null {
+  return raw && /^cs_[A-Za-z0-9_]+$/.test(raw) ? raw : null;
+}
+
+/** A same-origin path to land on after paying; anything else is dropped so a
+ * `?next=` can never be an open redirect. */
+export function safeNextPath(raw: string | null | undefined): string | null {
+  if (!raw || !raw.startsWith("/")) return null;
+  if (raw.startsWith("//") || raw.startsWith("/\\")) return null;
+  return raw;
+}
+
+/** Stripe fills {CHECKOUT_SESSION_ID} in; appended after building the URL so the
+ * braces are not percent-encoded, and success-sync reads that exact checkout. */
+export function withSessionPlaceholder(url: string): string {
+  return `${url}${url.includes("?") ? "&" : "?"}session_id={CHECKOUT_SESSION_ID}`;
+}

package/src/utils/credit-math.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { formatPackPrice, pricePerCredit, savingsPercent } from "./credit-math";
+
+describe("credit math", () => {
+  it("formats with cents always", () => {
+    expect(formatPackPrice("19", "usd")).toBe("$19.00");
+    expect(formatPackPrice("abc", "usd")).toBe("abc");
+  });
+  it("computes saving only when compareAt is higher", () => {
+    expect(savingsPercent({ price: "8", compareAt: "10" })).toBe(20);
+    expect(savingsPercent({ price: "10", compareAt: "10" })).toBeNull();
+    expect(savingsPercent({ price: "10", compareAt: null })).toBeNull();
+  });
+  it("divides price per credit", () => {
+    expect(pricePerCredit({ price: "10", credits: 4 })).toBe("2.50");
+    expect(pricePerCredit({ price: "10", credits: 0 })).toBe("10");
+  });
+});

package/src/utils/credit-math.ts

@@ -0,0 +1,32 @@
+/** Price math for one-time credit packs. Pure. */
+
+export interface PackPrice {
+  price: string;
+  compareAt?: string | null;
+  credits: number;
+}
+
+/** "$19.99" from a decimal-string price and its currency; cents always shown. */
+export function formatPackPrice(amount: string, currency: string): string {
+  const n = Number(amount);
+  if (!Number.isFinite(n)) return amount;
+  try {
+    return new Intl.NumberFormat("en-US", { style: "currency", currency: (currency || "USD").toUpperCase() }).format(n);
+  } catch {
+    return `${n.toFixed(2)} ${currency}`;
+  }
+}
+
+/** Whole-percent saving of `price` against a struck-through `compareAt`, or null when there is none. */
+export function savingsPercent(offer: Pick<PackPrice, "price" | "compareAt">): number | null {
+  const price = Number(offer.price);
+  const was = Number(offer.compareAt);
+  if (!offer.compareAt || !Number.isFinite(price) || !Number.isFinite(was) || was <= price || was <= 0) return null;
+  return Math.round((1 - price / was) * 100);
+}
+
+/** Price of one credit in this pack (decimal string, 2 places). */
+export function pricePerCredit(offer: Pick<PackPrice, "price" | "credits">): string {
+  const total = Number(offer.price);
+  return offer.credits > 0 && Number.isFinite(total) ? (total / offer.credits).toFixed(2) : offer.price;
+}

package/src/utils/return-urls.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import {
+  autoCheckoutOffer, billingReturnUrl, creditReturnUrls, creditSessionFrom, signUpReturnUrl, statusMessageFrom,
+} from "./return-urls";
+import type { ProductOffer } from "../types";
+
+const offers = [{ slug: "pro" }, { slug: "lite" }] as unknown as ProductOffer[];
+
+describe("return urls", () => {
+  it("prefers the public origin, trims slashes and adds a leading slash", () => {
+    expect(billingReturnUrl("/x", "http://localhost:3000", "https://app.example/")).toBe("https://app.example/x");
+    expect(billingReturnUrl("x", "http://localhost:3000")).toBe("http://localhost:3000/x");
+  });
+  it("builds the sign-up return with plan, auto and optional next", () => {
+    expect(signUpReturnUrl("https://a.b", "pro", null)).toBe("https://a.b/pricing?plan=pro&checkout=auto");
+    expect(signUpReturnUrl("https://a.b", "pro", "/go", "/plans")).toBe("https://a.b/plans?plan=pro&checkout=auto&next=%2Fgo");
+  });
+  it("picks the auto-checkout offer only when asked and known", () => {
+    expect(autoCheckoutOffer(offers, new URLSearchParams("checkout=auto&plan=lite"))?.slug).toBe("lite");
+    expect(autoCheckoutOffer(offers, new URLSearchParams("plan=lite"))).toBeNull();
+    expect(autoCheckoutOffer(offers, new URLSearchParams("checkout=auto&plan=zzz"))).toBeNull();
+    expect(autoCheckoutOffer(offers, new URLSearchParams("checkout=auto"))).toBeNull();
+  });
+  it("credit return urls carry the session placeholder, unencoded", () => {
+    const abs = (p: string) => `https://a.b${p}`;
+    expect(creditReturnUrls(abs)).toEqual({
+      successUrl: "https://a.b/settings/billing/credits/success?session_id={CHECKOUT_SESSION_ID}",
+      cancelUrl: "https://a.b/settings/billing/credits/cancelled",
+    });
+    expect(creditReturnUrls(abs, { successPath: "/ok", cancelledPath: "/no" }).cancelUrl).toBe("https://a.b/no");
+  });
+  it("reads only real session ids and known statuses", () => {
+    expect(creditSessionFrom(new URLSearchParams("session_id=cs_test_1"))).toBe("cs_test_1");
+    expect(creditSessionFrom(new URLSearchParams("session_id={CHECKOUT_SESSION_ID}"))).toBeNull();
+    expect(statusMessageFrom(new URLSearchParams("status=scheduled"))).toBe("scheduled");
+    expect(statusMessageFrom(new URLSearchParams("status=hax"))).toBeNull();
+  });
+});

package/src/utils/return-urls.ts

@@ -0,0 +1,74 @@
+/**
+ * Return-URL and hand-off helpers around checkout: where Stripe (or central
+ * sign-up) sends the browser back to, and how a pricing page picks up an
+ * "auto checkout" request. Pure: no React, no window.
+ */
+
+import type { ProductOffer } from "../types";
+import { checkoutSessionIdFrom, withSessionPlaceholder } from "./checkout-flow";
+
+/**
+ * The absolute URL Stripe (or central auth) sends the browser back to. The
+ * configured public origin wins so a build served behind a tunnel or proxy
+ * still returns to the public site; else the origin the page is on.
+ */
+export function billingReturnUrl(path: string, currentOrigin?: string, publicOrigin?: string): string {
+  const origin = (publicOrigin || currentOrigin || "").replace(/\/+$/, "");
+  const normalized = path.startsWith("/") ? path : `/${path}`;
+  return `${origin}${normalized}`;
+}
+
+/**
+ * Where sign-up sends the person back to: the pricing page with the plan they
+ * picked, so checkout starts without a second click.
+ */
+export function signUpReturnUrl(
+  origin: string,
+  planSlug: string,
+  nextPath: string | null,
+  pricingPath = "/pricing",
+): string {
+  const q = new URLSearchParams({ plan: planSlug, checkout: "auto" });
+  if (nextPath) q.set("next", nextPath);
+  return `${origin}${pricingPath}?${q.toString()}`;
+}
+
+/** The offer to check out straight away: only when ?checkout=auto&plan=<slug>. */
+export function autoCheckoutOffer(offers: ProductOffer[], params: URLSearchParams): ProductOffer | null {
+  if (params.get("checkout") !== "auto") return null;
+  const plan = params.get("plan");
+  if (!plan) return null;
+  return offers.find((o) => o.slug === plan) ?? null;
+}
+
+export interface CreditReturnPaths {
+  successPath: string;
+  cancelledPath: string;
+}
+
+/** Where Stripe sends the browser after a credit pack: the return pages. */
+export function creditReturnUrls(
+  absolute: (path: string) => string,
+  paths: CreditReturnPaths = {
+    successPath: "/settings/billing/credits/success",
+    cancelledPath: "/settings/billing/credits/cancelled",
+  },
+): { successUrl: string; cancelUrl: string } {
+  return {
+    successUrl: withSessionPlaceholder(absolute(paths.successPath)),
+    cancelUrl: absolute(paths.cancelledPath),
+  };
+}
+
+/** The Stripe session to sync from the success page's query, or null. */
+export function creditSessionFrom(params: URLSearchParams): string | null {
+  return checkoutSessionIdFrom(params.get("session_id"));
+}
+
+export type PlanStatusMessage = "success" | "cancelled" | "scheduled";
+
+/** ?status= on billing settings after a plan checkout or change. */
+export function statusMessageFrom(params: URLSearchParams): PlanStatusMessage | null {
+  const s = params.get("status");
+  return s === "success" || s === "cancelled" || s === "scheduled" ? s : null;
+}

package/src/utils/usage-meters.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { meterRows } from "./usage-meters";
+
+describe("meterRows", () => {
+  it("skips unlimited and flags, states by fill, humanizes missing labels", () => {
+    const rows = meterRows({
+      ai_designs: { used: 2, limit: 10 },
+      near: { used: 8, limit: 10 },
+      full: { used: 12, limit: 10 },
+      unlimited: { used: 5, limit: null },
+      zero: { used: 0, limit: 0 },
+    }, { near: "Near" });
+    expect(rows.map((r) => [r.key, r.state, r.label, r.left])).toEqual([
+      ["ai_designs", "ok", "Ai designs", 8],
+      ["near", "approaching", "Near", 2],
+      ["full", "at-cap", "Full", 0],
+      ["zero", "at-cap", "Zero", 0],
+    ]);
+  });
+});

package/src/utils/usage-meters.ts

@@ -0,0 +1,35 @@
+import type { UsageMap } from "../types";
+
+export type MeterState = "ok" | "approaching" | "at-cap";
+
+export interface MeterRow {
+  key: string;
+  label: string;
+  used: number;
+  limit: number;
+  pct: number;
+  left: number;
+  state: MeterState;
+}
+
+const humanize = (key: string): string => {
+  const words = key.replace(/[_-]+/g, " ").trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+};
+
+/**
+ * One meter per feature with a real numeric cap. Unlimited (-1 / null) and
+ * flags render nothing: a paying person is not shown a bar for what they have
+ * no cap on. Labels come from the plan's own feature names.
+ */
+export function meterRows(usage: UsageMap, labels: Record<string, string> = {}): MeterRow[] {
+  return Object.entries(usage ?? {})
+    .filter(([, u]) => u && typeof u.limit === "number" && u.limit >= 0)
+    .map(([key, u]) => {
+      const limit = u.limit as number;
+      const used = Math.max(0, u.used);
+      const pct = limit === 0 ? 100 : Math.min(100, Math.round((used / limit) * 100));
+      const state: MeterState = used >= limit ? "at-cap" : pct >= 80 ? "approaching" : "ok";
+      return { key, label: labels[key] ?? humanize(key), used, limit, pct, left: Math.max(0, limit - used), state };
+    });
+}