yukimu 2.0.8 → 2.0.9

package/dist/Rest.js

@@ -0,0 +1,246 @@
+"use strict";
+/** Yukimu v2.0.0 — REST Client with Retry, Rate Limiting & Circuit Breaker */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Rest = void 0;
+const YukimuError_1 = require("./errors/YukimuError");
+const Constants_1 = require("./Constants");
+/**
+ * REST client for communicating with a Lavalink node's HTTP API.
+ *
+ * Improvements from v1:
+ * - Automatic retry with exponential backoff for 429/5xx errors
+ * - Rate limit tracking (respects Retry-After headers)
+ * - Request timeout with proper AbortController cleanup
+ * - Uses VERSION constant for Client-Name header
+ * - Fixed v4.2+ data normalization bug (single track vs array)
+ * - Per-path rate limit awareness
+ * - Circuit breaker: after N consecutive failures, stop sending requests temporarily
+ */
+class Rest {
+    node;
+    rateLimit = null;
+    consecutiveFailures = 0;
+    circuitOpenUntil = 0;
+    static MAX_CONSECUTIVE_FAILURES = 5;
+    static CIRCUIT_OPEN_DURATION = 30_000;
+    constructor(node) {
+        this.node = node;
+    }
+    get baseUrl() {
+        const protocol = this.node.options.secure ? "https" : "http";
+        return `${protocol}://${this.node.options.host}:${this.node.options.port}`;
+    }
+    get prefix() {
+        return this.node.version === 4 ? "/v4" : "";
+    }
+    get headers() {
+        return {
+            Authorization: this.node.options.password,
+            "User-Id": this.node.manager.options.clientId,
+            "Client-Name": Constants_1.CLIENT_NAME,
+            "Content-Type": "application/json",
+            ...(this.node.version === 3 ? { "Num-Shards": "1" } : {}),
+        };
+    }
+    // ─── Core Request ───────────────────────────────────────────────────────
+    async request(method, path, body, retries = Constants_1.DEFAULTS.REST_MAX_RETRIES) {
+        // Circuit breaker check
+        if (Date.now() < this.circuitOpenUntil) {
+            throw new YukimuError_1.RestError(`Circuit breaker open for node "${this.node.options.name}" — too many consecutive failures`, 503, path);
+        }
+        // Rate limit check
+        if (this.rateLimit && this.rateLimit.remaining <= 0 && Date.now() < this.rateLimit.resetAt) {
+            const waitMs = this.rateLimit.resetAt - Date.now();
+            this.node.manager.logger.debug(`Rate limited on ${path}, waiting ${waitMs}ms`);
+            await this.sleep(waitMs);
+        }
+        const url = `${this.baseUrl}${this.prefix}${path}`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), Constants_1.DEFAULTS.REST_TIMEOUT);
+        try {
+            const res = await fetch(url, {
+                method,
+                headers: this.headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            // Track rate limit headers
+            this.updateRateLimit(res);
+            // Handle rate limiting with retry
+            if (res.status === 429) {
+                const retryAfter = this.parseRetryAfter(res);
+                if (retries > 0) {
+                    this.node.manager.logger.warn(`Rate limited on ${method} ${path}, retrying in ${retryAfter}ms`);
+                    await this.sleep(retryAfter);
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+                    return this.request(method, path, body, (retries - 1));
+                }
+                throw new YukimuError_1.RestError(`Rate limited on ${method} ${path}`, 429, path, retryAfter);
+            }
+            // Handle server errors with retry
+            if (res.status >= 500 && retries > 0) {
+                const delay = this.getRetryDelay(Constants_1.DEFAULTS.REST_MAX_RETRIES - retries);
+                this.node.manager.logger.warn(`Server error ${res.status} on ${method} ${path}, retrying in ${delay}ms`);
+                await this.sleep(delay);
+                return this.request(method, path, body, (retries - 1));
+            }
+            if (!res.ok) {
+                const text = await res.text().catch(() => "Unknown error");
+                throw new YukimuError_1.RestError(`REST ${res.status} on ${method} ${path}: ${text}`, res.status, path);
+            }
+            // Reset circuit breaker on success
+            this.consecutiveFailures = 0;
+            if (res.status === 204)
+                return undefined;
+            const text = await res.text();
+            if (!text)
+                return null;
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                return null;
+            }
+            // Normalize Lavalink v4.2+ response — uses "data" instead of "tracks"
+            if (parsed && "data" in parsed && !("tracks" in parsed)) {
+                const data = parsed["data"];
+                if (Array.isArray(data)) {
+                    parsed["tracks"] = data;
+                }
+                else if (data && typeof data === "object") {
+                    // Single track response — wrap in array
+                    parsed["tracks"] = [data];
+                }
+            }
+            return parsed;
+        }
+        catch (err) {
+            clearTimeout(timeout);
+            // Increment circuit breaker
+            this.consecutiveFailures++;
+            if (this.consecutiveFailures >= Rest.MAX_CONSECUTIVE_FAILURES) {
+                this.circuitOpenUntil = Date.now() + Rest.CIRCUIT_OPEN_DURATION;
+                this.node.manager.logger.error(`Circuit breaker opened for node "${this.node.options.name}" after ${this.consecutiveFailures} failures`);
+            }
+            if (err instanceof YukimuError_1.RestError)
+                throw err;
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new YukimuError_1.RestError(`REST timeout on ${method} ${path}`, 408, path);
+            }
+            throw err;
+        }
+    }
+    // ─── API Methods ────────────────────────────────────────────────────────
+    async loadTracks(identifier) {
+        const raw = await this.request("GET", `/loadtracks?identifier=${encodeURIComponent(identifier)}`);
+        if (!raw)
+            return { loadType: "empty", tracks: [] };
+        return this.node.version === 3 ? this.normalizeV3(raw) : this.normalizeV4(raw);
+    }
+    async decodeTrack(encoded) {
+        return this.request("GET", `/decodetrack?encodedTrack=${encodeURIComponent(encoded)}`);
+    }
+    async decodeTracks(encoded) {
+        return this.request("POST", `/decodetracks`, encoded);
+    }
+    async getInfo() {
+        return this.request("GET", "/info");
+    }
+    async getStats() {
+        return this.request("GET", "/stats");
+    }
+    async updatePlayer(guildId, body, noReplace = false) {
+        const path = this.node.version === 4
+            ? `/sessions/${this.node.sessionId}/players/${guildId}?noReplace=${noReplace}`
+            : `/players/${guildId}`;
+        return this.request("PATCH", path, body);
+    }
+    async destroyPlayer(guildId) {
+        const path = this.node.version === 4
+            ? `/sessions/${this.node.sessionId}/players/${guildId}`
+            : `/players/${guildId}`;
+        await this.request("DELETE", path).catch(() => { });
+    }
+    async updateSession(body) {
+        if (this.node.version !== 4 || !this.node.sessionId)
+            return;
+        return this.request("PATCH", `/sessions/${this.node.sessionId}`, body);
+    }
+    // ─── Normalization ──────────────────────────────────────────────────────
+    normalizeV4(raw) {
+        const result = raw;
+        if (!result.tracks)
+            result.tracks = [];
+        return result;
+    }
+    normalizeV3(raw) {
+        const loadType = String(raw["loadType"] ?? "").toLowerCase();
+        const rawTracks = raw["tracks"];
+        const tracks = Array.isArray(rawTracks) ? rawTracks : [];
+        const norm = (items) => items.map((t) => {
+            const track = t;
+            return {
+                encoded: (track["track"] ?? track["encoded"]),
+                info: track["info"],
+                pluginInfo: (track["pluginInfo"] ?? {}),
+            };
+        });
+        switch (loadType) {
+            case "track_loaded":
+                return { loadType: "track", tracks: norm(tracks) };
+            case "playlist_loaded":
+                return {
+                    loadType: "playlist",
+                    tracks: norm(tracks),
+                    playlistInfo: raw["playlistInfo"],
+                };
+            case "search_result":
+                return { loadType: "search", tracks: norm(tracks) };
+            case "no_matches":
+                return { loadType: "empty", tracks: [] };
+            case "load_failed":
+                return {
+                    loadType: "error",
+                    tracks: [],
+                    exception: raw["exception"],
+                };
+            default:
+                return { loadType: "empty", tracks: [] };
+        }
+    }
+    // ─── Helpers ────────────────────────────────────────────────────────────
+    updateRateLimit(res) {
+        const remaining = res.headers.get("x-ratelimit-remaining");
+        const reset = res.headers.get("x-ratelimit-reset");
+        if (remaining !== null && reset !== null) {
+            this.rateLimit = {
+                remaining: parseInt(remaining, 10),
+                resetAt: parseInt(reset, 10) * 1000,
+            };
+        }
+    }
+    parseRetryAfter(res) {
+        const retryAfter = res.headers.get("retry-after");
+        if (retryAfter) {
+            const seconds = parseFloat(retryAfter);
+            if (!isNaN(seconds))
+                return Math.ceil(seconds * 1000);
+        }
+        return 5000; // Default 5s
+    }
+    getRetryDelay(attempt) {
+        const base = Constants_1.DEFAULTS.REST_RETRY_BASE_DELAY;
+        const max = Constants_1.DEFAULTS.REST_RETRY_MAX_DELAY;
+        const delay = Math.min(base * Math.pow(2, attempt), max);
+        // Add jitter ±25%
+        const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+        return Math.round(delay + jitter);
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.Rest = Rest;
+//# sourceMappingURL=Rest.js.map

package/dist/Rest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Rest.js","sourceRoot":"","sources":["../src/Rest.ts"],"names":[],"mappings":";AAAA,8EAA8E;;;AAE9E,sDAA4D;AAC5D,2CAAoD;AAWpD;;;;;;;;;;;GAWG;AACH,MAAa,IAAI;IACE,IAAI,CAAO;IACpB,SAAS,GAA0B,IAAI,CAAC;IACxC,mBAAmB,GAAG,CAAC,CAAC;IACxB,gBAAgB,GAAG,CAAC,CAAC;IAErB,MAAM,CAAU,wBAAwB,GAAG,CAAC,CAAC;IAC7C,MAAM,CAAU,qBAAqB,GAAG,MAAM,CAAC;IAEvD,YAAY,IAAU;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,IAAI,OAAO;QACT,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;QAC7D,OAAO,GAAG,QAAQ,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAC7E,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C,CAAC;IAED,IAAI,OAAO;QACT,OAAO;YACL,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ;YACzC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ;YAC7C,aAAa,EAAE,uBAAW;YAC1B,cAAc,EAAE,kBAAkB;YAClC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1D,CAAC;IACJ,CAAC;IAED,2EAA2E;IAEpE,KAAK,CAAC,OAAO,CAClB,MAAc,EACd,IAAY,EACZ,IAAc,EACd,UAAkB,oBAAQ,CAAC,gBAAgB;QAE3C,wBAAwB;QACxB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACvC,MAAM,IAAI,uBAAS,CACjB,kCAAkC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,mCAAmC,EAC3F,GAAG,EACH,IAAI,CACL,CAAC;QACJ,CAAC;QAED,mBAAmB;QACnB,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,SAAS,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;YAC3F,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACnD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,IAAI,aAAa,MAAM,IAAI,CAAC,CAAC;YAC/E,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;QAED,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QACnD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,oBAAQ,CAAC,YAAY,CAAC,CAAC;QAE5E,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,MAAM;gBACN,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;gBAC3D,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,YAAY,CAAC,OAAO,CAAC,CAAC;YAEtB,2BAA2B;YAC3B,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;YAE1B,kCAAkC;YAClC,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBACvB,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;gBAC7C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;oBAChB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,MAAM,IAAI,IAAI,iBAAiB,UAAU,IAAI,CAAC,CAAC;oBAChG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;oBAC7B,+DAA+D;oBAC/D,OAAO,IAAI,CAAC,OAAO,CAAI,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,OAAO,GAAG,CAAC,CAAW,CAAC,CAAC;gBACtE,CAAC;gBACD,MAAM,IAAI,uBAAS,CAAC,mBAAmB,MAAM,IAAI,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;YAClF,CAAC;YAED,kCAAkC;YAClC,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBACrC,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,oBAAQ,CAAC,gBAAgB,GAAG,OAAO,CAAC,CAAC;gBACtE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,GAAG,CAAC,MAAM,OAAO,MAAM,IAAI,IAAI,iBAAiB,KAAK,IAAI,CAAC,CAAC;gBACzG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBACxB,OAAO,IAAI,CAAC,OAAO,CAAI,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,OAAO,GAAG,CAAC,CAAW,CAAC,CAAC;YACtE,CAAC;YAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC;gBAC3D,MAAM,IAAI,uBAAS,CAAC,QAAQ,GAAG,CAAC,MAAM,OAAO,MAAM,IAAI,IAAI,KAAK,IAAI,EAAE,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC5F,CAAC;YAED,mCAAmC;YACnC,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC;YAE7B,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,SAAc,CAAC;YAE9C,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;YAC9B,IAAI,CAAC,IAAI;gBAAE,OAAO,IAAS,CAAC;YAE5B,IAAI,MAA+B,CAAC;YACpC,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAS,CAAC;YACnB,CAAC;YAED,sEAAsE;YACtE,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC,EAAE,CAAC;gBACxD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;gBAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;oBACxB,MAAM,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;gBAC1B,CAAC;qBAAM,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC5C,wCAAwC;oBACxC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;YAED,OAAO,MAAW,CAAC;QACrB,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,YAAY,CAAC,OAAO,CAAC,CAAC;YAEtB,4BAA4B;YAC5B,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC3B,IAAI,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,wBAAwB,EAAE,CAAC;gBAC9D,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,qBAAqB,CAAC;gBAChE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAC5B,oCAAoC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,WAAW,IAAI,CAAC,mBAAmB,WAAW,CACzG,CAAC;YACJ,CAAC;YAED,IAAI,GAAG,YAAY,uBAAS;gBAAE,MAAM,GAAG,CAAC;YACxC,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBACtD,MAAM,IAAI,uBAAS,CAAC,mBAAmB,MAAM,IAAI,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;YACtE,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,2EAA2E;IAEpE,KAAK,CAAC,UAAU,CAAC,UAAkB;QACxC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAC5B,KAAK,EACL,0BAA0B,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAC3D,CAAC;QAEF,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACjF,CAAC;IAEM,KAAK,CAAC,WAAW,CAAC,OAAe;QACtC,OAAO,IAAI,CAAC,OAAO,CAAQ,KAAK,EAAE,6BAA6B,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAChG,CAAC;IAEM,KAAK,CAAC,YAAY,CAAC,OAAiB;QACzC,OAAO,IAAI,CAAC,OAAO,CAAU,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IAEM,KAAK,CAAC,OAAO;QAClB,OAAO,IAAI,CAAC,OAAO,CAAW,KAAK,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAEM,KAAK,CAAC,QAAQ;QACnB,OAAO,IAAI,CAAC,OAAO,CAAY,KAAK,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IAEM,KAAK,CAAC,YAAY,CAAC,OAAe,EAAE,IAAa,EAAE,SAAS,GAAG,KAAK;QACzE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC;YAClC,CAAC,CAAC,aAAa,IAAI,CAAC,IAAI,CAAC,SAAS,YAAY,OAAO,cAAc,SAAS,EAAE;YAC9E,CAAC,CAAC,YAAY,OAAO,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;IAEM,KAAK,CAAC,aAAa,CAAC,OAAe;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC;YAClC,CAAC,CAAC,aAAa,IAAI,CAAC,IAAI,CAAC,SAAS,YAAY,OAAO,EAAE;YACvD,CAAC,CAAC,YAAY,OAAO,EAAE,CAAC;QAC1B,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACrD,CAAC;IAEM,KAAK,CAAC,aAAa,CAAC,IAA8C;QACvE,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,aAAa,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,CAAC;IACzE,CAAC;IAED,2EAA2E;IAEnE,WAAW,CAAC,GAA4B;QAC9C,MAAM,MAAM,GAAG,GAA8B,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC;QACvC,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,WAAW,CAAC,GAA4B;QAC9C,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC7D,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QAEzD,MAAM,IAAI,GAAG,CAAC,KAAgB,EAAW,EAAE,CACzC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAU,EAAE,EAAE;YACvB,MAAM,KAAK,GAAG,CAA4B,CAAC;YAC3C,OAAO;gBACL,OAAO,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,CAAW;gBACvD,IAAI,EAAE,KAAK,CAAC,MAAM,CAAkB;gBACpC,UAAU,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,CAA4B;aACnE,CAAC;QACJ,CAAC,CAAC,CAAC;QAEL,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,cAAc;gBACjB,OAAO,EAAE,QAAQ,EAAE,OAAmB,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACjE,KAAK,iBAAiB;gBACpB,OAAO;oBACL,QAAQ,EAAE,UAAsB;oBAChC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;oBACpB,YAAY,EAAE,GAAG,CAAC,cAAc,CAAiC;iBAClE,CAAC;YACJ,KAAK,eAAe;gBAClB,OAAO,EAAE,QAAQ,EAAE,QAAoB,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAClE,KAAK,YAAY;gBACf,OAAO,EAAE,QAAQ,EAAE,OAAmB,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;YACvD,KAAK,aAAa;gBAChB,OAAO;oBACL,QAAQ,EAAE,OAAmB;oBAC7B,MAAM,EAAE,EAAE;oBACV,SAAS,EAAE,GAAG,CAAC,WAAW,CAA8B;iBACzD,CAAC;YACJ;gBACE,OAAO,EAAE,QAAQ,EAAE,OAAmB,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QACzD,CAAC;IACH,CAAC;IAED,2EAA2E;IAEnE,eAAe,CAAC,GAAa;QACnC,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;QAC3D,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;QACnD,IAAI,SAAS,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACzC,IAAI,CAAC,SAAS,GAAG;gBACf,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;gBAClC,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI;aACpC,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,GAAa;QACnC,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAClD,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;YACvC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;gBAAE,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,IAAI,CAAC,CAAC,aAAa;IAC5B,CAAC;IAEO,aAAa,CAAC,OAAe;QACnC,MAAM,IAAI,GAAG,oBAAQ,CAAC,qBAAqB,CAAC;QAC5C,MAAM,GAAG,GAAG,oBAAQ,CAAC,oBAAoB,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC;QACzD,kBAAkB;QAClB,MAAM,MAAM,GAAG,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;IACpC,CAAC;IAEO,KAAK,CAAC,EAAU;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;;AAhRH,oBAiRC"}

package/dist/TrackCache.d.ts

@@ -0,0 +1,41 @@
+/** Yukimu v2.0.0 — LRU Track Cache with Stats */
+import type { Track, SearchResult } from "./types";
+/**
+ * A TTL-based LRU cache for tracks and search results.
+ *
+ * Improvements from v1:
+ * - LRU eviction when cache exceeds maxSize
+ * - Lazy sweep (only sweeps if cache is non-empty)
+ * - Cache hit/miss stats for monitoring
+ * - Search result caching (not just individual tracks)
+ * - Configurable TTL and max size
+ */
+export declare class TrackCache {
+    private tracks;
+    private searches;
+    private readonly ttl;
+    private readonly maxSize;
+    private sweepInterval;
+    private _hits;
+    private _misses;
+    constructor(ttlMs?: number, maxSize?: number);
+    set(encoded: string, track: Track): void;
+    get(encoded: string): Track | null;
+    has(encoded: string): boolean;
+    deleteTrack(encoded: string): void;
+    setSearch(identifier: string, result: SearchResult): void;
+    getSearch(identifier: string): SearchResult | null;
+    private startSweep;
+    private sweep;
+    get stats(): {
+        tracks: number;
+        searches: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    clear(): void;
+    destroy(): void;
+    get size(): number;
+}
+//# sourceMappingURL=TrackCache.d.ts.map

package/dist/TrackCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrackCache.d.ts","sourceRoot":"","sources":["../src/TrackCache.ts"],"names":[],"mappings":"AAAA,iDAAiD;AAEjD,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAQnD;;;;;;;;;GASG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAA6C;IAC3D,OAAO,CAAC,QAAQ,CAAoD;IACpE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,aAAa,CAA+C;IACpE,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,OAAO,CAAK;gBAER,KAAK,GAAE,MAA2B,EAAE,OAAO,GAAE,MAAgC;IAQlF,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAWxC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAkBlC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAMlC,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAazD,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAezD,OAAO,CAAC,UAAU;IAclB,OAAO,CAAC,KAAK;IAYb,IAAW,KAAK;;;;;;MAUf;IAIM,KAAK,IAAI,IAAI;IAKb,OAAO,IAAI,IAAI;IAUtB,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/TrackCache.js

@@ -0,0 +1,144 @@
+"use strict";
+/** Yukimu v2.0.0 — LRU Track Cache with Stats */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrackCache = void 0;
+const Constants_1 = require("./Constants");
+/**
+ * A TTL-based LRU cache for tracks and search results.
+ *
+ * Improvements from v1:
+ * - LRU eviction when cache exceeds maxSize
+ * - Lazy sweep (only sweeps if cache is non-empty)
+ * - Cache hit/miss stats for monitoring
+ * - Search result caching (not just individual tracks)
+ * - Configurable TTL and max size
+ */
+class TrackCache {
+    tracks = new Map();
+    searches = new Map();
+    ttl;
+    maxSize;
+    sweepInterval = null;
+    _hits = 0;
+    _misses = 0;
+    constructor(ttlMs = Constants_1.DEFAULTS.CACHE_TTL, maxSize = Constants_1.DEFAULTS.MAX_CACHE_SIZE) {
+        this.ttl = ttlMs;
+        this.maxSize = maxSize;
+        this.startSweep();
+    }
+    // ─── Track Cache ────────────────────────────────────────────────────────
+    set(encoded, track) {
+        // LRU eviction: delete oldest entries if at capacity
+        if (this.tracks.size >= this.maxSize && !this.tracks.has(encoded)) {
+            const firstKey = this.tracks.keys().next().value;
+            if (firstKey !== undefined) {
+                this.tracks.delete(firstKey);
+            }
+        }
+        this.tracks.set(encoded, { value: track, expiresAt: Date.now() + this.ttl });
+    }
+    get(encoded) {
+        const entry = this.tracks.get(encoded);
+        if (!entry) {
+            this._misses++;
+            return null;
+        }
+        if (Date.now() > entry.expiresAt) {
+            this.tracks.delete(encoded);
+            this._misses++;
+            return null;
+        }
+        this._hits++;
+        // Move to end for LRU (delete + re-set)
+        this.tracks.delete(encoded);
+        this.tracks.set(encoded, entry);
+        return entry.value;
+    }
+    has(encoded) {
+        return this.get(encoded) !== null;
+    }
+    deleteTrack(encoded) {
+        this.tracks.delete(encoded);
+    }
+    // ─── Search Result Cache ────────────────────────────────────────────────
+    setSearch(identifier, result) {
+        // Only cache successful results
+        if (result.loadType === "error")
+            return;
+        if (this.searches.size >= this.maxSize && !this.searches.has(identifier)) {
+            const firstKey = this.searches.keys().next().value;
+            if (firstKey !== undefined) {
+                this.searches.delete(firstKey);
+            }
+        }
+        this.searches.set(identifier, { value: result, expiresAt: Date.now() + this.ttl });
+    }
+    getSearch(identifier) {
+        const entry = this.searches.get(identifier);
+        if (!entry)
+            return null;
+        if (Date.now() > entry.expiresAt) {
+            this.searches.delete(identifier);
+            return null;
+        }
+        // LRU
+        this.searches.delete(identifier);
+        this.searches.set(identifier, entry);
+        return entry.value;
+    }
+    // ─── Sweep ──────────────────────────────────────────────────────────────
+    startSweep() {
+        this.sweepInterval = setInterval(() => {
+            // Only sweep if there are entries (lazy sweep)
+            if (this.tracks.size > 0 || this.searches.size > 0) {
+                this.sweep();
+            }
+        }, Constants_1.DEFAULTS.CACHE_SWEEP_INTERVAL);
+        // Prevent the interval from keeping the process alive
+        if (this.sweepInterval.unref) {
+            this.sweepInterval.unref();
+        }
+    }
+    sweep() {
+        const now = Date.now();
+        for (const [key, entry] of this.tracks) {
+            if (now > entry.expiresAt)
+                this.tracks.delete(key);
+        }
+        for (const [key, entry] of this.searches) {
+            if (now > entry.expiresAt)
+                this.searches.delete(key);
+        }
+    }
+    // ─── Stats ──────────────────────────────────────────────────────────────
+    get stats() {
+        return {
+            tracks: this.tracks.size,
+            searches: this.searches.size,
+            hits: this._hits,
+            misses: this._misses,
+            hitRate: this._hits + this._misses > 0
+                ? Math.round((this._hits / (this._hits + this._misses)) * 100)
+                : 0,
+        };
+    }
+    // ─── Lifecycle ──────────────────────────────────────────────────────────
+    clear() {
+        this.tracks.clear();
+        this.searches.clear();
+    }
+    destroy() {
+        if (this.sweepInterval) {
+            clearInterval(this.sweepInterval);
+            this.sweepInterval = null;
+        }
+        this.clear();
+        this._hits = 0;
+        this._misses = 0;
+    }
+    get size() {
+        return this.tracks.size;
+    }
+}
+exports.TrackCache = TrackCache;
+//# sourceMappingURL=TrackCache.js.map

package/dist/TrackCache.js.map

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

package/dist/WsQueue.d.ts

@@ -0,0 +1,41 @@
+/** Yukimu v2.0.0 — WebSocket Message Queue with Timeouts & Priority */
+import WebSocket from "ws";
+/**
+ * Manages a WebSocket message queue that buffers messages when the socket
+ * is not open and flushes them once it becomes available.
+ *
+ * Fixes from v1:
+ * - Messages are rejected after a configurable timeout (prevents hanging promises)
+ * - Max queue size prevents unbounded memory growth
+ * - Priority messages (voice updates) are sent first
+ * - No duplicate "open" listener — flush is called externally
+ */
+export declare class WsQueue {
+    private queue;
+    private ws;
+    private readonly sendTimeout;
+    private readonly maxQueueSize;
+    constructor(sendTimeout?: 30000, maxQueueSize?: 100);
+    /**
+     * Set the underlying WebSocket.
+     * Unlike v1, does NOT add an "open" listener to avoid race conditions.
+     * The caller (Node) is responsible for calling flush() at the right time.
+     */
+    setSocket(ws: WebSocket | null): void;
+    /**
+     * Send data through the WebSocket, or queue it if not ready.
+     * @param data - The payload to send (will be JSON-serialized)
+     * @param priority - If true, message is prepended to the queue (used for voice updates)
+     */
+    send(data: Record<string, unknown>, priority?: boolean): Promise<void>;
+    /**
+     * Flush all queued messages. Called by Node after WebSocket is confirmed open.
+     */
+    flush(): void;
+    /**
+     * Clear the queue and reject all pending messages.
+     */
+    clear(): void;
+    get size(): number;
+}
+//# sourceMappingURL=WsQueue.d.ts.map

package/dist/WsQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WsQueue.d.ts","sourceRoot":"","sources":["../src/WsQueue.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAEvE,OAAO,SAAS,MAAM,IAAI,CAAC;AAW3B;;;;;;;;;GASG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,WAAW,QAA2B,EAAE,YAAY,MAAwB;IAKxF;;;;OAIG;IACI,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI;IAI5C;;;;OAIG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC3E;;OAEG;IACI,KAAK,IAAI,IAAI;IAsBpB;;OAEG;IACI,KAAK,IAAI,IAAI;IAQpB,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/WsQueue.js

@@ -0,0 +1,116 @@
+"use strict";
+/** Yukimu v2.0.0 — WebSocket Message Queue with Timeouts & Priority */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WsQueue = void 0;
+const ws_1 = __importDefault(require("ws"));
+const Constants_1 = require("./Constants");
+/**
+ * Manages a WebSocket message queue that buffers messages when the socket
+ * is not open and flushes them once it becomes available.
+ *
+ * Fixes from v1:
+ * - Messages are rejected after a configurable timeout (prevents hanging promises)
+ * - Max queue size prevents unbounded memory growth
+ * - Priority messages (voice updates) are sent first
+ * - No duplicate "open" listener — flush is called externally
+ */
+class WsQueue {
+    queue = [];
+    ws = null;
+    sendTimeout;
+    maxQueueSize;
+    constructor(sendTimeout = Constants_1.DEFAULTS.WS_SEND_TIMEOUT, maxQueueSize = Constants_1.DEFAULTS.WS_MAX_QUEUE) {
+        this.sendTimeout = sendTimeout;
+        this.maxQueueSize = maxQueueSize;
+    }
+    /**
+     * Set the underlying WebSocket.
+     * Unlike v1, does NOT add an "open" listener to avoid race conditions.
+     * The caller (Node) is responsible for calling flush() at the right time.
+     */
+    setSocket(ws) {
+        this.ws = ws;
+    }
+    /**
+     * Send data through the WebSocket, or queue it if not ready.
+     * @param data - The payload to send (will be JSON-serialized)
+     * @param priority - If true, message is prepended to the queue (used for voice updates)
+     */
+    send(data, priority = false) {
+        return new Promise((resolve, reject) => {
+            const serialized = JSON.stringify(data);
+            // If socket is open, send immediately
+            if (this.ws?.readyState === ws_1.default.OPEN) {
+                this.ws.send(serialized, (err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+                return;
+            }
+            // Enforce max queue size
+            if (this.queue.length >= this.maxQueueSize) {
+                reject(new Error(`WsQueue full (${this.maxQueueSize} messages)`));
+                return;
+            }
+            // Set a timeout so the promise doesn't hang forever
+            const timeout = setTimeout(() => {
+                const idx = this.queue.findIndex((m) => m.timeout === timeout);
+                if (idx !== -1) {
+                    this.queue.splice(idx, 1);
+                }
+                reject(new Error(`WsQueue send timeout after ${this.sendTimeout}ms`));
+            }, this.sendTimeout);
+            const msg = { data: serialized, resolve, reject, timeout, priority };
+            // Priority messages go to the front of the queue
+            if (priority) {
+                this.queue.unshift(msg);
+            }
+            else {
+                this.queue.push(msg);
+            }
+        });
+    }
+    /**
+     * Flush all queued messages. Called by Node after WebSocket is confirmed open.
+     */
+    flush() {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN)
+            return;
+        const toSend = [...this.queue];
+        this.queue = [];
+        for (const msg of toSend) {
+            clearTimeout(msg.timeout);
+            if (this.ws.readyState !== ws_1.default.OPEN) {
+                // Socket closed mid-flush — re-queue remaining
+                this.queue.unshift(msg);
+                return;
+            }
+            this.ws.send(msg.data, (err) => {
+                if (err)
+                    msg.reject(err);
+                else
+                    msg.resolve();
+            });
+        }
+    }
+    /**
+     * Clear the queue and reject all pending messages.
+     */
+    clear() {
+        for (const msg of this.queue) {
+            clearTimeout(msg.timeout);
+            msg.reject(new Error("WsQueue cleared"));
+        }
+        this.queue = [];
+    }
+    get size() {
+        return this.queue.length;
+    }
+}
+exports.WsQueue = WsQueue;
+//# sourceMappingURL=WsQueue.js.map

package/dist/WsQueue.js.map

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