@startsimpli/billing 0.4.8 → 0.4.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -32,20 +32,20 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.0.0",
-    "@testing-library/react": "^16.0.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^20.17.14",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "@vitest/ui": "^3.0.0",
-    "jsdom": "^25.0.0",
-    "next": "^15.5.12",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "@types/node": "^20.19.39",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/ui": "^4.1.5",
+    "jsdom": "^29.0.2",
+    "next": "^15.5.15",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
     "tsup": "^8.5.1",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
   "keywords": [
     "billing",

package/src/components/PlanGate.test.tsx

@@ -0,0 +1,133 @@
+/**
+ * Contract tests for PlanGate (bead my0e).
+ *
+ * PlanGate renders children only when the current user has an active paid
+ * subscription. Optimistic render while loading (no layout shift), then
+ * either the children or the fallback once the subscription resolves.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import React from "react";
+import { BillingProvider } from "../hooks/BillingProvider";
+import { PlanGate } from "./PlanGate";
+import type { SubscriptionInfo } from "../types";
+
+function makeSub(overrides: Partial<SubscriptionInfo> = {}): SubscriptionInfo {
+  return {
+    id: "sub-1",
+    offer: {
+      id: "offer-1",
+      name: "Pro",
+      slug: "pro",
+      unitPrice: "19.00",
+      currency: "usd",
+      pricingModel: "flat",
+      intervalUnit: "month",
+      intervalCount: 1,
+      intervalDisplay: "monthly",
+      isRecurring: true,
+      isFree: false,
+      features: [],
+      isActive: true,
+      isFeatured: false,
+      trialDays: 0,
+    },
+    status: "active",
+    currentPeriodStart: null,
+    currentPeriodEnd: null,
+    cancelAtPeriodEnd: false,
+    trialEnd: null,
+    ...overrides,
+  } as SubscriptionInfo;
+}
+
+/**
+ * Render PlanGate inside a BillingProvider with a controllable fetcher.
+ * Returns a `resolveSubscription` fn the test can call to settle the fetch.
+ */
+function renderWithSubscription(
+  planGate: React.ReactElement,
+  responseBuilder: () => Promise<SubscriptionInfo | null>
+) {
+  const fetcher = vi.fn(async () => ({
+    ok: true,
+    status: 200,
+    async json() {
+      return await responseBuilder();
+    },
+  })) as unknown as typeof fetch;
+
+  return render(
+    <BillingProvider apiBaseUrl="/api" fetcher={fetcher}>
+      {planGate}
+    </BillingProvider>
+  );
+}
+
+describe("PlanGate", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("optimistically renders children while subscription is loading", () => {
+    let resolveFn!: (v: SubscriptionInfo | null) => void;
+    const pending = new Promise<SubscriptionInfo | null>((resolve) => {
+      resolveFn = resolve;
+    });
+
+    renderWithSubscription(
+      <PlanGate>
+        <span>feature content</span>
+      </PlanGate>,
+      () => pending
+    );
+
+    // Content renders immediately during the loading window
+    expect(screen.getByText("feature content")).toBeDefined();
+
+    // Resolve the promise so the test doesn't leak
+    resolveFn(null);
+  });
+
+  it("renders fallback once resolved with a free/no plan", async () => {
+    renderWithSubscription(
+      <PlanGate fallback={<span>upgrade</span>}>
+        <span>feature content</span>
+      </PlanGate>,
+      async () => null
+    );
+
+    await waitFor(() => expect(screen.getByText("upgrade")).toBeDefined());
+    expect(screen.queryByText("feature content")).toBeNull();
+  });
+
+  it("renders children once resolved with an active paid subscription", async () => {
+    renderWithSubscription(
+      <PlanGate fallback={<span>upgrade</span>}>
+        <span>feature content</span>
+      </PlanGate>,
+      async () => makeSub({ status: "active" })
+    );
+
+    await waitFor(() =>
+      expect(screen.getByText("feature content")).toBeDefined()
+    );
+    expect(screen.queryByText("upgrade")).toBeNull();
+  });
+
+  it("renders default upgrade nudge when no fallback prop is provided", async () => {
+    renderWithSubscription(
+      <PlanGate>
+        <span>feature content</span>
+      </PlanGate>,
+      async () => null
+    );
+
+    // Default nudge mentions "paid plan" and has an upgrade affordance.
+    // Exact copy is allowed to evolve but the semantics must remain.
+    await waitFor(() =>
+      expect(screen.getAllByText(/paid plan|upgrade/i).length).toBeGreaterThan(0)
+    );
+  });
+});

