modern_treasury 0.1.0.pre.alpha.18 → 0.1.0.pre.alpha.20

data/lib/modern_treasury/internal/transport/base_client.rb

@@ -7,6 +7,8 @@ module ModernTreasury
       #
       # @abstract
       class BaseClient
+        extend ModernTreasury::Internal::Util::SorbetRuntimeSupport
+
         # from whatwg fetch spec
         MAX_REDIRECTS = 20
 
@@ -151,9 +153,30 @@ module ModernTreasury
           end
         end
 
+        # @return [URI::Generic]
+        attr_reader :base_url
+
+        # @return [Float]
+        attr_reader :timeout
+
+        # @return [Integer]
+        attr_reader :max_retries
+
+        # @return [Float]
+        attr_reader :initial_retry_delay
+
+        # @return [Float]
+        attr_reader :max_retry_delay
+
+        # @return [Hash{String=>String}]
+        attr_reader :headers
+
+        # @return [String, nil]
+        attr_reader :idempotency_header
+
         # @api private
         # @return [ModernTreasury::Internal::Transport::PooledNetRequester]
-        attr_accessor :requester
+        attr_reader :requester
 
         # @api private
         #
@@ -182,10 +205,11 @@ module ModernTreasury
             },
             headers
           )
-          @base_url = ModernTreasury::Internal::Util.parse_uri(base_url)
+          @base_url_components = ModernTreasury::Internal::Util.parse_uri(base_url)
+          @base_url = ModernTreasury::Internal::Util.unparse_uri(@base_url_components)
           @idempotency_header = idempotency_header&.to_s&.downcase
-          @max_retries = max_retries
           @timeout = timeout
+          @max_retries = max_retries
           @initial_retry_delay = initial_retry_delay
           @max_retry_delay = max_retry_delay
         end
@@ -214,11 +238,11 @@ module ModernTreasury
         #
         #   @option req [Object, nil] :body
         #
-        #   @option req [Symbol, nil] :unwrap
+        #   @option req [Symbol, Integer, Array<Symbol, Integer>, Proc, nil] :unwrap
         #
-        #   @option req [Class, nil] :page
+        #   @option req [Class<ModernTreasury::Internal::Type::BasePage>, nil] :page
         #
-        #   @option req [Class, nil] :stream
+        #   @option req [Class<ModernTreasury::Internal::Type::BaseStream>, nil] :stream
         #
         #   @option req [ModernTreasury::Internal::Type::Converter, Class, nil] :model
         #
@@ -253,7 +277,7 @@ module ModernTreasury
 
           if @idempotency_header &&
              !headers.key?(@idempotency_header) &&
-             (!Net::HTTP::IDEMPOTENT_METHODS_.include?(method.to_s.upcase) || opts.key?(:idempotency_key))
+             (%w[POST PUT].include?(method.to_s.upcase) || opts.key?(:idempotency_key))
             headers[@idempotency_header] = opts.fetch(:idempotency_key) { generate_idempotency_key }
           end
 
@@ -261,7 +285,7 @@ module ModernTreasury
             headers["x-stainless-retry-count"] = "0"
           end
 
-          timeout = opts.fetch(:timeout, @timeout).to_f.clamp((0..))
+          timeout = opts.fetch(:timeout, @timeout).to_f.clamp(0..)
           unless headers.key?("x-stainless-timeout") || timeout.zero?
             headers["x-stainless-timeout"] = timeout.to_s
           end
@@ -276,10 +300,14 @@ module ModernTreasury
               ModernTreasury::Internal::Util.deep_merge(*[req[:body], opts[:extra_body]].compact)
             end
 
