@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.7

package/src/core/command/command.ts

@@ -0,0 +1,125 @@
+const ESCAPE_MAP: Array<[string, string]> = [
+  ["\\", "\\\\"],
+  ["/", "\\/"],
+  [" ", "\\s"],
+  ["|", "\\p"],
+  ["\x07", "\\a"],
+  ["\x08", "\\b"],
+  ["\x0C", "\\f"],
+  ["\n", "\\n"],
+  ["\r", "\\r"],
+  ["\t", "\\t"],
+  ["\x0B", "\\v"],
+];
+
+/**
+ * Escape a value for the command line: the characters that delimit a command
+ * (space, `|`, `/`, the backslash itself, control characters) become their
+ * two-character escapes.
+ */
+export function escape(s: string): string {
+  let result = s;
+  for (const [from, to] of ESCAPE_MAP) {
+    result = result.split(from).join(to);
+  }
+  return result;
+}
+
+/** Undo {@link escape}, in one pass so that `\\s` comes back as `\s`, not a space. */
+export function unescape(s: string): string {
+  // Process escape sequences in a single pass to avoid double-substitution
+  let result = "";
+  let i = 0;
+  while (i < s.length) {
+    if (s[i] === "\\" && i + 1 < s.length) {
+      const next = s[i + 1];
+      switch (next) {
+        case "\\":
+          result += "\\";
+          i += 2;
+          break;
+        case "/":
+          result += "/";
+          i += 2;
+          break;
+        case "s":
+          result += " ";
+          i += 2;
+          break;
+        case "p":
+          result += "|";
+          i += 2;
+          break;
+        case "a":
+          result += "\x07";
+          i += 2;
+          break;
+        case "b":
+          result += "\x08";
+          i += 2;
+          break;
+        case "f":
+          result += "\x0C";
+          i += 2;
+          break;
+        case "n":
+          result += "\n";
+          i += 2;
+          break;
+        case "r":
+          result += "\r";
+          i += 2;
+          break;
+        case "t":
+          result += "\t";
+          i += 2;
+          break;
+        case "v":
+          result += "\x0B";
+          i += 2;
+          break;
+        case undefined:
+        default:
+          result += s[i] ?? "";
+          i++;
+          break;
+      }
+    } else {
+      result += s[i] ?? "";
+      i++;
+    }
+  }
+  return result;
+}
+
+/** A command line, parsed. */
+export interface Command {
+  /** The command's name, or `""` for a data row, which carries no name. */
+  readonly name: string;
+  /** Its parameters, unescaped. A flag such as `-uid` maps to `""`. */
+  readonly params: Readonly<Record<string, string>>;
+}
+
+/** Build a command line from a parameter map; keys and values are escaped alike. */
+export function buildCommand(cmd: string, params: Readonly<Record<string, string>>): string {
+  const parts: string[] = [escape(cmd)];
+  for (const [k, v] of Object.entries(params)) {
+    parts.push(`${escape(k)}=${escape(v)}`);
+  }
+  return parts.join(" ");
+}
+
+/** Build a TS3 command string preserving parameter order. */
+export function buildCommandOrdered(
+  cmd: string,
+  params: ReadonlyArray<readonly [string, string]>,
+): string {
+  const parts: string[] = [escape(cmd)];
+  for (const [k, v] of params) {
+    // A flag such as `-uid` is a bare switch. `-uid=1` happens to be accepted
+    // over the voice protocol, but it is not the documented form and nothing
+    // promises another transport tolerates it.
+    parts.push(k.startsWith("-") && v === "" ? escape(k) : `${escape(k)}=${escape(v)}`);
+  }
+  return parts.join(" ");
+}

package/src/core/command/ids.ts