package/src/components/PlanGate.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import React from "react";
+import { useSubscription } from "../hooks/useSubscription";
+import { isPaidSubscription } from "../utils/plan";
+
+export interface PlanGateProps {
+  children: React.ReactNode;
+  /**
+   * Element rendered in place of children when user is not on a paid plan.
+   * Defaults to a minimal upgrade nudge pointing at /pricing.
+   */
+  fallback?: React.ReactNode;
+  /**
+   * Path to send users to when they click the default nudge. Ignored if
+   * `fallback` is provided.
+   */
+  upgradeHref?: string;
+}
+
+function DefaultUpgradeNudge({ upgradeHref }: { upgradeHref: string }) {
+  return (
+    <div className="flex items-center gap-2 rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-sm text-amber-800">
+      <span>This feature requires a paid plan.</span>
+      <a href={upgradeHref} className="font-medium underline hover:no-underline">
+        Upgrade
+      </a>
+    </div>
+  );
+}
+
+/**
+ * Renders children only when the current user has an active paid subscription.
+ * While loading, renders children optimistically to avoid layout shift.
+ * On free/no plan, renders the upgrade nudge (or a custom fallback).
+ *
+ * Must be used inside a `<BillingProvider>`.
+ */
+export function PlanGate({
+  children,
+  fallback,
+  upgradeHref = "/pricing",
+}: PlanGateProps) {
+  const { subscription, loading } = useSubscription();
+
+  if (loading) return <>{children}</>;
+
+  if (isPaidSubscription(subscription)) {
+    return <>{children}</>;
+  }
+
+  return <>{fallback ?? <DefaultUpgradeNudge upgradeHref={upgradeHref} />}</>;
+}

package/src/components/index.ts

@@ -10,3 +10,5 @@ export { ManageSubscription } from "./ManageSubscription";
 export type { ManageSubscriptionProps } from "./ManageSubscription";
 export { SubscriptionManager } from "./SubscriptionManager";
 export type { SubscriptionManagerProps } from "./SubscriptionManager";
+export { PlanGate } from "./PlanGate";
+export type { PlanGateProps } from "./PlanGate";

package/src/index.ts

@@ -36,7 +36,7 @@ export type {
 } from "./types";
 
 // Components
