gerdur 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2.9.0 - 2026-08-31
+
+### Added
+
+- **`gerdur-core@^2.11.0`** — re-exports `searchFacets` (per-type hit counts +
+  Deezer's relevance `ORDER` from a `searchMusic` result).
+- Plain-text search in the interactive prompt now shows a hint — *"also N albums
+  · M artists · P playlists (prefix with `album:` / `artist:` / `playlist:` …)"* —
+  so you know the other result types are there.
+
+## 2.8.0 - 2026-08-31
+
+### Added
+
+- **`gerdur-core@^2.10.0`** — re-exports `refreshTrackTokens`, `getEpisode`,
+  `getShowEpisodes`.
+- **CLI `artist-top:<id>`** — pick from an artist's most popular tracks.
+- **CLI `episode:<id>`** — download a single podcast episode (plain MP3, no
+  `--quality` needed, saved to `Podcasts/`).
+
+### Changed
+
+- Batch downloads (album / playlist / search selection) now **refresh stale
+  `TRACK_TOKEN`s** before resolving URLs — a long playlist no longer starts
+  failing partway through with opaque CDN 403s.
+
 ## 2.7.0 - 2026-08-31
 
 ### Added

package/README.md

@@ -163,6 +163,8 @@ When `gerdur` asks for a URL, a search term, or a prefixed query:
 | `flow:2064440442` | pick tracks from another user's Flow |
 | `radio:38305` | pick tracks from a radio's current playlist |
 | `chart` / `chart:132` | pick tracks from this week's chart (optionally a genre) |
+| `artist-top:27` | pick from an artist's most popular tracks |
+| `episode:294961882` | download a single podcast episode (plain MP3, to `Podcasts/`) |
 
 `isrc:` / `upc:` / `flow` / `radio:` also work in `--headless` mode (`-u flow`, …).
 
@@ -319,8 +321,8 @@ or `createSession`):
 - **Query** — `parseInfo`, `getUser`, `getTrackInfo`, `getAlbumInfo`,
   `getAlbumTracks`, `getPlaylistInfo`, `getPlaylistTracks`, `getArtistInfo`,
   `getDiscography`, `getLyrics`
-- **Search** — `searchMusic`, `searchPublicApi`, `searchTracks`, `searchAlbums`,
-  `searchArtists`, `searchPlaylists`, `buildAdvancedQuery`, `suggest`
+- **Search** — `searchMusic`, `searchFacets`, `searchPublicApi`, `searchTracks`,
+  `searchAlbums`, `searchArtists`, `searchPlaylists`, `buildAdvancedQuery`, `suggest`
 - **Browse** — `getGenres`, `getChart`, `getChartTracks`, `getGenreArtists`,
   `getEditorialList`, `getEditorialReleases`, `getEditorialSelection`,
   `getEditorialCharts`, `getArtistTopTracks`, `getRelatedArtists`,
@@ -329,10 +331,11 @@ or `createSession`):
 - **Flow / library** — `getUserFlow`, `getUserFavoriteTracks`,
   `getUserFavoriteAlbums`, `getUserFavoriteArtists`, `getUserPlaylists`,
   `getUserRadios`, `getUserChartTracks`, `getRadios`, `getRadioTracks`,
-  `getRadioGenres`
+  `getRadioGenres`, `getEpisode`, `getShowEpisodes`
 - **Download** — `getTrackDownloadUrl`, `resolveDownloadUrls`,
