gerdur-core 2.5.0 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 2.7.0 - 2026-08-31
+
+Phase 3.2 — session lifecycle. The scattered module-level state
+(`request.ts`: `arl` / `sid` / `api_token`; `get-url.ts`: `license_token` /
+`country` / streaming rights) is consolidated into one **`Session`** object.
+Backwards compatible — `initDeezerApi` and every free function are unchanged.
+
+### Added
+
+- **`Session`** — owns one account's `arl`, HTTP client (`sid` / `api_token`),
+  `license_token` / `country` / `canStreamLossless` / `canStreamHq`, the
+  bounded-retry request loop, and token refresh (`init`, `refreshApiToken`,
+  `loadUserData`).
+- **`createSession(arl?)`** — an isolated session you hold and inspect, so
+  multiple accounts can be used concurrently.
+- **`defaultSession()`** — the process-wide session `initDeezerApi` and the free
+  functions run against. `setDefaultSession(session)` swaps it.
+- `SessionUserData` type; `DEFAULT_ARL` constant.
+
+### Changed
+
+- **Proactive `license_token` refresh** — `loadUserData()` caches the account's
+  media-API credentials for 25 min and force-refreshes on a media 403, instead of
+  only re-fetching after a failed download. Fewer opaque CDN 403s on long
+  playlists.
+- `RETRY_POLICY` now lives in `lib/session.ts` (still exported, same shape).
+
+## 2.6.0 - 2026-08-31
+
+Phase 2.4 round 2 — Flow, radios, and a user's library. All public REST, all
+memoised, all additive.
+
+### Added
+
+- **Flow / library** (take a `userId`): `getUserFlow`, `getUserFavoriteTracks`
+  (with `time_add`), `getUserFavoriteAlbums`, `getUserFavoriteArtists`,
+  `getUserPlaylists`, `getUserRadios`, `getUserChartTracks`.
+- **Radios**: `getRadios`, `getRadioTracks(radioId)`, `getRadioGenres`.
+- New types: `userFavoriteTrack`, `userFavoriteAlbum`, `userFavoriteArtist`,
+  `userPlaylistResult`, `radioResult`, `radioGenre`.
+
+### Internal
+
+- Tests run under `ts-node/register/transpile-only` (build still type-checks) —
+  the growing live-API suite was hitting the ts-node worker heap limit.
+- Live-API tests skip cleanly on Deezer's `code: 4` "Quota limit exceeded"
+  instead of failing when the suite bursts the public API.
+
 ## 2.5.0 - 2026-08-31
 
 Phase 3.1 — streaming download primitives. Additive.

package/README.md

@@ -97,6 +97,32 @@ Retries are bounded — `RETRY_POLICY` (exported) sets per-class attempt caps an
 `DeezerError` instead of spinning. `GeoBlocked`, `WrongLicense` and
 `ExpiredTrackToken` are still thrown as their own types from the download path.
 
+### Sessions
+
+A **`Session`** owns one account's state — the `arl`, the HTTP client (`sid` /
+`api_token`), and the account's `license_token` / `country` / streaming rights,
+plus the bounded-retry loop and token refresh. This state used to be
+module-level globals; bundling it means multiple accounts can coexist.
+
+- **`initDeezerApi(arl)`** — (re)authenticate the **default** session. Every free
+  function (`getTrackInfo`, `searchMusic`, `getTrackDownloadUrl`, …) runs against
+  it. Unchanged: same signature, returns the gateway `SESSION` id.
+- **`createSession(arl?)`** — an **isolated** session you hold and inspect:
+  `session.arl`, `session.sid`, and — after `await session.loadUserData()` —
+  `session.country`, `session.licenseToken`, `session.canStreamLossless`,
+  `session.canStreamHq`. `loadUserData()` caches for 25 min and refreshes on a
+  media-API 403.
+- **`defaultSession()`** — the `Session` the free functions use.
+
+```js
+await initDeezerApi(arl);                 // default session, as before
+const track = await getTrackInfo('3135556');
+
+const s = await createSession(otherArl);  // a second account, isolated
+await s.loadUserData();
+console.log(s.country, s.canStreamLossless);
+```
+
 ### `.initDeezerApi(arl_cookie);`
 
 > It is recommended that you first init the app with this method using your arl cookie.
@@ -244,6 +270,31 @@ const track = await getTrackByISRC('USUM71311296');      // "Get Lucky"
 pass the `id` to `getTrackInfo` / `getAlbumTracks` (or use the converter's
 `isrc2deezer` / `upc2deezer`, which hydrate a gw track for you).
 
