release: 0.1.0-alpha.17

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.16"
+  ".": "0.1.0-alpha.17"
 }

.rubocop.yml

@@ -8,7 +8,7 @@ AllCops:
     - "bin/*"
   NewCops: enable
   SuggestExtensions: false
-  TargetRubyVersion: 3.1.0
+  TargetRubyVersion: 3.2.0
 
 # Whether MFA is required or not should be left to the token configuration.
 Gemspec/RequireMFA:
@@ -112,6 +112,8 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   AllowedPatterns:
     - assert_pattern
+    - type_alias
+    - define_sorbet_constant!
   Exclude:
     - "**/*.rbi"
 
@@ -182,6 +184,9 @@ Style/ClassAndModuleChildren:
   Exclude:
     - "test/**/*"
 
+Style/CommentAnnotation:
+  Enabled: false
+
 # We should go back and add these docs, but ignore for now.
 Style/Documentation:
   Enabled: false

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 46
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-f09e5f2c555d7ee764478b7bc73e92cd21f403d6ec189be14574c8367bc131ce.yml
-openapi_spec_hash: bd0a8e001f14132c105992d40149909a
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-5b00a0bc705b1d5bfcb5ea79c7af544766d51ec12ccc4721825664ab397789d8.yml
+openapi_spec_hash: 34891659cff31395ba7683a8153b1db5
 config_hash: 53778a0b839c4f6ad34fbba051f5e8a6

CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.1.0-alpha.17 (2025-05-16)
+
+Full Changelog: [v0.1.0-alpha.16...v0.1.0-alpha.17](https://github.com/Finch-API/finch-api-ruby/compare/v0.1.0-alpha.16...v0.1.0-alpha.17)
+
+### Features
+
+* **api:** api update ([2cd7677](https://github.com/Finch-API/finch-api-ruby/commit/2cd76772fe2768477bb236372c94887a7f1f7022))
+* **api:** api update ([db14723](https://github.com/Finch-API/finch-api-ruby/commit/db147236a70addae46834af9b8339400480a7600))
+* **api:** api update ([1f0346a](https://github.com/Finch-API/finch-api-ruby/commit/1f0346afcca537802e8287a46bc2f759e909975f))
+* bump default connection pool size limit to minimum of 99 ([2e0e107](https://github.com/Finch-API/finch-api-ruby/commit/2e0e1078e5a29ffb965346cd6f620743f0e4b6db))
+* expose base client options as read only attributes ([289fb00](https://github.com/Finch-API/finch-api-ruby/commit/289fb00361821da703dbc9aab1db9ad8435427e3))
+* expose recursive `#to_h` conversion ([03335a6](https://github.com/Finch-API/finch-api-ruby/commit/03335a6a67ce9176fecdafc79c98ddeb22210803))
+* support sorbet aliases at the runtime ([beb18c8](https://github.com/Finch-API/finch-api-ruby/commit/beb18c85b5edba3d056d5d480f9fc4d19ea751a4))
+
+
+### Bug Fixes
+
+* **internal:** update gemspec name ([70eb621](https://github.com/Finch-API/finch-api-ruby/commit/70eb6214cf238d92f6b2f23969f252a5e4ce3941))
+
+
+### Chores
+
+* fix misc linting / minor issues ([9c271ed](https://github.com/Finch-API/finch-api-ruby/commit/9c271edf9374973a70e98774d1f55959181ed6be))
+* **internal:** version bump ([f365e16](https://github.com/Finch-API/finch-api-ruby/commit/f365e164984a15deeb545bc07ab8a85373d840ea))
+
+
+### Documentation
+
+* rewrite much of README.md for readability ([d5fac03](https://github.com/Finch-API/finch-api-ruby/commit/d5fac031d01715a45d40fab30e856e42c601a9a9))
+
 ## 0.1.0-alpha.16 (2025-05-08)
 
 Full Changelog: [v0.1.0-alpha.15...v0.1.0-alpha.16](https://github.com/Finch-API/finch-api-ruby/compare/v0.1.0-alpha.15...v0.1.0-alpha.16)

Gemfile.lock

@@ -11,7 +11,7 @@ GIT
 PATH
   remote: .
   specs:
-    finch-api (0.1.0.pre.alpha.15)
+    finch-api (0.1.0.pre.alpha.16)
       connection_pool
 
 GEM

README.md

@@ -1,6 +1,6 @@
 # Finch Ruby API library
 
-The Finch Ruby library provides convenient access to the Finch REST API from any Ruby 3.2.0+ application.
+The Finch Ruby library provides convenient access to the Finch 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/Finch-API/finch-api-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 "finch-api", "~> 0.1.0.pre.alpha.16"
+gem "finch-api", "~> 0.1.0.pre.alpha.17"
 ```
 
 <!-- x-release-please-end -->
@@ -35,16 +35,6 @@ page = finch.hris.directory.list
 puts(page.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
-finch.hris.directory.list
-```
-
 ### Pagination
 
 List methods in the Finch API are paginated.
@@ -64,15 +54,30 @@ page.auto_paging_each do |directory|
 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.individuals[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 `FinchAPI::Errors::APIError` will be thrown:
 
 ```ruby
 begin
   company = finch.hris.company.retrieve
-rescue FinchAPI::Errors::APIError => e
-  puts(e.status) # 400
+rescue FinchAPI::Errors::APIConnectionError => e
+  puts("The server could not be reached")
+  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
+rescue FinchAPI::Errors::RateLimitError => e
+  puts("A 429 status code was received; we should back off a bit.")
+rescue FinchAPI::Errors::APIStatusError => e
+  puts("Another non-200-range status code was received")
+  puts(e.status)
 end
 ```
 
@@ -112,11 +117,7 @@ finch.hris.directory.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.
-
-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:
@@ -128,82 +129,120 @@ finch = FinchAPI::Client.new(
 finch.hris.directory.list(request_options: {timeout: 5})
 ```
 
-## Model DSL
+On timeout, `FinchAPI::Errors::APITimeoutError` is raised.
+
+Note that requests that time out are retried by default.
 
-This library uses a simple DSL to represent request parameters and response shapes in `lib/finch_api/models`.
+## Advanced concepts
 
-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.
+### BaseModel
 
-In all places where a `BaseModel` type is specified, vanilla Ruby `Hash` can also be used. For example, the following are interchangeable as arguments:
+All parameter and response objects inherit from `FinchAPI::Internal::Type::BaseModel`, which provides several conveniences, including:
 
-```ruby
-# This has tooling readability, for auto-completion, static analysis, and goto definition with supported language services
-params = FinchAPI::Models::HRIS::DirectoryListParams.new
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
 
-# This also works
-params = {
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
 
-}
-```
+3. Both instances and the classes themselves can be pretty-printed.
 
-## Editor support
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
 
-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.
+### Making custom or undocumented requests
 
-## Advanced concepts
+#### Undocumented properties
+
+You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
 
-### Making custom/undocumented requests
+Note: the `extra_` parameters of the same name overrides the documented parameters.
+
+```ruby
+page =
+  finch.hris.directory.list(
+    request_options: {
+      extra_query: {my_query_parameter: value},
+      extra_body: {my_body_parameter: value},
+      extra_headers: {"my-header": value}
+    }
+  )
+
+puts(page[: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 `FinchAPI::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 `FinchAPI::Client` instances are threadsafe, but only are fork-safe when there are no in-flight HTTP requests.
 
-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.
+Each instance of `FinchAPI::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 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, `FinchAPI::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.
 
-#### Enums
+You can provide typesafe request parameters like so:
 
-Sorbet's typed enums require sub-classing of the [`T::Enum` class](https://sorbet.org/docs/tenum) from the `sorbet-runtime` gem.
+```ruby
+finch.hris.directory.list
+```
 
-Since this library does not depend on `sorbet-runtime`, it uses a [`T.all` intersection type](https://sorbet.org/docs/intersection-types) with a ruby primitive type to construct a "tagged alias" instead.
+Or, equivalently:
 
 ```ruby
-module FinchAPI::ConnectionStatusType
-  # This alias aids language service driven navigation.
-  TaggedSymbol = T.type_alias { T.all(Symbol, FinchAPI::ConnectionStatusType) }
-end
+# Hashes work, but are not typesafe:
+finch.hris.directory.list
+
+# You can also splat a full Params class:
+params = FinchAPI::HRIS::DirectoryListParams.new
+finch.hris.directory.list(**params)
 ```
 
-#### Argument passing trick
+### Enums
 
-It is possible to pass a compatible model / parameter class to a method that expects keyword arguments by using the `**` splat operator.
+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
-params = FinchAPI::Models::HRIS::DirectoryListParams.new
-finch.hris.directory.list(**params)
+# :one_time
+puts(FinchAPI::HRIS::BenefitFrequency::ONE_TIME)
+
+# Revealed type: `T.all(FinchAPI::HRIS::BenefitFrequency, Symbol)`
+T.reveal_type(FinchAPI::HRIS::BenefitFrequency::ONE_TIME)
+```
+
+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:
+finch.hris.benefits.create(
+  frequency: FinchAPI::HRIS::BenefitFrequency::ONE_TIME,
+  # …
+)
+
+# Literal values is also permissible:
+finch.hris.benefits.create(
+  frequency: :one_time,
+  # …
+)
 ```
 
 ## Versioning

Rakefile

@@ -41,7 +41,7 @@ desc("Lint `*.rb(i)`")
 multitask(:"lint:rubocop") do
   find = %w[find ./lib ./test ./rbi -type f -and ( -name *.rb -or -name *.rbi ) -print0]
 
-  rubocop = %w[rubocop --fail-level E]
+  rubocop = %w[rubocop]
   rubocop += %w[--format github] if ENV.key?("CI")
 
   # some lines cannot be shortened
@@ -147,7 +147,7 @@ multitask(:"build:gem") do
     sig/*
   GLOB
 
-  sh(*%w[gem build -- openai.gemspec])
+  sh(*%w[gem build -- finch_api.gemspec])
   rm_rf(ignore_file)
 end
 

lib/finch_api.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 # Standard libraries.
+# rubocop:disable Lint/RedundantRequireStatement
 require "English"
 require "cgi"
 require "date"
@@ -15,6 +16,7 @@
 require "stringio"
 require "time"
 require "uri"
+# rubocop:enable Lint/RedundantRequireStatement
 
 # We already ship the preferred sorbet manifests in the package itself.
 # `tapioca` currently does not offer us a way to opt out of unnecessary compilation.

lib/finch_api/client.rb

@@ -103,10 +103,10 @@ def initialize(
       client_secret: ENV["FINCH_CLIENT_SECRET"],
       access_token: nil,
       base_url: ENV["FINCH_BASE_URL"],
-      max_retries: FinchAPI::Client::DEFAULT_MAX_RETRIES,
-      timeout: FinchAPI::Client::DEFAULT_TIMEOUT_IN_SECONDS,
-      initial_retry_delay: FinchAPI::Client::DEFAULT_INITIAL_RETRY_DELAY,
-      max_retry_delay: FinchAPI::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.tryfinch.com"
 

lib/finch_api/errors.rb

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

lib/finch_api/internal.rb

@@ -2,10 +2,16 @@
 
 module FinchAPI
   module Internal
+    extend FinchAPI::Internal::Util::SorbetRuntimeSupport
+
     OMIT =
       Object.new.tap do
         _1.define_singleton_method(:inspect) { "#<#{FinchAPI::Internal}::OMIT>" }
       end
         .freeze
+
+    define_sorbet_constant!(:AnyHash) do
+      T.type_alias { T::Hash[Symbol, T.anything] }
+    end
   end
 end