@tryfinch/finch-api 3.1.1 → 4.0.0

package/src/core.ts

@@ -1,4 +1,3 @@
-import * as qs from 'qs';
 import { VERSION } from './version';
 import { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError } from './error';
 import type { Readable } from './_shims/node-readable';
@@ -10,6 +9,7 @@ import {
   type RequestInit,
   type Response,
 } from './_shims/fetch.js';
+export { type Response };
 import { isMultipartBody } from './uploads';
 export {
   maybeMultipartFormRequestOptions,
@@ -22,6 +22,100 @@ const MAX_RETRIES = 2;
 
 export type Fetch = (url: RequestInfo, init?: RequestInit) => Promise<Response>;
 
+type PromiseOrValue<T> = T | Promise<T>;
+
+type APIResponseProps = {
+  response: Response;
+  options: FinalRequestOptions;
+  controller: AbortController;
+};
+
+async function defaultParseResponse<T>(props: APIResponseProps): Promise<T> {
+  const { response } = props;
+  const contentType = response.headers.get('content-type');
+  if (contentType?.includes('application/json')) {
+    const json = await response.json();
+
+    debug('response', response.status, response.url, response.headers, json);
+
+    return json as 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;
+}
+
+/**
+ * A subclass of `Promise` providing additional helper methods
+ * for interacting with the SDK.
+ */
+export class APIPromise<T> extends Promise<T> {
+  private parsedPromise: Promise<T> | undefined;
+
+  constructor(
+    private responsePromise: Promise<APIResponseProps>,
+    private parseResponse: (props: APIResponseProps) => PromiseOrValue<T> = defaultParseResponse,
+  ) {
+    super((resolve) => {
+      // this is maybe a bit weird but this has to be a no-op to not implicitly
+      // parse the response body; instead .then, .catch, .finally are overridden
+      // to parse the response
+      resolve(null as any);
+    });
+  }
+
+  _thenUnwrap<U>(transform: (data: T) => U): APIPromise<U> {
+    return new APIPromise(this.responsePromise, async (props) => transform(await this.parseResponse(props)));
+  }
+
+  /**
+   * Gets the raw `Response` instance instead of parsing the response
+   * data.
+   *
+   * If you want to parse the response body but still get the `Response`
+   * instance, you can use {@link withResponse()}.
+   */
+  asResponse(): Promise<Response> {
+    return this.responsePromise.then((p) => p.response);
+  }
+  /**
+   * Gets the parsed response data and the raw `Response` instance.
+   *
+   * If you just want to get the raw `Response` instance without parsing it,
+   * you can use {@link asResponse()}.
+   */
+  async withResponse(): Promise<{ data: T; response: Response }> {
+    const [data, response] = await Promise.all([this.parse(), this.asResponse()]);
+    return { data, response };
+  }
+
+  private parse(): Promise<T> {
+    if (!this.parsedPromise) {
+      this.parsedPromise = this.responsePromise.then(this.parseResponse);
+    }
+    return this.parsedPromise;
+  }
+
+  override then<TResult1 = T, TResult2 = never>(
+    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
+  ): Promise<TResult1 | TResult2> {
+    return this.parse().then(onfulfilled, onrejected);
+  }
+
+  override catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null,
+  ): Promise<T | TResult> {
+    return this.parse().catch(onrejected);
+  }
+
+  override finally(onfinally?: (() => void) | undefined | null): Promise<T> {
+    return this.parse().finally(onfinally);
+  }
+}
+
 export abstract class APIClient {
   baseURL: string;
   maxRetries: number;
@@ -34,7 +128,7 @@ export abstract class APIClient {
   constructor({
     baseURL,
     maxRetries,
-    timeout = 60 * 1000, // 60s
+    timeout = 60000, // 1 minute
     httpAgent,
     fetch: overridenFetch,
   }: {
@@ -81,43 +175,43 @@ export abstract class APIClient {
    */
   protected validateHeaders(headers: Headers, customHeaders: Headers) {}
 
-  /**
-   * Override this to add your own qs.stringify options, for example:
-   *
-   *  {
-   *    ...super.qsOptions(),
-   *    strictNullHandling: true,
-   *  }
-   */
-  protected qsOptions(): qs.IStringifyOptions | undefined {
-    return {};
-  }
-
   protected defaultIdempotencyKey(): string {
     return `stainless-node-retry-${uuid4()}`;
   }
 
-  get<Req extends {}, Rsp>(path: string, opts?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'get', path, ...opts });
+  get<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('get', path, opts);
+  }
+
+  post<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('post', path, opts);
   }
-  post<Req extends {}, Rsp>(path: string, opts?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'post', path, ...opts });
+
+  patch<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('patch', path, opts);
   }
-  patch<Req extends {}, Rsp>(path: string, opts?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'patch', path, ...opts });
+
+  put<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('put', path, opts);
   }
