snapreq 0.0.1 → 0.0.3

package/types/snap-req.d.ts

@@ -0,0 +1,233 @@
+/**
+ * @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 {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 {string} [credentials] - Fetch credentials mode.
+ * @property {boolean | import("./retry.js").RetryOptions} [retry] - Retry transient failures.
+ * @property {boolean} [throwOnError] - Throw `SnapReqHttpError` on non-2xx responses.
+ */
+/**
+ * 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 {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, 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;
+        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;
+    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;
+    /**
+     * 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 {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;
+    /**
+     * - 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;
+    /**
+     * - Fetch credentials mode.
+     */
+    credentials?: string;
+    /**
+     * - Retry transient failures.
+     */
+    retry?: boolean | import("./retry.js").RetryOptions;
+    /**
+     * - Throw `SnapReqHttpError` on non-2xx responses.
+     */
+    throwOnError?: boolean;
+};
+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";

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

@@ -0,0 +1,112 @@
+/**
+ * Full-featured transport backed by Node's `http`/`https` modules. Supports
+ * Unix sockets, client TLS, keep-alive, request-body compression, response
+ * decompression and streaming. The `node:*` modules are loaded with a dynamic
+ * `import()` so this file never has to be bundled by web/Expo bundlers — the
+ * transport selector only imports it when running on Node.
+ */
+export default class NodeTransport {
+    /** @returns {string} - Transport name. */
+    static get transportName(): string;
+    /** @returns {boolean} - Whether this transport can run in the current environment. */
+    static isAvailable(): boolean;
+    /**
+     * @param {object} [config] - Transport configuration.
+     * @param {string} [config.socketPath] - Unix domain socket path.
+     * @param {{ca?: string | Buffer, cert?: string | Buffer, key?: string | Buffer, rejectUnauthorized?: boolean}} [config.tls] - TLS material for HTTPS connections.
+     * @param {boolean} [config.keepAlive] - Reuse connections across requests. Defaults to true.
+     */
+    constructor({ socketPath, tls, keepAlive }?: {
+        socketPath?: string;
+        tls?: {
+            ca?: string | Buffer;
+            cert?: string | Buffer;
+            key?: string | Buffer;
+            rejectUnauthorized?: boolean;
+        };
+        keepAlive?: boolean;
+    });
+    socketPath: string;
+    tls: {
+        ca?: string | Buffer;
+        cert?: string | Buffer;
+        key?: string | Buffer;
+        rejectUnauthorized?: boolean;
+    };
+    keepAlive: boolean;
+    /** @type {{http: any, https: any, zlib: any, stream: any} | null} */
+    _modules: {
+        http: any;
+        https: any;
+        zlib: any;
+        stream: any;
+    } | null;
+    /** @type {any} */
+    _httpAgent: any;
+    /** @type {any} */
+    _httpsAgent: any;
+    /** @returns {import("../capabilities.js").TransportCapabilities} - Supported capabilities. */
+    get capabilities(): import("../capabilities.js").TransportCapabilities;
+    /** @returns {Promise<{http: any, https: any, zlib: any, stream: any}>} - Lazily-loaded Node modules. */
+    _load(): Promise<{
+        http: any;
+        https: any;
+        zlib: any;
+        stream: any;
+    }>;
+    /**
+     * @param {boolean} useTls - Whether the request uses TLS.
+     * @returns {any} - The keep-alive agent for the protocol.
+     */
+    _agent(useTls: boolean): any;
+    /**
+     * Performs a single request and resolves once the response headers arrive,
+     * exposing the (decoded) body as a stream so callers can buffer or stream it.
+     * @param {import("../snap-req.js").NormalizedRequest} request - Normalized request.
+     * @returns {Promise<SnapReqResponse>} - The response.
+     */
+    performRequest(request: import("../snap-req.js").NormalizedRequest): Promise<SnapReqResponse>;
+    /**
+     * @param {import("../snap-req.js").NormalizedRequest} request - Normalized request.
+     * @param {SnapReqHeaders} headers - Headers, mutated with Content-Length / Content-Encoding.
+     * @param {{zlib: any, stream: any}} modules - Node modules.
+     * @returns {{buffer: Buffer | null, stream: import("node:stream").Readable | null}} - Prepared body.
+     */
+    _prepareRequestBody(request: import("../snap-req.js").NormalizedRequest, headers: SnapReqHeaders, { zlib, stream }: {
+        zlib: any;
+        stream: any;
+    }): {
+        buffer: Buffer | null;
+        stream: import("node:stream").Readable | null;
+    };
+    /**
+     * @param {string} encoding - Compression encoding.
+     * @param {any} zlib - The zlib module.
+     * @returns {import("node:stream").Transform} - A compressor transform.
+     */
+    _requestCompressor(encoding: string, zlib: any): import("node:stream").Transform;
+    /**
+     * @param {import("node:http").IncomingMessage} response - The raw response.
+     * @param {any} zlib - The zlib module.
+     * @returns {import("node:stream").Readable} - The decoded response body stream.
+     */
+    _decodeResponseStream(response: import("node:http").IncomingMessage, zlib: any): import("node:stream").Readable;
+    /**
+     * @param {string} encoding - Content encoding.
+     * @param {any} zlib - The zlib module.
+     * @returns {import("node:stream").Transform} - A decompressor transform.
+     */
+    _responseDecoder(encoding: string, zlib: any): import("node:stream").Transform;
+    /**
+     * @param {import("node:http").IncomingMessage} response - The raw response.
+     * @returns {SnapReqHeaders} - The response headers.
+     */
+    _responseHeaders(response: import("node:http").IncomingMessage): SnapReqHeaders;
+    /**
+     * Destroys the keep-alive agents, closing all persistent connections.
+     * @returns {void}
+     */
+    close(): void;
+}
+import SnapReqResponse from "../response.js";
+import SnapReqHeaders from "../headers.js";

