@startsimpli/billing 0.1.0

package/src/hooks/usePortal.ts

@@ -0,0 +1,43 @@
+/**
+ * usePortal — Create a customer portal session and redirect.
+ *
+ * Usage:
+ *   const { openPortal, loading, error } = usePortal();
+ *   await openPortal("https://app.example.com/settings");
+ */
+
+import { useCallback, useState } from "react";
+import type { PortalResult } from "../types";
+import { useBillingContext } from "./BillingProvider";
+
+interface UsePortalResult {
+  openPortal: (returnUrl: string) => Promise<PortalResult>;
+  loading: boolean;
+  error: Error | null;
+}
+
+export function usePortal(): UsePortalResult {
+  const { client } = useBillingContext();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const openPortal = useCallback(
+    async (returnUrl: string) => {
+      setLoading(true);
+      setError(null);
+      try {
+        const result = await client.createPortal(returnUrl);
+        return result;
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        setError(err);
+        throw err;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [client]
+  );
+
+  return { openPortal, loading, error };
+}

package/src/hooks/useProduct.test.tsx

@@ -0,0 +1,155 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import React from "react";
+import { BillingProvider } from "./BillingProvider";
+import { useProduct } from "./useProduct";
+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: [],
+      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 }],
+      is_active: true,
+      is_featured: true,
+      trial_days: 14,
+      sort_order: 1,
+      cta_text: "Start Trial",
+    },
+  ],
+};
+
+function createWrapper(fetcher: typeof fetch) {
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <BillingProvider
+        apiBaseUrl="https://api.test.com/api/v1"
+        fetcher={fetcher}
+      >
+        {children}
+      </BillingProvider>
+    );
+  };
+}
+
+describe("useProduct", () => {
+  it("fetches product by slug", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(mockProduct),
+    });
+    const wrapper = createWrapper(mockFetch as unknown as typeof fetch);
+
+    const { result } = renderHook(() => useProduct("raise-simpli"), {
+      wrapper,
+    });
+
+    // Initially loading
+    expect(result.current.loading).toBe(true);
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.product).toEqual(mockProduct);
+    expect(result.current.error).toBeNull();
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://api.test.com/api/v1/billing/products/raise-simpli/",
+      expect.any(Object)
+    );
+  });
+
+  it("handles fetch error", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+    });
+    const wrapper = createWrapper(mockFetch as unknown as typeof fetch);
+
+    const { result } = renderHook(() => useProduct("nonexistent"), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.product).toBeNull();
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error?.message).toContain("nonexistent");
+  });
+
+  it("handles network error", async () => {
+    const mockFetch = vi
+      .fn()
+      .mockRejectedValue(new Error("Network failure"));
+    const wrapper = createWrapper(mockFetch as unknown as typeof fetch);
+
+    const { result } = renderHook(() => useProduct("raise-simpli"), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.product).toBeNull();
+    expect(result.current.error?.message).toBe("Network failure");
+  });
+
+  it("provides refetch function", async () => {
+    let callCount = 0;
+    const mockFetch = vi.fn().mockImplementation(() => {
+      callCount++;
+      return Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            ...mockProduct,
+            name: `RaiseSimpli v${callCount}`,
+          }),
+      });
+    });
+    const wrapper = createWrapper(mockFetch as unknown as typeof fetch);
+
+    const { result } = renderHook(() => useProduct("raise-simpli"), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.product?.name).toBe("RaiseSimpli v1");
+
+    // Refetch
+    result.current.refetch();
+    await waitFor(() =>
+      expect(result.current.product?.name).toBe("RaiseSimpli v2")
+    );
+  });
+});

package/src/hooks/useProduct.ts

