seams 0.1.0

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Billing
+  module Gateways
+    # Contract every billing gateway must implement. Subclass this
+    # in the host application to wire Paddle, Adyen, Lemon Squeezy,
+    # then point Billing.configuration.gateway at the subclass name.
+    class Abstract
+      # Create or fetch a recurring subscription for the host's
+      # customer. `customer_ref` is whatever opaque identifier the
+      # host stores on its user (typically a Stripe customer id).
+      def create_subscription(customer_ref:, plan_ref:, **)
+        raise NotImplementedError, "#{self.class} must implement #create_subscription"
+      end
+
+      def cancel_subscription(subscription_ref:, **)
+        raise NotImplementedError, "#{self.class} must implement #cancel_subscription"
+      end
+
+      # Retrieve a subscription as a normalised hash:
+      #   { id:, status:, current_period_end:, plan_ref: }
+      def fetch_subscription(subscription_ref:)
+        raise NotImplementedError, "#{self.class} must implement #fetch_subscription"
+      end
+
+      # Create a hosted checkout session. Returns a normalised hash:
+      #   { id:, url: }
+      # The host redirects the user to `url`, the gateway handles the
+      # payment UI, and webhooks tell us the result.
+      def create_checkout_session(customer_ref:, plan_ref:, success_url:, cancel_url:, **)
+        raise NotImplementedError, "#{self.class} must implement #create_checkout_session"
+      end
+
+      # Create a customer-portal session so the user can self-serve
+      # their subscription (cancel, change plan, update payment
+      # method). Returns: { id:, url: }.
+      def create_billing_portal_session(customer_ref:, return_url:, **)
+        raise NotImplementedError, "#{self.class} must implement #create_billing_portal_session"
+      end
+
+      # Create a one-time-payment hosted-checkout session for an LTD
+      # plan. Same return shape as #create_checkout_session, but uses
+      # the gateway's `mode: payment` flow (Stripe) — no recurring
+      # billing, no customer.subscription.* webhooks. Idempotency
+      # carries through metadata so the webhook handler can resolve
+      # the LTD plan_ref without a separate API call.
+      def create_lifetime_checkout_session(customer_ref:, plan_ref:, success_url:, cancel_url:, **)
+        raise NotImplementedError, "#{self.class} must implement #create_lifetime_checkout_session"
+      end
+
+      # Verify a webhook payload + signature and return a normalised
+      # event hash:
+      #   { id:, type:, livemode:, object: <provider's raw object>, raw: <payload> }
+      #
+      # `id:` is the gateway's own event id (e.g. evt_* from Stripe).
+      # The Billing webhook controller uses it to dedupe retries via
+      # Billing::WebhookEvent.unique(gateway, gateway_event_id).
+      # Implementations MUST raise Billing::WebhookError on any
+      # signature mismatch.
+      def verify_webhook(payload:, signature:, secret:)
+        raise NotImplementedError, "#{self.class} must implement #verify_webhook"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Billing
+  module Gateways
+    # Adyen gateway stub — generated when the host runs
+    # `bin/rails generate seams:billing --gateway=adyen`. Each method
+    # raises NotImplementedError. Verify against
+    # https://docs.adyen.com/api-explorer/ and ship via Faraday
+    # (no Net::HTTP — see feedback_external_apis.md).
+    class Adyen < Abstract
+      # Override every Abstract method here. Adyen uses a recurring
+      # payments / shopper reference flow — design your customer_ref
+      # mapping accordingly.
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Billing
+  module Gateways
+    # Paddle gateway stub — generated when the host runs
+    # `bin/rails generate seams:billing --gateway=paddle`. Each method
+    # raises NotImplementedError so the host knows exactly where to
+    # plug in Paddle's REST API. Verify against
+    # https://developer.paddle.com/api-reference and ship via Faraday
+    # (no Net::HTTP — see feedback_external_apis.md).
+    class Paddle < Abstract
+      # Override every Abstract method here. As a starting point:
+      #
+      #   def create_checkout_session(customer_ref:, plan_ref:, success_url:, cancel_url:, **)
+      #     # POST /transactions to https://api.paddle.com via Faraday.
+      #     # Return: { id:, url: }
+      #   end
+      #
+      # See lib/billing/stripe/client.rb for the Faraday wrapper pattern.
+    end
+  end
+end

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "billing/gateways/abstract"
+require "billing/stripe/client"
+require "billing/stripe/webhook_signature"
+
+module Billing
+  module Gateways
+    # Stripe billing gateway. Implements the Billing::Gateways::Abstract
+    # contract on top of the official `stripe` Ruby gem
+    # (https://github.com/stripe/stripe-ruby), wrapped in a thin
+    # facade at Billing::Stripe::Client so the rest of the engine
+    # has one place to call. Webhook signature verification uses
+    # Stripe::Webhook.construct_event from the same gem rather than
+    # a hand-rolled HMAC. Wave 8's earlier decision to roll a Faraday
+    # client was reversed in 2026-05 — the gem is actively maintained
+    # by Stripe and tracking their API ourselves wasn't worth the
+    # centralisation benefit Faraday alone provided.
+    #
+    # API surface used (verified against current Stripe docs):
+    #   POST   /v1/customers                   https://docs.stripe.com/api/customers/create
+    #   GET    /v1/customers/search            https://docs.stripe.com/api/customers/search
+    #   POST   /v1/subscriptions               https://docs.stripe.com/api/subscriptions/create
+    #   POST   /v1/subscriptions/{id}          https://docs.stripe.com/api/subscriptions/update
+    #   DELETE /v1/subscriptions/{id}          https://docs.stripe.com/api/subscriptions/cancel
+    #   GET    /v1/subscriptions/{id}          https://docs.stripe.com/api/subscriptions/retrieve
+    #   GET    /v1/invoices/{id}               https://docs.stripe.com/api/invoices/retrieve
+    #   POST   /v1/checkout/sessions           https://docs.stripe.com/api/checkout/sessions/create
+    #   POST   /v1/billing_portal/sessions     https://docs.stripe.com/api/customer_portal/sessions/create
+    #   Webhook signature                      https://docs.stripe.com/webhooks/signatures
+    class Stripe < Abstract
+      def initialize(client: nil)
+        super()
+        @injected_client = client
+      end
+
+      # Lazy so `Billing::Gateways::Stripe.new` works without an API
+      # key configured — important for contract specs that only check
+      # the method shape via reflection. Real callers exercise actual
+      # endpoints, which forces the client to be built (and the
+      # missing-key error to fire) at the call site, not at boot.
+      def client
+        @injected_client || @client ||= Billing::Stripe::Client.new(api_key: Billing.configuration.api_key)
+      end
+
+      # POST /v1/subscriptions
+      def create_subscription(customer_ref:, plan_ref:, **opts)
+        sub = client.create_subscription(
+          customer: customer_ref,
+          items:    [{ price: plan_ref }],
+          **opts
+        )
+        normalise_subscription(sub)
+      end
+
+      # DELETE /v1/subscriptions/{id}
+      def cancel_subscription(subscription_ref:, **opts)
+        sub = client.cancel_subscription(subscription_ref, **opts)
+        normalise_subscription(sub)
+      end
+
+      # GET /v1/subscriptions/{id}
+      def fetch_subscription(subscription_ref:)
+        sub = client.retrieve_subscription(subscription_ref)
+        normalise_subscription(sub)
+      end
+
+      # POST /v1/checkout/sessions  (mode: "subscription")
+      def create_checkout_session(customer_ref:, plan_ref:, success_url:, cancel_url:, **opts)
+        session = client.create_checkout_session({
+          mode:        "subscription",
+          line_items:  [{ price: plan_ref, quantity: 1 }],
+          customer:    customer_ref,
+          success_url: success_url,
+          cancel_url:  cancel_url
+        }.merge(opts))
+        { id: session["id"], url: session["url"] }
+      end
+
+      # POST /v1/billing_portal/sessions
+      def create_billing_portal_session(customer_ref:, return_url:, **)
+        session = client.create_billing_portal_session(
+          customer:   customer_ref,
+          return_url: return_url
+        )
+        { id: session["id"], url: session["url"] }
+      end
+
+      # POST /v1/checkout/sessions  (mode: "payment", LTD path).
+      # metadata.access_type=lifetime + metadata.plan_ref=<plan_ref>
+      # are duplicated on the session AND payment_intent_data so the
+      # webhook handler can read either one. Caller-supplied metadata
+      # (typically `account_id` so the webhook handler knows which
+      # tenant the resulting LifetimePass belongs to) is merged in;
+      # `access_type` and `plan_ref` always win to avoid an LTD
+      # session being misclassified.
+      def create_lifetime_checkout_session(customer_ref:, plan_ref:, success_url:, cancel_url:, metadata: {}, **opts)
+        merged_metadata = metadata.merge(access_type: "lifetime", plan_ref: plan_ref)
+        session = client.create_checkout_session({
+          mode:        "payment",
+          line_items:  [{ price: plan_ref, quantity: 1 }],
+          customer:    customer_ref,
+          success_url: success_url,
+          cancel_url:  cancel_url,
+          payment_intent_data: { metadata: merged_metadata },
+          metadata:            merged_metadata
+        }.merge(opts))
+        { id: session["id"], url: session["url"] }
+      end
+
+      # https://docs.stripe.com/webhooks/signatures
+      # Verifies the Stripe-Signature header against `secret` via the
+      # official Stripe::Webhook helper. Raises Billing::WebhookError
+      # on any failure (no header / signature mismatch / timestamp
+      # outside the 5-minute tolerance window / non-JSON payload).
+      # Returns the normalised event hash on success.
+      def verify_webhook(payload:, signature:, secret:)
+        event = Billing::Stripe::WebhookSignature.verify!(
+          payload:          payload,
+          signature_header: signature,
+          secret:           secret
+        )
+        # event.data["object"] is a Stripe::StripeObject. Convert to
+        # a plain Hash so subscribers downstream don't need to know
+        # they're dealing with a Stripe SDK type — the engine's
+        # contract is "events are hashes".
+        object_hash = event.data["object"].respond_to?(:to_hash) ? event.data["object"].to_hash.transform_keys(&:to_s) : event.data["object"]
+        {
+          id:       event["id"],            # evt_* — controller dedupes via Billing::WebhookEvent
+          type:     event["type"],
+          livemode: event["livemode"],
+          object:   object_hash,
+          raw:      payload
+        }
+      end
+
+      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.
+      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")
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "stripe"
+
+module Billing
+  module Stripe
+    # Thin facade over the official `stripe` Ruby gem so the engine's
+    # service objects + gateway have one shape to call. The previous
+    # version of this file was a hand-rolled Faraday REST client we
+    # owned; that decision was reversed in 2026-05 (Wave 8 → reversed
+    # Wave 6) because Stripe maintains the gem as a first-class
+    # deliverable and keeping our own client current with their API
+    # was strictly more work than the centralisation benefit Faraday
+    # alone gave us.
+    #
+    # The public method surface is unchanged — every service object
+    # 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.
+    #
+    # Verified against:
+    #   https://docs.stripe.com/api/customers/create
+    #   https://docs.stripe.com/api/customers/search
+    #   https://docs.stripe.com/api/subscriptions/create
+    #   https://docs.stripe.com/api/subscriptions/update
+    #   https://docs.stripe.com/api/subscriptions/cancel
+    #   https://docs.stripe.com/api/subscriptions/retrieve
+    #   https://docs.stripe.com/api/invoices/retrieve
+    #   https://docs.stripe.com/api/checkout/sessions/create
+    #   https://docs.stripe.com/api/customer_portal/sessions/create
+    #   https://docs.stripe.com/api/idempotent_requests
+    class Client
+      def initialize(api_key:)
+        @sdk = ::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))
+      end
+
+      # DELETE /v1/subscriptions/{id}
+      def cancel_subscription(subscription_id, **extra)
+        sdk.v1.subscriptions.cancel(subscription_id, extra)
+      end
+
+      # GET /v1/subscriptions/{id}
+      def retrieve_subscription(subscription_id)
+        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)
+      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)
+      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)
+      end
+
+      # POST /v1/customers. The optional `idempotency_key:` is the gem's
+      # standard per-request opts hash (Stripe holds the response for
+      # ~24h and replays it for the same key, so concurrent
+      # FindOrCreate calls during a signup burst produce one customer
+      # instead of two — see https://docs.stripe.com/api/idempotent_requests).
+      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)
+      end
+
+      # GET /v1/customers/search
+      def search_customers(query:, limit: 1)
+        sdk.v1.customers.search(query: query, limit: limit)
+      end
+
+      # GET /v1/invoices/{id}
+      def retrieve_invoice(invoice_id)
+        sdk.v1.invoices.retrieve(invoice_id)
+      end
+
+      private
+
+      attr_reader :sdk
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "stripe"
+
+module Billing
+  module Stripe
+    # Verifies the Stripe-Signature header on incoming webhooks via
+    # the official `stripe` gem's first-party helper.
+    #
+    # Stripe maintains the verification logic — HMAC-SHA256 over
+    # `<timestamp>.<payload>`, 5-minute tolerance window, multiple
+    # v1= entries for key rotation, constant-time comparison. We used
+    # to reimplement this against https://docs.stripe.com/webhooks/signatures
+    # in a hand-rolled HMAC module; that decision was reversed in
+    # 2026-05 because Stripe ships breaking changes to the signing
+    # scheme over time and the gem tracks them as a first-class
+    # commitment.
+    #
+    # Public surface preserved (verify!) so callers (Billing::Gateways::Stripe)
+    # don't need to change. Stripe::SignatureVerificationError is
+    # rethrown as Billing::WebhookError to keep the engine's error
+    # boundary intact.
+    module WebhookSignature
+      DEFAULT_TOLERANCE = 300  # seconds — matches Stripe's default
+
+      module_function
+
+      # 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).
+      def verify!(payload:, signature_header:, secret:, tolerance: DEFAULT_TOLERANCE)
+        raise Billing::WebhookError, "Stripe-Signature header missing" if signature_header.nil? || signature_header.empty?
+
+        ::Stripe::Webhook.construct_event(payload, signature_header, secret, tolerance: tolerance)
+      rescue ::Stripe::SignatureVerificationError => e
+        raise Billing::WebhookError, "Stripe signature invalid: #{e.message}"
+      rescue JSON::ParserError => e
+        raise Billing::WebhookError, "Stripe payload not JSON: #{e.message}"
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/lib/tasks/billing_check.rake.tt

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Smoke-check Billing configuration without hitting Stripe.
+#
+# Run from a host or CI before promoting a deploy:
+#
+#   bin/rails seams:billing:check_config
+#
+# Exit non-zero if anything required is missing — wire it into your
+# pre-deploy gate so a missing STRIPE_SECRET_KEY fails the deploy
+# instead of silently surviving boot and 500ing on the first webhook.
+namespace :seams do
+  namespace :billing do
+    desc "Verify Billing configuration is complete (api_key + webhook_secret) — exits non-zero if not"
+    task check_config: :environment do
+      missing = []
+      missing << "Billing.configuration.api_key (set STRIPE_SECRET_KEY or assign in initializer)" \
+        if Billing.configuration.api_key.to_s.strip.empty?
+      missing << "Billing.configuration.webhook_secret (set STRIPE_WEBHOOK_SECRET or assign in initializer)" \
+        if Billing.configuration.webhook_secret.to_s.strip.empty?
+
+      if missing.any?
+        warn "Billing config incomplete:"
+        missing.each { |m| warn "  - #{m}" }
+        warn ""
+        warn "Without these, Billing::Gateways::Stripe will raise at the first " \
+             "outbound API call or webhook, not at boot. Set them before deploying."
+        abort("Billing config check failed.")
+      end
+
+      puts "Billing config OK: api_key + webhook_secret are present."
+    end
+  end
+end

