gerdur-core 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 2.9.0 - 2026-08-31
+
+Phase 3.2 (cont.) — downloads are session-aware. Additive.
+
+### Added
+
+- **`Session.getTrackDownloadUrl` / `resolveDownloadUrls` / `streamTrack` /
+  `getTrackBuffer`** — resolve and download **as a specific account**, so a
+  `createSession(arl)` client is now end-to-end usable.
+- **`downloadTrackBuffer(track, quality, options?)`** — download + decrypt a
+  track fully into a `Buffer` (no tagging), free-function form of
+  `session.getTrackBuffer`.
+- `getTrackDownloadUrl(track, quality, session?)`, `resolveDownloadUrls(tracks,
+  qualities?, session?)` and `streamTrackDownload(track, quality, {session})`
+  gained an optional session argument (defaults to the process default).
+
+## 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

package/README.md

@@ -114,13 +114,39 @@ module-level globals; bundling it means multiple accounts can coexist.
   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`) |
+| `getTrackDownloadUrl(track, quality)` | resolve a CDN URL **as this account** |
+| `resolveDownloadUrls(tracks, qualities?)` | batch-resolve, one request, as this account |
+| `streamTrack(track, quality, opts?)` | constant-memory stream of decrypted audio |
+| `getTrackBuffer(track, quality, opts?)` | download + decrypt fully into a `Buffer` |
+| `gw(body, method)` / `gwLight(body, method)` / `gwGet(method, params?)` | the raw coalesced request channels |
+| `init(arl?)` / `refreshApiToken()` / `loadUserData(force?)` / `invalidateUserData()` | lifecycle |
+
+The free `getTrackDownloadUrl(track, quality, session?)` / `resolveDownloadUrls(…, session?)`
+/ `streamTrackDownload(…, {session})` all take an optional session too;
+`downloadTrackBuffer(track, quality, opts?)` is the free-function form of
+`session.getTrackBuffer`.
+
 ```js
 await initDeezerApi(arl);                 // default session, as before
 const track = await getTrackInfo('3135556');
 
