orb-billing 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a8aab7ea27e9f429fb79d85663cb238393ef06c60acb43e7c1f4285658cdd2f
-  data.tar.gz: b48c4f83c56e09e04e50e10bb89c865c5fb72143f4a42dbd96e83cc183975fa8
+  metadata.gz: 4ce1529e168d4f47f75f48505cf8e528afc2056e95f075f4611382b97374d1a2
+  data.tar.gz: c4f6bd8086298f6950ddeed3480ee75a60836463355acd7f0bb5d70fff40b359
 SHA512:
-  metadata.gz: a5e2ba15a48f4b458f9758393a6f421d4b795e44b3ecf5f7f7e7dfdba71c139b26a229cd4956d2d4269d1f5df689e9fc583ced8da055ab59403f0372b24ed1d4
-  data.tar.gz: ca4923f45449e5f4187ad9bd4cabf2abbdea4c2e593f2f294607e1e2cf8ce5efe3e2f311ee2371a85cbf4ceba724fa2de98d30d9521fa8f10f9262214fd52a54
+  metadata.gz: d6a7ff2c8e6ec173a053c6ad9635cd97f372b08baf61bee105e1c736706fa265ebcc90b1a2dbeb05c0d67f5adfb56d157ccc5d355e06b3ce2340c78cdb056a20
+  data.tar.gz: 90bc92e99e52b0cb51a208337ccd2d4a6d6cb39cad3990db8518b886c3b471188e0a2981cbb769058cef19f2e391ef78b80eaa721befe6180cc531bcc4bd68aa

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.5.0 (2025-05-14)
+
+Full Changelog: [v0.4.0...v0.5.0](https://github.com/orbcorp/orb-ruby/compare/v0.4.0...v0.5.0)
+
+### Features
+
+* bump default connection pool size limit to minimum of 99 ([79f9994](https://github.com/orbcorp/orb-ruby/commit/79f9994e2a77d786a7e1ffaa52c56916835b9b5f))
+
+
+### Chores
+
+* **internal:** version bump ([cfc1793](https://github.com/orbcorp/orb-ruby/commit/cfc17939f09ece0217ea7683991e509c30491e96))
+
+
+### Documentation
+
+* rewrite much of README.md for readability ([ac8a45d](https://github.com/orbcorp/orb-ruby/commit/ac8a45d8765183d41fbeaf23d1bd03c372908b45))
+
+## 0.4.0 (2025-05-13)
+
+Full Changelog: [v0.3.2...v0.4.0](https://github.com/orbcorp/orb-ruby/compare/v0.3.2...v0.4.0)
+
+### Features
+
+* expose base client options as read only attributes ([1f638b6](https://github.com/orbcorp/orb-ruby/commit/1f638b60ad1679bc7969f441650ba61fb9a65e8a))
+* expose recursive `#to_h` conversion ([cfd49a1](https://github.com/orbcorp/orb-ruby/commit/cfd49a15d805ffaa5828249c5b91565661ae7e52))
+* support sorbet aliases at the runtime ([786d1e3](https://github.com/orbcorp/orb-ruby/commit/786d1e3dd882054bd298e33a448a194f1d68bac4))
+
+
+### Bug Fixes
+
+* **internal:** update gemspec name ([852ab56](https://github.com/orbcorp/orb-ruby/commit/852ab562ee4948d3fe4de8dd877f9301f36c8a4b))
+
+
+### Chores
+
+* fix misc linting / minor issues ([0e7dd84](https://github.com/orbcorp/orb-ruby/commit/0e7dd846c906cc2e72827f5477a93e4799ab9482))
+* **internal:** version bump ([359839c](https://github.com/orbcorp/orb-ruby/commit/359839c734c4bcf8051490b1e8723674ef634753))
+
 ## 0.3.2 (2025-05-07)
 
 Full Changelog: [v0.3.1...v0.3.2](https://github.com/orbcorp/orb-ruby/compare/v0.3.1...v0.3.2)

data/README.md

@@ -1,6 +1,6 @@
 # Orb Ruby API library
 
-The Orb Ruby library provides convenient access to the Orb REST API from any Ruby 3.2.0+ application.
+The Orb Ruby library provides convenient access to the Orb REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/orbcorp/orb-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
 
 ## Documentation
 
@@ -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.3.2"
+gem "orb-billing", "~> 0.5.0"
 ```
 
 <!-- x-release-please-end -->
@@ -35,16 +35,6 @@ 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.
@@ -64,15 +54,30 @@ page.auto_paging_each do |coupon|
 end
 ```
 
-### Errors
+Alternatively, you can use the `#next_page?` and `#next_page` methods for more granular control working with pages.
+
+```ruby
+if page.next_page?
+  new_page = page.next_page
+  puts(new_page.data[0].id)
+end
+```
+
+### Handling 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::Errors::APIError` will be thrown:
 
 ```ruby
 begin
   customer = orb.customers.create(email: "example-customer@withorb.com", name: "My Customer")
-rescue Orb::Errors::APIError => e
-  puts(e.status) # 400
+rescue Orb::Errors::APIConnectionError => e
+  puts("The server could not be reached")
+  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
+rescue Orb::Errors::RateLimitError => e
+  puts("A 429 status code was received; we should back off a bit.")
+rescue Orb::Errors::APIStatusError => e
+  puts("Another non-200-range status code was received")
+  puts(e.status)
 end
 ```
 
@@ -116,11 +121,7 @@ orb.customers.create(
 
 ### Timeouts
 
-By default, requests will time out after 60 seconds.
-
-Timeouts are applied separately to the initial connection and the overall request time, so in some cases a request could wait 2\*timeout seconds before it fails.
-
-You can use the `timeout` option to configure or disable this:
+By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:
 
 ```ruby
 # Configure the default for all requests:
@@ -136,40 +137,54 @@ orb.customers.create(
 )
 ```
 
-## Model DSL
+On timeout, `Orb::Errors::APITimeoutError` is raised.
 
-This library uses a simple DSL to represent request parameters and response shapes in `lib/orb/models`.
+Note that requests that time out are retried by default.
 
-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.
+## Advanced concepts
 
-In all places where a `BaseModel` type is specified, vanilla Ruby `Hash` can also be used. For example, the following are interchangeable as arguments:
+### BaseModel
 
-```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")
+All parameter and response objects inherit from `Orb::Internal::Type::BaseModel`, which provides several conveniences, including:
 
-# This also works
-params = {
-  email: "example-customer@withorb.com",
-  name: "My Customer"
-}
-```
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
 
-## Editor support
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
 
-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.
+3. Both instances and the classes themselves can be pretty-printed.
 
-## Advanced concepts
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
+
+### Making custom or undocumented requests
+
+#### Undocumented properties
 
-### Making custom/undocumented requests
+You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
+
+Note: the `extra_` parameters of the same name overrides the documented parameters.
+
+```ruby
+customer =
+  orb.customers.create(
+    email: "example-customer@withorb.com",
+    name: "My Customer",
+    request_options: {
+      extra_query: {my_query_parameter: value},
+      extra_body: {my_body_parameter: value},
+      extra_headers: {"my-header": value}
+    }
+  )
+
+puts(customer[:my_undocumented_property])
+```
 
 #### 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.
+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 request as seen in examples above.
 
 #### Undocumented endpoints
 
-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.
+To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:
 
 ```ruby
 response = client.request(
@@ -177,42 +192,67 @@ response = client.request(
   path: '/undocumented/endpoint',
   query: {"dog": "woof"},
   headers: {"useful-header": "interesting-value"},
-  body: {"he": "llo"},
+  body: {"hello": "world"}
 )
 ```
 
 ### 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.
+The `Orb::Client` instances are threadsafe, but only are fork-safe when there are no in-flight HTTP requests.
+
+Each instance of `Orb::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.
 
-When the maximum number of connections has been checked out from the connection pool, the `Client` will wait for an in use connection to become available. The queue time for this mechanism is accounted for by the per-request timeout.
+When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.
 
 Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
 
-Currently, `Orb::Client` instances are only fork-safe if there are no in-flight HTTP requests.
+## Sorbet
 
-### Sorbet
+This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
 
-#### Enums
+You can provide typesafe request parameters like so:
 
-Sorbet's typed enums require sub-classing of the [`T::Enum` class](https://sorbet.org/docs/tenum) from the `sorbet-runtime` gem.
+```ruby
+orb.customers.create(email: "example-customer@withorb.com", name: "My Customer")
+```
 
-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.
+Or, equivalently:
 
 ```ruby
-module Orb::BillingCycleRelativeDate
-  # This alias aids language service driven navigation.
-  TaggedSymbol = T.type_alias { T.all(Symbol, Orb::BillingCycleRelativeDate) }
-end
+# Hashes work, but are not typesafe:
+orb.customers.create(email: "example-customer@withorb.com", name: "My Customer")
+
+# You can also splat a full Params class:
+params = Orb::CustomerCreateParams.new(email: "example-customer@withorb.com", name: "My Customer")
+orb.customers.create(**params)
 ```
 
-#### Argument passing trick
+### Enums
 
-It is possible to pass a compatible model / parameter class to a method that expects keyword arguments by using the `**` splat operator.
+Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
 
 ```ruby
-params = Orb::Models::CustomerCreateParams.new(email: "example-customer@withorb.com", name: "My Customer")
-orb.customers.create(**params)
+# :duplicate
+puts(Orb::CreditNoteCreateParams::Reason::DUPLICATE)
+
+# Revealed type: `T.all(Orb::CreditNoteCreateParams::Reason, Symbol)`
+T.reveal_type(Orb::CreditNoteCreateParams::Reason::DUPLICATE)
+```
+
+Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
+
+```ruby
+# Using the enum constants preserves the tagged type information:
+orb.credit_notes.create(
+  reason: Orb::CreditNoteCreateParams::Reason::DUPLICATE,
+  # …
+)
+
+# Literal values is also permissible:
+orb.credit_notes.create(
+  reason: :duplicate,
+  # …
+)
 ```
 
 ## Versioning

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: 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,
+      max_retries: self.class::DEFAULT_MAX_RETRIES,
+      timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY,
       idempotency_header: "Idempotency-Key"
     )
       base_url ||= "https://api.withorb.com/v1"

data/lib/orb/errors.rb

@@ -99,7 +99,7 @@ module Orb
       # @param response [nil]
       # @param message [String, nil]
       #
-      # @return [Orb::Errors::APIStatusError]
+      # @return [self]
       def self.for(url:, status:, body:, request:, response:, message: nil)
         key = Orb::Internal::Util.dig(body, :type)
         kwargs = {

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

@@ -7,6 +7,8 @@ module Orb
       #
       # @abstract
       class BaseClient
+        extend Orb::Internal::Util::SorbetRuntimeSupport
+
         # from whatwg fetch spec
         MAX_REDIRECTS = 20
 
@@ -151,6 +153,27 @@ module Orb
           end
         end
 
+        # @return [URI::Generic]
+        attr_reader :base_url
+
+        # @return [Float]
+        attr_reader :timeout
+
+        # @return [Integer]
+        attr_reader :max_retries
+
+        # @return [Float]
+        attr_reader :initial_retry_delay
+
+        # @return [Float]
+        attr_reader :max_retry_delay
+
+        # @return [Hash{String=>String}]
+        attr_reader :headers
+
+        # @return [String, nil]
+        attr_reader :idempotency_header
+
         # @api private
         # @return [Orb::Internal::Transport::PooledNetRequester]
         attr_reader :requester
@@ -182,10 +205,11 @@ module Orb
             },
             headers
           )
-          @base_url = Orb::Internal::Util.parse_uri(base_url)
+          @base_url_components = Orb::Internal::Util.parse_uri(base_url)
+          @base_url = Orb::Internal::Util.unparse_uri(@base_url_components)
           @idempotency_header = idempotency_header&.to_s&.downcase
-          @max_retries = max_retries
           @timeout = timeout
+          @max_retries = max_retries
           @initial_retry_delay = initial_retry_delay
           @max_retry_delay = max_retry_delay
         end
@@ -276,10 +300,11 @@ module Orb
               Orb::Internal::Util.deep_merge(*[req[:body], opts[:extra_body]].compact)
             end
 
+          url = Orb::Internal::Util.join_parsed_uri(@base_url_components, {**req, path: path, query: query})
           headers, encoded = Orb::Internal::Util.encode_content(headers, body)
           {
             method: method,
-            url: Orb::Internal::Util.join_parsed_uri(@base_url, {**req, path: path, query: query}),
+            url: url,
             headers: headers,
             body: encoded,
             max_retries: opts.fetch(:max_retries, @max_retries),
@@ -473,10 +498,54 @@ module Orb
         # @return [String]
         def inspect
           # rubocop:disable Layout/LineLength
-          base_url = Orb::Internal::Util.unparse_uri(@base_url)
-          "#<#{self.class.name}:0x#{object_id.to_s(16)} base_url=#{base_url} max_retries=#{@max_retries} timeout=#{@timeout}>"
+          "#<#{self.class.name}:0x#{object_id.to_s(16)} base_url=#{@base_url} max_retries=#{@max_retries} timeout=#{@timeout}>"
           # rubocop:enable Layout/LineLength
         end
+
+        define_sorbet_constant!(:RequestComponents) do
+          T.type_alias do
+            {
+              method: Symbol,
+              path: T.any(String, T::Array[String]),
+              query: T.nilable(T::Hash[String, T.nilable(T.any(T::Array[String], String))]),
+              headers: T.nilable(
+                T::Hash[String,
+                        T.nilable(
+                          T.any(
+                            String,
+                            Integer,
+                            T::Array[T.nilable(T.any(String, Integer))]
+                          )
+                        )]
+              ),
+              body: T.nilable(T.anything),
+              unwrap: T.nilable(
+                T.any(
+                  Symbol,
+                  Integer,
+                  T::Array[T.any(Symbol, Integer)],
+                  T.proc.params(arg0: T.anything).returns(T.anything)
+                )
+              ),
+              page: T.nilable(T::Class[Orb::Internal::Type::BasePage[Orb::Internal::Type::BaseModel]]),
+              stream: T.nilable(T::Class[T.anything]),
+              model: T.nilable(Orb::Internal::Type::Converter::Input),
+              options: T.nilable(Orb::RequestOptions::OrHash)
+            }
+          end
+        end
+        define_sorbet_constant!(:RequestInput) do
+          T.type_alias do
+            {
+              method: Symbol,
+              url: URI::Generic,
+              headers: T::Hash[String, String],
+              body: T.anything,
+              max_retries: Integer,
+              timeout: Float
+            }
+          end
+        end
       end
     end
   end

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

@@ -5,10 +5,14 @@ module Orb
     module Transport
       # @api private
       class PooledNetRequester
+        extend Orb::Internal::Util::SorbetRuntimeSupport
+
         # from the golang stdlib
         # https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
         KEEP_ALIVE_TIMEOUT = 30
 
+        DEFAULT_MAX_CONNECTIONS = [Etc.nprocessors, 99].max
+
         class << self
           # @api private
           #
@@ -182,11 +186,23 @@ module Orb
         # @api private
         #
         # @param size [Integer]
-        def initialize(size: Etc.nprocessors)
+        def initialize(size: self.class::DEFAULT_MAX_CONNECTIONS)
           @mutex = Mutex.new
           @size = size
           @pools = {}
         end
+
+        define_sorbet_constant!(:Request) do
+          T.type_alias do
+            {
+              method: Symbol,
+              url: URI::Generic,
+              headers: T::Hash[String, String],
+              body: T.anything,
+              deadline: Float
+            }
+          end
+        end
       end
     end
   end

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

@@ -29,7 +29,7 @@ module Orb
         #
         #   @option spec [Boolean] :"nil?"
         #
-        # @return [Orb::Internal::Type::ArrayOf]
+        # @return [self]
         def self.[](...) = new(...)
 
         # @api public

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

@@ -6,6 +6,7 @@ module Orb
       # @abstract
       class BaseModel
         extend Orb::Internal::Type::Converter
+        extend Orb::Internal::Util::SorbetRuntimeSupport
 
         class << self
           # @api private
@@ -13,11 +14,17 @@ module Orb
           # Assumes superclass fields are totally defined before fields are accessed /
           # defined on subclasses.
           #
-          # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
-          def known_fields
-            @known_fields ||= (self < Orb::Internal::Type::BaseModel ? superclass.known_fields.dup : {})
+          # @param child [Class<Orb::Internal::Type::BaseModel>]
+          def inherited(child)
+            super
+            child.known_fields.replace(known_fields.dup)
           end
 
+          # @api private
+          #
+          # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+          def known_fields = @known_fields ||= {}
+
           # @api private
           #
           # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
@@ -199,7 +206,7 @@ module Orb
           #
           #   @option state [Integer] :branched
           #
-          # @return [Orb::Internal::Type::BaseModel, Object]
+          # @return [self, Object]
           def coerce(value, state:)
             exactness = state.fetch(:exactness)
 
@@ -258,7 +265,7 @@ module Orb
 
           # @api private
           #
-          # @param value [Orb::Internal::Type::BaseModel, Object]
+          # @param value [self, Object]
           #
           # @param state [Hash{Symbol=>Object}] .
           #
@@ -299,6 +306,39 @@ module Orb
           end
         end
 
+        class << self
+          # @api private
+          #
+          # @param model [Orb::Internal::Type::BaseModel]
+          # @param convert [Boolean]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def recursively_to_h(model, convert:)
+            rec = ->(x) do
+              case x
+              in Orb::Internal::Type::BaseModel
+                if convert
+                  fields = x.class.known_fields
+                  x.to_h.to_h do |key, val|
+                    [key, rec.call(fields.key?(key) ? x.public_send(key) : val)]
+                  rescue Orb::Errors::ConversionError
+                    [key, rec.call(val)]
+                  end
+                else
+                  rec.call(x.to_h)
+                end
+              in Hash
+                x.transform_values(&rec)
+              in Array
+                x.map(&rec)
+              else
+                x
+              end
+            end
+            rec.call(model)
+          end
+        end
+
         # @api public
         #
         # Returns the raw value associated with the given key, if found. Otherwise, nil is
@@ -335,9 +375,25 @@ module Orb
 
         alias_method :to_hash, :to_h
 
+        # @api public
+        #
+        # In addition to the behaviour of `#to_h`, this method will recursively call
+        # `#to_h` on nested models.
+        #
+        # @return [Hash{Symbol=>Object}]
+        def deep_to_h = self.class.recursively_to_h(@data, convert: false)
+
         # @param keys [Array<Symbol>, nil]
         #
         # @return [Hash{Symbol=>Object}]
+        #
+        # @example
+        #   # `amount_discount` is a `Orb::AmountDiscount`
+        #   amount_discount => {
+        #     amount_discount: amount_discount,
+        #     applies_to_price_ids: applies_to_price_ids,
+        #     discount_type: discount_type
+        #   }
         def deconstruct_keys(keys)
           (keys || self.class.known_fields.keys)
             .filter_map do |k|
@@ -350,29 +406,6 @@ 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]
@@ -418,12 +451,19 @@ module Orb
         # @api public
         #
         # @return [String]
-        def to_s = self.class.walk(@data).to_s
+        def to_s = deep_to_h.to_s
 
         # @api private
         #
         # @return [String]
-        def inspect = "#<#{self.class}:0x#{object_id.to_s(16)} #{self}>"
+        def inspect
+          converted = self.class.recursively_to_h(self, convert: true)
+          "#<#{self.class}:0x#{object_id.to_s(16)} #{converted}>"
+        end
+
+        define_sorbet_constant!(:KnownField) do
+          T.type_alias { {mode: T.nilable(Symbol), required: T::Boolean, nilable: T::Boolean} }
+        end
       end
     end
   end