knockapi 0.6.1 → 1.0.0

data/rbi/knockapi/internal/transport/base_client.rbi

@@ -0,0 +1,213 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Transport
+      # @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(
+                T.any(
+                  Symbol,
+                  Integer,
+                  T::Array[T.any(Symbol, Integer)],
+                  T.proc.params(arg0: T.anything).returns(T.anything)
+                )
+              ),
+              page: T.nilable(T::Class[Knockapi::Internal::Type::BasePage[Knockapi::Internal::Type::BaseModel]]),
+              stream: T.nilable(T::Class[T.anything]),
+              model: T.nilable(Knockapi::Internal::Type::Converter::Input),
+              options: T.nilable(Knockapi::RequestOpts)
+            }
+          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]
+
+        class << self
+          # @api private
+          sig { params(req: Knockapi::Internal::Transport::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: Knockapi::Internal::Transport::BaseClient::RequestInputShape,
+              status: Integer,
+              response_headers: T.any(T::Hash[String, String], Net::HTTPHeader)
+            )
+              .returns(Knockapi::Internal::Transport::BaseClient::RequestInputShape)
+          end
+          def follow_redirect(request, status:, response_headers:); end
+
+          # @api private
+          sig do
+            params(
+              status: T.any(Integer, Knockapi::Errors::APIConnectionError),
+              stream: T.nilable(T::Enumerable[String])
+            )
+              .void
+          end
+          def reap_connection!(status, stream:); end
+        end
+
+        # @api private
+        sig { returns(Knockapi::Internal::Transport::PooledNetRequester) }
+        attr_reader :requester
+
+        # @api private
+        sig do
+          params(
+            base_url: String,
+            timeout: Float,
+            max_retries: Integer,
+            initial_retry_delay: Float,
+            max_retry_delay: Float,
+            headers: T::Hash[String,
+                             T.nilable(T.any(String, Integer, T::Array[T.nilable(T.any(String, Integer))]))],
+            idempotency_header: T.nilable(String)
+          )
+            .returns(T.attached_class)
+        end
+        def self.new(
+          base_url:,
+          timeout: 0.0,
+          max_retries: 0,
+          initial_retry_delay: 0.0,
+          max_retry_delay: 0.0,
+          headers: {},
+          idempotency_header: nil
+        ); 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: Knockapi::Internal::Transport::BaseClient::RequestComponentsShape,
+              opts: Knockapi::Internal::AnyHash
+            )
+            .returns(Knockapi::Internal::Transport::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: Knockapi::Internal::Transport::BaseClient::RequestInputShape,
+            redirect_count: Integer,
+            retry_count: Integer,
+            send_retry_header: T::Boolean
+          )
+            .returns([Integer, Net::HTTPResponse, T::Enumerable[String]])
+        end
+        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.
+        #
+        # @overload request(method, path, query: {}, headers: {}, body: nil, unwrap: nil, page: nil, stream: nil, model: Knockapi::Internal::Type::Unknown, options: {})
+        sig do
+          params(
+            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[Knockapi::Internal::Type::BasePage[Knockapi::Internal::Type::BaseModel]]),
+            stream: T.nilable(T::Class[T.anything]),
+            model: T.nilable(Knockapi::Internal::Type::Converter::Input),
+            options: T.nilable(Knockapi::RequestOpts)
+          )
+            .returns(T.anything)
+        end
+        def request(
+          method,
+          path,
+          query: {},
+          headers: {},
+          body: nil,
+          unwrap: nil,
+          page: nil,
+          stream: nil,
+          model: Knockapi::Internal::Type::Unknown,
+          options: {}
+        ); end
+        # @api private
+        sig { returns(String) }
+        def inspect; end
+      end
+    end
+  end
+end

data/rbi/knockapi/internal/transport/pooled_net_requester.rbi