@@ -0,0 +1,43 @@
+/**
+ * useProduct — Fetch a BillingProduct by slug.
+ *
+ * Usage:
+ *   const { product, loading, error } = useProduct("raise-simpli");
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import type { BillingProduct } from "../types";
+import { useBillingContext } from "./BillingProvider";
+
+interface UseProductResult {
+  product: BillingProduct | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+export function useProduct(slug: string): UseProductResult {
+  const { client } = useBillingContext();
+  const [product, setProduct] = useState<BillingProduct | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchProduct = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await client.getProduct(slug);
+      setProduct(data);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+    } finally {
+      setLoading(false);
+    }
+  }, [client, slug]);
+
+  useEffect(() => {
+    fetchProduct();
+  }, [fetchProduct]);
+
+  return { product, loading, error, refetch: fetchProduct };
+}

package/src/hooks/useSubscription.test.tsx

@@ -0,0 +1,167 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import React from "react";
+import { BillingProvider } from "./BillingProvider";
+import { useSubscription } from "./useSubscription";
+import type { SubscriptionInfo, ProductOffer } from "../types";
+
+const mockOffer: ProductOffer = {
+  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 }],
+  is_active: true,
+  is_featured: true,
+  trial_days: 14,
+  sort_order: 1,
+  cta_text: "Start Trial",
+};
+
+const mockSubscription: SubscriptionInfo = {
+  id: "sub-123",
+  offer: mockOffer,
+  status: "active",
+  current_period_start: "2026-01-01T00:00:00Z",
+  current_period_end: "2026-02-01T00:00:00Z",
+  cancel_at_period_end: false,
+  trial_end: null,
+};
+
+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("useSubscription", () => {
+  it("starts in loading state", () => {
+    const mockFetch = vi.fn().mockReturnValue(
+      new Promise(() => {})
+    ) as unknown as typeof fetch;
+    const wrapper = createWrapper(mockFetch);
+
+    const { result } = renderHook(() => useSubscription(), { wrapper });
+
+    expect(result.current.loading).toBe(true);
+    expect(result.current.subscription).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  it("fetches subscription successfully", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockSubscription),
+    });
+    const wrapper = createWrapper(mockFetch as unknown as typeof fetch);
+
+    const { result } = renderHook(() => useSubscription(), { wrapper });
+
+    expect(result.current.loading).toBe(true);
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.subscription).toEqual(mockSubscription);
+    expect(result.current.error).toBeNull();
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://api.test.com/api/v1/billing/subscription/current/",
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: "Bearer tok_123",
+        }),
+      })
+    );
+  });
+
+  it("returns null when no subscription exists (404)", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+    });
+    const wrapper = createWrapper(mockFetch as unknown as typeof fetch);
+
+    const { result } = renderHook(() => useSubscription(), { wrapper });
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.subscription).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  it("sets error on non-404 API failure", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 500,
+      json: () => Promise.resolve({ detail: "Internal server error" }),
+    });
+    const wrapper = createWrapper(mockFetch as unknown as typeof fetch);
+
+    const { result } = renderHook(() => useSubscription(), { wrapper });
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.subscription).toBeNull();
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error?.message).toContain("Internal server error");
+  });
+
+  it("handles network error", async () => {
+    const mockFetch = vi
+      .fn()
+      .mockRejectedValue(new Error("Network failure"));
+    const wrapper = createWrapper(mockFetch as unknown as typeof fetch);
+
+    const { result } = renderHook(() => useSubscription(), { wrapper });
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.subscription).toBeNull();
+    expect(result.current.error?.message).toBe("Network failure");
+  });
+
+  it("provides refetch function", async () => {
+    let callCount = 0;
+    const mockFetch = vi.fn().mockImplementation(() => {
+      callCount++;
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        json: () =>
+          Promise.resolve({
+            ...mockSubscription,
+            id: `sub-${callCount}`,
+          }),
+      });
+    });
+    const wrapper = createWrapper(mockFetch as unknown as typeof fetch);
+
+    const { result } = renderHook(() => useSubscription(), { wrapper });
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.subscription?.id).toBe("sub-1");
+
+    // Refetch
+    act(() => {
+      result.current.refetch();
+    });
+    await waitFor(() =>
+      expect(result.current.subscription?.id).toBe("sub-2")
+    );
+  });
+});

package/src/hooks/useSubscription.ts

@@ -0,0 +1,40 @@
+/**
+ * useSubscription — Fetch current user's active subscription.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import type { SubscriptionInfo } from "../types";
+import { useBillingContext } from "./BillingProvider";
+
+interface UseSubscriptionResult {
+  subscription: SubscriptionInfo | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+export function useSubscription(): UseSubscriptionResult {
+  const { client } = useBillingContext();
+  const [subscription, setSubscription] = useState<SubscriptionInfo | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchSubscription = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await client.getSubscription();
+      setSubscription(data);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+    } finally {
+      setLoading(false);
+    }
+  }, [client]);
+
+  useEffect(() => {
+    fetchSubscription();
+  }, [fetchSubscription]);
+
+  return { subscription, loading, error, refetch: fetchSubscription };
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * @startsimpli/billing — Universal billing integration for StartSimpli apps.
+ *
+ * Usage:
+ *   import { BillingProvider, useProduct, useCheckout } from "@startsimpli/billing";
+ *
+ *   <BillingProvider apiBaseUrl="/api/v1" authToken={token}>
+ *     <PricingPage productId="raise-simpli" />
+ *   </BillingProvider>
+ */
+
+// Context & Hooks
+export {
+  BillingProvider,
+  useBillingContext,
+  useProduct,
+  useCheckout,
+  usePortal,
+  useSubscription,
+} from "./hooks";
+export type { BillingProviderProps } from "./hooks";
+
+// Types
+export type {
+  BillingConfig,
+  BillingProduct,
+  ProductOffer,
+  OfferFeature,
+  CheckoutResult,
+  FreeSubscriptionResult,
+  PortalResult,
+  SubscriptionInfo,
+} from "./types";
+
+// Components
+export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager } from "./components";
+export type {
+  PricingPageProps,
+  PricingSectionProps,
+  PricingDetailPageProps,
+  UpgradeModalProps,
+  ManageSubscriptionProps,
+  SubscriptionManagerProps,
+} from "./components";
+
+// API client (for advanced usage)
+export { BillingApiClient } from "./utils/api";

