gerdur-core 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 2.8.0 - 2026-08-31
+
+Phase 3.2 (cont.) — a `Session` is now usable per-account. Additive; free
+functions unchanged.
+
+### Added
+
+- **`Session` query methods**: `getUser`, `getTrackInfo`, `getLyrics`,
+  `getAlbumInfo`, `getAlbumTracks`, `getPlaylistInfo`, `getPlaylistTracks`,
+  `getArtistInfo`, `getDiscography`, `getProfile`, `searchMusic` — plus the raw
+  channels `gw` / `gwLight` / `gwGet`. So `createSession(arl)` gives you an
+  isolated client you can actually query, not just inspect.
+- Each `Session` has **its own response cache** (`session.cache`) — gateway
+  responses carry account-specific `TRACK_TOKEN`s, so sharing one cache across
+  accounts was wrong.
+
+### Changed
+
+- `request` / `requestLight` / `requestGet` are now thin wrappers over
+  `defaultSession()`. **`initDeezerApi(newArl)` now clears the default session's
+  cache** — previously a new account could be served the old account's cached
+  track tokens.
+
+## 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

package/README.md

@@ -97,6 +97,49 @@ 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.
+
+Each `Session` has **its own response cache** (per-account, since gateway
+responses carry account-specific `TRACK_TOKEN`s) and its own query methods:
+
+| Method | |
+| :--- | :--- |
+| `getUser()` | this account's profile |
+| `getTrackInfo(id)` | `song.getData` — the `TRACK_TOKEN` is this session's |
+| `getLyrics(id)` | plain + synced lyrics |
+| `getAlbumInfo(id)` / `getAlbumTracks(id)` | album metadata / full track list |
+| `getPlaylistInfo(id)` / `getPlaylistTracks(id)` | playlist metadata / tracks (with `TRACK_POSITION`) |
+| `getArtistInfo(id)` / `getDiscography(id, nb?)` | artist metadata / discography |
+| `getProfile(userId)` | a public profile |
+| `searchMusic(query, types?, nb?)` | search (`deezer.pageSearch`) |
+| `gw(body, method)` / `gwLight(body, method)` / `gwGet(method, params?)` | the raw coalesced request channels |
+| `init(arl?)` / `refreshApiToken()` / `loadUserData(force?)` / `invalidateUserData()` | lifecycle |
+
+```js
+await initDeezerApi(arl);                 // default session, as before
+const track = await getTrackInfo('3135556');
+
+const s = await createSession(otherArl);  // a second account, fully isolated
+await s.loadUserData();
+console.log(s.country, s.canStreamLossless);
+const mine = await s.getTrackInfo('3135556');   // runs against `otherArl`
+```
+
 ### `.initDeezerApi(arl_cookie);`
 
 > It is recommended that you first init the app with this method using your arl cookie.

package/dist/api/request.d.ts

@@ -1,23 +1,14 @@
 /**
- * Make POST requests to deezer api
- * @param {Object} body post body
- * @param {String} method request method
+ * The gateway request helpers are now thin wrappers over the **default**
+ * {@link Session} — its per-session cache + single-flight coalescing does the
+ * de-duplication that used to live here. `createSession(arl)` gives you an
+ * isolated one whose `session.gw(...)` / `session.getTrackInfo(...)` don't share
+ * this cache.
  */
+/** POST `gateway.php` (main gw channel). */
 export declare const request: (body: object, method: string) => Promise<any>;
-/**
- * Make POST requests to deezer api
- * @param {Object} body post body
- * @param {String} method request method
- */
+/** POST `gw-light.php` (search / suggest / lighter methods). */
 export declare const requestLight: (body: object, method: string) => Promise<any>;
-/**
- * Make GET requests to deezer public api
- * @param {String} method request method
- * @param {Object} params request parameters
- */
+/** GET `gateway.php` (app_page_get, user_getInfo, …). */
 export declare const requestGet: (method: string, params?: Record<string, any>, key?: string) => Promise<any>;
-/**
- * Make GET requests to deezer public api
- * @param {String} slug endpoint
- */
 export declare const requestPublicApi: (slug: string) => Promise<any>;

package/dist/api/request.js

