@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.7

package/dist/core/reconnect.js

@@ -0,0 +1,55 @@
+/**
+ * Reconnection policy.
+ *
+ * A dropped connection is normal on a UDP voice session, so a bot that cannot
+ * recover is not usable unattended. Reconnecting is opt-in rather than
+ * automatic: a silent reconnect makes a dropped session look like a healthy
+ * one, and a caller that wanted to know about the drop never finds out.
+ *
+ * Backoff is not a nicety here. TeamSpeak bans an IP that opens several
+ * connections in quick succession — measured at roughly three, after which the
+ * server answers `error id=3329` and refuses everything. A reconnect loop
+ * without a delay therefore bans itself, and the ban outlasts the outage it was
+ * recovering from.
+ */
+/** One second, doubling, capped at a minute, with 20% jitter, never giving up. */
+export const defaultBackoffPolicy = Object.freeze({
+    initialDelayMs: 1_000,
+    maxDelayMs: 60_000,
+    factor: 2,
+    jitter: 0.2,
+    maxAttempts: 0,
+});
+/**
+ * Compute the delay before an attempt.
+ *
+ * `attempt` is 1-based: the delay before the first retry is `initialDelayMs`,
+ * give or take the jitter, and the delay never grows past `maxDelayMs`.
+ */
+export function backoffDelay(policy, attempt) {
+    return jitteredDelay(policy, attempt, Math.random);
+}
+/** @internal The delay, with `random` supplying the jitter. */
+export function jitteredDelay(policy, attempt, random) {
+    const exponent = Math.max(0, attempt - 1);
+    const raw = policy.initialDelayMs * policy.factor ** exponent;
+    const capped = Math.min(raw, policy.maxDelayMs);
+    if (policy.jitter <= 0)
+        return Math.round(capped);
+    // Full jitter would ignore the computed delay; this keeps the trend while
+    // spreading peers, so a whole fleet does not retry on the same millisecond.
+    // Kept under the ceiling, which a caller reasonably reads as a promise.
+    const spread = capped * Math.min(policy.jitter, 1);
+    const delay = capped + (random() * 2 - 1) * spread;
+    return Math.round(Math.max(0, Math.min(delay, policy.maxDelayMs)));
+}
+export function resolveBackoffPolicy(options) {
+    const policy = { ...defaultBackoffPolicy };
+    // An explicit undefined keeps the default, as an unset field does.
+    for (const [key, value] of Object.entries(options.backoff ?? {})) {
+        if (value !== undefined)
+            policy[key] = value;
+    }
+    return policy;
+}
+//# sourceMappingURL=reconnect.js.map

package/dist/core/reconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.js","sourceRoot":"","sources":["../../src/core/reconnect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAqBH,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAA4B,MAAM,CAAC,MAAM,CAAC;IACzE,cAAc,EAAE,KAAK;IACrB,UAAU,EAAE,MAAM;IAClB,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,GAAG;IACX,WAAW,EAAE,CAAC;CACf,CAAC,CAAC;AAmBH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAA+B,EAAE,OAAe;IAC3E,OAAO,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,aAAa,CAC3B,MAA+B,EAC/B,OAAe,EACf,MAAoB;IAEpB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IAC1C,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,GAAG,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC;IAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAEhD,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAElD,0EAA0E;IAC1E,4EAA4E;IAC5E,wEAAwE;IACxE,MAAM,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAyB;IAC5D,MAAM,MAAM,GAA2B,EAAE,GAAG,oBAAoB,EAAE,CAAC;IACnE,mEAAmE;IACnE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QACjE,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC/C,CAAC;IACD,OAAO,MAAkC,CAAC;AAC5C,CAAC"}

package/dist/core/types.d.ts