package/types/transports/select.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @typedef {"auto" | "node" | "fetch" | "xhr"} TransportName
+ */
+/**
+ * @typedef {object} Transport
+ * @property {import("../capabilities.js").TransportCapabilities} capabilities - Supported capabilities.
+ * @property {(request: import("../snap-req.js").NormalizedRequest) => Promise<import("../response.js").default>} performRequest - Perform a request.
+ * @property {() => void} [close] - Optional resource cleanup.
+ */
+/**
+ * Detects the JavaScript runtime so `auto` can pick the right transport.
+ * @returns {"node" | "react-native" | "browser" | "unknown"} - Detected runtime.
+ */
+export function detectRuntime(): "node" | "react-native" | "browser" | "unknown";
+/**
+ * Resolves a transport for the requested preference. Returns the preference
+ * untouched when it is already a transport instance. The Node transport is
+ * imported dynamically so web/Expo bundlers never pull in `node:*` modules.
+ * @param {TransportName | Transport | undefined} preference - Requested transport.
+ * @param {object} nodeConfig - Configuration forwarded to the Node transport.
+ * @returns {Promise<Transport>} - The resolved transport.
+ */
+export function selectTransport(preference: TransportName | Transport | undefined, nodeConfig: object): Promise<Transport>;
+export type TransportName = "auto" | "node" | "fetch" | "xhr";
+export type Transport = {
+    /**
+     * - Supported capabilities.
+     */
+    capabilities: import("../capabilities.js").TransportCapabilities;
+    /**
+     * - Perform a request.
+     */
+    performRequest: (request: import("../snap-req.js").NormalizedRequest) => Promise<import("../response.js").default>;
+    /**
+     * - Optional resource cleanup.
+     */
+    close?: () => void;
+};

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

@@ -0,0 +1,25 @@
+/**
+ * Transport backed by `XMLHttpRequest`. A fallback for web environments that
+ * lack `fetch`. Buffers the whole response (no incremental streaming) and, like
+ * `fetch`, cannot do Unix sockets, client TLS or request-body compression.
+ */
+export default class XhrTransport {
+    /** @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 {string} rawHeaders - Raw header block from `getAllResponseHeaders`.
+     * @returns {SnapReqHeaders} - The parsed response headers.
+     */
+    _parseHeaders(rawHeaders: string): SnapReqHeaders;
+}
+import SnapReqResponse from "../response.js";
+import SnapReqHeaders from "../headers.js";

