gerdur 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 2.4.0 - 2026-08-31
+
+### Added
+
+- **`gerdur-core@^2.3.0`** — re-exports `getTrackPreview`, `downloadPreview`,
+  `formatName`, `toFormat`, `DEEZER_FORMATS` and the `DeezerFormat` /
+  `TrackPreview` types.
+- **`--preview`** — download the 30-second clip for each track as
+  `<name>.preview.mp3` instead of the full file. Plain licence-free MP3s: no
+  `--quality`, no decryption, no tagging. Works with every source and headless.
+- **`Session.trackPreview(track)`** and **`Session.downloadPreview(track)`**.
+
+## 2.3.0 - 2026-08-31
+
+### Added
+
+- **`gerdur-core@^2.2.0`** — the browse / discovery surface is re-exported:
+  `getGenres`, `getChart`, `getChartTracks`, `getGenreArtists`,
+  `getEditorialList` / `getEditorialReleases` / `getEditorialSelection` /
+  `getEditorialCharts`, `getArtistTopTracks`, `getRelatedArtists`,
+  `getArtistAlbums`, `getArtistPlaylists`, `getArtistRadioTracks`,
+  `getTrackByISRC`, `getAlbumByUPC`, plus their types.
+- **`Session` browse methods**: `genres`, `chart`, `chartTracks`,
+  `editorialSections`, `artistTopTracks`, `relatedArtists`, `artistAlbums`,
+  `artistRadio`, `trackByISRC`, `albumByUPC`.
+- **CLI `isrc:` / `upc:` prefixes** — `gerdur -u isrc:GBDUW0000059` downloads the
+  exact track for an ISRC; `gerdur -u upc:0724384960650` downloads the album for
+  a barcode. Both work in `--headless` mode and from the interactive prompt.
+
 ## 2.2.0 - 2026-08-31
 
 ### Added

package/README.md

@@ -142,12 +142,13 @@ All options are optional. You can suppress prompts via providing `quality` and `
 | `--bpm-min` / `--bpm-max` | *None*      |                                                        number                                                          |                                                    Search filter — tempo range (beats per minute)                                            |
 | `--dur-min` / `--dur-max` | *None*      |                                                    number (seconds)                                                    |                                                       Search filter — track duration range                                                    |
 | `--search-limit`      |     *None*      |                                                   number (default 50)                                                  |                                                       How many search results to fetch                                                        |
+| `--preview`           |     *None*      |                                                        *Nothing*                                                        |                            Download the 30-second preview clips (`.preview.mp3`) instead of full tracks — no `--quality` needed                |
 
 ## Search
 
 ### From the interactive prompt
 
-When `gerdur` asks for *"a URL, a search term, or `search:<advanced query>`"*:
+When `gerdur` asks for a URL, a search term, or a prefixed query:
 
 | Input | Does |
 | :--- | :--- |
@@ -156,6 +157,10 @@ When `gerdur` asks for *"a URL, a search term, or `search:<advanced query>`"*:
 | `album:discovery` | album search — pick an album |
 | `playlist:deep focus` | playlist search — pick a playlist |
 | `search:artist:"daft punk" bpm_min:120` | advanced track search (see operators below) |
+| `isrc:GBDUW0000059` | download the exact track for an ISRC |
+| `upc:0724384960650` | download the album for a UPC / EAN barcode |
+
+`isrc:` and `upc:` also work in `--headless` mode (`-u isrc:…` / `-u upc:…`).
 
 ### From flags (works headless)
 
@@ -194,6 +199,18 @@ only on **track** search:
 | `dur_min:` / `dur_max:` | `dur_min:200` (seconds) |
 | `bpm_min:` / `bpm_max:` | `bpm_min:120` |
 
+## Previews
+
+`--preview` writes the 30-second clip for each track as `<name>.preview.mp3`
+instead of downloading the full file. The clips are plain, licence-free MP3s —
+no `--quality`, no decryption, no tagging. Works with every source (URL, search,
+`isrc:` / `upc:`) and in `--headless` mode.
+
+```bash
+gerdur --preview -u https://deezer.com/album/302127          # 14 clips
+gerdur -d --preview --artist "Justice" --search-limit 10     # audition a search
+```
+
 ## Programmatic API
 
 When installed as a dependency, `gerdur` exposes a side-effect-free API
@@ -235,10 +252,18 @@ const hits = await session.searchAdvanced(
 const suggestions = await session.suggest('daft'); // autocomplete
 ```
 