+### Flow, radios & a user's library
+
+Public-profile data — pass a `userId` (`getUser().USER_ID`, a profile URL, or
+`parseInfo`). A private library is only visible to that user's own session.
+
+| Method | Returns |
+| :--- | :--- |
+| `getUserFlow(userId, limit = 40)` | **Flow** — the endless personalised mix, as tracks. |
+| `getUserFavoriteTracks(userId, limit?, index?)` | loved tracks, newest first (each with `time_add`). |
+| `getUserFavoriteAlbums(userId, limit?, index?)` | favourite albums. |
+| `getUserFavoriteArtists(userId, limit?, index?)` | favourite artists. |
+| `getUserPlaylists(userId, limit?, index?)` | the user's own + followed playlists. |
+| `getUserRadios(userId)` | radios the user favourited. |
+| `getUserChartTracks(userId, limit?)` | the user's personal top tracks. |
+| `getRadios()` | Deezer's curated radio list. |
+| `getRadioTracks(radioId)` | a radio's current tracklist — a ready-to-play source. |
+| `getRadioGenres()` | radios grouped by genre. |
+
+```js
+const me = await getUser();
+const {data: flow} = await getUserFlow(me.USER_ID);       // your Flow
+const {data: loved} = await getUserFavoriteTracks(me.USER_ID);
+const {data: eighties} = await getRadioTracks(38305);     // "The '80s"
+```
+
 ### `.getTrackDownloadUrl(track, quality);`
 
 | Parameters | Required |        Type |                        Description |

package/dist/api/index.d.ts

@@ -3,3 +3,4 @@ export * from './request';
 export * from './search';
 export * from './browse';
 export * from './preview';
+export * from './user';

package/dist/api/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./request"), exports);
 __exportStar(require("./search"), exports);
 __exportStar(require("./browse"), exports);
 __exportStar(require("./preview"), exports);
+__exportStar(require("./user"), exports);

package/dist/api/user.d.ts

@@ -0,0 +1,24 @@
+import type { publicApiList, radioGenre, radioResult, searchResultTrack, userFavoriteAlbum, userFavoriteArtist, userFavoriteTrack, userPlaylistResult } from '../types';
+/**
+ * Deezer **Flow** — the endless personalised mix — for a user. Returns
+ * public-API track objects; `getTrackInfo(id)` to make one downloadable.
+ */
+export declare const getUserFlow: (userId: number | string, limit?: number) => Promise<publicApiList<searchResultTrack>>;
+/** A user's favourite (loved) tracks, newest first; each carries `time_add`. */
+export declare const getUserFavoriteTracks: (userId: number | string, limit?: number, index?: number) => Promise<publicApiList<userFavoriteTrack>>;
+/** A user's favourite albums. */
+export declare const getUserFavoriteAlbums: (userId: number | string, limit?: number, index?: number) => Promise<publicApiList<userFavoriteAlbum>>;
+/** A user's favourite artists. */
+export declare const getUserFavoriteArtists: (userId: number | string, limit?: number, index?: number) => Promise<publicApiList<userFavoriteArtist>>;
+/** A user's own + followed playlists. */
+export declare const getUserPlaylists: (userId: number | string, limit?: number, index?: number) => Promise<publicApiList<userPlaylistResult>>;
+/** The radios a user has favourited. */
+export declare const getUserRadios: (userId: number | string) => Promise<publicApiList<radioResult>>;
+/** A user's personal track chart (their most-played). */
+export declare const getUserChartTracks: (userId: number | string, limit?: number) => Promise<publicApiList<searchResultTrack>>;
+/** Deezer's curated radio list. */
+export declare const getRadios: () => Promise<publicApiList<radioResult>>;
+/** A radio's current track list — a ready-to-play (public-API) source. */
+export declare const getRadioTracks: (radioId: number | string) => Promise<publicApiList<searchResultTrack>>;
+/** Radios grouped by genre. */
+export declare const getRadioGenres: () => Promise<publicApiList<radioGenre>>;

