kombo 1.1.4 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7e7c1bb39f82aa036bef045d24460655cdea148819ba24c2293a67a189ed53d
-  data.tar.gz: f39d1aa4f5cf90de344b460a76d9ff93eb4e0e2619793646d74a3febd70f3db8
+  metadata.gz: ecc70a18f1f0ede106494e469843ef6b5a1a3bbba20f6caabcc56459e1008bfd
+  data.tar.gz: d96ae6b802d34c16b38de65b3c728a544c32acdd30659fb3a9d5e3814a93af9d
 SHA512:
-  metadata.gz: b4f25f9957ed638c3a84fd251859a9588f18946b6a421f13553f34f834e024a2b9cdf34ba90da76a4e1a58332c9a248a20c6066749b9655be669f02be73d8749
-  data.tar.gz: 127f18762867242b07f79b6ea774915d3b15289644f1f5ac6c39573fe4adc6268345af42d53a4cdd1020fe03525b4bb5d6813f65e3770bfeaaaa42400235ece2
+  metadata.gz: 36be43c2528d5f0f4e5ac176097242b70da170455587c3667525cd513dffe2870dcf408a7876341d24ba6d4f734700539a3b49164abd1c435f3526b28c267b96
+  data.tar.gz: a476a560970318bd60d2eb08dffcf13b9e97c4639beac61fc264624b1ef6c5227d0b76cd2139f58c17887439914c7be74fe6027a4ac4cefeee5f578c07ea9e2c

data/lib/crystalline/enum.rbi

@@ -0,0 +1,17 @@
+# typed: true
+
+module Crystalline
+  module Enum
+    mixes_in_class_methods(ClassMethods)
+
+    module ClassMethods
+      def enums(&blk); end
+      def open!; end
+      def open?; end
+      def deserialize(val); end
+    end
+
+    def serialize; end
+    def known?; end
+  end
+end

data/lib/crystalline/metadata_fields.rb

@@ -37,19 +37,30 @@ module Crystalline
       def unmarshal_single(field_type, value, format_metadata = nil)
         decoder = format_metadata.fetch(:decoder, nil)
 
-        if field_type.instance_of?(Class) && field_type.include?(::Crystalline::MetadataFields)
+        # Delegate complex Crystalline types to unmarshal_json
+        if field_type.is_a?(Crystalline::DiscriminatedUnion) ||
+           Crystalline::Utils.arr?(field_type) ||
+           Crystalline::Utils.hash?(field_type) ||
+           Crystalline::Utils.union?(field_type)
+          return Crystalline.unmarshal_json(value, field_type)
+        elsif field_type.instance_of?(Class) && field_type.include?(::Crystalline::MetadataFields)
           return field_type.from_dict(value)
         elsif field_type.to_s == 'Date'
           return Date.parse(value)
         elsif field_type.to_s == 'DateTime'
           return DateTime.parse(value)
         elsif field_type.to_s == 'Object'
-          # rubocop:disable Lint/SuppressedException
-          begin
-            value = JSON.parse(value)
-          rescue TypeError, JSON::ParserError
+          if value.is_a?(::String)
+            trimmed = value.lstrip
+            if trimmed.start_with?('{') || trimmed.start_with?('[')
+              # rubocop:disable Lint/SuppressedException
+              begin
+                value = JSON.parse(value)
+              rescue TypeError, JSON::ParserError
+              end
+              # rubocop:enable Lint/SuppressedException
+            end
           end
-          # rubocop:enable Lint/SuppressedException
           return value
         elsif field_type.to_s == 'Float'
           return value.to_f
@@ -65,12 +76,27 @@ module Crystalline
       def from_dict(d)
         to_build = {}
 
+        # Collect lookup keys for regular fields so we can identify additional properties later
+        known_keys = {}
+        additional_props_fields = []
         fields.each do |field|
+          format_metadata = field.metadata.fetch(:format_json, {})
+          if format_metadata.fetch(:additional_properties, false)
+            additional_props_fields << field
+          else
+            lookup = format_metadata.fetch(:letter_case, nil).call
+            known_keys[lookup] = true
+          end
+        end
+
+        # Process regular fields
+        (fields - additional_props_fields).each do |field|
           key = field.name
           format_metadata = field.metadata.fetch(:format_json, {})
