schematichq 1.5.3 → 1.5.5

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

@@ -12,46 +12,84 @@ module Schematic
       # Instantiates an OffsetPageIterator, an Enumerable class which wraps calls to an offset-based paginated API and yields pages of items from it.
       #
       # @param initial_page [Integer] The initial page to use when iterating, if any.
-      # @param item_field [Symbol] The field to pull the list of items to iterate over.
-      # @param has_next_field [Symbol] The field to pull the boolean of whether a next page exists from, if any.
+      # @param item_field [Symbol, Array<Symbol>] The field (or nested path) to pull the list of items to iterate over.
+      # @param has_next_field [Symbol, Array<Symbol>] The field (or nested path) to pull the boolean of whether a next page exists from, if any.
       # @param step [Boolean] If true, treats the page number as a true offset (i.e. increments the page number by the number of items returned from each call rather than just 1)
       # @param block [Proc] A block which is responsible for receiving a page number to use and returning the given page from the API.
       #   The block should return a two-element array: [parsed_page, raw_http_response].
       # @return [Schematic::Internal::OffsetPageIterator]
       def initialize(initial_page:, item_field:, has_next_field:, step:, &block)
-        @page_number = initial_page || (step ? 0 : 1)
+        @initial_page = initial_page || (step ? 0 : 1)
         @item_field = item_field
         @has_next_field = has_next_field
         @step = step
         @get_next_page = block
+        @http_response = nil
+        @first_page_requested = false
+        @first_page = nil
+        rewind
+      end
 
-        # A cache of whether the API has another page, if it gives us that information...
-        @next_page = nil
-        # ...or the actual next page, preloaded, if it doesn't.
-        @has_next_page = nil
+      # 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 (an empty first page ends those loops without a new request). Does nothing if the first
+      # page was already requested.
+      #
+      # @return [self]
+      def load_first_page
+        return self if @first_page_requested
 
-        @http_response = nil
+        @first_page = fetch_page(@initial_page)
+        rewind
+        self
       end
 
-      # Iterates over each page returned by the API.
+      # Uses the first page that `other` loaded with `load_first_page`, unless this iterator already sent a request.
       #
-      # @param block [Proc] The block which each retrieved page is yielded to.
+      # @param other [Schematic::Internal::OffsetPageIterator]
       # @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
+        @page_number = @initial_page
+        # A cache of whether the API has another page, if it gives us that information...
+        @has_next_page = nil
+        # ...or the actual next page, preloaded, if it doesn't. A first page kept by `load_first_page` is reused.
+        @next_page = @first_page
+        nil
+      end
+
       # Whether another page will be available from the API.
       #
       # @return [Boolean]
       def next?
         return @has_next_page unless @has_next_page.nil?
-        return true if @next_page
+        return true if @next_page && page_has_items?(@next_page)
+        return @has_next_page = false if @next_page
 
         fetched_page = fetch_page(@page_number)
-        fetched_page_items = fetched_page&.send(@item_field)
+        fetched_page_items = read_field(fetched_page, @item_field)
         if fetched_page_items.nil? || fetched_page_items.empty?
           @has_next_page = false
         else
@@ -71,9 +109,9 @@ module Schematic
           this_page = fetch_page(@page_number)
         end
 
-        @has_next_page = this_page&.send(@has_next_field) if @has_next_field
+        @has_next_page = read_field(this_page, @has_next_field) if @has_next_field
 
-        items = this_page.send(@item_field)
+        items = read_field(this_page, @item_field)
         if items.nil? || items.empty?
           @page_number = nil
           return nil
@@ -86,10 +124,20 @@ module Schematic
         this_page
       end
 
+      protected
+
+      attr_reader :first_page
+
       private
 
+      def page_has_items?(page)
+        items = read_field(page, @item_field)
+        !items.nil? && !items.empty?
+      end
+
       def fetch_page(page_number)
         result = @get_next_page.call(page_number)
+        @first_page_requested = true
         if result.is_a?(Array)
           fetched_page, raw_response = result
           @http_response = raw_response
@@ -98,6 +146,15 @@ module Schematic
           result
         end
       end
+
+      # Reads a field from an API response, walking through enclosing objects when the field is nested.
+      #
+      # @param value [Object, nil] The API response.
+      # @param field [Symbol, Array<Symbol>] The field name, or the path of field names for a nested field.
+      # @return [Object, nil]
+      def read_field(value, field)
+        Array(field).reduce(value) { |object, name| object&.send(name) }
+      end
     end
   end
 end

data/lib/schematic/internal/json/request.rb

@@ -31,9 +31,18 @@ module Schematic
           merge_additional_headers(sdk_headers, protected_keys:)
         end
 
-        # @return [String, nil] The encoded HTTP request body.
+        # @return [String, nil] The encoded HTTP request body, including any additional_body_parameters
+        #   from request_options.
         def encode_body
-          @body.nil? ? nil : ::JSON.generate(@body)
+          body = request_body
+          body.nil? ? nil : ::JSON.generate(body)
+        end
+
+        private
+
+        # @return [Object, nil] The request body merged with additional_body_parameters.
+        def request_body
+          merge_additional_body_parameters(@body)
         end
       end
     end

data/lib/schematic/internal/multipart/multipart_request.rb

@@ -31,6 +31,7 @@ module Schematic
         end
 
         # @return [String, nil] The encoded HTTP request body.
