@honeybbq/teamspeak 1.0.0-beta.21 → 1.0.0-beta.22

package/src/core/api/clients.ts

@@ -270,8 +270,21 @@ export async function getClientProperties(
   return firstRow(rows, "clientinfo");
 }
 
+/** The values of the table below, before freezing. */
+const connectionTrafficClassValues = {
+  /** Voice and whisper packets. */
+  Speech: "speech",
+  /** Ping and pong packets. */
+  Keepalive: "keepalive",
+  /** Every other packet: commands, acknowledgements and the handshake. */
+  Control: "control",
+} as const;
 /** The three classes of traffic the server counts. */
-export type ConnectionTrafficClass = "speech" | "keepalive" | "control";
+export const ConnectionTrafficClass: typeof connectionTrafficClassValues =
+  /* @__PURE__ */ Object.freeze(connectionTrafficClassValues);
+/** One of {@link ConnectionTrafficClass}. */
+export type ConnectionTrafficClass =
+  (typeof ConnectionTrafficClass)[keyof typeof ConnectionTrafficClass];
 
 /** One direction of one class of a client's traffic, as the client reported it. */
 export interface ClientTraffic {

package/src/core/api/command.ts

@@ -289,10 +289,17 @@ export function encodeFields<T extends object>(fields: T, names: WireNames<T>):
   return out;
 }
 
