increase 0.3.3 → 1.1.0

data/README.md

@@ -1,356 +1,311 @@
-# Increase
+# Increase Ruby API library
 
-_A Ruby API client for [Increase](https://increase.com/), a platform for
-Bare-Metal Banking APIs!_
+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.
 
-Interact with Increase's API in a simple and Ruby-like manner.
+## Documentation
 
-🏦 Battle-tested at [HCB](https://hackclub.com/hcb/)
+Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/increase).
 
-- [Installation](#installation)
-- [Usage](#usage)
-    - [Per-request Configuration](#per-request-configuration)
-    - [Pagination](#pagination)
-    - [Error Handling](#error-handling)
-    - [Configuration](#configuration)
-    - [File Uploads](#file-uploads)
-    - [Webhooks](#webhooks)
-    - [Idempotency](#idempotency)
-- [Development](#development)
+The REST API documentation can be found on [increase.com](https://increase.com/documentation).
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+To use this gem, install via Bundler by adding the following to your application's `Gemfile`:
 
-```sh
-$ bundle add increase -v 0.3.2
-```
-
-If bundler is not being used to manage dependencies, install the gem by
-executing:
+<!-- x-release-please-start-version -->
 
-```sh
-$ gem install increase -v 0.3.2
+```ruby
+gem "increase", "~> 1.1.0"
 ```
 
+<!-- x-release-please-end -->
+
 ## Usage
 
 ```ruby
-require 'increase'
+require "bundler/setup"
+require "increase"
 
-# Grab your API key from https://dashboard.increase.com/developers/api_keys
-Increase.api_key = 'my_api_key'
-Increase.base_url = 'https://api.increase.com'
-
-# List transactions
-Increase::Transactions.list
-
-# Retrieve a transaction
-Increase::Transactions.retrieve('transaction_1234abcd')
+increase = Increase::Client.new(
+  api_key: ENV["INCREASE_API_KEY"], # This is the default and can be omitted
+  environment: "sandbox" # defaults to "production"
+)
 
-# Create an ACH Transfer
-Increase::AchTransfers.create(
-  account_id: 'account_1234abcd',
-  amount: 100_00, # 10,000 cents ($100 dollars)
-  routing_number: '123456789',
-  account_number: '9876543210',
-  statement_descriptor: 'broke the bank for some retail therapy'
+account = increase.accounts.create(
+  name: "New Account!",
+  entity_id: "entity_n8y8tnk2p9339ti393yi",
+  program_id: "program_i2v2os4mwza1oetokh9i"
 )
+
+puts(account.id)
 ```
 
-### Per-request Configuration
+### Pagination
 
-By default, the client will use the global API key and configurations. However,
-you can define a custom client to be used for per-request configuration.
+List methods in the Increase API are paginated.
 
-For example, you may want access to production and sandbox data at the same
-time.
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
 
 ```ruby
-sandbox = Increase::Client.new(
-  api_key: 'playing_it_safe',
-  base_url: 'https://sandbox.increase.com'
-)
+page = increase.accounts.list
 
-# This request will use the `sandbox` client and its configurations
-Increase::Transactions.with_config(sandbox).list
-# => [{some sandbox transactions here}, {transaction}, {transaction}, ...]
+# Fetch single item from page.
+account = page.data[0]
+puts(account.id)
 
-# This request will still use the global configurations (using production key)
-Increase::Transactions.list
-# => [{some production transactions here}, {transaction}, {transaction}, ...]
+# Automatically fetches more pages as needed.
+page.auto_paging_each do |account|
+  puts(account.id)
+end
 ```
 
-Alternatively, directly passing as hash to `with_config` works too!
+Alternatively, you can use the `#next_page?` and `#next_page` methods for more granular control working with pages.
 
 ```ruby
-Increase::Transactions.with_config(api_key: 'time_is_money', base_url: :sandbox).list
-# => [{some sandbox transactions here}, {transaction}, {transaction}, ...]
+if page.next_page?
+  new_page = page.next_page
+  puts(new_page.data[0].id)
+end
 ```
 
-See the [Configuration](#configuration) section for more information on the
-available configurations.
+### File uploads
 
-### Pagination
-
-When listing resources (e.g. transactions), **Increase** limits the number of
-results per page to 100. Luckily, the client will automatically paginate through
-all the results for you!
+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
-Increase::Transactions.list(limit: :all) do |transactions|
-  # This block will be called once for each page of results
-  puts "I got #{transactions.count} transactions!"
-end
+require "pathname"
 
-# Or, if you'd like a gargantuan array of all the transactions
-Increase::Transactions.list(limit: :all)
+# 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")
 
-# You can also use the `next_cursor` to manually paginate through the results
-txns = Increase::Transactions.list(
-  limit: 2_000,
-  'created_at.after': '2022-01-15T06:34:23Z'
-)
-# => [{transaction}, {transaction}, {transaction}, ...]
-txns.next_cursor
-# => "eyJwb2NpdGlvbiI6eyJvZmlzZXQiOjEwMH0sIm3pbHRlclI6e319"
+# 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)
 ```
 
-Watch out for the rate limit!
+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).
 
-### Error Handling
+### Handling errors
 
-Whenever you make an oopsie, the client will raise an error! Errors originating
-from the API will be a subclass of `Increase::ApiError`.
+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
-  Increase::Transactions.retrieve('i_dont_exist')
-rescue Increase::ApiError => e
-  puts e.message # "[404: object_not_found_error] Could not find the ..."
-  puts e.title # "Could not find the specified object."
-  puts e.detail # "No resource of type transaction was found with ID ..."
-  puts e.status # 404
-
-  puts e.response # This contains the full response, including headers!
-  # => #<Faraday::Response:0x000000010b1fe2b0 ...>
-
-  puts e.class # Increase::ObjectNotFoundError (subclass of Increase::ApiError)
+  account = increase.accounts.create(name: "New Account!")
+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
 ```
 
-To disable this behavior, set `Increase.raise_api_errors = false`. Errors will
-then be returned as a normal response.
+Error codes are as follows:
 
-```ruby
-Increase.raise_api_errors = false # Default: true
+| Cause            | Error Type                 |
+| ---------------- | -------------------------- |
+| HTTP 400         | `BadRequestError`          |
+| HTTP 401         | `AuthenticationError`      |
+| HTTP 403         | `PermissionDeniedError`    |
+| HTTP 404         | `NotFoundError`            |
+| HTTP 409         | `ConflictError`            |
+| HTTP 422         | `UnprocessableEntityError` |
+| HTTP 429         | `RateLimitError`           |
+| Other HTTP error | `APIStatusError`           |
+| Timeout          | `APITimeoutError`          |
+| Network error    | `APIConnectionError`       |
 
-Increase::Transactions.retrieve('i_dont_exist')
-# => {"status"=>404, "type"=>"object_not_found_error", ... }
-```
+### Retries
 
-### Configuration
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
 
-| Name                 | Description                                                                                                                                                                                                                                                     | Default                      |
-|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
-| **api_key**          | Your Increase API Key. Grab it from https://dashboard.increase.com/developers/api_keys                                                                                                                                                                          | `nil`                        |
-| **base_url**         | The base URL for Increase's API. You can use `:production` (https://api.increase.com), `:sandbox` (https://sandbox.increase.com), or set an actual URL                                                                                                          | `"https://api.increase.com"` |
-| **raise_api_errors** | Whether to raise an error when the API returns a non-2XX status. Learn more about Increase's errors [here](https://increase.com/documentation/api#errors). See error classes [here](https://github.com/garyhtou/increase-ruby/blob/main/lib/increase/errors.rb) | `true`                       |
+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.
 
-There are multiple syntaxes for configuring the client. Choose your favorite!
+You can use the `max_retries` option to configure or disable this:
 
 ```ruby
-# Set the configurations directly
-Increase.api_key = 'terabytes_of_cash' # Default: nil (you'll need one tho!)
-Increase.base_url = :production # Default: :production
-Increase.raise_api_errors = true # Default: true
-
-# Or, you can pass in a hash
-Increase.configure(api_key: 'just_my_two_cents')
-
-# Or, you can use a block!
-Increase.configure do |config|
-  config.api_key = 'digital_dough'
-  config.base_url = :sandbox # Default: :production
-  config.raise_api_errors = false # Default: true
-end
+# Configure the default for all requests:
+increase = Increase::Client.new(
+  max_retries: 0 # default is 2
+)
+
+# Or, configure per-request:
+increase.accounts.create(
+  name: "New Account!",
+  entity_id: "entity_n8y8tnk2p9339ti393yi",
+  program_id: "program_i2v2os4mwza1oetokh9i",
+  request_options: {max_retries: 5}
+)
 ```
 
-If you are using Rails, the recommended way is to set your configurations as a
-block in an initializer.
+### Timeouts
+
+By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:
 
 ```ruby
-# config/initializers/increase.rb
-
-Increase.configure do |config|
-  # Your Increase API Key!
-  # Grab it from https://dashboard.increase.com/developers/api_keys
-  config.api_key = Rails.application.credentials.dig(:increase, :api_key)
-
-  # The base URL for Increase's API.
-  # You can use
-  # - :production (https://api.increase.com)
-  # - :sandbox (https://sandbox.increase.com)
-  # - or set an actual URL
-  config.base_url = Rails.env.production? ? :production : :sandbox
-
-  # Whether to raise an error when the API returns a non-2XX status.
-  # If disabled (false), the client will return the error response as a normal,
-  # instead of raising an error.
-  # 
-  # Learn more about...
-  # - Increase's errors: https://increase.com/documentation/api#errors
-  # - Error classes: https://github.com/garyhtou/increase-ruby/blob/main/lib/increase/errors.rb
-  config.raise_api_errors = true # Default: true
-end
+# Configure the default for all requests:
+increase = Increase::Client.new(
+  timeout: nil # default is 60
+)
+
+# Or, configure per-request:
+increase.accounts.create(
+  name: "New Account!",
+  entity_id: "entity_n8y8tnk2p9339ti393yi",
+  program_id: "program_i2v2os4mwza1oetokh9i",
+  request_options: {timeout: 5}
+)
 ```
 
-### File Uploads
+On timeout, `Increase::Errors::APITimeoutError` is raised.
 
-It's as simple as passing in a file path!
+Note that requests that time out are retried by default.
 
-```ruby
-Increase::Files.create(
-  purpose: 'identity_document',
-  file: '/path/to/file.jpg'
-) 
-```
+## Advanced concepts
 
-Alternatively, you can pass in a `File` object.
+### BaseModel
 
-```ruby
-file = File.open('/path/to/file.jpg')
+All parameter and response objects inherit from `Increase::Internal::Type::BaseModel`, which provides several conveniences, including:
 
-Increase::Files.create(
-  purpose: 'identity_document',
-  file: file
-) 
-```
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
 
-Or, get even fancier and use `Increase::FileUpload` to specify the content type
-and filename.
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
 
-```ruby
-file = Increase::FileUpload.new(
-  '/path/to/file.jpg',
-  content_type: 'image/jpeg',
-  filename: 'my_file.jpg'
-)
+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`.
 
-Increase::Files.create(
-  purpose: 'identity_document',
-  file: file
-) 
+### Making custom or 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
+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])
 ```
 
-If no content type or filename is provided, the client will try to guess it.
+#### Undocumented request params
 
-### Webhooks
+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 the examples above.
 
-**Increase**'s webhooks include a `Increase-Webhook-Signature` header for
-securing your webhook endpoint. Although not required, it's strongly recommended
-that you verify the signature to ensure the request is coming from **Increase**.
+#### Undocumented endpoints
 
-Here is an example for Rails.
+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: {"hello": "world"}
+)
+```
 
-class IncreaseController < ApplicationController
-  protect_from_forgery except: :webhook # Ignore CSRF checks
+### Concurrency & connection pooling
 
-  def webhook
-    payload = request.body.read
-    sig_header = request.headers['Increase-Webhook-Signature']
-    secret = Rails.application.credentials.dig(:increase, :webhook_secret)
+The `Increase::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
 
-    Increase::Webhook::Signature.verify(
-      payload: payload,
-      signature_header: sig_header,
-      secret: secret
-    )
+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.
 
-    # It's a valid webhook! Do something with it...
+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.
 
-    render json: {success: true}
+Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
 
-  rescue Increase::WebhookSignatureVerificationError => e
-    render json: {error: 'Webhook signature verification failed'}, status: :bad_request
-  end
-end
-```
+## Sorbet
 
-### Idempotency
+This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
 
-**Increase**
-supports [idempotent requests](https://increase.com/documentation/api#idempotency)
-to allow for safely retrying requests without accidentally performing the same
-operation twice.
+You can provide typesafe request parameters like so:
 
 ```ruby
-card = Increase::Cards.create(
-  {
-    # Card parameters
-    account_id: 'account_1234abcd',
-    description: 'My Chipotle card'
-  },
-  {
-    # Request headers
-    'Idempotency-Key': 'use a V4 UUID here'
-  }
+increase.accounts.create(
+  name: "New Account!",
+  entity_id: "entity_n8y8tnk2p9339ti393yi",
+  program_id: "program_i2v2os4mwza1oetokh9i"
 )
-# => {"id"=>"card_1234abcd", "type"=>"card", ... }
+```
 
-card.idempotent_replayed
-# => nil
+Or, equivalently:
 
-# Repeat the exact same request
-card = Increase::Cards.create(...)
-# => {"id"=>"card_1234abcd", "type"=>"card", ... }
+```ruby
+# Hashes work, but are not typesafe:
+increase.accounts.create(
+  name: "New Account!",
+  entity_id: "entity_n8y8tnk2p9339ti393yi",
+  program_id: "program_i2v2os4mwza1oetokh9i"
+)
 
-card.idempotent_replayed
-# => "true"
+# 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)
 ```
 
-Reusing the key in subsequent requests will return the same response code and
-body as the original request along with an additional HTTP
-header (`Idempotent-Replayed: true`). This applies to both success and error
-responses. In situations where your request results in a validation error,
-you'll need to update your request and retry with a new idempotency key.
+### Enums
 
-## Development
+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:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then,
-run `rake spec` to run the tests. You can also run `bin/console` for an
-interactive prompt that will allow you to experiment.
+```ruby
+# :active
+puts(Increase::AccountNumberUpdateParams::Status::ACTIVE)
 
-You can also
-run `INCREASE_API_KEY=my_key_here INCREASE_BASE_URL=https://sandbox.increase.com bin/console`
-to run the console with your Increase sandbox API key pre-filled.
+# Revealed type: `T.all(Increase::AccountNumberUpdateParams::Status, Symbol)`
+T.reveal_type(Increase::AccountNumberUpdateParams::Status::ACTIVE)
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
 
-To release a new version:
+```ruby
+# Using the enum constants preserves the tagged type information:
+increase.account_numbers.update(
+  status: Increase::AccountNumberUpdateParams::Status::ACTIVE,
+  # …
+)
 
-- `gem bump --version patch|minor|major`
-    - Make sure you
-      have [`gem-release`](https://github.com/svenfuchs/gem-release)
-      installed
-- Update the CHANGELOG and README if necessary
-- `bundle exec rake release`
-- Create release on GitHub from newly created tag
+# Literal values are also permissible:
+increase.account_numbers.update(
+  status: :active,
+  # …
+)
+```
 
-## Contributing
+## 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.
 
-Bug reports and pull requests are welcome on GitHub
-at https://github.com/garyhtou/increase.
+This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
 
-## License
+## Requirements
 
-The gem is available as open source under the terms of
-the [MIT License](https://github.com/hackclub/increase-ruby/blob/main/LICENSE.txt).
+Ruby 3.2.0 or higher.
 
----
+## Contributing
 
-Please note that this is not an official library by **Increase**. This gem was
-created and maintained by [Gary Tou](https://garytou.com/).
+See [the contributing documentation](https://github.com/Increase/increase-ruby/tree/main/CONTRIBUTING.md).

data/SECURITY.md

@@ -0,0 +1,3 @@
+# Security Policy
+
+Please visit https://increase.com/security for our security policy.