finch-api 0.1.0.pre.alpha.1 → 0.1.0.pre.alpha.2

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

@@ -1,167 +1,280 @@
 # typed: strong
 
 module FinchAPI
+  # @api private
   module Util
+    # Due to the current WIP status of Shapes support in Sorbet, types referencing
+    #   this alias might be refined in the future.
+    AnyHash = T.type_alias { T::Hash[Symbol, T.anything] }
+
+    # @api private
     sig { returns(Float) }
     def self.monotonic_secs
     end
 
-    sig { returns(String) }
-    def self.arch
-    end
+    class << self
+      # @api private
+      sig { returns(String) }
+      def arch
+      end
 
-    sig { returns(String) }
-    def self.os
+      # @api private
+      sig { returns(String) }
+      def os
+      end
     end
 
-    sig { params(input: T.anything).returns(T.any(T::Boolean, T.anything)) }
-    def self.primitive?(input)
-    end
+    class << self
+      # @api private
+      sig { params(input: T.anything).returns(T::Boolean) }
+      def primitive?(input)
+      end
 
-    sig { params(input: T.anything).returns(T.any(T::Boolean, T.anything)) }
-    def self.coerce_boolean(input)
-    end
+      # @api private
+      sig { params(input: T.anything).returns(T.any(T::Boolean, T.anything)) }
+      def coerce_boolean(input)
+      end
 
-    sig { params(input: T.anything).returns(T.nilable(T::Boolean)) }
-    def self.coerce_boolean!(input)
-    end
+      # @api private
+      sig { params(input: T.anything).returns(T.nilable(T::Boolean)) }
+      def coerce_boolean!(input)
+      end
 
-    sig { params(input: T.anything).returns(T.any(Integer, T.anything)) }
-    def self.coerce_integer(input)
-    end
+      # @api private
+      sig { params(input: T.anything).returns(T.any(Integer, T.anything)) }
+      def coerce_integer(input)
+      end
 
-    sig { params(input: T.anything).returns(T.any(Float, T.anything)) }
-    def self.coerce_float(input)
-    end
+      # @api private
+      sig { params(input: T.anything).returns(T.any(Float, T.anything)) }
+      def coerce_float(input)
+      end
 
-    sig { params(input: T.anything).returns(T.any(T::Hash[T.anything, T.anything], T.anything)) }
-    def self.coerce_hash(input)
+      # @api private
+      sig { params(input: T.anything).returns(T.any(T::Hash[T.anything, T.anything], T.anything)) }
+      def coerce_hash(input)
+      end
     end
 
+    # Use this to indicate that a value should be explicitly removed from a data
+    #   structure when using `FinchAPI::Util.deep_merge`.
+    #
+    #   e.g. merging `{a: 1}` and `{a: OMIT}` should produce `{}`, where merging
+    #   `{a: 1}` and `{}` would produce `{a: 1}`.
     OMIT = T.let(T.anything, T.anything)
 
-    sig { params(lhs: T.anything, rhs: T.anything, concat: T::Boolean).returns(T.anything) }
-    private_class_method def self.deep_merge_lr(lhs, rhs, concat: false)
-    end
+    class << self
+      # @api private
+      sig { params(lhs: T.anything, rhs: T.anything, concat: T::Boolean).returns(T.anything) }
+      private def deep_merge_lr(lhs, rhs, concat: false)
+      end
 
