finch-api 0.1.0.pre.alpha.3 → 0.1.0.pre.alpha.4

data/lib/finch-api/individuals_page.rb

@@ -49,7 +49,7 @@ module FinchAPI
 
       case page_data
       in {paging: Hash | nil => paging}
-        @paging = FinchAPI::Models::Paging.coerce(paging)
+        @paging = FinchAPI::Converter.coerce(FinchAPI::Models::Paging, paging)
       else
       end
     end

data/lib/finch-api/models/introspection.rb

@@ -253,6 +253,16 @@ module FinchAPI
       end
 
       class ConnectionStatus < FinchAPI::BaseModel
+        # @!attribute [r] last_successful_sync
+        #   The datetime when the connection was last successfully synced.
+        #
+        #   @return [Time, nil]
+        optional :last_successful_sync, Time
+
+        # @!parse
+        #   # @return [Time]
+        #   attr_writer :last_successful_sync
+
         # @!attribute [r] message
         #
         #   @return [String, nil]
@@ -272,10 +282,11 @@ module FinchAPI
         #   attr_writer :status
 
         # @!parse
+        #   # @param last_successful_sync [Time]
         #   # @param message [String]
         #   # @param status [Symbol, FinchAPI::Models::ConnectionStatusType]
         #   #
-        #   def initialize(message: nil, status: nil, **) = super
+        #   def initialize(last_successful_sync: nil, message: nil, status: nil, **) = super
 
         # def initialize: (Hash | FinchAPI::BaseModel) -> void
       end

data/lib/finch-api/page.rb

@@ -49,7 +49,7 @@ module FinchAPI
 
       case page_data
       in {paging: Hash | nil => paging}
-        @paging = FinchAPI::Models::Paging.coerce(paging)
+        @paging = FinchAPI::Converter.coerce(FinchAPI::Models::Paging, paging)
       else
       end
     end

data/lib/finch-api/single_page.rb

@@ -37,7 +37,7 @@ module FinchAPI
 
       case page_data
       in Array
-        replace(page_data.map { model.coerce(_1) })
+        replace(page_data.map { FinchAPI::Converter.coerce(model, _1) })
       else
       end
     end

data/lib/finch-api/util.rb

@@ -75,7 +75,7 @@ module FinchAPI
       def coerce_boolean(input)
         case input.is_a?(String) ? input.downcase : input
         in Numeric
-          !input.zero?
+          input.nonzero?
         in "true"
           true
         in "false"
@@ -165,14 +165,12 @@ module FinchAPI
       private def deep_merge_lr(lhs, rhs, concat: false)
         case [lhs, rhs, concat]
         in [Hash, Hash, _]
-          # rubocop:disable Style/YodaCondition
-          rhs_cleaned = rhs.reject { |_, val| OMIT == val }
+          rhs_cleaned = rhs.reject { _2 == FinchAPI::Util::OMIT }
           lhs
-            .reject { |key, _| OMIT == rhs[key] }
+            .reject { |key, _| rhs[key] == FinchAPI::Util::OMIT }
             .merge(rhs_cleaned) do |_, old_val, new_val|
               deep_merge_lr(old_val, new_val, concat: concat)
             end
-          # rubocop:enable Style/YodaCondition
         in [Array, Array, true]
           lhs.concat(rhs)
         else

data/lib/finch-api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FinchAPI
-  VERSION = "0.1.0-alpha.3"
+  VERSION = "0.1.0-alpha.4"
 end

data/lib/finch-api.rb

@@ -36,7 +36,6 @@ require "connection_pool"
 # Package files.
 require_relative "finch-api/version"
 require_relative "finch-api/util"
-require_relative "finch-api/extern"
 require_relative "finch-api/base_model"
 require_relative "finch-api/base_page"
 require_relative "finch-api/request_options"

data/rbi/lib/finch-api/base_client.rbi

@@ -84,7 +84,7 @@ module FinchAPI
     end
 
     # @api private
-    sig { returns(T.anything) }
+    sig { returns(FinchAPI::PooledNetRequester) }
     attr_accessor :requester
 
     # @api private

data/rbi/lib/finch-api/base_model.rbi

