@startsimpli/billing 0.1.0

package/README.md

@@ -0,0 +1,145 @@
+# @startsimpli/billing
+
+Universal billing integration for StartSimpli Next.js apps. Products and pricing are configured in Django admin — frontend components auto-fetch and render.
+
+## Backend Setup
+
+The billing backend lives in `start-simpli-api/apps/billing/`. Models, admin, and API are already configured.
+
+### Key Endpoints
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/api/v1/billing/products/` | GET | Public | List public products with offers |
+| `/api/v1/billing/products/{slug}/` | GET | Public | Get product by slug |
+| `/api/v1/billing/offer-checkout/` | POST | Required | Create checkout session |
+| `/api/v1/billing/offer-portal/` | POST | Required | Create portal session |
+| `/api/v1/billing/subscription/current/` | GET | Required | Get current user's subscription |
+
+### Admin Workflow
+
+1. Add a `BillingProviderCredential` (Stripe secret key + webhook secret)
+2. Create a `BillingProduct` (slug = identifier used by frontend)
+3. Add `ProductOffer` inlines (pricing tiers)
+4. Use "Sync to provider" admin action to push to Stripe
+
+## Frontend Setup
+
+### Installation
+
+In your Next.js app's `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@startsimpli/billing": "workspace:*"
+  }
+}
+```
+
+Add `transpilePackages: ['@startsimpli/billing']` to `next.config.js`.
+
+### Usage
+
+```tsx
+import { BillingProvider, PricingPage, useCheckout, ManageSubscription } from '@startsimpli/billing'
+
+// Wrap your app (or a subtree) with BillingProvider
+<BillingProvider apiBaseUrl="/api/v1" authToken={accessToken}>
+  <PricingPage productId="raise-simpli" onSelectOffer={handleSelect} />
+</BillingProvider>
+
+// Checkout hook
+const { checkout, loading } = useCheckout()
+await checkout({ offerId, successUrl, cancelUrl })
+
+// Subscription management
+<ManageSubscription returnUrl="/settings" buttonText="Manage Billing" />
+```
+
+### Components
+
+| Component | Props | Description |
+|-----------|-------|-------------|
+| `BillingProvider` | `apiBaseUrl`, `authToken` | Context provider — required wrapper |
+| `PricingPage` | `productId`, `onSelectOffer?` | Full pricing display with offer cards |
+| `PricingSection` | `productId`, `onSelectOffer?` | Pricing section component |
+| `PricingDetailPage` | `productId`, `onSelectOffer?` | Detailed pricing page |
+| `UpgradeModal` | `productId`, `open`, `onClose`, `onSelectOffer?` | Modal pricing overlay |
+| `ManageSubscription` | `returnUrl`, `buttonText?` | Portal redirect button |
+| `SubscriptionManager` | `productId?` | Full subscription management interface |
+
+### Hooks
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useProduct(slug)` | `{ product, loading, error }` | Fetch product + offers |
+| `useCheckout()` | `{ checkout, subscribeFree, loading, error }` | Create checkout session or free subscription |
+| `usePortal()` | `{ openPortal, loading, error }` | Open customer portal |
+| `useSubscription()` | `{ subscription, loading, error, refetch }` | Get current user's subscription |
+
+## Architecture
+
+- **Provider-agnostic**: `BaseBillingProvider` → `StripeBillingProvider` (extensible to Paddle, etc.)
+- **BillingProviderFactory**: Resolves credentials per-team with global fallback
+- **BillingService**: Orchestrates sync, checkout, and portal operations
+- **ProductOffer**: Supports flat, per_seat, tiered, volume, and usage pricing models
+
+## Integration with @startsimpli/auth
+
+The billing package integrates seamlessly with `@startsimpli/auth`:
+
+```tsx
+import { BillingProvider } from '@startsimpli/billing'
+import { useAuth } from '@startsimpli/auth'
+
+function App() {
+  const { tokens } = useAuth()
+
+  return (
+    <BillingProvider
+      apiBaseUrl={process.env.NEXT_PUBLIC_API_URL + '/api/v1'}
+      authToken={tokens?.access}
+    >
+      {/* Your app */}
+    </BillingProvider>
+  )
+}
+```
+
+## Environment Variables
+
+```env
+NEXT_PUBLIC_API_URL=https://api.startsimpli.com
+```
+
+Backend requires:
+```env
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+## Tests
+
+```bash
+# Frontend tests (39 tests)
+cd packages/billing
+npm test
+
+# Backend tests (184 tests)
+cd start-simpli-api
+docker-compose -f docker-compose.local.yml exec -T django pytest apps/billing/tests/ -v
+```
+
+## Development
+
+```bash
+# Type checking
+npm run type-check
+
+# Watch mode for tests
+npm run test:watch
+
+# Coverage report
+npm run test:coverage
+```

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@startsimpli/billing",
+  "version": "0.1.0",
+  "description": "Universal billing integration for StartSimpli Next.js apps",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": ["src"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/index.ts",
+    "./server": "./src/server/index.ts",
+    "./types": "./src/types/index.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "next": ">=14.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.0.0",
+    "@testing-library/react": "^16.0.0",
+    "@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",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "billing",
+    "stripe",
+    "nextjs",
+    "django",
+    "startsimpli"
+  ]
+}

package/src/components/ManageSubscription.test.tsx

@@ -0,0 +1,140 @@
+/**
+ * TDD tests for ManageSubscription component.
+ *
+ * ManageSubscription is a button/link that opens the billing provider's
+ * customer portal for managing an existing subscription.
+ *
+ * Usage:
+ *   <ManageSubscription returnUrl="https://app.example.com/settings" />
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import React from "react";
+import { BillingProvider } from "../hooks/BillingProvider";
+import { ManageSubscription } from "./ManageSubscription";
+
+function createWrapper(fetcher: typeof fetch) {
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <BillingProvider
+        apiBaseUrl="https://api.test.com/api/v1"
+        authToken="tok_123"
+        fetcher={fetcher}
+      >
+        {children}
+      </BillingProvider>
+    );
+  };
+}
+
+describe("ManageSubscription", () => {
+  it("renders a manage billing button", () => {
+    const mockFetch = vi.fn() as unknown as typeof fetch;
+    const Wrapper = createWrapper(mockFetch);
+
+    render(
+      <Wrapper>
+        <ManageSubscription returnUrl="https://app.test.com/settings" />
+      </Wrapper>
+    );
+
+    expect(screen.getByText(/manage/i)).toBeDefined();
+  });
+
+  it("calls portal API on click and redirects", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () =>
+        Promise.resolve({ url: "https://billing.stripe.com/portal/test" }),
+    }) as unknown as typeof fetch;
+    const Wrapper = createWrapper(mockFetch);
+
+    // Mock window.location.href
+    const originalLocation = window.location;
+    const mockLocation = { ...originalLocation, href: "" };
+    Object.defineProperty(window, "location", {
+      value: mockLocation,
+      writable: true,
+    });
+
+    render(
+      <Wrapper>
+        <ManageSubscription returnUrl="https://app.test.com/settings" />
+      </Wrapper>
+    );
+
+    await userEvent.click(screen.getByText(/manage/i));
+
+    await waitFor(() => {
+      expect(mockLocation.href).toBe(
+        "https://billing.stripe.com/portal/test"
+      );
+    });
+
+    // Restore
+    Object.defineProperty(window, "location", {
+      value: originalLocation,
+      writable: true,
+    });
+  });
+
+  it("shows loading state while creating portal session", async () => {
+    const mockFetch = vi.fn().mockReturnValue(
+      new Promise(() => {})
+    ) as unknown as typeof fetch;
+    const Wrapper = createWrapper(mockFetch);
+
+    render(
+      <Wrapper>
+        <ManageSubscription returnUrl="https://app.test.com/settings" />
+      </Wrapper>
+    );
+
+    await userEvent.click(screen.getByText(/manage/i));
+
+    await waitFor(() => {
+      const button = screen.getByRole("button");
+      expect(button.getAttribute("disabled")).not.toBeNull();
+    });
+  });
+
+  it("shows error on portal failure", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+      json: () =>
+        Promise.resolve({ detail: "No active subscription found" }),
+    }) as unknown as typeof fetch;
+    const Wrapper = createWrapper(mockFetch);
+
+    render(
+      <Wrapper>
+        <ManageSubscription returnUrl="https://app.test.com/settings" />
+      </Wrapper>
+    );
+
+    await userEvent.click(screen.getByText(/manage/i));
+
+    await waitFor(() => {
+      expect(screen.getByText(/no active subscription/i)).toBeDefined();
+    });
+  });
+
+  it("accepts custom button text", () => {
+    const mockFetch = vi.fn() as unknown as typeof fetch;
+    const Wrapper = createWrapper(mockFetch);
+
+    render(
+      <Wrapper>
+        <ManageSubscription
+          returnUrl="https://app.test.com/settings"
+          buttonText="Billing Settings"
+        />
+      </Wrapper>
+    );
+
+    expect(screen.getByText("Billing Settings")).toBeDefined();
+  });
+});

package/src/components/ManageSubscription.tsx

@@ -0,0 +1,53 @@
+/**
+ * ManageSubscription — Button that opens the billing provider's customer portal.
+ *
+ * Usage:
+ *   <ManageSubscription returnUrl="https://app.example.com/settings" />
+ */
+
+import React from "react";
+import { usePortal } from "../hooks/usePortal";
+
+export interface ManageSubscriptionProps {
+  returnUrl: string;
+  buttonText?: string;
+}
+
+export function ManageSubscription({
+  returnUrl,
+  buttonText = "Manage Billing",
+}: ManageSubscriptionProps) {
+  const { openPortal, loading, error } = usePortal();
+
+  const handleClick = async () => {
+    try {
+      const result = await openPortal(returnUrl);
+      window.location.href = result.url;
+    } catch {
+      // Error is captured by the hook's error state
+    }
+  };
+
+  return (
+    <div data-testid="manage-subscription">
+      <button
+        onClick={handleClick}
+        disabled={loading}
+        className={`
+          inline-flex items-center gap-2 px-6 py-3 text-sm font-semibold rounded-xl border transition-colors
+          ${loading
+            ? "bg-gray-50 text-gray-400 border-gray-200 cursor-not-allowed"
+            : "bg-white text-gray-700 border-gray-200 hover:bg-gray-50 hover:border-gray-300 cursor-pointer"
+          }
+        `}
+      >
+        {loading ? "Loading..." : buttonText}
+      </button>
+      {error && (
+        <p data-testid="portal-error" className="mt-2 text-sm text-red-600">
+          {error.message}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/PricingDetailPage.integration.test.tsx

@@ -0,0 +1,244 @@
+/**
+ * Integration tests for PricingDetailPage component.
+ *
+ * Tests the full flow: loading -> data loaded -> user interaction -> callback.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import React from "react";
+import { BillingProvider } from "../hooks/BillingProvider";
+import { PricingDetailPage } from "./PricingDetailPage";
+import type { BillingProduct } from "../types";
+
+const mockProduct: BillingProduct = {
+  id: "prod-1",
+  slug: "raise-simpli",
+  name: "RaiseSimpli",
+  description: "VC fundraising platform",
+  offers: [
+    {
+      id: "offer-1",
+      name: "Starter",
+      slug: "starter-monthly",
+      unit_price: "0.00",
+      currency: "USD",
+      pricing_model: "flat",
+      interval_unit: "month",
+      interval_count: 1,
+      interval_display: "per month",
+      is_recurring: true,
+      is_free: true,
+      features: [
+        { key: "seats", name: "Team seats", value: 1, limit: 1, category: "core" },
+        { key: "projects", name: "Projects", value: 3, limit: 3, category: "core" },
+      ],
+      is_active: true,
+      is_featured: false,
+      trial_days: 0,
+      sort_order: 0,
+      cta_text: "Start Free",
+    },
+    {
+      id: "offer-2",
+      name: "Pro",
+      slug: "pro-monthly",
+      unit_price: "49.00",
+      currency: "USD",
+      pricing_model: "flat",
+      interval_unit: "month",
+      interval_count: 1,
+      interval_display: "per month",
+      is_recurring: true,
+      is_free: false,
+      features: [
+        { key: "seats", name: "Team seats", value: 5, limit: 5, category: "core" },
+        { key: "projects", name: "Projects", value: "Unlimited", category: "core" },
+      ],
+      is_active: true,
+      is_featured: true,
+      trial_days: 14,
+      sort_order: 1,
+      cta_text: "Start Trial",
+    },
+  ],
+};
+
+function createWrapper(fetchImpl: typeof fetch) {
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <BillingProvider
+        apiBaseUrl="https://api.test.com/api/v1"
+        authToken="tok_123"
+        fetcher={fetchImpl}
+      >
+        {children}
+      </BillingProvider>
+    );
+  };
+}
+
+describe("PricingDetailPage integration", () => {
+  it("shows loading, then renders pricing cards after data loads", async () => {
+    let resolveFetch!: (value: unknown) => void;
+    const fetchPromise = new Promise((resolve) => {
+      resolveFetch = resolve;
+    });
+    const fetcher = vi.fn().mockReturnValue(fetchPromise) as unknown as typeof fetch;
+    const Wrapper = createWrapper(fetcher);
+
+    render(
+      <Wrapper>
+        <PricingDetailPage productId="raise-simpli" />
+      </Wrapper>
+    );
+
+    // Phase 1: loading
+    expect(screen.getByText(/loading/i)).toBeDefined();
+
+    // Resolve the fetch
+    resolveFetch({
+      ok: true,
+      json: () => Promise.resolve(mockProduct),
+    });
+
+    // Phase 2: loaded - shows pricing content
+    await waitFor(() => {
+      expect(screen.getByText("RaiseSimpli")).toBeDefined();
+    });
+    // "Starter" and "Pro" appear in both the card and the comparison table header
+    expect(screen.getAllByText("Starter").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("Pro").length).toBeGreaterThan(0);
+    expect(screen.queryByText(/loading/i)).toBeNull();
+  });
+
+  it("full flow: view pricing -> click CTA -> verify callback with correct offer", async () => {
+    const onSelect = vi.fn();
+    const fetcher = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(mockProduct),
+    }) as unknown as typeof fetch;
+    const Wrapper = createWrapper(fetcher);
+
+    render(
+      <Wrapper>
+        <PricingDetailPage productId="raise-simpli" onSelectOffer={onSelect} />
+      </Wrapper>
+    );
+
+    // Wait for pricing to load
+    await waitFor(() => {
+      expect(screen.getByText("Start Free")).toBeDefined();
+    });
+
+    // Click the free plan CTA
+    await userEvent.click(screen.getByText("Start Free"));
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(onSelect).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "offer-1",
+        slug: "starter-monthly",
+        name: "Starter",
+        is_free: true,
+      })
+    );
+  });
+
+  it("click paid plan CTA -> callback receives the paid offer", async () => {
+    const onSelect = vi.fn();
+    const fetcher = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(mockProduct),
+    }) as unknown as typeof fetch;
+    const Wrapper = createWrapper(fetcher);
+
+    render(
+      <Wrapper>
+        <PricingDetailPage productId="raise-simpli" onSelectOffer={onSelect} />
+      </Wrapper>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("Start Trial")).toBeDefined();
+    });
+
+    // Click the Pro plan CTA
+    await userEvent.click(screen.getByText("Start Trial"));
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(onSelect).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "offer-2",
+        slug: "pro-monthly",
+        name: "Pro",
+        is_free: false,
+        unit_price: "49.00",
+      })
+    );
+  });
+
+  it("loading -> error transition when API fails", async () => {
+    let resolveFetch!: (value: unknown) => void;
+    const fetchPromise = new Promise((resolve) => {
+      resolveFetch = resolve;
+    });
+    const fetcher = vi.fn().mockReturnValue(fetchPromise) as unknown as typeof fetch;
+    const Wrapper = createWrapper(fetcher);
+
+    render(
+      <Wrapper>
+        <PricingDetailPage productId="raise-simpli" />
+      </Wrapper>
+    );
+
+    // Phase 1: loading
+    expect(screen.getByText(/loading/i)).toBeDefined();
+
+    // Resolve with an error
+    resolveFetch({
+      ok: false,
+      status: 500,
+    });
+
+    // Phase 2: error state
+    await waitFor(() => {
+      expect(screen.getByText(/unable to load/i)).toBeDefined();
+    });
+    expect(screen.queryByText(/loading/i)).toBeNull();
+  });
+
+  it("multiple CTA clicks call onSelectOffer with the correct offer each time", async () => {
+    const onSelect = vi.fn();
+    const fetcher = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(mockProduct),
+    }) as unknown as typeof fetch;
+    const Wrapper = createWrapper(fetcher);
+
+    render(
+      <Wrapper>
+        <PricingDetailPage productId="raise-simpli" onSelectOffer={onSelect} />
+      </Wrapper>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("Start Free")).toBeDefined();
+    });
+
+    // Click free plan
+    await userEvent.click(screen.getByText("Start Free"));
+    expect(onSelect).toHaveBeenLastCalledWith(
+      expect.objectContaining({ slug: "starter-monthly" })
+    );
+
+    // Click paid plan
+    await userEvent.click(screen.getByText("Start Trial"));
+    expect(onSelect).toHaveBeenLastCalledWith(
+      expect.objectContaining({ slug: "pro-monthly" })
+    );
+
+    expect(onSelect).toHaveBeenCalledTimes(2);
+  });
+});