@laplace.live/ws 7.0.0 → 7.0.2

package/dist/index.d.ts

@@ -1,16 +1,44 @@
-import { L as Live, I as Inflates, a as LiveOptions, K as KeepLive, b as LiveWSBase, W as WSOptions } from './ws-DVInVzNN.js';
-export { D as DataEvent, E as EventEvent } from './ws-DVInVzNN.js';
+import { L as Live, I as Inflates, a as LiveOptions, K as KeepLive, b as LiveWSBase, W as WSOptions } from './ws-D63GKJdI.js';
+export { c as LaplaceRawEvent } from './ws-D63GKJdI.js';
 import { Socket } from 'node:net';
 
+/**
+ * Configuration options for TCP-based live connections.
+ * Extends {@link LiveOptions} with optional host and port overrides.
+ */
 type TCPOptions = LiveOptions & {
+    /** TCP server hostname. Defaults to `broadcastlv.chat.bilibili.com`. */
     host?: string;
+    /** TCP server port. Defaults to `2243`. */
     port?: number;
 };
+/**
+ * TCP transport for Bilibili live room connections.
+ *
+ * Wraps a Node.js TCP {@link Socket}, handling packet reassembly from the
+ * stream and forwarding complete frames into the {@link Live} event system.
+ *
+ * Not typically instantiated directly — use {@link LiveTCP} which injects
+ * the Node.js inflate implementation.
+ *
+ * @param inflates - Platform-specific inflate/brotli decompressors.
+ * @param roomid   - Numeric Bilibili live room ID.
+ * @param options  - TCP host/port and authentication options.
+ */
 declare class LiveTCPBase extends Live {
+    /** The underlying Node.js TCP socket. */
     socket: Socket;
+    /** @internal Accumulator for incomplete packets from the TCP stream. */
     buf: Buffer;
+    /** @internal Counter for periodic buffer compaction. */
     i: number;
     constructor(inflates: Inflates, roomid: number, { host, port, ...options }?: TCPOptions);
+    /**
+     * Extract complete packets from the internal buffer and dispatch them
+     * as `message` events. Compacts the buffer periodically to avoid
+     * unbounded memory growth from `Buffer.concat` / `slice` chains.
+     * @internal
+     */
     splitBuffer(): void;
 }
 
@@ -33,23 +61,121 @@ type GET_DANMU_INFO = {
         token: string;
     };
 };
+/**
+ * Fetch WebSocket connection configuration for a Bilibili live room directly
+ * from the Bilibili API (`getDanmuInfo`).
+ *
+ * **Note:** This endpoint is subject to Bilibili's risk-control system and
+ * may return error code `-352` when called without proper cookies or headers.
+ * For production use, consider proxying through an external service that
+ * handles authentication.
+ *
+ * @param roomid - Numeric Bilibili live room ID.
+ * @returns An object containing:
+ *   - `key` — authentication token for the WebSocket handshake
+ *   - `host` — hostname of the danmaku WebSocket server
+ *   - `address` — full `wss://` URL ready to pass as `WSOptions.address`
+ *   - `raw` — the complete API response for advanced use
+ * @throws {Error} If the API returns no data (e.g. invalid room or risk-control block).
+ */
 declare const getConf: (roomid: number) => Promise<{
     key: string;
     host: string;
     address: string;
     raw: GET_DANMU_INFO;
 }>;
+/**
+ * Resolve a short (vanity) room ID to its real numeric room ID via the
+ * Bilibili API.
+ *
+ * Short room IDs are custom aliases (e.g. `1`) that map to longer numeric
+ * IDs used internally by the live platform.
+ *
+ * @param short - The short or numeric room ID to resolve.
+ * @returns The canonical numeric room ID.
+ */
 declare const getRoomid: (short: number) => Promise<any>;
 
