gerdur-core 2.9.0 → 2.11.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 2.11.0 - 2026-08-31
+
+### Added
+
+- **`searchFacets(result)`** — flatten the per-type hit counts + Deezer's
+  relevance `order` out of a `searchMusic` result.
+
+### Internal
+
+- The live-API test suite skips more gracefully when an upstream (Deezer public
+  REST, Tidal, YouTube) rate-limits or consent-walls the runner — the
+  `--> DEEZER` converter tests and YouTube tests now degrade to a skip instead
+  of a hard fail.
+
+## 2.10.0 - 2026-08-31
+
+Leftovers — batch token refresh + podcast episodes. Additive.
+
+### Added
+
+- **`refreshTrackTokens(tracks, {graceSeconds?, session?})`** — one
+  `song.getListData` request refreshes every `TRACK_TOKEN` that has expired (or
+  is about to). Run a long playlist through this before `resolveDownloadUrls` so
+  it doesn't die on stale tokens at track 40. Also `session.refreshTrackTokens`.
+- **`getEpisode(episodeId)`** (`episode.getData`) and **`getShowEpisodes(showId,
+  nb?, start?)`** — podcast episodes; `EPISODE_DIRECT_STREAM_URL` is a plain MP3
+  (no licence, no decryption).
+
 ## 2.9.0 - 2026-08-31
 
 Phase 3.2 (cont.) — downloads are session-aware. Additive.

package/README.md

@@ -261,6 +261,16 @@ ignore the operators, so pass a plain string there.
 "as you type" UIs. `nb` (default 5) caps items per type. Needs an initialised
 session (`initDeezerApi`).
 
+### `.searchFacets(result)`
+
+Flattens the per-type hit counts + Deezer's relevance `order` out of a
+`searchMusic` result — for "207 tracks · 99 albums · 17 artists" UIs.
+
+```js
+const r = await searchMusic('daft punk', ['TRACK', 'ALBUM', 'ARTIST']);
+searchFacets(r); // {track: 207, album: 99, artist: 17, …, order: ['TOP_RESULT','TRACK',…]}
+```
+
 ### Browse & discovery
 
 Public REST endpoints — no `arl` needed, memoised like the rest. All return a
