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

package/src/core/api/channels.ts

@@ -12,6 +12,8 @@ import {
   nonZero,
   firstRow,
   exec,
+  execRows,
+  continueOnErrorParams,
   query,
   list,
   parseChannel,
@@ -22,7 +24,13 @@ import {
   big,
   str,
 } from "./command.js";
-import type { Channel, PermissionEntry, WireNames } from "./command.js";
+import type {
+  BatchOptions,
+  Channel,
+  PermissionEntry,
+  PermissionValue,
+  WireNames,
+} from "./command.js";
 import type { CommandExecutor, CommandOptions } from "../command/request.js";
 import type { ChannelID, ClientDBID } from "../command/ids.js";
 import { asChannelID } from "../command/ids.js";
@@ -354,6 +362,71 @@ export async function addChannelPermission(
   );
 }
 
+/**
+ * Set several permissions on a channel, in one command: each permission is a
+ * row (`permsid=…  permvalue=…|permsid=…  permvalue=…`). With none, nothing is
+ * sent.
+ *
+ * The server checks every row before it applies any: a permission it does not
+ * know (2562) or a value it cannot read (1540) refuses the call, and none is
+ * set, with or without `continueOnError`. Measured on TeamSpeak 3 3.13.8 and
+ * TeamSpeak 6 beta13.1, over raw ServerQuery, SSH, WebQuery and the voice
+ * protocol alike. Resolves to nothing: the server never reports an answer per
+ * row.
+ *
+ * A permission the caller has too little modify power for (2570, or 2568 where
+ * the group power is short) is another matter: the rows are applied in order.
+ * Without `continueOnError` the first row that fails ends the call, so the rows
+ * before it are set and the rows after it are not; with it the rows that fail
+ * are skipped and the others set. The error is the failing row's, and which row
+ * is not reported; with several failing rows which error comes back was not
+ * measured. Measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 beta13.1, over raw
+ * ServerQuery (TeamSpeak 3), SSH, WebQuery and the voice protocol, in both
+ * orders of a free and a locked permission.
+ */
+export async function addChannelPermissions(
+  client: CommandExecutor,
+  cid: ChannelID,
+  permissions: readonly PermissionValue[],
+  options: BatchOptions = {},
+): Promise<void> {
+  await execRows(
+    client,
+    "channeladdperm",
+    [...continueOnErrorParams(options), ["cid", cid]],
+    permissions.map((entry) => [permissionParam(entry.permission), ["permvalue", entry.value]]),
+    options,
+  );
+}
+
+/**
+ * Remove several permissions from a channel, in one command: each permission is
+ * a row (`permsid=…|permsid=…`). With none, nothing is sent.
+ *
+ * The server checks every row first, and an unknown permission (2562) refuses
+ * the call with none removed. Removing a permission the channel does not have
+ * succeeds. A permission the caller has too little modify power for (2570) ends
+ * the call at that row: the rows before it are removed and the rows after it
+ * are not, measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 beta13.1 over every
+ * query transport and the voice protocol. The server documents no
+ * `-continueonerror` for this command, so none is offered, and sent anyway it
+ * changed nothing.
+ */
+export async function deleteChannelPermissions(
+  client: CommandExecutor,
+  cid: ChannelID,
+  permissions: readonly Permission[],
+  options?: CommandOptions,
+): Promise<void> {
+  await execRows(
+    client,
+    "channeldelperm",
+    [["cid", cid]],
+    permissions.map((permission) => [permissionParam(permission)]),
+    options,
+  );
+}
+
 /** Remove a permission from a channel. */
 export async function deleteChannelPermission(
   client: CommandExecutor,
@@ -409,6 +482,54 @@ export async function addChannelClientPermission(
   );
 }
 
