seams 0.1.0 → 0.2.0

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/invoice_policy.rb.tt

@@ -16,6 +16,12 @@ module Admin
           scope.where(account_id: account_id)
         end
       end
+
+      private
+
+      def permission_ability
+        "invoice.manage.billing"
+      end
     end
   end
 end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/lifetime_pass_policy.rb.tt

@@ -16,6 +16,12 @@ module Admin
           scope.where(account_id: account_id)
         end
       end
+
+      private
+
+      def permission_ability
+        "lifetime.manage.billing"
+      end
     end
   end
 end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/notification_policy.rb.tt

@@ -20,6 +20,12 @@ module Admin
           scope.where(account_id: account_id)
         end
       end
+
+      private
+
+      def permission_ability
+        "notification.manage.notifications"
+      end
     end
   end
 end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/notification_preference_policy.rb.tt

@@ -18,6 +18,12 @@ module Admin
           scope.where(account_id: account_id)
         end
       end
+
+      private
+
+      def permission_ability
+        "preference.manage.notifications"
+      end
     end
   end
 end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/plan_policy.rb.tt

@@ -36,6 +36,13 @@ module Admin
 
       private
 
+      # Read actions (index/show) resolve through the global plan
+      # catalogue ability; writes short-circuit on the staff? overrides
+      # above (tenant admins must not mutate the shared catalogue).
+      def permission_ability
+        "plan.manage.billing"
+      end
+
       # Plans are global; per-record tenant guard always passes for
       # the read actions, and the write actions short-circuit on the
       # staff? predicates above.

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/subscription_policy.rb.tt

@@ -17,6 +17,12 @@ module Admin
           scope.where(account_id: account_id)
         end
       end
+
+      private
+
+      def permission_ability
+        "subscription.manage.billing"
+      end
     end
   end
 end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/team_policy.rb.tt

@@ -23,6 +23,12 @@ module Admin
           scope.where(account_id: account_id)
         end
       end
+
+      private
+
+      def permission_ability
+        "team.manage.teams"
+      end
     end
   end
 end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/teams_membership_policy.rb.tt

@@ -19,6 +19,12 @@ module Admin
           scope.where(account_id: account_id)
         end
       end
+
+      private
+
+      def permission_ability
+        "member.manage.teams"
+      end
     end
   end
 end

data/lib/generators/seams/admin/templates/app/views/seams/admin/application/_index_header.html.erb.tt

@@ -0,0 +1,57 @@
+<%%#
+  Copy of Administrate 1.0's _index_header with one change: the "New"
+  link. Administrate builds it from the dashboard class name, which
+  gives new_admin_admin_<resource>_path for Admin::*Dashboard. The
+  link is built from this controller instead.
+%>
+<%% content_for(:title) do %>
+  <%%= display_resource_name(page.resource_name) %>
+<%% end %>
+
+<header class="main-content__header">
+  <h1 class="main-content__page-title" id="page-title">
+    <%%= content_for(:title) %>
+  </h1>
+
+  <%%= content_for(:header_middle) %>
+
+  <%% if show_search_bar %>
+    <%%= render(
+      "search",
+      search_term: search_term,
+      resource_name: display_resource_name(page.resource_name)
+    ) %>
+
+    <%% if filters.any? %>
+      <div data-controller="tooltip">
+        <button data-tooltip-target="tooltip" popovertarget="search-tooltip" class="button--tooltip search__tooltip">
+          <svg role="img">
+            <use xlink:href="#icon-question-mark" />
+          </svg>
+        </button>
+
+        <div data-tooltip-target="popover" popover id="search-tooltip" role="tooltip" class="search__tooltip-popover search__tooltip-popover-positioning">
+          <p><strong>Use filters to refine your search</strong></p>
+          <ul>
+            <%% filters.keys.each do |filter_key| %>
+            <li><%%= filter_key %>:<span class="search__tooltip-popover-value">&lt;value&gt;</span></li>
+            <%% end %>
+          </ul>
+        </div>
+      </div>
+    <%% end %>
+  <%% end %>
+
+  <div>
+    <%%= link_to(
+      t(
+        "administrate.actions.new_resource",
+        name: display_resource_name(page.resource_name, singular: true).downcase
+      ),
+      url_for(controller: "/admin/#{controller_name}", action: :new),
+      class: "button",
+    ) if accessible_action?(new_resource, :new) %>
+  </div>
+
+  <%%= content_for(:header_last) %>
+</header>

