seams 0.1.0

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Billing
+  module Subscriptions
+    # Un-cancels a subscription that's pending cancellation at period
+    # end. No-op for subscriptions already past their period end —
+    # those need a fresh checkout flow, not a reactivate. Verified
+    # against
+    # https://docs.stripe.com/billing/subscriptions/cancel#reactivate-canceled-subscription.
+    class ReactivateService < Billing::StripeService
+      def initialize(subscription_ref:)
+        @subscription_ref = subscription_ref
+      end
+
+      def call_stripe(client)
+        client.update_subscription(@subscription_ref, cancel_at_period_end: false)
+      end
+
+      def on_success(stripe_response)
+        ServiceResult.ok(value: {
+                           id:                  stripe_response[:id],
+                           status:              stripe_response[:status],
+                           cancel_at_period_end: stripe_response[:cancel_at_period_end]
+                         })
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    # Maps a Stripe event type → the handler class that processes it.
+    # Hosts extend the map by reopening this module in an initializer:
+    #
+    #   Billing::Webhooks::EventRouter.register(
+    #     "customer.tax_id.created",
+    #     "MyHost::TaxIdCreatedHandler"
+    #   )
+    #
+    # Returns nil for unmapped events so the controller can no-op
+    # without raising — Stripe sends events the host hasn't subscribed
+    # to and that's normal.
+    module EventRouter
+      HANDLERS = {
+        "customer.subscription.created"          => "Billing::Webhooks::Handlers::SubscriptionCreatedHandler",
+        "customer.subscription.updated"          => "Billing::Webhooks::Handlers::SubscriptionUpdatedHandler",
+        "customer.subscription.deleted"          => "Billing::Webhooks::Handlers::SubscriptionDeletedHandler",
+        "customer.subscription.trial_will_end"   => "Billing::Webhooks::Handlers::SubscriptionTrialWillEndHandler",
+        "invoice.created"                        => "Billing::Webhooks::Handlers::InvoiceCreatedHandler",
+        "invoice.paid"                           => "Billing::Webhooks::Handlers::InvoicePaidHandler",
+        "invoice.payment_failed"                 => "Billing::Webhooks::Handlers::InvoicePaymentFailedHandler",
+        "invoice.finalized"                      => "Billing::Webhooks::Handlers::InvoiceFinalizedHandler",
+        "invoice.voided"                         => "Billing::Webhooks::Handlers::InvoiceVoidedHandler",
+        "payment_intent.succeeded"               => "Billing::Webhooks::Handlers::PaymentSucceededHandler",
+        "payment_intent.payment_failed"          => "Billing::Webhooks::Handlers::PaymentFailedHandler",
+        "charge.refunded"                        => "Billing::Webhooks::Handlers::ChargeRefundedHandler",
+        "checkout.session.completed"             => "Billing::Webhooks::Handlers::CheckoutSessionCompletedHandler",
+        "checkout.session.async_payment_succeeded" => "Billing::Webhooks::Handlers::CheckoutSessionCompletedHandler",
+        # Follow-up generators that ship handlers for additional Stripe events (customer.tax_id.created, payment_method.attached) splice their `"event.type" => "Billing::Webhooks::Handlers::ClassName",` entry here. Trailing commas on every entry keep the hash valid both before and after a splice.
+        # seams:insertion-point billing.event_router.handlers
+      }
+
+      module_function
+
+      def register(stripe_event_type, handler_class_name)
+        HANDLERS[stripe_event_type] = handler_class_name
+      end
+
+      def handler_for(stripe_event_type)
+        klass_name = HANDLERS[stripe_event_type]
+        return nil unless klass_name
+
+        klass_name.constantize
+      end
+
+      def supported_event_types
+        HANDLERS.keys
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    # Base class for every webhook handler. Subclasses implement
+    # #call which receives a normalised event hash:
+    #
+    #   { id:, type:, livemode:, object:, raw: }
+    #
+    # And typically:
+    #   1. Upserts the local Billing::Subscription / Billing::Invoice
+    #      so downstream subscribers can read from the DB rather than
+    #      reparsing the raw payload.
+    #   2. Calls #publish with the canonical seams event name + the
+    #      shared payload shape.
+    #
+    # Subclasses MUST set SEAMS_EVENT to the canonical event name
+    # (e.g. "subscription.created.billing"). EventRouter routes by the
+    # Stripe event type; SEAMS_EVENT is what we re-publish.
+    class Handler
+      SEAMS_EVENT = nil # override in subclasses
+
+      def initialize(event:, gateway:)
+        @event   = event
+        @gateway = gateway
+      end
+
+      def call
+        raise NotImplementedError, "#{self.class} must implement #call"
+      end
+
+      protected
+
+      attr_reader :event, :gateway
+
+      def object_hash
+        @object_hash ||= begin
+          obj = event[:object]
+          obj.respond_to?(:to_hash) ? obj.to_hash : obj
+        end
+      end
+
+      def object_id
+        @object_id ||= begin
+          obj = event[:object]
+          return nil if obj.nil?
+
+          obj.respond_to?(:id) ? obj.id : (obj.is_a?(Hash) && (obj[:id] || obj["id"]))
+        end
+      end
+
+      def customer_ref
+        @customer_ref ||= object_hash.is_a?(Hash) && (object_hash[:customer] || object_hash["customer"])
+      end
+
+      # Resolves the Accounts::Account id for this webhook event by
+      # cross-referencing the gateway's customer id (`cus_*`) against
+      # the local Billing::Subscription mirror. Returns nil if no
+      # matching local row exists yet (e.g. the very first
+      # `customer.subscription.created` event lands before the local
+      # row is upserted; the leaf handler does the upsert and reads
+      # account_id off the just-saved row in that case).
+      def account_id
+        return @account_id if defined?(@account_id)
+
+        @account_id =
+          Billing::Subscription.where(customer_ref: customer_ref).pick(:account_id) if customer_ref
+      end
+
+      def publish(seams_event = self.class::SEAMS_EVENT, ref: object_id)
+        Seams::Events::Publisher.publish(
+          seams_event,
+          gateway:      gateway,
+          livemode:     event[:livemode],
+          account_id:   account_id,
+          customer_ref: customer_ref,
+          ref:          ref,
+          object_id:    object_id,
+          object:       object_hash
+        )
+      end
+
+      def warn_upsert_failure(error)
+        Seams::Observability.adapter.warn(
+          "billing.webhook.upsert_failed",
+          engine: "billing",
+          event:  self.class::SEAMS_EVENT,
+          error:  error.message
+        )
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/charge_refunded_handler.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      # charge.refunded — full or partial refund applied. Subscribers
+      # typically use this to revoke access, send a refund-receipt
+      # email, or reverse internal credit grants.
+      class ChargeRefundedHandler < Billing::Webhooks::Handler
+        SEAMS_EVENT = "charge.refunded.billing"
+
+        def call
+          publish
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/checkout_session_completed_handler.rb.tt

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      # Two distinct paths through one Stripe event:
+      #
+      #   - mode: "subscription"  → the recurring subscription is now
+      #     paid + active. The customer.subscription.created event
+      #     usually arrives first; this is the confirmation that the
+      #     checkout flow itself completed.
+      #   - mode: "payment" with metadata.access_type == "lifetime" →
+      #     a Lifetime Deal was purchased. Hands off to the LTD
+      #     service which creates the LifetimePass row + emits
+      #     lifetime.purchased.billing.
+      #
+      # Stripe also fires checkout.session.async_payment_succeeded for
+      # delayed methods (ACH). The router maps both to this handler.
+      # Verified against
+      # https://docs.stripe.com/payments/checkout/fulfill-orders.
+      class CheckoutSessionCompletedHandler < Billing::Webhooks::Handler
+        SEAMS_EVENT = "checkout.session_completed.billing"
+
+        def call
+          if lifetime?
+            handle_lifetime
+          else
+            publish
+          end
+        end
+
+        private
+
+        def lifetime?
+          mode_value == "payment" && access_type == "lifetime"
+        end
+
+        def handle_lifetime
+          Billing::Lifetime::CreatePassFromCheckoutService.call(
+            session:  event[:object],
+            livemode: event[:livemode]
+          )
+        end
+
+        def mode_value
+          object_hash.is_a?(Hash) && (object_hash[:mode] || object_hash["mode"])
+        end
+
+        def access_type
+          metadata = object_hash.is_a?(Hash) && (object_hash[:metadata] || object_hash["metadata"])
+          return nil unless metadata.is_a?(Hash)
+
+          metadata[:access_type] || metadata["access_type"]
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/invoice_created_handler.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      # invoice.created fires when Stripe drafts a new invoice (e.g.
+      # at the start of a billing period). Status is "draft" until
+      # finalised. Hosts rarely need to act on this — included for
+      # full audit coverage.
+      class InvoiceCreatedHandler < InvoiceHandlerBase
+        SEAMS_EVENT    = "invoice.created.billing"
+        INVOICE_STATUS = "draft"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/invoice_finalized_handler.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      # invoice.finalized — Stripe finalised the draft invoice and is
+      # about to attempt collection. Status flips draft → open.
+      class InvoiceFinalizedHandler < InvoiceHandlerBase
+        SEAMS_EVENT    = "invoice.finalized.billing"
+        INVOICE_STATUS = "open"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/invoice_handler_base.rb.tt

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      # Shared base for the five invoice.* handlers. Owns the upsert
+      # of Billing::Invoice. Subclasses set SEAMS_EVENT + INVOICE_STATUS.
+      #
+      # Account resolution mirrors SubscriptionHandlerBase: the
+      # invoice belongs to the same Account as the subscription it
+      # references; we resolve account_id by walking
+      # subscription_ref → Billing::Subscription#account_id, falling
+      # back to a sibling Billing::Invoice on the same customer_ref
+      # for one-off invoices that have no subscription.
+      class InvoiceHandlerBase < Billing::Webhooks::Handler
+        DEFAULT_STATUS = "open"
+
+        def call
+          upsert_invoice
+          publish
+        end
+
+        protected
+
+        def upsert_invoice
+          return unless object_id && customer_ref && object_hash.is_a?(Hash)
+
+          invoice = Billing::Invoice.find_or_initialize_by(gateway_ref: object_id)
+          resolved_account_id = invoice.account_id || resolve_account_id_for_invoice
+          unless resolved_account_id
+            warn_upsert_failure(
+              StandardError.new("could not resolve account_id for customer_ref=#{customer_ref}")
+            )
+            return
+          end
+
+          invoice.account_id       = resolved_account_id
+          invoice.customer_ref     = customer_ref
+          invoice.subscription_ref = object_hash[:subscription] || object_hash["subscription"]
+          invoice.amount_cents     = object_hash[:amount_paid] || object_hash["amount_paid"] ||
+                                     object_hash[:amount_due]  || object_hash["amount_due"]  || 0
+          invoice.currency         = (object_hash[:currency] || object_hash["currency"] || "usd").to_s.upcase
+          invoice.status           = invoice_status
+          invoice.paid_at          = paid_at_for_status
+          invoice.save!
+        rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique => e
+          warn_upsert_failure(e)
+        end
+
+        # First, try the subscription_ref → Subscription mirror.
+        # Fall back to any sibling Invoice on the same customer.
+        # Final fallback is a Subscription row on the same
+        # customer_ref (covers the case of a one-off invoice that
+        # arrives before any sibling Invoice).
+        def resolve_account_id_for_invoice
+          subscription_ref = object_hash[:subscription] || object_hash["subscription"]
+          if subscription_ref
+            id = Billing::Subscription.where(gateway_ref: subscription_ref).pick(:account_id)
+            return id if id
+          end
+
+          Billing::Invoice.where(customer_ref: customer_ref)
+                          .where.not(account_id: nil)
+                          .pick(:account_id) ||
+            Billing::Subscription.where(customer_ref: customer_ref)
+                                 .where.not(account_id: nil)
+                                 .pick(:account_id)
+        end
+
+        def invoice_status
+          self.class::INVOICE_STATUS || DEFAULT_STATUS
+        end
+
+        def paid_at_for_status
+          invoice_status == "paid" ? Time.current : nil
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/invoice_paid_handler.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      class InvoicePaidHandler < InvoiceHandlerBase
+        SEAMS_EVENT    = "invoice.paid.billing"
+        INVOICE_STATUS = "paid"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/invoice_payment_failed_handler.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      class InvoicePaymentFailedHandler < InvoiceHandlerBase
+        SEAMS_EVENT    = "invoice.failed.billing"
+        INVOICE_STATUS = "open"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/invoice_voided_handler.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      class InvoiceVoidedHandler < InvoiceHandlerBase
+        SEAMS_EVENT    = "invoice.voided.billing"
+        INVOICE_STATUS = "void"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/payment_failed_handler.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      class PaymentFailedHandler < Billing::Webhooks::Handler
+        SEAMS_EVENT = "payment.failed.billing"
+
+        def call
+          publish
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/payment_succeeded_handler.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      # payment_intent.succeeded — a one-off payment cleared. No local
+      # row to upsert (PaymentIntents are not modelled locally — see
+      # Phase 3A scope review). Just publishes the canonical event so
+      # subscribers can react (notifications, audit log, etc).
+      class PaymentSucceededHandler < Billing::Webhooks::Handler
+        SEAMS_EVENT = "payment.succeeded.billing"
+
+        def call
+          publish
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/subscription_created_handler.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      class SubscriptionCreatedHandler < SubscriptionHandlerBase
+        SEAMS_EVENT = "subscription.created.billing"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/subscription_deleted_handler.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      # Stripe sends customer.subscription.deleted when the
+      # subscription has actually ended (period elapsed after a
+      # period-end cancel, or immediate cancellation). The local
+      # status flips to "canceled".
+      class SubscriptionDeletedHandler < SubscriptionHandlerBase
+        SEAMS_EVENT = "subscription.canceled.billing"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/subscription_handler_base.rb.tt

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      # Base for the four customer.subscription.* handlers. Owns the
+      # upsert of Billing::Subscription so each leaf class just sets
+      # SEAMS_EVENT and inherits.
+      #
+      # Account resolution: for subscriptions created via the host's
+      # `Account#start_subscription!` flow, StartSubscriptionJob has
+      # already inserted a Billing::Subscription row with `account_id`
+      # set; the upsert here finds it via `gateway_ref` and preserves
+      # the existing `account_id`. For subscriptions created directly
+      # in the Stripe Dashboard (no local row pre-exists), the upsert
+      # falls back to looking up `account_id` from any sibling row
+      # under the same `customer_ref`. If neither path resolves,
+      # the upsert is skipped + a warning is logged — the host
+      # supports this case by reconciling the orphaned subscription
+      # via a sync task (see README "Stripe-initiated subscriptions").
+      class SubscriptionHandlerBase < Billing::Webhooks::Handler
+        def call
+          upsert_subscription
+          publish
+        end
+
+        protected
+
+        def upsert_subscription
+          return unless object_id && customer_ref && object_hash.is_a?(Hash)
+
+          subscription = Billing::Subscription.find_or_initialize_by(gateway_ref: object_id)
+          resolved_account_id = subscription.account_id || resolve_account_id_from_sibling
+          unless resolved_account_id
+            warn_upsert_failure(
+              StandardError.new("could not resolve account_id for customer_ref=#{customer_ref}")
+            )
+            return
+          end
+
+          subscription.account_id         = resolved_account_id
+          subscription.customer_ref       = customer_ref
+          subscription.plan_ref           = plan_ref_from_object_hash
+          subscription.status             = object_hash[:status] || object_hash["status"] || subscription.status || "incomplete"
+          subscription.current_period_end = current_period_end_at
+          subscription.save!
+        rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique => e
+          warn_upsert_failure(e)
+        end
+
+        # Look up account_id from any other Billing::Subscription row
+        # under the same Stripe customer. A customer almost always
+        # belongs to one Account post-Wave-9 (Account == Stripe
+        # customer), so the first sibling row's account_id is the
+        # correct answer.
+        def resolve_account_id_from_sibling
+          Billing::Subscription.where(customer_ref: customer_ref)
+                               .where.not(account_id: nil)
+                               .pick(:account_id)
+        end
+
+        def plan_ref_from_object_hash
+          first = first_subscription_item
+          return nil unless first
+
+          price = first[:price] || first["price"]
+          price.is_a?(Hash) ? (price[:id] || price["id"]) : nil
+        end
+
+        # Stripe moved current_period_end onto each subscription item
+        # in 2024; older API versions still set it at the root. Try
+        # root first, fall back to items.data[0].
+        # https://docs.stripe.com/api/subscriptions/object
+        def current_period_end_at
+          unix = object_hash[:current_period_end] ||
+                 object_hash["current_period_end"]
+          unix ||= (item = first_subscription_item) &&
+                   (item[:current_period_end] || item["current_period_end"])
+          unix && Time.at(unix)
+        end
+
+        def first_subscription_item
+          items = object_hash[:items] || object_hash["items"]
+          return nil unless items.is_a?(Hash)
+
+          first = (items[:data] || items["data"] || []).first
+          first if first.is_a?(Hash)
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/subscription_trial_will_end_handler.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      # Fires ~3 days before a trialing subscription transitions to
+      # active. Hosts subscribe to send "your trial is ending" email.
+      # Verified against
+      # https://docs.stripe.com/api/events/types#event_types-customer.subscription.trial_will_end
+      class SubscriptionTrialWillEndHandler < SubscriptionHandlerBase
+        SEAMS_EVENT = "subscription.trial_will_end.billing"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/services/webhooks/handlers/subscription_updated_handler.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Billing
+  module Webhooks
+    module Handlers
+      class SubscriptionUpdatedHandler < SubscriptionHandlerBase
+        SEAMS_EVENT = "subscription.updated.billing"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/app/views/admin/lifetime_passes/index.html.erb.tt