-  put<Req extends {}, Rsp>(path: string, opts?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'put', path, ...opts });
+
+  delete<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('delete', path, opts);
   }
-  delete<Req extends {}, Rsp>(path: string, opts?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'delete', path, ...opts });
+
+  private methodRequest<Req extends {}, Rsp>(
+    method: HTTPMethod,
+    path: string,
+    opts?: PromiseOrValue<RequestOptions<Req>>,
+  ): APIPromise<Rsp> {
+    return this.request(Promise.resolve(opts).then((opts) => ({ method, path, ...opts })));
   }
 
   getAPIList<Item, PageClass extends AbstractPage<Item> = AbstractPage<Item>>(
     path: string,
     Page: new (...args: any[]) => PageClass,
     opts?: RequestOptions<any>,
-  ): PagePromise<PageClass> {
+  ): PagePromise<PageClass, Item> {
     return this.requestAPIList(Page, { method: 'get', path, ...opts });
   }
 
@@ -127,9 +221,11 @@ export abstract class APIClient {
         return Buffer.byteLength(body, 'utf8').toString();
       }
 
-      const encoder = new TextEncoder();
-      const encoded = encoder.encode(body);
-      return encoded.length.toString();
+      if (typeof TextEncoder !== 'undefined') {
+        const encoder = new TextEncoder();
+        const encoded = encoder.encode(body);
+        return encoded.length.toString();
+      }
     }
 
     return null;
