terminal-shop 1.6.0 → 1.8.0

data/rbi/lib/terminal-shop/base_client.rbi

@@ -1,6 +1,7 @@
 # typed: strong
 
 module TerminalShop
+  # @api private
   class BaseClient
     abstract!
 
@@ -44,16 +45,19 @@ module TerminalShop
     PLATFORM_HEADERS = T::Hash[String, String]
 
     class << self
+      # @api private
       sig { params(req: TerminalShop::BaseClient::RequestComponentsShape).void }
       def validate!(req)
       end
 
+      # @api private
       sig do
         params(status: Integer, headers: T.any(T::Hash[String, String], Net::HTTPHeader)).returns(T::Boolean)
       end
       def should_retry?(status, headers:)
       end
 
+      # @api private
       sig do
         params(
           request: TerminalShop::BaseClient::RequestInputShape,
@@ -64,6 +68,17 @@ module TerminalShop
       end
       def follow_redirect(request, status:, response_headers:)
       end
+
+      # @api private
+      sig do
+        params(
+          status: T.any(Integer, TerminalShop::APIConnectionError),
+          stream: T.nilable(T::Enumerable[String])
+        )
+          .void
+      end
+      def reap_connection!(status, stream:)
+      end
     end
 
     sig { returns(T.anything) }
@@ -74,6 +89,7 @@ module TerminalShop
     def requester=(_)
     end
 
+    # @api private
     sig do
       params(
         base_url: String,
@@ -98,14 +114,17 @@ module TerminalShop
     )
     end
 
+    # @api private
     sig { overridable.returns(T::Hash[String, String]) }
     private def auth_headers
     end
 
+    # @api private
     sig { returns(String) }
     private def generate_idempotency_key
     end
 
+    # @api private
     sig do
       overridable
         .params(req: TerminalShop::BaseClient::RequestComponentsShape, opts: T::Hash[Symbol, T.anything])
@@ -114,10 +133,12 @@ module TerminalShop
     private def build_request(req, opts)
     end
 
+    # @api private
     sig { params(headers: T::Hash[String, String], retry_count: Integer).returns(Float) }
     private def retry_delay(headers, retry_count:)
     end
 
+    # @api private
     sig do
       params(
         request: TerminalShop::BaseClient::RequestInputShape,
@@ -130,6 +151,8 @@ module TerminalShop
     private def send_request(request, redirect_count:, retry_count:, send_retry_header:)
     end
 
+    # Execute the request specified by `req`. This is the method that all resource
+    #   methods call into.
     sig do
       params(
         method: Symbol,

data/rbi/lib/terminal-shop/base_model.rbi

@@ -1,19 +1,21 @@
 # typed: strong
 
 module TerminalShop
+  # @api private
   module Converter
-    abstract!
-
     Input = T.type_alias { T.any(TerminalShop::Converter, T::Class[T.anything]) }
 
+    # @api private
     sig { overridable.params(value: T.anything).returns(T.anything) }
     def coerce(value)
     end
 
+    # @api private
     sig { overridable.params(value: T.anything).returns(T.anything) }
     def dump(value)
     end
 
+    # @api private
     sig do
       overridable
         .params(value: T.anything)
@@ -23,6 +25,7 @@ module TerminalShop
     end
 
     class << self
+      # @api private
       sig do
         params(
           spec: T.any(
@@ -40,43 +43,69 @@ module TerminalShop
       def self.type_info(spec)
       end
 
+      # @api private
+      #
+      # Based on `target`, transform `value` into `target`, to the extent possible:
+      #
+      #   1. if the given `value` conforms to `target` already, return the given `value`
+      #   2. if it's possible and safe to convert the given `value` to `target`, then the
+      #      converted value
+      #   3. otherwise, the given `value` unaltered
       sig { params(target: TerminalShop::Converter::Input, value: T.anything).returns(T.anything) }
       def self.coerce(target, value)
       end
 
+      # @api private
       sig { params(target: TerminalShop::Converter::Input, value: T.anything).returns(T.anything) }
       def self.dump(target, value)
       end
 
+      # @api private
+      #
+      # The underlying algorithm for computing maximal compatibility is subject to
+      #   future improvements.
+      #
+      #   Similar to `#.coerce`, used to determine the best union variant to decode into.
+      #
+      #   1. determine if strict-ish coercion is possible
+      #   2. return either result of successful coercion or if loose coercion is possible
+      #   3. return a score for recursively tallied count for fields that can be coerced
       sig { params(target: TerminalShop::Converter::Input, value: T.anything).returns(T.anything) }
       def self.try_strict_coerce(target, value)
       end
     end
   end
 
+  # @api private
+  #
+  # When we don't know what to expect for the value.
   class Unknown
-    abstract!
-
     extend TerminalShop::Converter
 
-    sig { params(other: T.anything).returns(T::Boolean) }
+    abstract!
+    final!
+
+    sig(:final) { params(other: T.anything).returns(T::Boolean) }
     def self.===(other)
     end
 
-    sig { params(other: T.anything).returns(T::Boolean) }
+    sig(:final) { params(other: T.anything).returns(T::Boolean) }
     def self.==(other)
     end
 
     class << self
-      sig { override.params(value: T.anything).returns(T.anything) }
+      # @api private
+      sig(:final) { override.params(value: T.anything).returns(T.anything) }
       def coerce(value)
       end
 
-      sig { override.params(value: T.anything).returns(T.anything) }
+      # @api private
+      sig(:final) { override.params(value: T.anything).returns(T.anything) }
       def dump(value)
       end
 
-      sig do
+      # @api private
+      sig(:final) do
         override
           .params(value: T.anything)
           .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
@@ -86,29 +115,40 @@ module TerminalShop
     end
   end
 
+  # @api private
+  #
+  # Ruby has no Boolean class; this is something for models to refer to.
   class BooleanModel
-    abstract!
-
     extend TerminalShop::Converter
 
-    sig { params(other: T.anything).returns(T::Boolean) }
+    abstract!
+    final!
+
+    sig(:final) { params(other: T.anything).returns(T::Boolean) }
     def self.===(other)
     end
 
-    sig { params(other: T.anything).returns(T::Boolean) }
+    sig(:final) { params(other: T.anything).returns(T::Boolean) }
     def self.==(other)
     end
 
     class << self
-      sig { override.params(value: T.any(T::Boolean, T.anything)).returns(T.any(T::Boolean, T.anything)) }
+      # @api private
+      sig(:final) do
+        override.params(value: T.any(T::Boolean, T.anything)).returns(T.any(T::Boolean, T.anything))
+      end
       def coerce(value)
       end
 
-      sig { override.params(value: T.any(T::Boolean, T.anything)).returns(T.any(T::Boolean, T.anything)) }
+      # @api private
+      sig(:final) do
+        override.params(value: T.any(T::Boolean, T.anything)).returns(T.any(T::Boolean, T.anything))
+      end
       def dump(value)
       end
 
-      sig do
+      # @api private
+      sig(:final) do
         override
           .params(value: T.anything)
           .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
@@ -118,16 +158,34 @@ module TerminalShop
     end
   end
 
+  # @api private
+  #
+  # A value from among a specified list of options. OpenAPI enum values map to Ruby
+  #   values in the SDK as follows:
+  #
+  #   1. boolean => true | false
+  #   2. integer => Integer
+  #   3. float => Float
+  #   4. string => Symbol
+  #
+  #   We can therefore convert string values to Symbols, but can't convert other
+  #   values safely.
   class Enum
+    extend TerminalShop::Converter
+
     abstract!
 
-    extend TerminalShop::Converter
+    Value = type_template(:out)
 
     class << self
-      sig { overridable.returns(T::Array[T.any(NilClass, T::Boolean, Integer, Float, Symbol)]) }
+      # All of the valid Symbol values for this enum.
+      sig { overridable.returns(T::Array[Value]) }
       def values
       end
 
+      # @api private
+      #
+      # Guard against thread safety issues by instantiating `@values`.
       sig { void }
       private def finalize!
       end
@@ -142,14 +200,17 @@ module TerminalShop
     end
 
     class << self
+      # @api private
       sig { override.params(value: T.any(String, Symbol, T.anything)).returns(T.any(Symbol, T.anything)) }
       def coerce(value)
       end
 
+      # @api private
       sig { override.params(value: T.any(Symbol, T.anything)).returns(T.any(Symbol, T.anything)) }
       def dump(value)
       end
 
+      # @api private
       sig do
         override
           .params(value: T.anything)
@@ -160,44 +221,50 @@ module TerminalShop
     end
   end
 
+  # @api private
   class Union
+    extend TerminalShop::Converter
+
     abstract!
 
-    extend TerminalShop::Converter
+    Variants = type_template(:out)
 
     class << self
-      sig { returns(T::Array[[T.nilable(Symbol), Proc]]) }
+      # @api private
+      #
+      # All of the specified variant info for this union.
+      sig { returns(T::Array[[T.nilable(Symbol), T.proc.returns(Variants)]]) }
       private def known_variants
       end
 
-      sig { overridable.returns(T::Array[[T.nilable(Symbol), T.anything]]) }
-      protected def variants
+      # @api private
+      sig { returns(T::Array[[T.nilable(Symbol), Variants]]) }
+      protected def derefed_variants
       end
 
+      # All of the specified variants for this union.
+      sig { overridable.returns(T::Array[Variants]) }
+      def variants
+      end
+
+      # @api private
       sig { params(property: Symbol).void }
       private def discriminator(property)
       end
 
+      # @api private
       sig do
         params(
-          key: T.any(
-            Symbol,
-            T::Hash[Symbol, T.anything],
-            T.proc.returns(TerminalShop::Converter::Input),
-            TerminalShop::Converter::Input
-          ),
-          spec: T.any(
-            T::Hash[Symbol, T.anything],
-            T.proc.returns(TerminalShop::Converter::Input),
-            TerminalShop::Converter::Input
-          )
+          key: T.any(Symbol, T::Hash[Symbol, T.anything], T.proc.returns(Variants), Variants),
+          spec: T.any(T::Hash[Symbol, T.anything], T.proc.returns(Variants), Variants)
         )
           .void
       end
       private def variant(key, spec = nil)
       end
 
-      sig { params(value: T.anything).returns(T.nilable(TerminalShop::Converter::Input)) }
+      # @api private
+      sig { params(value: T.anything).returns(T.nilable(Variants)) }
       private def resolve_variant(value)
       end
     end
@@ -211,14 +278,17 @@ module TerminalShop
     end
 
     class << self
+      # @api private
       sig { override.params(value: T.anything).returns(T.anything) }
       def coerce(value)
       end
 
+      # @api private
       sig { override.params(value: T.anything).returns(T.anything) }
       def dump(value)
       end
 
+      # @api private
       sig do
         override
           .params(value: T.anything)
@@ -229,20 +299,27 @@ module TerminalShop
     end
   end
 
+  # @api private
+  #
+  # Array of items of a given type.
   class ArrayOf
+    include TerminalShop::Converter
+
     abstract!
+    final!
 
-    include TerminalShop::Converter
+    Elem = type_member(:out)
 
-    sig { params(other: T.anything).returns(T::Boolean) }
+    sig(:final) { params(other: T.anything).returns(T::Boolean) }
     def ===(other)
     end
 
-    sig { params(other: T.anything).returns(T::Boolean) }
+    sig(:final) { params(other: T.anything).returns(T::Boolean) }
     def ==(other)
     end
 
-    sig do
+    # @api private
+    sig(:final) do
       override
         .params(value: T.any(T::Enumerable[T.anything], T.anything))
         .returns(T.any(T::Array[T.anything], T.anything))
@@ -250,7 +327,8 @@ module TerminalShop
     def coerce(value)
     end
 
-    sig do
+    # @api private
+    sig(:final) do
       override
         .params(value: T.any(T::Enumerable[T.anything], T.anything))
         .returns(T.any(T::Array[T.anything], T.anything))
@@ -258,7 +336,8 @@ module TerminalShop
     def dump(value)
     end
 
-    sig do
+    # @api private
+    sig(:final) do
       override
         .params(value: T.anything)
         .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
@@ -266,11 +345,13 @@ module TerminalShop
     def try_strict_coerce(value)
     end
 
-    sig { returns(TerminalShop::Converter::Input) }
+    # @api private
+    sig(:final) { returns(Elem) }
     protected def item_type
     end
 
-    sig do
+    # @api private
+    sig(:final) do
       params(
         type_info: T.any(
           T::Hash[Symbol, T.anything],
@@ -285,20 +366,27 @@ module TerminalShop
     end
   end
 
+  # @api private
+  #
+  # Hash of items of a given type.
   class HashOf
+    include TerminalShop::Converter
+
     abstract!
+    final!
 
-    include TerminalShop::Converter
+    Elem = type_member(:out)
 
-    sig { params(other: T.anything).returns(T::Boolean) }
+    sig(:final) { params(other: T.anything).returns(T::Boolean) }
     def ===(other)
     end
 
-    sig { params(other: T.anything).returns(T::Boolean) }
+    sig(:final) { params(other: T.anything).returns(T::Boolean) }
     def ==(other)
     end
 
-    sig do
+    # @api private
+    sig(:final) do
       override
         .params(value: T.any(T::Hash[T.anything, T.anything], T.anything))
         .returns(T.any(T::Hash[Symbol, T.anything], T.anything))
@@ -306,7 +394,8 @@ module TerminalShop
     def coerce(value)
     end
 
-    sig do
+    # @api private
+    sig(:final) do
       override
         .params(value: T.any(T::Hash[T.anything, T.anything], T.anything))
         .returns(T.any(T::Hash[Symbol, T.anything], T.anything))
@@ -314,7 +403,8 @@ module TerminalShop
     def dump(value)
     end
 
-    sig do
+    # @api private
+    sig(:final) do
       override
         .params(value: T.anything)
         .returns(T.any([T::Boolean, T.anything, NilClass], [T::Boolean, T::Boolean, Integer]))
@@ -322,11 +412,13 @@ module TerminalShop
     def try_strict_coerce(value)
     end
 
-    sig { returns(TerminalShop::Converter::Input) }
+    # @api private
+    sig(:final) { returns(Elem) }
     protected def item_type
     end
 
-    sig do
+    # @api private
+    sig(:final) do
       params(
         type_info: T.any(
           T::Hash[Symbol, T.anything],
@@ -342,13 +434,17 @@ module TerminalShop
   end
 
   class BaseModel
-    abstract!
-
     extend TerminalShop::Converter
 
+    abstract!
+
     KnownFieldShape = T.type_alias { {mode: T.nilable(Symbol), required: T::Boolean} }
 
     class << self
+      # @api private
+      #
+      # Assumes superclass fields are totally defined before fields are accessed /
+      #   defined on subclasses.
       sig do
         returns(
           T::Hash[
@@ -363,6 +459,7 @@ module TerminalShop
       def known_fields
       end
 
+      # @api private
       sig do
         returns(
           T::Hash[Symbol,
@@ -372,10 +469,12 @@ module TerminalShop
       def fields
       end
 
+      # @api private
       sig { returns(T::Hash[Symbol, T.proc.returns(T::Class[T.anything])]) }
       def defaults
       end
 
+      # @api private
       sig do
         params(
           name_sym: Symbol,
@@ -398,6 +497,7 @@ module TerminalShop
       private def add_field(name_sym, required:, type_info:, spec:)
       end
 
+      # @api private
       sig do
         params(
           name_sym: Symbol,
@@ -413,6 +513,7 @@ module TerminalShop
       def required(name_sym, type_info, spec = {})
       end
 
+      # @api private
       sig do
         params(
           name_sym: Symbol,
@@ -428,10 +529,17 @@ module TerminalShop
       def optional(name_sym, type_info, spec = {})
       end
 
+      # @api private
+      #
+      # `request_only` attributes not excluded from `.#coerce` when receiving responses
+      #   even if well behaved servers should not send them
       sig { params(blk: T.proc.void).void }
       private def request_only(&blk)
       end
 
+      # @api private
+      #
+      # `response_only` attributes are omitted from `.#dump` when making requests
       sig { params(blk: T.proc.void).void }
       private def response_only(&blk)
       end
@@ -442,6 +550,7 @@ module TerminalShop
     end
 
     class << self
+      # @api private
       sig do
         override
           .params(value: T.any(TerminalShop::BaseModel, T::Hash[T.anything, T.anything], T.anything))
@@ -450,6 +559,7 @@ module TerminalShop
       def coerce(value)
       end
 
+      # @api private
       sig do
         override
           .params(value: T.any(T.attached_class, T.anything))
@@ -458,6 +568,7 @@ module TerminalShop
       def dump(value)
       end
 
+      # @api private
       sig do
         override
           .params(value: T.anything)
@@ -467,10 +578,24 @@ module TerminalShop
       end
     end
 
+    # Returns the raw value associated with the given key, if found. Otherwise, nil is
+    #   returned.
+    #
+    #   It is valid to lookup keys that are not in the API spec, for example to access
+    #   undocumented features. This method does not parse response data into
+    #   higher-level types. Lookup by anything other than a Symbol is an ArgumentError.
     sig { params(key: Symbol).returns(T.nilable(T.anything)) }
     def [](key)
     end
 
+    # 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
+    #   value indicates which values were ever set on the object. i.e. there will be a
+    #   key in this hash if they ever were, even if the set value was nil.
+    #
+    #   This method is not recursive. The returned value is shared by the object, so it
+    #   should not be mutated.
     sig { overridable.returns(T::Hash[Symbol, T.anything]) }
     def to_h
     end
@@ -481,6 +606,7 @@ module TerminalShop
     def deconstruct_keys(keys)
     end
 
+    # Create a new instance of a model.
     sig { params(data: T.any(T::Hash[Symbol, T.anything], T.self_type)).returns(T.attached_class) }
     def self.new(data = {})
     end

data/rbi/lib/terminal-shop/base_page.rbi

@@ -2,8 +2,6 @@
 
 module TerminalShop
   module BasePage
-    abstract!
-
     Elem = type_member(:out)
 
     sig { overridable.returns(T::Boolean) }
@@ -24,6 +22,7 @@ module TerminalShop
 
     alias_method :enum_for, :to_enum
 
+    # @api private
     sig do
       params(
         client: TerminalShop::BaseClient,

data/rbi/lib/terminal-shop/client.rbi

@@ -67,10 +67,12 @@ module TerminalShop
     def view
     end
 
+    # @api private
     sig { override.returns(T::Hash[String, String]) }
     private def auth_headers
     end
 
+    # Creates and returns a new client for interacting with the API.
     sig do
       params(
         environment: NilClass,
@@ -85,10 +87,19 @@ module TerminalShop
         .returns(T.attached_class)
     end
     def self.new(
+      # Specifies the environment to use for the API.
+      #
+      #   Each environment maps to a different base URL:
+      #
+      #   - `production` corresponds to `https://api.terminal.shop/`
+      #   - `dev` corresponds to `https://api.dev.terminal.shop/`
       environment: nil,
+      # Override the default base URL for the API, e.g., `"https://api.example.com/v2/"`
       base_url: nil,
+      # Defaults to `ENV["TERMINAL_BEARER_TOKEN"]`
       bearer_token: ENV["TERMINAL_BEARER_TOKEN"],
       app_id: nil,
+      # Max number of retries to attempt after a failed retryable request.
       max_retries: DEFAULT_MAX_RETRIES,
       timeout: DEFAULT_TIMEOUT_IN_SECONDS,
       initial_retry_delay: DEFAULT_INITIAL_RETRY_DELAY,