@startsimpli/billing 0.4.12 → 0.4.15

package/README.md

@@ -1,145 +1,343 @@
 # @startsimpli/billing
 
-Universal billing integration for StartSimpli Next.js apps. Products and pricing are configured in Django admin — frontend components auto-fetch and render.
+Universal billing UX for StartSimpli apps — auto-enrol on signup, real current-plan card with usage progress, structured limit-reached errors, full subscription-state matrix (trial / past-due / cancelled-in-period / incomplete / non-owner), and a tier-limit nudge that any list page can drop in.
 
-## Backend Setup
+**Shipping principle:** every component, hook, and adapter contract lives here or in `apps.billing` (Django). Apps add only (a) a slug to `BILLING_AUTO_SUBSCRIBE_PRODUCT_SLUGS` + `BILLING_USAGE_ADAPTERS`, (b) one `apps.<name>.billing.usage.collect(user, team)` callable, (c) `<BillingProvider>` at the dashboard root, and (d) `<SubscriptionManager productId="..." />` on `/settings/billing`. ~40 LOC of app-side glue. Don't reinvent.
 
-The billing backend lives in `start-simpli-api/apps/billing/`. Models, admin, and API are already configured.
+---
 
-### Key Endpoints
+## Quick start (wire a new app in <40 LOC)
 
-| 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 |
+### 1. Django side (`start-simpli-api/backend/`)
 
-### Admin Workflow
+```python
+# config/settings/base.py
+BILLING_AUTO_SUBSCRIBE_PRODUCT_SLUGS = [
+    s.strip() for s in os.environ.get(
+        "BILLING_AUTO_SUBSCRIBE_PRODUCT_SLUGS", "vault,my-new-app"
+    ).split(",") if s.strip()
+]
 
-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
+BILLING_USAGE_ADAPTERS = {
+    "vault": "apps.vault.billing.usage.collect",
+    "my-new-app": "apps.my_new_app.billing.usage.collect",
+}
+```
 
-## Frontend Setup
+```python
+# apps/my_new_app/billing/usage.py
+def collect(user, team) -> dict[str, int]:
+    """Return raw counts keyed by ProductOffer.features[].key.
+    The billing endpoint merges these with limits from the user's current
+    subscription's offer features — apps just report counts."""
+    company = team.company
+    return {
+        "projects": company.projects.count(),
+        "members_per_project": company.projects.annotate(n=Count("members")).aggregate(m=Max("n"))["m"] or 0,
+    }
+```
 
-### Installation
+That's the entire backend wiring. Auto-enrol on signup, the usage endpoint, the `limit_reached` 402 contract — all already in `apps.billing`. See "Limit enforcement" below for how to opt your data models in.
 
-In your Next.js app's `package.json`:
+### 2. Next.js side (`my-new-app/`)
 
