@honeybbq/teamspeak 1.0.0-beta.12 → 1.0.0-beta.13

package/src/core/notifications.ts

@@ -24,6 +24,8 @@ import { Reason } from "./reason.js";
 import { applyClientChanges } from "./api/clients.js";
 import { parseInt10, parseUint16, parseUint64 } from "./helpers.js";
 import type { Command } from "./command/command.js";
+import type { ChannelID } from "./command/ids.js";
+import type { ClientEntry } from "./api/clients.js";
 import type {
   ChannelCreatedEvent,
   ChannelDeletedEvent,
@@ -33,6 +35,7 @@ import type {
   ChannelPasswordChangedEvent,
   ChannelSubscribedEvent,
   ChannelUnsubscribedEvent,
+  ClientChatClosedEvent,
   ClientChatComposingEvent,
   ClientEnterEvent,
   ClientChannelGroupChangedEvent,
@@ -70,6 +73,7 @@ export type NotificationResult =
   | { kind: "channelUnsubscribed"; event: ChannelUnsubscribedEvent }
   | { kind: "pluginCommand"; event: PluginCommandEvent }
   | { kind: "clientChatComposing"; event: ClientChatComposingEvent }
+  | { kind: "clientChatClosed"; event: ClientChatClosedEvent }
   | { kind: "unknown" };
 
 /**
@@ -87,7 +91,7 @@ export type NotificationResult =
 export function handleNotification(
   cmd: Command,
   selfCLID: number,
-  clients: Map<number, ClientEnterEvent>,
+  clients: Map<number, ClientEntry>,
 ): NotificationResult {
   switch (cmd.name) {
     case "notifycliententerview":
@@ -137,6 +141,8 @@ export function handleNotification(
       };
     case "notifyclientchatcomposing":
       return handleChatComposing(cmd);
+    case "notifyclientchatclosed":
+      return handleChatClosed(cmd);
     default:
       return { kind: "unknown" };
   }
@@ -144,19 +150,41 @@ export function handleNotification(
 
 function handleClientEnterView(
   cmd: Command,
-  clients: Map<number, ClientEnterEvent>,
+  clients: Map<number, ClientEntry>,
 ): NotificationResult {
   const info = parseClient(cmd.params);
   // No client has id 0: a row without one describes nobody.
   if (info.id === 0) return { kind: "unknown" };
+  // The roster keeps the record alone; the event adds where it came from and why.
   clients.set(info.id, info);
-  return { kind: "clientEnter", info };
+  return {
+    kind: "clientEnter",
+    info: {
+      ...info,
+      ...channelOf(cmd.params, "cfid", "fromChannelID"),
+      ...(cmd.params["reasonid"] === undefined
+        ? {}
+        : { reason: parseInt10(cmd.params["reasonid"]) }),
+    },
+  };
+}
+
+/** A channel id the row names under `key`, as `{ [name]: id }`; nothing when the row lacks the key. */
+function channelOf<N extends string>(
+  params: Readonly<Record<string, string>>,
+  key: string,
+  name: N,
+): { [K in N]?: ChannelID } {
+  const raw = params[key];
+  return raw === undefined
+    ? {}
+    : ({ [name]: asChannelID(parseUint64(raw)) } as { [K in N]?: ChannelID });
 }
 
 function handleClientLeftView(
   cmd: Command,
   selfCLID: number,
-  clients: Map<number, ClientEnterEvent>,
+  clients: Map<number, ClientEntry>,
 ): NotificationResult {
   const clid = asClientID(parseUint16(cmd.params["clid"] ?? ""));
   if (clid === 0) return { kind: "unknown" };
@@ -166,6 +194,8 @@ function handleClientLeftView(
     kind: "clientLeave",
     event: {
       clientID: clid,
+      ...channelOf(cmd.params, "cfid", "fromChannelID"),
+      ...channelOf(cmd.params, "ctid", "targetChannelID"),
       reason: parseInt10(cmd.params["reasonid"] ?? ""),
       reasonMessage: cmd.params["reasonmsg"] ?? "",
       invokerID: asClientID(parseUint16(cmd.params["invokerid"] ?? "")),
@@ -176,10 +206,7 @@ function handleClientLeftView(
   };
 }
 
-function handleClientMoved(
-  cmd: Command,
-  clients: Map<number, ClientEnterEvent>,
-): NotificationResult {
+function handleClientMoved(cmd: Command, clients: Map<number, ClientEntry>): NotificationResult {
   const clid = asClientID(parseUint16(cmd.params["clid"] ?? ""));
   const ctid = asChannelID(parseUint64(cmd.params["ctid"] ?? ""));
   if (clid === 0) return { kind: "unknown" };
@@ -197,6 +224,7 @@ function handleClientMoved(
     event: {
       clientID: clid,
       targetChannelID: ctid,
+      ...channelOf(cmd.params, "cfid", "fromChannelID"),
       reason: parseInt10(cmd.params["reasonid"] ?? ""),
       reasonMessage: cmd.params["reasonmsg"] ?? "",
       invokerID,
@@ -206,10 +234,7 @@ function handleClientMoved(
   };
 }
 
-function handleTextMessage(
-  cmd: Command,
-  clients: Map<number, ClientEnterEvent>,
-): NotificationResult {
+function handleTextMessage(cmd: Command, clients: Map<number, ClientEntry>): NotificationResult {
   const invokerID = asClientID(parseUint16(cmd.params["invokerid"] ?? ""));
   const invokerInfo = clients.get(invokerID);
 
@@ -246,10 +271,7 @@ function invoked(params: Readonly<Record<string, string>>): Invoked {
   };
 }
 
-function handleClientUpdated(
-  cmd: Command,
-  clients: Map<number, ClientEnterEvent>,
-): NotificationResult {
+function handleClientUpdated(cmd: Command, clients: Map<number, ClientEntry>): NotificationResult {
   const clid = asClientID(parseUint16(cmd.params["clid"] ?? ""));
   if (clid === 0) return { kind: "unknown" };
   const changes = parseClientChanges(cmd.params);
@@ -282,7 +304,7 @@ function handleServerGroupMember(
 
 function handleClientChannelGroupChanged(
   cmd: Command,
-  clients: Map<number, ClientEnterEvent>,
+  clients: Map<number, ClientEntry>,
 ): NotificationResult {
   const clid = asClientID(parseUint16(cmd.params["clid"] ?? ""));
   if (clid === 0) return { kind: "unknown" };
@@ -402,3 +424,12 @@ function handleChatComposing(cmd: Command): NotificationResult {
     event: { clientID: clid, uid: asUID(cmd.params["cluid"] ?? "") },
   };
 }
+
+function handleChatClosed(cmd: Command): NotificationResult {
+  const clid = asClientID(parseUint16(cmd.params["clid"] ?? ""));
+  if (clid === 0) return { kind: "unknown" };
+  return {
+    kind: "clientChatClosed",
+    event: { clientID: clid, uid: asUID(cmd.params["cluid"] ?? "") },
+  };
+}

package/src/core/types.ts

@@ -148,3 +148,17 @@ export type ClientStatus = (typeof ClientStatus)[keyof typeof ClientStatus];
  * default case.
  */
 export type ServerFamily = "ts3" | "ts6" | "unknown";
+
+/**
+ * Pick the server generation from a `virtualserver_version` string such as
+ * "6.0.0-beta13.1" or "3.13.8 [Build: 1779874471]": major version 3 is TS3,
+ * 6 and later TS6, anything else, including a string with no number, unknown.
+ * Both clients use it, so they cannot disagree about the same server.
+ */
+export function serverFamilyForVersion(version: string): ServerFamily {
+  const major = Number.parseInt(version, 10);
+  if (Number.isNaN(major)) return "unknown";
+  if (major === 3) return "ts3";
+  if (major >= 6) return "ts6";
+  return "unknown";
+}

package/src/query/client.ts

@@ -9,7 +9,7 @@ import {
   TeamspeakError,
   backoffDelay,
   noopLogger,
-  type ClientEnterEvent,
+  type ClientEntry,
   type CommandExecutor,
   type CommandMiddleware,
   type CommandOptions,
@@ -18,6 +18,7 @@ import {
   type Listener,
   type Logger,
   type ReconnectOptions,
+  serverFamilyForVersion,
   type ServerEventMap,
   type ServerFamily,
   type ServerID,
@@ -33,7 +34,7 @@ import {
   parseServerError,
   resolveBackoffPolicy,
 } from "../core/internal.js";
-import type { QueryTransport } from "./transport.js";
+import type { QueryTransport, QueryTransportStats } from "./transport.js";
 import { connectTcp } from "./tcp.js";
 import { connectSsh } from "./ssh.js";
 import { WebQueryTransport } from "./web.js";
@@ -154,7 +155,7 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
    * 0 until it is known.
    */
   #clid = 0;
-  #clients = new Map<number, ClientEnterEvent>();
+  #clients = new Map<number, ClientEntry>();
 
   #reconnectOptions: ReconnectOptions | undefined;
   #reconnecting = false;
@@ -231,12 +232,32 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     return this.#version;
   }
 
+  /**
+   * What the current connection reports about itself: its kind, where it
+   * points, when it opened and how many bytes went each way, for a metrics
+   * exporter. Read-only. A client with no connection, and a `custom` transport
+   * that keeps no counts, report no kind, an empty address, no open time and
+   * zero bytes. A reconnection starts the counts again.
+   *
+   * @experimental Part of the entry, which may change in a minor release.
+   */
+  get stats(): QueryTransportStats {
+    return (
+      this.#transport?.stats?.() ?? {
+        connectedAt: undefined,
+        transport: undefined,
+        address: "",
+        bytesSent: 0,
+        bytesReceived: 0,
+      }
+    );
+  }
+
   /**
    * The transport carrying this connection, or `undefined` when there is none.
    *
    * Read-only, and the transport is the interface the client itself talks
-   * over — counts of what went out and came in, and which connection it is,
-   * can be read from it for metrics. The socket underneath is not exposed:
+   * over. The socket underneath is not exposed:
    * a caller that needs it supplies the seam instead (the `connect` option of
    * a `tcp` transport, or `connection` of an `ssh` one), where it is theirs to
    * keep.
@@ -384,7 +405,7 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     // Not `use()`: this session learns who it is, and who is there, once, below.
     if (server !== undefined) await this.#select(server, { nickname, signal });
     this.#version = await this.#getVersion(signal);
-    this.#serverFamily = serverFamilyOf(this.#version);
+    this.#serverFamily = serverFamilyForVersion(this.#version);
     // Like the version, a failure here fails the connect: a client that cannot
     // tell which one it is would miss its own kick without saying so.
     await this.#learnSelf(signal);
@@ -1020,6 +1041,7 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
       case "channelUnsubscribed":
       case "pluginCommand":
       case "clientChatComposing":
+      case "clientChatClosed":
       // Neither a TeamSpeak 3 ServerQuery connection nor a TeamSpeak 6 one over
       // SSH is sent these (measured), so a query client does not offer them.
       // Should a server send one, the clients it knows are still kept current
@@ -1269,15 +1291,6 @@ function serverIDOf(server: ResolvedQueryOptions["server"]): ServerID | number |
   return server !== undefined && "id" in server ? server.id : undefined;
 }
 
-/** Which server generation a `version` string names. */
-function serverFamilyOf(version: string): ServerFamily {
-  const major = Number.parseInt(version, 10);
-  if (Number.isNaN(major)) return "unknown";
-  if (major === 3) return "ts3";
-  if (major >= 6) return "ts6";
-  return "unknown";
-}
-
 /** Sleep, or wake early once `signal` aborts. Resolves either way, never rejects. */
 function sleep(ms: number, signal: AbortSignal): Promise<void> {
   if (ms <= 0 || signal.aborted) return Promise.resolve();

package/src/query/index.ts

@@ -31,7 +31,7 @@ export type {
   QueryTransportOptions,
 } from "./client.js";
 
-export type { QueryTransport } from "./transport.js";
+export type { QueryTransport, QueryTransportStats } from "./transport.js";
 
 // Reconnection: the client's default retry decision, and the shared options.
 export { defaultShouldRetry } from "./reconnect.js";

package/src/query/options.ts

@@ -46,9 +46,17 @@ export type QueryTransportOptions =
   | ({
       /** WebQuery, the HTTP interface of TeamSpeak 3 (3.12 and later) and TeamSpeak 6. */
       readonly kind: "web";
-      /** The server's base URL, such as `http://127.0.0.1:10080`. */
+      /**
+       * The server's base URL, such as `http://127.0.0.1:10080` or
+       * `https://ts.example.com:10443`.
+       */
       readonly url: string;
-      /** The `fetch` to use; a small one over `node:http` by default. */
+      /**
+       * The `fetch` to use; by default a small one over `node:http` or
+       * `node:https` by the URL's scheme, verifying an HTTPS certificate
+       * against Node's trust store. For a private CA, pass a `fetch` that
+       * trusts it, or start Node with `NODE_EXTRA_CA_CERTS`.
+       */
       readonly fetch?: typeof fetch | undefined;
     } & WebCredentials)
   | {
@@ -67,7 +75,10 @@ export type QueryTransportOptions =
  * `servernotifyregister`.
  *
  * `bans` is not registered by default: TeamSpeak 3 refuses it with 1539,
- * which would fail the registration of every category after it.
+ * which would fail the registration of every category after it. `tokenused`
+ * is not registered by default either: both servers accept it (measured) and
+ * then send `notifytokenused`, which carries a privilege key and has no typed
+ * event, so it reaches `notification` only.
  */
 export type QueryEventCategory =
   | "server"
@@ -75,7 +86,8 @@ export type QueryEventCategory =
   | "textserver"
   | "textchannel"
   | "textprivate"
-  | "bans";
+  | "bans"
+  | "tokenused";
 
 /**
  * Which notification categories to register for.
@@ -95,7 +107,8 @@ export type QueryEventCategory =
  * | `server`                                | `serverEdited`                                                                                                                              |
  * | `channel` (registered for every channel) | `channelCreated`, `channelEdited`, `channelMoved`, `channelDeleted`, `channelDescriptionChanged`, `channelPasswordChanged`, `clientEnter`, `clientLeave`, `clientMoved` |
  * | `textserver`, `textchannel`, `textprivate` | `textMessage`, for the server, the channel and private messages                                                                         |
- * | `bans`                                  | none                                                                                                                                        |
+ * | `bans`                                  | `banUpdated`                                                                                                                                |
+ * | `tokenused`                             | none (`notification` only)                                                                                                                  |
  *
  * Leaving a category out leaves its events out: `{ categories: ["textprivate"] }`
  * delivers no channel event. The voice client's events about clients' updates,
@@ -158,6 +171,7 @@ const CATEGORIES: ReadonlySet<string> = new Set([
   "textchannel",
   "textprivate",
   "bans",
+  "tokenused",
 ]);
 
 /** A transport with its defaults filled, and its fields copied. */

package/src/query/ssh.ts

@@ -538,7 +538,12 @@ export async function connectSsh(options: SshOptions): Promise<StreamTransport>
         // stream closes with it.
         ssh.on("error", (failure) => channel.emit("error", failure));
         channel.once("close", () => ssh.end());
-        resolve(new StreamTransport(channel, () => ssh.end()));
+        resolve(
+          new StreamTransport(channel, () => ssh.end(), {
+            transport: "ssh",
+            address: `${login === undefined ? "" : `${login.username}@`}${host}:${port}`,
+          }),
+        );
       });
     };
 

package/src/query/stream.ts

@@ -1,5 +1,5 @@
 import { LineReader } from "./lines.js";
-import type { QueryTransport } from "./transport.js";
+import type { QueryTransport, QueryTransportStats } from "./transport.js";
 
 /**
  * The part of a duplex byte stream a line transport uses. A `node:net` socket
@@ -43,14 +43,24 @@ export class StreamTransport implements QueryTransport {
   /** Wakes a `close()` that is waiting for the server to end the session. */
   #onEnded: (() => void) | undefined;
   #error: Error | undefined;
+  #identity: { readonly transport: "tcp" | "ssh"; readonly address: string } | undefined;
+  #openedAt = new Date();
+  #bytesSent = 0;
+  #bytesReceived = 0;
 
   /**
    * `onEnd` runs once the stream is closed, to release what the stream sits
-   * on: an SSH session's connection, say.
+   * on: an SSH session's connection, say. `identity` says which kind of
+   * connection this is and where it points, for {@link StreamTransport.stats}.
    */
-  constructor(stream: QueryStream, onEnd?: () => void) {
+  constructor(
+    stream: QueryStream,
+    onEnd?: () => void,
+    identity?: { readonly transport: "tcp" | "ssh"; readonly address: string },
+  ) {
     this.#stream = stream;
     this.#onEnd = onEnd;
+    this.#identity = identity;
     stream.on("data", (chunk) => this.#handleData(chunk));
     stream.on("error", (error) => {
       this.#error = error;
@@ -61,10 +71,26 @@ export class StreamTransport implements QueryTransport {
   send(line: string): Promise<void> {
     if (this.#ended) return Promise.reject(new Error("the query connection is closed"));
     return new Promise((resolve, reject) => {
-      this.#stream.write(`${line}\n`, (error) => (error ? reject(error) : resolve()));
+      this.#stream.write(`${line}\n`, (error) => {
+        if (error) reject(error);
+        else {
+          this.#bytesSent += Buffer.byteLength(line) + 1;
+          resolve();
+        }
+      });
     });
   }
 
+  stats(): QueryTransportStats {
+    return {
+      connectedAt: this.#openedAt,
+      transport: this.#identity?.transport,
+      address: this.#identity?.address ?? "",
+      bytesSent: this.#bytesSent,
+      bytesReceived: this.#bytesReceived,
+    };
+  }
+
   /**
    * Say `quit`, give the server a moment to end the session, and close.
    *
@@ -103,6 +129,7 @@ export class StreamTransport implements QueryTransport {
   }
 
   #handleData(chunk: Uint8Array): void {
+    this.#bytesReceived += chunk.byteLength;
     for (const line of this.#reader.push(chunk)) {
       if (this.#banner > 0) {
         this.#banner--;

package/src/query/tcp.ts

@@ -43,7 +43,7 @@ export async function connectTcp(options: TcpOptions): Promise<StreamTransport>
   signal?.throwIfAborted();
   const stream = await connect(host, port);
   await opened(stream, signal);
-  return new StreamTransport(stream);
+  return new StreamTransport(stream, undefined, { transport: "tcp", address: `${host}:${port}` });
 }
 
 /** A connected `node:net` socket, with whole lines sent as they are written. */