schematichq 1.5.3 → 1.5.4

data/lib/schematic/integrationsapi/client.rb

@@ -41,7 +41,14 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::RunIntegrationResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -100,7 +107,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::ListIntegrationsResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -135,7 +150,14 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::GetIntegrationWebhookUrlResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -170,7 +192,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::InstallIntegrationResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -205,7 +235,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::StartDataImportResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -238,7 +276,14 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::LoadSampleDataSetResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -271,7 +316,14 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::GetStripeSandboxClaimLinkResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -304,7 +356,14 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::GetStripeSandboxKeysResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -339,7 +398,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::ClaimStripeSandboxKeysResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -374,7 +441,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::AssumeStripeInstalledResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -409,7 +484,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::InstallStripeResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -444,7 +527,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::InstallStripeClaimableSandboxResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -477,7 +568,14 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::ListStripeSandboxCountriesResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
 
@@ -512,7 +610,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Integrationsapi::Types::UninstallIntegrationResponse.load(response.body))
         else
           error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(response.body, code: code)
+          error_types = {
+            400 => Schematic::Types::ApiError,
+            401 => Schematic::Types::ApiError,
+            403 => Schematic::Types::ApiError,
+            404 => Schematic::Types::ApiError,
+            500 => Schematic::Types::ApiError
+          }
+          error_body = Schematic::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body)
         end
       end
     end

data/lib/schematic/internal/http/base_request.rb

@@ -28,12 +28,42 @@ module Schematic
           @query.merge(additional_query)
         end
 
+        # @return [Hash] The additional body parameters from request options, keyed by wire-format name.
+        def additional_body_parameters
+          @request_options&.dig(:additional_body_parameters) || @request_options&.dig("additional_body_parameters") || {}
+        end
+
         # Child classes should implement:
         # - encode_headers: Returns the encoded HTTP request headers.
         # - encode_body: Returns the encoded HTTP request body.
 
         private
 
+        # Merges additional_body_parameters from request_options on top of the request body.
+        # Keys are used as-is (API wire-format names) and are normalized to strings so that a
+        # caller-supplied key always overrides the SDK-serialized field with the same name.
+        # When the body is nil the additional parameters become the body, except for GET and HEAD
+        # requests, which are sent without a body (the additional parameters are ignored). Bodies
+        # that are not hash-like (arrays, primitives) are returned unchanged.
+        # @param body [Object, nil] The request body.
+        # @return [Object, nil] The merged request body.
+        def merge_additional_body_parameters(body)
+          additional_body = additional_body_parameters
+          return body if additional_body.nil? || additional_body.empty?
+          return body if body.nil? && bodyless_method?
+
+          additional_body = additional_body.to_h.transform_keys(&:to_s)
+          return additional_body if body.nil?
+          return body if body.is_a?(::Array) || !body.respond_to?(:to_h)
+
+          body.to_h.transform_keys(&:to_s).merge(additional_body)
+        end
+
+        # @return [Boolean] Whether the request method is one that is sent without a body (GET, HEAD).
+        def bodyless_method?
+          %w[GET HEAD].include?(@method.to_s.upcase)
+        end
+
         # Merges additional_headers from request_options into sdk_headers, filtering out
         # any keys that collide with SDK-set or client-protected headers (case-insensitive).
         # @param sdk_headers [Hash] Headers set by the SDK for this request type.

data/lib/schematic/internal/http/raw_client.rb

@@ -47,6 +47,7 @@ module Schematic
           # Resolve auth headers once per request (not per retry) so token-based
           # providers refresh at most once here; static providers are cheap.
           auth_headers = resolve_auth_headers
+          timeout = request_timeout(request)
           attempt = 0
           response = nil
 
@@ -60,12 +61,12 @@ module Schematic
             )
 
             conn = connect(url)
-            conn.open_timeout = @timeout
-            conn.read_timeout = @timeout
-            conn.write_timeout = @timeout
-            conn.continue_timeout = @timeout
+            conn.open_timeout = timeout
+            conn.read_timeout = timeout
+            conn.write_timeout = timeout
+            conn.continue_timeout = timeout
 
-            response = conn.request(http_request)
+            response = wrap_transport_errors { conn.request(http_request) }
 
             break unless should_retry?(response, attempt)
 
@@ -77,6 +78,35 @@ module Schematic
           response
         end
 