@@ -0,0 +1,60 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Transport
+      # @api private
+      class PooledNetRequester
+        RequestShape =
+          T.type_alias do
+            {
+              method: Symbol,
+              url: URI::Generic,
+              headers: T::Hash[String, String],
+              body: T.anything,
+              deadline: Float
+            }
+          end
+
+        # from the golang stdlib
+        # https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
+        KEEP_ALIVE_TIMEOUT = 30
+
+        class << self
+          # @api private
+          sig { params(url: URI::Generic).returns(Net::HTTP) }
+          def connect(url); end
+
+          # @api private
+          sig { params(conn: Net::HTTP, deadline: Float).void }
+          def calibrate_socket_timeout(conn, deadline); end
+
+          # @api private
+          sig do
+            params(
+              request: Knockapi::Internal::Transport::PooledNetRequester::RequestShape,
+              blk: T.proc.params(arg0: String).void
+            )
+              .returns([Net::HTTPGenericRequest, T.proc.void])
+          end
+          def build_request(request, &blk); end
+        end
+
+        # @api private
+        sig { params(url: URI::Generic, deadline: Float, blk: T.proc.params(arg0: Net::HTTP).void).void }
+        private def with_pool(url, deadline:, &blk); end
+
+        # @api private
+        sig do
+          params(request: Knockapi::Internal::Transport::PooledNetRequester::RequestShape)
+            .returns([Integer, Net::HTTPResponse, T::Enumerable[String]])
+        end
+        def execute(request); end
+
+        # @api private
+        sig { params(size: Integer).returns(T.attached_class) }
+        def self.new(size: Etc.nprocessors); end
+      end
+    end
+  end
+end

data/rbi/knockapi/internal/type/array_of.rbi

@@ -0,0 +1,88 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      # @api private
+      #
+      # Array of items of a given type.
+      class ArrayOf
+        include Knockapi::Internal::Type::Converter
+
+        abstract!
+
+        Elem = type_member(:out)
+
+        sig do
+          params(
+            type_info: T.any(
+              Knockapi::Internal::AnyHash,
+              T.proc.returns(Knockapi::Internal::Type::Converter::Input),
+              Knockapi::Internal::Type::Converter::Input
+            ),
+            spec: Knockapi::Internal::AnyHash
+          )
+            .returns(T.attached_class)
+        end
+        def self.[](type_info, spec = {}); end
+
+        sig { params(other: T.anything).returns(T::Boolean) }
+        def ===(other); end
+
+        sig { params(other: T.anything).returns(T::Boolean) }
+        def ==(other); end
+
+        sig { returns(Integer) }
+        def hash; end
+
+        # @api private
+        sig do
+          override
+            .params(
+              value: T.any(T::Array[T.anything], T.anything),
+              state: Knockapi::Internal::Type::Converter::CoerceState
+            )
+            .returns(T.any(T::Array[T.anything], T.anything))
+        end
+        def coerce(value, state:); end
+
+        # @api private
+        sig do
+          override
+            .params(
+              value: T.any(T::Array[T.anything], T.anything),
+              state: Knockapi::Internal::Type::Converter::DumpState
+            )
+            .returns(T.any(T::Array[T.anything], T.anything))
+        end
+        def dump(value, state:); end
+
+        # @api private
+        sig { returns(Elem) }
+        protected def item_type; end
+
+        # @api private
+        sig { returns(T::Boolean) }
+        protected def nilable?; end
+
+        # @api private
+        sig do
+          params(
+            type_info: T.any(
+              Knockapi::Internal::AnyHash,
+              T.proc.returns(Knockapi::Internal::Type::Converter::Input),
+              Knockapi::Internal::Type::Converter::Input
+            ),
+            spec: Knockapi::Internal::AnyHash
+          )
+            .void
+        end
+        def initialize(type_info, spec = {}); end
+
+        # @api private
+        sig { params(depth: Integer).returns(String) }
+        def inspect(depth: 0); end
+      end
+    end
+  end
+end

data/rbi/knockapi/internal/type/base_model.rbi

