feat(billing): Paddle behind a port, checkout, portal and signed webhooks

Billing's only job is to write subscriptions correctly. A provider port with
a Paddle adapter and a null adapter for self-host; checkout mints a
transaction with the founding discount decided server-side; the webhook
route verifies the signature, records the event id before acting, locks per
subscription, re-fetches the entity from Paddle and applies the transition.

Author: Zingzy

config.py

@@ -10,6 +10,7 @@
 
 from __future__ import annotations
 
+from datetime import datetime, timedelta
 from functools import cached_property
 from typing import Literal
 from urllib.parse import urlparse
@@ -681,11 +682,51 @@ class BillingSettings(BaseSettings):
     founding_monthly_usd: int = Field(default=9, ge=0)
     founding_year_usd: int = Field(default=90, ge=0)
     founding_seats: int = Field(default=100, ge=0)
+    founding_window_days: int = Field(default=90, ge=0)
+    # The founding window opens when checkout opens; unset means closed.
+    founding_opened_at: datetime | None = None
+
+    paddle_env: Literal["sandbox", "production"] = "sandbox"
+    paddle_api_key: str = ""
+    paddle_webhook_secret: str = ""
+    paddle_price_pro_monthly: str = ""
+    paddle_price_pro_year: str = ""
+    paddle_discount_founding_first_monthly: str = ""
+    paddle_discount_founding_first_year: str = ""
+    paddle_discount_founding_renew_monthly: str = ""
+    paddle_discount_founding_renew_year: str = ""
 
     @property
     def selfhost(self) -> bool:
         return self.provider == "none"
 
+    @property
+    def founding_until(self) -> datetime | None:
+        if self.founding_opened_at is None:
+            return None
+        return self.founding_opened_at + timedelta(days=self.founding_window_days)
+
+    @model_validator(mode="after")
+    def _paddle_needs_its_keys(self) -> BillingSettings:
+        if self.provider != "paddle":
+            return self
+        missing = [
+            name
+            for name in (
+                "paddle_api_key",
+                "paddle_webhook_secret",
+                "paddle_price_pro_monthly",
+                "paddle_price_pro_year",
+            )
+            if not getattr(self, name)
+        ]
+        if missing:
+            raise ValueError(
+                "BILLING_PROVIDER=paddle needs "
+                + ", ".join(f"BILLING_{m.upper()}" for m in missing)
+            )
+        return self
+
 
 class AppSettings(BaseSettings):
     model_config = SettingsConfigDict(env_file=".env", extra="ignore")
@@ -955,6 +996,14 @@ def _populate_sub_configs_and_secret(self) -> AppSettings:
                 "none for self-host, paddle for the cloud"
             )
 
+        # Sandbox checkouts take Paddle's test card; the webhook would grant real Pro.
+        if (
+            self.env == "production"
+            and self.billing.provider == "paddle"
+            and self.billing.paddle_env != "production"
+        ):
+            raise ValueError("BILLING_PADDLE_ENV must be production in production")
+
         return self
 
     @property

dependencies/__init__.py

@@ -62,6 +62,7 @@
     AccountDeletionSvc,
     ApiKeySvc,
     AppGrantRepo,
+    BillingSvc,
     BulkUrlSvc,
     ClickSink,
     ClickSvc,
@@ -89,6 +90,7 @@
     get_account_deletion_service,
     get_api_key_service,
     get_app_grant_repo,
+    get_billing_service,
     get_bulk_url_service,
     get_click_service,
     get_click_sink,
@@ -129,6 +131,7 @@
     "AppRegistryDep",
     # auth
     "AuthUser",
+    "BillingSvc",
     "BulkUrlSvc",
     "ClickSink",
     "ClickSvc",
@@ -173,6 +176,7 @@
     "get_api_key_service",
     "get_app_grant_repo",
     "get_app_registry",
+    "get_billing_service",
     "get_bulk_url_service",
     "get_click_service",
     "get_click_sink",

dependencies/services.py

@@ -23,6 +23,7 @@
 from services.auth.device import DeviceAuthService
 from services.auth.password import PasswordService
 from services.auth.verification import EmailVerificationService
+from services.billing.service import BillingService
 from services.bulk_url_service import BulkUrlService
 from services.click import ClickService
 from services.click.sinks import ClickEventSink