-```json
-{
-  "dependencies": {
-    "@startsimpli/billing": "workspace:*"
-  }
+```tsx
+// src/app/(dashboard)/layout.tsx — hoist BillingProvider once
+'use client';
+import { BillingProvider } from '@startsimpli/billing';
+import { authFetch } from '@startsimpli/auth';
+
+export default function DashboardLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <BillingProvider apiBaseUrl="/api" fetcher={authFetch}>
+      {children}
+    </BillingProvider>
+  );
+}
+```
+
+```tsx
+// src/app/(dashboard)/settings/billing/page.tsx — ~30 LOC
+'use client';
+import { useEffect, useState } from 'react';
+import { SubscriptionManager, useCheckout } from '@startsimpli/billing';
+import type { ProductOffer } from '@startsimpli/billing';
+
+export default function BillingSettingsPage() {
+  const { checkout } = useCheckout();
+  const [status, setStatus] = useState<'success' | 'cancelled' | null>(null);
+
+  useEffect(() => {
+    const s = new URLSearchParams(window.location.search).get('status');
+    if (s === 'success' || s === 'cancelled') setStatus(s);
+  }, []);
+
+  const returnUrl = typeof window !== 'undefined'
+    ? `${window.location.origin}/settings/billing` : '/settings/billing';
+
+  // Free offers → SubscriptionManager calls subscribe-free internally;
+  // paid offers route through this Stripe checkout shim.
+  const onPaidPlanChange = async (offer: ProductOffer) => {
+    const { url } = await checkout({
+      offerId: offer.id,
+      successUrl: `${returnUrl}?status=success`,
+      cancelUrl: `${returnUrl}?status=cancelled`,
+    });
+    window.location.href = url;
+  };
+
+  return (
+    <SubscriptionManager
+      productId="my-new-app"
+      returnUrl={returnUrl}
+      onPlanChange={onPaidPlanChange}
+      statusMessage={status}
+    />
+  );
 }
 ```
 
-Add `transpilePackages: ['@startsimpli/billing']` to `next.config.js`.
+You also need 7 thin proxy routes under `src/app/api/billing/*` (products, subscription/current, offer-checkout, offer-portal, subscribe-free, success-sync, usage/[slug]) — copy them verbatim from `vault-web/src/app/api/billing/`. The products + subscription proxies need `fromSnake: true` (Django's public endpoints bypass the camelCase middleware).
 
-### Usage
+That's everything. The billing page now renders:
+- Auto-enrolled Free plan with live usage progress
+- Per-card CTAs that respect the user's current sub (Pro user sees "Downgrade to Free", not "Get Started")
+- "Upgrade to <NextTier>" CTA on free-tier users
+- Trial countdown, past-due red banner, cancelled-in-period banner with Reactivate
+- Read-only view for non-owner team members
+- Auto-revert to Free when a paid sub expires
+
+---
+
+## Limit enforcement (the `limit_reached` 402 contract)
+
+When you want to block creates past a tier's limit, raise `apps.<myapp>.billing.limits.LimitReached` (or use the helper):
+
+```python
+# In your viewset's perform_create — adapter mirror of apps.vault.billing.limits
+from apps.vault.billing.limits import enforce_limit
+
+def perform_create(self, serializer):
+    team = self.request.user.team_memberships.first().team
+    current = Project.objects.filter(company=team.company).count()
+    enforce_limit(team, "projects", current, "projects")  # 402 if at/over the offer's limit
+    serializer.save(...)
+```
+
+The handler at `apps.core.exceptions.custom_exception_handler` preserves your structured `code` (`limit_reached`) and ships `feature_key`, `limit`, `current` at the top level of the response. Silent (allows) on missing-sub / missing-feature / `limit=-1` (unlimited) — billing misconfig must never block a healthy team.
+
+Client-side, sniff `ApiException.code === 'limit_reached'` and surface the backend's human message:
 
 ```tsx
-import { BillingProvider, PricingPage, useCheckout, ManageSubscription } from '@startsimpli/billing'
+import { ApiException } from '@startsimpli/api';
+
+try {
+  await createProject.mutateAsync(...);
+  notifyUsageChanged('my-new-app');  // refresh the LimitNudge bar immediately
+} catch (err) {
+  if (err instanceof ApiException && err.code === 'limit_reached') {
+    setFormError(err.message);  // 'Your Free plan allows 3 projects. Upgrade to add more.'
+  }
+}
+```
 
-// 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 })
+## Backend reference
 
-// Subscription management
-<ManageSubscription returnUrl="/settings" buttonText="Manage Billing" />
+### 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 (raw snake_case) |
+| `/api/v1/billing/subscription/current/` | GET | Required | Current sub incl. `viewer_is_owner` + `owner_email` |
+| `/api/v1/billing/usage/{slug}/` | GET | Required | Per-product `{feature_key: {used, limit}}` |
+| `/api/v1/billing/offer-checkout/` | POST | Required | Create Stripe checkout session |
+| `/api/v1/billing/offer-portal/` | POST | Required | Create Stripe customer portal session |
+| `/api/v1/billing/subscribe-free/` | POST | Required | Subscribe to a `unit_price=0` offer (no Stripe) |
+| `/api/v1/billing/success-sync/` | POST | Required | Pull subscription state from Stripe on checkout return |
+
+### Settings
+
+```python
+# Comma-separated env, defaults to "vault"
+BILLING_AUTO_SUBSCRIBE_PRODUCT_SLUGS = ["vault", "raise-simpli", ...]
+
+# Per-product usage adapter callable paths
+BILLING_USAGE_ADAPTERS = {
+    "vault": "apps.vault.billing.usage.collect",
+}
 ```
 
+### Signals (auto-magic)
+
+- `post_save` on `TeamMember` → `auto_subscribe_team_to_default_free_offers` (startsim-bc8). When a team's OWNER joins, subscribe the team to every listed product's free offer.
+- `post_save` on `Subscription` → terminal-status auto-revert (startsim-7qh). When a PAID sub enters `cancelled` / `incomplete_expired` / `unpaid` / `trial_expired` and no other active sub exists, reactivate the team's pre-existing Free row instead of leaving them on "No active subscription".
+
+### Admin workflow
+
+1. Add a `BillingProviderCredential` (Stripe secret key + webhook secret).
+2. Create a `BillingProduct` (`slug` = the identifier the frontend uses as `productId`).
+3. Add `ProductOffer` inlines. `features` JSON shape:
+   ```json
+   [
+     {"key": "projects",         "name": "Projects",          "value": 3, "limit": 3},
+     {"key": "members_per_proj", "name": "Members per project", "value": -1, "limit": -1},
+     {"key": "sso",              "name": "SSO",                "value": true}
+   ]
+   ```
+   - `limit: -1` means unlimited
+   - boolean `value: true` renders a checkmark
+   - boolean `value: false` is OMITTED from the card (you don't get to brag about what you don't have)
+4. Use "Sync to provider" admin action to push the offers to Stripe.
+
+---
+
+## Frontend reference
+
 ### 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 |
+| Component | Purpose | Notes |
+|---|---|---|
+| `BillingProvider` | Context provider. Required wrapper. | Hoist to dashboard layout; one provider per app. |
+| `SubscriptionManager` | The whole `/settings/billing` experience. | Renders CurrentPlanCard + per-card grid + state banners + status banners. |
+| `CurrentPlanCard` | The "you are here" widget. | State banners (trial countdown, past-due, cancelled-in-period, incomplete) + feature list with usage progress + upgrade slot. Presentational — testable without provider context. |
+| `LimitNudge` | Usage strip for list-page headers. | `data-state="ok" / "approaching" / "at-cap"`; hidden on `limit=-1` / missing / errors. |
+| `PricingPage` / `PricingSection` / `PricingDetailPage` | Pre-billing display surfaces. | For marketing / landing pages. |
+| `UpgradeModal` | Modal pricing overlay. | For mid-flow upgrade prompts. |
+| `ManageSubscription` | Bare portal redirect button. | Use `SubscriptionManager` instead unless you really just want the button. |
+| `PlanGate` | Feature-gate wrapper. | Show / hide children based on the user's offer features. |
 
 ### 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 |
+| Hook | Returns | Notes |
+|---|---|---|
+| `useProduct(slug)` | `{ product, loading, error, refetch }` | Fetch product + offers |
+| `useSubscription()` | `{ subscription, loading, error, refetch }` | Current sub incl. `viewerIsOwner` + `ownerEmail` |
+| `useUsage(slug)` | `{ usage, loading, error, refetch }` | `{feature_key: {used, limit}}` map; auto-refetches on `visibilitychange` + `billing:usage-changed` event |
+| `useCheckout()` | `{ checkout, subscribeFree, loading, error }` | Stripe session creator + free-subscribe in one |
+| `usePortal()` | `{ openPortal, loading, error }` | Stripe customer portal session |
+| `useSuccessSync()` | `{ sync, data, loading, error }` | Pull subscription state from Stripe on `?status=success` (auto-fired inside SubscriptionManager) |
+
+### Imperative helpers
+
+```tsx
+import { notifyUsageChanged, USAGE_CHANGED_EVENT } from '@startsimpli/billing';
+
+// Call after any mutation that changed counts. Every mounted useUsage hook
+// (and therefore every LimitNudge) for the matching slug will refetch.
+notifyUsageChanged('vault');
+
+// notifyUsageChanged() with no slug fires for all slugs.
+```
+
+---
+
+## State matrix
+
+`CurrentPlanCard` shows AT MOST ONE banner at the top, with this precedence:
+
+1. **past_due** → red `role="alert"` "Payment failed on `<date>`. Update your card to keep your subscription active." + "Update card" portal CTA
+2. **cancelled** OR **cancelAtPeriodEnd** → neutral "Your `<Plan>` plan is cancelled. You'll keep access until `<Mon DD, YYYY>`." + "Reactivate" portal CTA
+3. **incomplete** OR **incomplete_expired** → warning "Your `<Plan>` plan setup is incomplete." + "Finish checkout" portal CTA
+4. **trialing** → info "Your trial ends in N days (`<Mon DD, YYYY>`)." (warning style when `≤ 3` days, info otherwise) + "Cancel trial" portal CTA. "ends tomorrow" / "ends today" phrasing on the tail.
+5. none
+
+The status badge in the top-right of the card (`data-testid="plan-status"`) carries `role="status"` and shows the human label (Active / Trialing / Past due / Cancelled / Incomplete / Expired / Unpaid). Trialing includes `until <YYYY-MM-DD>` inline.
+
+## Per-card CTA matrix
+
+The Change Plan grid shows EVERY offer (including the user's current plan, marked with a `CURRENT PLAN` badge + indigo ring). Each card's CTA branches on its direction relative to the user's current sub:
+
+| User on | Card represents | CTA | State |
+|---|---|---|---|
+| (no sub) | any offer | offer.ctaText | enabled |
+| Free | Free | "Current Plan" | **disabled**, with `CURRENT PLAN` badge |
+| Free | Pro | offer.ctaText (e.g. "Start Free Trial") | enabled, trial copy visible |
+| Pro | Free | "Downgrade to Free" | enabled, secondary outline styling |
+| Pro | Pro | "Current Plan" | **disabled**, with `CURRENT PLAN` badge |
+| Pro | Enterprise | offer.ctaText | enabled |
+| Trialing Pro | Pro | "Current Plan" | **disabled** |
+| Non-owner team member | ANY | shown but **disabled** with tooltip "Only the team owner can change the plan" | — |
+
+The standalone "Upgrade to `<PaidName>` →" button on the current-plan card picks the NEXT tier above the current sub by `sortOrder` (featured-preferred). Returns null when the user is on the top tier or there's no paid offer at all (free-only apps).
+
+---
 
 ## Architecture
 
-- **Provider-agnostic**: `BaseBillingProvider` → `StripeBillingProvider` (extensible to Paddle, etc.)
+- **Provider-agnostic backend**: `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
+- **ProductOffer**: Supports flat / per_seat / tiered / volume / usage pricing models
+- **Apps register usage adapters** (`BILLING_USAGE_ADAPTERS`) rather than embedding usage logic in the billing app — keeps billing slug-agnostic
 
-The billing package integrates seamlessly with `@startsimpli/auth`:
-
-```tsx
-import { BillingProvider } from '@startsimpli/billing'
-import { useAuth } from '@startsimpli/auth'
+### Error contract
 
-function App() {
-  const { tokens } = useAuth()
+Backend's `apps.core.exceptions.custom_exception_handler` ships a standardized JSON shape:
 
-  return (
-    <BillingProvider
-      apiBaseUrl={process.env.NEXT_PUBLIC_API_URL + '/api/v1'}
-      authToken={tokens?.access}
-    >
-      {/* Your app */}
-    </BillingProvider>
-  )
+```json
+{
+  "error": "Your Free plan allows 3 environments. Upgrade to add more.",
+  "code": "limit_reached",
+  "statusCode": 402,
+  "feature_key": "environments",
+  "limit": 3,
+  "current": 3,
+  "timestamp": "2026-05-28T18:11:34.655168Z"
 }
 ```
 
