@tetral-ai/sdk 0.110.0-alpha.1

package/src/internal/to-file.ts

@@ -0,0 +1,159 @@
+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;
+
+  name ||= getName(value, true);
+
+  // If we've been given a `File` we don't need to do anything if the name / options
+  // have not been customised.
+  if (isFileLike(value)) {
+    if (value instanceof File && name == null && options == null) {
+      return value;
+    }
+    return makeFile([await value.arrayBuffer()], name ?? value.name, {
+      type: value.type,
+      lastModified: value.lastModified,
+      ...options,
+    });
+  }
+
+  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);
+
+  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

@@ -0,0 +1,93 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export type PromiseOrValue<T> = T | Promise<T>;
+export type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+
+export type KeysEnum<T> = { [P in keyof Required<T>]: true };
+
+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.
+ */
+type OverloadedParameters<T> =
+  T extends (
+    {
+      (...args: infer A): unknown;
+      (...args: infer B): unknown;
+      (...args: infer C): unknown;
+      (...args: infer D): unknown;
+    }
+  ) ?
+    A | B | C | D
+  : T extends (
+    {
+      (...args: infer A): unknown;
+      (...args: infer B): unknown;
+      (...args: infer C): unknown;
+    }
+  ) ?
+    A | B | C
+  : T extends (
+    {
+      (...args: infer A): unknown;
+      (...args: infer B): unknown;
+    }
+  ) ?
+    A | B
+  : T extends (...args: infer A) => unknown ? A
+  : never;
+
+/**
+ * These imports attempt to get types from a parent package's dependencies.
+ * Unresolved bare specifiers can trigger [automatic type acquisition][1] in some projects, which
+ * would cause typescript to show types not present at runtime. To avoid this, we import
+ * directly from parent node_modules folders.
+ *
+ * We need to check multiple levels because we don't know what directory structure we'll be in.
+ * For example, pnpm generates directories like this:
+ * ```
+ * node_modules
+ * ├── .pnpm
+ * │   └── pkg@1.0.0
+ * │       └── node_modules
+ * │           └── pkg
+ * │               └── internal
+ * │                   └── types.d.ts
+ * ├── pkg -> .pnpm/pkg@1.0.0/node_modules/pkg
+ * └── undici
+ * ```
+ *
+ * [1]: https://www.typescriptlang.org/tsconfig/#typeAcquisition
+ */
+/** @ts-ignore For users with \@types/node */ /* prettier-ignore */
+type UndiciTypesRequestInit = NotAny<import('undici-types').RequestInit> | NotAny<import('undici-types').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 */ /* prettier-ignore */
+type UndiciRequestInit = NotAny<import('undici').RequestInit> | NotAny<import('undici').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 */ /* prettier-ignore */
+type BunRequestInit = globalThis.FetchRequestInit;
+/** @ts-ignore For users with node-fetch@2 */ /* prettier-ignore */
+type NodeFetch2RequestInit = NotAny<import('node-fetch').RequestInit> | NotAny<import('node-fetch').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 */ /* prettier-ignore */
+type NodeFetch3RequestInit =  NotAny<import('node-fetch.js').RequestInit> | NotAny<import('node-fetch.js').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 */ /* prettier-ignore */
+type FetchRequestInit = NonNullable<OverloadedParameters<typeof fetch>[1]>;
+
+type RequestInits =
+  | NotAny<UndiciTypesRequestInit>
+  | NotAny<UndiciRequestInit>
+  | NotAny<BunRequestInit>
+  | NotAny<NodeFetch2RequestInit>
+  | NotAny<NodeFetch3RequestInit>
+  | NotAny<RequestInit>
+  | NotAny<FetchRequestInit>;
+
+/**
+ * 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 = RequestInits &
+  /** We don't include these in the types as they'll be overridden for every request. */
+  Partial<Record<'body' | 'headers' | 'method' | 'signal', never>>;

package/src/internal/uploads.ts