+          url = ModernTreasury::Internal::Util.join_parsed_uri(
+            @base_url_components,
+            {**req, path: path, query: query}
+          )
           headers, encoded = ModernTreasury::Internal::Util.encode_content(headers, body)
           {
             method: method,
-            url: ModernTreasury::Internal::Util.join_parsed_uri(@base_url, {**req, path: path, query: query}),
+            url: url,
             headers: headers,
             body: encoded,
             max_retries: opts.fetch(:max_retries, @max_retries),
@@ -422,11 +450,11 @@ module ModernTreasury
         #
         # @param body [Object, nil]
         #
-        # @param unwrap [Symbol, nil]
+        # @param unwrap [Symbol, Integer, Array<Symbol, Integer>, Proc, nil]
         #
-        # @param page [Class, nil]
+        # @param page [Class<ModernTreasury::Internal::Type::BasePage>, nil]
         #
-        # @param stream [Class, nil]
+        # @param stream [Class<ModernTreasury::Internal::Type::BaseStream>, nil]
         #
         # @param model [ModernTreasury::Internal::Type::Converter, Class, nil]
         #
@@ -465,9 +493,9 @@ module ModernTreasury
 
           decoded = ModernTreasury::Internal::Util.decode_content(response, stream: stream)
           case req
-          in { stream: Class => st }
+          in {stream: Class => st}
             st.new(model: model, url: url, status: status, response: response, stream: decoded)
-          in { page: Class => page }
+          in {page: Class => page}
             page.new(client: self, req: req, headers: response, page_data: decoded)
           else
             unwrapped = ModernTreasury::Internal::Util.dig(decoded, req[:unwrap])
@@ -480,10 +508,54 @@ module ModernTreasury
         # @return [String]
         def inspect
           # rubocop:disable Layout/LineLength
-          base_url = ModernTreasury::Internal::Util.unparse_uri(@base_url)
-          "#<#{self.class.name}:0x#{object_id.to_s(16)} base_url=#{base_url} max_retries=#{@max_retries} timeout=#{@timeout}>"
+          "#<#{self.class.name}:0x#{object_id.to_s(16)} base_url=#{@base_url} max_retries=#{@max_retries} timeout=#{@timeout}>"
           # rubocop:enable Layout/LineLength
         end
+
+        define_sorbet_constant!(:RequestComponents) do
+          T.type_alias do
+            {
+              method: Symbol,
+              path: T.any(String, T::Array[String]),
+              query: T.nilable(T::Hash[String, T.nilable(T.any(T::Array[String], String))]),
+              headers: T.nilable(
+                T::Hash[String,
+                        T.nilable(
+                          T.any(
+                            String,
+                            Integer,
+                            T::Array[T.nilable(T.any(String, Integer))]
+                          )
+                        )]
+              ),
+              body: T.nilable(T.anything),
+              unwrap: T.nilable(
+                T.any(
+                  Symbol,
+                  Integer,
+                  T::Array[T.any(Symbol, Integer)],
+                  T.proc.params(arg0: T.anything).returns(T.anything)
+                )
+              ),
+              page: T.nilable(T::Class[ModernTreasury::Internal::Type::BasePage[ModernTreasury::Internal::Type::BaseModel]]),
+              stream: T.nilable(T::Class[T.anything]),
+              model: T.nilable(ModernTreasury::Internal::Type::Converter::Input),
+              options: T.nilable(ModernTreasury::RequestOptions::OrHash)
+            }
+          end
+        end
+        define_sorbet_constant!(:RequestInput) do
+          T.type_alias do
+            {
+              method: Symbol,
+              url: URI::Generic,
+              headers: T::Hash[String, String],
+              body: T.anything,
+              max_retries: Integer,
+              timeout: Float
+            }
+          end
+        end
       end
     end
   end

data/lib/modern_treasury/internal/transport/pooled_net_requester.rb

@@ -5,10 +5,14 @@ module ModernTreasury
     module Transport
       # @api private
       class PooledNetRequester
+        extend ModernTreasury::Internal::Util::SorbetRuntimeSupport
+
         # from the golang stdlib
         # https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
         KEEP_ALIVE_TIMEOUT = 30
 
+        DEFAULT_MAX_CONNECTIONS = [Etc.nprocessors, 99].max
+
         class << self
           # @api private
           #
@@ -57,15 +61,11 @@ module ModernTreasury
           # @return [Array(Net::HTTPGenericRequest, Proc)]
           def build_request(request, &blk)
             method, url, headers, body = request.fetch_values(:method, :url, :headers, :body)
-
-            # ensure we construct a URI class of the right scheme
-            url = URI(url.to_s)
-
             req = Net::HTTPGenericRequest.new(
               method.to_s.upcase,
               !body.nil?,
               method != :head,
-              url
+              URI(url.to_s) # ensure we construct a URI class of the right scheme
             )
 
             headers.each { req[_1] = _2 }
@@ -180,17 +180,29 @@ module ModernTreasury
             conn.finish if !eof && conn&.started?
             closing&.call
           end
-          [Integer(response.code), response, (response.body = body)]
+          [Integer(response.code), response, body]
         end
 
         # @api private
         #
         # @param size [Integer]
-        def initialize(size: Etc.nprocessors)
+        def initialize(size: self.class::DEFAULT_MAX_CONNECTIONS)
           @mutex = Mutex.new
           @size = size
           @pools = {}
         end
+
+        define_sorbet_constant!(:Request) do
+          T.type_alias do
+            {
+              method: Symbol,
+              url: URI::Generic,
+              headers: T::Hash[String, String],
+              body: T.anything,
+              deadline: Float
+            }
+          end
+        end
       end
     end
   end

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

@@ -12,6 +12,7 @@ module ModernTreasury
       # Array of items of a given type.
       class ArrayOf
         include ModernTreasury::Internal::Type::Converter
+        include ModernTreasury::Internal::Util::SorbetRuntimeSupport
 
         private_class_method :new
 
@@ -28,13 +29,19 @@ module ModernTreasury
         #   @option spec [Proc] :union
         #
         #   @option spec [Boolean] :"nil?"
+        #
+        # @return [self]
         def self.[](...) = new(...)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def ===(other) = other.is_a?(Array) && other.all?(item_type)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -44,6 +51,11 @@ module ModernTreasury
           # rubocop:enable Layout/LineLength
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, item_type].hash
+
         # @api private
         #
         # @param value [Array<Object>, Object]
