Add Clerk Billing integration with plan enforcement and pricing page

Backend:
- Add plan limits config (Free: 2 cams/1 node, Pro: 10/5, Business: 50/unlimited)
- Parse pla and fea JWT claims for active plan and features
- Add GET /api/nodes/plan endpoint returning plan, usage, and limits
- Enforce node creation limits based on org plan tier
- Rewrite webhook handler with correct Clerk billing event types
  (subscription.active, subscriptionItem.canceled, subscription.pastDue)
- Set org member limits via Clerk API on plan changes (2/10/20)

Frontend:
- Add PricingPage with Clerk <PricingTable for="organization" />
- Add Subscription section to Settings with plan badge and usage bars
- Add /pricing route and nav link
- Add getPlanInfo API function

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Sbussiso

backend/app/api/nodes.py

@@ -6,8 +6,9 @@
 from sqlalchemy.orm import Session
 
 from app.core.database import get_db
-from app.core.auth import AuthUser, require_admin
+from app.core.auth import AuthUser, require_admin, get_current_user
 from app.core.limiter import limiter
+from app.core.plans import get_plan_limits, get_plan_display_name
 from app.models.models import CameraNode, Camera
 from app.schemas.schemas import NodeRegister, NodeHeartbeat, CameraReport, NodeCreate
 from app.services.storage import get_storage
