snapreq 0.0.1 → 0.0.4

package/types/errors.d.ts

@@ -0,0 +1,81 @@
+/** Base class for every error thrown by snapreq. */
+export class SnapReqError extends Error {
+    /** @param {string} message - Human readable description. */
+    constructor(message: string);
+}
+/**
+ * Thrown when a request completes with a non-2xx status and the caller asked
+ * snapreq to treat error statuses as failures (`throwOnError`, the default for
+ * the high-level helpers). Carries enough metadata to build a friendly message
+ * without re-reading the response.
+ */
+export class SnapReqHttpError extends SnapReqError {
+    /**
+     * @param {object} options - Error metadata.
+     * @param {string} options.message - Human readable description.
+     * @param {string} options.method - HTTP method used for the request.
+     * @param {string} options.url - Fully resolved request URL.
+     * @param {number} options.status - HTTP status code returned by the server.
+     * @param {string} [options.statusText] - HTTP status text returned by the server.
+     * @param {string} [options.responseText] - Decoded response body, when available.
+     * @param {import("./response.js").default} [options.response] - The response that failed.
+     */
+    constructor({ message, method, url, status, statusText, responseText, response }: {
+        message: string;
+        method: string;
+        url: string;
+        status: number;
+        statusText?: string;
+        responseText?: string;
+        response?: import("./response.js").default;
+    });
+    method: string;
+    url: string;
+    status: number;
+    statusText: string;
+    responseText: string;
+    response: import("./response.js").default;
+}
+/**
+ * Thrown when a request asks for a capability the active transport cannot
+ * provide on the current platform (for example a Unix socket or request-body
+ * compression in a browser). The API stays identical across platforms; this
+ * error is how snapreq tells you a specific feature had to be left out.
+ */
+export class SnapReqUnsupportedFeatureError extends SnapReqError {
+    /**
+     * @param {object} options - Error metadata.
+     * @param {string} options.feature - The capability that is not supported.
+     * @param {string} options.transport - Name of the active transport.
+     * @param {string} [options.detail] - Optional extra context.
+     */
+    constructor({ feature, transport, detail }: {
+        feature: string;
+        transport: string;
+        detail?: string;
+    });
+    feature: string;
+    transport: string;
+}
+/** Thrown when a request is aborted via an `AbortSignal`. */
+export class SnapReqAbortError extends SnapReqError {
+    /** @param {string} [message] - Human readable description. */
+    constructor(message?: string);
+}
+/** Thrown when a request exceeds its configured timeout. */
+export class SnapReqTimeoutError extends SnapReqError {
+    /**
+     * @param {object} options - Error metadata.
+     * @param {string} options.method - HTTP method used for the request.
+     * @param {string} options.url - Fully resolved request URL.
+     * @param {number} options.timeoutMs - Timeout in milliseconds.
+     */
+    constructor({ method, url, timeoutMs }: {
+        method: string;
+        url: string;
+        timeoutMs: number;
+    });
+    method: string;
+    url: string;
+    timeoutMs: number;
+}

package/types/headers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A tiny case-insensitive header bag. Works the same on every platform and
+ * avoids depending on the DOM `Headers` global (absent in some runtimes) or on
+ * Node's header handling. Header values are always stored as strings.
+ */
+export default class SnapReqHeaders {
+    /**
+     * @param {Record<string, string | number | string[]> | SnapReqHeaders | Iterable<[string, string]>} [init] - Initial headers.
+     */
+    constructor(init?: Record<string, string | number | string[]> | SnapReqHeaders | Iterable<[string, string]>);
+    /** @type {Map<string, {name: string, value: string}>} - Keyed by lower-cased name. */
+    _map: Map<string, {
+        name: string;
+        value: string;
+    }>;
+    /**
+     * @param {string} name - Header name (case-insensitive).
+     * @param {string | number} value - Header value.
+     * @returns {void}
+     */
+    set(name: string, value: string | number): void;
+    /**
+     * @param {string} name - Header name (case-insensitive).
+     * @returns {string | null} - The header value or null when absent.
+     */
+    get(name: string): string | null;
+    /**
+     * @param {string} name - Header name (case-insensitive).
+     * @returns {boolean} - Whether the header is present.
+     */
+    has(name: string): boolean;
+    /**
+     * @param {string} name - Header name (case-insensitive).
+     * @returns {void}
+     */
+    delete(name: string): void;
+    /**
+     * @yields {[string, string]} - Name/value pair preserving original casing.
+     * @returns {IterableIterator<[string, string]>} - Name/value pairs preserving original casing.
+     */
+    entries(): IterableIterator<[string, string]>;
+    /** @returns {[string, string][]} - Name/value pairs preserving original casing. */
+    toArray(): [string, string][];
+    /**
+     * Plain object form keyed by the original header casing. Suitable for
+     * passing straight to `http.request` or `fetch`.
+     * @returns {Record<string, string>} - Header object.
+     */
+    toObject(): Record<string, string>;
+}

package/types/request.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Joins a base URL and a path and appends query parameters. `path` may be a
+ * fully-qualified URL, in which case the base is ignored.
+ * @param {string | undefined} baseUrl - Origin (and optional base path).
+ * @param {string} path - Path or absolute URL.
+ * @param {Record<string, string | number | boolean | null | undefined> | undefined} query - Query parameters.
+ * @returns {string} - Resolved absolute URL.
+ */
+export function buildUrl(baseUrl: string | undefined, path: string, query: Record<string, string | number | boolean | null | undefined> | undefined): string;
+/**
+ * Determines whether a value should be sent as a streamed request body.
+ * @param {unknown} body - Candidate body value.
+ * @returns {boolean} - Whether the body is a stream.
+ */
+export function isStreamBody(body: unknown): boolean;
+/**
+ * Normalizes a user-supplied body into one of a small set of shapes and applies
+ * a default `Content-Type` header when the caller did not set one.
+ * @param {unknown} body - Raw body value.
+ * @param {SnapReqHeaders} headers - Headers to receive a default `Content-Type`.
+ * @returns {NormalizedBody} - Normalized body descriptor.
+ */
+export function normalizeBody(body: unknown, headers: SnapReqHeaders): NormalizedBody;
+export type CompressionEncoding = "identity" | "gzip" | "deflate" | "br" | "zstd";
+export type NormalizedBody = {
+    /**
+     * - Shape of the body payload.
+     */
+    kind: "none" | "text" | "bytes" | "stream";
+    /**
+     * - The payload itself.
+     */
+    value: string | Uint8Array | AsyncIterable<Uint8Array> | null;
+};
+import SnapReqHeaders from "./headers.js";