@@ -99,6 +111,13 @@ module ModernTreasury
           end
         end
 
+        # @api private
+        #
+        # @return [Object]
+        def to_sorbet_type
+          T::Array[ModernTreasury::Internal::Util::SorbetRuntimeSupport.to_sorbet_type(item_type)]
+        end
+
         # @api private
         #
         # @return [generic<Elem>]

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

@@ -4,15 +4,9 @@ module ModernTreasury
   module Internal
     module Type
       # @abstract
-      #
-      # @example
-      #   # `async_response` is a `ModernTreasury::Models::AsyncResponse`
-      #   async_response => {
-      #     id: id,
-      #     object: object
-      #   }
       class BaseModel
         extend ModernTreasury::Internal::Type::Converter
+        extend ModernTreasury::Internal::Util::SorbetRuntimeSupport
 
         class << self
           # @api private
@@ -20,11 +14,17 @@ module ModernTreasury
           # Assumes superclass fields are totally defined before fields are accessed /
           # defined on subclasses.
           #
-          # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
-          def known_fields
-            @known_fields ||= (self < ModernTreasury::Internal::Type::BaseModel ? superclass.known_fields.dup : {})
+          # @param child [Class<ModernTreasury::Internal::Type::BaseModel>]
+          def inherited(child)
+            super
+            child.known_fields.replace(known_fields.dup)
           end
 
+          # @api private
+          #
+          # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+          def known_fields = @known_fields ||= {}
+
           # @api private
           #
           # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
@@ -97,11 +97,13 @@ module ModernTreasury
                   target, value, state: state
                 )
               end
-            rescue StandardError
+            rescue StandardError => e
               cls = self.class.name.split("::").last
-              # rubocop:disable Layout/LineLength
-              message = "Failed to parse #{cls}.#{__method__} from #{value.class} to #{target.inspect}. To get the unparsed API response, use #{cls}[:#{__method__}]."
-              # rubocop:enable Layout/LineLength
+              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 ModernTreasury::Errors::ConversionError.new(message)
             end
           end
@@ -169,19 +171,33 @@ module ModernTreasury
             @mode = nil
           end
 