@@ -4,106 +4,54 @@ 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 request_1 = __importDefault(require("../lib/request"));
+const session_1 = require("../lib/session");
 const cache_1 = __importDefault(require("./cache"));
 /**
- * In-flight request coalescing (single-flight).
- *
- * The LRU only helps *after* a response lands. During a batch download the
- * pipeline fires many identical metadata calls at once — e.g. tagging 14 tracks
- * of one album triggers 14 concurrent `album/<id>` lookups — and every one of
- * them misses the still-empty cache and hits the network. Here a second caller
- * for a key already in flight awaits the same promise instead, so the wire sees
- * exactly one request. Entries are removed as soon as they settle; the LRU takes
- * over from there.
+ * The gateway request helpers are now thin wrappers over the **default**
+ * {@link Session} — its per-session cache + single-flight coalescing does the
+ * de-duplication that used to live here. `createSession(arl)` gives you an
+ * isolated one whose `session.gw(...)` / `session.getTrackInfo(...)` don't share
+ * this cache.
+ */
+/** POST `gateway.php` (main gw channel). */
+const request = (body, method) => (0, session_1.defaultSession)().gw(body, method);
+exports.request = request;
+/** POST `gw-light.php` (search / suggest / lighter methods). */
+const requestLight = (body, method) => (0, session_1.defaultSession)().gwLight(body, method);
+exports.requestLight = requestLight;
+/** GET `gateway.php` (app_page_get, user_getInfo, …). */
+const requestGet = (method, params = {}, key = 'get_request') => (0, session_1.defaultSession)().gwGet(method, params, key);
+exports.requestGet = requestGet;
+/**
+ * GET the public REST API (`api.deezer.com`). Account-independent, so it keeps
+ * its own process-wide cache rather than a per-session one.
  */
-const inFlight = new Map();
-const coalesce = (cacheKey, fetcher) => {
-    const cached = cache_1.default.get(cacheKey);
+const inFlightPublic = new Map();
+const requestPublicApi = (slug) => {
+    const cached = cache_1.default.get(slug);
     if (cached) {
         return Promise.resolve(cached);
     }
-    const pending = inFlight.get(cacheKey);
+    const pending = inFlightPublic.get(slug);
     if (pending) {
         return pending;
     }
     const promise = (async () => {
         try {
-            return await fetcher();
+            const { data } = await request_1.default.get('https://api.deezer.com' + slug);
+            if (data.error) {
+                throw new errors_1.DeezerError(data.error);
+            }
+            cache_1.default.set(slug, data);
+            return data;
         }
         finally {
-            inFlight.delete(cacheKey);
+            inFlightPublic.delete(slug);
         }
     })();
-    inFlight.set(cacheKey, promise);
+    inFlightPublic.set(slug, promise);
     return promise;
 };
-/**
- * Make POST requests to deezer api
- * @param {Object} body post body
- * @param {String} method request method
- */
-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 (results && Object.keys(results).length > 0) {
-            cache_1.default.set(cacheKey, results);
-            return results;
-        }
-        throw new errors_1.DeezerError(error);
-    });
-};
-exports.request = request;
-/**
- * Make POST requests to deezer api
- * @param {Object} body post body
- * @param {String} method request method
- */
-const requestLight = async (body, method) => {
-    const cacheKey = method + ':' + Object.entries(body).join(':');
-    return coalesce(cacheKey, async () => {
-        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 (results && Object.keys(results).length > 0) {
-            cache_1.default.set(cacheKey, results);
-            return results;
-        }
-        throw new errors_1.DeezerError(error);
-    });
-};
-exports.requestLight = requestLight;
-/**
- * Make GET requests to deezer public api
- * @param {String} method request method
- * @param {Object} params request parameters
- */
-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 (results && Object.keys(results).length > 0) {
-            cache_1.default.set(cacheKey, results);
-            return results;
-        }
-        throw new errors_1.DeezerError(error);
-    });
-};
-exports.requestGet = requestGet;
-/**
- * Make GET requests to deezer public api
- * @param {String} slug endpoint
- */
-const requestPublicApi = async (slug) => {
-    return coalesce(slug, async () => {
-        const { data } = await request_1.default.get('https://api.deezer.com' + slug);
-        if (data.error) {
-            throw new errors_1.DeezerError(data.error);
-        }
-        cache_1.default.set(slug, data);
-        return data;
-    });
-};
 exports.requestPublicApi = requestPublicApi;

package/dist/converter/parse.d.ts