@@ -0,0 +1,219 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      class BaseModel
+        extend Knockapi::Internal::Type::Converter
+
+        abstract!
+
+        KnownFieldShape = T.type_alias do
+          {mode: T.nilable(Symbol), required: T::Boolean, nilable: T::Boolean}
+        end
+
+        class << self
+          # @api private
+          #
+          # Assumes superclass fields are totally defined before fields are accessed /
+          # defined on subclasses.
+          sig do
+            returns(
+              T::Hash[
+                Symbol,
+                T.all(
+                  Knockapi::Internal::Type::BaseModel::KnownFieldShape,
+                  {type_fn: T.proc.returns(Knockapi::Internal::Type::Converter::Input)}
+                )
+              ]
+            )
+          end
+          def known_fields; end
+
+          # @api private
+          sig do
+            returns(
+              T::Hash[
+                Symbol,
+                T.all(
+                  Knockapi::Internal::Type::BaseModel::KnownFieldShape,
+                  {type: Knockapi::Internal::Type::Converter::Input}
+                )
+              ]
+            )
+          end
+          def fields; end
+
+          # @api private
+          sig do
+            params(
+              name_sym: Symbol,
+              required: T::Boolean,
+              type_info: T.any(
+                {
+                  const: T.nilable(T.any(NilClass, T::Boolean, Integer, Float, Symbol)),
+                  enum: T.nilable(T.proc.returns(Knockapi::Internal::Type::Converter::Input)),
+                  union: T.nilable(T.proc.returns(Knockapi::Internal::Type::Converter::Input)),
+                  api_name: Symbol,
+                  nil?: T::Boolean
+                },
+                T.proc.returns(Knockapi::Internal::Type::Converter::Input),
+                Knockapi::Internal::Type::Converter::Input
+              ),
+              spec: Knockapi::Internal::AnyHash
+            )
+              .void
+          end
+          private def add_field(name_sym, required:, type_info:, spec:); end
+
+          # @api private
+          sig do
+            params(
+              name_sym: Symbol,
+              type_info: T.any(
+                Knockapi::Internal::AnyHash,
+                T.proc.returns(Knockapi::Internal::Type::Converter::Input),
+                Knockapi::Internal::Type::Converter::Input
+              ),
+              spec: Knockapi::Internal::AnyHash
+            )
+              .void
+          end
+          def required(name_sym, type_info, spec = {}); end
+
+          # @api private
+          sig do
+            params(
+              name_sym: Symbol,
+              type_info: T.any(
+                Knockapi::Internal::AnyHash,
+                T.proc.returns(Knockapi::Internal::Type::Converter::Input),
+                Knockapi::Internal::Type::Converter::Input
+              ),
+              spec: Knockapi::Internal::AnyHash
+            )
+              .void
+          end
+          def optional(name_sym, type_info, spec = {}); end
+
+          # @api private
+          #
+          # `request_only` attributes not excluded from `.#coerce` when receiving responses
+          # even if well behaved servers should not send them
+          sig { params(blk: T.proc.void).void }
+          private def request_only(&blk); end
+
+          # @api private
+          #
+          # `response_only` attributes are omitted from `.#dump` when making requests
+          sig { params(blk: T.proc.void).void }
+          private def response_only(&blk); end
+
+          sig { params(other: T.anything).returns(T::Boolean) }
+          def ==(other); end
+
+          sig { returns(Integer) }
+          def hash; end
+        end
+
+        sig { params(other: T.anything).returns(T::Boolean) }
+        def ==(other); end
+
+        sig { returns(Integer) }
+        def hash; end
+
+        class << self
+          # @api private
+          sig do
+            override
+              .params(
+                value: T.any(
+                  Knockapi::Internal::Type::BaseModel,
+                  T::Hash[T.anything, T.anything],
+                  T.anything
+                ),
+                state: Knockapi::Internal::Type::Converter::CoerceState
+              )
+              .returns(T.any(T.attached_class, T.anything))
+          end
+          def coerce(value, state:); end
+
+          # @api private
+          sig do
+            override
+              .params(value: T.any(
+                T.attached_class,
+                T.anything
+              ),
+                      state: Knockapi::Internal::Type::Converter::DumpState)
+              .returns(T.any(T::Hash[T.anything, T.anything], T.anything))
+          end
+          def dump(value, state:); end
+        end
+
+        # Returns the raw value associated with the given key, if found. Otherwise, nil is
+        # returned.
+        #
+        # It is valid to lookup keys that are not in the API spec, for example to access
+        # undocumented features. This method does not parse response data into
+        # higher-level types. Lookup by anything other than a Symbol is an ArgumentError.
+        sig { params(key: Symbol).returns(T.nilable(T.anything)) }
+        def [](key); end
+
+        # 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
+        # value indicates which values were ever set on the object. i.e. there will be a
+        # key in this hash if they ever were, even if the set value was nil.
+        #
+        # This method is not recursive. The returned value is shared by the object, so it
+        # should not be mutated.
+        sig { overridable.returns(Knockapi::Internal::AnyHash) }
+        def to_h; end
+
+        # 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
+        # value indicates which values were ever set on the object. i.e. there will be a
+        # key in this hash if they ever were, even if the set value was nil.
+        #
+        # This method is not recursive. The returned value is shared by the object, so it
+        # should not be mutated.
+        sig { overridable.returns(Knockapi::Internal::AnyHash) }
+        def to_hash; end
+
+        sig { params(keys: T.nilable(T::Array[Symbol])).returns(Knockapi::Internal::AnyHash) }
+        def deconstruct_keys(keys); end
+
+        class << self
+          # @api private
+          sig { params(model: Knockapi::Internal::Type::BaseModel).returns(Knockapi::Internal::AnyHash) }
+          def walk(model); end
+        end
+
+        sig { params(a: T.anything).returns(String) }
+        def to_json(*a); end
+
+        sig { params(a: T.anything).returns(String) }
+        def to_yaml(*a); end
+
+        # Create a new instance of a model.
+        sig { params(data: T.any(T::Hash[Symbol, T.anything], T.self_type)).returns(T.attached_class) }
+        def self.new(data = {}); end
+
+        class << self
+          # @api private
+          sig { params(depth: Integer).returns(String) }
+          def inspect(depth: 0); end
+        end
+
+        sig { returns(String) }
+        def to_s; end
+
+        # @api private
+        sig { returns(String) }
+        def inspect; end
+      end
+    end
+  end
+end