+          field_type = field.type
+
           lookup = format_metadata.fetch(:letter_case, nil).call
           value = d[lookup]
-          field_type = field.type
           if ::Crystalline::Utils.nilable? field_type
             if value == 'null'
               to_build[key] = nil
@@ -78,13 +104,15 @@ module Crystalline
             end
             field_type = ::Crystalline::Utils.nilable_of(field_type)
           end
-          
+
           # If field is not nilable, and the value is not in the dict, raise a KeyError
           raise KeyError, "key #{lookup} not found in hash" if value.nil? && !::Crystalline::Utils.nilable?(field.type)
           # If field is nilable, and the value is not in the dict, just move to the next field
           next if value.nil?
 
-          if Crystalline::Utils.arr? field_type
+          if field_type.is_a?(Crystalline::DiscriminatedUnion)
+            to_build[key] = field_type.parse(value)
+          elsif Crystalline::Utils.arr? field_type
             inner_type = Crystalline::Utils.arr_of(field_type)
             unmarshalled_array = value.map { |f| unmarshal_single(inner_type, f, format_metadata) }
             to_build[key] = unmarshalled_array
@@ -112,17 +140,21 @@ module Crystalline
               union_types = Crystalline::Utils.get_union_types(field_type)
               union_types = union_types.sort_by { |klass| Crystalline.non_nilable_attr_count(klass) }
 
-              union_types.each do |union_type|
-                begin
-                  to_build[key] = Crystalline.unmarshal_json(value, union_type)
-                rescue TypeError
-                  next
-                rescue NoMethodError
-                  next
-                rescue KeyError
-                  next
+              if Crystalline.union_strategy == :populated_fields
+                to_build[key] = Crystalline.unmarshal_union_populated_fields(value, union_types)
+              else
+                union_types.each do |union_type|
+                  begin
+                    to_build[key] = Crystalline.unmarshal_json(value, union_type)
+                  rescue TypeError
+                    next
+                  rescue NoMethodError
+                    next
+                  rescue KeyError
+                    next
+                  end
+                  break
                 end
-                break
               end
             end
           elsif field_type.instance_of?(Class) && field_type.include?(::Crystalline::MetadataFields)
@@ -131,6 +163,32 @@ module Crystalline
             to_build[key] = unmarshal_single(field_type, value, format_metadata)
           end
         end
+
+        # Process additional properties fields: collect remaining keys from the dict
+        additional_props_fields.each do |field|
+          key = field.name
+          format_metadata = field.metadata.fetch(:format_json, {})
+          field_type = field.type
+
+          remaining = d.reject { |k, _| known_keys.key?(k) }
+          if remaining.empty?
+            next if ::Crystalline::Utils.nilable?(field.type)
+
+            raise KeyError, 'no additional properties found in hash'
+          end
+
+          inner_field_type = field_type
+          inner_field_type = ::Crystalline::Utils.nilable_of(inner_field_type) if ::Crystalline::Utils.nilable?(inner_field_type)
+          if Crystalline::Utils.hash?(inner_field_type)
+            val_type = Crystalline::Utils.hash_of(inner_field_type)
+            # rubocop:disable Style/HashTransformValues
+            to_build[key] = remaining.map { |k, v| [k, unmarshal_single(val_type, v, format_metadata)] }.to_h
+            # rubocop:enable Style/HashTransformValues
+          else
+            to_build[key] = remaining
+          end
+        end
+
         new(**to_build)
       end
     end
@@ -172,6 +230,8 @@ module Crystalline
       fields.sort_by(&:name).each do |field|
         format_json_meta = field.metadata[:format_json]
         required = !format_json_meta.nil? && format_json_meta.include?(:required)
+        is_additional_props = !format_json_meta.nil? && format_json_meta.fetch(:additional_properties, false)
+
         if !format_json_meta.nil? && format_json_meta.include?(:letter_case)
           key = format_json_meta[:letter_case].call(field.name)
         else
@@ -182,10 +242,13 @@ module Crystalline
         next if f.nil? && !required
         result[key] = nil if f.nil? && required
 