data/lib/generators/seams/admin/templates/app/views/seams/admin/application/_navigation.html.erb.tt

@@ -0,0 +1,14 @@
+<%%#
+  Replaces Administrate's navigation partial. Administrate lists the
+  resources from Rails.application.routes, which does not include this
+  mounted engine, so its sidebar came out empty. Entries come from
+  Seams::Admin::ApplicationController#seams_admin_navigation: every
+  dashboard with an index route the current user may list.
+%>
+<nav class="navigation">
+  <%%= link_to(t("administrate.navigation.back_to_app"), main_app.root_path, class: "button button--alt button--nav") if main_app.respond_to?(:root_path) %>
+
+  <%% seams_admin_navigation.each do |entry| %>
+    <%%= link_to(entry[:label], entry[:path], class: "navigation__link navigation__link--#{entry[:active] ? "active" : "inactive"}") %>
+  <%% end %>
+</nav>

data/lib/generators/seams/admin/templates/config/routes.rb.tt

@@ -14,19 +14,29 @@ Seams::Admin::Engine.routes.draw do
   # Phase 2 dashboards. Per Administrate convention, each resource
   # gets a full CRUD route surface (index, show, new, create, edit,
   # update, destroy). The `controller:` option points at the
-  # engine-prefixed controllers under app/controllers/admin/.
-  resources :identities,             controller: "admin/identities"
-  resources :accounts,               controller: "admin/accounts"
-  resources :accounts_memberships,   controller: "admin/accounts_memberships"
-  resources :teams,                  controller: "admin/teams"
-  resources :teams_memberships,      controller: "admin/teams_memberships"
-  resources :invitations,            controller: "admin/invitations"
-  resources :notifications,          controller: "admin/notifications"
-  resources :notification_preferences, controller: "admin/notification_preferences"
-  resources :plans,                  controller: "admin/plans"
-  resources :subscriptions,          controller: "admin/subscriptions"
-  resources :invoices,               controller: "admin/invoices"
-  resources :lifetime_passes,        controller: "admin/lifetime_passes"
+  # top-level `Admin::*` controllers under app/controllers/admin/. The
+  # leading slash is required: isolate_namespace Seams::Admin would
+  # otherwise resolve "admin/identities" to
+  # Seams::Admin::Admin::IdentitiesController.
+  #
+  # `scope as: :admin` names the routes admin_identities, admin_plans,
+  # etc. Administrate's views build links and forms with those names
+  # (polymorphic `[:admin, resource]`); paths and controllers are
+  # unchanged.
+  scope as: :admin do
+    resources :identities,             controller: "/admin/identities"
+    resources :accounts,               controller: "/admin/accounts"
+    resources :accounts_memberships,   controller: "/admin/accounts_memberships"
+    resources :teams,                  controller: "/admin/teams"
+    resources :teams_memberships,      controller: "/admin/teams_memberships"
+    resources :invitations,            controller: "/admin/invitations"
+    resources :notifications,          controller: "/admin/notifications"
+    resources :notification_preferences, controller: "/admin/notification_preferences"
+    resources :plans,                  controller: "/admin/plans"
+    resources :subscriptions,          controller: "/admin/subscriptions"
+    resources :invoices,               controller: "/admin/invoices"
+    resources :lifetime_passes,        controller: "/admin/lifetime_passes"
+  end
 
   # Follow-up generators that add NEW route surfaces (custom collection routes, JSON-only endpoints) splice their resources here.
   # seams:insertion-point admin.routes.after_resources
@@ -34,5 +44,5 @@ Seams::Admin::Engine.routes.draw do
   # Default landing page so visiting `/admin` lands somewhere
   # meaningful. Identities is the natural index — the operator
   # console use case starts with "find this user".
-  root to: "admin/identities#index"
+  root to: "/admin/identities#index"
 end

data/lib/generators/seams/admin/templates/lib/concerns/authenticator.rb.tt

@@ -26,6 +26,9 @@ module Seams
 
       def authenticate_admin!
         return if admin_authenticator_call
+        # Signed-out visitors go to the auth engine's sign-in page; a
+        # signed-in identity that fails the gate gets the 403 below.
+        return authenticate_identity! if respond_to?(:signed_in?, true) && !signed_in?
 
         respond_with_admin_forbidden(<<~MSG.strip)
           Access denied. The seams admin surface is gated on

data/lib/generators/seams/admin/templates/lib/configuration.rb.tt

@@ -56,7 +56,9 @@ module Seams
         # Default authenticator: the current Identity must carry the
         # `staff` flag. Hosts that need a finer-grained gate (per-
         # account admin role, IP allow-list, etc.) override this.