+        # Socket-level `Errno` failures. Other `SystemCallError`s, such as file errors raised by a
+        # custom HTTP client, are not connection failures and propagate unchanged.
+        NETWORK_ERRNOS = [
+          Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ECONNABORTED, Errno::EPIPE,
+          Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ENETDOWN, Errno::EHOSTDOWN,
+          Errno::EADDRNOTAVAIL
+        ].freeze
+
+        # Runs a single request attempt, re-raising transport failures as SDK errors so that
+        # rescuing `Errors::ApiError` covers them. The original exception is kept as `cause`.
+        # These failures are not retried: the server may already have processed the request.
+        # @return [Net::HTTPResponse] The HTTP response.
+        def wrap_transport_errors
+          yield
+        rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Errno::ETIMEDOUT => e
+          raise Schematic::Errors::TimeoutError, e.message
+        rescue EOFError, SocketError, OpenSSL::SSL::SSLError, *NETWORK_ERRNOS,
+               Net::ProtocolError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError => e
+          raise Schematic::Errors::ConnectionError, e.message
+        end
+
+        # @param request [Schematic::Internal::Http::BaseRequest] The HTTP request.
+        # @return [Float] The request's `timeout_in_seconds` option, or the client-level timeout.
+        def request_timeout(request)
+          options = request.request_options || {}
+          timeout = options.key?(:timeout_in_seconds) ? options[:timeout_in_seconds] : options["timeout_in_seconds"]
+          (timeout.nil? ? @timeout : timeout).to_f
+        end
+
         # The client-level header names that `additional_headers` must not replace: every default
         # header except the API's global headers, which are overridable per request.
         # @return [Array<Symbol, String>] The protected header names.

data/lib/schematic/internal/iterators/cursor_item_iterator.rb

@@ -10,11 +10,16 @@ module Schematic
       # @param item_field [Symbol] The field in API responses to extract the items to iterate over.
       # @param block [Proc] A block which is responsible for receiving a cursor to use and returning the given page from the API.
       # @return [Schematic::Internal::CursorItemIterator]
-      def initialize(initial_cursor:, cursor_field:, item_field:, &)
+      def initialize(initial_cursor:, cursor_field:, item_field:, &block)
         super()
         @item_field = item_field
-        @page_iterator = CursorPageIterator.new(initial_cursor:, cursor_field:, &)
+        @http_response = nil
+        get_page = track_http_responses(block)
+        @page_iterator = CursorPageIterator.new(initial_cursor:, cursor_field:, &get_page)
+        # Items are read through their own page cursor so that reading `pages` never skips items.
+        @item_pages = CursorPageIterator.new(initial_cursor:, cursor_field:, &get_page)
         @page = nil
+        @item_index = 0
       end
 
       # Returns the CursorPageIterator mediating access to the underlying API.

data/lib/schematic/internal/iterators/cursor_page_iterator.rb

@@ -17,45 +17,99 @@ module Schematic
       #   The block should return a two-element array: [parsed_page, raw_http_response].
       # @return [Schematic::Internal::CursorPageIterator]
       def initialize(initial_cursor:, cursor_field:, &block)
-        @need_initial_load = initial_cursor.nil?
-        @cursor = initial_cursor
+        @initial_cursor = initial_cursor
         @cursor_field = cursor_field
         @get_next_page = block
         @http_response = nil
+        @first_page_requested = false
+        @first_page = nil
+        rewind
       end
 
-      # Iterates over each page returned by the API.
+      # Sends the request for the first page now instead of on the first iteration, so an API error for that page
+      # is raised here. The page is kept, and every loop that starts from the first page reuses it instead of
+      # requesting it again. Does nothing if the first page was already requested.
       #
-      # @param block [Proc] The block which each retrieved page is yielded to.
+      # @return [self]
+      def load_first_page
+        return self if @first_page_requested
+
+        @first_page = fetch_page(@initial_cursor)
+        rewind
+        self
+      end
+
+      # Uses the first page that `other` loaded with `load_first_page`, unless this iterator already sent a request.
+      #
+      # @param other [Schematic::Internal::CursorPageIterator]
       # @return [NilClass]
+      def reuse_first_page(other)
+        return if @first_page_requested || other.first_page.nil?
+
+        @first_page = other.first_page
+        rewind
+      end
+
+      # Iterates over each page returned by the API, starting again from the first page on every call.
+      #
+      # @param block [Proc] The block which each retrieved page is yielded to.
+      # @return [NilClass, Enumerator] An Enumerator when no block is given.
       def each(&block)
+        return enum_for(:each) unless block_given?
+
+        rewind
         while (page = next_page)
           block.call(page)
         end
       end
 
+      # Resets page-by-page iteration (`next_page` / `next?`) to the first page.
+      #
+      # @return [NilClass]
+      def rewind
+        @need_initial_load = @initial_cursor.nil?
+        @cursor = @initial_cursor
+        @at_first_page = true
+        nil
+      end
+
       # Whether another page will be available from the API.
       #
       # @return [Boolean]
       def next?
-        @need_initial_load || !@cursor.nil?
+        (@at_first_page && !@first_page.nil?) || @need_initial_load || !@cursor.nil?
       end
 
       # Retrieves the next page from the API.
       #
       # @return [Object, nil]
       def next_page
-        return if !@need_initial_load && @cursor.nil?
-
-        @need_initial_load = false
-        result = @get_next_page.call(@cursor)
-        if result.is_a?(Array)
-          fetched_page, raw_response = result
-          @http_response = raw_response
+        if @at_first_page && !@first_page.nil?
+          page = @first_page
         else