-        if f.is_a? Array
+        # Flatten additional properties into the parent object
+        if is_additional_props && f.is_a?(::Hash)
+          f.each { |k, v| result[k] = marshal_single(v) }
+        elsif f.is_a? ::Array
           result[key] = f.map { |o| marshal_single(o) }
-        elsif f.is_a? Hash
-          result[key] = f.map { |k, v| [k, marshal_single(v)] }
+        elsif f.is_a? ::Hash
+          result[key] = f.transform_values { |v| marshal_single(v) }
         else
           result[key] = marshal_single(f)
         end

data/lib/crystalline/module.rb

@@ -4,11 +4,16 @@
 # frozen_string_literal: true
 
 module Crystalline
+  @union_strategy = :left_to_right
+
+  class << self
+    attr_accessor :union_strategy
+  end
 
   def self.to_dict(complex)
-    if complex.is_a? Array
+    if complex.is_a? ::Array
       complex.map { |v| Crystalline.to_dict(v) }
-    elsif complex.is_a? Hash
+    elsif complex.is_a? ::Hash
       complex.transform_values { |v| Crystalline.to_dict(v) }
     elsif complex.respond_to?(:class) && complex.class.include?(::Crystalline::MetadataFields)
       complex.to_dict
@@ -29,21 +34,18 @@ module Crystalline
     if Crystalline::Utils.nilable? type
       type = Crystalline::Utils.nilable_of type
     end
-    if type.instance_of?(Class) && type.include?(::Crystalline::MetadataFields)
+    if type.is_a?(Crystalline::DiscriminatedUnion)
+      type.parse(data)
+    elsif type.instance_of?(Class) && type.include?(::Crystalline::MetadataFields)
       type.from_dict(data)
     elsif Crystalline::Utils.union? type
       union_types = Crystalline::Utils.get_union_types(type)
       union_types = union_types.sort_by { |klass| Crystalline.non_nilable_attr_count(klass) }
 
-      union_types.each do |union_type|
-        unmarshalled_val = Crystalline.unmarshal_json(data, union_type)
-        return unmarshalled_val
-      rescue TypeError
-        next
-      rescue NoMethodError
-        next
-      rescue KeyError
-        next
+      if Crystalline.union_strategy == :populated_fields
+        Crystalline.unmarshal_union_populated_fields(data, union_types)
+      else
+        Crystalline.unmarshal_union_left_to_right(data, union_types)
       end
     elsif Crystalline::Utils.arr? type
       data.map { |v| Crystalline.unmarshal_json(v, Crystalline::Utils.arr_of(type)) }
@@ -55,6 +57,8 @@ module Crystalline
       Crystalline::Utils.to_boolean(data)
     elsif type.is_a?(Class) && type < T::Enum
       type.deserialize(data)
+    elsif type.is_a?(Class) && type.respond_to?(:enums) && type.respond_to?(:deserialize)
+      type.deserialize(data)
     else
       data
     end
@@ -64,7 +68,7 @@ module Crystalline
     if val.class.respond_to? :enums
       val.serialize
     elsif val.is_a? DateTime
-      val.strftime('%Y-%m-%dT%H:%M:%S.%NZ')
+      val.strftime('%Y-%m-%dT%H:%M:%S.%NZ').sub(/(\.\d*[1-9])0+Z\z/, '\1Z').sub(/\.0+Z\z/, 'Z')
     elsif val.nil?
       nil
     elsif primitives
@@ -74,6 +78,88 @@ module Crystalline
     end
   end
 
