@startsimpli/billing 0.4.17 → 0.4.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/components/PricingDetailPage.tiers.test.tsx

@@ -0,0 +1,178 @@
+/**
+ * Tiers are cumulative: a paid plan includes what the cheaper plan includes.
+ *
+ * Real offer data only lists what a tier ADDS — crochet-pro declares
+ * advanced_generation / stitch_library / pdf_export / custom_sizing and omits
+ * the basic_generation and save_patterns that crochet-free declares. The table
+ * rendered every omission as an em-dash, so the paid plan showed a dash exactly
+ * where the free plan showed a tick, and read as though Pro could not save
+ * patterns. Reported as "the paid plan doesn't look like it has more checks".
+ *
+ * The fixture in PricingDetailPage.test.tsx restates every feature on every
+ * tier, which is why this never showed up there. This one is shaped like the
+ * data production actually serves.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import React from "react";
+import { BillingProvider } from "../hooks/BillingProvider";
+import { PricingDetailPage } from "./PricingDetailPage";
+import type { BillingProduct, OfferFeature } from "../types";
+
+function offer(
+  over: Partial<BillingProduct["offers"][number]> & { name: string; slug: string; features: OfferFeature[] },
+) {
+  return {
+    id: over.slug,
+    unitPrice: "0.00",
+    currency: "USD",
+    pricingModel: "flat" as const,
+    intervalUnit: "month" as const,
+    intervalCount: 1,
+    intervalDisplay: "per month",
+    isRecurring: true,
+    isFree: false,
+    isActive: true,
+    isFeatured: false,
+    trialDays: 0,
+    sortOrder: 0,
+    ctaText: "Choose",
+    ...over,
+  };
+}
+
+/** Shaped like the live crochet-patterns product. */
+const product: BillingProduct = {
+  id: "prod-crochet",
+  slug: "crochet-patterns",
+  name: "Crochet Patterns",
+  description: "AI-powered crochet pattern generator",
+  offers: [
+    offer({
+      name: "Free",
+      slug: "crochet-free",
+      isFree: true,
+      sortOrder: 0,
+      features: [
+        { key: "patterns_per_month", name: "Patterns per month", value: 3, limit: 3 },
+        { key: "basic_generation", name: "Basic pattern generation", value: true },
+        { key: "save_patterns", name: "Save patterns", value: true },
+      ],
+    }),
+    offer({
+      name: "Pro",
+      slug: "crochet-pro",
+      unitPrice: "9.00",
+      sortOrder: 1,
+      isFeatured: true,
+      features: [
+        { key: "patterns_per_month", name: "Patterns per month", value: -1 },
+        { key: "advanced_generation", name: "Advanced pattern generation", value: true },
+        { key: "pdf_export", name: "PDF export", value: true },
+      ],
+    }),
+  ],
+};
+
+function renderPricing(p: BillingProduct = product) {
+  const fetcher = vi.fn().mockResolvedValue({
+    ok: true,
+    json: () => Promise.resolve(p),
+  }) as unknown as typeof fetch;
+
+  return render(
+    <BillingProvider apiBaseUrl="https://api.test.com/api/v1" fetcher={fetcher}>
+      <PricingDetailPage productId={p.slug} />
+    </BillingProvider>,
+  );
+}
+
+/** The cell for one offer in one feature row, by column position. */
+function cell(featureKey: string, column: number) {
+  const row = screen.getByTestId(`comparison-row-${featureKey}`);
+  // column 0 is the feature name.
+  return within(row).getAllByRole("cell")[column + 1];
+}
+
+describe("comparison table — cumulative tiers", () => {
+  it("shows the paid plan as including what the free plan includes", async () => {
+    renderPricing();
+    await waitFor(() => expect(screen.getByTestId("comparison-table")).toBeDefined());
+
+    for (const key of ["basic_generation", "save_patterns"]) {
+      const pro = cell(key, 1);
+      expect(within(pro).queryByLabelText("Included"), key).not.toBeNull();
+      expect(pro.textContent, key).not.toContain("—");
+    }
+  });
+
+  it("gives the paid plan more ticks than the free plan, which is the whole point", async () => {
+    renderPricing();
+    await waitFor(() => expect(screen.getByTestId("comparison-table")).toBeDefined());
+
+    const ticks = (column: number) =>
+      ["basic_generation", "save_patterns", "advanced_generation", "pdf_export"].filter(
+        (key) => within(cell(key, column)).queryByLabelText("Included") !== null,
+      ).length;
+
+    expect(ticks(1)).toBeGreaterThan(ticks(0));
+  });
+
+  it("still lets a higher tier opt out by saying so explicitly", async () => {
+    renderPricing({
+      ...product,
+      offers: [
+        product.offers[0],
+        {
+          ...product.offers[1],
+          features: [
+            ...product.offers[1].features,
+            { key: "save_patterns", name: "Save patterns", value: false },
+          ],
+        },
+      ],
+    });
+    await waitFor(() => expect(screen.getByTestId("comparison-table")).toBeDefined());
+
+    expect(within(cell("save_patterns", 1)).queryByLabelText("Not included")).not.toBeNull();
+  });
+
+  it("never inherits a numeric allowance — a bigger plan must state its own", async () => {
+    renderPricing({
+      ...product,
+      offers: [
+        product.offers[0],
+        {
+          ...product.offers[1],
+          // Pro forgot to declare patterns_per_month.
+          features: product.offers[1].features.filter((f) => f.key !== "patterns_per_month"),
+        },
+      ],
+    });
+    await waitFor(() => expect(screen.getByTestId("comparison-table")).toBeDefined());
+
+    // Claiming Pro is capped at the free plan's 3 would be worse than saying nothing.
+    expect(cell("patterns_per_month", 1).textContent).not.toContain("3");
+  });
+
+  it("leaves the cheapest plan alone — nothing below it to inherit", async () => {
+    renderPricing();
+    await waitFor(() => expect(screen.getByTestId("comparison-table")).toBeDefined());
+
+    for (const key of ["advanced_generation", "pdf_export"]) {
+      expect(within(cell(key, 0)).queryByLabelText("Included"), key).toBeNull();
+    }
+  });
+
+  it("tells the reader on the card that a paid plan builds on the free one", async () => {
+    renderPricing();
+    await waitFor(() => expect(screen.getByTestId("detail-card-crochet-pro")).toBeDefined());
+
+    const proCard = screen.getByTestId("detail-card-crochet-pro");
+    expect(within(proCard).getByText(/everything in free/i)).toBeDefined();
+
+    const freeCard = screen.getByTestId("detail-card-crochet-free");
+    expect(within(freeCard).queryByText(/everything in/i)).toBeNull();
+  });
+});

