gerdur-core 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2.4.0 - 2026-08-31
+
+Phase 3.3 — deterministic retries and typed errors.
+
+### Fixed
+
+- **The gateway retry loop had no cap** on `error.code === 4`,
+  `NEED_API_AUTH_REQUIRED`, or `GATEWAY_ERROR` — a failing endpoint could spin
+  forever. `requestWithRetry` is now a bounded loop: per-class attempt caps
+  (`code 4` ×6, re-auth ×3, token refresh ×15), full-jittered exponential
+  backoff, and a 30 s wall-clock deadline. On exhaustion it throws.
+
+### Added
+
+- **`DeezerError`** (`extends Error`) — thrown for gateway / media-API failures
+  instead of `new Error(Object.entries(error).join(', '))`. Carries `code`,
+  `keys`, `retryable`, and the raw `payload`. `message` stays human-readable.
+- **`RETRY_POLICY`** — the exported, inspectable retry configuration.
+
+### Changed
+
+- Gateway helpers (`request`, `requestLight`, `requestGet`, `requestPublicApi`)
+  and `resolveDownloadUrls` now throw `DeezerError`. `message` text changed shape
+  (`"KEY: value"` rather than `"KEY,value"`); read `err.code` / `err.keys`
+  instead of matching the string.
+
 ## 2.3.0 - 2026-08-31
 
 Phase 2.1 — all the formats, and previews. Additive; the `1 / 3 / 9` path is

package/README.md

