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

data/lib/finch-api.rb

@@ -1,5 +1,20 @@
 # frozen_string_literal: true
 
+# 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") }
+  Warning.warn(
+    <<~WARN
+      \n
+      ⚠️ skipped loading of "finch-api" gem under `tapioca`.
+
+      This message is normal and expected if you are running a `tapioca` command, and does not impact `.rbi` generation.
+      \n
+    WARN
+  )
+  return
+end
+
 # Standard libraries.
 require "cgi"
 require "date"
@@ -7,6 +22,7 @@ require "erb"
 require "etc"
 require "json"
 require "net/http"
+require "pathname"
 require "rbconfig"
 require "securerandom"
 require "set"
@@ -104,6 +120,7 @@ require_relative "finch-api/models/jobs/automated_async_job"
 require_relative "finch-api/models/jobs/automated_create_params"
 require_relative "finch-api/models/jobs/automated_create_response"
 require_relative "finch-api/models/jobs/automated_list_params"
+require_relative "finch-api/models/jobs/automated_list_response"
 require_relative "finch-api/models/jobs/automated_retrieve_params"
 require_relative "finch-api/models/jobs/manual_async_job"
 require_relative "finch-api/models/jobs/manual_retrieve_params"

data/manifest.yaml

@@ -5,6 +5,7 @@ dependencies:
   - etc
   - json
   - net/http
+  - pathname
   - rbconfig
   - securerandom
   - set

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

@@ -1,77 +1,93 @@
 # typed: strong
 
 module FinchAPI
+  # @api private
   class BaseClient
     abstract!
 
-    RequestComponentsShape = 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(Symbol),
-        page: T.nilable(T::Class[FinchAPI::BasePage[FinchAPI::BaseModel]]),
-        stream: T.nilable(T::Class[T.anything]),
-        model: T.nilable(FinchAPI::Converter::Input),
-        options: T.nilable(T.any(FinchAPI::RequestOptions, T::Hash[Symbol, T.anything]))
-      }
-    end
-
-    RequestInputShape = T.type_alias do
-      {
-        method: Symbol,
-        url: URI::Generic,
-        headers: T::Hash[String, String],
-        body: T.anything,
-        max_retries: Integer,
-        timeout: Float
-      }
-    end
-
+    RequestComponentsShape =
+      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(Symbol),
+          page: T.nilable(T::Class[FinchAPI::BasePage[FinchAPI::BaseModel]]),
+          stream: T.nilable(T::Class[T.anything]),
+          model: T.nilable(FinchAPI::Converter::Input),
+          options: T.nilable(T.any(FinchAPI::RequestOptions, FinchAPI::Util::AnyHash))
+        }
+      end
+
+    RequestInputShape =
+      T.type_alias do
+        {
+          method: Symbol,
+          url: URI::Generic,
+          headers: T::Hash[String, String],
+          body: T.anything,
+          max_retries: Integer,
+          timeout: Float
+        }
+      end
+
+    # from whatwg fetch spec
     MAX_REDIRECTS = 20
 
     PLATFORM_HEADERS = T::Hash[String, String]
 
-    sig { params(req: FinchAPI::BaseClient::RequestComponentsShape).void }
-    def self.validate!(req)
-    end
-
-    sig do
-      params(status: Integer, headers: T.any(T::Hash[String, String], Net::HTTPHeader)).returns(T::Boolean)
-    end
-    def self.should_retry?(status, headers:)
-    end
-
-    sig do
-      params(
-        request: FinchAPI::BaseClient::RequestInputShape,
-        status: Integer,
-        response_headers: T.any(T::Hash[String, String], Net::HTTPHeader)
-      )
-        .returns(FinchAPI::BaseClient::RequestInputShape)
-    end
-    def self.follow_redirect(request, status:, response_headers:)
-    end
-
+    class << self
+      # @api private
+      sig { params(req: FinchAPI::BaseClient::RequestComponentsShape).void }
+      def validate!(req)
+      end
+
+      # @api private
+      sig do
+        params(status: Integer, headers: T.any(T::Hash[String, String], Net::HTTPHeader)).returns(T::Boolean)
+      end
+      def should_retry?(status, headers:)
+      end
+
+      # @api private
+      sig do
+        params(
+          request: FinchAPI::BaseClient::RequestInputShape,
+          status: Integer,
+          response_headers: T.any(T::Hash[String, String], Net::HTTPHeader)
+        )
+          .returns(FinchAPI::BaseClient::RequestInputShape)
+      end
+      def follow_redirect(request, status:, response_headers:)
+      end
+
+      # @api private
+      sig do
+        params(
+          status: T.any(Integer, FinchAPI::APIConnectionError),
+          stream: T.nilable(T::Enumerable[String])
+        ).void
+      end
+      def reap_connection!(status, stream:)
+      end
+    end
+
+    # @api private
     sig { returns(T.anything) }
-    def requester
-    end
-
-    sig { params(_: T.anything).returns(T.anything) }
-    def requester=(_)
-    end
+    attr_accessor :requester
 
+    # @api private
     sig do
       params(
         base_url: String,
@@ -83,9 +99,9 @@ module FinchAPI
                          T.nilable(T.any(String, Integer, T::Array[T.nilable(T.any(String, Integer))]))],
         idempotency_header: T.nilable(String)
       )
-        .void
+        .returns(T.attached_class)
     end
-    def initialize(
+    def self.new(
       base_url:,
       timeout: 0.0,
       max_retries: 0,
@@ -96,26 +112,31 @@ module FinchAPI
     )
     end
 
+    # @api private
     sig { overridable.returns(T::Hash[String, String]) }
     private def auth_headers
     end
 
+    # @api private
     sig { returns(String) }
     private def generate_idempotency_key
     end
 
+    # @api private
     sig do
       overridable
-        .params(req: FinchAPI::BaseClient::RequestComponentsShape, opts: T::Hash[Symbol, T.anything])
+        .params(req: FinchAPI::BaseClient::RequestComponentsShape, opts: FinchAPI::Util::AnyHash)
         .returns(FinchAPI::BaseClient::RequestInputShape)
     end
     private def build_request(req, opts)
     end
 
+    # @api private
     sig { params(headers: T::Hash[String, String], retry_count: Integer).returns(Float) }
     private def retry_delay(headers, retry_count:)
     end
 
+    # @api private
     sig do
       params(
         request: FinchAPI::BaseClient::RequestInputShape,
@@ -128,6 +149,8 @@ module FinchAPI
     private def send_request(request, redirect_count:, retry_count:, send_retry_header:)
     end
 
+    # Execute the request specified by `req`. This is the method that all resource
+    #   methods call into.
     sig do
       params(
         method: Symbol,
@@ -148,7 +171,7 @@ module FinchAPI
         page: T.nilable(T::Class[FinchAPI::BasePage[FinchAPI::BaseModel]]),
         stream: T.nilable(T::Class[T.anything]),
         model: T.nilable(FinchAPI::Converter::Input),
-        options: T.nilable(T.any(FinchAPI::RequestOptions, T::Hash[Symbol, T.anything]))
+        options: T.nilable(T.any(FinchAPI::RequestOptions, FinchAPI::Util::AnyHash))
       )
         .returns(T.anything)
     end