package/src/components/PricingDetailPage.tsx

@@ -11,6 +11,7 @@
 import React from "react";
 import { useProduct } from "../hooks/useProduct";
 import type { ProductOffer, OfferFeature } from "../types";
+import { cumulativeFeatureLookup, tierBelow } from "../utils/tiers";
 
 export interface PricingDetailPageProps {
   /** Product slug (e.g., "raise-simpli") */
@@ -83,6 +84,7 @@ export function PricingDetailPage({
             key={offer.id}
             offer={offer}
             onSelect={onSelectOffer}
+            buildsOn={tierBelow(product.offers, offer)?.name ?? null}
           />
         ))}
       </div>
@@ -101,9 +103,11 @@ export function PricingDetailPage({
 interface DetailCardProps {
   offer: ProductOffer;
   onSelect?: (offer: ProductOffer) => void;
+  /** Name of the tier just below this one, when there is one. */
+  buildsOn?: string | null;
 }
 
-function DetailCard({ offer, onSelect }: DetailCardProps) {
+function DetailCard({ offer, onSelect, buildsOn }: DetailCardProps) {
   const isFeatured = offer.isFeatured;
 
   return (
@@ -146,6 +150,12 @@ function DetailCard({ offer, onSelect }: DetailCardProps) {
         </span>
       )}
 
+      {buildsOn && (
+        <p className="text-sm font-semibold text-gray-900 mb-1">
+          Everything in {buildsOn}, plus:
+        </p>
+      )}
+
       <ul className="list-none p-0 m-0 mb-7 flex-1 space-y-0">
         {offer.features.map((feature) => (
           <li
@@ -202,14 +212,9 @@ interface ComparisonTableProps {
 }
 
 function ComparisonTable({ offers, featureKeys, featureNameMap }: ComparisonTableProps) {
-  // Build a lookup: offer slug -> feature key -> feature
-  const featureLookup: Record<string, Record<string, OfferFeature>> = {};
-  for (const offer of offers) {
-    featureLookup[offer.slug] = {};
-    for (const feature of offer.features) {
-      featureLookup[offer.slug][feature.key] = feature;
-    }
-  }
+  // offer slug -> feature key -> feature, with cheaper tiers' capabilities
+  // carried upward so a paid plan never shows a dash where free shows a tick.
+  const featureLookup = cumulativeFeatureLookup(offers);
 
   return (
     <div data-testid="comparison-table" className="overflow-x-auto">

package/src/components/PricingSection.test.tsx

@@ -315,4 +315,24 @@ describe("PricingSection", () => {
       expect(screen.getByText(/unable to load/i)).toBeDefined();
     });
   });
+
+  // The home-page cards sit next to /pricing, which says "Everything in Free,
+  // plus:" on the paid tier. Without it, a card that lists only what the tier
+  // ADDS reads as a plan that lost the cheaper tier's features.
+  it("says a paid tier builds on the one below it", async () => {
+    const Wrapper = createWrapper(mockFetchSuccess());
+
+    render(
+      <Wrapper>
+        <PricingSection productId="raise-simpli" />
+      </Wrapper>
+    );
+
+    await waitFor(() => expect(screen.getByTestId("pricing-section")).toBeDefined());
+
+    expect(screen.getAllByText(/everything in starter, plus/i).length).toBeGreaterThan(0);
+    // The cheapest tier has nothing below it.
+    const starter = screen.getByTestId("section-card-starter-monthly");
+    expect(starter.textContent).not.toMatch(/everything in/i);
+  });
 });

package/src/components/PricingSection.tsx

@@ -11,6 +11,7 @@
 import React from "react";
 import { useProduct } from "../hooks/useProduct";
 import type { ProductOffer } from "../types";
+import { tierBelow } from "../utils/tiers";
 
 export interface PricingSectionProps {
   /** Product slug (e.g., "raise-simpli") */
@@ -63,6 +64,7 @@ export function PricingSection({
             offer={offer}
             onSelect={onSelectOffer}
             maxFeatures={maxFeatures}
+            buildsOn={tierBelow(product.offers, offer)?.name ?? null}
           />
         ))}
       </div>
@@ -74,9 +76,11 @@ interface SectionCardProps {
   offer: ProductOffer;
   onSelect?: (offer: ProductOffer) => void;
   maxFeatures: number;
+  /** Name of the tier just below this one, when there is one. */
+  buildsOn?: string | null;
 }
 
-function SectionCard({ offer, onSelect, maxFeatures }: SectionCardProps) {
+function SectionCard({ offer, onSelect, maxFeatures, buildsOn }: SectionCardProps) {
   const isFeatured = offer.isFeatured;
   const visibleFeatures = offer.features.slice(0, maxFeatures);
 
@@ -116,6 +120,12 @@ function SectionCard({ offer, onSelect, maxFeatures }: SectionCardProps) {
         </span>
       )}
 
+      {buildsOn && (
+        <p className="text-sm font-semibold text-gray-900 mb-1">
+          Everything in {buildsOn}, plus:
+        </p>
+      )}
+
       <ul className="list-none p-0 m-0 mb-4 flex-1 space-y-0">
         {visibleFeatures.map((feature) => (
           <li

package/src/utils/api.test.ts

@@ -108,6 +108,201 @@ describe("BillingApiClient", () => {
     });
   });
 
+  // startsim-ol36d.27: a buyer saw "Checkout failed: 400" while Django was
+  // returning a specific reason. The app route proxies through
+  // proxyBillingRequest, which wraps Django's raw error text in an envelope,
+  // so the reason arrives as a JSON *string* under `details`.
+  describe("error messages carry the server's reason", () => {
+    // Captured verbatim from POST https://crochets.site/api/billing/offer-checkout/
+    // (signed in) on 2026-09-17.
+    const LIVE = {
+      bogusOfferUuid:
+        '{"error":"Billing API error","status":400,"details":"{\\"offer_id\\":[\\"Invalid or inactive offer\\"]}"}',
+      malformedOfferId:
+        '{"error":"Billing API error","status":400,"details":"{\\"offer_id\\":[\\"Must be a valid UUID.\\"]}"}',
+      emptyBody:
+        '{"error":"Billing API error","status":400,"details":"{\\"offer_id\\":[\\"This field is required.\\"],\\"success_url\\":[\\"This field is required.\\"],\\"cancel_url\\":[\\"This field is required.\\"]}"}',
+    };
+
+    function failWith(status: number, body: unknown) {
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status,
+        json: () => Promise.resolve(body),
+      });
+    }
+
+    function checkout() {
+      return createClient().createCheckout({
+        offerId: "bad",
+        successUrl: "x",
+        cancelUrl: "y",
+      });
+    }
+
+    it.each([
+      ["bogus offer id", LIVE.bogusOfferUuid, "Offer id: Invalid or inactive offer"],
+      ["malformed offer id", LIVE.malformedOfferId, "Offer id: Must be a valid UUID."],
+      ["empty body (first field wins)", LIVE.emptyBody, "Offer id: This field is required."],
+    ])("unwraps the live proxy envelope: %s", async (_name, raw, expected) => {
+      failWith(400, JSON.parse(raw));
+      await expect(checkout()).rejects.toThrow(new Error(expected));
+    });
+
+    it("unwraps the proxied non_field_errors that caused the original incident", async () => {
+      failWith(400, {
+        error: "Billing API error",
+        status: 400,
+        details: JSON.stringify({
+          non_field_errors: [
+            "BILLING_ALLOWED_REDIRECT_DOMAINS must be configured in production.",
+          ],
+        }),
+      });
+      await expect(checkout()).rejects.toThrow(
+        new Error("BILLING_ALLOWED_REDIRECT_DOMAINS must be configured in production.")
+      );
+    });
+
+    it("unwraps a camelCased body inside the proxy envelope", async () => {
+      failWith(400, {
+        error: "Billing API error",
+        status: 400,
+        details: JSON.stringify({ offerId: ["Invalid or inactive offer"] }),
+      });
+      await expect(checkout()).rejects.toThrow(
+        new Error("Offer id: Invalid or inactive offer")
+      );
+    });
+
+    it.each([
+      ["non_field_errors", { non_field_errors: ["Offer is not purchasable"] }],
+      ["nonFieldErrors", { nonFieldErrors: ["Offer is not purchasable"] }],
+    ])("reads a bare DRF %s array", async (_name, body) => {
+      failWith(400, body);
+      await expect(checkout()).rejects.toThrow(new Error("Offer is not purchasable"));
+    });
+
+    it.each([
+      ["offer_id", { offer_id: ["Invalid or inactive offer"] }],
+      ["offerId", { offerId: ["Invalid or inactive offer"] }],
+    ])("reads a bare DRF field error map keyed %s", async (_name, body) => {
+      failWith(400, body);
+      await expect(checkout()).rejects.toThrow(
+        new Error("Offer id: Invalid or inactive offer")
+      );
+    });
+
+    it("prefers detail over everything else", async () => {
+      failWith(400, {
+        detail: "Offer not synced",
+        non_field_errors: ["other"],
+        offer_id: ["other"],
+      });
+      await expect(checkout()).rejects.toThrow(new Error("Offer not synced"));
+    });
+
+    it("prefers non_field_errors over field errors", async () => {
+      failWith(400, {
+        offer_id: ["field message"],
+        non_field_errors: ["form message"],
+      });
+      await expect(checkout()).rejects.toThrow(new Error("form message"));
+    });
+
+    it.each([
+      [401, { error: "Not authenticated", code: "UNAUTHORIZED" }, "Not authenticated"],
+      [503, { error: "Billing service unavailable", code: "INTERNAL_ERROR" }, "Billing service unavailable"],
+    ])("surfaces an app route's {error, code} body (%i)", async (status, body, expected) => {
+      failWith(status, body);
+      await expect(checkout()).rejects.toThrow(new Error(expected));
+    });
+
+    it("never shows the proxy's generic label or an HTML page", async () => {
+      failWith(502, {
+        error: "Billing API error",
+        status: 502,
+        details: "<html><body><h1>502 Bad Gateway</h1></body></html>",
+      });
+      await expect(checkout()).rejects.toThrow(new Error("Checkout failed: 502"));
+    });
+
+    it("never shows the proxy's network-failure label", async () => {
+      failWith(500, { error: "Internal server error", details: "fetch failed" });
+      await expect(checkout()).rejects.toThrow(new Error("Checkout failed: 500"));
+    });
+
+    it("falls back to the status when the body is not JSON", async () => {
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 400,
+        json: () => Promise.reject(new SyntaxError("Unexpected token <")),
+      });
+      await expect(checkout()).rejects.toThrow(new Error("Checkout failed: 400"));
+    });
+
+    it("falls back to the status when the body has no message", async () => {
+      failWith(400, {});
+      await expect(checkout()).rejects.toThrow(new Error("Checkout failed: 400"));
+    });
+
+    it("applies to subscribeFree", async () => {
+      failWith(400, JSON.parse(LIVE.bogusOfferUuid));
+      await expect(createClient().subscribeFree("bad")).rejects.toThrow(
+        new Error("Offer id: Invalid or inactive offer")
+      );
+      failWith(400, {});
+      await expect(createClient().subscribeFree("bad")).rejects.toThrow(
+        new Error("Free signup failed: 400")
+      );
+    });
+
+    it("applies to createPortal", async () => {
+      failWith(400, {
+        error: "Billing API error",
+        status: 400,
+        details: JSON.stringify({ return_url: ["Enter a valid URL."] }),
+      });
+      await expect(createClient().createPortal("nope")).rejects.toThrow(
+        new Error("Return url: Enter a valid URL.")
+      );
+      failWith(400, {});
+      await expect(createClient().createPortal("nope")).rejects.toThrow(
+        new Error("Portal session failed: 400")
+      );
+    });
+
+    it("applies to successSync", async () => {
+      failWith(400, {
+        error: "Billing API error",
+        status: 400,
+        details: JSON.stringify({ detail: "No checkout session to sync" }),
+      });
+      await expect(createClient().successSync()).rejects.toThrow(
+        new Error("No checkout session to sync")
+      );
+      failWith(500, {});
+      await expect(createClient().successSync()).rejects.toThrow(
+        new Error("Success sync failed: 500")
+      );
+    });
+
+    it("applies to getSubscription", async () => {
+      failWith(403, {
+        error: "Billing API error",
+        status: 403,
+        details: JSON.stringify({ detail: "You are not a member of this team." }),
+      });
+      await expect(createClient().getSubscription("p")).rejects.toThrow(
+        new Error("You are not a member of this team.")
+      );
+      failWith(500, {});
+      await expect(createClient().getSubscription("p")).rejects.toThrow(
+        new Error("Failed to fetch subscription: 500")
+      );
+    });
+  });
+
   describe("createPortal", () => {
     it("sends POST with return_url", async () => {
       mockFetch.mockResolvedValue({

package/src/utils/api.ts

@@ -12,6 +12,7 @@ import type {
   SubscriptionInfo,
   UsageMap,
 } from "../types";
+import { billingErrorMessage } from "./error-message";
 
 export class BillingApiClient {
   private config: BillingConfig;
@@ -60,9 +61,7 @@ export class BillingApiClient {
     });
     if (!resp.ok) {
       const data = await resp.json().catch(() => ({}));
-      throw new Error(
-        data.detail ?? `Checkout failed: ${resp.status}`
-      );
+      throw new Error(billingErrorMessage(data, `Checkout failed: ${resp.status}`));
     }
     return resp.json();
   }
@@ -77,7 +76,7 @@ export class BillingApiClient {
     });
     if (!resp.ok) {
       const data = await resp.json().catch(() => ({}));
-      throw new Error(data.detail ?? `Free signup failed: ${resp.status}`);
+      throw new Error(billingErrorMessage(data, `Free signup failed: ${resp.status}`));
     }
     return resp.json();
   }
@@ -92,9 +91,7 @@ export class BillingApiClient {
     });
     if (!resp.ok) {
       const data = await resp.json().catch(() => ({}));
-      throw new Error(
-        data.detail ?? `Portal session failed: ${resp.status}`
-      );
+      throw new Error(billingErrorMessage(data, `Portal session failed: ${resp.status}`));
     }
     return resp.json();
   }
@@ -114,7 +111,7 @@ export class BillingApiClient {
     }
     if (!resp.ok) {
       const data = await resp.json().catch(() => ({}));
-      throw new Error(data.detail ?? `Success sync failed: ${resp.status}`);
+      throw new Error(billingErrorMessage(data, `Success sync failed: ${resp.status}`));
     }
     return resp.json();
   }
@@ -150,9 +147,7 @@ export class BillingApiClient {
     }
     if (!resp.ok) {
       const data = await resp.json().catch(() => ({}));
-      throw new Error(
-        data.detail ?? `Failed to fetch subscription: ${resp.status}`
-      );
+      throw new Error(billingErrorMessage(data, `Failed to fetch subscription: ${resp.status}`));
     }
     return this.normalizeSubscription(await resp.json());
   }

package/src/utils/error-message.ts

@@ -0,0 +1,111 @@
+/**
+ * Turn a failed billing response body into one human-readable sentence.
+ *
+ * Shapes handled, in priority order:
+ *   { detail: "..." }                                    DRF's standard message
+ *   { error: "Billing API error", details: "<json>" }    proxyBillingRequest's envelope:
+ *                                                        Django's raw error text, as a string
+ *   { non_field_errors: ["..."] } / { nonFieldErrors }   first message
+ *   { offer_id: ["..."] } / { offerId: [...] }           "Offer id: ..." (first field wins)
+ *   { error: "Not authenticated", code: "..." }          app routes' own errors
+ *   { error: { message: "..." } }                        (also app routes)
+ *
+ * Anything else (HTML error pages, the proxy's generic labels, empty bodies)
+ * yields `fallback`, so the user never sees raw JSON or markup.
+ */
+
+// Labels proxyBillingRequest writes itself. They say that something failed,
+// never why, so they must not be shown in place of the fallback.
+const PROXY_LABELS = new Set(["Billing API error", "Internal server error"]);
+
+const NON_FIELD_KEYS = new Set(["non_field_errors", "nonFieldErrors"]);
+
+const META_KEYS = new Set([
+  "detail",
+  "details",
+  "error",
+  "message",
+  "code",
+  "status",
+  "statusCode",
+  "timestamp",
+]);
+
+export function billingErrorMessage(body: unknown, fallback: string): string {
+  return messageFrom(body) ?? fallback;
+}
+
+function messageFrom(body: unknown): string | null {
+  if (Array.isArray(body)) return firstString(body);
+  if (!body || typeof body !== "object") return null;
+  const d = body as Record<string, unknown>;
+
+  const detail = typeof d.detail === "string" ? text(d.detail) : messageFrom(d.detail);
+  if (detail) return detail;
+
+  // The envelope carries Django's body as text. Only JSON is worth reading:
+  // plain text here is an HTML error page or a network error string.
+  if (typeof d.details === "string") {
+    const inner = messageFrom(parseJson(d.details));
+    if (inner) return inner;
+  } else {
+    const inner = messageFrom(d.details);
+    if (inner) return inner;
+  }
+
+  for (const key of NON_FIELD_KEYS) {
+    const s = firstString(d[key]);
+    if (s) return s;
+  }
+
+  for (const [key, val] of Object.entries(d)) {
+    if (META_KEYS.has(key) || NON_FIELD_KEYS.has(key)) continue;
+    // DRF field errors are always lists (or nested serializer maps); a scalar
+    // here is data, not an error.
+    if (!val || typeof val !== "object") continue;
+    const s = Array.isArray(val) ? firstString(val) : messageFrom(val);
+    if (s) return `${fieldLabel(key)}: ${s}`;
+  }
+
+  for (const key of ["message", "error"]) {
+    const val = d[key];
+    const s = typeof val === "string" ? text(val) : messageFrom(val);
+    if (s && !PROXY_LABELS.has(s)) return s;
+  }
+  return null;
+}
+
+function firstString(val: unknown): string | null {
+  if (typeof val === "string") return text(val);
+  if (!Array.isArray(val)) return null;
+  for (const item of val) {
+    const s = typeof item === "string" ? text(item) : messageFrom(item);
+    if (s) return s;
+  }
+  return null;
+}
+
+function text(s: string): string | null {
+  const t = s.trim();
+  return t ? t : null;
+}
+
+function parseJson(s: string): unknown {
+  const t = s.trim();
+  if (!t.startsWith("{") && !t.startsWith("[")) return null;
+  try {
+    return JSON.parse(t);
+  } catch {
+    return null;
+  }
+}
+
+/** "offer_id" / "offerId" → "Offer id" */
+function fieldLabel(key: string): string {
+  const words = key
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/_+/g, " ")
+    .trim()
+    .toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}

package/src/utils/tiers.ts

@@ -0,0 +1,55 @@
+/**
+ * How plan tiers relate to each other.
+ *
+ * Shared by the pricing cards and the comparison table so both read the offer
+ * data the same way — they disagreed before, and the table was the one that
+ * showed a paid plan as missing what the free plan had.
+ */
+import type { ProductOffer, OfferFeature } from "../types";
+/**
+ * Plans are cumulative: a paid tier includes what the cheaper tier includes.
+ *
+ * Offer data in the wild only lists what a tier ADDS — crochet-pro declares its
+ * advanced features and omits the "Save patterns" that crochet-free declares.
+ * Rendering that omission as "not included" put a dash on the paid plan exactly
+ * where the free plan had a tick, so the expensive plan looked WORSE.
+ *
+ * So a capability (`value === true`) established by a cheaper tier carries up
+ * into dearer ones. Two things deliberately do not carry:
+ *  - an explicit `false`, which is how a tier opts out and stops the carry; and
+ *  - numbers and strings, because an allowance is not a capability. Inheriting
+ *    the free plan's "3 patterns" onto Pro would state something untrue; a tier
+ *    has to declare its own allowance or say nothing.
+ */
+export function cumulativeFeatureLookup(
+  offers: ProductOffer[],
+): Record<string, Record<string, OfferFeature>> {
+  const cheapestFirst = [...offers].sort((a, b) => a.sortOrder - b.sortOrder);
+  const lookup: Record<string, Record<string, OfferFeature>> = {};
+  const carried: Record<string, OfferFeature> = {};
+
+  for (const offer of cheapestFirst) {
+    const own: Record<string, OfferFeature> = {};
+    for (const feature of offer.features) own[feature.key] = feature;
+
+    // Own declarations always win over anything inherited.
+    lookup[offer.slug] = { ...carried, ...own };
+
+    for (const feature of offer.features) {
+      if (feature.value === true) carried[feature.key] = feature;
+      // Anything else ends the run, so a tier that opts out does not have the
+      // capability silently handed back to the tier above it.
+      else delete carried[feature.key];
+    }
+  }
+
+  return lookup;
+}
+
+/** The tier immediately below each offer, for the "Everything in X" line. */
+export function tierBelow(offers: ProductOffer[], offer: ProductOffer): ProductOffer | null {
+  const cheapestFirst = [...offers].sort((a, b) => a.sortOrder - b.sortOrder);
+  const index = cheapestFirst.findIndex((o) => o.slug === offer.slug);
+  const below = index > 0 ? cheapestFirst[index - 1] : null;
+  return below && below.features.length > 0 ? below : null;
+}