lithic 0.1.0.pre.alpha.22 → 0.1.0.pre.alpha.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9def0867c0819d94f1af8b057db5bfdd1fb0f3fab5eb089a6550b2de044252ad
-  data.tar.gz: d431118e6f871c486da62b7c2c131a490eab1ac55c275121e2707b7638149fb4
+  metadata.gz: ba4b2ced2860455f74eec19b5b828190d4159cb4e1d3e7a985ebfc0bf6740c66
+  data.tar.gz: c07e21c629b95ed6e9384bb7de2a5a610a6c23db9b6a5dc37472ad089678ee38
 SHA512:
-  metadata.gz: ba358fa04bbd267e34807bec11bd6c1dacfe6cf5590bf91182523fda78291211bc3d39c88cad331d768215f4e358b5fedfddc8cd52c0f676edef842dd548646b
-  data.tar.gz: bcb3cb2c1e2ba111d5d1b14e82dfdcc0120a8c3d0806b36648fa767884ada73c7ac49c7e63b1f2d9156330c097c1ba7ccd3429b775b084243408babe23d09756
+  metadata.gz: 512ce892a78e39108a9773771eca855ea47a6fd300728b54635eadfc526530330f7055b6d8982499f29d64c3b523b724982456262faa6bea5761f9d6d06c153c
+  data.tar.gz: d31695bd240b2563752cf7a4f57a451168c249fadcfe220341c491a04da2f4b7e124583efda729e27afce7e05b4e8c5210b7e55bad721821e8d5cbe7363d7d17

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.1.0-alpha.24 (2025-05-12)
+
+Full Changelog: [v0.1.0-alpha.23...v0.1.0-alpha.24](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0-alpha.23...v0.1.0-alpha.24)
+
+### Features
+
+* **api:** manual updates ([2190d4d](https://github.com/lithic-com/lithic-ruby/commit/2190d4d4b9efc8b24cefeb0c8f6e011821f012a6))
+* expose base client options as read only attributes ([6aa1141](https://github.com/lithic-com/lithic-ruby/commit/6aa1141978a57e8d138e182c7f5dd6f1135e2106))
+* expose recursive `#to_h` conversion ([0d2635e](https://github.com/lithic-com/lithic-ruby/commit/0d2635eaf67be12441797b0d067b618b3e2cb076))
+* support sorbet aliases at the runtime ([aeb0c42](https://github.com/lithic-com/lithic-ruby/commit/aeb0c4266234c86ac7b36b46ddbc6dc956faa599))
+
+
+### Chores
+
+* fix misc linting / minor issues ([5b17b81](https://github.com/lithic-com/lithic-ruby/commit/5b17b8150b6eeed2e347960e2f5e86093b391a97))
+
+
+### Documentation
+
+* remove or fix invalid readme examples ([a533c26](https://github.com/lithic-com/lithic-ruby/commit/a533c267af8a88c539880430ce6616a1387425ff))
+
+## 0.1.0-alpha.23 (2025-05-07)
+
+Full Changelog: [v0.1.0-alpha.22...v0.1.0-alpha.23](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0-alpha.22...v0.1.0-alpha.23)
+
+### Bug Fixes
+
+* **internal:** ensure formatting always uses c.utf-8 locale ([00adb12](https://github.com/lithic-com/lithic-ruby/commit/00adb12df89392abd69ff031938647b65f124442))
+
 ## 0.1.0-alpha.22 (2025-05-06)
 
 Full Changelog: [v0.1.0-alpha.21...v0.1.0-alpha.22](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0-alpha.21...v0.1.0-alpha.22)

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "lithic", "~> 0.1.0.pre.alpha.22"
+gem "lithic", "~> 0.1.0.pre.alpha.24"
 ```
 
 <!-- x-release-please-end -->
@@ -71,7 +71,7 @@ When the library is unable to connect to the API, or if the API returns a non-su
 
 ```ruby
 begin
-  card = lithic.cards.create(type: "an_incorrect_type")
+  card = lithic.cards.create(type: "MERCHANT_LOCKED")
 rescue Lithic::Errors::APIError => e
   puts(e.status) # 400
 end
@@ -192,9 +192,9 @@ Sorbet's typed enums require sub-classing of the [`T::Enum` class](https://sorbe
 Since this library does not depend on `sorbet-runtime`, it uses a [`T.all` intersection type](https://sorbet.org/docs/intersection-types) with a ruby primitive type to construct a "tagged alias" instead.
 
 ```ruby
-module Lithic::Models::AccountFinancialAccountType
+module Lithic::AccountFinancialAccountType
   # This alias aids language service driven navigation.
-  TaggedSymbol = T.type_alias { T.all(Symbol, Lithic::Models::AccountFinancialAccountType) }
+  TaggedSymbol = T.type_alias { T.all(Symbol, Lithic::AccountFinancialAccountType) }
 end
 ```
 

data/lib/lithic/client.rb

@@ -104,16 +104,11 @@ module Lithic
     #
     # @param request_options [Lithic::RequestOptions, Hash{Symbol=>Object}, nil]
     #
-    # @return [Lithic::Models::APIStatus]
+    # @return [Lithic::APIStatus]
     #
     # @see Lithic::Models::ClientAPIStatusParams
     def api_status(params = {})
-      request(
-        method: :get,
-        path: "v1/status",
-        model: Lithic::Models::APIStatus,
-        options: params[:request_options]
-      )
+      request(method: :get, path: "v1/status", model: Lithic::APIStatus, options: params[:request_options])
     end
 
     # @api private

data/lib/lithic/errors.rb

@@ -99,7 +99,7 @@ module Lithic
       # @param response [nil]
       # @param message [String, nil]
       #
-      # @return [Lithic::Errors::APIStatusError]
+      # @return [self]
       def self.for(url:, status:, body:, request:, response:, message: nil)
         kwargs = {
           url: url,

data/lib/lithic/file_part.rb

@@ -45,9 +45,9 @@ module Lithic
       @filename =
         case content
         in Pathname
-          filename.nil? ? content.basename.to_path : File.basename(filename)
+          filename.nil? ? content.basename.to_path : ::File.basename(filename)
         else
-          filename.nil? ? nil : File.basename(filename)
+          filename.nil? ? nil : ::File.basename(filename)
         end
       @content_type = content_type
     end

data/lib/lithic/internal/transport/base_client.rb

@@ -7,6 +7,8 @@ module Lithic
       #
       # @abstract
       class BaseClient
+        extend Lithic::Internal::Util::SorbetRuntimeSupport
+
         # from whatwg fetch spec
         MAX_REDIRECTS = 20
 
@@ -151,6 +153,27 @@ module Lithic
           end
         end
 
+        # @return [URI::Generic]
+        attr_reader :base_url
+
+        # @return [Float]
+        attr_reader :timeout
+
+        # @return [Integer]
+        attr_reader :max_retries
+
+        # @return [Float]
+        attr_reader :initial_retry_delay
+
+        # @return [Float]
+        attr_reader :max_retry_delay
+
+        # @return [Hash{String=>String}]
+        attr_reader :headers
+
+        # @return [String, nil]
+        attr_reader :idempotency_header
+
         # @api private
         # @return [Lithic::Internal::Transport::PooledNetRequester]
         attr_reader :requester
@@ -182,10 +205,11 @@ module Lithic
             },
             headers
           )
-          @base_url = Lithic::Internal::Util.parse_uri(base_url)
+          @base_url_components = Lithic::Internal::Util.parse_uri(base_url)
+          @base_url = Lithic::Internal::Util.unparse_uri(@base_url_components)
           @idempotency_header = idempotency_header&.to_s&.downcase
-          @max_retries = max_retries
           @timeout = timeout
+          @max_retries = max_retries
           @initial_retry_delay = initial_retry_delay
           @max_retry_delay = max_retry_delay
         end
@@ -276,10 +300,14 @@ module Lithic
               Lithic::Internal::Util.deep_merge(*[req[:body], opts[:extra_body]].compact)
             end
 
+          url = Lithic::Internal::Util.join_parsed_uri(
+            @base_url_components,
+            {**req, path: path, query: query}
+          )
           headers, encoded = Lithic::Internal::Util.encode_content(headers, body)
           {
             method: method,
-            url: Lithic::Internal::Util.join_parsed_uri(@base_url, {**req, path: path, query: query}),
+            url: url,
             headers: headers,
             body: encoded,
             max_retries: opts.fetch(:max_retries, @max_retries),
@@ -473,10 +501,54 @@ module Lithic
         # @return [String]
         def inspect
           # rubocop:disable Layout/LineLength
-          base_url = Lithic::Internal::Util.unparse_uri(@base_url)
-          "#<#{self.class.name}:0x#{object_id.to_s(16)} base_url=#{base_url} max_retries=#{@max_retries} timeout=#{@timeout}>"
+          "#<#{self.class.name}:0x#{object_id.to_s(16)} base_url=#{@base_url} max_retries=#{@max_retries} timeout=#{@timeout}>"
           # rubocop:enable Layout/LineLength
         end
+
+        define_sorbet_constant!(:RequestComponents) do
+          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[Lithic::Internal::Type::BasePage[Lithic::Internal::Type::BaseModel]]),
+              stream: T.nilable(T::Class[T.anything]),
+              model: T.nilable(Lithic::Internal::Type::Converter::Input),
+              options: T.nilable(Lithic::RequestOptions::OrHash)
+            }
+          end
+        end
+        define_sorbet_constant!(:RequestInput) do
+          T.type_alias do
+            {
+              method: Symbol,
+              url: URI::Generic,
+              headers: T::Hash[String, String],
+              body: T.anything,
+              max_retries: Integer,
+              timeout: Float
+            }
+          end
+        end
       end
     end
   end

data/lib/lithic/internal/transport/pooled_net_requester.rb

@@ -5,6 +5,8 @@ module Lithic
     module Transport
       # @api private
       class PooledNetRequester
+        extend Lithic::Internal::Util::SorbetRuntimeSupport
+
         # from the golang stdlib
         # https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
         KEEP_ALIVE_TIMEOUT = 30
@@ -187,6 +189,18 @@ module Lithic
           @size = size
           @pools = {}
         end
+
+        define_sorbet_constant!(:Request) do
+          T.type_alias do
+            {
+              method: Symbol,
+              url: URI::Generic,
+              headers: T::Hash[String, String],
+              body: T.anything,
+              deadline: Float
+            }
+          end
+        end
       end
     end
   end

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

@@ -29,7 +29,7 @@ module Lithic
         #
         #   @option spec [Boolean] :"nil?"
         #
-        # @return [Lithic::Internal::Type::ArrayOf]
+        # @return [self]
         def self.[](...) = new(...)
 
         # @api public

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

@@ -6,6 +6,7 @@ module Lithic
       # @abstract
       class BaseModel
         extend Lithic::Internal::Type::Converter
+        extend Lithic::Internal::Util::SorbetRuntimeSupport
 
         class << self
           # @api private
@@ -13,11 +14,17 @@ module Lithic
           # Assumes superclass fields are totally defined before fields are accessed /
           # defined on subclasses.
           #
-          # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
-          def known_fields
-            @known_fields ||= (self < Lithic::Internal::Type::BaseModel ? superclass.known_fields.dup : {})
+          # @param child [Class<Lithic::Internal::Type::BaseModel>]
+          def inherited(child)
+            super
+            child.known_fields.replace(known_fields.dup)
           end
 
+          # @api private
+          #
+          # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+          def known_fields = @known_fields ||= {}
+
           # @api private
           #
           # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
@@ -199,7 +206,7 @@ module Lithic
           #
           #   @option state [Integer] :branched
           #
-          # @return [Lithic::Internal::Type::BaseModel, Object]
+          # @return [self, Object]
           def coerce(value, state:)
             exactness = state.fetch(:exactness)
 
@@ -258,7 +265,7 @@ module Lithic
 
           # @api private
           #
-          # @param value [Lithic::Internal::Type::BaseModel, Object]
+          # @param value [self, Object]
           #
           # @param state [Hash{Symbol=>Object}] .
           #
@@ -299,6 +306,39 @@ module Lithic
           end
         end
 
+        class << self
+          # @api private
+          #
+          # @param model [Lithic::Internal::Type::BaseModel]
+          # @param convert [Boolean]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def recursively_to_h(model, convert:)
+            rec = ->(x) do
+              case x
+              in Lithic::Internal::Type::BaseModel
+                if convert
+                  fields = x.class.known_fields
+                  x.to_h.to_h do |key, val|
+                    [key, rec.call(fields.key?(key) ? x.public_send(key) : val)]
+                  rescue Lithic::Errors::ConversionError
+                    [key, rec.call(val)]
+                  end
+                else
+                  rec.call(x.to_h)
+                end
+              in Hash
+                x.transform_values(&rec)
+              in Array
+                x.map(&rec)
+              else
+                x
+              end
+            end
+            rec.call(model)
+          end
+        end
+
         # @api public
         #
         # Returns the raw value associated with the given key, if found. Otherwise, nil is
@@ -335,6 +375,14 @@ module Lithic
 
         alias_method :to_hash, :to_h
 
+        # @api public
+        #
+        # In addition to the behaviour of `#to_h`, this method will recursively call
+        # `#to_h` on nested models.
+        #
+        # @return [Hash{Symbol=>Object}]
+        def deep_to_h = self.class.recursively_to_h(@data, convert: false)
+
         # @param keys [Array<Symbol>, nil]
         #
         # @return [Hash{Symbol=>Object}]
@@ -350,29 +398,6 @@ module Lithic
             .to_h
         end
 
-        class << self
-          # @api private
-          #
-          # @param model [Lithic::Internal::Type::BaseModel]
-          #
-          # @return [Hash{Symbol=>Object}]
-          def walk(model)
-            walk = ->(x) do
-              case x
-              in Lithic::Internal::Type::BaseModel
-                walk.call(x.to_h)
-              in Hash
-                x.transform_values(&walk)
-              in Array
-                x.map(&walk)
-              else
-                x
-              end
-            end
-            walk.call(model)
-          end
-        end
-
         # @api public
         #
         # @param a [Object]
@@ -418,12 +443,19 @@ module Lithic
         # @api public
         #
         # @return [String]
-        def to_s = self.class.walk(@data).to_s
+        def to_s = deep_to_h.to_s
 
         # @api private
         #
         # @return [String]
-        def inspect = "#<#{self.class}:0x#{object_id.to_s(16)} #{self}>"
+        def inspect
+          converted = self.class.recursively_to_h(self, convert: true)
+          "#<#{self.class}:0x#{object_id.to_s(16)} #{converted}>"
+        end
+
+        define_sorbet_constant!(:KnownField) do
+          T.type_alias { {mode: T.nilable(Symbol), required: T::Boolean, nilable: T::Boolean} }
+        end
       end
     end
   end

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

@@ -5,6 +5,8 @@ module Lithic
     module Type
       # @api private
       module Converter
+        extend Lithic::Internal::Util::SorbetRuntimeSupport
+
         # rubocop:disable Lint/UnusedMethodArgument
 
         # @api private
@@ -268,6 +270,22 @@ module Lithic
             end
           end
         end
+
+        define_sorbet_constant!(:Input) do
+          T.type_alias { T.any(Lithic::Internal::Type::Converter, T::Class[T.anything]) }
+        end
+        define_sorbet_constant!(:CoerceState) do
+          T.type_alias do
+            {
+              strictness: T.any(T::Boolean, Symbol),
+              exactness: {yes: Integer, no: Integer, maybe: Integer},
+              branched: Integer
+            }
+          end
+        end
+        define_sorbet_constant!(:DumpState) do
+          T.type_alias { {can_retry: T::Boolean} }
+        end
       end
     end
   end

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

@@ -17,11 +17,11 @@ module Lithic
       # values safely.
       #
       # @example
-      #   # `account_financial_account_type` is a `Lithic::Models::AccountFinancialAccountType`
+      #   # `account_financial_account_type` is a `Lithic::AccountFinancialAccountType`
       #   case account_financial_account_type
-      #   when Lithic::Models::AccountFinancialAccountType::ISSUING
+      #   when Lithic::AccountFinancialAccountType::ISSUING
       #     # ...
-      #   when Lithic::Models::AccountFinancialAccountType::OPERATING
+      #   when Lithic::AccountFinancialAccountType::OPERATING
       #     # ...
       #   else
       #     puts(account_financial_account_type)
@@ -38,6 +38,7 @@ module Lithic
       #   end
       module Enum
         include Lithic::Internal::Type::Converter
+        include Lithic::Internal::Util::SorbetRuntimeSupport
 
         # All of the valid Symbol values for this enum.
         #

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

@@ -29,7 +29,7 @@ module Lithic
         #
         #   @option spec [Boolean] :"nil?"
         #
-        # @return [Lithic::Internal::Type::HashOf]
+        # @return [self]
         def self.[](...) = new(...)
 
         # @api public

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

@@ -5,10 +5,10 @@ module Lithic
     module Type
       # @api private
       module RequestParameters
-        # @!parse
-        #   # Options to specify HTTP behaviour for this request.
-        #   # @return [Lithic::RequestOptions, Hash{Symbol=>Object}]
-        #   attr_accessor :request_options
+        # @!attribute request_options
+        # Options to specify HTTP behaviour for this request.
+        #
+        #   @return [Lithic::RequestOptions, Hash{Symbol=>Object}]
 
         # @param mod [Module]
         def self.included(mod)

data/lib/lithic/internal/type/union.rb

@@ -17,6 +17,7 @@ module Lithic
       #   end
       module Union
         include Lithic::Internal::Type::Converter
+        include Lithic::Internal::Util::SorbetRuntimeSupport
 
         # @api private
         #

data/lib/lithic/internal/util.rb

@@ -535,7 +535,7 @@ module Lithic
             filename = ERB::Util.url_encode(val.filename)
             y << "; filename=\"#{filename}\""
           in Pathname | IO
-            filename = ERB::Util.url_encode(File.basename(val.to_path))
+            filename = ERB::Util.url_encode(::File.basename(val.to_path))
             y << "; filename=\"#{filename}\""
           else
           end
@@ -801,6 +801,62 @@ module Lithic
           end
         end
       end
+
+      # @api private
+      module SorbetRuntimeSupport
+        class MissingSorbetRuntimeError < ::RuntimeError
+        end
+
+        # @api private
+        #
+        # @return [Hash{Symbol=>Object}]
+        private def sorbet_runtime_constants = @sorbet_runtime_constants ||= {}
+
+        # @api private
+        #
+        # @param name [Symbol]
+        def const_missing(name)
+          super unless sorbet_runtime_constants.key?(name)
+
+          unless Object.const_defined?(:T)
+            message = "Trying to access a Sorbet constant #{name.inspect} without `sorbet-runtime`."
+            raise MissingSorbetRuntimeError.new(message)
+          end
+
+          sorbet_runtime_constants.fetch(name).call
+        end
+
+        # @api private
+        #
+        # @param name [Symbol]
+        # @param blk [Proc]
+        def define_sorbet_constant!(name, &blk) = sorbet_runtime_constants.store(name, blk)
+      end
+
+      extend Lithic::Internal::Util::SorbetRuntimeSupport
+
+      define_sorbet_constant!(:ParsedUri) do
+        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
+      end
+
+      define_sorbet_constant!(:ServerSentEvent) do
+        T.type_alias do
+          {
+            event: T.nilable(String),
+            data: T.nilable(String),
+            id: T.nilable(String),
+            retry: T.nilable(Integer)
+          }
+        end
+      end
     end
   end
 end

data/lib/lithic/internal.rb

@@ -2,10 +2,16 @@
 
 module Lithic
   module Internal
+    extend Lithic::Internal::Util::SorbetRuntimeSupport
+
     OMIT =
       Object.new.tap do
         _1.define_singleton_method(:inspect) { "#<#{Lithic::Internal}::OMIT>" }
       end
         .freeze
+
+    define_sorbet_constant!(:AnyHash) do
+      T.type_alias { T::Hash[Symbol, T.anything] }
+    end
   end
 end