@honeybbq/teamspeak 1.0.0-beta.27 → 1.0.0-beta.29

package/README.md

@@ -8,8 +8,8 @@
 </p>
 
 <p align="center">
-  <strong>An independent TeamSpeak client protocol library written in pure TypeScript.</strong><br>
-  Works with TeamSpeak 3 and TeamSpeak 6 servers. No proprietary SDK or code.
+  <strong>A complete TeamSpeak client in pure TypeScript: voice, ServerQuery and screen share.</strong><br>
+  For TeamSpeak 3 and 6 servers. No native addons, no proprietary SDK.
 </p>
 
 <p align="center">
@@ -30,11 +30,11 @@
 
 ## Why this library
 
-- **The voice protocol, end to end.** ECDH key exchange, the RSA puzzle, EAX-encrypted transport, and Opus voice (codecs 4 and 5), in TypeScript with no native addons.
-- **ServerQuery too.** The same typed commands run over raw TCP, SSH (with host-key verification) or WebQuery, so an administration script and a voice bot share one vocabulary.
+- **Voice, both ways.** Send and receive Opus voice (codecs 4 and 5), whisper to clients, channels or groups, and get each frame with its speaker and sequence number for your own jitter buffer. The whole voice protocol is here: ECDH key exchange, the RSA puzzle and EAX-encrypted transport, in TypeScript with no native addons.
+- **ServerQuery.** The same typed commands run over raw TCP, SSH (with host-key verification) or WebQuery, so an administration script and a voice bot share one vocabulary.
+- **TeamSpeak 6 screen share.** Find, publish and watch the streams of a TeamSpeak 6 server, interoperable with the TeamSpeak 6 client. SDP and ICE are plain strings for any WebRTC stack: a browser, Electron, or werift in Node.
 - **Typed commands and events.** Every command the voice protocol answers is a typed function, and the server's notifications arrive as typed events with pluggable middleware.
-- **File transfers.** Upload, download and delete files on the server, with avatars and icons covered.
-- **TeamSpeak 6 screen-share signalling.** Find, publish and watch streams, with SDP and ICE as plain strings for any WebRTC stack.
+- **File transfers.** Upload, download and delete files on the server, with avatars and icons covered, and the S3 file transfer of a TeamSpeak 6 server that keeps its files in an S3 bucket.
 - **Built for long-running bots.** Opt-in reconnection tuned for TeamSpeak's antiflood ban, and a line middleware seam for pacing commands, with recipes for a token bucket, resending a refused command and keeping a query session open.
 - **Identities and server facts.** Generate, import, export and upgrade identities; read the server version, its uid hash (SHA-1 on TS3, SHA-256 on TS6) and its name, icon and banner.
 - **TeamSpeak 3 and 6, ESM with types.** Pure TypeScript, zero native dependencies, full declarations, and a custom-transport hook for proxies and tests.