package/dist/api/user.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRadioGenres = exports.getRadioTracks = exports.getRadios = exports.getUserChartTracks = exports.getUserRadios = exports.getUserPlaylists = exports.getUserFavoriteArtists = exports.getUserFavoriteAlbums = exports.getUserFavoriteTracks = exports.getUserFlow = void 0;
+const request_1 = require("./request");
+const withParams = (slug, params) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== '') {
+            search.set(key, String(value));
+        }
+    }
+    const qs = search.toString();
+    return qs ? `${slug}?${qs}` : slug;
+};
+// ─── Flow & a user's library (public REST) ───────────────────────────────────
+//
+// These take an explicit `userId` (from `getUser().USER_ID`, a profile URL, or
+// `parseInfo`). They read **public** profile data — a user whose library is
+// private only exposes it to their own authenticated session. All memoised.
+/**
+ * Deezer **Flow** — the endless personalised mix — for a user. Returns
+ * public-API track objects; `getTrackInfo(id)` to make one downloadable.
+ */
+const getUserFlow = (userId, limit = 40) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/flow`, { limit }));
+exports.getUserFlow = getUserFlow;
+/** A user's favourite (loved) tracks, newest first; each carries `time_add`. */
+const getUserFavoriteTracks = (userId, limit = 100, index = 0) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/tracks`, { limit, index }));
+exports.getUserFavoriteTracks = getUserFavoriteTracks;
+/** A user's favourite albums. */
+const getUserFavoriteAlbums = (userId, limit = 50, index = 0) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/albums`, { limit, index }));
+exports.getUserFavoriteAlbums = getUserFavoriteAlbums;
+/** A user's favourite artists. */
+const getUserFavoriteArtists = (userId, limit = 50, index = 0) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/artists`, { limit, index }));
+exports.getUserFavoriteArtists = getUserFavoriteArtists;
+/** A user's own + followed playlists. */
+const getUserPlaylists = (userId, limit = 50, index = 0) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/playlists`, { limit, index }));
+exports.getUserPlaylists = getUserPlaylists;
+/** The radios a user has favourited. */
+const getUserRadios = (userId) => (0, request_1.requestPublicApi)(`/user/${userId}/radios`);
+exports.getUserRadios = getUserRadios;
+/** A user's personal track chart (their most-played). */
+const getUserChartTracks = (userId, limit = 50) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/charts/tracks`, { limit }));
+exports.getUserChartTracks = getUserChartTracks;
+// ─── Radios (public REST) ────────────────────────────────────────────────────
+/** Deezer's curated radio list. */
+const getRadios = () => (0, request_1.requestPublicApi)('/radio');
+exports.getRadios = getRadios;
+/** A radio's current track list — a ready-to-play (public-API) source. */
+const getRadioTracks = (radioId) => (0, request_1.requestPublicApi)(`/radio/${radioId}/tracks`);
+exports.getRadioTracks = getRadioTracks;
+/** Radios grouped by genre. */
+const getRadioGenres = () => (0, request_1.requestPublicApi)('/radio/genres');
+exports.getRadioGenres = getRadioGenres;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { initDeezerApi, RETRY_POLICY } from './lib/request';
+export { initDeezerApi, createSession, defaultSession, Session, RETRY_POLICY, DEFAULT_ARL } from './lib/session';
+export type { SessionUserData } from './lib/session';
 export { DeezerError } from './lib/errors';
 export type { DeezerErrorPayload } from './lib/errors';
 export * from './api';

package/dist/index.js

@@ -14,10 +14,14 @@ 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.getStream = 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; } });
+exports.getStream = exports.getText = exports.getJson = exports.getBuffer = exports.httpsAgent = exports.httpAgent = exports.DeezerError = exports.DEFAULT_ARL = exports.RETRY_POLICY = exports.Session = exports.defaultSession = exports.createSession = exports.initDeezerApi = void 0;
+var session_1 = require("./lib/session");
+Object.defineProperty(exports, "initDeezerApi", { enumerable: true, get: function () { return session_1.initDeezerApi; } });
+Object.defineProperty(exports, "createSession", { enumerable: true, get: function () { return session_1.createSession; } });
+Object.defineProperty(exports, "defaultSession", { enumerable: true, get: function () { return session_1.defaultSession; } });
+Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return session_1.Session; } });
+Object.defineProperty(exports, "RETRY_POLICY", { enumerable: true, get: function () { return session_1.RETRY_POLICY; } });
+Object.defineProperty(exports, "DEFAULT_ARL", { enumerable: true, get: function () { return session_1.DEFAULT_ARL; } });
 var errors_1 = require("./lib/errors");
 Object.defineProperty(exports, "DeezerError", { enumerable: true, get: function () { return errors_1.DeezerError; } });
 __exportStar(require("./api"), exports);

package/dist/lib/get-url.js

