finch-api 0.1.0.pre.alpha.18 → 0.1.0.pre.alpha.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eddfa1529c8cfb3c7461b7553fc9ccebd1818115e88bd4a5a733dbcffad435d4
-  data.tar.gz: 37306b10b432110b7b3ce09d4cd245b97b1dd16fe467b050e78a5a2101e18839
+  metadata.gz: a22fefaabfd30029cb7ba2fd611db321dedf41081213b17d39b19defc545c720
+  data.tar.gz: 8667b02bf5c30e86fa594cb2772dc8296a08de01452a21c1512f51416fd7c197
 SHA512:
-  metadata.gz: 40f142561b69c398322f65338f567b6d7ed4e5c059ee067aaeddb2566be1ef3b1f19d9eac8bb635540cea61f1e1e63815020af5b3dc7ca9a920f8202f42d0a6f
-  data.tar.gz: 6cf31655554a967db22163906ae8ea254457761f706ea5cdb5d1dbaf920bd4e55c72e4606525bbac868ec3e7b5b38c6c6135b48727f4e0ff717f9acad778bab9
+  metadata.gz: 4b54fc4f9e12bfa3b9fca170644621323c6e4d1dc924ea349b5387a2e17dd68e0c262cddeb1e5f150fd8929430c62fa623b052e7eef3eb44d126775bba908723
+  data.tar.gz: 29ba1b68aee378643888164f0ccfeea541381e6861a718d2a9e2537143253f6a8ffb6fc885aa68d86845229d4dc9fe1d7969b3425826ed63c52eb246b52e9456

