modern_treasury 0.0.0 → 0.1.0.pre.alpha.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92da24721ade0d2e22c11206c7b5115af1064d4c6152fabbefeb66f2e974cfa4
-  data.tar.gz: 4a3fe90d205d614cdb0e9b862d714ecc7e866d90eba79cf66f20e1793eec1c3a
+  metadata.gz: 982153c7e4a473fd98806a6a918c95e9d2c4089a8a078c3d0e9741cb6882cd3e
+  data.tar.gz: d76a8e63ff7c9359878ceef73ab83a5e709e606ac2a2a106d881130f426106bc
 SHA512:
-  metadata.gz: afbaac197a7b230e9e62cd4021f47df3c65381245ca37f1a3c18367ae78a4b8a73f20ab96d74f76d394b48243ebd516d766155a014c5360e43e1e8c7a9df4535
-  data.tar.gz: 353543a1b23c6455d7765c48dbacf203603112aed193308e930479c55fc849762e305ffd17a9d5abcd242410123892d1b4dfe1e151807d5140751a298784e6a9
+  metadata.gz: bdc2dcda7b64d7749815a72511cc0d3221d382c25358486ee2aa046c9df2f2ace210892069a298036f52391eae6392c4a626d22fae377e5d1f826a13925328d8
+  data.tar.gz: c012c05a94e1c98227696be30cc8b0bbbe40c4c7da42045ace1f0d8f0fed2d03c13140b426f91d7db5f4e0709a6c477997fff31573a122516f5cd8cd73b20c82

data/README.md

