@exhumer/signalr-client 1.0.2 → 2.0.0

package/dist/index.mjs

@@ -0,0 +1,2901 @@
+import { PassThrough, Readable } from "node:stream";
+import { WebSocket, fetch, getGlobalDispatcher, pipeline, request, stream } from "undici";
+import { CookieAgent, CookieAgent as CookieAgent$1, cookie } from "@exhumer/undici-cookie-agent";
+import { CookieJar, CookieJar as CookieJar$1 } from "tough-cookie";
+import { decode, encode } from "@msgpack/msgpack";
+import * as net from "node:net";
+import * as tls from "node:tls";
+import * as crypto from "node:crypto";
+import { EventEmitter } from "node:events";
+//#region src/http-client.ts
+/**
+* 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.
+*/
+/**
+* Serialise the `body` option to a `Buffer` (or `null` for bodyless requests).
+* Returns the buffer AND the inferred Content-Type so callers can set the
+* header automatically.
+*/
+function prepareBody(body) {
+	if (body == null) return {
+		buf: null,
+		inferredContentType: null
+	};
+	if (body instanceof Uint8Array) return {
+		buf: Buffer.from(body.buffer, body.byteOffset, body.byteLength),
+		inferredContentType: null
+	};
+	if (typeof body === "string") return {
+		buf: Buffer.from(body, "utf8"),
+		inferredContentType: null
+	};
+	return {
+		buf: Buffer.from(JSON.stringify(body), "utf8"),
+		inferredContentType: "application/json"
+	};
+}
+/**
+* Merge session-level default headers with per-request headers.
+* Per-request headers win on collision.
+* Injects Content-Length and Content-Type when a body is present.
+*/
+function buildHeaders(defaults, overrides, body, inferredContentType) {
+	const merged = {
+		...defaults,
+		...overrides ?? {}
+	};
+	if (body !== null) {
+		merged["content-length"] = String(body.length);
+		if (!merged["content-type"] && inferredContentType !== null) merged["content-type"] = inferredContentType;
+	}
+	return merged;
+}
+/**
+* Normalise an undici response headers object
+* (`Record<string, string | string[]>`) to our `HttpResponse.headers` shape
+* (`Record<string, string | string[] | undefined>`).
+*/
+function normaliseHeaders(h) {
+	return h;
+}
+function assertBodySize(size, maximum) {
+	if (size > maximum) throw new Error(`HTTP response body exceeds the ${maximum} byte limit.`);
+}
+/**
+* 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()`.
+*/
+var BaseUndiciClient = class {
+	/** Default headers merged into every outgoing request. */
+	defaultHeaders;
+	/** Session-level request timeout in milliseconds. */
+	defaultTimeout;
+	/**
+	* Shared undici Dispatcher.  May be an Agent, Pool, Client, ProxyAgent, etc.
+	* Defaults to undici's process-global agent when not specified.
+	*/
+	dispatcher;
+	maximumResponseBodySize;
+	constructor(options = {}) {
+		this.defaultHeaders = options.headers ?? {};
+		this.defaultTimeout = options.timeout ?? 3e4;
+		this.dispatcher = options.dispatcher ?? getGlobalDispatcher();
+		this.maximumResponseBodySize = options.maximumResponseBodySize ?? 32 * 1024 * 1024;
+	}
+	get(url, options) {
+		return this.request("GET", url, options);
+	}
+	post(url, options) {
+		return this.request("POST", url, options);
+	}
+	delete(url, options) {
+		return this.request("DELETE", url, options);
+	}
+};
+/**
+* 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.
+*
+*/
+var RequestHttpClient = class 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`.
+	*/
+	async request(method, url, options = {}) {
+		const { buf, inferredContentType } = prepareBody(options.body);
+		const headers = buildHeaders(this.defaultHeaders, options.headers, buf, inferredContentType);
+		const timeout = options.timeout ?? this.defaultTimeout;
+		const { statusCode, headers: respHeaders, body } = await request(url, {
+			method,
+			headers,
+			...buf !== null && { body: buf },
+			headersTimeout: timeout,
+			bodyTimeout: timeout,
+			dispatcher: this.dispatcher
+		});
+		const text = await body.text();
+		assertBodySize(Buffer.byteLength(text), this.maximumResponseBodySize);
+		return {
+			status: statusCode,
+			headers: normaliseHeaders(respHeaders),
+			body: text
+		};
+	}
+	/**
+	* 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.
+	*/
+	async stream(method, url, options = {}) {
+		const { buf, inferredContentType } = prepareBody(options.body);
+		const { statusCode, headers: respHeaders, body } = await request(url, {
+			method,
+			headers: buildHeaders(this.defaultHeaders, options.headers, buf, inferredContentType),
+			...buf !== null && { body: buf },
+			headersTimeout: options.timeout ?? this.defaultTimeout,
+			dispatcher: this.dispatcher
+		});
+		return {
+			statusCode,
+			headers: normaliseHeaders(respHeaders),
+			body,
+			abort: () => body.destroy()
+		};
+	}
+};
+/**
+* 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+).
+*/
+var FetchHttpClient = class extends BaseUndiciClient {
+	async request(method, url, options = {}) {
+		const { buf, inferredContentType } = prepareBody(options.body);
+		const headers = buildHeaders(this.defaultHeaders, options.headers, buf, inferredContentType);
+		const ac = new AbortController();
+		const timeout = options.timeout ?? this.defaultTimeout;
+		const timer = timeout > 0 ? setTimeout(() => ac.abort(/* @__PURE__ */ new Error(`HTTP request timed out after ${timeout} ms`)), timeout) : null;
+		try {
+			const res = await fetch(url, {
+				method,
+				headers,
+				...buf !== null && { body: buf },
+				signal: ac.signal,
+				dispatcher: this.dispatcher
+			});
+			const text = await res.text();
+			assertBodySize(Buffer.byteLength(text), this.maximumResponseBodySize);
+			if (timer !== null) clearTimeout(timer);
+			const respHeaders = {};
+			res.headers.forEach((value, key) => {
+				respHeaders[key] = value;
+			});
+			return {
+				status: res.status,
+				headers: respHeaders,
+				body: text
+			};
+		} catch (err) {
+			if (timer !== null) clearTimeout(timer);
+			throw err;
+		}
+	}
+	async stream(method, url, options = {}) {
+		const { buf, inferredContentType } = prepareBody(options.body);
+		const headers = buildHeaders(this.defaultHeaders, options.headers, buf, inferredContentType);
+		const ac = new AbortController();
+		const res = await fetch(url, {
+			method,
+			headers,
+			...buf !== null && { body: buf },
+			signal: ac.signal,
+			dispatcher: this.dispatcher
+		});
+		const body = Readable.fromWeb(res.body);
+		const respHeaders = {};
+		res.headers.forEach((value, key) => {
+			respHeaders[key] = value;
+		});
+		return {
+			statusCode: res.status,
+			headers: respHeaders,
+			body,
+			abort: () => {
+				ac.abort();
+				body.destroy();
+			}
+		};
+	}
+};
+/**
+* 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`.
+*/
+var StreamHttpClient = class extends BaseUndiciClient {
+	request(method, url, options = {}) {
+		const { buf, inferredContentType } = prepareBody(options.body);
+		const headers = buildHeaders(this.defaultHeaders, options.headers, buf, inferredContentType);
+		const timeout = options.timeout ?? this.defaultTimeout;
+		let statusCode = 0;
+		let respHeaders = {};
+		const chunks = [];
+		return stream(url, {
+			method,
+			headers,
+			...buf !== null && { body: buf },
+			headersTimeout: timeout,
+			bodyTimeout: timeout,
+			dispatcher: this.dispatcher
+		}, ({ statusCode: sc, headers: h }) => {
+			statusCode = sc;
+			respHeaders = h;
+			const sink = new PassThrough();
+			sink.on("data", (chunk) => chunks.push(chunk));
+			return sink;
+		}).then(() => ({
+			status: statusCode,
+			headers: normaliseHeaders(respHeaders),
+			body: (() => {
+				const body = Buffer.concat(chunks);
+				assertBodySize(body.length, this.maximumResponseBodySize);
+				return body.toString("utf8");
+			})()
+		}));
+	}
+	stream(method, url, options = {}) {
+		const { buf, inferredContentType } = prepareBody(options.body);
+		const headers = buildHeaders(this.defaultHeaders, options.headers, buf, inferredContentType);
+		return new Promise((resolve, reject) => {
+			const pt = new PassThrough();
+			stream(url, {
+				method,
+				headers,
+				...buf !== null && { body: buf },
+				headersTimeout: options.timeout ?? this.defaultTimeout,
+				dispatcher: this.dispatcher
+			}, ({ statusCode, headers: h }) => {
+				resolve({
+					statusCode,
+					headers: normaliseHeaders(h),
+					body: pt,
+					abort: () => pt.destroy()
+				});
+				return pt;
+			}).catch((err) => {
+				pt.destroy();
+				reject(err);
+			});
+		});
+	}
+};
+/**
+* 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.
+*/
+var PipelineHttpClient = class extends BaseUndiciClient {
+	request(method, url, options = {}) {
+		const { buf, inferredContentType } = prepareBody(options.body);
+		const headers = buildHeaders(this.defaultHeaders, options.headers, buf, inferredContentType);
+		const timeout = options.timeout ?? this.defaultTimeout;
+		return new Promise((resolve, reject) => {
+			let statusCode = 0;
+			let respHeaders = {};
+			const chunks = [];
+			const duplex = pipeline(url, {
+				method,
+				headers,
+				...buf !== null && { body: buf },
+				headersTimeout: timeout,
+				bodyTimeout: timeout,
+				dispatcher: this.dispatcher
+			}, ({ statusCode: sc, headers: h, body }) => {
+				statusCode = sc;
+				respHeaders = h;
+				return body;
+			});
+			duplex.on("data", (chunk) => chunks.push(chunk));
+			duplex.on("end", () => resolve({
+				status: statusCode,
+				headers: normaliseHeaders(respHeaders),
+				body: (() => {
+					const body = Buffer.concat(chunks);
+					assertBodySize(body.length, this.maximumResponseBodySize);
+					return body.toString("utf8");
+				})()
+			}));
+			duplex.on("error", reject);
+			if (buf !== null) duplex.write(buf);
+			duplex.end();
+		});
+	}
+	stream(method, url, options = {}) {
+		const { buf, inferredContentType } = prepareBody(options.body);
+		const headers = buildHeaders(this.defaultHeaders, options.headers, buf, inferredContentType);
+		return new Promise((resolve, reject) => {
+			let resolved = false;
+			let duplex;
+			duplex = pipeline(url, {
+				method,
+				headers,
+				...buf !== null && { body: buf },
+				headersTimeout: options.timeout ?? this.defaultTimeout,
+				dispatcher: this.dispatcher
+			}, ({ statusCode, headers: h, body }) => {
+				if (!resolved) {
+					resolved = true;
+					resolve({
+						statusCode,
+						headers: normaliseHeaders(h),
+						body: duplex,
+						abort: () => duplex.destroy()
+					});
+				}
+				return body;
+			});
+			duplex.on("error", (err) => {
+				if (!resolved) reject(err);
+			});
+			if (buf !== null) duplex.write(buf);
+			duplex.end();
+		});
+	}
+};
+/**
+* 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.
+*/
+var DispatchHttpClient = class extends BaseUndiciClient {
+	request(method, url, options = {}) {
+		const { buf, inferredContentType } = prepareBody(options.body);
+		const headers = buildHeaders(this.defaultHeaders, options.headers, buf, inferredContentType);
+		const parsed = new URL(url);
+		const timeout = options.timeout ?? this.defaultTimeout;
+		return new Promise((resolve, reject) => {
+			let statusCode = 0;
+			let respHeaders = {};
+			const chunks = [];
+			let responseSize = 0;
+			let controller = null;
+			let settled = false;
+			let timer = null;
+			if (timeout > 0) timer = setTimeout(() => {
+				/* istanbul ignore next -- timer is cleared on every settled path */
+				if (settled) return;
+				settled = true;
+				const error = /* @__PURE__ */ new Error(`HTTP request timed out after ${timeout} ms`);
+				controller?.abort(error);
+				reject(error);
+			}, timeout);
+			const clearTimer = () => {
+				if (timer !== null) {
+					clearTimeout(timer);
+					timer = null;
+				}
+			};
+			this.dispatcher.dispatch({
+				origin: parsed.origin,
+				path: parsed.pathname + parsed.search,
+				method,
+				headers,
+				...buf !== null && { body: buf }
+			}, {
+				onRequestStart: (ctrl, _context) => {
+					controller = ctrl;
+				},
+				onResponseError: (_controller, err) => {
+					clearTimer();
+					/* istanbul ignore next -- undici does not end after reporting an error */
+					if (settled) return;
+					settled = true;
+					reject(err);
+				},
+				onResponseStart: (_controller, sc, headers) => {
+					statusCode = sc;
+					respHeaders = headers;
+				},
+				onResponseData: (_controller, chunk) => {
+					chunks.push(Buffer.from(chunk));
+					responseSize += chunk.length;
+					if (responseSize > this.maximumResponseBodySize) _controller.abort(/* @__PURE__ */ new Error(`HTTP response body exceeds the ${this.maximumResponseBodySize} byte limit.`));
+				},
+				onResponseEnd: (_controller, _trailers) => {
+					clearTimer();
+					/* istanbul ignore next -- undici does not end after reporting an error */
+					if (settled) return;
+					settled = true;
+					resolve({
+						status: statusCode,
+						headers: respHeaders,
+						body: Buffer.concat(chunks).toString("utf8")
+					});
+				}
+			});
+		});
+	}
+	stream(method, url, options = {}) {
+		const { buf, inferredContentType } = prepareBody(options.body);
+		const headers = buildHeaders(this.defaultHeaders, options.headers, buf, inferredContentType);
+		const parsed = new URL(url);
+		return new Promise((resolve, reject) => {
+			let resolved = false;
+			const pt = new PassThrough();
+			let controller = null;
+			this.dispatcher.dispatch({
+				origin: parsed.origin,
+				path: parsed.pathname + parsed.search,
+				method,
+				headers,
+				...buf !== null && { body: buf },
+				headersTimeout: options.timeout ?? this.defaultTimeout
+			}, {
+				onRequestStart: (ctrl, _context) => {
+					controller = ctrl;
+				},
+				onResponseError: (_ctrl, err) => {
+					if (!resolved) {
+						resolved = true;
+						pt.destroy();
+						reject(err);
+					} else pt.destroy(err);
+				},
+				onResponseStart: (_ctrl, statusCode, headers) => {
+					if (!resolved) {
+						resolved = true;
+						resolve({
+							statusCode,
+							headers,
+							body: pt,
+							abort: () => {
+								controller?.abort(/* @__PURE__ */ new Error("Stream aborted"));
+								pt.destroy();
+							}
+						});
+					}
+				},
+				onResponseData: (_ctrl, chunk) => {
+					if (!pt.write(chunk)) {
+						controller?.pause();
+						pt.once("drain", () => controller?.resume());
+					}
+				},
+				onResponseEnd: (_ctrl, _trailers) => {
+					pt.end();
+				}
+			});
+		});
+	}
+};
+//#endregion
+//#region src/constants.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.
+*/
+const MessageType = Object.freeze({
+	Invocation: 1,
+	StreamItem: 2,
+	Completion: 3,
+	StreamInvocation: 4,
+	CancelInvocation: 5,
+	Ping: 6,
+	Close: 7
+});
+const HubConnectionState = Object.freeze({
+	Disconnected: "Disconnected",
+	Connecting: "Connecting",
+	Connected: "Connected",
+	Disconnecting: "Disconnecting",
+	Reconnecting: "Reconnecting"
+});
+const LogLevel = {
+	Trace: 0,
+	Debug: 1,
+	Information: 2,
+	Warning: 3,
+	Error: 4,
+	Critical: 5,
+	None: 6
+};
+const HttpTransportType = {
+	None: 0,
+	WebSockets: 1,
+	ServerSentEvents: 2,
+	LongPolling: 4
+};
+const TransferFormat = {
+	Text: 1,
+	Binary: 2
+};
+/** ASCII 30 - the byte that terminates every SignalR JSON message. */
+const RECORD_SEPARATOR = "";
+/** Negotiate version we advertise to the server. */
+const NEGOTIATE_VERSION = 1;
+const DEFAULT_TIMEOUT_IN_MS = 3e4;
+const DEFAULT_PING_INTERVAL_IN_MS = 15e3;
+const DEFAULT_SERVER_TIMEOUT_IN_MS = 3e4;
+//#endregion
+//#region src/messages.ts
+/** Cast a plain string to an InvocationId (only used inside the library). */
+function toInvocationId(s) {
+	return s;
+}
+/**
+* Asserts a code path is unreachable at compile time.
+* Use at the `default` branch of a `switch` over `HubMessage['type']`.
+*/
+function assertNever(_x, label) {
+	throw new Error(`Unexpected value${label ? ` for ${label}` : ""}: ${JSON.stringify(_x)}`);
+}
+function isInvocationMessage(msg) {
+	return msg.type === 1;
+}
+function isStreamItemMessage(msg) {
+	return msg.type === 2;
+}
+function isCompletionMessage(msg) {
+	return msg.type === 3;
+}
+function isStreamInvocationMessage(msg) {
+	return msg.type === 4;
+}
+function isCancelInvocationMessage(msg) {
+	return msg.type === 5;
+}
+function isPingMessage(msg) {
+	return msg.type === 6;
+}
+function isCloseMessage(msg) {
+	return msg.type === 7;
+}
+//#endregion
+//#region src/protocols/json-hub-protocol.ts
+/**
+* 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
+*/
+const HANDSHAKE_REQUEST = JSON.stringify({
+	protocol: "json",
+	version: 1
+}) + "";
+/**
+* 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.
+*/
+function parseHandshakeResponse(data) {
+	const idx = data.indexOf("");
+	if (idx === -1) throw new Error("Handshake response is missing the record separator.");
+	const raw = data.slice(0, idx);
+	const response = JSON.parse(raw);
+	if (response.error) throw new Error(`Server rejected the handshake with the error: "${response.error}"`);
+	return { remainder: data.slice(idx + 1) };
+}
+var JsonHubProtocol = class {
+	name = "json";
+	version = 1;
+	transferFormat = TransferFormat.Text;
+	parseMessages(input, logger) {
+		const text = typeof input === "string" ? input : new TextDecoder().decode(input);
+		if (!text) return [];
+		const messages = [];
+		const parts = text.split("");
+		for (const part of parts) {
+			const trimmed = part.trim();
+			if (!trimmed) continue;
+			let raw;
+			try {
+				raw = JSON.parse(trimmed);
+			} catch (e) {
+				throw new Error(`Error parsing message: ${e.message}. Raw value: "${trimmed}"`);
+			}
+			const msg = this.#coerce(raw);
+			if (msg !== null) messages.push(msg);
+			else logger.log(3, `Ignoring message with unknown type ${String(raw.type)}.`);
+		}
+		return messages;
+	}
+	writeMessage(message) {
+		return JSON.stringify(message) + "";
+	}
+	/**
+	* Validate and narrow a raw parsed object into a typed `HubMessage`.
+	* Returns `null` for unknown types (not an error - new protocol versions
+	* may add types we don't know about).
+	*/
+	#coerce(raw) {
+		const type = raw.type;
+		if (typeof type !== "number") throw new Error(`Invalid message: 'type' must be a number, got ${JSON.stringify(type)}.`);
+		switch (type) {
+			case MessageType.Invocation: return this.#coerceInvocation(raw);
+			case MessageType.StreamItem: return this.#coerceStreamItem(raw);
+			case MessageType.Completion: return this.#coerceCompletion(raw);
+			case MessageType.StreamInvocation: return this.#coerceStreamInvocation(raw);
+			case MessageType.CancelInvocation: return this.#coerceCancelInvocation(raw);
+			case MessageType.Ping: return this.#coercePing();
+			case MessageType.Close: return this.#coerceClose(raw);
+			default: return null;
+		}
+	}
+	#coerceInvocation(raw) {
+		if (typeof raw.target !== "string") throw new Error("Invalid Invocation message: 'target' must be a string.");
+		if (!Array.isArray(raw.arguments)) throw new Error("Invalid Invocation message: 'arguments' must be an array.");
+		return {
+			type: MessageType.Invocation,
+			target: raw.target,
+			arguments: raw.arguments,
+			...raw.invocationId != null && { invocationId: parseInvocationId$1(raw.invocationId) },
+			...raw.streamIds != null && { streamIds: parseStreamIds$1(raw.streamIds) },
+			...raw.headers != null && { headers: parseHeaders$1(raw.headers) }
+		};
+	}
+	#coerceStreamItem(raw) {
+		if (raw.invocationId == null) throw new Error("Invalid StreamItem message: 'invocationId' is required.");
+		return {
+			type: MessageType.StreamItem,
+			invocationId: parseInvocationId$1(raw.invocationId),
+			item: raw.item,
+			...raw.headers != null && { headers: parseHeaders$1(raw.headers) }
+		};
+	}
+	#coerceCompletion(raw) {
+		if (raw.invocationId == null) throw new Error("Invalid Completion message: 'invocationId' is required.");
+		const hasResult = Object.prototype.hasOwnProperty.call(raw, "result");
+		if (raw.error != null && hasResult) throw new Error("Invalid Completion message: 'error' and 'result' are mutually exclusive.");
+		return {
+			type: MessageType.Completion,
+			invocationId: parseInvocationId$1(raw.invocationId),
+			...raw.error != null && { error: String(raw.error) },
+			...hasResult && { result: raw.result },
+			...raw.headers != null && { headers: parseHeaders$1(raw.headers) }
+		};
+	}
+	#coerceStreamInvocation(raw) {
+		if (raw.invocationId == null) throw new Error("Invalid StreamInvocation message: 'invocationId' is required.");
+		if (typeof raw.target !== "string") throw new Error("Invalid StreamInvocation message: 'target' must be a string.");
+		if (!Array.isArray(raw.arguments)) throw new Error("Invalid StreamInvocation message: 'arguments' must be an array.");
+		return {
+			type: MessageType.StreamInvocation,
+			invocationId: parseInvocationId$1(raw.invocationId),
+			target: raw.target,
+			arguments: raw.arguments,
+			...raw.streamIds != null && { streamIds: parseStreamIds$1(raw.streamIds) },
+			...raw.headers != null && { headers: parseHeaders$1(raw.headers) }
+		};
+	}
+	#coerceCancelInvocation(raw) {
+		if (raw.invocationId == null) throw new Error("Invalid CancelInvocation message: 'invocationId' is required.");
+		return {
+			type: MessageType.CancelInvocation,
+			invocationId: parseInvocationId$1(raw.invocationId),
+			...raw.headers != null && { headers: parseHeaders$1(raw.headers) }
+		};
+	}
+	#coercePing() {
+		return { type: MessageType.Ping };
+	}
+	#coerceClose(raw) {
+		if (raw.allowReconnect != null && typeof raw.allowReconnect !== "boolean") throw new Error("Invalid Close message: 'allowReconnect' must be a boolean.");
+		return {
+			type: MessageType.Close,
+			...raw.error != null && { error: String(raw.error) },
+			...raw.allowReconnect != null && { allowReconnect: raw.allowReconnect },
+			...raw.headers != null && { headers: parseHeaders$1(raw.headers) }
+		};
+	}
+	static invocation(invocationId, target, args, streamIds) {
+		return {
+			type: MessageType.Invocation,
+			invocationId,
+			target,
+			arguments: args,
+			...streamIds != null && streamIds.length > 0 ? { streamIds } : {}
+		};
+	}
+	/**
+	* Fire-and-forget (no `invocationId` → server won't send a Completion).
+	*/
+	static send(target, args, streamIds) {
+		return {
+			type: MessageType.Invocation,
+			target,
+			arguments: args,
+			...streamIds != null && streamIds.length > 0 ? { streamIds } : {}
+		};
+	}
+	static streamInvocation(invocationId, target, args, streamIds) {
+		return {
+			type: MessageType.StreamInvocation,
+			invocationId,
+			target,
+			arguments: args,
+			...streamIds != null && streamIds.length > 0 ? { streamIds } : {}
+		};
+	}
+	static cancelInvocation(invocationId) {
+		return {
+			type: MessageType.CancelInvocation,
+			invocationId
+		};
+	}
+	static streamItem(invocationId, item) {
+		return {
+			type: MessageType.StreamItem,
+			invocationId,
+			item
+		};
+	}
+	static completion(invocationId, result, error) {
+		return {
+			type: MessageType.Completion,
+			invocationId,
+			...error != null && { error },
+			...result != null && { result }
+		};
+	}
+	static ping() {
+		return { type: MessageType.Ping };
+	}
+};
+function parseInvocationId$1(value) {
+	if (typeof value !== "string") throw new Error("Invalid message: 'invocationId' must be a string.");
+	return toInvocationId(value);
+}
+function parseStreamIds$1(value) {
+	if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) throw new Error("Invalid message: 'streamIds' must be an array of strings.");
+	return value;
+}
+function parseHeaders$1(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value) || !Object.values(value).every((entry) => typeof entry === "string")) throw new Error("Invalid message: 'headers' must be an object containing string values.");
+	return value;
+}
+Object.freeze({
+	Connecting: 0,
+	Open: 1,
+	Closing: 2,
+	Closed: 3
+});
+var WebSocketTransport = class {
+	name = "WebSockets";
+	#accessTokenFactory;
+	#logger;
+	#extraHeaders;
+	#dispatcher;
+	#ws = null;
+	#onreceive = null;
+	#pendingMessages = [];
+	onclose = null;
+	get onreceive() {
+		return this.#onreceive;
+	}
+	set onreceive(handler) {
+		this.#onreceive = handler;
+		/* istanbul ignore else -- HubConnection installs a receiver after connect */
+		if (handler) {
+			const pending = this.#pendingMessages;
+			this.#pendingMessages = [];
+			for (const message of pending)
+ /* istanbul ignore next -- requires a server frame in the connect/onreceive microtask gap */
+			handler(message);
+		}
+	}
+	/**
+	* @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, logger, extraHeaders = {}, dispatcher) {
+		this.#accessTokenFactory = accessTokenFactory;
+		this.#logger = logger;
+		this.#extraHeaders = extraHeaders;
+		this.#dispatcher = dispatcher;
+	}
+	async connect(url, _transferFormat) {
+		this.#logger.log(LogLevel.Trace, `(WebSockets transport) Connecting to ${url}.`);
+		const headers = { ...this.#extraHeaders };
+		if (this.#accessTokenFactory) {
+			const token = await this.#accessTokenFactory();
+			if (token) headers["Authorization"] = `Bearer ${token}`;
+		}
+		const ws = new WebSocket(url.replace(/^http/, "ws"), {
+			headers,
+			...this.#dispatcher !== void 0 && { dispatcher: this.#dispatcher }
+		});
+		this.#ws = ws;
+		ws.binaryType = "arraybuffer";
+		ws.addEventListener("message", (event) => {
+			const data = event.data;
+			const message = typeof data === "string" ? data : Buffer.from(data);
+			this.#logger.log(LogLevel.Trace, typeof message === "string" ? `(WebSockets transport) Received text (${message.length} chars).` : `(WebSockets transport) Received binary (${message.length} bytes).`);
+			if (this.#onreceive) this.#onreceive(message);
+			else this.#pendingMessages.push(message);
+		});
+		await new Promise((resolve, reject) => {
+			const cleanup = () => {
+				ws.removeEventListener("open", onOpen);
+				ws.removeEventListener("error", onError);
+			};
+			const onOpen = () => {
+				cleanup();
+				this.#logger.log(LogLevel.Information, "(WebSockets transport) Connected.");
+				resolve();
+			};
+			const onError = (event) => {
+				cleanup();
+				const e = event;
+				let err;
+				if (e.error instanceof Error) err = e.error.message ? e.error : e.error.cause instanceof Error ? e.error.cause : /* @__PURE__ */ new Error("WebSocket connection failed");
+				else err = new Error(String(e.message ?? "WebSocket error"));
+				this.#logger.log(LogLevel.Error, `(WebSockets transport) Error during connect: ${err.message}`);
+				this.#ws = null;
+				ws.close();
+				reject(err);
+			};
+			ws.addEventListener("open", onOpen);
+			ws.addEventListener("error", onError);
+		});
+		ws.addEventListener("close", (event) => {
+			const closeEvent = event;
+			this.#logger.log(LogLevel.Information, `(WebSockets transport) Socket closed (code=${closeEvent.code}).`);
+			if (this.#ws !== null) {
+				this.#ws = null;
+				this.onclose?.();
+			}
+		});
+		ws.addEventListener("error", (event) => {
+			if (ws.readyState !== WebSocket.CONNECTING) {
+				const e = event;
+				const err = e.error instanceof Error ? e.error : new Error(String(e.message ?? "WebSocket error"));
+				this.#logger.log(LogLevel.Error, `(WebSockets transport) Error: ${err.message}`);
+				if (this.#ws !== null) {
+					this.#ws = null;
+					this.onclose?.(err);
+				}
+			}
+		});
+	}
+	send(data) {
+		if (!this.#ws || this.#ws.readyState !== WebSocket.OPEN) return Promise.reject(/* @__PURE__ */ new Error("WebSocket is not open."));
+		try {
+			this.#ws.send(data);
+			return Promise.resolve();
+		} catch (err) {
+			return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+		}
+	}
+	stop() {
+		if (this.#ws) {
+			const ws = this.#ws;
+			this.#ws = null;
+			ws.close(1e3, "Normal closure");
+		}
+		return Promise.resolve();
+	}
+};
+//#endregion
+//#region src/transports/sse-transport.ts
+var ServerSentEventsTransport = class {
+	name = "ServerSentEvents";
+	#httpClient;
+	#accessTokenFactory;
+	#logger;
+	#extraHeaders;
+	#url = null;
+	#abort = null;
+	#sseBuffer = "";
+	onreceive = null;
+	onclose = null;
+	constructor(httpClient, accessTokenFactory, logger, extraHeaders = {}) {
+		this.#httpClient = httpClient;
+		this.#accessTokenFactory = accessTokenFactory;
+		this.#logger = logger;
+		this.#extraHeaders = extraHeaders;
+	}
+	async connect(url, transferFormat) {
+		if (transferFormat === TransferFormat.Binary) throw new Error("The Server-Sent Events transport only supports the Text transfer format.");
+		this.#logger.log(LogLevel.Trace, `(SSE transport) Connecting to ${url}.`);
+		this.#url = url;
+		const headers = {
+			Accept: "text/event-stream",
+			...this.#extraHeaders
+		};
+		if (this.#accessTokenFactory) {
+			const token = await this.#accessTokenFactory();
+			if (token) headers["Authorization"] = `Bearer ${token}`;
+		}
+		const result = await this.#httpClient.stream("GET", url, { headers });
+		if (result.statusCode !== 200) {
+			result.body.on("error", () => {});
+			result.abort();
+			throw new Error(`Unexpected status code ${result.statusCode} from SSE endpoint.`);
+		}
+		this.#abort = result.abort;
+		result.body.setEncoding("utf8");
+		result.body.on("data", (chunk) => this.#onData(chunk));
+		result.body.on("end", () => {
+			this.#logger.log(LogLevel.Information, "(SSE transport) EventSource closed.");
+			this.#abort = null;
+			this.onclose?.();
+		});
+		result.body.on("error", (err) => {
+			this.#logger.log(LogLevel.Error, `(SSE transport) Stream error: ${err.message}`);
+			this.#abort = null;
+			this.onclose?.(err);
+		});
+		this.#logger.log(LogLevel.Information, "(SSE transport) Connected.");
+	}
+	async send(data) {
+		if (!this.#url) throw new Error("SSE transport is not connected.");
+		const headers = {
+			"Content-Type": typeof data === "string" ? "text/plain;charset=UTF-8" : "application/octet-stream",
+			...this.#extraHeaders
+		};
+		if (this.#accessTokenFactory) {
+			const token = await this.#accessTokenFactory();
+			if (token) headers["Authorization"] = `Bearer ${token}`;
+		}
+		const result = await this.#httpClient.post(this.#url, {
+			headers,
+			body: data
+		});
+		if (result.status < 200 || result.status >= 300) throw new Error(`SSE send failed with status ${result.status}.`);
+	}
+	stop() {
+		if (this.#abort) {
+			this.#abort();
+			this.#abort = null;
+		}
+		return Promise.resolve();
+	}
+	#onData(chunk) {
+		this.#sseBuffer += chunk;
+		let boundary;
+		while ((boundary = findEventBoundary(this.#sseBuffer)) !== -1) {
+			const block = this.#sseBuffer.slice(0, boundary);
+			this.#sseBuffer = this.#sseBuffer.slice(boundary).replace(/^[\r\n]+/, "");
+			this.#dispatchEvent(block);
+		}
+	}
+	#dispatchEvent(block) {
+		const lines = block.split(/\r?\n/);
+		const dataParts = [];
+		for (const line of lines) if (line.startsWith("data:")) dataParts.push(line.slice(5).replace(/^ /, ""));
+		if (dataParts.length === 0) return;
+		const message = dataParts.join("\n");
+		this.#logger.log(LogLevel.Trace, `(SSE transport) Received data: ${message}`);
+		this.onreceive?.(message);
+	}
+};
+function findEventBoundary(str) {
+	const i1 = str.indexOf("\n\n");
+	const i2 = str.indexOf("\r\n\r\n");
+	if (i1 === -1 && i2 === -1) return -1;
+	if (i1 === -1) return i2 + 4;
+	if (i2 === -1) return i1 + 2;
+	return Math.min(i1 + 2, i2 + 4);
+}
+//#endregion
+//#region src/transports/long-polling-transport.ts
+/** How long a single poll GET can hang before we issue a new one. */
+const POLL_TIMEOUT_MS = 1e5;
+var LongPollingTransport = class {
+	name = "LongPolling";
+	#httpClient;
+	#accessTokenFactory;
+	#logger;
+	#extraHeaders;
+	#url = null;
+	#running = false;
+	#pollImmediate = null;
+	#activeAbort = null;
+	#transferFormat = TransferFormat.Text;
+	onreceive = null;
+	onclose = null;
+	constructor(httpClient, accessTokenFactory, logger, extraHeaders = {}) {
+		this.#httpClient = httpClient;
+		this.#accessTokenFactory = accessTokenFactory;
+		this.#logger = logger;
+		this.#extraHeaders = extraHeaders;
+	}
+	async connect(url, transferFormat) {
+		this.#logger.log(LogLevel.Trace, `(LongPolling transport) Connecting to ${url}.`);
+		this.#url = url;
+		this.#running = true;
+		this.#transferFormat = transferFormat;
+		await this.#poll(url, true);
+		this.#schedulePoll();
+		this.#logger.log(LogLevel.Information, "(LongPolling transport) Connected.");
+	}
+	async send(data) {
+		if (!this.#running || !this.#url) throw new Error("LongPolling transport is not connected.");
+		const headers = await this.#buildHeaders({ "Content-Type": typeof data === "string" ? "text/plain;charset=UTF-8" : "application/octet-stream" });
+		const result = await this.#httpClient.post(this.#url, {
+			headers,
+			body: data
+		});
+		if (result.status < 200 || result.status >= 300) throw new Error(`Long polling send failed with status ${result.status}.`);
+	}
+	async stop() {
+		this.#running = false;
+		if (this.#pollImmediate !== null) {
+			clearImmediate(this.#pollImmediate);
+			this.#pollImmediate = null;
+		}
+		this.#activeAbort?.();
+		this.#activeAbort = null;
+		if (this.#url) try {
+			const headers = await this.#buildHeaders();
+			await this.#httpClient.delete(this.#url, { headers });
+		} catch (e) {
+			this.#logger.log(LogLevel.Warning, `(LongPolling transport) Error sending DELETE: ${e.message}`);
+		}
+	}
+	#schedulePoll() {
+		if (!this.#running) return;
+		this.#pollImmediate = setImmediate(() => void this.#pollLoop());
+	}
+	async #pollLoop() {
+		/* istanbul ignore next - #schedulePoll()'s !#running guard and
+		clearImmediate() in stop() together prevent #pollLoop from ever
+		being called once the transport has stopped; this is a
+		belt-and-suspenders defence. */
+		if (!this.#running || !this.#url) return;
+		try {
+			await this.#poll(this.#url, false);
+		} catch (err) {
+			/* istanbul ignore else - between #poll re-throwing and this catch,
+			no macrotask can run to set #running=false; the false branch is
+			a belt-and-suspenders defence against a theoretical race. */
+			if (this.#running) {
+				this.#logger.log(LogLevel.Error, `(LongPolling transport) Poll error: ${err.message}`);
+				this.#running = false;
+				this.onclose?.(err instanceof Error ? err : new Error(String(err)));
+				return;
+			}
+		}
+		this.#schedulePoll();
+	}
+	async #poll(url, isConnect) {
+		const headers = await this.#buildHeaders();
+		let res;
+		try {
+			res = await this.#httpClient.stream("GET", url, {
+				headers,
+				timeout: POLL_TIMEOUT_MS
+			});
+			this.#activeAbort = res.abort;
+		} catch (err) {
+			if (!this.#running) return;
+			throw err;
+		}
+		if (res.statusCode === 204) {
+			await readAll(res.body);
+			this.#activeAbort = null;
+			this.#logger.log(LogLevel.Information, "(LongPolling transport) Server closed (204).");
+			this.#running = false;
+			this.onclose?.();
+			return;
+		}
+		if (res.statusCode < 200 || res.statusCode >= 300) {
+			await readAll(res.body);
+			this.#activeAbort = null;
+			const err = /* @__PURE__ */ new Error(`Long polling received unexpected status ${res.statusCode}.`);
+			if (!isConnect) {
+				this.#running = false;
+				this.onclose?.(err);
+			} else throw err;
+			return;
+		}
+		let body;
+		try {
+			body = await readAll(res.body);
+		} catch (err) {
+			/* istanbul ignore next -- only an explicit stop aborts the active body */
+			if (!this.#running) return;
+			/* istanbul ignore next -- body errors are propagated to the poll loop */
+			throw err;
+		} finally {
+			this.#activeAbort = null;
+		}
+		if (body.length > 0) {
+			const data = this.#transferFormat === TransferFormat.Binary ? new Uint8Array(body.buffer, body.byteOffset, body.byteLength) : body.toString("utf8");
+			this.#logger.log(LogLevel.Trace, `(LongPolling transport) Received ${body.length} bytes.`);
+			this.onreceive?.(data);
+		}
+	}
+	async #buildHeaders(extra = {}) {
+		const headers = {
+			...this.#extraHeaders,
+			...extra
+		};
+		if (this.#accessTokenFactory) {
+			const token = await this.#accessTokenFactory();
+			if (token) headers["Authorization"] = `Bearer ${token}`;
+		}
+		return headers;
+	}
+};
+function readAll(stream) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		stream.on("data", (chunk) => {
+			/* istanbul ignore next -- Node HTTP response streams emit Buffer chunks */
+			chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+		});
+		stream.on("end", () => resolve(Buffer.concat(chunks)));
+		stream.on("error", reject);
+	});
+}
+//#endregion
+//#region src/logger.ts
+/**
+* logger.ts
+*
+* Built-in ILogger implementations.
+* ConsoleLogger - writes to console with timestamps and severity labels.
+* NullLogger     - discards everything (default when no logger is configured).
+*/
+var ConsoleLogger = class {
+	#minimumLevel;
+	constructor(minimumLevel = LogLevel.Information) {
+		this.#minimumLevel = minimumLevel;
+	}
+	log(level, message) {
+		if (level < this.#minimumLevel) return;
+		const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] [${logLevelName(level)}] ${message}`;
+		switch (level) {
+			case LogLevel.Trace:
+			case LogLevel.Debug:
+				console.debug(line);
+				break;
+			case LogLevel.Warning:
+				console.warn(line);
+				break;
+			case LogLevel.Error:
+			case LogLevel.Critical:
+				console.error(line);
+				break;
+			default:
+				console.log(line);
+				break;
+		}
+	}
+};
+var NullLogger = class NullLogger {
+	/** Singleton - no state, so one instance is enough. */
+	static instance = new NullLogger();
+	log(_logLevel, _message) {}
+};
+/** Reverse-map a LogLevel number to its string label. */
+function logLevelName(level) {
+	return Object.entries(LogLevel).find(([, v]) => v === level)?.[0] ?? String(level);
+}
+/** Normalise a LogLevel number or ILogger into an ILogger. */
+function resolveLogger(logLevelOrLogger) {
+	if (typeof logLevelOrLogger === "number") return new ConsoleLogger(logLevelOrLogger);
+	if (logLevelOrLogger != null && typeof logLevelOrLogger === "object" && typeof logLevelOrLogger.log === "function") return logLevelOrLogger;
+	throw new TypeError("configureLogging expects a LogLevel number or an object with a log(level, message) method.");
+}
+//#endregion
+//#region src/errors.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. */
+var HubError = class extends Error {
+	name = "HubError";
+	constructor(message) {
+		super(message);
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/** Thrown when an in-flight operation is cancelled (e.g. connection closed). */
+var AbortError = class extends Error {
+	name = "AbortError";
+	constructor(message = "The operation was aborted.") {
+		super(message);
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/** Thrown on network-level transport failures. */
+var TransportError = class extends Error {
+	name = "TransportError";
+	statusCode;
+	constructor(message, statusCode) {
+		super(message);
+		this.statusCode = statusCode;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/** Thrown when the SignalR protocol handshake is rejected by the server. */
+var HandshakeError = class extends Error {
+	name = "HandshakeError";
+	constructor(message) {
+		super(message);
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/** Thrown when no acceptable transport could be negotiated. */
+var UnsupportedTransportError = class extends Error {
+	name = "UnsupportedTransportError";
+	transport;
+	constructor(message, transport) {
+		super(message);
+		this.transport = transport;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+function isHubError(e) {
+	return e instanceof HubError;
+}
+function isAbortError(e) {
+	return e instanceof AbortError;
+}
+function isTransportError(e) {
+	return e instanceof TransportError;
+}
+//#endregion
+//#region src/hub-connection.ts
+/**
+* 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
+*/
+const MAX_REDIRECTS = 100;
+var StreamSubscription = class {
+	#disposed = false;
+	#cancel;
+	constructor(cancel) {
+		this.#cancel = cancel;
+	}
+	dispose() {
+		if (!this.#disposed) {
+			this.#disposed = true;
+			this.#cancel();
+		}
+	}
+	/** TS 5.2+ `using` keyword support. */
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+};
+var HubConnection = class {
+	#url;
+	#logger;
+	#accessTokenFactory;
+	#requestedTransport;
+	#extraHeaders;
+	#skipNegotiation;
+	#serverTimeout;
+	#pingInterval;
+	#handshakeTimeout;
+	#reconnectPolicy;
+	#protocol;
+	#http;
+	#dispatcher;
+	#ownsDispatcher;
+	#maximumReceiveMessageSize;
+	#transport = null;
+	#connectionId = null;
+	#connectionToken = null;
+	#state = HubConnectionState.Disconnected;
+	#stopping = false;
+	/** Pending `invoke()` calls awaiting a Completion message. */
+	#callbacks = /* @__PURE__ */ new Map();
+	/** Active server-streaming subscriptions awaiting StreamItem/Completion. */
+	#streamCbs = /* @__PURE__ */ new Map();
+	/** Client-method handlers registered via `on()`. */
+	#methods = /* @__PURE__ */ new Map();
+	/** Registered `onclose` callbacks. */
+	#closedCallbacks = [];
+	/** Registered `onreconnecting` callbacks. */
+	#reconnectingCallbacks = [];
+	/** Registered `onreconnected` callbacks. */
+	#reconnectedCallbacks = [];
+	#pingTimer = null;
+	#serverTimeoutTimer = null;
+	#handshakeTimer = null;
+	#handshakeResolver = null;
+	#handshakeRejecter = null;
+	#handshakeBuffer = Buffer.alloc(0);
+	#dispatcherClosePromise = null;
+	#invocationSeq = 0;
+	constructor(url, options = {}) {
+		this.#url = url;
+		this.#logger = options.logger ?? NullLogger.instance;
+		this.#accessTokenFactory = options.accessTokenFactory ?? null;
+		this.#requestedTransport = options.transport ?? HttpTransportType.WebSockets | HttpTransportType.ServerSentEvents | HttpTransportType.LongPolling;
+		this.#extraHeaders = options.headers ?? {};
+		this.#skipNegotiation = options.skipNegotiation ?? false;
+		this.#serverTimeout = options.serverTimeoutInMilliseconds ?? 3e4;
+		this.#pingInterval = options.keepAliveIntervalInMilliseconds ?? 15e3;
+		this.#handshakeTimeout = options.handshakeTimeoutInMilliseconds ?? 15e3;
+		this.#reconnectPolicy = options.reconnectPolicy ?? null;
+		this.#protocol = options.protocol ?? new JsonHubProtocol();
+		this.#dispatcher = options.dispatcher;
+		this.#ownsDispatcher = options.ownsDispatcher ?? false;
+		this.#maximumReceiveMessageSize = options.maximumReceiveMessageSize ?? 32 * 1024 * 1024;
+		this.#http = options.httpClient ?? new DispatchHttpClient({
+			headers: this.#extraHeaders,
+			...options.dispatcher !== void 0 && { dispatcher: options.dispatcher }
+		});
+	}
+	get state() {
+		return this.#state;
+	}
+	get connectionId() {
+		return this.#connectionId;
+	}
+	async start() {
+		if (this.#state !== HubConnectionState.Disconnected) throw new Error(`Cannot start: connection is not Disconnected (current: ${this.#state}).`);
+		this.#state = HubConnectionState.Connecting;
+		this.#stopping = false;
+		this.#logger.log(LogLevel.Debug, "Starting HubConnection.");
+		try {
+			await this.#startInternal();
+			this.#state = HubConnectionState.Connected;
+			this.#logger.log(LogLevel.Information, "HubConnection connected.");
+		} catch (err) {
+			this.#clearTimers();
+			this.#handshakeResolver = null;
+			this.#handshakeRejecter = null;
+			this.#handshakeBuffer = Buffer.alloc(0);
+			if (this.#transport) {
+				this.#transport.onclose = null;
+				await this.#transport.stop().catch(
+					/* istanbul ignore next -- cleanup is best-effort */
+					() => {}
+				);
+				this.#transport = null;
+			}
+			this.#state = HubConnectionState.Disconnected;
+			this.#logger.log(LogLevel.Error, `Failed to start: ${err.message}`);
+			throw err;
+		}
+	}
+	async stop() {
+		if (this.#state === HubConnectionState.Disconnected) return;
+		this.#stopping = true;
+		this.#state = HubConnectionState.Disconnecting;
+		this.#logger.log(LogLevel.Debug, "Stopping HubConnection.");
+		this.#clearTimers();
+		const stopErr = new AbortError("Connection stopped before the invocation completed.");
+		this.#rejectAllPending(stopErr);
+		/* istanbul ignore else -- non-disconnected connections normally own a transport */
+		if (this.#transport) {
+			this.#transport.onclose = null;
+			try {
+				await this.#transport.stop();
+			} catch {}
+			this.#transport = null;
+		}
+		this.#completeClose();
+		await this.#closeOwnedDispatcher();
+		this.#logger.log(LogLevel.Information, "HubConnection stopped.");
+	}
+	/**
+	* 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(methodName, ...args) {
+		this.#assertConnected("invoke");
+		const id = this.#nextId();
+		const msg = this.#encode(JsonHubProtocol.invocation(id, methodName, args));
+		return new Promise((resolve, reject) => {
+			this.#callbacks.set(id, {
+				resolve,
+				reject
+			});
+			this.#send(msg).catch((err) => {
+				this.#callbacks.delete(id);
+				reject(err);
+			});
+		});
+	}
+	/**
+	* Fire-and-forget hub method invocation.
+	* The server does not send a completion message.
+	*/
+	send(methodName, ...args) {
+		this.#assertConnected("send");
+		const msg = this.#encode(JsonHubProtocol.send(methodName, args));
+		return this.#send(msg);
+	}
+	/**
+	* 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(methodName, ...args) {
+		this.#assertConnected("stream");
+		const id = this.#nextId();
+		const queued = [];
+		let activeSubscriber = null;
+		let subscribed = false;
+		const deliver = (notification) => {
+			if (!activeSubscriber) {
+				queued.push(notification);
+				return;
+			}
+			if (notification.kind === "next") activeSubscriber.next?.(notification.value);
+			else if (notification.kind === "error") activeSubscriber.error?.(notification.error);
+			else activeSubscriber.complete?.();
+		};
+		this.#streamCbs.set(id, {
+			next: (value) => deliver({
+				kind: "next",
+				value
+			}),
+			error: (error) => deliver({
+				kind: "error",
+				error
+			}),
+			complete: () => deliver({ kind: "complete" })
+		});
+		const msg = this.#encode(JsonHubProtocol.streamInvocation(id, methodName, args));
+		this.#send(msg).catch((error) => {
+			this.#streamCbs.delete(id);
+			deliver({
+				kind: "error",
+				error
+			});
+		});
+		return { subscribe: (subscriber) => {
+			if (subscribed) throw new Error("A stream result can only be subscribed to once.");
+			subscribed = true;
+			activeSubscriber = subscriber;
+			for (const notification of queued.splice(0)) deliver(notification);
+			return new StreamSubscription(() => {
+				if (this.#streamCbs.has(id)) {
+					this.#streamCbs.delete(id);
+					this.#send(this.#encode(JsonHubProtocol.cancelInvocation(id))).catch(
+						/* istanbul ignore next -- cancellation is intentionally best-effort */
+						() => {}
+					);
+				}
+			});
+		} };
+	}
+	/**
+	* 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(methodName, handler) {
+		const key = methodName.toLowerCase();
+		if (!this.#methods.has(key)) this.#methods.set(key, /* @__PURE__ */ new Set());
+		this.#methods.get(key).add(handler);
+	}
+	/**
+	* Remove a previously registered handler, or all handlers for a method.
+	*/
+	off(methodName, handler) {
+		const key = methodName.toLowerCase();
+		if (!this.#methods.has(key)) return;
+		if (handler == null) this.#methods.delete(key);
+		else {
+			this.#methods.get(key).delete(handler);
+			if (this.#methods.get(key).size === 0) this.#methods.delete(key);
+		}
+	}
+	onclose(callback) {
+		this.#closedCallbacks.push(callback);
+	}
+	onreconnecting(callback) {
+		this.#reconnectingCallbacks.push(callback);
+	}
+	onreconnected(callback) {
+		this.#reconnectedCallbacks.push(callback);
+	}
+	async #startInternal() {
+		let url = this.#url;
+		if (this.#skipNegotiation) {
+			if (this.#requestedTransport !== HttpTransportType.WebSockets) throw new Error("skipNegotiation requires WebSockets as the only transport.");
+			this.#transport = this.#createTransport(HttpTransportType.WebSockets);
+			await this.#connectTransport(url, this.#protocol.transferFormat);
+		} else {
+			let redirectCount = 0;
+			for (;;) {
+				const neg = await this.#negotiate(url);
+				if (neg.url) {
+					if (redirectCount++ >= MAX_REDIRECTS) throw new Error("Too many negotiate redirects.");
+					url = neg.url;
+					if (neg.accessToken) {
+						const staticToken = neg.accessToken;
+						this.#overrideAccessToken(() => Promise.resolve(staticToken));
+					}
+					continue;
+				}
+				/* istanbul ignore next -- a successful negotiate response must include connectionId */
+				this.#connectionId = neg.connectionId ?? null;
+				/* istanbul ignore next -- the protocol requires a token or connectionId */
+				this.#connectionToken = neg.connectionToken ?? neg.connectionId ?? null;
+				/* istanbul ignore next -- the protocol requires availableTransports */
+				await this.#selectTransport(url, neg.availableTransports ?? []);
+				break;
+			}
+		}
+		this.#transport.onreceive = (data) => this.#processIncoming(data);
+		this.#transport.onclose = (err) => this.#onTransportClosed(err);
+		await this.#performHandshake();
+		this.#resetPingTimer();
+		this.#resetServerTimeoutTimer();
+	}
+	#_accessTokenFactory = null;
+	#overrideAccessToken(factory) {
+		this.#_accessTokenFactory = factory;
+	}
+	#getAccessTokenFactory() {
+		return this.#_accessTokenFactory ?? this.#accessTokenFactory;
+	}
+	async #negotiate(baseUrl) {
+		const negotiateUrl = new URL(baseUrl);
+		negotiateUrl.pathname = negotiateUrl.pathname.replace(/\/$/, "") + "/negotiate";
+		negotiateUrl.searchParams.set("negotiateVersion", String(1));
+		const url = negotiateUrl.toString();
+		this.#logger.log(LogLevel.Debug, `Sending negotiate request to ${url}.`);
+		const headers = { ...this.#extraHeaders };
+		const factory = this.#getAccessTokenFactory();
+		if (factory) {
+			const token = await factory();
+			if (token) headers["Authorization"] = `Bearer ${token}`;
+		}
+		const res = await this.#http.post(url, { headers });
+		if (res.status !== 200) throw new TransportError(`Unexpected status code ${res.status} from negotiate.`, res.status);
+		if (Buffer.byteLength(res.body, "utf8") > this.#maximumReceiveMessageSize) throw new Error(`Negotiate response exceeds ${this.#maximumReceiveMessageSize} bytes.`);
+		const body = JSON.parse(res.body);
+		if (body.error) throw new Error(`Negotiate returned error: ${body.error}`);
+		return body;
+	}
+	async #selectTransport(url, available) {
+		const ORDERED = [
+			{
+				flag: HttpTransportType.WebSockets,
+				name: "WebSockets"
+			},
+			{
+				flag: HttpTransportType.ServerSentEvents,
+				name: "ServerSentEvents"
+			},
+			{
+				flag: HttpTransportType.LongPolling,
+				name: "LongPolling"
+			}
+		];
+		/* istanbul ignore next -- both protocol formats are exercised at the protocol boundary */
+		const formatName = this.#protocol.transferFormat === TransferFormat.Binary ? "Binary" : "Text";
+		for (const pref of ORDERED) {
+			if ((this.#requestedTransport & pref.flag) === 0) continue;
+			if (!available.find((candidate) => candidate.transport === pref.name)?.transferFormats.includes(formatName)) continue;
+			this.#logger.log(LogLevel.Debug, `Trying ${pref.name} transport.`);
+			const transport = this.#createTransport(pref.flag);
+			const tUrl = appendParam(url, "id", this.#connectionToken ?? "");
+			try {
+				await transport.connect(tUrl, this.#protocol.transferFormat);
+				this.#transport = transport;
+				return;
+			} catch (err) {
+				this.#logger.log(LogLevel.Warning, `${pref.name} failed: ${err.message}`);
+			}
+		}
+		throw new UnsupportedTransportError("Unable to connect with any of the available transports.", null);
+	}
+	async #connectTransport(url, format) {
+		await this.#transport.connect(url, format);
+	}
+	#createTransport(type) {
+		const factory = this.#getAccessTokenFactory();
+		const headers = this.#extraHeaders;
+		switch (type) {
+			case HttpTransportType.WebSockets: return new WebSocketTransport(factory, this.#logger, headers, this.#dispatcher);
+			case HttpTransportType.ServerSentEvents: return new ServerSentEventsTransport(this.#http, factory, this.#logger, headers);
+			case HttpTransportType.LongPolling: return new LongPollingTransport(this.#http, factory, this.#logger, headers);
+			/* istanbul ignore next */
+			default: throw new UnsupportedTransportError(`Unknown transport type: ${type}`, type);
+		}
+	}
+	#performHandshake() {
+		return new Promise((resolve, reject) => {
+			this.#handshakeResolver = resolve;
+			this.#handshakeRejecter = reject;
+			const request = JSON.stringify({
+				protocol: this.#protocol.name,
+				version: this.#protocol.version
+			}) + "";
+			const fail = (error) => {
+				clearTimeout(this.#handshakeTimer);
+				this.#handshakeResolver = null;
+				this.#handshakeRejecter = null;
+				/* istanbul ignore next -- transport.send rejects with Error */
+				reject(error instanceof Error ? error : new Error(String(error)));
+			};
+			this.#transport.send(request).catch(fail);
+			this.#handshakeTimer = setTimeout(() => {
+				fail(/* @__PURE__ */ new Error("Server timeout: no handshake response received."));
+			}, this.#handshakeTimeout);
+		});
+	}
+	#processIncoming(data) {
+		this.#resetServerTimeoutTimer();
+		/* istanbul ignore next -- binary input is exercised through binary protocol tests */
+		const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+		if (bytes.byteLength > this.#maximumReceiveMessageSize) {
+			this.#stopWithError(/* @__PURE__ */ new Error(`Incoming message exceeds ${this.#maximumReceiveMessageSize} bytes.`));
+			return;
+		}
+		if (this.#handshakeResolver) {
+			this.#handshakeBuffer = Buffer.concat([this.#handshakeBuffer, bytes]);
+			const separator = this.#handshakeBuffer.indexOf(30);
+			/* istanbul ignore next -- partial handshakes are buffered for the next frame */
+			if (separator === -1) return;
+			try {
+				parseHandshakeResponse(this.#handshakeBuffer.subarray(0, separator + 1).toString("utf8"));
+				const remainder = this.#handshakeBuffer.subarray(separator + 1);
+				this.#handshakeBuffer = Buffer.alloc(0);
+				this.#logger.log(LogLevel.Debug, "Handshake complete.");
+				clearTimeout(this.#handshakeTimer);
+				const r = this.#handshakeResolver;
+				this.#handshakeResolver = null;
+				this.#handshakeRejecter = null;
+				r();
+				/* istanbul ignore next -- servers ordinarily send handshake and hub frames separately */
+				if (remainder.length > 0) this.#processProtocolPayload(remainder);
+			} catch (err) {
+				clearTimeout(this.#handshakeTimer);
+				const r = this.#handshakeRejecter;
+				this.#handshakeResolver = null;
+				this.#handshakeRejecter = null;
+				/* istanbul ignore next -- JSON.parse and protocol validation throw Error objects */
+				r(err instanceof Error ? err : new Error(String(err)));
+				return;
+			}
+			return;
+		}
+		this.#processProtocolPayload(bytes);
+	}
+	#processProtocolPayload(bytes) {
+		/* istanbul ignore next -- transports do not emit empty payloads */
+		if (bytes.length === 0) return;
+		let messages;
+		try {
+			/* istanbul ignore next -- MessagePack parsing is covered directly */
+			const input = this.#protocol.transferFormat === TransferFormat.Text ? Buffer.from(bytes).toString("utf8") : Uint8Array.from(bytes).buffer;
+			messages = this.#protocol.parseMessages(input, this.#logger);
+		} catch (err) {
+			this.#logger.log(LogLevel.Error, `Error parsing messages: ${err.message}`);
+			/* istanbul ignore next -- protocol parsers throw Error objects */
+			this.#stopWithError(err instanceof Error ? err : new Error(String(err)));
+			return;
+		}
+		for (const msg of messages) switch (msg.type) {
+			case MessageType.Invocation:
+				this.#invokeClientMethod(msg);
+				break;
+			case MessageType.StreamItem: {
+				const sc = this.#streamCbs.get(msg.invocationId);
+				if (!sc) break;
+				sc.next(msg.item);
+				break;
+			}
+			case MessageType.Completion: {
+				const cb = this.#callbacks.get(msg.invocationId);
+				if (cb) {
+					this.#callbacks.delete(msg.invocationId);
+					if (msg.error) cb.reject(new HubError(msg.error));
+					else cb.resolve(msg.result ?? null);
+				}
+				const sc = this.#streamCbs.get(msg.invocationId);
+				if (sc) {
+					this.#streamCbs.delete(msg.invocationId);
+					if (msg.error) sc.error(new HubError(msg.error));
+					else sc.complete();
+				}
+				break;
+			}
+			case MessageType.Ping: break;
+			case MessageType.Close: {
+				this.#logger.log(LogLevel.Information, "Server sent Close message.");
+				const closeErr = msg.error ? new HubError(msg.error) : null;
+				if (msg.allowReconnect && this.#reconnectPolicy && !this.#stopping) {
+					this.#clearTimers();
+					/* istanbul ignore next - #transport is always non-null here; null
+					is a defensive guard against theoretical concurrent nulling. */
+					if (this.#transport) this.#transport.onclose = null;
+					const t = this.#transport;
+					this.#transport = null;
+					this.#rejectAllPending(closeErr ?? new AbortError("Connection closed while reconnecting."));
+					t?.stop().catch(
+						/* istanbul ignore next -- shutdown after a server Close is best-effort */
+						() => {}
+					);
+					this.#doReconnect(closeErr);
+				} else this.#stopWithError(closeErr);
+				break;
+			}
+			default:
+				this.#logger.log(LogLevel.Warning, `Unknown message type: ${msg.type}`);
+				break;
+		}
+	}
+	async #invokeClientMethod(msg) {
+		const handlers = this.#methods.get(msg.target.toLowerCase());
+		if (!handlers || handlers.size === 0) {
+			this.#logger.log(LogLevel.Warning, `No handler for "${msg.target}".`);
+			if (msg.invocationId) await this.#send(this.#encode(JsonHubProtocol.completion(msg.invocationId, void 0, `No client handler registered for '${msg.target}'.`))).catch(
+				/* istanbul ignore next -- completion replies are best-effort */
+				() => {}
+			);
+			return;
+		}
+		let result;
+		let invocationError = null;
+		for (const handler of [...handlers]) try {
+			result = await handler(...msg.arguments);
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			invocationError ??= err;
+			this.#logger.log(LogLevel.Error, `Handler for "${msg.target}" threw: ${err.message}`);
+		}
+		if (msg.invocationId) {
+			const completion = invocationError ? {
+				type: MessageType.Completion,
+				invocationId: msg.invocationId,
+				error: invocationError.message
+			} : {
+				type: MessageType.Completion,
+				invocationId: msg.invocationId,
+				...result !== void 0 && { result }
+			};
+			await this.#send(this.#encode(completion)).catch(
+				/* istanbul ignore next -- completion replies are best-effort */
+				() => {}
+			);
+		}
+	}
+	#onTransportClosed(err) {
+		/* istanbul ignore next - WebSocketTransport.stop() nulls #ws before
+		calling ws.close(), so the close handler never invokes onclose once
+		stop() has set #stopping; this guard is a belt-and-suspenders defence. */
+		if (this.#stopping) return;
+		this.#logger.log(LogLevel.Warning, err ? `Transport closed with error: ${err.message}` : "Transport closed.");
+		this.#clearTimers();
+		this.#rejectAllPending(err ?? new AbortError("Connection closed while reconnecting."));
+		if (this.#reconnectPolicy) this.#doReconnect(err ?? null);
+		else this.#completeClose(err);
+	}
+	#stopWithError(err) {
+		this.#clearTimers();
+		this.#transport?.stop().catch(
+			/* istanbul ignore next -- error shutdown is best-effort */
+			() => {}
+		);
+		this.#transport = null;
+		this.#completeClose(err ?? void 0);
+	}
+	#completeClose(err) {
+		const closeErr = err ?? new AbortError("Connection closed.");
+		this.#rejectAllPending(closeErr);
+		this.#state = HubConnectionState.Disconnected;
+		for (const cb of this.#closedCallbacks) try {
+			cb(err);
+		} catch {}
+		this.#closeOwnedDispatcher();
+	}
+	#rejectAllPending(err) {
+		this.#callbacks.forEach((cb) => cb.reject(err));
+		this.#callbacks.clear();
+		this.#streamCbs.forEach((sc) => sc.error(err));
+		this.#streamCbs.clear();
+	}
+	async #doReconnect(disconnectError) {
+		this.#state = HubConnectionState.Reconnecting;
+		for (const cb of this.#reconnectingCallbacks) try {
+			cb(disconnectError ?? void 0);
+		} catch {}
+		let retryCount = 0;
+		const startTime = Date.now();
+		let lastError = disconnectError;
+		while (!this.#stopping) {
+			const ctx = {
+				previousRetryCount: retryCount,
+				elapsedMilliseconds: Date.now() - startTime,
+				retryReason: lastError
+			};
+			const delay = this.#reconnectPolicy.nextRetryDelayInMilliseconds(ctx);
+			if (delay === null) {
+				this.#logger.log(LogLevel.Debug, "Reconnect policy returned null - giving up.");
+				break;
+			}
+			this.#logger.log(LogLevel.Information, `Reconnecting in ${delay} ms (attempt ${retryCount + 1}).`);
+			await sleep(delay);
+			if (this.#stopping) break;
+			try {
+				await this.#startInternal();
+				this.#state = HubConnectionState.Connected;
+				this.#logger.log(LogLevel.Information, "Reconnected successfully.");
+				for (const cb of this.#reconnectedCallbacks) try {
+					cb(this.#connectionId);
+				} catch {}
+				return;
+			} catch (err) {
+				retryCount++;
+				/* istanbul ignore next - #startInternal() only throws Error instances. */
+				lastError = err instanceof Error ? err : new Error(String(err));
+				this.#logger.log(LogLevel.Warning, `Reconnect attempt ${retryCount} failed: ${lastError.message}`);
+			}
+		}
+		this.#completeClose(lastError ?? void 0);
+	}
+	#resetPingTimer() {
+		clearTimeout(this.#pingTimer);
+		this.#pingTimer = setTimeout(async () => {
+			/* istanbul ignore next - #clearTimers() always cancels this before state
+			leaves Connected; the guard is a defensive fallback. */
+			if (this.#state !== HubConnectionState.Connected) return;
+			try {
+				await this.#send(this.#encode(JsonHubProtocol.ping()));
+			} catch (err) {
+				this.#logger.log(LogLevel.Warning, `Ping failed: ${err.message}`);
+			}
+			this.#resetPingTimer();
+		}, this.#pingInterval);
+	}
+	#resetServerTimeoutTimer() {
+		clearTimeout(this.#serverTimeoutTimer);
+		this.#serverTimeoutTimer = setTimeout(() => {
+			this.#logger.log(LogLevel.Warning, "Server timeout - closing connection.");
+			this.#stopWithError(new AbortError("Server timeout: no message received within the timeout period."));
+		}, this.#serverTimeout);
+	}
+	#clearTimers() {
+		clearTimeout(this.#pingTimer);
+		clearTimeout(this.#serverTimeoutTimer);
+		clearTimeout(this.#handshakeTimer);
+		this.#pingTimer = null;
+		this.#serverTimeoutTimer = null;
+		this.#handshakeTimer = null;
+	}
+	#send(message) {
+		this.#resetPingTimer();
+		return this.#transport.send(message);
+	}
+	#encode(message) {
+		const encoded = this.#protocol.writeMessage(message);
+		return typeof encoded === "string" ? encoded : new Uint8Array(encoded);
+	}
+	#assertConnected(method) {
+		if (this.#state !== HubConnectionState.Connected) throw new Error(`Cannot call "${method}" when connection is not Connected (current: ${this.#state}).`);
+	}
+	#nextId() {
+		return toInvocationId(String(++this.#invocationSeq));
+	}
+	async #closeOwnedDispatcher() {
+		if (!this.#ownsDispatcher || !this.#dispatcher) return;
+		this.#dispatcherClosePromise ??= this.#dispatcher.close().catch(
+			/* istanbul ignore next -- shutdown cleanup is best-effort */
+			() => {}
+		);
+		await this.#dispatcherClosePromise;
+	}
+};
+/**
+* Append a single query-string name/value pair to a URL.
+*
+* Uses the WHATWG `URL` API so the operation is always correct regardless of
+* whether the URL already contains a query string, path segments, or both.
+* This avoids the classic bug where naive string concatenation appends a path
+* segment *after* an existing query string, corrupting the URL.
+*
+* e.g. appendParam('https://host/hub?token=x', 'id', 'y')
+*   → 'https://host/hub?token=x&id=y'   ✓  (not '?token=x&id=y' appended raw)
+*/
+function appendParam(url, name, value) {
+	const u = new URL(url);
+	u.searchParams.append(name, value);
+	return u.toString();
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//#endregion
+//#region src/hub-connection-builder.ts
+/**
+* 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();
+*/
+/** Default reconnect delay sequence in ms: 0, 2 s, 10 s, 30 s then give up. */
+const DEFAULT_RETRY_DELAYS = [
+	0,
+	2e3,
+	1e4,
+	3e4
+];
+var HubConnectionBuilder = class {
+	#url = null;
+	#urlOptions = {};
+	#logger = null;
+	#reconnectPolicy = null;
+	#dispatcher = null;
+	#httpClient = null;
+	#cookieJar = null;
+	#protocol = null;
+	withUrl(url, options) {
+		if (!url || typeof url !== "string") throw new TypeError("withUrl requires a non-empty string URL.");
+		this.#url = url;
+		this.#urlOptions = options ?? {};
+		return 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) {
+		if (this.#dispatcher !== null) throw new Error("withCookies() cannot be used after withDispatcher(). To combine a custom dispatcher with cookie support, compose the cookie interceptor from @exhumer/undici-cookie-agent onto your dispatcher and pass it to withDispatcher() instead.");
+		this.#cookieJar = jar ?? new CookieJar$1();
+		return 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) {
+		if (this.#cookieJar !== null) throw new Error("withDispatcher() cannot be used after withCookies(). To combine a custom dispatcher with cookie support, compose the cookie interceptor from @exhumer/undici-cookie-agent onto your dispatcher and pass it to withDispatcher() instead.");
+		this.#dispatcher = dispatcher;
+		return 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) {
+		this.#httpClient = httpClient;
+		return this;
+	}
+	/** Select the hub wire protocol (for example, MessagePack). */
+	withHubProtocol(protocol) {
+		this.#protocol = protocol;
+		return 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) {
+		this.#logger = resolveLogger(logLevelOrLogger);
+		return this;
+	}
+	withAutomaticReconnect(arg) {
+		if (arg === void 0) this.#reconnectPolicy = new DefaultReconnectPolicy([...DEFAULT_RETRY_DELAYS]);
+		else if (Array.isArray(arg)) this.#reconnectPolicy = new DefaultReconnectPolicy(arg);
+		else if (typeof arg === "object" && typeof arg.nextRetryDelayInMilliseconds === "function") this.#reconnectPolicy = arg;
+		else throw new TypeError("withAutomaticReconnect expects no args, a number[], or an IRetryPolicy.");
+		return this;
+	}
+	build() {
+		if (!this.#url) throw new Error("withUrl() must be called before build().");
+		const effectiveDispatcher = this.#cookieJar !== null ? new CookieAgent$1({ cookies: { jar: this.#cookieJar } }) : this.#dispatcher;
+		const options = {
+			...this.#logger != null && { logger: this.#logger },
+			...this.#urlOptions.accessTokenFactory != null && { accessTokenFactory: this.#urlOptions.accessTokenFactory },
+			...this.#urlOptions.transport != null && { transport: this.#urlOptions.transport },
+			...this.#urlOptions.headers != null && { headers: this.#urlOptions.headers },
+			...this.#urlOptions.skipNegotiation != null && { skipNegotiation: this.#urlOptions.skipNegotiation },
+			...this.#urlOptions.serverTimeoutInMilliseconds != null && { serverTimeoutInMilliseconds: this.#urlOptions.serverTimeoutInMilliseconds },
+			...this.#urlOptions.keepAliveIntervalInMilliseconds != null && { keepAliveIntervalInMilliseconds: this.#urlOptions.keepAliveIntervalInMilliseconds },
+			...this.#urlOptions.handshakeTimeoutInMilliseconds != null && { handshakeTimeoutInMilliseconds: this.#urlOptions.handshakeTimeoutInMilliseconds },
+			...this.#urlOptions.maximumReceiveMessageSize != null && { maximumReceiveMessageSize: this.#urlOptions.maximumReceiveMessageSize },
+			...this.#reconnectPolicy != null && { reconnectPolicy: this.#reconnectPolicy },
+			...effectiveDispatcher != null && { dispatcher: effectiveDispatcher },
+			...this.#httpClient != null && { httpClient: this.#httpClient },
+			...this.#protocol != null && { protocol: this.#protocol },
+			...this.#cookieJar != null && { ownsDispatcher: true }
+		};
+		return new HubConnection(this.#url, options);
+	}
+};
+var DefaultReconnectPolicy = class {
+	#retryDelays;
+	constructor(retryDelays = [...DEFAULT_RETRY_DELAYS]) {
+		this.#retryDelays = retryDelays;
+	}
+	nextRetryDelayInMilliseconds(context) {
+		return this.#retryDelays[context.previousRetryCount] ?? null;
+	}
+};
+//#endregion
+//#region src/protocols/msgpack-hub-protocol.ts
+/**
+* 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.
+*/
+const HANDSHAKE_REQUEST$1 = JSON.stringify({
+	protocol: "messagepack",
+	version: 1
+}) + "";
+const ResultKind = Object.freeze({
+	Error: 1,
+	Void: 2,
+	NonVoid: 3
+});
+/** Write `n` as a base-128 VarInt (little-endian groups of 7 bits). */
+function writeVarInt(n) {
+	const bytes = [];
+	do {
+		let b = n & 127;
+		n >>>= 7;
+		if (n > 0) b |= 128;
+		bytes.push(b);
+	} while (n > 0);
+	return new Uint8Array(bytes);
+}
+/** Read a VarInt from `data` starting at `offset`.  Returns value + bytes consumed. */
+function readVarInt(data, offset) {
+	let value = 0;
+	let shift = 0;
+	let bytesRead = 0;
+	let hasMore = true;
+	while (hasMore) {
+		if (offset + bytesRead >= data.length) throw new Error("MessagePack: unexpected end of data reading VarInt frame length.");
+		const byte = data[offset + bytesRead];
+		hasMore = (byte & 128) !== 0;
+		if (bytesRead === 4 && hasMore) throw new Error("MessagePack: VarInt frame length prefix is longer than 5 bytes.");
+		if (bytesRead === 4 && byte > 7) throw new Error("MessagePack: VarInt frame length exceeds the 2 GB SignalR limit.");
+		value |= (byte & 127) << shift;
+		shift += 7;
+		bytesRead++;
+	}
+	return {
+		value,
+		bytesRead
+	};
+}
+function pack(arr) {
+	const payload = encode(arr);
+	const lenPrefix = writeVarInt(payload.length);
+	const result = new Uint8Array(lenPrefix.length + payload.length);
+	result.set(lenPrefix, 0);
+	result.set(payload, lenPrefix.length);
+	return result.buffer.slice(0, result.byteLength);
+}
+var MsgpackHubProtocol = class {
+	name = "messagepack";
+	version = 1;
+	transferFormat = TransferFormat.Binary;
+	parseMessages(input, logger) {
+		const raw = typeof input === "string" ? new TextEncoder().encode(input).buffer : input;
+		const data = new Uint8Array(raw);
+		if (data.length === 0) return [];
+		const messages = [];
+		let offset = 0;
+		while (offset < data.length) {
+			const { value: msgLen, bytesRead } = readVarInt(data, offset);
+			offset += bytesRead;
+			if (offset + msgLen > data.length) throw new Error(`MessagePack hub message: declared length ${msgLen} B exceeds remaining data (${data.length - offset} B).`);
+			const frame = data.subarray(offset, offset + msgLen);
+			offset += msgLen;
+			const rawArr = decode(frame);
+			if (!Array.isArray(rawArr) || rawArr.length === 0) throw new Error("Invalid MessagePack hub message: top-level value must be a non-empty array.");
+			const msg = this.#coerce(rawArr, logger);
+			if (msg !== null) messages.push(msg);
+		}
+		return messages;
+	}
+	writeMessage(message) {
+		switch (message.type) {
+			case MessageType.Invocation: return pack([
+				MessageType.Invocation,
+				message.headers ?? {},
+				message.invocationId ?? null,
+				message.target,
+				message.arguments,
+				message.streamIds ?? []
+			]);
+			case MessageType.StreamItem: return pack([
+				MessageType.StreamItem,
+				message.headers ?? {},
+				message.invocationId,
+				message.item
+			]);
+			case MessageType.Completion: {
+				const hasError = message.error != null;
+				const hasResult = Object.prototype.hasOwnProperty.call(message, "result");
+				if (hasError) return pack([
+					MessageType.Completion,
+					message.headers ?? {},
+					message.invocationId,
+					ResultKind.Error,
+					message.error
+				]);
+				else if (hasResult) return pack([
+					MessageType.Completion,
+					message.headers ?? {},
+					message.invocationId,
+					ResultKind.NonVoid,
+					message.result
+				]);
+				else return pack([
+					MessageType.Completion,
+					message.headers ?? {},
+					message.invocationId,
+					ResultKind.Void
+				]);
+			}
+			case MessageType.StreamInvocation: return pack([
+				MessageType.StreamInvocation,
+				message.headers ?? {},
+				message.invocationId,
+				message.target,
+				message.arguments,
+				message.streamIds ?? []
+			]);
+			case MessageType.CancelInvocation: return pack([
+				MessageType.CancelInvocation,
+				message.headers ?? {},
+				message.invocationId
+			]);
+			case MessageType.Ping: return pack([MessageType.Ping]);
+			case MessageType.Close: {
+				const arr = [MessageType.Close, message.error ?? null];
+				if (message.allowReconnect !== void 0) arr.push(message.allowReconnect);
+				return pack(arr);
+			}
+		}
+	}
+	/**
+	* Validate and narrow a raw decoded array into a typed `HubMessage`.
+	* Returns `null` for unknown types - they are logged as warnings.
+	*/
+	#coerce(arr, logger) {
+		const type = arr[0];
+		if (typeof type !== "number") throw new Error(`Invalid MessagePack hub message: first element (type) must be a number, got ${JSON.stringify(type)}.`);
+		switch (type) {
+			case MessageType.Invocation: return this.#coerceInvocation(arr);
+			case MessageType.StreamItem: return this.#coerceStreamItem(arr);
+			case MessageType.Completion: return this.#coerceCompletion(arr);
+			case MessageType.StreamInvocation: return this.#coerceStreamInvocation(arr);
+			case MessageType.CancelInvocation: return this.#coerceCancelInvocation(arr);
+			case MessageType.Ping: return this.#coercePing();
+			case MessageType.Close: return this.#coerceClose(arr);
+			default:
+				logger.log(3, `Ignoring MessagePack message with unknown type ${String(type)}.`);
+				return null;
+		}
+	}
+	#coerceInvocation(arr) {
+		const target = arr[3];
+		const args = arr[4];
+		if (typeof target !== "string") throw new Error("Invalid Invocation message: index 3 ('target') must be a string.");
+		if (!Array.isArray(args)) throw new Error("Invalid Invocation message: index 4 ('arguments') must be an array.");
+		const rawId = arr[2];
+		const rawSids = arr[5];
+		const rawHdrs = arr[1];
+		const streamIds = rawSids == null ? [] : parseStreamIds(rawSids);
+		return {
+			type: MessageType.Invocation,
+			target,
+			arguments: args,
+			...rawId != null && rawId !== "" && { invocationId: parseInvocationId(rawId) },
+			...streamIds.length > 0 && { streamIds },
+			...isNonEmptyObject(rawHdrs) && { headers: parseHeaders(rawHdrs) }
+		};
+	}
+	#coerceStreamItem(arr) {
+		const rawId = arr[2];
+		if (rawId == null) throw new Error("Invalid StreamItem message: index 2 ('invocationId') is required.");
+		return {
+			type: MessageType.StreamItem,
+			invocationId: parseInvocationId(rawId),
+			item: arr[3],
+			...isNonEmptyObject(arr[1]) && { headers: parseHeaders(arr[1]) }
+		};
+	}
+	#coerceCompletion(arr) {
+		const rawId = arr[2];
+		if (rawId == null) throw new Error("Invalid Completion message: index 2 ('invocationId') is required.");
+		const invocationId = parseInvocationId(rawId);
+		const resultKind = arr[3];
+		const hdrs = isNonEmptyObject(arr[1]) ? { headers: parseHeaders(arr[1]) } : {};
+		switch (resultKind) {
+			case ResultKind.Error: return {
+				type: MessageType.Completion,
+				invocationId,
+				error: String(arr[4] ?? ""),
+				...hdrs
+			};
+			case ResultKind.Void: return {
+				type: MessageType.Completion,
+				invocationId,
+				...hdrs
+			};
+			case ResultKind.NonVoid: return {
+				type: MessageType.Completion,
+				invocationId,
+				result: arr[4],
+				...hdrs
+			};
+			default: throw new Error(`Invalid Completion message: unknown resultKind ${String(resultKind)}.`);
+		}
+	}
+	#coerceStreamInvocation(arr) {
+		const rawId = arr[2];
+		const target = arr[3];
+		const args = arr[4];
+		if (rawId == null) throw new Error("Invalid StreamInvocation message: index 2 ('invocationId') is required.");
+		if (typeof target !== "string") throw new Error("Invalid StreamInvocation message: index 3 ('target') must be a string.");
+		if (!Array.isArray(args)) throw new Error("Invalid StreamInvocation message: index 4 ('arguments') must be an array.");
+		const rawSids = arr[5];
+		const streamIds = rawSids == null ? [] : parseStreamIds(rawSids);
+		return {
+			type: MessageType.StreamInvocation,
+			invocationId: parseInvocationId(rawId),
+			target,
+			arguments: args,
+			...streamIds.length > 0 && { streamIds },
+			...isNonEmptyObject(arr[1]) && { headers: parseHeaders(arr[1]) }
+		};
+	}
+	#coerceCancelInvocation(arr) {
+		const rawId = arr[2];
+		if (rawId == null) throw new Error("Invalid CancelInvocation message: index 2 ('invocationId') is required.");
+		return {
+			type: MessageType.CancelInvocation,
+			invocationId: parseInvocationId(rawId),
+			...isNonEmptyObject(arr[1]) && { headers: parseHeaders(arr[1]) }
+		};
+	}
+	#coercePing() {
+		return { type: MessageType.Ping };
+	}
+	#coerceClose(arr) {
+		if (arr[2] != null && typeof arr[2] !== "boolean") throw new Error("Invalid Close message: index 2 ('allowReconnect') must be a boolean.");
+		return {
+			type: MessageType.Close,
+			...arr[1] != null && { error: String(arr[1]) },
+			...arr[2] != null && { allowReconnect: arr[2] }
+		};
+	}
+	static invocation(invocationId, target, args, streamIds) {
+		return {
+			type: MessageType.Invocation,
+			invocationId,
+			target,
+			arguments: args,
+			...streamIds != null && streamIds.length > 0 ? { streamIds } : {}
+		};
+	}
+	/** Fire-and-forget (no `invocationId`). */
+	static send(target, args, streamIds) {
+		return {
+			type: MessageType.Invocation,
+			target,
+			arguments: args,
+			...streamIds != null && streamIds.length > 0 ? { streamIds } : {}
+		};
+	}
+	static streamInvocation(invocationId, target, args, streamIds) {
+		return {
+			type: MessageType.StreamInvocation,
+			invocationId,
+			target,
+			arguments: args,
+			...streamIds != null && streamIds.length > 0 ? { streamIds } : {}
+		};
+	}
+	static cancelInvocation(invocationId) {
+		return {
+			type: MessageType.CancelInvocation,
+			invocationId
+		};
+	}
+	static streamItem(invocationId, item) {
+		return {
+			type: MessageType.StreamItem,
+			invocationId,
+			item
+		};
+	}
+	static completion(invocationId, result, error) {
+		return {
+			type: MessageType.Completion,
+			invocationId,
+			...error != null && { error },
+			...result != null && { result }
+		};
+	}
+	static ping() {
+		return { type: MessageType.Ping };
+	}
+};
+function isNonEmptyObject(v) {
+	return v !== null && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length > 0;
+}
+function parseInvocationId(value) {
+	if (typeof value !== "string") throw new Error("Invalid MessagePack message: invocationId must be a string.");
+	return toInvocationId(value);
+}
+function parseStreamIds(value) {
+	if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) throw new Error("Invalid MessagePack message: streamIds must be an array of strings.");
+	return value;
+}
+function parseHeaders(value) {
+	if (!isNonEmptyObject(value) || !Object.values(value).every((entry) => typeof entry === "string")) throw new Error("Invalid MessagePack message: headers must contain string values.");
+	return value;
+}
+//#endregion
+//#region src/ws-client.ts
+/**
+* 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
+*/
+let WebSocketReadyState = /* @__PURE__ */ function(WebSocketReadyState) {
+	WebSocketReadyState[WebSocketReadyState["Connecting"] = 0] = "Connecting";
+	WebSocketReadyState[WebSocketReadyState["Open"] = 1] = "Open";
+	WebSocketReadyState[WebSocketReadyState["Closing"] = 2] = "Closing";
+	WebSocketReadyState[WebSocketReadyState["Closed"] = 3] = "Closed";
+	return WebSocketReadyState;
+}({});
+const WS_MAGIC = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+var WebSocketClient = class extends EventEmitter {
+	#socket = null;
+	#state = 3;
+	#frameBuf = Buffer.alloc(0);
+	#fragments = [];
+	#fragmentOpcode = null;
+	#handshakeBuf = Buffer.alloc(0);
+	#handshakeResolve = null;
+	#handshakeReject = null;
+	get readyState() {
+		return this.#state;
+	}
+	/**
+	* Open a WebSocket connection.
+	* @param url      ws:// or wss:// URL
+	* @param headers  Extra HTTP headers for the upgrade request
+	*/
+	connect(url, headers = {}) {
+		return new Promise((resolve, reject) => {
+			if (this.#state !== 3) {
+				reject(/* @__PURE__ */ new Error("WebSocket is already open or connecting."));
+				return;
+			}
+			this.#state = 0;
+			this.#handshakeResolve = resolve;
+			this.#handshakeReject = reject;
+			const parsed = new URL(url);
+			const isSecure = parsed.protocol === "wss:";
+			const host = parsed.hostname;
+			const port = Number(parsed.port) || (isSecure ? 443 : 80);
+			/* istanbul ignore next -- URL normalizes an empty pathname to '/' */
+			const resource = (parsed.pathname || "/") + (parsed.search || "");
+			const portSuffix = parsed.port ? `:${parsed.port}` : "";
+			const nonce = crypto.randomBytes(16).toString("base64");
+			const expected = computeAccept(nonce);
+			const request = [
+				`GET ${resource} HTTP/1.1`,
+				`Host: ${host}${portSuffix}`,
+				"Upgrade: websocket",
+				"Connection: Upgrade",
+				`Sec-WebSocket-Key: ${nonce}`,
+				"Sec-WebSocket-Version: 13",
+				...Object.entries(headers).map(([k, v]) => `${k}: ${v}`),
+				"",
+				""
+			].join("\r\n");
+			const onSocketData = (chunk) => {
+				this.#onHandshakeData(chunk, expected);
+			};
+			const socketOpts = {
+				host,
+				port
+			};
+			if (isSecure) this.#socket = tls.connect(
+				{
+					...socketOpts,
+					servername: host
+				},
+				/* istanbul ignore next -- identical write callback is covered via TCP */
+				() => {
+					this.#socket.write(request);
+				}
+			);
+			else this.#socket = net.connect(socketOpts, () => {
+				this.#socket.write(request);
+			});
+			this.#socket.on("data", onSocketData);
+			this.#socket.on("error", (err) => {
+				if (this.#state === 0) {
+					this.#state = 3;
+					this.#handshakeReject(err);
+				} else if (this.#state !== 2) this.emit("error", err);
+			});
+			this.#socket.on("close", () => this.#onSocketClose());
+			this.#socket.on("end", () => this.#socket?.destroy());
+		});
+	}
+	/**
+	* Send a text or binary message.
+	* @throws if the socket is not open.
+	*/
+	send(data) {
+		if (this.#state !== 1) throw new Error("WebSocket is not open.");
+		if (typeof data === "string") this.#writeFrame(1, Buffer.from(data, "utf8"));
+		else this.#writeFrame(2, Buffer.isBuffer(data) ? data : Buffer.from(data));
+	}
+	/**
+	* 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 = 1e3, reason = "") {
+		if (this.#state !== 1) return;
+		this.#state = 2;
+		const reasonBuf = Buffer.from(reason, "utf8");
+		const payload = Buffer.allocUnsafe(2 + reasonBuf.length);
+		payload.writeUInt16BE(code, 0);
+		reasonBuf.copy(payload, 2);
+		this.#writeFrame(8, payload);
+	}
+	#onHandshakeData(chunk, expectedAccept) {
+		this.#handshakeBuf = Buffer.concat([this.#handshakeBuf, chunk]);
+		const idx = indexOfCRLFCRLF(this.#handshakeBuf);
+		if (idx === -1) return;
+		const headerStr = this.#handshakeBuf.subarray(0, idx).toString("ascii");
+		const remainder = this.#handshakeBuf.subarray(idx + 4);
+		const lines = headerStr.split("\r\n");
+		/* istanbul ignore next -- split() always returns at least one element */
+		const statusLine = lines[0] ?? "";
+		if (!statusLine.includes("101")) {
+			this.#failHandshake(/* @__PURE__ */ new Error(`WebSocket upgrade failed - server replied: ${statusLine}`));
+			return;
+		}
+		let accept = "";
+		for (let i = 1; i < lines.length; i++) {
+			const line = lines[i];
+			const colon = line.indexOf(":");
+			if (colon === -1) continue;
+			if (line.slice(0, colon).trim().toLowerCase() === "sec-websocket-accept") {
+				accept = line.slice(colon + 1).trim();
+				break;
+			}
+		}
+		if (accept !== expectedAccept) {
+			this.#failHandshake(/* @__PURE__ */ new Error(`Invalid Sec-WebSocket-Accept (got "${accept}", expected "${expectedAccept}")`));
+			return;
+		}
+		this.#state = 1;
+		this.#handshakeBuf = Buffer.alloc(0);
+		this.#socket.removeAllListeners("data");
+		this.#socket.on("data", (c) => this.#onFrameData(c));
+		const r = this.#handshakeResolve;
+		this.#handshakeResolve = null;
+		this.#handshakeReject = null;
+		r();
+		this.emit("open");
+		if (remainder.length > 0) this.#onFrameData(remainder);
+	}
+	#failHandshake(err) {
+		this.#state = 3;
+		this.#socket?.destroy();
+		const r = this.#handshakeReject;
+		this.#handshakeResolve = null;
+		this.#handshakeReject = null;
+		r(err);
+	}
+	#onFrameData(chunk) {
+		this.#frameBuf = Buffer.concat([this.#frameBuf, chunk]);
+		this.#drainFrames();
+	}
+	#drainFrames() {
+		for (;;) {
+			const result = tryParseFrame(this.#frameBuf);
+			if (!result) break;
+			this.#frameBuf = this.#frameBuf.subarray(result.consumed);
+			this.#dispatchFrame(result.frame);
+		}
+	}
+	#dispatchFrame({ fin, opcode, payload }) {
+		switch (opcode) {
+			case 1:
+			case 2:
+				if (!fin) {
+					this.#fragmentOpcode = opcode;
+					this.#fragments = [payload];
+				} else this.#emitData(opcode, payload);
+				break;
+			case 0:
+				this.#fragments.push(payload);
+				if (fin) {
+					const full = Buffer.concat(this.#fragments);
+					const op = this.#fragmentOpcode;
+					this.#fragments = [];
+					this.#fragmentOpcode = null;
+					this.#emitData(op, full);
+				}
+				break;
+			case 9:
+				this.#writeFrame(10, payload);
+				this.emit("ping", payload);
+				break;
+			case 10:
+				this.emit("pong", payload);
+				break;
+			case 8:
+				if (this.#state === 1) this.#writeFrame(8, payload);
+				this.#state = 3;
+				this.#socket?.destroy();
+				this.emit("close");
+				break;
+			default: break;
+		}
+	}
+	#emitData(opcode, payload) {
+		if (opcode === 1) this.emit("message", payload.toString("utf8"));
+		else this.emit("binary", payload);
+	}
+	/**
+	* Encode and send one WebSocket frame.
+	* All client→server frames MUST be masked (RFC 6455 §5.3).
+	*/
+	#writeFrame(opcode, payload) {
+		/* istanbul ignore next -- public methods validate state before writing */
+		if (!this.#socket || this.#socket.destroyed) return;
+		const len = payload.length;
+		let header;
+		if (len < 126) {
+			header = Buffer.allocUnsafe(2);
+			header[1] = 128 | len;
+		} else if (len < 65536) {
+			header = Buffer.allocUnsafe(4);
+			header[1] = 254;
+			header.writeUInt16BE(len, 2);
+		} else {
+			header = Buffer.allocUnsafe(10);
+			header[1] = 255;
+			header.writeUInt32BE(0, 2);
+			header.writeUInt32BE(len, 6);
+		}
+		header[0] = 128 | opcode;
+		const maskKey = crypto.randomBytes(4);
+		const maskedPayload = Buffer.allocUnsafe(len);
+		for (let i = 0; i < len; i++) maskedPayload[i] = payload[i] ^ maskKey[i % 4];
+		this.#socket.write(Buffer.concat([
+			header,
+			maskKey,
+			maskedPayload
+		]));
+	}
+	#onSocketClose() {
+		if (this.#state !== 3) {
+			this.#state = 3;
+			this.emit("close");
+		}
+	}
+};
+function computeAccept(key) {
+	return crypto.createHash("sha1").update(key + WS_MAGIC).digest("base64");
+}
+function indexOfCRLFCRLF(buf) {
+	for (let i = 0; i <= buf.length - 4; i++) if (buf[i] === 13 && buf[i + 1] === 10 && buf[i + 2] === 13 && buf[i + 3] === 10) return i;
+	return -1;
+}
+function tryParseFrame(buf) {
+	if (buf.length < 2) return null;
+	const b0 = buf[0];
+	const b1 = buf[1];
+	const fin = (b0 & 128) !== 0;
+	const opcode = b0 & 15;
+	const masked = (b1 & 128) !== 0;
+	let payLen = b1 & 127;
+	let offset = 2;
+	if (payLen === 126) {
+		if (buf.length < offset + 2) return null;
+		payLen = buf.readUInt16BE(offset);
+		offset += 2;
+	} else if (payLen === 127) {
+		if (buf.length < offset + 8) return null;
+		/* istanbul ignore next -- allocating a >4 GB test frame is impractical */
+		if (buf.readUInt32BE(offset) !== 0) throw new Error("Received a frame with payload > 4 GB - not supported.");
+		payLen = buf.readUInt32BE(offset + 4);
+		offset += 8;
+	}
+	let maskBytes = null;
+	if (masked) {
+		if (buf.length < offset + 4) return null;
+		maskBytes = buf.subarray(offset, offset + 4);
+		offset += 4;
+	}
+	if (buf.length < offset + payLen) return null;
+	let payload = buf.subarray(offset, offset + payLen);
+	if (masked && maskBytes !== null) {
+		payload = Buffer.from(payload);
+		for (let i = 0; i < payload.length; i++) payload[i] = payload[i] ^ maskBytes[i % 4];
+	}
+	return {
+		frame: {
+			fin,
+			opcode,
+			payload
+		},
+		consumed: offset + payLen
+	};
+}
+//#endregion
+export { AbortError, ConsoleLogger, CookieAgent, CookieJar, DEFAULT_PING_INTERVAL_IN_MS, DEFAULT_SERVER_TIMEOUT_IN_MS, DEFAULT_TIMEOUT_IN_MS, DefaultReconnectPolicy, DispatchHttpClient, DispatchHttpClient as HttpClient, FetchHttpClient, HANDSHAKE_REQUEST, HandshakeError, HttpTransportType, HubConnection, HubConnectionBuilder, HubConnectionState, HubError, JsonHubProtocol, LogLevel, LongPollingTransport, HANDSHAKE_REQUEST$1 as MSGPACK_HANDSHAKE_REQUEST, MessageType, MsgpackHubProtocol, NEGOTIATE_VERSION, NullLogger, PipelineHttpClient, RECORD_SEPARATOR, RequestHttpClient, ServerSentEventsTransport, StreamHttpClient, TransferFormat, TransportError, UnsupportedTransportError, WebSocketClient, WebSocketReadyState, WebSocketTransport, assertNever, cookie, isAbortError, isCancelInvocationMessage, isCloseMessage, isCompletionMessage, isHubError, isInvocationMessage, isPingMessage, isStreamInvocationMessage, isStreamItemMessage, isTransportError, parseHandshakeResponse, toInvocationId };
+
+//# sourceMappingURL=index.mjs.map