-        @authenticator = ->(controller) { controller.current_identity&.staff? }
+        # `try` keeps the default safe on a controller without
+        # Auth::Authentication: no identity means the gate says no.
+        @authenticator = ->(controller) { controller.try(:current_identity)&.staff? }
 
         # :platform → admins see every Account's data. :tenant → admins
         # are scoped to the Account they're a member of. Phase 3 reads

data/lib/generators/seams/admin/templates/spec/runtime/admin_boot_spec.rb.tt

@@ -431,12 +431,14 @@ RSpec.describe "Seams::Admin engine boot", type: :integration do
     end
   end
 
-  describe "Admin::Tenant::ApplicationPolicy permitted?" do
+  # The base ApplicationPolicy names no ability and fails closed, so
+  # the role hierarchy is exercised through a concrete policy.
+  describe "Admin::Tenant::ApplicationPolicy permitted? (via AccountPolicy)" do
     let(:identity)   { Auth::Identity.create!(email: "tap-#{SecureRandom.hex(4)}@example.com", password: "verysecret", staff: false) }
     let(:account)    { Accounts::Account.create!(name: "Tenant", external_account_id: SecureRandom.random_number(2**31)) }
     let(:membership) { Accounts::Membership.new(account: account, identity_id: identity.id, name: "Member", role: role) }
     let(:ctx)        { Seams::Admin::Context.new(identity, membership) }
-    let(:policy)     { Admin::Tenant::ApplicationPolicy.new(ctx, account) }
+    let(:policy)     { Admin::Tenant::AccountPolicy.new(ctx, account) }
 
     context "with role=admin" do
       let(:role) { "admin" }

data/lib/generators/seams/auth/add_oauth_provider/add_oauth_provider_generator.rb

@@ -94,7 +94,7 @@ module Seams
                    engine_path("spec/lib/auth/oauth/#{snake_name}_spec.rb")
         end
 
-        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable-next Metrics/AbcSize
         def report_summary
           say ""
           say "  Auth OAuth provider `#{snake_name}` added.", :green
@@ -122,7 +122,6 @@ module Seams
           say "    bin/seams resolve --eject auth/lib/auth/oauth/#{snake_name}.rb"
           say ""
         end
-        # rubocop:enable Metrics/AbcSize
 
         private
 

data/lib/generators/seams/auth/auth_generator.rb

@@ -25,7 +25,7 @@ module Seams
     #     identity.signed_out.auth, session.expired.auth.
     #
     # Run with: bin/rails generate seams:auth
-    # rubocop:disable Metrics/ClassLength
+    # rubocop:disable-next Metrics/ClassLength
     class AuthGenerator < Rails::Generators::Base
       include Seams::Generators::HostInjector
       include Seams::Generators::EjectAware
@@ -306,6 +306,5 @@ module Seams
         SCHEMA
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/generators/seams/auth/templates/app/controllers/oauth/callbacks_controller.rb.tt

@@ -11,6 +11,9 @@ module Auth
     # can trick a victim into linking the attacker's OAuth identity to
     # the victim's account.
     class CallbacksController < ApplicationController
+      # The OAuth dance happens while signed out, so it must bypass the
+      # engine base controller's `authenticate_identity!`.
+      skip_before_action :authenticate_identity!, only: %i[start callback]
       skip_before_action :verify_authenticity_token, only: %i[callback]
 
       rescue_from Auth::OAuthProviderUnknown do |e|

data/lib/generators/seams/auth/templates/app/controllers/password_resets_controller.rb.tt

@@ -2,6 +2,10 @@
 
 module Auth
   class PasswordResetsController < ApplicationController
+    # Password reset is for signed-out users by definition; opt every
+    # action out of the engine base controller's `authenticate_identity!`.
+    skip_before_action :authenticate_identity!, only: %i[new create edit update]
+
     # 5 reset requests per hour per IP. Cheap to send mail but
     # creating reset tokens for every email is a guess-the-user attack
     # vector — rate-limit modestly.

data/lib/generators/seams/auth/templates/app/controllers/registrations_controller.rb.tt

@@ -2,6 +2,11 @@
 
 module Auth
   class RegistrationsController < ApplicationController
+    # Sign-up must be reachable while signed out (the engine base
+    # controller gates every action by default, which would redirect the
+    # sign-up form to the sign-in page).
+    skip_before_action :authenticate_identity!, only: %i[new create]
+
     # 5 sign-ups per hour per IP. Tighter than sign-in because each
     # successful row also sends a welcome email + provisions side
     # effects. Rails 8's built-in rate_limit uses Solid Cache.

