finch-api 0.1.0.pre.alpha.1 → 0.1.0.pre.alpha.3

data/lib/finch-api/models/sandbox/payment_create_params.rb

@@ -243,28 +243,10 @@ module FinchAPI
               end
             end
 
-            # @abstract
-            #
             # The type of earning.
-            #
-            # @example
-            # ```ruby
-            # case type
-            # in :salary
-            #   # ...
-            # in :wage
-            #   # ...
-            # in :reimbursement
-            #   # ...
-            # in :overtime
-            #   # ...
-            # in :severance
-            #   # ...
-            # in ...
-            #   #...
-            # end
-            # ```
-            class Type < FinchAPI::Enum
+            module Type
+              extend FinchAPI::Enum
+
               SALARY = :salary
               WAGE = :wage
               REIMBURSEMENT = :reimbursement
@@ -283,7 +265,6 @@ module FinchAPI
 
               # @!parse
               #   # @return [Array<Symbol>]
-              #   #
               #   def self.values; end
             end
           end
@@ -463,20 +444,10 @@ module FinchAPI
             end
           end
 
-          # @abstract
-          #
           # The payment method.
-          #
-          # @example
-          # ```ruby
-          # case payment_method
-          # in :check
-          #   # ...
-          # in :direct_deposit
-          #   # ...
-          # end
-          # ```
-          class PaymentMethod < FinchAPI::Enum
+          module PaymentMethod
+            extend FinchAPI::Enum
+
             CHECK = :check
             DIRECT_DEPOSIT = :direct_deposit
 
@@ -484,7 +455,6 @@ module FinchAPI
 
             # @!parse
             #   # @return [Array<Symbol>]
-            #   #
             #   def self.values; end
           end
 
@@ -580,24 +550,10 @@ module FinchAPI
               end
             end
 
-            # @abstract
-            #
             # The type of taxes.
-            #
-            # @example
-            # ```ruby
-            # case type
-            # in :state
-            #   # ...
-            # in :federal
-            #   # ...
-            # in :local
-            #   # ...
-            # in :fica
-            #   # ...
-            # end
-            # ```
-            class Type < FinchAPI::Enum
+            module Type
+              extend FinchAPI::Enum
+
               STATE = :state
               FEDERAL = :federal
               LOCAL = :local
@@ -607,27 +563,14 @@ module FinchAPI
 
               # @!parse
               #   # @return [Array<Symbol>]
-              #   #
               #   def self.values; end
             end
           end
 
-          # @abstract
-          #
           # The type of the payment associated with the pay statement.
-          #
-          # @example
-          # ```ruby
-          # case type
-          # in :regular_payroll
-          #   # ...
-          # in :off_cycle_payroll
-          #   # ...
-          # in :one_time_payment
-          #   # ...
-          # end
-          # ```
-          class Type < FinchAPI::Enum
+          module Type
+            extend FinchAPI::Enum
+
             REGULAR_PAYROLL = :regular_payroll
             OFF_CYCLE_PAYROLL = :off_cycle_payroll
             ONE_TIME_PAYMENT = :one_time_payment
@@ -636,7 +579,6 @@ module FinchAPI
 
             # @!parse
             #   # @return [Array<Symbol>]
-            #   #
             #   def self.values; end
           end
         end

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

@@ -2,37 +2,16 @@
 
 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
+    module WebhookEvent
+      extend FinchAPI::Union
+
       discriminator :event_type
 
-      variant -> { FinchAPI::Models::AccountUpdateEvent }
+      variant :"account.updated", -> { FinchAPI::Models::AccountUpdateEvent }
 
-      variant -> { FinchAPI::Models::JobCompletionEvent }
+      variant :"company.updated", -> { FinchAPI::Models::CompanyEvent }
 
-      variant -> { FinchAPI::Models::CompanyEvent }
+      variant -> { FinchAPI::Models::JobCompletionEvent }
 
       variant -> { FinchAPI::Models::DirectoryEvent }
 
@@ -43,6 +22,10 @@ module FinchAPI
       variant -> { FinchAPI::Models::PaymentEvent }
 
       variant -> { FinchAPI::Models::PayStatementEvent }
