seams 0.1.0 → 0.2.0

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

@@ -60,32 +60,18 @@ module Billing
         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
+          Billing::Stripe::Payload.subscription_price_ref(object_hash)
         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
+        # Since API 2025-03-31.basil the billing period lives on each
+        # subscription item (items.data[].current_period_end); the
+        # subscription-level field was removed. Read the first item,
+        # fall back to the root for payloads from older API versions.
+        # https://docs.stripe.com/changelog/basil/2025-03-31/deprecate-subscription-current-period-start-and-end
         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 = Billing::Stripe::Payload.subscription_current_period_end(object_hash)
           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

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

@@ -33,6 +33,21 @@ module Billing
       # seams:insertion-point billing.engine.events
     end
 
+    initializer "billing.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.
+      Seams::PermissionRegistry.register("invoice.read.billing",        owned_by: "Billing")
+      Seams::PermissionRegistry.register("invoice.manage.billing",      owned_by: "Billing")
+      Seams::PermissionRegistry.register("subscription.read.billing",   owned_by: "Billing")
+      Seams::PermissionRegistry.register("subscription.manage.billing", owned_by: "Billing")
+      Seams::PermissionRegistry.register("plan.manage.billing",         owned_by: "Billing")
+      Seams::PermissionRegistry.register("lifetime.manage.billing",     owned_by: "Billing")
+      # Follow-up generators that ship new billing abilities register them here.
+      # seams:insertion-point billing.engine.abilities
+    end
+
     initializer "billing.append_migrations" do |app|
       unless app.root == root
         config.paths["db/migrate"].expanded.each do |expanded_path|

data/lib/generators/seams/billing/templates/lib/gateways/stripe.rb.tt

@@ -3,6 +3,7 @@
 require "billing/gateways/abstract"
 require "billing/stripe/client"
 require "billing/stripe/webhook_signature"
+require "billing/stripe/payload"
 
 module Billing
   module Gateways
@@ -136,18 +137,17 @@ module Billing
 
       private
 
-      # Stripe's response shape changed: current_period_end now lives
-      # on items.data[].current_period_end. We try the subscription
-      # root first for backwards compatibility, then fall back to the
-      # first item.
+      # `sub` is a ::Stripe::Subscription from the gem (no #dig) or a
+      # Hash in specs; Billing::Stripe::Payload reads both.
+      # Since API 2025-03-31.basil current_period_end lives on
+      # items.data[] only; the subscription root is the fallback for
+      # older payloads.
       def normalise_subscription(sub)
-        items_data = sub.dig("items", "data") || []
-        first_item = items_data.first || {}
         {
-          id:                  sub["id"],
-          status:              sub["status"],
-          current_period_end:  sub["current_period_end"] || first_item["current_period_end"],
-          plan_ref:            first_item.dig("price", "id")
+          id:                 Billing::Stripe::Payload.dig(sub, :id),
+          status:             Billing::Stripe::Payload.dig(sub, :status),
+          current_period_end: Billing::Stripe::Payload.subscription_current_period_end(sub),
+          plan_ref:           Billing::Stripe::Payload.subscription_price_ref(sub)
         }
       end
     end

data/lib/generators/seams/billing/templates/lib/stripe/client.rb.tt

@@ -17,10 +17,23 @@ module Billing
     # and the gateway adapter call this Client without knowing
     # whether the implementation is Faraday or the gem.
     #
-    # Stripe gem version pinned to ~> 13 in the host Gemfile by the
-    # Billing generator. The StripeClient API
-    # (`client.v1.<resource>.<action>`) is what Stripe documents at
-    # https://docs.stripe.com/api?lang=ruby for every endpoint we use.
+    # Stripe gem version pinned to ~> 19 in the host Gemfile by the
+    # Billing generator. stripe-ruby 19 pins API version
+    # 2026-08-26.dahlia (see ::Stripe.api_version). The StripeClient
+    # API (`client.v1.<resource>.<action>`) is what Stripe documents
+    # at https://docs.stripe.com/api?lang=ruby for every endpoint we
+    # use. Responses are ::Stripe::StripeObject instances: read them
+    # with `obj[:key]` or Billing::Stripe::Payload.dig — they have no
+    # Hash#dig.
+    #
+    # Errors: every ::Stripe::StripeError raised by the gem is
+    # re-raised as Billing::GatewayError (original kept as #cause),
+    # because every caller in the engine rescues Billing::GatewayError.
+    # The message prefix is what Billing::StripeService#classify_gateway_error
+    # matches on:
+    #   ::Stripe::APIConnectionError             -> "Stripe connection error: ..."
+    #   ::Stripe::AuthenticationError/Permission -> "Stripe authentication error: ..."
+    #   any other ::Stripe::StripeError          -> "Stripe <ErrorClass>: ..."
     #
     # Verified against:
     #   https://docs.stripe.com/api/customers/create