@@ -0,0 +1,204 @@
+import { type RequestOptions } from './request-options';
+import type { FilePropertyBag, Fetch } from './builtin-types';
+import type { BaseAnthropic } from '../client';
+import { ReadableStreamFrom } from './shims';
+
+export type BlobPart = string | ArrayBuffer | ArrayBufferView | Blob | DataView;
+type FsReadStream = AsyncIterable<Uint8Array> & { path: string | { toString(): string } };
+
+// https://github.com/oven-sh/bun/issues/5980
+interface BunFile extends Blob {
+  readonly name?: string | undefined;
+}
+
+export const checkFileSupport = () => {
+  if (typeof File === 'undefined') {
+    const { process } = globalThis as any;
+    const isOldNode =
+      typeof process?.versions?.node === 'string' && parseInt(process.versions.node.split('.')) < 20;
+    throw new Error(
+      '`File` is not defined as a global, which is required for file uploads.' +
+        (isOldNode ?
+          " Update to Node 20 LTS or newer, or set `globalThis.File` to `import('node:buffer').File`."
+        : ''),
+    );
+  }
+};
+
+/**
+ * Typically, this is a native "File" class.
+ *
+ * We provide the {@link toFile} utility to convert a variety of objects
+ * into the File class.
+ *
+ * For convenience, you can also pass a fetch Response, or in Node,
+ * the result of fs.createReadStream().
+ */
+export type Uploadable = File | Response | FsReadStream | BunFile;
+
+/**
+ * Construct a `File` instance. This is used to ensure a helpful error is thrown
+ * for environments that don't define a global `File` yet.
+ */
+export function makeFile(
+  fileBits: BlobPart[],
+  fileName: string | undefined,
+  options?: FilePropertyBag,
+): File {
+  checkFileSupport();
+  return new File(fileBits as any, fileName ?? 'unknown_file', options);
+}
+
+export function getName(value: any, stripPath: boolean): string | undefined {
+  const val =
+    (typeof value === 'object' &&
+      value !== null &&
+      (('name' in value && value.name && String(value.name)) ||
+        ('url' in value && value.url && String(value.url)) ||
+        ('filename' in value && value.filename && String(value.filename)) ||
+        ('path' in value && value.path && String(value.path)))) ||
+    '';
+
+  return stripPath ? val.split(/[\\/]/).pop() || undefined : val;
+}
+
+export const isAsyncIterable = (value: any): value is AsyncIterable<any> =>
+  value != null && typeof value === 'object' && typeof value[Symbol.asyncIterator] === 'function';
+
+/**
+ * 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 = async (
+  opts: RequestOptions,
+  fetch: BaseAnthropic | Fetch,
+): Promise<RequestOptions> => {
+  if (!hasUploadableValue(opts.body)) return opts;
+
+  return { ...opts, body: await createForm(opts.body, fetch) };
+};
+
+type MultipartFormRequestOptions = Omit<RequestOptions, 'body'> & { body: unknown };
+
+export const multipartFormRequestOptions = async (
+  opts: MultipartFormRequestOptions,
+  fetch: BaseAnthropic | Fetch,
+  stripFilenames: boolean = true,
+): Promise<RequestOptions> => {
+  return { ...opts, body: await createForm(opts.body, fetch, stripFilenames) };
+};
+
+const supportsFormDataMap = /* @__PURE__ */ new WeakMap<Fetch, Promise<boolean>>();
+
+/**
+ * node-fetch doesn't support the global FormData object in recent node versions. Instead of sending
+ * properly-encoded form data, it just stringifies the object, resulting in a request body of "[object FormData]".
+ * This function detects if the fetch function provided supports the global FormData object to avoid
+ * confusing error messages later on.
+ */
+function supportsFormData(fetchObject: BaseAnthropic | Fetch): Promise<boolean> {
+  const fetch: Fetch = typeof fetchObject === 'function' ? fetchObject : (fetchObject as any).fetch;
+  const cached = supportsFormDataMap.get(fetch);
+  if (cached) return cached;
+  const promise = (async () => {
+    try {
+      const FetchResponse = (
+        'Response' in fetch ?
+          fetch.Response
+        : (await fetch('data:,')).constructor) as typeof Response;
+      const data = new FormData();
+      if (data.toString() === (await new FetchResponse(data).text())) {
+        return false;
+      }
+      return true;
+    } catch {
+      // avoid false negatives
+      return true;
+    }
+  })();
+  supportsFormDataMap.set(fetch, promise);
+  return promise;
+}
+
+export const createForm = async <T = Record<string, unknown>>(
+  body: T | undefined,
+  fetch: BaseAnthropic | Fetch,
+  stripFilenames: boolean = true,
+): Promise<FormData> => {
+  if (!(await supportsFormData(fetch))) {
+    throw new TypeError(
+      'The provided fetch function does not support file uploads with the current global FormData class.',
+    );
+  }
+  const form = new FormData();
+  await Promise.all(
+    Object.entries(body || {}).map(([key, value]) => addFormValue(form, key, value, stripFilenames)),
+  );
+  return form;
+};
+
+// We check for Blob not File because Bun.File doesn't inherit from File,
+// but they both inherit from Blob and have a `name` property at runtime.
+const isNamedBlob = (value: unknown): value is Blob => value instanceof Blob && 'name' in value;
+
+const isUploadable = (value: unknown) =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value instanceof Response || isAsyncIterable(value) || isNamedBlob(value));
+
+const hasUploadableValue = (value: unknown): boolean => {
+  if (isUploadable(value)) return true;
+  if (Array.isArray(value)) return value.some(hasUploadableValue);
+  if (value && typeof value === 'object') {
+    for (const k in value) {
+      if (hasUploadableValue((value as any)[k])) return true;
+    }
+  }
+  return false;
+};
+
+const addFormValue = async (
+  form: FormData,
+  key: string,
+  value: unknown,
+  stripFilenames: boolean,
+): Promise<void> => {
+  if (value === undefined) return;
+  if (value == null) {
+    throw new TypeError(
+      `Received null for "${key}"; to pass null in FormData, you must use the string 'null'`,
+    );
+  }
+
+  // TODO: make nested formats configurable
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    form.append(key, String(value));
+  } else if (value instanceof Response) {
+    let options = {} as FilePropertyBag;
+    const contentType = value.headers.get('Content-Type');
+    if (contentType) {
+      options = { type: contentType };
+    }
+
+    form.append(key, makeFile([await value.blob()], getName(value, stripFilenames), options));
+  } else if (isAsyncIterable(value)) {
+    form.append(
+      key,
+      makeFile([await new Response(ReadableStreamFrom(value)).blob()], getName(value, stripFilenames)),
+    );
+  } else if (isNamedBlob(value)) {
+    form.append(key, makeFile([value], getName(value, stripFilenames), { type: value.type }));
+  } else if (Array.isArray(value)) {
+    await Promise.all(value.map((entry) => addFormValue(form, key + '[]', entry, stripFilenames)));
+  } else if (typeof value === 'object') {
+    await Promise.all(
+      Object.entries(value).map(([name, prop]) =>
+        addFormValue(form, `${key}[${name}]`, prop, stripFilenames),
+      ),
+    );
+  } else {
+    throw new TypeError(
+      `Invalid value given to form, expected a string, number, boolean, object, Array, File or Blob but got ${value} instead`,
+    );
+  }
+};

