@honeybbq/teamspeak-client 0.3.1 → 1.0.0-beta.2

package/README.md

@@ -4,15 +4,19 @@
 
 **A clean-room TeamSpeak client protocol library written in pure TypeScript.**
 
-Compatible with TeamSpeak 3, 5 & 6. No proprietary SDK. No copy-pasted code.
+Works with TeamSpeak 3 and TeamSpeak 6 servers. No proprietary SDK, no copied code.
 
 [![CI](https://github.com/honeybbq/teamspeak-js/actions/workflows/ci.yml/badge.svg)](https://github.com/honeybbq/teamspeak-js/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@honeybbq/teamspeak-client)](https://www.npmjs.com/package/@honeybbq/teamspeak-client)
+[![npm beta](https://img.shields.io/npm/v/@honeybbq/teamspeak-client/beta?label=beta)](https://www.npmjs.com/package/@honeybbq/teamspeak-client?activeTab=versions)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/HoneyBBQ/teamspeak-js/badge)](https://scorecard.dev/viewer/?uri=github.com/HoneyBBQ/teamspeak-js)
 [![Node Version](https://img.shields.io/node/v/@honeybbq/teamspeak-client)](package.json)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 </div>
 
+Upgrading from 0.x? See the [migration guide](https://github.com/HoneyBBQ/teamspeak-js/blob/main/docs/migrating-to-1.0.md).
+
 ## Features
 
 - **Full protocol handshake** — ECDH key exchange, RSA puzzle, EAX-encrypted transport
@@ -20,22 +24,29 @@ Compatible with TeamSpeak 3, 5 & 6. No proprietary SDK. No copy-pasted code.
 - **Event-driven API** — Register handlers for text messages, client enter/leave, channel moves, kicks, etc.
 - **Voice data** — Send Opus voice packets (codec 4 & 5)
 - **File transfers** — Upload, download, and delete files on the server
-- **Address resolution** — SRV records, TSDNS, and direct address support
+- **Address resolution** — SRV records, TSDNS, and direct addresses; server nicknames on request (`resolveNicknames: true`), since that lookup goes to named.myteamspeak.com
 - **Middleware** — Pluggable command and event middleware chains
 - **Built-in rate limiter** — Token-bucket throttling to prevent server-side flood kicks
 - **Identity management** — Generate, import/export, and upgrade security level of identities
-- **Dual format** — Ships ESM and CJS with full TypeScript declarations
+- **Full command set** — 111 typed functions covering every command the voice protocol answers
+- **Reconnection** — Opt-in retry with backoff, tuned for TeamSpeak's antiflood ban
+- **Server capabilities** — Reports the server version and the uid hash it uses (SHA-1 on TS3, SHA-256 on TS6), and the server's name, icon, banner and welcome message
+- **Custom transports** — Supply your own socket, for proxies, tunnels or tests
+- **ESM with types** — Ships ES modules with full TypeScript declarations
 - **Zero native deps** — Pure TypeScript, no native addons required
 
 ## Installation
 
+1.0 is in beta, published under the `beta` tag. A plain `npm install` still
+gets 0.3, so ask for the beta:
+
 ```bash
-npm install @honeybbq/teamspeak-client
+npm install @honeybbq/teamspeak-client@beta
 # or
-pnpm add @honeybbq/teamspeak-client
+pnpm add @honeybbq/teamspeak-client@beta
 ```
 
-Requires **Node.js 20.19** or later.
+Everything in this README is the 1.0 API. You need Node.js 20.19 or newer.
 
 ## Quick Start
 
@@ -43,7 +54,7 @@ Requires **Node.js 20.19** or later.
 import { Client, generateIdentity } from "@honeybbq/teamspeak-client";
 
 // Generate a new identity (or load an existing one)
-const identity = generateIdentity(8);
+const identity = await generateIdentity(8);
 
 // Create the client
 const client = new Client(identity, "localhost", "TSBot", {
@@ -65,11 +76,8 @@ client.on("disconnected", (err) => {
   console.log("Disconnected:", err?.message ?? "clean");
 });
 
-// Connect
-await client.connect();
-
-// Wait until connected (with 15s timeout)
-await client.waitConnected(AbortSignal.timeout(15_000));
+// Connect; resolves once the handshake completes.
+await client.connect({ signal: AbortSignal.timeout(15_000) });
 
 // Stay connected until interrupted
 process.on("SIGINT", async () => {
@@ -81,12 +89,26 @@ process.on("SIGINT", async () => {
 
 ### Client Lifecycle
 
-| Method                                        | Description                         |
-| --------------------------------------------- | ----------------------------------- |
-| `new Client(identity, addr, nickname, opts?)` | Create a new client                 |
-| `connect()`                                   | Initiate connection to the server   |
-| `waitConnected(signal?)`                      | Block until the handshake completes |
-| `disconnect()`                                | Gracefully disconnect               |
+| Method                                        | Description                                       |
+| --------------------------------------------- | ------------------------------------------------- |
+| `new Client(identity, addr, nickname, opts?)` | Create a new client                               |
+| `connect({ signal? })`                        | Connect; resolves once the handshake completes    |
+| `disconnect({ signal? })`                     | Leave the server and close the connection         |
+| `status`                                      | `"disconnected"`, `"connecting"` or `"connected"` |
+| `clientID`                                    | Our clid, assigned by the server                  |
+| `channelID`                                   | The channel we are in                             |
+| `serverCapabilities`                          | Server version, family and uid hash               |
+| `uid`                                         | Our own uid, hashed as the server does            |
+
+`connect()` rejects with an `InvalidAddressError` for an address that cannot be
+one — no host, or a port outside 1–65535 — before anything starts; a host name
+that does not resolve fails with a `TeamspeakError` whose `cause` is the lookup's
+error. A `connect()` called while `disconnect()` is still saying goodbye waits
+for it to finish, then connects.
+
+Commands, raw `exec`/`execNoWait`, voice and whispers need a connected client:
+until `connect()` resolves, and from the moment `disconnect()` begins, they fail
+with a `NotConnectedError` and send nothing.
 
 ### Events
 
@@ -99,59 +121,204 @@ process.on("SIGINT", async () => {
 | `on("clientLeave", handler)`  | Fires when a client leaves         |
 | `on("clientMoved", handler)`  | Fires when a client moves channels |
 | `on("kicked", handler)`       | Fires when the bot is kicked       |
-| `on("poke", handler)`         | Fires when poked by a client       |
-| `on("voice", handler)`        | Fires on incoming voice data       |
+| `on("poked", handler)`        | Fires when poked by a client       |
+| `on("voiceData", handler)`    | Fires on incoming voice data       |
+
+`on()` and `once()` return a function that removes the listener, which is also
+a `Disposable` (`using listener = client.on(...)`). Listeners run one at a
+time, in the order their events arrived, so a listener may call the client and
+await an answer. `disconnected` delivers `undefined` after `disconnect()`, and
+the cause otherwise — a `ConnectionTimeoutError`, or a `RemovedError` for a kick, a ban
+or a server stopping. `await using client = new Client(...)` disconnects when
+the scope ends.
+
+`connected` is delivered after `connect()` resolves, so a listener added right
+after `await client.connect()` still hears it. `disconnect()` waits a second at
+most for the server to acknowledge its goodbye, less if its `signal` aborts
+sooner, and resolves once `disconnected` has been delivered. A `connect()` waits
+for an earlier session's `disconnected` to be delivered before it starts, so no
+listener or `events()` iterator of the new session hears the old one end.
+
+A listener that throws does not stop the others: the event still reaches the
+listeners after it, and the exception surfaces as an `uncaughtException`, as an
+EventEmitter listener's would.
+
+Voice is the exception to "every event in order": while more than 256
+deliveries are waiting, voice frames are dropped (and counted in a warning at
+most every ten seconds) rather than queued without bound.
+
+`events(name, { signal })` is the same as an async iterator, buffering events
+that arrive while the loop body runs:
+
+```typescript
+for await (const msg of client.events("textMessage", { signal })) {
+  await reply(msg);
+}
+```
+
+`notification` delivers every notification as it arrived, for the ones the SDK
+does not model. `NotificationName` names them:
+
+```typescript
+import { NotificationName } from "@honeybbq/teamspeak-client";
+
+client.on("notification", (n) => {
+  if (n.name === NotificationName.ChannelEdited) console.log(n.params);
+});
+```
 
 ### Commands
 
-| Function                                             | Description                                |
-| ---------------------------------------------------- | ------------------------------------------ |
-| `sendTextMessage(client, targetMode, targetID, msg)` | Send a text message                        |
-| `clientMove(client, clid, channelID, password?)`     | Move a client to a channel                 |
-| `poke(client, clid, message)`                        | Poke a client                              |
-| `client.sendVoice(data, codec)`                      | Send Opus voice data                       |
-| `client.sendWhisper(data, clientIds, codec)`         | Send Opus voice to specific clients        |
-| `listChannels(client)`                               | List all channels                          |
-| `listClients(client)`                                | List all connected clients                 |
-| `getClientInfo(client, clid)`                        | Get detailed client information            |
-| `client.execCommand(cmd, timeout?)`                  | Execute a raw command                      |
-| `client.execCommandWithResponse(cmd, timeout?)`      | Execute a command and return response data |
+Every command the voice protocol answers is a typed function, grouped by area.
+Each is addressed by branded ids, so a `ChannelID` cannot be passed where a
+`ClientID` is meant. The constructors — `asChannelID(5)`, `asClientID(3)` and
+the rest — throw a `RangeError` for anything but an integer in the id's wire
+range: 0–65535 for a `ClientID` and the file transfer ids, 0–2^32−1 for a
+`PermissionID` (an `IconID` also takes the signed form), 0–2^64−1 for the
+`bigint` ids. Required arguments are positional; everything optional
+goes in one options object, always the last argument, which also carries
+`signal` and `timeout` to abandon the command or bound how long it waits.
+
+```typescript
+import {
+  listChannels,
+  createChannel,
+  moveClient,
+  kickClient,
+  sendChannelMessage,
+  addServerGroupPermission,
+  iterateClientDatabase,
+  permissionByName,
+  PermissionName,
+  asClientID,
+  Codec,
+  Reason,
+} from "@honeybbq/teamspeak-client";
+
+const channels = await listChannels(client, { signal: AbortSignal.timeout(5_000) });
+
+const cid = await createChannel(client, {
+  name: "Lounge",
+  topic: "the quiet one",
+  codec: Codec.OpusVoice,
+  isPermanent: true,
+});
+
+await moveClient(client, client.clientID, cid, { password: "channel-password" });
+await sendChannelMessage(client, "hello");
+await kickClient(client, someone, Reason.KickChannel, { reasonMessage: "take a break" });
+
+await addServerGroupPermission(client, sgid, {
+  permission: permissionByName(PermissionName.ClientTalkPower),
+  value: 50,
+});
+
+for await (const entry of iterateClientDatabase(client)) {
+  console.log(entry.nickname, entry.lastConnectedAt);
+}
+```
+
+A command that sends content — `createChannel`'s channel, `editChannel`'s
+settings, `updateClient`, `editClient`, `editClientDatabase`,
+`addServerGroupPermission`'s grant, `addBan`'s `BanFields` — takes it as its own
+argument, and `{ signal, timeout }` as a separate one after it: set among the
+content, they are not read.
+
+Options objects use camelCase names (`maxClients` for `channel_maxclients`),
+and only the fields you set are sent: an unset field leaves the setting alone,
+while `""` sends it empty — `editChannel(client, cid, { password: "" })` clears
+a password. A key an options type does not name is never sent. The exceptions
+are `editServer` and `editInstance`, which take the raw `virtualserver_*` and
+`serverinstance_*` properties as `getServerInfo` reports them; `PropertyName` names
+the keys.
+
+Results are camelCase too. Timestamps are `Date`s (`undefined` where the server
+sends 0 for "never"), durations are milliseconds with an `Ms` suffix
+(`idleTimeMs`, `durationMs`), and a permission is a `Permission`, built with
+`permissionByID` or `permissionByName`. Small enumerations — `GroupType`,
+`Codec`, `PrivilegeKeyType`, `LogLevel` and the rest — are objects of named values with
+a type of the same name.
+
+| Module       | Covers                                                         |
+| ------------ | -------------------------------------------------------------- |
+| `channels`   | Create, edit, move, delete, subscribe, channel permissions     |
+| `clients`    | List, move, kick, poke, edit, the client database, permissions |
+| `server`     | Server and instance settings, groups, temp passwords, bindings |
+| `groups`     | Channel groups, the permission catalogue, privilege keys       |
+| `moderation` | Bans, complaints, offline messages, text messages, the log     |
+| `files`      | List, delete, rename, create directories, transfer negotiation |
+
+Many of these commands are answered over the voice protocol with a
+notification rather than data rows — `servergrouplist` with
+`notifyservergrouplist`, `ftinitupload` with `notifystartupload` after the
+command has already succeeded. The client pairs each answer with its command,
+so this is invisible to callers; [docs/voice-protocol-responses.md](https://github.com/HoneyBBQ/teamspeak-js/blob/main/docs/voice-protocol-responses.md)
+has the measured table. A refusal is always thrown, never returned as an empty
+result. A list or find with nothing to report answers `[]`. A command that
+exists to return something — `createChannel`'s id, `initFileUpload`'s key,
+`getClientInfo`'s fields — throws a `NoDataError` when the server answers
+without it, rather than returning an id of 0 or an empty object.
+
+For anything outside the typed set, `client.exec(line, { signal?, timeout? })`
+sends a raw command line and resolves to the rows that answer it.
 
 ### File Transfers
 
-| Function                               | Description                       |
-| -------------------------------------- | --------------------------------- |
-| `client.fileTransferInitUpload(...)`   | Initialize a file upload          |
-| `client.fileTransferInitDownload(...)` | Initialize a file download        |
-| `fileTransferDeleteFile(client, ...)`  | Delete files on the server        |
-| `uploadFileData(host, info, reader)`   | Transfer file data to the server  |
-| `downloadFileData(host, info, writer)` | Receive file data from the server |
+Negotiate with the `files` module, then move the bytes over TCP:
+
+```typescript
+import { Readable } from "node:stream";
+import { initFileUpload } from "@honeybbq/teamspeak-client";
+
+const info = await initFileUpload(client, cid, "/notes.txt", BigInt(data.length));
+await client.uploadFileData(host, info, Readable.from([data]));
+```
+
+An upload does not replace a file already at the path unless passed
+`{ overwrite: true }`.
+
+| Function                                                | Description                       |
+| ------------------------------------------------------- | --------------------------------- |
+| `initFileUpload(client, ...)`                           | Negotiate an upload               |
+| `initFileDownload(client, ...)`                         | Negotiate a download              |
+| `client.uploadFileData(host, info, data, { signal? })`  | Transfer file data to the server  |
+| `client.downloadFileData(host, info, out, { signal? })` | Receive file data from the server |
 
 ### Identity
 
 ```typescript
-import { generateIdentity, identityFromString } from "@honeybbq/teamspeak-client";
+import { generateIdentity, parseIdentity } from "@honeybbq/teamspeak-client";
 
 // Generate a new identity with security level 8
-const identity = generateIdentity(8);
+const identity = await generateIdentity(8);
 
 // Export to string for persistent storage
-const exported = identity.exportString();
+const exported = identity.export();
 
 // Import from a previously exported string
-const restored = identityFromString(exported);
+const restored = parseIdentity(exported);
+
+// Raise the security level (CPU-intensive). Identities are immutable: this
+// returns a new one with the same key.
+const stronger = await identity.upgradeToLevel(10, { signal });
 
-// Upgrade security level (CPU-intensive)
-identity.upgradeToLevel(10);
+// The unique identifier, hashed as a TS3 (sha1) or TS6 (sha256) server does
+const uid = identity.uid("sha1");
 ```
 
+The private key never leaves the identity except through `export()`:
+`toString()`, `toJSON()` and `util.inspect()` describe it without the key.
+`parseIdentity` takes exactly what `export()` writes — the key as canonical
+base64 of at most 32 bytes, a colon, and a decimal offset that fits in 64 bits
+— and throws an `InvalidIdentityError` for anything else.
+
 ### Options
 
 ```typescript
 const client = new Client(identity, "ts.example.com", "Bot", {
-  logger: consoleLogger,
+  logger: consoleLogger, // silent unless set
   resolver: customResolver,
-  commandMiddleware: [loggingMiddleware],
+  commandMiddleware: [timing],
   eventMiddleware: [filterMiddleware],
   serverPassword: process.env.TEAMSPEAK_SERVER_PASSWORD,
   defaultChannel: "Lobby",
@@ -159,48 +326,162 @@ const client = new Client(identity, "ts.example.com", "Bot", {
 });
 ```
 
+Address resolution — the built-in one or a custom `resolver` — has ten seconds
+in all: the `signal` a resolver is given aborts then, and the client connects
+to the address as given.
+
+`commandMiddleware` wraps the typed commands: each middleware receives the
+request (its command name and parameters) with its options and returns the
+answering rows, so it can time, retry or answer a command itself. Raw `exec`
+and `execNoWait` lines do not pass through it.
+
+```typescript
+const timing: CommandMiddleware = (next) => async (request, options) => {
+  const started = Date.now();
+  try {
+    return await next(request, options);
+  } finally {
+    console.log(request.command, Date.now() - started, "ms");
+  }
+};
+```
+
 Connection auth options:
 
 - `serverPassword`: plain-text server password; sent as the TeamSpeak protocol hash during `clientinit`
 - `defaultChannel`: default channel name requested during `clientinit`
 - `defaultChannelPassword`: plain-text password for `defaultChannel`; sent as the TeamSpeak protocol hash
 
-## Subpath Exports
+### Diagnostics
+
+The client logs nothing unless given a `logger`. For tracing, it publishes on
+two [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html)
+channels, which cost nothing without a subscriber:
+
+- `honeybbq:teamspeak:command` (`commandChannel`), a tracing channel: `start`
+  when a command is sent, `asyncEnd` when its answer arrives, `error` when it
+  fails.
+- `honeybbq:teamspeak:packet` (`packetChannel`): every command the server sends.
+
+Both carry the command's name, never its parameters, which hold password hashes
+and privilege keys.
+
+### Reconnection
+
+Off by default: a silent reconnect makes an outage look like a healthy session.
+An explicit `disconnect()` never reconnects, whatever the policy says.
+
+```typescript
+const client = new Client(identity, "ts.example.com", "Bot", {
+  reconnect: {
+    backoff: { initialDelayMs: 1_000, maxDelayMs: 60_000, factor: 2, jitter: 0.2 },
+    // Optional: decide for yourself which failures are worth retrying.
+    shouldRetry: (err, attempt) => attempt < 10,
+  },
+});
+```
+
+The defaults are conservative because TeamSpeak **bans an IP after roughly
+three rapid connects** — a retry loop without a delay bans itself, and the ban
+outlasts the outage it was recovering from. Recovery is also not instant even
+when it succeeds: the server holds the dropped session for a while and refuses a
+reconnect with `521 too many clones already connected` until it reaps it, so the
+loop keeps trying rather than giving up on the first refusal. It stops once a
+`connect()` of your own has connected the client, and it does not retry an
+address that cannot be one (`InvalidAddressError`).
+
+### Custom transports
 
-The package provides granular subpath exports for advanced use cases:
+`fileTransferSocketFactory` and `socketFactory` are the only seams into the
+network layer. Without them the SDK always creates its own sockets, so an
+application running behind a proxy has no way through. `socketFactory` returns
+a `DatagramSocket` — a `node:dgram` socket, or anything with the few methods
+it names — and `fileTransferSocketFactory` any `Duplex` stream, such as the
+socket a SOCKS library returns.
 
 ```typescript
-import { Identity } from "@honeybbq/teamspeak-client/crypto";
-import { Resolver } from "@honeybbq/teamspeak-client/discovery";
-import { PacketHandler } from "@honeybbq/teamspeak-client/transport";
-import { buildCommand, parseCommand } from "@honeybbq/teamspeak-client/command";
-import { processInit1 } from "@honeybbq/teamspeak-client/handshake";
+const client = new Client(identity, "ts.example.com", "Bot", {
+  // UDP, for the voice and command channel.
+  socketFactory: (family) => createSocket(family === 6 ? "udp6" : "udp4"),
+  // TCP, dialled separately by each file transfer.
+  fileTransferSocketFactory: (host, port) => createConnection({ host, port }),
+});
+```
+
+### Server capabilities
+
+```typescript
+const caps = client.serverCapabilities;
+// {
+//   version: "6.0.0-beta13.1 [Build: 1790080330]", major: 6, family: "ts6",
+//   uidAlgorithm: "sha256", name: "TeamSpeak 6 Server", iconID: undefined,
+//   hostBannerImageURL: undefined, welcomeMessage: "…"
+// }
 ```
 
+Read from `initserver` during the handshake, so it costs no extra round trip.
+The uid hash matters because TS3 hashes a client's public key with SHA-1 and TS6
+with SHA-256 — a client that assumes either one computes an identifier the other
+server never sends.
+
+## Compatibility
+
+The packages follow semver from 1.0. A few sets are open by nature and may
+gain members in a minor release: the events (`EventMap`, `ServerEventName`),
+`ClientStatus`, `ServerFamily`, `UIDAlgorithm`, `ErrorCode`, `Reason` and the
+enumeration tables. Write a `switch` over any of them with a default case. A
+field the server sends as a number that one of those tables names — a codec, a
+text message's target mode, a group type — is a plain `number`, since a server
+may send a value newer than the table.
+
+`DatagramSocket` describes the part of a socket the client uses; should a
+later release use more, the new members will be optional.
+
+The [Go SDK](https://github.com/honeybbq/teamspeak-go) makes the same calls
+with the same semantics, apart from what the languages make differ:
+
+- Backoff fields: JavaScript takes `undefined` as "the default" and `0` as 0.
+  Go cannot tell an unset field from 0, so there a zero field takes the default
+  and a negative jitter disables it.
+- A listener that throws: here the exception is rethrown from a microtask, an
+  uncaught exception as an EventEmitter listener's would be, and the other
+  listeners still get the event. Go recovers a panicking handler, logs it at
+  Error, and keeps delivering.
+- Durations are milliseconds with an `Ms` suffix here, `time.Duration` in Go;
+  `listClients`' `uid` flag (on by default) is Go's `OmitUID`.
+
+## Packages
+
+This package is the voice client. It depends on
+[`@honeybbq/teamspeak-core`](https://github.com/HoneyBBQ/teamspeak-js/tree/main/packages/core) — the command language, ids, errors and
+typed commands it shares with the ServerQuery client — and re-exports all of
+it, so this is the only package to install.
+
+The protocol internals (crypto, handshake, transport) are not exported. They
+change with the protocol, and exporting them would have made every change a
+breaking one.
+
 ## Architecture
 
 ```
-teamspeak-js/
+packages/client/
 ├── src/
 │   ├── client.ts          # Client lifecycle, connection management
-│   ├── api.ts             # High-level API (messages, channels, clients)
 │   ├── commands.ts        # Command sending and response tracking
+│   ├── api/voice.ts       # Commands only the voice protocol has
+│   ├── capabilities.ts    # Server version and uid hash detection
+│   ├── reconnect.ts       # Backoff policy and permanent-failure detection
 │   ├── events.ts          # Event handler registration and middleware
 │   ├── notifications.ts   # Server notification parsing and dispatch
 │   ├── handshake.ts       # Protocol handshake orchestration
-│   ├── transfer.ts        # File transfer operations
+│   ├── transfer.ts        # File transfer data connections
 │   ├── throttle.ts        # Token-bucket rate limiter
-│   ├── types.ts           # Public type definitions
-│   ├── errors.ts          # Error classes
 │   ├── crypto/            # ECDH, EAX encryption, identity management
 │   ├── handshake/         # Crypto handshake and license verification
 │   ├── transport/         # UDP packet framing, ACK, compression
-│   ├── command/           # Command builder and parser
 │   └── discovery/         # SRV / TSDNS / direct address resolution
-├── examples/
-│   └── connect.ts         # Minimal connection example
-├── vite.config.ts         # Build configuration (Vite library mode)
-└── tsconfig.json
+└── examples/
+    └── connect.ts         # Minimal connection example
 ```
 
 ## Related

package/dist/abort.d.ts

@@ -0,0 +1,5 @@
+/** The reason an aborted signal gives, as an error. */
+export declare function abortReason(signal: AbortSignal): unknown;
+/** Settle with `promise`, or reject as soon as `signal` aborts, whichever is first. */
+export declare function abortable<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAExD;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAiB7F"}

package/dist/address.d.ts

@@ -4,6 +4,14 @@ export interface HostPort {
 }
 /** Parse a TeamSpeak address without confusing an IPv6 colon for a port separator. */
 export declare function splitHostPort(address: string, defaultPort?: string): HostPort;
+/**
+ * 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 declare function parseConnectAddress(address: string): HostPort & {
+    portNumber: number;
+};
 export declare function joinHostPort(host: string, port: string): string;
 export declare function isIpAddress(host: string): boolean;
 //# sourceMappingURL=address.d.ts.map

package/dist/address.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,SAAS,GAAG,QAAQ,CA0B7E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD"}
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,SAAS,GAAG,QAAQ,CA0B7E;AAKD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAatF;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/dist/api/voice.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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-core";
+/** The channel's description, which `listChannels` omits for bandwidth. */
+export declare function getChannelDescription(client: Client, cid: ChannelID, options?: CommandOptions): Promise<string>;
+/**
+ * Subscribe to a channel: receive its clients' events and voice without
+ * joining it.
+ */
+export declare function subscribeChannel(client: Client, cid: ChannelID, options?: CommandOptions): Promise<void>;
+/** Stop receiving a subscribed channel's events and voice. */
+export declare function unsubscribeChannel(client: Client, cid: ChannelID, options?: CommandOptions): Promise<void>;
+/** Subscribe to every channel on the server. */
+export declare function subscribeAllChannels(client: Client, options?: CommandOptions): Promise<void>;
+/** Unsubscribe from every channel on the server. */
+export declare function unsubscribeAllChannels(client: Client, options?: CommandOptions): Promise<void>;
+//# sourceMappingURL=voice.d.ts.map

package/dist/api/voice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.d.ts","sourceRoot":"","sources":["../../src/api/voice.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1E,2EAA2E;AAC3E,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,8DAA8D;AAC9D,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,gDAAgD;AAChD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,oDAAoD;AACpD,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/capabilities.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 type { IconID } from "@honeybbq/teamspeak-core";
+import { type UIDAlgorithm } from "./crypto/identity.js";
+/**
+ * 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.
+ */
+export type ServerFamily = "ts3" | "ts6" | "unknown";
+/** 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;
+}
+/**
+ * Read what a server says about itself in `initserver`, or a version string
+ * alone, such as "6.0.0-beta13.1 [Build: 1]".
+ */
+export declare function parseServerCapabilities(initserver: string | Readonly<Record<string, string>>): ServerCapabilities;
+/**
+ * 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 declare function unknownServerCapabilities(): ServerCapabilities;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEjF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;AAErD,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,uFAAuF;IACvF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,gFAAgF;IAChF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpD,kBAAkB,CAqBpB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,kBAAkB,CAE9D"}