@startsimpli/billing 0.4.37 → 0.4.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.37",
+  "version": "0.4.39",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "license": "MIT",
   "homepage": "https://startsimpli.com",
@@ -35,8 +35,8 @@
     "next": ">=14.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "^0.5.75",
-    "@startsimpli/ui": "^0.4.177"
+    "@startsimpli/api": "^0.5.77",
+    "@startsimpli/ui": "^0.4.178"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -61,8 +61,8 @@
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "@startsimpli/ui": "0.4.177",
-    "@startsimpli/api": "0.5.75"
+    "@startsimpli/api": "0.5.77",
+    "@startsimpli/ui": "0.4.178"
   },
   "keywords": [
     "billing",

package/src/components/PricingDetailPage.tsx

@@ -165,7 +165,7 @@ export function PricingDetailPage({
     for (const feature of offer.features) {
       if (!allFeatureKeys.includes(feature.key)) {
         allFeatureKeys.push(feature.key);
-        const override = resolveFeatureCopy(feature, featureCopy);
+        const override = resolveFeatureCopy(feature, featureCopy, { generic: true });
         featureNameMap[feature.key] = override?.label ?? feature.name;
         featureHintMap[feature.key] = override?.hint;
       }

package/src/copy/feature-copy.test.tsx

@@ -0,0 +1,48 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { FeatureLabel } from "../components/FeatureLabel";
+import { featureText, resolveFeatureCopy } from "./feature-copy";
+import type { OfferFeature } from "../types";
+
+const f = (over: Partial<OfferFeature> = {}): OfferFeature => ({ key: "ai_designs_per_month", name: "AI designs per month", value: 3, ...over });
+const copy = { ai_designs_per_month: "{value} new patterns each month" };
+
+describe("featureCopy {value} placeholder", () => {
+  it("fills from the feature value", () => {
+    expect(featureText(f({ value: 3 }), copy).label).toBe("3 new patterns each month");
+    expect(featureText(f({ value: 15 }), copy).label).toBe("15 new patterns each month");
+  });
+  it("prefers the limit over the value", () => {
+    expect(featureText(f({ value: true, limit: 15 }), copy).label).toBe("15 new patterns each month");
+    expect(featureText(f({ value: 3, limit: 15 }), copy).label).toBe("15 new patterns each month");
+    expect(featureText(f({ value: 3, limit: null }), copy).label).toBe("3 new patterns each month");
+  });
+  it("says unlimited for -1 and the string 'unlimited', matching the case of the spot", () => {
+    expect(featureText(f({ value: -1 }), copy).label).toBe("Unlimited new patterns each month");
+    expect(featureText(f({ limit: -1 }), { ai_designs_per_month: "Make {value} patterns" }).label).toBe("Make unlimited patterns");
+    expect(featureText(f({ value: "unlimited" }), copy).label).toBe("Unlimited new patterns each month");
+  });
+  it("drops the placeholder for true / other strings / null", () => {
+    expect(featureText(f({ value: true }), copy).label).toBe("new patterns each month");
+    expect(featureText(f({ value: "pro" }), copy).label).toBe("new patterns each month");
+    expect(featureText(f({ value: null }), { ai_designs_per_month: "Patterns ({value}) monthly" }).label).toBe("Patterns monthly");
+  });
+  it("works in {label, hint} and fills every occurrence", () => {
+    const out = featureText(f({ value: 3 }), { ai_designs_per_month: { label: "{value} patterns", hint: "Up to {value} a month, resets on the 1st" } });
+    expect(out).toEqual({ label: "3 patterns", hint: "Up to 3 a month, resets on the 1st" });
+  });
+  it("leaves text without a placeholder and the default label untouched", () => {
+    expect(featureText(f(), { ai_designs_per_month: "Patterns per month" }).label).toBe("Patterns per month");
+    expect(featureText(f({ value: 3 })).label).toBe("Up to 3 ai designs per month".replace("ai designs", "AI designs"));
+    expect(resolveFeatureCopy(f(), {})).toBeNull();
+  });
+  it("generic mode (comparison-table row labels) removes the placeholder", () => {
+    expect(resolveFeatureCopy(f({ value: 3 }), copy, { generic: true })?.label).toBe("new patterns each month");
+  });
+  it("renders through FeatureLabel", () => {
+    render(<FeatureLabel feature={f({ value: 15 })} featureCopy={{ ai_designs_per_month: { label: "{value} new patterns each month", hint: "of {value}" } }} />);
+    expect(screen.getByText(/15 new patterns each month/)).toBeTruthy();
+    expect(screen.getByTestId("feature-hint-ai_designs_per_month").textContent).toBe("of 15");
+  });
+});

package/src/copy/feature-copy.ts

@@ -11,11 +11,51 @@ export interface FeatureText {
   hint?: string;
 }
 
-/** The override for this feature, or null when the app set none. */
-export function resolveFeatureCopy(feature: Pick<OfferFeature, "key">, featureCopy?: FeatureCopy): FeatureText | null {
+const PLACEHOLDER = /\{value\}/g;
+
+/**
+ * The number a `{value}` placeholder reads: the feature's `limit` when it is a
+ * number, else its `value` when that is a number. -1 or the string "unlimited"
+ * is unlimited; anything else (true, other strings, null) has no number.
+ */
+function placeholderValue(feature: Pick<OfferFeature, "limit" | "value">): number | "unlimited" | null {
+  const n = typeof feature.limit === "number" ? feature.limit : typeof feature.value === "number" ? feature.value : null;
+  if (n === -1) return "unlimited";
+  if (n !== null && Number.isFinite(n) && n >= 0) return n;
+  if (n === null && typeof feature.value === "string" && feature.value.trim().toLowerCase() === "unlimited") return "unlimited";
+  return null;
+}
+
+function fillPlaceholder(text: string, value: number | "unlimited" | null): string {
+  if (!PLACEHOLDER.test(text)) return text;
+  PLACEHOLDER.lastIndex = 0;
+  if (value === null) {
+    return text.replace(PLACEHOLDER, "").replace(/\(\s*\)/g, "").replace(/\s{2,}/g, " ").trim();
+  }
+  return text.replace(PLACEHOLDER, (_m, offset: number) => {
+    if (value !== "unlimited") return String(value);
+    const atStart = text.slice(0, offset).trim() === "";
+    return atStart ? "Unlimited" : "unlimited";
+  });
+}
+
+/**
+ * The override for this feature, or null when the app set none. `{value}` in a
+ * label or hint is filled from the feature (see placeholderValue). `generic`
+ * drops the placeholder, for a row label shared by several plans.
+ */
+export function resolveFeatureCopy(
+  feature: Pick<OfferFeature, "key"> & Partial<Pick<OfferFeature, "limit" | "value">>,
+  featureCopy?: FeatureCopy,
+  opts?: { generic?: boolean },
+): FeatureText | null {
   const entry = featureCopy?.[feature.key];
   if (entry === undefined || entry === null) return null;
-  return typeof entry === "string" ? { label: entry } : { label: entry.label, ...(entry.hint ? { hint: entry.hint } : {}) };
+  const value = opts?.generic ? null : placeholderValue({ limit: feature.limit, value: feature.value ?? null });
+  const fill = (t: string) => fillPlaceholder(t, value);
+  return typeof entry === "string"
+    ? { label: fill(entry) }
+    : { label: fill(entry.label), ...(entry.hint ? { hint: fill(entry.hint) } : {}) };
 }
 
 /** What a feature row says: the override, else the label the card always had. */

package/src/credits/CreditPackCard.savings.test.tsx

@@ -0,0 +1,136 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { CreditPackCard, CreditPackGrid, CreditsPanel, SAVINGS_SASH_TOKENS, defaultCreditsCopy, withCreditsCopy, type CreditsView } from "./index";
+
+const five = { id: "p5", slug: "5", name: "5 pack", credits: 5, price: "19.99", currency: "usd", compareAt: "24.95", featured: false };
+const fifteen = { id: "p15", slug: "15", name: "15 pack", credits: 15, price: "49.99", currency: "usd", compareAt: "74.85", featured: true };
+const single = { id: "p1", slug: "1", name: "1", credits: 1, price: "4.99", currency: "usd", compareAt: "", featured: false };
+const server5 = { ...five, savingsPercent: 20, savingsAmount: 496, pricePerPattern: "4.00" };
+const server15 = { ...fifteen, savingsPercent: 33, savingsAmount: 2486, pricePerPattern: "3.33" };
+
+const card = (offer: object, copy = defaultCreditsCopy) =>
+  render(<ul><CreditPackCard offer={offer as never} copy={copy} buying={null} onBuy={vi.fn()} /></ul>);
+
+describe("CreditPackCard savings", () => {
+  it("shows the sash, the dollar line and the per-pattern line for the 5 and 15 packs", () => {
+    const { unmount } = card(server5);
+    expect(screen.getByTestId("savings-sash").textContent).toBe("Save 20%");
+    expect(screen.getByText("Save $4.96")).toBeTruthy();
+    expect(screen.getByText("$4.00 each")).toBeTruthy();
+    unmount();
+    card(server15);
+    expect(screen.getByTestId("savings-sash").textContent).toBe("Save 33%");
+    expect(screen.getByText("Save $24.86")).toBeTruthy();
+    expect(screen.getByText("$3.33 each")).toBeTruthy();
+  });
+
+  it("has no sash and no dollar line for a single pattern", () => {
+    card(single);
+    expect(screen.queryByTestId("savings-sash")).toBeNull();
+    expect(screen.queryByText(/^Save/)).toBeNull();
+  });
+
+  it("follows the data: change the offer and the text changes", () => {
+    card({ ...server5, savingsPercent: 35, savingsAmount: 1234, pricePerPattern: "2.50" });
+    expect(screen.getByTestId("savings-sash").textContent).toBe("Save 35%");
+    expect(screen.getByText("Save $12.34")).toBeTruthy();
+    expect(screen.getByText("$2.50 each")).toBeTruthy();
+  });
+
+  it("falls back to compareAt math against an older backend", () => {
+    card(five);
+    expect(screen.getByTestId("savings-sash").textContent).toBe("Save 20%");
+    expect(screen.getByText("Save $4.96")).toBeTruthy();
+    expect(screen.getByText("$4.00 each")).toBeTruthy();
+  });
+
+  it("has no sash when a multi pack saves nothing", () => {
+    card({ ...five, compareAt: "" });
+    expect(screen.queryByTestId("savings-sash")).toBeNull();
+    expect(screen.queryByText(/^Save/)).toBeNull();
+    expect(screen.getByText("$4.00 each")).toBeTruthy();
+  });
+
+  it("applies copy overrides to the sash and the line", () => {
+    card(server5, withCreditsCopy({ savingsSash: (p) => `${p}% off`, savingsLine: (a) => `You keep ${a}` }));
+    expect(screen.getByTestId("savings-sash").textContent).toBe("20% off");
+    expect(screen.getByText("You keep $4.96")).toBeTruthy();
+  });
+
+  it("keeps the older save key working for the sash", () => {
+    card(server5, withCreditsCopy({ save: (p) => `Spar ${p}%` }));
+    expect(screen.getByTestId("savings-sash").textContent).toBe("Spar 20%");
+  });
+
+  it("clips the ribbon inside the card corner", () => {
+    card(server5);
+    const li = screen.getByRole("listitem");
+    expect(li.className).toContain("relative");
+    expect(li.className).toContain("overflow-hidden");
+    const sash = screen.getByTestId("savings-sash");
+    expect(sash.className).toContain("rotate-45");
+    expect(sash.className).toContain("whitespace-nowrap");
+    expect(sash.className).toContain("pointer-events-none");
+  });
+});
+
+// Tailwind default palette values for the classes the sash may use.
+const PALETTE: Record<string, string> = { "bg-green-800": "#166534", "bg-green-900": "#14532d", "bg-emerald-800": "#065f46", "text-white": "#ffffff" };
+const lum = (hex: string) => {
+  const c = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255).map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+};
+const contrast = (a: string, b: string) => {
+  const [hi, lo] = [lum(a), lum(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+};
+
+describe("sash accessibility", () => {
+  it("meets WCAG AA (4.5:1) for its text on its fill", () => {
+    const bg = PALETTE[SAVINGS_SASH_TOKENS.bg];
+    const fg = PALETTE[SAVINGS_SASH_TOKENS.text];
+    expect(bg && fg).toBeTruthy();
+    expect(contrast(bg, fg)).toBeGreaterThanOrEqual(4.5);
+  });
+  it("meets AA for the savings line text (green-700) on white", () => {
+    expect(contrast("#15803d", "#ffffff")).toBeGreaterThanOrEqual(4.5);
+  });
+  it("uses the declared classes on the sash", () => {
+    card(server5);
+    const cls = screen.getByTestId("savings-sash").className;
+    expect(cls).toContain(SAVINGS_SASH_TOKENS.bg);
+    expect(cls).toContain(SAVINGS_SASH_TOKENS.text);
+  });
+});
+
+describe("CreditPackGrid", () => {
+  it("renders one card per offer with no hook and calls the caller's buy handler", () => {
+    const onBuy = vi.fn();
+    render(<CreditPackGrid offers={[single, server5, server15] as never} onBuy={onBuy} />);
+    expect(screen.getAllByRole("listitem")).toHaveLength(3);
+    expect(screen.getAllByTestId("savings-sash")).toHaveLength(2);
+    screen.getByRole("button", { name: "Buy 5 credits" }).click();
+    expect(onBuy).toHaveBeenCalledWith("p5");
+  });
+  it("marks the opening pack, disables the others, and takes copy", () => {
+    render(<CreditPackGrid offers={[server5, server15] as never} onBuy={vi.fn()} buying="p5" copy={{ buying: "Opening…" }} />);
+    expect(screen.getByRole("button", { name: "Opening…" })).toBeTruthy();
+    expect((screen.getByRole("button", { name: "Buy 15 credits" }) as HTMLButtonElement).disabled).toBe(true);
+  });
+  it("renders nothing for no offers", () => {
+    const { container } = render(<CreditPackGrid offers={[]} onBuy={vi.fn()} />);
+    expect(container.innerHTML).toBe("");
+  });
+});
+
+describe("CreditsPanel copy", () => {
+  it("passes the savings copy through to the cards", () => {
+    const credits: CreditsView = {
+      status: "ready", balance: 0, offers: [server5 as never], history: [], error: null, buying: null,
+      refresh: vi.fn(async () => {}), buy: vi.fn(async () => {}), sync: vi.fn(async () => ({ granted: true, balance: 0 })),
+    };
+    render(<CreditsPanel credits={credits} copy={{ savingsLine: (a) => `Keep ${a}` }} />);
+    expect(screen.getByText("Keep $4.96")).toBeTruthy();
+  });
+});

package/src/credits/CreditPackCard.tsx

@@ -1,5 +1,5 @@
 import { Button } from "@startsimpli/ui";
-import { formatPackPrice, pricePerCredit, savingsPercent } from "../utils/credit-math";
+import { formatPackPrice, formatSavingsAmount, packSavings } from "../utils/credit-math";
 import type { CreditsCopy } from "./copy";
 import type { PatternCreditOffer } from "./types";
 
@@ -11,14 +11,35 @@ export interface CreditPackCardProps {
   onBuy: (offerId: string) => void;
 }
 
-/** One pack: its price, the struck-through price and saving when the offer has one, and a Buy button. */
+/**
+ * Sash colours. White on green-800 (#166534) is 7.1:1, above WCAG AA 4.5:1;
+ * a test computes the ratio from these classes.
+ */
+export const SAVINGS_SASH_TOKENS = { bg: "bg-green-800", text: "text-white" } as const;
+
+/**
+ * One pack: its price, the struck-through price, a corner sash and a dollar
+ * saving line on multi-pattern packs, and a Buy button. Server savings fields
+ * win; compareAt math is the fallback.
+ */
 export function CreditPackCard({ offer, copy, buying, onBuy }: CreditPackCardProps) {
-  const saving = savingsPercent(offer);
+  const savings = packSavings(offer);
+  const multi = offer.credits > 1;
+  const showSash = multi && savings.percent !== null;
+  const struck = !!offer.compareAt && Number(offer.compareAt) > Number(offer.price);
   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">
+    <li className={`relative flex flex-col overflow-hidden rounded-xl border p-4 ${offer.featured ? "border-primary bg-primary/5" : "border-border bg-card"}`}>
+      {showSash && (
+        <span
+          data-testid="savings-sash"
+          className={`pointer-events-none absolute right-[-2.75rem] top-4 w-36 rotate-45 whitespace-nowrap py-1 text-center text-xs font-semibold shadow-sm ${SAVINGS_SASH_TOKENS.bg} ${SAVINGS_SASH_TOKENS.text}`}
+        >
+          {copy.savingsSash(savings.percent as number)}
+        </span>
+      )}
+      <div className={`flex flex-wrap items-center gap-2 ${showSash ? "pr-14" : ""}`}>
         <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>
@@ -26,16 +47,18 @@ export function CreditPackCard({ offer, copy, buying, onBuy }: CreditPackCardPro
       </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 && (
+        {struck && (
           <s className="text-sm text-muted-foreground" style={{ textDecoration: "line-through" }}>
             {formatPackPrice(offer.compareAt, offer.currency)}
           </s>
         )}
       </p>
+      {multi && savings.amountCents !== null && (
+        <p className="mt-1 text-sm font-medium text-green-700">{copy.savingsLine(formatSavingsAmount(savings.amountCents, offer.currency))}</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))}
+        {!multi && savings.percent !== null && <span className="font-medium text-green-700">{copy.save(savings.percent)}</span>}
+        {multi && copy.perCredit(formatPackPrice(savings.perPattern, offer.currency))}
       </p>
       <Button
         className="mt-4 w-full"

package/src/credits/CreditPackGrid.tsx

@@ -0,0 +1,26 @@
+import { CreditPackCard } from "./CreditPackCard";
+import { withCreditsCopy, type CreditsCopy } from "./copy";
+import type { PatternCreditOffer } from "./types";
+
+export interface CreditPackGridProps {
+  offers: PatternCreditOffer[];
+  /** Called with the offer id. The caller owns what buying means (checkout, or sign-in first for a visitor). */
+  onBuy: (offerId: string) => void;
+  /** Offer id being opened in checkout, if any. */
+  buying?: string | null;
+  copy?: Partial<CreditsCopy>;
+  className?: string;
+}
+
+/** The pack cards on their own: no hook, no balance, no history. For /pricing and home sections. */
+export function CreditPackGrid({ offers, onBuy, buying = null, copy: copyIn, className }: CreditPackGridProps) {
+  if (offers.length === 0) return null;
+  const copy = withCreditsCopy(copyIn);
+  return (
+    <ul className={className ?? "grid gap-3 sm:grid-cols-2 lg:grid-cols-3"}>
+      {offers.map((offer) => (
+        <CreditPackCard key={offer.id} offer={offer} copy={copy} buying={buying} onBuy={onBuy} />
+      ))}
+    </ul>
+  );
+}

package/src/credits/CreditsPanel.tsx

@@ -3,7 +3,7 @@
 import { Button } from "@startsimpli/ui";
 import { CreditBalanceBadge } from "./CreditBalanceBadge";
 import { CreditHistoryList } from "./CreditHistoryList";
-import { CreditPackCard } from "./CreditPackCard";
+import { CreditPackGrid } from "./CreditPackGrid";
 import { withCreditsCopy, type CreditsCopy } from "./copy";
 import type { CreditsView } from "./types";
 
@@ -45,11 +45,7 @@ export function CreditsPanel({ credits, copy: copyIn, headingId = "credits-headi
           {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>
+          <CreditPackGrid className="mb-2 grid gap-3 sm:grid-cols-2 lg:grid-cols-3" offers={credits.offers} copy={copy} buying={credits.buying} onBuy={(id) => void credits.buy(id)} />
           <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} />

package/src/credits/copy.ts

@@ -14,6 +14,10 @@ export interface CreditsCopy {
   packName: (credits: number) => string;
   perCredit: (price: string) => string;
   save: (pct: number) => string;
+  /** Corner sash on a multi-pattern pack. Defaults to `save` when only that is overridden. */
+  savingsSash: (percent: number) => string;
+  /** Dollar saving under the price; `amount` is already formatted ("$4.96"). */
+  savingsLine: (amount: string) => string;
   featured: string;
   buy: (name: string) => string;
   buying: string;
@@ -57,6 +61,8 @@ export const defaultCreditsCopy: CreditsCopy = {
   packName: (c) => `${c} ${plural(c, "credit", "credits")}`,
   perCredit: (p) => `${p} each`,
   save: (pct) => `Save ${pct}%`,
+  savingsSash: (percent) => `Save ${percent}%`,
+  savingsLine: (amount) => `Save ${amount}`,
   featured: "Best value",
   buy: (name) => `Buy ${name}`,
   buying: "Opening checkout…",
@@ -93,4 +99,9 @@ export const defaultCreditsCopy: CreditsCopy = {
   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 });
+export const withCreditsCopy = (copy?: Partial<CreditsCopy>): CreditsCopy => ({
+  ...defaultCreditsCopy,
+  // An app that only overrides `save` keeps its wording on the sash.
+  ...(copy?.save && !copy.savingsSash ? { savingsSash: copy.save } : {}),
+  ...copy,
+});

package/src/credits/index.ts

@@ -1,7 +1,9 @@
 export { CreditsPanel } from "./CreditsPanel";
 export type { CreditsPanelProps } from "./CreditsPanel";
-export { CreditPackCard } from "./CreditPackCard";
+export { CreditPackCard, SAVINGS_SASH_TOKENS } from "./CreditPackCard";
 export type { CreditPackCardProps } from "./CreditPackCard";
+export { CreditPackGrid } from "./CreditPackGrid";
+export type { CreditPackGridProps } from "./CreditPackGrid";
 export { CreditBalanceBadge } from "./CreditBalanceBadge";
 export { CreditHistoryList } from "./CreditHistoryList";
 export { UseCreditPrompt } from "./UseCreditPrompt";

package/src/index.ts

@@ -100,7 +100,7 @@ export {
   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 { formatPackPrice, formatSavingsAmount, packSavings, pricePerCredit, savingsPercent } from "./utils/credit-math";
+export type { PackPrice, PackSavings, PackSavingsInput } from "./utils/credit-math";
 export { meterRows } from "./utils/usage-meters";
 export type { MeterRow, MeterState } from "./utils/usage-meters";

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

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { formatSavingsAmount, packSavings } from "./credit-math";
+
+const base = { price: "19.99", compareAt: "24.95", credits: 5, currency: "usd" };
+
+describe("packSavings", () => {
+  it("prefers the server's values", () => {
+    expect(packSavings({ ...base, savingsPercent: 21, savingsAmount: 500, pricePerPattern: "3.99" })).toEqual({
+      percent: 21, amountCents: 500, perPattern: "3.99",
+    });
+  });
+  it("accepts save_percent and per_pattern_price spellings", () => {
+    expect(packSavings({ ...base, savePercent: 22, perPatternPrice: "3.98" })).toMatchObject({ percent: 22, perPattern: "3.98" });
+  });
+  it("falls back to compareAt math when the server sends nothing", () => {
+    expect(packSavings(base)).toEqual({ percent: 20, amountCents: 496, perPattern: "4.00" });
+  });
+  it("derives the percent from a server amount when there is no compareAt", () => {
+    expect(packSavings({ price: "19.99", compareAt: "", credits: 5, savingsAmount: 496 })).toMatchObject({ percent: 20, amountCents: 496 });
+  });
+  it("reports no saving when the server says zero or there is none", () => {
+    expect(packSavings({ ...base, savingsPercent: 0, savingsAmount: 0 })).toMatchObject({ percent: null, amountCents: null });
+    expect(packSavings({ price: "4.99", compareAt: "", credits: 1 })).toMatchObject({ percent: null, amountCents: null });
+  });
+  it("formats cents as a currency amount", () => {
+    expect(formatSavingsAmount(496, "usd")).toBe("$4.96");
+    expect(formatSavingsAmount(2486, "usd")).toBe("$24.86");
+  });
+});

package/src/utils/credit-math.ts

@@ -30,3 +30,53 @@ export function pricePerCredit(offer: Pick<PackPrice, "price" | "credits">): str
   const total = Number(offer.price);
   return offer.credits > 0 && Number.isFinite(total) ? (total / offer.credits).toFixed(2) : offer.price;
 }
+
+/** The server's savings fields on an offer (all optional: older backends send none). */
+export interface PackSavingsInput extends PackPrice {
+  savingsPercent?: number;
+  savePercent?: number;
+  savingsAmount?: number;
+  pricePerPattern?: string;
+  perPatternPrice?: string;
+}
+
+export interface PackSavings {
+  /** Whole percent saved, or null when the pack saves nothing. */
+  percent: number | null;
+  /** Integer cents saved, or null when the pack saves nothing. */
+  amountCents: number | null;
+  /** Price of one pattern, decimal string. */
+  perPattern: string;
+}
+
+const positiveNumber = (v: unknown): number | null =>
+  typeof v === "number" && Number.isFinite(v) && v > 0 ? v : null;
+
+/**
+ * Savings of a pack. Server values win when present (a server 0 means "no
+ * saving"); otherwise derived from compareAt so older backends still work.
+ */
+export function packSavings(offer: PackSavingsInput): PackSavings {
+  const price = Number(offer.price);
+  const was = Number(offer.compareAt);
+  const hasCompare = !!offer.compareAt && Number.isFinite(price) && Number.isFinite(was) && was > price && was > 0;
+
+  let amountCents: number | null;
+  if (typeof offer.savingsAmount === "number") amountCents = positiveNumber(Math.round(offer.savingsAmount));
+  else amountCents = hasCompare ? positiveNumber(Math.round((was - price) * 100)) : null;
+
+  const serverPercent = typeof offer.savingsPercent === "number" ? offer.savingsPercent : offer.savePercent;
+  let percent: number | null;
+  if (typeof serverPercent === "number") percent = positiveNumber(Math.round(serverPercent));
+  else if (hasCompare) percent = positiveNumber(savingsPercent(offer));
+  else if (amountCents !== null && Number.isFinite(price) && price > 0) {
+    percent = positiveNumber(Math.round((amountCents / (price * 100 + amountCents)) * 100));
+  } else percent = null;
+
+  return { percent, amountCents, perPattern: offer.pricePerPattern || offer.perPatternPrice || pricePerCredit(offer) };
+}
+
+/** "$4.96" from integer cents. */
+export function formatSavingsAmount(cents: number, currency: string): string {
+  return formatPackPrice((cents / 100).toFixed(2), currency);
+}