knockapi 0.6.1 → 1.0.0

data/rbi/knockapi/internal/type/converter.rbi

@@ -0,0 +1,120 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      # @api private
+      module Converter
+        Input = T.type_alias { T.any(Knockapi::Internal::Type::Converter, T::Class[T.anything]) }
+
+        CoerceState =
+          T.type_alias do
+            {
+              strictness: T.any(T::Boolean, Symbol),
+              exactness: {yes: Integer, no: Integer, maybe: Integer},
+              branched: Integer
+            }
+          end
+
+        DumpState = T.type_alias { {can_retry: T::Boolean} }
+
+        # @api private
+        sig do
+          overridable
+            .params(value: T.anything, state: Knockapi::Internal::Type::Converter::CoerceState)
+            .returns(T.anything)
+        end
+        def coerce(value, state:); end
+
+        # @api private
+        sig do
+          overridable
+            .params(value: T.anything, state: Knockapi::Internal::Type::Converter::DumpState)
+            .returns(T.anything)
+        end
+        def dump(value, state:); end
+
+        # @api private
+        sig { params(depth: Integer).returns(String) }
+        def inspect(depth: 0); end
+
+        class << self
+          # @api private
+          sig do
+            params(
+              spec: 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))
+                },
+                T.proc.returns(Knockapi::Internal::Type::Converter::Input),
+                Knockapi::Internal::Type::Converter::Input
+              )
+            )
+              .returns(T.proc.returns(T.anything))
+          end
+          def self.type_info(spec); end
+
+          # @api private
+          #
+          # Based on `target`, transform `value` into `target`, to the extent possible:
+          #
+          # 1. if the given `value` conforms to `target` already, return the given `value`
+          # 2. if it's possible and safe to convert the given `value` to `target`, then the
+          #    converted value
+          # 3. otherwise, the given `value` unaltered
+          #
+          # 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: Knockapi::Internal::Type::Converter::Input,
+              value: T.anything,
+              state: Knockapi::Internal::Type::Converter::CoerceState
+            )
+              .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 do
+            params(
+              target: Knockapi::Internal::Type::Converter::Input,
+              value: T.anything,
+              state: Knockapi::Internal::Type::Converter::DumpState
+            )
+              .returns(T.anything)
+          end
+          def self.dump(target, value, state: {can_retry: true}); end
+
+          # @api private
+          sig { params(target: T.anything, depth: Integer).returns(String) }
+          def self.inspect(target, depth:); end
+        end
+      end
+    end
+  end
+end

data/rbi/knockapi/internal/type/enum.rbi

@@ -0,0 +1,64 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      # @api private
+      #
+      # A value from among a specified list of options. OpenAPI enum values map to Ruby
+      # values in the SDK as follows:
+      #
+      # 1. boolean => true | false
+      # 2. integer => Integer
+      # 3. float => Float
+      # 4. string => Symbol
+      #
+      # We can therefore convert string values to Symbols, but can't convert other
+      # values safely.
+      module Enum
+        include Knockapi::Internal::Type::Converter
+
+        # All of the valid Symbol values for this enum.
+        sig { overridable.returns(T::Array[T.any(NilClass, T::Boolean, Integer, Float, Symbol)]) }
+        def values; 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
+        #
+        # 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: Knockapi::Internal::Type::Converter::CoerceState)
+            .returns(T.any(Symbol, T.anything))
+        end
+        def coerce(value, state:); end
+
+        # @api private
+        sig do
+          override
+            .params(value: T.any(Symbol, T.anything), state: Knockapi::Internal::Type::Converter::DumpState)
+            .returns(T.any(Symbol, T.anything))
+        end
+        def dump(value, state:); end
+
+        # @api private
+        sig { params(depth: Integer).returns(String) }
+        def inspect(depth: 0); end
+      end
+    end
+  end
+end

data/rbi/knockapi/internal/type/file_input.rbi