@@ -9,6 +9,7 @@ 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"));
+const session_1 = require("../lib/session");
 class WrongLicense extends Error {
     constructor(format) {
         super();
@@ -37,7 +38,6 @@ class ExpiredTrackToken extends Error {
     }
 }
 exports.ExpiredTrackToken = ExpiredTrackToken;
-let user_data = null;
 /**
  * Every audio format Deezer's `get_url` understands, best → worst. `FLAC`,
  * `MP3_320` and `MP3_128` are the classic `9 / 3 / 1` qualities; the rest are
@@ -83,22 +83,6 @@ const getTrackFileSize = (track, quality) => {
     const key = FORMAT_FILESIZE_KEY[(0, exports.toFormat)(quality)];
     return key ? Number(track[key]) || 0 : 0;
 };
-const dzAuthenticate = async () => {
-    const { data } = await request_1.default.get('https://www.deezer.com/ajax/gw-light.php', {
-        params: {
-            method: 'deezer.getUserData',
-            api_version: '1.0',
-            api_token: 'null',
-        },
-    });
-    user_data = {
-        license_token: data.results.USER.OPTIONS.license_token,
-        can_stream_lossless: data.results.USER.OPTIONS.web_lossless || data.results.USER.OPTIONS.mobile_loseless,
-        can_stream_hq: data.results.USER.OPTIONS.web_hq || data.results.USER.OPTIONS.mobile_hq,
-        country: data.results.COUNTRY,
-    };
-    return user_data;
-};
 const MEDIA_MAX_RETRIES = 3;
 /**
  * Quality code (`1 | 3 | 9`) or format string → the `format` string the media
@@ -110,10 +94,10 @@ exports.formatName = formatName;
 /** POST media.deezer.com/v1/get_url with re-auth + exponential-backoff retry on 403/429/5xx. */
 const mediaGetUrl = async (track_tokens, formats, attempt = 0) => {
     var _a;
-    const user = user_data ? user_data : await dzAuthenticate();
+    const user = await (0, session_1.defaultSession)().loadUserData();
     try {
         const { data } = await request_1.default.post('https://media.deezer.com/v1/get_url', {
-            license_token: user.license_token,
+            license_token: user.licenseToken,
             media: [{ type: 'FULL', formats }],
             track_tokens,
         });
@@ -122,7 +106,8 @@ const mediaGetUrl = async (track_tokens, formats, attempt = 0) => {
     catch (err) {
         const status = err instanceof http_1.HttpStatusError ? err.statusCode : 0;
         if ((status === 403 || status === 429 || status >= 500) && attempt < MEDIA_MAX_RETRIES) {
-            user_data = null;
+            // a stale license token is a common cause — force a refresh before the retry
+            await (0, session_1.defaultSession)().loadUserData(true);
             await (0, delay_1.default)(500 * 2 ** attempt + Math.floor(Math.random() * 250));
             return mediaGetUrl(track_tokens, formats, attempt + 1);
         }
@@ -148,8 +133,8 @@ const parseMediaEntry = (entry, token, country) => {
 /** Whether a track fetched with the given cipher needs Blowfish stripe decryption. */
 const cipherIsEncrypted = (cipher, url) => cipher ? cipher !== 'NONE' : url.includes('/mobile/') || url.includes('/media/');
 const getTrackUrlFromServer = async (track_token, format) => {
-    const user = user_data ? user_data : await dzAuthenticate();
-    if ((format === 'FLAC' && !user.can_stream_lossless) || (format === 'MP3_320' && !user.can_stream_hq)) {
+    const user = await (0, session_1.defaultSession)().loadUserData();
+    if ((format === 'FLAC' && !user.canStreamLossless) || (format === 'MP3_320' && !user.canStreamHq)) {
         throw new WrongLicense(format);
     }
     const { data, country } = await mediaGetUrl([track_token], [{ format, cipher: 'BF_CBC_STRIPE' }]);

package/dist/lib/request.d.ts

@@ -1,31 +1,17 @@
 import type { HttpQuery, HttpResponse } from './http';
+export { initDeezerApi, createSession, defaultSession, setDefaultSession, Session, RETRY_POLICY } from './session';
+export type { SessionUserData } from './session';
 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`).
+ * A thin proxy over the **default** {@link Session} — kept so the api / get-url
+ * layers can keep calling `client.get` / `client.post` unchanged. Each call runs
+ * through the session's bounded-retry loop.
  */
-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: {
+    readonly defaults: {
         baseURL?: string | undefined;
         headers: import("./http").HttpHeaders;
         maxRedirects: number;

package/dist/lib/request.js

@@ -1,123 +1,23 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-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';
+exports.RETRY_POLICY = exports.Session = exports.setDefaultSession = exports.defaultSession = exports.createSession = exports.initDeezerApi = void 0;
+const session_1 = require("./session");
+var session_2 = require("./session");
+Object.defineProperty(exports, "initDeezerApi", { enumerable: true, get: function () { return session_2.initDeezerApi; } });
+Object.defineProperty(exports, "createSession", { enumerable: true, get: function () { return session_2.createSession; } });
+Object.defineProperty(exports, "defaultSession", { enumerable: true, get: function () { return session_2.defaultSession; } });
+Object.defineProperty(exports, "setDefaultSession", { enumerable: true, get: function () { return session_2.setDefaultSession; } });
+Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return session_2.Session; } });
+Object.defineProperty(exports, "RETRY_POLICY", { enumerable: true, get: function () { return session_2.RETRY_POLICY; } });
 /**
- * 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`).
+ * A thin proxy over the **default** {@link Session} — kept so the api / get-url
+ * layers can keep calling `client.get` / `client.post` unchanged. Each call runs
+ * through the session's bounded-retry loop.
  */
-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,
-    headers: {
-        Accept: '*/*',
-        'Accept-Encoding': 'gzip, deflate',
-        'Accept-Language': 'en-US',
-        'Cache-Control': 'no-cache',
-        'Content-Type': 'application/json; charset=UTF-8',
-        'User-Agent': 'Deezer/8.32.0.2 (iOS; 14.4; Mobile; en; iPhone10_5)',
-    },
-    params: {
-        version: '8.32.0',
-        api_key: 'ZAIVAHCEISOHWAICUQUEXAEPICENGUAFAEZAIPHAELEEVAHPHUCUFONGUAPASUAY',
-        output: 3,
-        input: 3,
-        buildId: 'ios12_universal',
-        screenHeight: '480',
-        screenWidth: '320',
-        lang: 'en',
-    },
-});
-const getApiToken = async () => {
-    const { data } = await instance.get('https://www.deezer.com/ajax/gw-light.php', {
-        params: {
-            method: 'deezer.getUserData',
-            api_version: '1.0',
-            api_token: 'null',
-        },
-    });
-    instance.defaults.params.sid = data.results.SESSION_ID;
-    instance.defaults.params.api_token = data.results.checkForm;
-    return data.results.checkForm;
-};
-const initDeezerApi = async (arl) => {
-    if (arl.length !== 192) {
-        throw new Error(`Invalid arl. Length should be 192 characters. You have provided ${arl.length} characters.`);
-    }
-    user_arl = arl;
-    const { data } = await instance.get('https://www.deezer.com/ajax/gw-light.php', {
-        params: { method: 'deezer.ping', api_version: '1.0', api_token: '' },
-        headers: { cookie: 'arl=' + arl },
-    });
-    instance.defaults.params.sid = data.results.SESSION;
-    return data.results.SESSION;
-};
-exports.initDeezerApi = initDeezerApi;
-const requestWithRetry = async (method, url, body, config = {}) => {
-    var _a;
-    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);
-    }
-};
 exports.default = {
-    defaults: instance.defaults,
-    get: async (url, config = {}) => await requestWithRetry('GET', url, undefined, config),
-    post: async (url, body, config = {}) => await requestWithRetry('POST', url, body, config),
+    get defaults() {
+        return (0, session_1.defaultSession)().http.defaults;
+    },
+    get: (url, config = {}) => (0, session_1.defaultSession)().request('GET', url, undefined, config),
+    post: (url, body, config = {}) => (0, session_1.defaultSession)().request('POST', url, body, config),
 };

package/dist/lib/session.d.ts

@@ -0,0 +1,112 @@
+import { HttpClient } from './http';
+import type { HttpQuery, HttpResponse } from './http';
+/**
+ * The bundled default `arl`. It is shared, rate-limited and expiring — good for
+ * unauthenticated endpoints, useless for downloads. `initDeezerApi` /
+ * `createSession` replace it.
+ */
+export declare const DEFAULT_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.
+ */
+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;
+};
+type SessionRequestConfig = {
+    headers?: Record<string, string>;
+    params?: HttpQuery;
+};
+/** The account-scoped bits of `deezer.getUserData` a download needs. */
+export interface SessionUserData {
+    /** the `license_token` the media API's `get_url` requires */
+    licenseToken: string;
+    /** ISO country the account resolves to (drives geo-blocking) */
+    country: string;
+    /** account may stream FLAC */
+    canStreamLossless: boolean;
+    /** account may stream 320 kbps */
+    canStreamHq: boolean;
+    offerId?: number;
+}
+/**
+ * One Deezer session — owns the `arl`, the HTTP client (and its `sid` /
+ * `api_token`), and the account's `license_token` / `country` / streaming
+ * rights, plus the bounded-retry request loop and token refresh.
+ *
+ * The state used to be spread across module-level variables in `request.ts` and
+ * `get-url.ts`; a `Session` bundles it so multiple accounts can coexist. The
+ * free functions (`getTrackInfo`, `request`, …) run against a process-wide
+ * default session; `createSession(arl)` gives you an isolated one.
+ */
+export declare class Session {
+    /** the arl cookie in use */
+    arl: string;
+    /** the underlying HTTP client — its `defaults.params` carry `sid` / `api_token` */
+    readonly http: HttpClient;
+    private userData;
+    private userDataAt;
+    constructor(arl?: string);
+    /** current gateway session id */
+    get sid(): string | undefined;
+    /** current CSRF-ish api token */
+    get apiToken(): string | undefined;
+    /** ISO country the account resolves to, once `loadUserData` has run */
+    get country(): string | undefined;
+    /** the media-API `license_token`, once `loadUserData` has run */
+    get licenseToken(): string | undefined;
+    get canStreamLossless(): boolean;
+    get canStreamHq(): boolean;
+    /**
+     * Ping `gw-light.php` for a fresh `SESSION` id. Pass an `arl` to (re)authenticate
+     * this session as that account — it must be exactly 192 characters.
+     * Returns the new `SESSION`.
+     */
+    init(arl?: string): Promise<string>;
+    /** Refresh `sid` + `api_token` from `deezer.getUserData`. Returns the api token. */
+    refreshApiToken(): Promise<string>;
+    /**
+     * The account's `license_token` / `country` / streaming rights, from
+     * `deezer.getUserData`. Cached for {@link USER_DATA_TTL_MS}; pass `force` (or
+     * see a media-API 403) to refresh. Also refreshes `sid` / `api_token`.
+     */
+    loadUserData(force?: boolean): Promise<SessionUserData>;
+    /** Drop the cached user data so the next `loadUserData` re-fetches. */
+    invalidateUserData(): void;
+    /**
+     * The bounded-retry gateway request loop. Handles `NEED_API_AUTH_REQUIRED`
+     * (re-init), `GATEWAY_ERROR` / `VALID_TOKEN_REQUIRED` (token refresh) and
+     * `code === 4` (transient), each with its own attempt cap, full-jittered
+     * backoff, and a wall-clock deadline. Throws `DeezerError` on exhaustion.
+     */
+    request<T>(method: 'GET' | 'POST', url: string, body?: unknown, config?: SessionRequestConfig): Promise<HttpResponse<T>>;
+}
+/** The process-wide default session every free function runs against. */
+export declare const defaultSession: () => Session;
+/**
+ * (Re)authenticate the **default** session. Kept for backwards compatibility —
+ * `createSession` is the way to hold an isolated session. `arl` must be exactly
+ * 192 characters. Returns the gateway `SESSION` id.
+ */
+export declare const initDeezerApi: (arl: string) => Promise<string>;
+/**
+ * Create an **isolated** Deezer session — its own `arl`, `sid`, tokens and
+ * `license_token`, so multiple accounts can be used concurrently. Without an
+ * `arl` it runs on the bundled (shared, rate-limited) default.
+ */
+export declare const createSession: (arl?: string) => Promise<Session>;
+/** Replace the default session (used by tests). */
+export declare const setDefaultSession: (session: Session) => void;
+export {};

package/dist/lib/session.js

@@ -0,0 +1,238 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setDefaultSession = exports.createSession = exports.initDeezerApi = exports.defaultSession = exports.Session = exports.RETRY_POLICY = exports.DEFAULT_ARL = void 0;
+const delay_1 = __importDefault(require("delay"));
+const errors_1 = require("./errors");
+const http_1 = require("./http");
+/**
+ * The bundled default `arl`. It is shared, rate-limited and expiring — good for
+ * unauthenticated endpoints, useless for downloads. `initDeezerApi` /
+ * `createSession` replace it.
+ */
+exports.DEFAULT_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.
+ */
+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);
+};
+/** How long a loaded `deezer.getUserData` payload is trusted before a refresh. */
+const USER_DATA_TTL_MS = 25 * 60 * 1000;
+/**
+ * One Deezer session — owns the `arl`, the HTTP client (and its `sid` /
+ * `api_token`), and the account's `license_token` / `country` / streaming
+ * rights, plus the bounded-retry request loop and token refresh.
+ *
+ * The state used to be spread across module-level variables in `request.ts` and
+ * `get-url.ts`; a `Session` bundles it so multiple accounts can coexist. The
+ * free functions (`getTrackInfo`, `request`, …) run against a process-wide
+ * default session; `createSession(arl)` gives you an isolated one.
+ */
+class Session {
+    constructor(arl) {
+        this.userData = null;
+        this.userDataAt = 0;
+        this.arl = arl !== null && arl !== void 0 ? arl : exports.DEFAULT_ARL;
+        this.http = new http_1.HttpClient({
+            baseURL: 'https://api.deezer.com/1.0',
+            timeout: 15000,
+            headers: {
+                Accept: '*/*',
+                'Accept-Encoding': 'gzip, deflate',
+                'Accept-Language': 'en-US',
+                'Cache-Control': 'no-cache',
+                'Content-Type': 'application/json; charset=UTF-8',
+                'User-Agent': 'Deezer/8.32.0.2 (iOS; 14.4; Mobile; en; iPhone10_5)',
+            },
+            params: {
+                version: '8.32.0',
+                api_key: 'ZAIVAHCEISOHWAICUQUEXAEPICENGUAFAEZAIPHAELEEVAHPHUCUFONGUAPASUAY',
+                output: 3,
+                input: 3,
+                buildId: 'ios12_universal',
+                screenHeight: '480',
+                screenWidth: '320',
+                lang: 'en',
+            },
+        });
+    }
+    /** current gateway session id */
+    get sid() {
+        return this.http.defaults.params.sid;
+    }
+    /** current CSRF-ish api token */
+    get apiToken() {
+        return this.http.defaults.params.api_token;
+    }
+    /** ISO country the account resolves to, once `loadUserData` has run */
+    get country() {
+        var _a;
+        return (_a = this.userData) === null || _a === void 0 ? void 0 : _a.country;
+    }
+    /** the media-API `license_token`, once `loadUserData` has run */
+    get licenseToken() {
+        var _a;
+        return (_a = this.userData) === null || _a === void 0 ? void 0 : _a.licenseToken;
+    }
+    get canStreamLossless() {
+        var _a, _b;
+        return (_b = (_a = this.userData) === null || _a === void 0 ? void 0 : _a.canStreamLossless) !== null && _b !== void 0 ? _b : false;
+    }
+    get canStreamHq() {
+        var _a, _b;
+        return (_b = (_a = this.userData) === null || _a === void 0 ? void 0 : _a.canStreamHq) !== null && _b !== void 0 ? _b : false;
+    }
+    /**
+     * Ping `gw-light.php` for a fresh `SESSION` id. Pass an `arl` to (re)authenticate
+     * this session as that account — it must be exactly 192 characters.
+     * Returns the new `SESSION`.
+     */
+    async init(arl) {
+        if (arl !== undefined) {
+            if (arl.length !== 192) {
+                throw new Error(`Invalid arl. Length should be 192 characters. You have provided ${arl.length} characters.`);
+            }
+            this.arl = arl;
+            this.userData = null;
+        }
+        const { data } = await this.http.get('https://www.deezer.com/ajax/gw-light.php', {
+            params: { method: 'deezer.ping', api_version: '1.0', api_token: '' },
+            headers: { cookie: 'arl=' + this.arl },
+        });
+        this.http.defaults.params.sid = data.results.SESSION;
+        return data.results.SESSION;
+    }
+    /** Refresh `sid` + `api_token` from `deezer.getUserData`. Returns the api token. */
+    async refreshApiToken() {
+        const { data } = await this.http.get('https://www.deezer.com/ajax/gw-light.php', {
+            params: { method: 'deezer.getUserData', api_version: '1.0', api_token: 'null' },
+        });
+        this.http.defaults.params.sid = data.results.SESSION_ID;
+        this.http.defaults.params.api_token = data.results.checkForm;
+        return data.results.checkForm;
+    }
+    /**
+     * The account's `license_token` / `country` / streaming rights, from
+     * `deezer.getUserData`. Cached for {@link USER_DATA_TTL_MS}; pass `force` (or
+     * see a media-API 403) to refresh. Also refreshes `sid` / `api_token`.
+     */
+    async loadUserData(force = false) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        if (this.userData && !force && Date.now() - this.userDataAt < USER_DATA_TTL_MS) {
+            return this.userData;
+        }
+        const { data } = await this.http.get('https://www.deezer.com/ajax/gw-light.php', {
+            params: { method: 'deezer.getUserData', api_version: '1.0', api_token: 'null' },
+        });
+        const options = (_c = (_b = (_a = data.results) === null || _a === void 0 ? void 0 : _a.USER) === null || _b === void 0 ? void 0 : _b.OPTIONS) !== null && _c !== void 0 ? _c : {};
+        this.userData = {
+            licenseToken: options.license_token,
+            country: (_d = data.results) === null || _d === void 0 ? void 0 : _d.COUNTRY,
+            canStreamLossless: Boolean(options.web_lossless || options.mobile_loseless),
+            canStreamHq: Boolean(options.web_hq || options.mobile_hq),
+            offerId: (_e = data.results) === null || _e === void 0 ? void 0 : _e.OFFER_ID,
+        };
+        this.userDataAt = Date.now();
+        if ((_f = data.results) === null || _f === void 0 ? void 0 : _f.checkForm) {
+            this.http.defaults.params.api_token = data.results.checkForm;
+        }
+        if ((_g = data.results) === null || _g === void 0 ? void 0 : _g.SESSION_ID) {
+            this.http.defaults.params.sid = data.results.SESSION_ID;
+        }
+        return this.userData;
+    }
+    /** Drop the cached user data so the next `loadUserData` re-fetches. */
+    invalidateUserData() {
+        this.userData = null;
+    }
+    /**
+     * The bounded-retry gateway request loop. Handles `NEED_API_AUTH_REQUIRED`
+     * (re-init), `GATEWAY_ERROR` / `VALID_TOKEN_REQUIRED` (token refresh) and
+     * `code === 4` (transient), each with its own attempt cap, full-jittered
+     * backoff, and a wall-clock deadline. Throws `DeezerError` on exhaustion.
+     */
+    async request(method, url, body, config = {}) {
+        var _a;
+        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 this.http.post(url, body, config) : await this.http.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 this.init();
+                continue;
+            }
+            if ((error.GATEWAY_ERROR || error.VALID_TOKEN_REQUIRED) &&
+                tokenRefreshes < exports.RETRY_POLICY.tokenRefreshes &&
+                !overDeadline) {
+                tokenRefreshes += 1;
+                await this.refreshApiToken();
+                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;
+            }
+            throw new errors_1.DeezerError(error);
+        }
+    }
+}
+exports.Session = Session;
+let _default = new Session();
+/** The process-wide default session every free function runs against. */
+const defaultSession = () => _default;
+exports.defaultSession = defaultSession;
+/**
+ * (Re)authenticate the **default** session. Kept for backwards compatibility —
+ * `createSession` is the way to hold an isolated session. `arl` must be exactly
+ * 192 characters. Returns the gateway `SESSION` id.
+ */
+const initDeezerApi = (arl) => _default.init(arl);
+exports.initDeezerApi = initDeezerApi;
+/**
+ * Create an **isolated** Deezer session — its own `arl`, `sid`, tokens and
+ * `license_token`, so multiple accounts can be used concurrently. Without an
+ * `arl` it runs on the bundled (shared, rate-limited) default.
+ */
+const createSession = async (arl) => {
+    const session = new Session(arl);
+    await session.init();
+    return session;
+};
+exports.createSession = createSession;
+/** Replace the default session (used by tests). */
+const setDefaultSession = (session) => {
+    _default = session;
+};
+exports.setDefaultSession = setDefaultSession;

