@startsimpli/billing 0.4.17 → 0.4.18

package/package.json

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

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