@tryfinch/finch-api 5.1.0 → 5.3.0

package/src/_shims/index.js

@@ -0,0 +1,13 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+const shims = require('./registry');
+const auto = require('@tryfinch/finch-api/_shims/auto/runtime');
+if (!shims.kind) shims.setShims(auto.getRuntime(), { auto: true });
+for (const property of Object.keys(shims)) {
+  Object.defineProperty(exports, property, {
+    get() {
+      return shims[property];
+    },
+  });
+}

package/src/_shims/index.mjs

@@ -0,0 +1,7 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+import * as shims from './registry.mjs';
+import * as auto from "../ch/finch-api/_shims/auto/runtime";
+if (!shims.kind) shims.setShims(auto.getRuntime(), { auto: true });
+export * from './registry.mjs';

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

@@ -0,0 +1,12 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+/**
+ * Types will get added to this namespace when you import one of the following:
+ *
+ *   import '@tryfinch/finch-api/shims/node'
+ *   import '@tryfinch/finch-api/shims/web'
+ *
+ * Importing more than one will cause type and runtime errors.
+ */
+export namespace manual {}

package/src/_shims/manual-types.js

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

package/src/_shims/manual-types.mjs

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

package/src/_shims/node-runtime.ts

@@ -0,0 +1,79 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+import * as nf from 'node-fetch';
+import * as fd from 'formdata-node';
+import { type File, type FilePropertyBag } from 'formdata-node';
+import KeepAliveAgent from 'agentkeepalive';
+import { AbortController as AbortControllerPolyfill } from 'abort-controller';
+import { ReadStream as FsReadStream } from 'node:fs';
+import { type Agent } from 'node:http';
+import { FormDataEncoder } from 'form-data-encoder';
+import { Readable } from 'node:stream';
+import { type RequestOptions } from '../core';
+import { MultipartBody } from './MultipartBody';
+import { type Shims } from './registry';
+
+type FileFromPathOptions = Omit<FilePropertyBag, 'lastModified'>;
+
+let fileFromPathWarned = false;
+
+/**
+ * @deprecated use fs.createReadStream('./my/file.txt') instead
+ */
+async function fileFromPath(path: string): Promise<File>;
+async function fileFromPath(path: string, filename?: string): Promise<File>;
+async function fileFromPath(path: string, options?: FileFromPathOptions): Promise<File>;
+async function fileFromPath(path: string, filename?: string, options?: FileFromPathOptions): Promise<File>;
+async function fileFromPath(path: string, ...args: any[]): Promise<File> {
+  // this import fails in environments that don't handle export maps correctly, like old versions of Jest
+  const { fileFromPath: _fileFromPath } = await import('formdata-node/file-from-path');
+
+  if (!fileFromPathWarned) {
+    console.warn(`fileFromPath is deprecated; use fs.createReadStream(${JSON.stringify(path)}) instead`);
+    fileFromPathWarned = true;
+  }
+  // @ts-ignore
+  return await _fileFromPath(path, ...args);
+}
+
+const defaultHttpAgent: Agent = new KeepAliveAgent({ keepAlive: true, timeout: 5 * 60 * 1000 });
+const defaultHttpsAgent: Agent = new KeepAliveAgent.HttpsAgent({ keepAlive: true, timeout: 5 * 60 * 1000 });
+
+async function getMultipartRequestOptions<T extends {} = Record<string, unknown>>(
+  form: fd.FormData,
+  opts: RequestOptions<T>,
+): Promise<RequestOptions<T>> {
+  const encoder = new FormDataEncoder(form);
+  const readable = Readable.from(encoder);
+  const body = new MultipartBody(readable);
+  const headers = {
+    ...opts.headers,
+    ...encoder.headers,
+    'Content-Length': encoder.contentLength,
+  };
+
+  return { ...opts, body: body as any, headers };
+}
+
+export function getRuntime(): Shims {
+  // Polyfill global object if needed.
+  if (typeof AbortController === 'undefined') {
+    // @ts-ignore
+    AbortController = AbortControllerPolyfill;
+  }
+  return {
+    kind: 'node',
+    fetch: nf.default,
+    Request: nf.Request,
+    Response: nf.Response,
+    Headers: nf.Headers,
+    FormData: fd.FormData,
+    Blob: fd.Blob,
+    File: fd.File,
+    getMultipartRequestOptions,
+    getDefaultAgent: (url: string): Agent => (url.startsWith('https') ? defaultHttpsAgent : defaultHttpAgent),
+    fileFromPath,
+    isFsReadStream: (value: any): value is FsReadStream => value instanceof FsReadStream,
+  };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+import * as nf from 'node-fetch';
+import * as fd from 'formdata-node';
+
+export { type Agent } from 'node:http';
+export { type Readable } from 'node:stream';
+export { type ReadStream as FsReadStream } from 'node:fs';
+export { type ReadableStream } from 'web-streams-polyfill';
+
+export const fetch: typeof nf.default;
+
+export type Request = nf.Request;
+export type RequestInfo = nf.RequestInfo;
+export type RequestInit = nf.RequestInit;
+
+export type Response = nf.Response;
+export type ResponseInit = nf.ResponseInit;
+export type ResponseType = nf.ResponseType;
+export type BodyInit = nf.BodyInit;
+export type Headers = nf.Headers;
+export type HeadersInit = nf.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'>;
+
+export type FormData = fd.FormData;
+export const FormData: typeof fd.FormData;
+export type File = fd.File;
+export const File: typeof fd.File;
+export type Blob = fd.Blob;
+export const Blob: typeof fd.Blob;

package/src/_shims/node-types.js

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

package/src/_shims/node-types.mjs

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

package/src/_shims/registry.ts

@@ -0,0 +1,64 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+import { type RequestOptions } from '../core';
+
+export interface Shims {
+  kind: string;
+  fetch: any;
+  Request: any;
+  Response: any;
+  Headers: any;
+  FormData: any;
+  Blob: any;
+  File: any;
+  getMultipartRequestOptions: <T extends {} = Record<string, unknown>>(
+    form: Shims['FormData'],
+    opts: RequestOptions<T>,
+  ) => Promise<RequestOptions<T>>;
+  getDefaultAgent: (url: string) => any;
+  fileFromPath:
+    | ((path: string, filename?: string, options?: {}) => Promise<Shims['File']>)
+    | ((path: string, options?: {}) => Promise<Shims['File']>);
+  isFsReadStream: (value: any) => boolean;
+}
+
+export let auto = false;
+export let kind: Shims['kind'] | undefined = undefined;
+export let fetch: Shims['fetch'] | undefined = undefined;
+export let Request: Shims['Request'] | undefined = undefined;
+export let Response: Shims['Response'] | undefined = undefined;
+export let Headers: Shims['Headers'] | undefined = undefined;
+export let FormData: Shims['FormData'] | undefined = undefined;
+export let Blob: Shims['Blob'] | undefined = undefined;
+export let File: Shims['File'] | undefined = undefined;
+export let getMultipartRequestOptions: Shims['getMultipartRequestOptions'] | undefined = undefined;
+export let getDefaultAgent: Shims['getDefaultAgent'] | undefined = undefined;
+export let fileFromPath: Shims['fileFromPath'] | undefined = undefined;
+export let isFsReadStream: Shims['isFsReadStream'] | undefined = undefined;
+
+export function setShims(shims: Shims, options: { auto: boolean } = { auto: false }) {
+  if (auto) {
+    throw new Error(
+      `you must \`import '@tryfinch/finch-api/shims/${shims.kind}'\` before importing anything else from @tryfinch/finch-api`,
+    );
+  }
+  if (kind) {
+    throw new Error(
+      `can't \`import '@tryfinch/finch-api/shims/${shims.kind}'\` after \`import '@tryfinch/finch-api/shims/${kind}'\``,
+    );
+  }
+  auto = options.auto;
+  kind = shims.kind;
+  fetch = shims.fetch;
+  Request = shims.Request;
+  Response = shims.Response;
+  Headers = shims.Headers;
+  FormData = shims.FormData;
+  Blob = shims.Blob;
+  File = shims.File;
+  getMultipartRequestOptions = shims.getMultipartRequestOptions;
+  getDefaultAgent = shims.getDefaultAgent;
+  fileFromPath = shims.fileFromPath;
+  isFsReadStream = shims.isFsReadStream;
+}

package/src/_shims/web-runtime.ts

@@ -0,0 +1,91 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+import { MultipartBody } from './MultipartBody';
+import { type RequestOptions } from '../core';
+import { type Shims } from './registry';
+
+export function getRuntime({ manuallyImported }: { manuallyImported?: boolean } = {}): Shims {
+  const recommendation =
+    manuallyImported ?
+      `You may need to use polyfills`
+    : `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)
+`;
+
+  let _fetch, _Request, _Response, _Headers;
+  try {
+    // @ts-ignore
+    _fetch = fetch;
+    // @ts-ignore
+    _Request = Request;
+    // @ts-ignore
+    _Response = Response;
+    // @ts-ignore
+    _Headers = Headers;
+  } catch (error) {
+    throw new Error(
+      `this environment is missing the following Web Fetch API type: ${
+        (error as any).message
+      }. ${recommendation}`,
+    );
+  }
+
+  return {
+    kind: 'web',
+    fetch: _fetch,
+    Request: _Request,
+    Response: _Response,
+    Headers: _Headers,
+    FormData:
+      // @ts-ignore
+      typeof FormData !== 'undefined' ? FormData : (
+        class FormData {
+          // @ts-ignore
+          constructor() {
+            throw new Error(
+              `file uploads aren't supported in this environment yet as 'FormData' is undefined. ${recommendation}`,
+            );
+          }
+        }
+      ),
+    Blob:
+      typeof Blob !== 'undefined' ? Blob : (
+        class Blob {
+          constructor() {
+            throw new Error(
+              `file uploads aren't supported in this environment yet as 'Blob' is undefined. ${recommendation}`,
+            );
+          }
+        }
+      ),
+    File:
+      // @ts-ignore
+      typeof File !== 'undefined' ? File : (
+        class File {
+          // @ts-ignore
+          constructor() {
+            throw new Error(
+              `file uploads aren't supported in this environment yet as 'File' is undefined. ${recommendation}`,
+            );
+          }
+        }
+      ),
+    getMultipartRequestOptions: async <T extends {} = Record<string, unknown>>(
+      // @ts-ignore
+      form: FormData,
+      opts: RequestOptions<T>,
+    ): Promise<RequestOptions<T>> => ({
+      ...opts,
+      body: new MultipartBody(form) as any,
+    }),
+    getDefaultAgent: (url: string) => undefined,
+    fileFromPath: () => {
+      throw new Error(
+        'The `fileFromPath` function is only supported in Node. See the README for more details: https://www.github.com/Finch-API/finch-api-node#file-uploads',
+      );
+    },
+    isFsReadStream: (value: any) => false,
+  };
+}

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,23 +1,30 @@
-import { VERSION } from './version.js';
-import { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError } from './error.js';
-import type { Readable } from './_shims/node-readable.js';
-import { getDefaultAgent, type Agent } from './_shims/agent.js';
+import { VERSION } from './version';
 import {
+  FinchError,
+  APIError,
+  APIConnectionError,
+  APIConnectionTimeoutError,
+  APIUserAbortError,
+} from './error';
+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.js';
+import { isMultipartBody } from './uploads';
 export {
   maybeMultipartFormRequestOptions,
   multipartFormRequestOptions,
   createForm,
   type Uploadable,
-} from './uploads.js';
+} from './uploads';
 
 const MAX_RETRIES = 2;
 
