terminal-shop 3.6.2 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df81693d60a13914c0ca1d8f9b9b9f5691e846931716167132d2133c29471043
-  data.tar.gz: c8c644764b8b414bec54167ab89a1d3cc7b87b19611c9092fff4cc0209463194
+  metadata.gz: ec0b2f09a8009870055d5b2a868a6078adb11504f48eba5eea34b84ff89ba60f
+  data.tar.gz: f2e9a51a8c54a1eb7f07f40485b89b93218ba1055a8b0498a11f97caa15d5c71
 SHA512:
-  metadata.gz: 532a6a6630d948cbd312576bcfa4e1f173b8b8229bc9974e05bed17bb5740b6b944342c0cdcd590fdb1932323278a7189f9e9a047791ced7fbdd8cd557404b8e
-  data.tar.gz: f5741d50ec9f61d5e14a13161d9d13f89b4641b1aa88264681425545e281f1a2a4ef09459ef141971345cbf82560ae87ac71e751ad4dd7f98f458914a79933ed
+  metadata.gz: 1144da9caada255b1fd2a9856dd8a2d5e6375c0322e369d761289b41c8aa2fe1ba318add613dc0f1cbcd1031badc4576d27084c635921cd063848dbcae5a9ea9
+  data.tar.gz: e5271523d7d53bcd460ea32453cab3b764009685b290344dcbc07def5ebe9133dd0e8cf55cb3ea72b2491cfb47488c21cdab21c67c0ca4e9b5add53c266ee185

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 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)
+
+### Features
+
+* expose base client options as read only attributes ([5ed1891](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/5ed18915050ee0f2db755deaa6655e93e0e3b766))
+* expose recursive `#to_h` conversion ([ca0cc5f](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/ca0cc5f0001bbb2f5b9c5edd7e4e7a017f268956))
+* support sorbet aliases at the runtime ([9e210bb](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/9e210bb7cb568a0c4b7a10e87e69772d56a0306b))
+
+
+### Bug Fixes
+
+* **internal:** update gemspec name ([47cc74b](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/47cc74b18b522e6caa46b014977c035b144e8faf))
+
+
+### Chores
+
+* fix misc linting / minor issues ([536f483](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/536f483f7916651ae0ae11f663315c8b379dc619))
+* **internal:** version bump ([cbba1d7](https://github.com/terminaldotshop/terminal-sdk-ruby/commit/cbba1d7501215bf6a55a54d1fcbdaea01da212d6))
+
 ## 3.6.2 (2025-05-08)
 
 Full Changelog: [v3.6.1...v3.6.2](https://github.com/terminaldotshop/terminal-sdk-ruby/compare/v3.6.1...v3.6.2)

data/README.md

@@ -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.6.2"
+gem "terminal-shop", "~> 3.7.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/terminal_shop/errors.rb

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

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

@@ -7,6 +7,8 @@ module TerminalShop
       #
       # @abstract
       class BaseClient
+        extend TerminalShop::Internal::Util::SorbetRuntimeSupport
+
         # from whatwg fetch spec
         MAX_REDIRECTS = 20
 
@@ -151,6 +153,27 @@ module TerminalShop
           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 [TerminalShop::Internal::Transport::PooledNetRequester]
         attr_reader :requester
@@ -182,10 +205,11 @@ module TerminalShop
             },
             headers
           )
-          @base_url = TerminalShop::Internal::Util.parse_uri(base_url)
+          @base_url_components = TerminalShop::Internal::Util.parse_uri(base_url)
+          @base_url = TerminalShop::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,14 @@ module TerminalShop
               TerminalShop::Internal::Util.deep_merge(*[req[:body], opts[:extra_body]].compact)
             end
 
+          url = TerminalShop::Internal::Util.join_parsed_uri(
+            @base_url_components,
+            {**req, path: path, query: query}
+          )
           headers, encoded = TerminalShop::Internal::Util.encode_content(headers, body)
           {
             method: method,
-            url: TerminalShop::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),
@@ -476,10 +504,54 @@ module TerminalShop
         # @return [String]
         def inspect
           # rubocop:disable Layout/LineLength
-          base_url = TerminalShop::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[TerminalShop::Internal::Type::BasePage[TerminalShop::Internal::Type::BaseModel]]),
+              stream: T.nilable(T::Class[T.anything]),
+              model: T.nilable(TerminalShop::Internal::Type::Converter::Input),
+              options: T.nilable(TerminalShop::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/terminal_shop/internal/transport/pooled_net_requester.rb

@@ -5,6 +5,8 @@ module TerminalShop
     module Transport
       # @api private
       class PooledNetRequester
+        extend TerminalShop::Internal::Util::SorbetRuntimeSupport
+
         # from the golang stdlib
         # https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
         KEEP_ALIVE_TIMEOUT = 30
@@ -187,6 +189,18 @@ module TerminalShop
           @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/terminal_shop/internal/type/array_of.rb

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

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

@@ -6,6 +6,7 @@ module TerminalShop
       # @abstract
       class BaseModel
         extend TerminalShop::Internal::Type::Converter
+        extend TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         class << self
           # @api private
@@ -13,11 +14,17 @@ module TerminalShop
           # 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 < TerminalShop::Internal::Type::BaseModel ? superclass.known_fields.dup : {})
+          # @param child [Class<TerminalShop::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}}]
@@ -204,7 +211,7 @@ module TerminalShop
           #
           #   @option state [Integer] :branched
           #
-          # @return [TerminalShop::Internal::Type::BaseModel, Object]
+          # @return [self, Object]
           def coerce(value, state:)
             exactness = state.fetch(:exactness)
 
@@ -263,7 +270,7 @@ module TerminalShop
 
           # @api private
           #
-          # @param value [TerminalShop::Internal::Type::BaseModel, Object]
+          # @param value [self, Object]
           #
           # @param state [Hash{Symbol=>Object}] .
           #
@@ -304,6 +311,39 @@ module TerminalShop
           end
         end
 
+        class << self
+          # @api private
+          #
+          # @param model [TerminalShop::Internal::Type::BaseModel]
+          # @param convert [Boolean]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def recursively_to_h(model, convert:)
+            rec = ->(x) do
+              case x
+              in TerminalShop::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 TerminalShop::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
@@ -340,6 +380,14 @@ module TerminalShop
 
         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}]
