@startsimpli/billing 0.4.14 → 0.4.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -18,15 +18,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "type-check": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "clean": "rm -rf dist"
-  },
   "peerDependencies": {
     "next": ">=14.0.0",
     "react": "^18.0.0 || ^19.0.0",
@@ -54,5 +45,14 @@
     "nextjs",
     "django",
     "startsimpli"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist"
+  }
+}

package/src/__tests__/theme-contract.test.ts

@@ -0,0 +1,40 @@
+/**
+ * Theme-contract guard for @startsimpli/billing (startsim-1f3n.3).
+ *
+ * Shared components may only use the semantic tokens from
+ * packages/ui/theme/contract.css. The numeric Tailwind ramp
+ * (`bg-primary-600`, `focus:ring-primary-500`, …) is not part of it — an app
+ * that declares `--color-primary` without a ramp gets NO rule for those
+ * classes, which renders a plan card border as invisible white-on-white.
+ * Use an opacity modifier on the token instead (`hover:bg-primary/90`).
+ */
+import * as fs from 'fs'
+import * as path from 'path'
+import { describe, it, expect } from 'vitest'
+
+const SRC = path.resolve(__dirname, '..')
+const RAMP = /\b[a-z-]*-(primary|accent|secondary)-\d{2,3}\b/
+
+function sources(dir: string, acc: string[] = []): string[] {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name)
+    if (e.isDirectory()) {
+      if (e.name !== '__tests__' && e.name !== 'node_modules') sources(full, acc)
+    } else if (/\.tsx?$/.test(e.name)) acc.push(full)
+  }
+  return acc
+}
+
+describe('@startsimpli/billing theme contract', () => {
+  it('no component styles against a numeric color ramp', () => {
+    const offenders: string[] = []
+    for (const file of sources(SRC)) {
+      fs.readFileSync(file, 'utf8').split('\n').forEach((line, i) => {
+        const code = line.replace(/^\s*(\*|\/\/).*$/, '')
+        const hit = code.match(RAMP)
+        if (hit) offenders.push(`${path.relative(SRC, file)}:${i + 1} ${hit[0]}`)
+      })
+    }
+    expect(offenders).toEqual([])
+  })
+})

package/src/components/SubscriptionManager.test.tsx

@@ -14,7 +14,7 @@
  */
 
 import { describe, it, expect, vi } from "vitest";
-import { render, screen, waitFor } from "@testing-library/react";
+import { render, screen, waitFor, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import React from "react";
 import { BillingProvider } from "../hooks/BillingProvider";
@@ -1212,4 +1212,71 @@ describe("SubscriptionManager", () => {
     // strictly above proCurrent.offer.sortOrder=1.
     expect(upgrade?.textContent).toMatch(/upgrade to enterprise/i);
   });
+
+  // Regression: the subscription/current endpoint's Redis cache path returns a
+  // FLAT payload (offerId/offerSlug/productSlug, NO nested `offer`). The UI used
+  // to deref `subscription.offer.isFree` and white-screen ("client-side
+  // exception"). BillingApiClient now hydrates the offer from the product, so
+  // the rich CurrentPlanCard renders instead. startsim — billing-offer-null.
+  it("hydrates the flat cache-shape subscription payload instead of crashing", async () => {
+    const flatCachePayload = {
+      // Shape of CachedSubscriptionResponseSerializer after the camelCase proxy:
+      subscriptionId: "sub-cache-1",
+      providerSubscriptionId: "stripe_sub_1",
+      status: "active",
+      customerId: "cus_1",
+      priceId: "price_1",
+      offerId: "offer-2", // Pro
+      productSlug: "raise-simpli",
+      offerSlug: "pro-monthly",
+      currentPeriodStart: 1735689600, // unix seconds, not ISO
+      currentPeriodEnd: 1738368000,
+      cancelAtPeriodEnd: false,
+      trialEnd: null,
+      paymentMethod: null,
+    };
+    const fetcher = mockFetchRouter({
+      "/billing/subscription/current/": flatCachePayload,
+      "/billing/products/": mockProduct,
+    });
+    const Wrapper = createWrapper(fetcher);
+
+    render(
+      <Wrapper>
+        <SubscriptionManager productId="raise-simpli" returnUrl="https://t/s" />
+      </Wrapper>
+    );
+
+    // Renders the rich current-plan card (Pro) — proves no crash AND that the
+    // offer was hydrated from the product rather than dropped.
+    await waitFor(() => expect(screen.getByTestId("current-plan")).toBeDefined());
+    const card = screen.getByTestId("current-plan");
+    expect(within(card).getByText("Pro")).toBeDefined();
+    // Active paid sub → "Next billing date" derived from the unix-seconds period.
+    expect(within(card).getByTestId("next-billing-date")).toBeDefined();
+  });
+
+  it("degrades to 'no active subscription' when a flat payload can't resolve an offer", async () => {
+    const fetcher = mockFetchRouter({
+      "/billing/subscription/current/": {
+        status: "active",
+        offerId: "does-not-exist",
+        offerSlug: "ghost",
+        productSlug: "raise-simpli",
+      },
+      "/billing/products/": mockProduct,
+    });
+    const Wrapper = createWrapper(fetcher);
+
+    render(
+      <Wrapper>
+        <SubscriptionManager productId="raise-simpli" returnUrl="https://t/s" />
+      </Wrapper>
+    );
+
+    // No crash; falls through to the empty-state copy.
+    await waitFor(() =>
+      expect(screen.getByText("No active subscription")).toBeDefined()
+    );
+  });
 });