@@ -34,42 +47,45 @@ module Billing
     #   https://docs.stripe.com/api/customer_portal/sessions/create
     #   https://docs.stripe.com/api/idempotent_requests
     class Client
+      # StripeClient.new raises ::Stripe::AuthenticationError on a nil
+      # key; translated like any other call so callers see
+      # Billing::GatewayError (code :gateway_auth).
       def initialize(api_key:)
-        @sdk = ::Stripe::StripeClient.new(api_key)
+        @sdk = translate_errors { ::Stripe::StripeClient.new(api_key) }
       end
 
       # POST /v1/subscriptions
       def create_subscription(customer:, items:, **extra)
-        sdk.v1.subscriptions.create({ customer: customer, items: items }.merge(extra))
+        translate_errors { sdk.v1.subscriptions.create({ customer: customer, items: items }.merge(extra)) }
       end
 
       # DELETE /v1/subscriptions/{id}
       def cancel_subscription(subscription_id, **extra)
-        sdk.v1.subscriptions.cancel(subscription_id, extra)
+        translate_errors { sdk.v1.subscriptions.cancel(subscription_id, extra) }
       end
 
       # GET /v1/subscriptions/{id}
       def retrieve_subscription(subscription_id)
-        sdk.v1.subscriptions.retrieve(subscription_id)
+        translate_errors { sdk.v1.subscriptions.retrieve(subscription_id) }
       end
 
       # POST /v1/subscriptions/{id} — used by ChangePlanService (items[])
       # and ReactivateService (cancel_at_period_end: false).
       def update_subscription(subscription_id, **fields)
-        sdk.v1.subscriptions.update(subscription_id, fields)
+        translate_errors { sdk.v1.subscriptions.update(subscription_id, fields) }
       end
 
       # POST /v1/checkout/sessions — params is a Hash (subscription
       # mode for recurring; payment mode for LTDs).
       def create_checkout_session(params)
-        sdk.v1.checkout.sessions.create(params)
+        translate_errors { sdk.v1.checkout.sessions.create(params) }
       end
 
       # POST /v1/billing_portal/sessions
       def create_billing_portal_session(customer:, return_url: nil)
         body = { customer: customer }
         body[:return_url] = return_url if return_url
-        sdk.v1.billing_portal.sessions.create(body)
+        translate_errors { sdk.v1.billing_portal.sessions.create(body) }
       end
 
       # POST /v1/customers. The optional `idempotency_key:` is the gem's
@@ -80,22 +96,32 @@ module Billing
       def create_customer(email:, idempotency_key: nil, **extra)
         body = { email: email }.merge(extra)
         opts = idempotency_key ? { idempotency_key: idempotency_key } : {}
-        sdk.v1.customers.create(body, opts)
+        translate_errors { sdk.v1.customers.create(body, opts) }
       end
 
       # GET /v1/customers/search
       def search_customers(query:, limit: 1)
-        sdk.v1.customers.search(query: query, limit: limit)
+        translate_errors { sdk.v1.customers.search({ query: query, limit: limit }) }
       end
 
       # GET /v1/invoices/{id}
       def retrieve_invoice(invoice_id)
-        sdk.v1.invoices.retrieve(invoice_id)
+        translate_errors { sdk.v1.invoices.retrieve(invoice_id) }
       end
 
       private
 
       attr_reader :sdk
+
+      def translate_errors
+        yield
+      rescue ::Stripe::APIConnectionError => e
+        raise Billing::GatewayError, "Stripe connection error: #{e.message}"
+      rescue ::Stripe::AuthenticationError, ::Stripe::PermissionError => e
+        raise Billing::GatewayError, "Stripe authentication error: #{e.message}"
+      rescue ::Stripe::StripeError => e
+        raise Billing::GatewayError, "Stripe #{e.class.name.split('::').last}: #{e.message}"
+      end
     end
   end
 end