data/lib/generators/seams/auth/templates/app/controllers/sessions_controller.rb.tt

@@ -2,6 +2,11 @@
 
 module Auth
   class SessionsController < ApplicationController
+    # The sign-in form must be reachable while signed out, or the engine
+    # base controller's `before_action :authenticate_identity!` redirects
+    # the login page to itself. `destroy` stays gated.
+    skip_before_action :authenticate_identity!, only: %i[new create]
+
     # 10 attempts per minute per IP. Rails 8's built-in rate_limit
     # uses Solid Cache by default; configure cache_store in your host
     # if you need to override.

data/lib/generators/seams/auth/templates/db/migrate/create_auth_oauth_providers.rb.tt

@@ -10,7 +10,11 @@
 # Risk: append-mostly. profile_data is a json column for the raw
 #       provider response (sub/login/etc) so we can re-derive things
 #       like display name without re-fetching.
-class CreateAuthOauthProviders < ActiveRecord::Migration[7.1]
+# Class name uses the camel-OA "OAuth" spelling: the auth engine registers
+# `OAuth` as an ActiveSupport inflector acronym, so the migrator camelizes
+# this file's name to CreateAuthOAuthProviders. A single-O class name would
+# raise `uninitialized constant CreateAuthOAuthProviders` at migrate time.
+class CreateAuthOAuthProviders < ActiveRecord::Migration[7.1]
   def change
     create_table :auth_oauth_providers do |t|
       t.references :identity,     null: false, foreign_key: { to_table: :auth_identities }

data/lib/generators/seams/auth/templates/lib/concerns/authentication.rb.tt

@@ -9,9 +9,20 @@ module Auth
   #
   #   class ApplicationController < ActionController::Base
   #     include Auth::Authentication
-  #     before_action :authenticate_identity!
   #   end
   #
+  # Including this concern is what makes `authenticate_identity!` available
+  # to every engine controller that inherits from the host's
+  # `::ApplicationController`. Engine generators produced by `seams:engine`
+  # enforce authentication on every action by default via:
+  #
+  #   before_action :authenticate_identity!
+  #
+  # Controllers serving public flows (e.g. password reset, invitation
+  # accept-via-token) must opt out explicitly:
+  #
+  #   skip_before_action :authenticate_identity!, only: %i[accept_form accept]
+  #
   # Side-effect: when a sign-in is resolved, `Current.identity` is set
   # so models / services downstream can access the signed-in identity
   # without threading it through every method. Future waves will add

data/lib/generators/seams/auth/templates/lib/engine.rb.tt

@@ -20,6 +20,20 @@ module Auth
       Rails.autoloaders.main.inflector.inflect("oauth" => "OAuth")
     end
 
+    # The Zeitwerk inflection above only governs *autoloading* (file path
+    # → constant). Routing resolves a controller from its path through
+    # ActiveSupport::Inflector#camelize, which is a *separate* inflector:
+    # the route `auth/oauth/callbacks#start` camelizes to
+    # `Auth::Oauth::CallbacksController` (single-O) and raises
+    # `uninitialized constant Auth::Oauth`, because the real class is
+    # `Auth::OAuth::CallbacksController`. Registering "OAuth" as an acronym
+    # makes camelize agree with Zeitwerk, so the OAuth routes resolve.
+    initializer "auth.inflection_acronym", before: :set_autoload_paths do
+      ActiveSupport::Inflector.inflections(:en) do |inflect|
+        inflect.acronym "OAuth"
+      end
+    end
+
     initializer "auth.register_events" do
       Seams::EventRegistry.register("identity.signed_up.auth",   emitted_by: "Auth")
       Seams::EventRegistry.register("identity.signed_in.auth",   emitted_by: "Auth")
@@ -32,6 +46,19 @@ module Auth
       # seams:insertion-point auth.engine.events
     end
 
+    initializer "auth.register_abilities" do
+      # Ability codes this engine owns, registered exactly like events
+      # (resource.action.engine). `read` is the member-level view;
+      # `manage` is the admin-level mutate. Host grant maps reference
+      # these codes; see Seams::Permissions::DEFAULT_GRANTS. The admin
+      # engine's tenant Identity policy resolves through
+      # `identity.manage.auth`.
+      Seams::PermissionRegistry.register("identity.read.auth",   owned_by: "Auth")
+      Seams::PermissionRegistry.register("identity.manage.auth", owned_by: "Auth")
+      # Follow-up generators that ship new auth abilities register them here.
+      # seams:insertion-point auth.engine.abilities
+    end
+
     initializer "auth.append_migrations" do |app|
       unless app.root == root
         config.paths["db/migrate"].expanded.each do |expanded_path|

