auralis-sdk 0.2.0

package/README.md

@@ -0,0 +1,90 @@
+# auralis-sdk
+
+Official **Node.js / TypeScript SDK** for the [Auralis](https://github.com/auralis/auralis)
+music platform. One runtime dependency (`ws`), a tiny command surface, and the whole
+queue/skip/loop/shuffle brain handled for you.
+
+```bash
+npm install auralis-sdk
+```
+
+Requires Node 18+ (uses the global `fetch`).
+
+## Quickstart
+
+```ts
+import { Client, LoopMode } from "auralis-sdk";
+
+const client = new Client("http://localhost:8080", "YOUR-API-TOKEN");
+await client.start();
+
+client.on("trackStart", (player) => console.log("now playing:", player.current?.title));
+client.on("queueEnd", (player) => player.disconnect());
+
+const player = client.getPlayer(123456789n as unknown as number); // guild id
+
+// --- wire your Discord library's voice events to the player (see below) ---
+
+await player.play("ytsearch:never gonna give you up");
+await player.add("https://youtu.be/dQw4w9WgXcQ");
+player.setLoop(LoopMode.Queue);
+```
+
+## Player commands
+
+| Command | Does |
+|---|---|
+| `await player.play(query)` | resolve + enqueue, start if idle |
+| `await player.add(query)` | enqueue only |
+| `await player.skip()` | advance to next track |
+| `await player.stop()` | stop + clear queue (stays connected) |
+| `await player.pause()` / `resume()` | pause / resume |
+| `await player.seek(ms)` | seek |
+| `await player.setVolume(0..1000)` | volume (100 = unity) |
+| `player.setLoop(LoopMode.Off/Track/Queue)` | loop mode |
+| `player.shuffle()` | shuffle the queue |
+| `player.nowPlaying()` | current `Track` |
+| `await player.setFilters("bass=g=8")` | raw ffmpeg `-af` filtergraph |
+| `await player.disconnect()` | tear down the player |
+
+`query` is a search string (`"ytsearch:…"`, a URL, a playlist URL) or a `Track` you
+already loaded via `client.search(...)` / `client.loadTracks(...)`.
+
+## Events
+
+`client.on("<name>", handler)`:
+
+| Event | Args |
+|---|---|
+| `ready` | — |
+| `trackStart` | `(player, data)` |
+| `trackEnd` | `(player, data)` — `data.reason` |
+| `trackException` | `(player, data)` |
+| `trackStuck` | `(player, data)` |
+| `playerUpdate` | `(player, data)` — `player.state` |
+| `voiceClosed` | `(player, data)` |
+| `queueEnd` | `(player)` |
+| `disconnect` | — (auto-reconnects) |
+
+## Wiring Discord voice
+
+The SDK never touches the Discord gateway — your bot owns that. Join a channel with
+your library (e.g. discord.js), then forward the two raw voice payloads:
+
+```ts
+// discord.js
+client_discord.ws.on("VOICE_SERVER_UPDATE", (d) =>
+  client.getPlayer(Number(d.guild_id)).handleVoiceServerUpdate(d),
+);
+client_discord.ws.on("VOICE_STATE_UPDATE", (d) => {
+  if (d.user_id === botUserId)
+    client.getPlayer(Number(d.guild_id)).handleVoiceStateUpdate(d);
+});
+```
+
+Once both arrive, the player connects and starts anything already queued.
+
+## Notes
+
+- The queue lives in this process (lost on bot restart).
+- Node internals (node ids, endpoints, regions) are never exposed by this SDK.