@@ -12,7 +12,7 @@ export declare const getUrlParts: (url: string, setToken?: boolean) => Promise<u
 export declare const parseInfo: (url: string) => Promise<{
     info: urlPartsType;
     linktype: linkType;
-    linkinfo: Record<string, any> | artistInfoType | albumType | playlistInfo;
+    linkinfo: artistInfoType | albumType | playlistInfo | Record<string, any>;
     tracks: trackType[];
 }>;
 export {};

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,152 @@
+import FastLRU from './fast-lru';
+import { HttpClient } from './http';
+import type { HttpQuery, HttpResponse } from './http';
+import type { albumTracksType, albumType, artistInfoType, discographyType, lyricsType, playlistInfo, playlistTracksType, profileType, searchType, trackType, userType } from '../types';
+type SearchEntity = 'ALBUM' | 'ARTIST' | 'TRACK' | 'PLAYLIST' | 'RADIO' | 'SHOW' | 'USER' | 'LIVESTREAM' | 'CHANNEL';
+/**
+ * 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;
+    /**
+     * This session's response cache (1000 entries / 60 min). Per-session because
+     * gateway responses carry account-specific data (e.g. `TRACK_TOKEN`). Cleared
+     * when the account changes via `init(arl)`.
+     */
+    readonly cache: FastLRU;
+    private readonly inFlight;
+    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>>;
+    /** Single-flight + LRU around a fetcher, keyed per session. */
+    private coalesce;
+    /** POST `gateway.php` — the main gw method channel. Coalesced + cached. */
+    gw<T = any>(body: Record<string, unknown>, method: string): Promise<T>;
+    /** POST `gw-light.php` — the lighter method channel (search, suggest, …). */
+    gwLight<T = any>(body: Record<string, unknown>, method: string): Promise<T>;
+    /** GET `gateway.php` — used for `app_page_get` and the like. */
+    gwGet<T = any>(method: string, params?: Record<string, any>, key?: string): Promise<T>;
+    /** The logged-in user's profile. */
+    getUser(): Promise<userType>;
+    /** `song.getData` for a track — includes this session's `TRACK_TOKEN`. */
+    getTrackInfo(sngId: string): Promise<trackType>;
+    /** `song.getLyrics` — plain + time-synced lyrics. */
+    getLyrics(sngId: string): Promise<lyricsType>;
+    /** `album.getData`. */
+    getAlbumInfo(albId: string): Promise<albumType>;
+    /** All of an album's tracks (`song.getListByAlbum`). */
+    getAlbumTracks(albId: string): Promise<albumTracksType>;
+    /** `playlist.getData`. */
+    getPlaylistInfo(playlistId: string): Promise<playlistInfo>;
+    /** All of a playlist's tracks, with `TRACK_POSITION` filled in. */
+    getPlaylistTracks(playlistId: string): Promise<playlistTracksType>;
+    /** `artist.getData`. */
+    getArtistInfo(artId: string): Promise<artistInfoType>;
+    /** An artist's discography (`album.getDiscography`). */
+    getDiscography(artId: string, nb?: number): Promise<discographyType>;
+    /** A public profile (`mobile.pageUser`). */
+    getProfile(userId: string): Promise<profileType>;
+    /** Search (`deezer.pageSearch`). `types` defaults to `['TRACK']`. */
+    searchMusic(query: string, types?: SearchEntity[], nb?: number): Promise<searchType>;
+}
+/** 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,359 @@
+"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 fast_lru_1 = __importDefault(require("./fast-lru"));
+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 session's response cache (1000 entries / 60 min). Per-session because
+         * gateway responses carry account-specific data (e.g. `TRACK_TOKEN`). Cleared
+         * when the account changes via `init(arl)`.
+         */
+        this.cache = new fast_lru_1.default({ maxSize: 1000, ttl: 60 * 60000 });
+        this.inFlight = new Map();
+        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;
+            this.cache.clear();
+        }
+        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);
+        }
+    }
+    // ─── Cached request primitives ──────────────────────────────────────────────
+    /** Single-flight + LRU around a fetcher, keyed per session. */
+    coalesce(key, fetcher) {
+        const cached = this.cache.get(key);
+        if (cached) {
+            return Promise.resolve(cached);
+        }
+        const pending = this.inFlight.get(key);
+        if (pending) {
+            return pending;
+        }
+        const promise = (async () => {
+            try {
+                return await fetcher();
+            }
+            finally {
+                this.inFlight.delete(key);
+            }
+        })();
+        this.inFlight.set(key, promise);
+        return promise;
+    }
+    /** POST `gateway.php` — the main gw method channel. Coalesced + cached. */
+    gw(body, method) {
+        const key = `gw:${method}:${Object.entries(body).join(':')}`;
+        return this.coalesce(key, async () => {
+            const { data: { error, results }, } = await this.request('POST', '/gateway.php', body, { params: { method } });
+            if (results && Object.keys(results).length > 0) {
+                this.cache.set(key, results);
+                return results;
+            }
+            throw new errors_1.DeezerError(error);
+        });
+    }
+    /** POST `gw-light.php` — the lighter method channel (search, suggest, …). */
+    gwLight(body, method) {
+        const key = `gwl:${method}:${Object.entries(body).join(':')}`;
+        return this.coalesce(key, async () => {
+            const { data: { error, results }, } = await this.request('POST', 'https://www.deezer.com/ajax/gw-light.php', body, {
+                params: { method, api_version: '1.0' },
+            });
+            if (results && Object.keys(results).length > 0) {
+                this.cache.set(key, results);
+                return results;
+            }
+            throw new errors_1.DeezerError(error);
+        });
+    }
+    /** GET `gateway.php` — used for `app_page_get` and the like. */
+    gwGet(method, params = {}, key = 'get_request') {
+        const cacheKey = `gwget:${method}:${key}`;
+        return this.coalesce(cacheKey, async () => {
+            const { data: { error, results }, } = await this.request('GET', '/gateway.php', undefined, {
+                params: { method, ...params },
+            });
+            if (results && Object.keys(results).length > 0) {
+                this.cache.set(cacheKey, results);
+                return results;
+            }
+            throw new errors_1.DeezerError(error);
+        });
+    }
+    // ─── Query methods (this account's view) ────────────────────────────────────
+    /** The logged-in user's profile. */
+    getUser() {
+        return this.gwGet('user_getInfo');
+    }
+    /** `song.getData` for a track — includes this session's `TRACK_TOKEN`. */
+    getTrackInfo(sngId) {
+        return this.gw({ sng_id: sngId }, 'song.getData');
+    }
+    /** `song.getLyrics` — plain + time-synced lyrics. */
+    getLyrics(sngId) {
+        return this.gw({ sng_id: sngId }, 'song.getLyrics');
+    }
+    /** `album.getData`. */
+    getAlbumInfo(albId) {
+        return this.gw({ alb_id: albId }, 'album.getData');
+    }
+    /** All of an album's tracks (`song.getListByAlbum`). */
+    getAlbumTracks(albId) {
+        return this.gw({ alb_id: albId, lang: 'us', nb: -1 }, 'song.getListByAlbum');
+    }
+    /** `playlist.getData`. */
+    getPlaylistInfo(playlistId) {
+        return this.gw({ playlist_id: playlistId, lang: 'en' }, 'playlist.getData');
+    }
+    /** All of a playlist's tracks, with `TRACK_POSITION` filled in. */
+    async getPlaylistTracks(playlistId) {
+        const res = await this.gw({ playlist_id: playlistId, lang: 'en', nb: -1, start: 0, tab: 0, tags: true, header: true }, 'playlist.getSongs');
+        res.data = res.data.map((t, i) => {
+            t.TRACK_POSITION = i + 1;
+            return t;
+        });
+        return res;
+    }
+    /** `artist.getData`. */
+    getArtistInfo(artId) {
+        return this.gw({ art_id: artId, filter_role_id: [0], lang: 'en', tab: 0, nb: -1, start: 0 }, 'artist.getData');
+    }
+    /** An artist's discography (`album.getDiscography`). */
+    getDiscography(artId, nb = 500) {
+        return this.gw({ art_id: artId, filter_role_id: [0], lang: 'en', nb, nb_songs: -1, start: 0 }, 'album.getDiscography');
+    }
+    /** A public profile (`mobile.pageUser`). */
+    getProfile(userId) {
+        return this.gw({ user_id: userId, tab: 'loved', nb: -1 }, 'mobile.pageUser');
+    }
+    /** Search (`deezer.pageSearch`). `types` defaults to `['TRACK']`. */
+    searchMusic(query, types = ['TRACK'], nb = 15) {
+        return this.gwLight({ query, start: 0, nb, suggest: true, artist_suggest: true, top_tracks: true, types }, 'deezer.pageSearch');
+    }
+}
+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/package.json

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