orb-billing 0.1.3 → 0.3.0

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

@@ -4,14 +4,6 @@ module Orb
   module Internal
     module Type
       # @abstract
-      #
-      # @example
-      #   # `amount_discount` is a `Orb::Models::AmountDiscount`
-      #   amount_discount => {
-      #     amount_discount: amount_discount,
-      #     applies_to_price_ids: applies_to_price_ids,
-      #     discount_type: discount_type
-      #   }
       class BaseModel
         extend Orb::Internal::Type::Converter
 
@@ -63,7 +55,7 @@ module Orb
 
             setter = "#{name_sym}="
             api_name = info.fetch(:api_name, name_sym)
-            nilable = info[:nil?]
+            nilable = info.fetch(:nil?, false)
             const = required && !nilable ? info.fetch(:const, Orb::Internal::OMIT) : Orb::Internal::OMIT
 
             [name_sym, setter].each { undef_method(_1) } if known_fields.key?(name_sym)
@@ -93,11 +85,13 @@ module Orb
                   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 Orb::Errors::ConversionError.new(message)
             end
           end
@@ -165,19 +159,33 @@ module Orb
             @mode = nil
           end
 
+          # @api public
+          #
           # @param other [Object]
           #
           # @return [Boolean]
           def ==(other)
             other.is_a?(Class) && other <= Orb::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 Orb
           end
         end
 
+        # @api public
+        #
         # Returns the raw value associated with the given key, if found. Otherwise, nil is
         # returned.
         #
@@ -309,6 +319,8 @@ module Orb
           @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 Orb
             .to_h
         end
 
+        class << self
+          # @api private
+          #
+          # @param model [Orb::Internal::Type::BaseModel]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def walk(model)
+            walk = ->(x) do
+              case x
+              in Orb::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) = Orb::Internal::Type::Converter.dump(self.class, self).to_json(*a)
 
+        # @api public
+        #
         # @param a [Object]
         #
         # @return [String]
@@ -350,7 +389,7 @@ module Orb
 
         # Create a new instance of a model.
         #
-        # @param data [Hash{Symbol=>Object}, Orb::Internal::Type::BaseModel]
+        # @param data [Hash{Symbol=>Object}, self]
         def initialize(data = {})
           case Orb::Internal::Util.coerce_hash(data)
           in Hash => coerced
@@ -361,15 +400,38 @@ module Orb
           end
         end
 
