knockapi 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 903d2d837a18e4bb3ffa9c023971afcd4185354ab2d743af96d63e8601c85617
-  data.tar.gz: 3557d001b592fd33171c716392a98f76ca8e1d78c9b0297f034fa39489153487
+  metadata.gz: c57d893d557fe8c19367b85213334576858a8024857ea969f05f0dd2368d9b8c
+  data.tar.gz: 3becb6c5c1d4cd3abd4a48a5abb818b035e1771651afd4172641bf228b336a83
 SHA512:
-  metadata.gz: 7868b8ab6b9afa7bb213512d0eb9ee7efef256a6f87dd949712986bb3700028e8a9506253de8b359d1a6054380f803d70db021278e843595cd0a65ae1427d381
-  data.tar.gz: 9db5d54b2c22dd351cfe895dc0a0dda56511a63915dcf770ea9cb97e013907c5f57c4c5ced290843099590e418c5fef162e0864ef3550fdbd6db15c82b9aa77b
+  metadata.gz: 3241238cd0cc508b9c967d0f035b036483d1a1e774d84409adc91632b1629927079074c5692a8ef231dfe0bbdb68e227687da1e7f0d96124545a04f269388c4a
+  data.tar.gz: 89c50a639748a21f1733a174bc65017286875121414669dca2074d98d457796e7e96eddd5241a6b43c6efe2e8d31eecb73adfb0251ac836b8f90c0e0bdba038d

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 1.1.0 (2025-05-15)
+
+Full Changelog: [v1.0.0...v1.1.0](https://github.com/knocklabs/knock-ruby/compare/v1.0.0...v1.1.0)
+
+### Features
+
+* **api:** api update ([02959e8](https://github.com/knocklabs/knock-ruby/commit/02959e82c2148f3a1a3e9e6021d48298644305e9))
+* **api:** api update ([6bc31c4](https://github.com/knocklabs/knock-ruby/commit/6bc31c4a6c0a81e096267f1c5a1cb3a9f8b29dac))
+* **api:** removes duplicate activities section ([e83c36e](https://github.com/knocklabs/knock-ruby/commit/e83c36e5c6e88a457f7306ab7515d03c1ae0a7bc))
+* bump default connection pool size limit to minimum of 99 ([b04fe89](https://github.com/knocklabs/knock-ruby/commit/b04fe8949b02a6f56979748226d24b2a30e2ea62))
+* expose base client options as read only attributes ([4f7b9a2](https://github.com/knocklabs/knock-ruby/commit/4f7b9a248aed50a6b0077a5db4f34b764f86ffd5))
+* expose recursive `#to_h` conversion ([153be54](https://github.com/knocklabs/knock-ruby/commit/153be54a04fd0b2ac0dd27278d96be70cc87b1e1))
+* support sorbet aliases at the runtime ([5e9d146](https://github.com/knocklabs/knock-ruby/commit/5e9d146ae0303f729ebeb949d0d6bb4a9943e4be))
+
+
+### Bug Fixes
+
+* **internal:** ensure formatting always uses c.utf-8 locale ([9f8e834](https://github.com/knocklabs/knock-ruby/commit/9f8e8345f2206a5b060d55838f9e22226fa47589))
+* **internal:** fix formatting script for macos ([11e651e](https://github.com/knocklabs/knock-ruby/commit/11e651eaea730816e2a558cf708382eed559a71c))
+* **internal:** update gemspec name ([2a1af3a](https://github.com/knocklabs/knock-ruby/commit/2a1af3a8e6f8dbea4f448ce3acbdf694f993aea8))
+
+
+### Chores
+
+* accept all nd-json mimetype variants ([f13a7aa](https://github.com/knocklabs/knock-ruby/commit/f13a7aa66b6ef36d0d044cea3674bfeef1f18ac2))
+* always check if current page is empty in `next_page?` ([b43503c](https://github.com/knocklabs/knock-ruby/commit/b43503c22d1c7ca08adcf1f8a01d3d3c48608962))
+* fix misc linting / minor issues ([4d8eadc](https://github.com/knocklabs/knock-ruby/commit/4d8eadcee14d85c3eb7f95b0417b74d932b344ad))
+* **internal:** codegen related update ([1ab97b3](https://github.com/knocklabs/knock-ruby/commit/1ab97b344adc1bebd79bef05e33bf825500e91e2))
+* **internal:** codegen related update ([1cdabfe](https://github.com/knocklabs/knock-ruby/commit/1cdabfed4481b5bc2f1892647c604f37ec4f201b))
+* re-export top level models under library namespace ([a2bbf55](https://github.com/knocklabs/knock-ruby/commit/a2bbf558687ac11cdb6d72e9d54c47e0a8998e7b))
+* remove Gemfile.lock during bootstrap ([b0ad2cd](https://github.com/knocklabs/knock-ruby/commit/b0ad2cd268ff2f6fe6f96d8cf1baa7296287eec4))
+* reorganize type aliases ([c50a167](https://github.com/knocklabs/knock-ruby/commit/c50a16701c7a044b1b0b5c2b6aefffe2fc1eb102))
+* revert ignoring Gemfile.lock ([c005465](https://github.com/knocklabs/knock-ruby/commit/c0054656e506496ba90c6c3b68c18e2017531fec))
+* validate request option coercion correctness ([611e596](https://github.com/knocklabs/knock-ruby/commit/611e5969960440e4004a73158af6a26da4fb4755))
+
+
+### Documentation
+
+* illustrate environmental defaults for auth variables ([a6de609](https://github.com/knocklabs/knock-ruby/commit/a6de609be150aa0d64298b0cb8a696c27c3f724c))
+* rewrite much of README.md for readability ([0530377](https://github.com/knocklabs/knock-ruby/commit/0530377bd49cb6e65155c36ed30239fa64b3bc7b))
+
 ## 1.0.0 (2025-05-01)
 
 Full Changelog: [v0.6.2...v1.0.0](https://github.com/knocklabs/knock-ruby/compare/v0.6.2...v1.0.0)

data/README.md

@@ -1,6 +1,6 @@
 # Knock Ruby API library
 
-The Knock Ruby library provides convenient access to the Knock REST API from any Ruby 3.2.0+ application.
+The Knock Ruby library provides convenient access to the Knock REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/knocklabs/knock-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
 
 It is generated with [Stainless](https://www.stainless.com/).
 
@@ -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 "knockapi", "~> 1.0.0"
+gem "knockapi", "~> 1.1.0"
 ```
 
 <!-- x-release-please-end -->
@@ -29,7 +29,7 @@ require "bundler/setup"
 require "knockapi"
 
 knock = Knockapi::Client.new(
-  api_key: "My API Key" # defaults to ENV["KNOCK_API_KEY"]
+  api_key: ENV["KNOCK_API_KEY"] # This is the default and can be omitted
 )
 
 response = knock.workflows.trigger("dinosaurs-loose", recipients: ["dnedry"], data: {dinosaur: "triceratops"})
@@ -37,16 +37,6 @@ response = knock.workflows.trigger("dinosaurs-loose", recipients: ["dnedry"], da
 puts(response.workflow_run_id)
 ```
 
-## Sorbet
-
-This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
-
-When using sorbet, it is recommended to use model classes as below. This provides stronger type checking and tooling integration.
-
-```ruby
-knock.workflows.trigger("dinosaurs-loose", recipients: ["dnedry"], data: {dinosaur: "triceratops"})
-```
-
 ### Pagination
 
 List methods in the Knock API are paginated.
@@ -66,15 +56,30 @@ page.auto_paging_each do |user|
 end
 ```
 
-### Errors
+Alternatively, you can use the `#next_page?` and `#next_page` methods for more granular control working with pages.
+
+```ruby
+if page.next_page?
+  new_page = page.next_page
+  puts(new_page.entries[0].id)
+end
+```
+
+### Handling 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 `Knockapi::Errors::APIError` will be thrown:
 
 ```ruby
 begin
   user = knock.users.get("dnedry")
-rescue Knockapi::Errors::APIError => e
-  puts(e.status) # 400
+rescue Knockapi::Errors::APIConnectionError => e
+  puts("The server could not be reached")
+  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
+rescue Knockapi::Errors::RateLimitError => e
+  puts("A 429 status code was received; we should back off a bit.")
+rescue Knockapi::Errors::APIStatusError => e
+  puts("Another non-200-range status code was received")
+  puts(e.status)
 end
 ```
 
@@ -114,11 +119,7 @@ knock.users.get("dnedry", 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.
-
-You can use the `timeout` option to configure or disable this:
+By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:
 
 ```ruby
 # Configure the default for all requests:
@@ -130,40 +131,53 @@ knock = Knockapi::Client.new(
 knock.users.get("dnedry", request_options: {timeout: 5})
 ```
 
-## Model DSL
+On timeout, `Knockapi::Errors::APITimeoutError` is raised.
 
-This library uses a simple DSL to represent request parameters and response shapes in `lib/knockapi/models`.
+Note that requests that time out are retried by default.
 
-With the right [editor plugins](https://shopify.github.io/ruby-lsp), you can ctrl-click on elements of the DSL to navigate around and explore the library.
+## Advanced concepts
 
-In all places where a `BaseModel` type is specified, vanilla Ruby `Hash` can also be used. For example, the following are interchangeable as arguments:
+### BaseModel
 
-```ruby
-# This has tooling readability, for auto-completion, static analysis, and goto definition with supported language services
-params = Knockapi::Models::WorkflowTriggerParams.new(recipients: ["dnedry"], data: {dinosaur: "triceratops"})
-
-# This also works
-params = {
-  recipients: ["dnedry"],
-  data: {dinosaur: "triceratops"}
-}
-```
+All parameter and response objects inherit from `Knockapi::Internal::Type::BaseModel`, which provides several conveniences, including:
 
-## Editor support
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
 
-A combination of [Shopify LSP](https://shopify.github.io/ruby-lsp) and [Solargraph](https://solargraph.org/) is recommended for non-[Sorbet](https://sorbet.org) users. The former is especially good at go to definition, while the latter has much better auto-completion support.
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
 
-## Advanced concepts
+3. Both instances and the classes themselves can be pretty-printed.
+
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
+
+### Making custom or undocumented requests
 
-### Making custom/undocumented requests
+#### Undocumented properties
+
+You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
+
+Note: the `extra_` parameters of the same name overrides the documented parameters.
+
+```ruby
+user =
+  knock.users.get(
+    "dnedry",
+    request_options: {
+      extra_query: {my_query_parameter: value},
+      extra_body: {my_body_parameter: value},
+      extra_headers: {"my-header": value}
+    }
+  )
+
+puts(user[:my_undocumented_property])
+```
 
 #### Undocumented request params
 
-If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a requests as seen in examples above.
+If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request as seen in examples above.
 
 #### Undocumented endpoints
 
-To make requests to undocumented endpoints, you can make requests using `client.request`. Options on the client will be respected (such as retries) when making this request.
+To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:
 
 ```ruby
 response = client.request(
@@ -171,31 +185,69 @@ response = client.request(
   path: '/undocumented/endpoint',
   query: {"dog": "woof"},
   headers: {"useful-header": "interesting-value"},
-  body: {"he": "llo"},
+  body: {"hello": "world"}
 )
 ```
 
 ### Concurrency & connection pooling
 
-The `Knockapi::Client` instances are thread-safe, and should be re-used across multiple threads. By default, each `Client` have their own HTTP connection pool, with a maximum number of connections equal to thread count.
+The `Knockapi::Client` instances are threadsafe, but only are fork-safe when there are no in-flight HTTP requests.
+
+Each instance of `Knockapi::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.
 
-When the maximum number of connections has been checked out from the connection pool, the `Client` will wait for an in use connection to become available. The queue time for this mechanism is accounted for by the per-request timeout.
+When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.
 
 Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
 
-Currently, `Knockapi::Client` instances are only fork-safe if there are no in-flight HTTP requests.
+## Sorbet
+
+This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
 
-### Sorbet
+You can provide typesafe request parameters like so:
 
-#### Argument passing trick
+```ruby
+knock.workflows.trigger("dinosaurs-loose", recipients: ["dnedry"], data: {dinosaur: "triceratops"})
+```
 
-It is possible to pass a compatible model / parameter class to a method that expects keyword arguments by using the `**` splat operator.
+Or, equivalently:
 
 ```ruby
-params = Knockapi::Models::WorkflowTriggerParams.new(recipients: ["dnedry"], data: {dinosaur: "triceratops"})
+# Hashes work, but are not typesafe:
+knock.workflows.trigger("dinosaurs-loose", recipients: ["dnedry"], data: {dinosaur: "triceratops"})
+
+# You can also splat a full Params class:
+params = Knockapi::WorkflowTriggerParams.new(recipients: ["dnedry"], data: {dinosaur: "triceratops"})
 knock.workflows.trigger("dinosaurs-loose", **params)
 ```
 
+### Enums
+
+Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
+
+```ruby
+# :exclude
+puts(Knockapi::Users::FeedListItemsParams::Archived::EXCLUDE)
+
+# Revealed type: `T.all(Knockapi::Users::FeedListItemsParams::Archived, Symbol)`
+T.reveal_type(Knockapi::Users::FeedListItemsParams::Archived::EXCLUDE)
+```
+
+Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
+
+```ruby
+# Using the enum constants preserves the tagged type information:
+knock.users.feeds.list_items(
+  archived: Knockapi::Users::FeedListItemsParams::Archived::EXCLUDE,
+  # …
+)
+
+# Literal values is also permissible:
+knock.users.feeds.list_items(
+  archived: :exclude,
+  # …
+)
+```
+
 ## 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.

data/lib/knockapi/client.rb

@@ -83,10 +83,10 @@ module Knockapi
     def initialize(
       api_key: ENV["KNOCK_API_KEY"],
       base_url: ENV["KNOCK_BASE_URL"],
-      max_retries: Knockapi::Client::DEFAULT_MAX_RETRIES,
-      timeout: Knockapi::Client::DEFAULT_TIMEOUT_IN_SECONDS,
-      initial_retry_delay: Knockapi::Client::DEFAULT_INITIAL_RETRY_DELAY,
-      max_retry_delay: Knockapi::Client::DEFAULT_MAX_RETRY_DELAY
+      max_retries: self.class::DEFAULT_MAX_RETRIES,
+      timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
     )
       base_url ||= "https://api.knock.app"
 

data/lib/knockapi/errors.rb

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

data/lib/knockapi/file_part.rb

@@ -45,9 +45,9 @@ module Knockapi
       @filename =
         case content
         in Pathname
-          filename.nil? ? content.basename.to_path : File.basename(filename)
+          filename.nil? ? content.basename.to_path : ::File.basename(filename)
         else
-          filename.nil? ? nil : File.basename(filename)
+          filename.nil? ? nil : ::File.basename(filename)
         end
       @content_type = content_type
     end

data/lib/knockapi/internal/entries_cursor.rb

@@ -24,7 +24,7 @@ module Knockapi
 
       # @return [Boolean]
       def next_page?
-        !page_info&.after.nil?
+        !entries.to_a.empty? && !page_info&.after.to_s.empty?
       end
 
       # @raise [Knockapi::HTTP::Error]
@@ -66,8 +66,8 @@ module Knockapi
         super
 
         case page_data
-        in {entries: Array | nil => entries}
-          @entries = entries&.map { Knockapi::Internal::Type::Converter.coerce(@model, _1) }
+        in {entries: Array => entries}
+          @entries = entries.map { Knockapi::Internal::Type::Converter.coerce(@model, _1) }
         else
         end
         case page_data

data/lib/knockapi/internal/items_cursor.rb

@@ -24,7 +24,7 @@ module Knockapi
 
       # @return [Boolean]
       def next_page?
-        !page_info&.after.nil?
+        !items.to_a.empty? && !page_info&.after.to_s.empty?
       end
 
       # @raise [Knockapi::HTTP::Error]
@@ -66,8 +66,8 @@ module Knockapi
         super
 
         case page_data
-        in {items: Array | nil => items}
-          @items = items&.map { Knockapi::Internal::Type::Converter.coerce(@model, _1) }
+        in {items: Array => items}
+          @items = items.map { Knockapi::Internal::Type::Converter.coerce(@model, _1) }
         else
         end
         case page_data

data/lib/knockapi/internal/ms_teams_pagination.rb

@@ -24,7 +24,7 @@ module Knockapi
 
       # @return [Boolean]
       def next_page?
-        !skip_token.nil?
+        !ms_teams_teams.to_a.empty? && !skip_token.to_s.empty?
       end
 
       # @raise [Knockapi::HTTP::Error]
@@ -67,8 +67,8 @@ module Knockapi
 
         @skip_token = page_data[:skip_token]
         case page_data
-        in {ms_teams_teams: Array | nil => ms_teams_teams}
-          @ms_teams_teams = ms_teams_teams&.map { Knockapi::Internal::Type::Converter.coerce(@model, _1) }
+        in {ms_teams_teams: Array => ms_teams_teams}
+          @ms_teams_teams = ms_teams_teams.map { Knockapi::Internal::Type::Converter.coerce(@model, _1) }
         else
         end
       end

data/lib/knockapi/internal/slack_channels_cursor.rb

@@ -24,7 +24,7 @@ module Knockapi
 
       # @return [Boolean]
       def next_page?
-        !next_cursor.nil?
+        !slack_channels.to_a.empty? && !next_cursor.to_s.empty?
       end
 
       # @raise [Knockapi::HTTP::Error]
@@ -67,8 +67,8 @@ module Knockapi
 
         @next_cursor = page_data[:next_cursor]
         case page_data
-        in {slack_channels: Array | nil => slack_channels}
-          @slack_channels = slack_channels&.map { Knockapi::Internal::Type::Converter.coerce(@model, _1) }
+        in {slack_channels: Array => slack_channels}
+          @slack_channels = slack_channels.map { Knockapi::Internal::Type::Converter.coerce(@model, _1) }
         else
         end
       end

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

@@ -7,6 +7,8 @@ module Knockapi
       #
       # @abstract
       class BaseClient
+        extend Knockapi::Internal::Util::SorbetRuntimeSupport
+
         # from whatwg fetch spec
         MAX_REDIRECTS = 20
 
@@ -151,6 +153,27 @@ module Knockapi
           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 [Knockapi::Internal::Transport::PooledNetRequester]
         attr_reader :requester
@@ -182,10 +205,11 @@ module Knockapi
             },
             headers
           )
-          @base_url = Knockapi::Internal::Util.parse_uri(base_url)
+          @base_url_components = Knockapi::Internal::Util.parse_uri(base_url)
+          @base_url = Knockapi::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 Knockapi
               Knockapi::Internal::Util.deep_merge(*[req[:body], opts[:extra_body]].compact)
             end
 
+          url = Knockapi::Internal::Util.join_parsed_uri(
+            @base_url_components,
+            {**req, path: path, query: query}
+          )
           headers, encoded = Knockapi::Internal::Util.encode_content(headers, body)
           {
             method: method,
-            url: Knockapi::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),
@@ -458,9 +486,9 @@ module Knockapi
 
           decoded = Knockapi::Internal::Util.decode_content(response, stream: stream)
           case req
-          in { stream: Class => st }
+          in {stream: Class => st}
             st.new(model: model, url: url, status: status, response: response, stream: decoded)
-          in { page: Class => page }
+          in {page: Class => page}
             page.new(client: self, req: req, headers: response, page_data: decoded)
           else
             unwrapped = Knockapi::Internal::Util.dig(decoded, req[:unwrap])
@@ -473,10 +501,54 @@ module Knockapi
         # @return [String]
         def inspect
           # rubocop:disable Layout/LineLength
-          base_url = Knockapi::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[Knockapi::Internal::Type::BasePage[Knockapi::Internal::Type::BaseModel]]),
+              stream: T.nilable(T::Class[T.anything]),
+              model: T.nilable(Knockapi::Internal::Type::Converter::Input),
+              options: T.nilable(Knockapi::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/knockapi/internal/transport/pooled_net_requester.rb

@@ -5,10 +5,14 @@ module Knockapi
     module Transport
       # @api private
       class PooledNetRequester
+        extend Knockapi::Internal::Util::SorbetRuntimeSupport
+
         # from the golang stdlib
         # https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
         KEEP_ALIVE_TIMEOUT = 30
 
+        DEFAULT_MAX_CONNECTIONS = [Etc.nprocessors, 99].max
+
         class << self
           # @api private
           #
@@ -182,11 +186,23 @@ module Knockapi
         # @api private
         #
         # @param size [Integer]
-        def initialize(size: Etc.nprocessors)
+        def initialize(size: self.class::DEFAULT_MAX_CONNECTIONS)
           @mutex = Mutex.new
           @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/knockapi/internal/type/array_of.rb

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