terminal-shop 0.1.0.pre.alpha.15 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a3091f60527a7010ac8c95c545b0d74fdf801d4275fc573515a720cbe178fe8
-  data.tar.gz: 25cef1faf2a04c0aaf4695e8c9c5ac03b51006cb69e119efa6ffd8c8967080c0
+  metadata.gz: 751da463435546aa646463c23f281021151b8416d6d96abd3fcb607cb4f1d2dd
+  data.tar.gz: 9b4b300351f7f8752b18fe11098c91b6c77fd805859f9d91aa90d85e04e4a5fe
 SHA512:
-  metadata.gz: 31a440c12cd9f04c420d2baccb9d31f592d66cec2ad7bba4b240543cfd07ce5bb3a8155499154f835b13b95e737d2a70ac3fabfad3e30b3721ec7fe306124911
-  data.tar.gz: 0c9d51f4b0e74fd05220865b119d4a9e7f23270eafee16348fc2f5ae0369f1dc89131e19607185817f3f1dfa75d34a308728ad97b2ba15d4e3c2db82352a6e19
+  metadata.gz: 200d08ede71db6dc925f78727b3e15474e825400e8ef73da2affa1ad6991b4f2832cdfe363c3b3348d308ccd5a6127288d9beea6263f819c232cbbbb82c28a6a
+  data.tar.gz: 433ff5cef723e81a8fef27c0d48a8e6a7cf30a3f051b1ad454cc2fc9d1e7b05e0bf70f7a995254ec265c0f2c48a980ab0a809122b885cba976de93bcf0066d7f

data/README.md

@@ -1,7 +1,6 @@
 # Terminal Ruby API library
 
-The Terminal Ruby library provides convenient access to the Terminal REST API from any Ruby 3.0.0+
-application.
+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.stainless.com/).
 
