vitable-connect 0.1.0

data/rbi/vitable_connect/request_options.rbi

@@ -0,0 +1,61 @@
+# typed: strong
+
+module VitableConnect
+  # 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 < VitableConnect::Internal::Type::BaseModel
+    OrHash =
+      T.type_alias do
+        T.any(VitableConnect::RequestOptions, VitableConnect::Internal::AnyHash)
+      end
+
+    # @api private
+    sig { params(opts: VitableConnect::RequestOptions::OrHash).void }
+    def self.validate!(opts)
+    end
+
+    # Idempotency key to send with request and all associated retries. Will only be
+    # sent for write requests.
+    sig { returns(T.nilable(String)) }
+    attr_accessor :idempotency_key
+
+    # Extra query params to send with the request. These are `.merge`’d into any
+    # `query` given at the client level.
+    sig do
+      returns(
+        T.nilable(T::Hash[String, T.nilable(T.any(T::Array[String], String))])
+      )
+    end
+    attr_accessor :extra_query
+
+    # Extra headers to send with the request. These are `.merged`’d into any
+    # `extra_headers` given at the client level.
+    sig { returns(T.nilable(T::Hash[String, T.nilable(String)])) }
+    attr_accessor :extra_headers
+
+    # Extra data to send with the request. These are deep merged into any data
+    # generated as part of the normal request.
+    sig { returns(T.nilable(T.anything)) }
+    attr_accessor :extra_body
+
+    # Maximum number of retries to attempt after a failed initial request.
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :max_retries
+
+    # Request timeout in seconds.
+    sig { returns(T.nilable(Float)) }
+    attr_accessor :timeout
+
+    # Returns a new instance of RequestOptions.
+    sig do
+      params(values: VitableConnect::Internal::AnyHash).returns(
+        T.attached_class
+      )
+    end
+    def self.new(values = {})
+    end
+  end
+end

data/rbi/vitable_connect/resources/auth.rbi