@@ -232,12 +233,43 @@ async def list_nodes(
     return [n.to_dict() for n in nodes]
 
 
+@router.get("/plan")
+async def get_plan_info(
+    user: AuthUser = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """Return the org's current plan, usage, and limits."""
+    limits = get_plan_limits(user.plan)
+    current_nodes = db.query(CameraNode).filter_by(org_id=user.org_id).count()
+    current_cameras = db.query(Camera).filter_by(org_id=user.org_id).count()
+    return {
+        "plan": user.plan,
+        "plan_name": get_plan_display_name(user.plan),
+        "features": user.features,
+        "limits": limits,
+        "usage": {
+            "nodes": current_nodes,
+            "cameras": current_cameras,
+        },
+    }
+
+
 @router.post("")
 async def create_node(
     data: NodeCreate,
     user: AuthUser = Depends(require_admin),
     db: Session = Depends(get_db),
 ):
+    # Enforce node limit based on plan
+    limits = get_plan_limits(user.plan)
+    current_nodes = db.query(CameraNode).filter_by(org_id=user.org_id).count()
+    if current_nodes >= limits["max_nodes"]:
+        plan_name = get_plan_display_name(user.plan)
+        raise HTTPException(
+            status_code=403,
+            detail=f"Node limit reached ({limits['max_nodes']} on {plan_name} plan). Upgrade your plan to add more nodes.",
+        )
+
     node_id = str(uuid.uuid4())[:8]
     api_key = str(uuid.uuid4())
     api_key_hash = hashlib.sha256(api_key.encode()).hexdigest()

backend/app/api/webhooks.py

@@ -1,26 +1,37 @@
-import json
+import logging
 from fastapi import APIRouter, Request, HTTPException, status
 from svix.webhooks import Webhook, WebhookVerificationError
 from app.core.config import settings
 from app.core.clerk import clerk
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter(prefix="/api/webhooks", tags=["webhooks"])
 
-PRO_TIER_SLUG = "pro_tier"
-FREE_TIER_LIMIT = 2
-UNLIMITED_LIMIT = 1000000
+# Member limits per plan — must match Clerk Dashboard plan keys.
+PLAN_MEMBER_LIMITS = {
+    "free_org": 2,
+    "pro": 10,
+    "business": 20,
+}
 
 
 def set_org_member_limit(org_id: str, limit: int):
-    clerk.organizations.update(organization_id=org_id, max_allowed_memberships=limit)
+    """Update the Clerk org's max allowed memberships."""
+    try:
+        clerk.organizations.update(organization_id=org_id, max_allowed_memberships=limit)
+        logger.info("Set org %s member limit to %d", org_id, limit)
+    except Exception:
+        logger.error("Failed to set member limit for org %s", org_id, exc_info=True)
 
 
-def has_active_pro_plan(items: list) -> bool:
-    return any(
-        item.get("plan", {}).get("slug") == PRO_TIER_SLUG
-        and item.get("status") == "active"
-        for item in items
-    )
+def get_active_plan_slug(items: list) -> str:
+    """Extract the active plan slug from subscription items."""
+    for item in items:
+        plan = item.get("plan", {})
+        if item.get("status") == "active" and plan.get("slug"):
+            return plan["slug"]
+    return "free_org"
 
 
 @router.post("/clerk")
@@ -29,8 +40,7 @@ async def clerk_webhook(request: Request):
     headers = dict(request.headers)
 
     if not settings.CLERK_WEBHOOK_SECRET:
-        import logging
-        logging.getLogger(__name__).warning("CLERK_WEBHOOK_SECRET not set — rejecting unverified webhook")
+        logger.warning("CLERK_WEBHOOK_SECRET not set — rejecting unverified webhook")
         raise HTTPException(status.HTTP_500_INTERNAL_SERVER_ERROR, "Webhook secret not configured")
 
     try:
@@ -42,19 +52,39 @@ async def clerk_webhook(request: Request):
     event_type = event.get("type")
     data = event.get("data", {})
 
-    if event_type in ["subscription.created", "subscription.updated"]:
+    logger.info("Webhook received: %s", event_type)
+
+    # ── Subscription lifecycle ──────────────────────────────────────
+    if event_type in ("subscription.created", "subscription.updated", "subscription.active"):
         org_id = data.get("payer", {}).get("organization_id")
         if org_id:
-            limit = (
-                UNLIMITED_LIMIT
-                if has_active_pro_plan(data.get("items", []))
-                else FREE_TIER_LIMIT
-            )
+            plan_slug = get_active_plan_slug(data.get("items", []))
+            limit = PLAN_MEMBER_LIMITS.get(plan_slug, PLAN_MEMBER_LIMITS["free_org"])
             set_org_member_limit(org_id, limit)
+            logger.info("Org %s subscription active on plan '%s'", org_id, plan_slug)
+
+    # ── Payment failure ─────────────────────────────────────────────
+    elif event_type == "subscription.pastDue":
+        org_id = data.get("payer", {}).get("organization_id")
+        if org_id:
+            logger.warning("Org %s subscription is past due — payment failed", org_id)
+            # Keep current limits for a grace period; Clerk will retry payment.
+            # If you want to restrict access, downgrade here.
+
+    # ── Cancellation / end ──────────────────────────────────────────
+    elif event_type in ("subscriptionItem.canceled", "subscriptionItem.ended"):
+        org_id = data.get("payer", {}).get("organization_id")
+        if org_id:
+            # Clerk auto-assigns the free default plan on cancellation,
+            # so the JWT pla claim will revert. Just reset member limit.
+            set_org_member_limit(org_id, PLAN_MEMBER_LIMITS["free_org"])
+            logger.info("Org %s subscription canceled — reverted to free limits", org_id)
 
-    elif event_type in ["subscription.deleted", "subscription.cancelled"]:
+    # ── Free trial ending soon ──────────────────────────────────────
+    elif event_type == "subscriptionItem.freeTrialEnding":
         org_id = data.get("payer", {}).get("organization_id")
         if org_id:
-            set_org_member_limit(org_id, FREE_TIER_LIMIT)
+            logger.info("Org %s free trial ending in 3 days", org_id)
+            # Future: send notification email
 
     return {"received": True}

backend/app/core/auth.py

@@ -14,6 +14,8 @@ def __init__(
         org_permissions: list = None,
         email: str = "",
         username: str = "",
+        plan: str = "free_org",
+        features: list = None,
     ):
         self.user_id = user_id
         self.sub = user_id
@@ -22,6 +24,8 @@ def __init__(
         self.org_permissions = org_permissions or []
         self.email = email
         self.username = username
+        self.plan = plan
+        self.features = features or []
 
     def has_permission(self, permission: str) -> bool:
         return permission in self.org_permissions
@@ -124,6 +128,20 @@ async def get_current_user(request: Request) -> AuthUser:
         email = claims.get("email", "")
         username = claims.get("username", "")
 
+        # Extract active plan from V2 JWT (e.g. "o:pro" -> "pro")
+        plan_claim = claims.get("pla", "")
+        active_plan = plan_claim.split(":")[-1] if plan_claim else "free_org"
+
+        # Extract active features from fea claim
+        fea_claim = claims.get("fea", "")
+        active_features = []
+        for f in fea_claim.split(","):
+            f = f.strip()
+            if f.startswith("o:"):
+                active_features.append(f[2:])
+            elif f:
+                active_features.append(f)
+
         # Extract org_id and org_role from V1 or V2 JWT format
         # V1: top-level org_id and org_role claims
         # V2: compact "o" claim with id and rol fields
@@ -149,6 +167,8 @@ async def get_current_user(request: Request) -> AuthUser:
             org_permissions=org_permissions,
             email=email,
             username=username,
+            plan=active_plan,
+            features=active_features,
         )
     except HTTPException:
         raise

backend/app/core/plans.py

@@ -0,0 +1,38 @@
+"""
+Plan configuration and limit enforcement for OpenSentry billing tiers.
+
+Plan slugs must match the keys defined in the Clerk Dashboard:
+  - free_org  (Free)
+  - pro       (Pro — $19/mo)
+  - business  (Business — $49/mo)
+"""
+
+PLAN_LIMITS = {
+    "free_org": {
+        "max_cameras": 2,
+        "max_nodes": 1,
+    },
+    "pro": {
+        "max_cameras": 10,
+        "max_nodes": 5,
+    },
+    "business": {
+        "max_cameras": 50,
+        "max_nodes": 999,  # effectively unlimited
+    },
+}
+
+
+def get_plan_limits(plan: str) -> dict:
+    """Return the limits dict for a plan slug. Falls back to free tier."""
+    return PLAN_LIMITS.get(plan, PLAN_LIMITS["free_org"])
+
+
+def get_plan_display_name(plan: str) -> str:
+    """Human-readable plan name."""
+    names = {
+        "free_org": "Free",
+        "pro": "Pro",
+        "business": "Business",
+    }
+    return names.get(plan, "Free")

frontend/src/App.jsx

@@ -14,6 +14,7 @@ const DashboardPage = lazy(() => import("./pages/DashboardPage.jsx"))
 const SettingsPage = lazy(() => import("./pages/SettingsPage.jsx"))
 const AdminPage = lazy(() => import("./pages/AdminPage.jsx"))
 const TestHlsPage = lazy(() => import("./pages/TestHlsPage.jsx"))
+const PricingPage = lazy(() => import("./pages/PricingPage.jsx"))
 
 function RequireOrg({ children }) {
   const { organization, isLoaded } = useOrganization()
@@ -111,6 +112,14 @@ function App() {
 
         {/* Authenticated routes with Layout */}
         <Route element={<Layout />}>
+          <Route
+            path="/pricing"
+            element={
+              <RequireOrg>
+                <PricingPage />
+              </RequireOrg>
+            }
+          />
           <Route
             path="/dashboard"
             element={

frontend/src/components/Layout.jsx

@@ -47,6 +47,9 @@ function Layout() {
                         </Link>
                       </>
                     )}
+                    <Link to="/pricing" className={isActive("/pricing")}>
+                      Pricing
+                    </Link>
                   </nav>
                 </>
               )}