orb-billing 0.1.3 → 0.3.0

data/lib/orb/internal/util.rb

@@ -175,18 +175,17 @@ module Orb
         # @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 Orb
               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 Orb
         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`
@@ -448,7 +428,7 @@ module Orb
             else
               src
             end
-          @buf = String.new.b
+          @buf = String.new
           @blk = blk
         end
       end
@@ -460,7 +440,7 @@ module Orb
         # @return [Enumerable<String>]
         def writable_enum(&blk)
           Enumerator.new do |y|
-            buf = String.new.b
+            buf = String.new
             y.define_singleton_method(:write) do
               self << buf.replace(_1)
               buf.bytesize
@@ -471,46 +451,44 @@ module Orb
         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?(Orb::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 Orb::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 Orb
           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 Orb::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 Orb
         # @return [Object]
         def encode_content(headers, body)
           content_type = headers["content-type"]
-          body = body.inner if body.is_a?(Orb::Internal::Util::SerializationAdapter)
-
           case [content_type, body]
-          in [%r{^application/(?:vnd\.api\+)?json}, Hash | Array | -> { primitive?(_1) }]
+          in [Orb::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 [Orb::Internal::Util::JSONL_CONTENT, Enumerable] unless body.is_a?(Orb::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 | Orb::Internal::Type::FileInput]
             boundary, strio = encode_multipart_streaming(body)
             headers = {**headers, "content-type" => "#{content_type}; boundary=#{boundary}"}
             [headers, strio]
@@ -575,6 +581,8 @@ module Orb
             [headers, body.to_s]
           in [_, StringIO]
             [headers, body.string]
+          in [_, Orb::FilePart]
+            [headers, body.content]
           else
             [headers, body]
           end
@@ -582,6 +590,27 @@ module Orb
 
         # @api private
         #
+        # https://www.iana.org/assignments/character-sets/character-sets.xhtml
+        #
+        # @param content_type [String]
+        # @param text [String]
+        def force_charset!(content_type, text:)
+          charset = /charset=([^;\s]+)/.match(content_type)&.captures&.first
+
+          return unless charset
+
+          begin
+            encoding = Encoding.find(charset)
+            text.force_encoding(encoding)
+          rescue ArgumentError
+            nil
+          end
+        end
+
+        # @api private
+        #
+        # Assumes each chunk in stream has `Encoding::BINARY`.
+        #
         # @param headers [Hash{String=>String}, Net::HTTPHeader]
         # @param stream [Enumerable<String>]
         # @param suppress_error [Boolean]
@@ -589,8 +618,8 @@ module Orb
         # @raise [JSON::ParserError]
         # @return [Object]
         def decode_content(headers, stream:, suppress_error: false)
-          case headers["content-type"]
-          in %r{^application/(?:vnd\.api\+)?json}
+          case (content_type = headers["content-type"])
+          in Orb::Internal::Util::JSON_CONTENT
             json = stream.to_a.join
             begin
               JSON.parse(json, symbolize_names: true)
@@ -598,7 +627,7 @@ module Orb
               raise e unless suppress_error
               json
             end
-          in %r{^application/(?:x-)?jsonl}
+          in Orb::Internal::Util::JSONL_CONTENT
             lines = decode_lines(stream)
             chain_fused(lines) do |y|
               lines.each { y << JSON.parse(_1, symbolize_names: true) }
@@ -606,11 +635,10 @@ module Orb
           in %r{^text/event-stream}
             lines = decode_lines(stream)
             decode_sse(lines)
-          in %r{^text/}
-            stream.to_a.join
           else
-            # TODO: parsing other response types
-            StringIO.new(stream.to_a.join)
+            text = stream.to_a.join
+            force_charset!(content_type, text: text)
+            StringIO.new(text)
           end
         end
       end
@@ -675,12 +703,17 @@ module Orb
       class << self
         # @api private
         #
+        # Assumes Strings have been forced into having `Encoding::BINARY`.
+        #
+        # This decoder is responsible for reassembling lines split across multiple
+        # fragments.
+        #
         # @param enum [Enumerable<String>]
         #
         # @return [Enumerable<String>]
         def decode_lines(enum)
           re = /(\r\n|\r|\n)/
-          buffer = String.new.b
+          buffer = String.new
           cr_seen = nil
 
           chain_fused(enum) do |y|
@@ -711,6 +744,8 @@ module Orb
         #
         # https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream
         #
+        # Assumes that `lines` has been decoded with `#decode_lines`.
+        #
         # @param lines [Enumerable<String>]
         #
         # @return [Enumerable<Hash{Symbol=>Object}>]
