fix(billing): address PR review before stripe branch landing

Restore .env.example, drop BILLING_ENABLED, optimize nav middleware,
fix webhook retry semantics, use custom Stripe exceptions, standardize
has_permission checks, and revert unrelated footer redesign.

Author: chriscarrollsmith

.env.example

@@ -1,7 +1,45 @@
-# Billing (set to 0 to disable Stripe and hide billing routes/UI)
-BILLING_ENABLED=1
+# Secret key for JWT
+SECRET_KEY=
 
-# Stripe billing (required when BILLING_ENABLED=1)
+# Base URL
+BASE_URL=http://localhost:8000
+
+# Database connection mode (0 = direct, 1 = pooled)
+USE_POOL=0
+
+# Shared database settings
+DB_HOST=127.0.0.1
+DB_SSLMODE=prefer
+
+# Direct connection settings (when USE_POOL=0)
+DB_USER=postgres
+DB_PASSWORD=postgres
+DB_PORT=5432
+DB_NAME=
+
+# Pooled connection settings (when USE_POOL=1)
+# DB_APPUSER=
+# DB_APPUSER_PASSWORD=
+# DB_POOL_PORT=6543
+# DB_POOL_NAME=
+
+# Domain for production (used by Caddy for TLS)
+DOMAIN=
+
+# Rate limit storage: memory (single process) or postgres (multi-worker)
+# RATE_LIMIT_BACKEND=memory
+
+# Comma-separated reverse-proxy peer IPs for X-Forwarded-For (e.g. 127.0.0.1,::1)
+# TRUSTED_PROXY_IPS=
+
+# Set to 0 to disable CSRF checks (not recommended in production)
+# CSRF_ENABLED=1
+
+# Resend
+RESEND_API_KEY=
+EMAIL_FROM=
+
+# Stripe billing (required on the stripe branch)
 STRIPE_SECRET_KEY=
 STRIPE_WEBHOOK_SECRET=
 STRIPE_PRICE_ID=

exceptions/http_exceptions.py

@@ -259,6 +259,30 @@ def __init__(self) -> None:
         )
 
 
+class ActiveSubscriptionError(HTTPException):
+    def __init__(self) -> None:
+        super().__init__(
+            status_code=409,
+            detail="This organization already has an active subscription.",
+        )
+
+
+class StripeServiceUnavailableError(HTTPException):
+    def __init__(self, action: str) -> None:
+        super().__init__(
+            status_code=503,
+            detail=f"Unable to {action}. Please try again later.",
+        )
+
+
+class StripeSessionError(HTTPException):
+    def __init__(self, session_kind: str) -> None:
+        super().__init__(
+            status_code=502,
+            detail=f"Stripe did not return a {session_kind} URL.",
+        )
+
+
 class CsrfError(HTTPException):
     """Raised when CSRF validation fails."""
 

main.py

@@ -2,9 +2,6 @@
 from contextlib import asynccontextmanager
 
 from dotenv import load_dotenv
-
-load_dotenv()
-
 from fastapi import FastAPI, Request, Depends, status
 from fastapi.responses import RedirectResponse, Response
 from fastapi.staticfiles import StaticFiles
@@ -51,8 +48,8 @@
 )
 from exceptions.exceptions import NeedsNewTokens
 from routers.app import billing as billing_router
-from utils.app.credentials import billing_enabled, validate_billing_environment
-from utils.app.billing import billing_nav_href
+from utils.app.credentials import validate_billing_environment
+from utils.app.billing import resolve_billing_nav_href, should_resolve_billing_nav
 from utils.core.db import set_up_db
 
 logger = logging.getLogger("uvicorn.error")
@@ -61,6 +58,7 @@
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
+    load_dotenv()
     validate_billing_environment()
     set_up_db()
     yield
@@ -88,32 +86,12 @@ async def lifespan(app: FastAPI):
 @app.middleware("http")
 async def nav_billing_middleware(request: Request, call_next):
     request.state.billing_nav_href = None
