finch-api 0.1.0.pre.alpha.1

data/lib/finch-api/models/webhook_event.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Models
+    # @abstract
+    #
+    # @example
+    # ```ruby
+    # case webhook_event
+    # in FinchAPI::Models::AccountUpdateEvent
+    #   # ...
+    # in FinchAPI::Models::JobCompletionEvent
+    #   # ...
+    # in FinchAPI::Models::CompanyEvent
+    #   # ...
+    # in FinchAPI::Models::DirectoryEvent
+    #   # ...
+    # in FinchAPI::Models::EmploymentEvent
+    #   # ...
+    # in FinchAPI::Models::IndividualEvent
+    #   # ...
+    # in FinchAPI::Models::PaymentEvent
+    #   # ...
+    # in FinchAPI::Models::PayStatementEvent
+    #   # ...
+    # end
+    # ```
+    class WebhookEvent < FinchAPI::Union
+      discriminator :event_type
+
+      variant -> { FinchAPI::Models::AccountUpdateEvent }
+
+      variant -> { FinchAPI::Models::JobCompletionEvent }
+
+      variant -> { FinchAPI::Models::CompanyEvent }
+
+      variant -> { FinchAPI::Models::DirectoryEvent }
+
+      variant -> { FinchAPI::Models::EmploymentEvent }
+
+      variant -> { FinchAPI::Models::IndividualEvent }
+
+      variant -> { FinchAPI::Models::PaymentEvent }
+
+      variant -> { FinchAPI::Models::PayStatementEvent }
+    end
+  end
+end

data/lib/finch-api/page.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  # @example
+  # ```ruby
+  # if page.has_next?
+  #   page = page.next_page
+  # end
+  # ```
+  #
+  # @example
+  # ```ruby
+  # page.auto_paging_each do |item|
+  # #   item ...
+  # end
+  # ```
+  #
+  # @example
+  # ```ruby
+  # items = page.to_enum.take(2)
+  #
+  # items => Array
+  # ```
+  class Page
+    include FinchAPI::BasePage
+
+    # @return [Array<Object>]
+    attr_accessor :data
+
+    # @return [FinchAPI::Models::Paging]
+    attr_accessor :paging
+
+    # rubocop:disable Lint/UnusedMethodArgument
+    # @private
+    #
+    # @param client [FinchAPI::BaseClient]
+    # @param req [Hash{Symbol=>Object}]
+    # @param headers [Hash{String=>String}, Net::HTTPHeader]
+    # @param unwrapped [Hash{Symbol=>Object}]
+    #
+    def initialize(client:, req:, headers:, unwrapped:)
+      @client = client
+      @req = req
+      model = req.fetch(:model)
+
+      case unwrapped
+      in {data: Array | nil => data}
+        @data = data&.map { model.coerce(_1) }
+      else
+      end
+
+      case unwrapped
+      in {paging: Hash | nil => paging}
+        @paging = FinchAPI::Models::Paging.coerce(paging)
+      else
+      end
+    end
+    # rubocop:enable Lint/UnusedMethodArgument
+
+    # @return [Boolean]
+    #
+    def next_page?
+      paging&.offset.to_i + data.size < paging&.count.to_i
+    end
+
+    # @raise [FinchAPI::HTTP::Error]
+    # @return [FinchAPI::Page]
+    #
+    def next_page
+      unless next_page?
+        raise RuntimeError.new("No more pages available; please check #next_page? before calling #next_page")
+      end
+
+      req = FinchAPI::Util.deep_merge(@req, {query: {offset: paging&.offset.to_i + data.size}})
+      @client.request(req)
+    end
+
+    # @param blk [Proc]
+    #
+    def auto_paging_each(&blk)
+      unless block_given?
+        raise ArgumentError.new("A block must be given to #auto_paging_each")
+      end
+      page = self
+      loop do
+        page.data&.each { blk.call(_1) }
+        break unless page.next_page?
+        page = page.next_page
+      end
+    end
+
+    # @return [String]
+    #
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)} data=#{data.inspect} paging=#{paging.inspect}>"
+    end
+  end
+end