-export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager } from "./components";
+export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager, PlanGate } from "./components";
 export type {
   PricingPageProps,
   PricingSectionProps,
@@ -44,7 +44,11 @@ export type {
   UpgradeModalProps,
   ManageSubscriptionProps,
   SubscriptionManagerProps,
+  PlanGateProps,
 } from "./components";
 
 // API client (for advanced usage)
 export { BillingApiClient } from "./utils/api";
+
+// Pure helpers
+export { isPaidSubscription } from "./utils/plan";

package/src/server/index.ts

@@ -1,2 +1,2 @@
-export { camelToSnake, proxyBillingRequest, fetchDjangoServiceToken } from './proxy';
+export { camelToSnake, snakeToCamel, proxyBillingRequest, fetchDjangoServiceToken } from './proxy';
 export type { BillingProxyOptions, DjangoServiceTokenOptions } from './proxy';

package/src/server/proxy.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { snakeToCamel, camelToSnake, proxyBillingRequest } from './proxy';
+
+describe('snakeToCamel', () => {
+  it('converts snake_case keys to camelCase recursively', () => {
+    const input = {
+      unit_price: '9.00',
+      is_free: false,
+      nested_obj: { interval_display: 'per month', is_recurring: true },
+      list_of_things: [{ cta_text: 'Get Started' }],
+    };
+    expect(snakeToCamel(input)).toEqual({
+      unitPrice: '9.00',
+      isFree: false,
+      nestedObj: { intervalDisplay: 'per month', isRecurring: true },
+      listOfThings: [{ ctaText: 'Get Started' }],
+    });
+  });
+
+  it('leaves string values untouched even when they contain underscores', () => {
+    expect(snakeToCamel({ feature_key: 'patterns_per_month' })).toEqual({
+      featureKey: 'patterns_per_month',
+    });
+  });
+
+  it('is idempotent for camelCase keys', () => {
+    const input = { alreadyCamel: true, nested: { stillCamel: 1 } };
+    expect(snakeToCamel(input)).toEqual(input);
+  });
+
+  it('is the inverse of camelToSnake', () => {
+    const camel = { unitPrice: '9.00', isFree: true, nested: { ctaText: 'Go' } };
+    expect(snakeToCamel(camelToSnake(camel))).toEqual(camel);
+  });
+});
+
+describe('proxyBillingRequest with fromSnake option', () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    globalThis.fetch = vi.fn();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('transforms snake_case response to camelCase when fromSnake is true', async () => {
+    (globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ unit_price: '9.00', is_free: false, offers: [{ cta_text: 'Go' }] }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } }
+      )
+    );
+
+    const response = await proxyBillingRequest(
+      'http://django',
+      '/api/v1/billing/products/x/',
+      undefined,
+      { public: true, fromSnake: true }
+    );
+    const body = await response.json();
+    expect(body).toEqual({
+      unitPrice: '9.00',
+      isFree: false,
+      offers: [{ ctaText: 'Go' }],
+    });
+  });
+
+  it('leaves response untouched when no transform option is set', async () => {
+    (globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce(
+      new Response(JSON.stringify({ alreadyCamel: true }), { status: 200 })
+    );
+
+    const response = await proxyBillingRequest('http://django', '/path/', 'token');
+    const body = await response.json();
+    expect(body).toEqual({ alreadyCamel: true });
+  });
+
+  it('preserves non-OK status and error shape', async () => {
+    (globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce(
+      new Response('Not found', { status: 404 })
+    );
+
+    const response = await proxyBillingRequest(
+      'http://django',
+      '/x/',
+      undefined,
+      { public: true, fromSnake: true }
+    );
+    expect(response.status).toBe(404);
+  });
+});

package/src/server/proxy.ts

@@ -87,11 +87,31 @@ export function camelToSnake(obj: unknown): unknown {
   return obj;
 }
 
+/**
+ * Recursively converts snake_case object keys to camelCase.
+ * Used for Django endpoints that bypass the camel-case middleware
+ * (e.g. public product endpoints) so consumers always receive camelCase.
+ */
+export function snakeToCamel(obj: unknown): unknown {
+  if (Array.isArray(obj)) return obj.map(snakeToCamel);
+  if (obj !== null && typeof obj === 'object') {
+    return Object.fromEntries(
+      Object.entries(obj as Record<string, unknown>).map(([k, v]) => [
+        k.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase()),
+        snakeToCamel(v),
+      ])
+    );
+  }
+  return obj;
+}
+
 export interface BillingProxyOptions {
   method?: string;
   body?: unknown;
   /** If true, apply camelToSnake transform to the response body */
   normalize?: boolean;
+  /** If true, apply snakeToCamel transform to the response body */
+  fromSnake?: boolean;
   /** If true, skip Authorization header even when accessToken is provided */
   public?: boolean;
 }
