seams 0.1.0

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Billing
+  # Self-service subscription management for the current Account.
+  # Backed by the Phase 3 (2/4) service objects — every action is a
+  # thin wrapper that calls a service and renders / redirects on the
+  # ServiceResult.
+  #
+  # Routes (from config/routes.rb):
+  #
+  #   GET    /billing/subscriptions          → index   (list)
+  #   GET    /billing/subscriptions/:id      → show
+  #   DELETE /billing/subscriptions/:id      → cancel  (period-end by default)
+  #   POST   /billing/subscriptions/:id/reactivate
+  #   POST   /billing/subscriptions/:id/change_plan
+  #
+  # The host's authentication concern decides who `current_user` is —
+  # this controller scopes by the current Account (the tenant), not
+  # the human. Subscriptions belong to Accounts::Account post-Wave-9.
+  class SubscriptionsController < ApplicationController
+    before_action :require_subscription, only: %i[show cancel reactivate change_plan]
+
+    def index
+      @subscriptions = scoped_subscriptions.order(created_at: :desc)
+    end
+
+    def show
+      # @subscription is set by require_subscription
+    end
+
+    # DELETE /billing/subscriptions/:id
+    # Default: cancel at period end (user keeps access through what
+    # they have already paid for). Pass ?immediate=1 to cancel now.
+    def cancel
+      result = Billing::Subscriptions::CancelService.call(
+        subscription_ref: @subscription.gateway_ref,
+        immediate:        params[:immediate].present?
+      )
+
+      respond_to_result(result, success: "Subscription cancelled.")
+    end
+
+    # POST /billing/subscriptions/:id/reactivate
+    # Un-cancel a subscription that is pending end-of-period cancellation.
+    def reactivate
+      result = Billing::Subscriptions::ReactivateService.call(
+        subscription_ref: @subscription.gateway_ref
+      )
+
+      respond_to_result(result, success: "Subscription reactivated.")
+    end
+
+    # POST /billing/subscriptions/:id/change_plan
+    #   params[:price_ref]          — required, the new Stripe price id
+    #   params[:proration_behavior] — optional, "create_prorations" (default) | "none"
+    def change_plan
+      new_price = params[:price_ref].to_s
+      if new_price.empty?
+        redirect_to subscription_path(@subscription),
+                    alert: "Choose a plan before submitting."
+        return
+      end
+
+      result = Billing::Subscriptions::ChangePlanService.call(
+        subscription_ref:    @subscription.gateway_ref,
+        new_price_ref:       new_price,
+        proration_behavior:  params[:proration_behavior].presence || "create_prorations"
+      )
+
+      respond_to_result(result, success: "Plan changed.")
+    end
+
+    private
+
+    # Override in the host (or here) to scope by the current Account's
+    # billing rows. The default scopes by `current_billing_customer_ref`
+    # — the Stripe `cus_*` id resolved from the current Account — which
+    # is correct whenever the controller has an Account in scope.
+    def scoped_subscriptions
+      Billing::Subscription.where(customer_ref: current_billing_customer_ref)
+    end
+
+    def require_subscription
+      @subscription = scoped_subscriptions.find_by(id: params[:id])
+      return if @subscription
+
+      redirect_to subscriptions_path, alert: "Subscription not found."
+    end
+
+    # Reads the Stripe customer id off the current Account. Hosts on
+    # a pre-Wave-9 user-keyed flow can override this method to point
+    # at their User's own `billing_customer_ref` accessor.
+    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
+
+    def respond_to_result(result, success:)
+      if result.ok?
+        redirect_to subscriptions_path, notice: success
+      else
+        redirect_to subscription_path(@subscription), alert: result.error
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Billing
+  # Receives webhook callbacks from the configured payment gateway.
+  # The gateway adapter does the signature verification — we just
+  # record the event for idempotency and route it to the handler
+  # that knows how to process that event type.
+  #
+  # Trust boundary: the request body is treated as untrusted until
+  # the gateway adapter's `verify_webhook` returns. CSRF is
+  # intentionally skipped (webhooks come from Stripe, not a browser
+  # session) — DO NOT add authentication here; the signature IS the
+  # authentication.
+  #
+  # Idempotent: every accepted event is recorded by gateway+event_id;
+  # retries hit the unique index and short-circuit before any handler
+  # fires. Stripe explicitly requires this — retries can span days
+  # (https://docs.stripe.com/webhooks#handle-duplicate-events).
+  #
+  # Sync vs async: by default the handler runs in the request thread.
+  # Set Billing.configuration.process_webhooks_async = true to enqueue
+  # Billing::Webhooks::ProcessEventJob instead — Stripe recommends
+  # responding in <100ms (https://docs.stripe.com/webhooks#acknowledge-events-immediately).
+  class WebhooksController < ApplicationController
+    skip_before_action :verify_authenticity_token
+
+    # POST /billing/webhooks/stripe
+    def stripe
+      payload   = request.body.read
+      signature = request.headers["Stripe-Signature"]
+
+      event = Billing.gateway.verify_webhook(
+        payload:   payload,
+        signature: signature,
+        secret:    Billing.configuration.webhook_secret
+      )
+
+      record_and_dispatch("stripe", event)
+      head :ok
+    rescue Billing::WebhookError => e
+      Seams::Observability.adapter.warn(
+        "billing.webhook.invalid", engine: "billing", error: e.message
+      )
+      head :bad_request
+    end
+
+    private
+
+    # Insert WebhookEvent FIRST inside a transaction that ALSO runs
+    # the handler. If the handler raises, the WebhookEvent row rolls
+    # back — Stripe retries, we get another chance to publish.
+    # Otherwise a transient handler bug would permanently drop one
+    # event behind the unique-index guard. Async path skips the
+    # transaction (the job has its own retry semantics).
+    def record_and_dispatch(gateway, event)
+      Billing::WebhookEvent.transaction do
+        Billing::WebhookEvent.create!(
+          gateway:          gateway,
+          gateway_event_id: event[:id] || object_id_for(event[:object]),
+          event_type:       event[:type],
+          livemode:         event[:livemode]
+        )
+
+        dispatch(gateway: gateway, event: event)
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # Duplicate retry — Stripe will keep retrying; replying 200 stops
+      # the storm without re-publishing to subscribers.
+      Seams::Observability.adapter.info(
+        "billing.webhook.duplicate", engine: "billing",
+        gateway: gateway, event_type: event[:type]
+      )
+    end
+
+    def dispatch(gateway:, event:)
+      if Billing.configuration.process_webhooks_async
+        Billing::Webhooks::ProcessEventJob.perform_later(
+          gateway: gateway, event_data: event.deep_stringify_keys
+        )
+      else
+        run_handler(gateway: gateway, event: event)
+      end
+    end
+
+    def run_handler(gateway:, event:)
+      handler_class = Billing::Webhooks::EventRouter.handler_for(event[:type])
+      return unless handler_class
+
+      handler_class.new(event: event, gateway: gateway).call
+    end
+
+    def object_id_for(object)
+      return nil if object.nil?
+
+      object.respond_to?(:id) ? object.id : (object.is_a?(Hash) && (object[:id] || object["id"]))
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/helpers/currency_helper.rb.tt

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Billing
+  # Format minor-unit integer amounts (Stripe's native form — pence,
+  # cents, kuruş) into human-readable money strings. Stripe always
+  # quotes amounts as smallest-unit integers; the host's price tag
+  # never says "12.99" — it says "1299" for USD/GBP/EUR or "1299" for
+  # JPY (which has no minor unit).
+  #
+  #   format_money(1299, "GBP") # => "£12.99"
+  #   format_money(1299, "JPY") # => "¥1299"
+  #
+  # Hosts can override the symbol map by reopening this module in an
+  # initializer or monkey-patching SYMBOLS.
+  module CurrencyHelper
+    SYMBOLS = {
+      "USD" => "$",
+      "GBP" => "£",
+      "EUR" => "€",
+      "JPY" => "¥",
+      "CAD" => "$",
+      "AUD" => "$"
+    }.freeze
+
+    # Currencies with no minor unit (Stripe's "zero-decimal currencies").
+    # Source: https://docs.stripe.com/currencies#zero-decimal
+    ZERO_DECIMAL = %w[BIF CLP DJF GNF JPY KMF KRW MGA PYG RWF UGX VND VUV XAF XOF XPF].freeze
+
+    module_function
+
+    def format_money(amount_in_minor_units, currency_code)
+      code   = currency_code.to_s.upcase
+      symbol = SYMBOLS[code] || "#{code} "
+
+      if ZERO_DECIMAL.include?(code)
+        "#{symbol}#{amount_in_minor_units.to_i}"
+      else
+        major   = amount_in_minor_units.to_i / 100.0
+        decimal = format("%.2f", major)
+        "#{symbol}#{decimal}"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/jobs/application_job.rb.tt

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Billing
+  class ApplicationJob < ::ApplicationJob
+  end
+end

