lithic 0.1.0.pre.alpha.14 → 0.1.0.pre.alpha.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac2b9d69b258cc9761a52dc0632986c5f62d5c2150fa3b23c06fde0b64346017
-  data.tar.gz: '0848b77cb99c28a9c5752260c8532cea2087b3053bb048ffd77677c5e2901de9'
+  metadata.gz: 7bf1f6b2ae2b269fcbe2e915e81c0729bb7d166f035b27dde8e72d6713733841
+  data.tar.gz: 0c0adcbd79d3f29d0092cd87f2c77e4136219d952544c634c5340014b9ea75bb
 SHA512:
-  metadata.gz: 14ccbbef08bf3d2e4e2496fdeaefd03d82210b6bbed70d2d66e663a6fe2d3d88e879b004a9b6f7892ccc0a34dc7417d438a71af2e76588c37da8fac9a63454ca
-  data.tar.gz: f5aea3f807164d03c219be133208aff6216fcfda8cdf289537ae311752d22469f2302cf0a14d9251f20bb9c758ab76ad5266a7acd3a6102ba32a37302bbe8942
+  metadata.gz: 9454d14be6e4f884e28b5767cdc99bb8eb90a95890e8f69cc9c328c371edaf7acae6a496fe2ae213adf40e85dc702f5e48f63f1258b2a6153e3e03fef5aa0ed1
+  data.tar.gz: e115e05933d7b77fe91f4705937c27edf9d03fcff923abbbb78a638d5be00a474c8937a327a00d5cb493beeb21b82ed79ebf1ec117ee9ee38f33391b99aea6f3

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.1.0-alpha.16 (2025-04-21)
+
+Full Changelog: [v0.1.0-alpha.15...v0.1.0-alpha.16](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0-alpha.15...v0.1.0-alpha.16)
+
+### Features
+
+* implement `#hash` for data containers ([7e1420b](https://github.com/lithic-com/lithic-ruby/commit/7e1420bfec9d254eacd77be001cefbad637c7f63))
+
+
+### Bug Fixes
+
+* **internal:** refresh schemas ([cb47b40](https://github.com/lithic-com/lithic-ruby/commit/cb47b40b1aa544d6e6f8fb3f27153ec03cfd6904))
+
+
+### Chores
+
+* documentation improvements ([6700ace](https://github.com/lithic-com/lithic-ruby/commit/6700aced32a478a1c301a3b7e3efee908c5d224e))
+* explicitly mark apis public under `Internal` module ([b81d240](https://github.com/lithic-com/lithic-ruby/commit/b81d240b2048754f45ffe14c446490bce83bfce5))
+* update README with recommended editor plugins ([80d5967](https://github.com/lithic-com/lithic-ruby/commit/80d5967d1e747cbd42e66a570f6520e241a64ba8))
+
+## 0.1.0-alpha.15 (2025-04-18)
+
+Full Changelog: [v0.1.0-alpha.14...v0.1.0-alpha.15](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0-alpha.14...v0.1.0-alpha.15)
+
+### Features
+
+* **api:** updates to Card definition for PCI clarity ([bb157ab](https://github.com/lithic-com/lithic-ruby/commit/bb157abbede60505c67651947fa8c583d17ac84a))
+
+
+### Chores
+
+* make sorbet enums easier to read ([77f23c5](https://github.com/lithic-com/lithic-ruby/commit/77f23c58d44b4c33b6a897ff988da2cb97965653))
+* refine `#inspect` and `#to_s` for model classes ([7435187](https://github.com/lithic-com/lithic-ruby/commit/74351870d4768cd923ce9d88841ba8c84b6681d6))
+* simplify yard annotations by removing most `@!parse` directives ([12c6882](https://github.com/lithic-com/lithic-ruby/commit/12c6882a7db0b45f91d8e4df7b0d41016567ad7a))
+* use `@!method` instead of `@!parse` for virtual method type definitions ([a73c89a](https://github.com/lithic-com/lithic-ruby/commit/a73c89aa794ebfc771a7410603c10be08d1609d3))
+
 ## 0.1.0-alpha.14 (2025-04-17)
 
 Full Changelog: [v0.1.0-alpha.13...v0.1.0-alpha.14](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0-alpha.13...v0.1.0-alpha.14)

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.14"
+gem "lithic", "~> 0.1.0.pre.alpha.16"
 ```
 
 <!-- x-release-please-end -->
@@ -31,11 +31,21 @@ lithic = Lithic::Client.new(
   environment: "sandbox" # defaults to "production"
 )
 
-card = lithic.cards.create(type: "SINGLE_USE")
+card = lithic.cards.create(type: :SINGLE_USE)
 
 puts(card.token)
 ```
 
+## Sorbet
+
+This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
+
+When using sorbet, it is recommended to use model classes as below. This provides stronger type checking and tooling integration.
+
+```ruby
+lithic.cards.create(type: :SINGLE_USE)
+```
+
 ### Pagination
 
 List methods in the Lithic API are paginated.
@@ -61,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: :an_incorrect_type)
 rescue Lithic::Errors::APIError => e
   puts(e.status) # 400
 end
@@ -119,61 +129,32 @@ lithic = Lithic::Client.new(
 lithic.cards.list(page_size: 10, request_options: {timeout: 5})
 ```
 
-## LSP Support
-
-### Solargraph
-
-This library includes [Solargraph](https://solargraph.org) support for both auto completion and go to definition.
-
-```ruby
-gem "solargraph", group: :development
-```
-
-After Solargraph is installed, **you must populate its index** either via the provided editor command, or by running the following in your terminal:
-
-```sh
-bundle exec solargraph gems
-```
-
-Note: if you had installed the gem either using a `git:` or `github:` URL, or had vendored the gem using bundler, you will need to set up your [`.solargraph.yml`](https://solargraph.org/guides/configuration) to include the path to the gem's `lib` directory.
-
-```yaml
-include:
-  - 'vendor/bundle/ruby/*/gems/lithic-*/lib/**/*.rb'
-```
-
-Otherwise Solargraph will not be able to provide type information or auto-completion for any non-indexed libraries.
-
-### Sorbet
-
-This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
+## Model DSL
 
-What this means is that while you can use Sorbet to type check your code statically, and benefit from the [Sorbet Language Server](https://sorbet.org/docs/lsp) in your editor, there is no runtime type checking and execution overhead from Sorbet itself.
+This library uses a simple DSL to represent request parameters and response shapes in `lib/lithic/models`.
 
-Due to limitations with the Sorbet type system, where a method otherwise can take an instance of `Lithic::BaseModel` class, you will need to use the `**` splat operator to pass the arguments:
+With the right [editor plugins](https://shopify.github.io/ruby-lsp), you can ctrl-click on elements of the DSL to navigate around and explore the library.
 
-Please follow Sorbet's [setup guides](https://sorbet.org/docs/adopting) for best experience.
+In all places where a `BaseModel` type is specified, vanilla Ruby `Hash` can also be used. For example, the following are interchangeable as arguments:
 
 ```ruby
-params = Lithic::Models::CardCreateParams.new(type: "SINGLE_USE")
+# This has tooling readability, for auto-completion, static analysis, and goto definition with supported language services
+params = Lithic::Models::CardCreateParams.new(type: :SINGLE_USE)
 
-lithic.cards.create(**params)
+# This also works
+params = {
+  type: :SINGLE_USE
+}
 ```
 
-Note: **This library emits an intentional warning under the [`tapioca` toolchain](https://github.com/Shopify/tapioca)**. This is normal, and does not impact functionality.
-
-### Ruby LSP
+## Editor support
 
-The Ruby LSP has [best effort support](https://shopify.github.io/ruby-lsp/#guessed-types) for inferring type information from Ruby code, and as such it may not always be able to provide accurate type information.
+A combination of [Shopify LSP](https://shopify.github.io/ruby-lsp) and [Solargraph](https://solargraph.org/) is recommended for non-[Sorbet](https://sorbet.org) users. The former is especially good at go to definition, while the latter has much better auto-completion support.
 
-## Advanced
+## Advanced concepts
 
 ### Making custom/undocumented requests
 
-This library is typed for convenient access to the documented API.
-
-If you need to access undocumented endpoints, params, or response properties, the library can still be used.
-
 #### Undocumented request params
 
 If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a requests as seen in examples above.
@@ -184,15 +165,15 @@ To make requests to undocumented endpoints, you can make requests using `client.
 
 ```ruby
 response = client.request(
-    method: :post,
-    path: '/undocumented/endpoint',
-    query: {"dog": "woof"},
-    headers: {"useful-header": "interesting-value"},
-    body: {"he": "llo"},
-  )
+  method: :post,
+  path: '/undocumented/endpoint',
+  query: {"dog": "woof"},
+  headers: {"useful-header": "interesting-value"},
+  body: {"he": "llo"},
+)
 ```
 
-### Concurrency & Connection Pooling
+### Concurrency & connection pooling
 
 The `Lithic::Client` instances are thread-safe, and should be re-used across multiple threads. By default, each `Client` have their own HTTP connection pool, with a maximum number of connections equal to thread count.
 
@@ -202,6 +183,30 @@ Unless otherwise specified, other classes in the SDK do not have locks protectin
 
 Currently, `Lithic::Client` instances are only fork-safe if there are no in-flight HTTP requests.
 
+### Sorbet
+
+#### Enums
+
+Sorbet's typed enums require sub-classing of the [`T::Enum` class](https://sorbet.org/docs/tenum) from the `sorbet-runtime` gem.
+
+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
+  # This alias aids language service driven navigation.
+  TaggedSymbol = T.type_alias { T.all(Symbol, Lithic::Models::AccountFinancialAccountType) }
+end
+```
+
+#### Argument passing trick
+
+It is possible to pass a compatible model / parameter class to a method that expects keyword arguments by using the `**` splat operator.
+
+```ruby
+params = Lithic::Models::CardCreateParams.new(type: :SINGLE_USE)
+lithic.cards.create(**params)
+```
+
 ## Versioning
 
 This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
@@ -211,3 +216,7 @@ This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` typ
 ## Requirements
 
 Ruby 3.1.0 or higher.
+
+## Contributing
+
+See [the contributing documentation](https://github.com/lithic-com/lithic-ruby/tree/main/CONTRIBUTING.md).

data/lib/lithic/client.rb

@@ -148,10 +148,10 @@ module Lithic
       api_key: ENV["LITHIC_API_KEY"],
       environment: nil,
       base_url: ENV["LITHIC_BASE_URL"],
-      max_retries: DEFAULT_MAX_RETRIES,
-      timeout: DEFAULT_TIMEOUT_IN_SECONDS,
-      initial_retry_delay: DEFAULT_INITIAL_RETRY_DELAY,
-      max_retry_delay: DEFAULT_MAX_RETRY_DELAY
+      max_retries: Lithic::Client::DEFAULT_MAX_RETRIES,
+      timeout: Lithic::Client::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: Lithic::Client::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: Lithic::Client::DEFAULT_MAX_RETRY_DELAY
     )
       base_url ||= Lithic::Client::ENVIRONMENTS.fetch(environment&.to_sym || :production) do
         message = "environment must be one of #{Lithic::Client::ENVIRONMENTS.keys}, got #{environment}"

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

@@ -57,15 +57,11 @@ module Lithic
           # @return [Array(Net::HTTPGenericRequest, Proc)]
           def build_request(request, &blk)
             method, url, headers, body = request.fetch_values(:method, :url, :headers, :body)
-
-            # ensure we construct a URI class of the right scheme
-            url = URI(url.to_s)
-
             req = Net::HTTPGenericRequest.new(
               method.to_s.upcase,
               !body.nil?,
               method != :head,
-              url
+              URI(url.to_s) # ensure we construct a URI class of the right scheme
             )
 
             headers.each { req[_1] = _2 }

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

@@ -30,11 +30,15 @@ module Lithic
         #   @option spec [Boolean] :"nil?"
         def self.[](...) = new(...)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def ===(other) = other.is_a?(Array) && other.all?(item_type)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -44,6 +48,11 @@ module Lithic
           # rubocop:enable Layout/LineLength
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, item_type].hash
+
         # @api private
         #
         # @param value [Array<Object>, Object]

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

@@ -4,14 +4,6 @@ module Lithic
   module Internal
     module Type
       # @abstract
-      #
-      # @example
-      #   # `address` is a `Lithic::Models::Address`
-      #   address => {
-      #     address1: address1,
-      #     city: city,
-      #     country: country
-      #   }
       class BaseModel
         extend Lithic::Internal::Type::Converter
 
@@ -93,11 +85,13 @@ module Lithic
                   state: state
                 )
               end
-            rescue StandardError
+            rescue StandardError => e
               cls = self.class.name.split("::").last
-              # rubocop:disable Layout/LineLength
-              message = "Failed to parse #{cls}.#{__method__} from #{value.class} to #{target.inspect}. To get the unparsed API response, use #{cls}[:#{__method__}]."
-              # rubocop:enable Layout/LineLength
+              message = [
+                "Failed to parse #{cls}.#{__method__} from #{value.class} to #{target.inspect}.",
+                "To get the unparsed API response, use #{cls}[#{__method__.inspect}].",
+                "Cause: #{e.message}"
+              ].join(" ")
               raise Lithic::Errors::ConversionError.new(message)
             end
           end
@@ -165,19 +159,33 @@ module Lithic
             @mode = nil
           end
 
+          # @api public
+          #
           # @param other [Object]
           #
           # @return [Boolean]
           def ==(other)
             other.is_a?(Class) && other <= Lithic::Internal::Type::BaseModel && other.fields == fields
           end
+
+          # @api public
+          #
+          # @return [Integer]
+          def hash = fields.hash
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def ==(other) = self.class == other.class && @data == other.to_h
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, @data].hash
+
         class << self
           # @api private
           #
@@ -291,6 +299,8 @@ module Lithic
           end
         end
 
+        # @api public
+        #
         # Returns the raw value associated with the given key, if found. Otherwise, nil is
         # returned.
         #
@@ -309,6 +319,8 @@ module Lithic
           @data[key]
         end
 
+        # @api public
+        #
         # 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
@@ -338,11 +350,38 @@ 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]
         #
         # @return [String]
         def to_json(*a) = Lithic::Internal::Type::Converter.dump(self.class, self).to_json(*a)
 
+        # @api public
+        #
         # @param a [Object]
         #
         # @return [String]
@@ -373,31 +412,26 @@ module Lithic
             depth = depth.succ
             deferred = fields.transform_values do |field|
               type, required, nilable = field.fetch_values(:type, :required, :nilable)
-              -> do
-                [
-                  Lithic::Internal::Type::Converter.inspect(type, depth: depth),
-                  !required || nilable ? "nil" : nil
-                ].compact.join(" | ")
-              end
-                .tap { _1.define_singleton_method(:inspect) { call } }
+              inspected = [
+                Lithic::Internal::Type::Converter.inspect(type, depth: depth),
+                !required || nilable ? "nil" : nil
+              ].compact.join(" | ")
+              -> { inspected }.tap { _1.define_singleton_method(:inspect) { call } }
             end
 
             "#{name}[#{deferred.inspect}]"
           end
         end
 
-        # @api private
+        # @api public
         #
         # @return [String]
-        def inspect
-          rows = @data.map do
-            "#{_1}=#{self.class.known_fields.key?(_1) ? public_send(_1).inspect : ''}"
-          rescue Lithic::Errors::ConversionError
-            "#{_1}=#{_2.inspect}"
-          end
+        def to_s = self.class.walk(@data).to_s
 
-          "#<#{self.class}:0x#{object_id.to_s(16)} #{rows.join(' ')}>"
-        end
+        # @api private
+        #
+        # @return [String]
+        def inspect = "#<#{self.class}:0x#{object_id.to_s(16)} #{self}>"
       end
     end
   end

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

@@ -3,19 +3,27 @@
 module Lithic
   module Internal
     module Type
+      # @api private
+      #
       # @generic Elem
       #
       # This module provides a base implementation for paginated responses in the SDK.
       module BasePage
         # rubocop:disable Lint/UnusedMethodArgument
 
+        # @api public
+        #
         # @return [Boolean]
         def next_page? = (raise NotImplementedError)
 
+        # @api public
+        #
         # @raise [Lithic::Errors::APIError]
         # @return [Lithic::Internal::Type::BasePage]
         def next_page = (raise NotImplementedError)
 
+        # @api public
+        #
         # @param blk [Proc]
         #
         # @yieldparam [generic<Elem>]

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

@@ -13,11 +13,15 @@ module Lithic
 
         private_class_method :new
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def self.===(other) = other == true || other == false
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]

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

@@ -42,18 +42,17 @@ module Lithic
         # All of the valid Symbol values for this enum.
         #
         # @return [Array<NilClass, Boolean, Integer, Float, Symbol>]
-        def values = (@values ||= constants.map { const_get(_1) })
+        def values = constants.map { const_get(_1) }
 
-        # @api private
+        # @api public
         #
-        # Guard against thread safety issues by instantiating `@values`.
-        private def finalize! = values
-
         # @param other [Object]
         #
         # @return [Boolean]
         def ===(other) = values.include?(other)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -63,6 +62,11 @@ module Lithic
           # rubocop:enable Style/CaseEquality
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = values.to_set.hash
+
         # @api private
         #
         # Unlike with primitives, `Enum` additionally validates that the value is a member

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

@@ -30,6 +30,8 @@ module Lithic
         #   @option spec [Boolean] :"nil?"
         def self.[](...) = new(...)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -50,6 +52,8 @@ module Lithic
           end
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -59,6 +63,11 @@ module Lithic
           # rubocop:enable Layout/LineLength
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, item_type].hash
+
         # @api private
         #
         # @param value [Hash{Object=>Object}, Object]

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

@@ -13,6 +13,8 @@ module Lithic
 
         private_class_method :new
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -25,6 +27,8 @@ module Lithic
           end
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]

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

@@ -12,9 +12,8 @@ module Lithic
 
         # @param mod [Module]
         def self.included(mod)
-          return unless mod <= Lithic::Internal::Type::BaseModel
+          raise ArgumentError.new(mod) unless mod <= Lithic::Internal::Type::BaseModel
 
-          mod.extend(Lithic::Internal::Type::RequestParameters::Converter)
           mod.optional(:request_options, Lithic::RequestOptions)
         end
 

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

@@ -29,7 +29,7 @@ module Lithic
         #
         # @return [Array<Array(Symbol, Object)>]
         protected def derefed_variants
-          @known_variants.map { |key, variant_fn| [key, variant_fn.call] }
+          known_variants.map { |key, variant_fn| [key, variant_fn.call] }
         end
 
         # All of the specified variants for this union.
@@ -98,6 +98,8 @@ module Lithic
         # rubocop:disable Style/HashEachMethods
         # rubocop:disable Style/CaseEquality
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -107,6 +109,8 @@ module Lithic
           end
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -114,6 +118,11 @@ module Lithic
           Lithic::Internal::Type::Union === other && other.derefed_variants == derefed_variants
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = variants.hash
+
         # @api private
         #
         # @param value [Object]

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

@@ -15,11 +15,15 @@ module Lithic
 
         private_class_method :new
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def self.===(other) = true
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]

data/lib/lithic/internal.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Lithic
-  # @api private
   module Internal
     OMIT =
       Object.new.tap do