@honeybbq/teamspeak-client 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/notifications.d.ts

@@ -1,5 +1,5 @@
 import type { Command } from "@honeybbq/teamspeak-core/internal";
-import type { ClientEnterEvent, ClientLeaveEvent, ClientMovedEvent, TextMessageEvent, PokeEvent } from "./types.js";
+import type { ClientEnterEvent, ClientLeaveEvent, ClientMovedEvent, TextMessageEvent, PokeEvent } from "@honeybbq/teamspeak-core";
 export type NotificationResult = {
     kind: "clientEnter";
     info: ClientEnterEvent;

package/dist/notifications.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../src/notifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACV,MAAM,YAAY,CAAC;AASpB,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACtC,SAAS,EAAE,MAAM,GAChB,kBAAkB,CAepB"}
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../src/notifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACV,MAAM,0BAA0B,CAAC;AASlC,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACtC,SAAS,EAAE,MAAM,GAChB,kBAAkB,CAepB"}

package/dist/trace.d.ts

@@ -0,0 +1,223 @@
+import type { ChannelID, ClientID } from "@honeybbq/teamspeak-core";
+import type { ServerCapabilities } from "./capabilities.js";
+import type { ResolvedAddr } from "./types.js";
+/** The values of the table below, before freezing. */
+declare const connectPhaseValues: {
+    /** Opening the socket, or the address was not usable once resolved. */
+    readonly Open: "open";
+    /** The handshake, from the first packet until the shared secret exists. */
+    readonly Handshake: "handshake";
+    /** After the handshake, waiting for the server to accept the client: a wrong password, a ban or an invalid nickname end here. */
+    readonly Join: "join";
+};
+/** Where a connection attempt can fail; see {@link AttemptFailedInfo}. */
+export declare const ConnectPhase: typeof connectPhaseValues;
+/**
+ * One of {@link ConnectPhase}. May gain members in a minor release: a
+ * `switch` over it needs a default case.
+ */
+export type ConnectPhase = (typeof ConnectPhase)[keyof typeof ConnectPhase];
+/** What every milestone of one connection attempt says about the attempt. */
+interface AttemptInfo {
+    /**
+     * The attempt's number, from 1. The attempt `connect()` starts is 1; a
+     * reconnection attempt carries the retry number the reconnect policy uses,
+     * the one `shouldRetry` and the backoff see.
+     */
+    readonly attempt: number;
+    /** Whether the reconnect loop started this attempt rather than a call to `connect()`. */
+    readonly reconnect: boolean;
+}
+/** The address is about to be resolved. */
+export interface ResolveStartInfo extends AttemptInfo {
+    /** The address as the client was given it. */
+    readonly addr: string;
+}
+/** The address has been resolved, or the lookup failed and the address is used as given. */
+export interface ResolveDoneInfo extends AttemptInfo {
+    /** The address as the client was given it. */
+    readonly addr: string;
+    /** The `host:port` that will be dialled. */
+    readonly target: string;
+    /** What the resolver reports as the source of the answer dialled; may be empty. */
+    readonly source: string;
+    /** Every answer the resolver gave, in order; empty when the address is used as given. */
+    readonly candidates: readonly ResolvedAddr[];
+    /** Why the lookup failed, when the address is used as given; `undefined` otherwise. */
+    readonly error: unknown;
+    /** How long the resolution took, in milliseconds. */
+    readonly durationMs: number;
+}
+/** The socket is about to be opened. */
+export interface ConnectStartInfo extends AttemptInfo {
+    /** The `host:port` being dialled. */
+    readonly target: string;
+}
+/** The socket is open; the first handshake packet has not been sent yet. */
+export interface ConnectDoneInfo extends AttemptInfo {
+    /** The `host:port` being dialled. */
+    readonly target: string;
+    /** The local socket's `host:port`; empty when the socket does not say. */
+    readonly localAddr: string;
+    /** Milliseconds since `connectStart`. */
+    readonly durationMs: number;
+}
+/** The encrypted session exists; `clientinit` has not been sent yet. */
+export interface HandshakeDoneInfo extends AttemptInfo {
+    /** Milliseconds since `connectStart`. */
+    readonly durationMs: number;
+    /** The level of the RSA puzzle the server demanded; 0 if it sent none. */
+    readonly puzzleLevel: number;
+    /** Milliseconds spent solving the puzzle. */
+    readonly puzzleDurationMs: number;
+    /**
+     * The packets sent again from `connectStart` to now, for want of an
+     * acknowledgement: the Init1 steps and the handshake's command packets.
+     */
+    readonly resends: number;
+    /**
+     * The server's public key exactly as it sent it, base64, so that a caller can
+     * pin a server's identity.
+     */
+    readonly serverPublicKey: string;
+}
+/** The server accepted the client, which is now connected. */
+export interface SessionStartInfo extends AttemptInfo {
+    /** The client's ID on the server, the same as `client.clientID`. */
+    readonly clientID: ClientID;
+    /**
+     * The nickname the server accepted (`acn`), which differs from the one asked
+     * for when that was taken. The one asked for when the server did not say.
+     */
+    readonly nickname: string;
+    /** The client's talk power (`client_talk_power`); 0 when the server did not say. */
+    readonly talkPower: number;
+    /**
+     * Every parameter of `initserver`, unescaped, except those that could carry a
+     * secret: `client_server_password`, `client_default_channel_password`,
+     * `client_default_token` and `client_key_offset`. Frozen.
+     */
+    readonly initServer: Readonly<Record<string, string>>;
+    /** What the server said about itself in this handshake. */
+    readonly capabilities: ServerCapabilities;
+    /** Milliseconds since `connectStart`. */
+    readonly durationMs: number;
+}
+/** The server's welcome sequence ended: the channel list and the clients already there have arrived. */
+export interface WelcomeDoneInfo extends AttemptInfo {
+    /**
+     * The channel the client is in at the end of the welcome: where it landed,
+     * which differs from the default channel asked for when that was refused.
+     */
+    readonly channelID: ChannelID;
+    /** How many channel rows the welcome delivered. */
+    readonly channels: number;
+    /** How many clients are in view at the end of the welcome, this client included. */
+    readonly clients: number;
+    /** Milliseconds since `connectStart`. */
+    readonly durationMs: number;
+}
+/** An attempt ended without a session. */
+export interface AttemptFailedInfo extends AttemptInfo {
+    /** Where the attempt failed. */
+    readonly phase: ConnectPhase;
+    /** Why: the error `connect()` rejects with, or the one that ended the reconnection attempt. */
+    readonly error: unknown;
+    /** The `host:port` being dialled; empty when the attempt failed before `resolveDone`. */
+    readonly target: string;
+    /** Milliseconds since `resolveStart`. */
+    readonly durationMs: number;
+}
+/** The reconnect loop will retry, after a wait. */
+export interface ReconnectScheduledInfo {
+    /** The attempt that will follow, numbered as in {@link ResolveStartInfo.attempt}. */
+    readonly attempt: number;
+    /** How long the loop waits first, in milliseconds. */
+    readonly delayMs: number;
+    /** The error that ended the previous connection or attempt. */
+    readonly cause: unknown;
+}
+/** A connected session is about to be left with `disconnect()`. It has no fields yet. */
+export interface DisconnectStartInfo {
+}
+/** The goodbye of `disconnect()` is over. */
+export interface DisconnectDoneInfo {
+    /** Whether the server acknowledged the goodbye before the goodbye timeout. */
+    readonly acknowledged: boolean;
+    /** Milliseconds since `disconnectStart`. */
+    readonly durationMs: number;
+}
+/** A session that had a `sessionStart` has ended, however it ended. */
+export interface SessionEndInfo {
+    /** The client's ID on the server during the session. */
+    readonly clientID: ClientID;
+    /**
+     * `undefined` after `disconnect()`, and otherwise the cause the
+     * `disconnected` event gets.
+     */
+    readonly error: unknown;
+    /** Milliseconds since `sessionStart`. */
+    readonly durationMs: number;
+    /** The number of the attempt that started the session. */
+    readonly attempt: number;
+    /** Whether the reconnect loop started the attempt that started the session. */
+    readonly reconnect: boolean;
+}
+/** The reconnect loop ended without a session. */
+export interface ReconnectStoppedInfo {
+    /** How many reconnection attempts the loop made. */
+    readonly attempts: number;
+    /**
+     * The error `shouldRetry` declined, or the last attempt's when the attempts
+     * ran out; `undefined` when `disconnect()` stopped the loop.
+     */
+    readonly cause: unknown;
+}
+/**
+ * Hooks that observe a client for timing, metrics, logs or a progress
+ * display: the milestones of every connection attempt, the end of a session,
+ * and the reconnect loop. Every hook is optional.
+ *
+ * A hook is called synchronously, at the moment of the milestone, and the
+ * client waits for it to return: keep it quick, and hand slow work to your own
+ * task. What it returns is ignored, and a returned promise is never awaited. A
+ * hook that throws, or whose promise rejects, is reported the way a throwing
+ * event listener is, and the client carries on. A hook may read the
+ * client's state. It must not call `connect()` or `disconnect()`: to give up
+ * on an attempt, abort the signal passed to `connect()`, and to leave once
+ * connected, call `disconnect()` from a `connected` listener.
+ *
+ * Every attempt ends with exactly one of `sessionStart` and `attemptFailed`,
+ * and every session that started with exactly one `sessionEnd`. The hooks are
+ * read when the client is made, from a copy of this object.
+ */
+export interface ClientTrace {
+    /** Before the address is resolved. */
+    readonly resolveStart?: (info: ResolveStartInfo) => void;
+    /** After the address is resolved, also when it fell back to the address as given. */
+    readonly resolveDone?: (info: ResolveDoneInfo) => void;
+    /** Right before the socket is opened. */
+    readonly connectStart?: (info: ConnectStartInfo) => void;
+    /** Once the socket is open, before the first handshake packet is sent. */
+    readonly connectDone?: (info: ConnectDoneInfo) => void;
+    /** When the shared secret is derived, before `clientinit` is sent. */
+    readonly handshakeDone?: (info: HandshakeDoneInfo) => void;
+    /** When the server accepts the client: before `connect()` resolves and before `connected` is delivered. */
+    readonly sessionStart?: (info: SessionStartInfo) => void;
+    /** When the server's welcome sequence ends; at most once per attempt, and only after `sessionStart`. */
+    readonly welcomeDone?: (info: WelcomeDoneInfo) => void;
+    /** When an attempt ends without `sessionStart`, for any reason, an abort or `disconnect()` included. */
+    readonly attemptFailed?: (info: AttemptFailedInfo) => void;
+    /** When `disconnect()` begins saying goodbye to a connected session. */
+    readonly disconnectStart?: (info: DisconnectStartInfo) => void;
+    /** When that goodbye is over. */
+    readonly disconnectDone?: (info: DisconnectDoneInfo) => void;
+    /** When a session ends, however it ends; before `disconnected` is queued. */
+    readonly sessionEnd?: (info: SessionEndInfo) => void;
+    /** When the reconnect loop has decided to retry and is about to wait. */
+    readonly reconnectScheduled?: (info: ReconnectScheduledInfo) => void;
+    /** When the reconnect loop ends without a session. */
+    readonly reconnectStopped?: (info: ReconnectStoppedInfo) => void;
+}
+export {};
+//# sourceMappingURL=trace.d.ts.map

package/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,sDAAsD;AACtD,QAAA,MAAM,kBAAkB;IACtB,uEAAuE;aACvE,IAAI,EAAE,MAAM;IACZ,2EAA2E;aAC3E,SAAS,EAAE,WAAW;IACtB,iIAAiI;aACjI,IAAI,EAAE,MAAM;CACJ,CAAC;AACX,0EAA0E;AAC1E,eAAO,MAAM,YAAY,EAAE,OAAO,kBACiB,CAAC;AACpD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E,6EAA6E;AAC7E,UAAU,WAAW;IACnB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,2CAA2C;AAC3C,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,4FAA4F;AAC5F,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yFAAyF;IACzF,QAAQ,CAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wEAAwE;AACxE,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wGAAwG;AACxG,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,0CAA0C;AAC1C,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,yFAAyF;AAEzF,MAAM,WAAW,mBAAmB;CAAG;AAEvC,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzD,qFAAqF;IACrF,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;IACvD,yCAAyC;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzD,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;IACvD,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC3D,2GAA2G;IAC3G,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzD,wGAAwG;IACxG,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;IACvD,wGAAwG;IACxG,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC3D,wEAAwE;IACxE,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAC/D,iCAAiC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC7D,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IACrD,yEAAyE;IACzE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACrE,sDAAsD;IACtD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC;CAClE"}

package/dist/transfer.d.ts

@@ -5,10 +5,76 @@
  * the bytes then go over a separate TCP connection to the server's file
  * transfer port, opened with the key the negotiation returned.
  */
-import type { Duplex, Readable, Writable } from "node:stream";
+import { type Duplex, type Readable, type Writable } from "node:stream";
 import type { FileUploadInfo, FileDownloadInfo } from "@honeybbq/teamspeak-core";
 import type { FileTransferSocketFactory } from "./types.js";
 import { FileTransferError } from "./errors.js";
+/** Where a failed transfer failed. */
+export type FileTransferStage = "dial" | "transfer";
+/** The file transfer port is about to be dialled. */
+export interface FileTransferDialStartInfo {
+    /** The `host:port` being dialled. */
+    readonly addr: string;
+}
+/** The connection is open and the transfer key has been sent. */
+export interface FileTransferDialDoneInfo {
+    /** The `host:port` dialled. */
+    readonly addr: string;
+    /** The local socket's `host:port`; empty when the socket does not say. */
+    readonly localAddr: string;
+    /** Milliseconds since `dialStart`. */
+    readonly durationMs: number;
+}
+/** Data has moved. */
+export interface FileTransferProgressInfo {
+    /** The bytes moved so far. */
+    readonly bytes: number;
+    /** The size the negotiation gave; 0 when it is not known, as for an upload. */
+    readonly total: number;
+}
+/** The transfer succeeded. */
+export interface FileTransferDoneInfo {
+    /** The bytes moved. */
+    readonly bytes: number;
+    /** Milliseconds since `dialStart`. */
+    readonly durationMs: number;
+}
+/** The transfer failed. */
+export interface FileTransferFailedInfo {
+    /** Why: the error the transfer function rejects with. */
+    readonly error: unknown;
+    /** The bytes moved before it failed. */
+    readonly bytes: number;
+    /** Milliseconds since `dialStart`. */
+    readonly durationMs: number;
+    /** Whether the failure came while dialling or while the data moved. */
+    readonly stage: FileTransferStage;
+}
+/**
+ * Hooks that observe one file transfer. Every hook is optional, and none ever
+ * sees the transfer key.
+ *
+ * A hook runs synchronously on the task doing the transfer, and its return
+ * value is ignored: a returned promise is not awaited. A hook that throws, or
+ * whose promise rejects, is reported the way a throwing event listener is, and
+ * the transfer goes on. Keep hooks quick.
+ *
+ * A call of `uploadFileData` or `downloadFileData` ends with exactly one of
+ * `done` and `failed`; `dialFileTransfer` on its own reports `dialStart`, then
+ * `dialDone` or `failed` with the stage `"dial"`.
+ */
+export interface FileTransferTrace {
+    /** Before the file transfer port is dialled. */
+    readonly dialStart?: (info: FileTransferDialStartInfo) => void;
+    /** When the connection is open and the transfer key is sent. */
+    readonly dialDone?: (info: FileTransferDialDoneInfo) => void;
+    /** While data moves, at most once per 64 KiB, and once more at the end with the final count. */
+    readonly progress?: (info: FileTransferProgressInfo) => void;
+    /** When the transfer function is about to resolve. */
+    readonly done?: (info: FileTransferDoneInfo) => void;
+    /** When the transfer function is about to reject, a failed dial included. */
+    readonly failed?: (info: FileTransferFailedInfo) => void;
+}
 /** Options for a file transfer. */
 export interface FileTransferOptions {
     /** Abandons the transfer; it then rejects with the signal's reason. */
@@ -18,6 +84,19 @@ export interface FileTransferOptions {
      * through a proxy or tunnel.
      */
     readonly socketFactory?: FileTransferSocketFactory | undefined;
+    /**
+     * Hooks called at each milestone of this transfer. The object is copied when
+     * the call starts. See {@link FileTransferTrace}.
+     */
+    readonly trace?: FileTransferTrace | undefined;
+    /**
+     * The longest, in milliseconds, the transfer may go without moving a byte,
+     * the write of the transfer key included. When it passes, the transfer
+     * rejects with a {@link FileTransferError} whose `cause` is a `TimeoutError`
+     * and the connection is destroyed. `undefined` means the default, 30 000;
+     * `0` turns the limit off.
+     */
+    readonly idleTimeoutMs?: number | undefined;
 }
 /**
  * Open a connection to the file transfer port and send the transfer key.

package/dist/transfer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAKhD,mCAAmC;AACnC,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,yBAAyB,GAAG,SAAS,CAAC;CAChE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAuCD,kFAAkF;AAClF,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,qFAAqF;AACrF,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"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"}

package/dist/transport/handler.d.ts

@@ -25,6 +25,8 @@ export declare class PacketHandler {
      * ends the connection. Without an owner the error is logged.
      */
     onReceiveError: ((error: unknown) => void) | null;
+    /** Called with the socket once it is open, before the handshake's first packet is sent. */
+    onOpen: ((socket: DatagramSocket) => void) | null;
     constructor(crypt: Crypt, logger?: Logger, socketFactory?: SocketFactory);
     setClientID(id: number): void;
     /**

package/dist/transport/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/transport/handler.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,EACL,KAAK,MAAM,EACX,UAAU,EAMX,MAAM,aAAa,CAAC;AA4BrB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAa,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAgB,CAAC;AA4BhD,qBAAa,aAAa;;IACxB,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC9C,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IACtD;;;;OAIG;IACH,cAAc,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IA0CzD,YAAY,KAAK,EAAE,KAAK,EAAE,MAAM,GAAE,MAAmB,EAAE,aAAa,CAAC,EAAE,aAAa,EAInF;IAED,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5B;IAED;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAwD/D;IAOD,sGAAsG;IACtG,KAAK,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CA2ChC;IAED;;;;;;OAMG;IACH,oBAAoB,IAAI,IAAI,CAE3B;IAED,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOnE;IAED,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA6BrD;IAED,8EAA8E;IAC9E,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAwClF;IAED,4EAA4E;IAC5E,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,iDAAiD;IACjD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,KAAK,IAAI,IAAI,CAmBZ;CAufF"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/transport/handler.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,EACL,KAAK,MAAM,EACX,UAAU,EAMX,MAAM,aAAa,CAAC;AA4BrB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAa,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAgB,CAAC;AA4BhD,qBAAa,aAAa;;IACxB,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC9C,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IACtD;;;;OAIG;IACH,cAAc,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IACzD,2FAA2F;IAC3F,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IA0CzD,YAAY,KAAK,EAAE,KAAK,EAAE,MAAM,GAAE,MAAmB,EAAE,aAAa,CAAC,EAAE,aAAa,EAInF;IAED,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5B;IAED;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAyD/D;IAOD,sGAAsG;IACtG,KAAK,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CA2ChC;IAED;;;;;;OAMG;IACH,oBAAoB,IAAI,IAAI,CAE3B;IAED,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOnE;IAED,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA6BrD;IAED,8EAA8E;IAC9E,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAwClF;IAED,4EAA4E;IAC5E,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,iDAAiD;IACjD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,KAAK,IAAI,IAAI,CAmBZ;CAwfF"}

package/dist/types.d.ts

@@ -1,115 +1,7 @@
-import type { ChannelID, ClientEntry, ClientID, CommandMiddleware, Logger, NotificationName, ServerGroupID, UID } from "@honeybbq/teamspeak-core";
+import type { ClientEnterEvent, ClientLeaveEvent, ClientMovedEvent, CommandMiddleware, KickedEvent, Logger, NotificationEvent, PokeEvent, TextMessageEvent, VoiceDataEvent } from "@honeybbq/teamspeak-core";
 import type { Duplex } from "node:stream";
 import type { ReconnectOptions } from "./reconnect.js";
-/** A text message, sent privately, to a channel, or to the whole server. */
-export interface TextMessageEvent {
-    /** The sender's nickname. */
-    readonly invokerName: string;
-    /** The sender's unique identifier. */
-    readonly invokerUID: UID;
-    /** The message, unescaped. */
-    readonly message: string;
-    /** The sender's server groups, as this client last saw them. */
-    readonly invokerGroups: readonly ServerGroupID[];
-    /**
-     * Private, channel or server; compare it with `TextMessageTarget`. A plain
-     * number, since a server may send a mode that table does not name.
-     */
-    readonly targetMode: number;
-    /**
-     * The client a private message was sent to. Channel and server messages
-     * carry no target, so it is 0 for them.
-     */
-    readonly targetID: ClientID;
-    /** The sender. */
-    readonly invokerID: ClientID;
-}
-/** A client changing channel, of its own accord or moved by someone. */
-export interface ClientMovedEvent {
-    /** Who moved the client; the client itself for a move of its own. */
-    readonly invokerName: string;
-    /** The mover's unique identifier. */
-    readonly invokerUID: UID;
-    /** The channel the client is now in. */
-    readonly targetChannelID: ChannelID;
-    /** Why the client moved; compare it with `Reason`. */
-    readonly reason: number;
-    /** The client that moved. */
-    readonly clientID: ClientID;
-    /** The mover. */
-    readonly invokerID: ClientID;
-}
-/**
- * A client going out of view: leaving the server, kicked or banned from it, or
- * in a channel that stopped being subscribed.
- */
-export interface ClientLeaveEvent {
-    /** The reason given for a kick or a ban, or the client's own parting message. */
-    readonly reasonMessage: string;
-    /** Why the client left; compare it with `Reason`. */
-    readonly reason: number;
-    /** The client that left. */
-    readonly clientID: ClientID;
-    /** Who kicked or banned the client; empty otherwise. */
-    readonly invokerName: string;
-    /** The kicker's unique identifier; empty unless kicked or banned. */
-    readonly invokerUID: UID;
-    /** The kicker; 0 unless kicked or banned. */
-    readonly invokerID: ClientID;
-}
-/** This client being kicked from its channel or the server. */
-export interface KickedEvent {
-    /** The reason the invoker gave. */
-    readonly reasonMessage: string;
-    /** `Reason.KickChannel`, `Reason.KickServer` or `Reason.KickServerBan`. */
-    readonly reason: number;
-    /** Who kicked this client. */
-    readonly invokerName: string;
-    /** The kicker's unique identifier. */
-    readonly invokerUID: UID;
-    /** The kicker. */
-    readonly invokerID: ClientID;
-}
-/**
- * A client coming into view: the same record `listClients` returns, so one
- * type describes a client however it was learned of; its own id is `id`, as
- * in every record. The fields only `clientlist -times` reports are undefined
- * here.
- */
-export type ClientEnterEvent = ClientEntry;
-/** This client being poked. */
-export interface PokeEvent {
-    /** Who poked. */
-    readonly invokerName: string;
-    /** The poker's unique identifier. */
-    readonly invokerUID: UID;
-    /** The poker. */
-    readonly invokerID: ClientID;
-    /** The poke's message, unescaped. */
-    readonly message: string;
-}
-/** Audio from another client, in the channel or whispered. */
-export interface VoiceDataEvent {
-    /** Who is speaking. */
-    readonly clientID: ClientID;
-    /**
-     * How the audio is encoded; compare it with `Codec`. A plain number, since a
-     * server may relay a codec that table does not name.
-     */
-    readonly codec: number;
-    /** One encoded frame, copied: it stays valid after the listener returns. */
-    readonly data: Uint8Array;
-}
-/**
- * A notification from the server, as it arrived: the escape hatch for one the
- * SDK does not model. Match its `name` against `NotificationName`.
- */
-export interface NotificationEvent {
-    /** The notification's name, such as `notifyserveredited`; `NotificationName` lists the known ones. */
-    readonly name: NotificationName | (string & {});
-    /** Its parameters, unescaped. */
-    readonly params: Readonly<Record<string, string>>;
-}
+import type { ClientTrace } from "./trace.js";
 /**
  * The events `Client.on()` takes, and what each delivers. May gain events in a
  * minor release; code that handles every event generically should expect
@@ -190,6 +82,14 @@ export interface DatagramSocket {
     once(event: "error", listener: (error: Error) => void): unknown;
     /** Stop listening for failures. */
     off(event: "error", listener: (error: Error) => void): unknown;
+    /**
+     * The local end of the socket, for a trace to report. Optional: a socket that
+     * cannot say is reported with an empty local address.
+     */
+    address?(): {
+        readonly address: string;
+        readonly port: number;
+    };
 }
 /** Creates the UDP socket the client talks through, for the given address family. */
 export type SocketFactory = (family: 4 | 6) => DatagramSocket;
@@ -266,6 +166,13 @@ export interface ClientOptions {
      * session. An explicit `disconnect()` never reconnects regardless.
      */
     readonly reconnect?: ReconnectOptions | undefined;
+    /**
+     * Hooks called at each milestone of every connection attempt, for timing,
+     * metrics and progress. The object is copied when the client is made, so
+     * changing it afterwards has no effect. See {@link ClientTrace} for the
+     * rules a hook follows.
+     */
+    readonly trace?: ClientTrace | undefined;
     /**
      * Creates the TCP socket a file transfer runs over.
      *

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,MAAM,EACN,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,gEAAgE;IAChE,WAAW,EAAE,gBAAgB,CAAC;IAC9B,qFAAqF;IACrF,WAAW,EAAE,gBAAgB,CAAC;IAC9B,kCAAkC;IAClC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,iCAAiC;IACjC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,+BAA+B;IAC/B,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,SAAS,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC,0EAA0E;IAC1E,SAAS,EAAE,IAAI,CAAC;IAChB;;;;OAIG;IACH,YAAY,EAAE,KAAK,GAAG,SAAS,CAAC;IAChC,qFAAqF;IACrF,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GACvB,aAAa,GACb,aAAa,GACb,aAAa,GACb,aAAa,GACb,OAAO,GACP,WAAW,GACX,cAAc,CAAC;AAEnB,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG;KACvB,CAAC,IAAI,eAAe,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;KAAE;CAC5E,CAAC,eAAe,CAAC,CAAC;AAEnB,gCAAgC;AAChC,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,QAAQ,IAAI,QAAQ,CAAC,CAAC,CAAC,SAAS,IAAI,GACrE,MAAM,IAAI,GACV,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAEnC,2FAA2F;AAC3F,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,UAAU,CAAC;AAIpD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACnE,qCAAqC;IACrC,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;IACtE,+CAA+C;IAC/C,KAAK,IAAI,IAAI,CAAC;IACd,yCAAyC;IACzC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC;IACvE,uDAAuD;IACvD,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC;IAC9D,qCAAqC;IACrC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IAClD,0DAA0D;IAC1D,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC;IAChE,mCAAmC;IACnC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC;IAC/D;;;OAGG;IACH,OAAO,CAAC,IAAI;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,qFAAqF;AACrF,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,KAAK,cAAc,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAI/E,sDAAsD;AACtD,QAAA,MAAM,kBAAkB;IACtB,gFAAgF;aAChF,YAAY,EAAE,cAAc;IAC5B,4DAA4D;aAC5D,UAAU,EAAE,YAAY;IACxB,mEAAmE;aACnE,SAAS,EAAE,WAAW;CACd,CAAC;AACX,kDAAkD;AAClD,eAAO,MAAM,YAAY,EAAE,OAAO,kBACiB,CAAC;AACpD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E,+EAA+E;AAC/E,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,KAAK,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;AAInG;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CACpC;AAID;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;KAAE,GACtD,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;CACrC;AAID,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,kGAAkG;IAClG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,yBAAyB,GAAG,SAAS,CAAC;IAC3E;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAChD,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,iBAAiB,EAAE,GAAG,SAAS,CAAC;IACtE,8FAA8F;IAC9F,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,CAAC;IAClE,sEAAsE;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,qFAAqF;IACrF,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@honeybbq/teamspeak-client",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "description": "A clean-room TeamSpeak client for Node.js, speaking the voice protocol the way the TeamSpeak application does",
   "keywords": [
     "client",
@@ -10,6 +10,10 @@
     "ts6",
     "voip"
   ],
+  "homepage": "https://github.com/HoneyBBQ/teamspeak-js/tree/main/packages/client#readme",
+  "bugs": {
+    "url": "https://github.com/HoneyBBQ/teamspeak-js/issues"
+  },
   "license": "MIT",
   "author": "honeybbq",
   "repository": {
@@ -30,17 +34,19 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "dependencies": {
     "@noble/curves": "^2.0.1",
-    "@honeybbq/teamspeak-core": "1.0.0-beta.2"
+    "@honeybbq/teamspeak-core": "1.0.0-beta.4"
   },
   "engines": {
-    "node": ">=20.19"
+    "node": ">=22.12"
   },
   "scripts": {
     "build": "vite build && tsc -p tsconfig.build.json",

package/src/capabilities.ts

@@ -12,8 +12,8 @@
  * round trip.
  */
 
-import type { IconID } from "@honeybbq/teamspeak-core";
-import { parseIconID } from "@honeybbq/teamspeak-core/internal";
+import { asServerID, type IconID, type ServerID } from "@honeybbq/teamspeak-core";
+import { parseIconID, parseUint64 } from "@honeybbq/teamspeak-core/internal";
 import { uidAlgorithmForVersion, type UIDAlgorithm } from "./crypto/identity.js";
 
 /**
@@ -50,6 +50,18 @@ export interface ServerCapabilities {
   readonly hostBannerImageURL: string | undefined;
   /** The welcome message shown on connecting (`virtualserver_welcomemessage`). */
   readonly welcomeMessage: string;
+  /** The virtual server's ID (`virtualserver_id`); 0 when the server did not send it. */
+  readonly serverID: ServerID;
+  /** The virtual server's unique identifier (`virtualserver_unique_identifier`); empty when not sent. */
+  readonly serverUID: string;
+  /** The host message (`virtualserver_hostmessage`) the server wants shown on connecting. */
+  readonly hostMessage: string;
+  /**
+   * How the host message is to be shown (`virtualserver_hostmessage_mode`):
+   * 0 not at all, 1 in the chat log, 2 as a modal dialog, 3 as a modal dialog
+   * after which the client is disconnected.
+   */
+  readonly hostMessageMode: number;
 }
 
 /**
@@ -78,6 +90,10 @@ export function parseServerCapabilities(
     iconID: parseIconID(params["virtualserver_icon_id"]),
     hostBannerImageURL: params["virtualserver_hostbanner_gfx_url"]?.trim() || undefined,
     welcomeMessage: params["virtualserver_welcomemessage"] ?? "",
+    serverID: asServerID(parseUint64(params["virtualserver_id"] ?? "")),
+    serverUID: params["virtualserver_unique_identifier"] ?? "",
+    hostMessage: params["virtualserver_hostmessage"] ?? "",
+    hostMessageMode: hostMessageMode(params["virtualserver_hostmessage_mode"]),
   };
 }
 
@@ -90,3 +106,8 @@ export function parseServerCapabilities(
 export function unknownServerCapabilities(): ServerCapabilities {
   return parseServerCapabilities("");
 }
+
+function hostMessageMode(value: string | undefined): number {
+  const parsed = Number.parseInt(value ?? "", 10);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}