-const s = await createSession(otherArl);  // a second account, isolated
+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);`

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,3 +1,4 @@
+import './lib/session-augment';
 export { initDeezerApi, createSession, defaultSession, Session, RETRY_POLICY, DEFAULT_ARL } from './lib/session';
 export type { SessionUserData } from './lib/session';
 export { DeezerError } from './lib/errors';

package/dist/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 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;
+require("./lib/session-augment"); // wires the download methods onto Session.prototype
 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; } });

package/dist/lib/get-url.d.ts

@@ -1,3 +1,4 @@
+import { Session } from '../lib/session';
 import type { trackType } from '../types';
 export declare class WrongLicense extends Error {
     constructor(format: string);
@@ -34,8 +35,9 @@ export declare const formatName: (quality: Quality) => string;
 /**
  * @param track Track info json returned from `getTrackInfo`
  * @param quality 1 = 128kbps, 3 = 320kbps and 9 = flac (around 1411kbps)
+ * @param session which account to resolve for — defaults to the process default
  */
-export declare const getTrackDownloadUrl: (track: trackType, quality: number) => Promise<{
+export declare const getTrackDownloadUrl: (track: trackType, quality: number, session?: Session) => Promise<{
     trackUrl: string;
     isEncrypted: boolean;
     fileSize: number;
@@ -60,5 +62,6 @@ export interface ResolvedUrl {
  *
  * @param tracks    from `getTrackInfo` / `parseInfo` (needs `TRACK_TOKEN`, `SNG_ID`, `FILESIZE_*`)
  * @param qualities preference order — default `[9, 3, 1]` (FLAC → MP3 320 → MP3 128)
+ * @param session   which account to resolve for — defaults to the process default
  */
-export declare const resolveDownloadUrls: (tracks: trackType[], qualities?: Quality[]) => Promise<(ResolvedUrl | null)[]>;
+export declare const resolveDownloadUrls: (tracks: trackType[], qualities?: Quality[], session?: Session) => Promise<(ResolvedUrl | null)[]>;

package/dist/lib/get-url.js

@@ -8,7 +8,6 @@ const delay_1 = __importDefault(require("delay"));
 const decrypt_1 = require("../lib/decrypt");
 const errors_1 = require("../lib/errors");
 const http_1 = require("../lib/http");
-const request_1 = __importDefault(require("../lib/request"));
 const session_1 = require("../lib/session");
 class WrongLicense extends Error {
     constructor(format) {
@@ -92,11 +91,11 @@ const MEDIA_MAX_RETRIES = 3;
 const formatName = (quality) => (0, exports.toFormat)(quality);
 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) => {
+const mediaGetUrl = async (session, track_tokens, formats, attempt = 0) => {
     var _a;
-    const user = await (0, session_1.defaultSession)().loadUserData();
+    const user = await session.loadUserData();
     try {
-        const { data } = await request_1.default.post('https://media.deezer.com/v1/get_url', {
+        const { data } = await session.request('POST', 'https://media.deezer.com/v1/get_url', {
             license_token: user.licenseToken,
             media: [{ type: 'FULL', formats }],
             track_tokens,
@@ -107,9 +106,9 @@ const mediaGetUrl = async (track_tokens, formats, attempt = 0) => {
         const status = err instanceof http_1.HttpStatusError ? err.statusCode : 0;
         if ((status === 403 || status === 429 || status >= 500) && attempt < MEDIA_MAX_RETRIES) {
             // a stale license token is a common cause — force a refresh before the retry
-            await (0, session_1.defaultSession)().loadUserData(true);
+            await session.loadUserData(true);
             await (0, delay_1.default)(500 * 2 ** attempt + Math.floor(Math.random() * 250));
-            return mediaGetUrl(track_tokens, formats, attempt + 1);
+            return mediaGetUrl(session, track_tokens, formats, attempt + 1);
         }
         throw err;
     }
@@ -132,12 +131,12 @@ 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 = await (0, session_1.defaultSession)().loadUserData();
+const getTrackUrlFromServer = async (session, track_token, format) => {
+    const user = await session.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' }]);
+    const { data, country } = await mediaGetUrl(session, [track_token], [{ format, cipher: 'BF_CBC_STRIPE' }]);
     if (!data.length)
         return null;
     return parseMediaEntry(data[0], track_token, country);
@@ -145,8 +144,9 @@ const getTrackUrlFromServer = async (track_token, format) => {
 /**
  * @param track Track info json returned from `getTrackInfo`
  * @param quality 1 = 128kbps, 3 = 320kbps and 9 = flac (around 1411kbps)
+ * @param session which account to resolve for — defaults to the process default
  */
-const getTrackDownloadUrl = async (track, quality) => {
+const getTrackDownloadUrl = async (track, quality, session = (0, session_1.defaultSession)()) => {
     let wrongLicense = null;
     let geoBlocked = null;
     let expiredToken = null;
@@ -161,7 +161,7 @@ const getTrackDownloadUrl = async (track, quality) => {
     else {
         // Get URL with the official API
         try {
-            const resolved = await getTrackUrlFromServer(track.TRACK_TOKEN, format);
+            const resolved = await getTrackUrlFromServer(session, track.TRACK_TOKEN, format);
             if (resolved) {
                 return {
                     trackUrl: resolved.url,
@@ -237,12 +237,13 @@ const testUrl = async (url) => {
  *
  * @param tracks    from `getTrackInfo` / `parseInfo` (needs `TRACK_TOKEN`, `SNG_ID`, `FILESIZE_*`)
  * @param qualities preference order — default `[9, 3, 1]` (FLAC → MP3 320 → MP3 128)
+ * @param session   which account to resolve for — defaults to the process default
  */
-const resolveDownloadUrls = async (tracks, qualities = [9, 3, 1]) => {
+const resolveDownloadUrls = async (tracks, qualities = [9, 3, 1], session = (0, session_1.defaultSession)()) => {
     if (!tracks.length)
         return [];
     const formats = qualities.map((q) => ({ format: (0, exports.formatName)(q), cipher: 'BF_CBC_STRIPE' }));
-    const { data, country } = await mediaGetUrl(tracks.map((t) => t.TRACK_TOKEN), formats);
+    const { data, country } = await mediaGetUrl(session, tracks.map((t) => t.TRACK_TOKEN), formats);
     return tracks.map((track, i) => {
         let parsed;
         try {

package/dist/lib/session-augment.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+import type { Quality, ResolvedUrl } from './get-url';
+import type { StreamTrackOptions, TrackStream } from './stream-download';
+import type { trackType } from '../types';
+declare module './session' {
+    interface Session {
+        /** Resolve a downloadable URL for a track **as this account** (`1 | 3 | 9`). */
+        getTrackDownloadUrl(track: trackType, quality: number): Promise<{
+            trackUrl: string;
+            isEncrypted: boolean;
+            fileSize: number;
+        } | null>;
+        /** Batch-resolve download URLs for many tracks in one request, as this account. */
+        resolveDownloadUrls(tracks: trackType[], qualities?: Quality[]): Promise<(ResolvedUrl | null)[]>;
+        /** Download a track as a constant-memory stream of decrypted audio, as this account. */
+        streamTrack(track: trackType, quality: number, options?: Omit<StreamTrackOptions, 'session'>): Promise<TrackStream>;
+        /** Download + decrypt a track fully into a `Buffer`, as this account. */
+        getTrackBuffer(track: trackType, quality: number, options?: Omit<StreamTrackOptions, 'session' | 'resumeFrom'>): Promise<Buffer | null>;
+    }
+}

package/dist/lib/session-augment.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Download methods on {@link Session}, kept in a separate module so `session.ts`
+ * doesn't have to import the download stack (which imports `session.ts` back).
+ * `import`ing this file for its side effect wires the methods onto the prototype;
+ * `src/index.ts` does that.
+ */
+const get_url_1 = require("./get-url");
+const session_1 = require("./session");
+const stream_download_1 = require("./stream-download");
+session_1.Session.prototype.getTrackDownloadUrl = function (track, quality) {
+    return (0, get_url_1.getTrackDownloadUrl)(track, quality, this);
+};
+session_1.Session.prototype.resolveDownloadUrls = function (tracks, qualities) {
+    return (0, get_url_1.resolveDownloadUrls)(tracks, qualities, this);
+};
+session_1.Session.prototype.streamTrack = function (track, quality, options = {}) {
+    return (0, stream_download_1.streamTrackDownload)(track, quality, { ...options, session: this });
+};
+session_1.Session.prototype.getTrackBuffer = function (track, quality, options = {}) {
+    return (0, stream_download_1.downloadTrackBuffer)(track, quality, { ...options, session: this });
+};

package/dist/lib/session.d.ts

@@ -1,5 +1,8 @@
+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` /
@@ -56,6 +59,13 @@ export declare class Session {
     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);