data/lib/generators/seams/billing/templates/lib/stripe/payload.rb.tt

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Billing
+  module Stripe
+    # Reads Stripe objects without caring where they came from.
+    #
+    # The engine sees the same Stripe resource in three shapes:
+    #
+    #   1. a `::Stripe::StripeObject` returned by the `stripe` gem
+    #      (Billing::Stripe::Client). It supports `obj[:key]` but has
+    #      NO `#dig` — calling `dig` on it raises NoMethodError.
+    #   2. the Hash built by Billing::Gateways::Stripe#verify_webhook
+    #      (string keys at the top level, symbol keys below it).
+    #   3. a JSON-parsed Hash (string keys, or symbol keys in specs).
+    #
+    # `dig` walks any mix of those. The field readers below also hide
+    # the Stripe API-version differences the engine cares about, so
+    # the rest of the engine reads one field instead of two.
+    #
+    # API-version notes (stripe-ruby 19 pins 2026-08-26.dahlia; the
+    # shape changes below arrived in 2025-03-31.basil):
+    #   https://docs.stripe.com/changelog/basil/2025-03-31/adds-new-parent-field-to-invoicing-objects
+    #   https://docs.stripe.com/changelog/basil/2025-03-31/deprecate-subscription-current-period-start-and-end
+    #   https://docs.stripe.com/changelog/basil/2025-03-31/add-support-for-multiple-partial-payments-on-invoices
+    module Payload
+      module_function
+
+      # Key-tolerant dig. Integer segments index into Arrays.
+      #
+      #   Payload.dig(invoice, :parent, :subscription_details, :subscription)
+      #   Payload.dig(subscription, :items, :data, 0, :current_period_end)
+      def dig(object, *path)
+        path.reduce(object) do |node, key|
+          return nil if node.nil?
+
+          fetch(node, key)
+        end
+      end
+
+      def fetch(node, key)
+        if key.is_a?(Integer)
+          node.is_a?(Array) ? node[key] : nil
+        elsif node.is_a?(Hash)
+          node.key?(key.to_s) ? node[key.to_s] : node[key.to_sym]
+        elsif node.respond_to?(:keys) && node.respond_to?(:[])
+          node[key.to_sym] # ::Stripe::StripeObject
+        end
+      end
+
+      # Stripe id for a field that is either an id String or an
+      # expanded object.
+      def ref(value)
+        value.is_a?(String) ? value : dig(value, :id)
+      end
+
+      # The subscription an invoice belongs to.
+      # Current API: invoice.parent.subscription_details.subscription.
+      # Before 2025-03-31.basil: invoice.subscription.
+      def invoice_subscription_ref(invoice)
+        ref(dig(invoice, :parent, :subscription_details, :subscription)) ||
+          ref(dig(invoice, :subscription))
+      end
+
+      # Unix time the invoice was paid, or nil. Stripe reports it on
+      # status_transitions.paid_at; a top-level paid_at is tolerated
+      # for hand-built payloads.
+      def invoice_paid_at(invoice)
+        dig(invoice, :status_transitions, :paid_at) || dig(invoice, :paid_at)
+      end
+
+      # First subscription item (items.data[0]) or nil.
+      def first_subscription_item(subscription)
+        dig(subscription, :items, :data, 0)
+      end
+
+      # Unix end of the current billing period.
+      # Current API: items.data[].current_period_end (one per item).
+      # Before 2025-03-31.basil: subscription.current_period_end.
+      def subscription_current_period_end(subscription)
+        dig(first_subscription_item(subscription), :current_period_end) ||
+          dig(subscription, :current_period_end)
+      end
+
+      # Price id of the first subscription item.
+      def subscription_price_ref(subscription)
+        ref(dig(first_subscription_item(subscription), :price))
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/lib/stripe/webhook_signature.rb.tt

@@ -28,7 +28,15 @@ module Billing
       # Returns the parsed Stripe::Event on success; raises
       # Billing::WebhookError on any failure mode (no header,
       # malformed header, no v1, no matching v1, timestamp outside
-      # tolerance, malformed JSON).
+      # tolerance, malformed JSON, or a v2 "thin" event).
+      #
+      # stripe-ruby 19 made construct_event raise ArgumentError when
+      # the signed body is a v2 event notification
+      # (object: "v2.core.event"). This endpoint handles v1 snapshot
+      # events only, so a v2 payload means the event destination is
+      # misconfigured: we answer 400 via Billing::WebhookError rather
+      # than a 500.
+      # https://github.com/stripe/stripe-ruby/wiki/Migration-guide-for-v19
       def verify!(payload:, signature_header:, secret:, tolerance: DEFAULT_TOLERANCE)
         raise Billing::WebhookError, "Stripe-Signature header missing" if signature_header.nil? || signature_header.empty?
 
