@startsimpli/billing 0.4.33 → 0.4.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.33",
+  "version": "0.4.35",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "license": "MIT",
   "homepage": "https://startsimpli.com",
@@ -19,6 +19,7 @@
     "./client": "./src/index.ts",
     "./server": "./src/server/index.ts",
     "./plan": "./src/utils/plan.ts",
+    "./credits": "./src/credits/index.ts",
     "./types": "./src/types/index.ts",
     "./mock": "./src/mock/index.ts"
   },
@@ -33,7 +34,17 @@
   "peerDependencies": {
     "next": ">=14.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@startsimpli/api": "^0.5.73",
+    "@startsimpli/ui": "^0.4.176"
+  },
+  "peerDependenciesMeta": {
+    "@startsimpli/api": {
+      "optional": true
+    },
+    "@startsimpli/ui": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
@@ -49,7 +60,9 @@
     "react-dom": "^19.2.5",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.5",
+    "@startsimpli/api": "0.5.73",
+    "@startsimpli/ui": "0.4.176"
   },
   "keywords": [
     "billing",

package/src/components/UsageMeters.test.tsx

@@ -0,0 +1,27 @@
+import { render, screen } from "@testing-library/react";
+import React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { UsageMeters } from "./UsageMeters";
+
+const state = vi.hoisted(() => ({ usage: {} as Record<string, { used: number; limit: number | null }> }));
+vi.mock("../hooks/useUsage", () => ({ useUsage: () => ({ usage: state.usage, refetch: vi.fn() }) }));
+vi.mock("../hooks/useSubscription", () => ({
+  useSubscription: () => ({ subscription: { offer: { features: [{ key: "designs", name: "Designs" }] } } }),
+}));
+
+describe("UsageMeters", () => {
+  it("renders nothing without capped features", () => {
+    state.usage = { x: { used: 1, limit: null } };
+    const { container } = render(<UsageMeters productSlug="p" />);
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("renders a meter per capped feature with the plan's label and a state note", () => {
+    state.usage = { designs: { used: 9, limit: 10 }, extra: { used: 3, limit: 3 } };
+    render(<UsageMeters productSlug="p" copy={{ atCap: "Maxed" }} />);
+    expect(screen.getByTestId("meter-designs").getAttribute("data-state")).toBe("approaching");
+    expect(screen.getByText("Designs")).toBeTruthy();
+    expect(screen.getByText("1 of 10 left")).toBeTruthy();
+    expect(screen.getByText("Maxed")).toBeTruthy();
+  });
+});

package/src/components/UsageMeters.tsx

@@ -0,0 +1,85 @@
+"use client";
+
+import { useEffect, useMemo, useRef } from "react";
+import { useSubscription } from "../hooks/useSubscription";
+import { useUsage } from "../hooks/useUsage";
+import { meterRows, type MeterState } from "../utils/usage-meters";
+
+export interface UsageMetersCopy {
+  /** Shown on a meter at 80%+ of its cap. */
+  approaching: string;
+  /** Shown on a meter at its cap. */
+  atCap: string;
+  /** "{left} of {limit} left" line. */
+  left: (left: number, limit: number) => string;
+}
+
+const DEFAULT_COPY: UsageMetersCopy = {
+  approaching: "Almost used up",
+  atCap: "Limit reached",
+  left: (left, limit) => `${left} of ${limit} left`,
+};
+
+const TONE: Record<MeterState, { box: string; bar: string }> = {
+  ok: { box: "border-border bg-card", bar: "bg-primary" },
+  approaching: { box: "border-amber-300 bg-amber-50", bar: "bg-amber-500" },
+  "at-cap": { box: "border-red-300 bg-red-50", bar: "bg-red-500" },
+};
+
+/** Re-reads after checkout: the first read can predate the new plan. */
+const AFTER_CHECKOUT_REFETCH_MS = 2000;
+const AFTER_CHECKOUT_REFETCH_TRIES = 5;
+
+export interface UsageMetersProps {
+  productSlug: string;
+  /** Back from checkout: ask again a few times while usage still reads empty. */
+  afterCheckout?: boolean;
+  copy?: Partial<UsageMetersCopy>;
+}
+
+/** One meter per capped feature of the person's plan; nothing for unlimited ones. */
+export function UsageMeters({ productSlug, afterCheckout = false, copy }: UsageMetersProps) {
+  const text = { ...DEFAULT_COPY, ...copy };
+  const { usage, refetch } = useUsage(productSlug);
+  const { subscription } = useSubscription(productSlug);
+
+  const left = useRef(AFTER_CHECKOUT_REFETCH_TRIES);
+  const stillEmpty = Object.keys(usage).length === 0;
+  useEffect(() => {
+    if (!afterCheckout || !stillEmpty || left.current <= 0) return;
+    const t = setTimeout(() => {
+      left.current -= 1;
+      refetch();
+    }, AFTER_CHECKOUT_REFETCH_MS);
+    return () => clearTimeout(t);
+  }, [afterCheckout, stillEmpty, refetch]);
+
+  const labels = useMemo(() => {
+    const map: Record<string, string> = {};
+    for (const f of subscription?.offer?.features ?? []) map[f.key] = f.name;
+    return map;
+  }, [subscription]);
+  const rows = meterRows(usage, labels);
+  if (rows.length === 0) return null;
+
+  return (
+    <div className="mb-6 space-y-3" data-testid="usage-meters">
+      {rows.map((r) => {
+        const tone = TONE[r.state];
+        const note = r.state === "at-cap" ? text.atCap : r.state === "approaching" ? text.approaching : null;
+        return (
+          <div key={r.key} data-testid={`meter-${r.key}`} data-state={r.state} className={`rounded-lg border p-4 ${tone.box}`}>
+            <div className="mb-1.5 flex items-center justify-between gap-3">
+              <h3 className="text-sm font-semibold">{r.label}</h3>
+              {note && <span className="text-xs font-medium">{note}</span>}
+            </div>
+            <p className="mb-2 text-sm text-muted-foreground tabular-nums">{text.left(r.left, r.limit)}</p>
+            <div className="h-2 w-full rounded-full bg-muted" aria-hidden="true">
+              <div className={`h-2 rounded-full transition-all ${tone.bar}`} style={{ width: `${Math.max(r.pct, 3)}%` }} />
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/index.ts

@@ -18,3 +18,5 @@ export { LimitNudge } from "./LimitNudge";
 export type { LimitNudgeProps } from "./LimitNudge";
 export { PlanChangeConfirm, planChangeCopy } from "./PlanChangeConfirm";
 export type { PlanChangeConfirmProps } from "./PlanChangeConfirm";
+export { UsageMeters } from "./UsageMeters";
+export type { UsageMetersProps, UsageMetersCopy } from "./UsageMeters";

package/src/credits/CreditBalanceBadge.tsx

@@ -0,0 +1,13 @@
+import type { CreditsCopy } from "./copy";
+
+/** The balance, read out in full by screen readers. */
+export function CreditBalanceBadge({ balance, copy, className = "" }: { balance: number; copy: CreditsCopy; className?: string }) {
+  return (
+    <span
+      aria-label={copy.badgeLabel(balance)}
+      className={`inline-flex items-center rounded-full bg-green-100 px-3 py-1 text-sm font-medium text-green-800 ${className}`}
+    >
+      <span aria-hidden="true">{copy.badge(balance)}</span>
+    </span>
+  );
+}

package/src/credits/CreditHistoryList.tsx

@@ -0,0 +1,32 @@
+import type { CreditsCopy } from "./copy";
+import type { PatternCreditHistoryEntry } from "./types";
+
+const when = (iso: string) => {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+};
+
+/** Purchases and use, in the order given (newest first from the server). */
+export function CreditHistoryList({ history, copy }: { history: PatternCreditHistoryEntry[]; copy: CreditsCopy }) {
+  if (history.length === 0) return <p className="text-sm text-muted-foreground">{copy.historyEmpty}</p>;
+  const label = (e: PatternCreditHistoryEntry) =>
+    e.entryType === "grant" && e.reason ? e.reason : copy.entry[e.entryType] ?? e.entryType;
+  return (
+    <ul aria-label={copy.historyTitle} className="divide-y divide-border rounded-lg border border-border bg-card">
+      {history.map((e) => (
+        <li key={e.id} className="flex items-center justify-between gap-3 px-4 py-3 text-sm">
+          <span className="min-w-0">
+            <span className="block truncate text-foreground">{label(e)}</span>
+            <span className="block text-xs text-muted-foreground">{when(e.createdAt)}</span>
+          </span>
+          <span
+            className={`shrink-0 font-semibold ${e.quantity > 0 ? "text-green-700" : "text-muted-foreground"}`}
+            aria-label={`${e.quantity > 0 ? "plus" : "minus"} ${Math.abs(e.quantity)}`}
+          >
+            {e.quantity > 0 ? `+${e.quantity}` : e.quantity}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/credits/CreditPackCard.tsx

@@ -0,0 +1,51 @@
+import { Button } from "@startsimpli/ui";
+import { formatPackPrice, pricePerCredit, savingsPercent } from "../utils/credit-math";
+import type { CreditsCopy } from "./copy";
+import type { PatternCreditOffer } from "./types";
+
+export interface CreditPackCardProps {
+  offer: PatternCreditOffer;
+  copy: CreditsCopy;
+  /** Offer id being opened in checkout, if any. */
+  buying: string | null;
+  onBuy: (offerId: string) => void;
+}
+
+/** One pack: its price, the struck-through price and saving when the offer has one, and a Buy button. */
+export function CreditPackCard({ offer, copy, buying, onBuy }: CreditPackCardProps) {
+  const saving = savingsPercent(offer);
+  const name = copy.packName(offer.credits);
+  const opening = buying === offer.id;
+  return (
+    <li className={`flex flex-col rounded-xl border p-4 ${offer.featured ? "border-primary bg-primary/5" : "border-border bg-card"}`}>
+      <div className="flex items-start justify-between gap-2">
+        <p className="text-base font-semibold text-foreground">{name}</p>
+        {offer.featured && (
+          <span className="rounded-full bg-primary px-2 py-0.5 text-xs font-semibold text-primary-foreground">{copy.featured}</span>
+        )}
+      </div>
+      <p className="mt-3 flex flex-wrap items-baseline gap-x-2">
+        <span className="text-2xl font-bold text-foreground">{formatPackPrice(offer.price, offer.currency)}</span>
+        {saving !== null && (
+          <s className="text-sm text-muted-foreground" style={{ textDecoration: "line-through" }}>
+            {formatPackPrice(offer.compareAt, offer.currency)}
+          </s>
+        )}
+      </p>
+      <p className="mt-1 min-h-[1.25rem] text-sm text-muted-foreground">
+        {saving !== null && <span className="font-medium text-green-700">{copy.save(saving)}</span>}
+        {saving !== null && offer.credits > 1 && " · "}
+        {offer.credits > 1 && copy.perCredit(formatPackPrice(pricePerCredit(offer), offer.currency))}
+      </p>
+      <Button
+        className="mt-4 w-full"
+        variant={offer.featured ? "default" : "outline"}
+        disabled={buying !== null}
+        onClick={() => onBuy(offer.id)}
+        aria-label={opening ? undefined : copy.buy(name)}
+      >
+        {opening ? copy.buying : copy.buy(name)}
+      </Button>
+    </li>
+  );
+}

package/src/credits/CreditsPanel.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { Button } from "@startsimpli/ui";
+import { CreditBalanceBadge } from "./CreditBalanceBadge";
+import { CreditHistoryList } from "./CreditHistoryList";
+import { CreditPackCard } from "./CreditPackCard";
+import { withCreditsCopy, type CreditsCopy } from "./copy";
+import type { CreditsView } from "./types";
+
+export interface CreditsPanelProps {
+  credits: CreditsView;
+  copy?: Partial<CreditsCopy>;
+  headingId?: string;
+}
+
+/**
+ * Buy credits, see the balance and the history. Renders nothing while the sale
+ * is off (flag off, signed out, or the server's 409), so the page is exactly
+ * what it was.
+ */
+export function CreditsPanel({ credits, copy: copyIn, headingId = "credits-heading" }: CreditsPanelProps) {
+  const copy = withCreditsCopy(copyIn);
+  if (credits.status === "disabled") return null;
+  return (
+    <section aria-labelledby={headingId} className="mb-8 rounded-xl border border-border bg-muted/40 p-4 sm:p-6">
+      <div className="mb-4 flex flex-wrap items-center justify-between gap-2">
+        <h3 id={headingId} className="text-lg font-semibold text-foreground">{copy.sectionTitle}</h3>
+        {credits.status === "ready" && <CreditBalanceBadge balance={credits.balance} copy={copy} />}
+      </div>
+
+      {credits.status === "loading" && (
+        <p role="status" aria-live="polite" className="text-sm text-muted-foreground">{copy.loading}</p>
+      )}
+
+      {credits.status === "error" && (
+        <div role="alert" className="flex flex-wrap items-center gap-3 rounded-lg border border-red-200 bg-red-50 p-3 text-sm text-red-700">
+          <span>{copy.loadError}</span>
+          <Button size="sm" variant="outline" onClick={() => void credits.refresh()}>{copy.retry}</Button>
+        </div>
+      )}
+
+      {credits.status === "ready" && (
+        <>
+          <p className="mb-4 text-sm text-muted-foreground">{copy.sectionIntro}</p>
+          {credits.error && (
+            <p role="alert" className="mb-4 rounded-lg border border-red-200 bg-red-50 p-3 text-sm text-red-700">{credits.error}</p>
+          )}
+          <ul className="mb-2 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+            {credits.offers.map((offer) => (
+              <CreditPackCard key={offer.id} offer={offer} copy={copy} buying={credits.buying} onBuy={(id) => void credits.buy(id)} />
+            ))}
+          </ul>
+          <p className="mb-6 text-xs text-muted-foreground">{copy.secure}</p>
+          <h4 className="mb-2 text-sm font-semibold text-foreground">{copy.historyTitle}</h4>
+          <CreditHistoryList history={credits.history} copy={copy} />
+        </>
+      )}
+    </section>
+  );
+}

package/src/credits/CreditsReturn.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "@startsimpli/ui";
+import { withCreditsCopy, type CreditsCopy } from "./copy";
+import type { CreditsView } from "./types";
+
+type Phase = "pending" | "done" | "waiting" | "error";
+
+const LINK = "rounded-lg px-4 py-2 text-sm font-semibold";
+
+export interface CreditsReturnLinks {
+  /** Where "continue" goes (e.g. the builder). */
+  continueHref: string;
+  billingHref: string;
+}
+
+export interface CreditsSuccessProps extends CreditsReturnLinks {
+  credits: Pick<CreditsView, "status" | "sync">;
+  /** Stripe session from the return URL (`creditSessionFrom`). */
+  sessionId: string | null;
+  copy?: Partial<CreditsCopy>;
+}
+
+/** Back from Stripe: confirm the paid session (the webhook may not have arrived) and show the balance. */
+export function CreditsSuccess({ credits, sessionId, continueHref, billingHref, copy: copyIn }: CreditsSuccessProps) {
+  const copy = withCreditsCopy(copyIn);
+  const [phase, setPhase] = useState<Phase>("pending");
+  const [balance, setBalance] = useState(0);
+  const started = useRef(false);
+  const { sync } = credits;
+
+  const run = useCallback(async () => {
+    if (!sessionId) return;
+    setPhase("pending");
+    try {
+      const r = await sync(sessionId);
+      setBalance(r.balance);
+      setPhase(r.granted ? "done" : "waiting");
+    } catch {
+      setPhase("error");
+    }
+  }, [sessionId, sync]);
+
+  useEffect(() => {
+    if (!sessionId || started.current || credits.status === "disabled") return;
+    started.current = true;
+    void run();
+  }, [sessionId, credits.status, run]);
+
+  return (
+    <div className="mx-auto max-w-lg py-10 text-center">
+      <h3 className="mb-4 text-xl font-semibold text-foreground">{copy.successTitle}</h3>
+      {!sessionId && <p className="text-sm text-muted-foreground">{copy.successMissingSession}</p>}
+      {sessionId && phase === "pending" && <p role="status" className="text-sm text-muted-foreground">{copy.successPending}</p>}
+      {sessionId && phase === "done" && <p role="status" className="text-sm text-foreground">{copy.successDone(1, balance)}</p>}
+      {sessionId && phase === "waiting" && (
+        <div role="status" className="space-y-3 text-sm text-muted-foreground">
+          <p>{copy.successStillPending}</p>
+          <Button variant="outline" onClick={() => void run()}>{copy.successCheckAgain}</Button>
+        </div>
+      )}
+      {sessionId && phase === "error" && (
+        <div role="alert" className="space-y-3 rounded-lg border border-red-200 bg-red-50 p-4 text-sm text-red-700">
+          <p>{copy.successSyncError}</p>
+          <Button variant="outline" onClick={() => void run()}>{copy.successCheckAgain}</Button>
+        </div>
+      )}
+      <div className="mt-6 flex flex-wrap justify-center gap-3">
+        <a href={continueHref} className={`${LINK} bg-primary text-primary-foreground hover:opacity-90`}>{copy.continueLabel}</a>
+        <a href={billingHref} className={`${LINK} border border-border text-foreground hover:bg-muted`}>{copy.seeBilling}</a>
+      </div>
+    </div>
+  );
+}
+
+/** Back from Stripe after cancelling. */
+export function CreditsCancelled({ billingHref, copy: copyIn }: { billingHref: string; copy?: Partial<CreditsCopy> }) {
+  const copy = withCreditsCopy(copyIn);
+  return (
+    <div className="mx-auto max-w-lg py-10 text-center">
+      <h3 className="mb-4 text-xl font-semibold text-foreground">{copy.cancelledTitle}</h3>
+      <p className="text-sm text-muted-foreground">{copy.cancelledBody}</p>
+      <div className="mt-6">
+        <a href={billingHref} className={`${LINK} bg-primary text-primary-foreground hover:opacity-90`}>{copy.tryAgain}</a>
+      </div>
+    </div>
+  );
+}

package/src/credits/UseCreditPrompt.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { Button } from "@startsimpli/ui";
+import { CreditPackCard } from "./CreditPackCard";
+import { withCreditsCopy, type CreditsCopy } from "./copy";
+import type { PatternCreditOffer } from "./types";
+
+export interface UseCreditPromptProps {
+  balance: number;
+  offers: PatternCreditOffer[];
+  buying: string | null;
+  error: string | null;
+  onUse: () => void;
+  onBuy: (offerId: string) => void;
+  onCancel: () => void;
+  /** True when the plan's monthly allowance is used up (vs. no plan at all). */
+  planAllowanceUsed?: boolean;
+  copy?: Partial<CreditsCopy>;
+}
+
+/** At the action button, when the plan cannot cover it: confirm using a credit, or (with none left) buy a pack. */
+export function UseCreditPrompt({ balance, offers, buying, error, onUse, onBuy, onCancel, planAllowanceUsed, copy: copyIn }: UseCreditPromptProps) {
+  const copy = withCreditsCopy(copyIn);
+  const title = balance > 0 ? copy.confirmTitle : copy.outTitle;
+  return (
+    <div role="dialog" aria-label={title} className="w-full rounded-xl border border-border bg-muted/40 p-4 text-left">
+      <h4 className="text-base font-semibold text-foreground">{title}</h4>
+      <p className="mt-1 text-sm text-muted-foreground">{balance > 0 ? copy.confirmBody(balance) : copy.outBody}</p>
+      {planAllowanceUsed && balance > 0 && <p className="mt-1 text-xs text-muted-foreground">{copy.planAllowanceUsed}</p>}
+      {error && <p role="alert" className="mt-2 text-sm text-red-700">{error}</p>}
+      {balance > 0 ? (
+        <div className="mt-4 flex flex-wrap gap-2">
+          <Button onClick={onUse}>{copy.confirmUse}</Button>
+          <Button variant="outline" onClick={onCancel}>{copy.confirmCancel}</Button>
+        </div>
+      ) : (
+        <>
+          <ul className="mt-4 grid gap-3 sm:grid-cols-2">
+            {offers.map((o) => <CreditPackCard key={o.id} offer={o} copy={copy} buying={buying} onBuy={onBuy} />)}
+          </ul>
+          <div className="mt-3"><Button variant="outline" size="sm" onClick={onCancel}>{copy.confirmCancel}</Button></div>
+        </>
+      )}
+    </div>
+  );
+}

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";