package/types/websocket/websocket-channel.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Client-side handle for a channel subscription opened via
+ * `SnapReqWebSocketClient.subscribeChannel()`. Mirrors the server's
+ * subscription lifecycle — `subscribed` (resolves `ready`) / `onMessage` /
+ * `onClose`.
+ */
+export default class SnapReqWebSocketChannel {
+    /**
+     * @param {object} args - Channel arguments.
+     * @param {import("./websocket-client.js").default} args.client - Owning client.
+     * @param {string} args.subscriptionId - Generated id unique within the session.
+     * @param {string} args.channelType - Name the server registered the channel under.
+     * @param {Record<string, any>} [args.params] - Opaque params forwarded to the server.
+     * @param {string} [args.lastEventId] - Resume replay from this event id.
+     * @param {(body: any) => void} [args.onMessage] - Fired on each `channel-message` from the server.
+     * @param {() => void} [args.onDisconnect] - Fired when the socket drops.
+     * @param {() => void} [args.onResume] - Fired when the session resumes after a drop.
+     * @param {(reason: string) => void} [args.onClose] - Fired exactly once when the subscription closes permanently.
+     */
+    constructor({ client, subscriptionId, channelType, params, lastEventId, onMessage, onDisconnect, onResume, onClose }: {
+        client: import("./websocket-client.js").default;
+        subscriptionId: string;
+        channelType: string;
+        params?: Record<string, any>;
+        lastEventId?: string;
+        onMessage?: (body: any) => void;
+        onDisconnect?: () => void;
+        onResume?: () => void;
+        onClose?: (reason: string) => void;
+    });
+    client: import("./websocket-client.js").default;
+    subscriptionId: string;
+    channelType: string;
+    params: Record<string, any>;
+    lastEventId: string;
+    _onMessage: (body: any) => void;
+    _onDisconnect: () => void;
+    _onResume: () => void;
+    _onClose: (reason: string) => void;
+    _ready: boolean;
+    _resumeReadyOnResume: boolean;
+    _subscribed: boolean;
+    _subscribeSent: boolean;
+    _closed: boolean;
+    /** @returns {Promise<void>} - Resolves once the subscription is acknowledged. */
+    _ensureReadyPromise(): Promise<void>;
+    /** @type {Promise<void>} */
+    _readyPromise: Promise<void>;
+    _resolveReady: (value: void | PromiseLike<void>) => void;
+    _rejectReady: (reason?: any) => void;
+    /** @returns {Promise<void>} - Resolves once the subscription is acknowledged. */
+    get ready(): Promise<void>;
+    /** @returns {void} */
+    _resolveReadyState(): void;
+    /** @returns {void} */
+    _markNotReady(): void;
+    /** @returns {void} */
+    _handleSubscribed(): void;
+    /** @returns {void} */
+    _markSubscribeSent(): void;
+    /** @returns {boolean} - Whether the subscription still needs to be sent. */
+    _needsSubscribe(): boolean;
+    /**
+     * @param {any} body - Message payload.
+     * @returns {void}
+     */
+    _handleMessage(body: any): void;
+    /** @returns {void} */
+    _handleDisconnected(): void;
+    /** @returns {void} */
+    _handleResumed(): void;
+    /**
+     * @param {string} reason - Why the subscription closed.
+     * @returns {void}
+     */
+    _handleClosed(reason: string): void;
+    /**
+     * @param {{timeoutMs?: number}} [params] - Options.
+     * @returns {Promise<void>} - Resolves once ready or rejects on timeout.
+     */
+    waitForReady({ timeoutMs }?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** @returns {void} */
+    close(): void;
+    /** @returns {boolean} - Whether the subscription is closed. */
+    isClosed(): boolean;
+    /** @returns {boolean} - Whether the subscription is acknowledged and ready. */
+    isReady(): boolean;
+    /** @returns {boolean} - Whether the subscription is active. */
+    isSubscribed(): boolean;
+}