data/lib/generators/seams/billing/templates/app/jobs/cancel_subscription_job.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Billing
+  class CancelSubscriptionJob < ApplicationJob
+    queue_as :billing
+
+    def perform(subscription_ref:)
+      result = Billing.gateway.cancel_subscription(subscription_ref: subscription_ref)
+
+      sub = Billing::Subscription.find_by(gateway_ref: subscription_ref)
+      sub&.update!(status: result[:status])
+
+      if sub.nil?
+        # Local row missing — host's notification subscriber has no
+        # account_id / customer_ref to resolve the Account and will
+        # silently no-op. Log so the gap is visible (e.g. drift
+        # between Stripe + local DB after a partial migration).
+        Seams::Observability.adapter.warn(
+          "billing.cancel_subscription.local_row_missing",
+          engine: "billing", subscription_ref: subscription_ref
+        )
+      end
+
+      # Canonical event payload — must match what WebhooksController
+      # emits for the same event so subscribers can read one shape:
+      #   { gateway:, livemode:, account_id:, customer_ref:, ref:, object_id:, object: }
+      Seams::Events::Publisher.publish(
+        "subscription.canceled.billing",
+        gateway:      Billing.configuration.gateway_name,
+        livemode:     false,
+        account_id:   sub&.account_id,
+        customer_ref: sub&.customer_ref,
+        ref:          subscription_ref,
+        object_id:    subscription_ref,
+        object:       { id: subscription_ref, account_id: sub&.account_id, status: result[:status] }
+      )
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/jobs/start_subscription_job.rb.tt

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Billing
+  class StartSubscriptionJob < ApplicationJob
+    queue_as :billing
+
+    def perform(account_id:, customer_ref:, plan_ref:)
+      result = Billing.gateway.create_subscription(customer_ref: customer_ref, plan_ref: plan_ref)
+
+      Billing::Subscription.create!(
+        account_id:   account_id,
+        customer_ref: customer_ref,
+        plan_ref:     result[:plan_ref] || plan_ref,
+        gateway_ref:  result[:id],
+        status:       result[:status]
+      )
+
+      # Canonical event payload — same shape as WebhooksController emits:
+      #   { gateway:, livemode:, account_id:, customer_ref:, ref:, object_id:, object: }
+      Seams::Events::Publisher.publish(
+        "subscription.created.billing",
+        gateway:      Billing.configuration.gateway_name,
+        livemode:     false,
+        account_id:   account_id,
+        customer_ref: customer_ref,
+        ref:          result[:id],
+        object_id:    result[:id],
+        object:       { id: result[:id], account_id: account_id, plan: { id: plan_ref }, status: result[:status] }
+      )
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/jobs/webhooks/process_event_job.rb.tt

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    # Async wrapper around the synchronous handler dispatch. Hosts
+    # who want sub-100ms webhook responses (Stripe's recommendation —
+    # https://docs.stripe.com/webhooks#acknowledge-events-immediately)
+    # set Billing.configuration.process_webhooks_async = true and the
+    # WebhooksController enqueues this job instead of running the
+    # handler in the request thread.
+    #
+    # The event payload is serialised as a hash so the job survives
+    # Active Job's argument restrictions; the handler reconstructs
+    # what it needs from that hash.
+    class ProcessEventJob < Billing::ApplicationJob
+      queue_as :billing
+
+      def perform(gateway:, event_data:)
+        event   = symbolize(event_data)
+        handler = Billing::Webhooks::EventRouter.handler_for(event[:type])
+        return unless handler
+
+        handler.new(event: event, gateway: gateway).call
+      end
+
+      private
+
+      def symbolize(hash)
+        case hash
+        when Hash  then hash.transform_keys(&:to_sym).transform_values { |value| symbolize(value) }
+        when Array then hash.map { |element| symbolize(element) }
+        else            hash
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/models/application_record.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Billing
+  class ApplicationRecord < ::ApplicationRecord
+    self.abstract_class = true
+  end
+end

