finch-api 0.1.0.pre.alpha.5 → 0.1.0.pre.alpha.14

data/lib/finch_api/request_options.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  # 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::Internal::Type::BaseModel
+    # @api 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::Internal::Type::HashOf[FinchAPI::Internal::Type::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::Internal::Type::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 [Object, nil]
+    optional :extra_body, FinchAPI::Internal::Type::HashOf[FinchAPI::Internal::Type::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
+
+    # @!method initialize(values = {})
+    #   Returns a new instance of RequestOptions.
+    #
+    #   @param values [Hash{Symbol=>Object}]
+  end
+end

data/lib/finch_api/resources/access_tokens.rb

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

data/lib/finch_api/resources/account.rb

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

data/lib/finch_api/resources/connect/sessions.rb

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

data/lib/finch_api/resources/connect.rb

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

data/lib/finch_api/resources/hris/benefits/individuals.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class Benefits
+        class Individuals
+          # Enroll an individual into a deduction or contribution. This is an overwrite
+          # operation. If the employee is already enrolled, the enrollment amounts will be
+          # adjusted. Making the same request multiple times will not create new
+          # enrollments, but will continue to set the state of the existing enrollment.
+          #
+          # @overload enroll_many(benefit_id, individuals: nil, request_options: {})
+          #
+          # @param benefit_id [String]
+          #
+          # @param individuals [Array<FinchAPI::HRIS::Benefits::IndividualEnrollManyParams::Individual>] Array of the individual_id to enroll and a configuration object.
+          #
+          # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [FinchAPI::HRIS::Benefits::EnrolledIndividualBenefitResponse]
+          #
+          # @see FinchAPI::Models::HRIS::Benefits::IndividualEnrollManyParams
+          def enroll_many(benefit_id, params = {})
+            parsed, options = FinchAPI::HRIS::Benefits::IndividualEnrollManyParams.dump_request(params)
+            @client.request(
+              method: :post,
+              path: ["employer/benefits/%1$s/individuals", benefit_id],
+              body: parsed[:individuals],
+              model: FinchAPI::HRIS::Benefits::EnrolledIndividualBenefitResponse,
+              options: options
+            )
+          end
+
+          # Lists individuals currently enrolled in a given deduction.
+          #
+          # @overload enrolled_ids(benefit_id, request_options: {})
+          #
+          # @param benefit_id [String]
+          # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [FinchAPI::Models::HRIS::Benefits::IndividualEnrolledIDsResponse]
+          #
+          # @see FinchAPI::Models::HRIS::Benefits::IndividualEnrolledIDsParams
+          def enrolled_ids(benefit_id, params = {})
+            @client.request(
+              method: :get,
+              path: ["employer/benefits/%1$s/enrolled", benefit_id],
+              model: FinchAPI::Models::HRIS::Benefits::IndividualEnrolledIDsResponse,
+              options: params[:request_options]
+            )
+          end
+
+          # Some parameter documentations has been truncated, see
+          # {FinchAPI::Models::HRIS::Benefits::IndividualRetrieveManyBenefitsParams} for
+          # more details.
+          #
+          # Get enrollment information for the given individuals.
+          #
+          # @overload retrieve_many_benefits(benefit_id, individual_ids: nil, request_options: {})
+          #
+          # @param benefit_id [String]
+          #
+          # @param individual_ids [String] comma-delimited list of stable Finch uuids for each individual. If empty, defaul
+          #
+          # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [FinchAPI::Internal::SinglePage<FinchAPI::HRIS::Benefits::IndividualBenefit>]
+          #
+          # @see FinchAPI::Models::HRIS::Benefits::IndividualRetrieveManyBenefitsParams
+          def retrieve_many_benefits(benefit_id, params = {})
+            parsed, options = FinchAPI::HRIS::Benefits::IndividualRetrieveManyBenefitsParams.dump_request(params)
+            @client.request(
+              method: :get,
+              path: ["employer/benefits/%1$s/individuals", benefit_id],
+              query: parsed,
+              page: FinchAPI::Internal::SinglePage,
+              model: FinchAPI::HRIS::Benefits::IndividualBenefit,
+              options: options
+            )
+          end
+
+          # Unenroll individuals from a deduction or contribution
+          #
+          # @overload unenroll_many(benefit_id, individual_ids: nil, request_options: {})
+          #
+          # @param benefit_id [String]
+          #
+          # @param individual_ids [Array<String>] Array of individual_ids to unenroll.
+          #
+          # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [FinchAPI::HRIS::Benefits::UnenrolledIndividualBenefitResponse]
+          #
+          # @see FinchAPI::Models::HRIS::Benefits::IndividualUnenrollManyParams
+          def unenroll_many(benefit_id, params = {})
+            parsed, options = FinchAPI::HRIS::Benefits::IndividualUnenrollManyParams.dump_request(params)
+            @client.request(
+              method: :delete,
+              path: ["employer/benefits/%1$s/individuals", benefit_id],
+              body: parsed,
+              model: FinchAPI::HRIS::Benefits::UnenrolledIndividualBenefitResponse,
+              options: options
+            )
+          end
+
+          # @api private
+          #
+          # @param client [FinchAPI::Client]
+          def initialize(client:)
+            @client = client
+          end
+        end
+      end
+    end
+  end
+end

data/lib/finch_api/resources/hris/benefits.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class Benefits
+        # @return [FinchAPI::Resources::HRIS::Benefits::Individuals]
+        attr_reader :individuals
+
+        # Some parameter documentations has been truncated, see
+        # {FinchAPI::Models::HRIS::BenefitCreateParams} for more details.
+        #
+        # Creates a new company-wide deduction or contribution. Please use the
+        # `/providers` endpoint to view available types for each provider.
+        #
+        # @overload create(company_contribution: nil, description: nil, frequency: nil, type: nil, request_options: {})
+        #
+        # @param company_contribution [FinchAPI::HRIS::BenefitCreateParams::CompanyContribution, nil] The company match for this benefit.
+        #
+        # @param description [String] Name of the benefit as it appears in the provider and pay statements. Recommend
+        #
+        # @param frequency [Symbol, FinchAPI::HRIS::BenefitFrequency, nil] The frequency of the benefit deduction/contribution.
+        #
+        # @param type [Symbol, FinchAPI::HRIS::BenefitType, nil] Type of benefit.
+        #
+        # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [FinchAPI::HRIS::CreateCompanyBenefitsResponse]
+        #
+        # @see FinchAPI::Models::HRIS::BenefitCreateParams
+        def create(params = {})
+          parsed, options = FinchAPI::HRIS::BenefitCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "employer/benefits",
+            body: parsed,
+            model: FinchAPI::HRIS::CreateCompanyBenefitsResponse,
+            options: options
+          )
+        end
+
+        # Lists deductions and contributions information for a given item
+        #
+        # @overload retrieve(benefit_id, request_options: {})
+        #
+        # @param benefit_id [String]
+        # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [FinchAPI::HRIS::CompanyBenefit]
+        #
+        # @see FinchAPI::Models::HRIS::BenefitRetrieveParams
+        def retrieve(benefit_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["employer/benefits/%1$s", benefit_id],
+            model: FinchAPI::HRIS::CompanyBenefit,
+            options: params[:request_options]
+          )
+        end
+
+        # Updates an existing company-wide deduction or contribution
+        #
+        # @overload update(benefit_id, description: nil, request_options: {})
+        #
+        # @param benefit_id [String]
+        #
+        # @param description [String] Updated name or description.
+        #
+        # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [FinchAPI::HRIS::UpdateCompanyBenefitResponse]
+        #
+        # @see FinchAPI::Models::HRIS::BenefitUpdateParams
+        def update(benefit_id, params = {})
+          parsed, options = FinchAPI::HRIS::BenefitUpdateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["employer/benefits/%1$s", benefit_id],
+            body: parsed,
+            model: FinchAPI::HRIS::UpdateCompanyBenefitResponse,
+            options: options
+          )
+        end
+
+        # List all company-wide deductions and contributions.
+        #
+        # @overload list(request_options: {})
+        #
+        # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [FinchAPI::Internal::SinglePage<FinchAPI::HRIS::CompanyBenefit>]
+        #
+        # @see FinchAPI::Models::HRIS::BenefitListParams
+        def list(params = {})
+          @client.request(
+            method: :get,
+            path: "employer/benefits",
+            page: FinchAPI::Internal::SinglePage,
+            model: FinchAPI::HRIS::CompanyBenefit,
+            options: params[:request_options]
+          )
+        end
+
+        # Get deductions metadata
+        #
+        # @overload list_supported_benefits(request_options: {})
+        #
+        # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [FinchAPI::Internal::SinglePage<FinchAPI::Models::HRIS::BenefitListSupportedBenefitsResponse>]
+        #
+        # @see FinchAPI::Models::HRIS::BenefitListSupportedBenefitsParams
+        def list_supported_benefits(params = {})
+          @client.request(
+            method: :get,
+            path: "employer/benefits/meta",
+            page: FinchAPI::Internal::SinglePage,
+            model: FinchAPI::Models::HRIS::BenefitListSupportedBenefitsResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # @api private
+        #
+        # @param client [FinchAPI::Client]
+        def initialize(client:)
+          @client = client
+          @individuals = FinchAPI::Resources::HRIS::Benefits::Individuals.new(client: client)
+        end
+      end
+    end
+  end
+end

data/lib/finch_api/resources/hris/company/pay_statement_item/rules.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class Company
+        class PayStatementItem
+          class Rules
+            # **Beta:** this endpoint currently serves employers onboarded after March 4th and
+            # historical support will be added soon Custom rules can be created to associate
+            # specific attributes to pay statement items depending on the use case. For
+            # example, pay statement items that meet certain conditions can be labeled as a
+            # pre-tax 401k. This metadata can be retrieved where pay statement item
+            # information is available.
+            #
+            # @overload create(attributes: nil, conditions: nil, effective_end_date: nil, effective_start_date: nil, entity_type: nil, request_options: {})
+            #
+            # @param attributes [FinchAPI::HRIS::Company::PayStatementItem::RuleCreateParams::Attributes] Specifies the fields to be applied when the condition is met.
+            #
+            # @param conditions [Array<FinchAPI::HRIS::Company::PayStatementItem::RuleCreateParams::Condition>]
+            #
+            # @param effective_end_date [String, nil] Specifies when the rules should stop applying rules based on the date.
+            #
+            # @param effective_start_date [String, nil] Specifies when the rule should begin applying based on the date.
+            #
+            # @param entity_type [Symbol, FinchAPI::HRIS::Company::PayStatementItem::RuleCreateParams::EntityType] The entity type to which the rule is applied.
+            #
+            # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+            #
+            # @return [FinchAPI::Models::HRIS::Company::PayStatementItem::RuleCreateResponse]
+            #
+            # @see FinchAPI::Models::HRIS::Company::PayStatementItem::RuleCreateParams
+            def create(params = {})
+              parsed, options = FinchAPI::HRIS::Company::PayStatementItem::RuleCreateParams.dump_request(params)
+              @client.request(
+                method: :post,
+                path: "employer/pay-statement-item/rule",
+                body: parsed,
+                model: FinchAPI::Models::HRIS::Company::PayStatementItem::RuleCreateResponse,
+                options: options
+              )
+            end
+
+            # **Beta:** this endpoint currently serves employers onboarded after March 4th and
+            # historical support will be added soon Update a rule for a pay statement item.
+            #
+            # @overload update(rule_id, optional_property: nil, request_options: {})
+            #
+            # @param rule_id [String]
+            # @param optional_property [Object]
+            # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+            #
+            # @return [FinchAPI::Models::HRIS::Company::PayStatementItem::RuleUpdateResponse]
+            #
+            # @see FinchAPI::Models::HRIS::Company::PayStatementItem::RuleUpdateParams
+            def update(rule_id, params = {})
+              parsed, options = FinchAPI::HRIS::Company::PayStatementItem::RuleUpdateParams.dump_request(params)
+              @client.request(
+                method: :put,
+                path: ["employer/pay-statement-item/rule/%1$s", rule_id],
+                body: parsed,
+                model: FinchAPI::Models::HRIS::Company::PayStatementItem::RuleUpdateResponse,
+                options: options
+              )
+            end
+
+            # **Beta:** this endpoint currently serves employers onboarded after March 4th and
+            # historical support will be added soon List all rules of a connection account.
+            #
+            # @overload list(request_options: {})
+            #
+            # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+            #
+            # @return [FinchAPI::Internal::ResponsesPage<FinchAPI::Models::HRIS::Company::PayStatementItem::RuleListResponse>]
+            #
+            # @see FinchAPI::Models::HRIS::Company::PayStatementItem::RuleListParams
+            def list(params = {})
+              @client.request(
+                method: :get,
+                path: "employer/pay-statement-item/rule",
+                page: FinchAPI::Internal::ResponsesPage,
+                model: FinchAPI::Models::HRIS::Company::PayStatementItem::RuleListResponse,
+                options: params[:request_options]
+              )
+            end
+
+            # **Beta:** this endpoint currently serves employers onboarded after March 4th and
+            # historical support will be added soon Delete a rule for a pay statement item.
+            #
+            # @overload delete(rule_id, request_options: {})
+            #
+            # @param rule_id [String]
+            # @param request_options [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+            #
+            # @return [FinchAPI::Models::HRIS::Company::PayStatementItem::RuleDeleteResponse]
+            #
+            # @see FinchAPI::Models::HRIS::Company::PayStatementItem::RuleDeleteParams
+            def delete(rule_id, params = {})
+              @client.request(
+                method: :delete,
+                path: ["employer/pay-statement-item/rule/%1$s", rule_id],
+                model: FinchAPI::Models::HRIS::Company::PayStatementItem::RuleDeleteResponse,
+                options: params[:request_options]
+              )
+            end
+
+            # @api private
+            #
+            # @param client [FinchAPI::Client]
+            def initialize(client:)
+              @client = client
+            end
+          end
+        end
+      end
+    end
+  end
+end