terminal-shop 0.1.0.pre.alpha.10 → 0.1.0.pre.alpha.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e49f5a72c701e7a5a68d1b537d9910a95d385966dcab6788a080c0d7cfefc503
-  data.tar.gz: c94a21a6fc772735aedd857c5f592b5ab0eb7344419814d593f7bec71b96b5e5
+  metadata.gz: 0faffe9f60961c28b6fbab9b959d5b65da1595d913bd1b74d6f41da0eb449c4c
+  data.tar.gz: c3d20e0578b8f1656fafa94ebc97b38c1726b1382ee9d5c4cdfafcdaef9d92b4
 SHA512:
-  metadata.gz: 4b5237266009ebbfb3019971b882c5c92076931ee011fbad8023c8ac806a89bd58eeb1373aa38ee60374d8af66913bacd8f00afd5f809bec5e682cabdb70dced
-  data.tar.gz: 882c016a8b85b9ce829fb952eb63cccf295595f64c500863a8550243946e5164b0308af9699f618cfd768a812831d4d2953af97a1ef12c7e3dc3bc9ab0f5c8b8
+  metadata.gz: 8b80e5fa7efbdeed121f88a0e435b3d37c62f2c0cd0d0da49f69fe164b22a04eedca3b4682b8731e8181e80362ba4d8c596bd7eafd350e8973cab0e5ac88c2ab
+  data.tar.gz: 884a37c3363ebad19f5455de196ba2723710f04014947bf36eb1db8f67fdbbe03dc8073f3af47cafe5a9adb61a6db6804c38c8983be5cffee30b1a54a6534757

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.0+
+The Terminal Ruby library provides convenient access to the Terminal REST API from any Ruby 3.0.0+
 application.
 
 It is generated with [Stainless](https://www.stainlessapi.com/).

data/lib/terminal-shop/base_client.rb

@@ -9,23 +9,126 @@ module TerminalShop
     # from whatwg fetch spec
     MAX_REDIRECTS = 20
 
-    # @private
-    #
-    # @param req [Hash{Symbol=>Object}]
-    #
-    # @raise [ArgumentError]
-    #
-    def self.validate!(req)
-      keys = [:method, :path, :query, :headers, :body, :unwrap, :page, :model, :options]
-      case req
-      in Hash
-        req.each_key do |k|
-          unless keys.include?(k)
-            raise ArgumentError.new("Request `req` keys must be one of #{keys}, got #{k.inspect}")
+    # rubocop:disable Style/MutableConstant
+    PLATFORM_HEADERS = {
+      "x-stainless-arch" => TerminalShop::Util.arch,
+      "x-stainless-lang" => "ruby",
+      "x-stainless-os" => TerminalShop::Util.os,
+      "x-stainless-package-version" => TerminalShop::VERSION,
+      "x-stainless-runtime" => ::RUBY_ENGINE,
+      "x-stainless-runtime-version" => ::RUBY_ENGINE_VERSION
+    }
+    # rubocop:enable Style/MutableConstant
+
+    class << self
+      # @private
+      #
+      # @param req [Hash{Symbol=>Object}]
+      #
+      # @raise [ArgumentError]
+      #
+      def validate!(req)
+        keys = [:method, :path, :query, :headers, :body, :unwrap, :page, :model, :options]
+        case req
+        in Hash
+          req.each_key do |k|
+            unless keys.include?(k)
+              raise ArgumentError.new("Request `req` keys must be one of #{keys}, got #{k.inspect}")
+            end
           end
+        else
+          raise ArgumentError.new("Request `req` must be a Hash or RequestOptions, got #{req.inspect}")
         end
-      else
-        raise ArgumentError.new("Request `req` must be a Hash or RequestOptions, got #{req.inspect}")
+      end
+
+      # @private
+      #
+      # @param status [Integer]
+      # @param headers [Hash{String=>String}, Net::HTTPHeader]
+      #
+      # @return [Boolean]
+      #
+      def should_retry?(status, headers:)
+        coerced = TerminalShop::Util.coerce_boolean(headers["x-should-retry"])
+        case [coerced, status]
+        in [true | false, _]
+          coerced
+        in [_, 408 | 409 | 429 | (500..)]
+          # retry on:
+          # 408: timeouts
+          # 409: locks
+          # 429: rate limits
+          # 500+: unknown errors
+          true
+        else
+          false
+        end
+      end
+
+      # @private
+      #
+      # @param request [Hash{Symbol=>Object}] .
+      #
+      #   @option request [Symbol] :method
+      #
+      #   @option request [URI::Generic] :url
+      #
+      #   @option request [Hash{String=>String}] :headers
+      #
+      #   @option request [Object] :body
+      #
+      #   @option request [Integer] :max_retries
+      #
+      #   @option request [Float] :timeout
+      #
+      # @param status [Integer]
+      #
+      # @param response_headers [Hash{String=>String}, Net::HTTPHeader]
+      #
+      # @return [Hash{Symbol=>Object}]
+      #
+      def follow_redirect(request, status:, response_headers:)
+        method, url, headers = request.fetch_values(:method, :url, :headers)
+        location =
+          TerminalShop::Util.suppress(ArgumentError) do
+            URI.join(url, response_headers["location"])
+          end
+
+        unless location
+          message = "Server responded with status #{status} but no valid location header."
+          raise TerminalShop::APIConnectionError.new(url: url, message: message)
+        end
+
+        request = {**request, url: location}
+
+        case [url.scheme, location.scheme]
+        in ["https", "http"]
+          message = "Tried to redirect to a insecure URL"
+          raise TerminalShop::APIConnectionError.new(url: url, message: message)
+        else
+          nil
+        end
+
+        # from whatwg fetch spec
+        case [status, method]
+        in [301 | 302, :post] | [303, _]
+          drop = %w[content-encoding content-language content-length content-location content-type]
+          request = {
+            **request,
+            method: method == :head ? :head : :get,
+            headers: headers.except(*drop),
+            body: nil
+          }
+        else
+        end
+
+        # from undici
+        if TerminalShop::Util.uri_origin(url) != TerminalShop::Util.uri_origin(location)
+          drop = %w[authorization cookie host proxy-authorization]
+          request = {**request, headers: request.fetch(:headers).except(*drop)}
+        end
+
+        request
       end
     end
 
@@ -55,13 +158,10 @@ module TerminalShop
     )
       @requester = TerminalShop::PooledNetRequester.new
       @headers = TerminalShop::Util.normalized_headers(
+        self.class::PLATFORM_HEADERS,
         {
-          "X-Stainless-Lang" => "ruby",
-          "X-Stainless-Package-Version" => TerminalShop::VERSION,
-          "X-Stainless-Runtime" => RUBY_ENGINE,
-          "X-Stainless-Runtime-Version" => RUBY_ENGINE_VERSION,
-          "Content-Type" => "application/json",
-          "Accept" => "application/json"
+          "accept" => "application/json",
+          "content-type" => "application/json"
         },
         headers
       )