package/dist/types/user.d.ts

@@ -1,3 +1,4 @@
+import type { searchResultTrack, searchResultArtist } from './search';
 export interface userType {
     USER_ID: string;
     EMAIL: string;
@@ -14,3 +15,82 @@ export interface userType {
     PHONE?: string;
     __TYPE__: 'user';
 }
+/** A favourite track from `/user/{id}/tracks` — public-API shape, plus `time_add`. */
+export interface userFavoriteTrack extends searchResultTrack {
+    /** unix timestamp the track was added to favourites */
+    time_add?: number;
+}
+export interface userFavoriteAlbum {
+    id: number;
+    title: string;
+    link: string;
+    cover: string;
+    cover_small?: string;
+    cover_medium?: string;
+    cover_big?: string;
+    cover_xl?: string;
+    md5_image: string;
+    nb_tracks: number;
+    release_date: string;
+    record_type: string;
+    available: boolean;
+    tracklist: string;
+    explicit_lyrics: boolean;
+    time_add?: number;
+    artist: searchResultArtist | {
+        id: number;
+        name: string;
+        tracklist?: string;
+        type: 'artist';
+    };
+    type: 'album';
+}
+export interface userFavoriteArtist extends searchResultArtist {
+    time_add?: number;
+}
+export interface userPlaylistResult {
+    id: number;
+    title: string;
+    duration: number;
+    public: boolean;
+    is_loved_track: boolean;
+    collaborative: boolean;
+    nb_tracks: number;
+    fans: number;
+    link: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    checksum: string;
+    tracklist: string;
+    creation_date?: string;
+    time_add?: number;
+    time_mod?: number;
+    creator?: {
+        id: number;
+        name: string;
+        tracklist?: string;
+        type: 'user';
+    };
+    type: 'playlist';
+}
+export interface radioResult {
+    id: number;
+    title: string;
+    description?: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    md5_image?: string;
+    tracklist: string;
+    type: 'radio';
+}
+export interface radioGenre {
+    id: number;
+    title: string;
+    radios: radioResult[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur-core",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Core module for gerdur.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -61,7 +61,7 @@
       "!__tests__/helpers.ts"
     ],
     "require": [
-      "ts-node/register"
+      "ts-node/register/transpile-only"
     ],
     "timeout": "2m",
     "verbose": true