@@ -77,6 +84,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 +99,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 +290,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'];
     }
 
@@ -370,7 +390,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;
 
@@ -419,7 +439,7 @@ export abstract class APIClient {
         if (value === null) {
           return `${encodeURIComponent(key)}=`;
         }
-        throw new Error(
+        throw new FinchError(
           `Cannot stringify type ${typeof value}; Expected string, number, boolean, or null. If you need to pass nested query parameters, you can manually encode them, e.g. { query: { 'foo[key1]': value1, 'foo[key2]': value2 } }, and please open a GitHub issue requesting better support for your use case.`,
         );
       })
@@ -437,11 +457,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 {
@@ -456,6 +479,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;
 
@@ -476,32 +502,37 @@ export abstract class APIClient {
     retriesRemaining -= 1;
 
     // About the Retry-After header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
-    //
-    // TODO: we may want to handle the case where the header is using the http-date syntax: "Retry-After: <http-date>".
-    // See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After#syntax for details.
-    const retryAfter = parseInt(responseHeaders?.['retry-after'] || '');
+    let timeoutMillis: number | undefined;
+    const retryAfterHeader = responseHeaders?.['retry-after'];
+    if (retryAfterHeader) {
+      const timeoutSeconds = parseInt(retryAfterHeader);
+      if (!Number.isNaN(timeoutSeconds)) {
+        timeoutMillis = timeoutSeconds * 1000;
+      } else {
+        timeoutMillis = Date.parse(retryAfterHeader) - Date.now();
+      }
+    }
 
-    const maxRetries = options.maxRetries ?? this.maxRetries;
-    const timeout = this.calculateRetryTimeoutSeconds(retriesRemaining, retryAfter, maxRetries) * 1000;
-    await sleep(timeout);
+    // If the API asks us to wait a certain amount of time (and it's a reasonable amount),
+    // just do what it says, but otherwise calculate a default
+    if (
+      !timeoutMillis ||
+      !Number.isInteger(timeoutMillis) ||
+      timeoutMillis <= 0 ||
+      timeoutMillis > 60 * 1000
+    ) {
+      const maxRetries = options.maxRetries ?? this.maxRetries;
+      timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
+    }
+    await sleep(timeoutMillis);
 
     return this.makeRequest(options, retriesRemaining);
   }
 
-  private calculateRetryTimeoutSeconds(
-    retriesRemaining: number,
-    retryAfter: number,
-    maxRetries: number,
-  ): number {
+  private calculateDefaultRetryTimeoutMillis(retriesRemaining: number, maxRetries: number): number {
     const initialRetryDelay = 0.5;
     const maxRetryDelay = 2;
 
-    // If the API asks us to wait a certain amount of time (and it's a reasonable amount),
-    // just do what it says.
-    if (Number.isInteger(retryAfter) && retryAfter <= 60) {
-      return retryAfter;
-    }
-
     const numRetries = maxRetries - retriesRemaining;
 
     // Apply exponential backoff, but not more than the max.
@@ -510,7 +541,7 @@ export abstract class APIClient {
     // Apply some jitter, plus-or-minus half a second.
     const jitter = Math.random() - 0.5;
 
-    return sleepSeconds + jitter;
+    return (sleepSeconds + jitter) * 1000;
   }
 
   private getUserAgent(): string {
@@ -572,7 +603,7 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
   async getNextPage(): Promise<this> {
     const nextInfo = this.nextPageInfo();
     if (!nextInfo) {
-      throw new Error(
+      throw new FinchError(
         'No next page expected; please check `.hasNextPage()` before calling `.getNextPage()`.',
       );
     }
@@ -582,7 +613,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();
@@ -708,7 +739,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 &&
@@ -898,10 +929,10 @@ export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve
 
 const validatePositiveInteger = (name: string, n: unknown): number => {
   if (typeof n !== 'number' || !Number.isInteger(n)) {
-    throw new Error(`${name} must be an integer`);
+    throw new FinchError(`${name} must be an integer`);
   }
   if (n < 0) {
-    throw new Error(`${name} must be a positive integer`);
+    throw new FinchError(`${name} must be a positive integer`);
   }
   return n;
 };
@@ -912,7 +943,7 @@ export const castToError = (err: any): Error => {
 };
 
 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.`);
+  if (value == null) throw new FinchError(`Expected a value to be given but received ${value} instead.`);
   return value;
 };
 
@@ -935,14 +966,14 @@ export const coerceInteger = (value: unknown): number => {
   if (typeof value === 'number') return Math.round(value);
   if (typeof value === 'string') return parseInt(value, 10);
 
-  throw new Error(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+  throw new FinchError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
 };
 
 export const coerceFloat = (value: unknown): number => {
   if (typeof value === 'number') return value;
   if (typeof value === 'string') return parseFloat(value);
 
-  throw new Error(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+  throw new FinchError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
 };
 
 export const coerceBoolean = (value: unknown): boolean => {
@@ -1046,5 +1077,5 @@ export const toBase64 = (str: string | null | undefined): string => {
     return btoa(str);
   }
 
-  throw new Error('Cannot generate b64 string; Expected `Buffer` or `btoa` to be defined');
+  throw new FinchError('Cannot generate b64 string; Expected `Buffer` or `btoa` to be defined');
 };