terminal-shop 1.7.0 → 2.0.0

data/lib/terminal-shop/base_page.rb

@@ -1,60 +1,59 @@
 # frozen_string_literal: true
 
 module TerminalShop
-  # @private
-  #
-  # @abstract
-  #
   # @example
-  # ```ruby
-  # if page.has_next?
-  #   page = page.next_page
-  # end
-  # ```
+  #   if page.has_next?
+  #     page = page.next_page
+  #   end
   #
   # @example
-  # ```ruby
-  # page.auto_paging_each do |product|
-  #   puts(product)
-  # end
-  # ```
+  #   page.auto_paging_each do |product|
+  #     puts(product)
+  #   end
   #
   # @example
-  # ```ruby
-  # products = page.to_enum.take(2)
+  #   products =
+  #     page
+  #     .to_enum
+  #     .lazy
+  #     .select { _1.object_id.even? }
+  #     .map(&:itself)
+  #     .take(2)
+  #     .to_a
   #
-  # products => Array
-  # ```
+  #   products => Array
   module BasePage
+    # rubocop:disable Lint/UnusedMethodArgument
+
     # @return [Boolean]
-    #
     def next_page? = (raise NotImplementedError)
 
     # @raise [TerminalShop::APIError]
     # @return [TerminalShop::BasePage]
-    #
     def next_page = (raise NotImplementedError)
 
     # @param blk [Proc]
     #
     # @return [void]
-    #
     def auto_paging_each(&) = (raise NotImplementedError)
 
     # @return [Enumerable]
-    #
     def to_enum = super(:auto_paging_each)
 
     alias_method :enum_for, :to_enum
 
-    # @!parse
-    #   # @private
-    #   #
-    #   # @param client [TerminalShop::BaseClient]
-    #   # @param req [Hash{Symbol=>Object}]
-    #   # @param headers [Hash{String=>String}, Net::HTTPHeader]
-    #   # @param page_data [Object]
-    #   #
-    #   def initialize(client:, req:, headers:, page_data:); end
+    # @api private
+    #
+    # @param client [TerminalShop::BaseClient]
+    # @param req [Hash{Symbol=>Object}]
+    # @param headers [Hash{String=>String}, Net::HTTPHeader]
+    # @param page_data [Object]
+    def initialize(client:, req:, headers:, page_data:)
+      @client = client
+      @req = req
+      super()
+    end
+
+    # rubocop:enable Lint/UnusedMethodArgument
   end
 end

data/lib/terminal-shop/client.rb

@@ -16,6 +16,7 @@ module TerminalShop
     DEFAULT_MAX_RETRY_DELAY = 8.0
 
     # rubocop:disable Style/MutableConstant
+    # @type [Hash{Symbol=>String}]
     ENVIRONMENTS = {production: "https://api.terminal.shop/", dev: "https://api.dev.terminal.shop/"}
     # rubocop:enable Style/MutableConstant
 
@@ -58,10 +59,9 @@ module TerminalShop
     # @return [TerminalShop::Resources::View]
     attr_reader :view
 
-    # @private
+    # @api private
     #
     # @return [Hash{String=>String}]
-    #
     private def auth_headers
       return {} if @bearer_token.nil?
 
@@ -90,7 +90,6 @@ module TerminalShop
     # @param initial_retry_delay [Float]
     #
     # @param max_retry_delay [Float]