@@ -126,10 +226,7 @@ module TerminalShop
 
       path = TerminalShop::Util.interpolate_path(uninterpolated_path)
 
-      query = TerminalShop::Util.deep_merge(
-        req[:query].to_h,
-        opts[:extra_query].to_h
-      )
+      query = TerminalShop::Util.deep_merge(req[:query].to_h, opts[:extra_query].to_h)
 
       headers = TerminalShop::Util.normalized_headers(
         @headers,
@@ -163,34 +260,15 @@ module TerminalShop
           TerminalShop::Util.deep_merge(*[req[:body], opts[:extra_body]].compact)
         end
 
-      url = TerminalShop::Util.join_parsed_uri(@base_url, {**req, path: path, query: query})
       headers, encoded = TerminalShop::Util.encode_content(headers, body)
-      max_retries = opts.fetch(:max_retries, @max_retries)
-      {method: method, url: url, headers: headers, body: encoded, max_retries: max_retries, timeout: timeout}
-    end
-
-    # @private
-    #
-    # @param status [Integer]
-    # @param headers [Hash{String=>String}]
-    #
-    # @return [Boolean]
-    #
-    private def should_retry?(status, headers:)
-      coerced = TerminalShop::Util.coerce_boolean(headers["x-should-retry"])
-      case [coerced, status]
-      in [true | false, _]
-        coerced
-      in [_, 408 | 409 | 429 | (500..)]
-        # retry on:
-        # 408: timeouts
-        # 409: locks
-        # 429: rate limits
-        # 500+: unknown errors
-        true
-      else
-        false
-      end
+      {
+        method: method,
+        url: TerminalShop::Util.join_parsed_uri(@base_url, {**req, path: path, query: query}),
+        headers: headers,
+        body: encoded,
+        max_retries: opts.fetch(:max_retries, @max_retries),
+        timeout: timeout
+      }
     end
 
     # @private
@@ -218,72 +296,6 @@ module TerminalShop
       (@initial_retry_delay * scale * jitter).clamp(0, @max_retry_delay)
     end
 
-    # @private
-    #
-    # @param request [Hash{Symbol=>Object}] .
-    #
-    #   @option request [Symbol] :method
-    #
-    #   @option request [URI::Generic] :url
-    #
-    #   @option request [Hash{String=>String}] :headers
-    #
-    #   @option request [Object] :body
-    #
-    #   @option request [Integer] :max_retries
-    #
-    #   @option request [Float] :timeout
-    #
-    # @param status [Integer]
-    #
-    # @param location_header [String]
-    #
-    # @return [Hash{Symbol=>Object}]
-    #
-    private def follow_redirect(request, status:, location_header:)
-      method, url, headers = request.fetch_values(:method, :url, :headers)
-      location =
-        TerminalShop::Util.suppress(ArgumentError) do
-          URI.join(url, location_header)
-        end
-
-      unless location
-        message = "Server responded with status #{status} but no valid location header."
-        raise TerminalShop::APIConnectionError.new(url: url, message: message)
-      end
-
-      request = {**request, url: location}
-
-      case [url.scheme, location.scheme]
-      in ["https", "http"]
-        message = "Tried to redirect to a insecure URL"
-        raise TerminalShop::APIConnectionError.new(url: url, message: message)
-      else
-        nil
-      end
-
-      # from whatwg fetch spec
-      case [status, method]
-      in [301 | 302, :post] | [303, _]
-        drop = %w[content-encoding content-language content-length content-location content-type]
-        request = {
-          **request,
-          method: method == :head ? :head : :get,
-          headers: headers.except(*drop),
-          body: nil
-        }
-      else
-      end
-
-      # from undici
-      if TerminalShop::Util.uri_origin(url) != TerminalShop::Util.uri_origin(location)
-        drop = %w[authorization cookie host proxy-authorization]
-        request = {**request, headers: request.fetch(:headers).except(*drop)}
-      end
-
-      request
-    end
-
     # @private
     #
     # @param request [Hash{Symbol=>Object}] .
@@ -307,31 +319,39 @@ module TerminalShop
     # @param send_retry_header [Boolean]
     #
     # @raise [TerminalShop::APIError]
-    # @return [Net::HTTPResponse]
+    # @return [Array(Net::HTTPResponse, Enumerable)]
     #
     private def send_request(request, redirect_count:, retry_count:, send_retry_header:)
-      url, headers, body, max_retries = request.fetch_values(:url, :headers, :body, :max_retries)
-      no_retry = retry_count >= max_retries || body.is_a?(IO) || body.is_a?(StringIO)
+      url, headers, max_retries, timeout = request.fetch_values(:url, :headers, :max_retries, :timeout)
+      input = {**request.except(:timeout), deadline: TerminalShop::Util.monotonic_secs + timeout}
 
       if send_retry_header
         headers["x-stainless-retry-count"] = retry_count.to_s
       end
 
       begin
-        response = @requester.execute(request)
+        response, stream = @requester.execute(input)
         status = Integer(response.code)
       rescue TerminalShop::APIConnectionError => e
         status = e
       end
 
+      # normally we want to drain the response body and reuse the HTTP session by clearing the socket buffers
+      # unless we hit a server error
+      srv_fault = (500...).include?(status)
+
       case status
       in ..299
-        response
-      in 300..399 if redirect_count >= MAX_REDIRECTS
-        message = "Failed to complete the request within #{MAX_REDIRECTS} redirects."
+        [response, stream]
+      in 300..399 if redirect_count >= self.class::MAX_REDIRECTS
+        message = "Failed to complete the request within #{self.class::MAX_REDIRECTS} redirects."
+
+        stream.each { next }
         raise TerminalShop::APIConnectionError.new(url: url, message: message)
       in 300..399
-        request = follow_redirect(request, status: status, location_header: response["location"])
+        request = self.class.follow_redirect(request, status: status, response_headers: response)
+
+        stream.each { next }
         send_request(
           request,
           redirect_count: redirect_count + 1,
@@ -340,18 +360,24 @@ module TerminalShop
         )
       in TerminalShop::APIConnectionError if retry_count >= max_retries
         raise status
-      in (400..) if no_retry || (response && !should_retry?(status, headers: response))
-        body = TerminalShop::Util.decode_content(response, suppress_error: true)
+      in (400..) if retry_count >= max_retries || (response && !self.class.should_retry?(
+        status,
+        headers: response
+      ))
+        decoded = TerminalShop::Util.decode_content(response, stream: stream, suppress_error: true)
 
+        stream.each { srv_fault ? break : next }
         raise TerminalShop::APIStatusError.for(
           url: url,
           status: status,
-          body: body,
+          body: decoded,
           request: nil,
           response: response
         )
       in (400..) | TerminalShop::APIConnectionError
         delay = retry_delay(response, retry_count: retry_count)
+
+        stream&.each { srv_fault ? break : next }
         sleep(delay)
 
         send_request(
@@ -385,17 +411,19 @@ module TerminalShop
     #
     #   @option req [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :options
     #
-    # @param response [nil]
+    # @param headers [Hash{String=>String}, Net::HTTPHeader]
+    #
+    # @param stream [Enumerable]
     #
     # @return [Object]
     #
-    private def parse_response(req, response)
-      parsed = TerminalShop::Util.decode_content(response)
-      unwrapped = TerminalShop::Util.dig(parsed, req[:unwrap])
+    private def parse_response(req, headers:, stream:)
+      decoded = TerminalShop::Util.decode_content(headers, stream: stream)
+      unwrapped = TerminalShop::Util.dig(decoded, req[:unwrap])
 
       case [req[:page], req.fetch(:model, TerminalShop::Unknown)]
       in [Class => page, _]
-        page.new(client: self, req: req, headers: response, unwrapped: unwrapped)
+        page.new(client: self, req: req, headers: headers, unwrapped: unwrapped)
       in [nil, Class | TerminalShop::Converter => model]
         TerminalShop::Converter.coerce(model, unwrapped)
       in [nil, nil]
@@ -433,17 +461,17 @@ module TerminalShop
       self.class.validate!(req)
       opts = req[:options].to_h
       TerminalShop::RequestOptions.validate!(opts)
-      request = build_request(req, opts)
+      request = build_request(req.except(:options), opts)
 
       # Don't send the current retry count in the headers if the caller modified the header defaults.
       send_retry_header = request.fetch(:headers)["x-stainless-retry-count"] == "0"
-      response = send_request(
+      response, stream = send_request(
         request,
         redirect_count: 0,
         retry_count: 0,
         send_retry_header: send_retry_header
       )
-      parse_response(req, response)
+      parse_response(req, headers: response, stream: stream)
     end
 
     # @return [String]

data/lib/terminal-shop/base_model.rb

@@ -148,6 +148,8 @@ module TerminalShop
             [true, Integer(value), 1]
           in [-> { _1 <= Float }, Numeric]
             [true, Float(value), 1]
+          in [-> { _1 <= Symbol }, String]
+            [true, value.to_sym, 1]
           in [-> { _1 <= String }, Symbol]
             [true, value.to_s, 1]
           in [-> { _1 <= Date || _1 <= Time }, String]
@@ -367,7 +369,6 @@ module TerminalShop
   # @abstract
   #
   class Union
-    extend TerminalShop::Extern
     extend TerminalShop::Converter
 
     # @private
@@ -502,9 +503,7 @@ module TerminalShop
         end
       end
 
-      # rubocop:disable Style/NumberedParametersLimit
       _, variant = matches.sort! { _2.first <=> _1.first }.find { |score,| !score.zero? }
-      # rubocop:enable Style/NumberedParametersLimit
       variant.nil? ? value : TerminalShop::Converter.coerce(variant, value)
     end
 
@@ -840,7 +839,6 @@ module TerminalShop
   # @abstract
   #
   class BaseModel
-    extend TerminalShop::Extern
     extend TerminalShop::Converter
 
     # @private

data/lib/terminal-shop/base_page.rb

@@ -6,8 +6,6 @@ module TerminalShop
   # @abstract
   #
   module BasePage
-    # rubocop:disable Lint/UnusedMethodArgument
-
     # @return [Boolean]
     #
     def next_page? = (raise NotImplementedError)
@@ -21,7 +19,7 @@ module TerminalShop
     #
     # @return [void]
     #
-    def auto_paging_each(&blk) = (raise NotImplementedError)
+    def auto_paging_each(&) = (raise NotImplementedError)
 
     # @return [Enumerable]
     #
@@ -34,11 +32,9 @@ module TerminalShop
     #   #
     #   # @param client [TerminalShop::BaseClient]
     #   # @param req [Hash{Symbol=>Object}]
-    #   # @param headers [Hash{String=>String}]
+    #   # @param headers [Hash{String=>String}, Net::HTTPHeader]
     #   # @param unwrapped [Object]
     #   #
     #   def initialize(client:, req:, headers:, unwrapped:); end
-
-    # rubocop:enable Lint/UnusedMethodArgument
   end
 end

data/lib/terminal-shop/client.rb

@@ -19,7 +19,6 @@ module TerminalShop
     ENVIRONMENTS = {production: "https://api.terminal.shop/", dev: "https://api.dev.terminal.shop/"}
     # rubocop:enable Style/MutableConstant
 
-    # Client option
     # @return [String]
     attr_reader :bearer_token
 

data/lib/terminal-shop/models/address.rb

@@ -2,17 +2,6 @@
 
 module TerminalShop
   module Models
-    # @example
-    # ```ruby
-    # address_api => {
-    #   id: String,
-    #   city: String,
-    #   country: String,
-    #   name: String,
-    #   street1: String,
-    #   **_
-    # }
-    # ```
     class AddressAPI < TerminalShop::BaseModel
       # @!attribute id
       #   Unique object identifier. The format and length of IDs may change over time.

data/lib/terminal-shop/models/address_create_response.rb

@@ -2,12 +2,6 @@
 
 module TerminalShop
   module Models
-    # @example
-    # ```ruby
-    # address_create_response => {
-    #   data: String
-    # }
-    # ```
     class AddressCreateResponse < TerminalShop::BaseModel
       # @!attribute data
       #   Shipping address ID.

data/lib/terminal-shop/models/address_delete_response.rb

@@ -2,12 +2,6 @@
 
 module TerminalShop
   module Models
-    # @example
-    # ```ruby
-    # address_delete_response => {
-    #   data: :ok
-    # }
-    # ```
     class AddressDeleteResponse < TerminalShop::BaseModel
       # @!attribute data
       #

data/lib/terminal-shop/models/address_list_response.rb

@@ -2,12 +2,6 @@
 
 module TerminalShop
   module Models
-    # @example
-    # ```ruby
-    # address_list_response => {
-    #   data: -> { TerminalShop::ArrayOf[TerminalShop::Models::AddressAPI] === _1 }
-    # }
-    # ```
     class AddressListResponse < TerminalShop::BaseModel
       # @!attribute data
       #   Shipping addresses.

data/lib/terminal-shop/models/app.rb

@@ -2,14 +2,6 @@
 
 module TerminalShop
   module Models
-    # @example
-    # ```ruby
-    # app_api => {
-    #   id: String,
-    #   name: String,
-    #   redirect_uri: String
-    # }
-    # ```
     class AppAPI < TerminalShop::BaseModel
       # @!attribute id
       #   Unique object identifier. The format and length of IDs may change over time.
@@ -29,14 +21,21 @@ module TerminalShop
       #   @return [String]
       required :redirect_uri, String, api_name: :redirectURI
 
+      # @!attribute secret
+      #   OAuth 2.0 client secret of the app (obfuscated).
+      #
+      #   @return [String]
+      required :secret, String
+
       # @!parse
       #   # A Terminal App used for configuring an OAuth 2.0 client.
       #   #
       #   # @param id [String]
       #   # @param name [String]
       #   # @param redirect_uri [String]
+      #   # @param secret [String]
       #   #
-      #   def initialize(id:, name:, redirect_uri:, **) = super
+      #   def initialize(id:, name:, redirect_uri:, secret:, **) = super
 
       # def initialize: (Hash | TerminalShop::BaseModel) -> void
     end

data/lib/terminal-shop/models/app_create_response.rb

@@ -2,12 +2,6 @@
 
 module TerminalShop
   module Models
-    # @example
-    # ```ruby
-    # app_create_response => {
-    #   data: TerminalShop::Models::AppCreateResponse::Data
-    # }
-    # ```
     class AppCreateResponse < TerminalShop::BaseModel
       # @!attribute data
       #
@@ -21,13 +15,6 @@ module TerminalShop
 
       # def initialize: (Hash | TerminalShop::BaseModel) -> void
 
-      # @example
-      # ```ruby
-      # data => {
-      #   id: String,
-      #   secret: String
-      # }
-      # ```
       class Data < TerminalShop::BaseModel
         # @!attribute id
         #   OAuth 2.0 client ID.

data/lib/terminal-shop/models/app_delete_response.rb

@@ -2,12 +2,6 @@
 
 module TerminalShop
   module Models
-    # @example
-    # ```ruby
-    # app_delete_response => {
-    #   data: :ok
-    # }
-    # ```
     class AppDeleteResponse < TerminalShop::BaseModel
       # @!attribute data
       #

data/lib/terminal-shop/models/app_get_response.rb

@@ -2,12 +2,6 @@
 
 module TerminalShop
   module Models
-    # @example
-    # ```ruby
-    # app_get_response => {
-    #   data: TerminalShop::Models::AppAPI
-    # }
-    # ```
     class AppGetResponse < TerminalShop::BaseModel
       # @!attribute data
       #   A Terminal App used for configuring an OAuth 2.0 client.

data/lib/terminal-shop/models/app_list_response.rb

@@ -2,12 +2,6 @@
 
 module TerminalShop
   module Models
-    # @example
-    # ```ruby
-    # app_list_response => {
-    #   data: -> { TerminalShop::ArrayOf[TerminalShop::Models::AppAPI] === _1 }
-    # }
-    # ```
     class AppListResponse < TerminalShop::BaseModel
       # @!attribute data
       #   List of apps.