+/**
+ * WebSocket client for a Bilibili live room (Node.js / Bun).
+ *
+ * Uses `node:zlib` for inflate and brotli decompression.
+ *
+ * @param roomid - Numeric Bilibili live room ID.
+ * @param opts   - Optional WebSocket address and authentication options.
+ *
+ * @example
+ * ```ts
+ * import { LiveWS } from '@laplace.live/ws'
+ *
+ * const live = new LiveWS(12345, { key: '...', address: 'wss://...' })
+ * live.on('DANMU_MSG', (e) => console.log(e.data))
+ * ```
+ */
 declare class LiveWS extends LiveWSBase {
     constructor(roomid: number, opts?: WSOptions);
 }
+/**
+ * TCP client for a Bilibili live room (Node.js / Bun only).
+ *
+ * Uses `node:zlib` for inflate and brotli decompression, and `node:net`
+ * for the TCP transport.
+ *
+ * @param roomid - Numeric Bilibili live room ID.
+ * @param opts   - Optional TCP host/port and authentication options.
+ *
+ * @example
+ * ```ts
+ * import { LiveTCP } from '@laplace.live/ws'
+ *
+ * const live = new LiveTCP(12345, { key: '...' })
+ * live.on('heartbeat', (e) => console.log('online:', e.data))
+ * ```
+ */
 declare class LiveTCP extends LiveTCPBase {
     constructor(roomid: number, opts?: TCPOptions);
 }
+/**
+ * Auto-reconnecting WebSocket client for a Bilibili live room
+ * (Node.js / Bun).
+ *
+ * Wraps {@link LiveWS} with automatic reconnection on disconnect or
+ * heartbeat timeout. All events from the underlying connection are
+ * forwarded to this instance.
+ *
+ * @param roomid - Numeric Bilibili live room ID.
+ * @param opts   - Optional WebSocket address and authentication options.
+ *
+ * @example
+ * ```ts
+ * import { KeepLiveWS } from '@laplace.live/ws'
+ *
+ * const keep = new KeepLiveWS(12345, { key: '...' })
+ * keep.on('DANMU_MSG', (e) => console.log(e.data))
+ * ```
+ */
 declare class KeepLiveWS extends KeepLive<typeof LiveWSBase> {
     constructor(roomid: number, opts?: WSOptions);
 }
+/**
+ * Auto-reconnecting TCP client for a Bilibili live room
+ * (Node.js / Bun only).
+ *
+ * Wraps {@link LiveTCP} with automatic reconnection on disconnect or
+ * heartbeat timeout. All events from the underlying connection are
+ * forwarded to this instance.
+ *
+ * @param roomid - Numeric Bilibili live room ID.
+ * @param opts   - Optional TCP host/port and authentication options.
+ *
+ * @example
+ * ```ts
+ * import { KeepLiveTCP } from '@laplace.live/ws'
+ *
+ * const keep = new KeepLiveTCP(12345, { key: '...' })
+ * keep.on('heartbeat', (e) => console.log('online:', e.data))
+ * ```
+ */
 declare class KeepLiveTCP extends KeepLive<typeof LiveTCPBase> {
     constructor(roomid: number, opts?: TCPOptions);
 }

package/dist/index.js