data/lib/finch-api/pooled_net_requester.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  # @private
+  #
+  class PooledNetRequester
+    class << self
+      # @private
+      #
+      # @param url [URI::Generic]
+      #
+      # @return [Net::HTTP]
+      #
+      def connect(url)
+        port =
+          case [url.port, url.scheme]
+          in [Integer, _]
+            url.port
+          in [nil, "http" | "ws"]
+            Net::HTTP.http_default_port
+          in [nil, "https" | "wss"]
+            Net::HTTP.https_default_port
+          end
+
+        Net::HTTP.new(url.host, port).tap do
+          _1.use_ssl = %w[https wss].include?(url.scheme)
+          _1.max_retries = 0
+        end
+      end
+
+      # @private
+      #
+      # @param conn [Net::HTTP]
+      # @param deadline [Float]
+      #
+      def calibrate_socket_timeout(conn, deadline)
+        timeout = deadline - FinchAPI::Util.monotonic_secs
+        conn.open_timeout = conn.read_timeout = conn.write_timeout = conn.continue_timeout = timeout
+      end
+
+      # @private
+      #
+      # @param request [Hash{Symbol=>Object}] .
+      #
+      #   @option request [Symbol] :method
+      #
+      #   @option request [URI::Generic] :url
+      #
+      #   @option request [Hash{String=>String}] :headers
+      #
+      # @return [Net::HTTPGenericRequest]
+      #
+      def build_request(request)
+        method, url, headers, body = request.fetch_values(:method, :url, :headers, :body)
+        req = Net::HTTPGenericRequest.new(
+          method.to_s.upcase,
+          !body.nil?,
+          method != :head,
+          url.to_s
+        )
+
+        headers.each { req[_1] = _2 }
+
+        case body
+        in nil
+        in String
+          req.body = body
+        in StringIO
+          req.body = body.string
+        in IO
+          body.rewind
+          req.body_stream = body
+        end
+
+        req
+      end
+    end
+
+    # @private
+    #
+    # @param url [URI::Generic]
+    # @param blk [Proc]
+    #
+    private def with_pool(url, &blk)
+      origin = FinchAPI::Util.uri_origin(url)
+      th = Thread.current
+      key = :"#{object_id}-#{self.class.name}-connection_in_use_for_#{origin}"
+
+      if th[key]
+        tap do
+          conn = self.class.connect(url)
+          return blk.call(conn)
+        ensure
+          conn.finish if conn&.started?
+        end
+      end
+
+      pool =
+        @mutex.synchronize do
+          @pools[origin] ||= ConnectionPool.new(size: Etc.nprocessors) do
+            self.class.connect(url)
+          end
+        end
+
+      pool.with do |conn|
+        th[key] = true
+        blk.call(conn)
+      ensure
+        th[key] = nil
+      end
+    end
+
+    # @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 [Float] :deadline
+    #
+    # @return [Array(Net::HTTPResponse, Enumerable)]
+    #
+    def execute(request)
+      url, deadline = request.fetch_values(:url, :deadline)
+      req = self.class.build_request(request)
+
+      eof = false
+      finished = false
+      enum = Enumerator.new do |y|
+        with_pool(url) do |conn|
+          next if finished
+
+          self.class.calibrate_socket_timeout(conn, deadline)
+          conn.start unless conn.started?
+
+          self.class.calibrate_socket_timeout(conn, deadline)
+          conn.request(req) do |rsp|
+            y << [conn, rsp]
+            break if finished
+
+            rsp.read_body do |bytes|
+              y << bytes
+              break if finished
+
+              self.class.calibrate_socket_timeout(conn, deadline)
+            end
+            eof = true
+          end
+        end
+      end
+
+      conn, response = enum.next
+      body = FinchAPI::Util.fused_enum(enum) do
+        finished = true
+        tap do
+          enum.next
+        rescue StopIteration
+        end
+        conn.finish if !eof && conn&.started?
+      end
+      [response, (response.body = body)]
+    end
+
+    def initialize
+      @mutex = Mutex.new
+      @pools = {}
+    end
+  end
+end

