lithic 0.1.0.pre.alpha.4 → 0.1.0.pre.alpha.6

data/rbi/lib/lithic/internal/type/array_of.rbi

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

data/rbi/lib/lithic/internal/type/base_model.rbi

@@ -0,0 +1,208 @@
+# typed: strong
+
+module Lithic
+  module Internal
+    module Type
+      class BaseModel
+        extend Lithic::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(
+                Lithic::Internal::Type::BaseModel::KnownFieldShape,
+                {type_fn: T.proc.returns(Lithic::Internal::Type::Converter::Input)}
+              )
+              ]
+            )
+          end
+          def known_fields
+          end
+
+          # @api private
+          sig do
+            returns(
+              T::Hash[
+              Symbol,
+              T.all(
+                Lithic::Internal::Type::BaseModel::KnownFieldShape,
+                {type: Lithic::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(Lithic::Internal::Type::Converter::Input)),
+                  union: T.nilable(T.proc.returns(Lithic::Internal::Type::Converter::Input)),
+                  api_name: Symbol,
+                  nil?: T::Boolean
+                },
+                T.proc.returns(Lithic::Internal::Type::Converter::Input),
+                Lithic::Internal::Type::Converter::Input
+              ),
+              spec: Lithic::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(
+                Lithic::Internal::AnyHash,
+                T.proc.returns(Lithic::Internal::Type::Converter::Input),
+                Lithic::Internal::Type::Converter::Input
+              ),
+              spec: Lithic::Internal::AnyHash
+            )
+              .void
+          end
+          def required(name_sym, type_info, spec = {})
+          end
+
+          # @api private
+          sig do
+            params(
+              name_sym: Symbol,
+              type_info: T.any(
+                Lithic::Internal::AnyHash,
+                T.proc.returns(Lithic::Internal::Type::Converter::Input),
+                Lithic::Internal::Type::Converter::Input
+              ),
+              spec: Lithic::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
+        end
+
+        sig { params(other: T.anything).returns(T::Boolean) }
+        def ==(other)
+        end
+
+        class << self
+          # @api private
+          sig do
+            override
+              .params(
+                value: T.any(Lithic::Internal::Type::BaseModel, T::Hash[T.anything, T.anything], T.anything),
+                state: Lithic::Internal::Type::Converter::State
+              )
+              .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))
+              .returns(T.any(T::Hash[T.anything, T.anything], T.anything))
+          end
+          def dump(value)
+          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(Lithic::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(Lithic::Internal::AnyHash) }
+        def to_hash
+        end
+
+        sig { params(keys: T.nilable(T::Array[Symbol])).returns(Lithic::Internal::AnyHash) }
+        def deconstruct_keys(keys)
+        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
+
+        sig { returns(String) }
+        def inspect
+        end
+      end
+    end
+  end
+end

data/rbi/lib/lithic/internal/type/base_page.rbi

@@ -0,0 +1,41 @@
+# typed: strong
+
+module Lithic
+  module Internal
+    module Type
+      # 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: Lithic::Internal::Transport::BaseClient,
+            req: Lithic::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/lib/lithic/internal/type/boolean.rbi

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

data/rbi/lib/lithic/internal/type/converter.rbi

@@ -0,0 +1,108 @@
+# typed: strong
+
+module Lithic
+  module Internal
+    module Type
+      # @api private
+      module Converter
+        Input = T.type_alias { T.any(Lithic::Internal::Type::Converter, T::Class[T.anything]) }
+
+        State =
+          T.type_alias do
+            {
+              strictness: T.any(T::Boolean, Symbol),
+              exactness: {yes: Integer, no: Integer, maybe: Integer},
+              branched: Integer
+            }
+          end
+
+        # @api private
+        sig do
+          overridable.params(
+            value: T.anything,
+            state: Lithic::Internal::Type::Converter::State
+          ).returns(T.anything)
+        end
+        def coerce(value, state:)
+        end
+
+        # @api private
+        sig { overridable.params(value: T.anything).returns(T.anything) }
+        def dump(value)
+        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(Lithic::Internal::Type::Converter::Input)),
+                  union: T.nilable(T.proc.returns(Lithic::Internal::Type::Converter::Input))
+                },
+                T.proc.returns(Lithic::Internal::Type::Converter::Input),
+                Lithic::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: Lithic::Internal::Type::Converter::Input,
+              value: T.anything,
+              state: Lithic::Internal::Type::Converter::State
+            )
+              .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: Lithic::Internal::Type::Converter::Input, value: T.anything).returns(T.anything)
+          end
+          def self.dump(target, value)
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/lib/lithic/internal/type/enum.rbi