-Session methods: `parseUrl`, `search`, `searchAdvanced`, `suggest`, `getUser`,
-`getTrackBuffer`, `downloadTrack`, `downloadTracks`, `downloadUrl`. Every download
-call is silent; `downloadTracks` / `downloadUrl` accept `concurrency` and an
-`onProgress` callback and return one `{path, written} | null` per track.
+Session methods:
+
+- **resolve / search** — `parseUrl`, `search`, `searchAdvanced`, `suggest`
+- **browse** — `genres`, `chart`, `chartTracks`, `editorialSections`,
+  `artistTopTracks`, `relatedArtists`, `artistAlbums`, `artistRadio`,
+  `trackByISRC`, `albumByUPC`
+- **user / download** — `getUser`, `getTrackBuffer`, `downloadTrack`,
+  `downloadTracks`, `downloadUrl`, `trackPreview`, `downloadPreview`
+
+Every download call is silent; `downloadTracks` / `downloadUrl` accept
+`concurrency` and an `onProgress` callback and return one `{path, written} | null`
+per track.
 
 `searchAdvanced(filters, options?)` builds a Deezer advanced-search query from
 `{query?, artist?, album?, track?, label?, durMin?, durMax?, bpmMin?, bpmMax?}`
@@ -247,6 +272,17 @@ unreliable, so an empty result is retried as a plain free-text query unless
 `fallback: false`. It returns public-API track objects — fetch a hit's gw track
 with `getTrackInfo(id)` before downloading it.
 