+/**
+ * Set several permissions on one client within one channel, in one command:
+ * each permission is a row. With none, nothing is sent. The server's answer
+ * is as for {@link addChannelPermissions}: an unknown permission or a value it
+ * cannot read refuses the call with none set, and a row the caller lacks the
+ * power for ends it there, or is skipped with `continueOnError`.
+ */
+export async function addChannelClientPermissions(
+  client: CommandExecutor,
+  cid: ChannelID,
+  cldbid: ClientDBID,
+  permissions: readonly PermissionValue[],
+  options: BatchOptions = {},
+): Promise<void> {
+  await execRows(
+    client,
+    "channelclientaddperm",
+    [...continueOnErrorParams(options), ["cid", cid], ["cldbid", cldbid]],
+    permissions.map((entry) => [permissionParam(entry.permission), ["permvalue", entry.value]]),
+    options,
+  );
+}
+
+/**
+ * Remove several permissions from one client within one channel, in one
+ * command. With none, nothing is sent. The server's answer is as for
+ * {@link deleteChannelPermissions}, and it documents no `-continueonerror` for
+ * this command either.
+ */
+export async function deleteChannelClientPermissions(
+  client: CommandExecutor,
+  cid: ChannelID,
+  cldbid: ClientDBID,
+  permissions: readonly Permission[],
+  options?: CommandOptions,
+): Promise<void> {
+  await execRows(
+    client,
+    "channelclientdelperm",
+    [
+      ["cid", cid],
+      ["cldbid", cldbid],
+    ],
+    permissions.map((permission) => [permissionParam(permission)]),
+    options,
+  );
+}
+
 /** Remove a permission from one client within one channel. */
 export async function deleteChannelClientPermission(
   client: CommandExecutor,

package/src/core/api/clients.ts

@@ -12,6 +12,8 @@ import {
   U16,
   firstRow,
   exec,
+  execRows,
+  continueOnErrorParams,
   query,
   list,
   pages,
@@ -25,7 +27,14 @@ import {
   optNum,
   date,
 } from "./command.js";
-import type { PagingOptions, Params, PermissionEntry, WireNames } from "./command.js";
+import type {
+  BatchOptions,
+  PagingOptions,
+  Params,
+  PermissionEntry,
+  PermissionValue,
+  WireNames,
+} from "./command.js";
 import type { CommandExecutor, CommandOptions } from "../command/request.js";
 import type {
   ChannelGroupID,
@@ -419,6 +428,43 @@ export async function moveClient(
   );
 }
 
+/** How {@link moveClients} enters the channel. */
+export interface ClientsMoveOptions extends ClientMoveOptions, BatchOptions {}
+
+/**
+ * Move several clients to one channel, in one command, such as
+ * `clientmove clid=5|clid=6 cid=3`. With no ids nothing is sent.
+ *
+ * The server reports one answer for the whole call, never one per client, so
+ * this resolves to nothing and a failure says only what the server said.
+ * Measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 beta13.1, over raw
+ * ServerQuery, SSH, WebQuery and the voice protocol alike:
+ *
+ * - Without `continueOnError`, the server checks every client first: one id it
+ *   cannot move (no such client, error 512; a client already in the channel,
+ *   770) refuses the call, and no client is moved.
+ * - With it (`-continueonerror`), a client that cannot be moved is skipped, the
+ *   others are moved, and the answer is success, even when none could be moved.
+ *   Read the channel back, as `listClients` reports it, to know who moved.
+ *
+ * A channel that does not exist fails the call either way (768).
+ */
+export async function moveClients(
+  client: CommandExecutor,
+  clientIDs: readonly ClientID[],
+  channelID: ChannelID,
+  options: ClientsMoveOptions = {},
+): Promise<void> {
+  await execRows(
+    client,
+    "clientmove",
+    [...continueOnErrorParams(options), ["cid", channelID], ["cpw", options.password]],
+    clientIDs.map((clid) => [["clid", clid]]),
+    options,
+    ["cpw"],
+  );
+}
+
 /** The reasons a client can be kicked for. */
 export type KickReason = typeof Reason.KickChannel | typeof Reason.KickServer;
 
@@ -456,6 +502,51 @@ export async function kickClient(
   );
 }
 
+/** What {@link kickClients} tells the kicked clients, and whether it goes on past a failure. */
+export interface ClientsKickOptions extends ClientKickOptions, BatchOptions {}
+
+/**
+ * Kick several clients for one reason, in one command, such as
+ * `clientkick reasonid=4 clid=5|clid=6`. The reason is as for
+ * {@link kickClient}; with no ids nothing is sent.
+ *
+ * The server reports one answer for the whole call, never one per client, so
+ * this resolves to nothing and a failure says only what the server said.
+ * Measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 beta13.1, over raw
+ * ServerQuery, SSH, WebQuery and the voice protocol alike:
+ *
+ * - Without `continueOnError`, the clients are kicked in the order given and
+ *   the call stops at the first one that fails (an id no client has, 512):
+ *   the clients before it are kicked, the ones after it are not, and the
+ *   error is that client's.
+ * - With it (`-continueonerror`), every client is tried, a failing one is
+ *   skipped, and the answer is success, even when none could be kicked. Read
+ *   the clients back, as `listClients` reports them, to know who was kicked.
+ */
+export async function kickClients(
+  client: CommandExecutor,
+  clientIDs: readonly ClientID[],
+  reason: KickReason,
+  options: ClientsKickOptions = {},
+): Promise<void> {
+  if (reason !== Reason.KickChannel && reason !== Reason.KickServer) {
+    throw new RangeError(
+      `a kick's reason is Reason.KickChannel or Reason.KickServer, not ${String(reason)}`,
+    );
+  }
+  await execRows(
+    client,
+    "clientkick",
+    [
+      ...continueOnErrorParams(options),
+      ["reasonid", reason],
+      ["reasonmsg", nonEmpty(options.reasonMessage ?? "")],
+    ],
+    clientIDs.map((clid) => [["clid", clid]]),
+    options,
+  );
+}
+
 /** Send a poke to a client. */
 export async function pokeClient(
   client: CommandExecutor,
@@ -1049,6 +1140,53 @@ export async function addClientPermission(
   );
 }
 
+/** One permission to set on a client, server-wide, as {@link addClientPermissions} takes it. */
+export interface ClientPermissionValue extends PermissionValue {
+  /** Whether it skips channel and client overrides; false by default. Always sent (`permskip`). */
+  readonly skip?: boolean | undefined;
+}
+
+/**
+ * Set several permissions on a client, server-wide, in one command: each
+ * permission is a row (`permsid=…  permvalue=…  permskip=0|…`). With none,
+ * nothing is sent.
+ *
+ * The server checks every row before it applies any: a permission it does not
+ * know (2562) or a value it cannot read (1540) refuses the call, and none is
+ * set, with or without `continueOnError`. Measured on TeamSpeak 3 3.13.8 and
+ * TeamSpeak 6 beta13.1, over raw ServerQuery, SSH, WebQuery and the voice
+ * protocol alike. Resolves to nothing: the server never reports one answer
+ * per row.
+ *
+ * A permission the caller has too little modify power for (2570, or 2568 where
+ * the group power is short) is another matter: the rows are applied in order.
+ * Without `continueOnError` the first row that fails ends the call, so the rows
+ * before it are set and the rows after it are not; with it the rows that fail
+ * are skipped and the others set. The error is the failing row's, and which row
+ * is not reported; with several failing rows which error comes back was not
+ * measured. Measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 beta13.1, over raw
+ * ServerQuery (TeamSpeak 3), SSH, WebQuery and the voice protocol, in both
+ * orders of a free and a locked permission.
+ */
+export async function addClientPermissions(
+  client: CommandExecutor,
+  cldbid: ClientDBID,
+  permissions: readonly ClientPermissionValue[],
+  options: BatchOptions = {},
+): Promise<void> {
+  await execRows(
+    client,
+    "clientaddperm",
+    [...continueOnErrorParams(options), ["cldbid", cldbid]],
+    permissions.map((entry) => [
+      permissionParam(entry.permission),
+      ["permvalue", entry.value],
+      ["permskip", entry.skip ?? false],
+    ]),
+    options,
+  );
+}
+
 /** Remove a permission from a client. */
 export async function deleteClientPermission(
   client: CommandExecutor,
@@ -1059,6 +1197,34 @@ export async function deleteClientPermission(
   await exec(client, "clientdelperm", [["cldbid", cldbid], permissionParam(permission)], options);
 }
 
+/**
+ * Remove several permissions from a client, in one command: each permission is
+ * a row (`permsid=…|permsid=…`). With none, nothing is sent.
+ *
+ * The server checks every row before it removes any: one permission it does
+ * not know (2562) refuses the call and none is removed. Removing a permission
+ * the client does not have succeeds. A permission the caller has too little
+ * modify power for (2570) ends the call at that row: the rows before it are
+ * removed and the rows after it are not, measured on TeamSpeak 3 3.13.8 and
+ * TeamSpeak 6 beta13.1 over every query transport and the voice protocol. The
+ * server documents no `-continueonerror` for this command, so none is offered,
+ * and sent anyway it changed nothing.
+ */
+export async function deleteClientPermissions(
+  client: CommandExecutor,
+  cldbid: ClientDBID,
+  permissions: readonly Permission[],
+  options?: CommandOptions,
+): Promise<void> {
+  await execRows(
+    client,
+    "clientdelperm",
+    [["cldbid", cldbid]],
+    permissions.map((permission) => [permissionParam(permission)]),
+    options,
+  );
+}
+
 // ---- Custom properties --------------------------------------------------------
 
 /** One custom property of a client: a key and a value, both free text. */

package/src/core/api/command.ts

@@ -54,6 +54,47 @@ function commandOptions(options: CommandOptions | undefined): CommandOptions | u
   return { signal: options.signal, timeoutMs: options.timeoutMs };
 }
 
+/**
+ * Send a command that takes a list and produces no data: `params` are the
+ * parameters of the first row, and every entry of `rows` is one more row of
+ * the list (`a=1 b=2|b=3`). With no rows, nothing is sent.
+ */
+async function execRows(
+  client: CommandExecutor,
+  command: string,
+  params: Params,
+  rows: readonly Params[],
+  options?: CommandOptions,
+  passwords: readonly string[] = [],
+): Promise<void> {
+  if (rows.length === 0) return;
+  await client.send({ command, params, rows, passwords }, commandOptions(options));
+}
+
+/**
+ * Send a list command that answers with rows, as {@link execRows} sends one.
+ * With no rows nothing is sent, and the answer is empty.
+ */
+async function queryRows(
+  client: CommandExecutor,
+  command: string,
+  params: Params,
+  rows: readonly Params[],
+  options?: CommandOptions,
+): Promise<Array<Record<string, string>>> {
+  if (rows.length === 0) return [];
+  return client.send({ command, params, rows, passwords: [] }, commandOptions(options));
+}
+
+/**
+ * The `-continueonerror` switch, as a command's first parameter: the server
+ * reads it from the first row only, so a switch written after the last row
+ * does nothing.
+ */
+const continueOnErrorParams = (options: {
+  readonly continueOnError?: boolean | undefined;
+}): Params => (options.continueOnError === true ? [["-continueonerror", true]] : []);
+
 /** Send a command and return its response rows. */
 async function query(
   client: CommandExecutor,
@@ -187,7 +228,17 @@ function firstRow(
   return row;
 }
 
-export { exec, query, list, pages, commandOptions, firstRow };
+export {
+  exec,
+  execRows,
+  query,
+  queryRows,
+  list,
+  pages,
+  commandOptions,
+  continueOnErrorParams,
+  firstRow,
+};
 export type { ParamValue };
 
 // ---- Field tables -----------------------------------------------------------
@@ -722,6 +773,28 @@ function parseChannelChanges(row: Record<string, string>): ChannelChanges {
 
 export { parseChannel, parseChannelChanges };
 
+/**
+ * What a command that takes a list of options carries beside the usual signal
+ * and timeout: whether the server keeps going past an item that fails.
+ */
+export interface BatchOptions extends CommandOptions {
+  /**
+   * Send `-continueonerror`, which the server documents for this command: it
+   * processes every item and skips the ones that fail, instead of stopping at
+   * the first. What it then answers differs by command, and each function says.
+   * False by default.
+   */
+  readonly continueOnError?: boolean | undefined;
+}
+
+/** One permission to set, with its value: an entry of a batch that adds permissions. */
+export interface PermissionValue {
+  /** The permission to set. */
+  readonly permission: Permission;
+  /** Its value (`permvalue`). */
+  readonly value: number;
+}
+
 /** One entry of a permission list. */
 export interface PermissionEntry {
   /**

package/src/core/api/files.ts

@@ -96,6 +96,73 @@ export async function listFiles(
   return rows.map(parseFileEntry);
 }
 
+/** One entry of a recursive listing: what {@link listFiles} reports, with where it is. */
+export interface FileTreeEntry extends FileEntry {
+  /**
+   * The entry's full path in the channel's file area, from its root: `/a/b.txt`
+   * for the file `b.txt` in the directory `a`. A directory's path has no
+   * trailing slash.
+   */
+  readonly path: string;
+}
+
+/** How {@link listFilesRecursive} walks the file area. */
+export interface FileTreeOptions extends FileOptions {
+  /**
+   * How many directory levels to go down from the starting path: 0 lists the
+   * starting directory only, as {@link listFiles} does; 1 also lists the
+   * directories in it; and so on. 16 by default. A non-negative integer.
+   */
+  readonly maxDepth?: number | undefined;
+}
+
+/** A path without the slashes at its end; "/" becomes "". */
+function withoutTrailingSlashes(path: string): string {
+  let end = path.length;
+  while (end > 0 && path.charCodeAt(end - 1) === 0x2f) end--;
+  return path.slice(0, end);
+}
+
+/** How far {@link listFilesRecursive} goes down unless told otherwise. */
+const DEFAULT_MAX_DEPTH = 16;
+
+/**
+ * Every file and directory under a path in a channel's file area, in one list:
+ * the entries of the directory in the order {@link listFiles} gives them, each
+ * directory followed by what it holds.
+ *
+ * It lists one directory at a time, one command each, so a large tree costs
+ * that many round trips. `maxDepth` bounds how far it goes down; a directory
+ * at the bound is listed, but not entered. The options (password, signal,
+ * timeoutMs) reach every command, and the first error ends the walk. An empty
+ * directory has no entries, and a path that is not a directory fails as
+ * {@link listFiles} does: TS3 3.13.8 answers 2052 and TS6 beta13.1 2051 for a
+ * path that does not exist.
+ *
+ * File commands are not served over WebQuery (error 5120).
+ */
+export async function listFilesRecursive(
+  client: CommandExecutor,
+  cid: ChannelID,
+  path: string,
+  options: FileTreeOptions = {},
+): Promise<FileTreeEntry[]> {
+  const { maxDepth = DEFAULT_MAX_DEPTH, ...listOptions } = options;
+  if (!Number.isInteger(maxDepth) || maxDepth < 0) {
+    throw new RangeError(`maxDepth is a non-negative integer, not ${String(maxDepth)}`);
+  }
+  const found: FileTreeEntry[] = [];
+  const walk = async (directory: string, depth: number): Promise<void> => {
+    for (const entry of await listFiles(client, cid, directory, listOptions)) {
+      const entryPath = `${withoutTrailingSlashes(directory)}/${entry.name}`;
+      found.push({ ...entry, path: entryPath });
+      if (entry.isDirectory && depth < maxDepth) await walk(entryPath, depth + 1);
+    }
+  };
+  await walk(asPath(path), 0);
+  return found;
+}
+
 /** Size and timestamp of one file. */
 export async function getFileInfo(
   client: CommandExecutor,
@@ -144,7 +211,11 @@ export async function deleteFile(
   );
 }
 
-/** Create a directory, including any missing parents. */
+/**
+ * Create a directory. Its parent has to exist: measured on TS3 3.13.8 and TS6
+ * beta13.1, a path whose parent is missing is refused with 2052 (file
+ * input/output error), so nested directories are made one level at a time.
+ */
 export async function createDirectory(
   client: CommandExecutor,
   cid: ChannelID,

package/src/core/api/groups.ts

@@ -8,6 +8,8 @@ import {
   U32,
   firstRow,
   exec,
+  execRows,
+  continueOnErrorParams,
   query,
   list,
   encodeFields,
@@ -21,7 +23,13 @@ import {
   bool,
   date,
 } from "./command.js";
-import type { Params, PermissionEntry, WireNames } from "./command.js";
+import type {
+  BatchOptions,
+  Params,
+  PermissionEntry,
+  PermissionValue,
+  WireNames,
+} from "./command.js";
 import type { CommandExecutor, CommandOptions } from "../command/request.js";
 import type {
   ChannelGroupID,
@@ -267,6 +275,55 @@ export async function addChannelGroupPermission(
   );
 }
 
+/**
+ * Set several permissions on a channel group, in one command: each permission
+ * is a row. With none, nothing is sent. The server's answer is as for
+ * {@link addChannelPermissions}: an unknown permission or a value it cannot read
+ * refuses the call with none set, with or without `continueOnError`, and a row
+ * the caller lacks the power for ends it there, or is skipped with
+ * `continueOnError`.
+ */
+export async function addChannelGroupPermissions(
+  client: CommandExecutor,
+  cgid: ChannelGroupID,
+  permissions: readonly PermissionValue[],
+  options: BatchOptions = {},
+): Promise<void> {
+  await execRows(
+    client,
+    "channelgroupaddperm",
+    [...continueOnErrorParams(options), ["cgid", cgid]],
+    permissions.map((entry) => [permissionParam(entry.permission), ["permvalue", entry.value]]),
+    options,
+  );
+}
+
+/**
+ * Remove several permissions from a channel group, in one command: each
+ * permission is a row. With none, nothing is sent. An unknown permission (2562)
+ * is found first and leaves none removed, with or without `continueOnError`.
+ * Removing a permission the group does not have succeeds. A permission the
+ * caller has too little modify power for (2570) ends the call at that row, so
+ * the rows before it are removed and the rows after it are not; with
+ * `continueOnError` that row is skipped and the others removed. Measured on
+ * TeamSpeak 3 3.13.8 and TeamSpeak 6 beta13.1 over every query transport and
+ * the voice protocol.
+ */
+export async function deleteChannelGroupPermissions(
+  client: CommandExecutor,
+  cgid: ChannelGroupID,
+  permissions: readonly Permission[],
+  options: BatchOptions = {},
+): Promise<void> {
+  await execRows(
+    client,
+    "channelgroupdelperm",
+    [...continueOnErrorParams(options), ["cgid", cgid]],
+    permissions.map((permission) => [permissionParam(permission)]),
+    options,
+  );
+}
+
 /** Remove a permission from a channel group. */
 export async function deleteChannelGroupPermission(
   client: CommandExecutor,
@@ -314,8 +371,12 @@ export async function listPermissions(
 }
 
 /**
- * Resolve a permission name to its numeric id, or undefined when the server
- * knows no such permission.
+ * Resolve a permission name to its numeric id.
+ *
+ * A name the server does not know is not an `undefined` result: both TS3 3.13.8
+ * and TS6 beta13.1 refuse it with a ServerError 2562 (invalid permission ID),
+ * which is thrown. `undefined` is only for a server that acknowledges the
+ * command with no row, which neither measured server does.
  *
  * Needs an instance-level permission (`b_serverinstance_*`), which not even the
  * Server Admin group holds by default — expect error 2568 until it is granted.