+  def self.unmarshal_union_left_to_right(data, union_types)
+    union_types.each do |union_type|
+      return Crystalline.unmarshal_json(data, union_type)
+    rescue TypeError
+      next
+    rescue NoMethodError
+      next
+    rescue KeyError
+      next
+    end
+    nil
+  end
+
+  def self.unmarshal_union_populated_fields(data, union_types)
+    best_value = nil
+    best_matched = -1
+    best_inexact = 0
+    best_unmatched = 0
+
+    union_types.each do |union_type|
+      value = Crystalline.unmarshal_json(data, union_type)
+      matched, inexact, unmatched = count_matched_fields(value, data)
+
+      if best_value.nil? ||
+         matched > best_matched ||
+         (matched == best_matched && inexact < best_inexact) ||
+         (matched == best_matched && inexact == best_inexact && unmatched < best_unmatched)
+        best_value = value
+        best_matched = matched
+        best_inexact = inexact
+        best_unmatched = unmatched
+      end
+    rescue TypeError
+      next
+    rescue NoMethodError
+      next
+    rescue KeyError
+      next
+    end
+    best_value
+  end
+
+  def self.count_matched_fields(value, raw_data)
+    matched = 0
+    inexact = 0
+    unmatched = 0
+
+    if value.is_a?(Crystalline::Unknown)
+      return [0, 0, 0]
+    elsif value.class.include?(::Crystalline::MetadataFields)
+      value.fields.each do |field|
+        format_metadata = field.metadata.fetch(:format_json, {})
+        lookup = format_metadata.fetch(:letter_case, nil)&.call
+        field_val = value.send(field.name)
+
+        if raw_data.is_a?(::Hash) && lookup && raw_data.key?(lookup)
+          if field_val.class.include?(::Crystalline::MetadataFields) && raw_data[lookup].is_a?(::Hash)
+            nested_matched, nested_inexact, nested_unmatched = count_matched_fields(field_val, raw_data[lookup])
+            matched += nested_matched
+            inexact += nested_inexact
+            unmatched += nested_unmatched
+          else
+            matched += 1
+            if field_val.respond_to?(:known?) && !field_val.known?
+              inexact += 1
+            end
+          end
+        elsif !::Crystalline::Utils.nilable?(field.type)
+          unmatched += 1
+        end
+      end
+    elsif value.is_a?(::Array)
+      matched = value.length
+    elsif value.is_a?(::Hash)
+      matched = value.length
+    else
+      matched = 1
+    end
+
+    [matched, inexact, unmatched]
+  end
+
   def self.non_nilable_attr_count(klass)
     # somewhat sane sort ordering for Union deserialization.
     # All Crystalline objects return the number of non-nilable fields

data/lib/crystalline/types.rb

@@ -14,7 +14,7 @@ module Crystalline
 
   class Hash
     attr_accessor :key_type, :value_type
-    
+
     def initialize(key_type, value_type)
       @key_type = key_type
       @value_type = value_type
@@ -23,7 +23,7 @@ module Crystalline
 
   class Union
     attr_accessor :types
-    
+
     def initialize(*types)
       @types = types
     end
@@ -31,7 +31,7 @@ module Crystalline
 
   class Nilable
     attr_accessor :inner_type
-    
+
     def initialize(inner_type)
       @inner_type = inner_type
     end
@@ -40,6 +40,58 @@ module Crystalline
   class Boolean
   end
 
+  # Wraps an unrecognized payload from an open discriminated union.
+  # Produced when the discriminator value is missing, unknown, or schema validation fails.
+  class Unknown
+    attr_reader :raw
+
+    def initialize(raw:)
+      @raw = raw
+    end
+
+    def unknown?
+      true
+    end
+  end
+
+  # Forward-compatible discriminated union parser.
+  # Known discriminator values are deserialized to their mapped types.
+  # Unknown or invalid payloads are captured as Crystalline::Unknown.
+  class DiscriminatedUnion
+    attr_reader :discriminator, :variants
+
+    def initialize(discriminator, variants)
+      @discriminator = discriminator
+      @variants = variants
+    end
+
+    def parse(payload)
+      unless payload.is_a?(::Hash)
+        return Unknown.new(raw: payload)
+      end
+
+      disc_value = payload[@discriminator]
+      unless disc_value.is_a?(::String)
+        return Unknown.new(raw: payload)
+      end
+
+      variant_type = @variants[disc_value]
+      unless variant_type
+        return Unknown.new(raw: payload)
+      end
+
+      begin
+        Crystalline.unmarshal_json(payload, variant_type)
+      rescue StandardError
+        Unknown.new(raw: payload)
+      end
+    end
+  end
+
+  def self.unknown?(value)
+    value.is_a?(Unknown)
+  end
+
   module Enum
     def self.included(base)
       base.extend(ClassMethods)
@@ -67,9 +119,19 @@ module Crystalline
         end
       end
 
+      def open!
+        @open = true
+      end
+
+      def open?
+        @open == true
+      end
+
       def deserialize(val)
         if @mapping.include? val
           @mapping[val]
