terminal-shop 3.7.0 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec0b2f09a8009870055d5b2a868a6078adb11504f48eba5eea34b84ff89ba60f
-  data.tar.gz: f2e9a51a8c54a1eb7f07f40485b89b93218ba1055a8b0498a11f97caa15d5c71
+  metadata.gz: '01845ef0b10623ae25a1778177a60981b0edf186dc844b730f99d7cf76b91b99'
+  data.tar.gz: 59e7ee0af19ab4dd6ef9d95b54edad958cf89de4fb2e5ce9ba11b23e87509818
 SHA512:
-  metadata.gz: 1144da9caada255b1fd2a9856dd8a2d5e6375c0322e369d761289b41c8aa2fe1ba318add613dc0f1cbcd1031badc4576d27084c635921cd063848dbcae5a9ea9
-  data.tar.gz: e5271523d7d53bcd460ea32453cab3b764009685b290344dcbc07def5ebe9133dd0e8cf55cb3ea72b2491cfb47488c21cdab21c67c0ca4e9b5add53c266ee185
+  metadata.gz: 9f1503d288a6b28bce4920c36d9fdd71bf703985b7c7cba6eaeb117d27729cb9ce527b95ed3c8a8705cf5484015026e01a2532f690af7ac74f594f9adf044410
+  data.tar.gz: 7af9706e59ebac0b27c713f7d9e93b45867a865423139d7841b0eb655988ff7ced99f3cb6d2dd8bb75f8b15c6057f70ec86f20c2f76f4d73c9bbf67403de20d4

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 3.8.0 (2025-05-22)
+
+Full Changelog: [v3.7.0...v3.8.0](https://github.com/terminaldotshop/terminal-sdk-ruby/compare/v3.7.0...v3.8.0)
+
+### Features
+
+* bump default connection pool size limit to minimum of 99 ([81feb3e](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/81feb3eb7e2d0c5b1df983647c436ebf966ece2c))
+
+
+### Bug Fixes
+
+* correctly instantiate sorbet type aliases for enums and unions ([2698489](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/2698489f9f63ced3353196009dc2329e20f8cff5))
+
+
+### Chores
+
+* **docs:** grammar improvements ([841d9a7](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/841d9a7d18776a55e947cee60233d0756579b22c))
+* **internal:** codegen related update ([68a3efa](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/68a3efaf40e8944faf60b604b5aa33b46c1aedf0))
+* refine Yard and Sorbet types and ensure linting is turned on for examples ([41916e7](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/41916e7b6c195ae8085ac89393b0893b42bf72bc))
+* use sorbet union aliases where available ([046dd18](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/046dd183ff9c9826d45fdcf73a6512effd343ca5))
+* whitespaces ([88c3862](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/88c38620dbdceefd1eb268b457a464a0b59daa6c))
+
+
+### Documentation
+
+* rewrite much of README.md for readability ([564f4f7](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/564f4f7b65f67c1f4f17f6a06c952a570263d4d1))
+
 ## 3.7.0 (2025-05-14)
 
 Full Changelog: [v3.6.2...v3.7.0](https://github.com/terminaldotshop/terminal-sdk-ruby/compare/v3.6.2...v3.7.0)

data/README.md

@@ -1,6 +1,6 @@
 # Terminal Ruby API library
 
-The Terminal Ruby library provides convenient access to the Terminal REST API from any Ruby 3.2.0+ application.
+The Terminal Ruby library provides convenient access to the Terminal 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/terminaldotshop/terminal-sdk-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.
 
 It is generated with [Stainless](https://www.stainless.com/).
 
@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "terminal-shop", "~> 3.7.0"
+gem "terminal-shop", "~> 3.8.0"
 ```
 
 <!-- x-release-please-end -->
@@ -38,25 +38,21 @@ products = terminal.product.list
 puts(products.data)
 ```
 
-## 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
-terminal.product.list
-```
-
-### Errors
+### 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 `TerminalShop::Errors::APIError` will be thrown:
 
 ```ruby
 begin
   product = terminal.product.list
-rescue TerminalShop::Errors::APIError => e
-  puts(e.status) # 400
+rescue TerminalShop::Errors::APIConnectionError => e
+  puts("The server could not be reached")
+  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
+rescue TerminalShop::Errors::RateLimitError => e
+  puts("A 429 status code was received; we should back off a bit.")
+rescue TerminalShop::Errors::APIStatusError => e
+  puts("Another non-200-range status code was received")
+  puts(e.status)
 end
 ```
 
@@ -96,11 +92,7 @@ terminal.product.list(request_options: {max_retries: 5})
 
 ### 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:
@@ -112,39 +104,52 @@ terminal = TerminalShop::Client.new(
 terminal.product.list(request_options: {timeout: 5})
 ```
 
-## Model DSL
+On timeout, `TerminalShop::Errors::APITimeoutError` is raised.
 
-This library uses a simple DSL to represent request parameters and response shapes in `lib/terminal_shop/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 = TerminalShop::Models::ProductListParams.new
+All parameter and response objects inherit from `TerminalShop::Internal::Type::BaseModel`, which provides several conveniences, including:
 
-# This also works
-params = {
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
 
-}
-```
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
 
-## Editor support
+3. Both instances and the classes themselves can be pretty-printed.
 
-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.
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
 
-## Advanced concepts
+### 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
+products =
+  terminal.product.list(
+    request_options: {
+      extra_query: {my_query_parameter: value},
+      extra_body: {my_body_parameter: value},
+      extra_headers: {"my-header": value}
+    }
+  )
+
+puts(products[: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 the 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(
@@ -152,42 +157,65 @@ response = client.request(
   path: '/undocumented/endpoint',
   query: {"dog": "woof"},
   headers: {"useful-header": "interesting-value"},
-  body: {"he": "llo"},
+  body: {"hello": "world"}
 )
 ```
 
 ### Concurrency & connection pooling
 
-The `TerminalShop::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 `TerminalShop::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
 
-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.
+Each instance of `TerminalShop::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 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, `TerminalShop::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
+terminal.product.list
+```
 
-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 TerminalShop::Region
-  # This alias aids language service driven navigation.
-  TaggedSymbol = T.type_alias { T.all(Symbol, TerminalShop::Region) }
-end
+# Hashes work, but are not typesafe:
+terminal.product.list
+
+# You can also splat a full Params class:
+params = TerminalShop::ProductListParams.new
+terminal.product.list(**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 = TerminalShop::Models::ProductListParams.new
-terminal.product.list(**params)
+# :allowed
+puts(TerminalShop::ProductAPI::Subscription::ALLOWED)
+
+# Revealed type: `T.all(TerminalShop::ProductAPI::Subscription, Symbol)`
+T.reveal_type(TerminalShop::ProductAPI::Subscription::ALLOWED)
+```
+
+Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
+
+```ruby
+TerminalShop::ProductAPI.new(
+  subscription: TerminalShop::ProductAPI::Subscription::ALLOWED,
+  # …
+)
+
+TerminalShop::ProductAPI.new(
+  subscription: :allowed,
+  # …
+)
 ```
 
 ## Versioning

data/SECURITY.md

@@ -16,11 +16,11 @@ 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 Terminal please follow the respective company's security reporting guidelines.
+or products provided by Terminal, please follow the respective company's security reporting guidelines.
 
 ### Terminal Terms and Policies
 
-Please contact dev@terminal.com for any questions or concerns regarding security of our services.
+Please contact dev@terminal.com for any questions or concerns regarding the security of our services.
 
 ---
 

data/lib/terminal_shop/client.rb

@@ -96,10 +96,10 @@ module TerminalShop
       app_id: nil,
       environment: nil,
       base_url: ENV["TERMINAL_BASE_URL"],
-      max_retries: TerminalShop::Client::DEFAULT_MAX_RETRIES,
-      timeout: TerminalShop::Client::DEFAULT_TIMEOUT_IN_SECONDS,
-      initial_retry_delay: TerminalShop::Client::DEFAULT_INITIAL_RETRY_DELAY,
-      max_retry_delay: TerminalShop::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
     )
       base_url ||= TerminalShop::Client::ENVIRONMENTS.fetch(environment&.to_sym || :production) do
         message = "environment must be one of #{TerminalShop::Client::ENVIRONMENTS.keys}, got #{environment}"

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

@@ -11,6 +11,8 @@ module TerminalShop
         # 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
           #
@@ -184,7 +186,7 @@ module TerminalShop
         # @api private
         #
         # @param size [Integer]
-        def initialize(size: Etc.nprocessors)
+        def initialize(size: self.class::DEFAULT_MAX_CONNECTIONS)
           @mutex = Mutex.new
           @size = size
           @pools = {}

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

@@ -12,6 +12,7 @@ module TerminalShop
       # Array of items of a given type.
       class ArrayOf
         include TerminalShop::Internal::Type::Converter
+        include TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         private_class_method :new
 
@@ -110,6 +111,13 @@ module TerminalShop
           end
         end
 
+        # @api private
+        #
+        # @return [Object]
+        def to_sorbet_type
+          T::Array[TerminalShop::Internal::Util::SorbetRuntimeSupport.to_sorbet_type(item_type)]
+        end
+
         # @api private
         #
         # @return [generic<Elem>]

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

@@ -309,6 +309,13 @@ module TerminalShop
 
             acc
           end
+
+          # @api private
+          #
+          # @return [Object]
+          def to_sorbet_type
+            self
+          end
         end
 
         class << self
@@ -391,6 +398,14 @@ module TerminalShop
         # @param keys [Array<Symbol>, nil]
         #
         # @return [Hash{Symbol=>Object}]
+        #
+        # @example
+        #   # `product_api` is a `TerminalShop::ProductAPI`
+        #   product_api => {
+        #     id: id,
+        #     description: description,
+        #     name: name
+        #   }
         def deconstruct_keys(keys)
           (keys || self.class.known_fields.keys)
             .filter_map do |k|

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

@@ -10,6 +10,7 @@ module TerminalShop
       # Ruby has no Boolean class; this is something for models to refer to.
       class Boolean
         extend TerminalShop::Internal::Type::Converter
+        extend TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         private_class_method :new
 
@@ -56,6 +57,13 @@ module TerminalShop
           #     @option state [Boolean] :can_retry
           #
           #   @return [Boolean, Object]
+
+          # @api private
+          #
+          # @return [Object]
+          def to_sorbet_type
+            T::Boolean
+          end
         end
       end
     end

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

@@ -112,6 +112,18 @@ module TerminalShop
         #
         #   @return [Symbol, Object]
 
+        # @api private
+        #
+        # @return [Object]
+        def to_sorbet_type
+          case values
+          in []
+            T.noreturn
+          in [value, *_]
+            T.all(TerminalShop::Internal::Util::SorbetRuntimeSupport.to_sorbet_type(value), self)
+          end
+        end
+
         # @api private
         #
         # @param depth [Integer]

data/lib/terminal_shop/internal/type/file_input.rb

@@ -89,6 +89,13 @@ module TerminalShop
 
             value
           end
+
+          # @api private
+          #
+          # @return [Object]
+          def to_sorbet_type
+            T.any(Pathname, StringIO, IO, String, TerminalShop::FilePart)
+          end
         end
       end
     end

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

@@ -12,6 +12,7 @@ module TerminalShop
       # Hash of items of a given type.
       class HashOf
         include TerminalShop::Internal::Type::Converter
+        include TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         private_class_method :new
 
@@ -130,6 +131,13 @@ module TerminalShop
           end
         end
 
+        # @api private
+        #
+        # @return [Object]
+        def to_sorbet_type
+          T::Hash[TerminalShop::Internal::Util::SorbetRuntimeSupport.to_sorbet_type(item_type)]
+        end
+
         # @api private
         #
         # @return [generic<Elem>]

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

@@ -197,6 +197,18 @@ module TerminalShop
           super
         end
 
+        # @api private
+        #
+        # @return [Object]
+        def to_sorbet_type
+          case (v = variants)
+          in []
+            T.noreturn
+          else
+            T.any(*v.map { TerminalShop::Internal::Util::SorbetRuntimeSupport.to_sorbet_type(_1) })
+          end
+        end
+
         # rubocop:enable Style/CaseEquality
         # rubocop:enable Style/HashEachMethods
 

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

@@ -10,6 +10,7 @@ module TerminalShop
       # When we don't know what to expect for the value.
       class Unknown
         extend TerminalShop::Internal::Type::Converter
+        extend TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         # rubocop:disable Lint/UnusedMethodArgument
 
@@ -58,6 +59,13 @@ module TerminalShop
           #     @option state [Boolean] :can_retry
           #
           #   @return [Object]
+
+          # @api private
+          #
+          # @return [Object]
+          def to_sorbet_type
+            T.anything
+          end
         end
 
         # rubocop:enable Lint/UnusedMethodArgument

data/lib/terminal_shop/internal/util.rb

@@ -9,6 +9,23 @@ module TerminalShop
       # @return [Float]
       def self.monotonic_secs = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
+      # @api private
+      #
+      # @param ns [Module, Class]
+      #
+      # @return [Enumerable<Module, Class>]
+      def self.walk_namespaces(ns)
+        ns.constants(false).lazy.flat_map do
+          case (c = ns.const_get(_1, false))
+          in Module | Class
+            walk_namespaces(c)
+          else
+            []
+          end
+        end
+          .chain([ns])
+      end
+
       class << self
         # @api private
         #
@@ -826,11 +843,39 @@ module TerminalShop
           sorbet_runtime_constants.fetch(name).call
         end
 
+        # @api private
+        #
+        # @param name [Symbol]
+        #
+        # @return [Boolean]
+        def sorbet_constant_defined?(name) = sorbet_runtime_constants.key?(name)
+
         # @api private
         #
         # @param name [Symbol]
         # @param blk [Proc]
         def define_sorbet_constant!(name, &blk) = sorbet_runtime_constants.store(name, blk)
+
+        # @api private
+        #
+        # @return [Object]
+        def to_sorbet_type = raise NotImplementedError
+
+        class << self
+          # @api private
+          #
+          # @param type [TerminalShop::Internal::Util::SorbetRuntimeSupport, Object]
+          #
+          # @return [Object]
+          def to_sorbet_type(type)
+            case type
+            in TerminalShop::Internal::Util::SorbetRuntimeSupport
+              type.to_sorbet_type
+            else
+              type
+            end
+          end
+        end
       end
 
       extend TerminalShop::Internal::Util::SorbetRuntimeSupport

data/lib/terminal_shop/internal.rb

@@ -13,5 +13,8 @@ module TerminalShop
     define_sorbet_constant!(:AnyHash) do
       T.type_alias { T::Hash[Symbol, T.anything] }
     end
+    define_sorbet_constant!(:FileInput) do
+      T.type_alias { T.any(Pathname, StringIO, IO, String, TerminalShop::FilePart) }
+    end
   end
 end

data/lib/terminal_shop/models/subscription.rb

@@ -119,15 +119,6 @@ module TerminalShop
 
         # @!method self.variants
         #   @return [Array(TerminalShop::SubscriptionAPI::Schedule::Fixed, TerminalShop::SubscriptionAPI::Schedule::Weekly)]
-
-        define_sorbet_constant!(:Variants) do
-          T.type_alias do
-            T.any(
-              TerminalShop::SubscriptionAPI::Schedule::Fixed,
-              TerminalShop::SubscriptionAPI::Schedule::Weekly
-            )
-          end
-        end
       end
     end
   end

data/lib/terminal_shop/models/subscription_update_params.rb

@@ -70,15 +70,6 @@ module TerminalShop
 
         # @!method self.variants
         #   @return [Array(TerminalShop::SubscriptionUpdateParams::Schedule::Fixed, TerminalShop::SubscriptionUpdateParams::Schedule::Weekly)]
-
-        define_sorbet_constant!(:Variants) do
-          T.type_alias do
-            T.any(
-              TerminalShop::SubscriptionUpdateParams::Schedule::Fixed,
-              TerminalShop::SubscriptionUpdateParams::Schedule::Weekly
-            )
-          end
-        end
       end
     end
   end

data/lib/terminal_shop/models.rb

@@ -5,29 +5,40 @@ module TerminalShop
     cls.define_sorbet_constant!(:OrHash) { T.type_alias { T.any(cls, TerminalShop::Internal::AnyHash) } }
   end
 
-  [
-    *TerminalShop::Internal::Type::Enum.included_modules,
-    *TerminalShop::Internal::Type::Union.included_modules
-  ].each do |cls|
-    cls.constants.each do |name|
-      case cls.const_get(name)
-      in true | false
-        cls.define_sorbet_constant!(:TaggedBoolean) { T.type_alias { T.all(T::Boolean, cls) } }
-        cls.define_sorbet_constant!(:OrBoolean) { T.type_alias { T::Boolean } }
-      in Integer
-        cls.define_sorbet_constant!(:TaggedInteger) { T.type_alias { T.all(Integer, cls) } }
-        cls.define_sorbet_constant!(:OrInteger) { T.type_alias { Integer } }
-      in Float
-        cls.define_sorbet_constant!(:TaggedFloat) { T.type_alias { T.all(Float, cls) } }
-        cls.define_sorbet_constant!(:OrFloat) { T.type_alias { Float } }
-      in Symbol
-        cls.define_sorbet_constant!(:TaggedSymbol) { T.type_alias { T.all(Symbol, cls) } }
-        cls.define_sorbet_constant!(:OrSymbol) { T.type_alias { T.any(Symbol, String) } }
-      else
+  TerminalShop::Internal::Util.walk_namespaces(TerminalShop::Models).each do |mod|
+    case mod
+    in TerminalShop::Internal::Type::Enum | TerminalShop::Internal::Type::Union
+      mod.constants.each do |name|
+        case mod.const_get(name)
+        in true | false
+          mod.define_sorbet_constant!(:TaggedBoolean) { T.type_alias { T.all(T::Boolean, mod) } }
+          mod.define_sorbet_constant!(:OrBoolean) { T.type_alias { T::Boolean } }
+        in Integer
+          mod.define_sorbet_constant!(:TaggedInteger) { T.type_alias { T.all(Integer, mod) } }
+          mod.define_sorbet_constant!(:OrInteger) { T.type_alias { Integer } }
+        in Float
+          mod.define_sorbet_constant!(:TaggedFloat) { T.type_alias { T.all(Float, mod) } }
+          mod.define_sorbet_constant!(:OrFloat) { T.type_alias { Float } }
+        in Symbol
+          mod.define_sorbet_constant!(:TaggedSymbol) { T.type_alias { T.all(Symbol, mod) } }
+          mod.define_sorbet_constant!(:OrSymbol) { T.type_alias { T.any(Symbol, String) } }
+        else
+        end
       end
+    else
     end
   end
 
+  TerminalShop::Internal::Util.walk_namespaces(TerminalShop::Models)
+                              .lazy
+                              .grep(TerminalShop::Internal::Type::Union)
+                              .each do |mod|
+    const = :Variants
+    next if mod.sorbet_constant_defined?(const)
+
+    mod.define_sorbet_constant!(const) { T.type_alias { mod.to_sorbet_type } }
+  end
+
   AddressAPI = TerminalShop::Models::AddressAPI
 
   AddressCreateParams = TerminalShop::Models::AddressCreateParams

data/lib/terminal_shop/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TerminalShop
-  VERSION = "3.7.0"
+  VERSION = "3.8.0"
 end

data/rbi/terminal_shop/internal/transport/pooled_net_requester.rbi

@@ -22,6 +22,8 @@ module TerminalShop
         # https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
         KEEP_ALIVE_TIMEOUT = 30
 
+        DEFAULT_MAX_CONNECTIONS = T.let(T.unsafe(nil), Integer)
+
         class << self
           # @api private
           sig { params(url: URI::Generic).returns(Net::HTTP) }
@@ -68,7 +70,9 @@ module TerminalShop
 
         # @api private
         sig { params(size: Integer).returns(T.attached_class) }
-        def self.new(size: Etc.nprocessors)
+        def self.new(
+          size: TerminalShop::Internal::Transport::PooledNetRequester::DEFAULT_MAX_CONNECTIONS
+        )
         end
       end
     end

data/rbi/terminal_shop/internal/type/array_of.rbi

@@ -8,6 +8,7 @@ module TerminalShop
       # Array of items of a given type.
       class ArrayOf
         include TerminalShop::Internal::Type::Converter
+        include TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         abstract!
 
@@ -63,6 +64,11 @@ module TerminalShop
         def dump(value, state:)
         end
 
+        # @api private
+        sig { returns(T.anything) }
+        def to_sorbet_type
+        end
+
         # @api private
         sig { returns(Elem) }
         protected def item_type

data/rbi/terminal_shop/internal/type/base_model.rbi

@@ -205,6 +205,11 @@ module TerminalShop
           end
           def dump(value, state:)
           end
+
+          # @api private
+          sig { returns(T.anything) }
+          def to_sorbet_type
+          end
         end
 
         class << self

data/rbi/terminal_shop/internal/type/boolean.rbi

@@ -8,6 +8,7 @@ module TerminalShop
       # Ruby has no Boolean class; this is something for models to refer to.
       class Boolean
         extend TerminalShop::Internal::Type::Converter
+        extend TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         abstract!
 
@@ -43,6 +44,11 @@ module TerminalShop
           end
           def dump(value, state:)
           end
+
+          # @api private
+          sig { returns(T.anything) }
+          def to_sorbet_type
+          end
         end
       end
     end

data/rbi/terminal_shop/internal/type/enum.rbi

@@ -67,6 +67,11 @@ module TerminalShop
         def dump(value, state:)
         end
 
+        # @api private
+        sig { returns(T.anything) }
+        def to_sorbet_type
+        end
+
         # @api private
         sig { params(depth: Integer).returns(String) }
         def inspect(depth: 0)

data/rbi/terminal_shop/internal/type/file_input.rbi

@@ -47,6 +47,11 @@ module TerminalShop
           end
           def dump(value, state:)
           end
+
+          # @api private
+          sig { returns(T.anything) }
+          def to_sorbet_type
+          end
         end
       end
     end

data/rbi/terminal_shop/internal/type/hash_of.rbi

@@ -8,6 +8,7 @@ module TerminalShop
       # Hash of items of a given type.
       class HashOf
         include TerminalShop::Internal::Type::Converter
+        include TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         abstract!
 
@@ -63,6 +64,11 @@ module TerminalShop
         def dump(value, state:)
         end
 
+        # @api private
+        sig { returns(T.anything) }
+        def to_sorbet_type
+        end
+
         # @api private
         sig { returns(Elem) }
         protected def item_type

data/rbi/terminal_shop/internal/type/union.rbi

@@ -101,6 +101,11 @@ module TerminalShop
         def dump(value, state:)
         end
 
+        # @api private
+        sig { returns(T.anything) }
+        def to_sorbet_type
+        end
+
         # @api private
         sig { params(depth: Integer).returns(String) }
         def inspect(depth: 0)

data/rbi/terminal_shop/internal/type/unknown.rbi

@@ -8,6 +8,7 @@ module TerminalShop
       # When we don't know what to expect for the value.
       class Unknown
         extend TerminalShop::Internal::Type::Converter
+        extend TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         abstract!
 
@@ -43,6 +44,11 @@ module TerminalShop
           end
           def dump(value, state:)
           end
+
+          # @api private
+          sig { returns(T.anything) }
+          def to_sorbet_type
+          end
         end
       end
     end

data/rbi/terminal_shop/internal/util.rbi

@@ -11,6 +11,15 @@ module TerminalShop
       def self.monotonic_secs
       end
 
+      # @api private
+      sig do
+        params(ns: T.any(Module, T::Class[T.anything])).returns(
+          T::Enumerable[T.any(Module, T::Class[T.anything])]
+        )
+      end
+      def self.walk_namespaces(ns)
+      end
+
       class << self
         # @api private
         sig { returns(String) }
@@ -441,10 +450,35 @@ module TerminalShop
         def const_missing(name)
         end
 
+        # @api private
+        sig { params(name: Symbol).returns(T::Boolean) }
+        def sorbet_constant_defined?(name)
+        end
+
         # @api private
         sig { params(name: Symbol, blk: T.proc.returns(T.anything)).void }
         def define_sorbet_constant!(name, &blk)
         end
+
+        # @api private
+        sig { returns(T.anything) }
+        def to_sorbet_type
+        end
+
+        class << self
+          # @api private
+          sig do
+            params(
+              type:
+                T.any(
+                  TerminalShop::Internal::Util::SorbetRuntimeSupport,
+                  T.anything
+                )
+            ).returns(T.anything)
+          end
+          def to_sorbet_type(type)
+          end
+        end
       end
     end
   end

data/rbi/terminal_shop/internal.rbi

@@ -8,6 +8,11 @@ module TerminalShop
     # this alias might be refined in the future.
     AnyHash = T.type_alias { T::Hash[Symbol, T.anything] }
 
+    FileInput =
+      T.type_alias do
+        T.any(Pathname, StringIO, IO, String, TerminalShop::FilePart)
+      end
+
     OMIT = T.let(Object.new.freeze, T.anything)
   end
 end

data/rbi/terminal_shop/models/subscription.rbi

@@ -45,14 +45,7 @@ module TerminalShop
 
       # Schedule of the subscription.
       sig do
-        returns(
-          T.nilable(
-            T.any(
-              TerminalShop::SubscriptionAPI::Schedule::Fixed,
-              TerminalShop::SubscriptionAPI::Schedule::Weekly
-            )
-          )
-        )
+        returns(T.nilable(TerminalShop::SubscriptionAPI::Schedule::Variants))
       end
       attr_reader :schedule
 
@@ -118,11 +111,7 @@ module TerminalShop
             product_variant_id: String,
             quantity: Integer,
             next_: String,
-            schedule:
-              T.any(
-                TerminalShop::SubscriptionAPI::Schedule::Fixed,
-                TerminalShop::SubscriptionAPI::Schedule::Weekly
-              )
+            schedule: TerminalShop::SubscriptionAPI::Schedule::Variants
           }
         )
       end

data/sig/terminal_shop/internal/transport/pooled_net_requester.rbs

@@ -15,6 +15,8 @@ module TerminalShop
 
         KEEP_ALIVE_TIMEOUT: 30
 
+        DEFAULT_MAX_CONNECTIONS: Integer
+
         def self.connect: (URI::Generic url) -> top
 
         def self.calibrate_socket_timeout: (top conn, Float deadline) -> void

data/sig/terminal_shop/internal/type/array_of.rbs

@@ -3,6 +3,7 @@ module TerminalShop
     module Type
       class ArrayOf[Elem]
         include TerminalShop::Internal::Type::Converter
+        include TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         def self.[]: (
           ::Hash[Symbol, top]
@@ -27,6 +28,8 @@ module TerminalShop
           state: TerminalShop::Internal::Type::Converter::dump_state
         ) -> (::Array[top] | top)
 
+        def to_sorbet_type: -> top
+
         def item_type: -> Elem
 
         def nilable?: -> bool

data/sig/terminal_shop/internal/type/base_model.rbs

@@ -70,6 +70,8 @@ module TerminalShop
           state: TerminalShop::Internal::Type::Converter::dump_state
         ) -> (::Hash[top, top] | top)
 
+        def self.to_sorbet_type: -> top
+
         def self.recursively_to_h: (
           TerminalShop::Internal::Type::BaseModel model,
           convert: bool

data/sig/terminal_shop/internal/type/boolean.rbs

@@ -3,6 +3,7 @@ module TerminalShop
     module Type
       class Boolean
         extend TerminalShop::Internal::Type::Converter
+        extend TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         def self.===: (top other) -> bool
 
@@ -17,6 +18,8 @@ module TerminalShop
           bool | top value,
           state: TerminalShop::Internal::Type::Converter::dump_state
         ) -> (bool | top)
+
+        def self.to_sorbet_type: -> top
       end
     end
   end

data/sig/terminal_shop/internal/type/enum.rbs

@@ -23,6 +23,8 @@ module TerminalShop
           state: TerminalShop::Internal::Type::Converter::dump_state
         ) -> (Symbol | top)
 
+        def to_sorbet_type: -> top
+
         def inspect: (?depth: Integer) -> String
       end
     end

data/sig/terminal_shop/internal/type/file_input.rbs

@@ -17,6 +17,8 @@ module TerminalShop
           Pathname | StringIO | IO | String | top value,
           state: TerminalShop::Internal::Type::Converter::dump_state
         ) -> (Pathname | StringIO | IO | String | top)
+
+        def self.to_sorbet_type: -> top
       end
     end
   end

data/sig/terminal_shop/internal/type/hash_of.rbs

@@ -3,6 +3,7 @@ module TerminalShop
     module Type
       class HashOf[Elem]
         include TerminalShop::Internal::Type::Converter
+        include TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         def self.[]: (
           ::Hash[Symbol, top]
@@ -27,6 +28,8 @@ module TerminalShop
           state: TerminalShop::Internal::Type::Converter::dump_state
         ) -> (::Hash[Symbol, top] | top)
 
+        def to_sorbet_type: -> top
+
         def item_type: -> Elem
 
         def nilable?: -> bool

data/sig/terminal_shop/internal/type/union.rbs

@@ -43,6 +43,8 @@ module TerminalShop
           state: TerminalShop::Internal::Type::Converter::dump_state
         ) -> top
 
+        def to_sorbet_type: -> top
+
         def inspect: (?depth: Integer) -> String
       end
     end

data/sig/terminal_shop/internal/type/unknown.rbs

@@ -3,6 +3,7 @@ module TerminalShop
     module Type
       class Unknown
         extend TerminalShop::Internal::Type::Converter
+        extend TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         def self.===: (top other) -> bool
 
@@ -17,6 +18,8 @@ module TerminalShop
           top value,
           state: TerminalShop::Internal::Type::Converter::dump_state
         ) -> top
+
+        def self.to_sorbet_type: -> top
       end
     end
   end

data/sig/terminal_shop/internal/util.rbs

@@ -5,6 +5,10 @@ module TerminalShop
 
       def self?.monotonic_secs: -> Float
 
+      def self?.walk_namespaces: (
+        Module | Class ns
+      ) -> Enumerable[(Module | Class)]
+
       def self?.arch: -> String
 
       def self?.os: -> String
@@ -166,7 +170,15 @@ module TerminalShop
 
         def const_missing: (Symbol name) -> void
 
+        def sorbet_constant_defined?: (Symbol name) -> bool
+
         def define_sorbet_constant!: (Symbol name) { -> top } -> void
+
+        def to_sorbet_type: -> top
+
+        def self.to_sorbet_type: (
+          TerminalShop::Internal::Util::SorbetRuntimeSupport | top `type`
+        ) -> top
       end
     end
   end

data/sig/terminal_shop/internal.rbs

@@ -2,6 +2,8 @@ module TerminalShop
   module Internal
     extend TerminalShop::Internal::Util::SorbetRuntimeSupport
 
+    type file_input = Pathname | StringIO | IO | String | TerminalShop::FilePart
+
     OMIT: Object
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: terminal-shop
 version: !ruby/object:Gem::Version
-  version: 3.7.0
+  version: 3.8.0
 platform: ruby
 authors:
 - Terminal
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-14 00:00:00.000000000 Z
+date: 2025-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool