@aptos-labs/aptos-client/src/types.ts

Client package for accessing the Aptos network API.

/**
 * Response returned by all `aptosClient` entry points.
 *
 * @typeParam Res - The expected shape of the parsed response body.
 *   For {@link jsonRequest} this is the deserialized JSON object;
 *   for {@link bcsRequest} it is `ArrayBuffer`.
 */
export type AptosClientResponse<Res> = {
  /** HTTP status code (e.g. `200`, `404`). */
  status: number;
  /** HTTP reason phrase (e.g. `"OK"`, `"Not Found"`). */
  statusText: string;
  /** Parsed response body. */
  data: Res;
  /** The request options that were sent (shape varies per entry point). */
  // biome-ignore lint/suspicious/noExplicitAny: cross-platform response type; varies per entry point
  config?: any;
  /** Metadata about the outgoing request (Node entry point only). */
  // biome-ignore lint/suspicious/noExplicitAny: cross-platform response type; varies per entry point
  request?: any;
  /** The raw `Response` object (Node entry point only). */
  // biome-ignore lint/suspicious/noExplicitAny: cross-platform response type; varies per entry point
  response?: any;
  /** Response headers as a plain key-value record. */
  headers?: Record<string, string | string[]>;
};

/**
 * Minimal cookie jar interface for per-request cookie isolation.
 *
 * @remarks
 * Implement this interface or use the {@link CookieJar} class exported by
 * the Node and fetch entry points. The browser entry point ignores this
 * option (cookies are managed by the browser engine).
 */
export interface CookieJarLike {
  getCookies(url: URL): { name: string; value: string }[];
  setCookie(url: URL, cookieStr: string): void;
}

/**
 * Options accepted by every `aptosClient` call.
 */
export type AptosClientRequest = {
  /** Fully-qualified URL of the Aptos API endpoint. */
  url: string;
  /** HTTP method — only `GET` and `POST` are supported. */
  method: "GET" | "POST";
  /**
   * Request body. Objects are JSON-serialized; `Uint8Array` is sent as binary.
   *
   * @remarks
   * Typed as `unknown` for compatibility with the SDK's generic
   * `ClientRequest<Req>`. At runtime, values are handled as either
   * `Uint8Array` (sent verbatim) or anything else (`JSON.stringify`).
   */
  body?: unknown;
  /** Query-string parameters appended to the URL. `bigint` values are stringified automatically. */
  params?: Record<string, string | number | bigint | boolean | undefined>;
  /** Additional HTTP headers merged into the request. */
  headers?: Record<string, string | undefined>;
  /**
   * Runtime-specific overrides.
   *
   * @remarks
   * In the **browser** entry point, `overrides.WITH_CREDENTIALS` controls the
   * `credentials` option on the `fetch` call (`false` → `"omit"`,
   * default/`true` → `"include"`).
   */
  overrides?: { WITH_CREDENTIALS?: boolean };
  /**
   * Enable or disable HTTP/2 negotiation.
   *
   * @defaultValue `true`
   *
   * @remarks
   * Only effective in the **Node** entry point, where it maps to got's
   * `http2` option (which uses `http2-wrapper` under the hood to negotiate
   * H2 via ALPN). In the **fetch**, **browser**, and **React Native** entry
   * points the underlying runtime negotiates HTTP/2 automatically — this
   * option is ignored there.
   */
  http2?: boolean;
  /**
   * Override the module-level cookie jar for this request.
   *
   * @remarks
   * By default, the Node and fetch entry points use a shared module-level
   * `CookieJar` singleton. In multi-tenant or server-side environments,
   * pass a per-request jar to prevent cross-request cookie leakage.
   * The browser entry point ignores this option.
   */
  cookieJar?: CookieJarLike;
};