@startsimpli/billing 0.4.16 → 0.4.18

package/README.md

@@ -207,14 +207,14 @@ BILLING_USAGE_ADAPTERS = {
 | `PricingPage` / `PricingSection` / `PricingDetailPage` | Pre-billing display surfaces. | For marketing / landing pages. |
 | `UpgradeModal` | Modal pricing overlay. | For mid-flow upgrade prompts. |
 | `ManageSubscription` | Bare portal redirect button. | Use `SubscriptionManager` instead unless you really just want the button. |
-| `PlanGate` | Feature-gate wrapper. | Show / hide children based on the user's offer features. |
+| `PlanGate` | Feature-gate wrapper. | Show / hide children based on the user's offer features. Pass `productId`, or a paid plan on another product opens the gate. |
 
 ### Hooks
 
 | Hook | Returns | Notes |
 |---|---|---|
 | `useProduct(slug)` | `{ product, loading, error, refetch }` | Fetch product + offers |
-| `useSubscription()` | `{ subscription, loading, error, refetch }` | Current sub incl. `viewerIsOwner` + `ownerEmail` |
+| `useSubscription(productId)` | `{ subscription, loading, error, refetch }` | Current sub for that product, incl. `viewerIsOwner` + `ownerEmail`. Always pass the product: without it the newest sub for ANY product comes back. |
 | `useUsage(slug)` | `{ usage, loading, error, refetch }` | `{feature_key: {used, limit}}` map; auto-refetches on `visibilitychange` + `billing:usage-changed` event |
 | `useCheckout()` | `{ checkout, subscribeFree, loading, error }` | Stripe session creator + free-subscribe in one |
 | `usePortal()` | `{ openPortal, loading, error }` | Stripe customer portal session |

package/package.json

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

package/src/components/PlanGate.test.tsx

@@ -130,4 +130,28 @@ describe("PlanGate", () => {
       expect(screen.getAllByText(/paid plan|upgrade/i).length).toBeGreaterThan(0)
     );
   });
+
+  it("gates on the given product's subscription only (startsim-oyr3a.2)", async () => {
+    const fetcher = vi.fn(async () => ({
+      ok: false,
+      status: 404,
+      async json() {
+        return {};
+      },
+    })) as unknown as typeof fetch;
+
+    render(
+      <BillingProvider apiBaseUrl="/api" fetcher={fetcher}>
+        <PlanGate productId="crochet-patterns" fallback={<span>upgrade</span>}>
+          <span>pro feature</span>
+        </PlanGate>
+      </BillingProvider>
+    );
+
+    await waitFor(() => expect(screen.getByText("upgrade")).toBeDefined());
+    expect(fetcher).toHaveBeenCalledWith(
+      "/api/billing/subscription/current/?product=crochet-patterns",
+      expect.anything()
+    );
+  });
 });

package/src/components/PlanGate.tsx