@@ -734,7 +769,7 @@ module Orb
                 in "event"
                   current.merge!(event: value)
                 in "data"
-                  (current[:data] ||= String.new.b) << (value << "\n")
+                  (current[:data] ||= String.new) << (value << "\n")
                 in "id" unless value.include?("\0")
                   current.merge!(id: value)
                 in "retry" if /^\d+$/ =~ value

data/lib/orb/internal.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 module Orb
-  # @api private
   module Internal
-    OMIT = Object.new.freeze
+    OMIT =
+      Object.new.tap do
+        _1.define_singleton_method(:inspect) { "#<#{Orb::Internal}::OMIT>" }
+      end
+        .freeze
   end
 end

data/lib/orb/models/alert.rb

@@ -65,27 +65,36 @@ module Orb
       #   @return [Symbol, Orb::Models::Alert::Type]
       required :type, enum: -> { Orb::Models::Alert::Type }
 
-      # @!parse
-      #   # [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending,
-      #   # usage, or credit balance and trigger webhooks when a threshold is exceeded.
-      #   #
-      #   # Alerts created through the API can be scoped to either customers or
-      #   # subscriptions.
-      #   #
-      #   # @param id [String]
-      #   # @param created_at [Time]
-      #   # @param currency [String, nil]
-      #   # @param customer [Orb::Models::Alert::Customer, nil]
-      #   # @param enabled [Boolean]
-      #   # @param metric [Orb::Models::Alert::Metric, nil]
-      #   # @param plan [Orb::Models::Alert::Plan, nil]
-      #   # @param subscription [Orb::Models::Alert::Subscription, nil]
-      #   # @param thresholds [Array<Orb::Models::Alert::Threshold>, nil]
-      #   # @param type [Symbol, Orb::Models::Alert::Type]
-      #   #
-      #   def initialize(id:, created_at:, currency:, customer:, enabled:, metric:, plan:, subscription:, thresholds:, type:, **) = super
-
-      # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+      # @!method initialize(id:, created_at:, currency:, customer:, enabled:, metric:, plan:, subscription:, thresholds:, type:)
+      #   Some parameter documentations has been truncated, see {Orb::Models::Alert} for
+      #   more details.
+      #
+      #   [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending,
+      #   usage, or credit balance and trigger webhooks when a threshold is exceeded.
+      #
+      #   Alerts created through the API can be scoped to either customers or
+      #   subscriptions.
+      #
+      #   @param id [String] Also referred to as alert_id in this documentation.
+      #
+      #   @param created_at [Time] The creation time of the resource in Orb.
+      #
+      #   @param currency [String, nil] The name of the currency the credit balance or invoice cost is denominated in.
+      #
+      #   @param customer [Orb::Models::Alert::Customer, nil] The customer the alert applies to.
+      #
+      #   @param enabled [Boolean] Whether the alert is enabled or disabled.
+      #
+      #   @param metric [Orb::Models::Alert::Metric, nil] The metric the alert applies to.
+      #
+      #   @param plan [Orb::Models::Alert::Plan, nil] The plan the alert applies to.
+      #
+      #   @param subscription [Orb::Models::Alert::Subscription, nil] The subscription the alert applies to.
+      #
+      #   @param thresholds [Array<Orb::Models::Alert::Threshold>, nil] The thresholds that define the conditions under which the alert will be triggere
+      #   ...
+      #
+      #   @param type [Symbol, Orb::Models::Alert::Type] The type of alert. This must be a valid alert type.
 
       # @see Orb::Models::Alert#customer
       class Customer < Orb::Internal::Type::BaseModel
@@ -99,15 +108,11 @@ module Orb
         #   @return [String, nil]
         required :external_customer_id, String, nil?: true
 
-        # @!parse
-        #   # The customer the alert applies to.
-        #   #
-        #   # @param id [String]
-        #   # @param external_customer_id [String, nil]
-        #   #
-        #   def initialize(id:, external_customer_id:, **) = super
-
-        # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+        # @!method initialize(id:, external_customer_id:)
+        #   The customer the alert applies to.
+        #
+        #   @param id [String]
+        #   @param external_customer_id [String, nil]
       end
 
       # @see Orb::Models::Alert#metric
@@ -117,14 +122,10 @@ module Orb
         #   @return [String]
         required :id, String
 
