@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.8

package/dist/query/stream.js

@@ -0,0 +1,70 @@
+import { LineReader } from "./lines.js";
+/**
+ * A {@link QueryTransport} over a byte stream: raw TCP, or an SSH shell.
+ *
+ * Both greet with a two-line banner, `TS3` and a welcome sentence, before any
+ * answer. It is skipped, so the client sees only answers and notifications.
+ */
+export class StreamTransport {
+    /** A raw TCP connection and an SSH session both carry pushed notifications. */
+    supportsNotifications = true;
+    onLine = null;
+    onClose = null;
+    #stream;
+    #reader = new LineReader();
+    #onEnd;
+    /** How many of the two banner lines are still to come. */
+    #banner = 2;
+    #closing = false;
+    #ended = false;
+    #error;
+    /**
+     * `onEnd` runs once the stream is closed, to release what the stream sits
+     * on: an SSH session's connection, say.
+     */
+    constructor(stream, onEnd) {
+        this.#stream = stream;
+        this.#onEnd = onEnd;
+        stream.on("data", (chunk) => this.#handleData(chunk));
+        stream.on("error", (error) => {
+            this.#error = error;
+        });
+        stream.on("close", () => this.#handleClose());
+    }
+    send(line) {
+        if (this.#ended)
+            return Promise.reject(new Error("the query connection is closed"));
+        return new Promise((resolve, reject) => {
+            this.#stream.write(`${line}\n`, (error) => (error ? reject(error) : resolve()));
+        });
+    }
+    close() {
+        if (this.#ended)
+            return Promise.resolve();
+        this.#closing = true;
+        // Ending the stream is not enough to hear it close. An SSH session channel
+        // is half-open, so `end()` sends EOF and stops there without reporting
+        // 'close', and the hook that releases the connection underneath would never
+        // run; the close is owed here as well as from the stream's own event.
+        this.#stream.end();
+        this.#handleClose();
+        return Promise.resolve();
+    }
+    #handleData(chunk) {
+        for (const line of this.#reader.push(chunk)) {
+            if (this.#banner > 0) {
+                this.#banner--;
+                continue;
+            }
+            this.onLine?.(line);
+        }
+    }
+    #handleClose() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        this.#onEnd?.();
+        this.onClose?.(this.#closing ? undefined : this.#error);
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/query/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/query/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAoBxC;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IAC1B,+EAA+E;IACtE,qBAAqB,GAAG,IAAI,CAAC;IACtC,MAAM,GAAoC,IAAI,CAAC;IAC/C,OAAO,GAAgD,IAAI,CAAC;IAE5D,OAAO,CAAc;IACrB,OAAO,GAAG,IAAI,UAAU,EAAE,CAAC;IAC3B,MAAM,CAA2B;IACjC,0DAA0D;IAC1D,OAAO,GAAG,CAAC,CAAC;IACZ,QAAQ,GAAG,KAAK,CAAC;IACjB,MAAM,GAAG,KAAK,CAAC;IACf,MAAM,CAAoB;IAE1B;;;OAGG;IACH,YAAY,MAAmB,EAAE,KAAkB;QACjD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;QACtD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC3B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,IAAI,CAAC,IAAY;QACf,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC,CAAC;QACpF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAClF,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC1C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,2EAA2E;QAC3E,uEAAuE;QACvE,4EAA4E;QAC5E,sEAAsE;QACtE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QACnB,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,WAAW,CAAC,KAAiB;QAC3B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;gBACrB,IAAI,CAAC,OAAO,EAAE,CAAC;gBACf,SAAS;YACX,CAAC;YACD,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,YAAY;QACV,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAChB,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1D,CAAC;CACF"}

package/dist/query/tcp.d.ts

@@ -0,0 +1,38 @@
+import type { Duplex } from "node:stream";
+import { StreamTransport } from "./stream.js";
+/**
+ * Opens the byte stream a raw ServerQuery connection runs over.
+ *
+ * Returns a `Duplex` rather than a `node:net` socket: naming a concrete
+ * platform type here would bind the interface to Node's socket class for good,
+ * and a caller supplying a TLS socket, a SOCKS proxy's socket or a test double
+ * has no reason to hand back that particular class.
+ */
+export type TcpConnector = (host: string, port: number) => Duplex | Promise<Duplex>;
+/** Where a raw ServerQuery listens. */
+export interface TcpOptions {
+    /** The server's host. */
+    readonly host: string;
+    /** The raw query port; 10011 by default. */
+    readonly port?: number | undefined;
+    /** Abandons the connection attempt. */
+    readonly signal?: AbortSignal | undefined;
+    /**
+     * Opens the connection. `net.createConnection` by default.
+     *
+     * The seam into the transport: supplying one lets an application route the
+     * session through a TLS terminator or a SOCKS proxy, or drive it from
+     * something that is not a socket at all. It is deliberately narrow, so that
+     * a later release can widen what it hands back without breaking an
+     * implementation written today.
+     */
+    readonly connect?: TcpConnector | undefined;
+}
+/**
+ * Open a raw ServerQuery connection (`node:net`, 10011 by default).
+ *
+ * Resolves once the stream is connected; the server's banner is read and
+ * dropped by the transport.
+ */
+export declare function connectTcp(options: TcpOptions): Promise<StreamTransport>;
+//# sourceMappingURL=tcp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tcp.d.ts","sourceRoot":"","sources":["../../src/query/tcp.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEpF,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,uCAAuC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAM9E"}

package/dist/query/tcp.js

@@ -0,0 +1,53 @@
+import { createConnection } from "node:net";
+import { StreamTransport } from "./stream.js";
+/**
+ * Open a raw ServerQuery connection (`node:net`, 10011 by default).
+ *
+ * Resolves once the stream is connected; the server's banner is read and
+ * dropped by the transport.
+ */
+export async function connectTcp(options) {
+    const { host, port = 10011, signal, connect = defaultConnect } = options;
+    signal?.throwIfAborted();
+    const stream = await connect(host, port);
+    await opened(stream, signal);
+    return new StreamTransport(stream);
+}
+/** A connected `node:net` socket, with whole lines sent as they are written. */
+function defaultConnect(host, port) {
+    const socket = createConnection({ host, port });
+    // Whole lines are sent, and a query's answers are small: no waiting to
+    // coalesce.
+    socket.setNoDelay(true);
+    return socket;
+}
+/**
+ * Wait until the stream is connected, if it is not already.
+ *
+ * A `Duplex` a caller handed back may be open, still opening, or a test double
+ * that is neither — `connecting` says which, and a stream without it counts as
+ * open, since nothing else could report the moment it becomes usable.
+ */
+function opened(stream, signal) {
+    const connecting = stream.connecting;
+    if (connecting !== true)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const failed = (error) => {
+            signal?.removeEventListener("abort", onAbort);
+            reject(error);
+        };
+        const onAbort = () => {
+            stream.destroy();
+            failed(signal.reason);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        stream.once("error", failed);
+        stream.once("connect", () => {
+            stream.off("error", failed);
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=tcp.js.map

package/dist/query/tcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tcp.js","sourceRoot":"","sources":["../../src/query/tcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAgC9C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAmB;IAClD,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,KAAK,EAAE,MAAM,EAAE,OAAO,GAAG,cAAc,EAAE,GAAG,OAAO,CAAC;IACzE,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED,gFAAgF;AAChF,SAAS,cAAc,CAAC,IAAY,EAAE,IAAY;IAChD,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,uEAAuE;IACvE,YAAY;IACZ,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,MAAM,CAAC,MAAc,EAAE,MAA+B;IAC7D,MAAM,UAAU,GAAI,MAA4C,CAAC,UAAU,CAAC;IAC5E,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAClD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,CAAC,KAAY,EAAQ,EAAE;YACpC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,CAAC,MAAO,CAAC,MAAe,CAAC,CAAC;QAClC,CAAC,CAAC;QACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;YAC1B,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/query/transport.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The connection a ServerQuery client talks over.
+ *
+ * ServerQuery is a line protocol on three transports: raw TCP (10011), SSH
+ * (10022) and, on TeamSpeak 6, an HTTP WebQuery (10080) that frames each
+ * command as a request. The client depends on this interface only, so each
+ * transport is a separate piece, and a test or a proxy can supply its own.
+ */
+export interface QueryTransport {
+    /**
+     * Whether this connection can receive notifications at all.
+     *
+     * Raw TCP and SSH can: the server pushes `notify…` lines down the same
+     * connection whenever it likes. WebQuery cannot — it has no session for the
+     * server to push to, and refuses `servernotifyregister` with 5120 — so it
+     * reports false.
+     *
+     * A custom transport declares its own truth here rather than leaving the
+     * caller to guess: a client uses it to decide whether to register for
+     * notifications at all, and whether a listener for a server event can ever
+     * run.
+     */
+    readonly supportsNotifications: boolean;
+    /** Send one command line; the transport adds the line terminator. */
+    send(line: string): Promise<void>;
+    /**
+     * Called with each line the server sends, without its terminator, in the
+     * order received.
+     */
+    onLine: ((line: string) => void) | null;
+    /** Called once when the connection ends, with the cause unless it was `close()`. */
+    onClose: ((error: Error | undefined) => void) | null;
+    /** End the connection. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/query/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,qEAAqE;IACrE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,oFAAoF;IACpF,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACrD,0BAA0B;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/query/transport.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport.js.map

package/dist/query/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/query/transport.ts"],"names":[],"mappings":""}

package/dist/query/web.d.ts

@@ -0,0 +1,54 @@
+import { TeamspeakError } from "@honeybbq/teamspeak";
+import type { QueryTransport } from "./transport.js";
+/**
+ * A WebQuery request that failed with an HTTP status and no TeamSpeak error in
+ * its answer: a wrong or missing api key, a server that is not a WebQuery. A
+ * refusal from the server itself carries a TeamSpeak code and is a
+ * `ServerError` instead.
+ */
+export declare class WebQueryHttpError extends TeamspeakError {
+    /** {@inheritDoc @honeybbq/teamspeak!TeamspeakError.kind} */
+    static readonly kind: string;
+    /** The HTTP status. */
+    readonly status: number;
+    constructor(status: number, statusText: string);
+}
+/** How a WebQuery is reached. */
+export interface WebQueryOptions {
+    /** The server's base URL, such as `http://127.0.0.1:10080`. */
+    readonly url: string;
+    /** The api key, sent as `x-api-key`. */
+    readonly apiKey: string;
+    /** The virtual server to address; `use` changes it. Unset addresses the instance. */
+    readonly serverID?: number | bigint | undefined;
+    /**
+     * The `fetch` to use. By default a small one over `node:http`: the global
+     * `fetch` refuses port 10080, WebQuery's own default, as a port the Fetch
+     * standard blocks.
+     */
+    readonly fetch?: typeof fetch | undefined;
+}
+/**
+ * A {@link QueryTransport} over WebQuery, TeamSpeak 6's HTTP interface.
+ *
+ * Each command line becomes one request, `POST /<server>/<command>` with the
+ * parameters as JSON, and the JSON answer is turned back into what a raw
+ * connection would have sent: one line per row, then `error id=… msg=…`. The
+ * client above sees one answer shape.
+ *
+ * WebQuery has no session, so two things differ. The api key replaces `login`,
+ * which the server refuses; and `use` is answered here, by changing the server
+ * the following requests address, since the server has no `use` either. It
+ * also sends no notifications, so there is nothing to register for.
+ */
+export declare class WebQueryTransport implements QueryTransport {
+    #private;
+    /** WebQuery has no session for the server to push a notification to. */
+    readonly supportsNotifications = false;
+    onLine: ((line: string) => void) | null;
+    onClose: ((error: Error | undefined) => void) | null;
+    constructor(options: WebQueryOptions);
+    send(line: string): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=web.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/query/web.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;IACnD,4DAA4D;IAC5D,gBAAyB,IAAI,EAAE,MAAM,CAAuB;IAU5D,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YAAY,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAG7C;CACF;AAED,iCAAiC;AACjC,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,GAAG,SAAS,CAAC;CAC3C;AAYD;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAkB,YAAW,cAAc;;IACtD,wEAAwE;IACxE,QAAQ,CAAC,qBAAqB,SAAS;IACvC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC/C,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAQ5D,YAAY,OAAO,EAAE,eAAe,EAKnC;IAEK,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CtC;IAED,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAKrB;CAmBF"}

package/dist/query/web.js

@@ -0,0 +1,146 @@
+import { request } from "node:http";
+import { TeamspeakError } from "@honeybbq/teamspeak";
+import { buildCommandOrdered, parseCommand, splitCommandRows } from "../core/internal.js";
+/**
+ * A WebQuery request that failed with an HTTP status and no TeamSpeak error in
+ * its answer: a wrong or missing api key, a server that is not a WebQuery. A
+ * refusal from the server itself carries a TeamSpeak code and is a
+ * `ServerError` instead.
+ */
+export class WebQueryHttpError extends TeamspeakError {
+    /** {@inheritDoc @honeybbq/teamspeak!TeamspeakError.kind} */
+    static kind = "WebQueryHttpError";
+    static {
+        Object.defineProperty(this.prototype, "name", {
+            value: "WebQueryHttpError",
+            writable: true,
+            configurable: true,
+            enumerable: false,
+        });
+    }
+    /** The HTTP status. */
+    status;
+    constructor(status, statusText) {
+        super(`WebQuery answered HTTP ${status}${statusText === "" ? "" : ` ${statusText}`}`);
+        this.status = status;
+    }
+}
+/**
+ * A {@link QueryTransport} over WebQuery, TeamSpeak 6's HTTP interface.
+ *
+ * Each command line becomes one request, `POST /<server>/<command>` with the
+ * parameters as JSON, and the JSON answer is turned back into what a raw
+ * connection would have sent: one line per row, then `error id=… msg=…`. The
+ * client above sees one answer shape.
+ *
+ * WebQuery has no session, so two things differ. The api key replaces `login`,
+ * which the server refuses; and `use` is answered here, by changing the server
+ * the following requests address, since the server has no `use` either. It
+ * also sends no notifications, so there is nothing to register for.
+ */
+export class WebQueryTransport {
+    /** WebQuery has no session for the server to push a notification to. */
+    supportsNotifications = false;
+    onLine = null;
+    onClose = null;
+    #base;
+    #apiKey;
+    #prefix;
+    #fetch;
+    #closed = false;
+    constructor(options) {
+        this.#base = options.url.replace(/\/+$/, "");
+        this.#apiKey = options.apiKey;
+        this.#prefix = options.serverID === undefined ? "" : `/${options.serverID}`;
+        this.#fetch = options.fetch ?? httpFetch;
+    }
+    async send(line) {
+        if (this.#closed)
+            throw new Error("the query connection is closed");
+        const rows = splitCommandRows(line)
+            .map((row) => parseCommand(row))
+            .filter((row) => row !== null);
+        const name = rows[0]?.name ?? "";
+        if (name === "use") {
+            this.#use(rows[0].params);
+            return;
+        }
+        const params = rows.map((row) => ({ ...row.params }));
+        const response = await this.#fetch(`${this.#base}${this.#prefix}/${name}`, {
+            method: "POST",
+            headers: { "x-api-key": this.#apiKey, "content-type": "application/json" },
+            body: JSON.stringify(params.length === 1 ? params[0] : params),
+        });
+        let answer;
+        try {
+            answer = (await response.json());
+        }
+        catch {
+            // Not JSON: nothing the server said about the command.
+        }
+        const code = answer?.status?.code;
+        if (typeof code !== "number")
+            throw new WebQueryHttpError(response.status, response.statusText);
+        const body = answer?.body;
+        for (const row of Array.isArray(body) ? body : []) {
+            if (typeof row === "object" && row !== null)
+                this.onLine?.(rowLine(row));
+        }
+        const message = answer?.status?.message;
+        const extra = answer?.status?.extra_message;
+        const tail = typeof extra === "string" && extra !== "" ? { extra_msg: extra } : {};
+        this.onLine?.(buildCommandOrdered("error", [
+            ["id", String(code)],
+            ["msg", typeof message === "string" ? message : ""],
+            ...Object.entries(tail),
+        ]));
+    }
+    close() {
+        if (this.#closed)
+            return Promise.resolve();
+        this.#closed = true;
+        this.onClose?.(undefined);
+        return Promise.resolve();
+    }
+    /** `use sid=1`, or `use port=9987`, which WebQuery addresses as `/byport/9987`. */
+    #use(params) {
+        const sid = params["sid"];
+        const port = params["port"];
+        if (sid !== undefined && /^\d+$/.test(sid))
+            this.#prefix = `/${sid}`;
+        else if (port !== undefined && /^\d+$/.test(port))
+            this.#prefix = `/byport/${port}`;
+        else {
+            this.onLine?.(buildCommandOrdered("error", [
+                ["id", "1538"],
+                ["msg", "invalid parameter"],
+            ]));
+            return;
+        }
+        this.onLine?.("error id=0 msg=ok");
+    }
+}
+/** One answer row as a line of `key=value` fields; a field that is not text is written as text. */
+function rowLine(row) {
+    const fields = Object.entries(row).map(([key, value]) => [key, typeof value === "string" ? value : String(value)]);
+    // buildCommandOrdered writes a name first; a row has none.
+    return buildCommandOrdered("", fields).slice(1);
+}
+/**
+ * The part of `fetch` this transport uses, over `node:http`: a POST with a
+ * string body, answered with a `Response`. Plain HTTP only, as WebQuery is.
+ */
+const httpFetch = ((url, init) => new Promise((resolve, reject) => {
+    const req = request(url, { method: init.method, headers: init.headers }, (res) => {
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("error", reject);
+        res.on("end", () => resolve(new Response(Buffer.concat(chunks), {
+            status: res.statusCode ?? 0,
+            statusText: res.statusMessage ?? "",
+        })));
+    });
+    req.on("error", reject);
+    req.end(init.body);
+}));
+//# sourceMappingURL=web.js.map

package/dist/query/web.js.map

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