auralis-sdk 0.2.0

package/dist/index.cjs

@@ -0,0 +1,674 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIError: () => APIError,
+  AuralisError: () => AuralisError,
+  AuthError: () => AuthError,
+  Client: () => Client,
+  EndReason: () => EndReason,
+  LoadError: () => LoadError,
+  LoadType: () => LoadType,
+  LoopMode: () => LoopMode,
+  NotConnected: () => NotConnected,
+  Player: () => Player,
+  REST: () => REST,
+  RateLimited: () => RateLimited,
+  endReasonAdvances: () => endReasonAdvances
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_node_events = require("events");
+var import_ws = __toESM(require("ws"), 1);
+
+// src/errors.ts
+var AuralisError = class extends Error {
+};
+var AuthError = class extends AuralisError {
+};
+var RateLimited = class extends AuralisError {
+  constructor(message, retryAfter) {
+    super(message);
+    this.retryAfter = retryAfter;
+  }
+  retryAfter;
+};
+var APIError = class extends AuralisError {
+  constructor(status, message) {
+    super(`HTTP ${status}: ${message}`);
+    this.status = status;
+  }
+  status;
+};
+var NotConnected = class extends AuralisError {
+};
+var LoadError = class extends AuralisError {
+};
+
+// src/types.ts
+var LoopMode = /* @__PURE__ */ ((LoopMode2) => {
+  LoopMode2["Off"] = "off";
+  LoopMode2["Track"] = "track";
+  LoopMode2["Queue"] = "queue";
+  return LoopMode2;
+})(LoopMode || {});
+var LoadType = /* @__PURE__ */ ((LoadType2) => {
+  LoadType2["Track"] = "track";
+  LoadType2["Playlist"] = "playlist";
+  LoadType2["Search"] = "search";
+  LoadType2["Empty"] = "empty";
+  LoadType2["Error"] = "error";
+  return LoadType2;
+})(LoadType || {});
+var EndReason = /* @__PURE__ */ ((EndReason2) => {
+  EndReason2["Finished"] = "FINISHED";
+  EndReason2["LoadFailed"] = "LOAD_FAILED";
+  EndReason2["Stopped"] = "STOPPED";
+  EndReason2["Replaced"] = "REPLACED";
+  EndReason2["Cleanup"] = "CLEANUP";
+  return EndReason2;
+})(EndReason || {});
+function endReasonAdvances(reason) {
+  return reason === "FINISHED" /* Finished */ || reason === "LOAD_FAILED" /* LoadFailed */;
+}
+function trackFromJson(d) {
+  return {
+    encoded: d.encoded,
+    identifier: d.identifier ?? "",
+    title: d.title ?? "",
+    author: d.author ?? "",
+    lengthMs: d.length_ms ?? 0,
+    isStream: d.is_stream ?? false,
+    uri: d.uri ?? void 0,
+    sourceName: d.source_name ?? "",
+    artworkUrl: d.artwork_url ?? void 0,
+    isrc: d.isrc ?? void 0,
+    extras: {}
+  };
+}
+function loadResultFromJson(d) {
+  return {
+    loadType: d.load_type ?? "empty",
+    tracks: (d.tracks ?? []).map(trackFromJson),
+    playlistName: d.playlist_name ?? void 0,
+    error: d.error ?? void 0
+  };
+}
+function playerStateFromJson(d) {
+  return {
+    connected: d.connected ?? false,
+    playing: d.playing ?? false,
+    paused: d.paused ?? false,
+    positionMs: d.position_ms ?? 0,
+    volume: d.volume ?? 100,
+    track: d.track ? trackFromJson(d.track) : void 0
+  };
+}
+
+// src/player.ts
+var Player = class {
+  constructor(host, guildId) {
+    this.host = host;
+    this.guildId = guildId;
+  }
+  host;
+  guildId;
+  queue = [];
+  history = [];
+  current = null;
+  /** Cap on retained history so a long-lived player can't leak memory. Queue-loop
+   * still works; it just restores the most recent `historyLimit` tracks. */
+  historyLimit = 200;
+  loop = "off" /* Off */;
+  volume = 100;
+  paused = false;
+  state = {
+    connected: false,
+    playing: false,
+    paused: false,
+    positionMs: 0,
+    volume: 100
+  };
+  /** Optional async hook used when the queue and loop are exhausted. */
+  autoplay = null;
+  created = false;
+  voiceServer = null;
+  voiceState = null;
+  // --- voice plumbing ---------------------------------------------------
+  handleVoiceServerUpdate(data) {
+    this.voiceServer = { token: data.token, endpoint: data.endpoint };
+    void this.maybeStart();
+  }
+  handleVoiceStateUpdate(data) {
+    if (data.channel_id === null || data.channel_id === void 0) {
+      this.voiceState = null;
+      return;
+    }
+    this.voiceState = {
+      session_id: data.session_id,
+      channel_id: Number(data.channel_id),
+      user_id: Number(data.user_id)
+    };
+    void this.maybeStart();
+  }
+  get connected() {
+    return this.voiceServer !== null && this.voiceState !== null;
+  }
+  voicePayload() {
+    return { ...this.voiceServer, ...this.voiceState, guild_id: this.guildId };
+  }
+  async maybeStart() {
+    if (this.connected && this.current === null && this.queue.length > 0) {
+      await this.advance();
+    }
+  }
+  // --- public commands --------------------------------------------------
+  async play(query, requester) {
+    const tracks = await this.resolve(query);
+    for (const t of tracks) {
+      if (requester !== void 0) t.extras.requester = requester;
+      this.queue.push(t);
+    }
+    if (this.current === null && this.connected) await this.advance();
+    return tracks;
+  }
+  async add(query, requester) {
+    const tracks = await this.resolve(query);
+    for (const t of tracks) {
+      if (requester !== void 0) t.extras.requester = requester;
+      this.queue.push(t);
+    }
+    return tracks;
+  }
+  async skip() {
+    await this.advance(true);
+  }
+  async stop() {
+    this.queue = [];
+    this.current = null;
+    if (this.created) await this.host.rest.stop(this.guildId);
+  }
+  async pause() {
+    await this.setPausedInternal(true);
+  }
+  async resume() {
+    await this.setPausedInternal(false);
+  }
+  async setPause(paused) {
+    await this.setPausedInternal(paused);
+  }
+  async seek(positionMs) {
+    if (this.created) await this.host.rest.seek(this.guildId, positionMs);
+  }
+  async setVolume(volume) {
+    this.volume = Math.max(0, Math.min(1e3, volume));
+    if (this.created) await this.host.rest.setVolume(this.guildId, this.volume);
+  }
+  setLoop(mode) {
+    this.loop = mode;
+  }
+  shuffle() {
+    for (let i = this.queue.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [this.queue[i], this.queue[j]] = [this.queue[j], this.queue[i]];
+    }
+  }
+  /** Apply a raw ffmpeg `-af` filtergraph (e.g. `"bass=g=8"`); `null` clears. */
+  async setFilters(audioGraph) {
+    if (this.created) await this.host.rest.setFilters(this.guildId, audioGraph);
+  }
+  remove(index) {
+    return this.queue.splice(index, 1)[0];
+  }
+  clear() {
+    this.queue = [];
+  }
+  /** Reorder the queue: move the track at `from` to `to`. No-op on bad indices. */
+  move(from, to) {
+    if (from < 0 || from >= this.queue.length || to < 0 || to >= this.queue.length) return;
+    const [t] = this.queue.splice(from, 1);
+    this.queue.splice(to, 0, t);
+  }
+  /** Resolve `query` and insert it at `index` (clamped) instead of appending. */
+  async insert(index, query, requester) {
+    const tracks = await this.resolve(query);
+    for (const t of tracks) if (requester !== void 0) t.extras.requester = requester;
+    const at = Math.max(0, Math.min(index, this.queue.length));
+    this.queue.splice(at, 0, ...tracks);
+    if (this.current === null && this.connected) await this.advance();
+    return tracks;
+  }
+  /** Batch-enqueue several queries/tracks in order. Failed resolves are skipped. */
+  async addMany(queries, requester) {
+    const added = [];
+    for (const q of queries) {
+      try {
+        const tracks = await this.resolve(q);
+        for (const t of tracks) {
+          if (requester !== void 0) t.extras.requester = requester;
+          this.queue.push(t);
+          added.push(t);
+        }
+      } catch {
+      }
+    }
+    if (this.current === null && this.connected && added.length > 0) await this.advance();
+    return added;
+  }
+  /** Skip forward to queue position `index`, discarding the ones in between. */
+  async jump(index) {
+    if (index < 0 || index >= this.queue.length) return;
+    const skipped = this.queue.splice(0, index);
+    for (const t of skipped) this.pushHistory(t);
+    await this.advance(true);
+  }
+  /** Replay the previous track (from history), pushing the current one back on. */
+  async previous() {
+    const prev = this.history.pop();
+    if (!prev) return;
+    if (this.current !== null) this.queue.unshift(this.current);
+    this.queue.unshift(prev);
+    await this.advance(true);
+  }
+  /** Convenience EQ: bass boost in dB (0 clears). Built on {@link setFilters}. */
+  async setBassBoost(gainDb) {
+    await this.setFilters(gainDb === 0 ? null : `bass=g=${gainDb}`);
+  }
+  /** Convenience speed/pitch (nightcore/vaporwave): `rate` 1.0 = normal. */
+  async setSpeed(rate) {
+    const r = Math.max(0.5, Math.min(2, rate));
+    await this.setFilters(r === 1 ? null : `atempo=${r},asetrate=48000*${r}`);
+  }
+  nowPlaying() {
+    return this.current;
+  }
+  async disconnect() {
+    this.queue = [];
+    this.current = null;
+    if (this.created) await this.host.rest.destroyPlayer(this.guildId);
+    this.created = false;
+    this.voiceServer = null;
+    this.voiceState = null;
+    this.host.dropPlayer(this.guildId);
+  }
+  // --- internals --------------------------------------------------------
+  /** Append to history, evicting the oldest past `historyLimit` (leak guard). */
+  pushHistory(track) {
+    this.history.push(track);
+    if (this.history.length > this.historyLimit) {
+      this.history.splice(0, this.history.length - this.historyLimit);
+    }
+  }
+  async resolve(query) {
+    if (typeof query !== "string") return [query];
+    const result = await this.host.rest.loadTracks(query);
+    if (result.error || result.tracks.length === 0) {
+      throw new LoadError(result.error ?? `no tracks for ${query}`);
+    }
+    return result.loadType === "playlist" /* Playlist */ ? result.tracks : [result.tracks[0]];
+  }
+  async nextTrack(forced) {
+    if (this.loop === "track" /* Track */ && this.current !== null && !forced) {
+      return this.current;
+    }
+    if (this.queue.length > 0) {
+      if (this.current !== null) this.pushHistory(this.current);
+      return this.queue.shift();
+    }
+    if (this.loop === "queue" /* Queue */ && this.history.length > 0) {
+      this.queue = [...this.history, ...this.current ? [this.current] : []];
+      this.history = [];
+      return this.queue.shift() ?? null;
+    }
+    if (this.autoplay !== null) return this.autoplay(this);
+    return null;
+  }
+  async advance(forced = false) {
+    const next = await this.nextTrack(forced);
+    if (next === null) {
+      this.current = null;
+      if (this.created) await this.host.rest.stop(this.guildId);
+      this.host.emit("queueEnd", this);
+      return;
+    }
+    await this.playTrack(next);
+  }
+  async playTrack(track) {
+    if (!this.connected) throw new NotConnected(`guild ${this.guildId} has no voice connection`);
+    this.current = track;
+    if (!this.created) {
+      await this.host.rest.createPlayer(this.guildId, this.voicePayload(), {
+        track: track.encoded,
+        volume: this.volume,
+        paused: this.paused
+      });
+      this.created = true;
+    } else {
+      await this.host.rest.play(this.guildId, track.encoded);
+    }
+  }
+  async setPausedInternal(paused) {
+    this.paused = paused;
+    if (this.created) await this.host.rest.setPaused(this.guildId, paused);
+  }
+  /** Called by the client's WS loop when a TRACK_END for this guild arrives. */
+  async onTrackEnd(advances) {
+    if (advances) await this.advance();
+  }
+};
+
+// src/rest.ts
+var REST = class {
+  base;
+  headers;
+  constructor(baseUrl, token) {
+    this.base = baseUrl.replace(/\/$/, "");
+    this.headers = {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json"
+    };
+  }
+  async request(method, path, body) {
+    const res = await fetch(`${this.base}${path}`, {
+      method,
+      headers: this.headers,
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+    if (res.status === 401 || res.status === 403) throw new AuthError(await res.text());
+    if (res.status === 429) {
+      const retry = res.headers.get("Retry-After");
+      throw new RateLimited(await res.text(), retry ? Number(retry) : void 0);
+    }
+    if (res.status >= 400) throw new APIError(res.status, await res.text());
+    const ct = res.headers.get("Content-Type") ?? "";
+    return ct.includes("application/json") ? res.json() : res.text();
+  }
+  // --- metadata ---------------------------------------------------------
+  async loadTracks(identifier) {
+    const q = new URLSearchParams({ identifier });
+    return loadResultFromJson(await this.request("GET", `/v1/loadtracks?${q}`));
+  }
+  async prewarm(encoded, guildId) {
+    const body = { tracks: encoded.map((e) => ({ encoded: e })) };
+    if (guildId !== void 0) body.guild_id = guildId;
+    return this.request("POST", "/v1/tracks/prewarm", body);
+  }
+  // --- player lifecycle -------------------------------------------------
+  async createPlayer(guildId, voice, opts = {}) {
+    const body = {
+      voice,
+      volume: opts.volume ?? 100,
+      paused: opts.paused ?? false
+    };
+    if (opts.track) body.track = { encoded: opts.track };
+    if (opts.audioGraph !== void 0) body.filters = { audio_graph: opts.audioGraph };
+    return this.request("POST", `/v1/guilds/${guildId}/players`, body);
+  }
+  async destroyPlayer(guildId) {
+    return this.request("DELETE", `/v1/guilds/${guildId}/players`);
+  }
+  async getState(guildId) {
+    return playerStateFromJson(await this.request("GET", `/v1/guilds/${guildId}/player`));
+  }
+  // --- playback control -------------------------------------------------
+  async play(guildId, track, audioGraph) {
+    const body = { track: { encoded: track } };
+    if (audioGraph !== void 0) body.filters = { audio_graph: audioGraph };
+    return this.request("POST", `/v1/guilds/${guildId}/player/play`, body);
+  }
+  async stop(guildId) {
+    return this.request("POST", `/v1/guilds/${guildId}/player/stop`, {});
+  }
+  async setPaused(guildId, paused) {
+    return this.request("POST", `/v1/guilds/${guildId}/player/pause`, { paused });
+  }
+  async setVolume(guildId, volume) {
+    return this.request("POST", `/v1/guilds/${guildId}/player/volume`, { volume });
+  }
+  async seek(guildId, positionMs) {
+    return this.request("POST", `/v1/guilds/${guildId}/player/seek`, {
+      position_ms: positionMs
+    });
+  }
+  async setFilters(guildId, audioGraph) {
+    return this.request("POST", `/v1/guilds/${guildId}/player/filters`, {
+      filters: { audio_graph: audioGraph }
+    });
+  }
+};
+
+// src/client.ts
+var EVENT_OPS = {
+  TRACK_START: "trackStart",
+  TRACK_END: "trackEnd",
+  TRACK_EXCEPTION: "trackException",
+  TRACK_STUCK: "trackStuck",
+  PLAYER_UPDATE: "playerUpdate",
+  VOICE_CLOSED: "voiceClosed",
+  STATS: "stats"
+};
+var Client = class extends import_node_events.EventEmitter {
+  rest;
+  baseUrl;
+  token;
+  reconnect;
+  playersMap = /* @__PURE__ */ new Map();
+  ws = null;
+  heartbeatTimer = null;
+  reconnectTimer = null;
+  sessionId = null;
+  closed = false;
+  backoff = 1e3;
+  hasConnected = false;
+  heartbeatSentAt = 0;
+  /** Last measured heartbeat round-trip latency in ms (-1 until first ack). */
+  latencyMs = -1;
+  /** Most recent STATS frame payload from the node, or null. */
+  lastStats = null;
+  constructor(baseUrl, token, opts = {}) {
+    super();
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.token = token;
+    this.reconnect = opts.reconnect ?? true;
+    this.rest = new REST(this.baseUrl, token);
+  }
+  // --- lifecycle --------------------------------------------------------
+  async start() {
+    this.closed = false;
+    this.openSocket();
+  }
+  async close() {
+    this.closed = true;
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.ws?.removeAllListeners();
+    this.ws?.close();
+    this.ws = null;
+  }
+  /** Emit "error" without the Node EventEmitter footgun: an unlistened "error"
+   * throws and would crash the host process, so fall back to a console warning. */
+  safeError(err) {
+    if (this.listenerCount("error") > 0) this.emit("error", err);
+    else console.warn("[auralis] unhandled client error:", err);
+  }
+  // --- players ----------------------------------------------------------
+  getPlayer(guildId) {
+    let p = this.playersMap.get(guildId);
+    if (!p) {
+      p = new Player(this, guildId);
+      this.playersMap.set(guildId, p);
+    }
+    return p;
+  }
+  players() {
+    return [...this.playersMap.values()];
+  }
+  dropPlayer(guildId) {
+    this.playersMap.delete(guildId);
+  }
+  // --- metadata convenience --------------------------------------------
+  loadTracks(identifier) {
+    return this.rest.loadTracks(identifier);
+  }
+  /** `ytsearch:`-prefix a bare query and return the hits (empty on miss). */
+  async search(query) {
+    const first = query.split(" ", 1)[0];
+    const ident = first.includes(":") ? query : `ytsearch:${query}`;
+    return (await this.loadTracks(ident)).tracks;
+  }
+  // --- websocket --------------------------------------------------------
+  get wsUrl() {
+    return this.baseUrl.replace(/^http/, "ws") + "/v1/ws";
+  }
+  openSocket() {
+    if (this.closed) return;
+    const ws = new import_ws.default(this.wsUrl, {
+      headers: { Authorization: `Bearer ${this.token}` }
+    });
+    this.ws = ws;
+    ws.on("open", () => {
+      this.backoff = 1e3;
+      this.subscribeAll();
+    });
+    ws.on("message", (raw) => {
+      let frame;
+      try {
+        frame = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+      this.handleFrame(frame).catch((e) => this.safeError(e));
+    });
+    ws.on("error", (err) => this.safeError(err));
+    ws.on("close", () => {
+      if (this.heartbeatTimer) {
+        clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+      }
+      this.ws = null;
+      if (this.closed || !this.reconnect) return;
+      this.emit("disconnect");
+      const jitter = this.backoff * (0.75 + Math.random() * 0.5);
+      this.reconnectTimer = setTimeout(() => this.openSocket(), jitter);
+      this.backoff = Math.min(this.backoff * 2, 3e4);
+    });
+  }
+  /** After a reconnect, pull each player's authoritative state from the node so
+   * position/volume/paused are accurate again. Per-player failures are ignored. */
+  async resyncPlayers() {
+    await Promise.all(
+      this.players().map(async (p) => {
+        try {
+          p.state = await this.rest.getState(p.guildId);
+        } catch {
+        }
+      })
+    );
+  }
+  subscribeAll() {
+    if (this.ws?.readyState === import_ws.default.OPEN && this.playersMap.size > 0) {
+      this.send({
+        op: "SUBSCRIBE",
+        d: { guilds: [...this.playersMap.keys()].map(String) }
+      });
+    }
+  }
+  send(payload) {
+    if (this.ws?.readyState === import_ws.default.OPEN) this.ws.send(JSON.stringify(payload));
+  }
+  async handleFrame(frame) {
+    const op = frame.op;
+    const d = frame.d ?? {};
+    if (op === "HELLO") {
+      const interval = d.heartbeat_interval_ms ?? 3e4;
+      if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+      let seq = 0;
+      this.heartbeatTimer = setInterval(() => {
+        this.heartbeatSentAt = Date.now();
+        this.send({ op: "HEARTBEAT", d: { seq: ++seq } });
+      }, interval);
+      return;
+    }
+    if (op === "READY") {
+      const resumed = this.hasConnected;
+      this.sessionId = d.session_id ?? null;
+      this.hasConnected = true;
+      this.subscribeAll();
+      if (resumed) {
+        await this.resyncPlayers();
+        this.emit("resumed");
+      } else {
+        this.emit("ready");
+      }
+      return;
+    }
+    if (op === "HEARTBEAT_ACK") {
+      if (this.heartbeatSentAt) this.latencyMs = Date.now() - this.heartbeatSentAt;
+      return;
+    }
+    if (op === "STATS") {
+      this.lastStats = d;
+    }
+    const guildId = d.guild_id ? Number(d.guild_id) : null;
+    const player = guildId !== null ? this.playersMap.get(guildId) : void 0;
+    if (op === "TRACK_END" && player) {
+      await player.onTrackEnd(endReasonAdvances(d.reason ?? "FINISHED"));
+    } else if (op === "PLAYER_UPDATE" && player) {
+      player.state = playerStateFromJson(d.state ?? {});
+    }
+    const eventName = EVENT_OPS[op];
+    if (eventName) this.emit(eventName, player ?? guildId, d);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIError,
+  AuralisError,
+  AuthError,
+  Client,
+  EndReason,
+  LoadError,
+  LoadType,
+  LoopMode,
+  NotConnected,
+  Player,
+  REST,
+  RateLimited,
+  endReasonAdvances
+});
+//# sourceMappingURL=index.cjs.map