@@ -5,9 +5,18 @@ module FinchAPI
   module Converter
     Input = T.type_alias { T.any(FinchAPI::Converter, T::Class[T.anything]) }
 
+    State =
+      T.type_alias do
+        {
+          strictness: T.any(T::Boolean, Symbol),
+          exactness: {yes: Integer, no: Integer, maybe: Integer},
+          branched: Integer
+        }
+      end
+
     # @api private
-    sig { overridable.params(value: T.anything).returns(T.anything) }
-    def coerce(value)
+    sig { overridable.params(value: T.anything, state: FinchAPI::Converter::State).returns(T.anything) }
+    def coerce(value, state:)
     end
 
     # @api private
@@ -15,15 +24,6 @@ module FinchAPI
     def dump(value)
     end
 
-    # @api private
-    sig do
-      overridable
-        .params(value: T.anything)
-        .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
-    end
-    def try_strict_coerce(value)
-    end
-
     class << self
       # @api private
       sig do
@@ -38,7 +38,7 @@ module FinchAPI
             FinchAPI::Converter::Input
           )
         )
-          .returns(T.proc.returns(T.anything).void)
+          .returns(T.proc.returns(T.anything))
       end
       def self.type_info(spec)
       end
@@ -51,28 +51,43 @@ module FinchAPI
       #   2. if it's possible and safe to convert the given `value` to `target`, then the
       #      converted value
       #   3. otherwise, the given `value` unaltered
-      sig { params(target: FinchAPI::Converter::Input, value: T.anything).returns(T.anything) }
-      def self.coerce(target, value)
+      #
+      #   The coercion process is subject to improvement between minor release versions.
+      #   See https://docs.pydantic.dev/latest/concepts/unions/#smart-mode
+      sig do
+        params(target: FinchAPI::Converter::Input, value: T.anything, state: FinchAPI::Converter::State)
+          .returns(T.anything)
+      end
+      def self.coerce(
+        target,
+        value,
+        # The `strictness` is one of `true`, `false`, or `:strong`. 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
+        #   the value recursively matches the target type:
+        #
+        #   - `yes`: the value can be converted to the target type with minimum coercion.
+        #   - `maybe`: the value can be converted to the target type with some reasonable
+        #     coercion.
+        #   - `no`: the value cannot be converted to the target type.
+        #
+        #   See implementation below for more details.
+        state: {strictness: true, exactness: {yes: 0, no: 0, maybe: 0}, branched: 0}
+      )
       end
 
       # @api private
       sig { params(target: FinchAPI::Converter::Input, value: T.anything).returns(T.anything) }
       def self.dump(target, value)
       end
-
-      # @api private
-      #
-      # The underlying algorithm for computing maximal compatibility is subject to
-      #   future improvements.
-      #
-      #   Similar to `#.coerce`, used to determine the best union variant to decode into.
-      #
-      #   1. determine if strict-ish coercion is possible
-      #   2. return either result of successful coercion or if loose coercion is possible
-      #   3. return a score for recursively tallied count for fields that can be coerced
-      sig { params(target: FinchAPI::Converter::Input, value: T.anything).returns(T.anything) }
-      def self.try_strict_coerce(target, value)
-      end
     end
   end
 
@@ -95,23 +110,16 @@ module FinchAPI
 
     class << self
       # @api private
-      sig(:final) { override.params(value: T.anything).returns(T.anything) }
-      def coerce(value)
+      sig(:final) do
+        override.params(value: T.anything, state: FinchAPI::Converter::State).returns(T.anything)
+      end
+      def coerce(value, state:)
       end
 
       # @api private
       sig(:final) { override.params(value: T.anything).returns(T.anything) }
       def dump(value)
       end
-
-      # @api private
-      sig(:final) do
-        override
-          .params(value: T.anything)
-          .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
-      end
-      def try_strict_coerce(value)
-      end
     end
   end
 
@@ -135,9 +143,11 @@ module FinchAPI
     class << self
       # @api private
       sig(:final) do