+        elsif open?
+          new(val)
         else
           raise "Invalid value for enum: #{val}"
         end
@@ -79,5 +141,30 @@ module Crystalline
     def serialize
       @val
     end
+
+    def to_s
+      serialize.to_s
+    end
+
+    def inspect
+      "#<#{self.class} #{serialize.inspect}>"
+    end
+
+    def known?
+      self.class.instance_variable_get(:@mapping)&.value?(self) || false
+    end
+
+    def ==(other)
+      other = other.serialize if other.is_a?(self.class)
+      @val == other
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def hash
+      @val.hash
+    end
   end
 end

data/lib/kombo/assessment.rb

@@ -40,11 +40,13 @@ module Kombo
     end
 
 
-    sig { params(integration_id: T.nilable(::String), timeout_ms: T.nilable(Integer)).returns(Models::Operations::GetAssessmentPackagesResponse) }
-    def get_packages(integration_id: nil, timeout_ms: nil)
+
+
+    sig { params(integration_id: T.nilable(::String), timeout_ms: T.nilable(Integer), http_headers: T.nilable(T::Hash[T.any(String, Symbol), String])).returns(Models::Operations::GetAssessmentPackagesResponse) }
+    def get_packages(integration_id: nil, timeout_ms: nil, http_headers: nil)
       # get_packages - Get packages
       # Get all available assessment and background check packages for an integration.