+```ts
+// Browse: this week's electro chart, download the top 5
+const {tracks} = await session.chart(106, 5);            // 106 = "Dance" genre
+const full = await Promise.all(tracks.data.map((t) => getTrackInfo(String(t.id))));
+await session.downloadTracks(full, 'flac');
+
+// Find & grab an exact recording by barcode
+const t = await session.trackByISRC('GBDUW0000059');
+await session.downloadTrack(await getTrackInfo(String(t.id)), '320');
+```
+
 ### Low-level: primitives
 
 ```ts
@@ -269,11 +305,18 @@ const {path, written} = (await downloadTrackToFile(track, 'flac', {output: '{ART
 So you don't need `gerdur-core` as a second dependency (call after `initDeezerApi`
 or `createSession`):
 
-`parseInfo`, `searchMusic`, `searchPublicApi`, `searchTracks`, `searchAlbums`,
-`searchArtists`, `searchPlaylists`, `buildAdvancedQuery`, `suggest`, `getUser`,
-`getTrackInfo`, `getAlbumInfo`, `getAlbumTracks`, `getPlaylistInfo`,
-`getPlaylistTracks`, `getArtistInfo`, `getDiscography`, `getLyrics`,
-`getTrackDownloadUrl`, `resolveDownloadUrls`, `GeoBlocked`.
+- **Query** — `parseInfo`, `getUser`, `getTrackInfo`, `getAlbumInfo`,
+  `getAlbumTracks`, `getPlaylistInfo`, `getPlaylistTracks`, `getArtistInfo`,
+  `getDiscography`, `getLyrics`
+- **Search** — `searchMusic`, `searchPublicApi`, `searchTracks`, `searchAlbums`,
+  `searchArtists`, `searchPlaylists`, `buildAdvancedQuery`, `suggest`
+- **Browse** — `getGenres`, `getChart`, `getChartTracks`, `getGenreArtists`,
+  `getEditorialList`, `getEditorialReleases`, `getEditorialSelection`,
+  `getEditorialCharts`, `getArtistTopTracks`, `getRelatedArtists`,
+  `getArtistAlbums`, `getArtistPlaylists`, `getArtistRadioTracks`,
+  `getTrackByISRC`, `getAlbumByUPC`
+- **Download** — `getTrackDownloadUrl`, `resolveDownloadUrls`, `getTrackPreview`,
+  `downloadPreview`, `formatName`, `toFormat`, `DEEZER_FORMATS`, `GeoBlocked`
 
 ### Auth & config helpers
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gerdur",
-    "version": "2.2.0",
+    "version": "2.4.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.1.0",
+        "gerdur-core": "^2.3.0",
         "dot-prop": "^6.0.1",
         "got": "^11.8.6",
         "gradient-string": "^2.0.2",

package/dist/src/gerdur.js

@@ -57,7 +57,8 @@ const cmd = new commander_1.Command()
     .option('--bpm-max <n>', 'Search filter: maximum BPM')
     .option('--dur-min <seconds>', 'Search filter: minimum duration')
     .option('--dur-max <seconds>', 'Search filter: maximum duration')
-    .option('--search-limit <n>', 'Max search results to fetch', '50');
+    .option('--search-limit <n>', 'Max search results to fetch', '50')
+    .option('--preview', 'Download the 30-second preview clips instead of full tracks', false);
 if (process.pkg) {
     cmd.option('-U, --update', 'Update this program to latest version');
 }
@@ -79,7 +80,7 @@ const toFiniteNumber = (value) => {
 };
 const advancedFilters = (0, search_1.advancedFiltersFromFlags)(options);
 let advancedFiltersConsumed = false;
-if (options.headless && !options.quality) {
+if (options.headless && !options.quality && !options.preview) {
     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);
@@ -152,10 +153,48 @@ const resolveAdvancedSearch = async (filters) => {
     }
     return { info: { type: 'track', id: query }, linktype: 'track', linkinfo: {}, tracks };
 };
+/**
+ * `--preview`: fetch the 30-second clip for each selected track and write it as
+ * `<saveLayout path>.preview.mp3`. Bypasses the get_url / decrypt / tag pipeline
+ * entirely — previews are plain, licence-free MP3s.
+ */
+const downloadPreviews = async (tracks, info, template, totalTracks, trackNumber, overwrite) => {
+    const saved = [];
+    await queue.addAll(tracks.map((track, index) => async () => {
+        const rel = (0, util_1.saveLayout)({
+            track,
+            album: info,
+            path: template,
+            trackNumber,
+            minimumIntegerDigits: totalTracks >= 100 ? 3 : 2,
+        }) + '.preview.mp3';
+        (0, log_update_1.default)(signale_1.default.pending(`(${index + 1}/${tracks.length}) ${track.ART_NAME} - ${track.SNG_TITLE}`));
+        if (!overwrite && (0, fs_1.existsSync)(rel)) {
+            saved.push(rel);
+            return;
+        }
+        try {
+            const clip = await (0, gerdur_core_1.downloadPreview)(track);
+            if (!clip) {
+                (0, log_update_1.default)(signale_1.default.warn(`No preview for ${track.SNG_TITLE}`));
+                return;
+            }
+            (0, fs_1.mkdirSync)((0, path_1.dirname)(rel), { recursive: true });
+            (0, fs_1.writeFileSync)(rel, clip);
+            saved.push(rel);
+            (0, log_update_1.default)(signale_1.default.success(`${track.ART_NAME} - ${track.SNG_TITLE} (preview)`));
+        }
+        catch (err) {
+            (0, log_update_1.default)(signale_1.default.error(`${track.SNG_TITLE}: ${err.message}`));
+        }
+    }));
+    log_update_1.default.done();
+    return saved;
+};
 const startDownload = async (saveLayout, url, skipPrompt) => {
     try {
         url = url ?? '';
-        if (!options.quality) {
+        if (!options.quality && !options.preview) {
             const { musicQuality } = await (0, prompts_1.default)([
                 {
                     type: 'select',
@@ -189,7 +228,7 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                 {
                     type: 'text',
                     name: 'query',
-                    message: 'Enter a URL, a search term, or `search:<advanced query>`:',
+                    message: 'Enter a URL, a search term, or a `search:` / `isrc:` / `upc:` query:',
                     validate: (value) => (value ? true : false),
                 },
             ], { onCancel });
@@ -202,6 +241,25 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                 throw new Error('No tracks matched that search.');
             }
         }
+        // `isrc:` / `upc:` — resolve a barcode to a Deezer track / album (works headless).
+        if (!searchData && url && url.startsWith('isrc:')) {
+            const code = url.slice('isrc:'.length).trim();
+            const found = await (0, gerdur_core_1.getTrackByISRC)(code).catch(() => null);
+            if (!found) {
+                throw new Error(`No Deezer track for ISRC ${code}`);
+            }
+            const track = await (0, gerdur_core_1.getTrackInfo)(String(found.id));
+            searchData = { info: { type: 'track', id: code }, linktype: 'track', linkinfo: {}, tracks: [stampVersion(track)] };
+        }
+        if (!searchData && url && url.startsWith('upc:')) {
+            const code = url.slice('upc:'.length).trim();
+            const found = await (0, gerdur_core_1.getAlbumByUPC)(code).catch(() => null);
+            if (!found) {
+                throw new Error(`No Deezer album for UPC ${code}`);
+            }
+            console.log(signale_1.default.info(`UPC ${code} → ${found.title} (${found.nb_tracks} tracks)`));
+            url = `https://www.deezer.com/album/${found.id}`;
+        }
         if (!searchData && !url.match(urlRegex)) {
             if (options.headless) {
                 throw new Error('Please provide a valid URL. Unknown URL: ' + url);
@@ -308,56 +366,63 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
             const resolveFullPath = options.resolveFullPath ?? conf.get('playlist.resolveFullPath');
             const savedFiles = [];
             let m3u8 = [];
-            // One batched get_url for the whole selection instead of a request per track.
-            // Deezer returns the best licensed format, so pass an ordered preference list.
-            const QUALITY_PREF = {
-                '1': [1],
-                '128': [1],
-                '3': [3, 1],
-                '320': [3, 1],
-                '9': [9, 3, 1],
-                flac: [9, 3, 1],
-            };
-            const prefetchedUrls = new Map();
-            if (data.tracks.length > 1 && !process.env.SIMULATE) {
-                try {
-                    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);
-                    resolved.forEach((r, i) => {
-                        if (r) {
-                            prefetchedUrls.set(data.tracks[i].SNG_ID, r);
-                        }
-                    });
-                }
-                catch {
-                    // batch resolve failed wholesale — every track falls back to per-track resolution
-                }
+            const layoutTemplate = options.output ? options.output : saveLayout[data.linktype];
+            if (options.preview) {
+                const clips = await downloadPreviews(data.tracks, data.linkinfo, layoutTemplate, data.tracks.length, trackNumber, overwrite);
+                savedFiles.push(...clips);
             }
-            await queue.addAll(data.tracks.map((track, index) => {
-                return async () => {
-                    const savedPath = await (0, download_track_1.default)({
-                        track,
-                        quality: options.quality,
-                        info: data.linkinfo,
-                        coverSizes,
-                        path: options.output ? options.output : saveLayout[data.linktype],
-                        totalTracks: data ? data.tracks.length : 10,
-                        trackNumber,
-                        fallbackTrack,
-                        fallbackQuality,
-                        overwrite,
-                        message: `(${index}/${data.tracks.length})`,
-                        lrc,
-                        prefetched: prefetchedUrls.get(track.SNG_ID) ?? null,
-                    });
-                    // Add to saved list
-                    if (savedPath) {
-                        m3u8.push((0, path_1.resolve)(process.env.SIMULATE ? savedPath : (0, true_case_path_1.trueCasePathSync)(savedPath)));
-                        savedFiles.push(savedPath);
-                    }
+            else {
+                // One batched get_url for the whole selection instead of a request per track.
+                // Deezer returns the best licensed format, so pass an ordered preference list.
+                const QUALITY_PREF = {
+                    '1': [1],
+                    '128': [1],
+                    '3': [3, 1],
+                    '320': [3, 1],
+                    '9': [9, 3, 1],
+                    flac: [9, 3, 1],
                 };
-            }));
+                const prefetchedUrls = new Map();
+                if (data.tracks.length > 1 && !process.env.SIMULATE) {
+                    try {
+                        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);
+                        resolved.forEach((r, i) => {
+                            if (r) {
+                                prefetchedUrls.set(data.tracks[i].SNG_ID, r);
+                            }
+                        });
+                    }
+                    catch {
+                        // batch resolve failed wholesale — every track falls back to per-track resolution
+                    }
+                }
+                await queue.addAll(data.tracks.map((track, index) => {
+                    return async () => {
+                        const savedPath = await (0, download_track_1.default)({
+                            track,
+                            quality: options.quality,
+                            info: data.linkinfo,
+                            coverSizes,
+                            path: layoutTemplate,
+                            totalTracks: data ? data.tracks.length : 10,
+                            trackNumber,
+                            fallbackTrack,
+                            fallbackQuality,
+                            overwrite,
+                            message: `(${index}/${data.tracks.length})`,
+                            lrc,
+                            prefetched: prefetchedUrls.get(track.SNG_ID) ?? null,
+                        });
+                        // Add to saved list
+                        if (savedPath) {
+                            m3u8.push((0, path_1.resolve)(process.env.SIMULATE ? savedPath : (0, true_case_path_1.trueCasePathSync)(savedPath)));
+                            savedFiles.push(savedPath);
+                        }
+                    };
+                }));
+            }
             // Display downloaded location
             if (savedFiles.length > 0) {
                 const savedIn = new Set(savedFiles.map((l) => (0, path_1.dirname)(l)));

package/dist/src/index.d.ts

@@ -59,6 +59,7 @@ export type { SessionOptions, DownloadTracksOptions, SearchType } from './lib/se
 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, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, addTrackTags, getRichAlbum, normalizeContributors, toLrc, GeoBlocked, } from 'gerdur-core';
+export { initDeezerApi, parseInfo, searchMusic, searchPublicApi, searchTracks, searchAlbums, searchArtists, searchPlaylists, buildAdvancedQuery, suggest, getGenres, getChart, getChartTracks, getGenreArtists, getEditorialList, getEditorialReleases, getEditorialSelection, getEditorialCharts, getArtistTopTracks, getRelatedArtists, getArtistAlbums, getArtistPlaylists, getArtistRadioTracks, getTrackByISRC, getAlbumByUPC, getTrackPreview, downloadPreview, formatName, toFormat, DEEZER_FORMATS, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, addTrackTags, getRichAlbum, normalizeContributors, toLrc, GeoBlocked, } 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, } from 'gerdur-core/types';
+export type { advancedSearchFilters, searchOrder, searchEntity, publicApiSearchOptions, publicApiSearchResponse, searchResultTrack, searchResultAlbum, searchResultArtist, searchResultPlaylist, suggestResult, publicApiList, chartType, chartTrack, chartAlbum, chartArtist, chartPlaylist, chartPodcast, genreType, editorialType, artistAlbumResult, } from 'gerdur-core/types';
+export type { Quality as MediaFormat, DeezerFormat, TrackPreview } from 'gerdur-core';

package/dist/src/index.js

@@ -33,7 +33,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GeoBlocked = exports.toLrc = exports.normalizeContributors = exports.getRichAlbum = exports.addTrackTags = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.getLyrics = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getTrackInfo = exports.getUser = 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.Session = exports.createSession = exports.getArl = exports.LoginError = exports.loginWithEmail = void 0;
+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.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.Session = exports.createSession = exports.getArl = exports.LoginError = exports.loginWithEmail = void 0;
+exports.GeoBlocked = exports.toLrc = exports.normalizeContributors = exports.getRichAlbum = exports.addTrackTags = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = void 0;
 // ─── Authentication ────────────────────────────────────────────────────────
 const email_login_1 = require("./lib/email-login");
 Object.defineProperty(exports, "loginWithEmail", { enumerable: true, get: function () { return email_login_1.loginWithEmail; } });
@@ -96,6 +97,26 @@ Object.defineProperty(exports, "searchArtists", { enumerable: true, get: functio
 Object.defineProperty(exports, "searchPlaylists", { enumerable: true, get: function () { return gerdur_core_1.searchPlaylists; } });
 Object.defineProperty(exports, "buildAdvancedQuery", { enumerable: true, get: function () { return gerdur_core_1.buildAdvancedQuery; } });
 Object.defineProperty(exports, "suggest", { enumerable: true, get: function () { return gerdur_core_1.suggest; } });
+Object.defineProperty(exports, "getGenres", { enumerable: true, get: function () { return gerdur_core_1.getGenres; } });
+Object.defineProperty(exports, "getChart", { enumerable: true, get: function () { return gerdur_core_1.getChart; } });
+Object.defineProperty(exports, "getChartTracks", { enumerable: true, get: function () { return gerdur_core_1.getChartTracks; } });
+Object.defineProperty(exports, "getGenreArtists", { enumerable: true, get: function () { return gerdur_core_1.getGenreArtists; } });
+Object.defineProperty(exports, "getEditorialList", { enumerable: true, get: function () { return gerdur_core_1.getEditorialList; } });
+Object.defineProperty(exports, "getEditorialReleases", { enumerable: true, get: function () { return gerdur_core_1.getEditorialReleases; } });
+Object.defineProperty(exports, "getEditorialSelection", { enumerable: true, get: function () { return gerdur_core_1.getEditorialSelection; } });
+Object.defineProperty(exports, "getEditorialCharts", { enumerable: true, get: function () { return gerdur_core_1.getEditorialCharts; } });
+Object.defineProperty(exports, "getArtistTopTracks", { enumerable: true, get: function () { return gerdur_core_1.getArtistTopTracks; } });
+Object.defineProperty(exports, "getRelatedArtists", { enumerable: true, get: function () { return gerdur_core_1.getRelatedArtists; } });
+Object.defineProperty(exports, "getArtistAlbums", { enumerable: true, get: function () { return gerdur_core_1.getArtistAlbums; } });
+Object.defineProperty(exports, "getArtistPlaylists", { enumerable: true, get: function () { return gerdur_core_1.getArtistPlaylists; } });
+Object.defineProperty(exports, "getArtistRadioTracks", { enumerable: true, get: function () { return gerdur_core_1.getArtistRadioTracks; } });
+Object.defineProperty(exports, "getTrackByISRC", { enumerable: true, get: function () { return gerdur_core_1.getTrackByISRC; } });
+Object.defineProperty(exports, "getAlbumByUPC", { enumerable: true, get: function () { return gerdur_core_1.getAlbumByUPC; } });
+Object.defineProperty(exports, "getTrackPreview", { enumerable: true, get: function () { return gerdur_core_1.getTrackPreview; } });
+Object.defineProperty(exports, "downloadPreview", { enumerable: true, get: function () { return gerdur_core_1.downloadPreview; } });
+Object.defineProperty(exports, "formatName", { enumerable: true, get: function () { return gerdur_core_1.formatName; } });
+Object.defineProperty(exports, "toFormat", { enumerable: true, get: function () { return gerdur_core_1.toFormat; } });
+Object.defineProperty(exports, "DEEZER_FORMATS", { enumerable: true, get: function () { return gerdur_core_1.DEEZER_FORMATS; } });
 Object.defineProperty(exports, "getUser", { enumerable: true, get: function () { return gerdur_core_1.getUser; } });
 Object.defineProperty(exports, "getTrackInfo", { enumerable: true, get: function () { return gerdur_core_1.getTrackInfo; } });
 Object.defineProperty(exports, "getAlbumInfo", { enumerable: true, get: function () { return gerdur_core_1.getAlbumInfo; } });

package/dist/src/lib/session.d.ts

@@ -2,7 +2,8 @@
 import { parseInfo, searchMusic } from 'gerdur-core';
 import type { AdvancedSearchOptions } from './search';
 import type { Quality, DownloadTrackOptions, DownloadResult } from './api-download';
-import type { trackType, userType, advancedSearchFilters, publicApiSearchResponse, searchResultTrack, suggestResult } from 'gerdur-core/types';
+import type { trackType, userType, advancedSearchFilters, publicApiSearchResponse, searchResultTrack, suggestResult, chartType, genreType, editorialType, artistAlbumResult, searchResultArtist, publicApiList, trackTypePublicApi, albumTypePublicApi } from 'gerdur-core/types';
+import type { TrackPreview } from 'gerdur-core';
 /** Search result categories accepted by {@link Session.search}. */
 export type SearchType = 'ALBUM' | 'ARTIST' | 'TRACK' | 'PLAYLIST' | 'RADIO' | 'SHOW' | 'USER' | 'LIVESTREAM' | 'CHANNEL';
 export interface SessionOptions {
@@ -65,6 +66,30 @@ export declare class Session {
     searchAdvanced(filters: advancedSearchFilters, options?: AdvancedSearchOptions): Promise<publicApiSearchResponse<searchResultTrack>>;
     /** `deezer.suggest` autocomplete — for "as you type" UIs. `nb` caps items per type. */
     suggest(query: string, nb?: number): Promise<suggestResult>;
+    /** Deezer's genre list (`id` `0` = "All"). */
+    genres(): Promise<publicApiList<genreType>>;
+    /** The five ranked lists for a genre (`0` = all): `{tracks, albums, artists, playlists, podcasts}`. */
+    chart(genreId?: number | string, limit?: number): Promise<chartType>;
+    /** Just the track chart for a genre — a ready-to-download list. */
+    chartTracks(genreId?: number | string, limit?: number, index?: number): Promise<publicApiList<searchResultTrack>>;
+    /** Deezer's editorial sections. */
+    editorialSections(): Promise<publicApiList<editorialType>>;
+    /** An artist's most popular tracks (public-API shape). */
+    artistTopTracks(artistId: number | string, limit?: number): Promise<publicApiList<searchResultTrack>>;
+    /** Artists Deezer considers related / similar. */
+    relatedArtists(artistId: number | string, limit?: number): Promise<publicApiList<searchResultArtist>>;
+    /** An artist's discography (public-API album shape). */
+    artistAlbums(artistId: number | string, limit?: number, index?: number): Promise<publicApiList<artistAlbumResult>>;
+    /** A ready-made radio (track list) seeded from an artist. */
+    artistRadio(artistId: number | string): Promise<publicApiList<searchResultTrack>>;
+    /** Resolve an ISRC to the public-API track. Pass `.id` to `getTrackInfo` to download. */
+    trackByISRC(isrc: string): Promise<trackTypePublicApi>;
+    /** Resolve a UPC/EAN barcode to the public-API album (with its `tracks`). */
+    albumByUPC(upc: string): Promise<albumTypePublicApi>;
+    /** The 30-second preview clip URL for a track (plain MP3 — no licence, no decryption). */
+    trackPreview(track: trackType | string | number): Promise<TrackPreview | null>;
+    /** Fetch a track's 30-second preview clip as a `Buffer` (plain MP3). */
+    downloadPreview(track: trackType | string | number): Promise<Buffer | null>;
     /** Return a fully tagged audio Buffer for a track (nothing written to disk). */
     getTrackBuffer(track: trackType, quality?: Quality, options?: {}): Promise<Buffer | null>;
     /** Download a single track to disk. */

package/dist/src/lib/session.js

@@ -75,6 +75,55 @@ class Session {
     suggest(query, nb) {
         return (0, gerdur_core_1.suggest)(query, nb);
     }
+    // ─── Browse & discovery (public REST) ──────────────────────────────────────
+    /** Deezer's genre list (`id` `0` = "All"). */
+    genres() {
+        return (0, gerdur_core_1.getGenres)();
+    }
+    /** The five ranked lists for a genre (`0` = all): `{tracks, albums, artists, playlists, podcasts}`. */
+    chart(genreId = 0, limit = 10) {
+        return (0, gerdur_core_1.getChart)(genreId, limit);
+    }
+    /** Just the track chart for a genre — a ready-to-download list. */
+    chartTracks(genreId = 0, limit = 100, index = 0) {
+        return (0, gerdur_core_1.getChartTracks)(genreId, limit, index);
+    }
+    /** Deezer's editorial sections. */
+    editorialSections() {
+        return (0, gerdur_core_1.getEditorialList)();
+    }
+    /** An artist's most popular tracks (public-API shape). */
+    artistTopTracks(artistId, limit = 50) {
+        return (0, gerdur_core_1.getArtistTopTracks)(artistId, limit);
+    }
+    /** Artists Deezer considers related / similar. */
+    relatedArtists(artistId, limit = 20) {
+        return (0, gerdur_core_1.getRelatedArtists)(artistId, limit);
+    }
+    /** An artist's discography (public-API album shape). */
+    artistAlbums(artistId, limit = 50, index = 0) {
+        return (0, gerdur_core_1.getArtistAlbums)(artistId, limit, index);
+    }
+    /** A ready-made radio (track list) seeded from an artist. */
+    artistRadio(artistId) {
+        return (0, gerdur_core_1.getArtistRadioTracks)(artistId);
+    }
+    /** Resolve an ISRC to the public-API track. Pass `.id` to `getTrackInfo` to download. */
+    trackByISRC(isrc) {
+        return (0, gerdur_core_1.getTrackByISRC)(isrc);
+    }
+    /** Resolve a UPC/EAN barcode to the public-API album (with its `tracks`). */
+    albumByUPC(upc) {
+        return (0, gerdur_core_1.getAlbumByUPC)(upc);
+    }
+    /** The 30-second preview clip URL for a track (plain MP3 — no licence, no decryption). */
+    trackPreview(track) {
+        return (0, gerdur_core_1.getTrackPreview)(track);
+    }
+    /** Fetch a track's 30-second preview clip as a `Buffer` (plain MP3). */
+    downloadPreview(track) {
+        return (0, gerdur_core_1.downloadPreview)(track);
+    }
     /** Return a fully tagged audio Buffer for a track (nothing written to disk). */
     getTrackBuffer(track, quality = '320', options = {}) {
         return (0, api_download_1.getTrackBuffer)(track, quality, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur",
-  "version": "2.2.0",
+  "version": "2.4.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.1.0",
+    "gerdur-core": "^2.3.0",
     "dot-prop": "^6.0.1",
     "got": "^11.8.6",
     "gradient-string": "^2.0.2",