redweb-client 0.1.0

package/dist/index.cjs

@@ -0,0 +1,522 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ERROR_CODES: () => ERROR_CODES,
+  RedwebClient: () => RedwebClient,
+  RedwebProtocolError: () => RedwebProtocolError,
+  createLegacyEnvelope: () => createLegacyEnvelope,
+  createProtocolEnvelope: () => createProtocolEnvelope,
+  parseMessage: () => parseMessage,
+  resolveWebSocketUrl: () => resolveWebSocketUrl
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/protocol.ts
+var ERROR_CODES = Object.freeze({
+  INVALID_MESSAGE: "INVALID_MESSAGE",
+  UNKNOWN_HANDLER: "UNKNOWN_HANDLER",
+  HANDLER_FAILED: "HANDLER_FAILED",
+  BINARY_UNSUPPORTED: "BINARY_UNSUPPORTED",
+  RATE_LIMITED: "RATE_LIMITED",
+  QUEUE_FULL: "QUEUE_FULL",
+  CAPACITY_REACHED: "CAPACITY_REACHED",
+  INITIALIZATION_FAILED: "INITIALIZATION_FAILED"
+});
+function boundedString(value, name, maxLength) {
+  if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+    throw new TypeError(`${name} must be a non-empty string of at most ${maxLength} characters.`);
+  }
+  return value;
+}
+function validateMetadata(metadata) {
+  if (metadata.requestId !== void 0) boundedString(metadata.requestId, "requestId", 256);
+  if (metadata.sequence !== void 0 && (!Number.isSafeInteger(metadata.sequence) || metadata.sequence < 0)) {
+    throw new TypeError("sequence must be a non-negative safe integer.");
+  }
+}
+function createProtocolEnvelope(version, type, payload, metadata = {}) {
+  validateMetadata(metadata);
+  return {
+    v: boundedString(version, "version", 64),
+    type: boundedString(type, "type", 256),
+    payload,
+    ...metadata
+  };
+}
+function createLegacyEnvelope(type, payload, metadata = {}) {
+  validateMetadata(metadata);
+  const checkedType = boundedString(type, "type", 256);
+  if (payload !== null && typeof payload === "object" && !Array.isArray(payload)) {
+    return { ...payload, type: checkedType, ...metadata };
+  }
+  return { type: checkedType, payload, ...metadata };
+}
+function parseMessage(input, version) {
+  const value = typeof input === "string" ? JSON.parse(input) : input;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("Received an invalid Redweb message.");
+  }
+  const message = value;
+  if (message.requestId !== void 0) boundedString(message.requestId, "requestId", 256);
+  if (message.sequence !== void 0 && (!Number.isSafeInteger(message.sequence) || message.sequence < 0)) {
+    throw new TypeError("sequence must be a non-negative safe integer.");
+  }
+  if (version !== void 0) {
+    boundedString(message.type, "type", 256);
+    if (message.v !== version) throw new TypeError("Received a Redweb message for a different protocol version.");
+    if (message.type === "error") {
+      if (Object.prototype.hasOwnProperty.call(message, "payload")) {
+        throw new TypeError("Received an invalid Redweb protocol error.");
+      }
+      const error = message.error;
+      if (!error || typeof error !== "object") {
+        throw new TypeError("Received an invalid Redweb protocol error.");
+      }
+      boundedString(error.code, "error.code", 256);
+      boundedString(error.message, "error.message", 1024);
+    } else {
+      if (!Object.prototype.hasOwnProperty.call(message, "payload") || message.error !== void 0) {
+        throw new TypeError("Received an invalid Redweb protocol envelope.");
+      }
+    }
+  } else if (typeof message.type === "string") {
+    boundedString(message.type, "type", 256);
+  } else if (typeof message.error !== "string") {
+    throw new TypeError("Received an invalid Redweb message.");
+  }
+  return message;
+}
+function resolveWebSocketUrl(input, base) {
+  const fallbackBase = base ?? (typeof globalThis.location === "object" ? globalThis.location.href : void 0);
+  let url;
+  try {
+    url = fallbackBase === void 0 ? new URL(input) : new URL(input, fallbackBase);
+  } catch {
+    throw new TypeError("url must be an absolute ws:/wss: URL or resolvable against baseUrl/location.");
+  }
+  if (url.protocol === "http:") url.protocol = "ws:";
+  if (url.protocol === "https:") url.protocol = "wss:";
+  if (url.protocol !== "ws:" && url.protocol !== "wss:") throw new TypeError("url must use ws: or wss:.");
+  return url.toString();
+}
+var RedwebProtocolError = class extends Error {
+  code;
+  envelope;
+  constructor(envelope) {
+    super(envelope.error.message);
+    this.name = "RedwebProtocolError";
+    this.code = envelope.error.code;
+    this.envelope = envelope;
+  }
+};
+
+// src/client.ts
+var OPEN = 1;
+var CONNECTING = 0;
+var defaultReconnect = {
+  enabled: false,
+  maxAttempts: 8,
+  initialDelayMs: 250,
+  maxDelayMs: 1e4,
+  factor: 2,
+  jitter: 0.2,
+  shouldReconnect: (event) => event.code !== 1e3 && event.code !== 1008
+};
+function defaultFactory(url) {
+  if (typeof globalThis.WebSocket !== "function") {
+    throw new Error("WebSocket is unavailable; provide webSocketFactory outside a browser.");
+  }
+  return new globalThis.WebSocket(url);
+}
+function toError(value, fallback) {
+  return value instanceof Error ? value : new Error(fallback);
+}
+function assertNonNegativeInteger(value, name) {
+  if (!Number.isInteger(value) || value < 0) throw new TypeError(`${name} must be a non-negative integer.`);
+}
+var RedwebClient = class {
+  url;
+  version;
+  state = "idle";
+  socket;
+  factory;
+  reconnect;
+  maxQueueSize;
+  requestTimeoutMs;
+  createRequestId;
+  random;
+  listeners = /* @__PURE__ */ new Map();
+  anyListeners = /* @__PURE__ */ new Set();
+  binaryListeners = /* @__PURE__ */ new Set();
+  errorListeners = /* @__PURE__ */ new Set();
+  stateListeners = /* @__PURE__ */ new Set();
+  closeListeners = /* @__PURE__ */ new Set();
+  queue = [];
+  pending = /* @__PURE__ */ new Map();
+  connectPromise;
+  reconnectTimer;
+  reconnectAttempts = 0;
+  manualClose = false;
+  disposed = false;
+  requestSequence = 0;
+  constructor(url, options = {}) {
+    this.url = resolveWebSocketUrl(url, options.baseUrl);
+    const queryVersion = new URL(this.url).searchParams.get("redwebVersion") ?? void 0;
+    if (options.version !== void 0 && queryVersion !== void 0 && options.version !== queryVersion) {
+      throw new TypeError("options.version conflicts with the redwebVersion URL query.");
+    }
+    this.version = options.version ?? queryVersion;
+    if (this.version !== void 0) createProtocolEnvelope(this.version, "validation", null);
+    this.factory = options.webSocketFactory ?? defaultFactory;
+    this.reconnect = { ...defaultReconnect, ...options.reconnect };
+    this.maxQueueSize = options.maxQueueSize ?? 0;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 1e4;
+    this.createRequestId = options.createRequestId ?? (() => {
+      this.requestSequence += 1;
+      return `${Date.now().toString(36)}-${this.requestSequence.toString(36)}`;
+    });
+    this.random = options.random ?? Math.random;
+    assertNonNegativeInteger(this.maxQueueSize, "maxQueueSize");
+    assertNonNegativeInteger(this.requestTimeoutMs, "requestTimeoutMs");
+    assertNonNegativeInteger(this.reconnect.maxAttempts, "reconnect.maxAttempts");
+    assertNonNegativeInteger(this.reconnect.initialDelayMs, "reconnect.initialDelayMs");
+    assertNonNegativeInteger(this.reconnect.maxDelayMs, "reconnect.maxDelayMs");
+    if (!Number.isFinite(this.reconnect.factor) || this.reconnect.factor < 1) {
+      throw new TypeError("reconnect.factor must be a finite number of at least 1.");
+    }
+    if (!Number.isFinite(this.reconnect.jitter) || this.reconnect.jitter < 0 || this.reconnect.jitter > 1) {
+      throw new TypeError("reconnect.jitter must be between 0 and 1.");
+    }
+  }
+  connect() {
+    if (this.disposed) return Promise.reject(new Error("RedwebClient has been disposed."));
+    if (this.state === "open") return Promise.resolve();
+    if (this.connectPromise) return this.connectPromise;
+    this.manualClose = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = void 0;
+    }
+    this.connectPromise = this.openSocket(false).finally(() => {
+      this.connectPromise = void 0;
+    });
+    return this.connectPromise;
+  }
+  openSocket(reconnecting) {
+    this.transition(reconnecting ? "reconnecting" : "connecting");
+    let socket;
+    try {
+      socket = this.factory(this.connectionUrl());
+    } catch (error) {
+      this.transition("closed");
+      if (reconnecting && !this.manualClose) this.scheduleReconnect();
+      return Promise.reject(toError(error, "Unable to create WebSocket."));
+    }
+    this.socket = socket;
+    if ("binaryType" in socket) socket.binaryType = "arraybuffer";
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const onOpen = () => {
+        if (this.socket !== socket) {
+          if (!settled) reject(new Error("WebSocket connection attempt was superseded."));
+          socket.close(1e3, "Superseded");
+          return;
+        }
+        settled = true;
+        this.reconnectAttempts = 0;
+        this.transition("open");
+        this.flushQueue();
+        resolve();
+      };
+      const onMessage = (event) => {
+        if (this.socket === socket) void this.handleIncoming(event.data);
+      };
+      const onError = (event) => {
+        if (this.socket !== socket) return;
+        const error = toError(event.error, "WebSocket connection failed.");
+        this.emitError(error);
+      };
+      const onClose = (event) => {
+        socket.removeEventListener("open", onOpen);
+        socket.removeEventListener("message", onMessage);
+        socket.removeEventListener("error", onError);
+        socket.removeEventListener("close", onClose);
+        if (this.socket !== socket) {
+          if (!settled) reject(new Error("WebSocket connection attempt was superseded."));
+          return;
+        }
+        this.socket = void 0;
+        if (!settled) {
+          settled = true;
+          reject(new Error("WebSocket closed before opening."));
+        }
+        this.rejectPending(new Error("WebSocket connection closed."));
+        this.transition("closed");
+        this.notify(this.closeListeners, event);
+        if (!this.manualClose && this.reconnect.shouldReconnect(event)) this.scheduleReconnect();
+      };
+      socket.addEventListener("open", onOpen);
+      socket.addEventListener("message", onMessage);
+      socket.addEventListener("error", onError);
+      socket.addEventListener("close", onClose);
+    });
+  }
+  close(code = 1e3, reason = "Client closed") {
+    this.manualClose = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = void 0;
+    }
+    this.rejectPending(new Error("Client closed."));
+    this.queue.length = 0;
+    const socket = this.socket;
+    if (socket && (socket.readyState === OPEN || socket.readyState === CONNECTING)) {
+      this.transition("closing");
+      socket.close(code, reason);
+    } else {
+      this.transition("closed");
+    }
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.close(1e3, "Client disposed");
+    this.queue.length = 0;
+    this.listeners.clear();
+    this.anyListeners.clear();
+    this.binaryListeners.clear();
+    this.errorListeners.clear();
+    this.stateListeners.clear();
+    this.closeListeners.clear();
+  }
+  send(type, payload, metadata = {}) {
+    const envelope = this.version ? createProtocolEnvelope(this.version, type, payload, metadata) : createLegacyEnvelope(type, payload, metadata);
+    this.transmit(JSON.stringify(envelope));
+  }
+  sendRaw(data) {
+    this.transmit(data);
+  }
+  transmit(data, requestId) {
+    if (this.socket?.readyState === OPEN) {
+      this.socket.send(data);
+      return;
+    }
+    if (this.queue.length >= this.maxQueueSize) {
+      throw new Error(this.maxQueueSize === 0 ? "WebSocket is not open." : "Outbound message queue is full.");
+    }
+    this.queue.push(requestId === void 0 ? { data } : { data, requestId });
+  }
+  request(type, payload, options = {}) {
+    const requestId = options.requestId ?? this.createRequestId();
+    const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+    assertNonNegativeInteger(timeoutMs, "timeoutMs");
+    if (options.signal?.aborted) return Promise.reject(new DOMException("The request was aborted.", "AbortError"));
+    if (this.pending.has(requestId)) return Promise.reject(new Error(`A Redweb request with id "${requestId}" is already pending.`));
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.finishPending(requestId);
+        reject(new Error(`Redweb request timed out after ${timeoutMs}ms.`));
+      }, timeoutMs);
+      const pending = { resolve, reject, timer };
+      if (options.signal) {
+        pending.signal = options.signal;
+        pending.abort = () => {
+          this.finishPending(requestId);
+          reject(new DOMException("The request was aborted.", "AbortError"));
+        };
+        options.signal.addEventListener("abort", pending.abort, { once: true });
+      }
+      this.pending.set(requestId, pending);
+      try {
+        const metadata = { requestId, ...options.sequence === void 0 ? {} : { sequence: options.sequence } };
+        const envelope = this.version ? createProtocolEnvelope(this.version, type, payload, metadata) : createLegacyEnvelope(type, payload, metadata);
+        this.transmit(JSON.stringify(envelope), requestId);
+      } catch (error) {
+        this.finishPending(requestId);
+        reject(toError(error, "Unable to send Redweb request."));
+      }
+    });
+  }
+  waitFor(type, options = {}) {
+    const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+    assertNonNegativeInteger(timeoutMs, "timeoutMs");
+    if (options.signal?.aborted) return Promise.reject(new DOMException("The wait was aborted.", "AbortError"));
+    return new Promise((resolve, reject) => {
+      const off = this.on(type, (message) => {
+        cleanup();
+        resolve(message);
+      });
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Timed out waiting for Redweb message "${type}" after ${timeoutMs}ms.`));
+      }, timeoutMs);
+      const abort = () => {
+        cleanup();
+        reject(new DOMException("The wait was aborted.", "AbortError"));
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        off();
+        options.signal?.removeEventListener("abort", abort);
+      };
+      options.signal?.addEventListener("abort", abort, { once: true });
+    });
+  }
+  on(type, listener) {
+    let group = this.listeners.get(type);
+    if (!group) {
+      group = /* @__PURE__ */ new Set();
+      this.listeners.set(type, group);
+    }
+    group.add(listener);
+    return () => {
+      group?.delete(listener);
+      if (group?.size === 0) this.listeners.delete(type);
+    };
+  }
+  onAny(listener) {
+    return this.subscribe(this.anyListeners, listener);
+  }
+  onBinary(listener) {
+    return this.subscribe(this.binaryListeners, listener);
+  }
+  onError(listener) {
+    return this.subscribe(this.errorListeners, listener);
+  }
+  onStateChange(listener) {
+    return this.subscribe(this.stateListeners, listener);
+  }
+  onClose(listener) {
+    return this.subscribe(this.closeListeners, listener);
+  }
+  subscribe(set, listener) {
+    set.add(listener);
+    return () => {
+      set.delete(listener);
+    };
+  }
+  connectionUrl() {
+    const url = new URL(this.url);
+    if (this.version && !url.searchParams.has("redwebVersion")) url.searchParams.set("redwebVersion", this.version);
+    return url.toString();
+  }
+  transition(state) {
+    if (this.state === state) return;
+    this.state = state;
+    this.notify(this.stateListeners, state);
+  }
+  async handleIncoming(data) {
+    if (typeof data !== "string") {
+      if (data instanceof Blob || data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+        this.notify(this.binaryListeners, data);
+        return;
+      }
+      this.emitError(new TypeError("Received an unsupported WebSocket message type."));
+      return;
+    }
+    let message;
+    try {
+      message = parseMessage(data, this.version);
+    } catch (error) {
+      this.emitError(toError(error, "Unable to parse Redweb message."));
+      return;
+    }
+    const requestId = message.requestId;
+    if (typeof requestId === "string") {
+      const pending = this.pending.get(requestId);
+      if (pending) {
+        this.finishPending(requestId);
+        if (message.type === "error" && "error" in message) pending.reject(new RedwebProtocolError(message));
+        else pending.resolve(message);
+      }
+    }
+    const messageType = "type" in message && typeof message.type === "string" ? message.type : "error";
+    const group = this.listeners.get(messageType);
+    if (group) this.notify(group, message);
+    this.notify(this.anyListeners, message);
+  }
+  finishPending(requestId) {
+    const pending = this.pending.get(requestId);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    if (pending.signal && pending.abort) pending.signal.removeEventListener("abort", pending.abort);
+    this.pending.delete(requestId);
+    for (let index = this.queue.length - 1; index >= 0; index -= 1) {
+      if (this.queue[index]?.requestId === requestId) this.queue.splice(index, 1);
+    }
+  }
+  rejectPending(error) {
+    for (const [requestId, pending] of this.pending) {
+      this.finishPending(requestId);
+      pending.reject(error);
+    }
+  }
+  emitError(error) {
+    for (const listener of this.errorListeners) {
+      try {
+        listener(error);
+      } catch {
+      }
+    }
+  }
+  notify(listeners, value) {
+    for (const listener of listeners) {
+      try {
+        listener(value);
+      } catch (error) {
+        this.emitError(toError(error, "Redweb listener failed."));
+      }
+    }
+  }
+  flushQueue() {
+    while (this.socket?.readyState === OPEN && this.queue.length > 0) {
+      const entry = this.queue.shift();
+      if (entry !== void 0) this.socket.send(entry.data);
+    }
+  }
+  scheduleReconnect() {
+    if (this.disposed || !this.reconnect.enabled || this.reconnectAttempts >= this.reconnect.maxAttempts) return;
+    const baseDelay = Math.min(
+      this.reconnect.maxDelayMs,
+      this.reconnect.initialDelayMs * this.reconnect.factor ** this.reconnectAttempts
+    );
+    const spread = baseDelay * this.reconnect.jitter;
+    const delay = Math.max(0, Math.round(baseDelay - spread + this.random() * spread * 2));
+    this.reconnectAttempts += 1;
+    this.transition("reconnecting");
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = void 0;
+      void this.openSocket(true).catch(() => {
+      });
+    }, delay);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ERROR_CODES,
+  RedwebClient,
+  RedwebProtocolError,
+  createLegacyEnvelope,
+  createProtocolEnvelope,
+  parseMessage,
+  resolveWebSocketUrl
+});

package/dist/index.d.cts

@@ -0,0 +1,149 @@
+type ClientState = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closing' | 'closed';
+interface ProtocolMetadata {
+    requestId?: string;
+    sequence?: number;
+}
+interface ProtocolEnvelope<T = unknown> extends ProtocolMetadata {
+    v: string;
+    type: string;
+    payload: T;
+}
+interface ProtocolErrorEnvelope extends ProtocolMetadata {
+    v: string;
+    type: 'error';
+    error: {
+        code: string;
+        message: string;
+    };
+}
+interface LegacyErrorMessage extends ProtocolMetadata {
+    error: string;
+    type?: never;
+}
+type RedwebMessage<T = unknown> = ProtocolEnvelope<T> | ProtocolErrorEnvelope | LegacyErrorMessage | ({
+    type: string;
+    requestId?: string;
+    sequence?: number;
+} & Record<string, unknown>);
+interface SocketEventLike {
+    data?: unknown;
+    code?: number;
+    reason?: string;
+    wasClean?: boolean;
+    error?: unknown;
+}
+interface WebSocketLike {
+    readonly readyState: number;
+    binaryType?: string;
+    send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open' | 'message' | 'error' | 'close', listener: (event: SocketEventLike) => void): void;
+    removeEventListener(type: 'open' | 'message' | 'error' | 'close', listener: (event: SocketEventLike) => void): void;
+}
+interface ReconnectOptions {
+    enabled?: boolean;
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    factor?: number;
+    jitter?: number;
+    shouldReconnect?: (event: SocketEventLike) => boolean;
+}
+interface RedwebClientOptions {
+    version?: string;
+    reconnect?: ReconnectOptions;
+    maxQueueSize?: number;
+    requestTimeoutMs?: number;
+    webSocketFactory?: (url: string) => WebSocketLike;
+    createRequestId?: () => string;
+    baseUrl?: string | URL;
+    random?: () => number;
+}
+interface RequestOptions extends ProtocolMetadata {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+interface WaitOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+type MessageListener<T = unknown> = (message: RedwebMessage<T>) => void;
+type BinaryListener = (data: ArrayBuffer | ArrayBufferView | Blob) => void;
+type ErrorListener = (error: Error) => void;
+type StateListener = (state: ClientState) => void;
+type CloseListener = (event: SocketEventLike) => void;
+
+declare class RedwebClient<IncomingEvents extends object = Record<string, unknown>, OutgoingEvents extends object = Record<string, unknown>> {
+    readonly url: string;
+    readonly version: string | undefined;
+    state: ClientState;
+    socket: WebSocketLike | undefined;
+    private readonly factory;
+    private readonly reconnect;
+    private readonly maxQueueSize;
+    private readonly requestTimeoutMs;
+    private readonly createRequestId;
+    private readonly random;
+    private readonly listeners;
+    private readonly anyListeners;
+    private readonly binaryListeners;
+    private readonly errorListeners;
+    private readonly stateListeners;
+    private readonly closeListeners;
+    private readonly queue;
+    private readonly pending;
+    private connectPromise;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private manualClose;
+    private disposed;
+    private requestSequence;
+    constructor(url: string, options?: RedwebClientOptions);
+    connect(): Promise<void>;
+    private openSocket;
+    close(code?: number, reason?: string): void;
+    dispose(): void;
+    send<K extends keyof OutgoingEvents & string>(type: K, payload: OutgoingEvents[K], metadata?: ProtocolMetadata): void;
+    sendRaw(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+    private transmit;
+    request<TResponse = unknown, TPayload = unknown>(type: string, payload: TPayload, options?: RequestOptions): Promise<RedwebMessage<TResponse>>;
+    waitFor<K extends keyof IncomingEvents & string>(type: K, options?: WaitOptions): Promise<RedwebMessage<IncomingEvents[K]>>;
+    on<K extends keyof IncomingEvents & string>(type: K, listener: MessageListener<IncomingEvents[K]>): () => void;
+    onAny(listener: MessageListener): () => void;
+    onBinary(listener: BinaryListener): () => void;
+    onError(listener: ErrorListener): () => void;
+    onStateChange(listener: StateListener): () => void;
+    onClose(listener: CloseListener): () => void;
+    private subscribe;
+    private connectionUrl;
+    private transition;
+    private handleIncoming;
+    private finishPending;
+    private rejectPending;
+    private emitError;
+    private notify;
+    private flushQueue;
+    private scheduleReconnect;
+}
+
+declare const ERROR_CODES: Readonly<{
+    readonly INVALID_MESSAGE: "INVALID_MESSAGE";
+    readonly UNKNOWN_HANDLER: "UNKNOWN_HANDLER";
+    readonly HANDLER_FAILED: "HANDLER_FAILED";
+    readonly BINARY_UNSUPPORTED: "BINARY_UNSUPPORTED";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly QUEUE_FULL: "QUEUE_FULL";
+    readonly CAPACITY_REACHED: "CAPACITY_REACHED";
+    readonly INITIALIZATION_FAILED: "INITIALIZATION_FAILED";
+}>;
+declare function createProtocolEnvelope<T>(version: string, type: string, payload: T, metadata?: ProtocolMetadata): ProtocolEnvelope<T>;
+declare function createLegacyEnvelope<T>(type: string, payload: T, metadata?: ProtocolMetadata): RedwebMessage<T>;
+declare function parseMessage(input: unknown, version?: string): RedwebMessage;
+declare function resolveWebSocketUrl(input: string | URL, base?: string | URL): string;
+declare class RedwebProtocolError extends Error {
+    readonly code: string;
+    readonly envelope: ProtocolErrorEnvelope;
+    constructor(envelope: ProtocolErrorEnvelope);
+}
+
+export { type BinaryListener, type ClientState, type CloseListener, ERROR_CODES, type ErrorListener, type LegacyErrorMessage, type MessageListener, type ProtocolEnvelope, type ProtocolErrorEnvelope, type ProtocolMetadata, type ReconnectOptions, RedwebClient, type RedwebClientOptions, type RedwebMessage, RedwebProtocolError, type RequestOptions, type SocketEventLike, type StateListener, type WaitOptions, type WebSocketLike, createLegacyEnvelope, createProtocolEnvelope, parseMessage, resolveWebSocketUrl };