-## Environment Variables
+`@startsimpli/api`'s `ApiException` parses this into `.code` + `.details`. Apps branch on `err.code === 'limit_reached'` to surface the human message verbatim and link to /settings/billing.
+
+---
+
+## Environment variables
 
 ```env
 NEXT_PUBLIC_API_URL=https://api.startsimpli.com
 ```
 
-Backend requires:
+Backend:
 ```env
-STRIPE_SECRET_KEY=sk_test_...
+STRIPE_SECRET_KEY=sk_test_...   # real ~107-char test key from dashboard.stripe.com/test/apikeys
 STRIPE_WEBHOOK_SECRET=whsec_...
+BILLING_AUTO_SUBSCRIBE_PRODUCT_SLUGS=vault,my-new-app   # comma-separated
 ```
 
-## Tests
+---
+
+## Verification
 
 ```bash
-# Frontend tests (39 tests)
+# Frontend (71 tests across SubscriptionManager, CurrentPlanCard, LimitNudge,
+# useCheckout, useProduct, usePortal, useSubscription, BillingProvider)
 cd packages/billing
-npm test
+pnpm test                # or `pnpm vitest run`
+pnpm tsc --noEmit        # type-check
 
-# Backend tests (184 tests)
+# Backend (368+ tests in apps/billing/ + apps/vault/)
 cd start-simpli-api
-docker-compose -f docker-compose.local.yml exec -T django pytest apps/billing/tests/ -v
+docker compose -f docker-compose.local.yml exec -T django pytest apps/billing/tests/ -v
+
+# systemeval gates (real DB in Docker)
+systemeval test -e billing_auto_subscribe_gate
+systemeval test -e billing_usage_endpoint_gate
 ```
 
