@laplace.live/ws 7.0.0 → 7.0.1

package/dist/ws-BJGEziZp.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Platform-specific inflate/decompress implementations injected into the
+ * decoder at construction time.
+ *
+ * - **Node / Bun**: backed by `node:zlib` (`inflate` + `brotliDecompress`).
+ * - **Browser**: backed by `pako` (inflate) + a bundled JS Brotli decoder.
+ */
+type Inflates = {
+    inflateAsync: (b: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+    brotliDecompressAsync: (b: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+};
+
+/**
+ * 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 `DataEvent<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.on<number>('heartbeat', (e) => {
+ *   console.log('online:', e.data)
+ * })
+ * ```
+ */
+declare class DataEvent<T> extends Event {
+    data: T;
+    constructor(type: string, data: T);
+}
+
+/**
+ * Options for configuring the Bilibili live connection authentication.
+ *
+ * When {@link authBody} is provided it takes precedence over all other
+ * fields and is sent as the join payload verbatim.
+ */
+type LiveOptions = {
+    /** Protocol version. Defaults to `3` (brotli-compressed). */
+    protover?: 1 | 2 | 3;
+    /** Authentication token obtained from the danmaku info API. */
+    key?: string;
+    /**
+     * Pre-built authentication body. When supplied as a `Uint8Array` it is
+     * sent raw; when supplied as an object it is JSON-encoded before sending.
+     * Takes precedence over {@link key}, {@link uid}, and {@link buvid}.
+     */
+    authBody?: Uint8Array | Record<string, unknown>;
+    /** User ID. Defaults to `0` (anonymous). */
+    uid?: number;
+    /** Browser unique visitor ID used for risk-control tracking. */
+    buvid?: string;
+};
+/**
+ * Base class for a single Bilibili live room connection.
+ *
+ * Extends {@link EventTarget} and emits the following events:
+ *
+ * | Event         | Payload            | Description                                      |
+ * |---------------|--------------------|--------------------------------------------------|
+ * | `open`        | —                  | Underlying transport connected.                  |
+ * | `live`        | —                  | Server acknowledged the join (room entered).     |
+ * | `heartbeat`   | `DataEvent<number>`| Online viewer count received from server.        |
+ * | `msg`         | `DataEvent<any>`   | Any server command message.                      |
+ * | `DANMU_MSG`   | `DataEvent<any>`   | Danmaku (chat) message.                          |
+ * | `close`       | —                  | Connection closed.                               |
+ * | `error`       | —                  | Unrecoverable error (connection is closed).      |
+ * | `event`       | `DataEvent<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.
+ */
+declare class Live extends EventTarget {
+    /** The live room ID this instance is connected to. */
+    roomid: number;
+    /** Latest known online viewer count, updated on each heartbeat. */
+    online: number;
+    /** `true` after the server acknowledges the join (`welcome` packet). */
+    live: boolean;
+    /** `true` after {@link close} has been called. */
+    closed: boolean;
+    /** @internal Handle for the heartbeat interval timer. */
+    timeout: ReturnType<typeof setTimeout>;
+    /** Send raw binary data over the underlying transport. */
+    send: (data: Uint8Array) => void;
+    /** Gracefully close the connection and set {@link closed} to `true`. */
+    close: () => void;
+    constructor(inflates: Inflates, roomid: number, { send, close, protover, key, authBody, uid, buvid, }: {
+        send: (data: Uint8Array) => void;
+        close: () => void;
+    } & LiveOptions);
+    /**
+     * Overridden to also dispatch a `DataEvent<Event>` with type `"event"`
+     * for every event, enabling catch-all listeners.
+     */
+    dispatchEvent(event: Event): boolean;
+    /** Send a heartbeat packet to the server. */
+    heartbeat(): void;
+    /**
+     * 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(): Promise<number>;
+    /**
+     * Subscribe to an event type with a typed {@link DataEvent} 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 DataEvent DataEvent\<T\>}.
+     * @param options  - Standard `addEventListener` options.
+     */
+    on<T = unknown>(type: string, listener: (event: DataEvent<T>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * 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<T = unknown>(type: string, listener: (event: DataEvent<T>) => void, options?: boolean | EventListenerOptions): void;
+}
+
+/**
+ * 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 Base - The concrete {@link Live} subclass to manage
+ *                   (e.g. `typeof LiveWSBase` or `typeof LiveTCPBase`).
+ *
+ * @example
+ * ```ts
+ * const keep = new KeepLiveWS(12345, { key: '...' })
+ * keep.on('heartbeat', (e) => console.log('online:', e.data))
+ * keep.on('DANMU_MSG', (e) => console.log('danmaku:', e.data))
+ * ```
+ */
+declare class KeepLive<Base extends typeof Live> extends EventTarget {
+    /** @internal Stored constructor arguments for reconnection. */
+    params: ConstructorParameters<Base>;
+    /** `true` after {@link close} has been called; prevents further reconnects. */
+    closed: boolean;
+    /** Delay in milliseconds before attempting a reconnect. */
+    interval: number;
+    /** Maximum milliseconds to wait for a heartbeat before forcing a reconnect. */
+    timeout: number;
+    /** The current underlying connection instance. */
+    connection: InstanceType<Base>;
+    /** @internal The base class constructor used to create new connections. */
+    Base: Base;
+    constructor(Base: Base, ...params: ConstructorParameters<Base>);
+    /**
+     * Overridden to also dispatch a `DataEvent<Event>` with type `"event"`
+     * for every event, enabling catch-all listeners.
+     */
+    dispatchEvent(event: Event): boolean;
+    /**
+     * 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?: boolean): void;
+    /** Latest known online viewer count from the underlying connection. */
+    get online(): number;
+    /** The live room ID. */
+    get roomid(): number;
+    /** Permanently close the connection and stop reconnecting. */
+    close(): void;
+    /** Send a heartbeat packet to the server. */
+    heartbeat(): void;
+    /**
+     * 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(): Promise<number>;
+    /**
+     * Send raw binary data through the underlying connection.
+     * @param data - The binary packet to send.
+     */
+    send(data: Uint8Array): void;
+    /**
+     * Subscribe to an event type with a typed {@link DataEvent} 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 DataEvent DataEvent\<T\>}.
+     * @param options  - Standard `addEventListener` options.
+     */
+    on<T = unknown>(type: string, listener: (event: DataEvent<T>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * 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<T = unknown>(type: string, listener: (event: DataEvent<T>) => void, options?: boolean | EventListenerOptions): void;
+}
+
+/**
+ * Configuration options for WebSocket-based live connections.
+ * Extends {@link LiveOptions} with an optional WebSocket server address.
+ */
+type WSOptions = LiveOptions & {
+    /** WebSocket server URL. Defaults to `wss://broadcastlv.chat.bilibili.com/sub`. */
+    address?: string;
+};
+/**
+ * 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 `DataEvent<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.
+ */
+declare class LiveWSBase extends Live {
+    /** The underlying native WebSocket instance. */
+    ws: WebSocket;
+    constructor(inflates: Inflates, roomid: number, { address, ...options }?: WSOptions);
+}
+
+export { DataEvent as D, type Inflates as I, KeepLive as K, Live as L, type WSOptions as W, type LiveOptions as a, LiveWSBase as b };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/ws",
-  "version": "7.0.0",
+  "version": "7.0.1",
   "description": "Bilibili Live WebSocket/TCP API",
   "type": "module",
   "main": "./dist/index.js",

package/dist/ws-DVInVzNN.d.ts

@@ -1,67 +0,0 @@
-type Inflates = {
-    inflateAsync: (b: Uint8Array) => Uint8Array | Promise<Uint8Array>;
-    brotliDecompressAsync: (b: Uint8Array) => Uint8Array | Promise<Uint8Array>;
-};
-
-type LiveOptions = {
-    protover?: 1 | 2 | 3;
-    key?: string;
-    authBody?: Uint8Array | Record<string, unknown>;
-    uid?: number;
-    buvid?: string;
-};
-declare class DataEvent<T> extends Event {
-    data: T;
-    constructor(type: string, data: T);
-}
-declare class EventEvent extends Event {
-    event: Event;
-    constructor(event: Event);
-}
-declare class Live extends EventTarget {
-    roomid: number;
-    online: number;
-    live: boolean;
-    closed: boolean;
-    timeout: ReturnType<typeof setTimeout>;
-    send: (data: Uint8Array) => void;
-    close: () => void;
-    constructor(inflates: Inflates, roomid: number, { send, close, protover, key, authBody, uid, buvid, }: {
-        send: (data: Uint8Array) => void;
-        close: () => void;
-    } & LiveOptions);
-    dispatchEvent(event: Event): boolean;
-    heartbeat(): void;
-    getOnline(): Promise<number>;
-    on<T = unknown>(type: string, listener: (event: DataEvent<T>) => void, options?: boolean | AddEventListenerOptions): void;
-    off<T = unknown>(type: string, listener: (event: DataEvent<T>) => void, options?: boolean | EventListenerOptions): void;
-}
-declare class KeepLive<Base extends typeof Live> extends EventTarget {
-    params: ConstructorParameters<Base>;
-    closed: boolean;
-    interval: number;
-    timeout: number;
-    connection: InstanceType<Base>;
-    Base: Base;
-    constructor(Base: Base, ...params: ConstructorParameters<Base>);
-    dispatchEvent(event: Event): boolean;
-    connect(reconnect?: boolean): void;
-    get online(): number;
-    get roomid(): number;
-    close(): void;
-    heartbeat(): void;
-    getOnline(): Promise<number>;
-    send(data: Uint8Array): void;
-    on<T = unknown>(type: string, listener: (event: DataEvent<T>) => void, options?: boolean | AddEventListenerOptions): void;
-    off<T = unknown>(type: string, listener: (event: DataEvent<T>) => void, options?: boolean | EventListenerOptions): void;
-}
-
-type WSOptions = LiveOptions & {
-    address?: string;
-};
-declare class LiveWSBase extends Live {
-    ws: WebSocket;
-    constructor(inflates: Inflates, roomid: number, { address, ...options }?: WSOptions);
-}
-
-export { DataEvent as D, EventEvent as E, type Inflates as I, KeepLive as K, Live as L, type WSOptions as W, type LiveOptions as a, LiveWSBase as b };