-    sig do
-      params(values: T::Array[T.anything], sentinel: T.nilable(T.anything), concat: T::Boolean)
-        .returns(T.anything)
-    end
-    def self.deep_merge(*values, sentinel: nil, concat: false)
-    end
-
-    sig do
-      params(
-        data: T.any(T::Hash[Symbol, T.anything], T::Array[T.anything], T.anything),
-        pick: T.nilable(T.any(Symbol, Integer, T::Array[T.any(Symbol, Integer)])),
-        sentinel: T.nilable(T.anything),
-        blk: T.nilable(T.proc.returns(T.anything))
+      # @api private
+      #
+      # Recursively merge one hash with another. If the values at a given key are not
+      #   both hashes, just take the new value.
+      sig do
+        params(values: T::Array[T.anything], sentinel: T.nilable(T.anything), concat: T::Boolean)
+          .returns(T.anything)
+      end
+      def deep_merge(
+        *values,
+        # the value to return if no values are provided.
+        sentinel: nil,
+        # whether to merge sequences by concatenation.
+        concat: false
       )
-        .returns(T.nilable(T.anything))
-    end
-    def self.dig(data, pick, sentinel = nil, &blk)
-    end
+      end
 
-    sig { params(uri: URI::Generic).returns(String) }
-    def self.uri_origin(uri)
+      # @api private
+      sig do
+        params(
+          data: T.any(FinchAPI::Util::AnyHash, T::Array[T.anything], T.anything),
+          pick: T.nilable(T.any(Symbol, Integer, T::Array[T.any(Symbol, Integer)])),
+          sentinel: T.nilable(T.anything),
+          blk: T.nilable(T.proc.returns(T.anything))
+        )
+          .returns(T.nilable(T.anything))
+      end
+      def dig(data, pick, sentinel = nil, &blk)
+      end
     end
 
-    sig { params(path: T.any(String, T::Array[String])).returns(String) }
-    def self.interpolate_path(path)
-    end
+    class << self
+      # @api private
+      sig { params(uri: URI::Generic).returns(String) }
+      def uri_origin(uri)
+      end
 
-    sig { params(query: T.nilable(String)).returns(T::Hash[String, T::Array[String]]) }
-    def self.decode_query(query)
+      # @api private
+      sig { params(path: T.any(String, T::Array[String])).returns(String) }
+      def interpolate_path(path)
+      end
     end
 
-    sig do
-      params(query: T.nilable(T::Hash[String, T.nilable(T.any(T::Array[String], String))]))
-        .returns(T.nilable(String))
-    end
-    def self.encode_query(query)
-    end
+    class << self
+      # @api private
+      sig { params(query: T.nilable(String)).returns(T::Hash[String, T::Array[String]]) }
+      def decode_query(query)
+      end
 
-    ParsedUriShape = T.type_alias do
-      {
-        scheme: T.nilable(String),
-        host: T.nilable(String),
-        port: T.nilable(Integer),
-        path: T.nilable(String),
-        query: T::Hash[String, T::Array[String]]
-      }
+      # @api private
+      sig do
+        params(query: T.nilable(T::Hash[String, T.nilable(T.any(T::Array[String], String))]))
+          .returns(T.nilable(String))
+      end
+      def encode_query(query)
+      end
     end
 
-    sig { params(url: T.any(URI::Generic, String)).returns(FinchAPI::Util::ParsedUriShape) }
-    def self.parse_uri(url)
-    end
+    ParsedUriShape =
+      T.type_alias do
+        {
+          scheme: T.nilable(String),
+          host: T.nilable(String),
+          port: T.nilable(Integer),
+          path: T.nilable(String),
+          query: T::Hash[String, T::Array[String]]
+        }
+      end
 
-    sig { params(parsed: FinchAPI::Util::ParsedUriShape).returns(URI::Generic) }
-    def self.unparse_uri(parsed)
-    end
+    class << self
+      # @api private
+      sig { params(url: T.any(URI::Generic, String)).returns(FinchAPI::Util::ParsedUriShape) }
+      def parse_uri(url)
+      end
 
-    sig do
-      params(lhs: FinchAPI::Util::ParsedUriShape, rhs: FinchAPI::Util::ParsedUriShape).returns(URI::Generic)
-    end
-    def self.join_parsed_uri(lhs, rhs)
-    end
+      # @api private
+      sig { params(parsed: FinchAPI::Util::ParsedUriShape).returns(URI::Generic) }
+      def unparse_uri(parsed)
+      end
 
-    sig do
-      params(
-        headers: T::Hash[String,
-                         T.nilable(T.any(String, Integer, T::Array[T.nilable(T.any(String, Integer))]))]
-      )
-        .returns(T::Hash[String, String])
-    end
-    def self.normalized_headers(*headers)
+      # @api private
+      sig do
+        params(lhs: FinchAPI::Util::ParsedUriShape, rhs: FinchAPI::Util::ParsedUriShape).returns(URI::Generic)
+      end
+      def join_parsed_uri(lhs, rhs)
+      end
     end
 
-    sig { params(io: StringIO, boundary: String, key: T.any(Symbol, String), val: T.anything).void }
-    private_class_method def self.encode_multipart_formdata(io, boundary:, key:, val:)
+    class << self
+      # @api private
+      sig do
+        params(
+          headers: T::Hash[String,
+                           T.nilable(T.any(String, Integer, T::Array[T.nilable(T.any(String, Integer))]))]
+        )
+          .returns(T::Hash[String, String])
+      end
+      def normalized_headers(*headers)
+      end
     end
 
-    sig { params(headers: T::Hash[String, String], body: T.anything).returns(T.anything) }
-    def self.encode_content(headers, body)
-    end
+    # @api private
+    #
+    # An adapter that satisfies the IO interface required by `::IO.copy_stream`
+    class ReadIOAdapter
+      # @api private
+      sig { params(max_len: T.nilable(Integer)).returns(String) }
+      private def read_enum(max_len)
+      end
 
-    sig do
-      params(
-        headers: T.any(T::Hash[String, String], Net::HTTPHeader),
-        stream: T::Enumerable[String],
-        suppress_error: T::Boolean
-      )
-        .returns(T.anything)
-    end
-    def self.decode_content(headers, stream:, suppress_error: false)
-    end
+      # @api private
+      sig { params(max_len: T.nilable(Integer), out_string: T.nilable(String)).returns(T.nilable(String)) }
+      def read(max_len = nil, out_string = nil)
+      end
 
-    sig { params(enum: T::Enumerable[T.anything], close: T.proc.void).returns(T::Enumerable[T.anything]) }
-    def self.fused_enum(enum, &close)
+      # @api private
+      sig do
+        params(
+          stream: T.any(String, IO, StringIO, T::Enumerable[String]),
+          blk: T.proc.params(arg0: String).void
+        )
+          .returns(T.attached_class)
+      end
+      def self.new(stream, &blk)
+      end
     end
 
-    sig { params(enum: T.nilable(T::Enumerable[T.anything])).void }
-    def self.close_fused!(enum)
+    class << self
+      sig { params(blk: T.proc.params(y: Enumerator::Yielder).void).returns(T::Enumerable[String]) }
+      def string_io(&blk)
+      end
     end
 
-    sig do
-      params(
-        enum: T.nilable(T::Enumerable[T.anything]),
-        blk: T.proc.params(arg0: Enumerator::Yielder).void
-      ).void
-    end
-    def self.chain_fused(enum, &blk)
-    end
+    class << self
+      # @api private
+      sig do
+        params(y: Enumerator::Yielder, boundary: String, key: T.any(Symbol, String), val: T.anything).void
+      end
+      private def encode_multipart_formdata(y, boundary:, key:, val:)
+      end
+
+      # @api private
+      sig { params(body: T.anything).returns([String, T::Enumerable[String]]) }
+      private def encode_multipart_streaming(body)
+      end
+
+      # @api private
+      sig { params(headers: T::Hash[String, String], body: T.anything).returns(T.anything) }
+      def encode_content(headers, body)
+      end
 
-    SSEMessage = T.type_alias do
-      {event: T.nilable(String), data: T.nilable(String), id: T.nilable(String), retry: T.nilable(Integer)}
+      # @api private
+      sig do
+        params(
+          headers: T.any(T::Hash[String, String], Net::HTTPHeader),
+          stream: T::Enumerable[String],
+          suppress_error: T::Boolean
+        )
+          .returns(T.anything)
+      end
+      def decode_content(headers, stream:, suppress_error: false)
+      end
     end
 
-    sig { params(enum: T::Enumerable[String]).returns(T::Enumerable[String]) }
-    def self.enum_lines(enum)
+    class << self
+      # @api private
+      #
+      # https://doc.rust-lang.org/std/iter/trait.FusedIterator.html
+      sig do
+        params(enum: T::Enumerable[T.anything], external: T::Boolean, close: T.proc.void)
+          .returns(T::Enumerable[T.anything])
+      end
+      def fused_enum(enum, external: false, &close)
+      end
+
+      # @api private
+      sig { params(enum: T.nilable(T::Enumerable[T.anything])).void }
+      def close_fused!(enum)
+      end
+
+      # @api private
+      sig do
+        params(enum: T.nilable(T::Enumerable[T.anything]), blk: T.proc.params(arg0: Enumerator::Yielder).void)
+          .returns(T::Enumerable[T.anything])
+      end
+      def chain_fused(enum, &blk)
+      end
     end
 
-    sig { params(lines: T::Enumerable[String]).returns(FinchAPI::Util::SSEMessage) }
-    def self.parse_sse(lines)
+    ServerSentEvent =
+      T.type_alias do
+        {event: T.nilable(String), data: T.nilable(String), id: T.nilable(String), retry: T.nilable(Integer)}
+      end
+
+    class << self
+      # @api private
+      sig { params(enum: T::Enumerable[String]).returns(T::Enumerable[String]) }
+      def decode_lines(enum)
+      end
+
+      # @api private
+      #
+      # https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream
+      sig { params(lines: T::Enumerable[String]).returns(FinchAPI::Util::ServerSentEvent) }
+      def decode_sse(lines)
+      end
     end
   end
 end

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

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

data/sig/finch-api/base_client.rbs

@@ -43,19 +43,24 @@ module FinchAPI
       response_headers: ::Hash[String, String]
     ) -> FinchAPI::BaseClient::request_input
 