package/types/response.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A platform-agnostic response. Transports build it with either a fully-read
+ * body (`bytes`) or a `stream` (an async iterable of `Uint8Array`) that the
+ * read helpers buffer on first use. The body can be read exactly once as a
+ * stream; the buffering helpers may be called repeatedly because they cache.
+ */
+export default class SnapReqResponse {
+    /**
+     * @param {object} options - Response data.
+     * @param {string} options.url - Fully resolved request URL.
+     * @param {string} options.method - HTTP method used for the request.
+     * @param {number} options.status - HTTP status code.
+     * @param {string} [options.statusText] - HTTP status text.
+     * @param {SnapReqHeaders} [options.headers] - Response headers.
+     * @param {Uint8Array} [options.bytes] - Fully-read body, when the transport already buffered it.
+     * @param {AsyncIterable<Uint8Array>} [options.stream] - Streamed body, when the transport supports streaming.
+     * @param {import("node:stream").Readable} [options.nodeStream] - Raw Node stream, when available, for advanced consumers.
+     * @param {() => void} [options.onBodyDone] - Callback fired when body reading finishes or fails.
+     * @param {(error: unknown) => unknown} [options.mapBodyError] - Maps body read errors before rethrowing.
+     */
+    constructor({ url, method, status, statusText, headers, bytes, stream, nodeStream, onBodyDone, mapBodyError }: {
+        url: string;
+        method: string;
+        status: number;
+        statusText?: string;
+        headers?: SnapReqHeaders;
+        bytes?: Uint8Array;
+        stream?: AsyncIterable<Uint8Array>;
+        nodeStream?: import("node:stream").Readable;
+        onBodyDone?: () => void;
+        mapBodyError?: (error: unknown) => unknown;
+    });
+    url: string;
+    method: string;
+    status: number;
+    statusText: string;
+    headers: SnapReqHeaders;
+    /** @type {Uint8Array | null} */
+    _bytes: Uint8Array | null;
+    /** @type {AsyncIterable<Uint8Array> | null} */
+    _stream: AsyncIterable<Uint8Array> | null;
+    /** @type {import("node:stream").Readable | undefined} */
+    nodeStream: import("node:stream").Readable | undefined;
+    _streamConsumed: boolean;
+    _bodyDone: boolean;
+    _onBodyDone: () => void;
+    _mapBodyError: (error: unknown) => unknown;
+    /** @returns {boolean} - Whether the status is in the 2xx range. */
+    get ok(): boolean;
+    /**
+     * Returns the response body as an async iterable of byte chunks. Can only be
+     * called once and only when the transport provided a stream.
+     * @returns {AsyncIterable<Uint8Array>} - The streamed body.
+     */
+    stream(): AsyncIterable<Uint8Array>;
+    /** @returns {boolean} - Whether the body is available as a stream that has not been read yet. */
+    get streamable(): boolean;
+    /**
+     * Reads the whole body into a `Uint8Array`, buffering the stream if needed.
+     * @returns {Promise<Uint8Array>} - The full response body.
+     */
+    bytes(): Promise<Uint8Array>;
+    /**
+     * Reads the whole body as a Node `Buffer`. Node-only convenience; throws when
+     * the `Buffer` global is unavailable.
+     * @returns {Promise<Buffer>} - The full response body as a Buffer.
+     */
+    buffer(): Promise<Buffer>;
+    /**
+     * Reads the whole body and decodes it as a UTF-8 string.
+     * @returns {Promise<string>} - The decoded response body.
+     */
+    text(): Promise<string>;
+    /**
+     * Reads the whole body and parses it as JSON. Returns `null` for an empty
+     * body.
+     * @returns {Promise<any>} - The parsed JSON body.
+     */
+    json(): Promise<any>;
+    /**
+     * @param {AsyncIterable<Uint8Array>} source - Source response stream.
+     * @returns {AsyncIterable<Uint8Array>} - Stream with cleanup/error mapping.
+     */
+    _wrappedStream(source: AsyncIterable<Uint8Array>): AsyncIterable<Uint8Array>;
+    /**
+     * @param {unknown} error - Body read error.
+     * @returns {unknown} - Error to rethrow.
+     */
+    _mappedBodyError(error: unknown): unknown;
+    /** @returns {void} */
+    _finishBody(): void;
+}
+import SnapReqHeaders from "./headers.js";

package/types/retry.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @typedef {object} RetryOptions
+ * @property {number} [tries] - Maximum number of attempts. Defaults to 3.
+ * @property {number} [waitMs] - Delay between attempts in milliseconds. Defaults to 500.
+ * @property {number[]} [retryableStatuses] - HTTP status codes that should be retried. Defaults to 502/503/504.
+ * @property {(error: unknown, attempt: number) => boolean} [shouldRetry] - Override the retryable-error classifier.
+ */
+/**
+ * @typedef {object} NormalizedRetryOptions
+ * @property {number} tries - Maximum number of attempts.
+ * @property {number} waitMs - Delay between attempts in milliseconds.
+ * @property {number[]} retryableStatuses - HTTP status codes that should be retried.
+ * @property {(error: unknown, attempt: number) => boolean} shouldRetry - Retryable-error classifier.
+ */
+/**
+ * The default network-error classifier. Exposed so callers can compose extra
+ * rules on top of it (for example matching server-specific 500 messages).
+ * @param {unknown} error - Error thrown by a transport.
+ * @returns {boolean} - Whether the error is a transient network failure.
+ */
+export function defaultRetryableError(error: unknown): boolean;
+/**
+ * Normalizes the `retry` option into a complete set of retry settings, or
+ * `null` when retries are disabled.
+ * @param {boolean | RetryOptions | undefined} retry - Retry configuration.
+ * @returns {NormalizedRetryOptions | null} - Normalized retry settings.
+ */
+export function normalizeRetryOptions(retry: boolean | RetryOptions | undefined): NormalizedRetryOptions | null;
+/**
+ * Runs a request attempt, retrying transient network errors and retryable HTTP
+ * statuses. Retries are only used for buffered requests — the caller must not
+ * apply this to streamed responses.
+ * @param {() => Promise<import("./response.js").default>} attempt - Performs one request attempt.
+ * @param {NormalizedRetryOptions} retry - Normalized retry settings.
+ * @returns {Promise<import("./response.js").default>} - The successful (or final) response.
+ */
+export function runWithRetry(attempt: () => Promise<import("./response.js").default>, retry: NormalizedRetryOptions): Promise<import("./response.js").default>;
+export type RetryOptions = {
+    /**
+     * - Maximum number of attempts. Defaults to 3.
+     */
+    tries?: number;
+    /**
+     * - Delay between attempts in milliseconds. Defaults to 500.
+     */
+    waitMs?: number;
+    /**
+     * - HTTP status codes that should be retried. Defaults to 502/503/504.
+     */
+    retryableStatuses?: number[];
+    /**
+     * - Override the retryable-error classifier.
+     */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+};
+export type NormalizedRetryOptions = {
+    /**
+     * - Maximum number of attempts.
+     */
+    tries: number;
+    /**
+     * - Delay between attempts in milliseconds.
+     */
+    waitMs: number;
+    /**
+     * - HTTP status codes that should be retried.
+     */
+    retryableStatuses: number[];
+    /**
+     * - Retryable-error classifier.
+     */
+    shouldRetry: (error: unknown, attempt: number) => boolean;
+};