-    if billing_enabled():
+    if should_resolve_billing_nav(request):
         access_token = request.cookies.get("access_token")
         if access_token:
-            from sqlmodel import Session, select
-            from sqlalchemy.orm import selectinload
-
-            from utils.core.db import get_engine
-            from utils.core.dependencies import get_optional_user_from_access_token
-            from utils.core.models import Role, User
-
-            engine = get_engine()
-            with Session(engine) as session:
-                user = get_optional_user_from_access_token(access_token, session)
-                if user and user.id is not None:
-                    eager_user = session.exec(
-                        select(User)
-                        .where(User.id == user.id)
-                        .options(
-                            selectinload(User.roles).selectinload(Role.organization),
-                            selectinload(User.roles).selectinload(Role.permissions),
-                        )
-                    ).first()
-                    if eager_user is not None:
-                        request.state.billing_nav_href = billing_nav_href(
-                            request, eager_user
-                        )
+            request.state.billing_nav_href = resolve_billing_nav_href(
+                request, access_token
+            )
     return await call_next(request)
 
 
@@ -154,9 +132,8 @@ async def csrf_middleware(request: Request, call_next):
 app.include_router(role.router)
 app.include_router(static_pages.router)
 app.include_router(user.router)
-if billing_enabled():
-    app.include_router(billing_router.router)
-    app.include_router(billing_router.webhook_router)
+app.include_router(billing_router.router)
+app.include_router(billing_router.webhook_router)
 
 
 # --- Exception Handling Middlewares ---

pyproject.toml

@@ -41,8 +41,7 @@ dev = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-# load_dotenv() must run before app imports that read environment variables
-"main.py" = ["E402"]
+# load_dotenv() runs before app import in tests/conftest.py
 "tests/conftest.py" = ["E402"]
 
 [tool.ty.rules]

routers/app/billing.py

@@ -6,14 +6,17 @@
 import uuid
 
 import stripe