@@ -0,0 +1,149 @@
+/**
+ * Branded identifiers.
+ *
+ * TeamSpeak uses one 64-bit integer space for several unrelated kinds of id, so
+ * a `bigint` alone cannot tell a channel from a client. Branding makes the
+ * mistake a compile error instead of a silent move-to-the-wrong-place, and the
+ * brands cost nothing at runtime.
+ *
+ * The ids the protocol defines as 32 bits or narrower — a clid, a permission,
+ * an icon — are `number` brands; the 64-bit ones are `bigint` brands.
+ */
+
+/** A channel (`cid`). */
+export type ChannelID = bigint & { readonly __brand: "ChannelID" };
+/**
+ * A connected client (`clid`): an id for this connection only, assigned anew
+ * every time the client connects.
+ */
+export type ClientID = number & { readonly __brand: "ClientID" };
+/**
+ * A client's database record (`cldbid`): stable across connections, unlike its
+ * ClientID.
+ */
+export type ClientDBID = bigint & { readonly __brand: "ClientDBID" };
+/** A server group (`sgid`). */
+export type ServerGroupID = bigint & { readonly __brand: "ServerGroupID" };
+/** A channel group (`cgid`). */
+export type ChannelGroupID = bigint & { readonly __brand: "ChannelGroupID" };
+/** A permission's numeric id (`permid`), a 32-bit value assigned by the server build. */
+export type PermissionID = number & { readonly __brand: "PermissionID" };
+/**
+ * An icon: the unsigned CRC32 of the icon file, which also names the file
+ * (`/icon_<id>`) in the server's file area.
+ */
+export type IconID = number & { readonly __brand: "IconID" };
+
+/** A ban (`banid`). */
+export type BanID = bigint & { readonly __brand: "BanID" };
+/** An offline message (`msgid`). */
+export type MessageID = bigint & { readonly __brand: "MessageID" };
+/** A virtual server on an instance (`sid`, `virtualserver_id`). */
+export type ServerID = bigint & { readonly __brand: "ServerID" };
+/** The client's id for a file transfer (`clientftfid`), a 16-bit value it chooses. */
+export type ClientFileTransferID = number & { readonly __brand: "ClientFileTransferID" };
+/** The server's id for a file transfer (`serverftfid`), a 16-bit value. */
+export type ServerFileTransferID = number & { readonly __brand: "ServerFileTransferID" };
+
+const MAX_UINT16 = 0xffff;
+const MAX_UINT32 = 0xffff_ffff;
+const MAX_UINT64 = (1n << 64n) - 1n;
+
+/** `v` if it is an integer from 0 to `max`; a RangeError otherwise. */
+function uintInRange(v: number, max: number, what: string): number {
+  if (typeof v !== "number" || !Number.isInteger(v) || v < 0 || v > max) {
+    throw new RangeError(`${what} is an integer from 0 to ${max}, not ${String(v)}`);
+  }
+  return v;
+}
+
+/** `v` as a bigint if it is an integer from 0 to 2^64-1; a RangeError otherwise. */
+function uint64(v: bigint | number, what: string): bigint {
+  const integer = typeof v === "bigint" || (typeof v === "number" && Number.isInteger(v));
+  const value = integer ? BigInt(v) : -1n;
+  if (value < 0n || value > MAX_UINT64) {
+    throw new RangeError(`${what} is an integer from 0 to 2^64-1, not ${String(v)}`);
+  }
+  return value;
+}
+
+// Every constructor checks its value against the id's wire width and throws a
+// RangeError for anything else — a fraction, a negative, a value too wide —
+// rather than brand a value no server could mean.
+
+/** Brand a ban id, an integer from 0 to 2^64-1, from a number or a bigint. */
+export const asBanID = (v: bigint | number): BanID => uint64(v, "a ban id") as BanID;
+/** Brand an offline message id, an integer from 0 to 2^64-1. */
+export const asMessageID = (v: bigint | number): MessageID =>
+  uint64(v, "a message id") as MessageID;
+/** Brand a virtual server id, an integer from 0 to 2^64-1. */
+export const asServerID = (v: bigint | number): ServerID => uint64(v, "a server id") as ServerID;
+/** Brand the client's id for a file transfer, an integer from 0 to 65535. */
+export const asClientFileTransferID = (v: number): ClientFileTransferID =>
+  uintInRange(v, MAX_UINT16, "a client file transfer id") as ClientFileTransferID;
+/** Brand the server's id for a file transfer, an integer from 0 to 65535. */
+export const asServerFileTransferID = (v: number): ServerFileTransferID =>
+  uintInRange(v, MAX_UINT16, "a server file transfer id") as ServerFileTransferID;
+
+/** Brand a channel id, an integer from 0 to 2^64-1, from a number or a bigint. */
+export const asChannelID = (v: bigint | number): ChannelID =>
+  uint64(v, "a channel id") as ChannelID;
+/** Brand a client id, an integer from 0 to 65535: the voice protocol's width. */
+export const asClientID = (v: number): ClientID =>
+  uintInRange(v, MAX_UINT16, "a client id") as ClientID;
+/** Brand a client database id, an integer from 0 to 2^64-1. */
+export const asClientDBID = (v: bigint | number): ClientDBID =>
+  uint64(v, "a client database id") as ClientDBID;
+/** Brand a server group id, an integer from 0 to 2^64-1. */
+export const asServerGroupID = (v: bigint | number): ServerGroupID =>
+  uint64(v, "a server group id") as ServerGroupID;
+/** Brand a channel group id, an integer from 0 to 2^64-1. */
+export const asChannelGroupID = (v: bigint | number): ChannelGroupID =>
+  uint64(v, "a channel group id") as ChannelGroupID;
+/** Brand a permission id, an integer from 0 to 2^32-1. */
+export const asPermissionID = (v: number): PermissionID =>
+  uintInRange(v, MAX_UINT32, "a permission id") as PermissionID;
+/**
+ * Brand an icon id, an integer from -2^31 to 2^32-1. A negative value is taken
+ * as the signed form of the same CRC32, which is how the server sometimes
+ * sends one, and stored unsigned.
+ */
+export const asIconID = (v: number): IconID => {
+  if (typeof v !== "number" || !Number.isInteger(v) || v < -(2 ** 31) || v > MAX_UINT32) {
+    throw new RangeError(`an icon id is an integer from -2^31 to 2^32-1, not ${String(v)}`);
+  }
+  return (v >>> 0) as IconID;
+};
+
+/**
+ * Read an icon id as the server sends it: the CRC32, sometimes as a negative
+ * 32-bit number, sometimes unsigned. Both name the same icon, so both come back
+ * as the unsigned value; 0, garbage and out-of-range values mean no icon.
+ */
+export function parseIconID(raw: string | undefined): IconID | undefined {
+  const text = raw?.trim() ?? "";
+  if (!/^-?\d{1,10}$/.test(text)) return undefined;
+  const value = Number(text);
+  if (value < -(2 ** 31) || value >= 2 ** 32 || value === 0) return undefined;
+  return asIconID(value);
+}
+
+/**
+ * A unique identifier: `base64(SHA-1(publicKey))` on TeamSpeak 3 and
+ * `base64(SHA-256(publicKey))` on TeamSpeak 6.
+ *
+ * The length differs between versions, so treat it as opaque bytes rather than
+ * assuming either width.
+ */
+export type UID = string & { readonly __brand: "UID" };
+/** Brand a unique identifier. */
+export const asUID = (v: string): UID => v as UID;
+
+/**
+ * A channel's unique identifier (`channel_unique_identifier`), which TS6
+ * gives every channel and TS3 does not send. Opaque text, and not a client's
+ * {@link UID}.
+ */
+export type ChannelUID = string & { readonly __brand: "ChannelUID" };
+/** Brand a channel's unique identifier. */
+export const asChannelUID = (v: string): ChannelUID => v as ChannelUID;