@@ -0,0 +1,36 @@
+# typed: strong
+
+module VitableConnect
+  module Resources
+    # Issue short-lived access tokens for scoped API access
+    class Auth
+      # 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.
+      sig do
+        params(
+          grant_type:
+            VitableConnect::AuthIssueAccessTokenParams::GrantType::OrSymbol,
+          bound_entity:
+            T.nilable(
+              VitableConnect::AuthIssueAccessTokenParams::BoundEntity::OrHash
+            ),
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(VitableConnect::Models::AuthIssueAccessTokenResponse)
+      end
+      def issue_access_token(
+        # - `client_credentials` - client_credentials
+        grant_type:,
+        # Optional entity to bind the token to for scoped access
+        bound_entity: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: VitableConnect::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vitable_connect/resources/benefit_eligibility_policies.rbi

@@ -0,0 +1,27 @@
+# typed: strong
+
+module VitableConnect
+  module Resources
+    # Define rules that determine which employees qualify for benefits
+    class BenefitEligibilityPolicies
+      # Retrieves a benefit eligibility policy by ID.
+      sig do
+        params(
+          policy_id: String,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(VitableConnect::BenefitEligibilityPolicyResponse)
+      end
+      def retrieve(
+        # Unique benefit eligibility policy identifier (epol\_\*)
+        policy_id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: VitableConnect::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vitable_connect/resources/employees.rbi

@@ -0,0 +1,49 @@
+# typed: strong
+
+module VitableConnect
+  module Resources
+    class Employees
+      # Retrieves detailed information for a specific employee by ID. Returns employee
+      # details including personal information and employment status.
+      sig do
+        params(
+          employee_id: String,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(VitableConnect::Models::EmployeeRetrieveResponse)
+      end
+      def retrieve(
+        # Unique employee identifier (empl\_\*)
+        employee_id,
+        request_options: {}
+      )
+      end
+
+      # Retrieves a paginated list of benefit enrollments for an employee.
+      sig do
+        params(
+          employee_id: String,
+          limit: Integer,
+          page: Integer,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(
+          VitableConnect::Internal::PageNumberPage[VitableConnect::Enrollment]
+        )
+      end
+      def list_enrollments(
+        # Unique employee identifier (empl\_\*)
+        employee_id,
+        # Items per page (default: 20, max: 100)
+        limit: nil,
+        # Page number (default: 1)
+        page: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: VitableConnect::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vitable_connect/resources/employers.rbi

@@ -0,0 +1,147 @@
+# typed: strong
+
+module VitableConnect
+  module Resources
+    class Employers
+      # Creates a new employer for the authenticated organization. Requires employer
+      # name, legal name, EIN, email, and address information. Returns the created
+      # employer with its assigned ID.
+      sig do
+        params(
+          address: VitableConnect::EmployerCreateParams::Address::OrHash,
+          ein: String,
+          email: String,
+          legal_name: String,
+          name: String,
+          phone_number: T.nilable(String),
+          reference_id: T.nilable(String),
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(VitableConnect::EmployerResponse)
+      end
+      def create(
+        # Employer address
+        address:,
+        # Employer Identification Number (format: XX-XXXXXXX)
+        ein:,
+        # Email address for billing and communications
+        email:,
+        # Legal business name
+        legal_name:,
+        # Employer display name
+        name:,
+        # Employer phone number (10-digit US format, e.g. 5551234567)
+        phone_number: nil,
+        # External reference ID for this employer
+        reference_id: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieves detailed information for a specific employer by ID. The employer must
+      # belong to the authenticated organization.
+      sig do
+        params(
+          employer_id: String,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(VitableConnect::EmployerResponse)
+      end
+      def retrieve(
+        # Unique employer identifier (empr\_\*)
+        employer_id,
+        request_options: {}
+      )
+      end
+
+      # Retrieves a paginated list of all employers belonging to the authenticated
+      # organization. Results are sorted by creation date (newest first) and paginated
+      # using page and limit parameters.
+      sig do
+        params(
+          limit: Integer,
+          page: Integer,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(
+          VitableConnect::Internal::PageNumberPage[VitableConnect::Employer]
+        )
+      end
+      def list(
+        # Items per page (default: 20, max: 100)
+        limit: nil,
+        # Page number (default: 1)
+        page: nil,
+        request_options: {}
+      )
+      end
+
+      # Creates a benefit eligibility policy for the specified employer.
+      sig do
+        params(
+          employer_id: String,
+          classification: String,
+          waiting_period: String,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(VitableConnect::BenefitEligibilityPolicyResponse)
+      end
+      def create_benefit_eligibility_policy(
+        # Unique employer identifier (empr\_\*)
+        employer_id,
+        # Which employee classifications are eligible. One of: full_time, part_time, all
+        classification:,
+        # Waiting period before eligibility. One of: first_of_following_month, 30_days,
+        # 60_days, none
+        waiting_period:,
+        request_options: {}
+      )
+      end
+
+      # Retrieves a paginated list of all employees for a specific employer. Results are
+      # paginated using page and limit parameters.
+      sig do
+        params(
+          employer_id: String,
+          limit: Integer,
+          page: Integer,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(
+          VitableConnect::Internal::PageNumberPage[VitableConnect::Employee]
+        )
+      end
+      def list_employees(
+        # Unique employer identifier (empr\_\*)
+        employer_id,
+        # Items per page (default: 20, max: 100)
+        limit: nil,
+        # Page number (default: 1)
+        page: nil,
+        request_options: {}
+      )
+      end
+
+      # Submits a census sync payload for the specified employer. The employees in the
+      # payload will be queued for processing. Returns an accepted response with the
+      # timestamp of acceptance.
+      sig do
+        params(
+          employer_id: String,
+          employees:
+            T::Array[
+              VitableConnect::EmployerSubmitCensusSyncParams::Employee::OrHash
+            ],
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(VitableConnect::Models::EmployerSubmitCensusSyncResponse)
+      end
+      def submit_census_sync(
+        # Unique employer identifier (empr\_\*)
+        employer_id,
+        employees:,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: VitableConnect::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vitable_connect/resources/enrollments.rbi

@@ -0,0 +1,27 @@
+# typed: strong
+
+module VitableConnect
+  module Resources
+    # Manage benefit enrollments and elections for employees
+    class Enrollments
+      # Retrieves detailed information for a specific enrollment by ID.
+      sig do
+        params(
+          enrollment_id: String,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(VitableConnect::Models::EnrollmentRetrieveResponse)
+      end
+      def retrieve(
+        # Unique enrollment identifier (enrl\_\*)
+        enrollment_id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: VitableConnect::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vitable_connect/resources/webhook_events.rbi

@@ -0,0 +1,84 @@
+# typed: strong
+
+module VitableConnect
+  module Resources
+    class WebhookEvents
+      # Retrieves a single webhook event by its prefixed ID. Returns 404 if the event
+      # does not exist or belongs to a different organization.
+      sig do
+        params(
+          event_id: String,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(VitableConnect::Models::WebhookEventRetrieveResponse)
+      end
+      def retrieve(event_id, request_options: {})
+      end
+
+      # Retrieves a paginated list of webhook events for the authenticated organization.
+      # Supports filtering by event name, resource type, resource ID, and date range.
+      sig do
+        params(
+          created_after: Time,
+          created_before: Time,
+          event_name:
+            VitableConnect::WebhookEventListParams::EventName::OrSymbol,
+          limit: Integer,
+          page: Integer,
+          resource_id: String,
+          resource_type:
+            VitableConnect::WebhookEventListParams::ResourceType::OrSymbol,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(
+          VitableConnect::Internal::PageNumberPage[VitableConnect::WebhookEvent]
+        )
+      end
+      def list(
+        created_after: nil,
+        created_before: nil,
+        # - `enrollment.accepted` - Enrollment Accepted
+        # - `enrollment.terminated` - Enrollment Terminated
+        # - `enrollment.elected` - Enrollment Elected
+        # - `enrollment.granted` - Enrollment Granted
+        # - `enrollment.waived` - Enrollment Waived
+        # - `enrollment.started` - Enrollment Started
+        # - `employee.eligibility_granted` - Employee Eligibility Granted
+        # - `employee.eligibility_terminated` - Employee Eligibility Terminated
+        # - `employee.deactivated` - Employee Deactivated
+        # - `payroll_deduction.created` - Payroll Deduction Created
+        # - `employer.eligibility_policy_created` - Employer Eligibility Policy Created
+        event_name: nil,
+        # Items per page (default: 20, max: 100)
+        limit: nil,
+        # Page number (default: 1)
+        page: nil,
+        resource_id: nil,
+        # - `enrollment` - Enrollment
+        # - `employee` - Employee
+        # - `employer` - Employer
+        # - `dependent` - Dependent
+        # - `plan_year` - Plan Year
+        # - `payroll_deduction` - Payroll Deduction
+        resource_type: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieves all delivery attempts for a webhook event. Returns up to 100
+      # deliveries. Each delivery includes a computed status field (Pending, In
+      # Progress, Delivered, or Failed).
+      sig do
+        params(
+          event_id: String,
+          request_options: VitableConnect::RequestOptions::OrHash
+        ).returns(VitableConnect::Models::WebhookEventListDeliveriesResponse)
+      end
+      def list_deliveries(event_id, request_options: {})
+      end
+
+      # @api private
+      sig { params(client: VitableConnect::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vitable_connect/version.rbi

@@ -0,0 +1,5 @@
+# typed: strong
+
+module VitableConnect
+  VERSION = T.let(T.unsafe(nil), String)
+end

data/sig/vitable_connect/client.rbs

@@ -0,0 +1,42 @@
+module VitableConnect
+  class Client < VitableConnect::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES: 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS: Float
+
+    DEFAULT_INITIAL_RETRY_DELAY: Float
+
+    DEFAULT_MAX_RETRY_DELAY: Float
+
+    ENVIRONMENTS: {
+      production: "https://api.vitablehealth.com",
+      :environment_1 => "https://api.uat.vitablehealth.com"
+    }
+
+    attr_reader api_key: String
+
+    attr_reader auth: VitableConnect::Resources::Auth
+
+    attr_reader benefit_eligibility_policies: VitableConnect::Resources::BenefitEligibilityPolicies
+
+    attr_reader employees: VitableConnect::Resources::Employees
+
+    attr_reader employers: VitableConnect::Resources::Employers
+
+    attr_reader enrollments: VitableConnect::Resources::Enrollments
+
+    attr_reader webhook_events: VitableConnect::Resources::WebhookEvents
+
+    private def auth_headers: -> ::Hash[String, String]
+
+    def initialize: (
+      ?api_key: String?,
+      ?environment: :production | :environment_1 | nil,
+      ?base_url: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
+    ) -> void
+  end
+end

data/sig/vitable_connect/errors.rbs

@@ -0,0 +1,117 @@
+module VitableConnect
+  module Errors
+    class Error < StandardError
+      attr_accessor cause: StandardError?
+    end
+
+    class ConversionError < VitableConnect::Errors::Error
+      def cause: -> StandardError?
+
+      def initialize: (
+        on: Class,
+        method: Symbol,
+        target: top,
+        value: top,
+        ?cause: StandardError?
+      ) -> void
+    end
+
+    class APIError < VitableConnect::Errors::Error
+      attr_accessor url: URI::Generic
+
+      attr_accessor status: Integer?
+
+      attr_accessor headers: ::Hash[String, String]?
+
+      attr_accessor body: top?
+
+      def initialize: (
+        url: URI::Generic,
+        ?status: Integer?,
+        ?headers: ::Hash[String, String]?,
+        ?body: Object?,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIConnectionError < VitableConnect::Errors::APIError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APITimeoutError < VitableConnect::Errors::APIConnectionError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIStatusError < VitableConnect::Errors::APIError
+      def self.for: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> instance
+
+      def initialize: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class BadRequestError < VitableConnect::Errors::APIStatusError
+      HTTP_STATUS: 400
+    end
+
+    class AuthenticationError < VitableConnect::Errors::APIStatusError
+      HTTP_STATUS: 401
+    end
+
+    class PermissionDeniedError < VitableConnect::Errors::APIStatusError
+      HTTP_STATUS: 403
+    end
+
+    class NotFoundError < VitableConnect::Errors::APIStatusError
+      HTTP_STATUS: 404
+    end
+
+    class ConflictError < VitableConnect::Errors::APIStatusError
+      HTTP_STATUS: 409
+    end
+
+    class UnprocessableEntityError < VitableConnect::Errors::APIStatusError
+      HTTP_STATUS: 422
+    end
+
+    class RateLimitError < VitableConnect::Errors::APIStatusError
+      HTTP_STATUS: 429
+    end
+
+    class InternalServerError < VitableConnect::Errors::APIStatusError
+      HTTP_STATUS: Range[Integer]
+    end
+  end
+end

data/sig/vitable_connect/file_part.rbs

@@ -0,0 +1,21 @@
+module VitableConnect
+  class FilePart
+    attr_reader content: Pathname | StringIO | IO | String
+
+    attr_reader content_type: String?
+
+    attr_reader filename: String?
+
+    private def read: -> String
+
+    def to_json: (*top a) -> String
+
+    def to_yaml: (*top a) -> String
+
+    def initialize: (
+      Pathname | StringIO | IO | String content,
+      ?filename: (Pathname | String)?,
+      ?content_type: String?
+    ) -> void
+  end
+end

data/sig/vitable_connect/internal/page_number_page.rbs

@@ -0,0 +1,28 @@
+module VitableConnect
+  module Internal
+    class PageNumberPage[Elem]
+      include VitableConnect::Internal::Type::BasePage[Elem]
+
+      attr_accessor data: ::Array[Elem]?
+
+      attr_accessor pagination: Pagination
+
+      def inspect: -> String
+
+      type pagination = { page: Integer, total_pages: Integer }
+      class Pagination < VitableConnect::Internal::Type::BaseModel
+        attr_reader page: Integer?
+
+        def page=: (Integer) -> Integer
+
+        attr_reader total_pages: Integer?
+
+        def total_pages=: (Integer) -> Integer
+
+        def initialize: (?page: Integer, ?total_pages: Integer) -> void
+
+        def to_hash: -> { page: Integer, total_pages: Integer }
+      end
+    end
+  end
+end