@@ -84,14 +84,15 @@ process.on("SIGINT", () => void client.disconnect());
 
 The full API reference is at [honeybbq.github.io/teamspeak-js](https://honeybbq.github.io/teamspeak-js/). The pages below are the long-form guides.
 
-- [Guide](https://honeybbq.github.io/teamspeak-js/documents/guide.html): connecting, events, commands, file transfers and identities.
+- [Guide](https://honeybbq.github.io/teamspeak-js/documents/guide.html): connecting, events, sending and receiving voice, commands, file transfers and identities.
 - [Configuration](https://honeybbq.github.io/teamspeak-js/documents/configuration.html): options, client version, tracing, diagnostics, reconnection, custom transports and server capabilities.
-- [Streams](https://honeybbq.github.io/teamspeak-js/documents/streams.html): TeamSpeak 6 screen-share signalling, and interop with the TeamSpeak 6 client.
+- [Streams](https://honeybbq.github.io/teamspeak-js/documents/streams.html): watching and publishing TeamSpeak 6 screen shares, running WebRTC in Node and Electron, and interop with the TeamSpeak 6 client.
 - [ServerQuery](https://honeybbq.github.io/teamspeak-js/documents/serverquery.html): the query client and its SSH host-key policy.
 - [Flood control](https://honeybbq.github.io/teamspeak-js/documents/flood-control.html): what the server counts, what each command costs, and line middleware recipes for pacing, resending and keeping a query session open.
 - [Design](https://honeybbq.github.io/teamspeak-js/documents/design.html): errors, ids, absent values, events, stability, and the server behaviour the SDK works around.
 - [Compatibility](https://honeybbq.github.io/teamspeak-js/documents/compatibility.html): supported environments and the differences from the Go SDK.
 - [Architecture](https://honeybbq.github.io/teamspeak-js/documents/architecture.html): source layout and entry points.
+- [Examples](https://github.com/HoneyBBQ/teamspeak-js/tree/main/examples): connecting, a voice echo bot, watching a screen share from Node, pacing commands, and ServerQuery events and keepalive.
 - [Migrating to 1.0](https://honeybbq.github.io/teamspeak-js/documents/migrating-to-1.0.html), [voice protocol responses](https://honeybbq.github.io/teamspeak-js/documents/voice-protocol-responses.html) and [ServerQuery responses](https://honeybbq.github.io/teamspeak-js/documents/serverquery-responses.html): reference material.
 
 ## Compatibility

package/dist/client/api/files.d.ts

@@ -8,6 +8,10 @@
  * beta13.1 (SSH, voice), the key a query connection negotiates opens the same
  * file transfer port a voice client's does. WebQuery refuses every file command
  * (error 5120), on both servers.
+ *
+ * A TeamSpeak 6 server whose extensions name `s3` keeps a separate store in an
+ * S3 bucket, which these do not reach: see `uploadS3File` and the rest of the
+ * S3 functions.
  */
 import { Readable, Writable } from "node:stream";
 import type { ChannelID, CommandExecutor, FileDownloadOptions, FileUploadOptions } from "@honeybbq/teamspeak";

package/dist/client/api/files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../src/client/api/files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAa,QAAQ,EAAY,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EAEf,mBAAmB,EAEnB,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB,EAAE,mBAAmB;IAC/E;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB,EAAE,mBAAmB;IACnF,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAqHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,GAAG,QAAQ,EAC3B,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC;AACjB,wBAAgB,YAAY,CAC1B,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAAC"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../src/client/api/files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAa,QAAQ,EAAY,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EAEf,mBAAmB,EAEnB,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB,EAAE,mBAAmB;IAC/E;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB,EAAE,mBAAmB;IACnF,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAqHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,GAAG,QAAQ,EAC3B,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC;AACjB,wBAAgB,YAAY,CAC1B,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAAC"}

package/dist/client/api/files.js

@@ -8,6 +8,10 @@
  * beta13.1 (SSH, voice), the key a query connection negotiates opens the same
  * file transfer port a voice client's does. WebQuery refuses every file command
  * (error 5120), on both servers.
+ *
+ * A TeamSpeak 6 server whose extensions name `s3` keeps a separate store in an
+ * S3 bucket, which these do not reach: see `uploadS3File` and the rest of the
+ * S3 functions.
  */
 import { Readable, Transform, Writable, pipeline } from "node:stream";
 import { initFileDownload, initFileUpload, stopFileTransfer } from "@honeybbq/teamspeak";

package/dist/client/api/files.js.map

@@ -1 +1 @@
-{"version":3,"file":"files.js","sourceRoot":"","sources":["../../../src/client/api/files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AASzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AA+DnE,SAAS,iBAAiB,CAAC,MAAuB;IAChD,MAAM,SAAS,GAAG,MAAkC,CAAC;IACrD,OAAO,CACL,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;QAClC,OAAO,SAAS,CAAC,cAAc,KAAK,UAAU;QAC9C,OAAO,SAAS,CAAC,gBAAgB,KAAK,UAAU,CACjD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CACf,MAAuB,EACvB,OAA4F;IAK5F,IAAI,iBAAiB,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;QACtF,OAAO;YACL,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5E,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;SACjF,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACnF,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,SAAS,CACjB,4FAA4F,CAC7F,CAAC;IACJ,CAAC;IACD,OAAO;QACL,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9D,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;KACnE,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,SAAS,eAAe,CAAC,OAA4B;IACnD,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,aAAa,EAAE,OAAO,CAAC,aAAa;KACrC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,CAAC;AAErC,mFAAmF;AACnF,QAAQ,CAAC,CAAC,QAAQ,CAAC,IAAgB;IACjC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,CAAC;IAClC,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,kBAAkB,EAAE,CAAC;QAC5D,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,GAAG,kBAAkB,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CAAC,IAA2B,EAAE,QAAqC;IAChF,MAAM,IAAI,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACnE,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,UAAU,CAAC,qDAAqD,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,IAAI,YAAY,UAAU,EAAE,CAAC;QAC/B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,SAAS,CAAC,aAAa,IAAI,0BAA0B,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAChF,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,SAAS,CAAC,2DAA2D,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iDAAiD;AACjD,SAAS,SAAS,CAAC,KAAa;IAC9B,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,OAAO,IAAI,SAAS,CAAC;QACnB,SAAS,CAAC,KAAa,EAAE,SAAS,EAAE,QAAQ;YAC1C,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBACzB,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;gBACrB,QAAQ,EAAE,CAAC;gBACX,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,GAAG,CAAC,CAAC;YACT,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACvB,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAuB,EACvB,SAAoB,EACpB,IAAY,EACZ,IAA2B,EAC3B,OAAO,GAAsB,EAAE;IAE/B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE;QAC/D,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC,CAAC;IACH,0EAA0E;IAC1E,0BAA0B;IAC1B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACvC,IAAI,MAAgB,CAAC;IACrB,IAAI,IAAI,YAAY,UAAU;QAAE,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;SACjF,IAAI,IAAI,KAAK,CAAC;QAAE,MAAM,GAAG,IAAI,CAAC;;QAC9B,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACxD,MAAM,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAC5D,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,CACrD,CAAC;IACF,MAAM,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC;AAkCD,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAuB,EACvB,SAAoB,EACpB,IAAY,EACZ,OAAO,GAAwB,EAAE;IAEjC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,UAAU,CAAC,kDAAkD,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE;QAC3D,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC1B,MAAM,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAC5D,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,CACrD,CAAC;QACF,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC;IAC7C,IAAI,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,0EAA0E;QAC1E,2EAA2E;QAC3E,0CAA0C;QAC1C,MAAM,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,oBAAoB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC1E,MAAM,IAAI,iBAAiB,CACzB,mBAAmB,MAAM,oBAAoB,OAAO,iCAAiC,CACtF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC;QACxB,KAAK,CAAC,KAAa,EAAE,SAAS,EAAE,IAAI;YAClC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,IAAI,EAAE,CAAC;QACT,CAAC;KACF,CAAC,CAAC;IACH,MAAM,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAC5D,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,CACrD,CAAC;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,gBAAgB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC"}
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../../src/client/api/files.ts"],"names":[],"mappings":"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"}

package/dist/client/api/s3-list.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Reading the file list a TeamSpeak 6 server sends for `s3ft_list_files`.
+ */
+import type { S3FileEntry } from "./s3.js";
+/**
+ * The file list the server sends: base64 of the JSON
+ * `{"contents":[{"key":"dir/a.txt","last_modified":"…","size":2}]}`, each key
+ * from the channel's root without a leading slash, and an empty field for no
+ * files.
+ */
+export declare function parseFileList(field: string): S3FileEntry[];
+//# sourceMappingURL=s3-list.d.ts.map

package/dist/client/api/s3-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-list.d.ts","sourceRoot":"","sources":["../../../src/client/api/s3-list.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAmC1D"}

package/dist/client/api/s3-list.js

@@ -0,0 +1,43 @@
+/**
+ * Reading the file list a TeamSpeak 6 server sends for `s3ft_list_files`.
+ */
+import { NoDataError } from "@honeybbq/teamspeak";
+/**
+ * The file list the server sends: base64 of the JSON
+ * `{"contents":[{"key":"dir/a.txt","last_modified":"…","size":2}]}`, each key
+ * from the channel's root without a leading slash, and an empty field for no
+ * files.
+ */
+export function parseFileList(field) {
+    if (field === "")
+        return [];
+    const malformed = () => new NoDataError("s3ft_list_files", "the server answered s3ft_list_files with a malformed file list");
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(field, "base64").toString("utf8"));
+    }
+    catch {
+        throw malformed();
+    }
+    const contents = parsed?.contents;
+    if (!Array.isArray(contents))
+        throw malformed();
+    return contents.map((item) => {
+        const entry = item;
+        const key = entry?.key;
+        const size = entry?.size;
+        if (typeof key !== "string" ||
+            typeof size !== "number" ||
+            !Number.isSafeInteger(size) ||
+            size < 0) {
+            throw malformed();
+        }
+        const time = typeof entry?.last_modified === "string" ? new Date(entry.last_modified) : undefined;
+        return {
+            path: key.startsWith("/") ? key : `/${key}`,
+            size: BigInt(size),
+            modifiedAt: time === undefined || Number.isNaN(time.getTime()) ? undefined : time,
+        };
+    });
+}
+//# sourceMappingURL=s3-list.js.map

package/dist/client/api/s3-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-list.js","sourceRoot":"","sources":["../../../src/client/api/s3-list.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IAC5B,MAAM,SAAS,GAAG,GAAgB,EAAE,CAClC,IAAI,WAAW,CACb,iBAAiB,EACjB,gEAAgE,CACjE,CAAC;IACJ,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,SAAS,EAAE,CAAC;IACpB,CAAC;IACD,MAAM,QAAQ,GAAI,MAAwC,EAAE,QAAQ,CAAC;IACrE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAAE,MAAM,SAAS,EAAE,CAAC;IAChD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAa,EAAe,EAAE;QACjD,MAAM,KAAK,GAAG,IAAyE,CAAC;QACxF,MAAM,GAAG,GAAG,KAAK,EAAE,GAAG,CAAC;QACvB,MAAM,IAAI,GAAG,KAAK,EAAE,IAAI,CAAC;QACzB,IACE,OAAO,GAAG,KAAK,QAAQ;YACvB,OAAO,IAAI,KAAK,QAAQ;YACxB,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC;YAC3B,IAAI,GAAG,CAAC,EACR,CAAC;YACD,MAAM,SAAS,EAAE,CAAC;QACpB,CAAC;QACD,MAAM,IAAI,GACR,OAAO,KAAK,EAAE,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACvF,OAAO;YACL,IAAI,EAAE,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE;YAC3C,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC;YAClB,UAAU,EAAE,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;SAClF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/client/api/s3.d.ts

@@ -0,0 +1,239 @@
+/**
+ * TeamSpeak 6 S3 file transfer.
+ *
+ * A TeamSpeak 6 server started with S3 file transfer keeps channel files in an
+ * S3-compatible bucket, and says so: its `extensions`
+ * (`client.serverCapabilities.extensions`) name `"s3"`. A client asks the
+ * server for a presigned URL over the voice connection and moves the bytes
+ * with a plain HTTPS request to the storage; nothing goes through the server's
+ * file transfer port.
+ *
+ * TeamSpeak does not document these commands. Everything here was measured on
+ * TeamSpeak 6 6.0.0-beta13.1 with an S3-compatible storage behind TLS:
+ *
+ * - They run on the voice connection, which is why they take a `Client`:
+ *   WebQuery refuses them as unknown commands.
+ * - The server keeps each channel's file list in memory, takes a file out of it
+ *   when it deletes one, and reads it from the storage again when told an
+ *   upload is done: a file stored without {@link completeS3FileUpload} is not
+ *   listed.
+ * - Other clients are told nothing when a file is uploaded or deleted.
+ * - The classic file commands (`ftinitupload`, `ftgetfilelist`, …) still work
+ *   on such a server, and reach a separate store: a file uploaded one way is
+ *   not listed the other.
+ *
+ * Every function takes the channel password as `password`, in cleartext, and
+ * sends it the way every file command does.
+ */
+import { Readable, Writable } from "node:stream";
+import type { ChannelID, CommandOptions } from "@honeybbq/teamspeak";
+import type { Client } from "../client.js";
+/** The channel password an S3 file command needs, and the command's own options. */
+export interface S3FileOptions extends CommandOptions {
+    /** The channel's password, in cleartext; "" by default (`chpw`). */
+    readonly password?: string | undefined;
+}
+/**
+ * An upload the server signed: where to send the file, and what to tell the
+ * server once it is stored.
+ *
+ * `url` is a credential: whoever holds it can write the file until it expires,
+ * after the server's `s3ft-presigned-url-expiration` (300 seconds by default).
+ * Keep it out of logs.
+ */
+export interface S3FileUploadInfo {
+    /** The channel whose file area the file goes to. */
+    readonly channelID: ChannelID;
+    /** The file's path from the channel's root, as the server confirmed it. */
+    readonly path: string;
+    /** The size in bytes the URL is signed for. The upload must send exactly this many. */
+    readonly size: bigint;
+    /** The presigned URL to `PUT` the file to. */
+    readonly url: string;
+}
+/**
+ * A download the server signed. `url` is a credential as an upload's is: whoever
+ * holds it can read the file until it expires.
+ */
+export interface S3FileDownloadInfo {
+    /** The channel whose file area the file is in. */
+    readonly channelID: ChannelID;
+    /** The file's path from the channel's root, as the server confirmed it. */
+    readonly path: string;
+    /** The presigned URL to `GET` the file from. */
+    readonly url: string;
+}
+/** One file in a channel's S3 file area. */
+export interface S3FileEntry {
+    /** The file's path from the channel's root, with a leading slash: `/docs/a.txt`. */
+    readonly path: string;
+    /** The size in bytes. */
+    readonly size: bigint;
+    /** When the storage last wrote it; undefined when the server sent no time it could read. */
+    readonly modifiedAt: Date | undefined;
+}
+/** How an S3 transfer reaches the storage. */
+export interface S3TransferOptions {
+    /** Abandons the request; it then rejects with the signal's reason. */
+    readonly signal?: AbortSignal | undefined;
+    /**
+     * The `fetch` the request goes through; the global `fetch` by default. Pass
+     * one to route through a proxy, trust another certificate authority, time
+     * or watch the request, or to test.
+     */
+    readonly fetch?: typeof globalThis.fetch | undefined;
+}
+/** How {@link downloadS3FileData} reads the file. */
+export interface S3DownloadDataOptions extends S3TransferOptions {
+    /**
+     * The byte offset to start from, to resume; 0 by default. The bytes written
+     * are the file's from here to its end. The storage answers an offset at or
+     * past the end with 416, as an {@link S3TransferError}.
+     */
+    readonly seekPosition?: bigint | undefined;
+}
+/**
+ * Ask the server to sign an upload of `size` bytes to `path` in a channel's S3
+ * file area. Pass the result to {@link uploadS3FileData} to send the file, then
+ * to {@link completeS3FileUpload}; {@link uploadS3File} does all three.
+ *
+ * The upload replaces a file already at the path: the storage keeps no other
+ * copy, and nothing asks first. A client without upload power is refused with
+ * 2049 (invalid file permissions). A path into a directory the channel's file
+ * list does not have yet needs directory create power as well, and is refused
+ * with 2049 without it; an area with no files at all takes any path. The
+ * directory is no object of its own: it is there while a file is in it.
+ *
+ * Rejects with an {@link S3UnsupportedError} unless the server names `"s3"`
+ * among its extensions, and with a `TypeError` for a path that cannot be sent
+ * (see {@link uploadS3File}).
+ */
+export declare function initS3FileUpload(client: Client, channelID: ChannelID, path: string, size: bigint, options?: S3FileOptions): Promise<S3FileUploadInfo>;
+/**
+ * Ask the server to sign a download of `path` from a channel's S3 file area.
+ * Pass the result to {@link downloadS3FileData}; {@link downloadS3File} does
+ * both.
+ *
+ * The server signs a download whether or not the file is there: a missing one
+ * is the 404 of the download itself. A client without download power is
+ * refused with 2049 (invalid file permissions), as is a channel that does not
+ * exist.
+ */
+export declare function initS3FileDownload(client: Client, channelID: ChannelID, path: string, options?: S3FileOptions): Promise<S3FileDownloadInfo>;
+/**
+ * Tell the server an upload is stored, after {@link uploadS3FileData}. The
+ * server then reads the channel's file list from the storage again, and lists
+ * the file; without this it does not.
+ *
+ * Rejects with an {@link S3TransferError} when the server reports that its own
+ * request to the storage failed.
+ */
+export declare function completeS3FileUpload(client: Client, info: S3FileUploadInfo, options?: S3FileOptions): Promise<void>;
+/**
+ * Every file in a channel's S3 file area, in the storage's order (by path), as
+ * the server last read them from the storage.
+ *
+ * The list is the whole area, files in directories included: there are no
+ * directories, only paths. A file uploaded without
+ * {@link completeS3FileUpload} is missing from it until the server reads the
+ * list again. A channel that does not exist has no files.
+ */
+export declare function listS3Files(client: Client, channelID: ChannelID, options?: S3FileOptions): Promise<S3FileEntry[]>;
+/**
+ * Delete one file from a channel's S3 file area. The server deletes it from
+ * the storage and from the file list it keeps.
+ *
+ * Deleting a file that is not there succeeds, as the storage's delete does. A
+ * client without delete power is refused with 2568 (insufficient client
+ * permissions). Rejects with an {@link S3TransferError} when the server reports
+ * that its own request to the storage failed.
+ */
+export declare function deleteS3File(client: Client, channelID: ChannelID, path: string, options?: S3FileOptions): Promise<void>;
+/**
+ * Send a file to the storage, over an upload {@link initS3FileUpload} signed.
+ * `data` must be exactly `info.size` bytes: bytes or a `Blob` of another size
+ * are refused before anything is sent, and a stream that gives fewer or more
+ * fails the upload.
+ *
+ * Resolves once the storage has answered that it stored the file. Then call
+ * {@link completeS3FileUpload}, or the server does not list it. A failure is an
+ * {@link S3TransferError}: 403 for a URL that expired.
+ */
+export declare function uploadS3FileData(info: S3FileUploadInfo, data: Uint8Array | Blob | Readable, options?: S3TransferOptions): Promise<void>;
+/**
+ * Read a file from the storage into `dest`, over a download
+ * {@link initS3FileDownload} signed. Resolves once the file is written; `dest`
+ * is not ended, so it may take another download.
+ *
+ * A file that is not there is an {@link S3TransferError} with status 404; a URL
+ * that expired, one with 403.
+ */
+export declare function downloadS3FileData(info: S3FileDownloadInfo, dest: Writable, options?: S3DownloadDataOptions): Promise<void>;
+/**
+ * How {@link uploadS3File} signs and sends the file: the options of the
+ * commands and those of the request. `signal` applies to both.
+ */
+export interface UploadS3FileOptions extends S3FileOptions, S3TransferOptions {
+    /**
+     * The size in bytes of a stream passed as the data, which the server signs
+     * the upload for. Required for a `Readable`; for bytes or a `Blob` it is
+     * their size, and a different value here is refused.
+     */
+    readonly size?: bigint | number | undefined;
+}
+/**
+ * Upload a file into a channel's S3 file area: sign the upload
+ * ({@link initS3FileUpload}), send the file to the storage
+ * ({@link uploadS3FileData}) and tell the server it is stored
+ * ({@link completeS3FileUpload}), in one call.
+ *
+ * `data` is the bytes, a `Blob` (such as `fs.openAsBlob(file)`), or a
+ * `Readable` with `options.size` the number of bytes it will give. Resolves
+ * once the storage has stored the file and the server lists it. The file
+ * replaces one already at the path.
+ *
+ * `path` runs from the channel's root; a leading slash is added when missing,
+ * and the directories in it need not exist. A path is refused with a
+ * `TypeError` when an HTTP client would not send the URL the server signs for
+ * it: one with an empty, `.` or `..` segment, a control character, or a slash
+ * at its end.
+ *
+ * A refusal by the server is the ServerError it sends (2049 for a client
+ * without upload power); a failure of the storage request, or a server that
+ * reports its own request to the storage failed, is an {@link S3TransferError}. A
+ * server that does not name `"s3"` among its extensions is refused with an
+ * {@link S3UnsupportedError} before anything is sent.
+ */
+export declare function uploadS3File(client: Client, channelID: ChannelID, path: string, data: Uint8Array | Blob | Readable, options?: UploadS3FileOptions): Promise<void>;
+/**
+ * How {@link downloadS3File} signs and reads the file. With a `seekPosition`
+ * the bytes are the file's from there to its end.
+ */
+export interface DownloadS3FileOptions extends S3FileOptions, S3DownloadDataOptions {
+    /**
+     * Write the file into this stream instead of returning its bytes. The stream
+     * is neither ended nor destroyed, so it may take several downloads; a failed
+     * download still rejects the call.
+     */
+    readonly dest?: Writable | undefined;
+    /**
+     * The most bytes to hold in memory when no `dest` is given; 268435456
+     * (256 MiB) by default. A larger download is refused with a
+     * {@link FileTransferError} before its body is read.
+     */
+    readonly maxSize?: number | undefined;
+}
+/**
+ * Download a file from a channel's S3 file area into memory: sign the download
+ * ({@link initS3FileDownload}) and read the file ({@link downloadS3FileData}),
+ * in one call. With `options.dest` the bytes go into that stream instead and
+ * nothing is held, which is the way to fetch a large file.
+ *
+ * A file that is not there is an {@link S3TransferError} with status 404. Paths
+ * and refusals are as for {@link uploadS3File}.
+ */
+export declare function downloadS3File(client: Client, channelID: ChannelID, path: string, options: DownloadS3FileOptions & {
+    readonly dest: Writable;
+}): Promise<void>;
+export declare function downloadS3File(client: Client, channelID: ChannelID, path: string, options?: DownloadS3FileOptions): Promise<Uint8Array>;
+//# sourceMappingURL=s3.d.ts.map

package/dist/client/api/s3.d.ts.map

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