@@ -321,6 +331,13 @@ const {data: loved} = await getUserFavoriteTracks(me.USER_ID);
 const {data: eighties} = await getRadioTracks(38305);     // "The '80s"
 ```
 
+### Podcasts
+
+| Method | |
+| :--- | :--- |
+| `getShowEpisodes(showId, nb = 25, start = 0)` | a page of a show's episodes, newest first |
+| `getEpisode(episodeId)` | one episode — `EPISODE_DIRECT_STREAM_URL` is a plain MP3, no licence / decryption |
+
 ### `.getTrackDownloadUrl(track, quality);`
 
 | Parameters | Required |        Type |                        Description |
@@ -331,6 +348,19 @@ const {data: eighties} = await getRadioTracks(38305);     // "The '80s"
 Resolves `{trackUrl, isEncrypted, fileSize}`. `isEncrypted` now comes from the
 media API's `cipher` field (authoritative) rather than a URL guess.
 
+### `.refreshTrackTokens(tracks, options?);`
+
+`TRACK_TOKEN`s live ~1 hour, so a token fetched at the start of a long playlist
+download is dead by track 40 (surfacing as an opaque CDN 403). Run the selection
+through this first — **one** `song.getListData` request refreshes every token
+that has expired (or expires within `options.graceSeconds`, default 300).
+Tracks with a still-valid token come back untouched. Also `session.refreshTrackTokens(tracks, graceSeconds?)`.
+
+```js
+const fresh = await refreshTrackTokens(playlist.tracks);
+const urls = await resolveDownloadUrls(fresh, [9, 3, 1]);
+```
+
 ### Formats
 
 Deezer's `get_url` understands more than `1 / 3 / 9`. `DEEZER_FORMATS` lists them

package/dist/api/index.d.ts

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

package/dist/api/index.js

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

package/dist/api/podcast.d.ts

@@ -0,0 +1,16 @@
+import type { publicApiList, showEpisodeType } from '../types';
+/**
+ * One podcast episode (`episode.getData`). Carries `EPISODE_DIRECT_STREAM_URL`
+ * (a plain MP3 — no licence, no decryption) plus `MD5_ORIGIN` / `FILESIZE_MP3_*`
+ * / `TRACK_TOKEN` for the licensed stream.
+ */
+export declare const getEpisode: (episodeId: string) => Promise<showEpisodeType>;
+/**
+ * A page of a show's episodes, newest first — a thin view over `getShowInfo`'s
+ * `EPISODES` block.
+ *
+ * @param showId `SHOW_ID`
+ * @param nb     page size (default 25)
+ * @param start  offset
+ */
+export declare const getShowEpisodes: (showId: string, nb?: number, start?: number) => Promise<publicApiList<showEpisodeType>>;

package/dist/api/podcast.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getShowEpisodes = exports.getEpisode = void 0;
+const request_1 = require("./request");
+const api_1 = require("./api");
+/**
+ * One podcast episode (`episode.getData`). Carries `EPISODE_DIRECT_STREAM_URL`
+ * (a plain MP3 — no licence, no decryption) plus `MD5_ORIGIN` / `FILESIZE_MP3_*`
+ * / `TRACK_TOKEN` for the licensed stream.
+ */
+const getEpisode = (episodeId) => (0, request_1.request)({ episode_id: episodeId }, 'episode.getData');
+exports.getEpisode = getEpisode;
+/**
+ * A page of a show's episodes, newest first — a thin view over `getShowInfo`'s
+ * `EPISODES` block.
+ *
+ * @param showId `SHOW_ID`
+ * @param nb     page size (default 25)
+ * @param start  offset
+ */
+const getShowEpisodes = async (showId, nb = 25, start = 0) => {
+    const { EPISODES } = await (0, api_1.getShowInfo)(showId, nb, start);
+    return { data: EPISODES.data, total: EPISODES.total };
+};
+exports.getShowEpisodes = getShowEpisodes;

package/dist/api/search.d.ts

@@ -1,4 +1,4 @@
-import type { advancedSearchFilters, publicApiSearchOptions, publicApiSearchResponse, searchResultAlbum, searchResultArtist, searchResultPlaylist, searchResultTrack, suggestResult } from '../types';
+import type { advancedSearchFilters, publicApiSearchOptions, publicApiSearchResponse, searchResultAlbum, searchResultArtist, searchResultPlaylist, searchResultTrack, searchType, suggestResult } from '../types';
 /**
  * Compose Deezer's advanced search operators into one query string.
  *
@@ -47,3 +47,21 @@ export declare const searchPlaylists: (query: string, options?: Omit<publicApiSe
  * @param nb    max items per type (default 5)
  */
 export declare const suggest: (query: string, nb?: number) => Promise<suggestResult>;
+/** Per-type total hit counts + Deezer's own relevance ordering, from a `searchMusic` result. */
+export interface SearchFacets {
+    track: number;
+    album: number;
+    artist: number;
+    playlist: number;
+    radio: number;
+    show: number;
+    user: number;
+    /** the type order Deezer considers most relevant for this query, e.g. `['TOP_RESULT','ARTIST','TRACK',…]` */
+    order: string[];
+}
+/**
+ * Pull the facet counts out of a `searchMusic` (`deezer.pageSearch`) result —
+ * `pageSearch` already returns `TRACK.total`, `ALBUM.total`, … and an `ORDER`;
+ * this just surfaces them in one flat object for "N tracks · M albums · …" UIs.
+ */
+export declare const searchFacets: (result: searchType) => SearchFacets;

package/dist/api/search.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.suggest = exports.searchPlaylists = exports.searchArtists = exports.searchAlbums = exports.searchTracks = exports.searchPublicApi = exports.buildAdvancedQuery = void 0;
+exports.searchFacets = exports.suggest = exports.searchPlaylists = exports.searchArtists = exports.searchAlbums = exports.searchTracks = exports.searchPublicApi = exports.buildAdvancedQuery = void 0;
 const request_1 = require("./request");
 /**
  * Compose Deezer's advanced search operators into one query string.
@@ -108,3 +108,22 @@ const suggest = (query, nb = 5) => (0, request_1.requestLight)({
     TYPES: { ALBUM: true, ARTIST: true, TRACK: true, PLAYLIST: true, RADIO: true, SHOW: true },
 }, 'deezer.suggest');
 exports.suggest = suggest;
+/**
+ * Pull the facet counts out of a `searchMusic` (`deezer.pageSearch`) result —
+ * `pageSearch` already returns `TRACK.total`, `ALBUM.total`, … and an `ORDER`;
+ * this just surfaces them in one flat object for "N tracks · M albums · …" UIs.
+ */
+const searchFacets = (result) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+    return ({
+        track: (_b = (_a = result.TRACK) === null || _a === void 0 ? void 0 : _a.total) !== null && _b !== void 0 ? _b : 0,
+        album: (_d = (_c = result.ALBUM) === null || _c === void 0 ? void 0 : _c.total) !== null && _d !== void 0 ? _d : 0,
+        artist: (_f = (_e = result.ARTIST) === null || _e === void 0 ? void 0 : _e.total) !== null && _f !== void 0 ? _f : 0,
+        playlist: (_h = (_g = result.PLAYLIST) === null || _g === void 0 ? void 0 : _g.total) !== null && _h !== void 0 ? _h : 0,
+        radio: (_k = (_j = result.RADIO) === null || _j === void 0 ? void 0 : _j.total) !== null && _k !== void 0 ? _k : 0,
+        show: (_m = (_l = result.SHOW) === null || _l === void 0 ? void 0 : _l.total) !== null && _m !== void 0 ? _m : 0,
+        user: (_p = (_o = result.USER) === null || _o === void 0 ? void 0 : _o.total) !== null && _p !== void 0 ? _p : 0,
+        order: (_q = result.ORDER) !== null && _q !== void 0 ? _q : [],
+    });
+};
+exports.searchFacets = searchFacets;

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

@@ -65,3 +65,21 @@ export interface ResolvedUrl {
  * @param session   which account to resolve for — defaults to the process default
  */
 export declare const resolveDownloadUrls: (tracks: trackType[], qualities?: Quality[], session?: Session) => Promise<(ResolvedUrl | null)[]>;
+/**
+ * Batch-refresh `TRACK_TOKEN`s that have (or are about to) expire — one
+ * `song.getListData` request for the lot, instead of a `getTrackInfo` per track.
+ * `TRACK_TOKEN`s live ~1 hour, so a token fetched at the start of a long
+ * playlist download is dead by track 40 and surfaces as an opaque CDN 403; run
+ * the selection through this first.
+ *
+ * Returns the input tracks with fresh `TRACK_TOKEN` / `TRACK_TOKEN_EXPIRE`
+ * merged in; tracks whose token is still comfortably valid are returned as-is.
+ *
+ * @param tracks  from `getTrackInfo` / `getAlbumTracks` / `parseInfo`
+ * @param options `graceSeconds` — treat a token expiring within this window as
+ *   stale (default 300); `session` — which account (default: process default)
+ */
+export declare const refreshTrackTokens: (tracks: trackType[], options?: {
+    graceSeconds?: number;
+    session?: Session;
+}) => Promise<trackType[]>;

package/dist/lib/get-url.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.formatName = exports.toFormat = exports.DEEZER_FORMATS = exports.ExpiredTrackToken = exports.GeoBlocked = exports.WrongLicense = void 0;
+exports.refreshTrackTokens = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.formatName = exports.toFormat = exports.DEEZER_FORMATS = exports.ExpiredTrackToken = exports.GeoBlocked = exports.WrongLicense = void 0;
 const delay_1 = __importDefault(require("delay"));
 const decrypt_1 = require("../lib/decrypt");
 const errors_1 = require("../lib/errors");
@@ -265,3 +265,35 @@ const resolveDownloadUrls = async (tracks, qualities = [9, 3, 1], session = (0,
     });
 };
 exports.resolveDownloadUrls = resolveDownloadUrls;
+/**
+ * Batch-refresh `TRACK_TOKEN`s that have (or are about to) expire — one
+ * `song.getListData` request for the lot, instead of a `getTrackInfo` per track.
+ * `TRACK_TOKEN`s live ~1 hour, so a token fetched at the start of a long
+ * playlist download is dead by track 40 and surfaces as an opaque CDN 403; run
+ * the selection through this first.
+ *
+ * Returns the input tracks with fresh `TRACK_TOKEN` / `TRACK_TOKEN_EXPIRE`
+ * merged in; tracks whose token is still comfortably valid are returned as-is.
+ *
+ * @param tracks  from `getTrackInfo` / `getAlbumTracks` / `parseInfo`
+ * @param options `graceSeconds` — treat a token expiring within this window as
+ *   stale (default 300); `session` — which account (default: process default)
+ */
+const refreshTrackTokens = async (tracks, options = {}) => {
+    var _a, _b;
+    const session = (_a = options.session) !== null && _a !== void 0 ? _a : (0, session_1.defaultSession)();
+    const graceMs = ((_b = options.graceSeconds) !== null && _b !== void 0 ? _b : 300) * 1000;
+    const now = Date.now();
+    const staleIds = new Set(tracks
+        .filter((t) => !t.TRACK_TOKEN || !t.TRACK_TOKEN_EXPIRE || t.TRACK_TOKEN_EXPIRE * 1000 - now < graceMs)
+        .map((t) => t.SNG_ID));
+    if (!staleIds.size)
+        return tracks;
+    const { data } = await session.gw({ sng_ids: [...staleIds] }, 'song.getListData');
+    const fresh = new Map(data.map((d) => [d.SNG_ID, d]));
+    return tracks.map((track) => {
+        const f = fresh.get(track.SNG_ID);
+        return f ? { ...track, TRACK_TOKEN: f.TRACK_TOKEN, TRACK_TOKEN_EXPIRE: Number(f.TRACK_TOKEN_EXPIRE) } : track;
+    });
+};
+exports.refreshTrackTokens = refreshTrackTokens;

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

@@ -16,5 +16,7 @@ declare module './session' {
         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>;
+        /** Batch-refresh the `TRACK_TOKEN`s on these tracks (as this account) before a long download. */
+        refreshTrackTokens(tracks: trackType[], graceSeconds?: number): Promise<trackType[]>;
     }
 }

package/dist/lib/session-augment.js

@@ -21,3 +21,6 @@ session_1.Session.prototype.streamTrack = function (track, quality, options = {}
 session_1.Session.prototype.getTrackBuffer = function (track, quality, options = {}) {
     return (0, stream_download_1.downloadTrackBuffer)(track, quality, { ...options, session: this });
 };
+session_1.Session.prototype.refreshTrackTokens = function (tracks, graceSeconds) {
+    return (0, get_url_1.refreshTrackTokens)(tracks, { graceSeconds, session: this });
+};

package/package.json

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