package/src/core/command/parser.ts

@@ -0,0 +1,68 @@
+import { unescape } from "./command.js";
+import type { Command } from "./command.js";
+
+/**
+ * Whether a token is a command name.
+ *
+ * A command name is a run of ASCII alphanumerics — the rule tsproto-packets
+ * uses (CommandParser::new). Everything that splits or parses a line asks this
+ * one function, so the parser and the row splitter cannot disagree about where
+ * a command's data begins.
+ */
+export function isCommandName(token: string): boolean {
+  return /^[A-Za-z0-9]+$/.test(token);
+}
+
+/**
+ * Parse one command line, or one row of it. Returns null for an empty line.
+ * A line whose first token is not a command name is a data row, with `name`
+ * `""`.
+ */
+export function parseCommand(s: string): Command | null {
+  if (s === "") return null;
+
+  // Skip leading non-printable bytes (< 0x20 or > 0x7E)
+  let startIndex = 0;
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    if (code >= 32 && code <= 126) {
+      startIndex = i;
+      break;
+    }
+  }
+  if (startIndex > 0) {
+    s = s.slice(startIndex);
+  }
+
+  const parts = s.split(" ");
+  if (parts.length === 0) return null;
+
+  // A command name is a run of alphanumerics followed by a space — the rule
+  // tsproto-packets uses (CommandParser::new). Anything else means the line is
+  // not a command at all: response rows carry no name ("clid=6 cid=2 ..."),
+  // and negative feedback is "-1 id=2 ...", naming the *rejected* command id
+  // rather than a command of its own. Returning those as a nameless row keeps
+  // the data intact instead of folding the first field into a name, which is
+  // how a clientlist row used to arrive as name="clid=6" and lose its clid.
+  const first = parts[0] ?? "";
+  if (first === "") return null;
+
+  // No prototype: a key is whatever the line says, and one named __proto__
+  // must be stored, not swallowed by Object.prototype's setter.
+  const params: Record<string, string> = Object.create(null) as Record<string, string>;
+  const name = isCommandName(first) ? first : "";
+  const start = name === "" ? 0 : 1;
+
+  for (let i = start; i < parts.length; i++) {
+    const p = parts[i];
+    if (p === undefined || p === "") continue;
+    const eqIdx = p.indexOf("=");
+    if (eqIdx >= 0) {
+      params[unescape(p.slice(0, eqIdx))] = unescape(p.slice(eqIdx + 1));
+    } else {
+      params[unescape(p)] = "";
+    }
+  }
+
+  return { name, params };
+}