@@ -0,0 +1,110 @@
+import type { ClientFileTransferID, ServerFileTransferID } from "./command/ids.js";
+import type { CommandExecutor } from "./command/request.js";
+/**
+ * A client build a server accepts: the platform and version string a client
+ * sends in `clientinit`, and the signature TeamSpeak made over them.
+ *
+ * The signature is Ed25519 over the ASCII bytes of `platform` followed by
+ * `version`, base64 encoded. It cannot be made, only reused, so the values
+ * that work are the ones in `@honeybbq/teamspeak/versions`. The server checks
+ * the signature and refuses a build below its configured minimum.
+ */
+export interface ClientVersion {
+    /** The `client_platform` sent, such as `"Windows"`, `"Linux"` or `"Android"`. */
+    readonly platform: string;
+    /** The `client_version` sent, with its build, such as `"3.6.2 [Build: 1695203293]"`. */
+    readonly version: string;
+    /** Base64 of the 64-byte signature over `platform + version`. */
+    readonly sign: string;
+}
+/**
+ * Wraps the typed command layer, outermost first: it sees each request — the
+ * command's name and its parameters, passwords still in plain text — with its
+ * options, and returns the rows that answer it, or throws. So it can observe,
+ * time, retry, or answer a command itself without sending it.
+ *
+ * It wraps `send` rather than the interface — its type names that one method,
+ * `CommandExecutor["send"]` — so `send` is the whole seam between a client
+ * and a middleware.
+ *
+ * Only the typed commands, which reach the client through `send`, pass
+ * through it. Raw lines sent with `exec` or `execNoWait` and the client's own
+ * handshake-time commands do not. A request's parameters can hold passwords
+ * and privilege keys, so a middleware must not log them whole.
+ */
+export type CommandMiddleware = (next: CommandExecutor["send"]) => CommandExecutor["send"];
+/**
+ * Where the SDK logs. `console` is one; so is a pino or winston logger. The
+ * first argument is the message, the rest structured details.
+ */
+export interface Logger {
+    /** Detail for debugging the protocol; never the content of a command. */
+    debug(msg: string, ...args: unknown[]): void;
+    /** Connection lifecycle: connecting, connected, reconnecting. */
+    info(msg: string, ...args: unknown[]): void;
+    /** Something went wrong and was recovered from, or will be retried. */
+    warn(msg: string, ...args: unknown[]): void;
+    /** Something went wrong that the SDK could not report as an error to a caller. */
+    error(msg: string, ...args: unknown[]): void;
+}
+/** A no-op logger that discards all messages. */
+export declare const noopLogger: Logger;
+/** A console-backed logger. */
+export declare const consoleLogger: Logger;
+/** A negotiated upload, as `initFileUpload` returns it: what to dial and send. */
+export interface FileUploadInfo {
+    /** The key that identifies the transfer on the file transfer connection. */
+    readonly fileTransferKey: string;
+    /** Where to resume from, in bytes; 0 for a fresh upload. */
+    readonly seekPosition: bigint;
+    /** The client's id for the transfer. */
+    readonly clientFileTransferID: ClientFileTransferID;
+    /** The server's id for the transfer. */
+    readonly serverFileTransferID: ServerFileTransferID;
+    /** The file transfer port to dial. */
+    readonly port: number;
+}
+/** A negotiated download, as `initFileDownload` returns it: what to dial and receive. */
+export interface FileDownloadInfo {
+    /** The key that identifies the transfer on the file transfer connection. */
+    readonly fileTransferKey: string;
+    /** How many bytes the server will send. */
+    readonly size: bigint;
+    /** The client's id for the transfer. */
+    readonly clientFileTransferID: ClientFileTransferID;
+    /** The server's id for the transfer. */
+    readonly serverFileTransferID: ServerFileTransferID;
+    /** The file transfer port to dial. */
+    readonly port: number;
+}
+/** Removes a listener; calling it again does nothing. Also a `Disposable`, for `using`. */
+export type Unsubscribe = (() => void) & Disposable;
+/**
+ * A listener for the event `K` of the event map `M`: it takes the event's
+ * payload, or nothing for an event whose payload is `void`.
+ */
+export type Listener<M, K extends keyof M> = M[K] extends void ? () => void : (payload: M[K]) => void;
+/** The values of the table below, before freezing. */
+declare const clientStatusValues: {
+    /** Not connected: before `connect()`, after `disconnect()`, or after a drop. */
+    readonly Disconnected: "disconnected";
+    /** Connecting: `connect()` is waiting for the handshake. */
+    readonly Connecting: "connecting";
+    /** Connected: the handshake completed and commands can be sent. */
+    readonly Connected: "connected";
+};
+/** Where a client is in its connection's life. */
+export declare const ClientStatus: typeof clientStatusValues;
+/**
+ * One of {@link ClientStatus}. May gain members in a minor release: a
+ * `switch` over it needs a default case.
+ */
+export type ClientStatus = (typeof ClientStatus)[keyof typeof ClientStatus];
+/**
+ * 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";
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -0,0 +1,27 @@
+/** A no-op logger that discards all messages. */
+export const noopLogger = Object.freeze({
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+});
+/** A console-backed logger. */
+export const consoleLogger = Object.freeze({
+    debug: console.debug.bind(console),
+    info: console.info.bind(console),
+    warn: console.warn.bind(console),
+    error: console.error.bind(console),
+});
+/** The values of the table below, before freezing. */
+const clientStatusValues = {
+    /** Not connected: before `connect()`, after `disconnect()`, or after a drop. */
+    Disconnected: "disconnected",
+    /** Connecting: `connect()` is waiting for the handshake. */
+    Connecting: "connecting",
+    /** Connected: the handshake completed and commands can be sent. */
+    Connected: "connected",
+};
+/** Where a client is in its connection's life. */
+export const ClientStatus = 
+/* @__PURE__ */ Object.freeze(clientStatusValues);
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AA2DA,iDAAiD;AACjD,MAAM,CAAC,MAAM,UAAU,GAAW,MAAM,CAAC,MAAM,CAAC;IAC9C,KAAK,KAAI,CAAC;IACV,IAAI,KAAI,CAAC;IACT,IAAI,KAAI,CAAC;IACT,KAAK,KAAI,CAAC;CACX,CAAC,CAAC;AAEH,+BAA+B;AAC/B,MAAM,CAAC,MAAM,aAAa,GAAW,MAAM,CAAC,MAAM,CAAC;IACjD,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;IAClC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAChC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAChC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;CACnC,CAAC,CAAC;AAyCH,sDAAsD;AACtD,MAAM,kBAAkB,GAAG;IACzB,gFAAgF;IAChF,YAAY,EAAE,cAAc;IAC5B,4DAA4D;IAC5D,UAAU,EAAE,YAAY;IACxB,mEAAmE;IACnE,SAAS,EAAE,WAAW;CACd,CAAC;AACX,kDAAkD;AAClD,MAAM,CAAC,MAAM,YAAY;AACvB,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC"}