@@ -1,3 +1,157 @@
+// src/inflate/node.ts
+import { promisify } from "util";
+import { brotliDecompress, inflate } from "zlib";
+var _inflate = promisify(inflate);
+var _brotli = promisify(brotliDecompress);
+var inflateAsync = (b) => _inflate(b);
+var brotliDecompressAsync = (b) => _brotli(b);
+var inflates = { inflateAsync, brotliDecompressAsync };
+
+// src/events.ts
+var LaplaceRawEvent = class extends Event {
+  data;
+  constructor(type, data) {
+    super(type);
+    this.data = data;
+  }
+};
+
+// src/keep-live.ts
+var KeepLive = class extends EventTarget {
+  /** @internal Stored constructor arguments for reconnection. */
+  params;
+  /** `true` after {@link close} has been called; prevents further reconnects. */
+  closed;
+  /** Delay in milliseconds before attempting a reconnect. */
+  interval;
+  /** Maximum milliseconds to wait for a heartbeat before forcing a reconnect. */
+  timeout;
+  /** The current underlying connection instance. */
+  connection;
+  /** @internal The base class constructor used to create new connections. */
+  Base;
+  constructor(Base, ...params) {
+    super();
+    this.params = params;
+    this.closed = false;
+    this.interval = 100;
+    this.timeout = 45 * 1e3;
+    this.connection = new Base(...this.params);
+    this.Base = Base;
+    this.connect(false);
+  }
+  /**
+   * Overridden to also dispatch a `LaplaceRawEvent<Event>` with type `"event"`
+   * for every event, enabling catch-all listeners.
+   */
+  dispatchEvent(event) {
+    const result = super.dispatchEvent(event);
+    super.dispatchEvent(new LaplaceRawEvent("event", event));
+    return result;
+  }
+  /**
+   * Wire up event forwarding and timeout handling on the current connection.
+   * When `reconnect` is `true`, the previous connection is closed and a fresh
+   * one is created from the stored constructor parameters.
+   *
+   * @param reconnect - Whether to tear down and recreate the connection first.
+   */
+  connect(reconnect = true) {
+    if (reconnect) {
+      this.connection.close();
+      this.connection = new this.Base(...this.params);
+    }
+    const connection = this.connection;
+    let timeout = setTimeout(() => {
+      connection.close();
+      connection.dispatchEvent(new Event("timeout"));
+    }, this.timeout);
+    connection.addEventListener("event", (e) => {
+      const evt = e.data;
+      if (evt.type !== "error") {
+        if (evt instanceof LaplaceRawEvent) {
+          this.dispatchEvent(new LaplaceRawEvent(evt.type, evt.data));
+        } else {
+          this.dispatchEvent(new Event(evt.type));
+        }
+      }
+    });
+    connection.addEventListener("error", () => this.dispatchEvent(new Event("e")));
+    connection.addEventListener("close", () => {
+      if (!this.closed) {
+        setTimeout(() => this.connect(), this.interval);
+      }
+    });
+    connection.addEventListener("heartbeat", () => {
+      clearTimeout(timeout);
+      timeout = setTimeout(() => {
+        connection.close();
+        connection.dispatchEvent(new Event("timeout"));
+      }, this.timeout);
+    });
+    connection.addEventListener("close", () => {
+      clearTimeout(timeout);
+    });
+  }
+  /** Latest known online viewer count from the underlying connection. */
+  get online() {
+    return this.connection.online;
+  }
+  /** The live room ID. */
+  get roomid() {
+    return this.connection.roomid;
+  }
+  /** Permanently close the connection and stop reconnecting. */
+  close() {
+    this.closed = true;
+    this.connection.close();
+  }
+  /** Send a heartbeat packet to the server. */
+  heartbeat() {
+    return this.connection.heartbeat();
+  }
+  /**
+   * Send a heartbeat and resolve with the online viewer count from the
+   * next heartbeat response.
+   * @returns A promise that resolves with the current online count.
+   */
+  getOnline() {
+    return this.connection.getOnline();
+  }
+  /**
+   * Send raw binary data through the underlying connection.
+   * @param data - The binary packet to send.
+   */
+  send(data) {
+    return this.connection.send(data);
+  }
+  /**
+   * Subscribe to an event type with a typed {@link LaplaceRawEvent} listener.
+   *
+   * @typeParam T - Expected data type carried by the event.
+   * @param type     - Event name (e.g. `"heartbeat"`, `"msg"`, `"DANMU_MSG"`).
+   * @param listener - Callback receiving a {@link LaplaceRawEvent LaplaceRawEvent\<T\>}.
+   * @param options  - Standard `addEventListener` options.
+   */
+  on(type, listener, options) {
+    this.addEventListener(type, listener, options);
+  }
+  /**
+   * Unsubscribe a previously registered listener.
+   *
+   * @typeParam T - Data type matching the original subscription.
+   * @param type     - Event name.
+   * @param listener - The same function reference passed to {@link on}.
+   * @param options  - Standard `removeEventListener` options.
+   */
+  off(type, listener, options) {
+    this.removeEventListener(type, listener, options);
+  }
+};
+
+// src/tcp.ts
+import net from "net";
+
 // src/buffer.ts
 var textEncoder = new TextEncoder();
 var textDecoder = new TextDecoder();
