lithic 0.1.0.pre.alpha.17 → 0.1.0.pre.alpha.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d994bf8972c5500b7885b05e3d656c7dda04419796c1abb50218bbe4144e6a1a
-  data.tar.gz: 2f12393da601f3a7877b0b648bf6ff8bbe294cf690889934e9a9883c0ec9bc50
+  metadata.gz: 05aee8aa5e025c482dcce7eda27b3c395985006317087846d579d0ad8d7991e7
+  data.tar.gz: cd3fc85b83558917f6c34dce35268e67593914dc57ef1de4148984cfe9921cd8
 SHA512:
-  metadata.gz: 033661aaae27e014d00dc52cbb53c631ba2bfb5e604cc7a73d3a0a9e8fa9f00c9f88f34f288275fb548fac171de6c3920a6e88f76be0ba350f8312037a68b157
-  data.tar.gz: 6da37fe057e86fde01f7bbdaec2bbec7c36d9d474dc2c6cdc15cc093bedebe7a161cc222686d6fe53011a2077c8aa77109a8e28931a0087be936ed7ba55b51ae
+  metadata.gz: be54eb3eb00a6277372c104183d09f3d6bb7f4b8e771aaa5061084d9c06722b48eb2452e773176d1ea9ccc53584e9bce4585734d2fb80f5be7832a54909ef474
+  data.tar.gz: 1f5aed27dd5929a0a3066f073d5c544c0844c7ecb17bfb4e9f46c76693fecd7b0deeb3abb8dab3175d574afadc5c14ebf958fc81bede86b2ef69d325dc549fa3

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.1.0-alpha.19 (2025-04-25)
+
+Full Changelog: [v0.1.0-alpha.18...v0.1.0-alpha.19](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0-alpha.18...v0.1.0-alpha.19)
+
+### Bug Fixes
+
+* make a typo for `FilePart.content` ([4eb5bee](https://github.com/lithic-com/lithic-ruby/commit/4eb5bee30c1bfbc394092b72b338908643010f5a))
+
+## 0.1.0-alpha.18 (2025-04-25)
+
+Full Changelog: [v0.1.0-alpha.17...v0.1.0-alpha.18](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0-alpha.17...v0.1.0-alpha.18)
+
+### Features
+
+* support specifying content-type with FilePart class ([0cf245e](https://github.com/lithic-com/lithic-ruby/commit/0cf245eaa7321b8ae3ee08a9c585403cf654f9ca))
+* support webmock for testing ([56900e6](https://github.com/lithic-com/lithic-ruby/commit/56900e694ecd63ff000e880f2cd6add9e5548e86))
+
+
+### Bug Fixes
+
+* ensure gem release is unaffected by renaming ([84a2f71](https://github.com/lithic-com/lithic-ruby/commit/84a2f7191fa58067637c050575de5552aec2cf09))
+
+
+### Chores
+
+* broadly detect json family of content-type headers ([2b4f4bc](https://github.com/lithic-com/lithic-ruby/commit/2b4f4bca7f025906e369ed32f4cd71e357cd79a8))
+* **ci:** add timeout thresholds for CI jobs ([2f4319b](https://github.com/lithic-com/lithic-ruby/commit/2f4319b37459d2899350a1d05aec39a8134ac3e1))
+* **ci:** only use depot for staging repos ([99e9f7d](https://github.com/lithic-com/lithic-ruby/commit/99e9f7d78c04ab805321dabe41d5431717fc5eb4))
+* **ci:** run on more branches and use depot runners ([84743d4](https://github.com/lithic-com/lithic-ruby/commit/84743d4c86aeeadc23ef0cb025f77944e9822a4e))
+* consistently use string in examples, even for enums ([c35c6f4](https://github.com/lithic-com/lithic-ruby/commit/c35c6f45e00d6eed30d43f8b4335c6761f3fe2f5))
+* **internal:** improve response envelope unwrap functionality ([d2c37aa](https://github.com/lithic-com/lithic-ruby/commit/d2c37aa27246c9379a2400020047cd1c7761f03d))
+* **internal:** minor type annotation improvements ([964cec1](https://github.com/lithic-com/lithic-ruby/commit/964cec1b7eb9904a6f643dcbcaaff3ae64276032))
+* show truncated parameter docs in yard ([3d5f4b7](https://github.com/lithic-com/lithic-ruby/commit/3d5f4b7b7fc6d780cb19fe3cddac32306de1aaf2))
+
 ## 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)

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.17"
+gem "lithic", "~> 0.1.0.pre.alpha.19"
 ```
 
 <!-- x-release-please-end -->
@@ -31,7 +31,7 @@ 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)
 ```
@@ -43,7 +43,7 @@ This library is written with [Sorbet type definitions](https://sorbet.org/docs/r
 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)
+lithic.cards.create(type: "SINGLE_USE")
 ```
 
 ### Pagination
@@ -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: "an_incorrect_type")
 rescue Lithic::Errors::APIError => e
   puts(e.status) # 400
 end
@@ -139,11 +139,11 @@ In all places where a `BaseModel` type is specified, vanilla Ruby `Hash` can als
 
 ```ruby
 # This has tooling readability, for auto-completion, static analysis, and goto definition with supported language services
-params = Lithic::Models::CardCreateParams.new(type: :SINGLE_USE)
+params = Lithic::Models::CardCreateParams.new(type: "SINGLE_USE")
 
 # This also works
 params = {
-  type: :SINGLE_USE
+  type: "SINGLE_USE"
 }
 ```
 
@@ -203,7 +203,7 @@ end
 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)
+params = Lithic::Models::CardCreateParams.new(type: "SINGLE_USE")
 lithic.cards.create(**params)
 ```
 

data/lib/lithic/file_part.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Lithic
+  class FilePart
+    # @return [Pathname, StringIO, IO, String]
+    attr_reader :content
+
+    # @return [String, nil]
+    attr_reader :content_type
+
+    # @return [String, nil]
+    attr_reader :filename
+
+    # @api private
+    #
+    # @return [String]
+    private def read
+      case content
+      in Pathname
+        content.read(binmode: true)
+      in StringIO
+        content.string
+      in IO
+        content.read
+      in String
+        content
+      end
+    end
+
+    # @param a [Object]
+    #
+    # @return [String]
+    def to_json(*a) = read.to_json(*a)
+
+    # @param a [Object]
+    #
+    # @return [String]
+    def to_yaml(*a) = read.to_yaml(*a)
+
+    # @param content [Pathname, StringIO, IO, String]
+    # @param filename [String, nil]
+    # @param content_type [String, nil]
+    def initialize(content, filename: nil, content_type: nil)
+      @content = content
+      @filename =
+        case content
+        in Pathname
+          filename.nil? ? content.basename.to_path : File.basename(filename)
+        else
+          filename.nil? ? nil : File.basename(filename)
+        end
+      @content_type = content_type
+    end
+  end
+end

data/lib/lithic/internal/cursor_page.rb

@@ -28,7 +28,7 @@ module Lithic
       end
 
       # @raise [Lithic::HTTP::Error]
-      # @return [Lithic::Internal::CursorPage]
+      # @return [self]
       def next_page
         unless next_page?
           message = "No more pages available. Please check #next_page? before calling ##{__method__}"

data/lib/lithic/internal/single_page.rb

@@ -28,7 +28,7 @@ module Lithic
       end
 
       # @raise [Lithic::HTTP::Error]
-      # @return [Lithic::Internal::SinglePage]
+      # @return [self]
       def next_page
         RuntimeError.new("No more pages available.")
       end

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

@@ -153,7 +153,7 @@ module Lithic
 
         # @api private
         # @return [Lithic::Internal::Transport::PooledNetRequester]
-        attr_accessor :requester
+        attr_reader :requester
 
         # @api private
         #
@@ -214,11 +214,11 @@ module Lithic
         #
         #   @option req [Object, nil] :body
         #
-        #   @option req [Symbol, nil] :unwrap
+        #   @option req [Symbol, Integer, Array<Symbol, Integer>, Proc, nil] :unwrap
         #
-        #   @option req [Class, nil] :page
+        #   @option req [Class<Lithic::Internal::Type::BasePage>, nil] :page
         #
-        #   @option req [Class, nil] :stream
+        #   @option req [Class<Lithic::Internal::Type::BaseStream>, nil] :stream
         #
         #   @option req [Lithic::Internal::Type::Converter, Class, nil] :model
         #
@@ -415,11 +415,11 @@ module Lithic
         #
         # @param body [Object, nil]
         #
-        # @param unwrap [Symbol, nil]
+        # @param unwrap [Symbol, Integer, Array<Symbol, Integer>, Proc, nil]
         #
-        # @param page [Class, nil]
+        # @param page [Class<Lithic::Internal::Type::BasePage>, nil]
         #
-        # @param stream [Class, nil]
+        # @param stream [Class<Lithic::Internal::Type::BaseStream>, nil]
         #
         # @param model [Lithic::Internal::Type::Converter, Class, nil]
         #

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

@@ -176,7 +176,7 @@ module Lithic
             conn.finish if !eof && conn&.started?
             closing&.call
           end
-          [Integer(response.code), response, (response.body = body)]
+          [Integer(response.code), response, body]
         end
 
         # @api private

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

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

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

@@ -389,7 +389,7 @@ module Lithic
 
         # Create a new instance of a model.
         #
-        # @param data [Hash{Symbol=>Object}, Lithic::Internal::Type::BaseModel]
+        # @param data [Hash{Symbol=>Object}, self]
         def initialize(data = {})
           case Lithic::Internal::Util.coerce_hash(data)
           in Hash => coerced

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

@@ -19,7 +19,7 @@ module Lithic
         # @api public
         #
         # @raise [Lithic::Errors::APIError]
-        # @return [Lithic::Internal::Type::BasePage]
+        # @return [self]
         def next_page = (raise NotImplementedError)
 
         # @api public

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

@@ -43,7 +43,10 @@ module Lithic
             value.string
           in Pathname | IO
             state[:can_retry] = false if value.is_a?(IO)
-            Lithic::Internal::Util::SerializationAdapter.new(value)
+            Lithic::FilePart.new(value)
+          in Lithic::FilePart
+            state[:can_retry] = false if value.content.is_a?(IO)
+            value
           else
             value
           end

data/lib/lithic/internal/type/{io_like.rb → file_input.rb}

@@ -7,8 +7,12 @@ module Lithic
       #
       # @abstract
       #
-      # Either `Pathname` or `StringIO`.
-      class IOLike
+      # Either `Pathname` or `StringIO`, or `IO`, or
+      # `Lithic::Internal::Type::FileInput`.
+      #
+      # Note: when `IO` is used, all retries are disabled, since many IO` streams are
+      # not rewindable.
+      class FileInput
         extend Lithic::Internal::Type::Converter
 
         private_class_method :new
@@ -20,7 +24,7 @@ module Lithic
         # @return [Boolean]
         def self.===(other)
           case other
-          in StringIO | Pathname | IO
+          in Pathname | StringIO | IO | String | Lithic::FilePart
             true
           else
             false
@@ -32,7 +36,7 @@ module Lithic
         # @param other [Object]
         #
         # @return [Boolean]
-        def self.==(other) = other.is_a?(Class) && other <= Lithic::Internal::Type::IOLike
+        def self.==(other) = other.is_a?(Class) && other <= Lithic::Internal::Type::FileInput
 
         class << self
           # @api private
@@ -63,17 +67,28 @@ module Lithic
             end
           end
 
-          # @!parse
-          #   # @api private
-          #   #
-          #   # @param value [Pathname, StringIO, IO, String, Object]
-          #   #
-          #   # @param state [Hash{Symbol=>Object}] .
-          #   #
-          #   #   @option state [Boolean] :can_retry
-          #   #
-          #   # @return [Pathname, StringIO, IO, String, Object]
-          #   def dump(value, state:) = super
+          # @api private
+          #
+          # @param value [Pathname, StringIO, IO, String, Object]
+          #
+          # @param state [Hash{Symbol=>Object}] .
+          #
+          #   @option state [Boolean] :can_retry
+          #
+          # @return [Pathname, StringIO, IO, String, Object]
+          def dump(value, state:)
+            # rubocop:disable Lint/DuplicateBranch
+            case value
+            in IO
+              state[:can_retry] = false
+            in Lithic::FilePart if value.content.is_a?(IO)
+              state[:can_retry] = false
+            else
+            end
+            # rubocop:enable Lint/DuplicateBranch
+
+            value
+          end
         end
       end
     end

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

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

data/lib/lithic/internal/util.rb

@@ -175,18 +175,17 @@ module Lithic
         # @api private
         #
         # @param data [Hash{Symbol=>Object}, Array<Object>, Object]
-        # @param pick [Symbol, Integer, Array<Symbol, Integer>, nil]
-        # @param sentinel [Object, nil]
+        # @param pick [Symbol, Integer, Array<Symbol, Integer>, Proc, nil]
         # @param blk [Proc, nil]
         #
         # @return [Object, nil]
-        def dig(data, pick, sentinel = nil, &blk)
-          case [data, pick, blk]
-          in [_, nil, nil]
+        def dig(data, pick, &blk)
+          case [data, pick]
+          in [_, nil]
             data
-          in [Hash, Symbol, _] | [Array, Integer, _]
-            blk.nil? ? data.fetch(pick, sentinel) : data.fetch(pick, &blk)
-          in [Hash | Array, Array, _]
+          in [Hash, Symbol] | [Array, Integer]
+            data.fetch(pick) { blk&.call }
+          in [Hash | Array, Array]
             pick.reduce(data) do |acc, key|
               case acc
               in Hash if acc.key?(key)
@@ -194,11 +193,13 @@ module Lithic
               in Array if key.is_a?(Integer) && key < acc.length
                 acc[key]
               else
-                return blk.nil? ? sentinel : blk.call
+                return blk&.call
               end
             end
-          in _
-            blk.nil? ? sentinel : blk.call
+          in [_, Proc]
+            pick.call(data)
+          else
+            blk&.call
           end
         end
       end
@@ -348,27 +349,6 @@ module Lithic
         end
       end
 
-      # @api private
-      class SerializationAdapter
-        # @return [Pathname, IO]
-        attr_reader :inner
-
-        # @param a [Object]
-        #
-        # @return [String]
-        def to_json(*a) = (inner.is_a?(IO) ? inner.read : inner.read(binmode: true)).to_json(*a)
-
-        # @param a [Object]
-        #
-        # @return [String]
-        def to_yaml(*a) = (inner.is_a?(IO) ? inner.read : inner.read(binmode: true)).to_yaml(*a)
-
-        # @api private
-        #
-        # @param inner [Pathname, IO]
-        def initialize(inner) = @inner = inner
-      end
-
       # @api private
       #
       # An adapter that satisfies the IO interface required by `::IO.copy_stream`
@@ -471,46 +451,44 @@ module Lithic
         end
       end
 
+      # @type [Regexp]
+      JSON_CONTENT = %r{^application/(?:vnd(?:\.[^.]+)*\+)?json(?!l)}
+      # @type [Regexp]
+      JSONL_CONTENT = %r{^application/(?:x-)?jsonl}
+
       class << self
         # @api private
         #
         # @param y [Enumerator::Yielder]
-        # @param boundary [String]
-        # @param key [Symbol, String]
         # @param val [Object]
         # @param closing [Array<Proc>]
-        private def write_multipart_chunk(y, boundary:, key:, val:, closing:)
-          val = val.inner if val.is_a?(Lithic::Internal::Util::SerializationAdapter)
+        # @param content_type [String, nil]
+        private def write_multipart_content(y, val:, closing:, content_type: nil)
+          content_type ||= "application/octet-stream"
 
-          y << "--#{boundary}\r\n"
-          y << "Content-Disposition: form-data"
-          unless key.nil?
-            name = ERB::Util.url_encode(key.to_s)
-            y << "; name=\"#{name}\""
-          end
-          case val
-          in Pathname | IO
-            filename = ERB::Util.url_encode(File.basename(val.to_path))
-            y << "; filename=\"#{filename}\""
-          else
-          end
-          y << "\r\n"
           case val
+          in Lithic::FilePart
+            return write_multipart_content(
+              y,
+              val: val.content,
+              closing: closing,
+              content_type: val.content_type
+            )
           in Pathname
-            y << "Content-Type: application/octet-stream\r\n\r\n"
+            y << "Content-Type: #{content_type}\r\n\r\n"
             io = val.open(binmode: true)
             closing << io.method(:close)
             IO.copy_stream(io, y)
           in IO
-            y << "Content-Type: application/octet-stream\r\n\r\n"
+            y << "Content-Type: #{content_type}\r\n\r\n"
             IO.copy_stream(val, y)
           in StringIO
-            y << "Content-Type: application/octet-stream\r\n\r\n"
+            y << "Content-Type: #{content_type}\r\n\r\n"
             y << val.string
           in String
-            y << "Content-Type: application/octet-stream\r\n\r\n"
+            y << "Content-Type: #{content_type}\r\n\r\n"
             y << val.to_s
-          in _ if primitive?(val)
+          in -> { primitive?(_1) }
             y << "Content-Type: text/plain\r\n\r\n"
             y << val.to_s
           else
@@ -520,6 +498,36 @@ module Lithic
           y << "\r\n"
         end
 
+        # @api private
+        #
+        # @param y [Enumerator::Yielder]
+        # @param boundary [String]
+        # @param key [Symbol, String]
+        # @param val [Object]
+        # @param closing [Array<Proc>]
+        private def write_multipart_chunk(y, boundary:, key:, val:, closing:)
+          y << "--#{boundary}\r\n"
+          y << "Content-Disposition: form-data"
+
+          unless key.nil?
+            name = ERB::Util.url_encode(key.to_s)
+            y << "; name=\"#{name}\""
+          end
+
+          case val
+          in Lithic::FilePart unless val.filename.nil?
+            filename = ERB::Util.url_encode(val.filename)
+            y << "; filename=\"#{filename}\""
+          in Pathname | IO
+            filename = ERB::Util.url_encode(File.basename(val.to_path))
+            y << "; filename=\"#{filename}\""
+          else
+          end
+          y << "\r\n"
+
+          write_multipart_content(y, val: val, closing: closing)
+        end
+
         # @api private
         #
         # @param body [Object]
@@ -560,14 +568,12 @@ module Lithic
         # @return [Object]
         def encode_content(headers, body)
           content_type = headers["content-type"]
-          body = body.inner if body.is_a?(Lithic::Internal::Util::SerializationAdapter)
-
           case [content_type, body]
-          in [%r{^application/(?:vnd\.api\+)?json}, Hash | Array | -> { primitive?(_1) }]
+          in [Lithic::Internal::Util::JSON_CONTENT, Hash | Array | -> { primitive?(_1) }]
             [headers, JSON.fast_generate(body)]
-          in [%r{^application/(?:x-)?jsonl}, Enumerable] unless body.is_a?(StringIO) || body.is_a?(IO)
+          in [Lithic::Internal::Util::JSONL_CONTENT, Enumerable] unless body.is_a?(Lithic::Internal::Type::FileInput)
             [headers, body.lazy.map { JSON.fast_generate(_1) }]
-          in [%r{^multipart/form-data}, Hash | Pathname | StringIO | IO]
+          in [%r{^multipart/form-data}, Hash | Lithic::Internal::Type::FileInput]
             boundary, strio = encode_multipart_streaming(body)
             headers = {**headers, "content-type" => "#{content_type}; boundary=#{boundary}"}
             [headers, strio]
@@ -575,6 +581,8 @@ module Lithic
             [headers, body.to_s]
           in [_, StringIO]
             [headers, body.string]
+          in [_, Lithic::FilePart]
+            [headers, body.content]
           else
             [headers, body]
           end
@@ -611,7 +619,7 @@ module Lithic
         # @return [Object]
         def decode_content(headers, stream:, suppress_error: false)
           case (content_type = headers["content-type"])
-          in %r{^application/(?:vnd\.api\+)?json}
+          in Lithic::Internal::Util::JSON_CONTENT
             json = stream.to_a.join
             begin
               JSON.parse(json, symbolize_names: true)
@@ -619,7 +627,7 @@ module Lithic
               raise e unless suppress_error
               json
             end
-          in %r{^application/(?:x-)?jsonl}
+          in Lithic::Internal::Util::JSONL_CONTENT
             lines = decode_lines(stream)
             chain_fused(lines) do |y|
               lines.each { y << JSON.parse(_1, symbolize_names: true) }