@@ -0,0 +1,50 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      # @api private
+      #
+      # Either `Pathname` or `StringIO`, or `IO`, or
+      # `Knockapi::Internal::Type::FileInput`.
+      #
+      # Note: when `IO` is used, all retries are disabled, since many IO` streams are
+      # not rewindable.
+      class FileInput
+        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(StringIO, String, T.anything),
+                state: Knockapi::Internal::Type::Converter::CoerceState
+              )
+              .returns(T.any(StringIO, T.anything))
+          end
+          def coerce(value, state:); end
+
+          # @api private
+          sig do
+            override
+              .params(
+                value: T.any(Pathname, StringIO, IO, String, T.anything),
+                state: Knockapi::Internal::Type::Converter::DumpState
+              )
+              .returns(T.any(Pathname, StringIO, IO, String, T.anything))
+          end
+          def dump(value, state:); end
+        end
+      end
+    end
+  end
+end

data/rbi/knockapi/internal/type/hash_of.rbi

@@ -0,0 +1,88 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      # @api private
+      #
+      # Hash of items of a given type.
+      class HashOf
+        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::Hash[T.anything, T.anything], T.anything),
+              state: Knockapi::Internal::Type::Converter::CoerceState
+            )
+            .returns(T.any(Knockapi::Internal::AnyHash, T.anything))
+        end
+        def coerce(value, state:); end
+
+        # @api private
+        sig do
+          override
+            .params(
+              value: T.any(T::Hash[T.anything, T.anything], T.anything),
+              state: Knockapi::Internal::Type::Converter::DumpState
+            )
+            .returns(T.any(Knockapi::Internal::AnyHash, 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/request_parameters.rbi

@@ -0,0 +1,21 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      # @api private
+      module RequestParameters
+        # Options to specify HTTP behaviour for this request.
+        sig { returns(Knockapi::RequestOpts) }
+        attr_accessor :request_options
+
+        # @api private
+        module Converter
+          # @api private
+          sig { params(params: T.anything).returns([T.anything, Knockapi::Internal::AnyHash]) }
+          def dump_request(params); end
+        end
+      end
+    end
+  end
+end

data/rbi/knockapi/internal/type/union.rbi

@@ -0,0 +1,75 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      # @api private
+      module Union
+        include Knockapi::Internal::Type::Converter
+
+        # @api private
+        #
+        # All of the specified variant info for this union.
+        sig do
+          returns(T::Array[[T.nilable(Symbol), T.proc.returns(Knockapi::Internal::Type::Converter::Input)]])
+        end
+        private def known_variants; end
+
+        # @api private
+        sig { returns(T::Array[[T.nilable(Symbol), T.anything]]) }
+        protected def derefed_variants; end
+
+        # All of the specified variants for this union.
+        sig { overridable.returns(T::Array[T.anything]) }
+        def variants; end
+
+        # @api private
+        sig { params(property: Symbol).void }
+        private def discriminator(property); end
+
+        # @api private
+        sig do
+          params(
+            key: T.any(Symbol, Knockapi::Internal::AnyHash, T.proc.returns(T.anything), T.anything),
+            spec: T.any(Knockapi::Internal::AnyHash, T.proc.returns(T.anything), T.anything)
+          )
+            .void
+        end
+        private def variant(key, spec = nil); end
+
+        # @api private
+        sig { params(value: T.anything).returns(T.nilable(T.anything)) }
+        private def resolve_variant(value); 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.anything, state: Knockapi::Internal::Type::Converter::CoerceState)
+            .returns(T.anything)
+        end
+        def coerce(value, state:); end
+
+        # @api private
+        sig do
+          override
+            .params(value: T.anything, state: Knockapi::Internal::Type::Converter::DumpState)
+            .returns(T.anything)
+        end
+        def dump(value, state:); end
+
+        # @api private
+        sig { params(depth: Integer).returns(String) }
+        def inspect(depth: 0); end
+      end
+    end
+  end
+end

data/rbi/knockapi/internal/type/unknown.rbi

@@ -0,0 +1,40 @@
+# typed: strong
+
+module Knockapi
+  module Internal
+    module Type
+      # @api private
+      #
+      # When we don't know what to expect for the value.
+      class Unknown
+        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.anything, state: Knockapi::Internal::Type::Converter::CoerceState)
+              .returns(T.anything)
+          end
+          def coerce(value, state:); end
+
+          # @api private
+          sig do
+            override
+              .params(value: T.anything, state: Knockapi::Internal::Type::Converter::DumpState)
+              .returns(T.anything)
+          end
+          def dump(value, state:); end
+        end
+      end
+    end
+  end
+end