package/src/server/index.ts

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

package/src/server/proxy.ts

@@ -0,0 +1,89 @@
+/**
+ * Server-side billing proxy utilities for Next.js Route Handlers.
+ *
+ * Provides a typed proxy to the Django billing API, with optional
+ * camelCase-to-snake_case response normalization (Django's DRF camel-case
+ * middleware returns camelCase; some billing consumers expect snake_case).
+ *
+ * Import via: import { proxyBillingRequest, camelToSnake } from '@startsimpli/billing/server'
+ */
+
+import { NextResponse } from 'next/server';
+
+/**
+ * Recursively converts camelCase object keys to snake_case.
+ * Useful when Django's camel-case middleware returns camelCase field names
+ * but downstream consumers expect snake_case.
+ */
+export function camelToSnake(obj: unknown): unknown {
+  if (Array.isArray(obj)) return obj.map(camelToSnake);
+  if (obj !== null && typeof obj === 'object') {
+    return Object.fromEntries(
+      Object.entries(obj as Record<string, unknown>).map(([k, v]) => [
+        k.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`),
+        camelToSnake(v),
+      ])
+    );
+  }
+  return obj;
+}
+
+export interface BillingProxyOptions {
+  method?: string;
+  body?: unknown;
+  /** If true, apply camelToSnake transform to the response body */
+  normalize?: boolean;
+  /** If true, skip Authorization header even when accessToken is provided */
+  public?: boolean;
+}
+
+/**
+ * Proxy a request to the Django billing API from a Next.js Route Handler.
+ *
+ * @param apiBaseUrl  - Django API base URL (e.g. process.env.NEXT_PUBLIC_API_URL)
+ * @param path        - Billing API path (e.g. '/api/v1/billing/subscription/current/')
+ * @param accessToken - JWT access token from the current session (or undefined)
+ * @param options     - method, body, normalize, public
+ */
+export async function proxyBillingRequest(
+  apiBaseUrl: string,
+  path: string,
+  accessToken: string | undefined,
+  options: BillingProxyOptions = {}
+): Promise<NextResponse> {
+  const { method = 'GET', body, normalize = false } = options;
+  const url = `${apiBaseUrl}${path}`;
+
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (!options.public && accessToken) {
+    headers['Authorization'] = `Bearer ${accessToken}`;
+  }
+
+  try {
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      cache: 'no-store',
+    });
+
+    if (!response.ok) {
+      const errorData = await response.text();
+      return NextResponse.json(
+        { error: 'Billing API error', status: response.status, details: errorData },
+        { status: response.status }
+      );
+    }
+
+    const data = await response.json();
+    return NextResponse.json(normalize ? camelToSnake(data) : data);
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error: 'Internal server error',
+        details: error instanceof Error ? error.message : 'Unknown error',
+      },
+      { status: 500 }
+    );
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Type definitions for @simpli/billing.
+ *
+ * These types mirror the backend API response from:
+ *   GET /api/v1/billing/products/{slug}/
+ */
+
+export interface ProductOffer {
+  id: string;
+  name: string;
+  slug: string;
+  unit_price: string; // Decimal as string from DRF
+  currency: string;
+  pricing_model: "flat" | "per_seat" | "tiered" | "volume" | "usage";
+  interval_unit: "day" | "week" | "month" | "year" | null;
+  interval_count: number | null;
+  interval_display: string;
+  is_recurring: boolean;
+  is_free: boolean;
+  features: OfferFeature[];
+  is_active: boolean;
+  is_featured: boolean;
+  trial_days: number;
+  sort_order: number;
+  cta_text: string;
+}
+
+export interface OfferFeature {
+  key: string;
+  name: string;
+  value: boolean | number | string | null;
+  category?: string;
+  limit?: number | null;
+  tooltip?: string | null;
+}
+
+export interface BillingProduct {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  offers: ProductOffer[];
+}
+
+export interface CheckoutResult {
+  session_id: string;
+  url: string;
+}
+
+export interface FreeSubscriptionResult {
+  subscription_id: string;
+  status: string;
+}
+
+export interface PortalResult {
+  url: string;
+}
+
+export interface SubscriptionInfo {
+  id: string;
+  offer: ProductOffer;
+  status: "active" | "trialing" | "past_due" | "cancelled" | "incomplete" | "incomplete_expired" | "unpaid";
+  current_period_start: string;
+  current_period_end: string;
+  cancel_at_period_end: boolean;
+  trial_end: string | null;
+}
+
+export interface BillingConfig {
+  /** Base URL for the billing API (e.g., "https://api.startsimpli.com/api/v1") */
+  apiBaseUrl: string;
+
+  /** Optional auth token for authenticated endpoints (checkout, portal) */
+  authToken?: string;
+
+  /** Optional custom fetch implementation */
+  fetcher?: typeof fetch;
+}