package/types/snap-req.d.ts

@@ -0,0 +1,303 @@
+/**
+ * @typedef {import("./request.js").CompressionEncoding} CompressionEncoding
+ */
+/**
+ * @typedef {object} NormalizedRequest
+ * @property {string} method - Upper-cased HTTP method.
+ * @property {string} url - Fully resolved request URL.
+ * @property {SnapReqHeaders} headers - Request headers.
+ * @property {import("./request.js").NormalizedBody} body - Normalized request body.
+ * @property {CompressionEncoding} bodyCompression - Request body compression.
+ * @property {AbortSignal} [signal] - Abort signal.
+ * @property {number} [timeoutMs] - Request timeout in milliseconds.
+ * @property {string} [credentials] - Fetch credentials mode ("omit" | "same-origin" | "include").
+ */
+/**
+ * @typedef {object} RequestOptions
+ * @property {string} [method] - HTTP method. Defaults to GET.
+ * @property {string} [path] - Request path (joined with the client `baseUrl`) or absolute URL.
+ * @property {string} [url] - Alias for `path`.
+ * @property {Record<string, string | number | boolean | null | undefined>} [query] - Query parameters.
+ * @property {Record<string, string | number> | SnapReqHeaders} [headers] - Per-request headers.
+ * @property {any} [body] - Request body: string, object (JSON), Uint8Array/ArrayBuffer, or a stream/async-iterable.
+ * @property {CompressionEncoding} [bodyCompression] - Compress the request body (Node transport only).
+ * @property {AbortSignal} [signal] - Abort signal for the request.
+ * @property {number} [timeoutMs] - Request timeout in milliseconds. Set to `0` to disable a client default.
+ * @property {string} [credentials] - Fetch credentials mode.
+ * @property {boolean | import("./retry.js").RetryOptions} [retry] - Retry transient failures.
+ * @property {boolean} [throwOnError] - Throw `SnapReqHttpError` on non-2xx responses.
+ */
+/**
+ * @typedef {object} RequestTimeout
+ * @property {AbortSignal | undefined} signal - Signal to use for the request.
+ * @property {() => void} clear - Clears timeout resources.
+ * @property {(response: import("./response.js").default, request: NormalizedRequest) => import("./response.js").default} response - Attaches timeout handling to a response.
+ * @property {(error: unknown, request: NormalizedRequest) => unknown} error - Maps a thrown error.
+ */
+/**
+ * A cross-platform HTTP client with one API across Node, web, Expo and React
+ * Native. The right transport is chosen at runtime; features a platform cannot
+ * provide raise `SnapReqUnsupportedFeatureError` rather than silently changing
+ * behaviour.
+ */
+export default class SnapReq {
+    /**
+     * @param {object} [config] - Client configuration.
+     * @param {string} [config.baseUrl] - Origin (and optional base path) prepended to relative paths.
+     * @param {string} [config.socketPath] - Unix domain socket path (Node transport only).
+     * @param {{ca?: string | Buffer, cert?: string | Buffer, key?: string | Buffer, rejectUnauthorized?: boolean}} [config.tls] - TLS material (Node transport only).
+     * @param {boolean} [config.keepAlive] - Reuse connections across requests (Node transport only). Defaults to true.
+     * @param {Record<string, string | number> | (() => Record<string, string | number>)} [config.headers] - Default headers (object or factory).
+     * @param {boolean | import("./retry.js").RetryOptions} [config.retry] - Default retry policy.
+     * @param {boolean} [config.throwOnError] - Throw `SnapReqHttpError` on non-2xx responses by default. Defaults to false.
+     * @param {number} [config.timeoutMs] - Default request timeout in milliseconds. Set per-request `timeoutMs: 0` to disable.
+     * @param {string} [config.credentials] - Default fetch credentials mode.
+     * @param {import("./transports/select.js").TransportName | import("./transports/select.js").Transport} [config.transport] - Transport preference or instance. Defaults to "auto".
+     */
+    constructor({ baseUrl, socketPath, tls, keepAlive, headers, retry, throwOnError, timeoutMs, credentials, transport }?: {
+        baseUrl?: string;
+        socketPath?: string;
+        tls?: {
+            ca?: string | Buffer;
+            cert?: string | Buffer;
+            key?: string | Buffer;
+            rejectUnauthorized?: boolean;
+        };
+        keepAlive?: boolean;
+        headers?: Record<string, string | number> | (() => Record<string, string | number>);
+        retry?: boolean | import("./retry.js").RetryOptions;
+        throwOnError?: boolean;
+        timeoutMs?: number;
+        credentials?: string;
+        transport?: import("./transports/select.js").TransportName | import("./transports/select.js").Transport;
+    });
+    baseUrl: string;
+    defaultHeaders: Record<string, string | number> | (() => Record<string, string | number>);
+    defaultRetry: boolean | import("./retry.js").RetryOptions;
+    throwOnError: boolean;
+    timeoutMs: number;
+    credentials: string;
+    _transportPreference: import("./transports/select.js").TransportName | import("./transports/select.js").Transport;
+    _nodeConfig: {
+        socketPath: string;
+        tls: {
+            ca?: string | Buffer;
+            cert?: string | Buffer;
+            key?: string | Buffer;
+            rejectUnauthorized?: boolean;
+        };
+        keepAlive: boolean;
+    };
+    /** @type {Promise<import("./transports/select.js").Transport> | null} */
+    _transportPromise: Promise<import("./transports/select.js").Transport> | null;
+    /** @type {import("./transports/select.js").Transport | null} */
+    _transport: import("./transports/select.js").Transport | null;
+    /** @returns {Promise<import("./transports/select.js").Transport>} - The resolved transport. */
+    _resolveTransport(): Promise<import("./transports/select.js").Transport>;
+    /** @returns {Promise<import("./capabilities.js").TransportCapabilities>} - The active transport's capabilities. */
+    capabilities(): Promise<import("./capabilities.js").TransportCapabilities>;
+    /** @returns {Promise<string>} - The active transport's name. */
+    transportName(): Promise<string>;
+    /**
+     * @param {RequestOptions} options - Request options.
+     * @returns {NormalizedRequest} - The normalized request.
+     */
+    _normalize(options: RequestOptions): NormalizedRequest;
+    /**
+     * @param {RequestOptions} options - Request options.
+     * @returns {RequestTimeout} - Timeout handling for one request attempt.
+     */
+    _requestTimeout(options: RequestOptions): RequestTimeout;
+    /**
+     * @param {AbortSignal | undefined} callerSignal - Caller-supplied signal.
+     * @param {AbortSignal} timeoutSignal - Timeout signal.
+     * @returns {{signal: AbortSignal, clear: () => void}} - Signal that aborts when either source aborts.
+     */
+    _composeSignal(callerSignal: AbortSignal | undefined, timeoutSignal: AbortSignal): {
+        signal: AbortSignal;
+        clear: () => void;
+    };
+    /**
+     * @param {(() => void) | undefined} existing - Existing body-done callback.
+     * @param {() => void} next - Callback to add.
+     * @returns {() => void} - Combined callback.
+     */
+    _chainBodyDone(existing: (() => void) | undefined, next: () => void): () => void;
+    /**
+     * @param {((error: unknown) => unknown) | undefined} existing - Existing error mapper.
+     * @param {(error: unknown) => unknown} next - Mapper to add.
+     * @returns {(error: unknown) => unknown} - Combined mapper.
+     */
+    _chainBodyError(existing: ((error: unknown) => unknown) | undefined, next: (error: unknown) => unknown): (error: unknown) => unknown;
+    /**
+     * Performs a request and buffers nothing eagerly — read the body via the
+     * returned response (`json()`, `text()`, `bytes()`). Retries transient
+     * failures when a retry policy is configured (never for streamed bodies).
+     * @param {RequestOptions} options - Request options.
+     * @returns {Promise<import("./response.js").default>} - The response.
+     */
+    request(options: RequestOptions): Promise<import("./response.js").default>;
+    /**
+     * Performs a request and returns the response with its body available as a
+     * stream (`response.stream()`). Requires a transport that supports response
+     * streaming; never retries.
+     * @param {RequestOptions} options - Request options.
+     * @returns {Promise<import("./response.js").default>} - The streaming response.
+     */
+    requestStream(options: RequestOptions): Promise<import("./response.js").default>;
+    /**
+     * @param {RequestOptions} options - Request options.
+     * @param {(request: NormalizedRequest) => Promise<import("./response.js").default>} performRequest - Transport request runner.
+     * @returns {Promise<import("./response.js").default>} - Response with timeout handling attached.
+     */
+    _requestWithTimeout(options: RequestOptions, performRequest: (request: NormalizedRequest) => Promise<import("./response.js").default>): Promise<import("./response.js").default>;
+    /**
+     * @param {string} path - Request path or absolute URL.
+     * @param {RequestOptions} [options] - Request options.
+     * @returns {Promise<import("./response.js").default>} - The response.
+     */
+    get(path: string, options?: RequestOptions): Promise<import("./response.js").default>;
+    /**
+     * @param {string} path - Request path or absolute URL.
+     * @param {any} [body] - Request body.
+     * @param {RequestOptions} [options] - Request options.
+     * @returns {Promise<import("./response.js").default>} - The response.
+     */
+    post(path: string, body?: any, options?: RequestOptions): Promise<import("./response.js").default>;
+    /**
+     * @param {string} path - Request path or absolute URL.
+     * @param {any} [body] - Request body.
+     * @param {RequestOptions} [options] - Request options.
+     * @returns {Promise<import("./response.js").default>} - The response.
+     */
+    put(path: string, body?: any, options?: RequestOptions): Promise<import("./response.js").default>;
+    /**
+     * @param {string} path - Request path or absolute URL.
+     * @param {any} [body] - Request body.
+     * @param {RequestOptions} [options] - Request options.
+     * @returns {Promise<import("./response.js").default>} - The response.
+     */
+    patch(path: string, body?: any, options?: RequestOptions): Promise<import("./response.js").default>;
+    /**
+     * @param {string} path - Request path or absolute URL.
+     * @param {RequestOptions} [options] - Request options.
+     * @returns {Promise<import("./response.js").default>} - The response.
+     */
+    delete(path: string, options?: RequestOptions): Promise<import("./response.js").default>;
+    /**
+     * @param {import("./response.js").default} response - The failed response.
+     * @param {NormalizedRequest} request - The request that produced it.
+     * @returns {Promise<SnapReqHttpError>} - An error describing the failure.
+     */
+    _httpError(response: import("./response.js").default, request: NormalizedRequest): Promise<SnapReqHttpError>;
+    /**
+     * Releases transport resources (for example Node keep-alive sockets).
+     * @returns {void}
+     */
+    close(): void;
+}
+export type CompressionEncoding = import("./request.js").CompressionEncoding;
+export type NormalizedRequest = {
+    /**
+     * - Upper-cased HTTP method.
+     */
+    method: string;
+    /**
+     * - Fully resolved request URL.
+     */
+    url: string;
+    /**
+     * - Request headers.
+     */
+    headers: SnapReqHeaders;
+    /**
+     * - Normalized request body.
+     */
+    body: import("./request.js").NormalizedBody;
+    /**
+     * - Request body compression.
+     */
+    bodyCompression: CompressionEncoding;
+    /**
+     * - Abort signal.
+     */
+    signal?: AbortSignal;
+    /**
+     * - Request timeout in milliseconds.
+     */
+    timeoutMs?: number;
+    /**
+     * - Fetch credentials mode ("omit" | "same-origin" | "include").
+     */
+    credentials?: string;
+};
+export type RequestOptions = {
+    /**
+     * - HTTP method. Defaults to GET.
+     */
+    method?: string;
+    /**
+     * - Request path (joined with the client `baseUrl`) or absolute URL.
+     */
+    path?: string;
+    /**
+     * - Alias for `path`.
+     */
+    url?: string;
+    /**
+     * - Query parameters.
+     */
+    query?: Record<string, string | number | boolean | null | undefined>;
+    /**
+     * - Per-request headers.
+     */
+    headers?: Record<string, string | number> | SnapReqHeaders;
+    /**
+     * - Request body: string, object (JSON), Uint8Array/ArrayBuffer, or a stream/async-iterable.
+     */
+    body?: any;
+    /**
+     * - Compress the request body (Node transport only).
+     */
+    bodyCompression?: CompressionEncoding;
+    /**
+     * - Abort signal for the request.
+     */
+    signal?: AbortSignal;
+    /**
+     * - Request timeout in milliseconds. Set to `0` to disable a client default.
+     */
+    timeoutMs?: number;
+    /**
+     * - Fetch credentials mode.
+     */
+    credentials?: string;
+    /**
+     * - Retry transient failures.
+     */
+    retry?: boolean | import("./retry.js").RetryOptions;
+    /**
+     * - Throw `SnapReqHttpError` on non-2xx responses.
+     */
+    throwOnError?: boolean;
+};
+export type RequestTimeout = {
+    /**
+     * - Signal to use for the request.
+     */
+    signal: AbortSignal | undefined;
+    /**
+     * - Clears timeout resources.
+     */
+    clear: () => void;
+    /**
+     * - Attaches timeout handling to a response.
+     */
+    response: (response: import("./response.js").default, request: NormalizedRequest) => import("./response.js").default;
+    /**
+     * - Maps a thrown error.
+     */
+    error: (error: unknown, request: NormalizedRequest) => unknown;
+};
+import { SnapReqHttpError } from "./errors.js";
+import SnapReqHeaders from "./headers.js";

