finch-api 0.1.0.pre.alpha.1

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

@@ -0,0 +1,112 @@
+# 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.
+          #
+          # @param benefit_id [String]
+          #
+          # @param params [FinchAPI::Models::HRIS::Benefits::IndividualEnrollManyParams, Hash{Symbol=>Object}] .
+          #
+          #   @option params [Array<FinchAPI::Models::HRIS::Benefits::IndividualEnrollManyParams::Individual>] :individuals Array of the individual_id to enroll and a configuration object.
+          #
+          #   @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(
+              method: :post,
+              path: ["employer/benefits/%0s/individuals", benefit_id],
+              body: parsed[:individuals],
+              page: FinchAPI::SinglePage,
+              model: FinchAPI::Models::HRIS::Benefits::EnrolledIndividual,
+              options: options
+            )
+          end
+
+          # Lists individuals currently enrolled in a given deduction.
+          #
+          # @param benefit_id [String]
+          #
+          # @param params [FinchAPI::Models::HRIS::Benefits::IndividualEnrolledIDsParams, Hash{Symbol=>Object}] .
+          #
+          #   @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,
+              path: ["employer/benefits/%0s/enrolled", benefit_id],
+              model: FinchAPI::Models::HRIS::Benefits::IndividualEnrolledIDsResponse,
+              options: params[:request_options]
+            )
+          end
+
+          # Get enrollment information for the given individuals.
+          #
+          # @param benefit_id [String]
+          #
+          # @param params [FinchAPI::Models::HRIS::Benefits::IndividualRetrieveManyBenefitsParams, Hash{Symbol=>Object}] .
+          #
+          #   @option params [String] :individual_ids comma-delimited list of stable Finch uuids for each individual. If empty,
+          #     defaults to all individuals
+          #
+          #   @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)
+            @client.request(
+              method: :get,
+              path: ["employer/benefits/%0s/individuals", benefit_id],
+              query: parsed,
+              page: FinchAPI::SinglePage,
+              model: FinchAPI::Models::HRIS::Benefits::IndividualBenefit,
+              options: options
+            )
+          end
+
+          # Unenroll individuals from a deduction or contribution
+          #
+          # @param benefit_id [String]
+          #
+          # @param params [FinchAPI::Models::HRIS::Benefits::IndividualUnenrollManyParams, Hash{Symbol=>Object}] .
+          #
+          #   @option params [Array<String>] :individual_ids Array of individual_ids to unenroll.
+          #
+          #   @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(
+              method: :delete,
+              path: ["employer/benefits/%0s/individuals", benefit_id],
+              body: parsed,
+              page: FinchAPI::SinglePage,
+              model: FinchAPI::Models::HRIS::Benefits::UnenrolledIndividual,
+              options: options
+            )
+          end
+
+          # @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,125 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class Benefits
+        # @return [FinchAPI::Resources::HRIS::Benefits::Individuals]
+        attr_reader :individuals
+
+        # Creates a new company-wide deduction or contribution. Please use the
+        #   `/providers` endpoint to view available types for each provider.
+        #
+        # @param params [FinchAPI::Models::HRIS::BenefitCreateParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [String] :description Name of the benefit as it appears in the provider and pay statements. Recommend
+        #     limiting this to <30 characters due to limitations in specific providers (e.g.
+        #     Justworks).
+        #
+        #   @option params [Symbol, FinchAPI::Models::HRIS::BenefitFrequency, nil] :frequency
+        #
+        #   @option params [Symbol, FinchAPI::Models::HRIS::BenefitType, nil] :type Type of benefit.
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::HRIS::CreateCompanyBenefitsResponse]
+        #
+        def create(params = {})
+          parsed, options = FinchAPI::Models::HRIS::BenefitCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "employer/benefits",
+            body: parsed,
+            model: FinchAPI::Models::HRIS::CreateCompanyBenefitsResponse,
+            options: options
+          )
+        end
+
+        # Lists deductions and contributions information for a given item
+        #
+        # @param benefit_id [String]
+        #
+        # @param params [FinchAPI::Models::HRIS::BenefitRetrieveParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::HRIS::CompanyBenefit]
+        #
+        def retrieve(benefit_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["employer/benefits/%0s", benefit_id],
+            model: FinchAPI::Models::HRIS::CompanyBenefit,
+            options: params[:request_options]
+          )
+        end
+
+        # Updates an existing company-wide deduction or contribution
+        #
+        # @param benefit_id [String]
+        #
+        # @param params [FinchAPI::Models::HRIS::BenefitUpdateParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [String] :description Updated name or description.
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::HRIS::UpdateCompanyBenefitResponse]
+        #
+        def update(benefit_id, params = {})
+          parsed, options = FinchAPI::Models::HRIS::BenefitUpdateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["employer/benefits/%0s", benefit_id],
+            body: parsed,
+            model: FinchAPI::Models::HRIS::UpdateCompanyBenefitResponse,
+            options: options
+          )
+        end
+
+        # List all company-wide deductions and contributions.
+        #
+        # @param params [FinchAPI::Models::HRIS::BenefitListParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::CompanyBenefit>]
+        #
+        def list(params = {})
+          @client.request(
+            method: :get,
+            path: "employer/benefits",
+            page: FinchAPI::SinglePage,
+            model: FinchAPI::Models::HRIS::CompanyBenefit,
+            options: params[:request_options]
+          )
+        end
+
+        # Get deductions metadata
+        #
+        # @param params [FinchAPI::Models::HRIS::BenefitListSupportedBenefitsParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::SupportedBenefit>]
+        #
+        def list_supported_benefits(params = {})
+          @client.request(
+            method: :get,
+            path: "employer/benefits/meta",
+            page: FinchAPI::SinglePage,
+            model: FinchAPI::Models::HRIS::SupportedBenefit,
+            options: params[:request_options]
+          )
+        end
+
+        # @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.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class Company
+        # Read basic company data
+        #
+        # @param params [FinchAPI::Models::HRIS::CompanyRetrieveParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::HRIS::HRISCompany]
+        #
+        def retrieve(params = {})
+          @client.request(
+            method: :get,
+            path: "employer/company",
+            model: FinchAPI::Models::HRIS::HRISCompany,
+            options: params[:request_options]
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/hris/directory.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class Directory
+        # Read company directory and organization structure
+        #
+        # @param params [FinchAPI::Models::HRIS::DirectoryListParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [Integer] :limit Number of employees to return (defaults to all)
+        #
+        #   @option params [Integer] :offset Index to start from (defaults to 0)
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::IndividualsPage<FinchAPI::Models::HRIS::IndividualInDirectory>]
+        #
+        def list(params = {})
+          parsed, options = FinchAPI::Models::HRIS::DirectoryListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: "employer/directory",
+            query: parsed,
+            page: FinchAPI::IndividualsPage,
+            model: FinchAPI::Models::HRIS::IndividualInDirectory,
+            options: options
+          )
+        end
+
+        # @deprecated use `list` instead
+        #
+        # Read company directory and organization structure
+        #
+        # @param params [FinchAPI::Models::HRIS::DirectoryListIndividualsParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [Integer] :limit Number of employees to return (defaults to all)
+        #
+        #   @option params [Integer] :offset Index to start from (defaults to 0)
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::IndividualsPage<FinchAPI::Models::HRIS::IndividualInDirectory>]
+        #
+        def list_individuals(params = {})
+          parsed, options = FinchAPI::Models::HRIS::DirectoryListIndividualsParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: "employer/directory",
+            query: parsed,
+            page: FinchAPI::IndividualsPage,
+            model: FinchAPI::Models::HRIS::IndividualInDirectory,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/hris/documents.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class Documents
+        # **Beta:** This endpoint is in beta and may change.
+        #   Retrieve a list of company-wide documents.
+        #
+        # @param params [FinchAPI::Models::HRIS::DocumentListParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [Array<String>] :individual_ids Comma-delimited list of stable Finch uuids for each individual. If empty,
+        #     defaults to all individuals
+        #
+        #   @option params [Integer] :limit Number of documents to return (defaults to all)
+        #
+        #   @option params [Integer] :offset Index to start from (defaults to 0)
+        #
+        #   @option params [Array<Symbol, FinchAPI::Models::HRIS::DocumentListParams::Type>] :types Comma-delimited list of document types to filter on. If empty, defaults to all
+        #     types
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::HRIS::DocumentListResponse]
+        #
+        def list(params = {})
+          parsed, options = FinchAPI::Models::HRIS::DocumentListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: "employer/documents",
+            query: parsed,
+            model: FinchAPI::Models::HRIS::DocumentListResponse,
+            options: options
+          )
+        end
+
+        # **Beta:** This endpoint is in beta and may change.
+        #   Retrieve details of a specific document by its ID.
+        #
+        # @param document_id [String] The unique identifier of the document.
+        #
+        # @param params [FinchAPI::Models::HRIS::DocumentRetreiveParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::HRIS::W42020, FinchAPI::Models::HRIS::W42005]
+        #
+        def retreive(document_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["employer/documents/%0s", document_id],
+            model: FinchAPI::Models::HRIS::DocumentRetreiveResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/hris/employments.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class Employments
+        # Read individual employment and income data
+        #
+        # @param params [FinchAPI::Models::HRIS::EmploymentRetrieveManyParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [Array<FinchAPI::Models::HRIS::EmploymentRetrieveManyParams::Request>] :requests The array of batch requests.
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::ResponsesPage<FinchAPI::Models::HRIS::EmploymentDataResponse>]
+        #
+        def retrieve_many(params)
+          parsed, options = FinchAPI::Models::HRIS::EmploymentRetrieveManyParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "employer/employment",
+            body: parsed,
+            page: FinchAPI::ResponsesPage,
+            model: FinchAPI::Models::HRIS::EmploymentDataResponse,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class Individuals
+        # Read individual data, excluding income and employment data
+        #
+        # @param params [FinchAPI::Models::HRIS::IndividualRetrieveManyParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [FinchAPI::Models::HRIS::IndividualRetrieveManyParams::Options, nil] :options
+        #
+        #   @option params [Array<FinchAPI::Models::HRIS::IndividualRetrieveManyParams::Request>] :requests
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::ResponsesPage<FinchAPI::Models::HRIS::IndividualResponse>]
+        #
+        def retrieve_many(params = {})
+          parsed, options = FinchAPI::Models::HRIS::IndividualRetrieveManyParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "employer/individual",
+            body: parsed,
+            page: FinchAPI::ResponsesPage,
+            model: FinchAPI::Models::HRIS::IndividualResponse,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/hris/pay_statements.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class PayStatements
+        # Read detailed pay statements for each individual.
+        #
+        #   Deduction and contribution types are supported by the payroll systems that
+        #   supports Benefits.
+        #
+        # @param params [FinchAPI::Models::HRIS::PayStatementRetrieveManyParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [Array<FinchAPI::Models::HRIS::PayStatementRetrieveManyParams::Request>] :requests The array of batch requests.
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::ResponsesPage<FinchAPI::Models::HRIS::PayStatementResponse>]
+        #
+        def retrieve_many(params)
+          parsed, options = FinchAPI::Models::HRIS::PayStatementRetrieveManyParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "employer/pay-statement",
+            body: parsed,
+            page: FinchAPI::ResponsesPage,
+            model: FinchAPI::Models::HRIS::PayStatementResponse,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/hris/payments.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      class Payments
+        # Read payroll and contractor related payments by the company.
+        #
+        # @param params [FinchAPI::Models::HRIS::PaymentListParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [Date] :end_date The end date to retrieve payments by a company (inclusive) in `YYYY-MM-DD`
+        #     format.
+        #
+        #   @option params [Date] :start_date The start date to retrieve payments by a company (inclusive) in `YYYY-MM-DD`
+        #     format.
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::SinglePage<FinchAPI::Models::HRIS::Payment>]
+        #
+        def list(params)
+          parsed, options = FinchAPI::Models::HRIS::PaymentListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: "employer/payment",
+            query: parsed,
+            page: FinchAPI::SinglePage,
+            model: FinchAPI::Models::HRIS::Payment,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class HRIS
+      # @return [FinchAPI::Resources::HRIS::Company]
+      attr_reader :company
+
+      # @return [FinchAPI::Resources::HRIS::Directory]
+      attr_reader :directory
+
+      # @return [FinchAPI::Resources::HRIS::Individuals]
+      attr_reader :individuals
+
+      # @return [FinchAPI::Resources::HRIS::Employments]
+      attr_reader :employments
+
+      # @return [FinchAPI::Resources::HRIS::Payments]
+      attr_reader :payments
+
+      # @return [FinchAPI::Resources::HRIS::PayStatements]
+      attr_reader :pay_statements
+
+      # @return [FinchAPI::Resources::HRIS::Documents]
+      attr_reader :documents
+
+      # @return [FinchAPI::Resources::HRIS::Benefits]
+      attr_reader :benefits
+
+      # @param client [FinchAPI::Client]
+      #
+      def initialize(client:)
+        @client = client
+        @company = FinchAPI::Resources::HRIS::Company.new(client: client)
+        @directory = FinchAPI::Resources::HRIS::Directory.new(client: client)
+        @individuals = FinchAPI::Resources::HRIS::Individuals.new(client: client)
+        @employments = FinchAPI::Resources::HRIS::Employments.new(client: client)
+        @payments = FinchAPI::Resources::HRIS::Payments.new(client: client)
+        @pay_statements = FinchAPI::Resources::HRIS::PayStatements.new(client: client)
+        @documents = FinchAPI::Resources::HRIS::Documents.new(client: client)
+        @benefits = FinchAPI::Resources::HRIS::Benefits.new(client: client)
+      end
+    end
+  end
+end