@@ -355,29 +403,6 @@ module TerminalShop
             .to_h
         end
 
-        class << self
-          # @api private
-          #
-          # @param model [TerminalShop::Internal::Type::BaseModel]
-          #
-          # @return [Hash{Symbol=>Object}]
-          def walk(model)
-            walk = ->(x) do
-              case x
-              in TerminalShop::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]
@@ -423,12 +448,19 @@ module TerminalShop
         # @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

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

@@ -5,6 +5,8 @@ module TerminalShop
     module Type
       # @api private
       module Converter
+        extend TerminalShop::Internal::Util::SorbetRuntimeSupport
+
         # rubocop:disable Lint/UnusedMethodArgument
 
         # @api private
@@ -268,6 +270,22 @@ module TerminalShop
             end
           end
         end
+
+        define_sorbet_constant!(:Input) do
+          T.type_alias { T.any(TerminalShop::Internal::Type::Converter, T::Class[T.anything]) }
+        end
+        define_sorbet_constant!(:CoerceState) do
+          T.type_alias do
+            {
+              strictness: T.any(T::Boolean, Symbol),
+              exactness: {yes: Integer, no: Integer, maybe: Integer},
+              branched: Integer
+            }
+          end
+        end
+        define_sorbet_constant!(:DumpState) do
+          T.type_alias { {can_retry: T::Boolean} }
+        end
       end
     end
   end

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

@@ -42,6 +42,7 @@ module TerminalShop
       #   end
       module Enum
         include TerminalShop::Internal::Type::Converter
+        include TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         # All of the valid Symbol values for this enum.
         #

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

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

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