@@ -0,0 +1,36 @@
+<h1>Lifetime passes</h1>
+
+<p><%%= link_to "Grant a new pass", billing.new_admin_lifetime_pass_path %></p>
+
+<table>
+  <thead>
+    <tr>
+      <th>Account</th>
+      <th>Customer</th>
+      <th>Plan</th>
+      <th>Type</th>
+      <th>Granted at</th>
+      <th>Status</th>
+      <th></th>
+    </tr>
+  </thead>
+  <tbody>
+    <%% @passes.each do |pass| %>
+      <tr>
+        <td><%%= pass.account_id %></td>
+        <td><%%= pass.customer_ref %></td>
+        <td><%%= pass.plan_ref %></td>
+        <td><%%= pass.paid? ? "Paid" : "Granted" %></td>
+        <td><%%= pass.granted_at.utc.iso8601 %></td>
+        <td><%%= pass.revoked? ? "Revoked at #{pass.revoked_at.utc.iso8601}" : "Active" %></td>
+        <td>
+          <%% unless pass.revoked? %>
+            <%%= button_to "Revoke", billing.admin_lifetime_pass_path(pass),
+                          method: :delete,
+                          form: { onsubmit: "return confirm('Revoke this lifetime pass?')" } %>
+          <%% end %>
+        </td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>