package/dist/query/client.d.ts

@@ -0,0 +1,194 @@
+import { ClientStatus, type CommandExecutor, type CommandOptions, type CommandRequest, type Listener, type ServerEventMap, type ServerFamily, type ServerID, type SessionEventMap, type Unsubscribe } from "@honeybbq/teamspeak";
+import type { QueryTransport } from "./transport.js";
+import { type QueryClientOptions, type QueryEventCategory } from "./options.js";
+export type { QueryClientOptions, QueryEventsOption, QueryEventCategory, QueryTransportOptions, } from "./options.js";
+/**
+ * The events `QueryClient.on()` takes, and what each delivers.
+ *
+ * The server's own events are the core's, unchanged: ServerQuery and the voice
+ * protocol carry the same notifications with the same fields, so a listener
+ * written for one client reads the other. `connected` and `disconnected` come
+ * from this client's own lifecycle.
+ *
+ * A notification reaches this client on two layers at once, as it does the
+ * voice client: the typed event for it, if it has one, and then `notification`,
+ * which carries every notification with its wire name and unescaped parameters.
+ * So a typed event added here is additive — the notification it names stays on
+ * the catch-all — and none of these keys is removed in a minor release.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export interface QueryEventMap extends ServerEventMap, SessionEventMap {
+}
+/**
+ * A ServerQuery client: runs the typed commands from `@honeybbq/teamspeak` over
+ * one of the three ServerQuery transports, and delivers the notifications the
+ * server sends as the core's typed events.
+ *
+ * ServerQuery answers one command at a time, in order: data lines, then an
+ * `error` line that ends the answer. So commands are queued and sent one after
+ * another, which also keeps the server's flood protection from seeing a burst.
+ * Notifications (`notify…`) can arrive at any point and are not part of an
+ * answer.
+ *
+ * The transport is given as a {@link QueryClientOptions.transport} description
+ * rather than an open connection, so the client can build it again when it
+ * reconnects.
+ *
+ * @experimental New in 1.x and may change in a minor release: the options, the
+ * transport union and the event map are all still settling.
+ */
+export declare class QueryClient implements CommandExecutor, AsyncDisposable {
+    #private;
+    constructor(options: QueryClientOptions);
+    /** Where the client is in its connection's life. */
+    get status(): ClientStatus;
+    /**
+     * Which server generation the server is, read from its `version` answer.
+     * `"unknown"` before connecting.
+     *
+     * @experimental Part of the entry, which may change in a minor release.
+     */
+    get serverFamily(): ServerFamily;
+    /** The `version` string the server answered with; "" before connecting. */
+    get serverVersion(): string;
+    /**
+     * The transport carrying this connection, or `undefined` when there is none.
+     *
+     * Read-only, and the transport is the interface the client itself talks
+     * over — counts of what went out and came in, and which connection it is,
+     * can be read from it for metrics. The socket underneath is not exposed:
+     * a caller that needs it supplies the seam instead (the `connect` option of
+     * a `tcp` transport, or `connection` of an `ssh` one), where it is theirs to
+     * keep.
+     *
+     * @experimental Part of the entry, which may change in a minor release.
+     */
+    get transport(): QueryTransport | undefined;
+    /**
+     * The notification categories this connection registered for: what `events`
+     * asked for, and empty when the transport delivers no notifications or the
+     * client is not connected.
+     */
+    get eventCategories(): readonly QueryEventCategory[];
+    /**
+     * Connect and set the session up: open the transport, then `login` (raw TCP
+     * only), `use`, `version`, the notification registrations, and one client
+     * list.
+     *
+     * The `login` and `server` options are applied here rather than left to the
+     * caller so that a reconnection is the same session as the first connection
+     * was.
+     *
+     * A failure rejects with its cause and leaves the client disconnected; the
+     * transport it opened is closed. `signal` bounds only the connecting: once
+     * this resolves, the connection lasts until `disconnect()` or a drop.
+     * `connect()` does not retry itself; the `reconnect` option retries a
+     * connection that dropped after it was established.
+     *
+     * `connected` is delivered before this resolves, so a listener added after
+     * `await client.connect()` has missed it — add the listeners first.
+     */
+    connect(options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<void>;
+    /**
+     * Leave the server and close the connection.
+     *
+     * A `connect()` still in flight fails with a NotConnectedError, and so do
+     * the commands still waiting for an answer. Resolves once `disconnected` has
+     * been delivered, so a listener added after `await client.disconnect()` does
+     * not hear it. Does nothing on a client that is not connected; called again
+     * while an earlier call is still running, it waits for that one. An explicit
+     * `disconnect()` never reconnects.
+     */
+    disconnect(): Promise<void>;
+    /** `await using client = …` disconnects when the scope ends. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Send a typed command. Passwords go as they are: ServerQuery takes the
+     * password itself and hashes it server-side, where the voice protocol wants
+     * the hash.
+     */
+    send(request: CommandRequest, options?: CommandOptions): Promise<Array<Record<string, string>>>;
+    /** Send a raw command line and return the rows that answer it. */
+    exec(line: string, options?: CommandOptions): Promise<Array<Record<string, string>>>;
+    /**
+     * Log in with a query account. Over WebQuery the api key does this, and the
+     * server refuses the command; over SSH the session is logged in already.
+     *
+     * Public because a caller driving the client by hand needs it: `connect()`
+     * runs it from the `login` option, and this is the same `login` command.
+     */
+    login(name: string, password: string, options?: CommandOptions): Promise<void>;
+    /**
+     * Select the virtual server the following commands address, by id or by
+     * voice port. `nickname` names the query client on it.
+     *
+     * Public for the same reason as {@link QueryClient.login}: `connect()` runs
+     * it from the `server` option, and this is the same `use` command. Over
+     * WebQuery the transport answers it, by addressing that server from then on.
+     */
+    use(server: {
+        readonly id: ServerID | number;
+    } | {
+        readonly port: number;
+    }, options?: CommandOptions & {
+        readonly nickname?: string | undefined;
+    }): Promise<void>;
+    /**
+     * Ask the server for the notifications of one category: `server`, `channel`
+     * (for one channel, or `0` for all), `textserver`, `textchannel`,
+     * `textprivate`, and on TeamSpeak 6 `bans`.
+     *
+     * Public for the same reason as {@link QueryClient.login}: `connect()` runs
+     * it once per configured category. With the WebQuery transport there is
+     * nothing to register for and the server refuses it, so the client never
+     * calls it there, and neither should a caller.
+     */
+    registerNotifications(event: QueryEventCategory, channelID?: bigint | number, options?: CommandOptions): Promise<void>;
+    /**
+     * Listen for an event. Returns a function that removes the listener, which is
+     * also a `Disposable` (`using stop = client.on(...)`).
+     *
+     * ```ts
+     * client.on("textMessage", (message) => console.log(message.message));
+     * ```
+     *
+     * A listener that throws does not stop the others: the rest of the event's
+     * listeners, and the events after it, are still delivered, and the exception
+     * is rethrown on its own, from a microtask, so it surfaces as an
+     * `uncaughtException` just as an EventEmitter listener's would.
+     *
+     * With the WebQuery transport no server event can ever arrive, so this throws
+     * a `TypeError` for one rather than accepting a listener that would never
+     * run. `connected` and `disconnected` are still accepted: they come from the
+     * client, not the server.
+     */
+    on<K extends keyof QueryEventMap>(event: K, listener: Listener<QueryEventMap, K>): Unsubscribe;
+    /** Listen for the next occurrence of an event only. */
+    once<K extends keyof QueryEventMap>(event: K, listener: Listener<QueryEventMap, K>): Unsubscribe;
+    /**
+     * An event as an async iterator, for `for await`:
+     *
+     * ```ts
+     * for await (const message of client.events("textMessage")) { … }
+     * ```
+     *
+     * Events that arrive while the loop body runs are buffered, so none is
+     * missed. The buffer is unbounded: an iterator that is not consumed as fast
+     * as events arrive holds every one of them, so stop iterating (or abort
+     * `signal`) when you stop reading.
+     *
+     * Iteration ends when the loop exits early (`break`, `return`, a throw), and
+     * — for every event but `disconnected` — when the client disconnects. When
+     * `signal` aborts, listening stops at once, whatever is buffered is
+     * discarded, and the pending and every later `next()` reject with the
+     * signal's reason.
+     */
+    events<K extends keyof QueryEventMap>(event: K, options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): AsyncIterableIterator<QueryEventMap[K]>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/query/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/query/client.ts"],"names":[],"mappings":"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"}