@exhumer/signalr-client 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1079 @@
+import { Dispatcher } from 'undici';
+export { Dispatcher } from 'undici';
+import { Readable } from 'node:stream';
+import { CookieJar } from 'tough-cookie';
+export { CookieJar } from 'tough-cookie';
+import { EventEmitter } from 'node:events';
+export { CookieAgent, cookie } from '@exhumer/undici-cookie-agent';
+
+/**
+ * constants.ts
+ *
+ * All SignalR protocol constants, enumerations, and timing defaults.
+ * Uses `as const satisfies` (TS 4.9+) so values carry their narrow literal
+ * types while being verified against a constraint at compile time.
+ */
+declare const MessageType: Readonly<{
+    readonly Invocation: 1;
+    readonly StreamItem: 2;
+    readonly Completion: 3;
+    readonly StreamInvocation: 4;
+    readonly CancelInvocation: 5;
+    readonly Ping: 6;
+    readonly Close: 7;
+}>;
+/** Union of all valid message type numbers. */
+type MessageTypeValue = (typeof MessageType)[keyof typeof MessageType];
+declare const HubConnectionState: Readonly<{
+    readonly Disconnected: "Disconnected";
+    readonly Connecting: "Connecting";
+    readonly Connected: "Connected";
+    readonly Disconnecting: "Disconnecting";
+    readonly Reconnecting: "Reconnecting";
+}>;
+/** Union of all valid connection state strings. */
+type HubConnectionState = (typeof HubConnectionState)[keyof typeof HubConnectionState];
+declare const LogLevel: {
+    readonly Trace: 0;
+    readonly Debug: 1;
+    readonly Information: 2;
+    readonly Warning: 3;
+    readonly Error: 4;
+    readonly Critical: 5;
+    readonly None: 6;
+};
+type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+declare const HttpTransportType: {
+    readonly None: 0;
+    readonly WebSockets: 1;
+    readonly ServerSentEvents: 2;
+    readonly LongPolling: 4;
+};
+/** Bitmask of enabled transports - values can be OR-ed together. */
+type HttpTransportType = (typeof HttpTransportType)[keyof typeof HttpTransportType];
+declare const TransferFormat: {
+    readonly Text: 1;
+    readonly Binary: 2;
+};
+type TransferFormat = (typeof TransferFormat)[keyof typeof TransferFormat];
+/** ASCII 30 - the byte that terminates every SignalR JSON message. */
+declare const RECORD_SEPARATOR: "\u001E";
+/** Negotiate version we advertise to the server. */
+declare const NEGOTIATE_VERSION: 1;
+declare const DEFAULT_TIMEOUT_IN_MS: 30000;
+declare const DEFAULT_PING_INTERVAL_IN_MS: 15000;
+declare const DEFAULT_SERVER_TIMEOUT_IN_MS: 30000;
+
+/**
+ * http-client.ts
+ *
+ * Five HTTP client implementations backed by undici, each wrapping a different
+ * undici primitive.  All five satisfy the `IHttpClient` contract so any one
+ * can be used wherever an HTTP client is required (negotiate, SSE, polling…).
+ *
+ * ┌────────────────────┬───────────────────────────────────────────────────┐
+ * │ Class              │ undici primitive                                  │
+ * ├────────────────────┼───────────────────────────────────────────────────┤
+ * │ RequestHttpClient  │ undici.request()                                  │
+ * │ FetchHttpClient    │ undici.fetch()      (WHATWG-compatible)           │
+ * │ StreamHttpClient   │ undici.stream()     (factory-based streaming)     │
+ * │ PipelineHttpClient │ undici.pipeline()   (Duplex pipe chain)           │
+ * │ DispatchHttpClient │ Dispatcher#dispatch (low-level handler interface) ← DEFAULT │
+ * └────────────────────┴───────────────────────────────────────────────────┘
+ *
+ * Dispatcher (session-level):
+ *   Every client accepts an optional `dispatcher` option.  Pass an undici
+ *   `Agent`, `Pool`, `Client`, `ProxyAgent`, etc. to customise connection
+ *   pooling, proxy routing, TLS, or any other transport-level behaviour for
+ *   the entire client session.  When omitted, undici's process-global
+ *   default agent is used (`getGlobalDispatcher()`).
+ *
+ * HttpClient:
+ *   An alias for `DispatchHttpClient` so existing code that imported
+ *   `HttpClient` continues to work without changes.
+ */
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Per-request options accepted by every client method.
+ * These mirror the previous `node:http`-based API surface exactly so callers
+ * do not need to be changed when switching client implementations.
+ */
+interface RequestOptions {
+    /** Per-request headers merged on top of the instance-level defaults. */
+    readonly headers?: Record<string, string>;
+    /**
+     * Request body.
+     * Plain objects are serialised to JSON automatically.
+     * Strings are sent as-is (set Content-Type explicitly if needed).
+     */
+    readonly body?: string | Record<string, unknown> | null;
+    /** Override the session-level timeout for this single request (ms). */
+    readonly timeout?: number;
+}
+/**
+ * Session-level options shared by all client constructors.
+ */
+interface HttpClientOptions {
+    /** Headers sent with every request (merged before per-request headers). */
+    readonly headers?: Record<string, string>;
+    /** Default timeout in milliseconds applied to every request (default: 30 000). */
+    readonly timeout?: number;
+    /**
+     * undici Dispatcher to use for the entire session.
+     *
+     * You can pass any `Dispatcher` subclass:
+     *   - `new undici.Agent(opts)`              - connection-pool tuning
+     *   - `new undici.Pool(origin, opts)`       - per-origin pool
+     *   - `new undici.Client(origin, opts)`     - single connection
+     *   - `new undici.ProxyAgent(proxyUrl)`     - HTTP proxy
+     *   - `new undici.MockAgent()`              - in-process mocking
+     *
+     * When omitted the process-global dispatcher (`getGlobalDispatcher()`)
+     * is used, which is undici's default `Agent`.
+     */
+    readonly dispatcher?: Dispatcher;
+}
+/**
+ * Holds the session-level options and exposes the convenience wrappers
+ * (`get`, `post`, `delete`) that delegate to the abstract `request` method.
+ *
+ * Concrete subclasses only need to implement `request()` and `stream()`.
+ */
+declare abstract class BaseUndiciClient implements IHttpClient {
+    /** Default headers merged into every outgoing request. */
+    protected readonly defaultHeaders: Record<string, string>;
+    /** Session-level request timeout in milliseconds. */
+    protected readonly defaultTimeout: number;
+    /**
+     * Shared undici Dispatcher.  May be an Agent, Pool, Client, ProxyAgent, etc.
+     * Defaults to undici's process-global agent when not specified.
+     */
+    protected readonly dispatcher: Dispatcher;
+    constructor(options?: HttpClientOptions);
+    get(url: string, options?: RequestOptions): Promise<HttpResponse>;
+    post(url: string, options?: RequestOptions): Promise<HttpResponse>;
+    delete(url: string, options?: RequestOptions): Promise<HttpResponse>;
+    abstract request(method: HttpMethod, url: string, options?: RequestOptions): Promise<HttpResponse>;
+    abstract stream(method: HttpMethod, url: string, options?: RequestOptions): Promise<StreamResult>;
+}
+/**
+ * HTTP client backed by `undici.request()`.
+ *
+ * `undici.request` is the recommended high-level API for most use-cases.
+ * It returns a Promise that resolves with `{ statusCode, headers, body }`
+ * where `body` is an undici `BodyReadable` (a Node `Readable` subclass).
+ *
+ * For buffered responses (`request()`) we call `body.text()` to collect the
+ * full response.  For streaming responses (`stream()`) we return `body`
+ * directly as the `StreamResult.body` Readable, giving the caller zero-copy
+ * access to the response stream.
+ *
+ */
+declare class RequestHttpClient extends BaseUndiciClient {
+    /**
+     * Buffered request - collects the entire response body as a string.
+     *
+     * Timeout is implemented via undici's built-in `headersTimeout` /
+     * `bodyTimeout` options rather than an external `setTimeout`.
+     */
+    request(method: HttpMethod, url: string, options?: RequestOptions): Promise<HttpResponse>;
+    /**
+     * Streaming request - returns the response body `Readable` without
+     * buffering.  Used by SSE and long-polling transports.
+     *
+     * The `abort()` method destroys the underlying socket and the body stream.
+     */
+    stream(method: HttpMethod, url: string, options?: RequestOptions): Promise<StreamResult>;
+}
+/**
+ * HTTP client backed by `undici.fetch()`.
+ *
+ * `undici.fetch` is undici's WHATWG-compatible Fetch implementation.
+ * It accepts the same options as the browser `fetch()` API, plus an
+ * undici-specific `dispatcher` field for custom transport control.
+ *
+ * Useful when you need browser API compatibility (e.g., tests that run in
+ * both Node and a browser-like environment) or when consuming WHATWG `Response`
+ * helpers such as `res.json()` / `res.formData()`.
+ *
+ * For `stream()` we convert the WHATWG `ReadableStream<Uint8Array>` body to a
+ * Node.js `Readable` via `Readable.fromWeb()` (Node 17+).
+ */
+declare class FetchHttpClient extends BaseUndiciClient {
+    request(method: HttpMethod, url: string, options?: RequestOptions): Promise<HttpResponse>;
+    stream(method: HttpMethod, url: string, options?: RequestOptions): Promise<StreamResult>;
+}
+/**
+ * HTTP client backed by `undici.stream()`.
+ *
+ * `undici.stream` uses a *factory callback* pattern: you supply a function
+ * that receives `{ statusCode, headers, body }` and must return a
+ * `Writable` to which the response body is piped.
+ *
+ * This makes it ideal when you want to pipe response bytes directly to a
+ * destination (e.g., a file, a transform, or a compression stream) without
+ * ever holding the entire response in memory.
+ *
+ * For buffered `request()` we use a `PassThrough` as the sink and collect
+ * its output.  For streaming `stream()` we expose the PassThrough's
+ * readable side as `StreamResult.body`.
+ */
+declare class StreamHttpClient extends BaseUndiciClient {
+    request(method: HttpMethod, url: string, options?: RequestOptions): Promise<HttpResponse>;
+    stream(method: HttpMethod, url: string, options?: RequestOptions): Promise<StreamResult>;
+}
+/**
+ * HTTP client backed by `undici.pipeline()`.
+ *
+ * `undici.pipeline` returns a `stream.Duplex`:
+ *   - **Writable side**: the request body (write / pipe into it).
+ *   - **Readable side**: whatever your handler function *returns*.
+ *
+ * The handler receives `{ statusCode, headers, body }` and must return a
+ * `Readable`.  Whatever that readable emits becomes the duplex's output.
+ *
+ * Typical use: response transformation pipelines
+ *   `pipeline(url, opts, ({ body }) => body.pipe(gunzip()))`
+ *
+ * For `request()` we return the raw body from the handler, collect the duplex
+ * output into a buffer, and resolve with the buffered string.
+ *
+ * For `stream()` we return the raw body from the handler and give the caller
+ * the duplex's readable side directly - zero extra buffering.
+ */
+declare class PipelineHttpClient extends BaseUndiciClient {
+    request(method: HttpMethod, url: string, options?: RequestOptions): Promise<HttpResponse>;
+    stream(method: HttpMethod, url: string, options?: RequestOptions): Promise<StreamResult>;
+}
+/**
+ * HTTP client backed by `Dispatcher#dispatch()`.
+ *
+ * `dispatch` is the *lowest-level* undici API.  It exposes the full
+ * request/response lifecycle as a handler interface (undici 8+):
+ *
+ *   onRequestStart   → request is about to be sent; receives DispatchController
+ *   onResponseStart  → response status + headers received
+ *   onResponseData   → response body chunk
+ *   onResponseEnd    → response fully consumed
+ *   onResponseError  → error at any stage
+ *
+ * This gives you maximum control: you can abort mid-stream, transform
+ * chunks on the fly, or implement custom back-pressure logic.
+ *
+ * Unlike the other clients, `DispatchHttpClient` *requires* a `Dispatcher`
+ * (an `Agent`, `Pool`, or `Client` instance).  If none is provided the
+ * process-global agent is used.
+ *
+ * Note: `dispatcher.dispatch()` needs the URL split into `origin` + `path`
+ * (for `Agent` / `Pool`) or just `path` (for `Client` whose origin is
+ * already bound).  We always pass `origin` for maximum compatibility.
+ */
+declare class DispatchHttpClient extends BaseUndiciClient {
+    request(method: HttpMethod, url: string, options?: RequestOptions): Promise<HttpResponse>;
+    stream(method: HttpMethod, url: string, options?: RequestOptions): Promise<StreamResult>;
+}
+
+/**
+ * messages.ts
+ *
+ * Full discriminated-union type definitions for every SignalR hub protocol
+ * message.  The `type` field on each interface carries a numeric literal type
+ * derived from the `MessageType` constants so TypeScript narrows correctly
+ * inside `switch` / `if` statements.
+ *
+ * Reference:
+ *   https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/HubProtocol.md
+ */
+
+declare const __invocationIdBrand: unique symbol;
+/**
+ * Opaque wrapper around `string` for invocation IDs.
+ * Prevents mixing arbitrary strings with IDs at the type level.
+ */
+type InvocationId = string & {
+    readonly [__invocationIdBrand]: void;
+};
+/** Cast a plain string to an InvocationId (only used inside the library). */
+declare function toInvocationId(s: string): InvocationId;
+/** Optional headers that may appear on any hub message. */
+type MessageHeaders = Readonly<Record<string, string>>;
+interface BaseMessage {
+    readonly headers?: MessageHeaders;
+}
+type MT = typeof MessageType;
+/** Type 1 - Server→Client or Client→Server method call. */
+interface InvocationMessage extends BaseMessage {
+    readonly type: MT['Invocation'];
+    /** Absent on fire-and-forget invocations. */
+    readonly invocationId?: InvocationId;
+    readonly target: string;
+    readonly arguments: readonly unknown[];
+    readonly streamIds?: readonly string[];
+}
+/** Type 2 - One item from a server-streaming method. */
+interface StreamItemMessage extends BaseMessage {
+    readonly type: MT['StreamItem'];
+    readonly invocationId: InvocationId;
+    readonly item: unknown;
+}
+/** Type 3 - Terminal result or error for an invocation / stream. */
+interface CompletionMessage extends BaseMessage {
+    readonly type: MT['Completion'];
+    readonly invocationId: InvocationId;
+    readonly error?: string;
+    readonly result?: unknown;
+}
+/** Type 4 - Client initiates a server-streaming call. */
+interface StreamInvocationMessage extends BaseMessage {
+    readonly type: MT['StreamInvocation'];
+    readonly invocationId: InvocationId;
+    readonly target: string;
+    readonly arguments: readonly unknown[];
+    readonly streamIds?: readonly string[];
+}
+/** Type 5 - Client cancels an outstanding server stream. */
+interface CancelInvocationMessage extends BaseMessage {
+    readonly type: MT['CancelInvocation'];
+    readonly invocationId: InvocationId;
+}
+/** Type 6 - Keep-alive ping; expects no response from the other side. */
+interface PingMessage extends BaseMessage {
+    readonly type: MT['Ping'];
+}
+/** Type 7 - Graceful close notification from the server. */
+interface CloseMessage extends BaseMessage {
+    readonly type: MT['Close'];
+    readonly error?: string;
+    readonly allowReconnect?: boolean;
+}
+/** Exhaustive discriminated union of all SignalR hub protocol messages. */
+type HubMessage = InvocationMessage | StreamItemMessage | CompletionMessage | StreamInvocationMessage | CancelInvocationMessage | PingMessage | CloseMessage;
+/**
+ * Asserts a code path is unreachable at compile time.
+ * Use at the `default` branch of a `switch` over `HubMessage['type']`.
+ */
+declare function assertNever(_x: never, label?: string): never;
+declare function isInvocationMessage(msg: HubMessage): msg is InvocationMessage;
+declare function isStreamItemMessage(msg: HubMessage): msg is StreamItemMessage;
+declare function isCompletionMessage(msg: HubMessage): msg is CompletionMessage;
+declare function isStreamInvocationMessage(msg: HubMessage): msg is StreamInvocationMessage;
+declare function isCancelInvocationMessage(msg: HubMessage): msg is CancelInvocationMessage;
+declare function isPingMessage(msg: HubMessage): msg is PingMessage;
+declare function isCloseMessage(msg: HubMessage): msg is CloseMessage;
+
+/** Minimal logger contract.  Implement this to plug in any logging framework. */
+interface ILogger {
+    log(logLevel: LogLevel, message: string): void;
+}
+/** Low-level transport abstraction (WebSocket / SSE / LongPolling). */
+interface ITransport {
+    /** Human-readable name used in log messages and error reporting. */
+    readonly name: string;
+    /**
+     * Open the transport connection.
+     * @param url            Fully-qualified URL including any query parameters.
+     * @param transferFormat Text or Binary.
+     */
+    connect(url: string, transferFormat: TransferFormat): Promise<void>;
+    /** Send a message over the open transport. */
+    send(data: string | Uint8Array): Promise<void>;
+    /** Tear down the connection cleanly. */
+    stop(): Promise<void>;
+    /** Called by HubConnection whenever data arrives. */
+    onreceive: ((data: string | Uint8Array) => void) | null;
+    /** Called by HubConnection when the transport is closed (optionally with error). */
+    onclose: ((error?: Error) => void) | null;
+}
+/** Wire-protocol codec (JSON today; MessagePack can be added as an alternate). */
+interface IHubProtocol {
+    readonly name: string;
+    readonly version: number;
+    readonly transferFormat: TransferFormat;
+    /**
+     * Decode raw bytes/string into zero or more hub messages.
+     * Implementations must handle partial/buffered inputs gracefully.
+     */
+    parseMessages(input: string | ArrayBuffer, logger: ILogger): HubMessage[];
+    /** Encode a single hub message to its wire representation. */
+    writeMessage(message: HubMessage): string | ArrayBuffer;
+}
+/** Context passed to the retry policy on each reconnect attempt. */
+interface RetryContext {
+    readonly previousRetryCount: number;
+    readonly elapsedMilliseconds: number;
+    readonly retryReason: Error | null;
+}
+/**
+ * Controls the automatic-reconnect delay strategy.
+ * Return `null` to stop retrying.
+ */
+interface IRetryPolicy {
+    nextRetryDelayInMilliseconds(retryContext: RetryContext): number | null;
+}
+/** Observer passed to `IStreamResult.subscribe`. */
+interface IStreamSubscriber<T> {
+    readonly next?: (value: T) => void;
+    readonly error?: (err: Error) => void;
+    readonly complete?: () => void;
+}
+/**
+ * A handle returned by `subscribe` that lets the caller cancel the stream.
+ * Implements `Symbol.dispose` for use with the `using` keyword (TS 5.2+).
+ */
+interface ISubscription {
+    dispose(): void;
+    /** Enables `using subscription = connection.stream(...).subscribe(...)` */
+    [Symbol.dispose](): void;
+}
+/**
+ * Lazy stream result - the server-streaming call is not sent until
+ * `subscribe` is called.
+ */
+interface IStreamResult<T> {
+    subscribe(subscriber: IStreamSubscriber<T>): ISubscription;
+}
+/** Shape of the /negotiate response from an ASP.NET Core SignalR server. */
+interface NegotiateResponse {
+    readonly connectionId?: string;
+    readonly connectionToken?: string;
+    readonly negotiateVersion?: number;
+    readonly url?: string;
+    readonly accessToken?: string;
+    readonly error?: string;
+    readonly availableTransports?: readonly AvailableTransport[];
+}
+interface AvailableTransport {
+    readonly transport: string;
+    readonly transferFormats: readonly string[];
+}
+/** Buffered HTTP response shared by all client implementations. */
+interface HttpResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string | string[] | undefined>>;
+    readonly body: string;
+}
+/**
+ * Result of a non-buffered (streaming) HTTP request.
+ *
+ * `body`  - Node.js Readable carrying the response bytes.
+ *           The SSE and long-polling transports consume this stream directly.
+ *
+ * `abort` - Cancels the in-flight request and destroys the body stream.
+ *           Replaces the former `req.destroy()` pattern.
+ */
+interface StreamResult {
+    readonly statusCode: number;
+    readonly headers: Readonly<Record<string, string | string[] | undefined>>;
+    readonly body: Readable;
+    abort(): void;
+}
+/**
+ * Common contract satisfied by all five HTTP client variants
+ * (Request, Fetch, Stream, Pipeline, Dispatch).
+ *
+ * HubConnection depends on this interface so any implementation can be
+ * injected via `HubConnectionOptions.httpClient`.
+ */
+interface IHttpClient {
+    get(url: string, options?: RequestOptions): Promise<HttpResponse>;
+    post(url: string, options?: RequestOptions): Promise<HttpResponse>;
+    delete(url: string, options?: RequestOptions): Promise<HttpResponse>;
+    request(method: HttpMethod, url: string, options?: RequestOptions): Promise<HttpResponse>;
+    stream(method: HttpMethod, url: string, options?: RequestOptions): Promise<StreamResult>;
+}
+
+/**
+ * hub-connection.ts
+ *
+ * Core HubConnection - the main object users interact with.
+ *
+ * Mirrors the Microsoft SignalR JavaScript client API with full TypeScript types:
+ *   start() / stop()
+ *   invoke<T>(method, ...args)    → Promise<T>
+ *   send(method, ...args)         → Promise<void>
+ *   stream<T>(method, ...args)    → IStreamResult<T>
+ *   on(method, handler)
+ *   off(method, [handler])
+ *   onclose / onreconnecting / onreconnected
+ */
+
+interface HubConnectionOptions {
+    readonly logger?: ILogger;
+    readonly accessTokenFactory?: () => Promise<string | null>;
+    /** Bitmask of HttpTransportType flags (default: all transports). */
+    readonly transport?: number;
+    readonly headers?: Record<string, string>;
+    readonly skipNegotiation?: boolean;
+    readonly serverTimeoutInMilliseconds?: number;
+    readonly keepAliveIntervalInMilliseconds?: number;
+    readonly reconnectPolicy?: IRetryPolicy | null;
+    /**
+     * undici Dispatcher shared by all HTTP requests (negotiate, SSE, polling)
+     * and the WebSocket upgrade for this connection.
+     *
+     * Pass an `Agent`, `Pool`, `Client`, `ProxyAgent`, etc. to customise
+     * connection pooling, TLS, or proxy routing for the entire SignalR session.
+     * When omitted, undici's process-global default agent is used.
+     */
+    readonly dispatcher?: Dispatcher;
+    /**
+     * Custom HTTP client to use for all requests made by this connection
+     * (negotiate, SSE body reads, long-polling).
+     *
+     * When omitted, a `DispatchHttpClient` is created automatically using
+     * the `dispatcher` option (if any).  Provide this to use a different
+     * undici primitive (e.g. `FetchHttpClient`) or to inject a mock in tests.
+     */
+    readonly httpClient?: IHttpClient;
+}
+declare class HubConnection {
+    #private;
+    constructor(url: string, options?: HubConnectionOptions);
+    get state(): HubConnectionState;
+    get connectionId(): string | null;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Invoke a hub method and return the server's result.
+     *
+     * @typeParam T  The expected return type.  Asserted at runtime - the server
+     *               decides the actual value.
+     */
+    invoke<T = void>(methodName: string, ...args: unknown[]): Promise<T>;
+    /**
+     * Fire-and-forget hub method invocation.
+     * The server does not send a completion message.
+     */
+    send(methodName: string, ...args: unknown[]): Promise<void>;
+    /**
+     * Start a server-streaming invocation.
+     * The call is not sent until `subscribe` is called.
+     * The returned `ISubscription` implements `Symbol.dispose` for `using`.
+     *
+     * @typeParam T  Type of each streamed item.
+     *
+     * @example
+     * ```ts
+     * using sub = connection.stream<number>('Counter', 10).subscribe({
+     *   next:     (n) => console.log(n),
+     *   complete: ()  => console.log('done'),
+     * });
+     * ```
+     */
+    stream<T = unknown>(methodName: string, ...args: unknown[]): IStreamResult<T>;
+    /**
+     * Register a handler for a server→client hub method.
+     * Multiple handlers for the same method are supported.
+     *
+     * @typeParam TArgs  Tuple of argument types for the hub method.
+     */
+    on<TArgs extends unknown[] = unknown[]>(methodName: string, handler: (...args: TArgs) => void): void;
+    /**
+     * Remove a previously registered handler, or all handlers for a method.
+     */
+    off(methodName: string, handler?: (...args: unknown[]) => void): void;
+    onclose(callback: (error?: Error) => void): void;
+    onreconnecting(callback: (error?: Error) => void): void;
+    onreconnected(callback: (connectionId: string | null) => void): void;
+}
+
+/**
+ * hub-connection-builder.ts
+ *
+ * Fluent builder for HubConnection - mirrors the official Microsoft client API.
+ * Uses `const` type parameters (TS 5.0+) and `NoInfer<T>` (TS 5.4+) where
+ * applicable to preserve literal types and prevent unintended widening.
+ *
+ * Usage
+ * ─────
+ *   const connection = new HubConnectionBuilder()
+ *     .withUrl('https://example.com/hub', {
+ *       accessTokenFactory: () => fetchToken(),
+ *       transport: HttpTransportType.WebSockets,
+ *     })
+ *     .configureLogging(LogLevel.Information)
+ *     .withAutomaticReconnect()
+ *     .build();
+ */
+
+interface UrlOptions {
+    /** Async function returning a Bearer token (or null for unauthenticated). */
+    readonly accessTokenFactory?: () => Promise<string | null>;
+    /**
+     * Bitmask of {@link HttpTransportType} values.
+     * Defaults to all three transports if omitted.
+     */
+    readonly transport?: number;
+    /** Extra HTTP headers appended to every request (negotiate, upgrade, poll…). */
+    readonly headers?: Record<string, string>;
+    /**
+     * Skip the /negotiate step and connect directly via WebSocket.
+     * Only valid when transport is exclusively `HttpTransportType.WebSockets`.
+     */
+    readonly skipNegotiation?: boolean;
+    /** ms before the connection is considered unresponsive (default: 30 000). */
+    readonly serverTimeoutInMilliseconds?: number;
+    /** ms between keep-alive pings (default: 15 000). */
+    readonly keepAliveIntervalInMilliseconds?: number;
+}
+declare class HubConnectionBuilder {
+    #private;
+    withUrl(url: string, options?: UrlOptions): this;
+    /**
+     * Enable automatic cookie handling for the entire connection session using
+     * a `tough-cookie` `CookieJar` and an `@exhumer/undici-cookie-agent` `CookieAgent`.
+     *
+     * When enabled, the `CookieAgent` wraps every outgoing request - including
+     * the `/negotiate` POST, WebSocket upgrade, SSE long-lived GET, and all
+     * long-polling requests - so that:
+     *
+     *  1. `Set-Cookie` headers in the **negotiate response** (and any subsequent
+     *     response) are stored in the jar automatically.
+     *  2. All subsequent requests from the same session include the matching
+     *     `Cookie` header, exactly as a browser would.
+     *
+     * @param jar
+     *   An existing `CookieJar` to use.  Pass your own jar when you need to
+     *   pre-seed cookies (e.g. an auth session cookie obtained before calling
+     *   `start()`) or inspect the jar after the session ends.
+     *   When omitted a new, empty jar is created automatically.
+     *
+     * @throws if {@link withDispatcher} has already been called.  To combine a
+     *   custom dispatcher (e.g. `ProxyAgent`) with cookie support, compose the
+     *   `cookie` interceptor onto your dispatcher and pass it to `withDispatcher()`:
+     *
+     * ```ts
+     * import { ProxyAgent } from 'undici';
+     * import { cookie, CookieJar } from '@exhumer/signalr-client';
+     *
+     * const jar   = new CookieJar();
+     * const agent = new ProxyAgent('http://proxy:8080').compose(cookie({ jar }));
+     *
+     * const conn = new HubConnectionBuilder()
+     *   .withUrl('https://example.com/hub')
+     *   .withDispatcher(agent)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Automatic jar - no pre-configuration needed
+     * const conn = new HubConnectionBuilder()
+     *   .withUrl('https://example.com/hub')
+     *   .withCookies()
+     *   .build();
+     *
+     * // Pre-seeded jar - inject a session cookie before connecting
+     * import { CookieJar } from '@exhumer/signalr-client';
+     * const jar = new CookieJar();
+     * await jar.setCookie('session=abc123', 'https://example.com');
+     *
+     * const conn = new HubConnectionBuilder()
+     *   .withUrl('https://example.com/hub')
+     *   .withCookies(jar)
+     *   .build();
+     * ```
+     */
+    withCookies(jar?: CookieJar): this;
+    /**
+     * Set the undici `Dispatcher` for the entire connection session.
+     *
+     * The same dispatcher is used for:
+     *   • the `/negotiate` HTTP POST
+     *   • the WebSocket upgrade request
+     *   • SSE long-lived GET and send POSTs
+     *   • long-polling GETs, POSTs, and DELETE
+     *
+     * Accepts any `Dispatcher` subclass: `Agent`, `Pool`, `Client`,
+     * `ProxyAgent`, `MockAgent`, etc.
+     *
+     * To combine a custom dispatcher with automatic cookie handling, use
+     * `createCookieAgentClass()` to build a cookie-aware variant of your
+     * dispatcher and pass that here.  Do **not** chain both
+     * `withDispatcher()` and `withCookies()` - they are mutually exclusive
+     * because `withCookies()` creates its own dispatcher internally.
+     *
+     * @example
+     * ```ts
+     * import { ProxyAgent } from 'undici';
+     *
+     * const conn = new HubConnectionBuilder()
+     *   .withUrl('https://example.com/hub')
+     *   .withDispatcher(new ProxyAgent('http://proxy:8080'))
+     *   .build();
+     * ```
+     */
+    withDispatcher(dispatcher: Dispatcher): this;
+    /**
+     * Provide a custom HTTP client implementation.
+     *
+     * By default `HubConnection` uses `DispatchHttpClient` (undici `dispatch`).
+     * Use this to substitute any of the other undici-backed clients, or
+     * to inject a mock for testing.
+     *
+     * @example
+     * ```ts
+     * import { FetchHttpClient } from '@signalr/client';
+     *
+     * const conn = new HubConnectionBuilder()
+     *   .withUrl('https://example.com/hub')
+     *   .withHttpClient(new FetchHttpClient())
+     *   .build();
+     * ```
+     */
+    withHttpClient(httpClient: IHttpClient): this;
+    /**
+     * Set the minimum log level or provide a custom logger.
+     *
+     * @param logLevelOrLogger
+     *   - `LogLevel` number  →  uses the built-in ConsoleLogger
+     *   - `ILogger` object   →  used as-is
+     */
+    configureLogging(logLevelOrLogger: LogLevel | ILogger): this;
+    /**
+     * Enable automatic reconnection on unexpected disconnections.
+     *
+     * @overload  withAutomaticReconnect()
+     *   Uses the built-in delay sequence: 0 ms, 2 s, 10 s, 30 s.
+     *
+     * @overload  withAutomaticReconnect(retryDelays: readonly number[])
+     *   Each element is the wait (ms) before the corresponding retry.
+     *   Reconnection stops after all delays are exhausted.
+     *   Uses `NoInfer<number>` so literals are not widened unexpectedly.
+     *
+     * @overload  withAutomaticReconnect(policy: IRetryPolicy)
+     *   Custom policy.  Return `null` from
+     *   `nextRetryDelayInMilliseconds` to stop retrying.
+     */
+    withAutomaticReconnect(): this;
+    withAutomaticReconnect(retryDelays: readonly NoInfer<number>[]): this;
+    withAutomaticReconnect(policy: IRetryPolicy): this;
+    build(): HubConnection;
+}
+declare class DefaultReconnectPolicy implements IRetryPolicy {
+    #private;
+    constructor(retryDelays?: readonly number[]);
+    nextRetryDelayInMilliseconds(context: RetryContext): number | null;
+}
+
+/**
+ * json-hub-protocol.ts
+ *
+ * Implements the SignalR Hub Protocol over JSON (version 1).
+ *
+ * Wire format: every message is JSON followed by ASCII 0x1e (RECORD_SEPARATOR).
+ * A single transport payload may contain multiple messages.
+ *
+ * Reference:
+ *   https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/HubProtocol.md
+ */
+
+declare const HANDSHAKE_REQUEST$1: string;
+interface HandshakeResponse {
+    readonly error?: string;
+    readonly minorVersion?: number;
+}
+interface HandshakeParseResult {
+    /** Remainder of the input string after the handshake record (may be non-empty). */
+    readonly remainder: string;
+}
+/**
+ * Parse the first record from `data` as the server handshake response.
+ * @throws {Error} if the record separator is missing or the server returned an error.
+ */
+declare function parseHandshakeResponse(data: string): HandshakeParseResult;
+declare class JsonHubProtocol implements IHubProtocol {
+    #private;
+    readonly name: "json";
+    readonly version: 1;
+    readonly transferFormat: 1;
+    parseMessages(input: string | ArrayBuffer, logger: ILogger): HubMessage[];
+    writeMessage(message: HubMessage): string;
+    static invocation(invocationId: InvocationId, target: string, args: readonly unknown[], streamIds?: readonly string[]): InvocationMessage;
+    /**
+     * Fire-and-forget (no `invocationId` → server won't send a Completion).
+     */
+    static send(target: string, args: readonly unknown[], streamIds?: readonly string[]): InvocationMessage;
+    static streamInvocation(invocationId: InvocationId, target: string, args: readonly unknown[], streamIds?: readonly string[]): StreamInvocationMessage;
+    static cancelInvocation(invocationId: InvocationId): CancelInvocationMessage;
+    static streamItem(invocationId: InvocationId, item: unknown): StreamItemMessage;
+    static completion(invocationId: InvocationId, result: unknown, error: string | null): CompletionMessage;
+    static ping(): PingMessage;
+}
+
+/**
+ * msgpack-hub-protocol.ts
+ *
+ * Implements the SignalR Hub Protocol over MessagePack (version 1).
+ *
+ * Wire format
+ * ───────────
+ * • Handshake: JSON text terminated by ASCII 0x1e - identical to the JSON
+ *   protocol, only the "protocol" field changes to "messagepack".
+ * • All subsequent messages: binary MessagePack, each frame prefixed by a
+ *   base-128 VarInt carrying the byte-length of the following MessagePack
+ *   payload.  A single transport payload may contain multiple such frames.
+ *
+ * MessagePack array layout (per message type)
+ * ────────────────────────────────────────────
+ *   Invocation       [1, headers, invocationId|null, target, args, streamIds]
+ *   StreamItem       [2, headers, invocationId, item]
+ *   Completion       [3, headers, invocationId, resultKind, value?]
+ *     resultKind: 1 = error string, 2 = void, 3 = non-void result value
+ *   StreamInvocation [4, headers, invocationId, target, args, streamIds]
+ *   CancelInvocation [5, headers, invocationId]
+ *   Ping             [6]
+ *   Close            [7, error|null, allowReconnect]
+ *
+ * Reference:
+ *   https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/HubProtocol.md
+ */
+
+/**
+ * The JSON-formatted handshake request the client sends once the transport
+ * is open.  The server always responds with JSON ({} on success), regardless
+ * of the chosen hub protocol.
+ */
+declare const HANDSHAKE_REQUEST: string;
+
+declare class MsgpackHubProtocol implements IHubProtocol {
+    #private;
+    readonly name: "messagepack";
+    readonly version: 1;
+    readonly transferFormat: 2;
+    parseMessages(input: string | ArrayBuffer, logger: ILogger): HubMessage[];
+    writeMessage(message: HubMessage): ArrayBuffer;
+    static invocation(invocationId: InvocationId, target: string, args: readonly unknown[], streamIds?: readonly string[]): InvocationMessage;
+    /** Fire-and-forget (no `invocationId`). */
+    static send(target: string, args: readonly unknown[], streamIds?: readonly string[]): InvocationMessage;
+    static streamInvocation(invocationId: InvocationId, target: string, args: readonly unknown[], streamIds?: readonly string[]): StreamInvocationMessage;
+    static cancelInvocation(invocationId: InvocationId): CancelInvocationMessage;
+    static streamItem(invocationId: InvocationId, item: unknown): StreamItemMessage;
+    static completion(invocationId: InvocationId, result: unknown, error: string | null): CompletionMessage;
+    static ping(): PingMessage;
+}
+
+/**
+ * logger.ts
+ *
+ * Built-in ILogger implementations.
+ * ConsoleLogger - writes to console with timestamps and severity labels.
+ * NullLogger     - discards everything (default when no logger is configured).
+ */
+
+declare class ConsoleLogger implements ILogger {
+    #private;
+    constructor(minimumLevel?: LogLevel);
+    log(level: LogLevel, message: string): void;
+}
+declare class NullLogger implements ILogger {
+    /** Singleton - no state, so one instance is enough. */
+    static readonly instance: NullLogger;
+    log(_logLevel: LogLevel, _message: string): void;
+}
+
+/**
+ * errors.ts
+ *
+ * Typed error classes for the SignalR client.  Each has a distinct `name`
+ * so callers can use `instanceof` or switch on `error.name` to distinguish
+ * error categories at runtime.
+ */
+/** Thrown when a hub method invocation fails with a server-side error. */
+declare class HubError extends Error {
+    readonly name: "HubError";
+    constructor(message: string);
+}
+/** Thrown when an in-flight operation is cancelled (e.g. connection closed). */
+declare class AbortError extends Error {
+    readonly name: "AbortError";
+    constructor(message?: string);
+}
+/** Thrown on network-level transport failures. */
+declare class TransportError extends Error {
+    readonly name: "TransportError";
+    readonly statusCode: number | undefined;
+    constructor(message: string, statusCode?: number);
+}
+/** Thrown when the SignalR protocol handshake is rejected by the server. */
+declare class HandshakeError extends Error {
+    readonly name: "HandshakeError";
+    constructor(message: string);
+}
+/** Thrown when no acceptable transport could be negotiated. */
+declare class UnsupportedTransportError extends Error {
+    readonly name: "UnsupportedTransportError";
+    readonly transport: number | null;
+    constructor(message: string, transport: number | null);
+}
+declare function isHubError(e: unknown): e is HubError;
+declare function isAbortError(e: unknown): e is AbortError;
+declare function isTransportError(e: unknown): e is TransportError;
+
+/**
+ * websocket-transport.ts
+ *
+ * SignalR WebSocket transport - rewritten to use undici's built-in
+ * WHATWG-compatible `WebSocket` implementation.
+ *
+ * Why undici WebSocket instead of the hand-rolled RFC 6455 client?
+ * ─────────────────────────────────────────────────────────────────
+ * • undici is the HTTP engine Node.js core ships with (≥ v18).
+ * • Its WebSocket implementation passes the Autobahn test suite.
+ * • It accepts the same `Dispatcher` used by the HTTP clients, so the
+ *   entire SignalR session (negotiate, handshake, upgrade) shares a single
+ *   connection pool / proxy config.
+ * • It supports custom headers on the upgrade request (needed for auth
+ *   and extra headers), which the browser WebSocket API does not.
+ *
+ * undici WebSocket quirks in Node.js
+ * ────────────────────────────────────
+ * • The constructor signature is:
+ *     new WebSocket(url, { headers?, dispatcher?, protocols? })
+ *   The `headers` and `dispatcher` fields are undici extensions not in the
+ *   WHATWG spec.
+ * • `MessageEvent.data` type depends on `ws.binaryType`:
+ *     'arraybuffer' (what we set) → ArrayBuffer
+ *     'blob'                      → Blob
+ *   We set `binaryType = 'arraybuffer'` and convert ArrayBuffer → Buffer on
+ *   receipt.  ('nodebuffer' is a valid undici runtime value but is absent from
+ *   the WHATWG BinaryType union in undici's TypeScript declarations.)
+ * • `CloseEvent.code` / `.reason` behave identically to the browser.
+ */
+
+declare class WebSocketTransport implements ITransport {
+    #private;
+    readonly name: "WebSockets";
+    onreceive: ((data: string | Uint8Array) => void) | null;
+    onclose: ((error?: Error) => void) | null;
+    /**
+     * @param accessTokenFactory  Async factory for Bearer tokens, or null.
+     * @param logger              Logger instance.
+     * @param extraHeaders        Headers forwarded on every upgrade request.
+     * @param dispatcher          Optional undici Dispatcher (Agent/Pool/Client/
+     *                            ProxyAgent).  When omitted, undici's default
+     *                            global agent is used.  Pass the same dispatcher
+     *                            used by your HTTP clients to share the pool.
+     */
+    constructor(accessTokenFactory: (() => Promise<string | null>) | null, logger: ILogger, extraHeaders?: Record<string, string>, dispatcher?: Dispatcher);
+    connect(url: string, _transferFormat: TransferFormat): Promise<void>;
+    send(data: string | Uint8Array): Promise<void>;
+    stop(): Promise<void>;
+}
+
+/**
+ * sse-transport.ts
+ *
+ * SignalR transport using Server-Sent Events (SSE) for receiving and
+ * HTTP POST for sending.
+ *
+ * SSE spec: https://html.spec.whatwg.org/multipage/server-sent-events.html
+ *
+ * Updated to use the new StreamResult shape from http-client.ts:
+ *   result.body   - Node Readable carrying the SSE byte stream
+ *   result.abort  - cancels the in-flight request (replaces req.destroy())
+ */
+
+declare class ServerSentEventsTransport implements ITransport {
+    #private;
+    readonly name: "ServerSentEvents";
+    onreceive: ((data: string | Uint8Array) => void) | null;
+    onclose: ((error?: Error) => void) | null;
+    constructor(httpClient: IHttpClient, accessTokenFactory: (() => Promise<string | null>) | null, logger: ILogger, extraHeaders?: Record<string, string>);
+    connect(url: string, transferFormat: TransferFormat): Promise<void>;
+    send(data: string | Uint8Array): Promise<void>;
+    stop(): Promise<void>;
+}
+
+/**
+ * long-polling-transport.ts
+ *
+ * SignalR Long-Polling transport.
+ * HTTP GET (hangs until data arrives)  →  receive
+ * HTTP POST                            →  send
+ * HTTP DELETE                          →  disconnect
+ *
+ * Updated to depend on IHttpClient rather than the concrete HttpClient class
+ * so any of the five undici-backed client implementations can be injected.
+ */
+
+declare class LongPollingTransport implements ITransport {
+    #private;
+    readonly name: "LongPolling";
+    onreceive: ((data: string | Uint8Array) => void) | null;
+    onclose: ((error?: Error) => void) | null;
+    constructor(httpClient: IHttpClient, accessTokenFactory: (() => Promise<string | null>) | null, logger: ILogger, extraHeaders?: Record<string, string>);
+    connect(url: string, _transferFormat: TransferFormat): Promise<void>;
+    send(data: string | Uint8Array): Promise<void>;
+    stop(): Promise<void>;
+}
+
+/**
+ * ws-client.ts
+ *
+ * From-scratch WebSocket client (RFC 6455) built on Node's built-in `net`
+ * and `tls` modules.  Zero external runtime dependencies.
+ *
+ * Typed EventEmitter via interface declaration merging.
+ *
+ * Emitted events
+ *   'open'             – handshake complete, ready to send/receive
+ *   'message' (string) – UTF-8 text frame received
+ *   'binary'  (Buffer) – binary frame received
+ *   'ping'    (Buffer) – ping frame received (pong sent automatically)
+ *   'pong'    (Buffer) – pong frame received
+ *   'close'            – socket fully closed
+ *   'error'   (Error)  – socket-level error
+ */
+
+declare const enum WebSocketReadyState {
+    Connecting = 0,
+    Open = 1,
+    Closing = 2,
+    Closed = 3
+}
+interface WebSocketClient {
+    on(event: 'open', listener: () => void): this;
+    on(event: 'message', listener: (data: string) => void): this;
+    on(event: 'binary', listener: (data: Buffer) => void): this;
+    on(event: 'ping', listener: (data: Buffer) => void): this;
+    on(event: 'pong', listener: (data: Buffer) => void): this;
+    on(event: 'close', listener: () => void): this;
+    on(event: 'error', listener: (err: Error) => void): this;
+    once(event: 'open', listener: () => void): this;
+    once(event: 'message', listener: (data: string) => void): this;
+    once(event: 'close', listener: () => void): this;
+    once(event: 'error', listener: (err: Error) => void): this;
+    emit(event: 'open'): boolean;
+    emit(event: 'message', data: string): boolean;
+    emit(event: 'binary', data: Buffer): boolean;
+    emit(event: 'ping', data: Buffer): boolean;
+    emit(event: 'pong', data: Buffer): boolean;
+    emit(event: 'close'): boolean;
+    emit(event: 'error', err: Error): boolean;
+    removeAllListeners(event?: string): this;
+}
+declare class WebSocketClient extends EventEmitter {
+    #private;
+    get readyState(): WebSocketReadyState;
+    /**
+     * Open a WebSocket connection.
+     * @param url      ws:// or wss:// URL
+     * @param headers  Extra HTTP headers for the upgrade request
+     */
+    connect(url: string, headers?: Record<string, string>): Promise<void>;
+    /**
+     * Send a text or binary message.
+     * @throws if the socket is not open.
+     */
+    send(data: string | Buffer | Uint8Array): void;
+    /**
+     * Initiate a clean close handshake.
+     * @param code    WebSocket close code (default 1000 = Normal Closure)
+     * @param reason  UTF-8 reason string (max 123 bytes)
+     */
+    close(code?: number, reason?: string): void;
+}
+
+export { AbortError, type AvailableTransport, type CancelInvocationMessage, type CloseMessage, type CompletionMessage, ConsoleLogger, DEFAULT_PING_INTERVAL_IN_MS, DEFAULT_SERVER_TIMEOUT_IN_MS, DEFAULT_TIMEOUT_IN_MS, DefaultReconnectPolicy, DispatchHttpClient, FetchHttpClient, HANDSHAKE_REQUEST$1 as HANDSHAKE_REQUEST, HandshakeError, type HandshakeParseResult, type HandshakeResponse, DispatchHttpClient as HttpClient, type HttpClientOptions, type HttpMethod, type HttpResponse, HttpTransportType, HubConnection, HubConnectionBuilder, type HubConnectionOptions, HubConnectionState, HubError, type HubMessage, type IHttpClient, type IHubProtocol, type ILogger, type IRetryPolicy, type IStreamResult, type IStreamSubscriber, type ISubscription, type ITransport, type InvocationId, type InvocationMessage, JsonHubProtocol, LogLevel, LongPollingTransport, HANDSHAKE_REQUEST as MSGPACK_HANDSHAKE_REQUEST, type MessageHeaders, MessageType, type MessageTypeValue, MsgpackHubProtocol, NEGOTIATE_VERSION, type NegotiateResponse, NullLogger, type PingMessage, PipelineHttpClient, RECORD_SEPARATOR, RequestHttpClient, type RequestOptions, type RetryContext, ServerSentEventsTransport, StreamHttpClient, type StreamInvocationMessage, type StreamItemMessage, type StreamResult, TransferFormat, TransportError, UnsupportedTransportError, type UrlOptions, WebSocketClient, WebSocketReadyState, WebSocketTransport, assertNever, isAbortError, isCancelInvocationMessage, isCloseMessage, isCompletionMessage, isHubError, isInvocationMessage, isPingMessage, isStreamInvocationMessage, isStreamItemMessage, isTransportError, parseHandshakeResponse, toInvocationId };