package/src/core/command/request.ts

@@ -0,0 +1,119 @@
+/**
+ * A command as the typed layer describes it, before a transport encodes it.
+ *
+ * The typed commands run on any connection that can execute a command — the
+ * voice client today, ServerQuery later — and the two disagree about how some
+ * values go on the wire. A channel password is the case that matters: the
+ * voice protocol expects `base64(sha1(password))`, while ServerQuery takes the
+ * password itself and hashes it server-side. So a request says *which*
+ * parameters are passwords and leaves their encoding to the transport.
+ */
+
+import type { CommandName } from "../command-name.js";
+import { buildCommandOrdered } from "./command.js";
+
+/** A parameter value as a caller may supply it. */
+export type ParamValue = string | number | bigint | boolean | undefined;
+
+/** A command and its parameters, in the order they are sent. */
+export interface CommandRequest {
+  /** The command's name, such as `clientlist`; {@link CommandName} lists the known ones. */
+  readonly command: CommandName | (string & {});
+  /**
+   * Its parameters, as wire name and value pairs, in the order they are sent;
+   * an undefined value is omitted.
+   */
+  readonly params?: ReadonlyArray<readonly [string, ParamValue]> | undefined;
+  /**
+   * Further rows, for a command that takes a list: each is a group of
+   * parameters sent after a `|`, as `ftdeletefile cid=1 cpw= name=/a|name=/b`
+   * sends two names. The first row's parameters follow `params`.
+   */
+  readonly rows?: ReadonlyArray<ReadonlyArray<readonly [string, ParamValue]>> | undefined;
+  /** Names of the parameters that carry a channel password. */
+  readonly passwords?: readonly string[] | undefined;
+}
+
+/** How long a command may take, and how to abandon it. */
+export interface CommandOptions {
+  /** Abandons the command; it then rejects with the signal's reason. */
+  readonly signal?: AbortSignal | undefined;
+  /** Milliseconds to wait for the answer before failing with a CommandTimeoutError. */
+  readonly timeoutMs?: number | undefined;
+}
+
+/**
+ * A connection the typed commands can run on.
+ *
+ * It is deliberately this narrow. A caller implements it to run the typed
+ * commands over a transport of their own, and `CommandMiddleware` wraps its
+ * `send`, so a method added here would break every implementation and every
+ * middleware along with it: this interface gains no methods in a minor
+ * release. A new capability arrives as an interface, a function or an option
+ * of its own instead, and an implementer or a middleware author may rely on
+ * that.
+ */
+export interface CommandExecutor {
+  /** Send a command and return the rows that answer it. */
+  // oxlint-disable-next-line typescript/array-type -- the public API report spells this `[]`; respelling it changes the report
+  send(request: CommandRequest, options?: CommandOptions): Promise<Record<string, string>[]>;
+}
+
+/**
+ * Turn a value into its wire form.
+ *
+ * Returns undefined for values that should be omitted entirely — an unset
+ * optional field — because sending `foo=` is not the same as not sending it:
+ * for `channel_password` the first clears the password and the second leaves it
+ * alone. Callers distinguish "unset" from "empty string" by passing undefined
+ * versus "".
+ */
+function encodeValue(value: ParamValue): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "boolean") return value ? "1" : "0";
+  return String(value);
+}
+
+/**
+ * Render a request as a command line.
+ *
+ * `encodePassword` is the transport's rule for password parameters. An empty
+ * password is sent as is: it means "no password", in every encoding.
+ */
+export function encodeRequest(
+  request: CommandRequest,
+  encodePassword: (password: string) => string,
+): string {
+  const passwords = request.passwords ?? [];
+  const encode = (params: ReadonlyArray<readonly [string, ParamValue]>) =>
+    encodeParams(params, passwords, encodePassword);
+  const [first = [], ...rest] = request.rows ?? [];
+  const line = buildCommandOrdered(request.command, [
+    ...encode(request.params ?? []),
+    ...encode(first),
+  ]);
+  // A row is the parameters alone, with no command name before them.
+  return [line, ...rest.map((row) => buildCommandOrdered("", encode(row)).slice(1))].join("|");
+}
+
+function encodeParams(
+  params: ReadonlyArray<readonly [string, ParamValue]>,
+  passwords: readonly string[],
+  encodePassword: (password: string) => string,
+): Array<readonly [string, string]> {
+  const out: Array<readonly [string, string]> = [];
+  for (const [key, value] of params) {
+    // Flags (`-uid`) are switches: present when true, absent otherwise.
+    if (key.startsWith("-")) {
+      if (value === true) out.push([key, ""]);
+      continue;
+    }
+    if (passwords.includes(key) && typeof value === "string" && value !== "") {
+      out.push([key, encodePassword(value)]);
+      continue;
+    }
+    const encoded = encodeValue(value);
+    if (encoded !== undefined) out.push([key, encoded]);
+  }
+  return out;
+}