@@ -151,7 +247,10 @@ export abstract class APIClient {
     const timeout = options.timeout ?? this.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)) {
+    if (
+      typeof (httpAgent as any)?.options?.timeout === 'number' &&
+      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.
@@ -209,14 +308,31 @@ export abstract class APIClient {
     return APIError.generate(status, error, message, headers);
   }
 
-  async request<Req extends {}, Rsp>(
-    options: FinalRequestOptions<Req>,
-    retriesRemaining = options.maxRetries ?? this.maxRetries,
-  ): Promise<APIResponse<Rsp>> {
+  request<Req extends {}, Rsp>(
+    options: PromiseOrValue<FinalRequestOptions<Req>>,
+    remainingRetries: number | null = null,
+  ): APIPromise<Rsp> {
+    return new APIPromise(this.makeRequest(options, remainingRetries));
+  }
+
+  private async makeRequest<T>(
+    optionsInput: PromiseOrValue<FinalRequestOptions>,
+    retriesRemaining: number | null,
+  ): Promise<{ response: Response; options: FinalRequestOptions; controller: AbortController }> {
+    const options = await optionsInput;
+    if (retriesRemaining == null) {
+      retriesRemaining = options.maxRetries ?? this.maxRetries;
+    }
+
     const { req, url, timeout } = this.buildRequest(options);
+
     await this.prepareRequest(req, { url });
 
-    this.debug('request', url, options, req.headers);
+    debug('request', url, options, req.headers);
+
+    if (options.signal?.aborted) {
+      throw new APIUserAbortError();
+    }
 
     const controller = new AbortController();
     const response = await this.fetchWithTimeout(url, req, timeout, controller).catch(castToError);
@@ -245,42 +361,21 @@ export abstract class APIClient {
       const errJSON = safeJSON(errText);
       const errMessage = errJSON ? undefined : errText;
 
-      this.debug('response', response.status, url, responseHeaders, errMessage);
+      debug('response', response.status, url, responseHeaders, errMessage);
 
       const err = this.makeStatusError(response.status, errJSON, errMessage, responseHeaders);
       throw err;
     }
 
-    const contentType = response.headers.get('content-type');
-    if (contentType?.includes('application/json')) {
-      const json = await response.json();
-
-      if (typeof json === 'object' && json != null) {
-        /** @deprecated – we expect to change this interface in the near future. */
-        Object.defineProperty(json, 'responseHeaders', {
-          enumerable: false,
-          writable: false,
-          value: responseHeaders,
-        });
-      }
-
-      this.debug('response', response.status, url, responseHeaders, json);
-
-      return json as APIResponse<Rsp>;
-    }
-
-    // TODO handle blob, arraybuffer, other content types, etc.
-    const text = response.text();
-    this.debug('response', response.status, url, responseHeaders, text);
-    return text as Promise<any>;
+    return { response, options, controller };
   }
 
   requestAPIList<Item = unknown, PageClass extends AbstractPage<Item> = AbstractPage<Item>>(
     Page: new (...args: ConstructorParameters<typeof AbstractPage>) => PageClass,
     options: FinalRequestOptions,
-  ): PagePromise<PageClass> {
-    const requestPromise = this.request(options) as Promise<APIResponse<unknown>>;
-    return new PagePromise(this, requestPromise, options, Page);
+  ): PagePromise<PageClass, Item> {
+    const request = this.makeRequest(options, null);
+    return new PagePromise<PageClass, Item>(this, request, Page);
   }
 
   buildURL<Req>(path: string, query: Req | undefined): string {
@@ -295,12 +390,29 @@ export abstract class APIClient {
     }
 
     if (query) {
-      url.search = qs.stringify(query, this.qsOptions());
+      url.search = this.stringifyQuery(query);
     }
 
     return url.toString();
   }
 
+  protected stringifyQuery(query: Record<string, unknown>): string {
+    return Object.entries(query)
+      .filter(([_, value]) => typeof value !== 'undefined')
+      .map(([key, value]) => {
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+          return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+        }
+        if (value === null) {
+          return `${encodeURIComponent(key)}=`;
+        }
+        throw new Error(
+          `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.`,
+        );
+      })
+      .join('&');
+  }
+
   async fetchWithTimeout(
     url: RequestInfo,
     init: RequestInit | undefined,
@@ -391,12 +503,6 @@ export abstract class APIClient {
   private getUserAgent(): string {
     return `${this.constructor.name}/JS ${VERSION}`;
   }
-
-  private debug(action: string, ...args: any[]) {
-    if (typeof process !== 'undefined' && process.env['DEBUG'] === 'true') {
-      console.log(`${this.constructor.name}:DEBUG:${action}`, ...args);
-    }
-  }
 }
 
 export class APIResource {
@@ -426,9 +532,14 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
   #client: APIClient;
   protected options: FinalRequestOptions;
 
-  constructor(client: APIClient, response: APIResponse<unknown>, options: FinalRequestOptions) {
+  protected response: Response;
+  protected body: unknown;
+
+  constructor(client: APIClient, response: Response, body: unknown, options: FinalRequestOptions) {
     this.#client = client;
     this.options = options;
+    this.response = response;
+    this.body = body;
   }
 
   /**
@@ -485,35 +596,33 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
   }
 }
 
+/**
+ * This subclass of Promise will resolve to an instantiated Page once the request completes.
+ *
+ * It also implements AsyncIterable to allow auto-paginating iteration on an unawaited list call, eg:
+ *
+ *    for await (const item of client.items.list()) {
+ *      console.log(item)
+ *    }
+ */
 export class PagePromise<
     PageClass extends AbstractPage<Item>,
     Item = ReturnType<PageClass['getPaginatedItems']>[number],
   >
-  extends Promise<PageClass>
+  extends APIPromise<PageClass>
   implements AsyncIterable<Item>
 {
-  /**
-   * This subclass of Promise will resolve to an instantiated Page once the request completes.
-   */
   constructor(
     client: APIClient,
-    requestPromise: Promise<APIResponse<unknown>>,
-    options: FinalRequestOptions,
+    request: Promise<APIResponseProps>,
     Page: new (...args: ConstructorParameters<typeof AbstractPage>) => PageClass,
   ) {
-    super((resolve, reject) =>
-      requestPromise.then((response) => resolve(new Page(client, response, options))).catch(reject),
+    super(
+      request,
+      async (props) => new Page(client, props.response, await defaultParseResponse(props), props.options),
     );
   }
 
-  /**
-   * Enable subclassing Promise.
-   * Ref: https://stackoverflow.com/a/60328122
-   */
-  static get [Symbol.species]() {
-    return Promise;
-  }
-
   /**
    * Allow auto-paginating iteration on an unawaited list call, eg:
    *
@@ -600,11 +709,6 @@ export type FinalRequestOptions<Req extends {} = Record<string, unknown> | Reada
   path: string;
 };
 
-export type APIResponse<T> = T & {
-  /** @deprecated - we plan to add a different way to access raw response information shortly. */
-  responseHeaders: Headers;
-};
-
 declare const Deno: any;
 declare const EdgeRuntime: any;
 type Arch = 'x32' | 'x64' | 'arm' | 'arm64' | `other:${string}` | 'unknown';
@@ -618,12 +722,13 @@ type PlatformName =
   | 'Android'
   | `Other:${string}`
   | 'Unknown';
+type Browser = 'ie' | 'edge' | 'chrome' | 'firefox' | 'safari';
 type PlatformProperties = {
   'X-Stainless-Lang': 'js';
   'X-Stainless-Package-Version': string;
   'X-Stainless-OS': PlatformName;
   'X-Stainless-Arch': Arch;
-  'X-Stainless-Runtime': 'node' | 'deno' | 'edge' | 'unknown';
+  'X-Stainless-Runtime': 'node' | 'deno' | 'edge' | `browser:${Browser}` | 'unknown';
   'X-Stainless-Runtime-Version': string;
 };
 const getPlatformProperties = (): PlatformProperties => {
@@ -658,7 +763,20 @@ const getPlatformProperties = (): PlatformProperties => {
       'X-Stainless-Runtime-Version': process.version,
     };
   }
-  // TODO add support for Cloudflare workers, browsers, etc.
+
+  const browserInfo = getBrowserInfo();
+  if (browserInfo) {
+    return {
+      'X-Stainless-Lang': 'js',
+      'X-Stainless-Package-Version': VERSION,
+      'X-Stainless-OS': 'Unknown',
+      'X-Stainless-Arch': 'unknown',
+      'X-Stainless-Runtime': `browser:${browserInfo.browser}`,
+      'X-Stainless-Runtime-Version': browserInfo.version,
+    };
+  }
+
+  // TODO add support for Cloudflare workers, etc.
   return {
     'X-Stainless-Lang': 'js',
     'X-Stainless-Package-Version': VERSION,
@@ -669,6 +787,44 @@ const getPlatformProperties = (): PlatformProperties => {
   };
 };
 
+type BrowserInfo = {
+  browser: Browser;
+  version: string;
+};
+
+declare const navigator: { userAgent: string } | undefined;
+
+// Note: modified from https://github.com/JS-DevTools/host-environment/blob/b1ab79ecde37db5d6e163c050e54fe7d287d7c92/src/isomorphic.browser.ts
+function getBrowserInfo(): BrowserInfo | null {
+  if (!navigator || typeof navigator === 'undefined') {
+    return null;
+  }
+
+  // NOTE: The order matters here!
+  const browserPatterns = [
+    { key: 'edge' as const, pattern: /Edge(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: 'ie' as const, pattern: /MSIE(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: 'ie' as const, pattern: /Trident(?:.*rv\:(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: 'chrome' as const, pattern: /Chrome(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: 'firefox' as const, pattern: /Firefox(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: 'safari' as const, pattern: /(?:Version\W+(\d+)\.(\d+)(?:\.(\d+))?)?(?:\W+Mobile\S*)?\W+Safari/ },
+  ];
+
+  // Find the FIRST matching browser
+  for (const { key, pattern } of browserPatterns) {
+    const match = pattern.exec(navigator.userAgent);
+    if (match) {
+      const major = match[1] || 0;
+      const minor = match[2] || 0;
+      const patch = match[3] || 0;
+
+      return { browser: key, version: `${major}.${minor}.${patch}` };
+    }
+  }
+
+  return null;
+}
+
 const normalizeArch = (arch: string): Arch => {
   // Node docs:
   // - https://nodejs.org/api/process.html#processarch
@@ -727,8 +883,8 @@ const isAbsoluteURL = (url: string): boolean => {
 
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
-const validatePositiveInteger = (name: string, n: number) => {
-  if (!Number.isInteger(n)) {
+const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
     throw new Error(`${name} must be an integer`);
   }
   if (n < 0) {
@@ -747,6 +903,21 @@ export const ensurePresent = <T>(value: T | null | undefined): T => {
   return value;
 };
 
+/**
+ * Read an environment variable.
+ *
+ * Will return undefined if the environment variable doesn't exist or cannot be accessed.
+ */
+export const readEnv = (env: string): string | undefined => {
+  if (typeof process !== 'undefined') {
+    return process.env?.[env] ?? undefined;
+  }
+  if (typeof Deno !== 'undefined') {
+    return Deno.env?.get?.(env);
+  }
+  return undefined;
+};
+
 export const coerceInteger = (value: unknown): number => {
   if (typeof value === 'number') return Math.round(value);
   if (typeof value === 'string') return parseInt(value, 10);
@@ -767,6 +938,27 @@ export const coerceBoolean = (value: unknown): boolean => {
   return Boolean(value);
 };
 
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
 // https://stackoverflow.com/a/34491287
 export function isEmptyObj(obj: Object | null | undefined): boolean {
   if (!obj) return true;
@@ -779,6 +971,12 @@ export function hasOwn(obj: Object, key: string): boolean {
   return Object.prototype.hasOwnProperty.call(obj, key);
 }
 
+export function debug(action: string, ...args: any[]) {
+  if (typeof process !== 'undefined' && process.env['DEBUG'] === 'true') {
+    console.log(`Finch:DEBUG:${action}`, ...args);
+  }
+}
+
 /**
  * https://stackoverflow.com/a/2117523
  */
@@ -790,6 +988,17 @@ const uuid4 = () => {
   });
 };
 
+export const isRunningInBrowser = () => {
+  return (
+    // @ts-ignore
+    typeof window !== 'undefined' &&
+    // @ts-ignore
+    typeof window.document !== 'undefined' &&
+    // @ts-ignore
+    typeof navigator !== 'undefined'
+  );
+};
+
 export interface HeadersProtocol {
   get: (header: string) => string | null | undefined;
 }

package/src/error.ts

@@ -13,12 +13,22 @@ export class APIError extends Error {
     message: string | undefined,
     headers: Headers | undefined,
   ) {
-    super(message || (error as any)?.message || 'Unknown error occurred.');
+    super(APIError.makeMessage(error, message));
     this.status = status;
     this.headers = headers;
     this.error = error;
   }
 
+  private static makeMessage(error: any, message: string | undefined) {
+    return (
+      error?.message ?
+        typeof error.message === 'string' ? error.message
+        : JSON.stringify(error.message)
+      : error ? JSON.stringify(error)
+      : message || 'Unknown error occurred'
+    );
+  }
+
   static generate(
     status: number | undefined,
     errorResponse: Object | undefined,