@tryfinch/finch-api 6.31.0 → 8.0.0

package/src/resources/hris/benefits/benefits.ts

@@ -1,23 +1,24 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from "../../../resource.js";
-import { isRequestOptions } from "../../../core.js";
-import * as Core from "../../../core.js";
-import * as BenefitsAPI from "./benefits.js";
-import * as Shared from "../../shared.js";
-import * as IndividualsAPI from "./individuals.js";
+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.js";
-import { SinglePage } from "../../../pagination.js";
+} 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);
@@ -33,18 +34,11 @@ export class Benefits extends APIResource {
    * ```
    */
   create(
-    body?: BenefitCreateParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<CreateCompanyBenefitsResponse>;
-  create(options?: Core.RequestOptions): Core.APIPromise<CreateCompanyBenefitsResponse>;
-  create(
-    body: BenefitCreateParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<CreateCompanyBenefitsResponse> {
-    if (isRequestOptions(body)) {
-      return this.create({}, body);
-    }
-    return this._client.post('/employer/benefits', { body, ...options });
+    params: BenefitCreateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<CreateCompanyBenefitsResponse> {
+    const { entity_ids, ...body } = params ?? {};
+    return this._client.post('/employer/benefits', { query: { entity_ids }, body, ...options });
   }
 
   /**
@@ -57,8 +51,12 @@ export class Benefits extends APIResource {
    * );
    * ```
    */
-  retrieve(benefitId: string, options?: Core.RequestOptions): Core.APIPromise<CompanyBenefit> {
-    return this._client.get(`/employer/benefits/${benefitId}`, options);
+  retrieve(
+    benefitID: string,
+    query: BenefitRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<CompanyBenefit> {
+    return this._client.get(path`/employer/benefits/${benefitID}`, { query, ...options });
   }
 
   /**
@@ -71,20 +69,16 @@ export class Benefits extends APIResource {
    * ```
    */
   update(
-    benefitId: string,
-    body?: BenefitUpdateParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<UpdateCompanyBenefitResponse>;
-  update(benefitId: string, options?: Core.RequestOptions): Core.APIPromise<UpdateCompanyBenefitResponse>;
-  update(
-    benefitId: string,
-    body: BenefitUpdateParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<UpdateCompanyBenefitResponse> {
-    if (isRequestOptions(body)) {
-      return this.update(benefitId, {}, body);
-    }
-    return this._client.post(`/employer/benefits/${benefitId}`, { body, ...options });
+    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,
+    });
   }
 
   /**
@@ -98,8 +92,11 @@ export class Benefits extends APIResource {
    * }
    * ```
    */
-  list(options?: Core.RequestOptions): Core.PagePromise<CompanyBenefitsSinglePage, CompanyBenefit> {
-    return this._client.getAPIList('/employer/benefits', CompanyBenefitsSinglePage, options);
+  list(
+    query: BenefitListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CompanyBenefitsSinglePage, CompanyBenefit> {
+    return this._client.getAPIList('/employer/benefits', SinglePage<CompanyBenefit>, { query, ...options });
   }
 
   /**
@@ -108,112 +105,112 @@ export class Benefits extends APIResource {
    * @example
    * ```ts
    * // Automatically fetches more pages as needed.
-   * for await (const benefitListSupportedBenefitsResponse of client.hris.benefits.listSupportedBenefits()) {
+   * for await (const supportedBenefit of client.hris.benefits.listSupportedBenefits()) {
    *   // ...
    * }
    * ```
    */
   listSupportedBenefits(
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<BenefitListSupportedBenefitsResponsesSinglePage, BenefitListSupportedBenefitsResponse> {
-    return this._client.getAPIList(
-      '/employer/benefits/meta',
-      BenefitListSupportedBenefitsResponsesSinglePage,
-      options,
-    );
+    query: BenefitListSupportedBenefitsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<SupportedBenefitsSinglePage, SupportedBenefit> {
+    return this._client.getAPIList('/employer/benefits/meta', SinglePage<SupportedBenefit>, {
+      query,
+      ...options,
+    });
   }
 }
 
-export class CompanyBenefitsSinglePage extends SinglePage<CompanyBenefit> {}
-
-export class BenefitListSupportedBenefitsResponsesSinglePage extends SinglePage<BenefitListSupportedBenefitsResponse> {}
-
-export interface BenefitContribution {
-  /**
-   * Contribution amount in cents (if `fixed`) or basis points (if `percent`).
-   */
-  amount?: number | null;
-
-  /**
-   * Contribution type.
-   */
-  type?: 'fixed' | 'percent' | null;
-}
+export type CompanyBenefitsSinglePage = SinglePage<CompanyBenefit>;
 
-export interface BenefitFeaturesAndOperations {
-  supported_features?: BenefitFeaturesAndOperations.SupportedFeatures;
+export type SupportedBenefitsSinglePage = SinglePage<SupportedBenefit>;
 
-  supported_operations?: SupportPerBenefitType;
-}
+export type BenefitContribution =
+  | BenefitContribution.UnionMember0
+  | BenefitContribution.UnionMember1
+  | BenefitContribution.UnionMember2;
 
-export namespace BenefitFeaturesAndOperations {
-  export interface SupportedFeatures {
+export namespace BenefitContribution {
+  export interface UnionMember0 {
     /**
-     * Whether the provider supports an annual maximum for this benefit.
+     * Contribution amount in cents.
      */
-    annual_maximum?: boolean | null;
+    amount: number;
 
     /**
-     * Whether the provider supports catch up for this benefit. This field will only be
-     * true for retirement benefits.
+     * Fixed contribution type.
      */
-    catch_up?: boolean | null;
+    type: 'fixed';
+  }
 
+  export interface UnionMember1 {
     /**
-     * Supported contribution types. An empty array indicates contributions are not
-     * supported.
+     * Contribution amount in basis points (1/100th of a percent).
      */
-    company_contribution?: Array<'fixed' | 'percent' | null> | null;
-
-    description?: string | null;
+    amount: number;
 
     /**
-     * Supported deduction types. An empty array indicates deductions are not
-     * supported.
+     * Percentage contribution type.
      */
-    employee_deduction?: Array<'fixed' | 'percent' | null> | null;
+    type: 'percent';
+  }
 
+  export interface UnionMember2 {
     /**
-     * The list of frequencies supported by the provider for this benefit
+     * Array of tier objects defining employer match tiers based on employee
+     * contribution thresholds.
      */
-    frequencies?: Array<BenefitsAPI.BenefitFrequency | null>;
+    tiers: Array<UnionMember2.Tier>;
 
     /**
-     * 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.
+     * Tiered contribution type (only valid for company_contribution).
      */
-    hsa_contribution_limit?: Array<'individual' | 'family' | null> | null;
+    type: 'tiered';
+  }
+
+  export namespace UnionMember2 {
+    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 = 'one_time' | 'every_paycheck' | 'monthly' | null;
+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'
   | '457_roth'
-  | 's125_medical'
-  | 's125_dental'
-  | 's125_vision'
-  | 'hsa_pre'
-  | 'hsa_post'
-  | 'fsa_medical'
-  | 'fsa_dependent_care'
-  | 'simple_ira'
-  | 'simple'
   | '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;
 
 /**
@@ -254,11 +251,6 @@ export interface CompanyBenefit {
    */
   benefit_id: string;
 
-  /**
-   * The company match for this benefit.
-   */
-  company_contribution: CompanyBenefit.CompanyContribution | null;
-
   description: string | null;
 
   /**
@@ -270,6 +262,11 @@ export interface CompanyBenefit {
    * Type of benefit.
    */
   type: BenefitType | null;
+
+  /**
+   * The company match for this benefit.
+   */
+  company_contribution?: CompanyBenefit.CompanyContribution | null;
 }
 
 export namespace CompanyBenefit {
@@ -277,16 +274,16 @@ export namespace CompanyBenefit {
    * The company match for this benefit.
    */
   export interface CompanyContribution {
-    tiers?: Array<CompanyContribution.Tier>;
+    tiers: Array<CompanyContribution.Tier>;
 
-    type?: 'match';
+    type: 'match';
   }
 
   export namespace CompanyContribution {
     export interface Tier {
-      match?: number;
+      match: number;
 
-      threshold?: number;
+      threshold: number;
     }
   }
 }
@@ -310,38 +307,38 @@ export interface SupportedBenefit {
   /**
    * Whether the provider supports an annual maximum for this benefit.
    */
-  annual_maximum?: boolean | null;
-
-  /**
-   * Whether the provider supports catch up for this benefit. This field will only be
-   * true for retirement benefits.
-   */
-  catch_up?: boolean | null;
+  annual_maximum: boolean | null;
 
   /**
    * Supported contribution types. An empty array indicates contributions are not
    * supported.
    */
-  company_contribution?: Array<'fixed' | 'percent' | null> | null;
+  company_contribution: Array<'fixed' | 'percent' | 'tiered' | null> | null;
 
-  description?: string | null;
+  description: string | null;
 
   /**
    * Supported deduction types. An empty array indicates deductions are not
    * supported.
    */
-  employee_deduction?: Array<'fixed' | 'percent' | null> | null;
+  employee_deduction: Array<'fixed' | 'percent' | null> | null;
 
   /**
    * The list of frequencies supported by the provider for this benefit
    */
-  frequencies?: Array<BenefitFrequency | null>;
+  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<'individual' | 'family' | null> | null;
+  hsa_contribution_limit?: Array<'family' | 'individual' | null> | null;
 }
 
 export interface UpdateCompanyBenefitResponse {
@@ -353,44 +350,6 @@ export interface UpdateCompanyBenefitResponse {
   job_id: string;
 }
 
-export interface BenefitListSupportedBenefitsResponse {
-  /**
-   * Whether the provider supports an annual maximum for this benefit.
-   */
-  annual_maximum?: boolean | null;
-
-  /**
-   * Whether the provider supports catch up for this benefit. This field will only be
-   * true for retirement benefits.
-   */
-  catch_up?: boolean | null;
-
-  /**
-   * Supported contribution types. An empty array indicates contributions are not
-   * supported.
-   */
-  company_contribution?: Array<'fixed' | 'percent' | 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 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<'individual' | 'family' | null> | null;
-}
-
 /**
  * @deprecated use `BenefitContribution` instead
  */
@@ -398,24 +357,29 @@ export type BenfitContribution = BenefitContribution | null;
 
 export interface BenefitCreateParams {
   /**
-   * The company match for this benefit.
+   * 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;
 
   /**
-   * 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).
+   * 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;
 
   /**
-   * The frequency of the benefit deduction/contribution.
+   * Body param: The frequency of the benefit deduction/contribution.
    */
   frequency?: BenefitFrequency | null;
 
   /**
-   * Type of benefit.
+   * Body param: Type of benefit.
    */
   type?: BenefitType | null;
 }
@@ -425,31 +389,54 @@ export namespace BenefitCreateParams {
    * The company match for this benefit.
    */
   export interface CompanyContribution {
-    tiers?: Array<CompanyContribution.Tier>;
+    tiers: Array<CompanyContribution.Tier>;
 
-    type?: 'match';
+    type: 'match';
   }
 
   export namespace CompanyContribution {
     export interface Tier {
-      match?: number;
+      match: number;
 
-      threshold?: number;
+      threshold: number;
     }
   }
 }
 
+export interface BenefitRetrieveParams {
+  /**
+   * The entity IDs to specify which entities' data to access.
+   */
+  entity_ids?: Array<string>;
+}
+
 export interface BenefitUpdateParams {
   /**
-   * Updated name or description.
+   * Query param: The entity IDs to specify which entities' data to access.
+   */
+  entity_ids?: Array<string>;
+
+  /**
+   * Body param: Updated name or description.
    */
   description?: string;
 }
 
-Benefits.CompanyBenefitsSinglePage = CompanyBenefitsSinglePage;
-Benefits.BenefitListSupportedBenefitsResponsesSinglePage = BenefitListSupportedBenefitsResponsesSinglePage;
+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>;
+}
+
 Benefits.Individuals = Individuals;
-Benefits.IndividualBenefitsSinglePage = IndividualBenefitsSinglePage;
 
 export declare namespace Benefits {
   export {
@@ -463,12 +450,14 @@ export declare namespace Benefits {
     type SupportPerBenefitType as SupportPerBenefitType,
     type SupportedBenefit as SupportedBenefit,
     type UpdateCompanyBenefitResponse as UpdateCompanyBenefitResponse,
-    type BenefitListSupportedBenefitsResponse as BenefitListSupportedBenefitsResponse,
     type BenfitContribution as BenfitContribution,
-    CompanyBenefitsSinglePage as CompanyBenefitsSinglePage,
-    BenefitListSupportedBenefitsResponsesSinglePage as BenefitListSupportedBenefitsResponsesSinglePage,
+    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,
   };
 
   export {
@@ -477,8 +466,9 @@ export declare namespace Benefits {
     type IndividualBenefit as IndividualBenefit,
     type UnenrolledIndividualBenefitResponse as UnenrolledIndividualBenefitResponse,
     type IndividualEnrolledIDsResponse as IndividualEnrolledIDsResponse,
-    IndividualBenefitsSinglePage as IndividualBenefitsSinglePage,
+    type IndividualBenefitsSinglePage as IndividualBenefitsSinglePage,
     type IndividualEnrollManyParams as IndividualEnrollManyParams,
+    type IndividualEnrolledIDsParams as IndividualEnrolledIDsParams,
     type IndividualRetrieveManyBenefitsParams as IndividualRetrieveManyBenefitsParams,
     type IndividualUnenrollManyParams as IndividualUnenrollManyParams,
   };

package/src/resources/hris/benefits/index.ts

@@ -1,8 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 export {
-  CompanyBenefitsSinglePage,
-  BenefitListSupportedBenefitsResponsesSinglePage,
   Benefits,
   type BenefitContribution,
   type BenefitFeaturesAndOperations,
@@ -14,19 +12,24 @@ export {
   type SupportPerBenefitType,
   type SupportedBenefit,
   type UpdateCompanyBenefitResponse,
-  type BenefitListSupportedBenefitsResponse,
   type BenfitContribution,
   type BenefitCreateParams,
+  type BenefitRetrieveParams,
   type BenefitUpdateParams,
-} from "./benefits.js";
+  type BenefitListParams,
+  type BenefitListSupportedBenefitsParams,
+  type CompanyBenefitsSinglePage,
+  type SupportedBenefitsSinglePage,
+} from './benefits';
 export {
-  IndividualBenefitsSinglePage,
   Individuals,
   type EnrolledIndividualBenefitResponse,
   type IndividualBenefit,
   type UnenrolledIndividualBenefitResponse,
   type IndividualEnrolledIDsResponse,
   type IndividualEnrollManyParams,
+  type IndividualEnrolledIDsParams,
   type IndividualRetrieveManyBenefitsParams,
   type IndividualUnenrollManyParams,
-} from "./individuals.js";
+  type IndividualBenefitsSinglePage,
+} from './individuals';