@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.8

package/src/client/address.ts

@@ -0,0 +1,74 @@
+import { isIP } from "node:net";
+import { InvalidAddressError } from "./errors.js";
+
+export interface HostPort {
+  host: string;
+  port: string;
+}
+
+/** Parse a TeamSpeak address without confusing an IPv6 colon for a port separator. */
+export function splitHostPort(address: string, defaultPort = "9987"): HostPort {
+  const input = address.trim();
+  if (input.startsWith("[")) {
+    const closingBracket = input.indexOf("]");
+    if (closingBracket > 0) {
+      const host = input.slice(1, closingBracket);
+      const suffix = input.slice(closingBracket + 1);
+      if (suffix.startsWith(":") && /^\d+$/.test(suffix.slice(1))) {
+        return { host, port: suffix.slice(1) };
+      }
+      if (!suffix) return { host, port: defaultPort };
+    }
+  }
+
+  // A raw IPv6 literal has no unambiguous port separator. Internal callers
+  // normally use bracket notation, but accepting the literal with the default
+  // port prevents a final IPv6 segment from being mistaken for a port.
+  if (isIP(input) === 6) return { host: input, port: defaultPort };
+
+  const lastColon = input.lastIndexOf(":");
+  if (lastColon < 0) return { host: input, port: defaultPort };
+  const candidatePort = input.slice(lastColon + 1);
+  if (/^\d+$/.test(candidatePort) && input.indexOf(":") === lastColon) {
+    return { host: input.slice(0, lastColon), port: candidatePort };
+  }
+  return { host: input, port: defaultPort };
+}
+
+/** Characters no host name or IP address contains, whitespace among them. */
+const NOT_IN_A_HOST = /[\s\p{Cc}/?#@[\]\\]/u;
+
+/**
+ * Parse an address to connect to, and check it can be one: a host, which
+ * contains nothing a host name or IP address cannot, and a port from 1 to
+ * 65535. Throws an InvalidAddressError otherwise.
+ */
+export function parseConnectAddress(address: string): HostPort & { portNumber: number } {
+  const { host, port } = splitHostPort(address);
+  if (host === "") throw new InvalidAddressError(address, "no host");
+  // A colon is left only in an IPv6 literal; anywhere else it is a port that
+  // is not a number, which splitHostPort keeps as part of the host.
+  if (NOT_IN_A_HOST.test(host) || (host.includes(":") && isIP(host) !== 6)) {
+    throw new InvalidAddressError(address, "not a host name, IP address or host:port");
+  }
+  const portNumber = Number(port);
+  if (!Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65535) {
+    throw new InvalidAddressError(address, `port ${port} is not from 1 to 65535`);
+  }
+  return { host, port, portNumber };
+}
+
+export function joinHostPort(host: string, port: string): string {
+  const normalizedHost = stripBrackets(host);
+  return isIP(normalizedHost) === 6 || normalizedHost.includes(":")
+    ? `[${normalizedHost}]:${port}`
+    : `${normalizedHost}:${port}`;
+}
+
+export function isIpAddress(host: string): boolean {
+  return isIP(stripBrackets(host)) !== 0;
+}
+
+function stripBrackets(host: string): string {
+  return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}

package/src/client/api/voice.ts

@@ -0,0 +1,61 @@
+/**
+ * Commands only the voice protocol has.
+ *
+ * ServerQuery has no subscriptions — a query client hears every channel's
+ * events once it registers for them — and no `channelgetdescription`, since its
+ * `channelinfo` already carries the description. These run on the voice
+ * client alone, which is why they take one rather than any CommandExecutor.
+ */
+
+import type { Client } from "../client.js";
+import type { ChannelID, CommandOptions } from "@honeybbq/teamspeak";
+
+/** The channel's description, which `listChannels` omits for bandwidth. */
+export async function getChannelDescription(
+  client: Client,
+  cid: ChannelID,
+  options?: CommandOptions,
+): Promise<string> {
+  const rows = await client.send(
+    { command: "channelgetdescription", params: [["cid", cid]] },
+    options,
+  );
+  return rows[0]?.["channel_description"] ?? "";
+}
+
+/**
+ * Subscribe to a channel: receive its clients' events and voice without
+ * joining it.
+ */
+export async function subscribeChannel(
+  client: Client,
+  cid: ChannelID,
+  options?: CommandOptions,
+): Promise<void> {
+  await client.send({ command: "channelsubscribe", params: [["cid", cid]] }, options);
+}
+
+/** Stop receiving a subscribed channel's events and voice. */
+export async function unsubscribeChannel(
+  client: Client,
+  cid: ChannelID,
+  options?: CommandOptions,
+): Promise<void> {
+  await client.send({ command: "channelunsubscribe", params: [["cid", cid]] }, options);
+}
+
+/** Subscribe to every channel on the server. */
+export async function subscribeAllChannels(
+  client: Client,
+  options?: CommandOptions,
+): Promise<void> {
+  await client.send({ command: "channelsubscribeall" }, options);
+}
+
+/** Unsubscribe from every channel on the server. */
+export async function unsubscribeAllChannels(
+  client: Client,
+  options?: CommandOptions,
+): Promise<void> {
+  await client.send({ command: "channelunsubscribeall" }, options);
+}

package/src/client/capabilities.ts

@@ -0,0 +1,106 @@
+/**
+ * What the connected server is, and what that means for the caller.
+ *
+ * TS3 and TS6 differ in ways that stay invisible until something breaks. The
+ * clearest: the server hashes a client's public key with SHA-1 on TS3 and
+ * SHA-256 on TS6, so a client that assumes either one computes a
+ * `client_unique_identifier` the other server never sends.
+ *
+ * Everything below comes from the handshake — `initserver` carries
+ * `virtualserver_version`, the one place the server names itself, along with
+ * its name, icon, banner and welcome message — so reading it costs no extra
+ * round trip.
+ */
+
+import { asServerID, type IconID, type ServerFamily, type ServerID } from "@honeybbq/teamspeak";
+import { parseIconID, parseUint64 } from "../core/internal.js";
+import { uidAlgorithmForVersion, type UIDAlgorithm } from "./crypto/identity.js";
+
+/** What a server said about itself in the handshake. */
+export interface ServerCapabilities {
+  /** The `virtualserver_version` string, exactly as the server sent it. */
+  readonly version: string;
+  /** Major version number, or 0 when it could not be parsed. */
+  readonly major: number;
+  /** Which server generation this is. */
+  readonly family: ServerFamily;
+  /**
+   * The hash the server uses for `client_unique_identifier`.
+   *
+   * Read from the family rather than offered as a setting: the server decides
+   * this, and a client that picks differently never matches.
+   */
+  readonly uidAlgorithm: UIDAlgorithm;
+  /** The virtual server's name (`virtualserver_name`). */
+  readonly name: string;
+  /**
+   * The server's icon (`virtualserver_icon_id`), or `undefined` for none. The
+   * server sends the icon's CRC32, sometimes as a negative 32-bit number; this
+   * is the unsigned value, which names the icon file.
+   */
+  readonly iconID: IconID | undefined;
+  /** The host banner image's URL (`virtualserver_hostbanner_gfx_url`), if one is set. */
+  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`).
+   * Compare it with `HostMessageMode`; a server may send a value the table
+   * does not name.
+   */
+  readonly hostMessageMode: number;
+}
+
+/**
+ * Read what a server says about itself in `initserver`, or a version string
+ * alone, such as "6.0.0-beta13.1 [Build: 1]".
+ */
+export function parseServerCapabilities(
+  initserver: string | Readonly<Record<string, string>>,
+): ServerCapabilities {
+  const params =
+    typeof initserver === "string" ? { virtualserver_version: initserver } : initserver;
+  const version = params["virtualserver_version"] ?? "";
+  const parsed = Number.parseInt(version, 10);
+  const major = Number.isNaN(parsed) ? 0 : parsed;
+
+  let family: ServerFamily = "unknown";
+  if (major === 3) family = "ts3";
+  else if (major >= 6) family = "ts6";
+
+  return {
+    version,
+    major,
+    family,
+    uidAlgorithm: uidAlgorithmForVersion(version),
+    name: params["virtualserver_name"] ?? "",
+    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"]),
+  };
+}
+
+/**
+ * Capabilities of a server that has not been connected to yet.
+ *
+ * The family is `unknown` — nothing has said which server this is — and
+ * `uidAlgorithm` is SHA-1, the TS3 hash.
+ */
+export function unknownServerCapabilities(): ServerCapabilities {
+  return parseServerCapabilities("");
+}
+
+function hostMessageMode(value: string | undefined): number {
+  const parsed = Number.parseInt(value ?? "", 10);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}