-        # @!parse
-        #   # The metric the alert applies to.
-        #   #
-        #   # @param id [String]
-        #   #
-        #   def initialize(id:, **) = super
-
-        # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+        # @!method initialize(id:)
+        #   The metric the alert applies to.
+        #
+        #   @param id [String]
       end
 
       # @see Orb::Models::Alert#plan
@@ -152,17 +153,20 @@ module Orb
         #   @return [String]
         required :plan_version, String
 
-        # @!parse
-        #   # The plan the alert applies to.
-        #   #
-        #   # @param id [String, nil]
-        #   # @param external_plan_id [String, nil]
-        #   # @param name [String, nil]
-        #   # @param plan_version [String]
-        #   #
-        #   def initialize(id:, external_plan_id:, name:, plan_version:, **) = super
-
-        # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+        # @!method initialize(id:, external_plan_id:, name:, plan_version:)
+        #   Some parameter documentations has been truncated, see {Orb::Models::Alert::Plan}
+        #   for more details.
+        #
+        #   The plan the alert applies to.
+        #
+        #   @param id [String, nil]
+        #
+        #   @param external_plan_id [String, nil] An optional user-defined ID for this plan resource, used throughout the system a
+        #   ...
+        #
+        #   @param name [String, nil]
+        #
+        #   @param plan_version [String]
       end
 
       # @see Orb::Models::Alert#subscription
@@ -172,14 +176,10 @@ module Orb
         #   @return [String]
         required :id, String
 
-        # @!parse
-        #   # The subscription the alert applies to.
-        #   #
-        #   # @param id [String]
-        #   #
-        #   def initialize(id:, **) = super
-
-        # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+        # @!method initialize(id:)
+        #   The subscription the alert applies to.
+        #
+        #   @param id [String]
       end
 
       class Threshold < Orb::Internal::Type::BaseModel
@@ -191,15 +191,15 @@ module Orb
         #   @return [Float]
         required :value, Float
 
-        # @!parse
-        #   # Thresholds are used to define the conditions under which an alert will be
-        #   # triggered.
-        #   #
-        #   # @param value [Float]
-        #   #
-        #   def initialize(value:, **) = super
-
-        # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+        # @!method initialize(value:)
+        #   Some parameter documentations has been truncated, see
+        #   {Orb::Models::Alert::Threshold} for more details.
+        #
+        #   Thresholds are used to define the conditions under which an alert will be
+        #   triggered.
+        #
+        #   @param value [Float] The value at which an alert will fire. For credit balance alerts, the alert will
+        #   ...
       end
 
       # The type of alert. This must be a valid alert type.
@@ -214,11 +214,8 @@ module Orb
         USAGE_EXCEEDED = :usage_exceeded
         COST_EXCEEDED = :cost_exceeded
 
-        finalize!
-
-        # @!parse
-        #   # @return [Array<Symbol>]
-        #   def self.values; end
+        # @!method self.values
+        #   @return [Array<Symbol>]
       end
     end
   end

data/lib/orb/models/alert_create_for_customer_params.rb

@@ -4,8 +4,7 @@ module Orb
   module Models
     # @see Orb::Resources::Alerts#create_for_customer
     class AlertCreateForCustomerParams < Orb::Internal::Type::BaseModel
-      # @!parse
-      #   extend Orb::Internal::Type::RequestParameters::Converter
+      extend Orb::Internal::Type::RequestParameters::Converter
       include Orb::Internal::Type::RequestParameters
 
       # @!attribute currency
@@ -28,15 +27,14 @@ module Orb
                -> { Orb::Internal::Type::ArrayOf[Orb::Models::AlertCreateForCustomerParams::Threshold] },
                nil?: true
 
-      # @!parse
-      #   # @param currency [String]
-      #   # @param type [Symbol, Orb::Models::AlertCreateForCustomerParams::Type]
-      #   # @param thresholds [Array<Orb::Models::AlertCreateForCustomerParams::Threshold>, nil]
-      #   # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}]
-      #   #
-      #   def initialize(currency:, type:, thresholds: nil, request_options: {}, **) = super
-
-      # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+      # @!method initialize(currency:, type:, thresholds: nil, request_options: {})
+      #   @param currency [String] The case sensitive currency or custom pricing unit to use for this alert.
+      #
+      #   @param type [Symbol, Orb::Models::AlertCreateForCustomerParams::Type] The type of alert to create. This must be a valid alert type.
+      #
+      #   @param thresholds [Array<Orb::Models::AlertCreateForCustomerParams::Threshold>, nil] The thresholds that define the values at which the alert will be triggered.
+      #
+      #   @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}]
 
       # The type of alert to create. This must be a valid alert type.
       module Type
