@exhumer/signalr-client 1.0.2 → 2.0.0

package/dist/index.d.mts

@@ -0,0 +1,913 @@
+import { Readable } from "node:stream";
+import { Dispatcher, Dispatcher as Dispatcher$1 } from "undici";
+import { CookieAgent, cookie } from "@exhumer/undici-cookie-agent";
+import { CookieJar, CookieJar as CookieJar$1 } from "tough-cookie";
+import { EventEmitter } from "node:events";
+
+//#region src/constants.d.ts
+/**
+ * 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;
+//#endregion
+//#region src/http-client.d.ts
+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 | Uint8Array | 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$1;
+  /** Maximum buffered response body size in bytes (default: 32 MiB). */
+  readonly maximumResponseBodySize?: number;
+}
+/**
+ * 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$1;
+  protected readonly maximumResponseBodySize: number;
+  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>;
+}
+//#endregion
+//#region src/messages.d.ts
+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;
+//#endregion
+//#region src/interfaces.d.ts
+/** 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 used by a HubConnection. */
+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;
+}
+/**
+ * A running server-streaming invocation. It supports one subscriber.
+ */
+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>;
+}
+//#endregion
+//#region src/hub-connection.d.ts
+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;
+  /**
+   * Override the SignalR handshake timeout (ms). Defaults to 15 000.
+   * Intended for testing; production code should leave this at the default.
+   */
+  readonly handshakeTimeoutInMilliseconds?: 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;
+  /** Hub wire protocol. Defaults to JSON protocol version 1. */
+  readonly protocol?: IHubProtocol;
+  /** Maximum accepted transport payload size. Defaults to 32 MiB. */
+  readonly maximumReceiveMessageSize?: number;
+  /** Internal: close a builder-created dispatcher when the connection ends. */
+  readonly ownsDispatcher?: boolean;
+}
+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 immediately.
+   * 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) => unknown): void;
+  /**
+   * Remove a previously registered handler, or all handlers for a method.
+   */
+  off(methodName: string, handler?: (...args: unknown[]) => unknown): void;
+  onclose(callback: (error?: Error) => void): void;
+  onreconnecting(callback: (error?: Error) => void): void;
+  onreconnected(callback: (connectionId: string | null) => void): void;
+}
+//#endregion
+//#region src/hub-connection-builder.d.ts
+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;
+  /** ms to wait for the SignalR handshake response (default: 15 000). */
+  readonly handshakeTimeoutInMilliseconds?: number;
+  /** Maximum accepted transport payload size (default: 32 MiB). */
+  readonly maximumReceiveMessageSize?: 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$1): 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;
+  /** Select the hub wire protocol (for example, MessagePack). */
+  withHubProtocol(protocol: IHubProtocol): 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;
+}
+//#endregion
+//#region src/protocols/json-hub-protocol.d.ts
+declare const HANDSHAKE_REQUEST: 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;
+}
+//#endregion
+//#region src/protocols/msgpack-hub-protocol.d.ts
+/**
+ * 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$1: 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;
+}
+//#endregion
+//#region src/logger.d.ts
+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;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * 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;
+//#endregion
+//#region src/transports/websocket-transport.d.ts
+declare class WebSocketTransport implements ITransport {
+  #private;
+  readonly name: "WebSockets";
+  onclose: ((error?: Error) => void) | null;
+  get onreceive(): ((data: string | Uint8Array) => void) | null;
+  set onreceive(handler: ((data: string | Uint8Array) => 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$1);
+  connect(url: string, _transferFormat: TransferFormat): Promise<void>;
+  send(data: string | Uint8Array): Promise<void>;
+  stop(): Promise<void>;
+}
+//#endregion
+//#region src/transports/sse-transport.d.ts
+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>;
+}
+//#endregion
+//#region src/transports/long-polling-transport.d.ts
+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>;
+}
+//#endregion
+//#region src/ws-client.d.ts
+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;
+}
+//#endregion
+export { AbortError, type AvailableTransport, type CancelInvocationMessage, type CloseMessage, type CompletionMessage, ConsoleLogger, CookieAgent, CookieJar, DEFAULT_PING_INTERVAL_IN_MS, DEFAULT_SERVER_TIMEOUT_IN_MS, DEFAULT_TIMEOUT_IN_MS, DefaultReconnectPolicy, DispatchHttpClient, DispatchHttpClient as HttpClient, type Dispatcher, FetchHttpClient, HANDSHAKE_REQUEST, HandshakeError, type HandshakeParseResult, type HandshakeResponse, 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$1 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, cookie, isAbortError, isCancelInvocationMessage, isCloseMessage, isCompletionMessage, isHubError, isInvocationMessage, isPingMessage, isStreamInvocationMessage, isStreamItemMessage, isTransportError, parseHandshakeResponse, toInvocationId };
+//# sourceMappingURL=index.d.mts.map