package/src/internal/utils/abort.ts

@@ -0,0 +1,21 @@
+/**
+ * Chain an external {@link AbortSignal} into a local {@link AbortController}:
+ * the controller aborts whenever `external` aborts (synchronously if it is
+ * already aborted).
+ *
+ * Returns a cleanup function that detaches the listener. Callers MUST invoke it
+ * on their normal teardown path — `{ once: true }` only removes the listener if
+ * abort actually fires, so a long-lived `external` signal (e.g. a daemon-wide
+ * signal reused across many short-lived controllers) would otherwise leak one
+ * listener per controller.
+ */
+export function linkAbort(external: AbortSignal | null | undefined, controller: AbortController): () => void {
+  if (!external) return () => {};
+  if (external.aborted) {
+    controller.abort();
+    return () => {};
+  }
+  const onAbort = () => controller.abort();
+  external.addEventListener('abort', onAbort);
+  return () => external.removeEventListener('abort', onAbort);
+}

package/src/internal/utils/async-queue.ts

@@ -0,0 +1,66 @@
+export type AsyncQueueResult<T> = { done: false; value: T } | { done: true; value: undefined };
+
+/**
+ * Single-consumer async queue that bridges background producers to an
+ * `AsyncIterator`-style reader. Producers `push()` items; the consumer awaits
+ * `next()`. `close()` is idempotent and wakes any pending `next()` with
+ * `done: true`. `tryShift()` synchronously drains remaining items after
+ * iteration has been signalled to stop.
+ */
+export class AsyncQueue<T> {
+  #items: T[] = [];
+  #waiters: Array<(r: AsyncQueueResult<T>) => void> = [];
+  #closed = false;
+
+  /** Enqueue an item, or hand it directly to a waiting reader. Returns `false` once closed. */
+  push(item: T): boolean {
+    if (this.#closed) return false;
+    const w = this.#waiters.shift();
+    if (w) w({ done: false, value: item });
+    else this.#items.push(item);
+    return true;
+  }
+
+  /** Mark the queue done. Idempotent; wakes every pending reader with `done: true`. */
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    while (this.#waiters.length > 0) {
+      const w = this.#waiters.shift()!;
+      w({ done: true, value: undefined });
+    }
+  }
+
+  /**
+   * Resolve with the next item, or `done: true` once the queue is closed and
+   * drained. When `signal` is supplied, aborting it resolves a pending read
+   * with `done: true` (cancellation is pushed down here rather than handled by
+   * an outer `Promise.race`).
+   */
+  next(signal?: AbortSignal): Promise<AsyncQueueResult<T>> {
+    if (this.#items.length > 0) {
+      return Promise.resolve({ done: false, value: this.#items.shift()! });
+    }
+    if (this.#closed || signal?.aborted) {
+      return Promise.resolve({ done: true, value: undefined });
+    }
+    return new Promise<AsyncQueueResult<T>>((resolve) => {
+      const waiter = (r: AsyncQueueResult<T>) => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve(r);
+      };
+      const onAbort = () => {
+        const idx = this.#waiters.indexOf(waiter);
+        if (idx >= 0) this.#waiters.splice(idx, 1);
+        resolve({ done: true, value: undefined });
+      };
+      this.#waiters.push(waiter);
+      signal?.addEventListener('abort', onAbort, { once: true });
+    });
+  }
+
+  /** Synchronously remove and return the next buffered item, or `undefined` if empty. */
+  tryShift(): T | undefined {
+    return this.#items.shift();
+  }
+}

package/src/internal/utils/backoff.ts

@@ -0,0 +1,41 @@
+import { APIError } from '../../core/error';
+
+/** True when `e` is an {@link APIError} whose HTTP status equals `code`. */
+export function isStatus(e: unknown, code: number): boolean {
+  return e instanceof APIError && e.status === code;
+}
+
+/** True when `e` is an {@link APIError} with a 4xx status. */
+export function is4xx(e: unknown): boolean {
+  return e instanceof APIError && typeof e.status === 'number' && e.status >= 400 && e.status < 500;
+}
+
+/**
+ * True for a 4xx that the core client's retry policy would *not* retry, i.e. a
+ * permanent client error. 408 (request timeout), 409 (lock timeout) and 429
+ * (rate limit) are retryable for the base client (`Anthropic.shouldRetry`), so
+ * they are not treated as fatal here — keeping helper retry behaviour aligned
+ * with the rest of the SDK.
+ */
+export function isFatal4xx(e: unknown): boolean {
+  return is4xx(e) && !isStatus(e, 408) && !isStatus(e, 409) && !isStatus(e, 429);
+}
+
+/** Exponential backoff: `baseMs * 2 ** attempt`, clamped to `capMs`. */
+export function backoff(attempt: number, baseMs: number, capMs: number): number {
+  return Math.min(baseMs * 2 ** attempt, capMs);
+}
+
+/** Uniform random delay in the half-open interval `[lowMs, highMs)`. */
+export function jitter(lowMs: number, highMs: number): number {
+  return lowMs + Math.random() * (highMs - lowMs);
+}
+
+/**
+ * Trim up to 25% off `ms` at random so a fleet of clients backing off after a
+ * shared outage does not retry in lockstep — mirrors the jitter the core client
+ * applies to its own retry timeout.
+ */
+export function applyJitter(ms: number): number {
+  return ms * (1 - Math.random() * 0.25);
+}

package/src/internal/utils/base64.ts

@@ -0,0 +1,40 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { AnthropicError } from '../../core/error';
+import { encodeUTF8 } from './bytes';
+
+export const toBase64 = (data: string | Uint8Array | null | undefined): string => {
+  if (!data) return '';
+
+  if (typeof (globalThis as any).Buffer !== 'undefined') {
+    return (globalThis as any).Buffer.from(data).toString('base64');
+  }
+
+  if (typeof data === 'string') {
+    data = encodeUTF8(data);
+  }
+
+  if (typeof btoa !== 'undefined') {
+    return btoa(String.fromCharCode.apply(null, data as any));
+  }
+
+  throw new AnthropicError('Cannot generate base64 string; Expected `Buffer` or `btoa` to be defined');
+};
+
+export const fromBase64 = (str: string): Uint8Array => {
+  if (typeof (globalThis as any).Buffer !== 'undefined') {
+    const buf = (globalThis as any).Buffer.from(str, 'base64');
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  }
+
+  if (typeof atob !== 'undefined') {
+    const bstr = atob(str);
+    const buf = new Uint8Array(bstr.length);
+    for (let i = 0; i < bstr.length; i++) {
+      buf[i] = bstr.charCodeAt(i);
+    }
+    return buf;
+  }
+
+  throw new AnthropicError('Cannot decode base64 string; Expected `Buffer` or `atob` to be defined');
+};

package/src/internal/utils/bytes.ts

@@ -0,0 +1,32 @@
+export function concatBytes(buffers: Uint8Array[]): Uint8Array {
+  let length = 0;
+  for (const buffer of buffers) {
+    length += buffer.length;
+  }
+  const output = new Uint8Array(length);
+  let index = 0;
+  for (const buffer of buffers) {
+    output.set(buffer, index);
+    index += buffer.length;
+  }
+
+  return output;
+}
+
+let encodeUTF8_: (str: string) => Uint8Array;
+export function encodeUTF8(str: string) {
+  let encoder;
+  return (
+    encodeUTF8_ ??
+    ((encoder = new (globalThis as any).TextEncoder()), (encodeUTF8_ = encoder.encode.bind(encoder)))
+  )(str);
+}
+
+let decodeUTF8_: (bytes: Uint8Array) => string;
+export function decodeUTF8(bytes: Uint8Array) {
+  let decoder;
+  return (
+    decodeUTF8_ ??
+    ((decoder = new (globalThis as any).TextDecoder()), (decodeUTF8_ = decoder.decode.bind(decoder)))
+  )(bytes);
+}

package/src/internal/utils/env.ts

@@ -0,0 +1,18 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+/**
+ * Read an environment variable.
+ *
+ * Trims beginning and trailing whitespace.
+ *
+ * Will return undefined if the environment variable doesn't exist or cannot be accessed.
+ */
+export const readEnv = (env: string): string | undefined => {
+  if (typeof (globalThis as any).process !== 'undefined') {
+    return (globalThis as any).process.env?.[env]?.trim() || undefined;
+  }
+  if (typeof (globalThis as any).Deno !== 'undefined') {
+    return (globalThis as any).Deno.env?.get?.(env)?.trim() || undefined;
+  }
+  return undefined;
+};