data/lib/finch-api/request_options.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  # @private
+  #
+  # @abstract
+  #
+  module RequestParameters
+    # @!parse
+    #   # Options to specify HTTP behaviour for this request.
+    #   # @return [FinchAPI::RequestOptions, Hash{Symbol=>Object}]
+    #   attr_accessor :request_options
+
+    # @param mod [Module]
+    #
+    def self.included(mod)
+      return unless mod <= FinchAPI::BaseModel
+
+      mod.extend(FinchAPI::RequestParameters::Converter)
+      mod.optional(:request_options, FinchAPI::RequestOptions)
+    end
+
+    # @private
+    #
+    module Converter
+      # @private
+      #
+      # @param params [Object]
+      #
+      # @return [Array(Object, Hash{Symbol=>Object})]
+      #
+      def dump_request(params)
+        case (dumped = dump(params))
+        in Hash
+          [dumped.except(:request_options), dumped[:request_options]]
+        else
+          [dumped, nil]
+        end
+      end
+    end
+  end
+
+  # Specify HTTP behaviour to use for a specific request. These options supplement
+  #   or override those provided at the client level.
+  #
+  #   When making a request, you can pass an actual {RequestOptions} instance, or
+  #   simply pass a Hash with symbol keys matching the attributes on this class.
+  class RequestOptions < FinchAPI::BaseModel
+    # @private
+    #
+    # @param opts [FinchAPI::RequestOptions, Hash{Symbol=>Object}]
+    #
+    # @raise [ArgumentError]
+    #
+    def self.validate!(opts)
+      case opts
+      in FinchAPI::RequestOptions | Hash
+        opts.to_h.each_key do |k|
+          unless fields.include?(k)
+            raise ArgumentError.new("Request `opts` keys must be one of #{fields.keys}, got #{k.inspect}")
+          end
+        end
+      else
+        raise ArgumentError.new("Request `opts` must be a Hash or RequestOptions, got #{opts.inspect}")
+      end
+    end
+
+    # @!attribute idempotency_key
+    #   Idempotency key to send with request and all associated retries. Will only be
+    #     sent for write requests.
+    #
+    #   @return [String, nil]
+    optional :idempotency_key, String
+
+    # @!attribute extra_query
+    #   Extra query params to send with the request. These are `.merge`’d into any
+    #     `query` given at the client level.
+    #
+    #   @return [Hash{String=>Array<String>, String, nil}, nil]
+    optional :extra_query, FinchAPI::HashOf[FinchAPI::ArrayOf[String]]
+
+    # @!attribute extra_headers
+    #   Extra headers to send with the request. These are `.merged`’d into any
+    #     `extra_headers` given at the client level.
+    #
+    #   @return [Hash{String=>String, nil}, nil]
+    optional :extra_headers, FinchAPI::HashOf[String, nil?: true]
+
+    # @!attribute extra_body
+    #   Extra data to send with the request. These are deep merged into any data
+    #     generated as part of the normal request.
+    #
+    #   @return [Hash{Symbol=>Object}, nil]
+    optional :extra_body, FinchAPI::HashOf[FinchAPI::Unknown]
+
+    # @!attribute max_retries
+    #   Maximum number of retries to attempt after a failed initial request.
+    #
+    #   @return [Integer, nil]
+    optional :max_retries, Integer
+
+    # @!attribute timeout
+    #   Request timeout in seconds.
+    #
+    #   @return [Float, nil]
+    optional :timeout, Float
+
+    # @!parse
+    #   # Returns a new instance of RequestOptions.
+    #   #
+    #   # @param values [Hash{Symbol=>Object}]
+    #   #
+    #   def initialize(values = {}) = super
+  end
+end

