@roarkanalytics/sdk 2.21.1 → 2.22.0

package/src/internal/qs/utils.ts

@@ -1,10 +1,13 @@
 import { RFC1738 } from './formats';
 import type { DefaultEncoder, Format } from './types';
+import { isArray } from '../utils/values';
 
-const has = Object.prototype.hasOwnProperty;
-const is_array = Array.isArray;
+export let has = (obj: object, key: PropertyKey): boolean => (
+  (has = (Object as any).hasOwn ?? Function.prototype.call.bind(Object.prototype.hasOwnProperty)),
+  has(obj, key)
+);
 
-const hex_table = (() => {
+const hex_table = /* @__PURE__ */ (() => {
   const array = [];
   for (let i = 0; i < 256; ++i) {
     array.push('%' + ((i < 16 ? '0' : '') + i.toString(16)).toUpperCase());
@@ -20,7 +23,7 @@ function compact_queue<T extends Record<string, any>>(queue: Array<{ obj: T; pro
 
     const obj = item.obj[item.prop];
 
-    if (is_array(obj)) {
+    if (isArray(obj)) {
       const compacted: unknown[] = [];
 
       for (let j = 0; j < obj.length; ++j) {
@@ -56,13 +59,10 @@ export function merge(
   }
 
   if (typeof source !== 'object') {
-    if (is_array(target)) {
+    if (isArray(target)) {
       target.push(source);
     } else if (target && typeof target === 'object') {
-      if (
-        (options && (options.plainObjects || options.allowPrototypes)) ||
-        !has.call(Object.prototype, source)
-      ) {
+      if ((options && (options.plainObjects || options.allowPrototypes)) || !has(Object.prototype, source)) {
         target[source] = true;
       }
     } else {
@@ -77,14 +77,14 @@ export function merge(
   }
 
   let mergeTarget = target;
-  if (is_array(target) && !is_array(source)) {
+  if (isArray(target) && !isArray(source)) {
     // @ts-ignore
     mergeTarget = array_to_object(target, options);
   }
 
-  if (is_array(target) && is_array(source)) {
+  if (isArray(target) && isArray(source)) {
     source.forEach(function (item, i) {
-      if (has.call(target, i)) {
+      if (has(target, i)) {
         const targetItem = target[i];
         if (targetItem && typeof targetItem === 'object' && item && typeof item === 'object') {
           target[i] = merge(targetItem, item, options);
@@ -101,7 +101,7 @@ export function merge(
   return Object.keys(source).reduce(function (acc, key) {
     const value = source[key];
 
-    if (has.call(acc, key)) {
+    if (has(acc, key)) {
       acc[key] = merge(acc[key], value, options);
     } else {
       acc[key] = value;
@@ -254,7 +254,7 @@ export function combine(a: any, b: any) {
 }
 
 export function maybe_map<T>(val: T[], fn: (v: T) => T) {
-  if (is_array(val)) {
+  if (isArray(val)) {
     const mapped = [];
     for (let i = 0; i < val.length; i += 1) {
       mapped.push(fn(val[i]!));

package/src/internal/request-options.ts

@@ -3,55 +3,79 @@
 import { NullableHeaders } from './headers';
 
 import type { BodyInit } from './builtin-types';
-import { isEmptyObj, hasOwn } from './utils/values';
-import type { HTTPMethod, KeysEnum, MergedRequestInit } from './types';
+import type { HTTPMethod, MergedRequestInit } from './types';
 import { type HeadersLike } from './headers';
 
 export type FinalRequestOptions = RequestOptions & { method: HTTPMethod; path: string };
 
 export type RequestOptions = {
+  /**
+   * The HTTP method for the request (e.g., 'get', 'post', 'put', 'delete').
+   */
   method?: HTTPMethod;
+
+  /**
+   * The URL path for the request.
+   *
+   * @example "/v1/foo"
+   */
   path?: string;
+
+  /**
+   * Query parameters to include in the request URL.
+   */
   query?: object | undefined | null;
+
+  /**
+   * The request body. Can be a string, JSON object, FormData, or other supported types.
+   */
   body?: unknown;
+
+  /**
+   * HTTP headers to include with the request. Can be a Headers object, plain object, or array of tuples.
+   */
   headers?: HeadersLike;
+
+  /**
+   * 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;
+
   stream?: boolean | undefined;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * @unit milliseconds
+   */
   timeout?: number;
+
+  /**
+   * Additional `RequestInit` options to be passed to the underlying `fetch` call.
+   * These options will be merged with the client's default fetch options.
+   */
   fetchOptions?: MergedRequestInit;
+
+  /**
+   * An AbortSignal that can be used to cancel the request.
+   */
   signal?: AbortSignal | undefined | null;
-  idempotencyKey?: string;
 
-  __binaryResponse?: boolean | undefined;
-};
+  /**
+   * A unique key for this request to enable idempotency.
+   */
+  idempotencyKey?: string;
 
-// This is required so that we can determine if a given object matches the RequestOptions
-// type at runtime. While this requires duplication, it is enforced by the TypeScript
-// compiler such that any missing / extraneous keys will cause an error.
-const requestOptionsKeys: KeysEnum<RequestOptions> = {
-  method: true,
-  path: true,
-  query: true,
-  body: true,
-  headers: true,
-
-  maxRetries: true,
-  stream: true,
-  timeout: true,
-  fetchOptions: true,
-  signal: true,
-  idempotencyKey: true,
-
-  __binaryResponse: true,
-};
+  /**
+   * Override the default base URL for this specific request.
+   */
+  defaultBaseURL?: string | undefined;
 
-export const isRequestOptions = (obj: unknown): obj is RequestOptions => {
-  return (
-    typeof obj === 'object' &&
-    obj !== null &&
-    !isEmptyObj(obj) &&
-    Object.keys(obj).every((k) => hasOwn(requestOptionsKeys, k))
-  );
+  __binaryResponse?: boolean | undefined;
 };
 
 export type EncodedContent = { bodyHeaders: HeadersLike; body: BodyInit };

package/src/internal/shim-types.ts

@@ -0,0 +1,26 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+/**
+ * Shims for types that we can't always rely on being available globally.
+ *
+ * Note: these only exist at the type-level, there is no corresponding runtime
+ * version for any of these symbols.
+ */
+
+type NeverToAny<T> = T extends never ? any : T;
+
+/** @ts-ignore */
+type _DOMReadableStream<R = any> = globalThis.ReadableStream<R>;
+
+/** @ts-ignore */
+type _NodeReadableStream<R = any> = import('stream/web').ReadableStream<R>;
+
+type _ConditionalNodeReadableStream<R = any> =
+  typeof globalThis extends { ReadableStream: any } ? never : _NodeReadableStream<R>;
+
+type _ReadableStream<R = any> = NeverToAny<
+  | ([0] extends [1 & _DOMReadableStream<R>] ? never : _DOMReadableStream<R>)
+  | ([0] extends [1 & _ConditionalNodeReadableStream<R>] ? never : _ConditionalNodeReadableStream<R>)
+>;
+
+export type { _ReadableStream as ReadableStream };

package/src/internal/shims.ts

@@ -7,8 +7,8 @@
  * messages in cases where an environment isn't fully supported.
  */
 
-import { type Fetch } from './builtin-types';
-import { type ReadableStream } from './shim-types';
+import type { Fetch } from './builtin-types';
+import type { ReadableStream } from './shim-types';
 
 export function getDefaultFetch(): Fetch {
   if (typeof fetch !== 'undefined') {
@@ -20,62 +20,6 @@ export function getDefaultFetch(): Fetch {
   );
 }
 
-/**
- * A minimal copy of the NodeJS `stream.Readable` class so that we can
- * accept the NodeJS types in certain places, e.g. file uploads
- *
- * https://nodejs.org/api/stream.html#class-streamreadable
- */
-export interface ReadableLike {
-  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>;
-}
-
-/**
- * Determines if the given value looks like a NodeJS `stream.Readable`
- * object and that it is readable, i.e. has not been consumed.
- *
- * https://nodejs.org/api/stream.html#class-streamreadable
- */
-export function isReadableLike(value: any) {
-  // We declare our own class of Readable here, so it's not feasible to
-  // do an 'instanceof' check. Instead, check for Readable-like properties.
-  return !!value && value.readable === true && typeof value.read === 'function';
-}
-
-/**
- * A minimal copy of the NodeJS `fs.ReadStream` class for usage within file uploads.
- *
- * https://nodejs.org/api/fs.html#class-fsreadstream
- */
-export interface FsReadStreamLike extends ReadableLike {
-  path: {}; // real type is string | Buffer but we can't reference `Buffer` here
-}
-
-/**
- * Determines if the given value looks like a NodeJS `fs.ReadStream`
- * object.
- *
- * This just checks if the object matches our `Readable` interface
- * and defines a `path` property, there may be false positives.
- *
- * https://nodejs.org/api/fs.html#class-fsreadstream
- */
-export function isFsReadStreamLike(value: any): value is FsReadStreamLike {
-  return isReadableLike(value) && 'path' in value;
-}
-
 type ReadableStreamArgs = ConstructorParameters<typeof ReadableStream>;
 
 export function makeReadableStream(...args: ReadableStreamArgs): ReadableStream {
@@ -143,3 +87,21 @@ export function ReadableStreamToAsyncIterable<T>(stream: any): AsyncIterableIter
     },
   };
 }
+
+/**
+ * Cancels a ReadableStream we don't need to consume.
+ * See https://undici.nodejs.org/#/?id=garbage-collection
+ */
+export async function CancelReadableStream(stream: any): Promise<void> {
+  if (stream === null || typeof stream !== 'object') return;
+
+  if (stream[Symbol.asyncIterator]) {
+    await stream[Symbol.asyncIterator]().return?.();
+    return;
+  }
+
+  const reader = stream.getReader();
+  const cancelPromise = reader.cancel();
+  reader.releaseLock();
+  await cancelPromise;
+}

package/src/internal/to-file.ts

@@ -0,0 +1,154 @@
+import { BlobPart, getName, makeFile, isAsyncIterable } from './uploads';
+import type { FilePropertyBag } from './builtin-types';
+import { checkFileSupport } from './uploads';
+
+type BlobLikePart = string | ArrayBuffer | ArrayBufferView | BlobLike | DataView;
+
+/**
+ * Intended to match DOM Blob, node-fetch Blob, node:buffer Blob, etc.
+ * Don't add arrayBuffer here, node-fetch doesn't have it
+ */
+interface BlobLike {
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/size) */
+  readonly size: number;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/type) */
+  readonly type: string;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/text) */
+  text(): Promise<string>;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/slice) */
+  slice(start?: number, end?: number): BlobLike;
+}
+
+/**
+ * This check adds the arrayBuffer() method type because it is available and used at runtime
+ */
+const isBlobLike = (value: any): value is BlobLike & { arrayBuffer(): Promise<ArrayBuffer> } =>
+  value != null &&
+  typeof value === 'object' &&
+  typeof value.size === 'number' &&
+  typeof value.type === 'string' &&
+  typeof value.text === 'function' &&
+  typeof value.slice === 'function' &&
+  typeof value.arrayBuffer === 'function';
+
+/**
+ * Intended to match DOM File, node:buffer File, undici File, etc.
+ */
+interface FileLike extends BlobLike {
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/lastModified) */
+  readonly lastModified: number;
+  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/name) */
+  readonly name?: string | undefined;
+}
+
+/**
+ * This check adds the arrayBuffer() method type because it is available and used at runtime
+ */
+const isFileLike = (value: any): value is FileLike & { arrayBuffer(): Promise<ArrayBuffer> } =>
+  value != null &&
+  typeof value === 'object' &&
+  typeof value.name === 'string' &&
+  typeof value.lastModified === 'number' &&
+  isBlobLike(value);
+
+/**
+ * Intended to match DOM Response, node-fetch Response, undici Response, etc.
+ */
+export interface ResponseLike {
+  url: string;
+  blob(): Promise<BlobLike>;
+}
+
+const isResponseLike = (value: any): value is ResponseLike =>
+  value != null &&
+  typeof value === 'object' &&
+  typeof value.url === 'string' &&
+  typeof value.blob === 'function';
+
+export type ToFileInput =
+  | FileLike
+  | ResponseLike
+  | Exclude<BlobLikePart, string>
+  | AsyncIterable<BlobLikePart>;
+
+/**
+ * Helper for creating a {@link File} to pass to an SDK upload method from a variety of different data formats
+ * @param value the raw content of the file. Can be an {@link Uploadable}, BlobLikePart, or AsyncIterable of BlobLikeParts
+ * @param {string=} name the name of the file. If omitted, toFile will try to determine a file name from bits if possible
+ * @param {Object=} options additional properties
+ * @param {string=} options.type the MIME type of the content
+ * @param {number=} options.lastModified the last modified timestamp
+ * @returns a {@link File} with the given properties
+ */
+export async function toFile(
+  value: ToFileInput | PromiseLike<ToFileInput>,
+  name?: string | null | undefined,
+  options?: FilePropertyBag | undefined,
+): Promise<File> {
+  checkFileSupport();
+
+  // If it's a promise, resolve it.
+  value = await value;
+
+  // If we've been given a `File` we don't need to do anything
+  if (isFileLike(value)) {
+    if (value instanceof File) {
+      return value;
+    }
+    return makeFile([await value.arrayBuffer()], value.name);
+  }
+
+  if (isResponseLike(value)) {
+    const blob = await value.blob();
+    name ||= new URL(value.url).pathname.split(/[\\/]/).pop();
+
+    return makeFile(await getBytes(blob), name, options);
+  }
+
+  const parts = await getBytes(value);
+
+  name ||= getName(value);
+
+  if (!options?.type) {
+    const type = parts.find((part) => typeof part === 'object' && 'type' in part && part.type);
+    if (typeof type === 'string') {
+      options = { ...options, type };
+    }
+  }
+
+  return makeFile(parts, name, options);
+}
+
+async function getBytes(value: BlobLikePart | AsyncIterable<BlobLikePart>): Promise<Array<BlobPart>> {
+  let parts: Array<BlobPart> = [];
+  if (
+    typeof value === 'string' ||
+    ArrayBuffer.isView(value) || // includes Uint8Array, Buffer, etc.
+    value instanceof ArrayBuffer
+  ) {
+    parts.push(value);
+  } else if (isBlobLike(value)) {
+    parts.push(value instanceof Blob ? value : await value.arrayBuffer());
+  } else if (
+    isAsyncIterable(value) // includes Readable, ReadableStream, etc.
+  ) {
+    for await (const chunk of value) {
+      parts.push(...(await getBytes(chunk as BlobLikePart))); // TODO, consider validating?
+    }
+  } else {
+    const constructor = value?.constructor?.name;
+    throw new Error(
+      `Unexpected data type: ${typeof value}${
+        constructor ? `; constructor: ${constructor}` : ''
+      }${propsForError(value)}`,
+    );
+  }
+
+  return parts;
+}
+
+function propsForError(value: unknown): string {
+  if (typeof value !== 'object' || value === null) return '';
+  const props = Object.getOwnPropertyNames(value);
+  return `; props: [${props.map((p) => `"${p}"`).join(', ')}]`;
+}

package/src/internal/types.ts

@@ -5,15 +5,9 @@ export type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 
 export type KeysEnum<T> = { [P in keyof Required<T>]: true };
 
-type NotAny<T> = [unknown] extends [T] ? never : T;
-type Literal<T> = PropertyKey extends T ? never : T;
-type MappedLiteralKeys<T> = T extends any ? Literal<keyof T> : never;
-type MappedIndex<T, K> =
-  T extends any ?
-    K extends keyof T ?
-      T[K]
-    : never
-  : never;
+export type FinalizedRequestInit = RequestInit & { headers: Headers };
+
+type NotAny<T> = [0] extends [1 & T] ? never : T;
 
 /**
  * Some environments overload the global fetch function, and Parameters<T> only gets the last signature.
@@ -70,13 +64,15 @@ type OverloadedParameters<T> =
  * [1]: https://www.typescriptlang.org/tsconfig/#typeAcquisition
  */
 /** @ts-ignore For users with \@types/node */
-type UndiciTypesRequestInit = NotAny<import('../node_modules/undici-types').RequestInit> | NotAny<import('../../node_modules/undici-types').RequestInit> | NotAny<import('../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici-types').RequestInit>;
+type UndiciTypesRequestInit = NotAny<import('../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit>;
 /** @ts-ignore For users with undici */
-type UndiciRequestInit = NotAny<import('../node_modules/undici').RequestInit> | NotAny<import('../../node_modules/undici').RequestInit> | NotAny<import('../../../node_modules/undici').RequestInit> | NotAny<import('../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici').RequestInit>;
+type UndiciRequestInit = NotAny<import('../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici/index.d.ts').RequestInit>;
 /** @ts-ignore For users with \@types/bun */
 type BunRequestInit = globalThis.FetchRequestInit;
-/** @ts-ignore For users with node-fetch */
-type NodeFetchRequestInit = NotAny<import('../node_modules/node-fetch').RequestInit> | NotAny<import('../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/node-fetch').RequestInit>;
+/** @ts-ignore For users with node-fetch@2 */
+type NodeFetch2RequestInit = NotAny<import('../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit>;
+/** @ts-ignore For users with node-fetch@3, doesn't need file extension because types are at ./@types/index.d.ts */
+type NodeFetch3RequestInit =  NotAny<import('../node_modules/node-fetch').RequestInit> | NotAny<import('../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/node-fetch').RequestInit>;
 /** @ts-ignore For users who use Deno */
 type FetchRequestInit = NonNullable<OverloadedParameters<typeof fetch>[1]>;
 /* eslint-enable */
@@ -85,7 +81,8 @@ type RequestInits =
   | NotAny<UndiciTypesRequestInit>
   | NotAny<UndiciRequestInit>
   | NotAny<BunRequestInit>
-  | NotAny<NodeFetchRequestInit>
+  | NotAny<NodeFetch2RequestInit>
+  | NotAny<NodeFetch3RequestInit>
   | NotAny<RequestInit>
   | NotAny<FetchRequestInit>;
 
@@ -93,6 +90,6 @@ type RequestInits =
  * This type contains `RequestInit` options that may be available on the current runtime,
  * including per-platform extensions like `dispatcher`, `agent`, `client`, etc.
  */
-export type MergedRequestInit = {
-  [K in MappedLiteralKeys<RequestInits>]?: MappedIndex<RequestInits, K> | undefined;
-};
+export type MergedRequestInit = RequestInits &
+  /** We don't include these in the types as they'll be overridden for every request. */
+  Partial<Record<'body' | 'headers' | 'method' | 'signal', never>>;