release: 0.1.0-alpha.24

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.23"
+  ".": "0.1.0-alpha.24"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 195
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/increase%2Fincrease-3b98767c54e46b8a6cb396e0ec9c40154ab6566387fe3869ca2f36cb98759633.yml
-openapi_spec_hash: 870fbf29bc099f704b2e90a55362d6e5
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/increase%2Fincrease-27f9f4f9013338a67494704ce9fa855698e5de91ea0600decd52fddcf9b298a2.yml
+openapi_spec_hash: 21382ccac2711e76cdc2c1af0e2d6954
 config_hash: 1619155422217276e2489ae10ce63a25

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.0-alpha.24 (2025-05-15)
+
+Full Changelog: [v0.1.0-alpha.23...v0.1.0-alpha.24](https://github.com/Increase/increase-ruby/compare/v0.1.0-alpha.23...v0.1.0-alpha.24)
+
+### Features
+
+* **api:** api update ([3afcf27](https://github.com/Increase/increase-ruby/commit/3afcf27617485341a7bacdf0ce80d7cfdb047684))
+* **api:** api update ([bd63d1d](https://github.com/Increase/increase-ruby/commit/bd63d1d70c9bd7709a1f09e3183ddfc861a53729))
+* bump default connection pool size limit to minimum of 99 ([2742b21](https://github.com/Increase/increase-ruby/commit/2742b21734e33f6e6a3f10d74276e558345db8e0))
+
+
+### Documentation
+
+* rewrite much of README.md for readability ([30d40de](https://github.com/Increase/increase-ruby/commit/30d40de36a7c3f591ad793490f0bd09ada0343b7))
+
 ## 0.1.0-alpha.23 (2025-05-13)
 
 Full Changelog: [v0.1.0-alpha.22...v0.1.0-alpha.23](https://github.com/Increase/increase-ruby/compare/v0.1.0-alpha.22...v0.1.0-alpha.23)

Gemfile.lock

@@ -11,7 +11,7 @@ GIT
 PATH
   remote: .
   specs:
-    increase (0.1.0.pre.alpha.23)
+    increase (0.1.0.pre.alpha.24)
       connection_pool
 
 GEM

README.md

@@ -1,6 +1,6 @@
 # Increase Ruby API library
 
-The Increase Ruby library provides convenient access to the Increase REST API from any Ruby 3.2.0+ application.
+The Increase Ruby library provides convenient access to the Increase 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/Increase/increase-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.
 
 ## Documentation
 
@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "increase", "~> 0.1.0.pre.alpha.23"
+gem "increase", "~> 0.1.0.pre.alpha.24"
 ```
 
 <!-- x-release-please-end -->
@@ -40,20 +40,6 @@ account = increase.accounts.create(
 puts(account.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
-increase.accounts.create(
-  name: "New Account!",
-  entity_id: "entity_n8y8tnk2p9339ti393yi",
-  program_id: "program_i2v2os4mwza1oetokh9i"
-)
-```
-
 ### Pagination
 
 List methods in the Increase API are paginated.
@@ -73,32 +59,52 @@ page.auto_paging_each do |account|
 end
 ```
 
+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.data[0].id)
+end
+```
+
 ### File uploads
 
-Request parameters that correspond to file uploads can be passed as `StringIO`, or a [`Pathname`](https://rubyapi.org/3.2/o/pathname) instance.
+Request parameters that correspond to file uploads can be passed as raw contents, a [`Pathname`](https://rubyapi.org/3.2/o/pathname) instance, [`StringIO`](https://rubyapi.org/3.2/o/stringio), or more.
 
 ```ruby
 require "pathname"
 
-# using `Pathname`, the file will be lazily read, without reading everything in to memory
+# Use `Pathname` to send the filename and/or avoid paging a large file into memory:
 file = increase.files.create(file: Pathname("my/file.txt"), purpose: "check_image_front")
 
-file = File.read("my/file.txt")
-# using `StringIO`, useful if you already have the data in memory
-file = increase.files.create(file: StringIO.new(file), purpose: "check_image_front")
+# Alternatively, pass file contents or a `StringIO` directly:
+file = increase.files.create(file: File.read("my/file.txt"), purpose: "check_image_front")
+
+# Or, to control the filename and/or content type:
+file = Increase::FilePart.new(File.read("my/file.txt"), filename: "my/file.txt", content_type: "…")
+file = increase.files.create(file: file, purpose: "check_image_front")
 
 puts(file.id)
 ```
 
-### Errors
+Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).
+
+### 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 `Increase::Errors::APIError` will be thrown:
 
 ```ruby
 begin
   account = increase.accounts.create(name: "New Account!")
-rescue Increase::Errors::APIError => e
-  puts(e.status) # 400
+rescue Increase::Errors::APIConnectionError => e
+  puts("The server could not be reached")
+  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
+rescue Increase::Errors::RateLimitError => e
+  puts("A 429 status code was received; we should back off a bit.")
+rescue Increase::Errors::APIStatusError => e
+  puts("Another non-200-range status code was received")
+  puts(e.status)
 end
 ```
 
@@ -142,11 +148,7 @@ increase.accounts.create(
 
 ### 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:
@@ -163,81 +165,137 @@ increase.accounts.create(
 )
 ```
 
-## Model DSL
+On timeout, `Increase::Errors::APITimeoutError` is raised.
 
-This library uses a simple DSL to represent request parameters and response shapes in `lib/increase/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 = Increase::Models::AccountCreateParams.new(
-  name: "New Account!",
-  entity_id: "entity_n8y8tnk2p9339ti393yi",
-  program_id: "program_i2v2os4mwza1oetokh9i"
-)
+All parameter and response objects inherit from `Increase::Internal::Type::BaseModel`, which provides several conveniences, including:
 
-# This also works
-params = {
-  name: "New Account!",
-  entity_id: "entity_n8y8tnk2p9339ti393yi",
-  program_id: "program_i2v2os4mwza1oetokh9i"
-}
-```
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
 
-## Editor support
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
 
-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.
+3. Both instances and the classes themselves can be pretty-printed.
 
-## Advanced concepts
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
+
+### Making custom or undocumented requests
+
+#### Undocumented properties
 
-### Making custom/undocumented requests
+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
+account =
+  increase.accounts.create(
+    name: "New Account!",
+    entity_id: "entity_n8y8tnk2p9339ti393yi",
+    program_id: "program_i2v2os4mwza1oetokh9i",
+    request_options: {
+      extra_query: {my_query_parameter: value},
+      extra_body: {my_body_parameter: value},
+      extra_headers: {"my-header": value}
+    }
+  )
+
+puts(account[: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(
   method: :post,
   path: '/undocumented/endpoint',
   query: {"dog": "woof"},
   headers: {"useful-header": "interesting-value"},
-  body: {"he": "llo"},
+  body: {"hello": "world"}
 )
 ```
 
 ### Concurrency & connection pooling
 
-The `Increase::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 `Increase::Client` instances are threadsafe, but only are fork-safe when there are no in-flight HTTP requests.
+
+Each instance of `Increase::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, `Increase::Client` instances are only fork-safe if there are no in-flight HTTP requests.
+## Sorbet
 
-### Sorbet
+This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
 
-#### Argument passing trick
+You can provide typesafe request parameters like so:
 
-It is possible to pass a compatible model / parameter class to a method that expects keyword arguments by using the `**` splat operator.
+```ruby
+increase.accounts.create(
+  name: "New Account!",
+  entity_id: "entity_n8y8tnk2p9339ti393yi",
+  program_id: "program_i2v2os4mwza1oetokh9i"
+)
+```
+
+Or, equivalently:
 
 ```ruby
-params = Increase::Models::AccountCreateParams.new(
+# Hashes work, but are not typesafe:
+increase.accounts.create(
+  name: "New Account!",
+  entity_id: "entity_n8y8tnk2p9339ti393yi",
+  program_id: "program_i2v2os4mwza1oetokh9i"
+)
+
+# You can also splat a full Params class:
+params = Increase::AccountCreateParams.new(
   name: "New Account!",
   entity_id: "entity_n8y8tnk2p9339ti393yi",
   program_id: "program_i2v2os4mwza1oetokh9i"
 )
 increase.accounts.create(**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
+# :active
+puts(Increase::AccountNumberUpdateParams::Status::ACTIVE)
+
+# Revealed type: `T.all(Increase::AccountNumberUpdateParams::Status, Symbol)`
+T.reveal_type(Increase::AccountNumberUpdateParams::Status::ACTIVE)
+```
+
+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:
+increase.account_numbers.update(
+  status: Increase::AccountNumberUpdateParams::Status::ACTIVE,
+  # …
+)
+
+# Literal values is also permissible:
+increase.account_numbers.update(
+  status: :active,
+  # …
+)
+```
+
 ## 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.

lib/increase/client.rb

@@ -215,10 +215,10 @@ def initialize(
       api_key: ENV["INCREASE_API_KEY"],
       environment: nil,
       base_url: ENV["INCREASE_BASE_URL"],
-      max_retries: Increase::Client::DEFAULT_MAX_RETRIES,
-      timeout: Increase::Client::DEFAULT_TIMEOUT_IN_SECONDS,
-      initial_retry_delay: Increase::Client::DEFAULT_INITIAL_RETRY_DELAY,
-      max_retry_delay: Increase::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,
       idempotency_header: "Idempotency-Key"
     )
       base_url ||= Increase::Client::ENVIRONMENTS.fetch(environment&.to_sym || :production) do

lib/increase/internal/transport/pooled_net_requester.rb

@@ -11,6 +11,8 @@ class PooledNetRequester
         # 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
           #
@@ -184,7 +186,7 @@ def execute(request)
         # @api private
         #
         # @param size [Integer]
-        def initialize(size: Etc.nprocessors)
+        def initialize(size: self.class::DEFAULT_MAX_CONNECTIONS)
           @mutex = Mutex.new
           @size = size
           @pools = {}

lib/increase/internal/type/base_model.rb

@@ -393,6 +393,14 @@ def deep_to_h = self.class.recursively_to_h(@data, convert: false)
         # @param keys [Array<Symbol>, nil]
         #
         # @return [Hash{Symbol=>Object}]
+        #
+        # @example
+        #   # `account` is a `Increase::Account`
+        #   account => {
+        #     id: id,
+        #     bank: bank,
+        #     closed_at: closed_at
+        #   }
         def deconstruct_keys(keys)
           (keys || self.class.known_fields.keys)
             .filter_map do |k|

lib/increase/models/ach_transfer_create_params.rb

@@ -239,9 +239,11 @@ module Category
         # @see Increase::ACHTransferCreateParams::Addenda#freeform
         class Freeform < Increase::Internal::Type::BaseModel
           # @!attribute entries
-          #   Each entry represents an addendum sent with the transfer. Please reach out to
-          #   [support@increase.com](mailto:support@increase.com) to send more than one
-          #   addendum.
+          #   Each entry represents an addendum sent with the transfer. In general, you should
+          #   send at most one addendum–most ACH recipients cannot access beyond the first 80
+          #   characters sent. Please reach out to
+          #   [support@increase.com](mailto:support@increase.com) to send 2 or more addenda to
+          #   a recipient expecting a specific addendum format.
           #
           #   @return [Array<Increase::ACHTransferCreateParams::Addenda::Freeform::Entry>]
           required :entries,
@@ -255,7 +257,7 @@ class Freeform < Increase::Internal::Type::BaseModel
           #
           #   Unstructured `payment_related_information` passed through with the transfer.
           #
-          #   @param entries [Array<Increase::ACHTransferCreateParams::Addenda::Freeform::Entry>] Each entry represents an addendum sent with the transfer. Please reach out to [s
+          #   @param entries [Array<Increase::ACHTransferCreateParams::Addenda::Freeform::Entry>] Each entry represents an addendum sent with the transfer. In general, you should
 
           class Entry < Increase::Internal::Type::BaseModel
             # @!attribute payment_related_information