vitable-connect 0.6.0 → 1.0.0

data/README.md

@@ -1,8 +1,27 @@
-# Vitable Connect Ruby API library
-
-The Vitable Connect Ruby library provides convenient access to the Vitable Connect REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/Vitable-Inc/vitable-connect-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
-
-It is generated with [Stainless](https://www.stainless.com/).
+# Vitable Ruby Library
+
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2FVitable-Inc%2Fvitable-connect-ruby)
+
+The Vitable Ruby library provides convenient access to the Vitable APIs from Ruby.
+
+## Table of Contents
+
+- [Documentation](#documentation)
+- [Installation](#installation)
+- [Reference](#reference)
+- [Usage](#usage)
+- [Advanced Concepts](#advanced-concepts)
+- [Sorbet](#sorbet)
+- [Versioning](#versioning)
+- [Requirements](#requirements)
+- [Environments](#environments)
+- [Errors](#errors)
+- [Advanced](#advanced)
+  - [Retries](#retries)
+  - [Timeouts](#timeouts)
+  - [Additional Headers](#additional-headers)
+  - [Additional Query Parameters](#additional-query-parameters)
+- [Contributing](#contributing)
 
 ## Documentation
 
@@ -22,123 +41,22 @@ gem "vitable-connect", "~> 0.6.0"
 
 <!-- x-release-please-end -->
 
-## Usage
-
-```ruby
-require "bundler/setup"
-require "vitable_connect"
-
-vitable_connect = VitableConnect::Client.new(
-  api_key: ENV["VITABLE_CONNECT_API_KEY"], # This is the default and can be omitted
-  environment: "environment_1" # defaults to "production"
-)
-
-response = vitable_connect.auth.issue_access_token(grant_type: "client_credentials")
-
-puts(response.access_token)
-```
-
-### Pagination
-
-List methods in the Vitable Connect 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 = vitable_connect.employees.list_enrollments
-
-# Fetch single item from page.
-employee = page.data[0]
-puts(employee.id)
-
-# Automatically fetches more pages as needed.
-page.auto_paging_each do |employee|
-  puts(employee.id)
-end
-```
-
-Alternatively, you can use the `#next_page?` and `#next_page` methods for more granular control working with pages.
-
-```ruby
-if page.next_page?
-  new_page = page.next_page
-  puts(new_page.data[0].id)
-end
-```
-
-### Handling 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 `VitableConnect::Errors::APIError` will be thrown:
-
-```ruby
-begin
-  auth = vitable_connect.auth.issue_access_token(grant_type: "client_credentials")
-rescue VitableConnect::Errors::APIConnectionError => e
-  puts("The server could not be reached")
-  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
-rescue VitableConnect::Errors::RateLimitError => e
-  puts("A 429 status code was received; we should back off a bit.")
-rescue VitableConnect::Errors::APIStatusError => e
-  puts("Another non-200-range status code was received")
-  puts(e.status)
-end
-```
-
-Error codes are as follows:
-
-| 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
+## Reference
 
-Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+A full reference for this library is available [here](https://github.com/Vitable-Inc/vitable-connect-ruby/blob/HEAD/./reference.md).
 
-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.
+## Usage
 
-You can use the `max_retries` option to configure or disable this:
+Instantiate and use the client with the following:
 
 ```ruby
-# Configure the default for all requests:
-vitable_connect = VitableConnect::Client.new(
-  max_retries: 0 # default is 2
-)
-
-# Or, configure per-request:
-vitable_connect.auth.issue_access_token(
-  grant_type: "client_credentials",
-  request_options: {max_retries: 5}
-)
-```
-
-### Timeouts
+require "vitableconnect"
 
-By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:
+client = VitableConnect::Client.new(api_key: "<token>")
 
-```ruby
-# Configure the default for all requests:
-vitable_connect = VitableConnect::Client.new(
-  timeout: nil # default is 60
-)
-
-# Or, configure per-request:
-vitable_connect.auth.issue_access_token(grant_type: "client_credentials", request_options: {timeout: 5})
+client.auth.issue_access_token(grant_type: "client_credentials")
 ```
 
-On timeout, `VitableConnect::Errors::APITimeoutError` is raised.
-
-Note that requests that time out are retried by default.
-
 ## Advanced concepts
 
 ### BaseModel
@@ -262,6 +180,135 @@ This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` typ
 
 Ruby 3.2.0 or higher.
 
+## Environments
+
+This SDK allows you to configure different environments or custom URLs for API requests. You can either use the predefined environments or specify your own custom URL.
+### Environments
+```ruby
+require "VitableConnect"
+
+VitableConnect = VitableConnect::Client.new(
+    base_url: VitableConnect::Environment::PRODUCTION
+)
+```
+
+### Custom URL
+```ruby
+require "VitableConnect"
+
+client = VitableConnect::Client.new(
+    base_url: "https://example.com"
+)
+```
+
+## Errors
+
+Failed API calls will raise errors that can be rescued from granularly.
+
+```ruby
+require "VitableConnect"
+
+client = VitableConnect::Client.new(
+    base_url: "https://example.com"
+)
+
+begin
+    result = client.auth.issue_access_token
+rescue VitableConnect::Errors::TimeoutError
+    puts "API didn't respond before our timeout elapsed"
+rescue VitableConnect::Errors::ServiceUnavailableError
+    puts "API returned status 503, is probably overloaded, try again later"
+rescue VitableConnect::Errors::ServerError
+    puts "API returned some other 5xx status, this is probably a bug"
+rescue VitableConnect::Errors::ResponseError => e
+    puts "API returned an unexpected status other than 5xx: #{e.code} #{e.message}"
+rescue VitableConnect::Errors::ApiError => e
+    puts "Some other error occurred when calling the API: #{e.message}"
+end
+```
+
+## Advanced
+
+### Retries
+
+The SDK is instrumented with automatic retries. A request will be retried as long as the request is deemed
+retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).
+
+A request is deemed retryable when any of the following HTTP status codes is returned:
+
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (Internal Server Error)
+
+The `retryStatusCodes` configuration controls which [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) status codes are retried:
+
+- `legacy` (default): Retries `408`, `429`, `500`, `502`, `503`, `504`, `521`, `522`, `524`
+- `recommended`: Retries `408`, `429`, `502`, `503`, `504` only (excludes `500 Internal Server Error` to avoid retrying non-idempotent failures)
+
+Use the `max_retries` option to configure this behavior.
+
+```ruby
+require "VitableConnect"
+
+client = VitableConnect::Client.new(
+    base_url: "https://example.com",
+    max_retries: 3  # Configure max retries (default is 2)
+)
+```
+
+### Timeouts
+
+The SDK defaults to a 60 second timeout. Use the `timeout` option to configure this behavior.
+
+```ruby
+require "VitableConnect"
+
+response = client.auth.issue_access_token(
+    ...,
+    timeout: 30  # 30 second timeout
+)
+```
+
+### Additional Headers
+
+If you would like to send additional headers as part of the request, use the `additional_headers` request option.
+
+```ruby
+require "VitableConnect"
+
+response = client.auth.issue_access_token(
+    ...,
+    request_options: {
+        additional_headers: {
+            "X-Custom-Header" => "custom-value"
+        }
+    }
+)
+```
+
+### Additional Query Parameters
+
+If you would like to send additional query parameters as part of the request, use the `additional_query_parameters` request option.
+
+```ruby
+require "VitableConnect"
+
+response = client.auth.issue_access_token(
+    ...,
+    request_options: {
+        additional_query_parameters: {
+            "custom_param" => "custom-value"
+        }
+    }
+)
+```
+
 ## Contributing
 
-See [the contributing documentation](https://github.com/Vitable-Inc/vitable-connect-ruby/tree/main/CONTRIBUTING.md).
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!

data/Rakefile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test]
+
+task lint: %i[rubocop]
+
+# Run only the custom test file
+Minitest::TestTask.create(:customtest) do |t|
+  t.libs << "test"
+  t.test_globs = ["test/custom.test.rb"]
+end

data/custom.gemspec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Custom gemspec configuration file
+# This file is automatically loaded by the main gemspec file. The 'spec' variable is available
+# in this context from the main gemspec file. You can modify this file to add custom metadata,
+# dependencies, or other gemspec configurations. If you do make changes to this file, you will
+# need to add it to the .fernignore file to prevent your changes from being overwritten.
+
+def add_custom_gemspec_data(spec)
+  # Example custom configurations (uncomment and modify as needed)
+
+  # spec.authors = ["Your name"]
+  # spec.email = ["your.email@example.com"]
+  # spec.homepage = "https://github.com/your-org/vitableconnect-ruby"
+  # spec.license = "Your license"
+end

data/lib/VitableConnect/auth/client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Auth
+    class Client
+      # @param client [VitableConnect::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Issues a short-lived access token from the authenticated API key. Access tokens can optionally be bound to a
+      # specific employer or employee for scoped access. Tokens expire after 15 minutes.
+      #
+      # @param request_options [Hash]
+      # @param params [VitableConnect::Auth::Types::IssueAccessTokenRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @example
+      #   client.auth.issue_access_token(grant_type: "client_credentials")
+      #
+      # @return [VitableConnect::Types::AccessTokenResponse]
+      def issue_access_token(request_options: {}, **params)
+        params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
+        request = VitableConnect::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "v1/auth/access-tokens",
+          body: VitableConnect::Auth::Types::IssueAccessTokenRequest.new(params).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise VitableConnect::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          VitableConnect::Types::AccessTokenResponse.load(response.body)
+        else
+          error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+    end
+  end
+end

data/lib/VitableConnect/auth/types/issue_access_token_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Auth
+    module Types
+      class IssueAccessTokenRequest < Internal::Types::Model
+        field :grant_type, -> { VitableConnect::Types::GrantType }, optional: false, nullable: false
+
+        field :bound_entity, -> { VitableConnect::Types::BoundEntity }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/VitableConnect/client.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  class Client
+    # @param base_url [String, nil]
+    # @param api_key [String]
+    # @param max_retries [Integer]
+    #
+    # @return [void]
+    def initialize(base_url: nil, api_key: ENV.fetch("VITABLE_CONNECT_API_KEY", nil), max_retries: 2)
+      @raw_client = VitableConnect::Internal::Http::RawClient.new(
+        base_url: base_url || VitableConnect::Environment::PRODUCTION,
+        headers: {
+          "User-Agent" => "vitable-connect/1.0.0",
+          "X-Fern-Language" => "Ruby",
+          Authorization: "Bearer #{api_key}"
+        },
+        max_retries: max_retries
+      )
+    end
+
+    # @return [VitableConnect::Auth::Client]
+    def auth
+      @auth ||= VitableConnect::Auth::Client.new(client: @raw_client)
+    end
+
+    # @return [VitableConnect::Employees::Client]
+    def employees
+      @employees ||= VitableConnect::Employees::Client.new(client: @raw_client)
+    end
+
+    # @return [VitableConnect::Employers::Client]
+    def employers
+      @employers ||= VitableConnect::Employers::Client.new(client: @raw_client)
+    end
+
+    # @return [VitableConnect::Enrollments::Client]
+    def enrollments
+      @enrollments ||= VitableConnect::Enrollments::Client.new(client: @raw_client)
+    end
+
+    # @return [VitableConnect::Groups::Client]
+    def groups
+      @groups ||= VitableConnect::Groups::Client.new(client: @raw_client)
+    end
+
+    # @return [VitableConnect::Members::Client]
+    def members
+      @members ||= VitableConnect::Members::Client.new(client: @raw_client)
+    end
+
+    # @return [VitableConnect::Organizations::Client]
+    def organizations
+      @organizations ||= VitableConnect::Organizations::Client.new(client: @raw_client)
+    end
+
+    # @return [VitableConnect::Plans::Client]
+    def plans
+      @plans ||= VitableConnect::Plans::Client.new(client: @raw_client)
+    end
+
+    # @return [VitableConnect::WebhookEvents::Client]
+    def webhook_events
+      @webhook_events ||= VitableConnect::WebhookEvents::Client.new(client: @raw_client)
+    end
+  end
+end

data/lib/VitableConnect/employees/client.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Employees
+    class Client
+      # @param client [VitableConnect::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Retrieves detailed information for a specific employee by ID. Returns employee details including personal
+      # information, employment status, classification and compensation-type effective dates, compensation type, and
+      # payroll deductions from the most recent statement period. Deductions reflect a snapshot of the current period
+      # and are replaced when a new statement is generated.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [VitableConnect::Types::EmployeeID] :employee_id
+      #
+      # @example
+      #   client.employees.get(employee_id: "empl_abc123def456")
+      #
+      # @return [VitableConnect::Types::EmployeeResponse]
+      def get(request_options: {}, **params)
+        params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
+        request = VitableConnect::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "v1/employees/#{URI.encode_uri_component(params[:employee_id].to_s)}",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise VitableConnect::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          VitableConnect::Types::EmployeeResponse.load(response.body)
+        else
+          error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Updates employee personal, contact, address, and employment fields. This endpoint currently supports email,
+      # phone, gender, address, employee_class, start_date, and compensation_type. effective_date is required and
+      # applies to employee_class and compensation_type when those fields are included in the request.
+      #
+      # @param request_options [Hash]
+      # @param params [VitableConnect::Employees::Types::PatchedUpdateEmployeeRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [VitableConnect::Types::EmployeeID] :employee_id
+      #
+      # @example
+      #   client.employees.update(
+      #     employee_id: "empl_abc123def456",
+      #     employee_class: "Full Time",
+      #     start_date: "2023-01-15",
+      #     compensation_type: "Salary",
+      #     effective_date: "2023-03-01"
+      #   )
+      #
+      # @return [VitableConnect::Types::EmployeeResponse]
+      def update(request_options: {}, **params)
+        params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
+        request_data = VitableConnect::Employees::Types::PatchedUpdateEmployeeRequest.new(params).to_h
+        non_body_param_names = %w[employee_id]
+        body = request_data.except(*non_body_param_names)
+
+        request = VitableConnect::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "PATCH",
+          path: "v1/employees/#{URI.encode_uri_component(params[:employee_id].to_s)}",
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise VitableConnect::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          VitableConnect::Types::EmployeeResponse.load(response.body)
+        else
+          error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Retrieves a paginated list of benefit enrollments for an employee.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [VitableConnect::Types::EmployeeID] :employee_id
+      # @option params [Integer, nil] :limit
+      # @option params [Integer, nil] :page
+      #
+      # @example
+      #   client.employees.list_enrollments(
+      #     employee_id: "empl_abc123def456",
+      #     limit: 20,
+      #     page: 1
+      #   )
+      #
+      # @return [VitableConnect::Types::EnrollmentListResponse]
+      def list_enrollments(request_options: {}, **params)
+        params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
+        query_params = {}
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        query_params["page"] = params[:page] if params.key?(:page)
+
+        VitableConnect::Internal::OffsetItemIterator.new(
+          initial_page: query_params["page"],
+          item_field: :data,
+          has_next_field: nil,
+          step: false
+        ) do |next_page|
+          query_params["page"] = next_page
+          request = VitableConnect::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "GET",
+            path: "v1/employees/#{URI.encode_uri_component(params[:employee_id].to_s)}/enrollments",
+            query: query_params,
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise VitableConnect::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            parsed_response = VitableConnect::Types::EnrollmentListResponse.load(response.body)
+            [parsed_response, response]
+          else
+            error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/VitableConnect/employees/types/get_employees_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Employees
+    module Types
+      class GetEmployeesRequest < Internal::Types::Model
+        field :employee_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/VitableConnect/employees/types/list_enrollments_employees_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Employees
+    module Types
+      class ListEnrollmentsEmployeesRequest < Internal::Types::Model
+        field :employee_id, -> { String }, optional: false, nullable: false
+
+        field :limit, -> { Integer }, optional: true, nullable: false
+
+        field :page, -> { Integer }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/VitableConnect/employees/types/patched_update_employee_request.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Employees
+    module Types
+      class PatchedUpdateEmployeeRequest < Internal::Types::Model
+        field :employee_id, -> { String }, optional: false, nullable: false
+
+        field :email, -> { String }, optional: true, nullable: false
+
+        field :phone, -> { String }, optional: true, nullable: false
+
+        field :gender, -> { VitableConnect::Types::Gender }, optional: true, nullable: false
+
+        field :address, -> { VitableConnect::Types::EmployeeAddressInput }, optional: true, nullable: false
+
+        field :employee_class, -> { VitableConnect::Types::EmployeeClass }, optional: true, nullable: false
+
+        field :start_date, -> { String }, optional: true, nullable: false
+
+        field :compensation_type, -> { VitableConnect::Types::CompensationType }, optional: true, nullable: false
+
+        field :effective_date, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end