package/types/transports/fetch-transport.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Transport backed by the `fetch` global. Works on web, Expo / React Native and
+ * Node 18+. It cannot open Unix sockets, present client certificates or
+ * compress request bodies — those raise `SnapReqUnsupportedFeatureError`.
+ * Response streaming uses `response.body` where available and otherwise buffers
+ * the body once, keeping the same stream interface everywhere.
+ */
+export default class FetchTransport {
+    /** @returns {string} - Transport name. */
+    static get transportName(): string;
+    /** @returns {boolean} - Whether this transport can run in the current environment. */
+    static isAvailable(): boolean;
+    /** @returns {import("../capabilities.js").TransportCapabilities} - Supported capabilities. */
+    get capabilities(): import("../capabilities.js").TransportCapabilities;
+    /**
+     * @param {import("../snap-req.js").NormalizedRequest} request - Normalized request.
+     * @returns {Promise<SnapReqResponse>} - The response.
+     */
+    performRequest(request: import("../snap-req.js").NormalizedRequest): Promise<SnapReqResponse>;
+    /**
+     * @param {Response} response - The fetch response.
+     * @returns {SnapReqHeaders} - The response headers.
+     */
+    _responseHeaders(response: Response): SnapReqHeaders;
+    /**
+     * Builds an async iterable of byte chunks over a fetch response. Uses the
+     * `ReadableStream` body for true streaming when present and otherwise buffers
+     * the whole body once so the stream interface stays identical everywhere.
+     * @param {Response} response - The fetch response.
+     * @returns {AsyncIterable<Uint8Array>} - The response body stream.
+     */
+    _responseStream(response: Response): AsyncIterable<Uint8Array>;
+}
+import SnapReqResponse from "../response.js";
+import SnapReqHeaders from "../headers.js";