-        override.params(value: T.any(T::Boolean, T.anything)).returns(T.any(T::Boolean, T.anything))
+        override
+          .params(value: T.any(T::Boolean, T.anything), state: FinchAPI::Converter::State)
+          .returns(T.any(T::Boolean, T.anything))
       end
-      def coerce(value)
+      def coerce(value, state:)
       end
 
       # @api private
@@ -146,15 +156,6 @@ module FinchAPI
       end
       def dump(value)
       end
-
-      # @api private
-      sig(:final) do
-        override
-          .params(value: T.anything)
-          .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
-      end
-      def try_strict_coerce(value)
-      end
     end
   end
 
@@ -194,23 +195,21 @@ module FinchAPI
     end
 
     # @api private
-    sig { override.params(value: T.any(String, Symbol, T.anything)).returns(T.any(Symbol, T.anything)) }
-    def coerce(value)
+    #
+    # Unlike with primitives, `Enum` additionally validates that the value is a member
+    #   of the enum.
+    sig do
+      override
+        .params(value: T.any(String, Symbol, T.anything), state: FinchAPI::Converter::State)
+        .returns(T.any(Symbol, T.anything))
+    end
+    def coerce(value, state:)
     end
 
     # @api private
     sig { override.params(value: T.any(Symbol, T.anything)).returns(T.any(Symbol, T.anything)) }
     def dump(value)
     end
-
-    # @api private
-    sig do
-      override
-        .params(value: T.anything)
-        .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
-    end
-    def try_strict_coerce(value)
-    end
   end
 
   # @api private
@@ -264,23 +263,14 @@ module FinchAPI
     end
 
     # @api private
-    sig { override.params(value: T.anything).returns(T.anything) }
-    def coerce(value)
+    sig { override.params(value: T.anything, state: FinchAPI::Converter::State).returns(T.anything) }
+    def coerce(value, state:)
     end
 
     # @api private
     sig { override.params(value: T.anything).returns(T.anything) }
     def dump(value)
     end
-
-    # @api private
-    sig do
-      override
-        .params(value: T.anything)
-        .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
-    end
-    def try_strict_coerce(value)
-    end
   end
 
   # @api private
@@ -317,10 +307,10 @@ module FinchAPI
     # @api private
     sig(:final) do
       override
-        .params(value: T.any(T::Enumerable[T.anything], T.anything))
+        .params(value: T.any(T::Enumerable[T.anything], T.anything), state: FinchAPI::Converter::State)
         .returns(T.any(T::Array[T.anything], T.anything))
     end
-    def coerce(value)
+    def coerce(value, state:)
     end
 
     # @api private
@@ -333,17 +323,13 @@ module FinchAPI
     end
 
     # @api private
-    sig(:final) do
-      override
-        .params(value: T.anything)
-        .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
-    end
-    def try_strict_coerce(value)
+    sig(:final) { returns(T.anything) }
+    protected def item_type
     end
 
     # @api private
-    sig(:final) { returns(T.anything) }
-    protected def item_type
+    sig(:final) { returns(T::Boolean) }
+    protected def nilable?
     end
 
     # @api private
@@ -396,10 +382,10 @@ module FinchAPI
     # @api private
     sig(:final) do
       override
-        .params(value: T.any(T::Hash[T.anything, T.anything], T.anything))
+        .params(value: T.any(T::Hash[T.anything, T.anything], T.anything), state: FinchAPI::Converter::State)
         .returns(T.any(FinchAPI::Util::AnyHash, T.anything))
     end
-    def coerce(value)
+    def coerce(value, state:)
     end
 
     # @api private
@@ -412,17 +398,13 @@ module FinchAPI
     end
 
     # @api private
-    sig(:final) do
-      override
-        .params(value: T.anything)
-        .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
-    end
-    def try_strict_coerce(value)
+    sig(:final) { returns(T.anything) }
+    protected def item_type
     end
 
     # @api private
-    sig(:final) { returns(T.anything) }
-    protected def item_type
+    sig(:final) { returns(T::Boolean) }
+    protected def nilable?
     end
 
     # @api private
@@ -446,7 +428,7 @@ module FinchAPI
 
     abstract!
 