-        # @return [String]
-        def inspect
-          rows = self.class.known_fields.keys.map do
-            "#{_1}=#{@data.key?(_1) ? public_send(_1) : ''}"
-          rescue Orb::Errors::ConversionError
-            "#{_1}=#{@data.fetch(_1)}"
+        class << self
+          # @api private
+          #
+          # @param depth [Integer]
+          #
+          # @return [String]
+          def inspect(depth: 0)
+            return super() if depth.positive?
+
+            depth = depth.succ
+            deferred = fields.transform_values do |field|
+              type, required, nilable = field.fetch_values(:type, :required, :nilable)
+              inspected = [
+                Orb::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
-          "#<#{self.class.name}:0x#{object_id.to_s(16)} #{rows.join(' ')}>"
         end
+
+        # @api public
+        #
+        # @return [String]
+        def to_s = self.class.walk(@data).to_s
+
+        # @api private
+        #
+        # @return [String]
+        def inspect = "#<#{self.class}:0x#{object_id.to_s(16)} #{self}>"
       end
     end
   end

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

@@ -3,19 +3,27 @@
 module Orb
   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 [Orb::Errors::APIError]
-        # @return [Orb::Internal::Type::BasePage]
+        # @return [self]
         def next_page = (raise NotImplementedError)
 
+        # @api public
+        #
         # @param blk [Proc]
         #
         # @yieldparam [generic<Elem>]
@@ -36,6 +44,7 @@ module Orb
         def initialize(client:, req:, headers:, page_data:)
           @client = client
           @req = req
+          @model = req.fetch(:model)
           super()
         end
 

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

@@ -11,11 +11,17 @@ module Orb
       class Boolean
         extend Orb::Internal::Type::Converter
 
+        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/orb/internal/type/converter.rb

@@ -43,12 +43,24 @@ module Orb
             value.string
           in Pathname | IO
             state[:can_retry] = false if value.is_a?(IO)
-            Orb::Internal::Util::SerializationAdapter.new(value)
+            Orb::FilePart.new(value)
+          in Orb::FilePart
+            state[:can_retry] = false if value.content.is_a?(IO)
+            value
           else
             value
           end
         end
 
+        # @api private
+        #
+        # @param depth [Integer]
+        #
+        # @return [String]
+        def inspect(depth: 0)
+          super()
+        end
+
         # rubocop:enable Lint/UnusedMethodArgument
 
         class << self
@@ -240,6 +252,21 @@ module Orb
               Orb::Internal::Type::Unknown.dump(value, state: state)
             end
           end
+
+          # @api private
+          #
+          # @param target [Object]
+          # @param depth [Integer]
+          #
+          # @return [String]
+          def inspect(target, depth:)
+            case target
+            in Orb::Internal::Type::Converter
+              target.inspect(depth: depth.succ)
+            else
+              target.inspect
+            end
+          end
         end
       end
     end

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

@@ -42,27 +42,31 @@ module Orb
         # 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]
         def ==(other)
-          # rubocop:disable Layout/LineLength
-          other.is_a?(Module) && other.singleton_class <= Orb::Internal::Type::Enum && other.values.to_set == values.to_set
-          # rubocop:enable Layout/LineLength
+          # rubocop:disable Style/CaseEquality
+          Orb::Internal::Type::Enum === other && other.values.to_set == values.to_set
+          # 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
@@ -103,6 +107,22 @@ module Orb
         #   #
         #   # @return [Symbol, Object]
         #   def dump(value, state:) = super
+
+        # @api private
+        #
+        # @param depth [Integer]
+        #
+        # @return [String]
+        def inspect(depth: 0)
+          if depth.positive?
+            return is_a?(Module) ? super() : self.class.name
+          end
+
+          members = values.map { Orb::Internal::Type::Converter.inspect(_1, depth: depth.succ) }
+          prefix = is_a?(Module) ? name : self.class.name
+
+          "#{prefix}[#{members.join(' | ')}]"
+        end
       end
     end
   end

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

@@ -7,26 +7,35 @@ module Orb
       #
       # @abstract
       #
-      # Either `Pathname` or `StringIO`.
-      class IOLike
+      # Either `Pathname` or `StringIO`, or `IO`, or `Orb::Internal::Type::FileInput`.
+      #
+      # Note: when `IO` is used, all retries are disabled, since many IO` streams are
+      # not rewindable.
+      class FileInput
         extend Orb::Internal::Type::Converter
 
+        private_class_method :new
+
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def self.===(other)
           case other
-          in StringIO | Pathname | IO
+          in Pathname | StringIO | IO | String | Orb::FilePart
             true
           else
             false
           end
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
-        def self.==(other) = other.is_a?(Class) && other <= Orb::Internal::Type::IOLike
+        def self.==(other) = other.is_a?(Class) && other <= Orb::Internal::Type::FileInput
 
         class << self
           # @api private
@@ -57,17 +66,28 @@ module Orb
             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 Orb::FilePart if value.content.is_a?(IO)
+              state[:can_retry] = false
+            else
+            end
+            # rubocop:enable Lint/DuplicateBranch
+
+            value
+          end
         end
       end
     end

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

@@ -13,6 +13,10 @@ module Orb
       class HashOf
         include Orb::Internal::Type::Converter
 
+        private_class_method :new
+
+        # @overload [](type_info, spec = {})
+        #
         # @param type_info [Hash{Symbol=>Object}, Proc, Orb::Internal::Type::Converter, Class]
         #
         # @param spec [Hash{Symbol=>Object}] .
@@ -24,8 +28,12 @@ module Orb
         #   @option spec [Proc] :union
         #
         #   @option spec [Boolean] :"nil?"
-        def self.[](type_info, spec = {}) = new(type_info, spec)
+        #
+        # @return [Orb::Internal::Type::HashOf]
+        def self.[](...) = new(...)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -46,6 +54,8 @@ module Orb
           end
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -55,6 +65,11 @@ module Orb
           # rubocop:enable Layout/LineLength
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, item_type].hash
+
         # @api private
         #
         # @param value [Hash{Object=>Object}, Object]
@@ -140,7 +155,18 @@ module Orb
         #   @option spec [Boolean] :"nil?"
         def initialize(type_info, spec = {})
           @item_type_fn = Orb::Internal::Type::Converter.type_info(type_info || spec)
-          @nilable = spec[:nil?]
+          @nilable = spec.fetch(:nil?, false)
+        end
+
+        # @api private
+        #
+        # @param depth [Integer]
+        #
+        # @return [String]
+        def inspect(depth: 0)
+          items = Orb::Internal::Type::Converter.inspect(item_type, depth: depth.succ)
+
+          "#{self.class}[#{[items, nilable? ? 'nil' : nil].compact.join(' | ')}]"
         end
       end
     end

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

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

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

@@ -58,7 +58,7 @@ module Orb
         #
         # @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.
@@ -127,6 +127,8 @@ module Orb
         # rubocop:disable Style/HashEachMethods
         # rubocop:disable Style/CaseEquality
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -136,15 +138,20 @@ module Orb
           end
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def ==(other)
-          # rubocop:disable Layout/LineLength
-          other.is_a?(Module) && other.singleton_class <= Orb::Internal::Type::Union && other.derefed_variants == derefed_variants
-          # rubocop:enable Layout/LineLength
+          Orb::Internal::Type::Union === other && other.derefed_variants == derefed_variants
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = variants.hash
+
         # @api private
         #
         # @param value [Object]
@@ -225,6 +232,22 @@ module Orb
 
         # rubocop:enable Style/CaseEquality
         # rubocop:enable Style/HashEachMethods
+
+        # @api private
+        #
+        # @param depth [Integer]
+        #
+        # @return [String]
+        def inspect(depth: 0)
+          if depth.positive?
+            return is_a?(Module) ? super() : self.class.name
+          end
+
+          members = variants.map { Orb::Internal::Type::Converter.inspect(_1, depth: depth.succ) }
+          prefix = is_a?(Module) ? name : self.class.name
+
+          "#{prefix}[#{members.join(' | ')}]"
+        end
       end
     end
   end

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

@@ -13,11 +13,17 @@ module Orb
 
         # rubocop:disable Lint/UnusedMethodArgument
 
+        private_class_method :new
+
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def self.===(other) = true
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]