-          fetched_page = result
+          return if !@need_initial_load && @cursor.nil?
+
+          page = fetch_page(@cursor)
         end
-        @cursor = fetched_page.send(@cursor_field)
+        @at_first_page = false
+        @need_initial_load = false
+        @cursor = page.send(@cursor_field)
+        page
+      end
+
+      protected
+
+      attr_reader :first_page
+
+      private
+
+      def fetch_page(cursor)
+        result = @get_next_page.call(cursor)
+        @first_page_requested = true
+        return result unless result.is_a?(Array)
+
+        fetched_page, raw_response = result
+        @http_response = raw_response
         fetched_page
       end
     end

data/lib/schematic/internal/iterators/item_iterator.rb

@@ -5,20 +5,35 @@ module Schematic
     class ItemIterator
       include Enumerable
 
-      # The raw HTTP response from the most recent page response.
+      # The raw HTTP response from the most recent page request made by this pager or its `pages`.
       # @return [Net::HTTPResponse, nil]
-      def http_response
-        @page_iterator&.http_response
-      end
+      attr_reader :http_response
 
-      # Iterates over each item returned by the API.
+      # Iterates over each item returned by the API, starting again from the first page on every call.
+      # Each loop is independent of other loops and of `next_element`.
       #
       # @param block [Proc] The block which each retrieved item is yielded to.
-      # @return [NilClass]
-      def each(&block)
-        while (item = next_element)
-          block.call(item)
+      # @return [NilClass, Enumerator] An Enumerator when no block is given.
+      def each(&)
+        return enum_for(:each) unless block_given?
+
+        # Each loop reads through its own copy of the page stream, so repeated or nested loops never
+        # share a position with each other or with `next_element`.
+        pass = @item_pages.dup.tap(&:rewind)
+        while (page = pass.next_page)
+          (page.send(@item_field) || []).each(&)
         end
+        nil
+      end
+
+      # Resets manual item-by-item iteration (`next_element` / `next?`) to the first page.
+      #
+      # @return [NilClass]
+      def rewind
+        @item_pages.rewind
+        @page = nil
+        @item_index = 0
+        nil
       end
 
       # Whether another item will be available from the API.
@@ -34,6 +49,19 @@ module Schematic
         any_items_in_cached_page?
       end
 
+      # Sends the request for the first page now instead of on the first iteration, so an API error for that page
+      # is raised here. The page is kept, and every loop (over items or `pages`) that starts from the first page
+      # reuses it instead of requesting it again. Does nothing if this pager already sent a request.
+      #
+      # @return [self]
+      def load_first_page
+        return self if @requested
+
+        @item_pages.load_first_page
+        @page_iterator.reuse_first_page(@item_pages)
+        self
+      end
+
       # Retrieves the next item from the API.
       def next_element
         item = next_item_from_cached_page
@@ -45,20 +73,38 @@ module Schematic
 
       private
 
+      # Wraps the page-fetching block so that `http_response` reflects the most recent request.
+      def track_http_responses(get_page)
+        proc do |*args|
+          result = get_page.call(*args)
+          @requested = true
+          @http_response = result[1] if result.is_a?(Array)
+          result
+        end
+      end
+
+      def cached_page_items
+        return [] unless @page
+
+        @page.send(@item_field) || []
+      end
+
       def next_item_from_cached_page
-        return unless @page
+        items = cached_page_items
+        return if @item_index >= items.length
 
-        @page.send(@item_field).shift
+        item = items[@item_index]
+        @item_index += 1
+        item
       end
 
       def any_items_in_cached_page?
-        return false unless @page
-
-        !@page.send(@item_field).empty?
+        @item_index < cached_page_items.length
       end
 
       def load_next_page
-        @page = @page_iterator.next_page
+        @page = @item_pages.next_page
+        @item_index = 0
       end
     end
   end

data/lib/schematic/internal/iterators/offset_item_iterator.rb

@@ -12,11 +12,16 @@ module Schematic
       # @param block [Proc] A block which is responsible for receiving a page number to use and returning the given page from the API.
       #
       # @return [Schematic::Internal::OffsetItemIterator]
-      def initialize(initial_page:, item_field:, has_next_field:, step:, &)
+      def initialize(initial_page:, item_field:, has_next_field:, step:, &block)
         super()
         @item_field = item_field
-        @page_iterator = OffsetPageIterator.new(initial_page:, item_field:, has_next_field:, step:, &)
+        @http_response = nil
+        get_page = track_http_responses(block)
+        @page_iterator = OffsetPageIterator.new(initial_page:, item_field:, has_next_field:, step:, &get_page)
+        # Items are read through their own page cursor so that reading `pages` never skips items.
+        @item_pages = OffsetPageIterator.new(initial_page:, item_field:, has_next_field:, step:, &get_page)
         @page = nil
+        @item_index = 0
       end
 
       # Returns the OffsetPageIterator that is mediating access to the underlying API.