-      # 
+      #
       # This is mainly intended for debugging. As you always need to submit the full list of available packages when using ["set packages"](/assessment/v1/put-packages), there shouldn't ever be a need to call this endpoint in production.
       request = Models::Operations::GetAssessmentPackagesRequest.new(
         integration_id: integration_id
@@ -82,6 +84,9 @@ module Kombo
           req.headers.merge!(headers)
           req.options.timeout = timeout unless timeout.nil?
           Utils.configure_request_security(req, security)
+          http_headers&.each do |key, value|
+            req.headers[key.to_s] = value
+          end
 
           @sdk_configuration.hooks.before_request(
             hook_ctx: SDKHooks::BeforeRequestHookContext.new(
@@ -157,17 +162,17 @@ module Kombo
     end
 
 
-    sig { params(body: Models::Shared::PutAssessmentPackagesRequestBody, integration_id: T.nilable(::String), timeout_ms: T.nilable(Integer)).returns(Models::Operations::PutAssessmentPackagesResponse) }
-    def set_packages(body:, integration_id: nil, timeout_ms: nil)
+    sig { params(body: Models::Shared::PutAssessmentPackagesRequestBody, integration_id: T.nilable(::String), timeout_ms: T.nilable(Integer), http_headers: T.nilable(T::Hash[T.any(String, Symbol), String])).returns(Models::Operations::PutAssessmentPackagesResponse) }
+    def set_packages(body:, integration_id: nil, timeout_ms: nil, http_headers: nil)
       # set_packages - Set packages
       # Set packages
-      # 
+      #
       # Replaces the list of available assessment and or background check packages.
-      # 
+      #
       # Packages that have been previously submitted through this endpoint but aren't included again will be marked as deleted.
-      # 
+      #
       # ### Example Request Body
-      # 
+      #
       # ```json
       # {
       #   "packages": [
@@ -199,7 +204,7 @@ module Kombo
       headers['content-type'] = req_content_type
       raise StandardError, 'request body is required' if data.nil? && form.nil?
 
-      if form
+      if form && !form.empty?
         body = Utils.encode_form(form)
       elsif Utils.match_content_type(req_content_type, 'application/x-www-form-urlencoded')
         body = URI.encode_www_form(T.cast(data, T::Hash[Symbol, Object]))
@@ -235,6 +240,9 @@ module Kombo
           req.headers.merge!(headers)
           req.options.timeout = timeout unless timeout.nil?
           Utils.configure_request_security(req, security)
+          http_headers&.each do |key, value|
+            req.headers[key.to_s] = value
+          end
 
           @sdk_configuration.hooks.before_request(
             hook_ctx: SDKHooks::BeforeRequestHookContext.new(
@@ -310,8 +318,8 @@ module Kombo
     end
 
 
-    sig { params(integration_id: T.nilable(::String), cursor: T.nilable(::String), page_size: T.nilable(::Integer), ids: T.nilable(T::Array[::String]), statuses: T.nilable(T::Array[::String]), created_after: T.nilable(::DateTime), timeout_ms: T.nilable(Integer)).returns(Models::Operations::GetAssessmentOrdersResponse) }
-    def get_assessment_orders(integration_id: nil, cursor: nil, page_size: nil, ids: nil, statuses: nil, created_after: nil, timeout_ms: nil)
+    sig { params(integration_id: T.nilable(::String), cursor: T.nilable(::String), page_size: T.nilable(::Integer), ids: T.nilable(T::Array[::String]), statuses: T.nilable(T::Array[::String]), created_after: T.nilable(::DateTime), timeout_ms: T.nilable(Integer), http_headers: T.nilable(T::Hash[T.any(String, Symbol), String])).returns(Models::Operations::GetAssessmentOrdersResponse) }
+    def get_assessment_orders(integration_id: nil, cursor: nil, page_size: nil, ids: nil, statuses: nil, created_after: nil, timeout_ms: nil, http_headers: nil)
       # get_assessment_orders - Get orders
       # Get all assessment and background check orders of an integration.
       request = Models::Operations::GetAssessmentOrdersRequest.new(
@@ -357,6 +365,9 @@ module Kombo
           req.options.timeout = timeout unless timeout.nil?
           req.params = query_params
           Utils.configure_request_security(req, security)
+          http_headers&.each do |key, value|
+            req.headers[key.to_s] = value
+          end
 
           @sdk_configuration.hooks.before_request(
             hook_ctx: SDKHooks::BeforeRequestHookContext.new(
@@ -422,12 +433,13 @@ module Kombo
             end
 
             sdk.get_assessment_orders(
-              integration_id: integration_id,
+              integration_id: request.integration_id,
               cursor: next_cursor,
-              page_size: page_size,
-              ids: ids,
-              statuses: statuses,
-              created_after: created_after
+              page_size: request.page_size,
+              ids: request.ids,
+              statuses: request.statuses,
+              created_after: request.created_after,
+              http_headers: http_headers
             )
           end
 
@@ -455,13 +467,13 @@ module Kombo
     end
 
 
-    sig { params(body: Models::Shared::PutAssessmentOrdersAssessmentOrderIdResultRequestBody, assessment_order_id: ::String, integration_id: T.nilable(::String), timeout_ms: T.nilable(Integer)).returns(Models::Operations::PutAssessmentOrdersAssessmentOrderIdResultResponse) }
-    def update_order_result(body:, assessment_order_id:, integration_id: nil, timeout_ms: nil)
+    sig { params(body: Models::Shared::PutAssessmentOrdersAssessmentOrderIdResultRequestBody, assessment_order_id: ::String, integration_id: T.nilable(::String), timeout_ms: T.nilable(Integer), http_headers: T.nilable(T::Hash[T.any(String, Symbol), String])).returns(Models::Operations::PutAssessmentOrdersAssessmentOrderIdResultResponse) }
+    def update_order_result(body:, assessment_order_id:, integration_id: nil, timeout_ms: nil, http_headers: nil)
       # update_order_result - Update order result
       # Updates an assessment or a background check order result.
-      # 
+      #
       # ### Example Request Body
-      # 
+      #
       # ```json
       # {
       #   "status": "COMPLETED",
@@ -515,7 +527,7 @@ module Kombo
       headers['content-type'] = req_content_type
       raise StandardError, 'request body is required' if data.nil? && form.nil?
 
-      if form
+      if form && !form.empty?
         body = Utils.encode_form(form)
       elsif Utils.match_content_type(req_content_type, 'application/x-www-form-urlencoded')
         body = URI.encode_www_form(T.cast(data, T::Hash[Symbol, Object]))
@@ -551,6 +563,9 @@ module Kombo
           req.headers.merge!(headers)
           req.options.timeout = timeout unless timeout.nil?
           Utils.configure_request_security(req, security)
+          http_headers&.each do |key, value|
+            req.headers[key.to_s] = value
+          end
 
           @sdk_configuration.hooks.before_request(
             hook_ctx: SDKHooks::BeforeRequestHookContext.new(
@@ -624,5 +639,5 @@ module Kombo
         end
       end
     end
-  end
+end
 end