release: 10.2.0

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: '22'
+          node-version: '24'
 
       - name: Bootstrap
         run: ./scripts/bootstrap
@@ -48,7 +48,7 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: '22'
+          node-version: '24'
 
       - name: Bootstrap
         run: ./scripts/bootstrap
@@ -96,7 +96,7 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: '22'
+          node-version: '24'
 
       - name: Bootstrap
         run: ./scripts/bootstrap

.github/workflows/publish-npm.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@3235b876344d2a9aa001b8d1453c930bba69e610 # v3.9.1
         with:
-          node-version: '20'
+          node-version: '24'
 
       - name: Install dependencies
         run: |

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "10.1.1"
+  ".": "10.2.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 48
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch/finch-3cd1346947fabfca2aa9c6f821170c8d945a82667fb20a15644d5c77f8e98c10.yml
-openapi_spec_hash: 642e04e90d37c0e4875d154abd06eb54
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch/finch-a6b05e51c46366a54466c2009f5fdde74e0fa40bbcc6568601a4e3342dd16937.yml
+openapi_spec_hash: 084797c220144df17d98eb984dd4cba2
 config_hash: 9ae56f40cec7304896138bfad5caf748

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 10.2.0 (2026-07-13)
+
+Full Changelog: [v10.1.1...v10.2.0](https://github.com/Finch-API/finch-api-node/compare/v10.1.1...v10.2.0)
+
+### Features
+
+* **api:** api update ([08ac7b8](https://github.com/Finch-API/finch-api-node/commit/08ac7b8f028ebc199b3adcb4de3d71702ca3e92c))
+
+
+### Bug Fixes
+
+* **ci:** bump @arethetypeswrong/cli to ^0.18.0 and run CI workflows on Node 24 ([eba627c](https://github.com/Finch-API/finch-api-node/commit/eba627cb871da059cce759df9ee810424af09fd1))
+
 ## 10.1.1 (2026-07-10)
 
 Full Changelog: [v10.1.0...v10.1.1](https://github.com/Finch-API/finch-api-node/compare/v10.1.0...v10.1.1)

MIGRATION.md

@@ -97,7 +97,6 @@ client.example.list(undefined, { headers: { ... } });
 - `client.hris.payStatementItem.rules.delete()`
 - `client.hris.directory.list()`
 - `client.hris.directory.listIndividuals()`
-- `client.hris.individuals.retrieveMany()`
 - `client.hris.documents.list()`
 - `client.hris.documents.retreive()`
 - `client.hris.benefits.create()`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryfinch/finch-api",
-  "version": "10.1.1",
+  "version": "10.2.0",
   "description": "The official TypeScript library for the Finch API",
   "author": "Finch <founders@tryfinch.com>",
   "types": "dist/index.d.ts",
@@ -30,7 +30,7 @@
     "@noble/hashes": "^1.5.0"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.17.0",
+    "@arethetypeswrong/cli": "^0.18.0",
     "@swc/core": "^1.3.102",
     "@swc/jest": "^0.2.29",
     "@types/jest": "^29.4.0",

packages/mcp-server/manifest.json

@@ -1,7 +1,7 @@
 {
   "dxt_version": "0.2",
   "name": "@tryfinch/finch-api-mcp",
-  "version": "10.1.1",
+  "version": "10.2.0",
   "description": "The official MCP Server for the Finch API",
   "author": {
     "name": "Finch",

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryfinch/finch-api-mcp",
-  "version": "10.1.1",
+  "version": "10.2.0",
   "description": "The official MCP Server for the Finch API",
   "author": "Finch <founders@tryfinch.com>",
   "types": "dist/index.d.ts",

packages/mcp-server/src/server.ts

@@ -29,7 +29,7 @@ export const newMcpServer = async ({
   new McpServer(
     {
       name: 'tryfinch_finch_api_api',
-      version: '10.1.1',
+      version: '10.2.0',
     },
     {
       instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }),

src/resources/hris/employments.ts

@@ -215,7 +215,7 @@ export interface EmploymentDataResponse {
 
 export interface EmploymentRetrieveManyParams {
   /**
-   * Body param: The array of batch requests.
+   * Body param: The array of batch requests. Maximum 10000 items per request.
    */
   requests: Array<EmploymentRetrieveManyParams.Request>;
 
@@ -228,9 +228,7 @@ export interface EmploymentRetrieveManyParams {
 export namespace EmploymentRetrieveManyParams {
   export interface Request {
     /**
-     * A stable Finch `id` (UUID v4) for an individual in the company. There is no
-     * limit to the number of `individual_id` to send per request. It is preferantial
-     * to send all ids in a single request for Finch to optimize provider rate-limits.
+     * A stable Finch `id` (UUID v4) for an individual in the company.
      */
     individual_id: string;
   }

src/resources/hris/individuals.ts

@@ -12,16 +12,18 @@ export class Individuals extends APIResource {
    * @example
    * ```ts
    * // Automatically fetches more pages as needed.
-   * for await (const individualResponse of client.hris.individuals.retrieveMany()) {
+   * for await (const individualResponse of client.hris.individuals.retrieveMany(
+   *   { requests: [{ individual_id: 'individual_id' }] },
+   * )) {
    *   // ...
    * }
    * ```
    */
   retrieveMany(
-    params: IndividualRetrieveManyParams | null | undefined = {},
+    params: IndividualRetrieveManyParams,
     options?: RequestOptions,
   ): PagePromise<IndividualResponsesPage, IndividualResponse> {
-    const { entity_ids, ...body } = params ?? {};
+    const { entity_ids, ...body } = params;
     return this._client.getAPIList('/employer/individual', ResponsesPage<IndividualResponse>, {
       query: { entity_ids },
       body,
@@ -141,28 +143,28 @@ export interface IndividualResponse {
 
 export interface IndividualRetrieveManyParams {
   /**
-   * Query param: The entity IDs to specify which entities' data to access.
+   * Body param: The array of batch requests. Maximum 10000 items per request.
    */
-  entity_ids?: Array<string>;
+  requests: Array<IndividualRetrieveManyParams.Request>;
 
   /**
-   * Body param
+   * Query param: The entity IDs to specify which entities' data to access.
    */
-  options?: IndividualRetrieveManyParams.Options | null;
+  entity_ids?: Array<string>;
 
   /**
    * Body param
    */
-  requests?: Array<IndividualRetrieveManyParams.Request>;
+  options?: IndividualRetrieveManyParams.Options | null;
 }
 
 export namespace IndividualRetrieveManyParams {
-  export interface Options {
-    include?: Array<string>;
+  export interface Request {
+    individual_id: string;
   }
 
-  export interface Request {
-    individual_id?: string;
+  export interface Options {
+    include?: Array<string>;
   }
 }
 

src/resources/hris/pay-statements.ts

@@ -20,7 +20,9 @@ export class PayStatements extends APIResource {
    *   {
    *     requests: [
    *       {
-   *         payment_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *         payment_id: 'fc8b024e-d373-4c9c-80fc-f1625383d142',
+   *         limit: 100,
+   *         offset: 0,
    *       },
    *     ],
    *   },
@@ -313,7 +315,7 @@ export namespace PayStatementResponse {
 
 export interface PayStatementRetrieveManyParams {
   /**
-   * Body param: The array of batch requests.
+   * Body param: The array of batch requests. Maximum 10 payment_ids per request.
    */
   requests: Array<PayStatementRetrieveManyParams.Request>;
 
@@ -331,7 +333,7 @@ export namespace PayStatementRetrieveManyParams {
     payment_id: string;
 
     /**
-     * Number of pay statements to return (defaults to all).
+     * Number of pay statements to return (defaults to 100, maximum 5000).
      */
     limit?: number;
 

src/version.ts

@@ -1 +1 @@
-export const VERSION = '10.1.1'; // x-release-please-version
+export const VERSION = '10.2.0'; // x-release-please-version

tests/api-resources/hris/directory.test.ts

@@ -27,7 +27,7 @@ describe('resource directory', () => {
       client.hris.directory.list(
         {
           entity_ids: ['550e8400-e29b-41d4-a716-446655440000'],
-          limit: 0,
+          limit: 10000,
           offset: 0,
         },
         { path: '/_stainless_unknown_path' },
@@ -52,7 +52,7 @@ describe('resource directory', () => {
       client.hris.directory.listIndividuals(
         {
           entity_ids: ['550e8400-e29b-41d4-a716-446655440000'],
-          limit: 0,
+          limit: 10000,
           offset: 0,
         },
         { path: '/_stainless_unknown_path' },

tests/api-resources/hris/individuals.test.ts

@@ -10,8 +10,10 @@ const client = new Finch({
 });
 
 describe('resource individuals', () => {
-  test('retrieveMany', async () => {
-    const responsePromise = client.hris.individuals.retrieveMany();
+  test('retrieveMany: only required params', async () => {
+    const responsePromise = client.hris.individuals.retrieveMany({
+      requests: [{ individual_id: 'individual_id' }],
+    });
     const rawResponse = await responsePromise.asResponse();
     expect(rawResponse).toBeInstanceOf(Response);
     const response = await responsePromise;
@@ -21,17 +23,11 @@ describe('resource individuals', () => {
     expect(dataAndResponse.response).toBe(rawResponse);
   });
 
-  test('retrieveMany: request options and params are passed correctly', async () => {
-    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
-    await expect(
-      client.hris.individuals.retrieveMany(
-        {
-          entity_ids: ['550e8400-e29b-41d4-a716-446655440000'],
-          options: { include: ['string'] },
-          requests: [{ individual_id: 'individual_id' }],
-        },
-        { path: '/_stainless_unknown_path' },
-      ),
-    ).rejects.toThrow(Finch.NotFoundError);
+  test('retrieveMany: required and optional params', async () => {
+    const response = await client.hris.individuals.retrieveMany({
+      requests: [{ individual_id: 'individual_id' }],
+      entity_ids: ['550e8400-e29b-41d4-a716-446655440000'],
+      options: { include: ['string'] },
+    });
   });
 });

tests/api-resources/hris/pay-statements.test.ts

@@ -12,7 +12,7 @@ const client = new Finch({
 describe('resource payStatements', () => {
   test('retrieveMany: only required params', async () => {
     const responsePromise = client.hris.payStatements.retrieveMany({
-      requests: [{ payment_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }],
+      requests: [{ payment_id: 'fc8b024e-d373-4c9c-80fc-f1625383d142' }],
     });
     const rawResponse = await responsePromise.asResponse();
     expect(rawResponse).toBeInstanceOf(Response);
@@ -27,8 +27,8 @@ describe('resource payStatements', () => {
     const response = await client.hris.payStatements.retrieveMany({
       requests: [
         {
-          payment_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-          limit: 50,
+          payment_id: 'fc8b024e-d373-4c9c-80fc-f1625383d142',
+          limit: 100,
           offset: 0,
         },
       ],