data/lib/generators/seams/billing/billing_generator.rb

@@ -17,7 +17,7 @@ module Seams
     # the host's user model can include.
     #
     # Run with: bin/rails generate seams:billing
-    # rubocop:disable Metrics/ClassLength
+    # rubocop:disable-next Metrics/ClassLength
     class BillingGenerator < Rails::Generators::Base
       include Seams::Generators::HostInjector
       include Seams::Generators::EjectAware
@@ -77,6 +77,8 @@ module Seams
                                 engine_path("lib/billing/stripe/client.rb")
         template_unless_ejected "lib/stripe/webhook_signature.rb.tt",
                                 engine_path("lib/billing/stripe/webhook_signature.rb")
+        template_unless_ejected "lib/stripe/payload.rb.tt",
+                                engine_path("lib/billing/stripe/payload.rb")
 
         return if gateway == "stripe"
 
@@ -316,7 +318,7 @@ module Seams
         # maintains the gem as a first-class deliverable; tracking
         # their API ourselves wasn't worth the centralisation
         # benefit. See feedback_external_apis.md.
-        host_inject_gem("stripe", "~> 13.0")
+        host_inject_gem("stripe", "~> 19.0")
         host_inject_gem("factory_bot_rails", "~> 6.4",  group: :test)
         host_inject_gem("webmock",           "~> 3.23", group: :test)
         host_inject_mount(engine_class: "Billing::Engine", at: "/billing")
@@ -471,6 +473,5 @@ module Seams
         SCHEMA
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

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

@@ -215,6 +215,32 @@ STRIPE_SECRET_KEY=sk_live_...
 STRIPE_WEBHOOK_SECRET=whsec_...
 ```
 
+### Stripe gem and API version
+
+The generator pins `gem "stripe", "~> 19.0"`. stripe-ruby 19 sends API
+version `2026-08-26.dahlia` on every request (`Stripe.api_version`).
+Webhook payloads use the version set on the webhook endpoint, not the
+gem's. Create the endpoint on the same version so API responses and
+webhook payloads have the same shape.
+
+The handlers read the current (2025-03-31.basil and later) shapes and
+still accept the older ones:
+
+| Field                         | Current location                                  | Pre-basil fallback              |
+| ---                           | ---                                               | ---                             |
+| Invoice's subscription        | `invoice.parent.subscription_details.subscription` | `invoice.subscription`          |
+| Subscription period end       | `subscription.items.data[0].current_period_end`   | `subscription.current_period_end` |
+| Invoice paid time             | `invoice.status_transitions.paid_at`              | none                            |
+
+`Billing::Stripe::Payload` holds these readers. Use it from your own
+subscribers too: SDK objects (`::Stripe::StripeObject`) have no `#dig`.
+
+The endpoint accepts v1 snapshot events only. A v2 thin event is
+rejected with `400` (stripe-ruby 19 raises `ArgumentError` for it).
+
+Every `::Stripe::StripeError` from `Billing::Stripe::Client` is
+re-raised as `Billing::GatewayError`, with the original on `#cause`.
+
 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

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

@@ -32,6 +32,8 @@ module Billing
     private
 
     def scoped_invoices
+      return Billing::Invoice.none if current_billing_customer_ref.nil?
+
       Billing::Invoice.where(customer_ref: current_billing_customer_ref)
     end
 

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

@@ -77,6 +77,8 @@ module Billing
     # — the Stripe `cus_*` id resolved from the current Account — which
     # is correct whenever the controller has an Account in scope.
     def scoped_subscriptions
+      return Billing::Subscription.none if current_billing_customer_ref.nil?
+
       Billing::Subscription.where(customer_ref: current_billing_customer_ref)
     end
 

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

@@ -19,11 +19,14 @@ module Billing
         client.retrieve_invoice(@invoice_ref)
       end
 