@@ -46,11 +44,8 @@ module Orb
         CREDIT_BALANCE_DROPPED = :credit_balance_dropped
         CREDIT_BALANCE_RECOVERED = :credit_balance_recovered
 
-        finalize!
-
-        # @!parse
-        #   # @return [Array<Symbol>]
-        #   def self.values; end
+        # @!method self.values
+        #   @return [Array<Symbol>]
       end
 
       class Threshold < Orb::Internal::Type::BaseModel
@@ -62,15 +57,15 @@ module Orb
         #   @return [Float]
         required :value, Float
 
-        # @!parse
-        #   # Thresholds are used to define the conditions under which an alert will be
-        #   # triggered.
-        #   #
-        #   # @param value [Float]
-        #   #
-        #   def initialize(value:, **) = super
-
-        # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+        # @!method initialize(value:)
+        #   Some parameter documentations has been truncated, see
+        #   {Orb::Models::AlertCreateForCustomerParams::Threshold} for more details.
+        #
+        #   Thresholds are used to define the conditions under which an alert will be
+        #   triggered.
+        #
+        #   @param value [Float] The value at which an alert will fire. For credit balance alerts, the alert will
+        #   ...
       end
     end
   end

data/lib/orb/models/alert_create_for_external_customer_params.rb

@@ -4,8 +4,7 @@ module Orb
   module Models
     # @see Orb::Resources::Alerts#create_for_external_customer
     class AlertCreateForExternalCustomerParams < Orb::Internal::Type::BaseModel
-      # @!parse
-      #   extend Orb::Internal::Type::RequestParameters::Converter
+      extend Orb::Internal::Type::RequestParameters::Converter
       include Orb::Internal::Type::RequestParameters
 
       # @!attribute currency
@@ -28,15 +27,14 @@ module Orb
                -> { Orb::Internal::Type::ArrayOf[Orb::Models::AlertCreateForExternalCustomerParams::Threshold] },
                nil?: true
 
-      # @!parse
-      #   # @param currency [String]
-      #   # @param type [Symbol, Orb::Models::AlertCreateForExternalCustomerParams::Type]
-      #   # @param thresholds [Array<Orb::Models::AlertCreateForExternalCustomerParams::Threshold>, nil]
-      #   # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}]
-      #   #
-      #   def initialize(currency:, type:, thresholds: nil, request_options: {}, **) = super
-
-      # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+      # @!method initialize(currency:, type:, thresholds: nil, request_options: {})
+      #   @param currency [String] The case sensitive currency or custom pricing unit to use for this alert.
+      #
+      #   @param type [Symbol, Orb::Models::AlertCreateForExternalCustomerParams::Type] The type of alert to create. This must be a valid alert type.
+      #
+      #   @param thresholds [Array<Orb::Models::AlertCreateForExternalCustomerParams::Threshold>, nil] The thresholds that define the values at which the alert will be triggered.
+      #
+      #   @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}]
 
       # The type of alert to create. This must be a valid alert type.
       module Type
@@ -46,11 +44,8 @@ module Orb
         CREDIT_BALANCE_DROPPED = :credit_balance_dropped
         CREDIT_BALANCE_RECOVERED = :credit_balance_recovered
 
-        finalize!
-
-        # @!parse
-        #   # @return [Array<Symbol>]
-        #   def self.values; end
+        # @!method self.values
+        #   @return [Array<Symbol>]
       end
 
       class Threshold < Orb::Internal::Type::BaseModel
@@ -62,15 +57,15 @@ module Orb
         #   @return [Float]
         required :value, Float
 
-        # @!parse
-        #   # Thresholds are used to define the conditions under which an alert will be
-        #   # triggered.
-        #   #
-        #   # @param value [Float]
-        #   #
-        #   def initialize(value:, **) = super
-
-        # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+        # @!method initialize(value:)
+        #   Some parameter documentations has been truncated, see
+        #   {Orb::Models::AlertCreateForExternalCustomerParams::Threshold} for more details.
+        #
+        #   Thresholds are used to define the conditions under which an alert will be
+        #   triggered.
+        #
+        #   @param value [Float] The value at which an alert will fire. For credit balance alerts, the alert will
+        #   ...
       end
     end
   end