data/lib/finch-api/resources/access_tokens.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class AccessTokens
+      # Exchange the authorization code for an access token
+      #
+      # @param params [FinchAPI::Models::AccessTokenCreateParams, Hash{Symbol=>Object}] .
+      #
+      #   @option params [String] :code
+      #
+      #   @option params [String] :client_id
+      #
+      #   @option params [String] :client_secret
+      #
+      #   @option params [String] :redirect_uri
+      #
+      #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      #
+      # @return [FinchAPI::Models::CreateAccessTokenResponse]
+      #
+      def create(params)
+        parsed, options = FinchAPI::Models::AccessTokenCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "auth/token",
+          body: parsed,
+          model: FinchAPI::Models::CreateAccessTokenResponse,
+          options: options
+        )
+      end
+
+      # @param client [FinchAPI::Client]
+      #
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/finch-api/resources/account.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Account
+      # Disconnect one or more `access_token`s from your application.
+      #
+      # @param params [FinchAPI::Models::AccountDisconnectParams, Hash{Symbol=>Object}] .
+      #
+      #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      #
+      # @return [FinchAPI::Models::DisconnectResponse]
+      #
+      def disconnect(params = {})
+        @client.request(
+          method: :post,
+          path: "disconnect",
+          model: FinchAPI::Models::DisconnectResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Read account information associated with an `access_token`
+      #
+      # @param params [FinchAPI::Models::AccountIntrospectParams, Hash{Symbol=>Object}] .
+      #
+      #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      #
+      # @return [FinchAPI::Models::Introspection]
+      #
+      def introspect(params = {})
+        @client.request(
+          method: :get,
+          path: "introspect",
+          model: FinchAPI::Models::Introspection,
+          options: params[:request_options]
+        )
+      end
+
+      # @param client [FinchAPI::Client]
+      #
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/finch-api/resources/connect/sessions.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Connect
+      class Sessions
+        # Create a new connect session for an employer
+        #
+        # @param params [FinchAPI::Models::Connect::SessionNewParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [String] :customer_id
+        #
+        #   @option params [String] :customer_name
+        #
+        #   @option params [Array<Symbol, FinchAPI::Models::Connect::SessionNewParams::Product>] :products
+        #
+        #   @option params [String, nil] :customer_email
+        #
+        #   @option params [FinchAPI::Models::Connect::SessionNewParams::Integration, nil] :integration
+        #
+        #   @option params [Boolean, nil] :manual
+        #
+        #   @option params [Float, nil] :minutes_to_expire The number of minutes until the session expires (defaults to 43,200, which is 30
+        #     days)
+        #
+        #   @option params [String, nil] :redirect_uri
+        #
+        #   @option params [Symbol, FinchAPI::Models::Connect::SessionNewParams::Sandbox, nil] :sandbox
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::Connect::SessionNewResponse]
+        #
+        def new(params)
+          parsed, options = FinchAPI::Models::Connect::SessionNewParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "connect/sessions",
+            body: parsed,
+            model: FinchAPI::Models::Connect::SessionNewResponse,
+            options: options
+          )
+        end
+
+        # Create a new Connect session for reauthenticating an existing connection
+        #
+        # @param params [FinchAPI::Models::Connect::SessionReauthenticateParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [String] :connection_id The ID of the existing connection to reauthenticate
+        #
+        #   @option params [Integer, nil] :minutes_to_expire The number of minutes until the session expires (defaults to 43,200, which is 30
+        #     days)
+        #
+        #   @option params [Array<Symbol, FinchAPI::Models::Connect::SessionReauthenticateParams::Product>, nil] :products The products to request access to (optional for reauthentication)
+        #
+        #   @option params [String, nil] :redirect_uri The URI to redirect to after the Connect flow is completed
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::Connect::SessionReauthenticateResponse]
+        #
+        def reauthenticate(params)
+          parsed, options = FinchAPI::Models::Connect::SessionReauthenticateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "connect/sessions/reauthenticate",
+            body: parsed,
+            model: FinchAPI::Models::Connect::SessionReauthenticateResponse,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/connect.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Connect
+      # @return [FinchAPI::Resources::Connect::Sessions]
+      attr_reader :sessions
+
+      # @param client [FinchAPI::Client]
+      #
+      def initialize(client:)
+        @client = client
+        @sessions = FinchAPI::Resources::Connect::Sessions.new(client: client)
+      end
+    end
+  end
+end