stripe 15.5.0 → 16.0.0

data/lib/stripe/services/treasury/transaction_service.rb

@@ -4,101 +4,6 @@
 module Stripe
   module Treasury
     class TransactionService < StripeService
-      class ListParams < Stripe::RequestParams
-        class Created < Stripe::RequestParams
-          # Minimum value to filter by (exclusive)
-          attr_accessor :gt
-          # Minimum value to filter by (inclusive)
-          attr_accessor :gte
-          # Maximum value to filter by (exclusive)
-          attr_accessor :lt
-          # Maximum value to filter by (inclusive)
-          attr_accessor :lte
-
-          def initialize(gt: nil, gte: nil, lt: nil, lte: nil)
-            @gt = gt
-            @gte = gte
-            @lt = lt
-            @lte = lte
-          end
-        end
-
-        class StatusTransitions < Stripe::RequestParams
-          class PostedAt < Stripe::RequestParams
-            # Minimum value to filter by (exclusive)
-            attr_accessor :gt
-            # Minimum value to filter by (inclusive)
-            attr_accessor :gte
-            # Maximum value to filter by (exclusive)
-            attr_accessor :lt
-            # Maximum value to filter by (inclusive)
-            attr_accessor :lte
-
-            def initialize(gt: nil, gte: nil, lt: nil, lte: nil)
-              @gt = gt
-              @gte = gte
-              @lt = lt
-              @lte = lte
-            end
-          end
-          # Returns Transactions with `posted_at` within the specified range.
-          attr_accessor :posted_at
-
-          def initialize(posted_at: nil)
-            @posted_at = posted_at
-          end
-        end
-        # Only return Transactions that were created during the given date interval.
-        attr_accessor :created
-        # A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
-        attr_accessor :ending_before
-        # Specifies which fields in the response should be expanded.
-        attr_accessor :expand
-        # Returns objects associated with this FinancialAccount.
-        attr_accessor :financial_account
-        # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
-        attr_accessor :limit
-        # The results are in reverse chronological order by `created` or `posted_at`. The default is `created`.
-        attr_accessor :order_by
-        # A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
-        attr_accessor :starting_after
-        # Only return Transactions that have the given status: `open`, `posted`, or `void`.
-        attr_accessor :status
-        # A filter for the `status_transitions.posted_at` timestamp. When using this filter, `status=posted` and `order_by=posted_at` must also be specified.
-        attr_accessor :status_transitions
-
-        def initialize(
-          created: nil,
-          ending_before: nil,
-          expand: nil,
-          financial_account: nil,
-          limit: nil,
-          order_by: nil,
-          starting_after: nil,
-          status: nil,
-          status_transitions: nil
-        )
-          @created = created
-          @ending_before = ending_before
-          @expand = expand
-          @financial_account = financial_account
-          @limit = limit
-          @order_by = order_by
-          @starting_after = starting_after
-          @status = status
-          @status_transitions = status_transitions
-        end
-      end
-
-      class RetrieveParams < Stripe::RequestParams
-        # Specifies which fields in the response should be expanded.
-        attr_accessor :expand
-
-        def initialize(expand: nil)
-          @expand = expand
-        end
-      end
-
       # Retrieves a list of Transaction objects.
       def list(params = {}, opts = {})
         request(

data/lib/stripe/services/v1_services.rb

@@ -4,7 +4,7 @@ module Stripe
   class V1Services < StripeService
     # v1 accessors: The beginning of the section generated from our OpenAPI spec
     attr_reader :accounts
-    attr_reader :account_links, :account_sessions, :apple_pay_domains, :application_fees, :apps, :balance, :balance_transactions, :billing, :billing_portal, :charges, :checkout, :climate, :confirmation_tokens, :country_specs, :coupons, :credit_notes, :customers, :customer_sessions, :disputes, :entitlements, :ephemeral_keys, :events, :exchange_rates, :files, :file_links, :financial_connections, :forwarding, :identity, :invoices, :invoice_items, :invoice_payments, :invoice_rendering_templates, :issuing, :mandates, :payment_intents, :payment_links, :payment_methods, :payment_method_configurations, :payment_method_domains, :payouts, :plans, :prices, :products, :promotion_codes, :quotes, :radar, :refunds, :reporting, :reviews, :setup_attempts, :setup_intents, :shipping_rates, :sigma, :sources, :subscriptions, :subscription_items, :subscription_schedules, :tax, :tax_codes, :tax_ids, :tax_rates, :terminal, :test_helpers, :tokens, :topups, :transfers, :treasury, :webhook_endpoints
+    attr_reader :account_links, :account_sessions, :apple_pay_domains, :application_fees, :apps, :balance, :balance_settings, :balance_transactions, :billing, :billing_portal, :charges, :checkout, :climate, :confirmation_tokens, :country_specs, :coupons, :credit_notes, :customers, :customer_sessions, :disputes, :entitlements, :ephemeral_keys, :events, :exchange_rates, :files, :file_links, :financial_connections, :forwarding, :identity, :invoices, :invoice_items, :invoice_payments, :invoice_rendering_templates, :issuing, :mandates, :payment_intents, :payment_links, :payment_methods, :payment_method_configurations, :payment_method_domains, :payouts, :plans, :prices, :products, :promotion_codes, :quotes, :radar, :refunds, :reporting, :reviews, :setup_attempts, :setup_intents, :shipping_rates, :sigma, :sources, :subscriptions, :subscription_items, :subscription_schedules, :tax, :tax_codes, :tax_ids, :tax_rates, :terminal, :test_helpers, :tokens, :topups, :transfers, :treasury, :webhook_endpoints
     # v1 accessors: The end of the section generated from our OpenAPI spec
 
     # OAuthService is manually maintained, as it has special behaviors
@@ -20,6 +20,7 @@ module Stripe
       @application_fees = Stripe::ApplicationFeeService.new(@requestor)
       @apps = Stripe::AppsService.new(@requestor)
       @balance = Stripe::BalanceService.new(@requestor)
+      @balance_settings = Stripe::BalanceSettingsService.new(@requestor)
       @balance_transactions = Stripe::BalanceTransactionService.new(@requestor)
       @billing = Stripe::BillingService.new(@requestor)
       @billing_portal = Stripe::BillingPortalService.new(@requestor)

data/lib/stripe/services/v2/billing/meter_event_adjustment_service.rb

@@ -5,29 +5,6 @@ module Stripe
   module V2
     module Billing
       class MeterEventAdjustmentService < StripeService
-        class CreateParams < Stripe::RequestParams
-          class Cancel < Stripe::RequestParams
-            # Unique identifier for the event. You can only cancel events within 24 hours of Stripe receiving them.
-            attr_accessor :identifier
-
-            def initialize(identifier: nil)
-              @identifier = identifier
-            end
-          end
-          # Specifies which event to cancel.
-          attr_accessor :cancel
-          # The name of the meter event. Corresponds with the `event_name` field on a meter.
-          attr_accessor :event_name
-          # Specifies whether to cancel a single event or a range of events for a time period. Time period cancellation is not supported yet.
-          attr_accessor :type
-
-          def initialize(cancel: nil, event_name: nil, type: nil)
-            @cancel = cancel
-            @event_name = event_name
-            @type = type
-          end
-        end
-
         # Creates a meter event adjustment to cancel a previously sent meter event.
         def create(params = {}, opts = {})
           request(

data/lib/stripe/services/v2/billing/meter_event_service.rb

@@ -5,31 +5,6 @@ module Stripe
   module V2
     module Billing
       class MeterEventService < StripeService
-        class CreateParams < Stripe::RequestParams
-          # The name of the meter event. Corresponds with the `event_name` field on a meter.
-          attr_accessor :event_name
-          # A unique identifier for the event. If not provided, one will be generated.
-          # We recommend using a globally unique identifier for this. We’ll enforce
-          # uniqueness within a rolling 24 hour period.
-          attr_accessor :identifier
-          # The payload of the event. This must contain the fields corresponding to a meter’s
-          # `customer_mapping.event_payload_key` (default is `stripe_customer_id`) and
-          # `value_settings.event_payload_key` (default is `value`). Read more about
-          # the
-          # [payload](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage#payload-key-overrides).
-          attr_accessor :payload
-          # The time of the event. Must be within the past 35 calendar days or up to
-          # 5 minutes in the future. Defaults to current timestamp if not specified.
-          attr_accessor :timestamp
-
-          def initialize(event_name: nil, identifier: nil, payload: nil, timestamp: nil)
-            @event_name = event_name
-            @identifier = identifier
-            @payload = payload
-            @timestamp = timestamp
-          end
-        end
-
         # Creates a meter event. Events are validated synchronously, but are processed asynchronously. Supports up to 1,000 events per second in livemode. For higher rate-limits, please use meter event streams instead.
         def create(params = {}, opts = {})
           request(

data/lib/stripe/services/v2/billing/meter_event_session_service.rb

@@ -5,8 +5,6 @@ module Stripe
   module V2
     module Billing
       class MeterEventSessionService < StripeService
-        class CreateParams < Stripe::RequestParams; end
-
         # Creates a meter event session to send usage on the high-throughput meter event stream. Authentication tokens are only valid for 15 minutes, so you will need to create a new meter event session when your token expires.
         def create(params = {}, opts = {})
           request(

data/lib/stripe/services/v2/billing/meter_event_stream_service.rb

@@ -5,39 +5,6 @@ module Stripe
   module V2
     module Billing
       class MeterEventStreamService < StripeService
-        class CreateParams < Stripe::RequestParams
-          class Event < Stripe::RequestParams
-            # The name of the meter event. Corresponds with the `event_name` field on a meter.
-            attr_accessor :event_name
-            # A unique identifier for the event. If not provided, one will be generated.
-            # We recommend using a globally unique identifier for this. We’ll enforce
-            # uniqueness within a rolling 24 hour period.
-            attr_accessor :identifier
-            # The payload of the event. This must contain the fields corresponding to a meter’s
-            # `customer_mapping.event_payload_key` (default is `stripe_customer_id`) and
-            # `value_settings.event_payload_key` (default is `value`). Read more about
-            # the
-            # [payload](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage#payload-key-overrides).
-            attr_accessor :payload
-            # The time of the event. Must be within the past 35 calendar days or up to
-            # 5 minutes in the future. Defaults to current timestamp if not specified.
-            attr_accessor :timestamp
-
-            def initialize(event_name: nil, identifier: nil, payload: nil, timestamp: nil)
-              @event_name = event_name
-              @identifier = identifier
-              @payload = payload
-              @timestamp = timestamp
-            end
-          end
-          # List of meter events to include in the request.
-          attr_accessor :events
-
-          def initialize(events: nil)
-            @events = events
-          end
-        end
-
         # Creates meter events. Events are processed asynchronously, including validation. Requires a meter event session for authentication. Supports up to 10,000 requests per second in livemode. For even higher rate-limits, contact sales.
         #
         # ** raises TemporarySessionExpiredError

data/lib/stripe/services/v2/core/event_destination_service.rb

@@ -5,143 +5,6 @@ module Stripe
   module V2
     module Core
       class EventDestinationService < StripeService
-        class ListParams < Stripe::RequestParams
-          # Additional fields to include in the response. Currently supports `webhook_endpoint.url`.
-          attr_accessor :include
-          # The page size.
-          attr_accessor :limit
-
-          def initialize(include: nil, limit: nil)
-            @include = include
-            @limit = limit
-          end
-        end
-
-        class CreateParams < Stripe::RequestParams
-          class AmazonEventbridge < Stripe::RequestParams
-            # The AWS account ID.
-            attr_accessor :aws_account_id
-            # The region of the AWS event source.
-            attr_accessor :aws_region
-
-            def initialize(aws_account_id: nil, aws_region: nil)
-              @aws_account_id = aws_account_id
-              @aws_region = aws_region
-            end
-          end
-
-          class WebhookEndpoint < Stripe::RequestParams
-            # The URL of the webhook endpoint.
-            attr_accessor :url
-
-            def initialize(url: nil)
-              @url = url
-            end
-          end
-          # An optional description of what the event destination is used for.
-          attr_accessor :description
-          # The list of events to enable for this endpoint.
-          attr_accessor :enabled_events
-          # Payload type of events being subscribed to.
-          attr_accessor :event_payload
-          # Where events should be routed from.
-          attr_accessor :events_from
-          # Additional fields to include in the response.
-          attr_accessor :include
-          # Metadata.
-          attr_accessor :metadata
-          # Event destination name.
-          attr_accessor :name
-          # If using the snapshot event payload, the API version events are rendered as.
-          attr_accessor :snapshot_api_version
-          # Event destination type.
-          attr_accessor :type
-          # Amazon EventBridge configuration.
-          attr_accessor :amazon_eventbridge
-          # Webhook endpoint configuration.
-          attr_accessor :webhook_endpoint
-
-          def initialize(
-            description: nil,
-            enabled_events: nil,
-            event_payload: nil,
-            events_from: nil,
-            include: nil,
-            metadata: nil,
-            name: nil,
-            snapshot_api_version: nil,
-            type: nil,
-            amazon_eventbridge: nil,
-            webhook_endpoint: nil
-          )
-            @description = description
-            @enabled_events = enabled_events
-            @event_payload = event_payload
-            @events_from = events_from
-            @include = include
-            @metadata = metadata
-            @name = name
-            @snapshot_api_version = snapshot_api_version
-            @type = type
-            @amazon_eventbridge = amazon_eventbridge
-            @webhook_endpoint = webhook_endpoint
-          end
-        end
-
-        class DeleteParams < Stripe::RequestParams; end
-
-        class RetrieveParams < Stripe::RequestParams
-          # Additional fields to include in the response.
-          attr_accessor :include
-
-          def initialize(include: nil)
-            @include = include
-          end
-        end
-
-        class UpdateParams < Stripe::RequestParams
-          class WebhookEndpoint < Stripe::RequestParams
-            # The URL of the webhook endpoint.
-            attr_accessor :url
-
-            def initialize(url: nil)
-              @url = url
-            end
-          end
-          # An optional description of what the event destination is used for.
-          attr_accessor :description
-          # The list of events to enable for this endpoint.
-          attr_accessor :enabled_events
-          # Additional fields to include in the response. Currently supports `webhook_endpoint.url`.
-          attr_accessor :include
-          # Metadata.
-          attr_accessor :metadata
-          # Event destination name.
-          attr_accessor :name
-          # Webhook endpoint configuration.
-          attr_accessor :webhook_endpoint
-
-          def initialize(
-            description: nil,
-            enabled_events: nil,
-            include: nil,
-            metadata: nil,
-            name: nil,
-            webhook_endpoint: nil
-          )
-            @description = description
-            @enabled_events = enabled_events
-            @include = include
-            @metadata = metadata
-            @name = name
-            @webhook_endpoint = webhook_endpoint
-          end
-        end
-
-        class DisableParams < Stripe::RequestParams; end
-        class EnableParams < Stripe::RequestParams; end
-        class PingParams < Stripe::RequestParams; end
-
         # Create a new event destination.
         def create(params = {}, opts = {})
           request(

data/lib/stripe/services/v2/core/event_service.rb

@@ -5,22 +5,6 @@ module Stripe
   module V2
     module Core
       class EventService < StripeService
-        class ListParams < Stripe::RequestParams
-          # The page size.
-          attr_accessor :limit
-          # Primary object ID used to retrieve related events.
-          #
-          # To avoid conflict with Ruby's ':object_id', this attribute has been renamed. If using a hash parameter map instead, please use the original name ':object_id' with NO trailing underscore as the provided param key.
-          attr_accessor :object_id_
-
-          def initialize(limit: nil, object_id_: nil)
-            @limit = limit
-            @object_id_ = object_id_
-          end
-        end
-
-        class RetrieveParams < Stripe::RequestParams; end
-
         # List events, going back up to 30 days.
         def list(params = {}, opts = {})
           request(

data/lib/stripe/services/webhook_endpoint_service.rb

@@ -3,101 +3,6 @@
 
 module Stripe
   class WebhookEndpointService < StripeService
-    class DeleteParams < Stripe::RequestParams; end
-
-    class RetrieveParams < Stripe::RequestParams
-      # Specifies which fields in the response should be expanded.
-      attr_accessor :expand
-
-      def initialize(expand: nil)
-        @expand = expand
-      end
-    end
-
-    class UpdateParams < Stripe::RequestParams
-      # An optional description of what the webhook is used for.
-      attr_accessor :description
-      # Disable the webhook endpoint if set to true.
-      attr_accessor :disabled
-      # The list of events to enable for this endpoint. You may specify `['*']` to enable all events, except those that require explicit selection.
-      attr_accessor :enabled_events
-      # Specifies which fields in the response should be expanded.
-      attr_accessor :expand
-      # Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
-      attr_accessor :metadata
-      # The URL of the webhook endpoint.
-      attr_accessor :url
-
-      def initialize(
-        description: nil,
-        disabled: nil,
-        enabled_events: nil,
-        expand: nil,
-        metadata: nil,
-        url: nil
-      )
-        @description = description
-        @disabled = disabled
-        @enabled_events = enabled_events
-        @expand = expand
-        @metadata = metadata
-        @url = url
-      end
-    end
-
-    class ListParams < Stripe::RequestParams
-      # A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
-      attr_accessor :ending_before
-      # Specifies which fields in the response should be expanded.
-      attr_accessor :expand
-      # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
-      attr_accessor :limit
-      # A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
-      attr_accessor :starting_after
-
-      def initialize(ending_before: nil, expand: nil, limit: nil, starting_after: nil)
-        @ending_before = ending_before
-        @expand = expand
-        @limit = limit
-        @starting_after = starting_after
-      end
-    end
-
-    class CreateParams < Stripe::RequestParams
-      # Events sent to this endpoint will be generated with this Stripe Version instead of your account's default Stripe Version.
-      attr_accessor :api_version
-      # Whether this endpoint should receive events from connected accounts (`true`), or from your account (`false`). Defaults to `false`.
-      attr_accessor :connect
-      # An optional description of what the webhook is used for.
-      attr_accessor :description
-      # The list of events to enable for this endpoint. You may specify `['*']` to enable all events, except those that require explicit selection.
-      attr_accessor :enabled_events
-      # Specifies which fields in the response should be expanded.
-      attr_accessor :expand
-      # Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
-      attr_accessor :metadata
-      # The URL of the webhook endpoint.
-      attr_accessor :url
-
-      def initialize(
-        api_version: nil,
-        connect: nil,
-        description: nil,
-        enabled_events: nil,
-        expand: nil,
-        metadata: nil,
-        url: nil
-      )
-        @api_version = api_version
-        @connect = connect
-        @description = description
-        @enabled_events = enabled_events
-        @expand = expand
-        @metadata = metadata
-        @url = url
-      end
-    end
-
     # A webhook endpoint must have a url and a list of enabled_events. You may optionally specify the Boolean connect parameter. If set to true, then a Connect webhook endpoint that notifies the specified url about events from all connected accounts is created; otherwise an account webhook endpoint that notifies the specified url only about events from your account is created. You can also create webhook endpoints in the [webhooks settings](https://dashboard.stripe.com/account/webhooks) section of the Dashboard.
     def create(params = {}, opts = {})
       request(

data/lib/stripe/services.rb

@@ -14,6 +14,7 @@ require "stripe/services/application_fee_service"
 require "stripe/services/apps/secret_service"
 require "stripe/services/apps_service"
 require "stripe/services/balance_service"
+require "stripe/services/balance_settings_service"
 require "stripe/services/balance_transaction_service"
 require "stripe/services/billing/alert_service"
 require "stripe/services/billing/credit_balance_summary_service"

data/lib/stripe/stripe_client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "stripe/events/unknown_event_notification"
 
 module Stripe
   class StripeClient
@@ -42,7 +43,7 @@ module Stripe
         connect_base: connect_base,
         meter_events_base: meter_events_base,
         client_id: client_id,
-      }.reject { |_k, v| v.nil? }
+      }.compact
 
       config = StripeConfiguration.client_init(config_opts)
       @requestor = APIRequestor.new(config)
@@ -59,7 +60,7 @@ module Stripe
     extend Gem::Deprecate
     deprecate :request, :raw_request, 2024, 9
 
-    def parse_thin_event(payload, sig_header, secret, tolerance: Webhook::DEFAULT_TOLERANCE)
+    def parse_event_notification(payload, sig_header, secret, tolerance: Webhook::DEFAULT_TOLERANCE)
       payload = payload.force_encoding("UTF-8") if payload.respond_to?(:force_encoding)
 
       # v2 events use the same signing mechanism as v1 events
@@ -67,15 +68,17 @@ module Stripe
 
       parsed = JSON.parse(payload, symbolize_names: true)
 
-      Stripe::ThinEvent.new(parsed)
+      cls = Util.event_notification_classes.fetch(parsed[:type], Stripe::Events::UnknownEventNotification)
+
+      cls.new(parsed, self)
     end
 
-    def raw_request(method, url, base_address: :api, params: {}, opts: {})
+    def raw_request(method, url, base_address: :api, params: {}, opts: {}, usage: nil)
       opts = Util.normalize_opts(opts)
       req_opts = RequestOptions.extract_opts_from_hash(opts)
 
       params = params.to_h if params.is_a?(Stripe::RequestParams)
-      resp, = @requestor.send(:execute_request_internal, method, url, base_address, params, req_opts, usage: ["raw_request"])
+      resp, = @requestor.send(:execute_request_internal, method, url, base_address, params, req_opts, usage: usage || ["raw_request"])
 
       @requestor.interpret_response(resp)
     end

data/lib/stripe/stripe_configuration.rb

@@ -45,12 +45,7 @@ module Stripe
       imported_options = USER_CONFIGURABLE_GLOBAL_OPTIONS - StripeClient::CLIENT_OPTIONS
       client_config = StripeConfiguration.setup do |instance|
         imported_options.each do |key|
-          begin
-            instance.public_send("#{key}=", global_config.public_send(key)) if global_config.respond_to?(key)
-          rescue NotImplementedError => e
-            # In Ruby <= 2.5, we can't set write_timeout on Net::HTTP, log an error and continue
-            Util.log_error("Failed to set #{key} on client configuration: #{e}")
-          end
+          instance.public_send("#{key}=", global_config.public_send(key)) if global_config.respond_to?(key)
         end
       end
       client_config.reverse_duplicate_merge(config_opts)

data/lib/stripe/stripe_context.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Stripe
+  # Represents hierarchical context for Stripe API operations.
+  #
+  # This class is immutable - all methods return new instances rather than
+  # modifying the existing instance. It provides utilities for building
+  # context hierarchies and converting to/from string representations.
+  class StripeContext
+    include Comparable
+
+    attr_reader :segments
+
+    # Creates a new StripeContext with the given segments.
+    def initialize(segments = nil)
+      @segments = (segments || []).map(&:to_s).freeze
+    end
+
+    # Parses a context string into a StripeContext instance.
+    def self.parse(context_str)
+      return new if context_str.nil? || context_str.empty?
+
+      new(context_str.split("/"))
+    end
+
+    # Creates a new StripeContext with an additional segment appended.
+    def push(segment)
+      segment_str = segment.to_s.strip
+      raise ArgumentError, "Segment cannot be empty or whitespace" if segment_str.empty?
+
+      new_segments = @segments + [segment_str]
+      self.class.new(new_segments)
+    end
+
+    # Creates a new StripeContext with the last segment removed.
+    # If there are no segments, returns a new empty StripeContext.
+    def pop
+      raise IndexError, "No segments to pop" if @segments.empty?
+
+      new_segments = @segments[0...-1]
+      self.class.new(new_segments)
+    end
+
+    # Converts this context to its string representation.
+    def to_s
+      @segments.join("/")
+    end
+
+    # Checks equality with another StripeContext.
+    def ==(other)
+      other.is_a?(StripeContext) && @segments == other.segments
+    end
+
+    # Alias for == to support eql? method
+    alias eql? ==
+
+    # Returns a human-readable representation for debugging.
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)} segments=#{@segments.inspect}>"
+    end
+
+    # Returns true if the context has no segments.
+    # @return [Boolean] true if empty, false otherwise
+    def empty?
+      @segments.empty?
+    end
+  end
+end