orb-billing 0.1.2 → 0.2.0

data/README.md

@@ -4,9 +4,9 @@ The Orb Ruby library provides convenient access to the Orb REST API from any Rub
 
 ## Documentation
 
-Documentation for released of this gem can be found [on RubyDoc](https://gemdocs.org/gems/orb-billing).
+Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/orb-billing).
 
-The underlying REST API documentation can be found on [docs.withorb.com](https://docs.withorb.com/reference/api-reference).
+The REST API documentation can be found on [docs.withorb.com](https://docs.withorb.com/reference/api-reference).
 
 ## Installation
 
@@ -15,22 +15,16 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "orb-billing", "~> 0.1.2"
+gem "orb-billing", "~> 0.2.0"
 ```
 
 <!-- x-release-please-end -->
 
-To fetch an initial copy of the gem:
-
-```sh
-bundle install
-```
-
 ## Usage
 
 ```ruby
 require "bundler/setup"
-require "orb-billing"
+require "orb"
 
 orb = Orb::Client.new(
   api_key: "My API Key" # defaults to ENV["ORB_API_KEY"]
@@ -62,7 +56,7 @@ end
 
 ### Errors
 
-When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Orb::Error` will be thrown:
+When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Orb::Errors::APIError` will be thrown:
 
 ```ruby
 begin
@@ -168,8 +162,7 @@ Due to limitations with the Sorbet type system, where a method otherwise can tak
 Please follow Sorbet's [setup guides](https://sorbet.org/docs/adopting) for best experience.
 
 ```ruby
-params =
-  Orb::Models::CustomerCreateParams.new(email: "example-customer@withorb.com", name: "My Customer")
+params = Orb::Models::CustomerCreateParams.new(email: "example-customer@withorb.com", name: "My Customer")
 
 orb.customers.create(**params)
 ```
@@ -197,8 +190,7 @@ If you want to explicitly send an extra param, you can do so with the `extra_que
 To make requests to undocumented endpoints, you can make requests using `client.request`. Options on the client will be respected (such as retries) when making this request.
 
 ```ruby
-response =
-  client.request(
+response = client.request(
     method: :post,
     path: '/undocumented/endpoint',
     query: {"dog": "woof"},

data/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Reporting Security Issues
+
+This SDK is generated by [Stainless Software Inc](http://stainless.com). Stainless takes security seriously, and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
+
+To report a security issue, please contact the Stainless team at security@stainless.com.
+
+## Responsible Disclosure
+
+We appreciate the efforts of security researchers and individuals who help us maintain the security of
+SDKs we generate. If you believe you have found a security vulnerability, please adhere to responsible
+disclosure practices by allowing us a reasonable amount of time to investigate and address the issue
+before making any information public.
+
+## Reporting Non-SDK Related Security Issues
+
+If you encounter security issues that are not directly related to SDKs but pertain to the services
+or products provided by Orb please follow the respective company's security reporting guidelines.
+
+### Orb Terms and Policies
+
+Please contact team@withorb.com for any questions or concerns regarding security of our services.
+
+---
+
+Thank you for helping us keep the SDKs and systems they interact with secure.

data/lib/orb/client.rb

@@ -76,7 +76,8 @@ module Orb
     #
     # @param api_key [String, nil] Defaults to `ENV["ORB_API_KEY"]`
     #
-    # @param base_url [String, nil] Override the default base URL for the API, e.g., `"https://api.example.com/v2/"`
+    # @param base_url [String, nil] Override the default base URL for the API, e.g.,
+    # `"https://api.example.com/v2/"`. Defaults to `ENV["ORB_BASE_URL"]`
     #
     # @param max_retries [Integer] Max number of retries to attempt after a failed retryable request.
     #
@@ -89,7 +90,7 @@ module Orb
     # @param idempotency_header [String]
     def initialize(
       api_key: ENV["ORB_API_KEY"],
-      base_url: nil,
+      base_url: ENV["ORB_BASE_URL"],
       max_retries: DEFAULT_MAX_RETRIES,
       timeout: DEFAULT_TIMEOUT_IN_SECONDS,
       initial_retry_delay: DEFAULT_INITIAL_RETRY_DELAY,

data/lib/orb/internal/page.rb

@@ -22,33 +22,6 @@ module Orb
       # @return [PaginationMetadata]
       attr_accessor :pagination_metadata
 
-      # @api private
-      #
-      # @param client [Orb::Internal::Transport::BaseClient]
-      # @param req [Hash{Symbol=>Object}]
-      # @param headers [Hash{String=>String}, Net::HTTPHeader]
-      # @param page_data [Hash{Symbol=>Object}]
-      def initialize(client:, req:, headers:, page_data:)
-        super
-        model = req.fetch(:model)
-
-        case page_data
-        in {data: Array | nil => data}
-          @data = data&.map { Orb::Internal::Type::Converter.coerce(model, _1) }
-        else
-        end
-
-        case page_data
-        in {pagination_metadata: Hash | nil => pagination_metadata}
-          @pagination_metadata =
-            Orb::Internal::Type::Converter.coerce(
-              Orb::Internal::Page::PaginationMetadata,
-              pagination_metadata
-            )
-        else
-        end
-      end
-
       # @return [Boolean]
       def next_page?
         !pagination_metadata&.next_cursor.nil?
@@ -73,19 +46,48 @@ module Orb
         unless block_given?
           raise ArgumentError.new("A block must be given to ##{__method__}")
         end
+
         page = self
         loop do
-          page.data&.each { blk.call(_1) }
+          page.data&.each(&blk)
+
           break unless page.next_page?
           page = page.next_page
         end
       end
 
+      # @api private
+      #
+      # @param client [Orb::Internal::Transport::BaseClient]
+      # @param req [Hash{Symbol=>Object}]
+      # @param headers [Hash{String=>String}, Net::HTTPHeader]
+      # @param page_data [Hash{Symbol=>Object}]
+      def initialize(client:, req:, headers:, page_data:)
+        super
+
+        case page_data
+        in {data: Array | nil => data}
+          @data = data&.map { Orb::Internal::Type::Converter.coerce(@model, _1) }
+        else
+        end
+        case page_data
+        in {pagination_metadata: Hash | nil => pagination_metadata}
+          @pagination_metadata =
+            Orb::Internal::Type::Converter.coerce(
+              Orb::Internal::Page::PaginationMetadata,
+              pagination_metadata
+            )
+        else
+        end
+      end
+
+      # @api private
+      #
       # @return [String]
       def inspect
-        # rubocop:disable Layout/LineLength
-        "#<#{self.class}:0x#{object_id.to_s(16)} data=#{data.inspect} pagination_metadata=#{pagination_metadata.inspect}>"
-        # rubocop:enable Layout/LineLength
+        model = Orb::Internal::Type::Converter.inspect(@model, depth: 1)
+
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)}>"
       end
 
       class PaginationMetadata < Orb::Internal::Type::BaseModel

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

@@ -93,7 +93,11 @@ module Orb
                 URI.join(url, response_headers["location"])
               rescue ArgumentError
                 message = "Server responded with status #{status} but no valid location header."
-                raise Orb::Errors::APIConnectionError.new(url: url, message: message)
+                raise Orb::Errors::APIConnectionError.new(
+                  url: url,
+                  response: response_headers,
+                  message: message
+                )
               end
 
             request = {**request, url: location}
@@ -101,7 +105,11 @@ module Orb
             case [url.scheme, location.scheme]
             in ["https", "http"]
               message = "Tried to redirect to a insecure URL"
-              raise Orb::Errors::APIConnectionError.new(url: url, message: message)
+              raise Orb::Errors::APIConnectionError.new(
+                url: url,
+                response: response_headers,
+                message: message
+              )
             else
               nil
             end
@@ -245,7 +253,7 @@ module Orb
 
           if @idempotency_header &&
              !headers.key?(@idempotency_header) &&
-             !Net::HTTP::IDEMPOTENT_METHODS_.include?(method.to_s.upcase)
+             (!Net::HTTP::IDEMPOTENT_METHODS_.include?(method.to_s.upcase) || opts.key?(:idempotency_key))
             headers[@idempotency_header] = opts.fetch(:idempotency_key) { generate_idempotency_key }
           end
 
@@ -350,7 +358,7 @@ module Orb
             self.class.reap_connection!(status, stream: stream)
 
             message = "Failed to complete the request within #{self.class::MAX_REDIRECTS} redirects."
-            raise Orb::Errors::APIConnectionError.new(url: url, message: message)
+            raise Orb::Errors::APIConnectionError.new(url: url, response: response, message: message)
           in 300..399
             self.class.reap_connection!(status, stream: stream)
 
@@ -460,6 +468,8 @@ module Orb
           end
         end
 
+        # @api private
+        #
         # @return [String]
         def inspect
           # rubocop:disable Layout/LineLength

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

@@ -149,7 +149,7 @@ module Orb
                 break if finished
 
                 rsp.read_body do |bytes|
-                  y << bytes
+                  y << bytes.force_encoding(Encoding::BINARY)
                   break if finished
 
                   self.class.calibrate_socket_timeout(conn, deadline)

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

@@ -13,6 +13,10 @@ module Orb
       class ArrayOf
         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,7 +28,7 @@ module Orb
         #   @option spec [Proc] :union
         #
         #   @option spec [Boolean] :"nil?"
-        def self.[](type_info, spec = {}) = new(type_info, spec)
+        def self.[](...) = new(...)
 
         # @param other [Object]
         #
@@ -120,7 +124,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/base_model.rb

@@ -63,7 +63,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)
@@ -338,6 +338,27 @@ module Orb
             .to_h
         end
 
+        class << self
+          # @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
+
         # @param a [Object]
         #
         # @return [String]
@@ -361,15 +382,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 private
+        #
+        # @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

@@ -36,6 +36,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,6 +11,8 @@ module Orb
       class Boolean
         extend Orb::Internal::Type::Converter
 
+        private_class_method :new
+
         # @param other [Object]
         #
         # @return [Boolean]

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

@@ -49,6 +49,15 @@ module Orb
           end
         end
 
+        # @api private
+        #
+        # @param depth [Integer]
+        #
+        # @return [String]
+        def inspect(depth: 0)
+          super()
+        end
+
         # rubocop:enable Lint/UnusedMethodArgument
 
         class << self
@@ -240,6 +249,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

@@ -58,9 +58,9 @@ module Orb
         #
         # @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 private
@@ -103,6 +103,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/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,7 +28,7 @@ module Orb
         #   @option spec [Proc] :union
         #
         #   @option spec [Boolean] :"nil?"
-        def self.[](type_info, spec = {}) = new(type_info, spec)
+        def self.[](...) = new(...)
 
         # @param other [Object]
         #
@@ -140,7 +144,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/io_like.rb

@@ -11,6 +11,8 @@ module Orb
       class IOLike
         extend Orb::Internal::Type::Converter
 
+        private_class_method :new
+
         # @param other [Object]
         #
         # @return [Boolean]

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

@@ -140,9 +140,7 @@ module Orb
         #
         # @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 private
@@ -225,6 +223,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,6 +13,8 @@ module Orb
 
         # rubocop:disable Lint/UnusedMethodArgument
 
+        private_class_method :new
+
         # @param other [Object]
         #
         # @return [Boolean]

data/lib/orb/internal/util.rb

@@ -448,7 +448,7 @@ module Orb
             else
               src
             end
-          @buf = String.new.b
+          @buf = String.new
           @blk = blk
         end
       end
@@ -460,7 +460,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
@@ -582,6 +582,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,7 +610,7 @@ module Orb
         # @raise [JSON::ParserError]
         # @return [Object]
         def decode_content(headers, stream:, suppress_error: false)
-          case headers["content-type"]
+          case (content_type = headers["content-type"])
           in %r{^application/(?:vnd\.api\+)?json}
             json = stream.to_a.join
             begin
@@ -606,11 +627,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 +695,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 +736,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 +761,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