{
  "schema": "agent-buildprint/publication.v1",
  "publish": true,
  "fileExcludes": [],
  "slug": "stripe-billing-extension",
  "title": "Stripe Billing Extension",
  "creator": "Agent Buildprint",
  "category": "Feature / Extension",
  "tier": "basic",
  "status": "validated",
  "runtime": [
    "Any backend",
    "TypeScript proof"
  ],
  "stack": [
    "Stripe",
    "Webhooks",
    "Entitlements",
    "SaaS"
  ],
  "iconKeys": [
    "typescript",
    "stripe",
    "json"
  ],
  "difficulty": "Medium",
  "featured": true,
  "summary": "Add SaaS billing to any backend without forgetting checkout, subscriptions, trials, portal, webhooks, entitlement checks, and billing UI.",
  "plainDescription": "A portable blueprint for adding paid SaaS billing to an existing backend: checkout, subscriptions, customer portal, webhooks, entitlement checks, and billing settings.",
  "promise": "A practical extension Buildprint for the paid-app foundation coding agents often implement incompletely.",
  "whatYouGet": [
    "Stripe checkout flow",
    "Subscription and trial handling",
    "Customer portal entry point",
    "Verified webhook handler",
    "Server-side entitlement checks",
    "Billing settings UI"
  ],
  "whatYouNeed": [
    "Stripe account and API keys for live billing",
    "Webhook signing secret for production webhooks",
    "Product/pricing decisions from the human",
    "Nothing for mocked/local billing tests"
  ],
  "architectureFlow": [
    "Checkout",
    "Webhook",
    "Subscription",
    "Entitlements",
    "Portal",
    "Billing UI"
  ],
  "includes": [
    "Checkout session",
    "Subscriptions and trials",
    "Customer portal",
    "Webhook handler",
    "Subscription state model",
    "Entitlement guards",
    "Billing settings UI"
  ],
  "risks": [
    "Webhook signature skipped",
    "Frontend state trusted for access",
    "Failed payment states ignored",
    "Portal exposed without auth",
    "Subscription state drift"
  ],
  "checks": [
    "Codex dry-run generated a TypeScript billing proof",
    "npm run build passed in dry-run proof",
    "npm test passed: 6/6 lifecycle tests",
    "Target-stack adapters document Node/TypeScript, Python, Rails, Go, and PHP/Laravel mappings",
    "Webhook signatures verified before state mutation",
    "Premium access uses server-side subscription state",
    "Portal requires authenticated customer",
    "Failed/canceled/trialing states handled"
  ],
  "trustBadges": [
    {
      "label": "Codex dry-run passed",
      "detail": "Fresh Codex run built an offline TypeScript billing proof from the Buildprint package.",
      "tone": "success"
    },
    {
      "label": "6/6 tests passed",
      "detail": "Checkout, portal, webhook signature, lifecycle states, entitlements, and billing UI stub are covered.",
      "tone": "success"
    },
    {
      "label": "Portable backend contract",
      "detail": "Adapters preserve the same checkout, webhook, state, entitlement, portal, and test boundaries across stacks.",
      "tone": "info"
    },
    {
      "label": "No real Stripe calls",
      "detail": "Validation uses mock providers and env var names only; no secrets or network billing calls.",
      "tone": "info"
    }
  ],
  "copyPrompt": "Use the Stripe Billing Extension Buildprint. First bootstrap exact snapshots: agb start https://agent-buildprint.com/buildprints/stripe-billing-extension/package.json . If agb is not installed, clone https://github.com/DomEscobar/agent-buildprint and run node agent-buildprint/bin/agb.js start https://agent-buildprint.com/buildprints/stripe-billing-extension/package.json . Then read .buildprint/next-agent.md and continue. Do not write Buildprint snapshots manually. Adapt adapters to the target stack first; use env var names only and do not call real Stripe APIs in tests."
}