seams 0.1.0

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Billing
+  module Customers
+    # Resolves a Stripe customer for an Accounts::Account. Looks up by
+    # `email` first via /v1/customers/search; creates a new one if no
+    # match is found. Returns ServiceResult with `value: customer_ref`
+    # (the Stripe `cus_*` id).
+    #
+    #   result = Billing::Customers::FindOrCreateService.call(
+    #     email: "owner@acme.com",
+    #     metadata: { account_id: "5e3b...", account_name: "Acme Inc" }
+    #   )
+    #   result.ok?         # => true
+    #   result.value       # => "cus_xyz"
+    #
+    # Idempotent — re-running with the same email returns the same
+    # customer_ref. Stripe's `/v1/customers/search` index is eventually
+    # consistent (the docs quote a "less than a minute" delay:
+    # https://docs.stripe.com/api/customers/search), so two
+    # near-simultaneous signups for the same email can both miss the
+    # search and both fall through to `POST /v1/customers`. Stripe
+    # does not dedupe customers by email server-side, so without
+    # protection that produces two `cus_*` rows for the same person.
+    #
+    # We defend against that with a deterministic Stripe
+    # `Idempotency-Key` header derived from the email plus the
+    # caller-supplied scope (typically `account_id` — the tenant the
+    # customer represents). Per
+    # https://docs.stripe.com/api/idempotent_requests Stripe caches
+    # the response for at least 24h and replays it for the same key,
+    # so two concurrent calls with the same key produce one customer.
+    # The key is SHA-256(email:scope) so it stays well under the 255-
+    # character ceiling and is stable across retries.
+    class FindOrCreateService < Billing::StripeService
+      def initialize(email:, metadata: {})
+        @email    = email
+        @metadata = metadata
+      end
+
+      def call_stripe(client)
+        existing = client.search_customers(query: %(email:"#{@email}"), limit: 1)
+        return existing[:data].first if existing[:data].any?
+
+        client.create_customer(
+          email:           @email,
+          metadata:        @metadata,
+          idempotency_key: idempotency_key
+        )
+      end
+
+      def on_success(stripe_response)
+        ServiceResult.ok(value: stripe_response[:id])
+      end
+
+      private
+
+      # Deterministic per-(email, scope) key. SHA-256 hex is 64 chars
+      # — well within Stripe's 255-character limit
+      # (https://docs.stripe.com/api/idempotent_requests). The
+      # `seams:billing:customer:` prefix namespaces the key so it
+      # cannot collide with other engines that share the same Stripe
+      # account. Scope defaults to the caller-supplied `account_id`
+      # (the tenant the Stripe customer represents post-Wave-9).
+      def idempotency_key
+        scope = @metadata[:account_id] || @metadata["account_id"] || ""
+        Digest::SHA256.hexdigest("seams:billing:customer:#{@email}:#{scope}")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Billing
+  module Invoices
+    # Fetches an invoice from Stripe and upserts the local
+    # Billing::Invoice row. Used by the invoice.* webhook handlers
+    # for retries / out-of-order delivery, and by the
+    # InvoicesController for on-demand refresh when a host wants the
+    # latest status without waiting for the next webhook.
+    #
+    #   result = Billing::Invoices::SyncService.call(invoice_ref: "in_xyz")
+    #   result.value.status   # => "paid"
+    class SyncService < Billing::StripeService
+      def initialize(invoice_ref:)
+        @invoice_ref = invoice_ref
+      end
+
+      def call_stripe(client)
+        client.retrieve_invoice(@invoice_ref)
+      end
+
+      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],
+          status:           stripe_response[:status],
+          amount_cents:     stripe_response[:amount_paid] || stripe_response[:amount_due],
+          currency:         stripe_response[:currency].to_s.upcase,
+          paid_at:          paid_at_for(stripe_response)
+        )
+        invoice.save!
+
+        ServiceResult.ok(value: invoice)
+      end
+
+      private
+
+      # Stripe moved the paid timestamp out of the top-level invoice
+      # object into 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.
+      def paid_at_for(stripe_response)
+        unix = stripe_response.dig(:status_transitions, :paid_at) ||
+               stripe_response[:paid_at]
+        unix && Time.at(unix)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Billing
+  module Lifetime
+    # Creates a Stripe Checkout session for an LTD plan (`mode: payment`).
+    # Validates inventory + plan-is-lifetime before round-tripping to
+    # the gateway so a sold-out plan doesn't burn a Stripe API call.
+    #
+    # The `account_id:` arg is the Accounts::Account id that will own
+    # the LifetimePass once the buyer completes Checkout. It's
+    # threaded into Stripe's session metadata so the webhook handler
+    # (CreatePassFromCheckoutService) can write the correct
+    # `account_id` on the resulting LifetimePass row.
+    #
+    # Concurrency note (the reason this service is not "just call Stripe"):
+    # `Billing::Plan#max_lifetime_units` is enforced by counting issued
+    # `LifetimePass` rows. A plain count is racey — two browsers clicking
+    # "Buy lifetime" within the same second on a plan with one seat left
+    # will both pass the check, both hit Stripe Checkout, both pay, and
+    # the unique index on `(account_id, plan_ref)` does not save us
+    # because the buyers are on different accounts. We end up with
+    # `count > max_lifetime_units` and an oversold promo.
+    #
+    # The fix: open a transaction, take a `SELECT ... FOR UPDATE`
+    # row-lock on the plan, re-check inventory under the lock, and
+    # only THEN create the Stripe Checkout session. The lock is held
+    # for the duration of the Stripe API call (released on commit).
+    #
+    # Trade-off: the Stripe call can take up to ~30s, so under a viral
+    # promo with 1000+ concurrent buyers on the same plan, checkout
+    # session creation serialises. For LTDs (low-volume by design) this
+    # is the right trade — correctness over throughput. For high-volume
+    # workloads the alternative is optimistic concurrency via a counter
+    # column + `UPDATE ... WHERE remaining > 0 RETURNING`, which is out
+    # of scope for the seams generator.
+    #
+    # Returns a Result with ok?, url, error.
+    module CreateLifetimeSessionService
+      Result = Struct.new(:ok?, :url, :error, keyword_init: true)
+
+      module_function
+
+      def call(account_id:, customer_ref:, plan_ref:, success_url:, cancel_url:)
+        url = Billing::Plan.transaction do
+          plan = Billing::Plan.find_by(gateway_ref: plan_ref)
+          raise PlanLookupError, "Plan #{plan_ref.inspect} not found" unless plan
+          raise PlanLookupError, "Plan #{plan_ref.inspect} is not a lifetime plan" unless plan.lifetime?
+
+          # Inside the transaction so the row-lock is held until commit.
+          # Raises Billing::Plan::SoldOut if the cap is exhausted.
+          plan.enforce_lifetime_inventory_or_raise!
+
+          # Stripe Checkout session creation happens under the lock.
+          # Yes, this serialises concurrent buyers on the same plan —
+          # see the class comment for why that's the right trade for LTDs.
+          session = Billing.gateway.create_lifetime_checkout_session(
+            customer_ref: customer_ref,
+            plan_ref:     plan_ref,
+            success_url:  success_url,
+            cancel_url:   cancel_url,
+            metadata:     { account_id: account_id }
+          )
+          session[:url]
+        end
+
+        Result.new(ok?: true, url: url)
+      rescue PlanLookupError => e
+        Result.new(ok?: false, error: e.message)
+      rescue Billing::Plan::SoldOut => e
+        Result.new(ok?: false, error: e.message)
+      rescue Billing::GatewayError => e
+        Result.new(ok?: false, error: e.message)
+      end
+
+      # Internal sentinel so `find_by` misses + non-lifetime plans bubble
+      # out of the transaction block as failures (rather than as a return
+      # value, which `transaction { }` would commit). Not part of the
+      # public API.
+      class PlanLookupError < StandardError; end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Billing
+  module Lifetime
+    # Creates a LifetimePass from a successful Stripe Checkout Session.
+    # Called from the WebhooksController when a `checkout.session.completed`
+    # (or `checkout.session.async_payment_succeeded`) event arrives with
+    # `mode == "payment"` AND the session metadata flags `access_type:
+    # "lifetime"`.
+    #
+    # The session metadata MUST include `account_id` (the
+    # Accounts::Account id) — CreateLifetimeSessionService writes it
+    # when generating the Stripe Checkout session, so a webhook that
+    # arrives without it is from a manually-created session and
+    # should fail loudly.
+    #
+    # Idempotent on `gateway_ref` (the Stripe Checkout Session id) so
+    # Stripe retries hit the unique index and short-circuit.
+    #
+    # Publishes `lifetime.purchased.billing` on success.
+    #
+    # Docs:
+    #   https://docs.stripe.com/api/checkout/sessions/object
+    #   https://docs.stripe.com/payments/checkout/fulfill-orders
+    module CreatePassFromCheckoutService
+      Result = Struct.new(:ok?, :pass, :error, keyword_init: true)
+
+      module_function
+
+      def call(session:, livemode: false)
+        gateway_ref  = session_field(session, :id)
+        customer_ref = session_field(session, :customer)
+        metadata     = session_field(session, :metadata) || {}
+        plan_ref     = metadata_value(metadata, :plan_ref)
+        account_id   = metadata_value(metadata, :account_id)
+
+        return Result.new(ok?: false, error: "Session id missing") if gateway_ref.nil?
+        return Result.new(ok?: false, error: "Customer ref missing on session") if customer_ref.nil?
+        return Result.new(ok?: false, error: "plan_ref metadata missing on session") if plan_ref.nil?
+        return Result.new(ok?: false, error: "account_id metadata missing on session") if account_id.nil?
+
+        pass = Billing::LifetimePass.find_or_initialize_by(gateway_ref: gateway_ref)
+        return Result.new(ok?: true, pass: pass) if pass.persisted?
+
+        pass.assign_attributes(
+          account_id:   account_id,
+          customer_ref: customer_ref,
+          plan_ref:     plan_ref,
+          granted_at:   Time.current,
+          revoked_at:   nil
+        )
+        pass.save!
+
+        Seams::Events::Publisher.publish(
+          "lifetime.purchased.billing",
+          gateway:      Billing.configuration.gateway_name,
+          livemode:     livemode,
+          account_id:   account_id,
+          customer_ref: customer_ref,
+          ref:          pass.id.to_s,
+          object_id:    gateway_ref,
+          object:       { id: gateway_ref, account_id: account_id, plan_ref: plan_ref, pass_id: pass.id }
+        )
+        Result.new(ok?: true, pass: pass)
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique => e
+        Result.new(ok?: false, error: e.message)
+      end
+
+      # Stripe SDK objects respond to method-style access; webhook
+      # payloads parsed from JSON are Hashes. Handle both.
+      def self.session_field(session, name)
+        if session.respond_to?(name)
+          session.public_send(name)
+        elsif session.is_a?(Hash)
+          session[name] || session[name.to_s]
+        end
+      end
+
+      def self.metadata_value(metadata, key)
+        if metadata.respond_to?(key)
+          metadata.public_send(key)
+        elsif metadata.is_a?(Hash)
+          metadata[key] || metadata[key.to_s]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Billing
+  module Lifetime
+    # Privately grants a Lifetime Pass to an Account. NO Stripe charge —
+    # used for early adopters, influencer giveaways, support gestures,
+    # ToS-violation refunds-then-re-grant.
+    #
+    # The `granted_by` argument is an Auth::Identity (the human who
+    # pressed the "grant lifetime" button) — Identity, not the
+    # Account, because we record human action here. Pass `nil` for
+    # system-granted passes (background job / migration / seed data).
+    #
+    # Idempotent on (account_id, plan_ref) — re-granting an existing
+    # pass returns ok? + the existing record rather than raising.
+    #
+    # Publishes `lifetime.granted.billing` on success (canonical billing
+    # payload shape — see billing/README).
+    module GrantPassService
+      Result = Struct.new(:ok?, :pass, :error, keyword_init: true)
+
+      module_function
+
+      def call(account_id:, customer_ref:, plan_ref:, granted_by:, notes: nil)
+        plan = Billing::Plan.find_by(gateway_ref: plan_ref)
+        return Result.new(ok?: false, error: "Plan #{plan_ref.inspect} not found") unless plan
+        return Result.new(ok?: false, error: "Plan #{plan_ref.inspect} is not a lifetime plan") unless plan.lifetime?
+        return Result.new(ok?: false, error: "No lifetime inventory remaining for #{plan_ref.inspect}") if plan.lifetime_sold_out?
+
+        pass = Billing::LifetimePass.find_or_initialize_by(account_id: account_id, plan_ref: plan_ref)
+        return Result.new(ok?: true, pass: pass) if pass.persisted? && pass.active?
+
+        pass.assign_attributes(
+          customer_ref:           customer_ref,
+          gateway_ref:            nil,
+          granted_by_identity_id: granted_by_identity_id_from(granted_by),
+          granted_at:             Time.current,
+          revoked_at:             nil,
+          notes:                  notes
+        )
+        pass.save!
+
+        publish_granted(pass)
+        Result.new(ok?: true, pass: pass)
+      rescue ActiveRecord::RecordInvalid => e
+        Result.new(ok?: false, error: e.message)
+      end
+
+      # Coerces the `granted_by` argument into an integer Identity id.
+      # Accepts:
+      #   - an Integer (assumed already an Auth::Identity#id)
+      #   - any object responding to `#id` (an Auth::Identity record)
+      #   - nil (system-granted; column stays NULL)
+      def self.granted_by_identity_id_from(granted_by)
+        return granted_by if granted_by.is_a?(Integer)
+        return granted_by.id if granted_by.respond_to?(:id) && !granted_by.nil?
+
+        nil
+      end
+
+      def self.publish_granted(pass)
+        Seams::Events::Publisher.publish(
+          "lifetime.granted.billing",
+          gateway:      Billing.configuration.gateway_name,
+          livemode:     false,  # private grants are never livemode
+          account_id:   pass.account_id,
+          customer_ref: pass.customer_ref,
+          ref:          pass.id.to_s,
+          object_id:    pass.id.to_s,
+          object:       {
+            id:                     pass.id,
+            account_id:             pass.account_id,
+            plan_ref:               pass.plan_ref,
+            granted_by_identity_id: pass.granted_by_identity_id
+          }
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Billing
+  module Lifetime
+    # Revokes a previously-issued LifetimePass. Soft delete: sets
+    # `revoked_at` (and `revoked_by_identity_id`) so the audit trail
+    # survives. Use for refunds, ToS violations, support gestures
+    # that are later reversed.
+    #
+    # The `revoked_by` argument is an Auth::Identity (the human who
+    # pressed "revoke") — Identity, not the Account that lost the
+    # entitlement. Pass `nil` for system-revoked passes (a background
+    # ToS sweep, for instance).
+    #
+    # Stripe refund (if the pass was paid) is NOT issued here — the
+    # caller is expected to refund via the gateway separately. This
+    # service updates only the local row.
+    #
+    # Idempotent: revoking an already-revoked pass returns ok? + the
+    # same row without re-publishing the event.
+    module RevokePassService
+      Result = Struct.new(:ok?, :pass, :error, keyword_init: true)
+
+      module_function
+
+      def call(pass:, revoked_by:, notes: nil)
+        pass = Billing::LifetimePass.find(pass) if pass.is_a?(Integer)
+        return Result.new(ok?: false, error: "Pass not found") unless pass
+
+        return Result.new(ok?: true, pass: pass) if pass.revoked?
+
+        pass.update!(
+          revoked_at:             Time.current,
+          revoked_by_identity_id: GrantPassService.granted_by_identity_id_from(revoked_by),
+          notes:                  [pass.notes, notes].compact.join("\n---\n").presence
+        )
+
+        Seams::Events::Publisher.publish(
+          "lifetime.revoked.billing",
+          gateway:      Billing.configuration.gateway_name,
+          livemode:     false,
+          account_id:   pass.account_id,
+          customer_ref: pass.customer_ref,
+          ref:          pass.id.to_s,
+          object_id:    pass.id.to_s,
+          object:       {
+            id:                     pass.id,
+            account_id:             pass.account_id,
+            plan_ref:               pass.plan_ref,
+            revoked_by_identity_id: pass.revoked_by_identity_id
+          }
+        )
+        Result.new(ok?: true, pass: pass)
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotFound => e
+        Result.new(ok?: false, error: e.message)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Billing
+  module Portal
+    # Creates a customer-portal session — Stripe-hosted UI for the
+    # user to manage their subscription. Returns Result(ok?, url, error).
+    module CreateSessionService
+      Result = Struct.new(:ok?, :url, :error, keyword_init: true)
+
+      module_function
+
+      def call(customer_ref:, return_url:)
+        session = Billing.gateway.create_billing_portal_session(
+          customer_ref: customer_ref,
+          return_url:   return_url
+        )
+        Result.new(ok?: true, url: session[:url])
+      rescue Billing::GatewayError => e
+        Result.new(ok?: false, error: e.message)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Billing
+  # Uniform return shape for every Billing service object. Services
+  # return `Billing::ServiceResult.ok(value: ...)` or
+  # `Billing::ServiceResult.failure(error: ..., code: ...)` so callers
+  # can branch on `result.ok?` without each service inventing its own
+  # contract.
+  #
+  #   result = Billing::Subscriptions::CancelService.call(subscription_ref: "sub_X")
+  #   if result.ok?
+  #     redirect_to billing_root_path, notice: "Cancelled"
+  #   else
+  #     flash[:alert] = result.error
+  #     redirect_back(fallback_location: billing_root_path)
+  #   end
+  #
+  # `code:` is an optional machine-readable tag (`:not_found`,
+  # `:gateway_error`, `:already_cancelled`, etc.) that callers can
+  # branch on without parsing the human message in `error:`.
+  ServiceResult = Struct.new(:ok, :value, :error, :code, keyword_init: true) do
+    def self.ok(value: nil)
+      new(ok: true, value: value)
+    end
+
+    def self.failure(error:, code: nil)
+      new(ok: false, error: error, code: code)
+    end
+
+    def ok?
+      ok == true
+    end
+
+    def failure?
+      !ok?
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+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.
+  #
+  #   class MyService < Billing::StripeService
+  #     def initialize(plan_ref:)
+  #       @plan_ref = plan_ref
+  #     end
+  #
+  #     def call_stripe(client)
+  #       client.create_checkout_session(...)
+  #     end
+  #
+  #     def on_success(stripe_response)
+  #       ServiceResult.ok(value: stripe_response)
+  #     end
+  #   end
+  #
+  #   MyService.call(plan_ref: "p_pro")
+  class StripeService
+    def self.call(**kwargs)
+      new(**kwargs).call
+    end
+
+    # Override in subclasses. Receives a configured
+    # Billing::Stripe::Client. Return whatever the Stripe call
+    # returns — the base class translates it via #on_success.
+    def call_stripe(_client)
+      raise NotImplementedError, "#{self.class} must implement #call_stripe"
+    end
+
+    # Override to shape the Stripe response into the service's public
+    # ServiceResult value. Default: pass the raw response through.
+    def on_success(stripe_response)
+      ServiceResult.ok(value: stripe_response)
+    end
+
+    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`.
+      ServiceResult.failure(error: e.message, code: classify_gateway_error(e))
+    end
+
+    private
+
+    def classify_gateway_error(error)
+      case error.message
+      when /connection error|TimeoutError|ConnectionFailed/i then :gateway_unreachable
+      when /authentication|invalid api key/i                 then :gateway_auth
+      else                                                        :gateway_error
+      end
+    end
+
+    def client
+      @client ||= Billing::Stripe::Client.new(api_key: Billing.configuration.api_key)
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Billing
+  module Subscriptions
+    # Cancels a Stripe subscription. By default schedules the cancel
+    # for end-of-period (cancel_at_period_end: true) so the user
+    # keeps access through what they've already paid for.
+    # `immediate: true` cancels the subscription right away — the
+    # webhook fires customer.subscription.deleted shortly after.
+    #
+    #   Billing::Subscriptions::CancelService.call(
+    #     subscription_ref: subscription.gateway_ref
+    #   )
+    #
+    # Verified against
+    # https://docs.stripe.com/api/subscriptions/update (period-end)
+    # and https://docs.stripe.com/api/subscriptions/cancel (immediate).
+    class CancelService < Billing::StripeService
+      def initialize(subscription_ref:, immediate: false)
+        @subscription_ref = subscription_ref
+        @immediate        = immediate
+      end
+
+      def call_stripe(client)
+        if @immediate
+          client.cancel_subscription(@subscription_ref)
+        else
+          client.update_subscription(@subscription_ref, cancel_at_period_end: true)
+        end
+      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],
+                           canceled_at:         stripe_response[:canceled_at]
+                         })
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Billing
+  module Subscriptions
+    # Switches a Stripe subscription to a new price. Stripe requires
+    # the existing subscription_item id (not just the new price), so
+    # this service does a retrieve-then-update rather than a single
+    # call. Proration mode defaults to "create_prorations" so the
+    # user is billed/credited the difference immediately; pass
+    # `proration_behavior: "none"` to defer until the next cycle.
+    #
+    #   Billing::Subscriptions::ChangePlanService.call(
+    #     subscription_ref: "sub_xyz",
+    #     new_price_ref:    "price_pro_annual"
+    #   )
+    #
+    # Verified against
+    # https://docs.stripe.com/billing/subscriptions/upgrade-downgrade.
+    class ChangePlanService < Billing::StripeService
+      def initialize(subscription_ref:, new_price_ref:, proration_behavior: "create_prorations")
+        @subscription_ref   = subscription_ref
+        @new_price_ref      = new_price_ref
+        @proration_behavior = proration_behavior
+      end
+
+      def call_stripe(client)
+        existing      = client.retrieve_subscription(@subscription_ref)
+        existing_item = existing[:items][:data].first
+        return :no_items if existing_item.nil?
+
+        client.update_subscription(
+          @subscription_ref,
+          items: [
+            { id: existing_item[:id], price: @new_price_ref }
+          ],
+          proration_behavior: @proration_behavior
+        )
+      end
+
+      def on_success(stripe_response)
+        return ServiceResult.failure(error: "Subscription has no items", code: :invalid_state) if stripe_response == :no_items
+
+        new_price = stripe_response[:items][:data].first[:price][:id]
+        ServiceResult.ok(value: { id: stripe_response[:id], plan_ref: new_price })
+      end
+    end
+  end
+end