@startsimpli/billing 0.4.9 → 0.4.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.9",
+  "version": "0.4.12",
   "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/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);
+}