-    KnownFieldShape = T.type_alias { {mode: T.nilable(Symbol), required: T::Boolean} }
+    KnownFieldShape = T.type_alias { {mode: T.nilable(Symbol), required: T::Boolean, nilable: T::Boolean} }
 
     class << self
       # @api private
@@ -465,11 +447,6 @@ module FinchAPI
       def known_fields
       end
 
-      # @api private
-      sig { returns(T::Hash[Symbol, Symbol]) }
-      def reverse_map
-      end
-
       # @api private
       sig do
         returns(
@@ -480,11 +457,6 @@ module FinchAPI
       def fields
       end
 
-      # @api private
-      sig { returns(T::Hash[Symbol, T.proc.returns(T::Class[T.anything])]) }
-      def defaults
-      end
-
       # @api private
       sig do
         params(
@@ -554,6 +526,10 @@ module FinchAPI
       sig { params(blk: T.proc.void).void }
       private def response_only(&blk)
       end
+
+      sig { params(other: T.anything).returns(T::Boolean) }
+      def ==(other)
+      end
     end
 
     sig { params(other: T.anything).returns(T::Boolean) }
@@ -564,10 +540,13 @@ module FinchAPI
       # @api private
       sig do
         override
-          .params(value: T.any(FinchAPI::BaseModel, T::Hash[T.anything, T.anything], T.anything))
+          .params(
+            value: T.any(FinchAPI::BaseModel, T::Hash[T.anything, T.anything], T.anything),
+            state: FinchAPI::Converter::State
+          )
           .returns(T.any(T.attached_class, T.anything))
       end
-      def coerce(value)
+      def coerce(value, state:)
       end
 
       # @api private
@@ -578,15 +557,6 @@ module FinchAPI
       end
       def dump(value)
       end
-
-      # @api private
-      sig do
-        override
-          .params(value: T.anything)
-          .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
-      end
-      def try_strict_coerce(value)
-      end
     end
 
     # Returns the raw value associated with the given key, if found. Otherwise, nil is
@@ -632,10 +602,6 @@ module FinchAPI
     def self.new(data = {})
     end
 
-    sig { returns(String) }
-    def to_s
-    end
-
     sig { returns(String) }
     def inspect
     end

data/rbi/lib/finch-api/models/introspection.rbi

@@ -265,6 +265,13 @@ module FinchAPI
       end
 
       class ConnectionStatus < FinchAPI::BaseModel
+        # The datetime when the connection was last successfully synced.
+        sig { returns(T.nilable(Time)) }
+        attr_reader :last_successful_sync
+
+        sig { params(last_successful_sync: Time).void }
+        attr_writer :last_successful_sync
+
         sig { returns(T.nilable(String)) }
         attr_reader :message
 
@@ -278,12 +285,22 @@ module FinchAPI
         attr_writer :status
 
         sig do
-          params(message: String, status: FinchAPI::Models::ConnectionStatusType::OrSymbol).returns(T.attached_class)
+          params(
+            last_successful_sync: Time,
+            message: String,
+            status: FinchAPI::Models::ConnectionStatusType::OrSymbol
+          )
+            .returns(T.attached_class)
         end
-        def self.new(message: nil, status: nil)
+        def self.new(last_successful_sync: nil, message: nil, status: nil)
         end
 
-        sig { override.returns({message: String, status: FinchAPI::Models::ConnectionStatusType::TaggedSymbol}) }
+        sig do
+          override
+            .returns(
+              {last_successful_sync: Time, message: String, status: FinchAPI::Models::ConnectionStatusType::TaggedSymbol}
+            )
+        end
         def to_hash
         end
       end

data/rbi/lib/finch-api/version.rbi

@@ -1,5 +1,5 @@
 # typed: strong
 
 module FinchAPI
-  VERSION = "0.1.0-alpha.3"
+  VERSION = "0.1.0-alpha.4"
 end

data/sig/finch-api/base_client.rbs

@@ -49,7 +49,7 @@ module FinchAPI
     ) -> void
 
     # @api private
-    attr_accessor requester: top
+    attr_accessor requester: FinchAPI::PooledNetRequester
 
     def initialize: (
       base_url: String,