@tryfinch/finch-api 1.1.0 → 3.0.0

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

@@ -1,17 +1,28 @@
-import qs from 'qs';
-
-import type { Agent } from 'http';
-import type { RequestInfo, RequestInit, Response } from 'node-fetch';
-import { FormData, File, Blob } from 'formdata-node';
-import { FormDataEncoder } from 'form-data-encoder';
-import { Readable } from 'stream';
-
+import * as qs from 'qs';
 import { VERSION } from './version';
 import { Stream } from './streaming';
-import { Fetch, getDefaultAgent, getFetch } from './fetch-polyfill';
+import { APIError, APIConnectionError, APIConnectionTimeoutError } from './error';
+import type { Readable } from '@tryfinch/finch-api/_shims/node-readable';
+import { getDefaultAgent, type Agent } from '@tryfinch/finch-api/_shims/agent';
+import {
+  fetch,
+  isPolyfilled as fetchIsPolyfilled,
+  type RequestInfo,
+  type RequestInit,
+  type Response,
+} from '@tryfinch/finch-api/_shims/fetch';
+import { isMultipartBody } from './uploads';
+export {
+  maybeMultipartFormRequestOptions,
+  multipartFormRequestOptions,
+  createForm,
+  type Uploadable,
+} from './uploads';
 
 const MAX_RETRIES = 2;
 
+type Fetch = (url: RequestInfo, init?: RequestInit) => Promise<Response>;
+
 export abstract class APIClient {
   baseURL: string;
   maxRetries: number;
@@ -37,7 +48,7 @@ export abstract class APIClient {
     this.timeout = validatePositiveInteger('timeout', timeout);
     this.httpAgent = httpAgent;
 
-    this.fetch = getFetch();
+    this.fetch = fetch;
   }
 
   protected authHeaders(): Headers {
@@ -62,6 +73,8 @@ export abstract class APIClient {
     };
   }
 
+  protected abstract defaultQuery(): DefaultQuery | undefined;
+
   /**
    * Override this to add your own headers validation:
    */
@@ -111,8 +124,9 @@ export abstract class APIClient {
     options: FinalRequestOptions<Req>,
   ): { req: RequestInit; url: string; timeout: number } {
     const { method, path, query, headers: headers = {} } = options;
+
     const body =
-      options.body instanceof Readable ? options.body
+      isMultipartBody(options.body) ? options.body.body
       : options.body ? JSON.stringify(options.body, null, 2)
       : null;
     const contentLength = typeof body === 'string' ? body.length.toString() : null;
@@ -132,18 +146,23 @@ export abstract class APIClient {
       ...this.defaultHeaders(),
       ...headers,
     };
+    // let builtin fetch set the Content-Type for multipart bodies
+    if (isMultipartBody(options.body) && !fetchIsPolyfilled) {
+      delete reqHeaders['Content-Type'];
+    }
 
     // Strip any headers being explicitly omitted with null
     Object.keys(reqHeaders).forEach((key) => reqHeaders[key] === null && delete reqHeaders[key]);
 
     const req: RequestInit = {
       method,
-      ...(body && { body }),
+      ...(body && { body: body as any }),
       headers: reqHeaders,
       ...(httpAgent && { agent: httpAgent }),
     };
 
     this.validateHeaders(reqHeaders, headers);
+
     return { req, url, timeout };
   }
 
@@ -243,6 +262,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());
     }
@@ -252,11 +276,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);
 