data/lib/generators/seams/billing/templates/spec/factories/billing.rb.tt

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Factories for Billing engine specs. Sequences keep ref columns
+# (gateway_ref, customer_ref, plan_ref) unique across the spec run
+# so uniqueness validations don't trip.
+#
+# Post-Wave-9: every billing-row factory carries an `account_id`
+# (UUID) — the Accounts::Account the row belongs to. We don't
+# `association :account` because cross-engine model access is
+# forbidden by the Seams cops; the spec generates a fresh
+# SecureRandom UUID per row, which is safe in a test DB without a
+# DB-level FK to accounts. Hosts that have an Accounts::Account
+# factory available can override the `account_id` value with one
+# from a real `create(:account)`.
+FactoryBot.define do
+  factory :billing_plan, class: "Billing::Plan" do
+    sequence(:gateway_ref) { |n| "price_test_#{n}" }
+    sequence(:name)        { |n| "Plan #{n}" }
+    amount_cents           { 1299 }
+    currency               { "GBP" }
+    interval               { "month" }
+    trial_period_days      { 0 }
+
+    factory :billing_lifetime_plan do
+      interval                   { "lifetime" }
+      max_lifetime_units         { nil }
+      sequence(:gateway_ref) { |n| "price_test_lifetime_#{n}" }
+    end
+  end
+
+  factory :billing_subscription, class: "Billing::Subscription" do
+    account_id              { SecureRandom.uuid }
+    sequence(:gateway_ref)  { |n| "sub_test_#{n}" }
+    sequence(:customer_ref) { |n| "cus_test_#{n}" }
+    sequence(:plan_ref)     { |n| "price_test_#{n}" }
+    status                  { "active" }
+    current_period_end      { 30.days.from_now }
+  end
+
+  factory :billing_invoice, class: "Billing::Invoice" do
+    account_id                     { SecureRandom.uuid }
+    sequence(:gateway_ref)         { |n| "in_test_#{n}" }
+    sequence(:customer_ref)        { |n| "cus_test_#{n}" }
+    sequence(:subscription_ref)    { |n| "sub_test_#{n}" }
+    status                         { "paid" }
+    amount_cents                   { 1299 }
+    currency                       { "GBP" }
+    paid_at                        { Time.current }
+  end
+
+  factory :billing_lifetime_pass, class: "Billing::LifetimePass" do
+    account_id              { SecureRandom.uuid }
+    sequence(:customer_ref) { |n| "cus_test_lifetime_#{n}" }
+    sequence(:plan_ref)     { |n| "price_test_lifetime_#{n}" }
+    sequence(:gateway_ref)  { |n| "cs_test_#{n}" }
+    granted_at              { Time.current }
+  end
+
+  factory :billing_webhook_event, class: "Billing::WebhookEvent" do
+    gateway                     { "stripe" }
+    sequence(:gateway_event_id) { |n| "evt_test_#{n}" }
+    event_type                  { "customer.subscription.created" }
+    livemode                    { false }
+  end
+end

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