@@ -45,6 +46,10 @@
 from services.webhooks.service import WebhookService
 
 
+def get_billing_service(request: Request) -> BillingService:
+    return request.app.state.billing_service
+
+
 def get_url_service(request: Request) -> UrlService:
     return request.app.state.url_service
 
@@ -172,6 +177,7 @@ def get_webhook_service(request: Request) -> WebhookService:
 # ── Annotated type aliases — Depends shortcuts for route signatures ──────────
 
 UrlSvc = Annotated[UrlService, Depends(get_url_service)]
+BillingSvc = Annotated[BillingService, Depends(get_billing_service)]
 UrlPolicy = Annotated[UrlPolicyService, Depends(get_url_policy)]
 BulkUrlSvc = Annotated[BulkUrlService, Depends(get_bulk_url_service)]
 TagSvc = Annotated[TagService, Depends(get_tag_service)]

dependencies/wiring.py

@@ -34,6 +34,7 @@
 )
 from repositories.api_key_repository import ApiKeyRepository
 from repositories.app_grant_repository import AppGrantRepository
+from repositories.billing_event_repository import BillingEventRepository
 from repositories.blocked_domain_repository import BlockedDomainRepository
 from repositories.blocked_url_repository import BlockedUrlRepository
 from repositories.click_repository import ClickRepository
@@ -77,6 +78,12 @@
 from services.auth.otp import OtpService
 from services.auth.password import PasswordService
 from services.auth.verification import EmailVerificationService
+from services.billing import (
+    BillingProvider,
+    BillingService,
+    NullBillingProvider,
+    PaddleProvider,
+)
 from services.bulk_url_service import BulkUrlService
 from services.cf_saas_backend import CfSaasBackend
 from services.click import ClickService, LegacyClickHandler, V2ClickHandler
@@ -323,6 +330,37 @@ def build_entitlement_service(
     )
 
 
+def build_billing_service(
+    db,
+    settings: AppSettings,
+    redis_client,
+    *,
+    http_client,
+    entitlements: EntitlementService,
+    subscriptions: SubscriptionRepository,
+) -> BillingService:
+    billing = settings.billing
+    provider: BillingProvider
+    if billing.provider == "paddle":
+        provider = PaddleProvider(
+            http_client,
+            api_key=billing.paddle_api_key,
+            webhook_secret=billing.paddle_webhook_secret,
+            env=billing.paddle_env,
+        )
+    else:
+        provider = NullBillingProvider()
+    return BillingService(
+        provider,
+        entitlements,
+        subscriptions,
+        BillingEventRepository(db["billing_events"]),
+        redis_client,
+        billing,
+        app_url=settings.app_url,
+    )
+
+
 def build_account_erasure_service(
     db,
     settings: AppSettings,
@@ -479,6 +517,14 @@ def wire_services(app: FastAPI, settings: AppSettings, redis_client) -> None:
     app.state.entitlement_service = build_entitlement_service(
         db, settings, redis_client, store=ent_store
     )
+    app.state.billing_service = build_billing_service(
+        db,
+        settings,
+        redis_client,
+        http_client=http_client,
+        entitlements=app.state.entitlement_service,
+        subscriptions=subscription_repo,
+    )
 
     # ── Infrastructure ───────────────────────────────────────────────────
     url_cache = UrlCache(redis_client, ttl_seconds=settings.redis.redis_ttl_seconds)

errors.py

@@ -212,6 +212,14 @@ class NotConfiguredError(AppError):
     error_code = "not_configured"
 
 
+class BillingProviderError(AppError):
+    """The billing provider answered with an error or not at all; the caller
+    retries or fails loudly, never guesses a plan state."""
+
+    status_code = 502
+    error_code = "billing_provider_error"
+
+
 class R2StorageError(AppError):
     """R2 object PUT failed — the user write that needed it must fail
     loudly rather than store a broken image URL."""

middleware/rate_limiter.py

@@ -77,6 +77,9 @@ class Limits:
     API_KEY_READ = "60 per minute"
     API_KEY_DELETE = "30 per minute"
 
+    # Billing: checkout and portal links are cheap to mint, expensive to spam.
+    BILLING_WRITE = "10 per minute"
+
     # Per-user page layouts (client debounces writes)
     LAYOUT_READ = "120 per minute"
     LAYOUT_WRITE = "60 per minute"