+        # Note: additional_body_parameters from request_options are not applied to multipart requests.
         def encode_body
           @body&.encode
         end

data/lib/schematic/internal/types/model.rb

@@ -94,6 +94,18 @@ module Schematic
             define_setter(name)
           end
 
+          # Whether an unknown input key is dropped instead of kept as an extra field: it matches a declared
+          # field's name or API name, ignoring case
+          #
+          # @api private
+          #
+          # @param key [Symbol, String]
+          # @return [Boolean]
+          def drop_extra_key?(key)
+            key = key.to_s
+            fields.any? { |name, field| name.to_s.casecmp?(key) || field.api_name.to_s.casecmp?(key) }
+          end
+
           # @api private
           private def define_accessor(name)
             method_name = name.to_sym
@@ -108,6 +120,7 @@ module Schematic
             method_name = :"#{name}="
 
             define_method(method_name) do |val|
+              @explicit_fields[name] = true
               @data[name] = val
             end
           end
@@ -137,6 +150,7 @@ module Schematic
         # @return [self]
         def initialize(values = {})
           @data = {}
+          @explicit_fields = {}
 
           values = Utils.symbolize_keys(values.dup)
 
@@ -145,6 +159,7 @@ module Schematic
             [field.api_name.to_sym, field_name].uniq.each do |key|
               next unless values.key?(key)
 
+              @explicit_fields[field_name] = true
               candidate = values.delete(key)
               value = candidate if value.nil?
             end
@@ -160,8 +175,12 @@ module Schematic
             @data[field_name] = Utils.coerce(field.type, field_value)
           end
 
-          # Any remaining values in the input become extra fields
+          # Any remaining values in the input become extra fields, except keys that match a declared field
+          # case-insensitively (e.g. `VALUE` next to `value`): re-emitting those would let a case-insensitive
+          # JSON decoder downstream read the extra key instead of the declared field.
           values.each do |name, value|
+            next if self.class.drop_extra_key?(name)
+
             self.class.add_extra_field_definition(name: name, type: value.class)
 
             @data[name.to_sym] = value
@@ -173,14 +192,15 @@ module Schematic
             # If there is a value present in the data, use that value
             # If there is a `nil` value present in the data, and it is optional but NOT nullable, exclude key altogether
             # If there is a `nil` value present in the data, and it is optional and nullable, use the nil value
+            # only when it was explicitly provided; an omitted optional field is excluded
 
             value = @data[name]
 
-            next if value.nil? && field.optional && !field.nullable
+            next if value.nil? && field.optional && (!field.nullable || !@explicit_fields&.key?(name))
 
             if value.is_a?(::Array)
-              value = value.map { |item| item.respond_to?(:to_h) ? item.to_h : item }
-            elsif value.respond_to?(:to_h)
+              value = value.map { |item| !item.nil? && item.respond_to?(:to_h) ? item.to_h : item }
+            elsif !value.nil? && value.respond_to?(:to_h)
               value = value.to_h
             end
 

data/lib/schematic/internal/types/utils.rb

@@ -60,11 +60,18 @@ module Schematic
             case value
             when Numeric, String, Time
               return value.to_i
+            when Symbol
+              # JSON object keys are parsed as symbols, so numeric map keys arrive as e.g. :"1"
+              parsed = Integer(value.to_s, 10, exception: false)
+              return parsed unless parsed.nil?
             end
           in ->(t) { t <= Float }
             case value
             when Numeric, Time, String
               return value.to_f
+            when Symbol
+              parsed = Float(value.to_s, exception: false)
+              return parsed unless parsed.nil?
             end
           in ->(t) { t <= Model }
             case value

data/lib/schematic/licenses/client.rb

@@ -59,7 +59,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Licenses::Types::ListLicensesResponse.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
 
@@ -94,7 +102,14 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Licenses::Types::GetSingleLicenseResponse.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
 
@@ -147,7 +162,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Licenses::Types::CountLicensesResponse.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/planbundle/client.rb

@@ -53,7 +53,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planbundle::Types::CreateCustomPlanBundleResponse.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
 
@@ -96,7 +104,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planbundle::Types::CreatePlanBundleResponse.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
 
@@ -144,7 +160,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planbundle::Types::UpdatePlanBundleResponse.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/plangroups/client.rb

@@ -45,7 +45,14 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Plangroups::Types::GetPlanGroupResponse.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
 
@@ -108,7 +115,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Plangroups::Types::CreatePlanGroupResponse.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
 
@@ -177,7 +192,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Plangroups::Types::UpdatePlanGroupResponse.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/planmigrations/client.rb

@@ -59,7 +59,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::ListCompanyMigrationsResponse.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
 
@@ -94,7 +102,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::RetryCompanyMigrationResponse.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
 
@@ -147,7 +163,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::CountCompanyMigrationsResponse.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
 
@@ -203,7 +227,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::ListMigrationsResponse.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
 
@@ -243,7 +275,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::CreateMigrationResponse.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
 
@@ -278,7 +318,14 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::GetMigrationResponse.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
 
@@ -313,7 +360,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::CancelMigrationResponse.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
 
@@ -353,7 +408,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::CompleteMigrationNowResponse.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
 
@@ -396,7 +459,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::RetryMigrationResponse.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
 
@@ -452,7 +523,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::CountMigrationsResponse.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
 
@@ -491,7 +570,15 @@ module Schematic
           (response.body.to_s.empty? ? nil : Schematic::Planmigrations::Types::PreviewMigrationResponse.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