+      # stripe_response is a ::Stripe::Invoice (no #dig). The
+      # subscription id moved to parent.subscription_details.subscription
+      # in API 2025-03-31.basil; Billing::Stripe::Payload reads both.
       def on_success(stripe_response)
         invoice = Billing::Invoice.find_or_initialize_by(gateway_ref: stripe_response[:id])
         invoice.assign_attributes(
-          customer_ref:     stripe_response[:customer],
-          subscription_ref: stripe_response[:subscription],
+          customer_ref:     Billing::Stripe::Payload.ref(stripe_response[:customer]),
+          subscription_ref: Billing::Stripe::Payload.invoice_subscription_ref(stripe_response),
           status:           stripe_response[:status],
           amount_cents:     stripe_response[:amount_paid] || stripe_response[:amount_due],
           currency:         stripe_response[:currency].to_s.upcase,
@@ -36,13 +39,11 @@ module Billing
 
       private
 
-      # Stripe moved the paid timestamp out of the top-level invoice
-      # object into status_transitions.paid_at — see
+      # The paid timestamp is status_transitions.paid_at — see
       # https://docs.stripe.com/api/invoices/object#invoice_object-status_transitions.
-      # We still tolerate a top-level :paid_at on older API versions.
+      # A top-level :paid_at is still tolerated for hand-built payloads.
       def paid_at_for(stripe_response)
-        unix = stripe_response.dig(:status_transitions, :paid_at) ||
-               stripe_response[:paid_at]
+        unix = Billing::Stripe::Payload.invoice_paid_at(stripe_response)
         unix && Time.at(unix)
       end
     end

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

@@ -3,9 +3,10 @@
 module Billing
   # Base class for service objects that talk to Stripe via
   # Billing::Stripe::Client. Subclasses define #call_stripe and the
-  # base wraps it in uniform error handling that converts Faraday
-  # errors + Billing::Stripe::Client errors into ServiceResult
-  # failures with stable codes.
+  # base wraps it in uniform error handling that converts the
+  # Billing::GatewayError raised by Billing::Stripe::Client (which
+  # translates every ::Stripe::StripeError from the `stripe` gem)
+  # into ServiceResult failures with stable codes.
   #
   #   class MyService < Billing::StripeService
   #     def initialize(plan_ref:)
@@ -43,10 +44,11 @@ module Billing
     def call
       on_success(call_stripe(client))
     rescue Billing::GatewayError => e
-      # The Faraday-based Billing::Stripe::Client raises
-      # Billing::GatewayError on 4xx/5xx, network failures, and
-      # auth errors. Sub-classify by message prefix so callers can
-      # branch on `result.code`.
+      # Billing::Stripe::Client re-raises every ::Stripe::StripeError
+      # (4xx/5xx, network failures, auth errors) as
+      # Billing::GatewayError with a stable message prefix.
+      # Sub-classify by that prefix so callers can branch on
+      # `result.code`.
       ServiceResult.failure(error: e.message, code: classify_gateway_error(e))
     end
 

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

@@ -12,6 +12,13 @@ module Billing
       # 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.
+      #
+      # Payload shape (stripe-ruby 19 / API 2026-08-26.dahlia): the
+      # subscription id is at invoice.parent.subscription_details.subscription.
+      # The top-level invoice.subscription was removed in
+      # 2025-03-31.basil; Billing::Stripe::Payload still reads it so
+      # events from an endpoint pinned to an older API version work.
+      # https://docs.stripe.com/changelog/basil/2025-03-31/adds-new-parent-field-to-invoicing-objects
       class InvoiceHandlerBase < Billing::Webhooks::Handler
         DEFAULT_STATUS = "open"
 
@@ -36,7 +43,7 @@ module Billing
 
           invoice.account_id       = resolved_account_id
           invoice.customer_ref     = customer_ref
-          invoice.subscription_ref = object_hash[:subscription] || object_hash["subscription"]
+          invoice.subscription_ref = subscription_ref
           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
@@ -53,7 +60,6 @@ module Billing
         # 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
@@ -67,12 +73,21 @@ module Billing
                                  .pick(:account_id)
         end
 
+        def subscription_ref
+          @subscription_ref ||= Billing::Stripe::Payload.invoice_subscription_ref(object_hash)
+        end
+
         def invoice_status
           self.class::INVOICE_STATUS || DEFAULT_STATUS
         end
 
+        # Stripe's own paid timestamp (status_transitions.paid_at) when
+        # the payload carries it; otherwise the time we saw the event.
         def paid_at_for_status
-          invoice_status == "paid" ? Time.current : nil
+          return nil unless invoice_status == "paid"
+
+          unix = Billing::Stripe::Payload.invoice_paid_at(object_hash)
+          unix ? Time.at(unix) : Time.current
         end
       end
     end