package/src/components/SubscriptionManager.tsx

@@ -228,8 +228,13 @@ export function SubscriptionManager({
     );
   }
 
-  const currentOfferId = subscription?.offer?.id ?? null;
-  const currentOffer = subscription?.offer ?? null;
+  // A subscription is only renderable if it carries a nested `offer` object —
+  // the cache-path payload (offerId/offerSlug, no `offer`) is normalized away in
+  // BillingApiClient, but guard here too so CurrentPlanCard can never deref
+  // `subscription.offer.*` on undefined and white-screen the page.
+  const usableSubscription = subscription?.offer ? subscription : null;
+  const currentOfferId = usableSubscription?.offer?.id ?? null;
+  const currentOffer = usableSubscription?.offer ?? null;
   // Show ALL offers in the Change Plan grid (not just non-current ones) so users
   // can compare and see what they have. The card matching their current sub
   // gets a "Current Plan" badge + disabled CTA. startsim-1f1.
@@ -339,30 +344,30 @@ export function SubscriptionManager({
         </div>
       )}
 
-      {subscription ? (
+      {usableSubscription ? (
         <>
           {/* Non-owner team members get a clear read-only callout. The OWNER
               gates that follow (Upgrade CTA, portal button, plan-change CTAs)
               all flip off when viewerIsOwner === false. startsim-wo9. */}
-          {subscription.viewerIsOwner === false && (
+          {usableSubscription.viewerIsOwner === false && (
             <div
               data-testid="non-owner-billing-notice"
               className="rounded-lg border border-blue-100 bg-blue-50 p-4 text-sm text-blue-900"
               role="status"
             >
               You&apos;re viewing your team&apos;s billing.{" "}
-              {subscription.ownerEmail
-                ? <>The team owner <span className="font-medium">{subscription.ownerEmail}</span> manages plan changes.</>
+              {usableSubscription.ownerEmail
+                ? <>The team owner <span className="font-medium">{usableSubscription.ownerEmail}</span> manages plan changes.</>
                 : <>The team owner manages plan changes.</>
               }
             </div>
           )}
           <CurrentPlanCard
-            subscription={subscription}
+            subscription={usableSubscription}
             usage={usage}
-            onPortalClick={subscription.viewerIsOwner === false ? undefined : handlePortalClick}
+            onPortalClick={usableSubscription.viewerIsOwner === false ? undefined : handlePortalClick}
             upgradeCta={
-              subscription.viewerIsOwner !== false && subscription.offer.isFree && featuredPaidOffer ? (
+              usableSubscription.viewerIsOwner !== false && usableSubscription.offer.isFree && featuredPaidOffer ? (
                 <button
                   data-testid="upgrade-cta-current-plan"
                   onClick={() => handleOfferClick(featuredPaidOffer)}
@@ -428,7 +433,7 @@ export function SubscriptionManager({
 
               // Border: current = solid ring; featured upgrade = blue; else gray.
               const cardBorder =
-                isCurrent ? "border-2 border-primary-600 ring-2 ring-primary-100 bg-white shadow-md"
+                isCurrent ? "border-2 border-primary ring-2 ring-primary/20 bg-white shadow-md"
                 : offer.isFeatured ? "border border-blue-600 shadow-md bg-white"
                 : "border border-gray-200 bg-white shadow-sm";
 
@@ -452,7 +457,7 @@ export function SubscriptionManager({
                   {isCurrent && (
                     <span
                       data-testid={`current-plan-badge-${offer.slug}`}
-                      className="absolute -top-2.5 right-4 inline-block bg-primary-600 text-white text-xs font-bold uppercase tracking-wide px-2.5 py-0.5 rounded-full"
+                      className="absolute -top-2.5 right-4 inline-block bg-primary text-primary-foreground text-xs font-bold uppercase tracking-wide px-2.5 py-0.5 rounded-full"
                     >
                       Current Plan
                     </span>
@@ -501,7 +506,7 @@ export function SubscriptionManager({
           Free-tier users (provider='none') have no Stripe customer, so the
           portal call would 404 — they get the Upgrade CTA on the current-plan
           card instead. startsim-b1z. */}
-      {subscription && subscription.status !== "cancelled" && !subscription.offer.isFree && subscription.viewerIsOwner !== false && (
+      {usableSubscription && usableSubscription.status !== "cancelled" && !usableSubscription.offer.isFree && usableSubscription.viewerIsOwner !== false && (
         <div className="pt-4 border-t border-gray-100">
           <button
             data-testid="portal-button"

package/src/utils/api.ts

@@ -149,6 +149,61 @@ export class BillingApiClient {
         data.detail ?? `Failed to fetch subscription: ${resp.status}`
       );
     }
-    return resp.json();
+    return this.normalizeSubscription(await resp.json());
+  }
+
+  /**
+   * The `subscription/current/` endpoint is polymorphic: the DB path returns
+   * the rich SubscriptionInfo (nested `offer` object), but the Redis cache path
+   * returns the flat CachedSubscriptionState (offerId/offerSlug/productSlug, no
+   * nested `offer`). The UI reads `subscription.offer.*` unconditionally, so a
+   * flat payload white-screens the page. This guard hydrates the flat shape
+   * into the rich one by resolving the offer from the product; if it can't, it
+   * returns null ("no usable subscription") rather than letting the page crash.
+   * Defense-in-depth against backend contract drift. startsim — billing-offer-null.
+   */
+  private async normalizeSubscription(raw: unknown): Promise<SubscriptionInfo | null> {
+    if (!raw || typeof raw !== "object") return null;
+    const r = raw as Record<string, unknown>;
+
+    // Already the rich shape — nested offer object present.
+    if (r.offer && typeof r.offer === "object") return raw as SubscriptionInfo;
+
+    // Flat cache shape: try to hydrate the offer from the product.
+    const productSlug = r.productSlug as string | undefined;
+    const offerId = r.offerId as string | undefined;
+    const offerSlug = r.offerSlug as string | undefined;
+    const status = r.status as string | undefined;
+    // No status or nothing to resolve an offer from → not a renderable sub.
+    if (!status || status === "none" || !productSlug || (!offerId && !offerSlug)) {
+      return null;
+    }
+
+    try {
+      const product = await this.getProduct(productSlug);
+      const offer = product.offers.find(
+        (o) => (offerId && o.id === offerId) || (offerSlug && o.slug === offerSlug)
+      );
+      if (!offer) return null;
+      const toIso = (v: unknown): string | null => {
+        if (v == null) return null;
+        // Cache stores unix seconds; SubscriptionInfo expects ISO strings.
+        if (typeof v === "number") return new Date(v * 1000).toISOString();
+        if (typeof v === "string") return v;
+        return null;
+      };
+      return {
+        id: (r.subscriptionId as string) ?? offer.id,
+        offer,
+        status: status as SubscriptionInfo["status"],
+        currentPeriodStart: toIso(r.currentPeriodStart),
+        currentPeriodEnd: toIso(r.currentPeriodEnd),
+        cancelAtPeriodEnd: Boolean(r.cancelAtPeriodEnd),
+        trialEnd: toIso(r.trialEnd),
+      };
+    } catch {
+      // Product fetch failed — degrade to "no subscription" instead of crashing.
+      return null;
+    }
   }
 }