@@ -13,8 +12,7 @@ The underlying REST API documentation can be found on [terminal.shop](https://te
 
 ## Installation
 
-To use this gem during the beta, install directly from GitHub with Bundler by
-adding the following to your application's `Gemfile`:
+To use this gem during the beta, install directly from GitHub with Bundler by adding the following to your application's `Gemfile`:
 
 ```ruby
 gem "terminal-shop", git: "https://github.com/terminaldotshop/terminal-sdk-ruby", branch: "main"
@@ -26,8 +24,7 @@ To fetch an initial copy of the gem:
 bundle install
 ```
 
-To update the version used by your application when updates are pushed to
-GitHub:
+To update the version used by your application when updates are pushed to GitHub:
 
 ```sh
 bundle update terminal-shop
@@ -51,9 +48,7 @@ puts(product.data)
 
 ### 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::Error` will be thrown:
+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::Error` will be thrown:
 
 ```ruby
 begin
@@ -81,10 +76,9 @@ Error codes are as followed:
 
 ### Retries
 
-Certain errors will be automatically retried 2 times by default, with a short
-exponential backoff. Connection errors (for example, due to a network
-connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors,
-and timeouts will all be retried by default.
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+
+Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
 
 You can use the `max_retries` option to configure or disable this:
 
@@ -101,8 +95,8 @@ 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.
+
+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:
 
@@ -116,12 +110,26 @@ terminal = TerminalShop::Client.new(
 terminal.product.list(request_options: {timeout: 5})
 ```
 
+## Sorbet Support
+
+This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
+
+What this means is that while you can use Sorbet to type check your code statically, and benefit from the [Sorbet Language Server](https://sorbet.org/docs/lsp) in your editor, there is no runtime type checking and execution overhead from Sorbet itself.
+
+Due to limitations with the Sorbet type system, where a method otherwise can take an instance of `TerminalShop::BaseModel` class, you will need to use the `**` splat operator to pass the arguments:
+
+```ruby
+model = ProductListParams.new
+
+terminal.product.list(**model)
+```
+
 ## Versioning
 
-This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the
-library is in initial development and has a major version of `0`, APIs may change
-at any time.
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
+
+This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
 
 ## Requirements
 
-Ruby 3.0 or higher.
+Ruby 3.0.0 or higher.

data/lib/terminal-shop/base_client.rb

@@ -28,7 +28,7 @@ module TerminalShop
       # @raise [ArgumentError]
       #
       def validate!(req)
-        keys = [:method, :path, :query, :headers, :body, :unwrap, :page, :model, :options]
+        keys = [:method, :path, :query, :headers, :body, :unwrap, :page, :stream, :model, :options]
         case req
         in Hash
           req.each_key do |k|
@@ -201,6 +201,8 @@ module TerminalShop
     #
     #   @option req [Class, nil] :page
     #
+    #   @option req [Class, nil] :stream
+    #
     #   @option req [TerminalShop::Converter, Class, nil] :model
     #
     # @param opts [Hash{Symbol=>Object}] .
@@ -244,8 +246,8 @@ module TerminalShop
       end
 
       timeout = opts.fetch(:timeout, @timeout).to_f.clamp((0..))
-      unless headers.key?("x-stainless-read-timeout") || timeout.zero?
-        headers["x-stainless-read-timeout"] = timeout.to_s
+      unless headers.key?("x-stainless-timeout") || timeout.zero?
+        headers["x-stainless-timeout"] = timeout.to_s
       end
 
       headers.reject! { |_, v| v.to_s.empty? }
@@ -319,7 +321,7 @@ module TerminalShop
     # @param send_retry_header [Boolean]
     #
     # @raise [TerminalShop::APIError]
-    # @return [Array(Net::HTTPResponse, Enumerable)]
+    # @return [Array(Integer, Net::HTTPResponse, Enumerable)]
     #
     private def send_request(request, redirect_count:, retry_count:, send_retry_header:)
       url, headers, max_retries, timeout = request.fetch_values(:url, :headers, :max_retries, :timeout)
@@ -342,7 +344,7 @@ module TerminalShop
 
       case status
       in ..299
-        [response, stream]
+        [status, response, stream]
       in 300..399 if redirect_count >= self.class::MAX_REDIRECTS
         message = "Failed to complete the request within #{self.class::MAX_REDIRECTS} redirects."
 
@@ -360,13 +362,15 @@ module TerminalShop
         )
       in TerminalShop::APIConnectionError if retry_count >= max_retries
         raise status
-      in (400..) if retry_count >= max_retries || (response && !self.class.should_retry?(
-        status,
-        headers: response
-      ))
+      in (400..) if retry_count >= max_retries || !self.class.should_retry?(status, headers: response)
         decoded = TerminalShop::Util.decode_content(response, stream: stream, suppress_error: true)
 
-        stream.each { srv_fault ? break : next }
+        if srv_fault
+          TerminalShop::Util.close_fused!(stream)
+        else
+          stream.each { next }
+        end
+
         raise TerminalShop::APIStatusError.for(
           url: url,
           status: status,
@@ -377,7 +381,11 @@ module TerminalShop
       in (400..) | TerminalShop::APIConnectionError
         delay = retry_delay(response, retry_count: retry_count)
 
-        stream&.each { srv_fault ? break : next }
+        if srv_fault
+          TerminalShop::Util.close_fused!(stream)
+        else
+          stream&.each { next }
+        end
         sleep(delay)
 
         send_request(
@@ -389,48 +397,6 @@ module TerminalShop
       end
     end
 
-    # @private
-    #
-    # @param req [Hash{Symbol=>Object}] .
-    #
-    #   @option req [Symbol] :method
-    #
-    #   @option req [String, Array<String>] :path
-    #
-    #   @option req [Hash{String=>Array<String>, String, nil}, nil] :query
-    #
-    #   @option req [Hash{String=>String, Integer, Array<String, Integer, nil>, nil}, nil] :headers
-    #
-    #   @option req [Object, nil] :body
-    #
-    #   @option req [Symbol, nil] :unwrap
-    #
-    #   @option req [Class, nil] :page
-    #
-    #   @option req [TerminalShop::Converter, Class, nil] :model
-    #
-    #   @option req [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :options
-    #
-    # @param headers [Hash{String=>String}, Net::HTTPHeader]
-    #
-    # @param stream [Enumerable]
-    #
-    # @return [Object]
-    #
-    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: headers, unwrapped: unwrapped)
-      in [nil, Class | TerminalShop::Converter => model]
-        TerminalShop::Converter.coerce(model, unwrapped)
-      in [nil, nil]
-        unwrapped
-      end
-    end
-
     # Execute the request specified by `req`. This is the method that all resource
     #   methods call into.
     #
@@ -450,6 +416,8 @@ module TerminalShop
     #
     #   @option req [Class, nil] :page
     #
+    #   @option req [Class, nil] :stream
+    #
     #   @option req [TerminalShop::Converter, Class, nil] :model
     #
     #   @option req [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :options
@@ -459,19 +427,31 @@ module TerminalShop
     #
     def request(req)
       self.class.validate!(req)
+      model = req.fetch(:model) { TerminalShop::Unknown }
       opts = req[:options].to_h
       TerminalShop::RequestOptions.validate!(opts)
       request = build_request(req.except(:options), opts)
+      url = request.fetch(:url)
 
       # 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, stream = send_request(
+      status, response, stream = send_request(
         request,
         redirect_count: 0,
         retry_count: 0,
         send_retry_header: send_retry_header
       )
-      parse_response(req, headers: response, stream: stream)
+
+      decoded = TerminalShop::Util.decode_content(response, stream: stream)
+      case req
+      in { stream: Class => st }
+        st.new(model: model, url: url, status: status, response: response, messages: decoded)
+      in { page: Class => page }
+        page.new(client: self, req: req, headers: response, page_data: decoded)
+      else
+        unwrapped = TerminalShop::Util.dig(decoded, req[:unwrap])
+        TerminalShop::Converter.coerce(model, unwrapped)
+      end
     end
 
     # @return [String]