@@ -82,7 +82,20 @@ if (model.lyricsSynced) fs.writeFileSync(track.SNG_TITLE + '.lrc', model.lyricsS
 
 ## Methods
 
-All method returns `Object` or throws `Error`. Make sure to catch error on your side.
+Every method returns an `Object` or throws. Gateway / media-API failures throw a
+**`DeezerError`** (`extends Error`) with:
+
+| Field | |
+| :--- | :--- |
+| `code` | Deezer's numeric error code, when it sent one (e.g. `4`, `800`) |
+| `keys` | the gateway error keys, e.g. `['VALID_TOKEN_REQUIRED']`, `['DATA_ERROR']` |
+| `retryable` | whether a retry could plausibly succeed |
+| `payload` | the raw error object |
+
+Retries are bounded — `RETRY_POLICY` (exported) sets per-class attempt caps and a
+30 s wall-clock deadline, so a persistently failing endpoint surfaces a
+`DeezerError` instead of spinning. `GeoBlocked`, `WrongLicense` and
+`ExpiredTrackToken` are still thrown as their own types from the download path.
 
 ### `.initDeezerApi(arl_cookie);`
 

package/dist/api/request.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestPublicApi = exports.requestGet = exports.requestLight = exports.request = void 0;
 const request_1 = __importDefault(require("../lib/request"));
+const errors_1 = require("../lib/errors");
 const cache_1 = __importDefault(require("./cache"));
 /**
  * In-flight request coalescing (single-flight).
@@ -47,11 +48,11 @@ const request = async (body, method) => {
     const cacheKey = method + ':' + Object.entries(body).join(':');
     return coalesce(cacheKey, async () => {
         const { data: { error, results }, } = await request_1.default.post('/gateway.php', body, { params: { method } });
-        if (Object.keys(results).length > 0) {
+        if (results && Object.keys(results).length > 0) {
             cache_1.default.set(cacheKey, results);
             return results;
         }
-        throw new Error(Object.entries(error).join(', '));
+        throw new errors_1.DeezerError(error);
     });
 };
 exports.request = request;
@@ -66,11 +67,11 @@ const requestLight = async (body, method) => {
         const { data: { error, results }, } = await request_1.default.post('https://www.deezer.com/ajax/gw-light.php', body, {
             params: { method, api_version: '1.0' },
         });
-        if (Object.keys(results).length > 0) {
+        if (results && Object.keys(results).length > 0) {
             cache_1.default.set(cacheKey, results);
             return results;
         }
-        throw new Error(Object.entries(error).join(', '));
+        throw new errors_1.DeezerError(error);
     });
 };
 exports.requestLight = requestLight;
@@ -83,11 +84,11 @@ const requestGet = async (method, params = {}, key = 'get_request') => {
     const cacheKey = method + key;
     return coalesce(cacheKey, async () => {
         const { data: { error, results }, } = await request_1.default.get('/gateway.php', { params: { method, ...params } });
-        if (Object.keys(results).length > 0) {
+        if (results && Object.keys(results).length > 0) {
             cache_1.default.set(cacheKey, results);
             return results;
         }
-        throw new Error(Object.entries(error).join(', '));
+        throw new errors_1.DeezerError(error);
     });
 };
 exports.requestGet = requestGet;
@@ -99,8 +100,7 @@ const requestPublicApi = async (slug) => {
     return coalesce(slug, async () => {
         const { data } = await request_1.default.get('https://api.deezer.com' + slug);
         if (data.error) {
-            const errorMessage = Object.entries(data.error).join(', ');
-            throw new Error(errorMessage);
+            throw new errors_1.DeezerError(data.error);
         }
         cache_1.default.set(slug, data);
         return data;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export { initDeezerApi } from './lib/request';
+export { initDeezerApi, RETRY_POLICY } from './lib/request';
+export { DeezerError } from './lib/errors';
+export type { DeezerErrorPayload } from './lib/errors';
 export * from './api';
 export * from './converter';
 export * from './lib/decrypt';

package/dist/index.js

@@ -14,9 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getText = exports.getJson = exports.getBuffer = exports.httpsAgent = exports.httpAgent = exports.initDeezerApi = void 0;
+exports.getText = exports.getJson = exports.getBuffer = exports.httpsAgent = exports.httpAgent = exports.DeezerError = exports.RETRY_POLICY = exports.initDeezerApi = void 0;
 var request_1 = require("./lib/request");
 Object.defineProperty(exports, "initDeezerApi", { enumerable: true, get: function () { return request_1.initDeezerApi; } });
+Object.defineProperty(exports, "RETRY_POLICY", { enumerable: true, get: function () { return request_1.RETRY_POLICY; } });
+var errors_1 = require("./lib/errors");
+Object.defineProperty(exports, "DeezerError", { enumerable: true, get: function () { return errors_1.DeezerError; } });
 __exportStar(require("./api"), exports);
 __exportStar(require("./converter"), exports);
 __exportStar(require("./lib/decrypt"), exports);

package/dist/lib/errors.d.ts

@@ -0,0 +1,27 @@
+/** The raw `error` object a Deezer gateway response carries. */
+export type DeezerErrorPayload = Record<string, unknown>;
+/**
+ * A structured error from the Deezer gateway or media API — replaces the old
+ * `new Error(Object.entries(error).join(', '))`. Carries the numeric `code`, the
+ * gateway error `keys`, a `retryable` hint, and the raw `payload`.
+ *
+ * The `message` is still human-readable (`"VALID_TOKEN_REQUIRED: …"`), so code
+ * that only reads `err.message` keeps working — but prefer `err.code` /
+ * `err.keys` / `err.retryable`.
+ */
+export declare class DeezerError extends Error {
+    /** `error.code` when Deezer sent a numeric one */
+    readonly code?: number;
+    /** the gateway error keys, e.g. `['VALID_TOKEN_REQUIRED']`, `['DATA_ERROR']` */
+    readonly keys: string[];
+    /** whether a retry could plausibly succeed */
+    readonly retryable: boolean;
+    /** the raw error payload */
+    readonly payload: DeezerErrorPayload;
+    constructor(payload: DeezerErrorPayload | null | undefined, opts?: {
+        retryable?: boolean;
+        message?: string;
+    });
+    /** Whether a `code` / key set is worth retrying. */
+    static retryable(code: number | undefined, keys: string[]): boolean;
+}

package/dist/lib/errors.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeezerError = void 0;
+/** Gateway error keys where retrying (after a token refresh / re-auth) can help. */
+const RETRYABLE_KEYS = new Set(['NEED_API_AUTH_REQUIRED', 'GATEWAY_ERROR', 'VALID_TOKEN_REQUIRED']);
+/**
+ * A structured error from the Deezer gateway or media API — replaces the old
+ * `new Error(Object.entries(error).join(', '))`. Carries the numeric `code`, the
+ * gateway error `keys`, a `retryable` hint, and the raw `payload`.
+ *
+ * The `message` is still human-readable (`"VALID_TOKEN_REQUIRED: …"`), so code
+ * that only reads `err.message` keeps working — but prefer `err.code` /
+ * `err.keys` / `err.retryable`.
+ */
+class DeezerError extends Error {
+    constructor(payload, opts = {}) {
+        var _a, _b;
+        const p = payload && typeof payload === 'object' ? payload : {};
+        const keys = Object.keys(p);
+        const rawCode = p.code;
+        const code = typeof rawCode === 'number' ? rawCode : undefined;
+        super((_a = opts.message) !== null && _a !== void 0 ? _a : describe(p, keys));
+        this.name = 'DeezerError';
+        this.code = code;
+        this.keys = keys;
+        this.payload = p;
+        this.retryable = (_b = opts.retryable) !== null && _b !== void 0 ? _b : isRetryable(code, keys);
+    }
+    /** Whether a `code` / key set is worth retrying. */
+    static retryable(code, keys) {
+        return isRetryable(code, keys);
+    }
+}
+exports.DeezerError = DeezerError;
+const describe = (payload, keys) => {
+    if (!keys.length)
+        return 'Deezer request failed';
+    return keys.map((k) => `${k}: ${String(payload[k])}`).join(', ');
+};
+const isRetryable = (code, keys) => {
+    if (code === 4)
+        return true; // Deezer's transient "quota exceeded"
+    return keys.some((k) => RETRYABLE_KEYS.has(k));
+};

package/dist/lib/get-url.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.formatName = exports.toFormat = exports.DEEZER_FORMATS = exports.ExpiredTrackToken = exports.GeoBlocked = exports.WrongLicense = void 0;
 const delay_1 = __importDefault(require("delay"));
 const decrypt_1 = require("../lib/decrypt");
+const errors_1 = require("../lib/errors");
 const http_1 = require("../lib/http");
 const request_1 = __importDefault(require("../lib/request"));
 class WrongLicense extends Error {
@@ -137,7 +138,7 @@ const parseMediaEntry = (entry, token, country) => {
             throw new GeoBlocked(country);
         if (code === 2000 || code === 2001)
             throw new ExpiredTrackToken(token);
-        throw new Error(Object.entries(entry.errors[0]).join(', '));
+        throw new errors_1.DeezerError(entry.errors[0]);
     }
     const media = (_a = entry === null || entry === void 0 ? void 0 : entry.media) === null || _a === void 0 ? void 0 : _a[0];
     if (!((_b = media === null || media === void 0 ? void 0 : media.sources) === null || _b === void 0 ? void 0 : _b.length))

package/dist/lib/request.d.ts

@@ -3,6 +3,26 @@ type DeezerRequestConfig = {
     headers?: Record<string, string>;
     params?: HttpQuery;
 };
+/**
+ * Bounded-retry policy for the gateway. Every retry class has its own attempt
+ * cap **and** there is a wall-clock deadline, so a persistently failing endpoint
+ * can no longer spin forever (the old code had no cap on `code === 4`,
+ * `NEED_API_AUTH_REQUIRED` or `GATEWAY_ERROR`).
+ */
+export declare const RETRY_POLICY: {
+    /** total attempts for the transient `code === 4` class */
+    code4Attempts: number;
+    /** re-inits allowed for `NEED_API_AUTH_REQUIRED` */
+    authReinits: number;
+    /** token refreshes allowed for `GATEWAY_ERROR` / `VALID_TOKEN_REQUIRED` */
+    tokenRefreshes: number;
+    /** base backoff (ms) — grows exponentially, full-jittered */
+    baseMs: number;
+    /** cap on a single backoff wait */
+    maxDelayMs: number;
+    /** overall wall-clock budget from the first attempt */
+    deadlineMs: number;
+};
 export declare const initDeezerApi: (arl: string) => Promise<string>;
 declare const _default: {
     defaults: {

package/dist/lib/request.js

@@ -3,10 +3,36 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initDeezerApi = void 0;
+exports.initDeezerApi = exports.RETRY_POLICY = void 0;
 const delay_1 = __importDefault(require("delay"));
 const http_1 = require("./http");
+const errors_1 = require("./errors");
 let user_arl = 'c973964816688562722418b5200c1515dffaad15a42643ebf87cc72824a54612ec51c2ad42d566743f9e424c774e98ccae7737770acff59251328e6cd598c7bcac38ca269adf78bfb88ec5bbad6cd800db3c0b88b2af645bb22b99e71de26416';
+/**
+ * Bounded-retry policy for the gateway. Every retry class has its own attempt
+ * cap **and** there is a wall-clock deadline, so a persistently failing endpoint
+ * can no longer spin forever (the old code had no cap on `code === 4`,
+ * `NEED_API_AUTH_REQUIRED` or `GATEWAY_ERROR`).
+ */
+exports.RETRY_POLICY = {
+    /** total attempts for the transient `code === 4` class */
+    code4Attempts: 6,
+    /** re-inits allowed for `NEED_API_AUTH_REQUIRED` */
+    authReinits: 3,
+    /** token refreshes allowed for `GATEWAY_ERROR` / `VALID_TOKEN_REQUIRED` */
+    tokenRefreshes: 15,
+    /** base backoff (ms) — grows exponentially, full-jittered */
+    baseMs: 800,
+    /** cap on a single backoff wait */
+    maxDelayMs: 8000,
+    /** overall wall-clock budget from the first attempt */
+    deadlineMs: 30000,
+};
+/** Exponential backoff (ms) with full jitter on the top half of the window. */
+const backoffDelay = (attempt) => {
+    const windowMs = Math.min(exports.RETRY_POLICY.baseMs * 2 ** attempt, exports.RETRY_POLICY.maxDelayMs);
+    return windowMs / 2 + Math.random() * (windowMs / 2);
+};
 const instance = new http_1.HttpClient({
     baseURL: 'https://api.deezer.com/1.0',
     timeout: 15000,
@@ -54,30 +80,41 @@ const initDeezerApi = async (arl) => {
     return data.results.SESSION;
 };
 exports.initDeezerApi = initDeezerApi;
-let token_retry = 0;
 const requestWithRetry = async (method, url, body, config = {}) => {
     var _a;
-    const response = method === 'POST' ? await instance.post(url, body, config) : await instance.get(url, config);
-    const error = (_a = response.data) === null || _a === void 0 ? void 0 : _a.error;
-    if (!error || Object.keys(error).length === 0) {
-        token_retry = 0;
-        return response;
-    }
-    if (error.NEED_API_AUTH_REQUIRED) {
-        await (0, exports.initDeezerApi)(user_arl);
-        return await requestWithRetry(method, url, body, config);
-    }
-    if (error.code === 4) {
-        await delay_1.default.range(1000, 1500);
-        return await requestWithRetry(method, url, body, config);
-    }
-    if (error.GATEWAY_ERROR || (error.VALID_TOKEN_REQUIRED && token_retry < 15)) {
-        token_retry += 1;
-        await getApiToken();
-        return await requestWithRetry(method, url, body, config);
+    const startedAt = Date.now();
+    let authReinits = 0;
+    let tokenRefreshes = 0;
+    let code4Attempts = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const response = method === 'POST' ? await instance.post(url, body, config) : await instance.get(url, config);
+        const error = (_a = response.data) === null || _a === void 0 ? void 0 : _a.error;
+        if (!error || Object.keys(error).length === 0) {
+            return response;
+        }
+        const overDeadline = Date.now() - startedAt > exports.RETRY_POLICY.deadlineMs;
+        if (error.NEED_API_AUTH_REQUIRED && authReinits < exports.RETRY_POLICY.authReinits && !overDeadline) {
+            authReinits += 1;
+            await (0, exports.initDeezerApi)(user_arl);
+            continue;
+        }
+        if ((error.GATEWAY_ERROR || error.VALID_TOKEN_REQUIRED) &&
+            tokenRefreshes < exports.RETRY_POLICY.tokenRefreshes &&
+            !overDeadline) {
+            tokenRefreshes += 1;
+            await getApiToken();
+            await (0, delay_1.default)(backoffDelay(tokenRefreshes - 1));
+            continue;
+        }
+        if (error.code === 4 && code4Attempts < exports.RETRY_POLICY.code4Attempts && !overDeadline) {
+            await (0, delay_1.default)(backoffDelay(code4Attempts));
+            code4Attempts += 1;
+            continue;
+        }
+        // Unhandled error, or a retry class ran out of attempts / hit the deadline.
+        throw new errors_1.DeezerError(error);
     }
-    token_retry = 0;
-    return response;
 };
 exports.default = {
     defaults: instance.defaults,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur-core",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Core module for gerdur.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",