-/** Raw wire properties, sent as given; a value that is not a string is left out. */
-export const rawProperties = (settings: Readonly<Record<string, string>>): Params =>
-  Object.entries(settings).filter(
-    (entry): entry is [string, string] => typeof entry[1] === "string",
+/** The kinds of value a raw property is sent as. */
+const propertyKinds: ReadonlySet<string> = new Set(["string", "number", "bigint", "boolean"]);
+
+/**
+ * Raw wire properties, sent as given: a string as is, a number or bigint in
+ * decimal, a boolean as 1 or 0. Any other value, undefined among them, is left
+ * out.
+ */
+export const rawProperties = (settings: Readonly<Record<string, unknown>>): Params =>
+  Object.entries(settings).filter((entry): entry is [string, string | number | bigint | boolean] =>
+    propertyKinds.has(typeof entry[1]),
   );
 
 /** An encoder that omits an empty string instead of sending it. */
@@ -668,7 +675,11 @@ export interface Channel {
   readonly isForcedSilence?: boolean | undefined;
   /** The URL of the channel's banner image (`channel_banner_gfx_url`). */
   readonly bannerURL?: string | undefined;
-  /** How the banner is scaled (`channel_banner_mode`). */
+  /**
+   * How the banner is fitted to the channel (`channel_banner_mode`); compare it
+   * with `BannerMode`. A plain number, since a server may send a mode that
+   * table does not name.
+   */
   readonly bannerMode?: number | undefined;
   /**
    * How long the channel has had no client, in milliseconds (`seconds_empty`,

package/src/core/api/groups.ts

@@ -50,6 +50,7 @@ import { parseChannelGroup } from "./group-rows.js";
 import { PermissionTarget, PrivilegeKeyType } from "../enums.js";
 import type { GroupType } from "../enums.js";
 import type { Permission } from "../permission.js";
+import type { PermissionName } from "../permission-name.js";
 import { escape, unescape } from "../command/command.js";
 import type { CustomProperty } from "./clients.js";
 
@@ -396,7 +397,7 @@ export async function listPermissions(
  */
 export async function getPermissionIDByName(
   client: CommandExecutor,
-  name: string,
+  name: PermissionName | (string & {}),
   options?: CommandOptions,
 ): Promise<PermissionID | undefined> {
   const rows = await query(client, "permidgetbyname", [["permsid", name]], options);

package/src/core/api/instance.ts

@@ -27,6 +27,7 @@ import {
   SECOND,
 } from "./command.js";
 import type { WireNames } from "./command.js";
+import type { ServerSettings } from "./server.js";
 import type { CommandExecutor, CommandOptions } from "../command/request.js";
 import type { ChannelID, ServerID } from "../command/ids.js";
 import { asChannelID, asServerID } from "../command/ids.js";
@@ -40,8 +41,9 @@ export interface VirtualServer {
   /** The voice port it listens on (`virtualserver_port`). */
   readonly port: number;
   /**
-   * Its state, as the server words it: "online", "offline", "booting up",
-   * "shutting down", "online virtual" (`virtualserver_status`).
+   * Its state, as the server words it (`virtualserver_status`); compare it
+   * with `VirtualServerStatus`. A plain string, since a server may send a
+   * state that table does not name.
    */
   readonly status: string;
   /** Its name (`virtualserver_name`); "" with `short`. */
@@ -165,7 +167,7 @@ export interface ServerCreated {
 export async function createServer(
   client: CommandExecutor,
   name: string,
-  settings: Readonly<Record<string, string>> = {},
+  settings: ServerSettings = {},
   options?: CommandOptions,
 ): Promise<ServerCreated> {
   const rows = await query(

package/src/core/api/server.ts

@@ -55,10 +55,11 @@ import {
   asServerID,
   asUID,
 } from "../command/ids.js";
-import type { GroupAutoUpdateType, GroupType } from "../enums.js";
+import type { BindingSubsystem, GroupAutoUpdateType, GroupType } from "../enums.js";
 import type { GroupDeleteOptions } from "./groups.js";
 import { parseServerGroup } from "./group-rows.js";
 import type { Permission } from "../permission.js";
+import type { PropertyName } from "../property-name.js";
 
 /** A server group as `servergrouplist` reports it. */
 export interface ServerGroup {
@@ -107,6 +108,29 @@ export async function getServerInfo(
   return firstRow(await query(client, "serverinfo", [], options), "serverinfo");
 }
 
+/**
+ * A raw property's value: a string is sent as is, a number or bigint in
+ * decimal and a boolean as 1 or 0. So a value read back as text, or a table's
+ * constant such as `BannerMode.AdjustKeepAspect`, is written without
+ * converting it.
+ */
+export type PropertyValue = string | number | bigint | boolean;
+
+/**
+ * Raw `virtualserver_*` properties, for {@link editServer} and
+ * `createServer`. The keys `PropertyName` names are offered by an editor; any
+ * other key is sent as well, since a server may know properties the table does
+ * not. A key whose value is undefined is left out.
+ */
+export type ServerSettings = {
+  readonly [K in Extract<PropertyName, `virtualserver_${string}`>]?: PropertyValue | undefined;
+} & { readonly [key: string]: PropertyValue | undefined };
+
+/** Raw `serverinstance_*` properties, for {@link editInstance}, as {@link ServerSettings} are. */
+export type InstanceSettings = {
+  readonly [K in Extract<PropertyName, `serverinstance_${string}`>]?: PropertyValue | undefined;
+} & { readonly [key: string]: PropertyValue | undefined };
+
 /**
  * Change the virtual server's settings. Only the properties you pass are sent.
  *
@@ -114,12 +138,12 @@ export async function getServerInfo(
  * wire properties from `serverinfo`, passed through as given rather than
  * enumerated: there are well over a hundred, they are version-dependent, and a
  * value read back from {@link getServerInfo} should be writable straight back.
- * The values are strings, as `getServerInfo` returns them. The editable keys
- * are marked in `PropertyName`.
+ * A value may also be a number or a boolean; see {@link PropertyValue}. The
+ * editable keys are marked in `PropertyName`.
  */
 export async function editServer(
   client: CommandExecutor,
-  settings: Readonly<Record<string, string>>,
+  settings: ServerSettings,
   options?: CommandOptions,
 ): Promise<void> {
   await exec(client, "serveredit", rawProperties(settings), options);
@@ -162,7 +186,7 @@ export async function getInstanceInfo(
  */
 export async function editInstance(
   client: CommandExecutor,
-  settings: Readonly<Record<string, string>>,
+  settings: InstanceSettings,
   options?: CommandOptions,
 ): Promise<void> {
   await exec(client, "instanceedit", rawProperties(settings), options);
@@ -171,9 +195,10 @@ export async function editInstance(
 /** An address the instance listens on. */
 export interface Binding {
   /**
-   * What listens there: `voice`, `query` or `filetransfer`. The server does not
+   * What listens there; compare it with `BindingSubsystem`. The server does not
    * name it in each row, so it is the subsystem asked for, or `voice` when none
-   * was.
+   * was. A plain string, since a server may send a subsystem that table does
+   * not name.
    */
   readonly subsystem: string;
   /** The address. */
@@ -184,8 +209,8 @@ export interface Binding {
 
 /** Which bindings {@link listBindings} reports. */
 export interface BindingListOptions extends CommandOptions {
-  /** Only this subsystem's: `voice`, `query` or `filetransfer`; unset for all (`subsystem`). */
-  readonly subsystem?: string | undefined;
+  /** Only this subsystem's; unset for all (`subsystem`). */
+  readonly subsystem?: BindingSubsystem | undefined;
 }
 
 /**
@@ -234,7 +259,11 @@ export async function getVersion(
 
 /** Which server and client a connection is, as `whoami` reports it. */
 export interface WhoAmI {
-  /** The virtual server's state, such as "online" (`virtualserver_status`). */
+  /**
+   * The virtual server's state (`virtualserver_status`); compare it with
+   * `VirtualServerStatus`. A plain string, since a server may send a state that
+   * table does not name.
+   */
   readonly serverStatus: string;
   /** The virtual server's id, 0 when none is selected (`virtualserver_id`). */
   readonly serverID: ServerID;

package/src/core/command-name.ts

@@ -96,6 +96,10 @@ const commandNameValues = {
   ClientAddPerm: "clientaddperm",
   /** `clientaddservergroup`: Adds a client to one or more server groups specified with sgid. */
   ClientAddServerGroup: "clientaddservergroup",
+  /** `clientchatclosed`: Tells a client this client has closed its private chat window with it. Voice protocol only. */
+  ClientChatClosed: "clientchatclosed",
+  /** `clientchatcomposing`: Tells a client this client is typing a private message to it. Voice protocol only. */
+  ClientChatComposing: "clientchatcomposing",
   /** `clientdbdelete`: Deletes a client's properties from the database. */
   ClientDBDelete: "clientdbdelete",
   /** `clientdbedit`: Changes a client's settings using given properties. */
@@ -238,6 +242,8 @@ const commandNameValues = {
   PermOverview: "permoverview",
   /** `permreset`: Restores the default permission settings on the selected virtual server and creates a new initial administrator token. */
   PermReset: "permreset",
+  /** `plugincmd`: Sends a plugin-defined message to the clients of a channel, the server or chosen clients, for plugins to read. Voice protocol only. */
+  PluginCmd: "plugincmd",
   /** `privilegekeyadd`: Creates a new privilege key, a token that grants a server or channel group. */
   PrivilegeKeyAdd: "privilegekeyadd",
   /** `privilegekeydelete`: Deletes an existing token matching the token key specified with token. */

package/src/core/enums.ts

@@ -1,13 +1,19 @@
 /**
- * Enumerations the server reports and accepts as small integers.
+ * Enumerations the server reports and accepts as small integers or fixed
+ * strings.
  *
  * Each is an object of named values plus a type of the same name, the way
  * `Reason` is: the object names the values (`GroupType.Regular`), the type
  * restricts a parameter to them.
  *
- * Parameters take the type; parsed results carry a plain `number`, since a
- * server may send a value newer than this table — compare it against the
- * names (`group.type === GroupType.Query`).
+ * Parameters take the type; parsed results carry a plain `number` or `string`,
+ * since a server may send a value newer than this table — compare it against
+ * the names (`group.type === GroupType.Query`).
+ *
+ * The values are the server's own, plain numbers and strings, so they are what
+ * to store: one written to JSON or a database reads back unchanged. A value read
+ * back is a `number` or `string` to TypeScript; {@link isValueOf} narrows it to
+ * the table's type before it is passed as a parameter.
  *
  * Every table, and `ErrorCode` and `Reason` with them, may gain members in a
  * minor release: a `switch` over one needs a default case.
@@ -213,3 +219,104 @@ export const LogLevel: typeof logLevelValues = /* @__PURE__ */ Object.freeze(log
 
 /** A log level. */
 export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+
+/** The values of the table below, before freezing. */
+const bannerModeValues = {
+  /** Show the image at its own size. */
+  NoAdjust: 0,
+  /** Scale the image to fill its space, ignoring its aspect ratio. */
+  AdjustIgnoreAspect: 1,
+  /** Scale the image to fit its space, keeping its aspect ratio. */
+  AdjustKeepAspect: 2,
+} as const;
+/**
+ * How a banner image is fitted to its space: a channel's (`channel_banner_mode`)
+ * and the server's host banner (`virtualserver_hostbanner_mode`).
+ */
+export const BannerMode: typeof bannerModeValues = /* @__PURE__ */ Object.freeze(bannerModeValues);
+
+/** A banner mode. */
+export type BannerMode = (typeof BannerMode)[keyof typeof BannerMode];
+
+/** The values of the table below, before freezing. */
+const codecEncryptionModeValues = {
+  /** Each channel decides, by its `channel_codec_is_unencrypted`. */
+  PerChannel: 0,
+  /** Voice is never encrypted, whatever the channel says. */
+  ForcedOff: 1,
+  /** Voice is always encrypted, whatever the channel says. */
+  ForcedOn: 2,
+} as const;
+/** Whether the virtual server encrypts voice (`virtualserver_codec_encryption_mode`). */
+export const CodecEncryptionMode: typeof codecEncryptionModeValues =
+  /* @__PURE__ */ Object.freeze(codecEncryptionModeValues);
+
+/** A codec encryption mode. */
+export type CodecEncryptionMode = (typeof CodecEncryptionMode)[keyof typeof CodecEncryptionMode];
+
+/** The values of the table below, before freezing. */
+const virtualServerStatusValues = {
+  /** Running, and voice clients can connect. */
+  Online: "online",
+  /** Stopped. */
+  Offline: "offline",
+  /** Starting up. */
+  BootingUp: "booting up",
+  /** Stopping. */
+  ShuttingDown: "shutting down",
+  /**
+   * Stopped, but selected by a ServerQuery client with `-virtual` so it can be
+   * configured. Voice clients cannot connect, and it returns to offline when
+   * the last query client deselects it.
+   */
+  OnlineVirtual: "online virtual",
+} as const;
+/**
+ * The state of a virtual server (`virtualserver_status`), as `serverlist` and
+ * `whoami` report it.
+ */
+export const VirtualServerStatus: typeof virtualServerStatusValues =
+  /* @__PURE__ */ Object.freeze(virtualServerStatusValues);
+
+/** A virtual server status. */
+export type VirtualServerStatus = (typeof VirtualServerStatus)[keyof typeof VirtualServerStatus];
+
+/** The values of the table below, before freezing. */
+const bindingSubsystemValues = {
+  /** The voice port. */
+  Voice: "voice",
+  /** The ServerQuery port. */
+  Query: "query",
+  /** The file transfer port. */
+  FileTransfer: "filetransfer",
+} as const;
+/**
+ * What listens on an instance binding (`subsystem`), as `bindinglist` takes
+ * and reports it.
+ */
+export const BindingSubsystem: typeof bindingSubsystemValues =
+  /* @__PURE__ */ Object.freeze(bindingSubsystemValues);
+
+/** A binding subsystem. */
+export type BindingSubsystem = (typeof BindingSubsystem)[keyof typeof BindingSubsystem];
+
+/**
+ * Whether `value` is one of `table`'s values, narrowing it to the table's type.
+ * For a value from outside the program, such as one read back from storage or
+ * a configuration file, before it is passed where the table's type is taken:
+ *
+ * ```ts
+ * if (!isValueOf(BannerMode, row.bannerMode)) throw new Error(`bad banner mode ${row.bannerMode}`);
+ * await editChannel(client, cid, { bannerMode: row.bannerMode });
+ * ```
+ *
+ * It takes any of the SDK's tables, of any entry point, and compares with
+ * `===`: a number kept as text, `"2"`, is not the number `2`, so a value stored
+ * in another form is converted first.
+ */
+export function isValueOf<T extends Readonly<Record<string, string | number>>>(
+  table: T,
+  value: unknown,
+): value is T[keyof T] {
+  return (Object.values(table) as unknown[]).includes(value);
+}

package/src/core/index.ts

@@ -68,8 +68,12 @@ export { Reason } from "./reason.js";
 // Small-integer enumerations, as named values and types.
 export {
   APIKeyScope,
+  BannerMode,
+  BindingSubsystem,
   ClientType,
   Codec,
+  CodecEncryptionMode,
+  isValueOf,
   GroupAutoUpdateType,
   GroupNameMode,
   GroupType,
@@ -78,6 +82,7 @@ export {
   PermissionTarget,
   TextMessageTarget,
   PrivilegeKeyType,
+  VirtualServerStatus,
 } from "./enums.js";
 
 // Permissions, by id or by name.
@@ -88,11 +93,16 @@ export { NotificationName } from "./notification-name.js";
 export { PropertyName } from "./property-name.js";
 export type { Permission } from "./permission.js";
 
-export { noopLogger, consoleLogger, ClientStatus, serverFamilyForVersion } from "./types.js";
+export {
+  noopLogger,
+  consoleLogger,
+  ClientStatus,
+  ServerFamily,
+  serverFamilyForVersion,
+} from "./types.js";
 export type {
   ClientVersion,
   Listener,
-  ServerFamily,
   Unsubscribe,
   CommandMiddleware,
   FileDownloadInfo,

package/src/core/property-name.ts

@@ -37,7 +37,7 @@ const propertyNameValues = {
   VirtualServerCreated: "virtualserver_created",
   /** `virtualserver_uptime`: Seconds since the virtual server started. */
   VirtualServerUptime: "virtualserver_uptime",
-  /** `virtualserver_codec_encryption_mode`: The global codec encryption mode of the virtual server. Editable. */
+  /** `virtualserver_codec_encryption_mode`: The global codec encryption mode of the virtual server; see `CodecEncryptionMode`. Editable. */
   VirtualServerCodecEncryptionMode: "virtualserver_codec_encryption_mode",
   /** `virtualserver_hostmessage`: The host message of the server. Editable. */
   VirtualServerHostMessage: "virtualserver_hostmessage",
@@ -151,7 +151,7 @@ const propertyNameValues = {
   VirtualServerWebListEnabled: "virtualserver_weblist_enabled",
   /** `virtualserver_ask_for_privilegekey`: 1 if clients are asked for a privilege key on their first connection to an unclaimed server, 0 if not. */
   VirtualServerAskForPrivilegeKey: "virtualserver_ask_for_privilegekey",
-  /** `virtualserver_hostbanner_mode`: The display mode for the virtual servers hostbanner. Editable. */
+  /** `virtualserver_hostbanner_mode`: The display mode for the virtual servers hostbanner; see `BannerMode`. Editable. */
   VirtualServerHostBannerMode: "virtualserver_hostbanner_mode",
   /** `virtualserver_channel_temp_delete_delay_default`: Default delay, in seconds, before an empty temporary channel is deleted. */
   VirtualServerChannelTempDeleteDelayDefault: "virtualserver_channel_temp_delete_delay_default",
@@ -168,7 +168,7 @@ const propertyNameValues = {
   VirtualServerCapabilityExtensions: "virtualserver_capability_extensions",
   /** `virtualserver_file_storage_class`: Storage backend of the server's files; empty for the local disk. TeamSpeak 3 only. */
   VirtualServerFileStorageClass: "virtualserver_file_storage_class",
-  /** `virtualserver_status`: Status of the virtual server (online | virtual online | offline | booting up | shutting down). Editable. */
+  /** `virtualserver_status`: Status of the virtual server (online | online virtual | offline | booting up | shutting down); see `VirtualServerStatus`. Editable. */
   VirtualServerStatus: "virtualserver_status",
   /** `connection_filetransfer_bandwidth_sent`: Current file transfer upload speed, in bytes per second. Also in hostinfo and clientinfo. */
   ConnectionFileTransferBandwidthSent: "connection_filetransfer_bandwidth_sent",

package/src/core/types.ts

@@ -141,12 +141,23 @@ export const ClientStatus: typeof clientStatusValues =
  */
 export type ClientStatus = (typeof ClientStatus)[keyof typeof ClientStatus];
 
+/** The values of the table below, before freezing. */
+const serverFamilyValues = {
+  /** TeamSpeak 3: major version 3. */
+  TS3: "ts3",
+  /** TeamSpeak 6: major version 6 or later. */
+  TS6: "ts6",
+  /** A version string that names neither generation, or has no number. */
+  Unknown: "unknown",
+} as const;
+/** The server generation a version string belongs to. */
+export const ServerFamily: typeof serverFamilyValues =
+  /* @__PURE__ */ Object.freeze(serverFamilyValues);
 /**
- * The server generation a version string belongs to. May gain members in a
- * minor release, as server generations appear: a `switch` over it needs a
- * default case.
+ * One of {@link ServerFamily}. May gain members in a minor release, as server
+ * generations appear: a `switch` over it needs a default case.
  */
-export type ServerFamily = "ts3" | "ts6" | "unknown";
+export type ServerFamily = (typeof ServerFamily)[keyof typeof ServerFamily];
 
 /**
  * Pick the server generation from a `virtualserver_version` string such as
@@ -156,8 +167,8 @@ export type ServerFamily = "ts3" | "ts6" | "unknown";
  */
 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";
+  if (Number.isNaN(major)) return ServerFamily.Unknown;
+  if (major === 3) return ServerFamily.TS3;
+  if (major >= 6) return ServerFamily.TS6;
+  return ServerFamily.Unknown;
 }

package/src/query/client.ts

@@ -52,12 +52,8 @@ import {
 import type { ResolvedQueryOptions, ResolvedTransport } from "./options.js";
 import { defaultShouldRetry, noteConnectFailure } from "./reconnect.js";
 
-export type {
-  QueryClientOptions,
-  QueryEventsOption,
-  QueryEventCategory,
-  QueryTransportOptions,
-} from "./options.js";
+export type { QueryClientOptions, QueryEventsOption, QueryTransportOptions } from "./options.js";
+export { QueryEventCategory } from "./options.js";
 
 /**
  * The events `QueryClient.on()` takes, and what each delivers.
@@ -82,6 +78,72 @@ export type {
  */
 export interface QueryEventMap extends ServerEventMap, SessionEventMap {}
 
+/** The values of the table below, before freezing. */
+const queryEventNameValues = {
+  /** A text message to this client, its channel or the server. */
+  TextMessage: "textMessage",
+  /** A client coming into view, including every client already there on connecting. */
+  ClientEnter: "clientEnter",
+  /** A client going out of view. */
+  ClientLeave: "clientLeave",
+  /** A client changing channel. */
+  ClientMoved: "clientMoved",
+  /** A channel being created. */
+  ChannelCreated: "channelCreated",
+  /** A channel's properties being edited. */
+  ChannelEdited: "channelEdited",
+  /** A channel being moved or reordered. */
+  ChannelMoved: "channelMoved",
+  /** A channel being deleted. */
+  ChannelDeleted: "channelDeleted",
+  /** A channel's description changing; the text is not in it. */
+  ChannelDescriptionChanged: "channelDescriptionChanged",
+  /** A channel's password being set, changed or removed. */
+  ChannelPasswordChanged: "channelPasswordChanged",
+  /** The server's settings being edited. */
+  ServerEdited: "serverEdited",
+  /**
+   * Every notification the server sends, modelled or not, after any event it
+   * produces; one with a typed event arrives here as well, not only there.
+   */
+  Notification: "notification",
+  /** The handshake completing, on `connect()` and on every reconnection. */
+  Connected: "connected",
+  /** The connection ending, with its cause and whether a reconnection follows. */
+  Disconnected: "disconnected",
+  /** A kick from the server or from its channel; a kick from the server also ends the connection. */
+  Kicked: "kicked",
+} as const;
+/**
+ * The names of the events `QueryClient.on()` takes, as constants.
+ * `on(QueryEventName.TextMessage, ...)` and `on("textMessage", ...)` are the
+ * same call, and both give the listener the same payload type.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export const QueryEventName: typeof queryEventNameValues =
+  /* @__PURE__ */ Object.freeze(queryEventNameValues);
+/**
+ * One of {@link QueryEventName}, and so a key of {@link QueryEventMap}. May
+ * gain members in a minor release: a `switch` over it needs a default case.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export type QueryEventName = (typeof QueryEventName)[keyof typeof QueryEventName];
+
+// Each direction fails to compile when `QueryEventMap` and `QueryEventName`
+// drift: an event without a name, and a name that is not an event.
+const eventNamesCoverEventMap: [Exclude<keyof QueryEventMap, QueryEventName>] extends [never]
+  ? true
+  : never = true;
+const eventMapCoversEventNames: [Exclude<QueryEventName, keyof QueryEventMap>] extends [never]
+  ? true
+  : never = true;
+void eventNamesCoverEventMap;
+void eventMapCoversEventNames;
+
 /** How long a command waits for its answer unless told otherwise. */
 const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
 

package/src/query/index.ts

@@ -22,10 +22,9 @@
  * @packageDocumentation
  */
 
-export { QueryClient } from "./client.js";
+export { QueryClient, QueryEventCategory, QueryEventName } from "./client.js";
 export type {
   QueryClientOptions,
-  QueryEventCategory,
   QueryEventMap,
   QueryEventsOption,
   QueryTransportOptions,

package/src/query/options.ts

@@ -70,6 +70,23 @@ export type QueryTransportOptions =
       readonly open: (signal?: AbortSignal) => Promise<QueryTransport>;
     };
 
+/** The values of the table below, before freezing. */
+const queryEventCategoryValues = {
+  /** Server-wide events, such as clients joining and leaving. */
+  Server: "server",
+  /** Events of the channels, such as one being created or edited. */
+  Channel: "channel",
+  /** Text messages to the server. */
+  TextServer: "textserver",
+  /** Text messages to a channel. */
+  TextChannel: "textchannel",
+  /** Private text messages to this client. */
+  TextPrivate: "textprivate",
+  /** Ban list changes. */
+  Bans: "bans",
+  /** A privilege key being used. */
+  TokenUsed: "tokenused",
+} as const;
 /**
  * One category of notifications to register for: the `event` parameter of
  * `servernotifyregister`.
@@ -80,14 +97,10 @@ export type QueryTransportOptions =
  * then send `notifytokenused`, which carries a privilege key and has no typed
  * event, so it reaches `notification` only.
  */
-export type QueryEventCategory =
-  | "server"
-  | "channel"
-  | "textserver"
-  | "textchannel"
-  | "textprivate"
-  | "bans"
-  | "tokenused";
+export const QueryEventCategory: typeof queryEventCategoryValues =
+  /* @__PURE__ */ Object.freeze(queryEventCategoryValues);
+/** One of {@link QueryEventCategory}. */
+export type QueryEventCategory = (typeof QueryEventCategory)[keyof typeof QueryEventCategory];
 
 /**
  * Which notification categories to register for.
@@ -184,11 +197,11 @@ export interface QueryClientOptions {
 
 /** The five categories both raw TCP on TS3 and SSH on TS6 accept. */
 export const DEFAULT_EVENT_CATEGORIES: readonly QueryEventCategory[] = Object.freeze([
-  "server",
-  "channel",
-  "textserver",
-  "textchannel",
-  "textprivate",
+  QueryEventCategory.Server,
+  QueryEventCategory.Channel,
+  QueryEventCategory.TextServer,
+  QueryEventCategory.TextChannel,
+  QueryEventCategory.TextPrivate,
 ]);
 
 const CATEGORIES: ReadonlySet<string> = new Set([