+          # @api public
+          #
           # @param other [Object]
           #
           # @return [Boolean]
           def ==(other)
             other.is_a?(Class) && other <= ModernTreasury::Internal::Type::BaseModel && other.fields == fields
           end
+
+          # @api public
+          #
+          # @return [Integer]
+          def hash = fields.hash
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def ==(other) = self.class == other.class && @data == other.to_h
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, @data].hash
+
         class << self
           # @api private
           #
@@ -195,7 +211,7 @@ module ModernTreasury
           #
           #   @option state [Integer] :branched
           #
-          # @return [ModernTreasury::Internal::Type::BaseModel, Object]
+          # @return [self, Object]
           def coerce(value, state:)
             exactness = state.fetch(:exactness)
 
@@ -254,7 +270,7 @@ module ModernTreasury
 
           # @api private
           #
-          # @param value [ModernTreasury::Internal::Type::BaseModel, Object]
+          # @param value [self, Object]
           #
           # @param state [Hash{Symbol=>Object}] .
           #
@@ -296,8 +312,50 @@ module ModernTreasury
 
             acc
           end
+
+          # @api private
+          #
+          # @return [Object]
+          def to_sorbet_type
+            self
+          end
         end
 
+        class << self
+          # @api private
+          #
+          # @param model [ModernTreasury::Internal::Type::BaseModel]
+          # @param convert [Boolean]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def recursively_to_h(model, convert:)
+            rec = ->(x) do
+              case x
+              in ModernTreasury::Internal::Type::BaseModel
+                if convert
+                  fields = x.class.known_fields
+                  x.to_h.to_h do |key, val|
+                    [key, rec.call(fields.key?(key) ? x.public_send(key) : val)]
+                  rescue ModernTreasury::Errors::ConversionError
+                    [key, rec.call(val)]
+                  end
+                else
+                  rec.call(x.to_h)
+                end
+              in Hash
+                x.transform_values(&rec)
+              in Array
+                x.map(&rec)
+              else
+                x
+              end
+            end
+            rec.call(model)
+          end
+        end
+
+        # @api public
+        #
         # Returns the raw value associated with the given key, if found. Otherwise, nil is
         # returned.
         #
@@ -316,6 +374,8 @@ module ModernTreasury
           @data[key]
         end
 
+        # @api public
+        #
         # Returns a Hash of the data underlying this object. O(1)
         #
         # Keys are Symbols and values are the raw values from the response. The return
@@ -330,9 +390,24 @@ module ModernTreasury
 
         alias_method :to_hash, :to_h
 
+        # @api public
+        #
+        # In addition to the behaviour of `#to_h`, this method will recursively call
+        # `#to_h` on nested models.
+        #
+        # @return [Hash{Symbol=>Object}]
+        def deep_to_h = self.class.recursively_to_h(@data, convert: false)
+
         # @param keys [Array<Symbol>, nil]
         #
         # @return [Hash{Symbol=>Object}]
+        #
+        # @example
+        #   # `async_response` is a `ModernTreasury::AsyncResponse`
+        #   async_response => {
+        #     id: id,
+        #     object: object
+        #   }
         def deconstruct_keys(keys)
           (keys || self.class.known_fields.keys)
             .filter_map do |k|
@@ -345,11 +420,15 @@ module ModernTreasury
             .to_h
         end
 
+        # @api public
+        #
         # @param a [Object]
         #
         # @return [String]
         def to_json(*a) = ModernTreasury::Internal::Type::Converter.dump(self.class, self).to_json(*a)
 
+        # @api public
+        #
         # @param a [Object]
         #
         # @return [String]
@@ -357,16 +436,8 @@ module ModernTreasury
 
         # Create a new instance of a model.
         #