data/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.1.0-alpha.20 (2025-06-18)
+
+Full Changelog: [v0.1.0-alpha.19...v0.1.0-alpha.20](https://github.com/Finch-API/finch-api-ruby/compare/v0.1.0-alpha.19...v0.1.0-alpha.20)
+
+### Features
+
+* **api:** api update ([6a3cc47](https://github.com/Finch-API/finch-api-ruby/commit/6a3cc47713d3f52d84da946c1f86c328692a71f1))
+* **api:** api update ([055b260](https://github.com/Finch-API/finch-api-ruby/commit/055b260f9607ea1c408510bf19c86390ba515b48))
+* **api:** api update ([6e46c62](https://github.com/Finch-API/finch-api-ruby/commit/6e46c62b78b34d3944136bea9decd9254b9d7b2c))
+* **api:** api update ([68d04c3](https://github.com/Finch-API/finch-api-ruby/commit/68d04c3e38f076254375ef4e1ea24383d7ff7aa2))
+
+
+### Bug Fixes
+
+* `to_sorbet_type` should not return branded types ([2819280](https://github.com/Finch-API/finch-api-ruby/commit/281928010fa852dd399354a4561191120e85ad00))
+* **client:** fix PayStatementResponse body ([bb0bb58](https://github.com/Finch-API/finch-api-ruby/commit/bb0bb581ffc994714895363e21f461e2ec82676e))
+* **client:** manual fix ([3774286](https://github.com/Finch-API/finch-api-ruby/commit/3774286f68227085e6f54396290e3de7569bba0d))
+* correctly instantiate sorbet type aliases for enums and unions ([9a84b92](https://github.com/Finch-API/finch-api-ruby/commit/9a84b92df48e001ee28989703cbe8bdd9f461528))
+* default content-type for text in multi-part formdata uploads should be text/plain ([2288848](https://github.com/Finch-API/finch-api-ruby/commit/2288848990739f298069c86ad90d915c1bd88c60))
+* issue where we cannot mutate arrays on base model derivatives ([c4c0158](https://github.com/Finch-API/finch-api-ruby/commit/c4c01587e16d76f1c6b3f5a48414000954dc4805))
+* prevent rubocop from mangling `===` to `is_a?` check ([6301929](https://github.com/Finch-API/finch-api-ruby/commit/6301929d697ae1c006446a12e6c67046e83ef132))
+* sorbet types for enums, and make tapioca detection ignore `tapioca dsl` ([4aaba62](https://github.com/Finch-API/finch-api-ruby/commit/4aaba6261e6c92833ab6e46acb2e2652da843be9))
+
+
+### Chores
+
+* **ci:** enable for pull requests ([77fdc63](https://github.com/Finch-API/finch-api-ruby/commit/77fdc63fa78dd6356baf44cc3770902bfb83311b))
+* **ci:** link to correct github repo ([6479e22](https://github.com/Finch-API/finch-api-ruby/commit/6479e2217a712d55aac84da1041a88efcbd4f1f2))
+* **docs:** grammar improvements ([0c55f26](https://github.com/Finch-API/finch-api-ruby/commit/0c55f26abe131663cfe8e739b95154172d967085))
+* force utf-8 locale via `RUBYOPT` when formatting ([2f00817](https://github.com/Finch-API/finch-api-ruby/commit/2f008175f0a18dc01a0c2b900c2e692f77b3a0ac))
+* **internal:** version bump ([2b40219](https://github.com/Finch-API/finch-api-ruby/commit/2b4021961b248f64cb9c5564b4199d0c840593fd))
+* refine Yard and Sorbet types and ensure linting is turned on for examples ([e0eb636](https://github.com/Finch-API/finch-api-ruby/commit/e0eb63695b803e35dd9e35a57cd0769a60db7bc7))
+* **tests:** skip endpoints with basic auth ([529b41e](https://github.com/Finch-API/finch-api-ruby/commit/529b41ea3cf67b553d85e36a256cc5d6c4b13800))
+* use fully qualified names for yard annotations and rbs aliases ([98866d5](https://github.com/Finch-API/finch-api-ruby/commit/98866d5133c2afb76b141045f1361705f9bac94a))
+* use sorbet union aliases where available ([37cc1c2](https://github.com/Finch-API/finch-api-ruby/commit/37cc1c27968a448e7bfef8527a0f3105b476de09))
+* whitespaces ([16ff9b3](https://github.com/Finch-API/finch-api-ruby/commit/16ff9b32a68eecb17c5719b354de64fe788bedd4))
+
+## 0.1.0-alpha.19 (2025-05-16)
+
+Full Changelog: [v0.1.0-alpha.18...v0.1.0-alpha.19](https://github.com/Finch-API/finch-api-ruby/compare/v0.1.0-alpha.18...v0.1.0-alpha.19)
+
+### Features
+
+* **api:** api update ([e7b5270](https://github.com/Finch-API/finch-api-ruby/commit/e7b527009b74ba9ea5a0c681d12627617971ce31))
+
+
+### Chores
+
+* **internal:** version bump ([4c65aec](https://github.com/Finch-API/finch-api-ruby/commit/4c65aecc566acd9f72c296c003b12bd36acbd8ca))
+
 ## 0.1.0-alpha.18 (2025-05-16)
 
 Full Changelog: [v0.1.0-alpha.17...v0.1.0-alpha.18](https://github.com/Finch-API/finch-api-ruby/compare/v0.1.0-alpha.17...v0.1.0-alpha.18)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "finch-api", "~> 0.1.0.pre.alpha.18"
+gem "finch-api", "~> 0.1.0.pre.alpha.20"
 ```
 
 <!-- x-release-please-end -->
@@ -170,7 +170,7 @@ puts(page[:my_undocumented_property])
 
 #### Undocumented request params
 
-If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request as seen in examples above.
+If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.
 
 #### Undocumented endpoints
 
@@ -188,7 +188,7 @@ response = client.request(
 
 ### Concurrency & connection pooling
 
-The `FinchAPI::Client` instances are threadsafe, but only are fork-safe when there are no in-flight HTTP requests.
+The `FinchAPI::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
 
 Each instance of `FinchAPI::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.
 
@@ -238,7 +238,7 @@ finch.hris.benefits.create(
   # …
 )
 
-# Literal values is also permissible:
+# Literal values are also permissible:
 finch.hris.benefits.create(
   frequency: :one_time,
   # …

data/SECURITY.md

@@ -16,11 +16,11 @@ before making any information public.
 ## Reporting Non-SDK Related Security Issues
 
 If you encounter security issues that are not directly related to SDKs but pertain to the services
-or products provided by Finch please follow the respective company's security reporting guidelines.
+or products provided by Finch, please follow the respective company's security reporting guidelines.
 
 ### Finch Terms and Policies
 
-Please contact founders@tryfinch.com for any questions or concerns regarding security of our services.
+Please contact founders@tryfinch.com for any questions or concerns regarding the security of our services.
 
 ---
 

data/lib/finch_api/errors.rb

@@ -9,6 +9,28 @@ module FinchAPI
     end
 
     class ConversionError < FinchAPI::Errors::Error
+      # @return [StandardError, nil]
+      def cause = @cause.nil? ? super : @cause
+
+      # @api private
+      #
+      # @param on [Class<StandardError>]
+      # @param method [Symbol]
+      # @param target [Object]
+      # @param value [Object]
+      # @param cause [StandardError, nil]
+      def initialize(on:, method:, target:, value:, cause: nil)
+        cls = on.name.split("::").last
+
+        message = [
+          "Failed to parse #{cls}.#{method} from #{value.class} to #{target.inspect}.",
+          "To get the unparsed API response, use #{cls}[#{method.inspect}].",
+          cause && "Cause: #{cause.message}"
+        ].filter(&:itself).join(" ")
+
+        @cause = cause
+        super(message)
+      end
     end
 
     class APIError < FinchAPI::Errors::Error

data/lib/finch_api/internal/individuals_page.rb

@@ -19,7 +19,7 @@ module FinchAPI
       # @return [Array<generic<Elem>>, nil]
       attr_accessor :individuals
 
-      # @return [FinchAPI::Paging]
+      # @return [FinchAPI::Models::Paging]
       attr_accessor :paging
 
       # @return [Boolean]

data/lib/finch_api/internal/page.rb

@@ -19,7 +19,7 @@ module FinchAPI
       # @return [Array<generic<Elem>>, nil]
       attr_accessor :data
 
-      # @return [FinchAPI::Paging]
+      # @return [FinchAPI::Models::Paging]
       attr_accessor :paging
 
       # @return [Boolean]

data/lib/finch_api/internal/type/array_of.rb

@@ -12,6 +12,7 @@ module FinchAPI
       # Array of items of a given type.
       class ArrayOf
         include FinchAPI::Internal::Type::Converter
+        include FinchAPI::Internal::Util::SorbetRuntimeSupport
 
         private_class_method :new
 
@@ -61,10 +62,14 @@ module FinchAPI
         #
         # @param state [Hash{Symbol=>Object}] .
         #
-        #   @option state [Boolean, :strong] :strictness
+        #   @option state [Boolean] :translate_names
+        #
+        #   @option state [Boolean] :strictness
         #
         #   @option state [Hash{Symbol=>Object}] :exactness
         #
+        #   @option state [Class<StandardError>] :error
+        #
         #   @option state [Integer] :branched
         #
         # @return [Array<Object>, Object]
@@ -73,6 +78,7 @@ module FinchAPI
 
           unless value.is_a?(Array)
             exactness[:no] += 1
+            state[:error] = TypeError.new("#{value.class} can't be coerced into #{Array}")
             return value
           end
 
@@ -110,6 +116,13 @@ module FinchAPI
           end
         end
 
+        # @api private
+        #
+        # @return [Object]
+        def to_sorbet_type
+          T::Array[FinchAPI::Internal::Util::SorbetRuntimeSupport.to_sorbet_type(item_type)]
+        end
+
         # @api private
         #
         # @return [generic<Elem>]

data/lib/finch_api/internal/type/base_model.rb

@@ -60,7 +60,7 @@ module FinchAPI
                 [FinchAPI::Internal::Type::Converter.type_info(type_info), type_info]
               end
 
-            setter = "#{name_sym}="
+            setter = :"#{name_sym}="
             api_name = info.fetch(:api_name, name_sym)
             nilable = info.fetch(:nil?, false)
             const = if required && !nilable
@@ -84,30 +84,61 @@ module FinchAPI
                 type_fn: type_fn
               }
 
-            define_method(setter) { @data.store(name_sym, _1) }
+            define_method(setter) do |value|
+              target = type_fn.call
+              state = FinchAPI::Internal::Type::Converter.new_coerce_state(translate_names: false)
+              coerced = FinchAPI::Internal::Type::Converter.coerce(target, value, state: state)
+              status = @coerced.store(name_sym, state.fetch(:error) || true)
+              stored =
+                case [target, status]
+                in [FinchAPI::Internal::Type::Converter | Symbol, true]
+                  coerced
+                else
+                  value
+                end
+              @data.store(name_sym, stored)
+            end
 
+            # rubocop:disable Style/CaseEquality
+            # rubocop:disable Metrics/BlockLength
             define_method(name_sym) do
               target = type_fn.call
-              value = @data.fetch(name_sym) { const == FinchAPI::Internal::OMIT ? nil : const }
-              state = {strictness: :strong, exactness: {yes: 0, no: 0, maybe: 0}, branched: 0}
-              if (nilable || !required) && value.nil?
-                nil
-              else
-                FinchAPI::Internal::Type::Converter.coerce(
-                  target,
-                  value,
-                  state: state
+
+              case @coerced[name_sym]
+              in true | false if FinchAPI::Internal::Type::Converter === target
+                @data.fetch(name_sym)
+              in ::StandardError => e
+                raise FinchAPI::Errors::ConversionError.new(
+                  on: self.class,
+                  method: __method__,
+                  target: target,
+                  value: @data.fetch(name_sym),
+                  cause: e
                 )
+              else
+                Kernel.then do
+                  value = @data.fetch(name_sym) { const == FinchAPI::Internal::OMIT ? nil : const }
+                  state = FinchAPI::Internal::Type::Converter.new_coerce_state(translate_names: false)
+                  if (nilable || !required) && value.nil?
+                    nil
+                  else
+                    FinchAPI::Internal::Type::Converter.coerce(
+                      target, value, state: state
+                    )
+                  end
+                rescue StandardError => e
+                  raise FinchAPI::Errors::ConversionError.new(
+                    on: self.class,
+                    method: __method__,
+                    target: target,
+                    value: value,
+                    cause: e
+                  )
+                end
               end
-            rescue StandardError => e
-              cls = self.class.name.split("::").last
-              message = [
-                "Failed to parse #{cls}.#{__method__} from #{value.class} to #{target.inspect}.",
-                "To get the unparsed API response, use #{cls}[#{__method__.inspect}].",
-                "Cause: #{e.message}"
-              ].join(" ")
-              raise FinchAPI::Errors::ConversionError.new(message)
             end
+            # rubocop:enable Metrics/BlockLength
+            # rubocop:enable Style/CaseEquality
           end
 
           # @api private
@@ -207,23 +238,28 @@ module FinchAPI
           #
           # @param state [Hash{Symbol=>Object}] .
           #
-          #   @option state [Boolean, :strong] :strictness
+          #   @option state [Boolean] :translate_names
+          #
+          #   @option state [Boolean] :strictness
           #
           #   @option state [Hash{Symbol=>Object}] :exactness
           #
+          #   @option state [Class<StandardError>] :error
+          #
           #   @option state [Integer] :branched
           #
           # @return [self, Object]
           def coerce(value, state:)
             exactness = state.fetch(:exactness)
 
-            if value.is_a?(self.class)
+            if value.is_a?(self)
               exactness[:yes] += 1
               return value
             end
 
             unless (val = FinchAPI::Internal::Util.coerce_hash(value)).is_a?(Hash)
               exactness[:no] += 1
+              state[:error] = TypeError.new("#{value.class} can't be coerced into #{Hash}")
               return value
             end
             exactness[:yes] += 1
@@ -231,13 +267,15 @@ module FinchAPI
             keys = val.keys.to_set
             instance = new
             data = instance.to_h
+            status = instance.instance_variable_get(:@coerced)
 
             # rubocop:disable Metrics/BlockLength
             fields.each do |name, field|
               mode, required, target = field.fetch_values(:mode, :required, :type)
               api_name, nilable, const = field.fetch_values(:api_name, :nilable, :const)
+              src_name = state.fetch(:translate_names) ? api_name : name
 
-              unless val.key?(api_name)
+              unless val.key?(src_name)
                 if required && mode != :dump && const == FinchAPI::Internal::OMIT
                   exactness[nilable ? :maybe : :no] += 1
                 else
@@ -246,9 +284,10 @@ module FinchAPI
                 next
               end
 
-              item = val.fetch(api_name)
-              keys.delete(api_name)
+              item = val.fetch(src_name)
+              keys.delete(src_name)
 
+              state[:error] = nil
               converted =
                 if item.nil? && (nilable || !required)
                   exactness[nilable ? :yes : :maybe] += 1
@@ -262,6 +301,8 @@ module FinchAPI
                     item
                   end
                 end
+
+              status.store(name, state.fetch(:error) || true)
               data.store(name, converted)
             end
             # rubocop:enable Metrics/BlockLength
@@ -311,6 +352,13 @@ module FinchAPI
 
             acc
           end
+
+          # @api private
+          #
+          # @return [Object]
+          def to_sorbet_type
+            self
+          end
         end
 
         class << self
@@ -430,7 +478,18 @@ module FinchAPI
         # Create a new instance of a model.
         #
         # @param data [Hash{Symbol=>Object}, self]
-        def initialize(data = {}) = (@data = FinchAPI::Internal::Util.coerce_hash!(data).to_h)
+        def initialize(data = {})
+          @data = {}
+          @coerced = {}
+          FinchAPI::Internal::Util.coerce_hash!(data).each do
+            if self.class.known_fields.key?(_1)
+              public_send(:"#{_1}=", _2)
+            else
+              @data.store(_1, _2)
+              @coerced.store(_1, false)
+            end
+          end
+        end
 
         class << self
           # @api private

data/lib/finch_api/internal/type/boolean.rb

@@ -10,6 +10,7 @@ module FinchAPI
       # Ruby has no Boolean class; this is something for models to refer to.
       class Boolean
         extend FinchAPI::Internal::Type::Converter
+        extend FinchAPI::Internal::Util::SorbetRuntimeSupport
 
         private_class_method :new
 
@@ -30,14 +31,20 @@ module FinchAPI
         class << self
           # @api private
           #
+          # Coerce value to Boolean if possible, otherwise return the original value.
+          #
           # @param value [Boolean, Object]
           #
           # @param state [Hash{Symbol=>Object}] .
           #
-          #   @option state [Boolean, :strong] :strictness
+          #   @option state [Boolean] :translate_names
+          #
+          #   @option state [Boolean] :strictness
           #
           #   @option state [Hash{Symbol=>Object}] :exactness
           #
+          #   @option state [Class<StandardError>] :error
+          #
           #   @option state [Integer] :branched
           #
           # @return [Boolean, Object]
@@ -56,6 +63,13 @@ module FinchAPI
           #     @option state [Boolean] :can_retry
           #
           #   @return [Boolean, Object]
+
+          # @api private
+          #
+          # @return [Object]
+          def to_sorbet_type
+            T::Boolean
+          end
         end
       end
     end

data/lib/finch_api/internal/type/converter.rb

@@ -15,10 +15,14 @@ module FinchAPI
         #
         # @param state [Hash{Symbol=>Object}] .
         #
-        #   @option state [Boolean, :strong] :strictness
+        #   @option state [Boolean] :translate_names
+        #
+        #   @option state [Boolean] :strictness
         #
         #   @option state [Hash{Symbol=>Object}] :exactness
         #
+        #   @option state [Class<StandardError>] :error
+        #
         #   @option state [Integer] :branched
         #
         # @return [Object]
@@ -94,6 +98,21 @@ module FinchAPI
             end
           end
 
+          # @api private
+          #
+          # @param translate_names [Boolean]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def new_coerce_state(translate_names: true)
+            {
+              translate_names: translate_names,
+              strictness: true,
+              exactness: {yes: 0, no: 0, maybe: 0},
+              error: nil,
+              branched: 0
+            }
+          end
+
           # @api private
           #
           # Based on `target`, transform `value` into `target`, to the extent possible:
@@ -110,14 +129,11 @@ module FinchAPI
           #
           # @param value [Object]
           #
-          # @param state [Hash{Symbol=>Object}] The `strictness` is one of `true`, `false`, or `:strong`. This informs the
-          # coercion strategy when we have to decide between multiple possible conversion
-          # targets:
+          # @param state [Hash{Symbol=>Object}] The `strictness` is one of `true`, `false`. This informs the coercion strategy
+          # when we have to decide between multiple possible conversion targets:
           #
           # - `true`: the conversion must be exact, with minimum coercion.
           # - `false`: the conversion can be approximate, with some coercion.
-          # - `:strong`: the conversion must be exact, with no coercion, and raise an error
-          #   if not possible.
           #
           # The `exactness` is `Hash` with keys being one of `yes`, `no`, or `maybe`. For
           # any given conversion attempt, the exactness will be updated based on how closely
@@ -130,21 +146,20 @@ module FinchAPI
           #
           # See implementation below for more details.
           #
-          #   @option state [Boolean, :strong] :strictness
+          #   @option state [Boolean] :translate_names
+          #
+          #   @option state [Boolean] :strictness
           #
           #   @option state [Hash{Symbol=>Object}] :exactness
           #
+          #   @option state [Class<StandardError>] :error
+          #
           #   @option state [Integer] :branched
           #
           # @return [Object]
-          def coerce(
-            target,
-            value,
-            state: {strictness: true, exactness: {yes: 0, no: 0, maybe: 0}, branched: 0}
-          )
-            # rubocop:disable Lint/SuppressedException
+          def coerce(target, value, state: FinchAPI::Internal::Type::Converter.new_coerce_state)
             # rubocop:disable Metrics/BlockNesting
-            strictness, exactness = state.fetch_values(:strictness, :exactness)
+            exactness = state.fetch(:exactness)
 
             case target
             in FinchAPI::Internal::Type::Converter
@@ -160,29 +175,26 @@ module FinchAPI
                 exactness[value.nil? ? :yes : :maybe] += 1
                 return nil
               in -> { _1 <= Integer }
-                if value.is_a?(Integer)
+                case value
+                in Integer
                   exactness[:yes] += 1
                   return value
-                elsif strictness == :strong && Integer(value, exception: false) != value
-                  message = "no implicit conversion of #{value.class} into #{target.inspect}"
-                  raise value.is_a?(Numeric) ? ArgumentError.new(message) : TypeError.new(message)
                 else
                   Kernel.then do
                     return Integer(value).tap { exactness[:maybe] += 1 }
-                  rescue ArgumentError, TypeError
+                  rescue ArgumentError, TypeError => e
+                    state[:error] = e
                   end
                 end
               in -> { _1 <= Float }
                 if value.is_a?(Numeric)
                   exactness[:yes] += 1
                   return Float(value)
-                elsif strictness == :strong
-                  message = "no implicit conversion of #{value.class} into #{target.inspect}"
-                  raise TypeError.new(message)
                 else
                   Kernel.then do
                     return Float(value).tap { exactness[:maybe] += 1 }
-                  rescue ArgumentError, TypeError
+                  rescue ArgumentError, TypeError => e
+                    state[:error] = e
                   end
                 end
               in -> { _1 <= String }
@@ -194,16 +206,13 @@ module FinchAPI
                   exactness[:yes] += 1
                   return value.string
                 else
-                  if strictness == :strong
-                    message = "no implicit conversion of #{value.class} into #{target.inspect}"
-                    raise TypeError.new(message)
-                  end
+                  state[:error] = TypeError.new("#{value.class} can't be coerced into #{String}")
                 end
               in -> { _1 <= Date || _1 <= Time }
                 Kernel.then do
                   return target.parse(value).tap { exactness[:yes] += 1 }
                 rescue ArgumentError, TypeError => e
-                  raise e if strictness == :strong
+                  state[:error] = e
                 end
               in -> { _1 <= StringIO } if value.is_a?(String)
                 exactness[:yes] += 1
@@ -221,10 +230,8 @@ module FinchAPI
                   return value
                 end
               else
-                if strictness == :strong
-                  message = "cannot convert non-matching #{value.class} into #{target.inspect}"
-                  raise ArgumentError.new(message)
-                end
+                message = "cannot convert non-matching #{value.class} into #{target.inspect}"
+                state[:error] = ArgumentError.new(message)
               end
             else
             end
@@ -232,7 +239,6 @@ module FinchAPI
             exactness[:no] += 1
             value
             # rubocop:enable Metrics/BlockNesting
-            # rubocop:enable Lint/SuppressedException
           end
 
           # @api private
@@ -277,8 +283,10 @@ module FinchAPI
         define_sorbet_constant!(:CoerceState) do
           T.type_alias do
             {
-              strictness: T.any(T::Boolean, Symbol),
+              translate_names: T::Boolean,
+              strictness: T::Boolean,
               exactness: {yes: Integer, no: Integer, maybe: Integer},
+              error: T::Class[StandardError],
               branched: Integer
             }
           end

data/lib/finch_api/internal/type/enum.rb

@@ -81,10 +81,14 @@ module FinchAPI
         #
         # @param state [Hash{Symbol=>Object}] .
         #
-        #   @option state [Boolean, :strong] :strictness
+        #   @option state [Boolean] :translate_names
+        #
+        #   @option state [Boolean] :strictness
         #
         #   @option state [Hash{Symbol=>Object}] :exactness
         #
+        #   @option state [Class<StandardError>] :error
+        #
         #   @option state [Integer] :branched
         #
         # @return [Symbol, Object]
@@ -95,8 +99,12 @@ module FinchAPI
           if values.include?(val)
             exactness[:yes] += 1
             val
+          elsif values.first&.class == val.class
+            exactness[:maybe] += 1
+            value
           else
-            exactness[values.first&.class == val.class ? :maybe : :no] += 1
+            exactness[:no] += 1
+            state[:error] = TypeError.new("#{value.class} can't be coerced into #{self}")
             value
           end
         end
@@ -112,6 +120,21 @@ module FinchAPI
         #
         #   @return [Symbol, Object]
 
+        # @api private
+        #
+        # @return [Object]
+        def to_sorbet_type
+          types = values.map { FinchAPI::Internal::Util::SorbetRuntimeSupport.to_sorbet_type(_1) }.uniq
+          case types
+          in []
+            T.noreturn
+          in [type]
+            type
+          else
+            T.any(*types)
+          end
+        end
+
         # @api private
         #
         # @param depth [Integer]