data/rbi/knockapi/internal/type/base_page.rbi

@@ -0,0 +1,38 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      # @api private
+      #
+      # This module provides a base implementation for paginated responses in the SDK.
+      module BasePage
+        Elem = type_member(:out)
+
+        sig { overridable.returns(T::Boolean) }
+        def next_page?; end
+
+        sig { overridable.returns(T.self_type) }
+        def next_page; end
+
+        sig { overridable.params(blk: T.proc.params(arg0: Elem).void).void }
+        def auto_paging_each(&blk); end
+
+        sig { returns(T::Enumerable[Elem]) }
+        def to_enum; end
+
+        # @api private
+        sig do
+          params(
+            client: Knockapi::Internal::Transport::BaseClient,
+            req: Knockapi::Internal::Transport::BaseClient::RequestComponentsShape,
+            headers: T.any(T::Hash[String, String], Net::HTTPHeader),
+            page_data: T.anything
+          )
+            .void
+        end
+        def initialize(client:, req:, headers:, page_data:); end
+      end
+    end
+  end
+end

data/rbi/knockapi/internal/type/boolean.rbi

@@ -0,0 +1,48 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      # @api private
+      #
+      # Ruby has no Boolean class; this is something for models to refer to.
+      class Boolean
+        extend Knockapi::Internal::Type::Converter
+
+        abstract!
+
+        sig { params(other: T.anything).returns(T::Boolean) }
+        def self.===(other); end
+
+        sig { params(other: T.anything).returns(T::Boolean) }
+        def self.==(other); end
+
+        class << self
+          # @api private
+          sig do
+            override
+              .params(value: T.any(
+                T::Boolean,
+                T.anything
+              ),
+                      state: Knockapi::Internal::Type::Converter::CoerceState)
+              .returns(T.any(T::Boolean, T.anything))
+          end
+          def coerce(value, state:); end
+
+          # @api private
+          sig do
+            override
+              .params(value: T.any(
+                T::Boolean,
+                T.anything
+              ),
+                      state: Knockapi::Internal::Type::Converter::DumpState)
+              .returns(T.any(T::Boolean, T.anything))
+          end
+          def dump(value, state:); end
+        end
+      end
+    end
+  end
+end