data/lib/generators/seams/billing/templates/app/views/admin/lifetime_passes/new.html.erb.tt

@@ -0,0 +1,37 @@
+<h1>Grant a lifetime pass</h1>
+
+<%%= form_with url: billing.admin_lifetime_passes_path, scope: nil, local: true do %>
+  <p>
+    <label>Account id (Accounts::Account#id, UUID):
+      <input type="text" name="account_id" required>
+    </label>
+  </p>
+  <p>
+    <label>Customer ref (Stripe customer id):
+      <input type="text" name="customer_ref" required>
+    </label>
+  </p>
+  <p>
+    <label>Plan:
+      <select name="plan_ref" required>
+        <option value=""></option>
+        <%% @plan_options.each do |plan| %>
+          <option value="<%%= plan.gateway_ref %>">
+            <%%= plan.name %> · <%%= plan.gateway_ref %>
+            <%% if (rem = plan.lifetime_inventory_remaining) %>
+              · <%%= rem %> remaining
+            <%% end %>
+          </option>
+        <%% end %>
+      </select>
+    </label>
+  </p>
+  <p>
+    <label>Notes:
+      <textarea name="notes" rows="3"></textarea>
+    </label>
+  </p>
+  <button type="submit">Grant lifetime pass</button>
+<%% end %>
+
+<p><%%= link_to "Back", billing.admin_lifetime_passes_path %></p>