-from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response
+from fastapi import APIRouter, Depends, Query, Request, Response
 from fastapi.responses import RedirectResponse
 from fastapi.templating import Jinja2Templates
 from sqlmodel import Session
 
 from exceptions.http_exceptions import (
+    ActiveSubscriptionError,
     InsufficientPermissionsError,
     OrganizationNotFoundError,
+    StripeServiceUnavailableError,
+    StripeSessionError,
 )
 from utils.app.billing import (
     billing_status,
@@ -54,15 +57,6 @@ def _require_org_member(user: User, org_id: int):
     return org
 
 
-def _user_permissions_for_org(user: User, org_id: int) -> set:
-    permissions: set = set()
-    for role in user.roles:
-        if role.organization_id == org_id:
-            for permission in role.permissions:
-                permissions.add(permission.name)
-    return permissions
-
-
 @router.get("/{org_id}/billing")
 async def read_billing(
     org_id: int,
@@ -71,14 +65,13 @@ async def read_billing(
     session: Session = Depends(get_session),
 ):
     org = _require_org_member(user, org_id)
-    permissions = _user_permissions_for_org(user, org_id)
-    if AppPermissions.VIEW_BILLING not in permissions:
+    if not user.has_permission(AppPermissions.VIEW_BILLING, org_id):
         raise InsufficientPermissionsError()
 
     billing = get_org_billing(session, org_id)
     status = billing_status(billing)
     settings = stripe_settings()
-    can_manage = AppPermissions.MANAGE_BILLING in permissions
+    can_manage = user.has_permission(AppPermissions.MANAGE_BILLING, org_id)
 
     return templates.TemplateResponse(
         request,
@@ -140,9 +133,7 @@ async def start_checkout(
             "Checkout blocked for org_id=%s: organization already has an active subscription",
             org_id,
         )
-        raise InsufficientPermissionsError(
-            "This organization already has an active subscription."
-        )
+        raise ActiveSubscriptionError()
 
     assert user.account is not None
     billing = get_org_billing(session, org_id)
@@ -158,14 +149,11 @@ async def start_checkout(
         logger.exception(
             "Stripe Checkout session creation failed for org_id=%s", org_id
         )
-        raise HTTPException(
-            status_code=503,
-            detail="Unable to start checkout. Please try again later.",
-        ) from None
+        raise StripeServiceUnavailableError("start checkout") from None
 
     checkout_url = checkout.url
     if not checkout_url:
-        raise InsufficientPermissionsError("Stripe did not return a checkout URL.")
+        raise StripeSessionError("checkout")
     return _redirect_to_stripe(request, checkout_url)
 
 
@@ -193,14 +181,11 @@ async def start_customer_portal(
         )
     except stripe.StripeError:
         logger.exception("Stripe Customer Portal session failed for org_id=%s", org_id)
-        raise HTTPException(
-            status_code=503,
-            detail="Unable to open billing portal. Please try again later.",
-        ) from None
+        raise StripeServiceUnavailableError("open billing portal") from None
 
     portal_url = portal.url
     if not portal_url:
-        raise InsufficientPermissionsError("Stripe did not return a portal URL.")
+        raise StripeSessionError("portal")
     return _redirect_to_stripe(request, portal_url)
 
 
@@ -313,7 +298,7 @@ async def stripe_webhook(
         return Response(status_code=200, content='{"ok": true}')
 
     result = handle_stripe_webhook_event(session, event)
-    if result is WebhookHandleResult.FAILED:
+    if result in {WebhookHandleResult.FAILED, WebhookHandleResult.RETRYABLE}:
         release_webhook_event_claim(session, event.id)
         return Response(status_code=500, content="Webhook handler failed")
 

routers/core/organization.py

@@ -24,7 +24,6 @@
     DataIntegrityError,
 )
 from utils.app.billing import cancel_org_stripe_subscription
-from utils.app.credentials import billing_enabled
 from pydantic import EmailStr
 from utils.core.htmx import is_htmx_request, set_flash_cookie
 
@@ -86,7 +85,6 @@ async def read_organization(
             "AppPermissions": AppPermissions,
             "all_permissions": list(ValidPermissions) + list(AppPermissions),
             "pending_invitations": pending_invitations,
-            "billing_enabled": billing_enabled(),
         },
     )
 

static/css/extras.css

@@ -434,68 +434,6 @@ input:invalid:not(:placeholder-shown) + .invalid-feedback {
     }
 }
 
-/* Site footer: align horizontal padding with navbar; spread copyright and contact. */
-.site-footer-inner {
-    padding-inline: 1.25rem;
-}
-
-.site-footer-row {
-    display: grid;
-    gap: 1.25rem;
-    text-align: center;
-}
-
-.site-footer-copyright,
-.site-footer-links,
-.site-footer-contact {
-    min-width: 0;
-}
-
-.site-footer-heading {
-    font-family: var(--font-display);
-    font-weight: 600;
-    font-size: 1rem;
-    line-height: 1.15;
-    letter-spacing: -0.015em;
-    color: var(--muted);
-    margin: 0 0 0.5rem;
-}
-
-.site-footer-body,
-.site-footer-body a {
-    font-family: var(--font-body);
-    font-size: 1rem;
-    line-height: 1.55;
-    color: var(--muted);
-}
-
-.site-footer-body a:hover {
-    color: var(--primary);
-}
-
-@media (min-width: 992px) {
-    .site-footer-row {
-        grid-template-columns: 1fr auto 1fr;
-        align-items: end;
-        gap: 2rem;
-    }
-
-    .site-footer-copyright {
-        justify-self: start;
-        text-align: start;
-    }
-
-    .site-footer-links {
-        justify-self: center;
-        text-align: center;
-    }
-
-    .site-footer-contact {
-        justify-self: end;
-        text-align: end;
-    }
-}
-
 /* Pending invitations in organization members card. */
 .invitation-list-item-body {
     display: flex;