@@ -0,0 +1,19 @@
+{
+  "id": "evt_test_charge_refunded",
+  "object": "event",
+  "type": "charge.refunded",
+  "livemode": false,
+  "created": 1731100000,
+  "data": {
+    "object": {
+      "id": "ch_test_123",
+      "object": "charge",
+      "customer": "cus_test_123",
+      "payment_intent": "pi_test_123",
+      "amount": 1299,
+      "amount_refunded": 1299,
+      "currency": "gbp",
+      "refunded": true
+    }
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "id": "evt_test_checkout_session_completed",
+  "object": "event",
+  "type": "checkout.session.completed",
+  "livemode": false,
+  "created": 1731200000,
+  "data": {
+    "object": {
+      "id": "cs_test_123",
+      "object": "checkout.session",
+      "mode": "subscription",
+      "customer": "cus_test_123",
+      "subscription": "sub_test_123",
+      "payment_status": "paid"
+    }
+  }
+}

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

@@ -0,0 +1,25 @@
+{
+  "id": "evt_test_subscription_created",
+  "object": "event",
+  "type": "customer.subscription.created",
+  "livemode": false,
+  "created": 1730000000,
+  "data": {
+    "object": {
+      "id": "sub_test_123",
+      "object": "subscription",
+      "customer": "cus_test_123",
+      "status": "active",
+      "current_period_end": 1732678400,
+      "items": {
+        "data": [
+          {
+            "id": "si_test_123",
+            "price": { "id": "price_test_pro", "lookup_key": "pro" },
+            "current_period_end": 1732678400
+          }
+        ]
+      }
+    }
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "id": "evt_test_subscription_deleted",
+  "object": "event",
+  "type": "customer.subscription.deleted",
+  "livemode": false,
+  "created": 1730200000,
+  "data": {
+    "object": {
+      "id": "sub_test_123",
+      "object": "subscription",
+      "customer": "cus_test_123",
+      "status": "canceled",
+      "canceled_at": 1730200000,
+      "items": { "data": [] }
+    }
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "id": "evt_test_trial_will_end",
+  "object": "event",
+  "type": "customer.subscription.trial_will_end",
+  "livemode": false,
+  "created": 1730300000,
+  "data": {
+    "object": {
+      "id": "sub_test_123",
+      "object": "subscription",
+      "customer": "cus_test_123",
+      "status": "trialing",
+      "trial_end": 1730560000,
+      "items": { "data": [{ "price": { "lookup_key": "pro" } }] }
+    }
+  }
+}

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

@@ -0,0 +1,28 @@
+{
+  "id": "evt_test_subscription_updated",
+  "object": "event",
+  "type": "customer.subscription.updated",
+  "livemode": false,
+  "created": 1730100000,
+  "data": {
+    "object": {
+      "id": "sub_test_123",
+      "object": "subscription",
+      "customer": "cus_test_123",
+      "status": "active",
+      "current_period_end": 1735270400,
+      "items": {
+        "data": [
+          {
+            "id": "si_test_123",
+            "price": { "id": "price_test_pro_annual", "lookup_key": "pro_annual" },
+            "current_period_end": 1735270400
+          }
+        ]
+      }
+    },
+    "previous_attributes": {
+      "items": { "data": [{ "price": { "lookup_key": "pro" } }] }
+    }
+  }
+}

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

@@ -0,0 +1,18 @@
+{
+  "id": "evt_test_invoice_created",
+  "object": "event",
+  "type": "invoice.created",
+  "livemode": false,
+  "created": 1730400000,
+  "data": {
+    "object": {
+      "id": "in_test_123",
+      "object": "invoice",
+      "customer": "cus_test_123",
+      "subscription": "sub_test_123",
+      "status": "draft",
+      "amount_due": 1299,
+      "currency": "gbp"
+    }
+  }
+}