@laplace.live/ws 7.1.9 → 8.0.0

package/dist/ws-CyLLjAlr.js

@@ -0,0 +1,426 @@
+//#region src/events.ts
+/**
+* A typed {@link Event} that carries an arbitrary data payload.
+*
+* Used throughout the library to deliver structured messages such as
+* heartbeat counts, danmaku payloads, and other server-pushed data.
+*
+* Also used internally with `LaplaceRawEvent<Event>` as a catch-all meta-event
+* (type `"event"`) to forward all events through {@link KeepLive}.
+*
+* @typeParam T - The type of the data payload attached to this event.
+*
+* @example
+* ```ts
+* live.addEventListener('heartbeat', (e) => {
+*   console.log('online:', e.data)
+* })
+* ```
+*/
+var LaplaceRawEvent = class extends Event {
+	data;
+	constructor(type, data) {
+		super(type);
+		this.data = data;
+	}
+};
+/**
+* Typed {@link EventTarget} base class for live connections.
+*
+* Provides typed `addEventListener` / `removeEventListener` via
+* {@link LiveEventMap} and a `dispatchEvent` override that emits a
+* catch-all `"event"` meta-event for every dispatched event.
+*
+* Extend this instead of `EventTarget` when building wrappers around
+* `LiveWS` / `KeepLiveWS` to inherit typed event signatures
+* automatically — no `declare` duplication required.
+*
+* @example
+* ```ts
+* import { LaplaceEventTarget, LaplaceRawEvent } from '@laplace.live/ws'
+*
+* class MyWrapper extends LaplaceEventTarget {
+*   // addEventListener is already typed — no extra `declare` needed
+* }
+* ```
+*/
+var LaplaceEventTarget = class extends EventTarget {
+	dispatchEvent(event) {
+		const result = super.dispatchEvent(event);
+		super.dispatchEvent(new LaplaceRawEvent("event", event));
+		return result;
+	}
+};
+//#endregion
+//#region src/keep-live.ts
+/**
+* Auto-reconnecting wrapper around a {@link Live} subclass.
+*
+* `KeepLive` maintains a persistent connection to a Bilibili live room by
+* automatically re-creating the underlying {@link Live} instance whenever
+* the connection drops or a heartbeat timeout is reached. All events from
+* the inner connection are forwarded to this instance.
+*
+* @typeParam T - The concrete {@link Live} instance type being managed.
+*
+* @example
+* ```ts
+* const keep = new KeepLiveWS(12345, { key: '...' })
+* keep.addEventListener('heartbeat', (e) => console.log('online:', e.data))
+* keep.addEventListener('DANMU_MSG', ({ data }) => console.log('danmaku:', data.msg_id))
+* ```
+*/
+var KeepLive = class extends LaplaceEventTarget {
+	/** @internal Factory that creates a fresh connection with the original arguments. */
+	createConnection;
+	/** `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;
+	constructor(createConnection) {
+		super();
+		this.createConnection = createConnection;
+		this.closed = false;
+		this.interval = 3e3;
+		this.timeout = 45 * 1e3;
+		this.connection = this.createConnection();
+		this.connect(false);
+	}
+	/**
+	* 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 via the factory.
+	*
+	* @param reconnect - Whether to tear down and recreate the connection first.
+	*/
+	connect(reconnect = true) {
+		if (reconnect) {
+			const old = this.connection;
+			this.connection = this.createConnection();
+			old.close();
+		}
+		const connection = this.connection;
+		let timeout = setTimeout(() => {
+			connection.close();
+			connection.dispatchEvent(new Event("timeout"));
+		}, this.timeout);
+		connection.addEventListener("event", (e) => {
+			if (this.connection !== connection) return;
+			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 && this.connection === connection) setTimeout(() => this.connect(), this.interval);
+		});
+		connection.addEventListener("heartbeat", () => {
+			if (this.connection !== connection) return;
+			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);
+	}
+};
+//#endregion
+//#region src/buffer.ts
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+function concatUint8Arrays(arrs) {
+	let totalLength = 0;
+	for (const arr of arrs) totalLength += arr.length;
+	const result = new Uint8Array(totalLength);
+	let offset = 0;
+	for (const arr of arrs) {
+		result.set(arr, offset);
+		offset += arr.length;
+	}
+	return result;
+}
+const cutBuffer = (buffer) => {
+	const bufferPacks = [];
+	const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+	let size;
+	for (let i = 0; i < buffer.length; i += size) {
+		size = view.getInt32(i);
+		bufferPacks.push(buffer.slice(i, i + size));
+	}
+	return bufferPacks;
+};
+/**
+* Create an async decoder function that parses raw Bilibili live WebSocket
+* frames into structured packets.
+*
+* Each frame has a 16-byte header:
+* - bytes 0–3: total packet length (int32 BE)
+* - bytes 4–5: header length (int16 BE, always 16)
+* - bytes 6–7: protocol version (0 = JSON, 1 = heartbeat, 2 = zlib, 3 = brotli)
+* - bytes 8–11: operation (2 = heartbeat req, 3 = heartbeat resp, 5 = message, 7 = join, 8 = welcome)
+* - bytes 12–15: sequence id
+*
+* Compressed frames (protocol 2/3) are recursively decoded after inflation.
+*
+* @link https://github.com/lovelyyoshino/Bilibili-Live-API/blob/master/API.WebSocket.md
+* @param inflates - Platform-specific decompression implementations.
+* @returns An async function that decodes a raw `Uint8Array` frame into an
+*          array of `{ buf, type, protocol, data }` packets.
+*/
+const makeDecoder = ({ inflateAsync, brotliDecompressAsync }) => {
+	const decoder = async (buffer) => {
+		return (await Promise.all(cutBuffer(buffer).map(async (buf) => {
+			const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+			const body = buf.slice(16);
+			const protocol = view.getInt16(6);
+			const operation = view.getInt32(8);
+			let type = "unknow";
+			if (operation === 3) type = "heartbeat";
+			else if (operation === 5) type = "message";
+			else if (operation === 8) type = "welcome";
+			let data;
+			if (protocol === 0) data = JSON.parse(textDecoder.decode(body));
+			if (protocol === 1 && body.length === 4) data = new DataView(body.buffer, body.byteOffset, body.byteLength).getUint32(0);
+			if (protocol === 2) data = await decoder(await inflateAsync(body));
+			if (protocol === 3) data = await decoder(await brotliDecompressAsync(body));
+			return {
+				buf,
+				type,
+				protocol,
+				data
+			};
+		}))).flatMap((pack) => {
+			if (pack.protocol === 2 || pack.protocol === 3) return pack.data;
+			return pack;
+		});
+	};
+	return decoder;
+};
+/**
+* Encode a Bilibili live protocol packet with a 16-byte header and an
+* optional body.
+*
+* Header layout:
+* - bytes 0–3: total length (header + body)
+* - bytes 4–5: header length (16)
+* - bytes 6–7: protocol version (1)
+* - bytes 8–11: operation (`2` for heartbeat, `7` for join)
+* - bytes 12–15: sequence id (1)
+*
+* @param type - Packet type: `"heartbeat"` (keep-alive) or `"join"` (room enter).
+* @param body - Optional payload. Objects are JSON-stringified; strings are
+*               encoded as UTF-8. Defaults to an empty string.
+* @returns The encoded packet as a `Uint8Array`.
+*/
+const encoder = (type, body = "") => {
+	const encoded = typeof body === "string" ? body : JSON.stringify(body);
+	const head = new Uint8Array(16);
+	const headView = new DataView(head.buffer, head.byteOffset, head.byteLength);
+	const buffer = textEncoder.encode(encoded);
+	headView.setInt32(0, buffer.length + head.length);
+	headView.setInt16(4, 16);
+	headView.setInt16(6, 1);
+	if (type === "heartbeat") headView.setInt32(8, 2);
+	if (type === "join") headView.setInt32(8, 7);
+	headView.setInt32(12, 1);
+	return concatUint8Arrays([head, buffer]);
+};
+//#endregion
+//#region src/live.ts
+/**
+* Base class for a single Bilibili live room connection.
+*
+* Extends {@link LaplaceEventTarget} and emits the following events:
+*
+* | Event         | Payload            | Description                                      |
+* |---------------|--------------------|--------------------------------------------------|
+* | `open`        | —                  | Underlying transport connected.                  |
+* | `live`        | —                  | Server acknowledged the join (room entered).     |
+* | `heartbeat`   | `LaplaceRawEvent<number>`| Online viewer count received from server.        |
+* | `msg`         | `LaplaceRawEvent<any>`   | Any server command message.                      |
+* | `DANMU_MSG`   | `LaplaceRawEvent<any>`   | Danmaku (chat) message.                          |
+* | `close`       | —                  | Connection closed.                               |
+* | `error`       | —                  | Unrecoverable error (connection is closed).      |
+* | `event`       | `LaplaceRawEvent<Event>` | Meta-event wrapping every dispatched event.      |
+*
+* Subclasses ({@link LiveWSBase}, {@link LiveTCPBase}) provide the concrete
+* transport and supply `send` / `close` callbacks to this constructor.
+*
+* @param inflates - Platform-specific inflate + brotli decompressors.
+* @param roomid   - Numeric Bilibili live room ID.
+* @param options  - Transport callbacks and authentication options.
+*
+* @throws {Error} If `roomid` is not a finite number.
+*/
+var Live = class extends LaplaceEventTarget {
+	/** 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(inflates, roomid, { send, close, protover = 3, key, authBody, uid = 0, buvid }) {
+		if (typeof roomid !== "number" || Number.isNaN(roomid)) throw new Error(`roomid ${roomid} must be Number not NaN`);
+		super();
+		this.roomid = roomid;
+		this.online = 0;
+		this.live = false;
+		this.closed = false;
+		this.timeout = setTimeout(() => {}, 0);
+		this.send = send;
+		this.close = () => {
+			if (this.closed) return;
+			this.closed = true;
+			close();
+			this.dispatchEvent(new Event("close"));
+		};
+		const decode = makeDecoder(inflates);
+		this.addEventListener("message", async (e) => {
+			const buffer = e.data;
+			(await decode(buffer)).forEach(({ type, data }) => {
+				if (type === "welcome") {
+					this.live = true;
+					this.dispatchEvent(new Event("live"));
+					this.send(encoder("heartbeat"));
+				}
+				if (type === "heartbeat") {
+					this.online = data;
+					clearTimeout(this.timeout);
+					this.timeout = setTimeout(() => this.heartbeat(), 1e3 * 30);
+					this.dispatchEvent(new LaplaceRawEvent("heartbeat", this.online));
+				}
+				if (type === "message") {
+					this.dispatchEvent(new LaplaceRawEvent("msg", data));
+					const cmd = data.cmd || data.msg?.cmd;
+					if (cmd) this.dispatchEvent(new LaplaceRawEvent(cmd, data));
+				}
+			});
+		});
+		this.addEventListener("open", () => {
+			if (authBody) this.send(authBody instanceof Uint8Array ? authBody : encoder("join", authBody));
+			else {
+				const hi = {
+					uid,
+					roomid,
+					protover,
+					platform: "web",
+					type: 2
+				};
+				if (key) hi.key = key;
+				if (buvid) hi.buvid = buvid;
+				const buf = encoder("join", hi);
+				this.send(buf);
+			}
+		});
+		this.addEventListener("close", () => {
+			clearTimeout(this.timeout);
+		});
+		this.addEventListener("_error", () => {
+			this.close();
+			this.dispatchEvent(new Event("error"));
+		});
+	}
+	/** 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 }));
+	}
+};
+//#endregion
+//#region src/ws.ts
+/**
+* WebSocket transport for Bilibili live room connections.
+*
+* Wraps a native {@link WebSocket}, wiring its lifecycle events (`open`,
+* `message`, `close`, `error`) into the {@link Live} event system. Binary
+* frames are forwarded as `LaplaceRawEvent<Uint8Array>` for protocol decoding.
+*
+* Not typically instantiated directly — use {@link LiveWS} (server) or the
+* browser-specific `LiveWS` which inject the appropriate inflate
+* implementation.
+*
+* @param inflates - Platform-specific inflate/brotli decompressors.
+* @param roomid   - Numeric Bilibili live room ID.
+* @param options  - WebSocket address and authentication options.
+*/
+var LiveWSBase = class extends Live {
+	/** The underlying native WebSocket instance. */
+	ws;
+	constructor(inflates, roomid, { address = "wss://broadcastlv.chat.bilibili.com/sub", createWebSocket, ...options } = {}) {
+		const ws = createWebSocket ? createWebSocket(address) : new WebSocket(address);
+		const send = (data) => {
+			if (ws.readyState === 1) ws.send(data);
+		};
+		const close = () => this.ws.close();
+		super(inflates, roomid, {
+			send,
+			close,
+			...options
+		});
+		ws.binaryType = "arraybuffer";
+		ws.addEventListener("open", (e) => this.dispatchEvent(new Event(e.type)));
+		ws.addEventListener("message", (e) => this.dispatchEvent(new LaplaceRawEvent("message", new Uint8Array(e.data))));
+		ws.addEventListener("close", (e) => {
+			if (!this.closed) this.dispatchEvent(new Event(e.type));
+		});
+		ws.addEventListener("error", () => this.dispatchEvent(new Event("_error")));
+		this.ws = ws;
+	}
+};
+//#endregion
+export { LaplaceRawEvent as a, LaplaceEventTarget as i, Live as n, KeepLive as r, LiveWSBase as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/ws",
-  "version": "7.1.9",
+  "version": "8.0.0",
   "description": "LAPLACE Live! flavored bilibili live WebSocket/TCP API",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,12 +32,13 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "check": "tsc --noEmit",
     "test": "bun test --timeout 5000",
     "prepublishOnly": "bun run build",
     "release": "changeset publish",
-    "version": "changeset version"
+    "version": "changeset version",
+    "lint": "biome check"
   },
   "repository": {
     "type": "git",
@@ -62,14 +63,14 @@
     "provenance": true
   },
   "dependencies": {
-    "@laplace.live/internal": "^1.3.7"
+    "@laplace.live/internal": "^1.3.18"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.12",
-    "@changesets/cli": "^2.30.0",
-    "@types/bun": "^1.3.12",
-    "playwright": "^1.59.1",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "@biomejs/biome": "^2.4.16",
+    "@changesets/cli": "^2.31.0",
+    "@types/bun": "^1.3.14",
+    "playwright": "^1.60.0",
+    "tsdown": "^0.22.1",
+    "typescript": "^6.0.3"
   }
 }