@@ -0,0 +1,168 @@
+# Modern Treasury Ruby API library
+
+The Modern Treasury Ruby library provides convenient access to the Modern Treasury REST API from any Ruby 3.0.0+ application.
+
+## Documentation
+
+Documentation for released of this gem can be found [on RubyDoc](https://gemdocs.org/gems/modern_treasury).
+
+The underlying REST API documentation can be found on [docs.moderntreasury.com](https://docs.moderntreasury.com).
+
+## Installation
+
+To use this gem during the beta, install directly from GitHub with Bundler by adding the following to your application's `Gemfile`:
+
+```ruby
+gem "modern_treasury", git: "https://github.com/Modern-Treasury/modern-treasury-ruby", branch: "main"
+```
+
+To fetch an initial copy of the gem:
+
+```sh
+bundle install
+```
+
+To update the version used by your application when updates are pushed to GitHub:
+
+```sh
+bundle update modern_treasury
+```
+
+## Usage
+
+```ruby
+require "bundler/setup"
+require "modern_treasury"
+
+modern_treasury = ModernTreasury::Client.new(
+  organization_id: "my-organization-ID", # defaults to ENV["MODERN_TREASURY_ORGANIZATION_ID"]
+  api_key: "My API Key" # defaults to ENV["MODERN_TREASURY_API_KEY"]
+)
+
+counterparty = modern_treasury.counterparties.create(name: "my first counterparty")
+
+puts(counterparty.id)
+```
+
+### Pagination
+
+List methods in the Modern Treasury API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```ruby
+page = modern_treasury.counterparties.list
+
+# Fetch single item from page.
+counterparty = page.items[0]
+puts(counterparty.id)
+
+# Automatically fetches more pages as needed.
+page.auto_paging_each do |counterparty|
+  puts(counterparty.id)
+end
+```
+
+### 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 `ModernTreasury::Error` will be thrown:
+
+```ruby
+begin
+  external_account = modern_treasury.external_accounts.create(counterparty_id: "missing")
+rescue ModernTreasury::Error => e
+  puts(e.status) # 400
+end
+```
+
+Error codes are as followed:
+
+| Cause            | Error Type                 |
+| ---------------- | -------------------------- |
+| HTTP 400         | `BadRequestError`          |
+| HTTP 401         | `AuthenticationError`      |
+| HTTP 403         | `PermissionDeniedError`    |
+| HTTP 404         | `NotFoundError`            |
+| HTTP 409         | `ConflictError`            |
+| HTTP 422         | `UnprocessableEntityError` |
+| HTTP 429         | `RateLimitError`           |
+| HTTP >=500       | `InternalServerError`      |
+| Other HTTP error | `APIStatusError`           |
+| Timeout          | `APITimeoutError`          |
+| Network error    | `APIConnectionError`       |
+
+### Retries
+
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+
+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.
+
+You can use the `max_retries` option to configure or disable this:
+
+```ruby
+# Configure the default for all requests:
+modern_treasury = ModernTreasury::Client.new(
+  max_retries: 0 # default is 2
+)
+
+# Or, configure per-request:
+modern_treasury.counterparties.create(name: "my first counterparty", 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:
+
+```ruby
+# Configure the default for all requests:
+modern_treasury = ModernTreasury::Client.new(
+  timeout: nil # default is 60
+)
+
+# Or, configure per-request:
+modern_treasury.counterparties.create(name: "my first counterparty", request_options: {timeout: 5})
+```
+
+## Sorbet Support
+
+**This library emits an intentional warning under the [`tapioca` toolchain](https://github.com/Shopify/tapioca)**. This is normal, and does not impact functionality.
+
+This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
+
+What this means is that while you can use Sorbet to type check your code statically, and benefit from the [Sorbet Language Server](https://sorbet.org/docs/lsp) in your editor, there is no runtime type checking and execution overhead from Sorbet itself.
+
+Due to limitations with the Sorbet type system, where a method otherwise can take an instance of `ModernTreasury::BaseModel` class, you will need to use the `**` splat operator to pass the arguments:
+
+Please follow Sorbet's [setup guides](https://sorbet.org/docs/adopting) for best experience.
+
+```ruby
+model = CounterpartyCreateParams.new(name: "my first counterparty")
+
+modern_treasury.counterparties.create(**model)
+```
+
+## Advanced
+
+### Concurrency & Connection Pooling
+
+The `ModernTreasury::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.
+
+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.
+
+Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
+
+Currently, `ModernTreasury::Client` instances are only fork-safe if there are no in-flight HTTP requests.
+
+## 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.
+
+This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
+
+## Requirements
+
+Ruby 3.0.0 or higher.

data/lib/modern_treasury/base_client.rb

@@ -0,0 +1,457 @@
+# frozen_string_literal: true
+
+module ModernTreasury
+  # @api private
+  #
+  # @abstract
+  class BaseClient
+    # from whatwg fetch spec
+    MAX_REDIRECTS = 20
+
+    # rubocop:disable Style/MutableConstant
+    PLATFORM_HEADERS =
+      {
+        "x-stainless-arch" => ModernTreasury::Util.arch,
+        "x-stainless-lang" => "ruby",
+        "x-stainless-os" => ModernTreasury::Util.os,
+        "x-stainless-package-version" => ModernTreasury::VERSION,
+        "x-stainless-runtime" => ::RUBY_ENGINE,
+        "x-stainless-runtime-version" => ::RUBY_ENGINE_VERSION
+      }
+    # rubocop:enable Style/MutableConstant
+
+    class << self
+      # @api private
+      #
+      # @param req [Hash{Symbol=>Object}]
+      #
+      # @raise [ArgumentError]
+      def validate!(req)
+        keys = [:method, :path, :query, :headers, :body, :unwrap, :page, :stream, :model, :options]
+        case req
+        in Hash
+          req.each_key do |k|
+            unless keys.include?(k)
+              raise ArgumentError.new("Request `req` keys must be one of #{keys}, got #{k.inspect}")
+            end
+          end
+        else
+          raise ArgumentError.new("Request `req` must be a Hash or RequestOptions, got #{req.inspect}")
+        end
+      end
+
+      # @api private
+      #
+      # @param status [Integer]
+      # @param headers [Hash{String=>String}, Net::HTTPHeader]
+      #
+      # @return [Boolean]
+      def should_retry?(status, headers:)
+        coerced = ModernTreasury::Util.coerce_boolean(headers["x-should-retry"])
+        case [coerced, status]
+        in [true | false, _]
+          coerced
+        in [_, 408 | 409 | 429 | (500..)]
+          # retry on:
+          # 408: timeouts
+          # 409: locks
+          # 429: rate limits
+          # 500+: unknown errors
+          true
+        else
+          false
+        end
+      end
+
+      # @api private
+      #
+      # @param request [Hash{Symbol=>Object}] .
+      #
+      #   @option request [Symbol] :method
+      #
+      #   @option request [URI::Generic] :url
+      #
+      #   @option request [Hash{String=>String}] :headers
+      #
+      #   @option request [Object] :body
+      #
+      #   @option request [Integer] :max_retries
+      #
+      #   @option request [Float] :timeout
+      #
+      # @param status [Integer]
+      #
+      # @param response_headers [Hash{String=>String}, Net::HTTPHeader]
+      #
+      # @return [Hash{Symbol=>Object}]
+      def follow_redirect(request, status:, response_headers:)
+        method, url, headers = request.fetch_values(:method, :url, :headers)
+        location =
+          Kernel.then do
+            URI.join(url, response_headers["location"])
+          rescue ArgumentError
+            message = "Server responded with status #{status} but no valid location header."
+            raise ModernTreasury::APIConnectionError.new(url: url, message: message)
+          end
+
+        request = {**request, url: location}
+
+        case [url.scheme, location.scheme]
+        in ["https", "http"]
+          message = "Tried to redirect to a insecure URL"
+          raise ModernTreasury::APIConnectionError.new(url: url, message: message)
+        else
+          nil
+        end
+
+        # from whatwg fetch spec
+        case [status, method]
+        in [301 | 302, :post] | [303, _]
+          drop = %w[content-encoding content-language content-length content-location content-type]
+          request = {
+            **request,
+            method: method == :head ? :head : :get,
+            headers: headers.except(*drop),
+            body: nil
+          }
+        else
+        end
+
+        # from undici
+        if ModernTreasury::Util.uri_origin(url) != ModernTreasury::Util.uri_origin(location)
+          drop = %w[authorization cookie host proxy-authorization]
+          request = {**request, headers: request.fetch(:headers).except(*drop)}
+        end
+
+        request
+      end
+
+      # @api private
+      #
+      # @param status [Integer, ModernTreasury::APIConnectionError]
+      # @param stream [Enumerable, nil]
+      def reap_connection!(status, stream:)
+        case status
+        in (..199) | (300..499)
+          stream&.each { next }
+        in ModernTreasury::APIConnectionError | (500..)
+          ModernTreasury::Util.close_fused!(stream)
+        else
+        end
+      end
+    end
+
+    # @api private
+    # @return [ModernTreasury::PooledNetRequester]
+    attr_accessor :requester
+
+    # @api private
+    #
+    # @param base_url [String]
+    # @param timeout [Float]
+    # @param max_retries [Integer]
+    # @param initial_retry_delay [Float]
+    # @param max_retry_delay [Float]
+    # @param headers [Hash{String=>String, Integer, Array<String, Integer, nil>, nil}]
+    # @param idempotency_header [String, nil]
+    def initialize(
+      base_url:,
+      timeout: 0.0,
+      max_retries: 0,
+      initial_retry_delay: 0.0,
+      max_retry_delay: 0.0,
+      headers: {},
+      idempotency_header: nil
+    )
+      @requester = ModernTreasury::PooledNetRequester.new
+      @headers = ModernTreasury::Util.normalized_headers(
+        self.class::PLATFORM_HEADERS,
+        {
+          "accept" => "application/json",
+          "content-type" => "application/json"
+        },
+        headers
+      )
+      @base_url = ModernTreasury::Util.parse_uri(base_url)
+      @idempotency_header = idempotency_header&.to_s&.downcase
+      @max_retries = max_retries
+      @timeout = timeout
+      @initial_retry_delay = initial_retry_delay
+      @max_retry_delay = max_retry_delay
+    end
+
+    # @api private
+    #
+    # @return [Hash{String=>String}]
+    private def auth_headers = {}
+
+    # @api private
+    #
+    # @return [String]
+    private def generate_idempotency_key = "stainless-ruby-retry-#{SecureRandom.uuid}"
+
+    # @api private
+    #
+    # @param req [Hash{Symbol=>Object}] .
+    #
+    #   @option req [Symbol] :method
+    #
+    #   @option req [String, Array<String>] :path
+    #
+    #   @option req [Hash{String=>Array<String>, String, nil}, nil] :query
+    #
+    #   @option req [Hash{String=>String, Integer, Array<String, Integer, nil>, nil}, nil] :headers
+    #
+    #   @option req [Object, nil] :body
+    #
+    #   @option req [Symbol, nil] :unwrap
+    #
+    #   @option req [Class, nil] :page
+    #
+    #   @option req [Class, nil] :stream
+    #
+    #   @option req [ModernTreasury::Converter, Class, nil] :model
+    #
+    # @param opts [Hash{Symbol=>Object}] .
+    #
+    #   @option opts [String, nil] :idempotency_key
+    #
+    #   @option opts [Hash{String=>Array<String>, String, nil}, nil] :extra_query
+    #
+    #   @option opts [Hash{String=>String, nil}, nil] :extra_headers
+    #
+    #   @option opts [Object, nil] :extra_body
+    #
+    #   @option opts [Integer, nil] :max_retries
+    #
+    #   @option opts [Float, nil] :timeout
+    #
+    # @return [Hash{Symbol=>Object}]
+    private def build_request(req, opts)
+      method, uninterpolated_path = req.fetch_values(:method, :path)
+
+      path = ModernTreasury::Util.interpolate_path(uninterpolated_path)
+
+      query = ModernTreasury::Util.deep_merge(req[:query].to_h, opts[:extra_query].to_h)
+
+      headers = ModernTreasury::Util.normalized_headers(
+        @headers,
+        auth_headers,
+        req[:headers].to_h,
+        opts[:extra_headers].to_h
+      )
+
+      if @idempotency_header &&
+         !headers.key?(@idempotency_header) &&
+         !Net::HTTP::IDEMPOTENT_METHODS_.include?(method.to_s.upcase)
+        headers[@idempotency_header] = opts.fetch(:idempotency_key) { generate_idempotency_key }
+      end
+
+      unless headers.key?("x-stainless-retry-count")
+        headers["x-stainless-retry-count"] = "0"
+      end
+
+      timeout = opts.fetch(:timeout, @timeout).to_f.clamp((0..))
+      unless headers.key?("x-stainless-timeout") || timeout.zero?
+        headers["x-stainless-timeout"] = timeout.to_s
+      end
+
+      headers.reject! { |_, v| v.to_s.empty? }
+
+      body =
+        case method
+        in :get | :head | :options | :trace
+          nil
+        else
+          ModernTreasury::Util.deep_merge(*[req[:body], opts[:extra_body]].compact)
+        end
+
+      headers, encoded = ModernTreasury::Util.encode_content(headers, body)
+      {
+        method: method,
+        url: ModernTreasury::Util.join_parsed_uri(@base_url, {**req, path: path, query: query}),
+        headers: headers,
+        body: encoded,
+        max_retries: opts.fetch(:max_retries, @max_retries),
+        timeout: timeout
+      }
+    end
+
+    # @api private
+    #
+    # @param headers [Hash{String=>String}]
+    # @param retry_count [Integer]
+    #
+    # @return [Float]
+    private def retry_delay(headers, retry_count:)
+      # Non-standard extension
+      span = Float(headers["retry-after-ms"], exception: false)&.then { _1 / 1000 }
+      return span if span
+
+      retry_header = headers["retry-after"]
+      return span if (span = Float(retry_header, exception: false))
+
+      span = retry_header&.then do
+        Time.httpdate(_1) - Time.now
+      rescue ArgumentError
+        nil
+      end
+      return span if span
+
+      scale = retry_count**2
+      jitter = 1 - (0.25 * rand)
+      (@initial_retry_delay * scale * jitter).clamp(0, @max_retry_delay)
+    end
+
+    # @api private
+    #
+    # @param request [Hash{Symbol=>Object}] .
+    #
+    #   @option request [Symbol] :method
+    #
+    #   @option request [URI::Generic] :url
+    #
+    #   @option request [Hash{String=>String}] :headers
+    #
+    #   @option request [Object] :body
+    #
+    #   @option request [Integer] :max_retries
+    #
+    #   @option request [Float] :timeout
+    #
+    # @param redirect_count [Integer]
+    #
+    # @param retry_count [Integer]
+    #
+    # @param send_retry_header [Boolean]
+    #
+    # @raise [ModernTreasury::APIError]
+    # @return [Array(Integer, Net::HTTPResponse, Enumerable)]
+    private def send_request(request, redirect_count:, retry_count:, send_retry_header:)
+      url, headers, max_retries, timeout = request.fetch_values(:url, :headers, :max_retries, :timeout)
+      input = {**request.except(:timeout), deadline: ModernTreasury::Util.monotonic_secs + timeout}
+
+      if send_retry_header
+        headers["x-stainless-retry-count"] = retry_count.to_s
+      end
+
+      begin
+        status, response, stream = @requester.execute(input)
+      rescue ModernTreasury::APIConnectionError => e
+        status = e
+      end
+
+      case status
+      in ..299
+        [status, response, stream]
+      in 300..399 if redirect_count >= self.class::MAX_REDIRECTS
+        self.class.reap_connection!(status, stream: stream)
+
+        message = "Failed to complete the request within #{self.class::MAX_REDIRECTS} redirects."
+        raise ModernTreasury::APIConnectionError.new(url: url, message: message)
+      in 300..399
+        self.class.reap_connection!(status, stream: stream)
+
+        request = self.class.follow_redirect(request, status: status, response_headers: response)
+        send_request(
+          request,
+          redirect_count: redirect_count + 1,
+          retry_count: retry_count,
+          send_retry_header: send_retry_header
+        )
+      in ModernTreasury::APIConnectionError if retry_count >= max_retries
+        raise status
+      in (400..) if retry_count >= max_retries || !self.class.should_retry?(status, headers: response)
+        decoded = Kernel.then do
+          ModernTreasury::Util.decode_content(response, stream: stream, suppress_error: true)
+        ensure
+          self.class.reap_connection!(status, stream: stream)
+        end
+
+        raise ModernTreasury::APIStatusError.for(
+          url: url,
+          status: status,
+          body: decoded,
+          request: nil,
+          response: response
+        )
+      in (400..) | ModernTreasury::APIConnectionError
+        self.class.reap_connection!(status, stream: stream)
+
+        delay = retry_delay(response, retry_count: retry_count)
+        sleep(delay)
+
+        send_request(
+          request,
+          redirect_count: redirect_count,
+          retry_count: retry_count + 1,
+          send_retry_header: send_retry_header
+        )
+      end
+    end
+
+    # Execute the request specified by `req`. This is the method that all resource
+    #   methods call into.
+    #
+    # @param req [Hash{Symbol=>Object}] .
+    #
+    #   @option req [Symbol] :method
+    #
+    #   @option req [String, Array<String>] :path
+    #
+    #   @option req [Hash{String=>Array<String>, String, nil}, nil] :query
+    #
+    #   @option req [Hash{String=>String, Integer, Array<String, Integer, nil>, nil}, nil] :headers
+    #
+    #   @option req [Object, nil] :body
+    #
+    #   @option req [Symbol, nil] :unwrap
+    #
+    #   @option req [Class, nil] :page
+    #
+    #   @option req [Class, nil] :stream
+    #
+    #   @option req [ModernTreasury::Converter, Class, nil] :model
+    #
+    #   @option req [ModernTreasury::RequestOptions, Hash{Symbol=>Object}, nil] :options
+    #
+    # @raise [ModernTreasury::APIError]
+    # @return [Object]
+    def request(req)
+      self.class.validate!(req)
+      model = req.fetch(:model) { ModernTreasury::Unknown }
+      opts = req[:options].to_h
+      ModernTreasury::RequestOptions.validate!(opts)
+      request = build_request(req.except(:options), opts)
+      url = request.fetch(:url)
+
+      # Don't send the current retry count in the headers if the caller modified the header defaults.
+      send_retry_header = request.fetch(:headers)["x-stainless-retry-count"] == "0"
+      status, response, stream = send_request(
+        request,
+        redirect_count: 0,
+        retry_count: 0,
+        send_retry_header: send_retry_header
+      )
+
+      decoded = ModernTreasury::Util.decode_content(response, stream: stream)
+      case req
+      in { stream: Class => st }
+        st.new(model: model, url: url, status: status, response: response, stream: decoded)
+      in { page: Class => page }
+        page.new(client: self, req: req, headers: response, page_data: decoded)
+      else
+        unwrapped = ModernTreasury::Util.dig(decoded, req[:unwrap])
+        ModernTreasury::Converter.coerce(model, unwrapped)
+      end
+    end
+
+    # @return [String]
+    def inspect
+      # rubocop:disable Layout/LineLength
+      base_url = ModernTreasury::Util.unparse_uri(@base_url)
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} base_url=#{base_url} max_retries=#{@max_retries} timeout=#{@timeout}>"
+      # rubocop:enable Layout/LineLength
+    end
+  end
+end