-    #
     def initialize(
       environment: nil,
       base_url: nil,

data/lib/terminal-shop/errors.rb

@@ -4,7 +4,7 @@ module TerminalShop
   class Error < StandardError
     # @!parse
     #   # @return [StandardError, nil]
-    #   attr_reader :cause
+    #   attr_accessor :cause
   end
 
   class ConversionError < TerminalShop::Error
@@ -12,15 +12,15 @@ module TerminalShop
 
   class APIError < TerminalShop::Error
     # @return [URI::Generic]
-    attr_reader :url
+    attr_accessor :url
 
     # @return [Integer, nil]
-    attr_reader :status
+    attr_accessor :status
 
     # @return [Object, nil]
-    attr_reader :body
+    attr_accessor :body
 
-    # @private
+    # @api private
     #
     # @param url [URI::Generic]
     # @param status [Integer, nil]
@@ -28,7 +28,6 @@ module TerminalShop
     # @param request [nil]
     # @param response [nil]
     # @param message [String, nil]
-    #
     def initialize(url:, status: nil, body: nil, request: nil, response: nil, message: nil)
       @url = url
       @status = status
@@ -42,13 +41,13 @@ module TerminalShop
   class APIConnectionError < TerminalShop::APIError
     # @!parse
     #   # @return [nil]
-    #   attr_reader :status
+    #   attr_accessor :status
 
     # @!parse
     #   # @return [nil]
-    #   attr_reader :body
+    #   attr_accessor :body
 
-    # @private
+    # @api private
     #
     # @param url [URI::Generic]
     # @param status [nil]
@@ -56,7 +55,6 @@ module TerminalShop
     # @param request [nil]
     # @param response [nil]
     # @param message [String, nil]
-    #
     def initialize(
       url:,
       status: nil,
@@ -70,7 +68,7 @@ module TerminalShop
   end
 
   class APITimeoutError < TerminalShop::APIConnectionError
-    # @private
+    # @api private
     #
     # @param url [URI::Generic]
     # @param status [nil]
@@ -78,7 +76,6 @@ module TerminalShop
     # @param request [nil]
     # @param response [nil]
     # @param message [String, nil]
-    #
     def initialize(
       url:,
       status: nil,
@@ -92,7 +89,7 @@ module TerminalShop
   end
 
   class APIStatusError < TerminalShop::APIError
-    # @private
+    # @api private
     #
     # @param url [URI::Generic]
     # @param status [Integer]
@@ -102,7 +99,6 @@ module TerminalShop
     # @param message [String, nil]
     #
     # @return [TerminalShop::APIStatusError]
-    #
     def self.for(url:, status:, body:, request:, response:, message: nil)
       kwargs = {url: url, status: status, body: body, request: request, response: response, message: message}
 
@@ -130,9 +126,9 @@ module TerminalShop
 
     # @!parse
     #   # @return [Integer]
-    #   attr_reader :status
+    #   attr_accessor :status
 
-    # @private
+    # @api private
     #
     # @param url [URI::Generic]
     # @param status [Integer]
@@ -140,7 +136,6 @@ module TerminalShop
     # @param request [nil]
     # @param response [nil]
     # @param message [String, nil]
-    #
     def initialize(url:, status:, body:, request:, response:, message: nil)
       message ||= {url: url.to_s, status: status, body: body}
       super(

data/lib/terminal-shop/extern.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
 module TerminalShop
-  # @private
-  #
-  # @abstract
-  #
+  # @api private
   module Extern
   end
 end

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

@@ -72,14 +72,18 @@ module TerminalShop
 
       # def initialize: (Hash | TerminalShop::BaseModel) -> void
 
-      # @abstract
-      #
       # Whether the product must be or can be subscribed to.
-      class Subscription < TerminalShop::Enum
+      module Subscription
+        extend TerminalShop::Enum
+
         ALLOWED = :allowed
         REQUIRED = :required
 
         finalize!
+
+        # @!parse
+        #   # @return [Array<Symbol>]
+        #   def self.values; end
       end
 
       class Tags < TerminalShop::BaseModel

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

@@ -2,14 +2,18 @@
 
 module TerminalShop
   module Models
-    # @abstract
-    #
     # A Terminal shop user's region.
-    class Region < TerminalShop::Enum
+    module Region
+      extend TerminalShop::Enum
+
       EU = :eu
       NA = :na
 
       finalize!
+
+      # @!parse
+      #   # @return [Array<Symbol>]
+      #   def self.values; end
     end
   end
 end

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

@@ -68,10 +68,10 @@ module TerminalShop
 
       # def initialize: (Hash | TerminalShop::BaseModel) -> void
 
-      # @abstract
-      #
       # Schedule of the subscription.
-      class Schedule < TerminalShop::Union
+      module Schedule
+        extend TerminalShop::Union
+
         variant -> { TerminalShop::Models::SubscriptionAPI::Schedule::Fixed }
 
         variant -> { TerminalShop::Models::SubscriptionAPI::Schedule::Weekly }
@@ -109,6 +109,10 @@ module TerminalShop
 
           # def initialize: (Hash | TerminalShop::BaseModel) -> void
         end
+
+        # @!parse
+        #   # @return [Array(TerminalShop::Models::SubscriptionAPI::Schedule::Fixed, TerminalShop::Models::SubscriptionAPI::Schedule::Weekly)]
+        #   def self.variants; end
       end
     end
   end

data/lib/terminal-shop/pooled_net_requester.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
 module TerminalShop
-  # @private
-  #
+  # @api private
   class PooledNetRequester
+    # from the golang stdlib
+    #   https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
+    KEEP_ALIVE_TIMEOUT = 30
+
     class << self
-      # @private
+      # @api private
       #
       # @param url [URI::Generic]
       #
       # @return [Net::HTTP]
-      #
       def connect(url)
         port =
           case [url.port, url.scheme]
@@ -28,17 +30,16 @@ module TerminalShop
         end
       end
 
-      # @private
+      # @api private
       #
       # @param conn [Net::HTTP]
       # @param deadline [Float]
-      #
       def calibrate_socket_timeout(conn, deadline)
         timeout = deadline - TerminalShop::Util.monotonic_secs
         conn.open_timeout = conn.read_timeout = conn.write_timeout = conn.continue_timeout = timeout
       end
 
-      # @private
+      # @api private
       #
       # @param request [Hash{Symbol=>Object}] .
       #
@@ -50,8 +51,8 @@ module TerminalShop
       #
       # @param blk [Proc]
       #
+      # @yieldparam [String]
       # @return [Net::HTTPGenericRequest]
-      #
       def build_request(request, &)
         method, url, headers, body = request.fetch_values(:method, :url, :headers, :body)
         req = Net::HTTPGenericRequest.new(
@@ -65,6 +66,7 @@ module TerminalShop
 
         case body
         in nil
+          nil
         in String
           req["content-length"] ||= body.bytesize.to_s unless req["transfer-encoding"]
           req.body_stream = TerminalShop::Util::ReadIOAdapter.new(body, &)
@@ -80,13 +82,17 @@ module TerminalShop
       end
     end
 
-    # @private
+    # @api private
     #
     # @param url [URI::Generic]
+    # @param deadline [Float]
     # @param blk [Proc]
     #
-    private def with_pool(url, &)
+    # @raise [Timeout::Error]
+    # @yieldparam [Net::HTTP]
+    private def with_pool(url, deadline:, &blk)
       origin = TerminalShop::Util.uri_origin(url)
+      timeout = deadline - TerminalShop::Util.monotonic_secs
       pool =
         @mutex.synchronize do
           @pools[origin] ||= ConnectionPool.new(size: @size) do
@@ -94,10 +100,10 @@ module TerminalShop
           end
         end
 
-      pool.with(&)
+      pool.with(timeout: timeout, &blk)
     end
 
-    # @private
+    # @api private
     #
     # @param request [Hash{Symbol=>Object}] .
     #
@@ -111,15 +117,14 @@ module TerminalShop
     #
     #   @option request [Float] :deadline
     #
-    # @return [Array(Net::HTTPResponse, Enumerable)]
-    #
+    # @return [Array(Integer, Net::HTTPResponse, Enumerable)]
     def execute(request)
       url, deadline = request.fetch_values(:url, :deadline)
 
       eof = false
       finished = false
       enum = Enumerator.new do |y|
-        with_pool(url) do |conn|
+        with_pool(url, deadline: deadline) do |conn|
           next if finished
 
           req = self.class.build_request(request) do
@@ -127,11 +132,14 @@ module TerminalShop
           end
 
           self.class.calibrate_socket_timeout(conn, deadline)
-          conn.start unless conn.started?
+          unless conn.started?
+            conn.keep_alive_timeout = self.class::KEEP_ALIVE_TIMEOUT
+            conn.start
+          end
 
           self.class.calibrate_socket_timeout(conn, deadline)
           conn.request(req) do |rsp|
-            y << [conn, rsp]
+            y << [conn, req, rsp]
             break if finished
 
             rsp.read_body do |bytes|
@@ -143,9 +151,11 @@ module TerminalShop
             eof = true
           end
         end
+      rescue Timeout::Error
+        raise TerminalShop::APITimeoutError
       end
 
-      conn, response = enum.next
+      conn, _, response = enum.next
       body = TerminalShop::Util.fused_enum(enum, external: true) do
         finished = true
         tap do
@@ -155,13 +165,12 @@ module TerminalShop
         end
         conn.finish if !eof && conn&.started?
       end
-      [response, (response.body = body)]
+      [Integer(response.code), response, (response.body = body)]
     end
 
-    # @private
+    # @api private
     #
     # @param size [Integer]
-    #
     def initialize(size: Etc.nprocessors)
       @mutex = Mutex.new
       @size = size

data/lib/terminal-shop/request_options.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
 module TerminalShop
-  # @private
-  #
-  # @abstract
-  #
+  # @api private
   module RequestParameters
     # @!parse
     #   # Options to specify HTTP behaviour for this request.
@@ -12,7 +9,6 @@ module TerminalShop
     #   attr_accessor :request_options
 
     # @param mod [Module]
-    #
     def self.included(mod)
       return unless mod <= TerminalShop::BaseModel
 
@@ -20,15 +16,13 @@ module TerminalShop
       mod.optional(:request_options, TerminalShop::RequestOptions)
     end
 
-    # @private
-    #
+    # @api private
     module Converter
-      # @private
+      # @api private
       #
       # @param params [Object]
       #
       # @return [Array(Object, Hash{Symbol=>Object})]
-      #
       def dump_request(params)
         case (dumped = dump(params))
         in Hash
@@ -46,12 +40,11 @@ module TerminalShop
   #   When making a request, you can pass an actual {RequestOptions} instance, or
   #   simply pass a Hash with symbol keys matching the attributes on this class.
   class RequestOptions < TerminalShop::BaseModel
-    # @private
+    # @api private
     #
     # @param opts [TerminalShop::RequestOptions, Hash{Symbol=>Object}]
     #
     # @raise [ArgumentError]
-    #
     def self.validate!(opts)
       case opts
       in TerminalShop::RequestOptions | Hash
@@ -90,7 +83,7 @@ module TerminalShop
     #   Extra data to send with the request. These are deep merged into any data
     #     generated as part of the normal request.
     #
-    #   @return [Hash{Symbol=>Object}, nil]
+    #   @return [Object, nil]
     optional :extra_body, TerminalShop::HashOf[TerminalShop::Unknown]
 
     # @!attribute max_retries

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

@@ -26,7 +26,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::AddressCreateResponse]
-      #
       def create(params)
         parsed, options = TerminalShop::Models::AddressCreateParams.dump_request(params)
         @client.request(
@@ -45,7 +44,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::AddressListResponse]
-      #
       def list(params = {})
         @client.request(
           method: :get,
@@ -64,7 +62,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::AddressDeleteResponse]
-      #
       def delete(id, params = {})
         @client.request(
           method: :delete,
@@ -83,7 +80,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::AddressGetResponse]
-      #
       def get(id, params = {})
         @client.request(
           method: :get,
@@ -94,7 +90,6 @@ module TerminalShop
       end
 
       # @param client [TerminalShop::Client]
-      #
       def initialize(client:)
         @client = client
       end

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

@@ -14,7 +14,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::AppCreateResponse]
-      #
       def create(params)
         parsed, options = TerminalShop::Models::AppCreateParams.dump_request(params)
         @client.request(
@@ -33,7 +32,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::AppListResponse]
-      #
       def list(params = {})
         @client.request(
           method: :get,
@@ -52,7 +50,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::AppDeleteResponse]
-      #
       def delete(id, params = {})
         @client.request(
           method: :delete,
@@ -71,7 +68,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::AppGetResponse]
-      #
       def get(id, params = {})
         @client.request(
           method: :get,
@@ -82,7 +78,6 @@ module TerminalShop
       end
 
       # @param client [TerminalShop::Client]
-      #
       def initialize(client:)
         @client = client
       end

data/lib/terminal-shop/resources/card.rb

@@ -13,7 +13,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::CardCreateResponse]
-      #
       def create(params)
         parsed, options = TerminalShop::Models::CardCreateParams.dump_request(params)
         @client.request(
@@ -32,7 +31,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::CardListResponse]
-      #
       def list(params = {})
         @client.request(
           method: :get,
@@ -51,7 +49,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::CardDeleteResponse]
-      #
       def delete(id, params = {})
         @client.request(
           method: :delete,
@@ -69,7 +66,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::CardCollectResponse]
-      #
       def collect(params = {})
         @client.request(
           method: :post,
@@ -88,7 +84,6 @@ module TerminalShop
       #   @option params [TerminalShop::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [TerminalShop::Models::CardGetResponse]
-      #
       def get(id, params = {})
         @client.request(
           method: :get,
@@ -99,7 +94,6 @@ module TerminalShop
       end
 
       # @param client [TerminalShop::Client]
-      #
       def initialize(client:)
         @client = client
       end