@@ -37,6 +45,8 @@ module Billing
         raise Billing::WebhookError, "Stripe signature invalid: #{e.message}"
       rescue JSON::ParserError => e
         raise Billing::WebhookError, "Stripe payload not JSON: #{e.message}"
+      rescue ArgumentError => e
+        raise Billing::WebhookError, "Stripe payload is not a v1 event: #{e.message}"
       end
     end
   end

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/charge_refunded.json.tt

@@ -4,6 +4,7 @@
   "type": "charge.refunded",
   "livemode": false,
   "created": 1731100000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "ch_test_123",

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/checkout_session_completed.json.tt

@@ -4,6 +4,7 @@
   "type": "checkout.session.completed",
   "livemode": false,
   "created": 1731200000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "cs_test_123",

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/customer_subscription_created.json.tt

@@ -4,21 +4,32 @@
   "type": "customer.subscription.created",
   "livemode": false,
   "created": 1730000000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "sub_test_123",
       "object": "subscription",
       "customer": "cus_test_123",
       "status": "active",
-      "current_period_end": 1732678400,
       "items": {
+        "object": "list",
         "data": [
           {
             "id": "si_test_123",
-            "price": { "id": "price_test_pro", "lookup_key": "pro" },
-            "current_period_end": 1732678400
+            "object": "subscription_item",
+            "current_period_start": 1730000000,
+            "current_period_end": 1732678400,
+            "price": {
+              "id": "price_test_pro",
+              "object": "price",
+              "lookup_key": "pro"
+            },
+            "quantity": 1,
+            "subscription": "sub_test_123"
           }
-        ]
+        ],
+        "has_more": false,
+        "url": "/v1/subscription_items?subscription=sub_test_123"
       }
     }
   }

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/customer_subscription_deleted.json.tt

@@ -4,6 +4,7 @@
   "type": "customer.subscription.deleted",
   "livemode": false,
   "created": 1730200000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "sub_test_123",
@@ -11,7 +12,12 @@
       "customer": "cus_test_123",
       "status": "canceled",
       "canceled_at": 1730200000,
-      "items": { "data": [] }
+      "items": {
+        "object": "list",
+        "data": [],
+        "has_more": false,
+        "url": "/v1/subscription_items?subscription=sub_test_123"
+      }
     }
   }
 }

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/customer_subscription_trial_will_end.json.tt

@@ -4,6 +4,7 @@
   "type": "customer.subscription.trial_will_end",
   "livemode": false,
   "created": 1730300000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "sub_test_123",
@@ -11,7 +12,23 @@
       "customer": "cus_test_123",
       "status": "trialing",
       "trial_end": 1730560000,
-      "items": { "data": [{ "price": { "lookup_key": "pro" } }] }
+      "items": {
+        "object": "list",
+        "data": [
+          {
+            "id": "si_test_123",
+            "object": "subscription_item",
+            "current_period_start": 1729955200,
+            "current_period_end": 1730560000,
+            "price": {
+              "object": "price",
+              "lookup_key": "pro"
+            }
+          }
+        ],
+        "has_more": false,
+        "url": "/v1/subscription_items?subscription=sub_test_123"
+      }
     }
   }
 }

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/customer_subscription_updated.json.tt

@@ -4,25 +4,46 @@
   "type": "customer.subscription.updated",
   "livemode": false,
   "created": 1730100000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "sub_test_123",
       "object": "subscription",
       "customer": "cus_test_123",
       "status": "active",
-      "current_period_end": 1735270400,
       "items": {
+        "object": "list",
         "data": [
           {
             "id": "si_test_123",
-            "price": { "id": "price_test_pro_annual", "lookup_key": "pro_annual" },
-            "current_period_end": 1735270400
+            "object": "subscription_item",
+            "current_period_start": 1732678400,
+            "current_period_end": 1735270400,
+            "price": {
+              "id": "price_test_pro_annual",
+              "object": "price",
+              "lookup_key": "pro_annual"
+            },
+            "quantity": 1,
+            "subscription": "sub_test_123"
           }
-        ]
+        ],
+        "has_more": false,
+        "url": "/v1/subscription_items?subscription=sub_test_123"
       }
     },
     "previous_attributes": {
-      "items": { "data": [{ "price": { "lookup_key": "pro" } }] }
+      "items": {
+        "data": [
+          {
+            "id": "si_test_123",
+            "price": {
+              "id": "price_test_pro",
+              "lookup_key": "pro"
+            }
+          }
+        ]
+      }
     }
   }
 }

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/invoice_created.json.tt