@@ -92,6 +102,36 @@ export declare class Session {
      * 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;

package/dist/lib/session.js

@@ -6,6 +6,7 @@ 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
@@ -51,6 +52,13 @@ const USER_DATA_TTL_MS = 25 * 60 * 1000;
  */
 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;
@@ -115,6 +123,7 @@ class Session {
             }
             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: '' },
@@ -207,6 +216,118 @@ class Session {
             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();

package/dist/lib/stream-download.d.ts

@@ -1,5 +1,7 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import { Readable } from 'stream';
+import type { Session } from './session';
 import type { trackType } from '../types';
 export interface StreamTrackOptions {
     /**
@@ -10,6 +12,8 @@ export interface StreamTrackOptions {
     resumeFrom?: number;
     /** progress callback — `(bytesReceived, totalBytes)`; `total` is 0 when unknown */
     onProgress?: (received: number, total: number) => void;
+    /** which account to download as — defaults to the process default session */
+    session?: Session;
 }
 export interface TrackStream {
     /** decrypted audio bytes, ready to pipe to a file or a tag muxer */
@@ -35,3 +39,10 @@ export interface TrackStream {
  *   track+quality can't be resolved at all.
  */
 export declare const streamTrackDownload: (track: trackType, quality: number, options?: StreamTrackOptions) => Promise<TrackStream>;
+/**
+ * Download + decrypt a track fully into memory. Convenience over
+ * {@link streamTrackDownload} for callers that just want the bytes (no tagging —
+ * pipe through `addTrackTags` yourself). `null` when the track+quality can't be
+ * resolved. Does **not** support resume.
+ */
+export declare const downloadTrackBuffer: (track: trackType, quality: number, options?: Omit<StreamTrackOptions, 'resumeFrom'>) => Promise<Buffer | null>;

package/dist/lib/stream-download.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.streamTrackDownload = void 0;
+exports.downloadTrackBuffer = exports.streamTrackDownload = void 0;
 const stream_1 = require("stream");
 const decrypt_1 = require("./decrypt");
 const http_1 = require("./http");
@@ -20,7 +20,7 @@ const CHUNK = 2048;
  *   track+quality can't be resolved at all.
  */
 const streamTrackDownload = async (track, quality, options = {}) => {
-    const resolved = await (0, get_url_1.getTrackDownloadUrl)(track, quality);
+    const resolved = await (0, get_url_1.getTrackDownloadUrl)(track, quality, options.session);
     if (!resolved) {
         throw new Error(`Track ${track.SNG_ID} is unavailable at quality ${quality}`);
     }
@@ -52,3 +52,27 @@ const streamTrackDownload = async (track, quality, options = {}) => {
     };
 };
 exports.streamTrackDownload = streamTrackDownload;
+/**
+ * Download + decrypt a track fully into memory. Convenience over
+ * {@link streamTrackDownload} for callers that just want the bytes (no tagging —
+ * pipe through `addTrackTags` yourself). `null` when the track+quality can't be
+ * resolved. Does **not** support resume.
+ */
+const downloadTrackBuffer = async (track, quality, options = {}) => {
+    let ts;
+    try {
+        ts = await (0, exports.streamTrackDownload)(track, quality, { onProgress: options.onProgress, session: options.session });
+    }
+    catch (err) {
+        if (err instanceof Error && /unavailable at quality/.test(err.message)) {
+            return null;
+        }
+        throw err;
+    }
+    const chunks = [];
+    for await (const chunk of ts.stream) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+};
+exports.downloadTrackBuffer = downloadTrackBuffer;

package/package.json

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