lithic 0.1.0.pre.alpha.15 → 0.1.0.pre.alpha.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fafc3f795882ee224abd07c56daed52c0b894f76cbe97f9b6c578b06ba3aa40
-  data.tar.gz: d04f5e51cdbf0596b57cae1baad86dfd0991ff677396248ff78520d98d3409bd
+  metadata.gz: d994bf8972c5500b7885b05e3d656c7dda04419796c1abb50218bbe4144e6a1a
+  data.tar.gz: 2f12393da601f3a7877b0b648bf6ff8bbe294cf690889934e9a9883c0ec9bc50
 SHA512:
-  metadata.gz: 869dd1a4561a4d622d02dd694ec56173da240e7cd1e4505cb20994af65ab1c27c5c464cbedecabbd7d81474ec4e057fba8647ade3cee8bb133bb488c7d400264
-  data.tar.gz: ba0ab63186ac15a2d57b4d44d2e6c75e8f7853101076ca17032b152bf3e5223765bea88e77aaf94e37c3fa82508bbcd3e1d9b5a0f46f22bdcdbe0866cf128568
+  metadata.gz: 033661aaae27e014d00dc52cbb53c631ba2bfb5e604cc7a73d3a0a9e8fa9f00c9f88f34f288275fb548fac171de6c3920a6e88f76be0ba350f8312037a68b157
+  data.tar.gz: 6da37fe057e86fde01f7bbdaec2bbec7c36d9d474dc2c6cdc15cc093bedebe7a161cc222686d6fe53011a2077c8aa77109a8e28931a0087be936ed7ba55b51ae

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.1.0-alpha.17 (2025-04-21)
+
+Full Changelog: [v0.1.0-alpha.16...v0.1.0-alpha.17](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0-alpha.16...v0.1.0-alpha.17)
+
+### Bug Fixes
+
+* **internals:** fix Card schema definition ([1a3d18b](https://github.com/lithic-com/lithic-ruby/commit/1a3d18be7e1817fad98013b032defbaa5663b354))
+
+## 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)

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.15"
+gem "lithic", "~> 0.1.0.pre.alpha.17"
 ```
 
 <!-- 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
@@ -361,11 +373,15 @@ module Lithic
           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]
@@ -407,7 +423,7 @@ module Lithic
           end
         end
 
-        # @api private
+        # @api public
         #
         # @return [String]
         def to_s = self.class.walk(@data).to_s

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

@@ -44,11 +44,15 @@ module Lithic
         # @return [Array<NilClass, Boolean, Integer, Float, Symbol>]
         def values = constants.map { const_get(_1) }
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def ===(other) = values.include?(other)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -58,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/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

data/lib/lithic/models/account.rb

@@ -50,6 +50,8 @@ module Lithic
       optional :account_holder, -> { Lithic::Models::Account::AccountHolder }
 
       # @!attribute auth_rule_tokens
+      #   @deprecated
+      #
       #   List of identifiers for the Auth Rule(s) that are applied on the account. This
       #   field is deprecated and will no longer be populated in the `account_holder`
       #   object. The key will be removed from the schema in a future release. Use the
@@ -65,6 +67,7 @@ module Lithic
       optional :cardholder_currency, String
 
       # @!attribute verification_address
+      #   @deprecated
       #
       #   @return [Lithic::Models::Account::VerificationAddress, nil]
       optional :verification_address, -> { Lithic::Models::Account::VerificationAddress }

data/lib/lithic/models/account_holder.rb

@@ -23,6 +23,8 @@ module Lithic
       optional :account_token, String
 
       # @!attribute beneficial_owner_entities
+      #   @deprecated
+      #
       #   Deprecated.
       #
       #   @return [Array<Lithic::Models::AccountHolder::BeneficialOwnerEntity>, nil]

data/lib/lithic/models/account_holder_create_params.rb

@@ -61,6 +61,8 @@ module Lithic
       required :workflow, enum: -> { Lithic::Models::AccountHolderCreateParams::Workflow }
 
       # @!attribute beneficial_owner_entities
+      #   @deprecated
+      #
       #   Deprecated.
       #
       #   @return [Array<Lithic::Models::AccountHolderCreateParams::BeneficialOwnerEntity>, nil]

data/lib/lithic/models/account_holder_update_params.rb

@@ -8,6 +8,8 @@ module Lithic
       include Lithic::Internal::Type::RequestParameters
 
       # @!attribute beneficial_owner_entities
+      #   @deprecated
+      #
       #   Deprecated.
       #
       #   @return [Array<Lithic::Models::AccountHolderUpdateParams::BeneficialOwnerEntity>, nil]

data/lib/lithic/models/account_update_params.rb

@@ -40,6 +40,8 @@ module Lithic
       optional :state, enum: -> { Lithic::Models::AccountUpdateParams::State }
 
       # @!attribute verification_address
+      #   @deprecated
+      #
       #   Address used during Address Verification Service (AVS) checks during
       #   transactions if enabled via Auth Rules. This field is deprecated as AVS checks
       #   are no longer supported by Authorization Rules. The field will be removed from

data/lib/lithic/models/card.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Models
+    # @see Lithic::Resources::Cards#create
+    class Card < Lithic::Models::NonPCICard
+      # @!attribute cvv
+      #   Three digit cvv printed on the back of the card.
+      #
+      #   @return [String, nil]
+      optional :cvv, String
+
+      # @!attribute pan
+      #   Primary Account Number (PAN) (i.e. the card number). Customers must be PCI
+      #   compliant to have PAN returned as a field in production. Please contact
+      #   support@lithic.com for questions.
+      #
+      #   @return [String, nil]
+      optional :pan, String
+
+      # @!method initialize(cvv: nil, pan: nil)
+      #   Card details with potentially PCI sensitive information for Enterprise customers
+      #
+      #   @param cvv [String]
+      #   @param pan [String]
+    end
+  end
+end