@@ -6,6 +6,7 @@ module TerminalShop
       # @api private
       module Union
         include TerminalShop::Internal::Type::Converter
+        include TerminalShop::Internal::Util::SorbetRuntimeSupport
 
         # @api private
         #

data/lib/terminal_shop/internal/util.rb

@@ -801,6 +801,62 @@ module TerminalShop
           end
         end
       end
+
+      # @api private
+      module SorbetRuntimeSupport
+        class MissingSorbetRuntimeError < ::RuntimeError
+        end
+
+        # @api private
+        #
+        # @return [Hash{Symbol=>Object}]
+        private def sorbet_runtime_constants = @sorbet_runtime_constants ||= {}
+
+        # @api private
+        #
+        # @param name [Symbol]
+        def const_missing(name)
+          super unless sorbet_runtime_constants.key?(name)
+
+          unless Object.const_defined?(:T)
+            message = "Trying to access a Sorbet constant #{name.inspect} without `sorbet-runtime`."
+            raise MissingSorbetRuntimeError.new(message)
+          end
+
+          sorbet_runtime_constants.fetch(name).call
+        end
+
+        # @api private
+        #
+        # @param name [Symbol]
+        # @param blk [Proc]
+        def define_sorbet_constant!(name, &blk) = sorbet_runtime_constants.store(name, blk)
+      end
+
+      extend TerminalShop::Internal::Util::SorbetRuntimeSupport
+
+      define_sorbet_constant!(:ParsedUri) do
+        T.type_alias do
+          {
+            scheme: T.nilable(String),
+            host: T.nilable(String),
+            port: T.nilable(Integer),
+            path: T.nilable(String),
+            query: T::Hash[String, T::Array[String]]
+          }
+        end
+      end
+
+      define_sorbet_constant!(:ServerSentEvent) do
+        T.type_alias do
+          {
+            event: T.nilable(String),
+            data: T.nilable(String),
+            id: T.nilable(String),
+            retry: T.nilable(Integer)
+          }
+        end
+      end
     end
   end
 end

data/lib/terminal_shop/internal.rb

@@ -2,10 +2,16 @@
 
 module TerminalShop
   module Internal
+    extend TerminalShop::Internal::Util::SorbetRuntimeSupport
+
     OMIT =
       Object.new.tap do
         _1.define_singleton_method(:inspect) { "#<#{TerminalShop::Internal}::OMIT>" }
       end
         .freeze
+
+    define_sorbet_constant!(:AnyHash) do
+      T.type_alias { T::Hash[Symbol, T.anything] }
+    end
   end
 end

data/lib/terminal_shop/models/subscription.rb

@@ -119,6 +119,15 @@ 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,6 +70,15 @@ 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

@@ -1,6 +1,33 @@
 # frozen_string_literal: true
 
 module TerminalShop
+  [TerminalShop::Internal::Type::BaseModel, *TerminalShop::Internal::Type::BaseModel.subclasses].each do |cls|
+    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
+      end
+    end
+  end
+
   AddressAPI = TerminalShop::Models::AddressAPI
 
   AddressCreateParams = TerminalShop::Models::AddressCreateParams

data/lib/terminal_shop/request_options.rb

@@ -69,5 +69,9 @@ module TerminalShop
     #   Returns a new instance of RequestOptions.
     #
     #   @param values [Hash{Symbol=>Object}]
+
+    define_sorbet_constant!(:OrHash) do
+      T.type_alias { T.any(TerminalShop::RequestOptions, TerminalShop::Internal::AnyHash) }
+    end
   end
 end

data/lib/terminal_shop/version.rb

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

data/lib/terminal_shop.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 # Standard libraries.
+# rubocop:disable Lint/RedundantRequireStatement
 require "English"
 require "cgi"
 require "date"
@@ -15,6 +16,7 @@ require "set"
 require "stringio"
 require "time"
 require "uri"
+# rubocop:enable Lint/RedundantRequireStatement
 
 # We already ship the preferred sorbet manifests in the package itself.
 # `tapioca` currently does not offer us a way to opt out of unnecessary compilation.