@startsimpli/billing 0.4.32 → 0.4.34

package/src/credits/copy.ts

@@ -0,0 +1,96 @@
+/**
+ * Every customer-facing string of the credit-pack UI. The app owns wording
+ * (what a credit is called, its brand voice); these defaults are neutral.
+ * Prices and pack sizes are NOT here: they come from the offers.
+ */
+export interface CreditsCopy {
+  badge: (n: number) => string;
+  badgeLabel: (n: number) => string;
+  sectionTitle: string;
+  sectionIntro: string;
+  loading: string;
+  loadError: string;
+  retry: string;
+  packName: (credits: number) => string;
+  perCredit: (price: string) => string;
+  save: (pct: number) => string;
+  featured: string;
+  buy: (name: string) => string;
+  buying: string;
+  secure: string;
+  historyTitle: string;
+  historyEmpty: string;
+  /** Label per history entry type (grant, reserve, commit, release, refund, expire, adjust). */
+  entry: Record<string, string>;
+  successTitle: string;
+  successPending: string;
+  successDone: (granted: number | null, balance: number) => string;
+  successStillPending: string;
+  successCheckAgain: string;
+  successMissingSession: string;
+  successSyncError: string;
+  /** Primary action on the success page (e.g. "Make a design"). */
+  continueLabel: string;
+  seeBilling: string;
+  cancelledTitle: string;
+  cancelledBody: string;
+  tryAgain: string;
+  confirmTitle: string;
+  confirmBody: (balance: number) => string;
+  confirmUse: string;
+  confirmCancel: string;
+  outTitle: string;
+  outBody: string;
+  planAllowanceUsed: string;
+}
+
+const plural = (n: number, one: string, many: string) => (n === 1 ? one : many);
+
+export const defaultCreditsCopy: CreditsCopy = {
+  badge: (n) => `${n} ${plural(n, "credit", "credits")}`,
+  badgeLabel: (n) => `You have ${n} ${plural(n, "credit", "credits")}`,
+  sectionTitle: "Credits",
+  sectionIntro: "Buy credits to use when your plan's allowance runs out. Credits never expire.",
+  loading: "Loading your credits…",
+  loadError: "We couldn’t load your credits.",
+  retry: "Try again",
+  packName: (c) => `${c} ${plural(c, "credit", "credits")}`,
+  perCredit: (p) => `${p} each`,
+  save: (pct) => `Save ${pct}%`,
+  featured: "Best value",
+  buy: (name) => `Buy ${name}`,
+  buying: "Opening checkout…",
+  secure: "Secure checkout by Stripe.",
+  historyTitle: "Purchases and use",
+  historyEmpty: "Nothing yet. When you buy or use a credit it shows up here.",
+  entry: {
+    grant: "Bought",
+    reserve: "Used",
+    commit: "Used",
+    release: "Returned",
+    refund: "Refunded",
+    expire: "Expired",
+    adjust: "Adjustment",
+  },
+  successTitle: "Thank you",
+  successPending: "Adding your credits…",
+  successDone: (_g, balance) => `Your credits are ready. You now have ${balance}.`,
+  successStillPending: "Your payment went through, and your credits are still being added. This can take a minute.",
+  successCheckAgain: "Check again",
+  successMissingSession: "We couldn’t find a checkout to confirm. If you just paid, your credits will appear on the billing page shortly.",
+  successSyncError: "We couldn’t confirm your payment just yet. Your card was not charged twice; check again in a moment.",
+  continueLabel: "Continue",
+  seeBilling: "Back to billing",
+  cancelledTitle: "Checkout cancelled",
+  cancelledBody: "No charge was made. Your credits are unchanged.",
+  tryAgain: "Choose a pack",
+  confirmTitle: "Use a credit?",
+  confirmBody: (b) => `This uses 1 credit. You have ${b}.`,
+  confirmUse: "Use a credit",
+  confirmCancel: "Not now",
+  outTitle: "You’re out of credits",
+  outBody: "Buy a pack to continue.",
+  planAllowanceUsed: "Your plan’s allowance for this month is used. You can use a credit instead.",
+};
+
+export const withCreditsCopy = (copy?: Partial<CreditsCopy>): CreditsCopy => ({ ...defaultCreditsCopy, ...copy });

package/src/credits/credits.test.tsx

@@ -0,0 +1,75 @@
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { CreditsCancelled, CreditsPanel, CreditsSuccess, UseCreditPrompt, type CreditsView } from "./index";
+
+const offer = (over = {}) => ({ id: "o1", credits: 5, price: "8.00", compareAt: "10.00", currency: "usd", featured: true, ...over }) as never;
+const view = (over: Partial<CreditsView> = {}): CreditsView => ({
+  status: "ready", balance: 3, offers: [offer()], history: [], error: null, buying: null,
+  refresh: vi.fn(async () => {}), buy: vi.fn(async () => {}), sync: vi.fn(async () => ({ granted: true, balance: 7 })), ...over,
+});
+
+describe("CreditsPanel", () => {
+  it("renders nothing while disabled", () => {
+    const { container } = render(<CreditsPanel credits={view({ status: "disabled" })} />);
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("shows balance, price, saving and buys the clicked pack with injected copy", () => {
+    const credits = view();
+    render(<CreditsPanel credits={credits} copy={{ packName: (n) => `${n} pattern credits`, badge: (n) => `${n} pattern credits` }} />);
+    expect(screen.getByText("3 pattern credits")).toBeTruthy();
+    expect(screen.getByText("$8.00")).toBeTruthy();
+    expect(screen.getByText("Save 20%")).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "Buy 5 pattern credits" }));
+    expect(credits.buy).toHaveBeenCalledWith("o1");
+  });
+
+  it("offers a retry on error", () => {
+    const credits = view({ status: "error" });
+    render(<CreditsPanel credits={credits} />);
+    fireEvent.click(screen.getByRole("button", { name: "Try again" }));
+    expect(credits.refresh).toHaveBeenCalled();
+  });
+});
+
+describe("UseCreditPrompt", () => {
+  it("confirms with a balance, sells packs without one", () => {
+    const onUse = vi.fn();
+    const { rerender } = render(<UseCreditPrompt balance={2} offers={[offer()]} buying={null} error={null} onUse={onUse} onBuy={vi.fn()} onCancel={vi.fn()} />);
+    fireEvent.click(screen.getByRole("button", { name: "Use a credit" }));
+    expect(onUse).toHaveBeenCalled();
+    rerender(<UseCreditPrompt balance={0} offers={[offer()]} buying={null} error={null} onUse={onUse} onBuy={vi.fn()} onCancel={vi.fn()} />);
+    expect(screen.getByText("You’re out of credits")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Buy 5 credits" })).toBeTruthy();
+  });
+});
+
+describe("CreditsSuccess / CreditsCancelled", () => {
+  it("syncs the session once and reports the balance", async () => {
+    const credits = view();
+    render(<CreditsSuccess credits={credits} sessionId="cs_1" continueHref="/go" billingHref="/b" />);
+    await waitFor(() => expect(screen.getByText("Your credits are ready. You now have 7.")).toBeTruthy());
+    expect(credits.sync).toHaveBeenCalledTimes(1);
+    expect(screen.getByText("Continue").getAttribute("href")).toBe("/go");
+  });
+
+  it("says so when there is no session and never syncs", () => {
+    const credits = view();
+    render(<CreditsSuccess credits={credits} sessionId={null} continueHref="/go" billingHref="/b" />);
+    expect(screen.getByText(/couldn’t find a checkout/)).toBeTruthy();
+    expect(credits.sync).not.toHaveBeenCalled();
+  });
+
+  it("waits and allows re-check when not granted yet", async () => {
+    const sync = vi.fn(async () => ({ granted: false, balance: 1 }));
+    render(<CreditsSuccess credits={view({ sync })} sessionId="cs_1" continueHref="/go" billingHref="/b" />);
+    fireEvent.click(await screen.findByRole("button", { name: "Check again" }));
+    await waitFor(() => expect(sync).toHaveBeenCalledTimes(2));
+  });
+
+  it("cancelled links back to billing", () => {
+    render(<CreditsCancelled billingHref="/b" />);
+    expect(screen.getByText("Choose a pack").getAttribute("href")).toBe("/b");
+  });
+});

package/src/credits/index.ts

@@ -0,0 +1,13 @@
+export { CreditsPanel } from "./CreditsPanel";
+export type { CreditsPanelProps } from "./CreditsPanel";
+export { CreditPackCard } from "./CreditPackCard";
+export type { CreditPackCardProps } from "./CreditPackCard";
+export { CreditBalanceBadge } from "./CreditBalanceBadge";
+export { CreditHistoryList } from "./CreditHistoryList";
+export { UseCreditPrompt } from "./UseCreditPrompt";
+export type { UseCreditPromptProps } from "./UseCreditPrompt";
+export { CreditsSuccess, CreditsCancelled } from "./CreditsReturn";
+export type { CreditsSuccessProps, CreditsReturnLinks } from "./CreditsReturn";
+export { defaultCreditsCopy, withCreditsCopy } from "./copy";
+export type { CreditsCopy } from "./copy";
+export type { CreditsView } from "./types";

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)
@@ -63,6 +67,7 @@ export { BillingApiClient } from "./utils/api";
 export {
   isPaidSubscription,
   isPayingSubscription,
+  trialLabel,
   isUnlistedOffer,
   getFeatureLimit,
   resolvePlanEntitlement,
@@ -76,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/types/index.ts

@@ -21,6 +21,8 @@ export interface ProductOffer {
   isActive: boolean;
   isFeatured: boolean;
   trialDays: number;
+  /** Charged at checkout to start the trial (cents); 0/absent = a free trial. */
+  trialFeeCents?: number;
   sortOrder: number;
   ctaText: string;
   /** Plan tier shared by an offer's monthly and annual prices ("lite",

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");
+  });
+});