package/src/core/command/responses.ts

@@ -0,0 +1,114 @@
+/**
+ * Where each command's answer actually arrives.
+ *
+ * ServerQuery answers a query with nameless rows followed by `error`. The voice
+ * protocol often does not: it answers `servergrouplist` with a named
+ * `notifyservergrouplist` command, `clientgetuidfromclid` with
+ * `notifyclientuidfromclid`, and so on. A client that only collects nameless
+ * rows reports an empty success for every one of those — which this SDK did,
+ * and documented as a property of the protocol.
+ *
+ * Notifications carry no return_code, so nothing on the wire ties one to the
+ * command that caused it. The pairing is a property of the command, and this
+ * table is where it lives. It was measured command by command
+ * against TS3 3.13.8 and TS6 6.0.0-beta13.1, which answer identically — see
+ * scripts/probe-response-shapes.mts to re-run that measurement.
+ *
+ * Commands not listed answer with nameless rows, or with nothing.
+ */
+
+/** How the voice protocol delivers one command's data. */
+export interface ResponseSpec {
+  /**
+   * Notifications carrying the data, sent before the command's `error`.
+   *
+   * Rows of these are attributed to the command whose `error` follows them.
+   * The same notification can also arrive unprompted — `notifyservergrouplist`
+   * after someone else edits a group — so they are still dispatched as events.
+   */
+  readonly notifications?: readonly string[];
+  /**
+   * Keep only rows whose `invokerid` is the client itself.
+   *
+   * `notifychannelcreated` is broadcast for every channel anyone creates; the
+   * one answering our `channelcreate` is the one we invoked.
+   */
+  readonly ownRowsOnly?: boolean;
+  /**
+   * Notifications that answer after the `error`, matched on a request field.
+   *
+   * File transfer negotiation reports its key once the command has already
+   * succeeded, echoing the `clientftfid` the request carried; that echo is the
+   * only link between the two.
+   */
+  readonly correlated?: {
+    readonly notifications: readonly string[];
+    /** Request parameter the answer echoes back. */
+    readonly key: string;
+    /**
+     * A notification that reports failure rather than data. Its `status` is an
+     * ordinary server error id: an `ftinitupload` refused for permissions
+     * answers `error id=0` and then this with `status=2568`.
+     */
+    readonly failure?: string;
+  };
+}
+
+const inline = (...notifications: string[]): ResponseSpec => ({ notifications });
+
+const fileTransfer = (answer: string): ResponseSpec => ({
+  correlated: {
+    notifications: [answer, "notifystatusfiletransfer"],
+    key: "clientftfid",
+    failure: "notifystatusfiletransfer",
+  },
+});
+
+/** The table behind {@link responseSpec}, by command name; exported for the tests that check it against the name tables. */
+export const RESPONSES: Readonly<Record<string, ResponseSpec>> = {
+  banlist: inline("notifybanlist"),
+  channelclientpermlist: inline("notifychannelclientpermlist"),
+  channelcreate: { notifications: ["notifychannelcreated"], ownRowsOnly: true },
+  channelgetdescription: inline("notifychanneledited"),
+  channelgroupadd: inline("notifychannelgrouplist"),
+  channelgroupclientlist: inline("notifychannelgroupclientlist"),
+  channelgroupcopy: inline("notifychannelgrouplist"),
+  channelgrouplist: inline("notifychannelgrouplist"),
+  channelgrouppermlist: inline("notifychannelgrouppermlist"),
+  channelpermlist: inline("notifychannelpermlist"),
+  clientdbfind: inline("notifyclientdbfind"),
+  clientdblist: inline("notifyclientdblist"),
+  clientgetdbidfromuid: inline("notifyclientdbidfromuid"),
+  clientgetids: inline("notifyclientids"),
+  clientgetnamefromdbid: inline("notifyclientnamefromdbid"),
+  clientgetnamefromuid: inline("notifyclientnamefromuid"),
+  clientgetuidfromclid: inline("notifyclientuidfromclid"),
+  clientpermlist: inline("notifyclientpermlist"),
+  complainlist: inline("notifycomplainlist"),
+  ftgetfileinfo: inline("notifyfileinfo"),
+  ftgetfilelist: inline("notifyfilelist"),
+  ftinitdownload: fileTransfer("notifystartdownload"),
+  ftinitupload: fileTransfer("notifystartupload"),
+  ftlist: inline("notifyfiletransferlist"),
+  logview: inline("notifyserverlog"),
+  messageget: inline("notifymessage"),
+  messagelist: inline("notifymessagelist"),
+  permfind: inline("notifypermfind"),
+  permissionlist: inline("notifypermissionlist"),
+  permoverview: inline("notifypermoverview"),
+  privilegekeyadd: inline("notifytokenadd"),
+  privilegekeylist: inline("notifytokenlist"),
+  servergroupadd: inline("notifyservergrouplist"),
+  servergroupclientlist: inline("notifyservergroupclientlist"),
+  servergroupcopy: inline("notifyservergrouplist"),
+  servergrouplist: inline("notifyservergrouplist"),
+  servergrouppermlist: inline("notifyservergrouppermlist"),
+  servergroupsbyclientid: inline("notifyservergroupsbyclientid"),
+  serverrequestconnectioninfo: inline("notifyserverconnectioninfo"),
+  servertemppasswordlist: inline("notifyservertemppasswordlist"),
+};
+
+/** The response shape of a command, or undefined for plain rows. */
+export function responseSpec(command: string): ResponseSpec | undefined {
+  return Object.hasOwn(RESPONSES, command) ? RESPONSES[command] : undefined;
+}