@@ -6,6 +6,11 @@ import { isPaidSubscription } from "../utils/plan";
 
 export interface PlanGateProps {
   children: React.ReactNode;
+  /**
+   * The app's product slug. Without it, a paid plan on ANY product opens the
+   * gate (startsim-oyr3a.2).
+   */
+  productId?: string;
   /**
    * Element rendered in place of children when user is not on a paid plan.
    * Defaults to a minimal upgrade nudge pointing at /pricing.
@@ -40,8 +45,9 @@ export function PlanGate({
   children,
   fallback,
   upgradeHref = "/pricing",
+  productId,
 }: PlanGateProps) {
-  const { subscription, loading } = useSubscription();
+  const { subscription, loading } = useSubscription(productId);
 
   if (loading) return <>{children}</>;
 

package/src/components/SubscriptionManager.test.tsx

@@ -1279,4 +1279,28 @@ describe("SubscriptionManager", () => {
       expect(screen.getByText("No active subscription")).toBeDefined()
     );
   });
+
+  it("asks only for its own product's subscription (startsim-oyr3a.2)", async () => {
+    const fetcher = mockFetchRouter({
+      "/billing/subscription/current/": null,
+      "/billing/products/": mockProduct,
+    });
+    const Wrapper = createWrapper(fetcher);
+
+    render(
+      <Wrapper>
+        <SubscriptionManager
+          productId="raise-simpli"
+          returnUrl="https://app.test.com/settings"
+        />
+      </Wrapper>
+    );
+
+    await waitFor(() =>
+      expect(fetcher).toHaveBeenCalledWith(
+        "https://api.test.com/api/v1/billing/subscription/current/?product=raise-simpli",
+        expect.anything()
+      )
+    );
+  });
 });

package/src/components/SubscriptionManager.tsx

@@ -172,7 +172,7 @@ export function SubscriptionManager({
   onPlanChange,
   statusMessage,
 }: SubscriptionManagerProps) {
-  const { subscription, loading: subLoading, error: subError, refetch: refetchSubscription } = useSubscription();
+  const { subscription, loading: subLoading, error: subError, refetch: refetchSubscription } = useSubscription(productId);
   const { product, loading: productLoading, error: productError, refetch: refetchProduct } = useProduct(productId);
   const { openPortal, loading: portalLoading } = usePortal();
   const { subscribeFree } = useCheckout();

package/src/hooks/useSubscription.test.tsx

@@ -88,6 +88,24 @@ describe("useSubscription", () => {
     );
   });
 
+  it("asks only for the given product's subscription (startsim-oyr3a.2)", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockSubscription),
+    });
+    const wrapper = createWrapper(mockFetch as unknown as typeof fetch);
+
+    const { result } = renderHook(() => useSubscription("crochet-patterns"), { wrapper });
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://api.test.com/api/v1/billing/subscription/current/?product=crochet-patterns",
+      expect.anything()
+    );
+  });
+
   it("returns null when no subscription exists (404)", async () => {
     const mockFetch = vi.fn().mockResolvedValue({
       ok: false,

package/src/hooks/useSubscription.ts

@@ -1,5 +1,8 @@
 /**
  * useSubscription — Fetch current user's active subscription.
+ *
+ * Pass the app's product slug so another app's plan is never returned
+ * (startsim-oyr3a.2).
  */
 
 import { useCallback, useEffect, useState } from "react";
@@ -13,7 +16,7 @@ interface UseSubscriptionResult {
   refetch: () => void;
 }
 
-export function useSubscription(): UseSubscriptionResult {
+export function useSubscription(productId?: string): UseSubscriptionResult {
   const { client } = useBillingContext();
   const [subscription, setSubscription] = useState<SubscriptionInfo | null>(null);
   const [loading, setLoading] = useState(true);
@@ -23,14 +26,14 @@ export function useSubscription(): UseSubscriptionResult {
     setLoading(true);
     setError(null);
     try {
-      const data = await client.getSubscription();
+      const data = await client.getSubscription(productId);
       setSubscription(data);
     } catch (e) {
       setError(e instanceof Error ? e : new Error(String(e)));
     } finally {
       setLoading(false);
     }
-  }, [client]);
+  }, [client, productId]);
 
   useEffect(() => {
     fetchSubscription();

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();
   }
@@ -134,9 +131,14 @@ export class BillingApiClient {
     return (await resp.json()) as UsageMap;
   }
 
-  /** Get current user's subscription. */
-  async getSubscription(): Promise<SubscriptionInfo | null> {
-    const url = `${this.config.apiBaseUrl}/billing/subscription/current/`;
+  /**
+   * Get current user's subscription. Pass the app's product slug: a team can
+   * hold subscriptions to several products, and without it the backend returns
+   * the newest one for ANY product (startsim-oyr3a.2).
+   */
+  async getSubscription(productSlug?: string): Promise<SubscriptionInfo | null> {
+    const query = productSlug ? `?product=${encodeURIComponent(productSlug)}` : "";
+    const url = `${this.config.apiBaseUrl}/billing/subscription/current/${query}`;
     const resp = await this.fetcher(url, {
       headers: this.headers,
     });
@@ -145,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);
+}