finch-api 0.1.0.pre.alpha.2 → 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/models/sandbox/directory_create_params.rb

@@ -495,14 +495,10 @@ module FinchAPI
           end
 
           class PhoneNumber < FinchAPI::BaseModel
-            # @!attribute [r] data
+            # @!attribute data
             #
             #   @return [String, nil]
-            optional :data, String
-
-            # @!parse
-            #   # @return [String]
-            #   attr_writer :data
+            optional :data, String, nil?: true
 
             # @!attribute type
             #
@@ -512,7 +508,7 @@ module FinchAPI
                      nil?: true
 
             # @!parse
-            #   # @param data [String]
+            #   # @param data [String, nil]
             #   # @param type [Symbol, FinchAPI::Models::Sandbox::DirectoryCreateParams::Body::PhoneNumber::Type, nil]
             #   #
             #   def initialize(data: nil, type: nil, **) = super

data/lib/finch-api/models/sandbox/individual_update_params.rb

@@ -195,14 +195,10 @@ module FinchAPI
         end
 
         class PhoneNumber < FinchAPI::BaseModel
-          # @!attribute [r] data
+          # @!attribute data
           #
           #   @return [String, nil]
-          optional :data, String
-
-          # @!parse
-          #   # @return [String]
-          #   attr_writer :data
+          optional :data, String, nil?: true
 
           # @!attribute type
           #
@@ -212,7 +208,7 @@ module FinchAPI
                    nil?: true
 
           # @!parse
-          #   # @param data [String]
+          #   # @param data [String, nil]
           #   # @param type [Symbol, FinchAPI::Models::Sandbox::IndividualUpdateParams::PhoneNumber::Type, nil]
           #   #
           #   def initialize(data: nil, type: nil, **) = super

data/lib/finch-api/models/sandbox/individual_update_response.rb

@@ -203,14 +203,10 @@ module FinchAPI
         end
 
         class PhoneNumber < FinchAPI::BaseModel
-          # @!attribute [r] data
+          # @!attribute data
           #
           #   @return [String, nil]
-          optional :data, String
-
-          # @!parse
-          #   # @return [String]
-          #   attr_writer :data
+          optional :data, String, nil?: true
 
           # @!attribute type
           #
@@ -220,7 +216,7 @@ module FinchAPI
                    nil?: true
 
           # @!parse
-          #   # @param data [String]
+          #   # @param data [String, nil]
           #   # @param type [Symbol, FinchAPI::Models::Sandbox::IndividualUpdateResponse::PhoneNumber::Type, nil]
           #   #
           #   def initialize(data: nil, type: nil, **) = super

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.2"
+  VERSION = "0.1.0-alpha.4"
 end

data/lib/finch-api.rb

@@ -2,7 +2,7 @@
 
 # We already ship the preferred sorbet manifests in the package itself.
 # `tapioca` currently does not offer us a way to opt out of unnecessary compilation.
-if Object.const_defined?(:Tapioca) && caller_locations.any? { _1.path.end_with?("tapioca/cli.rb") }
+if Object.const_defined?(:Tapioca) && caller.chain([$0]).chain(ARGV).grep(/tapioca/)
   Warning.warn(
     <<~WARN
       \n
@@ -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/models/sandbox/directory_create_params.rbi

@@ -619,17 +619,14 @@ module FinchAPI
 
           class PhoneNumber < FinchAPI::BaseModel
             sig { returns(T.nilable(String)) }
-            attr_reader :data
-
-            sig { params(data: String).void }
-            attr_writer :data
+            attr_accessor :data
 
             sig { returns(T.nilable(FinchAPI::Models::Sandbox::DirectoryCreateParams::Body::PhoneNumber::Type::OrSymbol)) }
             attr_accessor :type
 
             sig do
               params(
-                data: String,
+                data: T.nilable(String),
                 type: T.nilable(FinchAPI::Models::Sandbox::DirectoryCreateParams::Body::PhoneNumber::Type::OrSymbol)
               )
                 .returns(T.attached_class)
@@ -641,7 +638,7 @@ module FinchAPI
               override
                 .returns(
                   {
-                    data: String,
+                    data: T.nilable(String),
                     type: T.nilable(FinchAPI::Models::Sandbox::DirectoryCreateParams::Body::PhoneNumber::Type::OrSymbol)
                   }
                 )

data/rbi/lib/finch-api/models/sandbox/individual_update_params.rbi

@@ -226,17 +226,14 @@ module FinchAPI
 
         class PhoneNumber < FinchAPI::BaseModel
           sig { returns(T.nilable(String)) }
-          attr_reader :data
-
-          sig { params(data: String).void }
-          attr_writer :data
+          attr_accessor :data
 
           sig { returns(T.nilable(FinchAPI::Models::Sandbox::IndividualUpdateParams::PhoneNumber::Type::OrSymbol)) }
           attr_accessor :type
 
           sig do
             params(
-              data: String,
+              data: T.nilable(String),
               type: T.nilable(FinchAPI::Models::Sandbox::IndividualUpdateParams::PhoneNumber::Type::OrSymbol)
             )
               .returns(T.attached_class)
@@ -248,7 +245,7 @@ module FinchAPI
             override
               .returns(
                 {
-                  data: String,
+                  data: T.nilable(String),
                   type: T.nilable(FinchAPI::Models::Sandbox::IndividualUpdateParams::PhoneNumber::Type::OrSymbol)
                 }
               )