@tryfinch/finch-api 2.0.0 → 3.1.0

package/src/_shims/formdata.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import type { BlobPart } from '../uploads';
+
+type EndingType = 'native' | 'transparent';
+
+export interface BlobPropertyBag {
+  endings?: EndingType;
+  type?: string;
+}
+
+export interface FilePropertyBag extends BlobPropertyBag {
+  lastModified?: number;
+}
+
+// Use builtin web types if present; else never (user should
+// add appropriate lib or types to tsconfig)
+
+// @ts-ignore
+type _FormData = unknown extends FormData ? never : FormData;
+// @ts-ignore
+type _File = unknown extends File ? never : File;
+// @ts-ignore
+type _Blob = unknown extends Blob ? never : Blob;
+
+declare const _FormData: {
+  new (form?: any): _FormData;
+  prototype: _FormData;
+};
+declare const _File: {
+  new (fileBits: BlobPart[], fileName: string, options?: FilePropertyBag | undefined): _File;
+  prototype: _File;
+};
+declare const _Blob: {
+  new (blobParts?: BlobPart[] | undefined, options?: BlobPropertyBag | undefined): _Blob;
+  prototype: _Blob;
+};
+
+export const isPolyfilled = false;
+
+export { _FormData as FormData, _File as File, _Blob as Blob };

package/src/_shims/formdata.js

@@ -0,0 +1,9 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+exports.FormData = FormData;
+exports.File = File;
+exports.Blob = Blob;
+
+exports.isPolyfilled = false;

package/src/_shims/formdata.mjs

@@ -0,0 +1,11 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+const _FormData = FormData;
+const _File = File;
+const _Blob = Blob;
+
+export { _FormData as FormData, _File as File, _Blob as Blob };
+
+export const isPolyfilled = false;

package/src/_shims/formdata.node.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+import * as fd from 'formdata-node';
+
+import type { BlobPart } from '../uploads';
+
+type EndingType = 'native' | 'transparent';
+
+export interface BlobPropertyBag {
+  endings?: EndingType;
+  type?: string;
+}
+
+export interface FilePropertyBag extends BlobPropertyBag {
+  lastModified?: number;
+}
+
+// Use builtin web types if present; else formdata-node types
+
+// @ts-ignore
+type _FormData = unknown extends FormData ? fd.FormData : FormData;
+// @ts-ignore
+type _File = unknown extends File ? fd.File : File;
+// @ts-ignore
+type _Blob = unknown extends Blob ? fd.Blob : Blob;
+
+declare const _FormData: {
+  new (form?: any): _FormData;
+  prototype: _FormData;
+};
+declare const _File: {
+  new (fileBits: BlobPart[], fileName: string, options?: FilePropertyBag | undefined): _File;
+  prototype: _File;
+};
+declare const _Blob: {
+  new (blobParts?: BlobPart[] | undefined, options?: BlobPropertyBag | undefined): _Blob;
+  prototype: _Blob;
+};
+
+export const isPolyfilled = false;
+
+export { _FormData as FormData, _File as File, _Blob as Blob };

package/src/_shims/formdata.node.js

@@ -0,0 +1,11 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+const fd = require('formdata-node');
+
+exports.FormData = fd.FormData;
+exports.File = fd.File;
+exports.Blob = fd.Blob;
+
+exports.isPolyfilled = true;

package/{dist/esm/_shims/formdata.node.js → src/_shims/formdata.node.mjs}

@@ -1,7 +1,9 @@
 /**
  * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
  */
+
 import { FormData, File, Blob } from 'formdata-node';
+
 export { FormData, File, Blob };
+
 export const isPolyfilled = true;
-//# sourceMappingURL=formdata.node.js.map

package/{_shims → src/_shims}/getMultipartRequestOptions.node.ts

@@ -2,10 +2,11 @@
  * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
  */
 
-import { FormData } from './formdata.node';
+import { FormData } from './formdata.node.js';
 import type { RequestOptions } from '../core';
 import { Readable } from 'node:stream';
 import { FormDataEncoder } from 'form-data-encoder';
