orb-billing 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b20102d8611954dcd1c5682addb7eb5d7b54314f2a38a14ac662e61fdd3084d5
-  data.tar.gz: '0857f6afda9adda33b5370837b17c5ab08e2bead3d708a3554e0c23c4398c2de'
+  metadata.gz: 6367789d025f1cbcd45171eca19809e1cb2cdff2c24af5335fac8641c876b093
+  data.tar.gz: 57a3c5bcb71ebf4f3e78b4412b386616cc1e37fc6adc682f38f13a129bc9aed4
 SHA512:
-  metadata.gz: a2641bfb912356b7b5458ffa63da5c444a75c651dc14984a863badfb4b461e1b06da20ac25153dfa4d1e8176411268b541777f631cf75300b1704dfc0316a417
-  data.tar.gz: 51816a9538c1d9e475afd9bc3e027aa4ef09874850ebb0d12d0c3b662c63315ef1a61e28e3d271ad83e3c529d8dddb545eace95b2fafa4c6e6689edbd63cb2a2
+  metadata.gz: 62f9112f730c3b05638d410aba2302c4ce137f46ad72e4a888636eff8eacc0f6649a41d69726f05e05ffb82d2de1fe9996f72556e537f065b43d415ffeb1024d
+  data.tar.gz: a0f8bd39183054afa8f172d776b20c54c08019b04001b00b33878fb4a69e6c0a0b54038bd7072e930fb85b2a070012fabf6319b4b2ce34195844b9f3b2cbe90a

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.3.0 (2025-04-25)
+
+Full Changelog: [v0.2.0...v0.3.0](https://github.com/orbcorp/orb-ruby/compare/v0.2.0...v0.3.0)
+
+### Features
+
+* implement `#hash` for data containers ([ba49d29](https://github.com/orbcorp/orb-ruby/commit/ba49d294bfa09eca64b9a137c730c452318a56d4))
+* support specifying content-type with FilePart class ([200103f](https://github.com/orbcorp/orb-ruby/commit/200103fddf8b1d524caa1cb3a126d72b476315f4))
+* support webmock for testing ([ca1c497](https://github.com/orbcorp/orb-ruby/commit/ca1c497d57309c0bd2518070a0f8af3e0c639be4))
+
+
+### Bug Fixes
+
+* ensure gem release is unaffected by renaming ([3e0fd9e](https://github.com/orbcorp/orb-ruby/commit/3e0fd9e21bb02529c0513b7a1e2fbdfa7d80b049))
+* make a typo for `FilePart.content` ([f62d185](https://github.com/orbcorp/orb-ruby/commit/f62d18544ccd90a55bdfc520cbea03c1ea7583d1))
+
+
+### Chores
+
+* broadly detect json family of content-type headers ([d4e5904](https://github.com/orbcorp/orb-ruby/commit/d4e5904287b32db4efe997b617310670961be6b1))
+* **ci:** add timeout thresholds for CI jobs ([450f552](https://github.com/orbcorp/orb-ruby/commit/450f552e892e75242d3ec3e3e0c98605e1ac0b61))
+* **ci:** only use depot for staging repos ([fd387ce](https://github.com/orbcorp/orb-ruby/commit/fd387ce6f9dff526039887480712e8b0c35595b5))
+* **ci:** run on more branches and use depot runners ([7f5a6c3](https://github.com/orbcorp/orb-ruby/commit/7f5a6c320853a23d5ac339ea368d7cad7bbc35c5))
+* documentation improvements ([6e04e50](https://github.com/orbcorp/orb-ruby/commit/6e04e5062b468fdf1f40fe3cd491b9fbb610bc5c))
+* explicitly mark apis public under `Internal` module ([d19524a](https://github.com/orbcorp/orb-ruby/commit/d19524a2a412b98ac4529b46c02e249e8a587c34))
+* **internal:** improve response envelope unwrap functionality ([b3f0632](https://github.com/orbcorp/orb-ruby/commit/b3f0632eae23d838395933fe4a334fd23dff46fd))
+* **internal:** minor type annotation improvements ([cf871bc](https://github.com/orbcorp/orb-ruby/commit/cf871bca5feacf6e95351418a3553c774889ccee))
+* **internal:** version bump ([6b83db6](https://github.com/orbcorp/orb-ruby/commit/6b83db65c3d405b7f7c5e20a93be6428dcf7fc08))
+* make sorbet enums easier to read ([3793346](https://github.com/orbcorp/orb-ruby/commit/3793346c4a6cd6ff18aad64e4c48933a5159ebe1))
+* show truncated parameter docs in yard ([0fb86bd](https://github.com/orbcorp/orb-ruby/commit/0fb86bd1313bb300e565f873e5a181f652ce88fa))
+* simplify yard annotations by removing most `@!parse` directives ([a94843b](https://github.com/orbcorp/orb-ruby/commit/a94843be3f13ed22ae07ded47bff22e044525f0b))
+* update README with recommended editor plugins ([50771fd](https://github.com/orbcorp/orb-ruby/commit/50771fdf28dcee2856522c5c29a491873ec14a4a))
+* use `@!method` instead of `@!parse` for virtual method type definitions ([21cfdfc](https://github.com/orbcorp/orb-ruby/commit/21cfdfcc91f9dbd04831e502b990f9118f4b5eb0))
+
 ## 0.2.0 (2025-04-17)
 
 Full Changelog: [v0.1.3...v0.2.0](https://github.com/orbcorp/orb-ruby/compare/v0.1.3...v0.2.0)

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 "orb-billing", "~> 0.2.0"
+gem "orb-billing", "~> 0.3.0"
 ```
 
 <!-- x-release-please-end -->
@@ -35,6 +35,16 @@ customer = orb.customers.create(email: "example-customer@withorb.com", name: "My
 puts(customer.id)
 ```
 
+## 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
+orb.customers.create(email: "example-customer@withorb.com", name: "My Customer")
+```
+
 ### Pagination
 
 List methods in the Orb API are paginated.
@@ -126,61 +136,33 @@ orb.customers.create(
 )
 ```
 
-## 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/orb-billing-*/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/orb/models`.
 
-Due to limitations with the Sorbet type system, where a method otherwise can take an instance of `Orb::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
+# This has tooling readability, for auto-completion, static analysis, and goto definition with supported language services
 params = Orb::Models::CustomerCreateParams.new(email: "example-customer@withorb.com", name: "My Customer")
 
-orb.customers.create(**params)
+# This also works
+params = {
+  email: "example-customer@withorb.com",
+  name: "My Customer"
+}
 ```
 
-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.
@@ -191,15 +173,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 `Orb::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.
 
@@ -209,6 +191,30 @@ Unless otherwise specified, other classes in the SDK do not have locks protectin
 
 Currently, `Orb::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 Orb::Models::BillingCycleRelativeDate
+  # This alias aids language service driven navigation.
+  TaggedSymbol = T.type_alias { T.all(Symbol, Orb::Models::BillingCycleRelativeDate) }
+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 = Orb::Models::CustomerCreateParams.new(email: "example-customer@withorb.com", name: "My Customer")
+orb.customers.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.
@@ -218,3 +224,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/orbcorp/orb-ruby/tree/main/CONTRIBUTING.md).

data/lib/orb/client.rb

@@ -91,10 +91,10 @@ module Orb
     def initialize(
       api_key: ENV["ORB_API_KEY"],
       base_url: ENV["ORB_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: Orb::Client::DEFAULT_MAX_RETRIES,
+      timeout: Orb::Client::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: Orb::Client::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: Orb::Client::DEFAULT_MAX_RETRY_DELAY,
       idempotency_header: "Idempotency-Key"
     )
       base_url ||= "https://api.withorb.com/v1"

data/lib/orb/file_part.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Orb
+  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/orb/internal/page.rb

@@ -28,7 +28,7 @@ module Orb
       end
 
       # @raise [Orb::HTTP::Error]
-      # @return [Orb::Internal::Page]
+      # @return [self]
       def next_page
         unless next_page?
           message = "No more pages available. Please check #next_page? before calling ##{__method__}"
@@ -101,13 +101,9 @@ module Orb
         #   @return [String, nil]
         required :next_cursor, String, nil?: true
 
-        # @!parse
-        #   # @param has_more [Boolean]
-        #   # @param next_cursor [String, nil]
-        #   #
-        #   def initialize(has_more:, next_cursor:, **) = super
-
-        # def initialize: (Hash | Orb::Internal::Type::BaseModel) -> void
+        # @!method initialize(has_more:, next_cursor:)
+        #   @param has_more [Boolean]
+        #   @param next_cursor [String, nil]
       end
     end
   end

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

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

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

@@ -61,7 +61,7 @@ module Orb
               method.to_s.upcase,
               !body.nil?,
               method != :head,
-              url.to_s
+              URI(url.to_s) # ensure we construct a URI class of the right scheme
             )
 
             headers.each { req[_1] = _2 }
@@ -176,7 +176,7 @@ module Orb
             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/orb/internal/type/array_of.rb

@@ -28,13 +28,19 @@ module Orb
         #   @option spec [Proc] :union
         #
         #   @option spec [Boolean] :"nil?"
+        #
+        # @return [Orb::Internal::Type::ArrayOf]
         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 +50,11 @@ module Orb
           # 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/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
 
@@ -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
@@ -339,6 +351,8 @@ module Orb
         end
 
         class << self
+          # @api private
+          #
           # @param model [Orb::Internal::Type::BaseModel]
           #
           # @return [Hash{Symbol=>Object}]
@@ -359,11 +373,15 @@ module Orb
           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]
@@ -371,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
@@ -405,7 +423,7 @@ module Orb
           end
         end
 
-        # @api private
+        # @api public
         #
         # @return [String]
         def to_s = self.class.walk(@data).to_s

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>]

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

@@ -13,11 +13,15 @@ module Orb
 
         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,7 +43,10 @@ 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

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

@@ -42,18 +42,17 @@ 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]
@@ -63,6 +62,11 @@ module Orb
           # 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