@@ -0,0 +1,60 @@
+# typed: strong
+
+module Lithic
+  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 Lithic::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
+
+        # @api private
+        #
+        # Guard against thread safety issues by instantiating `@values`.
+        sig { void }
+        private def finalize!
+        end
+
+        sig { params(other: T.anything).returns(T::Boolean) }
+        def ===(other)
+        end
+
+        sig { params(other: T.anything).returns(T::Boolean) }
+        def ==(other)
+        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: Lithic::Internal::Type::Converter::State)
+            .returns(T.any(Symbol, T.anything))
+        end
+        def coerce(value, state:)
+        end
+
+        # @api private
+        sig { override.params(value: T.any(Symbol, T.anything)).returns(T.any(Symbol, T.anything)) }
+        def dump(value)
+        end
+      end
+    end
+  end
+end

data/rbi/lib/lithic/internal/type/hash_of.rbi

@@ -0,0 +1,87 @@
+# typed: strong
+
+module Lithic
+  module Internal
+    module Type
+      # @api private
+      #
+      # Hash of items of a given type.
+      class HashOf
+        include Lithic::Internal::Type::Converter
+
+        abstract!
+        final!
+
+        Elem = type_member(:out)
+
+        sig(:final) do
+          params(
+            type_info: T.any(
+              Lithic::Internal::AnyHash,
+              T.proc.returns(Lithic::Internal::Type::Converter::Input),
+              Lithic::Internal::Type::Converter::Input
+            ),
+            spec: Lithic::Internal::AnyHash
+          )
+            .returns(T.attached_class)
+        end
+        def self.[](type_info, spec = {})
+        end
+
+        sig(:final) { params(other: T.anything).returns(T::Boolean) }
+        def ===(other)
+        end
+
+        sig(:final) { params(other: T.anything).returns(T::Boolean) }
+        def ==(other)
+        end
+
+        # @api private
+        sig(:final) do
+          override
+            .params(
+              value: T.any(T::Hash[T.anything, T.anything], T.anything),
+              state: Lithic::Internal::Type::Converter::State
+            )
+            .returns(T.any(Lithic::Internal::AnyHash, T.anything))
+        end
+        def coerce(value, state:)
+        end
+
+        # @api private
+        sig(:final) do
+          override
+            .params(value: T.any(T::Hash[T.anything, T.anything], T.anything))
+            .returns(T.any(Lithic::Internal::AnyHash, T.anything))
+        end
+        def dump(value)
+        end
+
+        # @api private
+        sig(:final) { returns(Elem) }
+        protected def item_type
+        end
+
+        # @api private
+        sig(:final) { returns(T::Boolean) }
+        protected def nilable?
+        end
+
+        # @api private
+        sig(:final) do
+          params(
+            type_info: T.any(
+              Lithic::Internal::AnyHash,
+              T.proc.returns(Lithic::Internal::Type::Converter::Input),
+              Lithic::Internal::Type::Converter::Input
+            ),
+            spec: Lithic::Internal::AnyHash
+          )
+            .void
+        end
+        def initialize(type_info, spec = {})
+        end
+      end
+    end
+  end
+end

data/rbi/lib/lithic/internal/type/request_parameters.rbi

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