@@ -4,15 +4,29 @@
   "type": "invoice.created",
   "livemode": false,
   "created": 1730400000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "in_test_123",
       "object": "invoice",
       "customer": "cus_test_123",
-      "subscription": "sub_test_123",
+      "parent": {
+        "type": "subscription_details",
+        "quote_details": null,
+        "subscription_details": {
+          "metadata": {},
+          "subscription": "sub_test_123"
+        }
+      },
       "status": "draft",
       "amount_due": 1299,
-      "currency": "gbp"
+      "currency": "gbp",
+      "status_transitions": {
+        "finalized_at": null,
+        "marked_uncollectible_at": null,
+        "paid_at": null,
+        "voided_at": null
+      }
     }
   }
 }

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/invoice_finalized.json.tt

@@ -4,15 +4,29 @@
   "type": "invoice.finalized",
   "livemode": false,
   "created": 1730700000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "in_test_123",
       "object": "invoice",
       "customer": "cus_test_123",
-      "subscription": "sub_test_123",
+      "parent": {
+        "type": "subscription_details",
+        "quote_details": null,
+        "subscription_details": {
+          "metadata": {},
+          "subscription": "sub_test_123"
+        }
+      },
       "status": "open",
       "amount_due": 1299,
-      "currency": "gbp"
+      "currency": "gbp",
+      "status_transitions": {
+        "finalized_at": 1730700000,
+        "marked_uncollectible_at": null,
+        "paid_at": null,
+        "voided_at": null
+      }
     }
   }
 }

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/invoice_paid.json.tt

@@ -4,16 +4,31 @@
   "type": "invoice.paid",
   "livemode": false,
   "created": 1730500000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "in_test_123",
       "object": "invoice",
       "customer": "cus_test_123",
-      "subscription": "sub_test_123",
+      "parent": {
+        "type": "subscription_details",
+        "quote_details": null,
+        "subscription_details": {
+          "metadata": {},
+          "subscription": "sub_test_123"
+        }
+      },
       "status": "paid",
       "amount_paid": 1299,
       "currency": "gbp",
-      "paid_at": 1730500000
+      "amount_due": 1299,
+      "amount_remaining": 0,
+      "status_transitions": {
+        "finalized_at": 1730450000,
+        "marked_uncollectible_at": null,
+        "paid_at": 1730500000,
+        "voided_at": null
+      }
     }
   }
 }

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/invoice_payment_failed.json.tt

@@ -4,17 +4,31 @@
   "type": "invoice.payment_failed",
   "livemode": false,
   "created": 1730600000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "in_test_123",
       "object": "invoice",
       "customer": "cus_test_123",
-      "subscription": "sub_test_123",
+      "parent": {
+        "type": "subscription_details",
+        "quote_details": null,
+        "subscription_details": {
+          "metadata": {},
+          "subscription": "sub_test_123"
+        }
+      },
       "status": "open",
       "amount_due": 1299,
       "currency": "gbp",
       "attempt_count": 1,
-      "next_payment_attempt": 1730700000
+      "next_payment_attempt": 1730700000,
+      "status_transitions": {
+        "finalized_at": 1730550000,
+        "marked_uncollectible_at": null,
+        "paid_at": null,
+        "voided_at": null
+      }
     }
   }
 }

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/invoice_voided.json.tt

@@ -4,15 +4,29 @@
   "type": "invoice.voided",
   "livemode": false,
   "created": 1730800000,
+  "api_version": "2026-08-26.dahlia",
   "data": {
     "object": {
       "id": "in_test_123",
       "object": "invoice",
       "customer": "cus_test_123",
-      "subscription": "sub_test_123",
+      "parent": {
+        "type": "subscription_details",
+        "quote_details": null,
+        "subscription_details": {
+          "metadata": {},
+          "subscription": "sub_test_123"
+        }
+      },
       "status": "void",
       "amount_due": 1299,
-      "currency": "gbp"
+      "currency": "gbp",
+      "status_transitions": {
+        "finalized_at": 1730700000,
+        "marked_uncollectible_at": null,
+        "paid_at": null,
+        "voided_at": 1730800000
+      }
     }
   }
 }