+import { MultipartBody } from '../uploads';
 
 export async function getMultipartRequestOptions<T extends {} = Record<string, unknown>>(
   form: FormData,
@@ -13,7 +14,7 @@ export async function getMultipartRequestOptions<T extends {} = Record<string, u
 ): Promise<RequestOptions<T>> {
   const encoder = new FormDataEncoder(form);
   const readable = Readable.from(encoder);
-  const body = { __multipartBody__: readable };
+  const body = new MultipartBody(readable);
   const headers = {
     ...opts.headers,
     ...encoder.headers,

package/{_shims → src/_shims}/getMultipartRequestOptions.ts

@@ -2,12 +2,13 @@
  * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
  */
 
-import { FormData } from './formdata';
+import { FormData } from './formdata.js';
 import type { RequestOptions } from '../core';
+import { MultipartBody } from '../uploads';
 
 export async function getMultipartRequestOptions<T extends {} = Record<string, unknown>>(
   form: FormData,
   opts: RequestOptions<T>,
 ): Promise<RequestOptions<T>> {
-  return { ...opts, body: { __multipartBody__: form } as any };
+  return { ...opts, body: new MultipartBody(form) as any };
 }

package/src/_shims/node-readable.node.ts

@@ -0,0 +1,10 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+export type { Readable } from 'node:stream';
+import { ReadStream as FsReadStream } from 'node:fs';
+export type { FsReadStream };
+
+export function isFsReadStream(value: any): value is FsReadStream {
+  return value instanceof FsReadStream;
+}

package/src/_shims/node-readable.ts

@@ -0,0 +1,30 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+// shim these Node types to avoid importing @types/node and polluting the user's
+// type environment in non-node projects
+
+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
+}
+
+export function isFsReadStream(value: any): value is FsReadStream {
+  return false;
+}

package/{core.ts → src/core.ts}

@@ -1,21 +1,27 @@
-import type { Readable } from 'node:stream';
-import type { Agent } from 'http';
-
-import qs from 'qs';
-
+import * as qs from 'qs';
 import { VERSION } from './version';
 import { Stream } from './streaming';
-import { APIError, APIConnectionError, APIConnectionTimeoutError } from './error';
-import { getDefaultAgent } from '@tryfinch/finch-api/_shims/agent';
-import { fetch, isPolyfilled as fetchIsPolyfilled } from '@tryfinch/finch-api/_shims/fetch';
-import type { RequestInfo, RequestInit, Response } from '@tryfinch/finch-api/_shims/fetch';
+import { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError } from './error';
+import type { Readable } from './_shims/node-readable';
+import { getDefaultAgent, type Agent } from './_shims/agent';
+import {
+  fetch,
+  isPolyfilled as fetchIsPolyfilled,
+  type RequestInfo,
+  type RequestInit,
+  type Response,
+} from './_shims/fetch.js';
 import { isMultipartBody } from './uploads';
-export { maybeMultipartFormRequestOptions, multipartFormRequestOptions, createForm } from './uploads';
-export type { Uploadable } from '@tryfinch/finch-api/_shims/uploadable';
+export {
+  maybeMultipartFormRequestOptions,
+  multipartFormRequestOptions,
+  createForm,
+  type Uploadable,
+} from './uploads';
 
 const MAX_RETRIES = 2;
 
-type Fetch = (url: RequestInfo, init?: RequestInit) => Promise<Response>;
+export type Fetch = (url: RequestInfo, init?: RequestInit) => Promise<Response>;
 
 export abstract class APIClient {
   baseURL: string;
@@ -31,18 +37,20 @@ export abstract class APIClient {
     maxRetries,
     timeout = 60 * 1000, // 60s
     httpAgent,
+    fetch: overridenFetch,
   }: {
     baseURL: string;
     maxRetries?: number | undefined;
     timeout: number | undefined;
     httpAgent: Agent | undefined;
+    fetch: Fetch | undefined;
   }) {
     this.baseURL = baseURL;
     this.maxRetries = validatePositiveInteger('maxRetries', maxRetries ?? MAX_RETRIES);
     this.timeout = validatePositiveInteger('timeout', timeout);
     this.httpAgent = httpAgent;
 
-    this.fetch = fetch;
+    this.fetch = overridenFetch ?? fetch;
   }
 
   protected authHeaders(): Headers {
@@ -67,6 +75,8 @@ export abstract class APIClient {
     };
   }
 
+  protected abstract defaultQuery(): DefaultQuery | undefined;
+
   /**
    * Override this to add your own headers validation:
    */
@@ -112,21 +122,43 @@ export abstract class APIClient {
     return this.requestAPIList(Page, { method: 'get', path, ...opts });
   }
 
+  private calculateContentLength(body: unknown): string | null {
+    if (typeof body === 'string') {
+      if (typeof Buffer !== 'undefined') {
+        return Buffer.byteLength(body, 'utf8').toString();
+      }
+
+      const encoder = new TextEncoder();
+      const encoded = encoder.encode(body);
+      return encoded.length.toString();
+    }
+
+    return null;
+  }
+
   buildRequest<Req extends {}>(
     options: FinalRequestOptions<Req>,
   ): { req: RequestInit; url: string; timeout: number } {
     const { method, path, query, headers: headers = {} } = options;
 
     const body =
-      isMultipartBody(options.body) ? options.body.__multipartBody__
+      isMultipartBody(options.body) ? options.body.body
       : options.body ? JSON.stringify(options.body, null, 2)
       : null;
-    const contentLength = typeof body === 'string' ? body.length.toString() : null;
+    const contentLength = this.calculateContentLength(body);
 
     const url = this.buildURL(path!, query);
-    const httpAgent = options.httpAgent ?? this.httpAgent ?? getDefaultAgent(url);
+    if ('timeout' in options) validatePositiveInteger('timeout', options.timeout);
     const timeout = options.timeout ?? this.timeout;
-    validatePositiveInteger('timeout', timeout);
+    const httpAgent = options.httpAgent ?? this.httpAgent ?? getDefaultAgent(url);
+    const minAgentTimeout = timeout + 1000;
+    if ((httpAgent as any)?.options && minAgentTimeout > ((httpAgent as any).options.timeout ?? 0)) {
+      // Allow any given request to bump our agent active socket timeout.
+      // This may seem strange, but leaking active sockets should be rare and not particularly problematic,
+      // and without mutating agent we would need to create more of them.
+      // This tradeoff optimizes for performance.
+      (httpAgent as any).options.timeout = minAgentTimeout;
+    }
 
     if (this.idempotencyHeader && method !== 'get') {
       if (!options.idempotencyKey) options.idempotencyKey = this.defaultIdempotencyKey();
@@ -148,9 +180,12 @@ export abstract class APIClient {
 
     const req: RequestInit = {
       method,
-      ...(body && { body }),
+      ...(body && { body: body as any }),
       headers: reqHeaders,
       ...(httpAgent && { agent: httpAgent }),
+      // @ts-ignore node-fetch uses a custom AbortSignal type that is
+      // not compatible with standard web types
+      signal: options.signal ?? null,
     };
 
     this.validateHeaders(reqHeaders, headers);
@@ -188,8 +223,15 @@ export abstract class APIClient {
     const response = await this.fetchWithTimeout(url, req, timeout, controller).catch(castToError);
 
     if (response instanceof Error) {
-      if (retriesRemaining) return this.retryRequest(options, retriesRemaining);
-      if (response.name === 'AbortError') throw new APIConnectionTimeoutError();
+      if (options.signal?.aborted) {
+        throw new APIUserAbortError();
+      }
+      if (retriesRemaining) {
+        return this.retryRequest(options, retriesRemaining);
+      }
+      if (response.name === 'AbortError') {
+        throw new APIConnectionTimeoutError();
+      }
       throw new APIConnectionError({ cause: response });
     }
 
@@ -254,6 +296,11 @@ export abstract class APIClient {
         new URL(path)
       : new URL(this.baseURL + (this.baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
+    const defaultQuery = this.defaultQuery();
+    if (!isEmptyObj(defaultQuery)) {
+      query = { ...defaultQuery, ...query } as Req;
+    }
+
     if (query) {
       url.search = qs.stringify(query, this.qsOptions());
     }
@@ -263,11 +310,12 @@ export abstract class APIClient {
 
   async fetchWithTimeout(
     url: RequestInfo,
-    { signal, ...options }: RequestInit = {},
+    init: RequestInit | undefined,
     ms: number,
     controller: AbortController,
-  ) {
-    if (signal) signal.addEventListener('abort', controller.abort);
+  ): Promise<Response> {
+    const { signal, ...options } = init || {};
+    if (signal) signal.addEventListener('abort', () => controller.abort());
 
     const timeout = setTimeout(() => controller.abort(), ms);
 
@@ -491,18 +539,25 @@ export class PagePromise<
 export const createResponseHeaders = (
   headers: Awaited<ReturnType<Fetch>>['headers'],
 ): Record<string, string> => {
-  return new Proxy(Object.fromEntries(headers.entries()), {
-    get(target, name) {
-      const key = name.toString();
-      return target[key.toLowerCase()] || target[key];
+  return new Proxy(
+    Object.fromEntries(
+      // @ts-ignore
+      headers.entries(),
+    ),
+    {
+      get(target, name) {
+        const key = name.toString();
+        return target[key.toLowerCase()] || target[key];
+      },
     },
-  });
+  );
 };
 
 type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 
 export type RequestClient = { fetch: Fetch };
 export type Headers = Record<string, string | null | undefined>;
+export type DefaultQuery = Record<string, string | undefined>;
 export type KeysEnum<T> = { [P in keyof Required<T>]: true };
 
 export type RequestOptions<Req extends {} = Record<string, unknown> | Readable> = {
@@ -516,6 +571,7 @@ export type RequestOptions<Req extends {} = Record<string, unknown> | Readable>
   stream?: boolean | undefined;
   timeout?: number;
   httpAgent?: Agent;
+  signal?: AbortSignal | undefined | null;
   idempotencyKey?: string;
 };
 
@@ -533,6 +589,7 @@ const requestOptionsKeys: KeysEnum<RequestOptions> = {
   stream: true,
   timeout: true,
   httpAgent: true,
+  signal: true,
   idempotencyKey: true,
 };
 
@@ -551,6 +608,7 @@ export type FinalRequestOptions<Req extends {} = Record<string, unknown> | Reada
 };
 
 export type APIResponse<T> = T & {
+  /** @deprecated - we plan to add a different way to access raw response information shortly. */
   responseHeaders: Headers;
 };
 

package/{error.ts → src/error.ts}

@@ -67,6 +67,14 @@ export class APIError extends Error {
   }
 }
 
+export class APIUserAbortError extends APIError {
+  override readonly status: undefined = undefined;
+
+  constructor({ message }: { message?: string } = {}) {
+    super(undefined, undefined, message || 'Request was aborted.', undefined);
+  }
+}
+
 export class APIConnectionError extends APIError {
   override readonly status: undefined = undefined;
 

package/{index.ts → src/index.ts}

@@ -1,11 +1,11 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import qs from 'qs';
+import * as qs from 'qs';
 import * as Core from './core';
 import * as Pagination from './pagination';
-import * as API from './resources';
+import * as API from './resources/index';
 import * as Errors from './error';
-import type { Agent } from 'http';
+import type { Agent } from './_shims/agent';
 import * as Uploads from './uploads';
 
 type Config = {
@@ -13,12 +13,63 @@ type Config = {
    * Set it to null if you want to send unauthenticated requests.
    */
   accessToken?: string | null;
+
+  /**
+   * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
+   */
   baseURL?: string;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
+   * much longer than this timeout before the promise succeeds or fails.
+   */
   timeout?: number;
+
+  /**
+   * An HTTP agent used to manage HTTP(S) connections.
+   *
+   * If not provided, an agent will be constructed by default in the Node.js environment,
+   * otherwise no agent is used.
+   */
   httpAgent?: Agent;
+
+  /**
+   * Specify a custom `fetch` function implementation.
+   *
+   * If not provided, we use `node-fetch` on Node.js and otherwise expect that `fetch` is
+   * defined globally.
+   */
+  fetch?: Core.Fetch | undefined;
+
+  /**
+   * The maximum number of times that the client will retry a request in case of a
+   * temporary failure, like a network error or a 5XX error from the server.
+   *
+   * @default 2
+   */
   maxRetries?: number;
+
+  /**
+   * Default headers to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * header to `undefined` or `null` in request options.
+   */
   defaultHeaders?: Core.Headers;
+
+  /**
+   * Default query parameters to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * param to `undefined` in request options.
+   */
+  defaultQuery?: Core.DefaultQuery;
+
   clientId?: string | null;
+
   clientSecret?: string | null;
 };
 
@@ -42,6 +93,7 @@ export class Finch extends Core.APIClient {
       timeout: options.timeout,
       httpAgent: options.httpAgent,
       maxRetries: options.maxRetries,
+      fetch: options.fetch,
     });
     this.accessToken = options.accessToken || null;
     this._options = options;
@@ -79,6 +131,7 @@ export class Finch extends Core.APIClient {
       },
     }).then((response) => response.access_token);
   }
+
   /**
    * Returns the authorization url which can be visited in order to obtain an
    * authorization code from Finch. The autorization code can then be exchanged for
@@ -109,6 +162,10 @@ export class Finch extends Core.APIClient {
     return url.toString();
   }
 
+  protected override defaultQuery(): Core.DefaultQuery | undefined {
+    return this._options.defaultQuery;
+  }
+
   protected override defaultHeaders(): Core.Headers {
     return {
       ...super.defaultHeaders(),
@@ -144,6 +201,7 @@ export class Finch extends Core.APIClient {
   static APIError = Errors.APIError;
   static APIConnectionError = Errors.APIConnectionError;
   static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
+  static APIUserAbortError = Errors.APIUserAbortError;
   static NotFoundError = Errors.NotFoundError;
   static ConflictError = Errors.ConflictError;
   static RateLimitError = Errors.RateLimitError;
@@ -158,6 +216,7 @@ export const {
   APIError,
   APIConnectionError,
   APIConnectionTimeoutError,
+  APIUserAbortError,
   NotFoundError,
   ConflictError,
   RateLimitError,
@@ -218,4 +277,5 @@ export namespace Finch {
   export import DisconnectResponse = API.DisconnectResponse;
   export import Introspection = API.Introspection;
 }
+
 export default Finch;

package/{resources → src/resources}/account.ts

@@ -1,8 +1,8 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import * as Core from '~/core';
-import { APIResource } from '~/resource';
-import * as API from './';
+import * as Core from '../core';
+import { APIResource } from '../resource';
+import * as API from '.';
 
 export class Account extends APIResource {
   /**

package/{resources → src/resources}/ats/applications.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 Stages from '~/resources/ats/stages';
-import * as API from './';
-import { ApplicationsPage, ApplicationsPageParams } from '~/pagination';
+import * as Core from '../../core';
+import { APIResource } from '../../resource';
+import { isRequestOptions } from '../../core';
+import * as Stages from './stages';
+import * as API from '.';
+import { ApplicationsPage, ApplicationsPageParams } from '../../pagination';
 
 export class Applications extends APIResource {
   /**

package/{resources → src/resources}/ats/ats.ts

@@ -1,12 +1,12 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import { APIResource } from '~/resource';
+import { APIResource } from '../../resource';
 import { Candidates } from './candidates';
 import { Applications } from './applications';
 import { Stages } from './stages';
 import { Jobs } from './jobs';
 import { Offers } from './offers';
-import * as API from './';
+import * as API from '.';
 
 export class ATS extends APIResource {
   candidates: Candidates = new Candidates(this.client);

package/{resources → src/resources}/ats/candidates.ts

@@ -1,10 +1,10 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import * as Core from '~/core';
-import { APIResource } from '~/resource';
-import { isRequestOptions } from '~/core';
-import * as API from './';
-import { CandidatesPage, CandidatesPageParams } from '~/pagination';
+import * as Core from '../../core';
+import { APIResource } from '../../resource';
+import { isRequestOptions } from '../../core';
+import * as API from '.';
+import { CandidatesPage, CandidatesPageParams } from '../../pagination';
 
 export class Candidates extends APIResource {
   /**

package/{resources → src/resources}/ats/jobs.ts

@@ -1,10 +1,10 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import * as Core from '~/core';
-import { APIResource } from '~/resource';
-import { isRequestOptions } from '~/core';
-import * as API from './';
-import { JobsPage, JobsPageParams } from '~/pagination';
+import * as Core from '../../core';
+import { APIResource } from '../../resource';
+import { isRequestOptions } from '../../core';
+import * as API from '.';
+import { JobsPage, JobsPageParams } from '../../pagination';
 
 export class Jobs extends APIResource {
   /**