modern-treasury 2.2.0 → 2.4.0

package/src/core.ts

@@ -1,26 +1,122 @@
-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 { 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 {
   fetch,
   isPolyfilled as fetchIsPolyfilled,
   type RequestInfo,
   type RequestInit,
   type Response,
+  type HeadersInit,
 } from './_shims/fetch.js';
-import { isMultipartBody } from './uploads';
+export { type Response };
+import { isMultipartBody } from './uploads.js';
 export {
   maybeMultipartFormRequestOptions,
   multipartFormRequestOptions,
   createForm,
   type Uploadable,
-} from './uploads';
+} from './uploads.js';
 
 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 any 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;
@@ -33,7 +129,7 @@ export abstract class APIClient {
   constructor({
     baseURL,
     maxRetries,
-    timeout = 60 * 1000, // 60s
+    timeout = 60000, // 1 minute
     httpAgent,
     fetch: overridenFetch,
   }: {
@@ -51,7 +147,7 @@ export abstract class APIClient {
     this.fetch = overridenFetch ?? fetch;
   }
 
-  protected authHeaders(): Headers {
+  protected authHeaders(opts: FinalRequestOptions): Headers {
     return {};
   }
 
@@ -63,13 +159,13 @@ export abstract class APIClient {
    *    Authorization: 'Bearer 123',
    *  }
    */
-  protected defaultHeaders(): Headers {
+  protected defaultHeaders(opts: FinalRequestOptions): Headers {
     return {
       Accept: 'application/json',
       'Content-Type': 'application/json',
       'User-Agent': this.getUserAgent(),
       ...getPlatformHeaders(),
-      ...this.authHeaders(),
+      ...this.authHeaders(opts),
     };
   }
 
@@ -84,27 +180,39 @@ export abstract class APIClient {
     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?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'post', path, ...opts });
+
+  post<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('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 });
   }
 
@@ -140,7 +248,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.
@@ -155,7 +266,7 @@ export abstract class APIClient {
 
     const reqHeaders: Record<string, string> = {
       ...(contentLength && { 'Content-Length': contentLength }),
-      ...this.defaultHeaders(),
+      ...this.defaultHeaders(options),
       ...headers,
     };
     // let builtin fetch set the Content-Type for multipart bodies
@@ -187,7 +298,19 @@ export abstract class APIClient {
    * This is useful for cases where you want to add certain headers based off of
    * the request properties, e.g. `method` or `url`.
    */
-  protected async prepareRequest(request: RequestInit, { url }: { url: string }): Promise<void> {}
+  protected async prepareRequest(
+    request: RequestInit,
+    { url, options }: { url: string; options: FinalRequestOptions },
+  ): Promise<void> {}
+
+  protected parseHeaders(headers: HeadersInit | null | undefined): Record<string, string> {
+    return (
+      !headers ? {}
+      : Symbol.iterator in headers ?
+        Object.fromEntries(Array.from(headers as Iterable<string[]>).map((header) => [...header]))
+      : { ...headers }
+    );
+  }
 
   protected makeStatusError(
     status: number | undefined,
@@ -198,14 +321,27 @@ 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(
+    optionsInput: PromiseOrValue<FinalRequestOptions>,
+    retriesRemaining: number | null,
+  ): Promise<APIResponseProps> {
+    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);
+    await this.prepareRequest(req, { url, options });
+
+    debug('request', url, options, req.headers);
 
     if (options.signal?.aborted) {
       throw new APIUserAbortError();
@@ -238,45 +374,24 @@ 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 {
+  buildURL<Req extends Record<string, unknown>>(path: string, query: Req | null | undefined): string {
     const url =
       isAbsoluteURL(path) ?
         new URL(path)
@@ -353,11 +468,11 @@ export abstract class APIClient {
     return false;
   }
 
-  private async retryRequest<Req extends {}, Rsp>(
-    options: FinalRequestOptions<Req>,
+  private async retryRequest(
+    options: FinalRequestOptions,
     retriesRemaining: number,
     responseHeaders?: Headers | undefined,
-  ): Promise<Rsp> {
+  ): Promise<APIResponseProps> {
     retriesRemaining -= 1;
 
     // About the Retry-After header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
@@ -370,7 +485,7 @@ export abstract class APIClient {
     const timeout = this.calculateRetryTimeoutSeconds(retriesRemaining, retryAfter, maxRetries) * 1000;
     await sleep(timeout);
 
-    return this.request(options, retriesRemaining);
+    return this.makeRequest(options, retriesRemaining);
   }
 
   private calculateRetryTimeoutSeconds(
@@ -401,12 +516,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 {
@@ -436,9 +545,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;
   }
 
   /**
@@ -455,7 +569,7 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
     return this.nextPageInfo() != null;
   }
 
-  async getNextPage(): Promise<AbstractPage<Item>> {
+  async getNextPage(): Promise<this> {
     const nextInfo = this.nextPageInfo();
     if (!nextInfo) {
       throw new Error(
@@ -495,35 +609,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:
    *
@@ -610,11 +722,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';
@@ -628,12 +735,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 => {
@@ -668,7 +776,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,
@@ -679,6 +800,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 (typeof navigator === 'undefined' || !navigator) {
+    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
@@ -760,14 +919,16 @@ export const ensurePresent = <T>(value: T | null | undefined): T => {
 /**
  * Read an environment variable.
  *
- * Will return an empty string if the environment variable doesn't exist or cannot be accessed.
+ * 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 undefined;
+  if (typeof process !== 'undefined') {
+    return process.env?.[env] ?? undefined;
   }
-
-  return process.env[env] ?? undefined;
+  if (typeof Deno !== 'undefined') {
+    return Deno.env?.get?.(env);
+  }
+  return undefined;
 };
 
 export const coerceInteger = (value: unknown): number => {
@@ -823,6 +984,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(`ModernTreasury:DEBUG:${action}`, ...args);
+  }
+}
+
 /**
  * https://stackoverflow.com/a/2117523
  */
@@ -834,6 +1001,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

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import { castToError, Headers } from './core';
+import { castToError, Headers } from './core.js';
 
 export class APIError extends Error {
   readonly status: number | undefined;