+
+      # @!parse
+      #   # @return [Array(FinchAPI::Models::AccountUpdateEvent, FinchAPI::Models::CompanyEvent, FinchAPI::Models::JobCompletionEvent, FinchAPI::Models::DirectoryEvent, FinchAPI::Models::EmploymentEvent, FinchAPI::Models::IndividualEvent, FinchAPI::Models::PaymentEvent, FinchAPI::Models::PayStatementEvent)]
+      #   def self.variants; end
     end
   end
 end

data/lib/finch-api/page.rb

@@ -2,84 +2,79 @@
 
 module FinchAPI
   # @example
-  # ```ruby
-  # if page.has_next?
-  #   page = page.next_page
-  # end
-  # ```
+  #   if page.has_next?
+  #     page = page.next_page
+  #   end
   #
   # @example
-  # ```ruby
-  # page.auto_paging_each do |item|
-  # #   item ...
-  # end
-  # ```
+  #   page.auto_paging_each do |item|
+  #     puts(item)
+  #   end
   #
   # @example
-  # ```ruby
-  # items = page.to_enum.take(2)
+  #   items =
+  #     page
+  #     .to_enum
+  #     .lazy
+  #     .select { _1.object_id.even? }
+  #     .map(&:itself)
+  #     .take(2)
+  #     .to_a
   #
-  # items => Array
-  # ```
+  #   items => Array
   class Page
     include FinchAPI::BasePage
 
-    # @return [Array<Object>]
+    # @return [Array<Object>, nil]
     attr_accessor :data
 
     # @return [FinchAPI::Models::Paging]
     attr_accessor :paging
 
-    # rubocop:disable Lint/UnusedMethodArgument
-    # @private
+    # @api 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
+    # @param page_data [Hash{Symbol=>Object}]
+    def initialize(client:, req:, headers:, page_data:)
+      super
       model = req.fetch(:model)
 
-      case unwrapped
+      case page_data
       in {data: Array | nil => data}
-        @data = data&.map { model.coerce(_1) }
+        @data = data&.map { FinchAPI::Converter.coerce(model, _1) }
       else
       end
 
-      case unwrapped
+      case page_data
       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
+      paging&.offset.to_i + data.to_a.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")
+        message = "No more pages available. Please check #next_page? before calling ##{__method__}"
+        raise RuntimeError.new(message)
       end
 
