auralis-sdk 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,10 @@
 import { EventEmitter } from 'node:events';
 
 /** Wire vocabulary and data models — mirror the control-plane JSON exactly. */
+/** A Discord snowflake. Accepted as string/number/bigint at the API boundary and
+ * normalized to `bigint` internally: a 64-bit id cannot survive a JS `number`
+ * (over 2^53 the low digits corrupt), and the control plane parses ids as `u64`. */
+type Snowflake = string | number | bigint;
 /** How the queue advances when a track finishes. */
 declare enum LoopMode {
     Off = "off",
@@ -61,8 +65,8 @@ interface VoiceServerUpdate {
 }
 interface VoiceStateUpdate {
     session_id: string;
-    channel_id: string | number | null;
-    user_id: string | number;
+    channel_id: Snowflake | null;
+    user_id: Snowflake;
 }
 
 /** Thin wrapper over the control-plane HTTP API using the global `fetch`
@@ -71,24 +75,27 @@ interface VoiceStateUpdate {
 declare class REST {
     private base;
     private headers;
+    /** Per-request timeout (ms). Exposed so a slow-network deployment can raise it. */
+    timeoutMs: number;
     constructor(baseUrl: string, token: string);
+    private fetchWithTimeout;
     private request;
     loadTracks(identifier: string): Promise<LoadResult>;
-    prewarm(encoded: string[], guildId?: number): Promise<any>;
-    createPlayer(guildId: number, voice: Record<string, unknown>, opts?: {
+    prewarm(encoded: string[], guildId?: bigint): Promise<any>;
+    createPlayer(guildId: bigint, voice: Record<string, unknown>, opts?: {
         track?: string;
         volume?: number;
         paused?: boolean;
         audioGraph?: string;
     }): Promise<any>;
-    destroyPlayer(guildId: number): Promise<any>;
-    getState(guildId: number): Promise<PlayerState>;
-    play(guildId: number, track: string, audioGraph?: string): Promise<any>;
-    stop(guildId: number): Promise<any>;
-    setPaused(guildId: number, paused: boolean): Promise<any>;
-    setVolume(guildId: number, volume: number): Promise<any>;
-    seek(guildId: number, positionMs: number): Promise<any>;
-    setFilters(guildId: number, audioGraph: string | null): Promise<any>;
+    destroyPlayer(guildId: bigint): Promise<any>;
+    getState(guildId: bigint): Promise<PlayerState>;
+    play(guildId: bigint, track: string, audioGraph?: string): Promise<any>;
+    stop(guildId: bigint): Promise<any>;
+    setPaused(guildId: bigint, paused: boolean): Promise<any>;
+    setVolume(guildId: bigint, volume: number): Promise<any>;
+    seek(guildId: bigint, positionMs: number): Promise<any>;
+    setFilters(guildId: bigint, audioGraph: string | null): Promise<any>;
 }
 
 /** Per-guild player: the client-side queue brain.
@@ -108,12 +115,11 @@ declare class REST {
 interface PlayerHost {
     rest: REST;
     emit(event: string, ...args: unknown[]): void;
-    dropPlayer(guildId: number): void;
+    dropPlayer(guildId: bigint): void;
 }
 type AutoplayHook = (player: Player) => Promise<Track | null>;
 declare class Player {
     private host;
-    guildId: number;
     queue: Track[];
     history: Track[];
     current: Track | null;
@@ -126,13 +132,42 @@ declare class Player {
     state: PlayerState;
     /** Optional async hook used when the queue and loop are exhausted. */
     autoplay: AutoplayHook | null;
+    /** When a non-stream track "finishes" without ever streaming (dead source:
+     * geo/age-restricted, throttled, removed), search for and play an alternate
+     * upload instead of silently draining the queue. */
+    recoverDeadStreams: boolean;
+    /** A track whose furthest observed position never passed this many ms is
+     * treated as never-streamed (used by {@link recoverDeadStreams}). */
+    deadStreamThresholdMs: number;
+    /** Give up recovering a single dead track after this many alternate attempts. */
+    deadStreamRecoveryLimit: number;
+    /** Auto-skip a track the node reports as `TRACK_STUCK` instead of stalling. */
+    advanceOnStuck: boolean;
+    /** On a remote `VOICE_CLOSED`, reset so the next voice material re-creates the
+     * player and resumes the current track (the bot must re-send its op-4 join). */
+    rejoinOnVoiceClosed: boolean;
+    /** The guild this player drives. Always a `bigint` so 64-bit ids stay exact. */
+    readonly guildId: bigint;
     private created;
     private voiceServer;
     private voiceState;
-    constructor(host: PlayerHost, guildId: number);
+    /** Furthest position seen for the current track — reset on every track start. */
+    private maxPositionMs;
+    /** Alternate-upload attempts spent on the current dead track. */
+    private recoverAttempts;
+    constructor(host: PlayerHost, guildId: Snowflake);
     handleVoiceServerUpdate(data: VoiceServerUpdate): void;
     handleVoiceStateUpdate(data: VoiceStateUpdate): void;
     get connected(): boolean;
+    /** Called by the client on `PLAYER_UPDATE` (and reconnect resync). Tracks the
+     * furthest position reached so a "finished but never streamed" track can be
+     * spotted, and clears the recovery counter once a track is genuinely playing. */
+    applyState(state: PlayerState): void;
+    /** Discord terminated the voice session (remote `VOICE_CLOSED`). The node has
+     * dropped our player, so reset local voice/created state and requeue the
+     * current track; once the bot re-sends its op-4 join, fresh voice material
+     * re-creates the player and resumes. Bot-initiated closes don't call this. */
+    handleVoiceClosed(): void;
     private voicePayload;
     private maybeStart;
     play(query: string | Track, requester?: number): Promise<Track[]>;
@@ -173,8 +208,19 @@ declare class Player {
     private advance;
     private playTrack;
     private setPausedInternal;
-    /** Called by the client's WS loop when a TRACK_END for this guild arrives. */
+    /** Called by the client's WS loop when a TRACK_END for this guild arrives.
+     * `advances` is true for FINISHED / LOAD_FAILED. Before draining the queue we
+     * check for a dead source and try to recover it with an alternate upload. */
     onTrackEnd(advances: boolean): Promise<void>;
+    /** Called by the client on `TRACK_STUCK`: skip the stalled track. */
+    onTrackStuck(): Promise<void>;
+    /** A non-stream track that "finished" without its position ever advancing
+     * almost certainly never streamed. Genuinely short tracks (length at most a
+     * few × the threshold) are excluded so we don't loop on real short songs. */
+    private isDeadStream;
+    /** Search for an alternate upload of the current (dead) track and play it.
+     * Returns true when an alternate started; false to let the caller advance. */
+    private tryRecover;
 }
 
 /** The top-level client: owns the REST wrapper, the WebSocket event loop, the
@@ -190,14 +236,23 @@ interface ClientEvents {
     resumed: [];
     disconnect: [];
     error: [err: unknown];
-    trackStart: [player: Player | number, data: any];
-    trackEnd: [player: Player | number, data: any];
-    trackException: [player: Player | number, data: any];
-    trackStuck: [player: Player | number, data: any];
-    playerUpdate: [player: Player | number, data: any];
-    voiceClosed: [player: Player | number, data: any];
-    stats: [player: Player | number | null, data: any];
+    trackStart: [player: Player | bigint, data: any];
+    trackEnd: [player: Player | bigint, data: any];
+    trackException: [player: Player | bigint, data: any];
+    trackStuck: [player: Player | bigint, data: any];
+    playerUpdate: [player: Player | bigint, data: any];
+    voiceClosed: [player: Player | bigint, data: any];
+    stats: [player: Player | bigint | null, data: any];
     queueEnd: [player: Player];
+    /** A dead source could not be recovered — the bot should tell the user. */
+    trackStreamDead: [player: Player, data: {
+        failed: Track;
+    }];
+    /** A dead source was auto-recovered by playing an alternate upload. */
+    trackRecovered: [player: Player, data: {
+        failed: Track;
+        alternate: Track;
+    }];
 }
 interface Client {
     on<K extends keyof ClientEvents>(event: K, listener: (...args: ClientEvents[K]) => void): this;
@@ -229,9 +284,9 @@ declare class Client extends EventEmitter implements PlayerHost {
     /** Emit "error" without the Node EventEmitter footgun: an unlistened "error"
      * throws and would crash the host process, so fall back to a console warning. */
     private safeError;
-    getPlayer(guildId: number): Player;
+    getPlayer(guildId: Snowflake): Player;
     players(): Player[];
-    dropPlayer(guildId: number): void;
+    dropPlayer(guildId: bigint): void;
     loadTracks(identifier: string): Promise<LoadResult>;
     /** `ytsearch:`-prefix a bare query and return the hits (empty on miss). */
     search(query: string): Promise<Track[]>;
@@ -268,4 +323,4 @@ declare class NotConnected extends AuralisError {
 declare class LoadError extends AuralisError {
 }
 
-export { APIError, AuralisError, AuthError, type AutoplayHook, Client, type ClientEvents, type ClientOptions, EndReason, LoadError, type LoadResult, LoadType, LoopMode, NotConnected, Player, type PlayerHost, type PlayerState, REST, RateLimited, type Track, type VoiceServerUpdate, type VoiceStateUpdate, endReasonAdvances };
+export { APIError, AuralisError, AuthError, type AutoplayHook, Client, type ClientEvents, type ClientOptions, EndReason, LoadError, type LoadResult, LoadType, LoopMode, NotConnected, Player, type PlayerHost, type PlayerState, REST, RateLimited, type Snowflake, type Track, type VoiceServerUpdate, type VoiceStateUpdate, endReasonAdvances };

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 import { EventEmitter } from 'node:events';
 
 /** Wire vocabulary and data models — mirror the control-plane JSON exactly. */
+/** A Discord snowflake. Accepted as string/number/bigint at the API boundary and
+ * normalized to `bigint` internally: a 64-bit id cannot survive a JS `number`
+ * (over 2^53 the low digits corrupt), and the control plane parses ids as `u64`. */
+type Snowflake = string | number | bigint;
 /** How the queue advances when a track finishes. */
 declare enum LoopMode {
     Off = "off",
@@ -61,8 +65,8 @@ interface VoiceServerUpdate {
 }
 interface VoiceStateUpdate {
     session_id: string;
-    channel_id: string | number | null;
-    user_id: string | number;
+    channel_id: Snowflake | null;
+    user_id: Snowflake;
 }
 
 /** Thin wrapper over the control-plane HTTP API using the global `fetch`
@@ -71,24 +75,27 @@ interface VoiceStateUpdate {
 declare class REST {
     private base;
     private headers;
+    /** Per-request timeout (ms). Exposed so a slow-network deployment can raise it. */
+    timeoutMs: number;
     constructor(baseUrl: string, token: string);
+    private fetchWithTimeout;
     private request;
     loadTracks(identifier: string): Promise<LoadResult>;
-    prewarm(encoded: string[], guildId?: number): Promise<any>;
-    createPlayer(guildId: number, voice: Record<string, unknown>, opts?: {
+    prewarm(encoded: string[], guildId?: bigint): Promise<any>;
+    createPlayer(guildId: bigint, voice: Record<string, unknown>, opts?: {
         track?: string;
         volume?: number;
         paused?: boolean;
         audioGraph?: string;
     }): Promise<any>;
-    destroyPlayer(guildId: number): Promise<any>;
-    getState(guildId: number): Promise<PlayerState>;
-    play(guildId: number, track: string, audioGraph?: string): Promise<any>;
-    stop(guildId: number): Promise<any>;
-    setPaused(guildId: number, paused: boolean): Promise<any>;
-    setVolume(guildId: number, volume: number): Promise<any>;
-    seek(guildId: number, positionMs: number): Promise<any>;
-    setFilters(guildId: number, audioGraph: string | null): Promise<any>;
+    destroyPlayer(guildId: bigint): Promise<any>;
+    getState(guildId: bigint): Promise<PlayerState>;
+    play(guildId: bigint, track: string, audioGraph?: string): Promise<any>;
+    stop(guildId: bigint): Promise<any>;
+    setPaused(guildId: bigint, paused: boolean): Promise<any>;
+    setVolume(guildId: bigint, volume: number): Promise<any>;
+    seek(guildId: bigint, positionMs: number): Promise<any>;
+    setFilters(guildId: bigint, audioGraph: string | null): Promise<any>;
 }
 
 /** Per-guild player: the client-side queue brain.
@@ -108,12 +115,11 @@ declare class REST {
 interface PlayerHost {
     rest: REST;
     emit(event: string, ...args: unknown[]): void;
-    dropPlayer(guildId: number): void;
+    dropPlayer(guildId: bigint): void;
 }
 type AutoplayHook = (player: Player) => Promise<Track | null>;
 declare class Player {
     private host;
-    guildId: number;
     queue: Track[];
     history: Track[];
     current: Track | null;
@@ -126,13 +132,42 @@ declare class Player {
     state: PlayerState;
     /** Optional async hook used when the queue and loop are exhausted. */
     autoplay: AutoplayHook | null;
+    /** When a non-stream track "finishes" without ever streaming (dead source:
+     * geo/age-restricted, throttled, removed), search for and play an alternate
+     * upload instead of silently draining the queue. */
+    recoverDeadStreams: boolean;
+    /** A track whose furthest observed position never passed this many ms is
+     * treated as never-streamed (used by {@link recoverDeadStreams}). */
+    deadStreamThresholdMs: number;
+    /** Give up recovering a single dead track after this many alternate attempts. */
+    deadStreamRecoveryLimit: number;
+    /** Auto-skip a track the node reports as `TRACK_STUCK` instead of stalling. */
+    advanceOnStuck: boolean;
+    /** On a remote `VOICE_CLOSED`, reset so the next voice material re-creates the
+     * player and resumes the current track (the bot must re-send its op-4 join). */
+    rejoinOnVoiceClosed: boolean;
+    /** The guild this player drives. Always a `bigint` so 64-bit ids stay exact. */
+    readonly guildId: bigint;
     private created;
     private voiceServer;
     private voiceState;
-    constructor(host: PlayerHost, guildId: number);
+    /** Furthest position seen for the current track — reset on every track start. */
+    private maxPositionMs;
+    /** Alternate-upload attempts spent on the current dead track. */
+    private recoverAttempts;
+    constructor(host: PlayerHost, guildId: Snowflake);
     handleVoiceServerUpdate(data: VoiceServerUpdate): void;
     handleVoiceStateUpdate(data: VoiceStateUpdate): void;
     get connected(): boolean;
+    /** Called by the client on `PLAYER_UPDATE` (and reconnect resync). Tracks the
+     * furthest position reached so a "finished but never streamed" track can be
+     * spotted, and clears the recovery counter once a track is genuinely playing. */
+    applyState(state: PlayerState): void;
+    /** Discord terminated the voice session (remote `VOICE_CLOSED`). The node has
+     * dropped our player, so reset local voice/created state and requeue the
+     * current track; once the bot re-sends its op-4 join, fresh voice material
+     * re-creates the player and resumes. Bot-initiated closes don't call this. */
+    handleVoiceClosed(): void;
     private voicePayload;
     private maybeStart;
     play(query: string | Track, requester?: number): Promise<Track[]>;
@@ -173,8 +208,19 @@ declare class Player {
     private advance;
     private playTrack;
     private setPausedInternal;
-    /** Called by the client's WS loop when a TRACK_END for this guild arrives. */
+    /** Called by the client's WS loop when a TRACK_END for this guild arrives.
+     * `advances` is true for FINISHED / LOAD_FAILED. Before draining the queue we
+     * check for a dead source and try to recover it with an alternate upload. */
     onTrackEnd(advances: boolean): Promise<void>;
+    /** Called by the client on `TRACK_STUCK`: skip the stalled track. */
+    onTrackStuck(): Promise<void>;
+    /** A non-stream track that "finished" without its position ever advancing
+     * almost certainly never streamed. Genuinely short tracks (length at most a
+     * few × the threshold) are excluded so we don't loop on real short songs. */
+    private isDeadStream;
+    /** Search for an alternate upload of the current (dead) track and play it.
+     * Returns true when an alternate started; false to let the caller advance. */
+    private tryRecover;
 }
 
 /** The top-level client: owns the REST wrapper, the WebSocket event loop, the
@@ -190,14 +236,23 @@ interface ClientEvents {
     resumed: [];
     disconnect: [];
     error: [err: unknown];
-    trackStart: [player: Player | number, data: any];
-    trackEnd: [player: Player | number, data: any];
-    trackException: [player: Player | number, data: any];
-    trackStuck: [player: Player | number, data: any];
-    playerUpdate: [player: Player | number, data: any];
-    voiceClosed: [player: Player | number, data: any];
-    stats: [player: Player | number | null, data: any];
+    trackStart: [player: Player | bigint, data: any];
+    trackEnd: [player: Player | bigint, data: any];
+    trackException: [player: Player | bigint, data: any];
+    trackStuck: [player: Player | bigint, data: any];
+    playerUpdate: [player: Player | bigint, data: any];
+    voiceClosed: [player: Player | bigint, data: any];
+    stats: [player: Player | bigint | null, data: any];
     queueEnd: [player: Player];
+    /** A dead source could not be recovered — the bot should tell the user. */
+    trackStreamDead: [player: Player, data: {
+        failed: Track;
+    }];
+    /** A dead source was auto-recovered by playing an alternate upload. */
+    trackRecovered: [player: Player, data: {
+        failed: Track;
+        alternate: Track;
+    }];
 }
 interface Client {
     on<K extends keyof ClientEvents>(event: K, listener: (...args: ClientEvents[K]) => void): this;
@@ -229,9 +284,9 @@ declare class Client extends EventEmitter implements PlayerHost {
     /** Emit "error" without the Node EventEmitter footgun: an unlistened "error"
      * throws and would crash the host process, so fall back to a console warning. */
     private safeError;
-    getPlayer(guildId: number): Player;
+    getPlayer(guildId: Snowflake): Player;
     players(): Player[];
-    dropPlayer(guildId: number): void;
+    dropPlayer(guildId: bigint): void;
     loadTracks(identifier: string): Promise<LoadResult>;
     /** `ytsearch:`-prefix a bare query and return the hits (empty on miss). */
     search(query: string): Promise<Track[]>;
@@ -268,4 +323,4 @@ declare class NotConnected extends AuralisError {
 declare class LoadError extends AuralisError {
 }
 
-export { APIError, AuralisError, AuthError, type AutoplayHook, Client, type ClientEvents, type ClientOptions, EndReason, LoadError, type LoadResult, LoadType, LoopMode, NotConnected, Player, type PlayerHost, type PlayerState, REST, RateLimited, type Track, type VoiceServerUpdate, type VoiceStateUpdate, endReasonAdvances };
+export { APIError, AuralisError, AuthError, type AutoplayHook, Client, type ClientEvents, type ClientOptions, EndReason, LoadError, type LoadResult, LoadType, LoopMode, NotConnected, Player, type PlayerHost, type PlayerState, REST, RateLimited, type Snowflake, type Track, type VoiceServerUpdate, type VoiceStateUpdate, endReasonAdvances };

package/dist/index.js

@@ -27,6 +27,13 @@ var LoadError = class extends AuralisError {
 };
 
 // src/types.ts
+var BIG_TAG = "__BIG__";
+function snowflakeStringify(obj) {
+  return JSON.stringify(
+    obj,
+    (_k, v) => typeof v === "bigint" ? `${BIG_TAG}${v}${BIG_TAG}` : v
+  ).replace(new RegExp(`"${BIG_TAG}(\\d+)${BIG_TAG}"`, "g"), "$1");
+}
 var LoopMode = /* @__PURE__ */ ((LoopMode2) => {
   LoopMode2["Off"] = "off";
   LoopMode2["Track"] = "track";
@@ -90,10 +97,9 @@ function playerStateFromJson(d) {
 var Player = class {
   constructor(host, guildId) {
     this.host = host;
-    this.guildId = guildId;
+    this.guildId = BigInt(guildId);
   }
   host;
-  guildId;
   queue = [];
   history = [];
   current = null;
@@ -112,9 +118,29 @@ var Player = class {
   };
   /** Optional async hook used when the queue and loop are exhausted. */
   autoplay = null;
+  /** When a non-stream track "finishes" without ever streaming (dead source:
+   * geo/age-restricted, throttled, removed), search for and play an alternate
+   * upload instead of silently draining the queue. */
+  recoverDeadStreams = true;
+  /** A track whose furthest observed position never passed this many ms is
+   * treated as never-streamed (used by {@link recoverDeadStreams}). */
+  deadStreamThresholdMs = 1500;
+  /** Give up recovering a single dead track after this many alternate attempts. */
+  deadStreamRecoveryLimit = 2;
+  /** Auto-skip a track the node reports as `TRACK_STUCK` instead of stalling. */
+  advanceOnStuck = true;
+  /** On a remote `VOICE_CLOSED`, reset so the next voice material re-creates the
+   * player and resumes the current track (the bot must re-send its op-4 join). */
+  rejoinOnVoiceClosed = true;
+  /** The guild this player drives. Always a `bigint` so 64-bit ids stay exact. */
+  guildId;
   created = false;
   voiceServer = null;
   voiceState = null;
+  /** Furthest position seen for the current track — reset on every track start. */
+  maxPositionMs = 0;
+  /** Alternate-upload attempts spent on the current dead track. */
+  recoverAttempts = 0;
   // --- voice plumbing ---------------------------------------------------
   handleVoiceServerUpdate(data) {
     this.voiceServer = { token: data.token, endpoint: data.endpoint };
@@ -127,14 +153,35 @@ var Player = class {
     }
     this.voiceState = {
       session_id: data.session_id,
-      channel_id: Number(data.channel_id),
-      user_id: Number(data.user_id)
+      channel_id: BigInt(data.channel_id),
+      user_id: BigInt(data.user_id)
     };
     void this.maybeStart();
   }
   get connected() {
     return this.voiceServer !== null && this.voiceState !== null;
   }
+  /** Called by the client on `PLAYER_UPDATE` (and reconnect resync). Tracks the
+   * furthest position reached so a "finished but never streamed" track can be
+   * spotted, and clears the recovery counter once a track is genuinely playing. */
+  applyState(state) {
+    this.state = state;
+    if (state.positionMs > this.maxPositionMs) this.maxPositionMs = state.positionMs;
+    if (this.maxPositionMs > this.deadStreamThresholdMs) this.recoverAttempts = 0;
+  }
+  /** Discord terminated the voice session (remote `VOICE_CLOSED`). The node has
+   * dropped our player, so reset local voice/created state and requeue the
+   * current track; once the bot re-sends its op-4 join, fresh voice material
+   * re-creates the player and resumes. Bot-initiated closes don't call this. */
+  handleVoiceClosed() {
+    if (this.current !== null) {
+      this.queue.unshift(this.current);
+      this.current = null;
+    }
+    this.created = false;
+    this.voiceServer = null;
+    this.voiceState = null;
+  }
   voicePayload() {
     return { ...this.voiceServer, ...this.voiceState, guild_id: this.guildId };
   }
@@ -317,6 +364,7 @@ var Player = class {
   async playTrack(track) {
     if (!this.connected) throw new NotConnected(`guild ${this.guildId} has no voice connection`);
     this.current = track;
+    this.maxPositionMs = 0;
     if (!this.created) {
       await this.host.rest.createPlayer(this.guildId, this.voicePayload(), {
         track: track.encoded,
@@ -332,16 +380,67 @@ var Player = class {
     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. */
+  /** Called by the client's WS loop when a TRACK_END for this guild arrives.
+   * `advances` is true for FINISHED / LOAD_FAILED. Before draining the queue we
+   * check for a dead source and try to recover it with an alternate upload. */
   async onTrackEnd(advances) {
-    if (advances) await this.advance();
+    if (!advances) return;
+    if (this.recoverDeadStreams && this.loop !== "track" /* Track */ && this.isDeadStream()) {
+      if (await this.tryRecover()) return;
+    }
+    await this.advance();
+  }
+  /** Called by the client on `TRACK_STUCK`: skip the stalled track. */
+  async onTrackStuck() {
+    if (this.advanceOnStuck) await this.advance(true);
+  }
+  /** A non-stream track that "finished" without its position ever advancing
+   * almost certainly never streamed. Genuinely short tracks (length at most a
+   * few × the threshold) are excluded so we don't loop on real short songs. */
+  isDeadStream() {
+    const t = this.current;
+    if (t === null || t.isStream) return false;
+    if (this.maxPositionMs > this.deadStreamThresholdMs) return false;
+    return t.lengthMs === 0 || t.lengthMs > this.deadStreamThresholdMs * 4;
+  }
+  /** Search for an alternate upload of the current (dead) track and play it.
+   * Returns true when an alternate started; false to let the caller advance. */
+  async tryRecover() {
+    const failed = this.current;
+    if (failed === null) return false;
+    this.recoverAttempts++;
+    if (this.recoverAttempts > this.deadStreamRecoveryLimit) {
+      this.recoverAttempts = 0;
+      this.host.emit("trackStreamDead", this, { failed });
+      return false;
+    }
+    const query = [failed.title, failed.author].filter(Boolean).join(" ").trim();
+    if (query === "") return false;
+    let tracks;
+    try {
+      tracks = (await this.host.rest.loadTracks(`ytsearch:${query}`)).tracks;
+    } catch {
+      return false;
+    }
+    const alt = tracks.find((t) => t.encoded && t.encoded !== failed.encoded);
+    if (!alt) return false;
+    alt.extras = { ...alt.extras, ...failed.extras };
+    await this.playTrack(alt);
+    this.host.emit("trackRecovered", this, { failed, alternate: alt });
+    return true;
   }
 };
 
 // src/rest.ts
+var DEFAULT_TIMEOUT_MS = 8e3;
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([502, 503]);
+var BACKOFF_MS = [200, 500];
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var REST = class {
   base;
   headers;
+  /** Per-request timeout (ms). Exposed so a slow-network deployment can raise it. */
+  timeoutMs = DEFAULT_TIMEOUT_MS;
   constructor(baseUrl, token) {
     this.base = baseUrl.replace(/\/$/, "");
     this.headers = {
@@ -349,20 +448,56 @@ var REST = class {
       "Content-Type": "application/json"
     };
   }
+  async fetchWithTimeout(method, path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(`${this.base}${path}`, {
+        method,
+        headers: this.headers,
+        // snowflakeStringify keeps 64-bit voice ids (channel_id/user_id) exact —
+        // the control plane parses them as u64 bare numbers.
+        body: body === void 0 ? void 0 : snowflakeStringify(body),
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // Retry policy: GET is idempotent, so retry it on both transient 502/503 and
+  // network/timeout errors. Writes only retry on 502/503 (a network error might
+  // mean the write half-applied). 401/403/429/other 4xx are terminal — no retry.
   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);
+    const idempotent = method === "GET";
+    const maxAttempts = idempotent ? BACKOFF_MS.length + 1 : 2;
+    let lastErr;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const isLast = attempt === maxAttempts - 1;
+      try {
+        const res = await this.fetchWithTimeout(method, path, 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 (RETRYABLE_STATUS.has(res.status) && !isLast) {
+          await sleep(BACKOFF_MS[attempt]);
+          continue;
+        }
+        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();
+      } catch (err) {
+        if (err instanceof AuralisError) throw err;
+        lastErr = err;
+        if (idempotent && !isLast) {
+          await sleep(BACKOFF_MS[attempt]);
+          continue;
+        }
+        throw err;
+      }
     }
-    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();
+    throw lastErr;
   }
   // --- metadata ---------------------------------------------------------
   async loadTracks(identifier) {
@@ -480,10 +615,11 @@ var Client = class extends EventEmitter {
   }
   // --- players ----------------------------------------------------------
   getPlayer(guildId) {
-    let p = this.playersMap.get(guildId);
+    const id = BigInt(guildId);
+    let p = this.playersMap.get(id);
     if (!p) {
-      p = new Player(this, guildId);
-      this.playersMap.set(guildId, p);
+      p = new Player(this, id);
+      this.playersMap.set(id, p);
     }
     return p;
   }
@@ -546,7 +682,7 @@ var Client = class extends EventEmitter {
     await Promise.all(
       this.players().map(async (p) => {
         try {
-          p.state = await this.rest.getState(p.guildId);
+          p.applyState(await this.rest.getState(p.guildId));
         } catch {
         }
       })
@@ -596,12 +732,16 @@ var Client = class extends EventEmitter {
     if (op === "STATS") {
       this.lastStats = d;
     }
-    const guildId = d.guild_id ? Number(d.guild_id) : null;
+    const guildId = d.guild_id != null ? BigInt(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 ?? {});
+      player.applyState(playerStateFromJson(d.state ?? {}));
+    } else if (op === "TRACK_STUCK" && player) {
+      await player.onTrackStuck();
+    } else if (op === "VOICE_CLOSED" && player && d.by_remote && player.rejoinOnVoiceClosed) {
+      player.handleVoiceClosed();
     }
     const eventName = EVENT_OPS[op];
     if (eventName) this.emit(eventName, player ?? guildId, d);