seams 0.1.0

data/lib/generators/seams/billing/templates/README.md.tt

@@ -0,0 +1,355 @@
+# Billing
+
+> Subscription billing for a Seams-powered host. Stripe by default,
+> swap-able to any gateway via the `Billing::Gateways::Abstract`
+> contract.
+
+**Requires:** by default, the `accounts` engine — billing rows
+carry `account_id` and the `Billing::Billable` concern auto-includes
+into `Billing.configuration.billable_class` (default
+`"Accounts::Account"`). Hosts that prefer User-as-customer
+override `billable_class` in `config/initializers/billing.rb` and
+can run without the accounts engine.
+
+## The Account-as-customer model
+
+Post-Wave-9, the **Stripe customer represents an Account, not an
+Identity (human)**. Subscriptions, invoices, and lifetime passes
+belong to the tenant. The same Identity who is a member of two
+Accounts has two independent billing relationships — even though
+they're the same human.
+
+Concrete: every billing table carries `account_id` (UUID, the
+`Accounts::Account#id`) as its local foreign key. The Stripe
+`customer_ref` (the `cus_*` id) is also stored on every row, so
+webhook handlers can address rows either way. There is no
+`user_id` / `host_user_id` column anywhere — those were removed in
+this refactor.
+
+`granted_by_identity_id` and `revoked_by_identity_id` on
+`billing_lifetime_passes` are deliberate exceptions: they reference
+an `Auth::Identity` (the human who pressed the "grant" or "revoke"
+button), not an Account. The columns track human action, not
+tenant-level data.
+
+### Migration story for hosts on a prior wave
+
+If your host already had Wave 8 billing in production with `user_id`
+on `billing_subscriptions` etc, those columns are gone. Write a
+host-side data migration that backfills `account_id` from your
+existing User → Account mapping before adopting the new schema.
+There is no automated migration shipped with seams — every host's
+mapping is different.
+
+## Wiring `Billing::Billable` into your tenant model
+
+`Billing::Billable` provides the helpers that the host's tenant
+model needs:
+
+```ruby
+account.billing_subscriptions          # association
+account.billing_invoices               # association
+account.billing_lifetime_passes        # association
+account.has_active_billing?            # paying right now?
+account.lifetime?                      # holds an active LTD?
+account.has_lifetime_for?(plan_ref:)   # specific LTD?
+account.start_subscription!(plan_ref:, email:)
+account.cancel_subscription!(subscription_ref:)
+account.stripe_customer_ref!(email:)   # lazy Stripe customer creation
+```
+
+The engine wires the concern into `Accounts::Account` automatically
+at boot via:
+
+```ruby
+# lib/billing/engine.rb (paraphrased)
+config.to_prepare do
+  Billing.configuration.billable_class.constantize.include(Billing::Billable)
+end
+```
+
+Override the target class in `config/initializers/billing.rb` if your
+tenant lives on a different model:
+
+```ruby
+Billing.configure do |c|
+  c.billable_class = "Workspaces::Workspace"
+end
+```
+
+Set `c.billable_class = nil` to opt out and `include Billing::Billable`
+manually wherever it makes sense.
+
+## Events emitted
+
+All billing events publish the **same canonical payload shape** so
+subscribers can read one format regardless of source:
+
+```
+{ gateway:      "stripe",      # which adapter emitted it
+  livemode:     true | false,  # gateway's livemode flag
+  account_id:   "uuid",        # the Accounts::Account that owns this row
+  customer_ref: "cus_xxx",     # gateway customer id
+  ref:          "sub_xxx",     # canonical id of the subject
+  object_id:    "sub_xxx",     # raw object id from the gateway
+  object:       { ... } }      # the gateway object as a hash (incl. account_id where applicable)
+```
+
+| Event name                                  | Subject       | Emitted when |
+| ---                                         | ---           | --- |
+| `subscription.created.billing`              | Subscription  | StartSubscriptionJob succeeds, or `customer.subscription.created` webhook fires |
+| `subscription.updated.billing`              | Subscription  | `customer.subscription.updated` webhook fires |
+| `subscription.canceled.billing`             | Subscription  | CancelSubscriptionJob succeeds, or `customer.subscription.deleted` webhook fires |
+| `subscription.trial_will_end.billing`       | Subscription  | `customer.subscription.trial_will_end` webhook fires (~3 days before trial end) |
+| `invoice.created.billing`                   | Invoice       | `invoice.created` webhook fires (status: draft) |
+| `invoice.paid.billing`                      | Invoice       | `invoice.paid` webhook fires |
+| `invoice.failed.billing`                    | Invoice       | `invoice.payment_failed` webhook fires |
+| `invoice.finalized.billing`                 | Invoice       | `invoice.finalized` webhook fires |
+| `invoice.voided.billing`                    | Invoice       | `invoice.voided` webhook fires |
+| `payment.succeeded.billing`                 | PaymentIntent | `payment_intent.succeeded` webhook fires |
+| `payment.failed.billing`                    | PaymentIntent | `payment_intent.payment_failed` webhook fires |
+| `charge.refunded.billing`                   | Charge        | `charge.refunded` webhook fires |
+| `checkout.session_completed.billing`        | CheckoutSession | `checkout.session.completed` webhook fires (subscription mode; LTD mode forks to lifetime.purchased.billing) |
+| `lifetime.granted.billing`                  | LifetimePass  | Admin grants a Lifetime Deal via `Billing::Lifetime::GrantPassService`. Includes `granted_by_identity_id`. |
+| `lifetime.purchased.billing`                | LifetimePass  | Customer pays for an LTD via Stripe Checkout `mode: "payment"` |
+| `lifetime.revoked.billing`                  | LifetimePass  | `Billing::Lifetime::RevokePassService` is called. Includes `revoked_by_identity_id`. |
+
+The webhook controller upserts a local `Billing::Subscription` /
+`Billing::Invoice` row before publishing, so subscribers can resolve
+either from `payload[:account_id]` directly or by querying the
+local DB with `payload[:ref]`.
+
+## Events consumed
+
+This engine does not subscribe to any other engine's events by default.
+Hosts often subscribe to `account.created.accounts` to create a Stripe
+customer at tenant creation time.
+
+## Exposed concerns
+
+| Concern              | Purpose                                                                        |
+| ---                  | ---                                                                            |
+| `Billing::Billable`  | Mix into your tenant model (default `Accounts::Account`) for `start_subscription!` / `cancel_subscription!` / `lifetime?` / `has_lifetime_for?(plan_ref:)` / `has_active_billing?` helpers. The engine auto-includes it via `Billing.configuration.billable_class` at boot. |
+
+## Lifetime Deals (LTD)
+
+The engine ships native LTD support — one-time payment for permanent
+access — alongside recurring subscriptions. Two flows:
+
+1. **Public purchase** — Stripe Checkout with `mode: "payment"`. The
+   pricing page renders any `Billing::Plan` with `interval: "lifetime"`
+   under a "Buy once, own forever" section. POST
+   `/billing/checkout/lifetime?plan=<gateway_ref>` →
+   `Billing::Lifetime::CreateLifetimeSessionService` (which threads
+   the current Account's id into Stripe session metadata) →
+   redirect to Stripe → on `checkout.session.completed` (or
+   `checkout.session.async_payment_succeeded`) the webhook handler
+   creates the `Billing::LifetimePass` row (with `account_id` read
+   off the metadata) and publishes `lifetime.purchased.billing`.
+
+2. **Private grant** — admin issues an LTD without a Stripe charge via
+   `Billing::Admin::LifetimePassesController` (mounted at
+   `/billing/admin/lifetime_passes`). Use for early adopters,
+   influencer giveaways, ToS-violation refund-then-re-grant. Calls
+   `Billing::Lifetime::GrantPassService` with the target Account's id
+   AND the Identity of the admin pressing the button. Publishes
+   `lifetime.granted.billing` with `granted_by_identity_id` set.
+
+### Trade-off (read this before turning LTDs on)
+
+LTDs lock you into supporting those users **indefinitely with no
+recurring revenue**. They're a strong early-adopter / launch lever —
+quick cash, fast feedback — but get expensive long-term as your
+support load grows while LTD users contribute zero MRR. Cap inventory
+on every LTD plan via `max_lifetime_units` (nil = unlimited):
+
+```ruby
+Billing::Plan.create!(
+  gateway_ref:        "price_lifetime_pro_2026",
+  name:               "Pro Lifetime",
+  interval:           "lifetime",
+  amount_cents:       249_00,
+  currency:           "usd",
+  max_lifetime_units: 100   # only the first 100 buyers
+)
+```
+
+The pricing page reads `Plan#lifetime_inventory_remaining` and
+disables the "Buy lifetime" button when `lifetime_sold_out?`.
+
+### Authorization model
+
+The engine ships no admin gate — `Billing::Admin::LifetimePassesController`
+mounts at `/billing/admin/...` and the host wires their own
+`require_admin!` `before_action` (ActiveAdmin / Avo / your own
+solution). Per the issue #2 4B scope decision, Seams doesn't ship its
+own admin engine.
+
+### Revoke
+
+`Billing::Lifetime::RevokePassService.call(pass:, revoked_by:, notes:)`
+soft-revokes via `revoked_at`. `revoked_by` is an Auth::Identity
+(the human pressing the revoke button); pass `nil` for system-revoked
+passes. The pass row stays in the DB so the audit trail survives.
+Stripe refund (for paid LTDs) is the caller's responsibility — this
+service updates the local row only. Publishes `lifetime.revoked.billing`.
+
+## Gateways
+
+| Gateway                       | Default | Configure via                                                                    |
+| ---                           | ---     | ---                                                                              |
+| `Billing::Gateways::Stripe`   | yes     | `Billing.configure { \|c\| c.gateway = "Billing::Gateways::Stripe" }`            |
+
+To add a gateway, subclass `Billing::Gateways::Abstract` and implement
+`#create_subscription`, `#cancel_subscription`, `#fetch_subscription`,
+`#verify_webhook`. Then point `Billing.configuration.gateway` at the
+new class.
+
+## Webhook setup
+
+Stripe will POST events to `/billing/webhooks/stripe`. The engine
+verifies signatures via `Billing::Stripe::WebhookSignature`. Set:
+
+```bash
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+In your Stripe dashboard, configure the webhook endpoint to send any
+of the events listed below. Each maps to a handler class in
+`app/services/billing/webhooks/handlers/`; missing handlers no-op
+gracefully so subscribing to extras is safe.
+
+| Stripe event                              | Handler                                    | Canonical seams event                |
+| ---                                       | ---                                        | ---                                  |
+| `customer.subscription.created`           | `SubscriptionCreatedHandler`               | `subscription.created.billing`       |
+| `customer.subscription.updated`           | `SubscriptionUpdatedHandler`               | `subscription.updated.billing`       |
+| `customer.subscription.deleted`           | `SubscriptionDeletedHandler`               | `subscription.canceled.billing`      |
+| `customer.subscription.trial_will_end`    | `SubscriptionTrialWillEndHandler`          | `subscription.trial_will_end.billing`|
+| `invoice.created`                         | `InvoiceCreatedHandler`                    | `invoice.created.billing`            |
+| `invoice.paid`                            | `InvoicePaidHandler`                       | `invoice.paid.billing`               |
+| `invoice.payment_failed`                  | `InvoicePaymentFailedHandler`              | `invoice.failed.billing`             |
+| `invoice.finalized`                       | `InvoiceFinalizedHandler`                  | `invoice.finalized.billing`          |
+| `invoice.voided`                          | `InvoiceVoidedHandler`                     | `invoice.voided.billing`             |
+| `payment_intent.succeeded`                | `PaymentSucceededHandler`                  | `payment.succeeded.billing`          |
+| `payment_intent.payment_failed`           | `PaymentFailedHandler`                     | `payment.failed.billing`             |
+| `charge.refunded`                         | `ChargeRefundedHandler`                    | `charge.refunded.billing`            |
+| `checkout.session.completed`              | `CheckoutSessionCompletedHandler`          | (subscription path / LTD path)       |
+
+The handler base resolves `account_id` for each webhook by looking
+up the local `Billing::Subscription` / `Billing::Invoice` row keyed
+on the gateway's `customer_ref`. For brand-new Stripe-initiated
+subscriptions (created in the Stripe Dashboard, not via
+`Account#start_subscription!`), there's no local row to resolve —
+the upsert logs a warning and skips. Reconcile those via a
+host-side sync task that maps Stripe customers to Accounts.
+
+Adding a new event type means registering a handler from your host —
+no fork required:
+
+```ruby
+Billing::Webhooks::EventRouter.register(
+  "customer.tax_id.created",
+  "MyApp::TaxIdCreatedHandler"
+)
+```
+
+Default dispatch is synchronous so handler raises roll back the
+`WebhookEvent` row and Stripe retries. Flip
+`Billing.configuration.process_webhooks_async = true` to enqueue
+`Billing::Webhooks::ProcessEventJob.perform_later` instead — Stripe
+recommends responding in <100ms.
+
+## Self-service controllers
+
+| Controller                                  | Action                                                |
+| ---                                         | ---                                                   |
+| `Billing::SubscriptionsController#index`    | List the current Account's subscriptions              |
+| `#show`                                     | Single subscription with cancel / change-plan controls|
+| `#cancel`                                   | Period-end cancel (immediate via `?immediate=1`)      |
+| `#reactivate`                               | Un-cancel a pending-cancellation subscription         |
+| `#change_plan`                              | Switch to a new price (proration configurable)        |
+| `Billing::InvoicesController#index/#show`   | Read-only billing history                             |
+
+The controllers expect `current_billing_account` to return the
+current `Accounts::Account` — by default they read
+`Accounts::Current.account` (set up by the accounts engine's
+controller concern). Override `#current_billing_account` and
+`#current_billing_customer_ref` in your host's `SubscriptionsController` /
+`InvoicesController` if your tenant resolution is bound differently.
+
+## Stripe API surface used
+
+Every Stripe call has a doc URL cited inline in
+`lib/billing/gateways/stripe.rb` and in each `Billing::Stripe::Client`
+method:
+
+| Stripe call                       | Docs URL                                                             |
+| ---                               | ---                                                                  |
+| `POST /v1/customers`              | https://docs.stripe.com/api/customers/create                         |
+| `GET  /v1/customers/search`       | https://docs.stripe.com/api/customers/search                         |
+| `POST /v1/subscriptions`          | https://docs.stripe.com/api/subscriptions/create                     |
+| `POST /v1/subscriptions/:id`      | https://docs.stripe.com/api/subscriptions/update                     |
+| `DELETE /v1/subscriptions/:id`    | https://docs.stripe.com/api/subscriptions/cancel                     |
+| `GET  /v1/subscriptions/:id`      | https://docs.stripe.com/api/subscriptions/retrieve                   |
+| `GET  /v1/invoices/:id`           | https://docs.stripe.com/api/invoices/retrieve                        |
+| `POST /v1/checkout/sessions`      | https://docs.stripe.com/api/checkout/sessions/create                 |
+| `POST /v1/billing_portal/sessions`| https://docs.stripe.com/api/customer_portal/sessions/create          |
+| Webhook signature verification    | https://docs.stripe.com/webhooks/signatures                          |
+
+## Verifying the Stripe Checkout flow against test mode
+
+For end-to-end confidence in the Stripe wiring, run a real Checkout
+session against Stripe's test mode — no mocks, no webmock.
+
+1. Grab a test secret key + webhook secret from
+   https://dashboard.stripe.com/test/apikeys and
+   https://dashboard.stripe.com/test/webhooks (point the webhook at a
+   tunnelled URL via `stripe listen --forward-to localhost:3000/billing/webhooks/stripe`).
+2. Set the env vars:
+   ```bash
+   STRIPE_SECRET_KEY=sk_test_...
+   STRIPE_WEBHOOK_SECRET=whsec_...   # from `stripe listen` output
+   ```
+3. Seed at least one Plan whose `gateway_ref` matches a Stripe test
+   price id.
+4. Visit `/billing/plans`, click "Subscribe", complete Checkout with
+   the test card `4242 4242 4242 4242`.
+5. Watch your logs — `customer.subscription.created` and
+   `invoice.paid` should arrive within seconds; the local
+   `Billing::Subscription` + `Billing::Invoice` rows should appear
+   with the current Account's id pinned to them.
+6. Visit `/billing/subscriptions` — your new subscription should be
+   listed. Cancel + reactivate via the UI to exercise the full
+   service-object surface.
+
+If webhook events do not arrive, check
+`Billing::WebhookEvent.where(gateway: "stripe").order(created_at: :desc)`
+— rows mean Stripe reached you but a handler raised; absence means
+the signature verification or the URL is wrong.
+
+## Gateway contract specs
+
+The shared example `"a billing gateway"` lives at
+`spec/support/shared_examples/a_billing_gateway.rb`. Every gateway
+adapter (Stripe is the reference; Paddle / Adyen / your own) MUST
+satisfy it:
+
+```ruby
+RSpec.describe Billing::Gateways::Paddle do
+  it_behaves_like "a billing gateway"
+end
+```
+
+The contract checks that every method on `Billing::Gateways::Abstract`
+exists on the subclass with the documented keyword arguments, and
+that `verify_webhook` raises `Billing::WebhookError` on a bad
+signature. Wiring-level correctness ("does Paddle actually charge
+people?") needs an integration test against that gateway's test mode
+— see the Stripe walk-through above for the pattern.
+
+## Running the specs
+
+```bash
+bin/rails seams:test[billing]
+```

data/lib/generators/seams/billing/templates/app/controllers/admin/lifetime_passes_controller.rb.tt

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Billing
+  module Admin
+    # Admin-side controller for issuing + revoking LifetimePasses
+    # without a Stripe charge. Use for early adopters, influencer
+    # giveaways, and ToS revocations.
+    #
+    # Authorization is the host's responsibility — Seams ships no
+    # admin engine (per the explicit scope decision in issue #2 4B).
+    # Mount this behind whatever admin gate the host uses (ActiveAdmin,
+    # Avo, your own #require_admin! before_action).
+    #
+    # Suggested host-side wiring:
+    #
+    #   # config/routes.rb
+    #   namespace :admin do
+    #     resources :lifetime_passes, controller: "billing/admin/lifetime_passes",
+    #                                  only: %i[index new create destroy]
+    #   end
+    #
+    #   # app/controllers/billing/admin/lifetime_passes_controller_decorator.rb
+    #   Billing::Admin::LifetimePassesController.class_eval do
+    #     before_action :require_admin!
+    #   end
+    class LifetimePassesController < ApplicationController
+      def index
+        @passes = Billing::LifetimePass.order(granted_at: :desc).limit(100)
+      end
+
+      def new
+        @plan_options = Billing::Plan.active.lifetime
+      end
+
+      def create
+        result = Billing::Lifetime::GrantPassService.call(
+          account_id:   params.require(:account_id),
+          customer_ref: params.require(:customer_ref),
+          plan_ref:     params.require(:plan_ref),
+          granted_by:   current_admin_identity,
+          notes:        params[:notes]
+        )
+
+        if result.ok?
+          redirect_to billing.admin_lifetime_passes_path,
+                      notice: "Lifetime pass issued."
+        else
+          redirect_to billing.new_admin_lifetime_pass_path,
+                      alert: result.error
+        end
+      end
+
+      def destroy
+        pass   = Billing::LifetimePass.find(params[:id])
+        result = Billing::Lifetime::RevokePassService.call(
+          pass:       pass,
+          revoked_by: current_admin_identity,
+          notes:      params[:notes]
+        )
+
+        if result.ok?
+          redirect_to billing.admin_lifetime_passes_path,
+                      notice: "Lifetime pass revoked."
+        else
+          redirect_to billing.admin_lifetime_passes_path,
+                      alert: result.error
+        end
+      end
+
+      private
+
+      # Override in the host. The default reads `current_user` if the
+      # host's admin gate uses the same `current_user` helper — for a
+      # post-Wave-9 host that means the Auth::Identity row currently
+      # signed in. Pre-Wave-9 hosts (host User present) override this
+      # to return the User; the GrantPassService coerces both shapes.
+      def current_admin_identity
+        return nil unless respond_to?(:current_user)
+
+        current_user
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/controllers/checkout_controller.rb.tt

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Billing
+  class CheckoutController < ApplicationController
+    # POST /billing/checkout?plan=price_xxx
+    def create
+      plan = Billing::Plan.active.find_by!(gateway_ref: params[:plan])
+
+      result = Billing::Checkout::CreateSessionService.call(
+        customer_ref: customer_ref_or_create!,
+        plan_ref:     plan.gateway_ref,
+        success_url:  billing.checkout_success_url,
+        cancel_url:   billing.plans_url
+      )
+
+      if result.ok?
+        redirect_to result.url, allow_other_host: true, status: :see_other
+      else
+        redirect_to billing.plans_path, alert: result.error
+      end
+    end
+
+    # GET /billing/checkout/success
+    def success
+      # Stripe will fire `checkout.session.completed` webhook; the
+      # subscription row gets created/updated by the webhook handler.
+      render :success
+    end
+
+    # POST /billing/checkout/lifetime?plan=price_xxx
+    # LTD purchase flow — same shape as #create but uses Stripe's
+    # `mode: "payment"`. The webhook handler distinguishes the two via
+    # session.metadata.access_type.
+    def lifetime
+      plan = Billing::Plan.active.find_by!(gateway_ref: params[:plan])
+
+      result = Billing::Lifetime::CreateLifetimeSessionService.call(
+        account_id:   current_billing_account.id,
+        customer_ref: customer_ref_or_create!,
+        plan_ref:     plan.gateway_ref,
+        success_url:  billing.checkout_success_url,
+        cancel_url:   billing.plans_url
+      )
+
+      if result.ok?
+        redirect_to result.url, allow_other_host: true, status: :see_other
+      else
+        redirect_to billing.plans_path, alert: result.error
+      end
+    end
+
+    private
+
+    # Resolves the Stripe customer id for the current Account. The
+    # host must implement `current_billing_account` (or set it from
+    # a before_action) — typically `Accounts::Current.account`.
+    # Hosts pre-Wave-9 can override the entire method to use their
+    # own user-keyed lookup.
+    def customer_ref_or_create!
+      account = current_billing_account
+      raise Billing::Error, "current_billing_account is not set" unless account
+      raise Billing::Error, "Account #{account.id} does not respond to stripe_customer_ref!" unless account.respond_to?(:stripe_customer_ref!)
+
+      account.stripe_customer_ref!(email: billing_contact_email_for(account))
+    end
+
+    # Override in the host to point at the right contact email for
+    # the Stripe customer record. Default reads `current_user.email`
+    # if the host's auth concern wires one up — usually the right
+    # answer for B2C flows. B2B hosts often want the Account owner's
+    # email instead; override accordingly.
+    def billing_contact_email_for(_account)
+      return current_user.email_address if respond_to?(:current_user) && current_user.respond_to?(:email_address)
+      return current_user.email if respond_to?(:current_user) && current_user.respond_to?(:email)
+
+      raise Billing::Error,
+            "Override #billing_contact_email_for(account) to supply the Stripe customer email."
+    end
+
+    # Default implementation reads `Accounts::Current.account` if the
+    # accounts engine is installed. Override in the host if your
+    # Account is bound differently (e.g. via params, subdomain, etc).
+    def current_billing_account
+      return @current_billing_account if defined?(@current_billing_account)
+
+      @current_billing_account =
+        if defined?(Accounts::Current) && Accounts::Current.respond_to?(:account)
+          Accounts::Current.account
+        end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/controllers/invoices_controller.rb.tt

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Billing
+  # Read-only billing history for the current Account. The local
+  # Billing::Invoice rows are populated by the InvoiceHandlerBase
+  # webhook handlers as Stripe fires invoice.* events; SyncService
+  # can refresh on demand.
+  #
+  # No `download` action — Stripe hosts the PDF; link to the
+  # `hosted_invoice_url` Stripe returns on the invoice object. Saves
+  # us from being a redirect proxy for content we do not own.
+  #
+  #   GET /billing/invoices       → index (paginated history)
+  #   GET /billing/invoices/:id   → show
+  class InvoicesController < ApplicationController
+    before_action :require_invoice, only: %i[show]
+
+    def index
+      @invoices = scoped_invoices.order(created_at: :desc)
+    end
+
+    def show
+      # @invoice is set by require_invoice. Hosts that want a fresh
+      # read from Stripe before rendering can opt in:
+      #
+      #   Billing::Invoices::SyncService.call(invoice_ref: @invoice.gateway_ref)
+      #
+      # The default render is the local DB row — webhook lag is
+      # usually <1s, so this is good enough for almost every UI.
+    end
+
+    private
+
+    def scoped_invoices
+      Billing::Invoice.where(customer_ref: current_billing_customer_ref)
+    end
+
+    def require_invoice
+      @invoice = scoped_invoices.find_by(id: params[:id])
+      return if @invoice
+
+      redirect_to invoices_path, alert: "Invoice not found."
+    end
+
+    def current_billing_customer_ref
+      account = current_billing_account
+      return nil unless account
+
+      account.billing_subscriptions.pick(:customer_ref) ||
+        account.billing_invoices.pick(:customer_ref) ||
+        account.billing_lifetime_passes.pick(:customer_ref)
+    end
+
+    def current_billing_account
+      return @current_billing_account if defined?(@current_billing_account)
+
+      @current_billing_account =
+        if defined?(Accounts::Current) && Accounts::Current.respond_to?(:account)
+          Accounts::Current.account
+        end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/controllers/plans_controller.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Billing
+  class PlansController < ApplicationController
+    def index
+      @recurring_plans = Billing::Plan.active.recurring.order(:amount_cents)
+      # LTD plans grouped separately on the pricing page so the host
+      # can render them under a "buy once, own forever" section.
+      # `lifetime_inventory_remaining` is nil for unlimited; integer
+      # for capped (used by the view to show "X seats left").
+      @lifetime_plans = Billing::Plan.active.lifetime.order(:amount_cents)
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/controllers/portal_controller.rb.tt

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Billing
+  class PortalController < ApplicationController
+    # POST /billing/portal
+    def create
+      account = current_billing_account
+      raise Billing::Error, "current_billing_account is not set" unless account
+
+      result = Billing::Portal::CreateSessionService.call(
+        customer_ref: account_customer_ref(account),
+        return_url:   billing.plans_url
+      )
+
+      if result.ok?
+        redirect_to result.url, allow_other_host: true, status: :see_other
+      else
+        redirect_to billing.plans_path, alert: result.error
+      end
+    end
+
+    private
+
+    # Reads the Stripe customer id off any existing billing row for
+    # this Account. Avoids a synchronous Stripe API call — the
+    # portal is only meaningful when the Account already has a
+    # subscription anyway.
+    def account_customer_ref(account)
+      account.billing_subscriptions.pick(:customer_ref) ||
+        account.billing_invoices.pick(:customer_ref) ||
+        account.billing_lifetime_passes.pick(:customer_ref) ||
+        raise(Billing::Error, "Account has no billing customer_ref yet — create a subscription or LTD first.")
+    end
+
+    # See CheckoutController#current_billing_account — same default.
+    def current_billing_account
+      return @current_billing_account if defined?(@current_billing_account)
+
+      @current_billing_account =
+        if defined?(Accounts::Current) && Accounts::Current.respond_to?(:account)
+          Accounts::Current.account
+        end
+    end
+  end
+end