-    # @private
+    def self.reap_connection!: (
+      Integer | FinchAPI::APIConnectionError status,
+      stream: Enumerable[String]?
+    ) -> void
+
+    # @api private
     attr_accessor requester: top
 
     def initialize: (
       base_url: String,
-      timeout: Float,
-      max_retries: Integer,
-      initial_retry_delay: Float,
-      max_retry_delay: Float,
-      headers: ::Hash[String, (String
+      ?timeout: Float,
+      ?max_retries: Integer,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float,
+      ?headers: ::Hash[String, (String
       | Integer
       | ::Array[(String | Integer)?])?],
-      idempotency_header: String?
+      ?idempotency_header: String?
     ) -> void
 
     private def auth_headers: -> ::Hash[String, String]
@@ -83,16 +88,16 @@ module FinchAPI
       (
         Symbol method,
         String | ::Array[String] path,
-        query: ::Hash[String, (::Array[String] | String)?]?,
-        headers: ::Hash[String, (String
+        ?query: ::Hash[String, (::Array[String] | String)?]?,
+        ?headers: ::Hash[String, (String
         | Integer
         | ::Array[(String | Integer)?])?]?,
-        body: top?,
-        unwrap: Symbol?,
-        page: Class?,
-        stream: Class?,
-        model: FinchAPI::Converter::input?,
-        options: FinchAPI::request_opts?
+        ?body: top?,
+        ?unwrap: Symbol?,
+        ?page: Class?,
+        ?stream: Class?,
+        ?model: FinchAPI::Converter::input?,
+        ?options: FinchAPI::request_opts?
       ) -> top
       | (FinchAPI::BaseClient::request_components req) -> top
 

data/sig/finch-api/base_model.rbs

@@ -62,32 +62,34 @@ module FinchAPI
     ) -> ([true, top, nil] | [false, bool, Integer])
   end
 
-  class Enum
-    extend FinchAPI::Converter
+  module Enum
+    include FinchAPI::Converter
 
     def self.values: -> ::Array[(nil | bool | Integer | Float | Symbol)]
 
     private def self.finalize!: -> void
 
-    def self.===: (top other) -> bool
+    def ===: (top other) -> bool
 
-    def self.==: (top other) -> bool
+    def ==: (top other) -> bool
 
-    def self.coerce: (String | Symbol | top value) -> (Symbol | top)
+    def coerce: (String | Symbol | top value) -> (Symbol | top)
 
-    def self.dump: (Symbol | top value) -> (Symbol | top)
+    def dump: (Symbol | top value) -> (Symbol | top)
 
-    def self.try_strict_coerce: (
+    def try_strict_coerce: (
       top value
     ) -> ([true, top, nil] | [false, bool, Integer])
   end
 
-  class Union
-    extend FinchAPI::Converter
+  module Union
+    include FinchAPI::Converter
 
-    private def self.known_variants: -> ::Array[[Symbol?, Proc]]
+    private def self.known_variants: -> ::Array[[Symbol?, (^-> FinchAPI::Converter::input)]]
 
-    def self.variants: -> ::Array[[Symbol?, top]]
+    def self.derefed_variants: -> ::Array[[Symbol?, top]]
+
+    def self.variants: -> ::Array[top]
 
     private def self.discriminator: (Symbol property) -> void
 
@@ -103,15 +105,15 @@ module FinchAPI
 
     private def self.resolve_variant: (top value) -> FinchAPI::Converter::input?
 
-    def self.===: (top other) -> bool
+    def ===: (top other) -> bool
 
-    def self.==: (top other) -> bool
+    def ==: (top other) -> bool
 
-    def self.coerce: (top value) -> top
+    def coerce: (top value) -> top
 
-    def self.dump: (top value) -> top
+    def dump: (top value) -> top
 
-    def self.try_strict_coerce: (
+    def try_strict_coerce: (
       top value
     ) -> ([true, top, nil] | [false, bool, Integer])
   end
@@ -119,6 +121,13 @@ module FinchAPI
   class ArrayOf
     include FinchAPI::Converter
 
+    def self.[]: (
+      ::Hash[Symbol, top]
+      | ^-> FinchAPI::Converter::input
+      | FinchAPI::Converter::input type_info,
+      ?::Hash[Symbol, top] spec
+    ) -> instance
+
     def ===: (top other) -> bool
 
     def ==: (top other) -> bool
@@ -131,7 +140,7 @@ module FinchAPI
       top value
     ) -> ([true, top, nil] | [false, bool, Integer])
 
-    def item_type: -> FinchAPI::Converter::input
+    def item_type: -> top
 
     def initialize: (
       ::Hash[Symbol, top]
@@ -144,6 +153,13 @@ module FinchAPI
   class HashOf
     include FinchAPI::Converter
 
+    def self.[]: (
+      ::Hash[Symbol, top]
+      | ^-> FinchAPI::Converter::input
+      | FinchAPI::Converter::input type_info,
+      ?::Hash[Symbol, top] spec
+    ) -> instance
+
     def ===: (top other) -> bool
 
     def ==: (top other) -> bool
@@ -156,7 +172,7 @@ module FinchAPI
       top value
     ) -> ([true, top, nil] | [false, bool, Integer])
 
-    def item_type: -> FinchAPI::Converter::input
+    def item_type: -> top
 
     def initialize: (
       ::Hash[Symbol, top]
@@ -174,6 +190,8 @@ module FinchAPI
     def self.known_fields: -> ::Hash[Symbol, (FinchAPI::BaseModel::known_field
     & { type_fn: (^-> FinchAPI::Converter::input) })]
 
+    def self.reverse_map: -> ::Hash[Symbol, Symbol]
+
     def self.fields: -> ::Hash[Symbol, (FinchAPI::BaseModel::known_field
     & { type: FinchAPI::Converter::input })]
 

data/sig/finch-api/base_page.rbs

@@ -14,7 +14,7 @@ module FinchAPI
       client: FinchAPI::BaseClient,
       req: FinchAPI::BaseClient::request_components,
       headers: ::Hash[String, String],
-      unwrapped: top
+      page_data: top
     ) -> void
   end
 end

data/sig/finch-api/client.rbs

@@ -41,14 +41,14 @@ module FinchAPI
     private def basic_auth: -> ::Hash[String, String]
 
     def initialize: (
-      base_url: String?,
-      access_token: String?,
-      client_id: String?,
-      client_secret: String?,
-      max_retries: Integer,
-      timeout: Float,
-      initial_retry_delay: Float,
-      max_retry_delay: Float
+      ?base_url: String?,
+      ?access_token: String?,
+      ?client_id: String?,
+      ?client_secret: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
     ) -> void
   end
 end