@tryfinch/finch-api 5.0.0 → 5.2.0

package/src/_shims/web-types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+export type Agent = any;
+
+declare const _fetch: typeof fetch;
+export { _fetch as fetch };
+
+type _Request = Request;
+export { _Request as Request };
+
+type _RequestInfo = RequestInfo;
+export { type _RequestInfo as RequestInfo };
+
+type _RequestInit = RequestInit;
+export { type _RequestInit as RequestInit };
+
+type _Response = Response;
+export { _Response as Response };
+
+type _ResponseInit = ResponseInit;
+export { type _ResponseInit as ResponseInit };
+
+type _ResponseType = ResponseType;
+export { type _ResponseType as ResponseType };
+
+type _BodyInit = BodyInit;
+export { type _BodyInit as BodyInit };
+
+type _Headers = Headers;
+export { _Headers as Headers };
+
+type _HeadersInit = HeadersInit;
+export { type _HeadersInit as HeadersInit };
+
+type EndingType = 'native' | 'transparent';
+
+export interface BlobPropertyBag {
+  endings?: EndingType;
+  type?: string;
+}
+
+export interface FilePropertyBag extends BlobPropertyBag {
+  lastModified?: number;
+}
+
+export type FileFromPathOptions = Omit<FilePropertyBag, 'lastModified'>;
+
+type _FormData = FormData;
+declare const _FormData: typeof FormData;
+export { _FormData as FormData };
+
+type _File = File;
+declare const _File: typeof File;
+export { _File as File };
+
+type _Blob = Blob;
+declare const _Blob: typeof Blob;
+export { _Blob as Blob };
+
+export declare class Readable {
+  readable: boolean;
+  readonly readableEnded: boolean;
+  readonly readableFlowing: boolean | null;
+  readonly readableHighWaterMark: number;
+  readonly readableLength: number;
+  readonly readableObjectMode: boolean;
+  destroyed: boolean;
+  read(size?: number): any;
+  pause(): this;
+  resume(): this;
+  isPaused(): boolean;
+  destroy(error?: Error): this;
+  [Symbol.asyncIterator](): AsyncIterableIterator<any>;
+}
+
+export declare class FsReadStream extends Readable {
+  path: {}; // node type is string | Buffer
+}
+
+type _ReadableStream<R = any> = ReadableStream<R>;
+export { type _ReadableStream as ReadableStream };

package/src/_shims/web-types.js

@@ -0,0 +1,3 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */

package/src/_shims/web-types.mjs

@@ -0,0 +1,3 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */

package/src/core.ts

@@ -1,15 +1,16 @@
 import { VERSION } from './version';
 import { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError } from './error';