-## Development
+### Live verification policy
 
-```bash
-# Type checking
-npm run type-check
+Every UI change here must be driven through a real browser via the debugg-ai MCP (`mcp__debugg-ai__check_app_in_browser`) against a running localhost dev server. Type-checks + vitest are NOT proof. See the [MCP-default rule in CLAUDE.md](/CLAUDE.md). The canonical pattern for state-driven UI is to flip the test user's `Subscription.status` via Django shell, then drive the billing page — see `startsim-c6p` close-reasons for examples of every state.
 
-# Watch mode for tests
-npm run test:watch
+---
 
-# Coverage report
-npm run test:coverage
-```
+## Real-world reference
+
+`vault-web` is the canonical integration:
+- Backend slug: `vault` in `BILLING_AUTO_SUBSCRIBE_PRODUCT_SLUGS` + `BILLING_USAGE_ADAPTERS`
+- Usage adapter: `apps.vault.billing.usage.collect` (reports `environments` + `secrets_per_env`)
+- Limit enforcement: `apps.vault.billing.limits.enforce_limit` in `EnvironmentViewSet` + `SecretViewSet`
+- Frontend: `<BillingProvider>` in `vault-web/src/app/(dashboard)/layout.tsx` (one provider for the whole dashboard); `<SubscriptionManager productId="vault" />` in `/settings/billing` (34 LOC including the Stripe URL shim); `<LimitNudge>` in `/environments` (env count) and `/environments/[slug]` (per-env secret count); `notifyUsageChanged('vault')` after every env/secret mutation.
+
+Copy that pattern. If you find yourself writing app-local billing UI logic, stop — extend the shared layer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.12",
+  "version": "0.4.15",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -8,7 +8,8 @@
     ".": "./src/index.ts",
     "./client": "./src/index.ts",
     "./server": "./src/server/index.ts",
-    "./types": "./src/types/index.ts"
+    "./types": "./src/types/index.ts",
+    "./mock": "./src/mock/index.ts"
   },
   "files": [
     "src",
@@ -17,15 +18,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "type-check": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "clean": "rm -rf dist"
-  },
   "peerDependencies": {
     "next": ">=14.0.0",
     "react": "^18.0.0 || ^19.0.0",
@@ -53,5 +45,14 @@
     "nextjs",
     "django",
     "startsimpli"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist"
+  }
+}