-        # @param data [Hash{Symbol=>Object}, ModernTreasury::Internal::Type::BaseModel]
-        def initialize(data = {})
-          case ModernTreasury::Internal::Util.coerce_hash(data)
-          in Hash => coerced
-            @data = coerced
-          else
-            message = "Expected a #{Hash} or #{ModernTreasury::Internal::Type::BaseModel}, got #{data.inspect}"
-            raise ArgumentError.new(message)
-          end
-        end
+        # @param data [Hash{Symbol=>Object}, self]
+        def initialize(data = {}) = (@data = ModernTreasury::Internal::Util.coerce_hash!(data).to_h)
 
         class << self
           # @api private
@@ -380,30 +451,32 @@ module ModernTreasury
             depth = depth.succ
             deferred = fields.transform_values do |field|
               type, required, nilable = field.fetch_values(:type, :required, :nilable)
-              -> do
-                [
-                  ModernTreasury::Internal::Type::Converter.inspect(type, depth: depth),
-                  !required || nilable ? "nil" : nil
-                ].compact.join(" | ")
-              end
-                .tap { _1.define_singleton_method(:inspect) { call } }
+              inspected = [
+                ModernTreasury::Internal::Type::Converter.inspect(type, depth: depth),
+                !required || nilable ? "nil" : nil
+              ].compact.join(" | ")
+              -> { inspected }.tap { _1.define_singleton_method(:inspect) { call } }
             end
 
             "#{name}[#{deferred.inspect}]"
           end
         end
 
+        # @api public
+        #
+        # @return [String]
+        def to_s = deep_to_h.to_s
+
         # @api private
         #
         # @return [String]
         def inspect
-          rows = @data.map do
-            "#{_1}=#{self.class.known_fields.key?(_1) ? public_send(_1).inspect : ''}"
-          rescue ModernTreasury::Errors::ConversionError
-            "#{_1}=#{_2.inspect}"
-          end
+          converted = self.class.recursively_to_h(self, convert: true)
+          "#<#{self.class}:0x#{object_id.to_s(16)} #{converted}>"
+        end
 
-          "#<#{self.class}:0x#{object_id.to_s(16)} #{rows.join(' ')}>"
+        define_sorbet_constant!(:KnownField) do
+          T.type_alias { {mode: T.nilable(Symbol), required: T::Boolean, nilable: T::Boolean} }
         end
       end
     end

data/lib/modern_treasury/internal/type/base_page.rb

@@ -3,19 +3,27 @@
 module ModernTreasury
   module Internal
     module Type
+      # @api private
+      #
       # @generic Elem
       #
       # This module provides a base implementation for paginated responses in the SDK.
       module BasePage
         # rubocop:disable Lint/UnusedMethodArgument
 
+        # @api public
+        #
         # @return [Boolean]
         def next_page? = (raise NotImplementedError)
 
+        # @api public
+        #
         # @raise [ModernTreasury::Errors::APIError]
-        # @return [ModernTreasury::Internal::Type::BasePage]
+        # @return [self]
         def next_page = (raise NotImplementedError)
 
+        # @api public
+        #
         # @param blk [Proc]
         #
         # @yieldparam [generic<Elem>]

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

@@ -10,14 +10,19 @@ module ModernTreasury
       # Ruby has no Boolean class; this is something for models to refer to.
       class Boolean
         extend ModernTreasury::Internal::Type::Converter
+        extend ModernTreasury::Internal::Util::SorbetRuntimeSupport
 
         private_class_method :new
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def self.===(other) = other == true || other == false
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -42,17 +47,23 @@ module ModernTreasury
             value
           end
 
-          # @!parse
-          #   # @api private
-          #   #
-          #   # @param value [Boolean, Object]
-          #   #
-          #   # @param state [Hash{Symbol=>Object}] .
-          #   #
-          #   #   @option state [Boolean] :can_retry
-          #   #
-          #   # @return [Boolean, Object]
-          #   def dump(value, state:) = super
+          # @!method dump(value, state:)
+          #   @api private
+          #
+          #   @param value [Boolean, Object]
+          #
+          #   @param state [Hash{Symbol=>Object}] .
+          #
+          #     @option state [Boolean] :can_retry
+          #
+          #   @return [Boolean, Object]
+
+          # @api private
+          #
+          # @return [Object]
+          def to_sorbet_type
+            T::Boolean
+          end
         end
       end
     end