-import type { Readable } from './_shims/node-readable';
-import { getDefaultAgent, type Agent } from './_shims/agent';
 import {
+  kind as shimsKind,
+  type Readable,
+  getDefaultAgent,
+  type Agent,
   fetch,
-  isPolyfilled as fetchIsPolyfilled,
   type RequestInfo,
   type RequestInit,
   type Response,
   type HeadersInit,
-} from './_shims/fetch.js';
+} from './_shims/index';
 export { type Response };
 import { isMultipartBody } from './uploads';
 export {
@@ -45,7 +46,7 @@ async function defaultParseResponse<T>(props: APIResponseProps): Promise<T> {
   // TODO handle blob, arraybuffer, other content types, etc.
   const text = await response.text();
   debug('response', response.status, response.url, response.headers, text);
-  return text as T;
+  return text as any as T;
 }
 
 /**
@@ -77,6 +78,12 @@ export class APIPromise<T> extends Promise<T> {
    *
    * If you want to parse the response body but still get the `Response`
    * instance, you can use {@link withResponse()}.
+   *
+   * 👋 Getting the wrong TypeScript type for `Response`?
+   * Try setting `"moduleResolution": "NodeNext"` if you can,
+   * or add one of these imports before your first `import … from '@tryfinch/finch-api'`:
+   * - `import '@tryfinch/finch-api/shims/node'` (if you're running on Node)
+   * - `import '@tryfinch/finch-api/shims/web'` (otherwise)
    */
   asResponse(): Promise<Response> {
     return this.responsePromise.then((p) => p.response);
@@ -86,6 +93,13 @@ export class APIPromise<T> extends Promise<T> {
    *
    * If you just want to get the raw `Response` instance without parsing it,
    * you can use {@link asResponse()}.
+   *
+   *
+   * 👋 Getting the wrong TypeScript type for `Response`?
+   * Try setting `"moduleResolution": "NodeNext"` if you can,
+   * or add one of these imports before your first `import … from '@tryfinch/finch-api'`:
+   * - `import '@tryfinch/finch-api/shims/node'` (if you're running on Node)
+   * - `import '@tryfinch/finch-api/shims/web'` (otherwise)
    */
   async withResponse(): Promise<{ data: T; response: Response }> {
     const [data, response] = await Promise.all([this.parse(), this.asResponse()]);
@@ -270,7 +284,7 @@ export abstract class APIClient {
       ...headers,
     };
     // let builtin fetch set the Content-Type for multipart bodies
-    if (isMultipartBody(options.body) && !fetchIsPolyfilled) {
+    if (isMultipartBody(options.body) && shimsKind !== 'node') {
       delete reqHeaders['Content-Type'];
     }
 
@@ -306,7 +320,8 @@ export abstract class APIClient {
   protected parseHeaders(headers: HeadersInit | null | undefined): Record<string, string> {
     return (
       !headers ? {}
-      : Symbol.iterator in headers ? Object.fromEntries(Array.from(headers).map((header) => [...header]))
+      : Symbol.iterator in headers ?
+        Object.fromEntries(Array.from(headers as Iterable<string[]>).map((header) => [...header]))
       : { ...headers }
     );
   }
@@ -369,7 +384,7 @@ export abstract class APIClient {
         return this.retryRequest(options, retriesRemaining, responseHeaders);
       }
 
-      const errText = await response.text().catch(() => 'Unknown');
+      const errText = await response.text().catch((e) => castToError(e).message);
       const errJSON = safeJSON(errText);
       const errMessage = errJSON ? undefined : errText;
 
@@ -390,7 +405,7 @@ export abstract class APIClient {
     return new PagePromise<PageClass, Item>(this, request, Page);
   }
 
-  buildURL<Req>(path: string, query: Req | undefined): string {
+  buildURL<Req extends Record<string, unknown>>(path: string, query: Req | null | undefined): string {
     const url =
       isAbsoluteURL(path) ?
         new URL(path)
@@ -436,11 +451,14 @@ export abstract class APIClient {
 
     const timeout = setTimeout(() => controller.abort(), ms);
 
-    return this.getRequestClient()
-      .fetch(url, { signal: controller.signal as any, ...options })
-      .finally(() => {
-        clearTimeout(timeout);
-      });
+    return (
+      this.getRequestClient()
+        // use undefined this binding; fetch errors if bound to something else in browser/cloudflare
+        .fetch.call(undefined, url, { signal: controller.signal as any, ...options })
+        .finally(() => {
+          clearTimeout(timeout);
+        })
+    );
   }
 
   protected getRequestClient(): RequestClient {
@@ -455,6 +473,9 @@ export abstract class APIClient {
     if (shouldRetryHeader === 'true') return true;
     if (shouldRetryHeader === 'false') return false;
 
+    // Retry on request timeouts.
+    if (response.status === 408) return true;
+
     // Retry on lock timeouts.
     if (response.status === 409) return true;
 
@@ -581,7 +602,7 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
     } else if ('url' in nextInfo) {
       const params = [...Object.entries(nextOptions.query || {}), ...nextInfo.url.searchParams.entries()];
       for (const [key, value] of params) {
-        nextInfo.url.searchParams.set(key, value);
+        nextInfo.url.searchParams.set(key, value as any);
       }
       nextOptions.query = undefined;
       nextOptions.path = nextInfo.url.toString();
@@ -707,7 +728,7 @@ const requestOptionsKeys: KeysEnum<RequestOptions> = {
   idempotencyKey: true,
 };
 
-export const isRequestOptions = (obj: unknown): obj is RequestOptions => {
+export const isRequestOptions = (obj: unknown): obj is RequestOptions<Record<string, unknown> | Readable> => {
   return (
     typeof obj === 'object' &&
     obj !== null &&
@@ -893,7 +914,7 @@ const isAbsoluteURL = (url: string): boolean => {
   return startsWithSchemeRegexp.test(url);
 };
 
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
 const validatePositiveInteger = (name: string, n: unknown): number => {
   if (typeof n !== 'number' || !Number.isInteger(n)) {

package/src/error.ts

@@ -13,7 +13,7 @@ export class APIError extends Error {
     message: string | undefined,
     headers: Headers | undefined,
   ) {
-    super(APIError.makeMessage(error, message));
+    super(`${status} ${APIError.makeMessage(error, message)}`);
     this.status = status;
     this.headers = headers;
     this.error = error;
@@ -25,7 +25,7 @@ export class APIError extends Error {
         typeof error.message === 'string' ? error.message
         : JSON.stringify(error.message)
       : error ? JSON.stringify(error)
-      : message || 'Unknown error occurred'
+      : message || 'status code (no body)'
     );
   }
 
@@ -97,8 +97,8 @@ export class APIConnectionError extends APIError {
 }
 
 export class APIConnectionTimeoutError extends APIConnectionError {
-  constructor() {
-    super({ message: 'Request timed out.' });
+  constructor({ message }: { message?: string } = {}) {
+    super({ message: message ?? 'Request timed out.' });
   }
 }
 

package/src/index.ts

@@ -4,7 +4,7 @@ import * as Core from './core';
 import * as Pagination from './pagination';
 import * as API from './resources/index';
 import * as Errors from './error';
-import type { Agent } from './_shims/agent';
+import { type Agent } from './_shims/index';
 import * as Uploads from './uploads';
 
 export interface ClientOptions {
@@ -70,6 +70,8 @@ export interface ClientOptions {
   clientId?: string | null;
 
   clientSecret?: string | null;
+
+  webhookSecret?: string | null;
 }
 
 /** API Client for interfacing with the Finch API. */
@@ -77,6 +79,7 @@ export class Finch extends Core.APIClient {
   accessToken: string | null;
   clientId?: string | null;
   clientSecret?: string | null;
+  webhookSecret?: string | null;
 
   private _options: ClientOptions;
 
@@ -93,19 +96,22 @@ export class Finch extends Core.APIClient {
    * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
    * @param {string | null} [opts.clientId]
    * @param {string | null} [opts.clientSecret]
+   * @param {string | null} [opts.webhookSecret]
    */
   constructor({
     accessToken = null,
     clientId = Core.readEnv('FINCH_CLIENT_ID') ?? null,
     clientSecret = Core.readEnv('FINCH_CLIENT_SECRET') ?? null,
+    webhookSecret = Core.readEnv('FINCH_WEBHOOK_SECRET') ?? null,
     ...opts
   }: ClientOptions = {}) {
     const options: ClientOptions = {
       accessToken,
       clientId,
       clientSecret,
-      baseURL: `https://api.tryfinch.com`,
+      webhookSecret,
       ...opts,
+      baseURL: opts.baseURL ?? `https://api.tryfinch.com`,
     };
 
     super({
@@ -120,12 +126,13 @@ export class Finch extends Core.APIClient {
     this.accessToken = accessToken;
     this.clientId = clientId;
     this.clientSecret = clientSecret;
+    this.webhookSecret = webhookSecret;
   }
 
   hris: API.HRIS = new API.HRIS(this);
-  ats: API.ATS = new API.ATS(this);
   providers: API.Providers = new API.Providers(this);
   account: API.Account = new API.Account(this);
+  webhooks: API.Webhooks = new API.Webhooks(this);
 
   /**
    * Returns an access token for the Finch API given an authorization code. An
@@ -262,30 +269,12 @@ export namespace Finch {
   export import IndividualsPageParams = Pagination.IndividualsPageParams;
   export import IndividualsPageResponse = Pagination.IndividualsPageResponse;
 
-  export import CandidatesPage = Pagination.CandidatesPage;
-  export import CandidatesPageParams = Pagination.CandidatesPageParams;
-  export import CandidatesPageResponse = Pagination.CandidatesPageResponse;
-
-  export import ApplicationsPage = Pagination.ApplicationsPage;
-  export import ApplicationsPageParams = Pagination.ApplicationsPageParams;
-  export import ApplicationsPageResponse = Pagination.ApplicationsPageResponse;
-
-  export import JobsPage = Pagination.JobsPage;
-  export import JobsPageParams = Pagination.JobsPageParams;
-  export import JobsPageResponse = Pagination.JobsPageResponse;
-
-  export import OffersPage = Pagination.OffersPage;
-  export import OffersPageParams = Pagination.OffersPageParams;
-  export import OffersPageResponse = Pagination.OffersPageResponse;
-
   export import HRIS = API.HRIS;
   export import Income = API.Income;
   export import Location = API.Location;
   export import Money = API.Money;
   export import Paging = API.Paging;
 
-  export import ATS = API.ATS;
-
   export import Providers = API.Providers;
   export import Provider = API.Provider;
   export import ProvidersSinglePage = API.ProvidersSinglePage;
@@ -293,6 +282,8 @@ export namespace Finch {
   export import Account = API.Account;
   export import DisconnectResponse = API.DisconnectResponse;
   export import Introspection = API.Introspection;
+
+  export import Webhooks = API.Webhooks;
 }
 
 export default Finch;

package/src/pagination.ts

@@ -2,7 +2,6 @@
 
 import { AbstractPage, Response, APIClient, FinalRequestOptions, PageInfo } from './core';
 import * as HRIS from './resources/hris/index';
-import * as ATS from './resources/ats/index';
 
 export type SinglePageResponse<Item> = Item[];
 
@@ -149,261 +148,3 @@ export class IndividualsPage
     return null;
   }
 }
-
-export interface CandidatesPageResponse {
-  candidates: Array<ATS.Candidate>;
-
-  paging: HRIS.Paging;
-}
-
-export interface CandidatesPageParams {
-  /**
-   * Number of candidates to return (defaults to all)
-   */
-  limit?: number;
-
-  /**
-   * Index to start from (defaults to 0)
-   */
-  offset?: number;
-}
-
-export class CandidatesPage extends AbstractPage<ATS.Candidate> implements CandidatesPageResponse {
-  paging: HRIS.Paging;
-
-  candidates: Array<ATS.Candidate>;
-
-  constructor(
-    client: APIClient,
-    response: Response,
-    body: CandidatesPageResponse,
-    options: FinalRequestOptions,
-  ) {
-    super(client, response, body, options);
-
-    this.paging = body.paging;
-    this.candidates = body.candidates;
-  }
-
-  getPaginatedItems(): ATS.Candidate[] {
-    return this.candidates;
-  }
-
-  // @deprecated Please use `nextPageInfo()` instead
-  nextPageParams(): Partial<CandidatesPageParams> | null {
-    const info = this.nextPageInfo();
-    if (!info) return null;
-    if ('params' in info) return info.params;
-    const params = Object.fromEntries(info.url.searchParams);
-    if (!Object.keys(params).length) return null;
-    return params;
-  }
-
-  nextPageInfo(): PageInfo | null {
-    const offset = this.paging.offset;
-    if (!offset) return null;
-
-    const length = this.candidates.length;
-    const currentCount = offset + length;
-
-    const totalCount = this.paging.count;
-    if (!totalCount) return null;
-
-    if (currentCount < totalCount) {
-      return { params: { offset: currentCount } };
-    }
-
-    return null;
-  }
-}
-
-export interface ApplicationsPageResponse {
-  applications: Array<ATS.Application>;
-
-  paging: HRIS.Paging;
-}
-
-export interface ApplicationsPageParams {
-  /**
-   * Number of applications to return (defaults to all)
-   */
-  limit?: number;
-
-  /**
-   * Index to start from (defaults to 0)
-   */
-  offset?: number;
-}
-
-export class ApplicationsPage extends AbstractPage<ATS.Application> implements ApplicationsPageResponse {
-  paging: HRIS.Paging;
-
-  applications: Array<ATS.Application>;
-
-  constructor(
-    client: APIClient,
-    response: Response,
-    body: ApplicationsPageResponse,
-    options: FinalRequestOptions,
-  ) {
-    super(client, response, body, options);
-
-    this.paging = body.paging;
-    this.applications = body.applications;
-  }
-
-  getPaginatedItems(): ATS.Application[] {
-    return this.applications;
-  }
-
-  // @deprecated Please use `nextPageInfo()` instead
-  nextPageParams(): Partial<ApplicationsPageParams> | null {
-    const info = this.nextPageInfo();
-    if (!info) return null;
-    if ('params' in info) return info.params;
-    const params = Object.fromEntries(info.url.searchParams);
-    if (!Object.keys(params).length) return null;
-    return params;
-  }
-
-  nextPageInfo(): PageInfo | null {
-    const offset = this.paging.offset;
-    if (!offset) return null;
-
-    const length = this.applications.length;
-    const currentCount = offset + length;
-
-    const totalCount = this.paging.count;
-    if (!totalCount) return null;
-
-    if (currentCount < totalCount) {
-      return { params: { offset: currentCount } };
-    }
-
-    return null;
-  }
-}
-
-export interface JobsPageResponse {
-  jobs: Array<ATS.Job>;
-
-  paging: HRIS.Paging;
-}
-
-export interface JobsPageParams {
-  /**
-   * Number of jobs to return (defaults to all)
-   */
-  limit?: number;
-
-  /**
-   * Index to start from (defaults to 0)
-   */
-  offset?: number;
-}
-
-export class JobsPage extends AbstractPage<ATS.Job> implements JobsPageResponse {
-  paging: HRIS.Paging;
-
-  jobs: Array<ATS.Job>;
-
-  constructor(client: APIClient, response: Response, body: JobsPageResponse, options: FinalRequestOptions) {
-    super(client, response, body, options);
-
-    this.paging = body.paging;
-    this.jobs = body.jobs;
-  }
-
-  getPaginatedItems(): ATS.Job[] {
-    return this.jobs;
-  }
-
-  // @deprecated Please use `nextPageInfo()` instead
-  nextPageParams(): Partial<JobsPageParams> | null {
-    const info = this.nextPageInfo();
-    if (!info) return null;
-    if ('params' in info) return info.params;
-    const params = Object.fromEntries(info.url.searchParams);
-    if (!Object.keys(params).length) return null;
-    return params;
-  }
-
-  nextPageInfo(): PageInfo | null {
-    const offset = this.paging.offset;
-    if (!offset) return null;
-
-    const length = this.jobs.length;
-    const currentCount = offset + length;
-
-    const totalCount = this.paging.count;
-    if (!totalCount) return null;
-
-    if (currentCount < totalCount) {
-      return { params: { offset: currentCount } };
-    }
-
-    return null;
-  }
-}
-
-export interface OffersPageResponse {
-  offers: Array<ATS.Offer>;
-
-  paging: HRIS.Paging;
-}
-
-export interface OffersPageParams {
-  /**
-   * Number of offers to return (defaults to all)
-   */
-  limit?: number;
-
-  /**
-   * Index to start from (defaults to 0)
-   */
-  offset?: number;
-}
-
-export class OffersPage extends AbstractPage<ATS.Offer> implements OffersPageResponse {
-  paging: HRIS.Paging;
-
-  offers: Array<ATS.Offer>;
-
-  constructor(client: APIClient, response: Response, body: OffersPageResponse, options: FinalRequestOptions) {
-    super(client, response, body, options);
-
-    this.paging = body.paging;
-    this.offers = body.offers;
-  }
-
-  getPaginatedItems(): ATS.Offer[] {
-    return this.offers;
-  }
-
-  // @deprecated Please use `nextPageInfo()` instead
-  nextPageParams(): Partial<OffersPageParams> | null {
-    const info = this.nextPageInfo();
-    if (!info) return null;
-    if ('params' in info) return info.params;
-    const params = Object.fromEntries(info.url.searchParams);
-    if (!Object.keys(params).length) return null;
-    return params;
-  }
-
-  nextPageInfo(): PageInfo | null {
-    const offset = this.paging.offset;
-    if (!offset) return null;
-
-    const length = this.offers.length;
-    const currentCount = offset + length;
-
-    const totalCount = this.paging.count;
-    if (!totalCount) return null;
-
-    if (currentCount < totalCount) {
-      return { params: { offset: currentCount } };
-    }
-
-    return null;
-  }
-}

package/src/resources/account.ts

@@ -1,7 +1,7 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import * as Core from '../core';
-import { APIResource } from '../resource';
+import * as Core from "../ch/finch-api/core";
+import { APIResource } from "../ch/finch-api/resource";
 import * as API from './index';
 
 export class Account extends APIResource {

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

@@ -1,11 +1,11 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import * as Core from '../../../core';
-import { APIResource } from '../../../resource';
-import { isRequestOptions } from '../../../core';
+import * as Core from "../../../ch/finch-api/core";
+import { APIResource } from "../../../ch/finch-api/resource";
+import { isRequestOptions } from "../../../ch/finch-api/core";
 import { Individuals } from './individuals';
 import * as API from './index';
-import { SinglePage } from '../../../pagination';
+import { SinglePage } from "../../../ch/finch-api/pagination";
 
 export class Benefits extends APIResource {
   individuals: Individuals = new Individuals(this.client);

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

@@ -1,11 +1,11 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import * as Core from '../../../core';
-import { APIResource } from '../../../resource';
-import { isRequestOptions } from '../../../core';
-import * as Benefits from './index';
+import * as Core from "../../../ch/finch-api/core";
+import { APIResource } from "../../../ch/finch-api/resource";
+import { isRequestOptions } from "../../../ch/finch-api/core";
+import * as Benefits from "../../../ch/finch-api/resources/hris/benefits/index";
 import * as API from './index';
-import { SinglePage } from '../../../pagination';
+import { SinglePage } from "../../../ch/finch-api/pagination";
 
 export class Individuals extends APIResource {
   /**