@@ -110,7 +130,7 @@ export async function proxyBillingRequest(
   accessToken: string | undefined,
   options: BillingProxyOptions = {}
 ): Promise<NextResponse> {
-  const { method = 'GET', body, normalize = false } = options;
+  const { method = 'GET', body, normalize = false, fromSnake = false } = options;
   const url = `${apiBaseUrl}${path}`;
 
   const headers: Record<string, string> = { 'Content-Type': 'application/json' };
@@ -135,7 +155,8 @@ export async function proxyBillingRequest(
     }
 
     const data = await response.json();
-    return NextResponse.json(normalize ? camelToSnake(data) : data);
+    const transformed = normalize ? camelToSnake(data) : fromSnake ? snakeToCamel(data) : data;
+    return NextResponse.json(transformed);
   } catch (error) {
     return NextResponse.json(
       {

package/src/utils/plan.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Contract tests for isPaidSubscription (bead my0e).
+ *
+ * Derives the "is the user on a paid plan" boolean from a SubscriptionInfo.
+ * Pure function — no React/hooks coupling.
+ *
+ * Semantics chosen to match the definition raise-simpli has been using:
+ *   - Must have a subscription at all
+ *   - Must have an offer
+ *   - Offer must not be free
+ *   - Status must be active or trialing (past_due / cancelled / etc. don't count)
+ */
+import { describe, it, expect } from 'vitest'
+import { isPaidSubscription } from './plan'
+import type { ProductOffer, SubscriptionInfo } from '../types'
+
+function makeOffer(overrides: Partial<ProductOffer> = {}): ProductOffer {
+  return {
+    id: 'offer-1',
+    name: 'Pro',
+    slug: 'pro',
+    unitPrice: '19.00',
+    currency: 'usd',
+    pricingModel: 'flat',
+    intervalUnit: 'month',
+    intervalCount: 1,
+    intervalDisplay: 'monthly',
+    isRecurring: true,
+    isFree: false,
+    features: [],
+    isActive: true,
+    isFeatured: false,
+    trialDays: 0,
+    ...overrides,
+  } as ProductOffer
+}
+
+function makeSub(overrides: Partial<SubscriptionInfo> = {}): SubscriptionInfo {
+  return {
+    id: 'sub-1',
+    offer: makeOffer(),
+    status: 'active',
+    currentPeriodStart: null,
+    currentPeriodEnd: null,
+    cancelAtPeriodEnd: false,
+    trialEnd: null,
+    ...overrides,
+  } as SubscriptionInfo
+}
+
+describe('isPaidSubscription', () => {
+  it('returns false for null subscription (no plan at all)', () => {
+    expect(isPaidSubscription(null)).toBe(false)
+  })
+
+  it('returns false for undefined', () => {
+    expect(isPaidSubscription(undefined)).toBe(false)
+  })
+
+  it('returns true for active + paid offer', () => {
+    expect(isPaidSubscription(makeSub({ status: 'active' }))).toBe(true)
+  })
+
+  it('returns true for trialing + paid offer', () => {
+    expect(isPaidSubscription(makeSub({ status: 'trialing' }))).toBe(true)
+  })
+
+  it('returns false for active + free offer', () => {
+    expect(
+      isPaidSubscription(makeSub({ status: 'active', offer: makeOffer({ isFree: true }) }))
+    ).toBe(false)
+  })
+
+  const deadStatuses = ['past_due', 'cancelled', 'incomplete', 'incomplete_expired', 'unpaid'] as const
+  for (const status of deadStatuses) {
+    it(`returns false for status=${status} even with a paid offer`, () => {
+      expect(isPaidSubscription(makeSub({ status }))).toBe(false)
+    })
+  }
+
+  it('returns false when offer is missing entirely', () => {
+    // Offer is typed non-nullable on SubscriptionInfo but real backend responses
+    // have been seen without it during bad states; be defensive.
+    const sub = { ...makeSub(), offer: null as unknown as ProductOffer }
+    expect(isPaidSubscription(sub)).toBe(false)
+  })
+})

package/src/utils/plan.ts

@@ -0,0 +1,30 @@
+/**
+ * Plan-status derivations.
+ *
+ * Pure helpers for reasoning about a user's subscription state without
+ * coupling to any React context. Callers either already have a
+ * SubscriptionInfo (from useSubscription or their own fetcher) or know
+ * they don't.
+ */
+
+import type { SubscriptionInfo } from "../types";
+
+const PAID_STATUSES: ReadonlyArray<SubscriptionInfo["status"]> = ["active", "trialing"];
+
+/**
+ * True iff the user is currently on an active (or trialing) paid plan.
+ *
+ * Returns false for:
+ *  - no subscription at all (null / undefined)
+ *  - subscriptions without an offer (bad backend state)
+ *  - free offers (even if status is active — a free tier is not "paid")
+ *  - lapsed / cancelled / past_due / incomplete / unpaid statuses
+ */
+export function isPaidSubscription(
+  sub: SubscriptionInfo | null | undefined
+): boolean {
+  if (!sub) return false;
+  if (!sub.offer) return false;
+  if (sub.offer.isFree) return false;
+  return PAID_STATUSES.includes(sub.status);
+}