docs(types): add API docs for public surface

Author: StopMakingThatBigFace

src/client/index.ts

@@ -196,6 +196,7 @@ class WreqClient implements Client {
   }
 }
 
+/** Creates a reusable client with mergeable default options. */
 export function createClient(defaults: ClientDefaults = {}): Client {
   return new WreqClient(defaults);
 }

src/errors/index.ts

@@ -9,11 +9,17 @@ type RequestErrorOptions = {
   attempt?: number;
 };
 
+/** Base error type used by HTTP and WebSocket operations. */
 export class RequestError extends Error {
+  /** Machine-readable error code when one is available. */
   code?: string;
+  /** Original error that caused this failure. */
   cause?: unknown;
+  /** Request associated with the failure, when available. */
   request?: Request;
+  /** Response associated with the failure, when available. */
   response?: Response;
+  /** Attempt number associated with the failure, when available. */
   attempt?: number;
 
   constructor(message: string, options?: RequestErrorOptions) {
@@ -27,7 +33,9 @@ export class RequestError extends Error {
   }
 }
 
+/** Error raised for disallowed HTTP status codes. */
 export class HTTPError extends RequestError {
+  /** HTTP status code returned by the server. */
   status: number;
 
   constructor(message: string, status: number, options?: RequestErrorOptions) {
@@ -37,20 +45,23 @@ export class HTTPError extends RequestError {
   }
 }
 
+/** Error raised when a request exceeds its configured timeout. */
 export class TimeoutError extends RequestError {
   constructor(message = 'Request timed out', options?: RequestErrorOptions) {
     super(message, { ...options, code: 'ERR_TIMEOUT' });
     this.name = 'TimeoutError';
   }
 }
 
+/** Error raised when an operation is aborted. */
 export class AbortError extends RequestError {
   constructor(message = 'The operation was aborted', options?: RequestErrorOptions) {
     super(message, { ...options, code: 'ERR_ABORTED' });
     this.name = 'AbortError';
   }
 }
 
+/** Error raised for WebSocket connection and I/O failures. */
 export class WebSocketError extends RequestError {
   constructor(message = 'WebSocket operation failed', options?: RequestErrorOptions) {
     super(message, { ...options, code: 'ERR_WEBSOCKET' });

src/headers/index.ts

@@ -19,6 +19,7 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return prototype === Object.prototype || prototype === null;
 }
 
+/** Minimal `Headers` implementation used by the public API. */
 export class Headers implements Iterable<HeaderTuple> {
   private readonly store = new Map<string, HeaderEntry>();
   private entriesList: HeaderTuple[] = [];
@@ -69,6 +70,7 @@ export class Headers implements Iterable<HeaderTuple> {
     return { key: trimmed.toLowerCase(), display: trimmed };
   }
 
+  /** Appends a header value without removing existing values for the same name. */
   append(name: string, value: unknown): void {
     const normalized = this.normalizeName(name);
     const entry = this.store.get(normalized.key);
@@ -88,6 +90,7 @@ export class Headers implements Iterable<HeaderTuple> {
     });
   }
 
+  /** Replaces all existing values for a header name. */
   set(name: string, value: unknown): void {
     const normalized = this.normalizeName(name);
     const stringValue = String(value);
@@ -100,22 +103,26 @@ export class Headers implements Iterable<HeaderTuple> {
       name: normalized.display,
       values: [stringValue],
     });
+
     this.entriesList.push([normalized.display, stringValue]);
   }
 
+  /** Returns the combined header value for `name`, or `null` when absent. */
   get(name: string): string | null {
     const normalized = this.normalizeName(name);
     const entry = this.store.get(normalized.key);
 
     return entry ? entry.values.join(', ') : null;
   }
 
+  /** Returns `true` when the header collection contains `name`. */
   has(name: string): boolean {
     const normalized = this.normalizeName(name);
 
     return this.store.has(normalized.key);
   }
 
+  /** Removes all values associated with `name`. */
   delete(name: string): void {
     const normalized = this.normalizeName(name);
 
@@ -125,6 +132,7 @@ export class Headers implements Iterable<HeaderTuple> {
     );
   }
 
+  /** Converts the header collection into a plain object. */
   toObject(): Record<string, string> {
     const result: Record<string, string> = {};
 
@@ -135,10 +143,12 @@ export class Headers implements Iterable<HeaderTuple> {
     return result;
   }
 
+  /** Returns headers as ordered `[name, value]` tuples. */
   toTuples(): HeaderTuple[] {
     return this.entriesList.map(([name, value]) => [name, value]);
   }
 
+  /** Returns unique header names preserving their original casing. */
   toOriginalNames(): string[] {
     const names: string[] = [];
     const seen = new Set<string>();
@@ -157,12 +167,14 @@ export class Headers implements Iterable<HeaderTuple> {
     return names;
   }
 
+  /** Iterates over normalized `[name, value]` header entries. */
   *entries(): IterableIterator<HeaderTuple> {
     for (const entry of this.store.values()) {
       yield [entry.name, entry.values.join(', ')];
     }
   }
 
+  /** Iterates over normalized `[name, value]` header entries. */
   [Symbol.iterator](): IterableIterator<HeaderTuple> {
     return this.entries();
   }

src/http/fetch.ts

@@ -24,6 +24,7 @@ import {
 } from './pipeline/redirects';
 import { runRetryDelay, shouldRetryRequest } from './pipeline/retries';
 
+/** Performs an HTTP request using the native transport pipeline. */
 export async function fetch(input: RequestInput, init?: WreqInit) {
   const merged = await mergeInputAndInit(input, init);
   const state = (merged.init.context ? { ...merged.init.context } : {}) as Record<string, unknown>;

src/http/request.ts

@@ -10,10 +10,15 @@ import {
   toBodyBytes,
 } from './body/bytes';
 
+/** WHATWG-style request wrapper used by the public API. */
 export class Request {
+  /** Fully resolved request URL. */
   readonly url: string;
+  /** Uppercased HTTP method. */
   readonly method: string;
+  /** Request headers. */
   readonly headers: Headers;
+  /** Abort signal associated with the request, if any. */
   readonly signal: AbortSignal | null;
   #bodyBytes: Uint8Array | null;
   #multipartBody: globalThis.Request | null;
@@ -52,6 +57,7 @@ export class Request {
     this.#setBody(init.body);
   }
 
+  /** Returns the request body as a readable byte stream. */
   get body(): ReadableStream<Uint8Array> | null {
     if (this.#bodyUsed || (this.#bodyBytes === null && this.#multipartBody === null)) {
       return null;
@@ -68,10 +74,12 @@ export class Request {
     return this.#stream;
   }
 
+  /** Indicates whether the request body has already been consumed. */
   get bodyUsed(): boolean {
     return this.#bodyUsed;
   }
 
+  /** Creates a clone whose body can be consumed independently. */
   clone(): Request {
     if (this.#bodyUsed) {
       throw new TypeError('Request body is already used');
@@ -89,22 +97,27 @@ export class Request {
     return cloned;
   }
 
+  /** Reads the request body as UTF-8 text. */
   async text(): Promise<string> {
     return Buffer.from(await this.#consumeBytes()).toString('utf8');
   }
 
+  /** Reads the request body as JSON. */
   async json<T = unknown>(): Promise<T> {
     return JSON.parse(await this.text()) as T;
   }
 
+  /** Reads the request body as an `ArrayBuffer`. */
   async arrayBuffer(): Promise<ArrayBuffer> {
     return Uint8Array.from(await this.#consumeBytes()).buffer;
   }
 
+  /** Reads the request body as a `Blob`. */
   async blob(): Promise<Blob> {
     return new Blob([await this.#consumeBytes()]);
   }
 
+  /** Reads the request body as `FormData`. */
   async formData(): Promise<FormData> {
     if (this.#multipartBody) {
       if (this.#bodyUsed) {
@@ -132,6 +145,7 @@ export class Request {
     return formData;
   }
 
+  /** Internal helper that clones the encoded request body bytes. */
   async _cloneBodyBytes(): Promise<Uint8Array | null> {
     if (this.#bodyBytes !== null) {
       return cloneBytes(this.#bodyBytes);
@@ -144,16 +158,19 @@ export class Request {
     return new Uint8Array(await this.#multipartBody.clone().arrayBuffer());
   }
 
+  /** Internal helper that prepares body bytes for native dispatch. */
   async _getBodyBytesForDispatch(): Promise<Uint8Array | undefined> {
     return (await this._cloneBodyBytes()) ?? undefined;
   }
 
+  /** Internal helper that marks the request body as consumed. */
   _markBodyUsed(): void {
     if (this.#bodyBytes !== null || this.#multipartBody !== null) {
       this.#bodyUsed = true;
     }
   }
 
+  /** Internal helper that creates a modified request copy. */
   _replace(input: {
     url?: string;
     method?: string;

src/http/response-meta.ts

@@ -2,25 +2,31 @@ import { Readable } from 'node:stream';
 import type { RequestTimings, RedirectEntry, TlsPeerInfo, WreqResponseMeta } from '../types';
 import type { Response } from './response';
 
+/** Implementation backing the `response.wreq` metadata surface. */
 export class ResponseMeta implements WreqResponseMeta {
   constructor(private readonly response: Response) {}
 
+  /** Cookies parsed from the final response state. */
   get cookies(): Record<string, string> {
     return { ...this.response._cookies };
   }
 
+  /** Raw `Set-Cookie` header values from the final response. */
   get setCookies(): string[] {
     return [...this.response._setCookies];
   }
 
+  /** Timing metrics collected for the request. */
   get timings(): RequestTimings | undefined {
     return this.response._timings ? { ...this.response._timings } : undefined;
   }
 
+  /** Redirect chain leading to the final response. */
   get redirectChain(): RedirectEntry[] {
     return [...this.response._redirectChain];
   }
 
+  /** Parsed `content-length` header value when present. */
   get contentLength(): number | undefined {
     const value = this.response.headers.get('content-length');
 
@@ -33,6 +39,7 @@ export class ResponseMeta implements WreqResponseMeta {
     return Number.isFinite(parsed) ? parsed : undefined;
   }
 
+  /** TLS peer certificate information when requested. */
   get tls(): TlsPeerInfo | undefined {
     return this.response._tls
       ? {
@@ -46,6 +53,7 @@ export class ResponseMeta implements WreqResponseMeta {
       : undefined;
   }
 
+  /** Converts the response body into a Node.js readable stream. */
   readable(): Readable {
     const body = this.response.clone().body;
 

src/http/response.ts

@@ -95,19 +95,33 @@ function cloneTlsInfo(value: TlsPeerInfo | undefined): TlsPeerInfo | undefined {
   };
 }
 
+/** WHATWG-style response wrapper. */
 export class Response {
+  /** HTTP status code. */
   readonly status: number;
+  /** HTTP reason phrase. */
   readonly statusText: string;
+  /** Whether `status` is in the 2xx range. */
   readonly ok: boolean;
+  /** Final response URL. */
   readonly url: string;
+  /** Response headers. */
   readonly headers: Headers;
+  /** Response type exposed for Fetch API compatibility. */
   readonly type = 'basic' as const;
+  /** Extra transport metadata exposed by node-wreq. */
   readonly wreq: WreqResponseMeta;
+  /** Internal cookie map used to build `response.wreq.cookies`. */
   _cookies: Record<string, string>;
+  /** Internal raw `Set-Cookie` list used to build `response.wreq.setCookies`. */
   _setCookies: string[];
+  /** Internal timing metadata used to build `response.wreq.timings`. */
   _timings?: RequestTimings;
+  /** Internal redirect chain used to build `response.wreq.redirectChain`. */
   _redirectChain: RedirectEntry[];
+  /** Internal TLS metadata used to build `response.wreq.tls`. */
   _tls?: TlsPeerInfo;
+  /** Whether the response was produced after at least one redirect hop. */
   redirected: boolean;
   #payloadBytes: Uint8Array | null;
   #bodyHandle: number | null;
@@ -154,49 +168,59 @@ export class Response {
     this.#orphanedStreamReaders = [];
   }
 
+  /** Indicates whether the response body has already been consumed. */
   get bodyUsed(): boolean {
     return this.#bodyUsed;
   }
 
+  /** Attaches redirect metadata and returns the same response instance. */
   setRedirectMetadata(chain: RedirectEntry[]): this {
     this.redirected = chain.length > 0;
     this._redirectChain = [...chain];
 
     return this;
   }
 
+  /** Attaches timing metadata and returns the same response instance. */
   setTimings(timings: RequestTimings): this {
     this._timings = { ...timings };
 
     return this;
   }
 
+  /** Returns the response body as a readable byte stream. */
   get body(): ReadableStream<Uint8Array> | null {
     return this.#ensureStream();
   }
 
+  /** Reads the response body as text, honoring the declared charset when possible. */
   async text(): Promise<string> {
     return decodeText(await this.#consumeBytes(), this.headers.get('content-type'));
   }
 
+  /** Reads the response body as JSON. */
   async json<T = unknown>(): Promise<T> {
     return JSON.parse(await this.text()) as T;
   }
 
+  /** Reads the response body as an `ArrayBuffer`. */
   async arrayBuffer(): Promise<ArrayBuffer> {
     return Uint8Array.from(await this.#consumeBytes()).buffer;
   }
 
+  /** Reads the response body as a `Blob`. */
   async blob(): Promise<Blob> {
     return new Blob([await this.#consumeBytes()]);
   }
 
+  /** Reads the response body as `FormData`. */
   async formData(): Promise<FormData> {
     const contentType = this.headers.get('content-type') ?? '';
 
     return parseResponseFormData(await this.#consumeBytes(), contentType);
   }
 
+  /** Creates a clone whose body can be consumed independently. */
   clone(): Response {
     if (this.#isBodyUnusable()) {
       throw new TypeError('Response.clone: Body has already been consumed.');

src/native/profiles.ts

@@ -3,6 +3,7 @@ import { getBinding } from './binding';
 
 let cachedProfiles: BrowserProfile[] | undefined;
 
+/** Returns the list of browser profiles supported by the native transport. */
 export function getProfiles(): BrowserProfile[] {
   cachedProfiles ??= getBinding().getProfiles() as BrowserProfile[];