@startsimpli/billing 0.1.0 → 0.1.2

package/src/hooks/BillingProvider.test.tsx

@@ -1,12 +1,12 @@
 import { describe, it, expect, vi } from "vitest";
-import { renderHook, act, waitFor } from "@testing-library/react";
-import React, { useState } from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import React from "react";
 import { BillingProvider, useBillingContext } from "./BillingProvider";
 import { useProduct } from "./useProduct";
 
 describe("BillingProvider", () => {
   const wrapper = ({ children }: { children: React.ReactNode }) => (
-    <BillingProvider apiBaseUrl="https://api.test.com/api/v1">
+    <BillingProvider apiBaseUrl="/api">
       {children}
     </BillingProvider>
   );
@@ -14,9 +14,7 @@ describe("BillingProvider", () => {
   it("provides billing context to children", () => {
     const { result } = renderHook(() => useBillingContext(), { wrapper });
     expect(result.current.client).toBeDefined();
-    expect(result.current.config.apiBaseUrl).toBe(
-      "https://api.test.com/api/v1"
-    );
+    expect(result.current.config.apiBaseUrl).toBe("/api");
   });
 
   it("throws when used outside provider", () => {
@@ -25,52 +23,8 @@ describe("BillingProvider", () => {
     }).toThrow("useBillingContext must be used within a <BillingProvider>");
   });
 
-  it("passes auth token to config", () => {
-    const authWrapper = ({ children }: { children: React.ReactNode }) => (
-      <BillingProvider
-        apiBaseUrl="https://api.test.com/api/v1"
-        authToken="tok_123"
-      >
-        {children}
-      </BillingProvider>
-    );
-
-    const { result } = renderHook(() => useBillingContext(), {
-      wrapper: authWrapper,
-    });
-    expect(result.current.config.authToken).toBe("tok_123");
-  });
-
-  it("creates a new client when authToken changes", () => {
-    let token = "tok_first";
-
-    const DynamicWrapper = ({ children }: { children: React.ReactNode }) => (
-      <BillingProvider
-        apiBaseUrl="https://api.test.com/api/v1"
-        authToken={token}
-      >
-        {children}
-      </BillingProvider>
-    );
-
-    const { result, rerender } = renderHook(() => useBillingContext(), {
-      wrapper: DynamicWrapper,
-    });
-
-    const firstClient = result.current.client;
-    expect(result.current.config.authToken).toBe("tok_first");
-
-    // Change token and re-render
-    token = "tok_second";
-    rerender();
-
-    expect(result.current.config.authToken).toBe("tok_second");
-    // BillingProvider uses useMemo keyed on authToken, so client should change
-    expect(result.current.client).not.toBe(firstClient);
-  });
-
   it("creates a new client when apiBaseUrl changes", () => {
-    let baseUrl = "https://api.test.com/api/v1";
+    let baseUrl = "/api";
 
     const DynamicWrapper = ({ children }: { children: React.ReactNode }) => (
       <BillingProvider apiBaseUrl={baseUrl}>
@@ -84,41 +38,36 @@ describe("BillingProvider", () => {
 
     const firstClient = result.current.client;
 
-    // Change base URL and re-render
-    baseUrl = "https://api2.test.com/api/v1";
+    baseUrl = "/api/v2";
     rerender();
 
-    expect(result.current.config.apiBaseUrl).toBe("https://api2.test.com/api/v1");
+    expect(result.current.config.apiBaseUrl).toBe("/api/v2");
     expect(result.current.client).not.toBe(firstClient);
   });
 
-  it("API calls include auth token in headers", async () => {
+  it("routes API calls through the configured base URL", async () => {
     const mockFetch = vi.fn().mockResolvedValue({
       ok: true,
       json: () => Promise.resolve({ slug: "test", name: "Test", description: "", id: "1", offers: [] }),
     });
 
-    const authWrapper = ({ children }: { children: React.ReactNode }) => (
+    const testWrapper = ({ children }: { children: React.ReactNode }) => (
       <BillingProvider
-        apiBaseUrl="https://api.test.com/api/v1"
-        authToken="tok_for_header_test"
+        apiBaseUrl="/api"
         fetcher={mockFetch as unknown as typeof fetch}
       >
         {children}
       </BillingProvider>
     );
 
-    // useProduct makes a GET request (public, no auth header)
-    // But we can verify the fetcher was injected properly
-    renderHook(() => useProduct("test-slug"), { wrapper: authWrapper });
+    renderHook(() => useProduct("test-slug"), { wrapper: testWrapper });
 
     await waitFor(() => {
       expect(mockFetch).toHaveBeenCalled();
     });
 
-    // Verify the fetch was called with the correct base URL
     expect(mockFetch).toHaveBeenCalledWith(
-      "https://api.test.com/api/v1/billing/products/test-slug/",
+      "/api/billing/products/test-slug/",
       expect.any(Object)
     );
   });

package/src/hooks/BillingProvider.tsx

@@ -4,10 +4,20 @@
  * Wrap your app (or a section of it) with <BillingProvider> to configure
  * the API connection. All billing hooks read from this context.
  *
+ * Auth is handled server-side by your Next.js Route Handlers — you do NOT
+ * pass any tokens here. Set apiBaseUrl to the billing proxy prefix in your app.
+ *
  * Usage:
- *   <BillingProvider apiBaseUrl="https://api.startsimpli.com/api/v1" authToken={token}>
- *     <PricingPage productId="raise-simpli" />
+ *   <BillingProvider apiBaseUrl="/api">
+ *     <PricingPage productId="crochet-patterns" />
  *   </BillingProvider>
+ *
+ * Your Next.js app must expose these Route Handlers under apiBaseUrl:
+ *   GET  /api/billing/products/[slug]/          → public (no auth needed)
+ *   POST /api/billing/offer-checkout/            → calls fetchDjangoServiceToken + proxyBillingRequest
+ *   POST /api/billing/subscribe-free/            → same
+ *   POST /api/billing/offer-portal/              → same
+ *   GET  /api/billing/subscription/current/      → same
  */
 
 import React, { createContext, useContext, useMemo } from "react";
@@ -32,7 +42,7 @@ export function BillingProvider({
   const value = useMemo(() => {
     const client = new BillingApiClient(config);
     return { client, config };
-  }, [config.apiBaseUrl, config.authToken]);
+  }, [config.apiBaseUrl]);
 
   return (
     <BillingContext.Provider value={value}>

package/src/hooks/index.ts

@@ -4,3 +4,4 @@ export { useProduct } from "./useProduct";
 export { useCheckout } from "./useCheckout";
 export { usePortal } from "./usePortal";
 export { useSubscription } from "./useSubscription";
+export { useSuccessSync } from "./useSuccessSync";

package/src/hooks/useCheckout.test.tsx

@@ -9,7 +9,6 @@ function createWrapper(fetcher: typeof fetch) {
     return (
       <BillingProvider
         apiBaseUrl="https://api.test.com/api/v1"
-        authToken="tok_123"
         fetcher={fetcher}
       >
         {children}
@@ -48,13 +47,13 @@ describe("useCheckout", () => {
     expect(result.current.loading).toBe(false);
     expect(result.current.error).toBeNull();
 
-    // Verify correct API call
+    // Verify correct API call — no auth header, proxy handles auth server-side
     expect(mockFetch).toHaveBeenCalledWith(
       "https://api.test.com/api/v1/billing/offer-checkout/",
       expect.objectContaining({
         method: "POST",
-        headers: expect.objectContaining({
-          Authorization: "Bearer tok_123",
+        headers: expect.not.objectContaining({
+          Authorization: expect.any(String),
         }),
       })
     );
@@ -169,13 +168,13 @@ describe("useCheckout", () => {
       expect(result.current.loading).toBe(false);
       expect(result.current.error).toBeNull();
 
-      // Verify correct API call
+      // Verify correct API call — no auth header, proxy handles auth server-side
       expect(mockFetch).toHaveBeenCalledWith(
         "https://api.test.com/api/v1/billing/subscribe-free/",
         expect.objectContaining({
           method: "POST",
-          headers: expect.objectContaining({
-            Authorization: "Bearer tok_123",
+          headers: expect.not.objectContaining({
+            Authorization: expect.any(String),
           }),
         })
       );

package/src/hooks/usePortal.test.tsx

@@ -9,7 +9,6 @@ function createWrapper(fetcher: typeof fetch) {
     return (
       <BillingProvider
         apiBaseUrl="https://api.test.com/api/v1"
-        authToken="tok_123"
         fetcher={fetcher}
       >
         {children}
@@ -62,8 +61,8 @@ describe("usePortal", () => {
       "https://api.test.com/api/v1/billing/offer-portal/",
       expect.objectContaining({
         method: "POST",
-        headers: expect.objectContaining({
-          Authorization: "Bearer tok_123",
+        headers: expect.not.objectContaining({
+          Authorization: expect.any(String),
         }),
       })
     );

package/src/hooks/useSubscription.test.tsx

@@ -40,7 +40,6 @@ function createWrapper(fetcher: typeof fetch) {
     return (
       <BillingProvider
         apiBaseUrl="https://api.test.com/api/v1"
-        authToken="tok_123"
         fetcher={fetcher}
       >
         {children}
@@ -82,8 +81,8 @@ describe("useSubscription", () => {
     expect(mockFetch).toHaveBeenCalledWith(
       "https://api.test.com/api/v1/billing/subscription/current/",
       expect.objectContaining({
-        headers: expect.objectContaining({
-          Authorization: "Bearer tok_123",
+        headers: expect.not.objectContaining({
+          Authorization: expect.any(String),
         }),
       })
     );

package/src/hooks/useSuccessSync.ts

@@ -0,0 +1,48 @@
+/**
+ * useSuccessSync — Eagerly sync subscription state after Stripe checkout.
+ *
+ * Call this from your checkout success page. It POSTs to the success-sync
+ * endpoint which fetches the latest subscription from Stripe and populates
+ * the Redis cache + DB, so the UI can show subscription status immediately
+ * instead of waiting for the webhook.
+ *
+ * Usage:
+ *   const { sync, data, loading, error } = useSuccessSync();
+ *   useEffect(() => { sync(); }, [sync]);
+ */
+
+import { useCallback, useState } from "react";
+import type { CachedSubscriptionState } from "../types";
+import { useBillingContext } from "./BillingProvider";
+
+interface UseSuccessSyncResult {
+  sync: () => Promise<CachedSubscriptionState | null>;
+  data: CachedSubscriptionState | null;
+  loading: boolean;
+  error: Error | null;
+}
+
+export function useSuccessSync(): UseSuccessSyncResult {
+  const { client } = useBillingContext();
+  const [data, setData] = useState<CachedSubscriptionState | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const sync = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await client.successSync();
+      setData(result);
+      return result;
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e));
+      setError(err);
+      throw err;
+    } finally {
+      setLoading(false);
+    }
+  }, [client]);
+
+  return { sync, data, loading, error };
+}

package/src/index.ts

@@ -4,7 +4,7 @@
  * Usage:
  *   import { BillingProvider, useProduct, useCheckout } from "@startsimpli/billing";
  *
- *   <BillingProvider apiBaseUrl="/api/v1" authToken={token}>
+ *   <BillingProvider apiBaseUrl="/api">
  *     <PricingPage productId="raise-simpli" />
  *   </BillingProvider>
  */
@@ -17,6 +17,7 @@ export {
   useCheckout,
   usePortal,
   useSubscription,
+  useSuccessSync,
 } from "./hooks";
 export type { BillingProviderProps } from "./hooks";
 
@@ -27,7 +28,9 @@ export type {
   ProductOffer,
   OfferFeature,
   CheckoutResult,
+  CachedSubscriptionState,
   FreeSubscriptionResult,
+  PaymentMethod,
   PortalResult,
   SubscriptionInfo,
 } from "./types";

package/src/server/index.ts

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

package/src/server/proxy.ts

@@ -5,11 +5,70 @@
  * 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 via: import { proxyBillingRequest, fetchDjangoServiceToken, camelToSnake } from '@startsimpli/billing/server'
  */
 
 import { NextResponse } from 'next/server';
 
+export interface DjangoServiceTokenOptions {
+  /** Django base URL. Defaults to INTERNAL_API_URL ?? NEXT_PUBLIC_API_URL env vars. */
+  apiUrl?: string;
+  /** Shared service key. Defaults to INTERNAL_SERVICE_KEY env var. */
+  serviceKey?: string;
+}
+
+/**
+ * Exchange the shared INTERNAL_SERVICE_KEY for a Django JWT for the given user.
+ *
+ * Must only be called server-side (Route Handlers, Server Actions).
+ * Never expose the service key or the returned JWT to the browser.
+ *
+ * Django creates the user if they don't exist and ensures they have a Team,
+ * so billing endpoints (which require team membership) work immediately.
+ *
+ * Prefers INTERNAL_API_URL over NEXT_PUBLIC_API_URL for server-to-server
+ * calls — set INTERNAL_API_URL to the Docker service name in production
+ * (e.g. http://django:8000) to avoid routing through the public load balancer.
+ */
+export async function fetchDjangoServiceToken(
+  email: string,
+  name?: string | null,
+  opts?: DjangoServiceTokenOptions,
+): Promise<string | undefined> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const env = (typeof process !== 'undefined' ? process.env : {}) as Record<string, string | undefined>;
+  const apiUrl =
+    opts?.apiUrl ??
+    env['INTERNAL_API_URL'] ??
+    env['NEXT_PUBLIC_API_URL'] ??
+    '';
+  const serviceKey = opts?.serviceKey ?? env['INTERNAL_SERVICE_KEY'] ?? '';
+
+  if (!serviceKey) {
+    console.error('[billing] INTERNAL_SERVICE_KEY is not set — billing auth will fail');
+    return undefined;
+  }
+
+  try {
+    const response = await fetch(`${apiUrl}/api/v1/auth/service-token/`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, name: name ?? '', service_key: serviceKey }),
+      cache: 'no-store',
+    });
+    if (response.ok) {
+      const data = await response.json() as { access?: string };
+      return data.access;
+    }
+    const body = await response.text();
+    console.error('[billing] service-token failed:', response.status, body);
+    return undefined;
+  } catch (err) {
+    console.error('[billing] service-token request threw:', err);
+    return undefined;
+  }
+}
+
 /**
  * Recursively converts camelCase object keys to snake_case.
  * Useful when Django's camel-case middleware returns camelCase field names

package/src/types/index.ts

@@ -60,19 +60,48 @@ 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;
+  current_period_start: string | null;
+  current_period_end: string | null;
   cancel_at_period_end: boolean;
   trial_end: string | null;
 }
 
+export interface PaymentMethod {
+  brand: string | null;
+  last4: string | null;
+}
+
+export interface CachedSubscriptionState {
+  subscription_id: string | null;
+  provider_subscription_id: string | null;
+  status: string;
+  customer_id: string | null;
+  price_id: string | null;
+  offer_id: string | null;
+  product_slug: string | null;
+  offer_slug: string | null;
+  current_period_start: number | null;
+  current_period_end: number | null;
+  cancel_at_period_end: boolean;
+  trial_end: number | null;
+  payment_method: PaymentMethod | null;
+}
+
 export interface BillingConfig {
-  /** Base URL for the billing API (e.g., "https://api.startsimpli.com/api/v1") */
+  /**
+   * Base path for billing API calls.
+   *
+   * Point this at your Next.js app's billing route prefix — NOT at Django directly.
+   * The Next.js Route Handlers act as an authenticated proxy: they add the Django JWT
+   * server-side using INTERNAL_SERVICE_KEY, so no credentials are needed here.
+   *
+   * Example (Next.js app router):
+   *   apiBaseUrl="/api"
+   *   → public:  GET /api/billing/products/{slug}/
+   *   → authed:  POST /api/billing/offer-checkout/  (Route Handler adds Django JWT)
+   */
   apiBaseUrl: string;
 
-  /** Optional auth token for authenticated endpoints (checkout, portal) */
-  authToken?: string;
-
-  /** Optional custom fetch implementation */
+  /** Optional custom fetch implementation (useful for testing). */
   fetcher?: typeof fetch;
 }

package/src/utils/api.test.ts

@@ -4,10 +4,9 @@ import { BillingApiClient } from "./api";
 describe("BillingApiClient", () => {
   const mockFetch = vi.fn();
 
-  function createClient(authToken?: string) {
+  function createClient() {
     return new BillingApiClient({
-      apiBaseUrl: "https://api.test.com/api/v1",
-      authToken,
+      apiBaseUrl: "/api",
       fetcher: mockFetch as unknown as typeof fetch,
     });
   }
@@ -17,18 +16,18 @@ describe("BillingApiClient", () => {
   });
 
   describe("getProduct", () => {
-    it("calls correct URL with no auth", async () => {
+    it("calls correct URL without auth header", async () => {
       mockFetch.mockResolvedValue({
         ok: true,
         json: () =>
           Promise.resolve({ slug: "test", name: "Test", offers: [] }),
       });
 
-      const client = createClient("tok_123");
+      const client = createClient();
       await client.getProduct("test-product");
 
       expect(mockFetch).toHaveBeenCalledWith(
-        "https://api.test.com/api/v1/billing/products/test-product/",
+        "/api/billing/products/test-product/",
         expect.objectContaining({
           headers: expect.not.objectContaining({
             Authorization: expect.any(String),
@@ -46,14 +45,14 @@ describe("BillingApiClient", () => {
   });
 
   describe("createCheckout", () => {
-    it("sends POST with auth header", async () => {
+    it("sends POST without auth header (proxy handles auth server-side)", async () => {
       mockFetch.mockResolvedValue({
         ok: true,
         json: () =>
           Promise.resolve({ session_id: "cs_1", url: "https://pay.com" }),
       });
 
-      const client = createClient("tok_abc");
+      const client = createClient();
       const result = await client.createCheckout({
         offerId: "offer-1",
         successUrl: "https://ok.com",
@@ -62,11 +61,11 @@ describe("BillingApiClient", () => {
 
       expect(result.session_id).toBe("cs_1");
       expect(mockFetch).toHaveBeenCalledWith(
-        "https://api.test.com/api/v1/billing/offer-checkout/",
+        "/api/billing/offer-checkout/",
         expect.objectContaining({
           method: "POST",
-          headers: expect.objectContaining({
-            Authorization: "Bearer tok_abc",
+          headers: expect.not.objectContaining({
+            Authorization: expect.any(String),
           }),
         })
       );
@@ -79,7 +78,7 @@ describe("BillingApiClient", () => {
           Promise.resolve({ session_id: "cs_1", url: "https://pay.com" }),
       });
 
-      const client = createClient("tok");
+      const client = createClient();
       await client.createCheckout({
         offerId: "offer-1",
         successUrl: "https://ok.com",
@@ -98,7 +97,7 @@ describe("BillingApiClient", () => {
         json: () => Promise.resolve({ detail: "Offer not synced" }),
       });
 
-      const client = createClient("tok");
+      const client = createClient();
       await expect(
         client.createCheckout({
           offerId: "bad",
@@ -117,7 +116,7 @@ describe("BillingApiClient", () => {
           Promise.resolve({ url: "https://portal.stripe.com/test" }),
       });
 
-      const client = createClient("tok_xyz");
+      const client = createClient();
       const result = await client.createPortal("https://app.com/settings");
 
       expect(result.url).toBe("https://portal.stripe.com/test");

package/src/utils/api.ts

@@ -5,6 +5,7 @@
 import type {
   BillingConfig,
   BillingProduct,
+  CachedSubscriptionState,
   CheckoutResult,
   FreeSubscriptionResult,
   PortalResult,
@@ -22,21 +23,15 @@ export class BillingApiClient {
     return this.config.fetcher ?? fetch.bind(globalThis);
   }
 
-  private headers(authenticated: boolean = false): HeadersInit {
-    const h: Record<string, string> = {
-      "Content-Type": "application/json",
-    };
-    if (authenticated && this.config.authToken) {
-      h["Authorization"] = `Bearer ${this.config.authToken}`;
-    }
-    return h;
+  private get headers(): HeadersInit {
+    return { "Content-Type": "application/json" };
   }
 
   /** Fetch a public billing product by slug. */
   async getProduct(slug: string): Promise<BillingProduct> {
     const url = `${this.config.apiBaseUrl}/billing/products/${slug}/`;
     const resp = await this.fetcher(url, {
-      headers: this.headers(false),
+      headers: this.headers,
     });
     if (!resp.ok) {
       throw new Error(`Failed to fetch product "${slug}": ${resp.status}`);
@@ -54,7 +49,7 @@ export class BillingApiClient {
     const url = `${this.config.apiBaseUrl}/billing/offer-checkout/`;
     const resp = await this.fetcher(url, {
       method: "POST",
-      headers: this.headers(true),
+      headers: this.headers,
       body: JSON.stringify({
         offer_id: params.offerId,
         success_url: params.successUrl,
@@ -76,7 +71,7 @@ export class BillingApiClient {
     const url = `${this.config.apiBaseUrl}/billing/subscribe-free/`;
     const resp = await this.fetcher(url, {
       method: "POST",
-      headers: this.headers(true),
+      headers: this.headers,
       body: JSON.stringify({ offer_id: offerId }),
     });
     if (!resp.ok) {
@@ -91,7 +86,7 @@ export class BillingApiClient {
     const url = `${this.config.apiBaseUrl}/billing/offer-portal/`;
     const resp = await this.fetcher(url, {
       method: "POST",
-      headers: this.headers(true),
+      headers: this.headers,
       body: JSON.stringify({ return_url: returnUrl }),
     });
     if (!resp.ok) {
@@ -103,11 +98,31 @@ export class BillingApiClient {
     return resp.json();
   }
 
+  /**
+   * Eagerly sync subscription state after Stripe checkout redirect.
+   * Call this from your success_url page to avoid waiting for the webhook.
+   */
+  async successSync(): Promise<CachedSubscriptionState | null> {
+    const url = `${this.config.apiBaseUrl}/billing/success-sync/`;
+    const resp = await this.fetcher(url, {
+      method: "POST",
+      headers: this.headers,
+    });
+    if (resp.status === 404) {
+      return null;
+    }
+    if (!resp.ok) {
+      const data = await resp.json().catch(() => ({}));
+      throw new Error(data.detail ?? `Success sync failed: ${resp.status}`);
+    }
+    return resp.json();
+  }
+
   /** Get current user's subscription. */
   async getSubscription(): Promise<SubscriptionInfo | null> {
     const url = `${this.config.apiBaseUrl}/billing/subscription/current/`;
     const resp = await this.fetcher(url, {
-      headers: this.headers(true),
+      headers: this.headers,
     });
     if (resp.status === 404) {
       return null; // No active subscription