-      req = FinchAPI::Util.deep_merge(@req, {query: {offset: paging&.offset.to_i + data.size}})
+      req = FinchAPI::Util.deep_merge(@req, {query: {offset: paging&.offset.to_i + data.to_a.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")
+        raise ArgumentError.new("A block must be given to ##{__method__}")
       end
       page = self
       loop do
@@ -90,7 +85,6 @@ module FinchAPI
     end
 
     # @return [String]
-    #
     def inspect
       "#<#{self.class}:0x#{object_id.to_s(16)} data=#{data.inspect} paging=#{paging.inspect}>"
     end

data/lib/finch-api/pooled_net_requester.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
 module FinchAPI
-  # @private
-  #
+  # @api private
   class PooledNetRequester
+    # from the golang stdlib
+    #   https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
+    KEEP_ALIVE_TIMEOUT = 30
+
     class << self
-      # @private
+      # @api private
       #
       # @param url [URI::Generic]
       #
       # @return [Net::HTTP]
-      #
       def connect(url)
         port =
           case [url.port, url.scheme]
@@ -28,17 +30,16 @@ module FinchAPI
         end
       end
 
-      # @private
+      # @api 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
+      # @api private
       #
       # @param request [Hash{Symbol=>Object}] .
       #
@@ -48,9 +49,11 @@ module FinchAPI
       #
       #   @option request [Hash{String=>String}] :headers
       #
-      # @return [Net::HTTPGenericRequest]
+      # @param blk [Proc]
       #
-      def build_request(request)
+      # @yieldparam [String]
+      # @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,
@@ -63,54 +66,44 @@ module FinchAPI
 
         case body
         in nil
+          nil
         in String
-          req.body = body
+          req["content-length"] ||= body.bytesize.to_s unless req["transfer-encoding"]
+          req.body_stream = FinchAPI::Util::ReadIOAdapter.new(body, &)
         in StringIO
-          req.body = body.string
-        in IO
-          body.rewind
-          req.body_stream = body
+          req["content-length"] ||= body.size.to_s unless req["transfer-encoding"]
+          req.body_stream = FinchAPI::Util::ReadIOAdapter.new(body, &)
+        in IO | Enumerator
+          req["transfer-encoding"] ||= "chunked" unless req["content-length"]
+          req.body_stream = FinchAPI::Util::ReadIOAdapter.new(body, &)
         end
 
         req
       end
     end
 
-    # @private
+    # @api private
     #
     # @param url [URI::Generic]
+    # @param deadline [Float]
     # @param blk [Proc]
     #
-    private def with_pool(url, &blk)
+    # @raise [Timeout::Error]
+    # @yieldparam [Net::HTTP]
+    private def with_pool(url, deadline:, &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
-
+      timeout = deadline - FinchAPI::Util.monotonic_secs
       pool =
         @mutex.synchronize do
-          @pools[origin] ||= ConnectionPool.new(size: Etc.nprocessors) do
+          @pools[origin] ||= ConnectionPool.new(size: @size) do
             self.class.connect(url)
           end
         end
 
-      pool.with do |conn|
-        th[key] = true
-        blk.call(conn)
-      ensure
-        th[key] = nil
-      end
+      pool.with(timeout: timeout, &blk)
     end
 
-    # @private
+    # @api private
     #
     # @param request [Hash{Symbol=>Object}] .
     #
@@ -124,24 +117,29 @@ module FinchAPI
     #
     #   @option request [Float] :deadline
     #
-    # @return [Array(Net::HTTPResponse, Enumerable)]
-    #
+    # @return [Array(Integer, 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|
+        with_pool(url, deadline: deadline) do |conn|
           next if finished
 
+          req = self.class.build_request(request) do
+            self.class.calibrate_socket_timeout(conn, deadline)
+          end
+
           self.class.calibrate_socket_timeout(conn, deadline)
-          conn.start unless conn.started?
+          unless conn.started?
+            conn.keep_alive_timeout = self.class::KEEP_ALIVE_TIMEOUT
+            conn.start
+          end
 
           self.class.calibrate_socket_timeout(conn, deadline)
           conn.request(req) do |rsp|
-            y << [conn, rsp]
+            y << [conn, req, rsp]
             break if finished
 
             rsp.read_body do |bytes|
@@ -153,22 +151,29 @@ module FinchAPI
             eof = true
           end
         end
+      rescue Timeout::Error
+        raise FinchAPI::APITimeoutError
       end
 
-      conn, response = enum.next
-      body = FinchAPI::Util.fused_enum(enum) do
+      conn, _, response = enum.next
+      body = FinchAPI::Util.fused_enum(enum, external: true) do
         finished = true
         tap do
           enum.next
         rescue StopIteration
+          nil
         end
         conn.finish if !eof && conn&.started?
       end
-      [response, (response.body = body)]
+      [Integer(response.code), response, (response.body = body)]
     end
 
-    def initialize
+    # @api private
+    #
+    # @param size [Integer]
+    def initialize(size: Etc.nprocessors)
       @mutex = Mutex.new
+      @size = size
       @pools = {}
     end
   end

data/lib/finch-api/request_options.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
 module FinchAPI
-  # @private
-  #
-  # @abstract
-  #
+  # @api private
   module RequestParameters
     # @!parse
     #   # Options to specify HTTP behaviour for this request.
@@ -12,7 +9,6 @@ module FinchAPI
     #   attr_accessor :request_options
 
     # @param mod [Module]
-    #
     def self.included(mod)
       return unless mod <= FinchAPI::BaseModel
 
@@ -20,15 +16,13 @@ module FinchAPI
       mod.optional(:request_options, FinchAPI::RequestOptions)
     end
 
-    # @private
-    #
+    # @api private
     module Converter
-      # @private
+      # @api private
       #
       # @param params [Object]
       #
       # @return [Array(Object, Hash{Symbol=>Object})]
-      #
       def dump_request(params)
         case (dumped = dump(params))
         in Hash
@@ -46,12 +40,11 @@ module FinchAPI
   #   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
+    # @api private
     #
     # @param opts [FinchAPI::RequestOptions, Hash{Symbol=>Object}]
     #
     # @raise [ArgumentError]
-    #
     def self.validate!(opts)
       case opts
       in FinchAPI::RequestOptions | Hash
@@ -90,7 +83,7 @@ module FinchAPI
     #   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]
+    #   @return [Object, nil]
     optional :extra_body, FinchAPI::HashOf[FinchAPI::Unknown]
 
     # @!attribute max_retries

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

@@ -18,7 +18,6 @@ module FinchAPI
       #   @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(
@@ -31,7 +30,6 @@ module FinchAPI
       end
 
       # @param client [FinchAPI::Client]
-      #
       def initialize(client:)
         @client = client
       end

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

@@ -10,7 +10,6 @@ module FinchAPI
       #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [FinchAPI::Models::DisconnectResponse]
-      #
       def disconnect(params = {})
         @client.request(
           method: :post,
@@ -27,7 +26,6 @@ module FinchAPI
       #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
       #
       # @return [FinchAPI::Models::Introspection]
-      #
       def introspect(params = {})
         @client.request(
           method: :get,
@@ -38,7 +36,6 @@ module FinchAPI
       end
 
       # @param client [FinchAPI::Client]
-      #
       def initialize(client:)
         @client = client
       end

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

@@ -30,7 +30,6 @@ module FinchAPI
         #   @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(
@@ -58,7 +57,6 @@ module FinchAPI
         #   @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(
@@ -71,7 +69,6 @@ module FinchAPI
         end
 
         # @param client [FinchAPI::Client]
-        #
         def initialize(client:)
           @client = client
         end

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

@@ -7,7 +7,6 @@ module FinchAPI
       attr_reader :sessions
 
       # @param client [FinchAPI::Client]
-      #
       def initialize(client:)
         @client = client
         @sessions = FinchAPI::Resources::Connect::Sessions.new(client: client)

data/lib/finch-api/resources/hris/benefits/individuals.rb

@@ -19,7 +19,6 @@ module FinchAPI
           #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
           #
           # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::Benefits::EnrolledIndividual>]
-          #
           def enroll_many(benefit_id, params = {})
             parsed, options = FinchAPI::Models::HRIS::Benefits::IndividualEnrollManyParams.dump_request(params)
             @client.request(
@@ -41,7 +40,6 @@ module FinchAPI
           #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
           #
           # @return [FinchAPI::Models::HRIS::Benefits::IndividualEnrolledIDsResponse]
-          #
           def enrolled_ids(benefit_id, params = {})
             @client.request(
               method: :get,
@@ -63,9 +61,9 @@ module FinchAPI
           #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
           #
           # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::Benefits::IndividualBenefit>]
-          #
           def retrieve_many_benefits(benefit_id, params = {})
-            parsed, options = FinchAPI::Models::HRIS::Benefits::IndividualRetrieveManyBenefitsParams.dump_request(params)
+            parsed, options =
+              FinchAPI::Models::HRIS::Benefits::IndividualRetrieveManyBenefitsParams.dump_request(params)
             @client.request(
               method: :get,
               path: ["employer/benefits/%0s/individuals", benefit_id],
@@ -87,7 +85,6 @@ module FinchAPI
           #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
           #
           # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::Benefits::UnenrolledIndividual>]
-          #
           def unenroll_many(benefit_id, params = {})
             parsed, options = FinchAPI::Models::HRIS::Benefits::IndividualUnenrollManyParams.dump_request(params)
             @client.request(
@@ -101,7 +98,6 @@ module FinchAPI
           end
 
           # @param client [FinchAPI::Client]
-          #
           def initialize(client:)
             @client = client
           end