@@ -82,28 +236,21 @@ var encoder = (type, body = "") => {
   return concatUint8Arrays([head, buffer]);
 };
 
-// src/common.ts
-var DataEvent = class extends Event {
-  data;
-  constructor(type, data) {
-    super(type);
-    this.data = data;
-  }
-};
-var EventEvent = class extends Event {
-  event;
-  constructor(event) {
-    super("event");
-    this.event = event;
-  }
-};
+// src/live.ts
 var Live = class extends EventTarget {
+  /** The live room ID this instance is connected to. */
   roomid;
+  /** Latest known online viewer count, updated on each heartbeat. */
   online;
+  /** `true` after the server acknowledges the join (`welcome` packet). */
   live;
+  /** `true` after {@link close} has been called. */
   closed;
+  /** @internal Handle for the heartbeat interval timer. */
   timeout;
+  /** Send raw binary data over the underlying transport. */
   send;
+  /** Gracefully close the connection and set {@link closed} to `true`. */
   close;
   constructor(inflates2, roomid, {
     send,
@@ -143,16 +290,16 @@ var Live = class extends EventTarget {
           this.online = data;
           clearTimeout(this.timeout);
           this.timeout = setTimeout(() => this.heartbeat(), 1e3 * 30);
-          this.dispatchEvent(new DataEvent("heartbeat", this.online));
+          this.dispatchEvent(new LaplaceRawEvent("heartbeat", this.online));
         }
         if (type === "message") {
-          this.dispatchEvent(new DataEvent("msg", data));
+          this.dispatchEvent(new LaplaceRawEvent("msg", data));
           const cmd = data.cmd || data.msg?.cmd;
           if (cmd) {
             if (cmd.includes("DANMU_MSG")) {
-              this.dispatchEvent(new DataEvent("DANMU_MSG", data));
+              this.dispatchEvent(new LaplaceRawEvent("DANMU_MSG", data));
             } else {
-              this.dispatchEvent(new DataEvent(cmd, data));
+              this.dispatchEvent(new LaplaceRawEvent(cmd, data));
             }
           }
         }
@@ -181,127 +328,63 @@ var Live = class extends EventTarget {
       this.dispatchEvent(new Event("error"));
     });
   }
+  /**
+   * Overridden to also dispatch a `LaplaceRawEvent<Event>` with type `"event"`
+   * for every event, enabling catch-all listeners.
+   */
   dispatchEvent(event) {
     const result = super.dispatchEvent(event);
-    super.dispatchEvent(new EventEvent(event));
+    super.dispatchEvent(new LaplaceRawEvent("event", event));
     return result;
   }
+  /** Send a heartbeat packet to the server. */
   heartbeat() {
     this.send(encoder("heartbeat"));
   }
+  /**
+   * Send a heartbeat and resolve with the online viewer count from the
+   * next heartbeat response.
+   * @returns A promise that resolves with the current online count.
+   */
   getOnline() {
     this.heartbeat();
     return new Promise(
       (resolve) => this.addEventListener("heartbeat", (e) => resolve(e.data), { once: true })
     );
   }
+  /**
+   * Subscribe to an event type with a typed {@link LaplaceRawEvent} listener.
+   * Convenience wrapper around {@link EventTarget.addEventListener}.
+   *
+   * @typeParam T - Expected data type carried by the event.
+   * @param type     - Event name (e.g. `"heartbeat"`, `"msg"`, `"DANMU_MSG"`).
+   * @param listener - Callback receiving a {@link LaplaceRawEvent LaplaceRawEvent\<T\>}.
+   * @param options  - Standard `addEventListener` options.
+   */
   on(type, listener, options) {
     this.addEventListener(type, listener, options);
   }
-  off(type, listener, options) {
-    this.removeEventListener(type, listener, options);
-  }
-};
-var KeepLive = class extends EventTarget {
-  params;
-  closed;
-  interval;
-  timeout;
-  connection;
-  Base;
-  constructor(Base, ...params) {
-    super();
-    this.params = params;
-    this.closed = false;
-    this.interval = 100;
-    this.timeout = 45 * 1e3;
-    this.connection = new Base(...this.params);
-    this.Base = Base;
-    this.connect(false);
-  }
-  dispatchEvent(event) {
-    const result = super.dispatchEvent(event);
-    super.dispatchEvent(new EventEvent(event));
-    return result;
-  }
-  connect(reconnect = true) {
-    if (reconnect) {
-      this.connection.close();
-      this.connection = new this.Base(...this.params);
-    }
-    const connection = this.connection;
-    let timeout = setTimeout(() => {
-      connection.close();
-      connection.dispatchEvent(new Event("timeout"));
-    }, this.timeout);
-    connection.addEventListener("event", (e) => {
-      const evt = e.event;
-      if (evt.type !== "error") {
-        if (evt instanceof DataEvent) {
-          this.dispatchEvent(new DataEvent(evt.type, evt.data));
-        } else {
-          this.dispatchEvent(new Event(evt.type));
-        }
-      }
-    });
-    connection.addEventListener("error", () => this.dispatchEvent(new Event("e")));
-    connection.addEventListener("close", () => {
-      if (!this.closed) {
-        setTimeout(() => this.connect(), this.interval);
-      }
-    });
-    connection.addEventListener("heartbeat", () => {
-      clearTimeout(timeout);
-      timeout = setTimeout(() => {
-        connection.close();
-        connection.dispatchEvent(new Event("timeout"));
-      }, this.timeout);
-    });
-    connection.addEventListener("close", () => {
-      clearTimeout(timeout);
-    });
-  }
-  get online() {
-    return this.connection.online;
-  }
-  get roomid() {
-    return this.connection.roomid;
-  }
-  close() {
-    this.closed = true;
-    this.connection.close();
-  }
-  heartbeat() {
-    return this.connection.heartbeat();
-  }
-  getOnline() {
-    return this.connection.getOnline();
-  }
-  send(data) {
-    return this.connection.send(data);
-  }
-  on(type, listener, options) {
-    this.addEventListener(type, listener, options);
-  }
+  /**
+   * Unsubscribe a previously registered listener.
+   * Convenience wrapper around {@link EventTarget.removeEventListener}.
+   *
+   * @typeParam T - Data type matching the original subscription.
+   * @param type     - Event name.
+   * @param listener - The same function reference passed to {@link on}.
+   * @param options  - Standard `removeEventListener` options.
+   */
   off(type, listener, options) {
     this.removeEventListener(type, listener, options);
   }
 };
 