@@ -341,7 +366,7 @@ export abstract class APIClient {
   }
 
   private debug(action: string, ...args: any[]) {
-    if (process.env['DEBUG'] === 'true') {
+    if (typeof process !== 'undefined' && process.env['DEBUG'] === 'true') {
       console.log(`${this.constructor.name}:DEBUG:${action}`, ...args);
     }
   }
@@ -480,18 +505,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> = {
@@ -540,88 +572,12 @@ 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;
 };
 
-export class APIError extends Error {
-  readonly status: number | undefined;
-  readonly headers: Headers | undefined;
-  readonly error: Object | undefined;
-
-  constructor(
-    status: number | undefined,
-    error: Object | undefined,
-    message: string | undefined,
-    headers: Headers | undefined,
-  ) {
-    super(message || (error as any)?.message);
-    this.status = status;
-    this.headers = headers;
-    this.error = error;
-  }
-
-  static generate(
-    status: number | undefined,
-    error: Object | undefined,
-    message: string | undefined,
-    headers: Headers | undefined,
-  ) {
-    if (!status) return new APIConnectionError({ cause: castToError(error) });
-
-    if (status === 400) return new BadRequestError(status, error, message, headers);
-    if (status === 401) return new AuthenticationError(status, error, message, headers);
-    if (status === 403) return new PermissionDeniedError(status, error, message, headers);
-    if (status === 404) return new NotFoundError(status, error, message, headers);
-    if (status === 409) return new ConflictError(status, error, message, headers);
-    if (status === 422) return new UnprocessableEntityError(status, error, message, headers);
-    if (status === 429) return new RateLimitError(status, error, message, headers);
-    if (status >= 500) return new InternalServerError(status, error, message, headers);
-
-    return new APIError(status, error, message, headers);
-  }
-}
-
-export class BadRequestError extends APIError {
-  override readonly status: 400 = 400;
-}
-export class AuthenticationError extends APIError {
-  override readonly status: 401 = 401;
-}
-export class PermissionDeniedError extends APIError {
-  override readonly status: 403 = 403;
-}
-export class NotFoundError extends APIError {
-  override readonly status: 404 = 404;
-}
-export class ConflictError extends APIError {
-  override readonly status: 409 = 409;
-}
-export class UnprocessableEntityError extends APIError {
-  override readonly status: 422 = 422;
-}
-export class RateLimitError extends APIError {
-  override readonly status: 429 = 429;
-}
-export class InternalServerError extends APIError {}
-
-export class APIConnectionError extends APIError {
-  override readonly status: undefined = undefined;
-
-  constructor({ message, cause }: { message?: string; cause?: Error | undefined }) {
-    super(undefined, undefined, message || 'Connection error.', undefined);
-    // eslint-disable-next-line
-    // @ts-ignore
-    if (cause) this.cause = cause;
-  }
-}
-
-export class APIConnectionTimeoutError extends APIConnectionError {
-  constructor() {
-    super({ message: 'Request timed out.' });
-  }
-}
-
 declare const Deno: any;
+declare const EdgeRuntime: any;
 type Arch = 'x32' | 'x64' | 'arm' | 'arm64' | `other:${string}` | 'unknown';
 type PlatformName =
   | 'MacOS'
@@ -638,7 +594,7 @@ type PlatformProperties = {
   'X-Stainless-Package-Version': string;
   'X-Stainless-OS': PlatformName;
   'X-Stainless-Arch': Arch;
-  'X-Stainless-Runtime': 'node' | 'deno' | 'unknown';
+  'X-Stainless-Runtime': 'node' | 'deno' | 'edge' | 'unknown';
   'X-Stainless-Runtime-Version': string;
 };
 const getPlatformProperties = (): PlatformProperties => {
@@ -652,7 +608,18 @@ const getPlatformProperties = (): PlatformProperties => {
       'X-Stainless-Runtime-Version': Deno.version,
     };
   }
-  if (typeof process !== 'undefined') {
+  if (typeof EdgeRuntime !== 'undefined') {
+    return {
+      'X-Stainless-Lang': 'js',
+      'X-Stainless-Package-Version': VERSION,
+      'X-Stainless-OS': 'Unknown',
+      'X-Stainless-Arch': `other:${EdgeRuntime}`,
+      'X-Stainless-Runtime': 'edge',
+      'X-Stainless-Runtime-Version': process.version,
+    };
+  }
+  // Check if Node.js
+  if (Object.prototype.toString.call(typeof process !== 'undefined' ? process : 0) === '[object process]') {
     return {
       'X-Stainless-Lang': 'js',
       'X-Stainless-Package-Version': VERSION,
@@ -741,86 +708,11 @@ const validatePositiveInteger = (name: string, n: number) => {
   return n;
 };
 
-const castToError = (err: any): Error => {
+export const castToError = (err: any): Error => {
   if (err instanceof Error) return err;
   return new Error(err);
 };
 
-/**
- * Returns a multipart/form-data request if any part of the given request body contains a File / Blob value.
- * Otherwise returns the request as is.
- */
-export const maybeMultipartFormRequestOptions = <T extends {} = Record<string, unknown>>(
-  opts: RequestOptions<T>,
-): RequestOptions<T | Readable> => {
-  // TODO: does this add unreasonable overhead in the case where we shouldn't use multipart/form-data?
-  const form = createForm(opts.body);
-
-  for (const [_, entry] of form.entries()) {
-    const value = entry.valueOf();
-    if (value instanceof File || value instanceof Blob) {
-      return getMultipartRequestOptions(form, opts);
-    }
-  }
-
-  return opts;
-};
-
-export const multipartFormRequestOptions = <T extends {} = Record<string, unknown>>(
-  opts: RequestOptions<T>,
-): RequestOptions<T | Readable> => {
-  return getMultipartRequestOptions(createForm(opts.body), opts);
-};
-
-const createForm = <T = Record<string, unknown>>(body: T | undefined): FormData => {
-  const form = new FormData();
-  Object.entries(body || {}).forEach(([key, value]) => addFormValue(form, key, value));
-  return form;
-};
-
-const getMultipartRequestOptions = <T extends {} = Record<string, unknown>>(
-  form: FormData,
-  opts: RequestOptions<T>,
-): RequestOptions<T | Readable> => {
-  const encoder = new FormDataEncoder(form);
-  return {
-    ...opts,
-    headers: { ...opts.headers, ...encoder.headers, 'Content-Length': encoder.contentLength },
-    body: Readable.from(encoder),
-  };
-};
-
-const addFormValue = (form: FormData, key: string, value: unknown) => {
-  if (value == null) {
-    throw new TypeError(
-      `null is not a valid form data value, if you want to pass null then you need to use the string 'null'`,
-    );
-  }
-
-  // TODO: make nested formats configurable
-  if (
-    typeof value === 'string' ||
-    typeof value === 'number' ||
-    typeof value === 'boolean' ||
-    value instanceof File ||
-    value instanceof Blob
-  ) {
-    form.append(key, value);
-  } else if (Array.isArray(value)) {
-    value.forEach((entry) => {
-      addFormValue(form, key + '[]', entry);
-    });
-  } else if (typeof value === 'object') {
-    Object.entries(value).forEach(([name, prop]) => {
-      addFormValue(form, `${key}[${name}]`, prop);
-    });
-  } else {
-    throw new TypeError(
-      `Invalid value given to form, expected a string, number, boolean, object, Array, File or Blob but got ${value} instead`,
-    );
-  }
-};
-
 export const ensurePresent = <T>(value: T | null | undefined): T => {
   if (value == null) throw new Error(`Expected a value to be given but received ${value} instead.`);
   return value;

package/src/error.ts

@@ -0,0 +1,115 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import { castToError, Headers } from './core';
+
+export class APIError extends Error {
+  readonly status: number | undefined;
+  readonly headers: Headers | undefined;
+  readonly error: Object | undefined;
+
+  constructor(
+    status: number | undefined,
+    error: Object | undefined,
+    message: string | undefined,
+    headers: Headers | undefined,
+  ) {
+    super(message || (error as any)?.message || 'Unknown error occurred.');
+    this.status = status;
+    this.headers = headers;
+    this.error = error;
+  }
+
+  static generate(
+    status: number | undefined,
+    errorResponse: Object | undefined,
+    message: string | undefined,
+    headers: Headers | undefined,
+  ) {
+    if (!status) {
+      return new APIConnectionError({ cause: castToError(errorResponse) });
+    }
+
+    const error = errorResponse as Record<string, any>;
+
+    if (status === 400) {
+      return new BadRequestError(status, error, message, headers);
+    }
+
+    if (status === 401) {
+      return new AuthenticationError(status, error, message, headers);
+    }
+
+    if (status === 403) {
+      return new PermissionDeniedError(status, error, message, headers);
+    }
+
+    if (status === 404) {
+      return new NotFoundError(status, error, message, headers);
+    }
+
+    if (status === 409) {
+      return new ConflictError(status, error, message, headers);
+    }
+
+    if (status === 422) {
+      return new UnprocessableEntityError(status, error, message, headers);
+    }
+
+    if (status === 429) {
+      return new RateLimitError(status, error, message, headers);
+    }
+
+    if (status >= 500) {
+      return new InternalServerError(status, error, message, headers);
+    }
+
+    return new APIError(status, error, message, headers);
+  }
+}
+
+export class APIConnectionError extends APIError {
+  override readonly status: undefined = undefined;
+
+  constructor({ message, cause }: { message?: string; cause?: Error | undefined }) {
+    super(undefined, undefined, message || 'Connection error.', undefined);
+    // in some environments the 'cause' property is already declared
+    // @ts-ignore
+    if (cause) this.cause = cause;
+  }
+}
+
+export class APIConnectionTimeoutError extends APIConnectionError {
+  constructor() {
+    super({ message: 'Request timed out.' });
+  }
+}
+
+export class BadRequestError extends APIError {
+  override readonly status: 400 = 400;
+}
+
+export class AuthenticationError extends APIError {
+  override readonly status: 401 = 401;
+}
+
+export class PermissionDeniedError extends APIError {
+  override readonly status: 403 = 403;
+}
+
+export class NotFoundError extends APIError {
+  override readonly status: 404 = 404;
+}
+
+export class ConflictError extends APIError {
+  override readonly status: 409 = 409;
+}
+
+export class UnprocessableEntityError extends APIError {
+  override readonly status: 422 = 422;
+}
+
+export class RateLimitError extends APIError {
+  override readonly status: 429 = 429;
+}
+
+export class InternalServerError extends APIError {}

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

@@ -1,23 +1,67 @@
 // 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 type { Agent } from 'http';
-import * as FileFromPath from 'formdata-node/file-from-path';
+import * as API from './resources/index';
+import * as Errors from './error';
+import type { Agent } from '@tryfinch/finch-api/_shims/agent';
+import * as Uploads from './uploads';
 
 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;
+
+  /**
+   * 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;
 };
 
@@ -78,6 +122,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
@@ -108,6 +153,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(),
@@ -140,42 +189,40 @@ export class Finch extends Core.APIClient {
     return { arrayFormat: 'comma' };
   }
 
-  static APIError = Core.APIError;
-
-  static APIConnectionError = Core.APIConnectionError;
-  static APIConnectionTimeoutError = Core.APIConnectionTimeoutError;
-
-  static BadRequestError = Core.BadRequestError;
-  static AuthenticationError = Core.AuthenticationError;
-  static PermissionDeniedError = Core.PermissionDeniedError;
-  static NotFoundError = Core.NotFoundError;
-  static ConflictError = Core.ConflictError;
-  static UnprocessableEntityError = Core.UnprocessableEntityError;
-  static RateLimitError = Core.RateLimitError;
-  static InternalServerError = Core.InternalServerError;
+  static APIError = Errors.APIError;
+  static APIConnectionError = Errors.APIConnectionError;
+  static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
+  static NotFoundError = Errors.NotFoundError;
+  static ConflictError = Errors.ConflictError;
+  static RateLimitError = Errors.RateLimitError;
+  static BadRequestError = Errors.BadRequestError;
+  static AuthenticationError = Errors.AuthenticationError;
+  static InternalServerError = Errors.InternalServerError;
+  static PermissionDeniedError = Errors.PermissionDeniedError;
+  static UnprocessableEntityError = Errors.UnprocessableEntityError;
 }
 
 export const {
   APIError,
-
   APIConnectionError,
   APIConnectionTimeoutError,
-
-  BadRequestError,
-  AuthenticationError,
-  PermissionDeniedError,
   NotFoundError,
   ConflictError,
-  UnprocessableEntityError,
   RateLimitError,
+  BadRequestError,
+  AuthenticationError,
   InternalServerError,
-} = Finch;
+  PermissionDeniedError,
+  UnprocessableEntityError,
+} = Errors;
 
-export import fileFromPath = FileFromPath.fileFromPath;
+export import toFile = Uploads.toFile;
+export import fileFromPath = Uploads.fileFromPath;
 
 export namespace Finch {
   // Helper functions
-  export import fileFromPath = FileFromPath.fileFromPath;
+  export import toFile = Uploads.toFile;
+  export import fileFromPath = Uploads.fileFromPath;
 
   export import SinglePage = Pagination.SinglePage;
   export import SinglePageResponse = Pagination.SinglePageResponse;
@@ -203,17 +250,21 @@ export namespace Finch {
   export import OffersPageParams = Pagination.OffersPageParams;
   export import OffersPageResponse = Pagination.OffersPageResponse;
 
+  export import ATS = API.ATS;
+
+  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 Providers = API.Providers;
   export import Provider = API.Provider;
   export import ProvidersSinglePage = API.ProvidersSinglePage;
 
+  export import Account = API.Account;
   export import DisconnectResponse = API.DisconnectResponse;
   export import Introspection = API.Introspection;
 }
 
-exports = module.exports = Finch;
 export default Finch;

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

@@ -98,7 +98,10 @@ export class IndividualsPage
   implements IndividualsPageResponse
 {
   paging: HRIS.Paging;
-  /** The array of employees. */
+
+  /**
+   * The array of employees.
+   */
   individuals: Array<HRIS.IndividualInDirectory>;
 
   constructor(

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

@@ -1,7 +1,8 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import * as Core from '~/core';
-import { APIResource } from '~/resource';
+import * as Core from '@tryfinch/finch-api/core';
+import { APIResource } from '@tryfinch/finch-api/resource';
+import * as API from './';
 
 export class Account extends APIResource {
   /**
@@ -61,3 +62,8 @@ export interface Introspection {
    */
   username: string;
 }
+
+export namespace Account {
+  export import DisconnectResponse = API.DisconnectResponse;
+  export import Introspection = API.Introspection;
+}