// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../../core/resource';
import * as Shared from '../../shared';
import * as IndividualsAPI from './individuals';
import {
  EnrolledIndividualBenefitResponse,
  IndividualBenefit,
  IndividualBenefitsSinglePage,
  IndividualEnrollManyParams,
  IndividualEnrolledIDsParams,
  IndividualEnrolledIDsResponse,
  IndividualRetrieveManyBenefitsParams,
  IndividualUnenrollManyParams,
  Individuals,
  UnenrolledIndividualBenefitResponse,
} from './individuals';
import { APIPromise } from '../../../core/api-promise';
import { PagePromise, SinglePage } from '../../../core/pagination';
import { RequestOptions } from '../../../internal/request-options';
import { path } from '../../../internal/utils/path';

export class Benefits extends APIResource {
  individuals: IndividualsAPI.Individuals = new IndividualsAPI.Individuals(this._client);

  /**
   * Creates a new company-wide deduction or contribution. Please use the
   * `/providers` endpoint to view available types for each provider.
   *
   * @example
   * ```ts
   * const createCompanyBenefitsResponse =
   *   await client.hris.benefits.create();
   * ```
   */
  create(
    params: BenefitCreateParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<CreateCompanyBenefitsResponse> {
    const { entity_ids, ...body } = params ?? {};
    return this._client.post('/employer/benefits', {
      query: { entity_ids },
      body,
      ...options,
      __security: { bearerAuth: true },
    });
  }

  /**
   * Lists deductions and contributions information for a given item
   *
   * @example
   * ```ts
   * const companyBenefit = await client.hris.benefits.retrieve(
   *   'benefit_id',
   * );
   * ```
   */
  retrieve(
    benefitID: string,
    query: BenefitRetrieveParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<CompanyBenefit> {
    return this._client.get(path`/employer/benefits/${benefitID}`, {
      query,
      ...options,
      __security: { bearerAuth: true },
    });
  }

  /**
   * Updates an existing company-wide deduction or contribution
   *
   * @example
   * ```ts
   * const updateCompanyBenefitResponse =
   *   await client.hris.benefits.update('benefit_id');
   * ```
   */
  update(
    benefitID: string,
    params: BenefitUpdateParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<UpdateCompanyBenefitResponse> {
    const { entity_ids, ...body } = params ?? {};
    return this._client.post(path`/employer/benefits/${benefitID}`, {
      query: { entity_ids },
      body,
      ...options,
      __security: { bearerAuth: true },
    });
  }

  /**
   * List all company-wide deductions and contributions.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const companyBenefit of client.hris.benefits.list()) {
   *   // ...
   * }
   * ```
   */
  list(
    query: BenefitListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<CompanyBenefitsSinglePage, CompanyBenefit> {
    return this._client.getAPIList('/employer/benefits', SinglePage<CompanyBenefit>, {
      query,
      ...options,
      __security: { bearerAuth: true },
    });
  }

  /**
   * Get deductions metadata
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const supportedBenefit of client.hris.benefits.listSupportedBenefits()) {
   *   // ...
   * }
   * ```
   */
  listSupportedBenefits(
    query: BenefitListSupportedBenefitsParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<SupportedBenefitsSinglePage, SupportedBenefit> {
    return this._client.getAPIList('/employer/benefits/meta', SinglePage<SupportedBenefit>, {
      query,
      ...options,
      __security: { bearerAuth: true },
    });
  }

  /**
   * Register existing benefits from the customer on the provider, on Finch's end.
   * Please use the `/provider` endpoint to view available types for each provider.
   *
   * @example
   * ```ts
   * const registerCompanyBenefitResponse =
   *   await client.hris.benefits.register();
   * ```
   */
  register(
    params: BenefitRegisterParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<RegisterCompanyBenefitResponse> {
    const { entity_ids, ...body } = params ?? {};
    return this._client.post('/employer/benefits/register', {
      query: { entity_ids },
      body,
      ...options,
      __security: { bearerAuth: true },
    });
  }
}

export type CompanyBenefitsSinglePage = SinglePage<CompanyBenefit>;

export type SupportedBenefitsSinglePage = SinglePage<SupportedBenefit>;

export type BenefitContribution =
  | BenefitContribution.BenefitContributionFixed
  | BenefitContribution.BenefitContributionPercent
  | BenefitContribution.BenefitContributionTiered;

export namespace BenefitContribution {
  export interface BenefitContributionFixed {
    /**
     * Contribution amount in cents.
     */
    amount: number;

    /**
     * Fixed contribution type.
     */
    type: 'fixed';
  }

  export interface BenefitContributionPercent {
    /**
     * Contribution amount in basis points (1/100th of a percent).
     */
    amount: number;

    /**
     * Percentage contribution type.
     */
    type: 'percent';
  }

  export interface BenefitContributionTiered {
    /**
     * Array of tier objects defining employer match tiers based on employee
     * contribution thresholds.
     */
    tiers: Array<BenefitContributionTiered.Tier>;

    /**
     * Tiered contribution type (only valid for company_contribution).
     */
    type: 'tiered';
  }

  export namespace BenefitContributionTiered {
    export interface Tier {
      match: number;

      threshold: number;
    }
  }
}

export interface BenefitFeaturesAndOperations {
  supported_features?: SupportedBenefit;

  supported_operations?: SupportPerBenefitType;
}

/**
 * The frequency of the benefit deduction/contribution.
 */
export type BenefitFrequency = 'every_paycheck' | 'monthly' | 'one_time' | null;

/**
 * Type of benefit.
 */
export type BenefitType =
  | '457'
  | '401k'
  | '401k_roth'
  | '401k_loan'
  | '403b'
  | '403b_roth'
  | '457_roth'
  | 'commuter'
  | 'custom_post_tax'
  | 'custom_pre_tax'
  | 'fsa_dependent_care'
  | 'fsa_medical'
  | 'hsa_post'
  | 'hsa_pre'
  | 's125_dental'
  | 's125_medical'
  | 's125_vision'
  | 'simple'
  | 'simple_ira'
  | null;

/**
 * Each benefit type and their supported features. If the benefit type is not
 * supported, the property will be null
 */
export interface BenefitsSupport {
  commuter?: BenefitFeaturesAndOperations | null;

  custom_post_tax?: BenefitFeaturesAndOperations | null;

  custom_pre_tax?: BenefitFeaturesAndOperations | null;

  fsa_dependent_care?: BenefitFeaturesAndOperations | null;

  fsa_medical?: BenefitFeaturesAndOperations | null;

  hsa_post?: BenefitFeaturesAndOperations | null;

  hsa_pre?: BenefitFeaturesAndOperations | null;

  s125_dental?: BenefitFeaturesAndOperations | null;

  s125_medical?: BenefitFeaturesAndOperations | null;

  s125_vision?: BenefitFeaturesAndOperations | null;

  simple?: BenefitFeaturesAndOperations | null;

  simple_ira?: BenefitFeaturesAndOperations | null;

  [k: string]: BenefitFeaturesAndOperations | null | undefined;
}

export interface CompanyBenefit {
  /**
   * The id of the benefit.
   */
  benefit_id: string;

  description: string | null;

  /**
   * The frequency of the benefit deduction/contribution.
   */
  frequency: BenefitFrequency | null;

  /**
   * Type of benefit.
   */
  type: BenefitType | null;

  /**
   * The company match for this benefit.
   */
  company_contribution?: CompanyBenefit.CompanyContribution | null;
}

export namespace CompanyBenefit {
  /**
   * The company match for this benefit.
   */
  export interface CompanyContribution {
    tiers: Array<CompanyContribution.Tier>;

    type: 'match';
  }

  export namespace CompanyContribution {
    export interface Tier {
      match: number;

      threshold: number;
    }
  }
}

export interface CreateCompanyBenefitsResponse {
  /**
   * The id of the benefit.
   */
  benefit_id: string;

  job_id: string;
}

export interface RegisterCompanyBenefitResponse {
  /**
   * The id of the benefit.
   */
  benefit_id: string;

  job_id: string;
}

export interface SupportPerBenefitType {
  company_benefits?: Shared.OperationSupportMatrix;

  individual_benefits?: Shared.OperationSupportMatrix;
}

export interface SupportedBenefit {
  /**
   * Whether the provider supports an annual maximum for this benefit.
   */
  annual_maximum: boolean | null;

  /**
   * Supported contribution types. An empty array indicates contributions are not
   * supported.
   */
  company_contribution: Array<'fixed' | 'percent' | 'tiered' | null> | null;

  description: string | null;

  /**
   * Supported deduction types. An empty array indicates deductions are not
   * supported.
   */
  employee_deduction: Array<'fixed' | 'percent' | null> | null;

  /**
   * The list of frequencies supported by the provider for this benefit
   */
  frequencies: Array<BenefitFrequency | null>;

  /**
   * Whether the provider supports catch up for this benefit. This field will only be
   * true for retirement benefits.
   */
  catch_up?: boolean | null;

  /**
   * Whether the provider supports HSA contribution limits. Empty if this feature is
   * not supported for the benefit. This array only has values for HSA benefits.
   */
  hsa_contribution_limit?: Array<'family' | 'individual' | null> | null;
}

export interface UpdateCompanyBenefitResponse {
  /**
   * The id of the benefit.
   */
  benefit_id: string;

  job_id: string;
}

/**
 * @deprecated use `BenefitContribution` instead
 */
export type BenfitContribution = BenefitContribution | null;

export interface BenefitCreateParams {
  /**
   * Query param: The entity IDs to specify which entities' data to access.
   */
  entity_ids?: Array<string>;

  /**
   * Body param: The company match for this benefit.
   */
  company_contribution?: BenefitCreateParams.CompanyContribution | null;

  /**
   * Body param: 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).
   */
  description?: string;

  /**
   * Body param: The frequency of the benefit deduction/contribution.
   */
  frequency?: BenefitFrequency | null;

  /**
   * Body param: Type of benefit.
   */
  type?: BenefitType | null;
}

export namespace BenefitCreateParams {
  /**
   * The company match for this benefit.
   */
  export interface CompanyContribution {
    tiers: Array<CompanyContribution.Tier>;

    type: 'match';
  }

  export namespace CompanyContribution {
    export interface Tier {
      match: number;

      threshold: number;
    }
  }
}

export interface BenefitRetrieveParams {
  /**
   * The entity IDs to specify which entities' data to access.
   */
  entity_ids?: Array<string>;
}

export interface BenefitUpdateParams {
  /**
   * Query param: The entity IDs to specify which entities' data to access.
   */
  entity_ids?: Array<string>;

  /**
   * Body param: Updated name or description.
   */
  description?: string;
}

export interface BenefitListParams {
  /**
   * The entity IDs to specify which entities' data to access.
   */
  entity_ids?: Array<string>;
}

export interface BenefitListSupportedBenefitsParams {
  /**
   * The entity IDs to specify which entities' data to access.
   */
  entity_ids?: Array<string>;
}

export interface BenefitRegisterParams {
  /**
   * Query param: The entity IDs to specify which entities' data to access.
   */
  entity_ids?: Array<string>;

  /**
   * Body param
   */
  description?: string;

  /**
   * Body param: The frequency of the benefit deduction/contribution.
   */
  frequency?: BenefitFrequency | null;

  /**
   * Body param: Type of benefit.
   */
  type?: BenefitType | null;
}

Benefits.Individuals = Individuals;

export declare namespace Benefits {
  export {
    type BenefitContribution as BenefitContribution,
    type BenefitFeaturesAndOperations as BenefitFeaturesAndOperations,
    type BenefitFrequency as BenefitFrequency,
    type BenefitType as BenefitType,
    type BenefitsSupport as BenefitsSupport,
    type CompanyBenefit as CompanyBenefit,
    type CreateCompanyBenefitsResponse as CreateCompanyBenefitsResponse,
    type RegisterCompanyBenefitResponse as RegisterCompanyBenefitResponse,
    type SupportPerBenefitType as SupportPerBenefitType,
    type SupportedBenefit as SupportedBenefit,
    type UpdateCompanyBenefitResponse as UpdateCompanyBenefitResponse,
    type BenfitContribution as BenfitContribution,
    type CompanyBenefitsSinglePage as CompanyBenefitsSinglePage,
    type SupportedBenefitsSinglePage as SupportedBenefitsSinglePage,
    type BenefitCreateParams as BenefitCreateParams,
    type BenefitRetrieveParams as BenefitRetrieveParams,
    type BenefitUpdateParams as BenefitUpdateParams,
    type BenefitListParams as BenefitListParams,
    type BenefitListSupportedBenefitsParams as BenefitListSupportedBenefitsParams,
    type BenefitRegisterParams as BenefitRegisterParams,
  };

  export {
    Individuals as Individuals,
    type EnrolledIndividualBenefitResponse as EnrolledIndividualBenefitResponse,
    type IndividualBenefit as IndividualBenefit,
    type UnenrolledIndividualBenefitResponse as UnenrolledIndividualBenefitResponse,
    type IndividualEnrolledIDsResponse as IndividualEnrolledIDsResponse,
    type IndividualBenefitsSinglePage as IndividualBenefitsSinglePage,
    type IndividualEnrollManyParams as IndividualEnrollManyParams,
    type IndividualEnrolledIDsParams as IndividualEnrolledIDsParams,
    type IndividualRetrieveManyBenefitsParams as IndividualRetrieveManyBenefitsParams,
    type IndividualUnenrollManyParams as IndividualUnenrollManyParams,
  };
}