-  `streamTrackDownload`, `downloadTrackBuffer`, `createDecryptStream`, `getStream`,
-  `getTrackPreview`, `downloadPreview`, `formatName`, `toFormat`, `DEEZER_FORMATS`
+  `refreshTrackTokens`, `streamTrackDownload`, `downloadTrackBuffer`,
+  `createDecryptStream`, `getStream`, `getTrackPreview`, `downloadPreview`,
+  `formatName`, `toFormat`, `DEEZER_FORMATS`
 - **Errors** — `DeezerError` (`code` / `keys` / `retryable`), `GeoBlocked`
 - **Low-level sessions** — `createCoreSession(arl)` / `CoreSession` /
   `defaultSession` from `gerdur-core`: an isolated client (its own `arl`, cache,

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gerdur",
-    "version": "2.7.0",
+    "version": "2.9.0",
     "description": "The crucial streaming module for dabox systems.",
     "author": "Christian",
     "license": "SEE LICENSE IN LICENSE",
@@ -48,7 +48,7 @@
         "adm-zip": "^0.5.16",
         "chalk": "^4.1.2",
         "commander": "^9.5.0",
-        "gerdur-core": "^2.9.0",
+        "gerdur-core": "^2.11.0",
         "dot-prop": "^6.0.1",
         "got": "^11.8.6",
         "gradient-string": "^2.0.2",

package/dist/src/gerdur.js

@@ -9,6 +9,7 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const commander_1 = require("commander");
 const gradient_string_1 = __importDefault(require("gradient-string"));
+const got_1 = __importDefault(require("got"));
 const gerdur_core_1 = require("gerdur-core");
 const prompts_1 = __importDefault(require("prompts"));
 const log_update_1 = __importDefault(require("log-update"));
@@ -80,7 +81,8 @@ const toFiniteNumber = (value) => {
 };
 const advancedFilters = (0, search_1.advancedFiltersFromFlags)(options);
 let advancedFiltersConsumed = false;
-if (options.headless && !options.quality && !options.preview) {
+const isEpisodeUrl = String(options.url ?? '').startsWith('episode:');
+if (options.headless && !options.quality && !options.preview && !isEpisodeUrl) {
     console.error(signale_1.default.error('Missing parameters --quality'));
     console.error(signale_1.default.note('Quality must be provided with headless mode'));
     process.exit(1);
@@ -107,14 +109,9 @@ const stampVersion = (t) => {
     return t;
 };
 /**
- * Run an advanced (public-REST) track search, let the user pick, and hydrate the
- * picks into download-ready gw tracks via `getTrackInfo`. Returns `null` when
- * nothing was matched or selected.
- */
-/**
- * Given a list of public-API track objects (from search / flow / a radio), let
- * the user pick (unless headless) and hydrate the picks into download-ready gw
- * tracks via `getTrackInfo`.
+ * Given a list of public-API track objects (from search / flow / a radio / a
+ * chart), let the user pick (unless headless) and hydrate the picks into
+ * download-ready gw tracks via `getTrackInfo`.
  */
 const pickAndHydrate = async (results, id) => {
     if (!results.length) {
@@ -202,7 +199,7 @@ const downloadPreviews = async (tracks, info, template, totalTracks, trackNumber
 const startDownload = async (saveLayout, url, skipPrompt) => {
     try {
         url = url ?? '';
-        if (!options.quality && !options.preview) {
+        if (!options.quality && !options.preview && !url.startsWith('episode:')) {
             const { musicQuality } = await (0, prompts_1.default)([
                 {
                     type: 'select',
@@ -236,7 +233,7 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                 {
                     type: 'text',
                     name: 'query',
-                    message: 'Enter a URL, a search term, or `search:` / `isrc:` / `upc:` / `flow` / `radio:<id>` / `chart[:<genre>]`:',
+                    message: 'Enter a URL, a search term, or a prefix (search: isrc: upc: flow radio: chart artist-top: episode:):',
                     validate: (value) => (value ? true : false),
                 },
             ], { onCancel });
@@ -298,6 +295,34 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                 throw new Error('Chart returned no tracks.');
             }
         }
+        // `artist-top:<id>` — an artist's most popular tracks.
+        if (!searchData && url && url.startsWith('artist-top:')) {
+            const aid = url.slice('artist-top:'.length).trim();
+            console.log(signale_1.default.info(`Fetching top tracks for artist ${aid}…`));
+            const { data } = await (0, gerdur_core_1.getArtistTopTracks)(aid, toFiniteNumber(options.searchLimit) ?? 50);
+            searchData = await pickAndHydrate(data, `artist-top:${aid}`);
+            if (!searchData) {
+                throw new Error(`Artist ${aid} returned no top tracks.`);
+            }
+        }
+        // `episode:<id>` — a podcast episode (a plain MP3: no licence, decryption or tagging).
+        if (!searchData && url && url.startsWith('episode:')) {
+            const eid = url.slice('episode:'.length).trim();
+            const episode = await (0, gerdur_core_1.getEpisode)(eid);
+            if (!episode.EPISODE_DIRECT_STREAM_URL) {
+                throw new Error(`Episode ${eid} has no direct stream.`);
+            }
+            const dir = options.output ? (0, path_1.dirname)(options.output) : 'Podcasts';
+            const dest = (0, path_1.join)(dir, (0, util_1.sanitizeFilename)(`${episode.SHOW_NAME} - ${episode.EPISODE_TITLE}`.slice(0, 180)) + '.mp3');
+            console.log(signale_1.default.info(`Downloading episode: ${episode.EPISODE_TITLE}`));
+            if (options.overwrite || !(0, fs_1.existsSync)(dest)) {
+                (0, fs_1.mkdirSync)(dir, { recursive: true });
+                const { body } = await (0, got_1.default)(episode.EPISODE_DIRECT_STREAM_URL, { responseType: 'buffer' });
+                (0, fs_1.writeFileSync)(dest, body);
+            }
+            console.log(signale_1.default.success(`Saved ${dest}`));
+            return;
+        }
         if (!searchData && !url.match(urlRegex)) {
             if (options.headless) {
                 throw new Error('Please provide a valid URL. Unknown URL: ' + url);
@@ -352,12 +377,17 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                 url = `https://deezer.com/us/playlist/${choice.items.PLAYLIST_ID}`;
             }
             else {
-                const { TRACK } = await (0, gerdur_core_1.searchMusic)(url, ['TRACK']);
+                const result = await (0, gerdur_core_1.searchMusic)(url, ['TRACK', 'ALBUM', 'ARTIST', 'PLAYLIST']);
+                const facets = (0, gerdur_core_1.searchFacets)(result);
+                if (facets.album || facets.artist || facets.playlist) {
+                    console.log(signale_1.default.note(`also ${facets.album} albums · ${facets.artist} artists · ${facets.playlist} playlists ` +
+                        `(prefix with album: / artist: / playlist: to pick those)`));
+                }
                 searchData = {
                     info: { type: 'track', id: url },
                     linktype: 'track',
                     linkinfo: {},
-                    tracks: TRACK.data.map(stampVersion),
+                    tracks: result.TRACK.data.map(stampVersion),
                 };
             }
         }
@@ -423,6 +453,9 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                 const prefetchedUrls = new Map();
                 if (data.tracks.length > 1 && !process.env.SIMULATE) {
                     try {
+                        // TRACK_TOKENs expire ~1h — refresh any stale ones so a long download
+                        // doesn't start failing partway through with opaque CDN 403s.
+                        data.tracks = await (0, gerdur_core_1.refreshTrackTokens)(data.tracks);
                         const base = QUALITY_PREF[String(options.quality).toLowerCase()] ?? [3, 1];
                         const pref = fallbackQuality ? base : [base[0]];
                         const resolved = await (0, gerdur_core_1.resolveDownloadUrls)(data.tracks, pref);

package/dist/src/index.d.ts

@@ -57,11 +57,11 @@ export declare const getArl: (email: string, password: string) => Promise<string
 export { createSession, Session } from './lib/session';
 export type { SessionOptions, DownloadTracksOptions, SearchType } from './lib/session';
 export { createSession as createCoreSession, Session as CoreSession, defaultSession } from 'gerdur-core';
-export type { SessionUserData } from 'gerdur-core';
+export type { SessionUserData, SearchFacets } from 'gerdur-core';
 export { getTrackBuffer, getTaggedTrack, downloadTrackToFile } from './lib/api-download';
 export type { Quality, GetTrackBufferOptions, DownloadTrackOptions, DownloadResult } from './lib/api-download';
 export { default as Config, globalConfigPath, resolveConfigFile } from './lib/config';
-export { initDeezerApi, parseInfo, searchMusic, searchPublicApi, searchTracks, searchAlbums, searchArtists, searchPlaylists, buildAdvancedQuery, suggest, getGenres, getChart, getChartTracks, getGenreArtists, getEditorialList, getEditorialReleases, getEditorialSelection, getEditorialCharts, getArtistTopTracks, getRelatedArtists, getArtistAlbums, getArtistPlaylists, getArtistRadioTracks, getUserFlow, getUserFavoriteTracks, getUserFavoriteAlbums, getUserFavoriteArtists, getUserPlaylists, getUserRadios, getUserChartTracks, getRadios, getRadioTracks, getRadioGenres, getTrackByISRC, getAlbumByUPC, getTrackPreview, downloadPreview, formatName, toFormat, DEEZER_FORMATS, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, streamTrackDownload, downloadTrackBuffer, createDecryptStream, getStream, addTrackTags, getRichAlbum, normalizeContributors, toLrc, GeoBlocked, DeezerError, } from 'gerdur-core';
+export { initDeezerApi, parseInfo, searchMusic, searchFacets, searchPublicApi, searchTracks, searchAlbums, searchArtists, searchPlaylists, buildAdvancedQuery, suggest, getGenres, getChart, getChartTracks, getGenreArtists, getEditorialList, getEditorialReleases, getEditorialSelection, getEditorialCharts, getArtistTopTracks, getRelatedArtists, getArtistAlbums, getArtistPlaylists, getArtistRadioTracks, getUserFlow, getUserFavoriteTracks, getUserFavoriteAlbums, getUserFavoriteArtists, getUserPlaylists, getUserRadios, getUserChartTracks, getRadios, getRadioTracks, getRadioGenres, getEpisode, getShowEpisodes, refreshTrackTokens, getTrackByISRC, getAlbumByUPC, getTrackPreview, downloadPreview, formatName, toFormat, DEEZER_FORMATS, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, streamTrackDownload, downloadTrackBuffer, createDecryptStream, getStream, addTrackTags, getRichAlbum, normalizeContributors, toLrc, GeoBlocked, DeezerError, } from 'gerdur-core';
 export type { AddTrackTagsOptions, TaggedTrack, TrackTagModel, RichAlbum, ResolvedUrl, NormalizedContributors, } from 'gerdur-core';
 export type { advancedSearchFilters, searchOrder, searchEntity, publicApiSearchOptions, publicApiSearchResponse, searchResultTrack, searchResultAlbum, searchResultArtist, searchResultPlaylist, suggestResult, publicApiList, chartType, chartTrack, chartAlbum, chartArtist, chartPlaylist, chartPodcast, genreType, editorialType, artistAlbumResult, userFavoriteTrack, userFavoriteAlbum, userFavoriteArtist, userPlaylistResult, radioResult, radioGenre, } from 'gerdur-core/types';
 export type { Quality as MediaFormat, DeezerFormat, TrackPreview, StreamTrackOptions, TrackStream, StreamResponse, DeezerErrorPayload, } from 'gerdur-core';

package/dist/src/index.js

@@ -33,8 +33,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTrackPreview = exports.getAlbumByUPC = exports.getTrackByISRC = exports.getRadioGenres = exports.getRadioTracks = exports.getRadios = exports.getUserChartTracks = exports.getUserRadios = exports.getUserPlaylists = exports.getUserFavoriteArtists = exports.getUserFavoriteAlbums = exports.getUserFavoriteTracks = exports.getUserFlow = exports.getArtistRadioTracks = exports.getArtistPlaylists = exports.getArtistAlbums = exports.getRelatedArtists = exports.getArtistTopTracks = exports.getEditorialCharts = exports.getEditorialSelection = exports.getEditorialReleases = exports.getEditorialList = exports.getGenreArtists = exports.getChartTracks = exports.getChart = exports.getGenres = exports.suggest = exports.buildAdvancedQuery = exports.searchPlaylists = exports.searchArtists = exports.searchAlbums = exports.searchTracks = exports.searchPublicApi = exports.searchMusic = exports.parseInfo = exports.initDeezerApi = exports.resolveConfigFile = exports.globalConfigPath = exports.Config = exports.downloadTrackToFile = exports.getTaggedTrack = exports.getTrackBuffer = exports.defaultSession = exports.CoreSession = exports.createCoreSession = exports.Session = exports.createSession = exports.getArl = exports.LoginError = exports.loginWithEmail = void 0;
-exports.DeezerError = exports.GeoBlocked = exports.toLrc = exports.normalizeContributors = exports.getRichAlbum = exports.addTrackTags = exports.getStream = exports.createDecryptStream = exports.downloadTrackBuffer = exports.streamTrackDownload = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.getLyrics = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getTrackInfo = exports.getUser = exports.DEEZER_FORMATS = exports.toFormat = exports.formatName = exports.downloadPreview = void 0;
+exports.getShowEpisodes = exports.getEpisode = exports.getRadioGenres = exports.getRadioTracks = exports.getRadios = exports.getUserChartTracks = exports.getUserRadios = exports.getUserPlaylists = exports.getUserFavoriteArtists = exports.getUserFavoriteAlbums = exports.getUserFavoriteTracks = exports.getUserFlow = exports.getArtistRadioTracks = exports.getArtistPlaylists = exports.getArtistAlbums = exports.getRelatedArtists = exports.getArtistTopTracks = exports.getEditorialCharts = exports.getEditorialSelection = exports.getEditorialReleases = exports.getEditorialList = exports.getGenreArtists = exports.getChartTracks = exports.getChart = exports.getGenres = exports.suggest = exports.buildAdvancedQuery = exports.searchPlaylists = exports.searchArtists = exports.searchAlbums = exports.searchTracks = exports.searchPublicApi = exports.searchFacets = exports.searchMusic = exports.parseInfo = exports.initDeezerApi = exports.resolveConfigFile = exports.globalConfigPath = exports.Config = exports.downloadTrackToFile = exports.getTaggedTrack = exports.getTrackBuffer = exports.defaultSession = exports.CoreSession = exports.createCoreSession = exports.Session = exports.createSession = exports.getArl = exports.LoginError = exports.loginWithEmail = void 0;
+exports.DeezerError = exports.GeoBlocked = exports.toLrc = exports.normalizeContributors = exports.getRichAlbum = exports.addTrackTags = exports.getStream = exports.createDecryptStream = exports.downloadTrackBuffer = exports.streamTrackDownload = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.getLyrics = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getTrackInfo = exports.getUser = exports.DEEZER_FORMATS = exports.toFormat = exports.formatName = exports.downloadPreview = exports.getTrackPreview = exports.getAlbumByUPC = exports.getTrackByISRC = exports.refreshTrackTokens = void 0;
 // ─── Authentication ────────────────────────────────────────────────────────
 const email_login_1 = require("./lib/email-login");
 Object.defineProperty(exports, "loginWithEmail", { enumerable: true, get: function () { return email_login_1.loginWithEmail; } });
@@ -97,6 +97,7 @@ var gerdur_core_2 = require("gerdur-core");
 Object.defineProperty(exports, "initDeezerApi", { enumerable: true, get: function () { return gerdur_core_2.initDeezerApi; } });
 Object.defineProperty(exports, "parseInfo", { enumerable: true, get: function () { return gerdur_core_2.parseInfo; } });
 Object.defineProperty(exports, "searchMusic", { enumerable: true, get: function () { return gerdur_core_2.searchMusic; } });
+Object.defineProperty(exports, "searchFacets", { enumerable: true, get: function () { return gerdur_core_2.searchFacets; } });
 Object.defineProperty(exports, "searchPublicApi", { enumerable: true, get: function () { return gerdur_core_2.searchPublicApi; } });
 Object.defineProperty(exports, "searchTracks", { enumerable: true, get: function () { return gerdur_core_2.searchTracks; } });
 Object.defineProperty(exports, "searchAlbums", { enumerable: true, get: function () { return gerdur_core_2.searchAlbums; } });
@@ -127,6 +128,9 @@ Object.defineProperty(exports, "getUserChartTracks", { enumerable: true, get: fu
 Object.defineProperty(exports, "getRadios", { enumerable: true, get: function () { return gerdur_core_2.getRadios; } });
 Object.defineProperty(exports, "getRadioTracks", { enumerable: true, get: function () { return gerdur_core_2.getRadioTracks; } });
 Object.defineProperty(exports, "getRadioGenres", { enumerable: true, get: function () { return gerdur_core_2.getRadioGenres; } });
+Object.defineProperty(exports, "getEpisode", { enumerable: true, get: function () { return gerdur_core_2.getEpisode; } });
+Object.defineProperty(exports, "getShowEpisodes", { enumerable: true, get: function () { return gerdur_core_2.getShowEpisodes; } });
+Object.defineProperty(exports, "refreshTrackTokens", { enumerable: true, get: function () { return gerdur_core_2.refreshTrackTokens; } });
 Object.defineProperty(exports, "getTrackByISRC", { enumerable: true, get: function () { return gerdur_core_2.getTrackByISRC; } });
 Object.defineProperty(exports, "getAlbumByUPC", { enumerable: true, get: function () { return gerdur_core_2.getAlbumByUPC; } });
 Object.defineProperty(exports, "getTrackPreview", { enumerable: true, get: function () { return gerdur_core_2.getTrackPreview; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "The crucial streaming module for dabox systems.",
   "author": "Christian",
   "license": "SEE LICENSE IN LICENSE",
@@ -48,7 +48,7 @@
     "adm-zip": "^0.5.16",
     "chalk": "^4.1.2",
     "commander": "^9.5.0",
-    "gerdur-core": "^2.9.0",
+    "gerdur-core": "^2.11.0",
     "dot-prop": "^6.0.1",
     "got": "^11.8.6",
     "gradient-string": "^2.0.2",