-// src/inflate/node.ts
-import { promisify } from "util";
-import { brotliDecompress, inflate } from "zlib";
-var _inflate = promisify(inflate);
-var _brotli = promisify(brotliDecompress);
-var inflateAsync = (b) => _inflate(b);
-var brotliDecompressAsync = (b) => _brotli(b);
-var inflates = { inflateAsync, brotliDecompressAsync };
-
 // src/tcp.ts
-import net from "net";
 var LiveTCPBase = class extends Live {
+  /** The underlying Node.js TCP socket. */
   socket;
+  /** @internal Accumulator for incomplete packets from the TCP stream. */
   buf;
+  /** @internal Counter for periodic buffer compaction. */
   i;
   constructor(inflates2, roomid, { host = "broadcastlv.chat.bilibili.com", port = 2243, ...options } = {}) {
     const socket = net.connect(port, host);
@@ -321,23 +404,30 @@ var LiveTCPBase = class extends Live {
     });
     this.socket = socket;
   }
+  /**
+   * Extract complete packets from the internal buffer and dispatch them
+   * as `message` events. Compacts the buffer periodically to avoid
+   * unbounded memory growth from `Buffer.concat` / `slice` chains.
+   * @internal
+   */
   splitBuffer() {
     while (this.buf.length >= 4 && this.buf.readInt32BE(0) <= this.buf.length) {
       const size = this.buf.readInt32BE(0);
-      const pack = this.buf.slice(0, size);
-      this.buf = this.buf.slice(size);
+      const pack = this.buf.subarray(0, size);
+      this.buf = this.buf.subarray(size);
       this.i++;
       if (this.i > 5) {
         this.i = 0;
         this.buf = Buffer.from(this.buf);
       }
-      this.dispatchEvent(new DataEvent("message", pack));
+      this.dispatchEvent(new LaplaceRawEvent("message", pack));
     }
   }
 };
 
 // src/ws.ts
 var LiveWSBase = class extends Live {
+  /** The underlying native WebSocket instance. */
   ws;
   constructor(inflates2, roomid, { address = "wss://broadcastlv.chat.bilibili.com/sub", ...options } = {}) {
     const ws = new WebSocket(address);
@@ -352,7 +442,7 @@ var LiveWSBase = class extends Live {
     ws.addEventListener("open", (e) => this.dispatchEvent(new Event(e.type)));
     ws.addEventListener(
       "message",
-      (e) => this.dispatchEvent(new DataEvent("message", new Uint8Array(e.data)))
+      (e) => this.dispatchEvent(new LaplaceRawEvent("message", new Uint8Array(e.data)))
     );
     ws.addEventListener("close", (e) => this.dispatchEvent(new Event(e.type)));
     ws.addEventListener("error", () => this.dispatchEvent(new Event("_error")));
@@ -362,13 +452,25 @@ var LiveWSBase = class extends Live {
 
 // src/extra.ts
 var getConf = async (roomid) => {
-  const raw = await fetch(`https://api.live.bilibili.com/xlive/web-room/v1/index/getDanmuInfo?id=${roomid}`).then((w) => w.json());
-  const { data: { token: key, host_list: [{ host }] } } = raw;
+  const raw = await fetch(`https://api.live.bilibili.com/xlive/web-room/v1/index/getDanmuInfo?id=${roomid}`).then(
+    (w) => w.json()
+  );
+  if (!raw.data) {
+    throw new Error(`getConf failed for room ${roomid}: ${raw.message || "no data"} (code: ${raw.code})`);
+  }
+  const {
+    data: {
+      token: key,
+      host_list: [{ host }]
+    }
+  } = raw;
   const address = `wss://${host}/sub`;
   return { key, host, address, raw };
 };
 var getRoomid = async (short) => {
-  const { data: { room_id } } = await fetch(`https://api.live.bilibili.com/room/v1/Room/mobileRoomInit?id=${short}`).then((w) => w.json());
+  const {
+    data: { room_id }
+  } = await fetch(`https://api.live.bilibili.com/room/v1/Room/mobileRoomInit?id=${short}`).then((w) => w.json());
   return room_id;
 };
 
@@ -394,10 +496,9 @@ var KeepLiveTCP = class extends KeepLive {
   }
 };
 export {
-  DataEvent,
-  EventEvent,
   KeepLiveTCP,
   KeepLiveWS,
+  LaplaceRawEvent,
   LiveTCP,
   LiveWS,
   getConf,