data/lib/generators/seams/billing/templates/app/models/invoice.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Billing
+  # Local mirror of a gateway invoice. Keyed on `account_id` (the
+  # Accounts::Account tenant) AND `customer_ref` (the gateway's
+  # `cus_*` id) so subscribers can address it either way. No
+  # `belongs_to :account` — cross-engine model access is forbidden;
+  # querying flows through `account.billing_invoices` (provided by
+  # Billing::Billable on the host's Account model).
+  class Invoice < ApplicationRecord
+    self.table_name = "billing_invoices"
+
+    STATUSES = %w[draft open paid void uncollectible].freeze
+
+    validates :gateway_ref,  presence: true, uniqueness: true
+    validates :account_id,   presence: true
+    validates :customer_ref, presence: true
+    validates :amount_cents, numericality: { greater_than_or_equal_to: 0 }
+    validates :currency,     presence: true
+    validates :status,       inclusion: { in: STATUSES }
+
+    # Convenience association — Stripe sends `subscription` as a
+    # gateway-side id (sub_*), not a local FK; resolve through the
+    # local subscription mirror by gateway_ref.
+    def subscription
+      return nil if subscription_ref.blank?
+
+      Billing::Subscription.find_by(gateway_ref: subscription_ref)
+    end
+
+    def paid?
+      status == "paid"
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/models/lifetime_pass.rb.tt

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Billing
+  # A LifetimePass is a one-time-paid OR privately-granted permanent
+  # access record. It deliberately lives in its own table rather than
+  # piggy-backing on Subscription with a `lifetime: true` flag — the
+  # semantics diverge enough (no current_period_end, no renewal
+  # webhook, no proration) that mixing them invites bugs.
+  #
+  # Belongs to an Accounts::Account (the tenant the entitlement
+  # applies to). The "granted_by" / "revoked_by" columns reference
+  # an Auth::Identity (the human who pressed the button) — Identity
+  # rather than Account because they track human action, not
+  # tenant-level data.
+  #
+  # Two creation paths:
+  #   1. Public — host's pricing page → Stripe Checkout (mode: payment)
+  #      → `checkout.session.completed` webhook → CreatePassFromCheckoutService.
+  #      `gateway_ref` is the Stripe Checkout Session id; `granted_by_identity_id`
+  #      is nil (paid, not granted).
+  #   2. Private grant — admin form → GrantPassService.
+  #      `gateway_ref` is nil (no Stripe charge); `granted_by_identity_id`
+  #      is the admin Identity who issued it.
+  #
+  # Active passes can be revoked via RevokePassService (refunded,
+  # ToS violation, etc.) — sets `revoked_at` rather than deleting so
+  # the audit trail survives.
+  class LifetimePass < ApplicationRecord
+    self.table_name = "billing_lifetime_passes"
+
+    belongs_to :plan, class_name: "Billing::Plan",
+                      foreign_key: :plan_ref, primary_key: :gateway_ref,
+                      optional: true
+
+    validates :account_id, :customer_ref, :plan_ref, :granted_at, presence: true
+    validates :account_id, uniqueness: { scope: :plan_ref,
+                                         message: "already has a lifetime pass for this plan" }
+
+    scope :active,  -> { where(revoked_at: nil) }
+    scope :revoked, -> { where.not(revoked_at: nil) }
+
+    # True for paid passes (Stripe Checkout completed), false for
+    # privately-granted ones (admin form, no charge).
+    def paid?
+      gateway_ref.present?
+    end
+
+    def granted?
+      granted_by_identity_id.present?
+    end
+
+    def revoked?
+      revoked_at.present?
+    end
+
+    def active?
+      !revoked?
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/models/plan.rb.tt

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Billing
+  # A subscription plan. Mirror of a Stripe Price (or whatever your
+  # gateway calls a recurring billable thing). Hosts seed Plans
+  # locally so the pricing page can render without a Stripe round-trip.
+  class Plan < ApplicationRecord
+    # Raised when a lifetime plan with a finite `max_lifetime_units`
+    # capacity has no remaining inventory at the moment of purchase.
+    # `Billing::Lifetime::CreateLifetimeSessionService` rescues this
+    # and converts it into a ServiceResult-style failure so callers
+    # see a friendly "sold out" message rather than an exception
+    # bubbling up from inside a transaction.
+    class SoldOut < StandardError; end
+
+    self.table_name = "billing_plans"
+
+    # `lifetime` is the LTD interval — a one-time payment with permanent
+    # access. Stripe Checkout uses `mode: "payment"` for these instead
+    # of `mode: "subscription"`. See LifetimePass + the LTD section in
+    # the README for the trade-off (no recurring revenue, indefinite
+    # support burden).
+    INTERVALS = %w[day week month year lifetime].freeze
+
+    has_many :lifetime_passes, class_name: "Billing::LifetimePass",
+                               foreign_key: :plan_ref, primary_key: :gateway_ref,
+                               dependent: :nullify
+
+    validates :gateway_ref, presence: true, uniqueness: true
+    validates :name, presence: true
+    validates :amount_cents, numericality: { greater_than_or_equal_to: 0 }
+    validates :currency, presence: true
+    validates :interval, inclusion: { in: INTERVALS }
+
+    scope :active,    -> { where(active: true) }
+    scope :recurring, -> { where.not(interval: "lifetime") }
+    scope :lifetime,  -> { where(interval: "lifetime") }
+
+    def free?
+      amount_cents.zero?
+    end
+
+    def has_trial?
+      trial_period_days.to_i.positive?
+    end
+
+    def lifetime?
+      interval == "lifetime"
+    end
+
+    # nil = unlimited; otherwise the count of LTD slots still available
+    # (max_lifetime_units minus already-issued LifetimePass count).
+    def lifetime_inventory_remaining
+      return nil if max_lifetime_units.nil? || !lifetime?
+
+      [max_lifetime_units - lifetime_passes.count, 0].max
+    end
+
+    def lifetime_sold_out?
+      lifetime? && lifetime_inventory_remaining&.zero?
+    end
+
+    # Lock-and-check guard that the lifetime inventory cap has not
+    # already been hit. Must be called from inside an open
+    # `transaction` block so the `SELECT ... FOR UPDATE` row-lock is
+    # held until commit — that's what makes the check race-free across
+    # concurrent buyers.
+    #
+    # No-op for plans without a `max_lifetime_units` cap (nil = unlimited)
+    # and for non-lifetime plans (cap is meaningless on recurring plans).
+    #
+    # Trade-off: holding a row lock across the Stripe API call (the
+    # caller does this so the lock spans the Checkout-session creation)
+    # means concurrent buyers serialise. For viral promos this can slow
+    # checkout under load. The alternative — letting the check race —
+    # oversells the plan, which costs refunds + support time + brand
+    # damage. For LTDs (capped, low-volume by design) the lock is the
+    # right trade. A more sophisticated optimistic alternative
+    # (counter column + `UPDATE ... WHERE remaining > 0 RETURNING`) is
+    # documented in the README but is out of scope for the generator.
+    #
+    # Raises `Billing::Plan::SoldOut` when the cap is exhausted.
+    def enforce_lifetime_inventory_or_raise!
+      return unless lifetime?
+      return if max_lifetime_units.nil?
+
+      lock!
+      return unless lifetime_sold_out?
+
+      raise SoldOut,
+            "Plan #{gateway_ref.inspect} is sold out " \
+            "(cap: #{max_lifetime_units})"
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/models/subscription.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Billing
+  # Subscription record mirrored from the gateway. Keyed locally on
+  # `account_id` (UUID, the Accounts::Account tenant id) and on
+  # `customer_ref` (the gateway's `cus_*` id). Both are present on
+  # every row so the same data can be addressed via either side.
+  #
+  # No `belongs_to :account` declaration: cross-engine model access
+  # is forbidden by Seams::Cops::NoCrossEngineModelAccess. Hosts that
+  # want a typed handle can call `.account` on their Account model
+  # via the `Billing::Billable` concern (which queries the inverse
+  # association `account.billing_subscriptions`).
+  class Subscription < ApplicationRecord
+    self.table_name = "billing_subscriptions"
+
+    STATUSES = %w[trialing active past_due canceled unpaid incomplete incomplete_expired paused].freeze
+
+    validates :gateway_ref,  presence: true, uniqueness: true
+    validates :account_id,   presence: true
+    validates :customer_ref, presence: true
+    validates :plan_ref,     presence: true
+    validates :status,       inclusion: { in: STATUSES }
+
+    scope :active_or_trialing, -> { where(status: %w[active trialing]) }
+
+    def active?
+      %w[active trialing].include?(status)
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/models/webhook_event.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Billing
+  # Audit log of every accepted webhook event. Used to dedupe retries
+  # from the gateway (Stripe in particular retries until the endpoint
+  # responds 2xx).
+  class WebhookEvent < ApplicationRecord
+    self.table_name = "billing_webhook_events"
+
+    validates :gateway, :gateway_event_id, :event_type, presence: true
+    validates :gateway_event_id, uniqueness: { scope: :gateway }
+  end
+end

data/lib/generators/seams/billing/templates/app/services/checkout_session_service.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Billing
+  module Checkout
+    # Creates a hosted-checkout session for a given customer + plan.
+    # Returns a Result with ok?, url, error.
+    module CreateSessionService
+      Result = Struct.new(:ok?, :url, :error, keyword_init: true)
+
+      module_function
+
+      def call(customer_ref:, plan_ref:, success_url:, cancel_url:)
+        session = Billing.gateway.create_checkout_session(
+          customer_ref: customer_ref,
+          plan_ref:     plan_ref,
+          success_url:  success_url,
+          cancel_url:   cancel_url
+        )
+        Result.new(ok?: true, url: session[:url])
+      rescue Billing::GatewayError => e
+        Result.new(ok?: false, error: e.message)
+      end
+    end
+  end
+end