gerdur-core 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 2.3.0 - 2026-08-31
+
+Phase 2.1 — all the formats, and previews. Additive; the `1 / 3 / 9` path is
+unchanged.
+
+### Added
+
+- **`getTrackPreview(track)` / `downloadPreview(track)`** — the 30-second preview
+  clip. A plain MP3: no licence, no `arl`, no Blowfish. Accepts a gw track (reads
+  `MEDIA`, no extra request), a track id, or a number.
+- **`DEEZER_FORMATS`** — every format `get_url` understands, best → worst
+  (`FLAC`, `MP3_320`, `MP3_256`, `MP3_128`, `MP3_64`, `AAC_64`, `MP4_RA3/2/1`).
+- **`resolveDownloadUrls(tracks, qualities)`** now accepts format strings in the
+  preference list (`['FLAC', 'MP3_320', 'AAC_64']`), not just `1 | 3 | 9`. Each
+  `ResolvedUrl` gains `cipher` (`'BF_CBC_STRIPE'` | `'NONE'`).
+- **`toFormat(quality)`** — normalise a number or format string to the `get_url`
+  format string. `formatName` now also accepts format strings (identity).
+- `Quality` / `DeezerFormat` exported types.
+
+### Changed
+
+- `isEncrypted` (from `getTrackDownloadUrl` and `resolveDownloadUrls`) is now
+  taken from the media API's `cipher` field instead of guessing from the URL
+  path — authoritative, and correct for `cipher: NONE` content.
+- `trackType.FILESIZE_*` fields are typed `string` (several were mistyped as the
+  literal `'0'`); added `FILESIZE_MP3_MISC` / `FILESIZE_MHM1_RA*`.
+
+## 2.2.0 - 2026-08-31
+
+Phase 2.4 — browse & discovery. All additive, all on the public REST API (no
+`arl` needed), all memoised.
+
+### Added
+
+- **Charts / editorial**: `getGenres`, `getChart(genreId, limit)` (the five
+  ranked lists), `getChartTracks`, `getGenreArtists`, `getEditorialList`,
+  `getEditorialReleases`, `getEditorialSelection`, `getEditorialCharts`.
+- **Artist discovery**: `getArtistTopTracks`, `getRelatedArtists`,
+  `getArtistAlbums`, `getArtistPlaylists`, `getArtistRadioTracks`.
+- **ISRC / UPC resolution**: `getTrackByISRC(isrc)` and `getAlbumByUPC(upc)` —
+  raw public-API track/album (with `bpm`, `gain`, `preview`, embedded `tracks`).
+  Complements the converter's `isrc2deezer` / `upc2deezer`, which hydrate a gw
+  track instead.
+- New exported types: `chartType`, `chartTrack`/`chartAlbum`/`chartArtist`/
+  `chartPlaylist`/`chartPodcast`, `genreType`, `editorialType`,
+  `artistAlbumResult`, `publicApiList<T>`.
+
 ## 2.1.0 - 2026-08-31
 
 Phase 2.5 — search, properly. All additive.

package/README.md

@@ -196,6 +196,41 @@ 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`).
 
+### Browse & discovery
+
+Public REST endpoints — no `arl` needed, memoised like the rest. All return a
+`{data, total?, next?}` list unless noted.
+
+| Method | Returns |
+| :--- | :--- |
+| `getGenres()` | Deezer's genre list (`id` `0` = "All"). |
+| `getChart(genreId = 0, limit = 10)` | `{tracks, albums, artists, playlists, podcasts}` — the ranked lists for a genre. |
+| `getChartTracks(genreId = 0, limit = 100, index = 0)` | just the track chart, each with a `position`. |
+| `getGenreArtists(genreId)` | artists filed under a genre. |
+| `getEditorialList()` | Deezer's editorial sections. |
+| `getEditorialReleases(editorialId = 0, limit = 25, index = 0)` | new releases for a section. |
+| `getEditorialSelection(editorialId = 0)` | albums the editors are pushing. |
+| `getEditorialCharts(editorialId = 0)` | a section's charts (same 5-list shape as `getChart`). |
+| `getArtistTopTracks(artistId, limit = 50)` | an artist's most popular tracks. |
+| `getRelatedArtists(artistId, limit = 20)` | similar / related artists. |
+| `getArtistAlbums(artistId, limit = 50, index = 0)` | the artist's discography. |
+| `getArtistPlaylists(artistId, limit = 25)` | playlists featuring the artist. |
+| `getArtistRadioTracks(artistId)` | a ready-made radio seeded from the artist. |
+| `getTrackByISRC(isrc)` | the public-API track for an ISRC (`bpm`, `gain`, `preview`, …). |
+| `getAlbumByUPC(upc)` | the public-API album (with its `tracks`) for a UPC/EAN barcode. |
+
+```js
+const {data: genres} = await getGenres();
+const rock = genres.find((g) => g.name === 'Rock');
+const {tracks} = await getChart(rock.id, 20);            // this week's rock chart
+const similar = await getRelatedArtists(27);             // artists like Daft Punk
+const track = await getTrackByISRC('USUM71311296');      // "Get Lucky"
+```
+
+`getTrackByISRC` / `getAlbumByUPC` return raw public-API objects. To download,
+pass the `id` to `getTrackInfo` / `getAlbumTracks` (or use the converter's
+`isrc2deezer` / `upc2deezer`, which hydrate a gw track for you).
+
 ### `.getTrackDownloadUrl(track, quality);`
 
 | Parameters | Required |        Type |                        Description |
@@ -203,6 +238,37 @@ session (`initDeezerApi`).
 | `track`    |   Yes    |    `string` |                       track object |
 | `quality`  |   Yes    | `1, 3 or 9` | 1 = 128kbps, 3 = 320kbps, 9 = flac |
 
+Resolves `{trackUrl, isEncrypted, fileSize}`. `isEncrypted` now comes from the
+media API's `cipher` field (authoritative) rather than a URL guess.
+
+### Formats
+
+Deezer's `get_url` understands more than `1 / 3 / 9`. `DEEZER_FORMATS` lists them
+best → worst: `FLAC`, `MP3_320`, `MP3_256`, `MP3_128`, `MP3_64`, `AAC_64`,
+`MP4_RA3`, `MP4_RA2`, `MP4_RA1` (the last four are the HE-AAC ladder some
+accounts / regions expose).
+
+- **`resolveDownloadUrls(tracks, qualities)`** — `qualities` entries may be the
+  `1 | 3 | 9` shorthand **or** any format string, e.g.
+  `resolveDownloadUrls(tracks, ['FLAC', 'MP3_320', 'AAC_64'])`. Deezer returns
+  the best each track is licensed for. Each result now also carries `format` and
+  `cipher` (`'BF_CBC_STRIPE'` or `'NONE'`).
+- **`formatName(quality)`** / **`toFormat(quality)`** — normalise a number or
+  format string to the `get_url` format string.
+
+### `.getTrackPreview(track)` / `.downloadPreview(track)`
+
+The 30-second preview clip — a plain MP3, **no licence, no `arl`, no
+encryption**. `track` may be a gw track object (reads its `MEDIA`, no extra
+request), a track id, or a number.
+
+```js
+const {url} = await getTrackPreview('3135556');      // {url, duration: 30}
+const clip = await downloadPreview('3135556');       // Buffer (ID3-tagged MP3)
+```
+
+Useful for "audition before download" and for CI that shouldn't pull full tracks.
+
 ### `.decryptDownload(data, song_id);`
 
 | Parameters | Required |     Type |            Description |

package/dist/api/browse.d.ts

@@ -0,0 +1,49 @@
+import type { albumTypePublicApi, artistAlbumResult, chartType, editorialType, genreType, publicApiList, searchResultArtist, searchResultPlaylist, searchResultTrack, trackTypePublicApi } from '../types';
+/**
+ * The five ranked lists Deezer publishes for a genre: `tracks`, `albums`,
+ * `artists`, `playlists`, `podcasts`. `genreId` `0` (the default) is "all
+ * genres"; other ids come from {@link getGenres}.
+ */
+export declare const getChart: (genreId?: number | string, limit?: number) => Promise<chartType>;
+/** Just the track chart for a genre (`0` = all). Handy as a ready-to-play list. */
+export declare const getChartTracks: (genreId?: number | string, limit?: number, index?: number) => Promise<publicApiList<searchResultTrack & {
+    position: number;
+}>>;
+/** Deezer's genre list — the `id`s feed {@link getChart}, {@link getGenreArtists}, advanced search. */
+export declare const getGenres: () => Promise<publicApiList<genreType>>;
+/** Artists Deezer files under a genre. */
+export declare const getGenreArtists: (genreId: number | string) => Promise<publicApiList<searchResultArtist>>;
+/** Deezer's editorial sections (the `id`s feed {@link getEditorialReleases} / {@link getEditorialSelection}). */
+export declare const getEditorialList: () => Promise<publicApiList<editorialType>>;
+/** New releases for an editorial section (`0` = the default section). */
+export declare const getEditorialReleases: (editorialId?: number | string, limit?: number, index?: number) => Promise<publicApiList<artistAlbumResult>>;
+/** The albums Deezer's editors are currently pushing for a section. */
+export declare const getEditorialSelection: (editorialId?: number | string) => Promise<publicApiList<artistAlbumResult>>;
+/** The editorial charts for a section — same five-list shape as {@link getChart}. */
+export declare const getEditorialCharts: (editorialId?: number | string) => Promise<chartType>;
+/** An artist's most popular tracks. */
+export declare const getArtistTopTracks: (artistId: number | string, limit?: number) => Promise<publicApiList<searchResultTrack>>;
+/** Artists Deezer considers related / similar. */
+export declare const getRelatedArtists: (artistId: number | string, limit?: number) => Promise<publicApiList<searchResultArtist>>;
+/** An artist's discography (public-API album shape). */
+export declare const getArtistAlbums: (artistId: number | string, limit?: number, index?: number) => Promise<publicApiList<artistAlbumResult>>;
+/** Playlists featuring an artist. */
+export declare const getArtistPlaylists: (artistId: number | string, limit?: number) => Promise<publicApiList<searchResultPlaylist>>;
+/** A ready-made radio (track list) seeded from an artist. */
+export declare const getArtistRadioTracks: (artistId: number | string) => Promise<publicApiList<searchResultTrack>>;
+/**
+ * Resolve an ISRC to the Deezer **public-API** track (with `bpm`, `gain`,
+ * `isrc`, `preview`, `contributors`). Unlike the converter's `isrc2deezer`, this
+ * does not hydrate a gw track — pass `result.id` to `getTrackInfo` for that.
+ *
+ * @throws when Deezer has no track for the code
+ */
+export declare const getTrackByISRC: (isrc: string) => Promise<trackTypePublicApi>;
+/**
+ * Resolve a UPC / EAN barcode to the Deezer **public-API** album (with its
+ * `tracks`). A 13-digit barcode with a leading `0` is trimmed to 12, matching
+ * Deezer's own lookup.
+ *
+ * @throws when Deezer has no album for the code
+ */
+export declare const getAlbumByUPC: (upc: string) => Promise<albumTypePublicApi>;

package/dist/api/browse.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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.getGenres = exports.getChartTracks = exports.getChart = void 0;
+const request_1 = require("./request");
+const withParams = (slug, params) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== '') {
+            search.set(key, String(value));
+        }
+    }
+    const qs = search.toString();
+    return qs ? `${slug}?${qs}` : slug;
+};
+// ─── Charts ──────────────────────────────────────────────────────────────────
+/**
+ * The five ranked lists Deezer publishes for a genre: `tracks`, `albums`,
+ * `artists`, `playlists`, `podcasts`. `genreId` `0` (the default) is "all
+ * genres"; other ids come from {@link getGenres}.
+ */
+const getChart = (genreId = 0, limit = 10) => (0, request_1.requestPublicApi)(withParams(`/chart/${genreId}`, { limit }));
+exports.getChart = getChart;
+/** Just the track chart for a genre (`0` = all). Handy as a ready-to-play list. */
+const getChartTracks = (genreId = 0, limit = 100, index = 0) => (0, request_1.requestPublicApi)(withParams(`/chart/${genreId}/tracks`, { limit, index }));
+exports.getChartTracks = getChartTracks;
+// ─── Genres & editorial ──────────────────────────────────────────────────────
+/** Deezer's genre list — the `id`s feed {@link getChart}, {@link getGenreArtists}, advanced search. */
+const getGenres = () => (0, request_1.requestPublicApi)('/genre');
+exports.getGenres = getGenres;
+/** Artists Deezer files under a genre. */
+const getGenreArtists = (genreId) => (0, request_1.requestPublicApi)(`/genre/${genreId}/artists`);
+exports.getGenreArtists = getGenreArtists;
+/** Deezer's editorial sections (the `id`s feed {@link getEditorialReleases} / {@link getEditorialSelection}). */
+const getEditorialList = () => (0, request_1.requestPublicApi)('/editorial');
+exports.getEditorialList = getEditorialList;
+/** New releases for an editorial section (`0` = the default section). */
+const getEditorialReleases = (editorialId = 0, limit = 25, index = 0) => (0, request_1.requestPublicApi)(withParams(`/editorial/${editorialId}/releases`, { limit, index }));
+exports.getEditorialReleases = getEditorialReleases;
+/** The albums Deezer's editors are currently pushing for a section. */
+const getEditorialSelection = (editorialId = 0) => (0, request_1.requestPublicApi)(`/editorial/${editorialId}/selection`);
+exports.getEditorialSelection = getEditorialSelection;
+/** The editorial charts for a section — same five-list shape as {@link getChart}. */
+const getEditorialCharts = (editorialId = 0) => (0, request_1.requestPublicApi)(`/editorial/${editorialId}/charts`);
+exports.getEditorialCharts = getEditorialCharts;
+// ─── Artist discovery ────────────────────────────────────────────────────────
+/** An artist's most popular tracks. */
+const getArtistTopTracks = (artistId, limit = 50) => (0, request_1.requestPublicApi)(withParams(`/artist/${artistId}/top`, { limit }));
+exports.getArtistTopTracks = getArtistTopTracks;
+/** Artists Deezer considers related / similar. */
+const getRelatedArtists = (artistId, limit = 20) => (0, request_1.requestPublicApi)(withParams(`/artist/${artistId}/related`, { limit }));
+exports.getRelatedArtists = getRelatedArtists;
+/** An artist's discography (public-API album shape). */
+const getArtistAlbums = (artistId, limit = 50, index = 0) => (0, request_1.requestPublicApi)(withParams(`/artist/${artistId}/albums`, { limit, index }));
+exports.getArtistAlbums = getArtistAlbums;
+/** Playlists featuring an artist. */
+const getArtistPlaylists = (artistId, limit = 25) => (0, request_1.requestPublicApi)(withParams(`/artist/${artistId}/playlists`, { limit }));
+exports.getArtistPlaylists = getArtistPlaylists;
+/** A ready-made radio (track list) seeded from an artist. */
+const getArtistRadioTracks = (artistId) => (0, request_1.requestPublicApi)(`/artist/${artistId}/radio`);
+exports.getArtistRadioTracks = getArtistRadioTracks;
+// ─── ISRC / UPC resolution ───────────────────────────────────────────────────
+/**
+ * Resolve an ISRC to the Deezer **public-API** track (with `bpm`, `gain`,
+ * `isrc`, `preview`, `contributors`). Unlike the converter's `isrc2deezer`, this
+ * does not hydrate a gw track — pass `result.id` to `getTrackInfo` for that.
+ *
+ * @throws when Deezer has no track for the code
+ */
+const getTrackByISRC = (isrc) => (0, request_1.requestPublicApi)(`/track/isrc:${encodeURIComponent(isrc)}`);
+exports.getTrackByISRC = getTrackByISRC;
+/**
+ * Resolve a UPC / EAN barcode to the Deezer **public-API** album (with its
+ * `tracks`). A 13-digit barcode with a leading `0` is trimmed to 12, matching
+ * Deezer's own lookup.
+ *
+ * @throws when Deezer has no album for the code
+ */
+const getAlbumByUPC = (upc) => {
+    const code = upc.length > 12 && upc.startsWith('0') ? upc.slice(-12) : upc;
+    return (0, request_1.requestPublicApi)(`/album/upc:${encodeURIComponent(code)}`);
+};
+exports.getAlbumByUPC = getAlbumByUPC;

package/dist/api/index.d.ts

@@ -1,3 +1,5 @@
 export * from './api';
 export * from './request';
 export * from './search';
+export * from './browse';
+export * from './preview';

package/dist/api/index.js

@@ -17,3 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./api"), exports);
 __exportStar(require("./request"), exports);
 __exportStar(require("./search"), exports);
+__exportStar(require("./browse"), exports);
+__exportStar(require("./preview"), exports);

package/dist/api/preview.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="node" />
+import type { trackType } from '../types';
+export interface TrackPreview {
+    /** direct URL to a ~30 s MP3 clip — no licence, no encryption, no `arl` */
+    url: string;
+    /** clip length in seconds (Deezer previews are 30 s) */
+    duration: number;
+}
+/**
+ * The 30-second preview clip for a track. Deezer exposes it two ways:
+ * `song.getData` carries it in `MEDIA` (`{TYPE: 'preview', HREF}`), and the
+ * public `/track/` endpoint carries it as `preview`. Pass a gw `track` object
+ * (uses `MEDIA`, no extra request) or a track id (one public-API lookup).
+ *
+ * The clip is a plain MP3 — never Blowfish-encrypted — so it needs no
+ * `decryptDownload` and is safe to use in tests and "audition before download"
+ * flows.
+ */
+export declare const getTrackPreview: (track: trackType | string | number) => Promise<TrackPreview | null>;
+/** Fetch the 30-second preview clip as a `Buffer` (plain MP3, no decryption needed). */
+export declare const downloadPreview: (track: trackType | string | number) => Promise<Buffer | null>;

package/dist/api/preview.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadPreview = exports.getTrackPreview = void 0;
+const http_1 = require("../lib/http");
+const api_1 = require("./api");
+/**
+ * The 30-second preview clip for a track. Deezer exposes it two ways:
+ * `song.getData` carries it in `MEDIA` (`{TYPE: 'preview', HREF}`), and the
+ * public `/track/` endpoint carries it as `preview`. Pass a gw `track` object
+ * (uses `MEDIA`, no extra request) or a track id (one public-API lookup).
+ *
+ * The clip is a plain MP3 — never Blowfish-encrypted — so it needs no
+ * `decryptDownload` and is safe to use in tests and "audition before download"
+ * flows.
+ */
+const getTrackPreview = async (track) => {
+    var _a;
+    if (typeof track === 'object') {
+        const media = (_a = track.MEDIA) === null || _a === void 0 ? void 0 : _a[0];
+        if ((media === null || media === void 0 ? void 0 : media.HREF) && (!media.TYPE || media.TYPE === 'preview')) {
+            return { url: media.HREF, duration: 30 };
+        }
+        const pub = await (0, api_1.getTrackInfoPublicApi)(track.SNG_ID);
+        return pub.preview ? { url: pub.preview, duration: 30 } : null;
+    }
+    const pub = await (0, api_1.getTrackInfoPublicApi)(String(track));
+    return pub.preview ? { url: pub.preview, duration: 30 } : null;
+};
+exports.getTrackPreview = getTrackPreview;
+/** Fetch the 30-second preview clip as a `Buffer` (plain MP3, no decryption needed). */
+const downloadPreview = async (track) => {
+    const preview = await (0, exports.getTrackPreview)(track);
+    if (!preview)
+        return null;
+    return (0, http_1.getBuffer)(preview.url);
+};
+exports.downloadPreview = downloadPreview;

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

@@ -13,8 +13,24 @@ export declare class ExpiredTrackToken extends Error {
     readonly sngId: string;
     constructor(sngId: string);
 }
-/** quality code -> the `format` string the media API expects */
-export declare const formatName: (quality: number) => string;
+/**
+ * Every audio format Deezer's `get_url` understands, best → worst. `FLAC`,
+ * `MP3_320` and `MP3_128` are the classic `9 / 3 / 1` qualities; the rest are
+ * additional tiers (`MP3_256`, `MP3_64`, the `AAC_64` / `MP4_RA*` HE-AAC ladder)
+ * that some accounts and regions expose.
+ */
+export declare const DEEZER_FORMATS: readonly ["FLAC", "MP3_320", "MP3_256", "MP3_128", "MP3_64", "AAC_64", "MP4_RA3", "MP4_RA2", "MP4_RA1"];
+export type DeezerFormat = (typeof DEEZER_FORMATS)[number];
+/** A quality request: the numeric `1 | 3 | 9` shorthand, or any format string. */
+export type Quality = number | DeezerFormat | string;
+/** Normalise a {@link Quality} (number shorthand or format string) to a format string. */
+export declare const toFormat: (quality: Quality) => string;
+/**
+ * Quality code (`1 | 3 | 9`) or format string → the `format` string the media
+ * API expects. Format strings pass straight through, so this doubles as a
+ * validator-free identity for `'AAC_64'`, `'MP3_256'`, …
+ */
+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)
@@ -28,18 +44,21 @@ export interface ResolvedUrl {
     trackUrl: string;
     isEncrypted: boolean;
     fileSize: number;
-    /** the format Deezer actually returned, e.g. `'FLAC'` */
+    /** the format Deezer actually returned, e.g. `'FLAC'`, `'MP3_128'`, `'AAC_64'` */
     format: string;
+    /** the cipher Deezer applied — `'BF_CBC_STRIPE'` (stripe-encrypted) or `'NONE'` */
+    cipher: string;
 }
 /**
  * Resolve download URLs for many tracks in a **single** `get_url` request.
  *
- * `qualities` is an ordered preference list (e.g. `[9, 3, 1]`): Deezer returns
- * the best each track is licensed for, so there is no per-quality retry. The
- * result has one entry per input track, in order; `null` for a track that is
- * geo-blocked, unavailable, or errored.
+ * `qualities` is an ordered preference list: Deezer returns the best each track
+ * is licensed for, so there is no per-quality retry. Entries may be the numeric
+ * `1 | 3 | 9` shorthand **or** any format string from {@link DEEZER_FORMATS}
+ * (e.g. `['FLAC', 'MP3_320', 'AAC_64']`). The result has one entry per input
+ * track, in order; `null` for a track that is geo-blocked, unavailable, or errored.
  *
  * @param tracks    from `getTrackInfo` / `parseInfo` (needs `TRACK_TOKEN`, `SNG_ID`, `FILESIZE_*`)
- * @param qualities preference order — 9 = FLAC, 3 = MP3 320, 1 = MP3 128
+ * @param qualities preference order — default `[9, 3, 1]` (FLAC → MP3 320 → MP3 128)
  */
-export declare const resolveDownloadUrls: (tracks: trackType[], qualities?: number[]) => Promise<(ResolvedUrl | null)[]>;
+export declare const resolveDownloadUrls: (tracks: trackType[], qualities?: Quality[]) => Promise<(ResolvedUrl | null)[]>;

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.ExpiredTrackToken = exports.GeoBlocked = exports.WrongLicense = void 0;
+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 http_1 = require("../lib/http");
@@ -37,17 +37,50 @@ class ExpiredTrackToken extends Error {
 }
 exports.ExpiredTrackToken = ExpiredTrackToken;
 let user_data = null;
-const getTrackFileSize = (track, quality) => {
-    switch (quality) {
-        case 9:
-            return Number(track.FILESIZE_FLAC);
-        case 3:
-            return Number(track.FILESIZE_MP3_320);
-        case 1:
-            return Number(track.FILESIZE_MP3_128);
-        default:
-            return 0;
+/**
+ * Every audio format Deezer's `get_url` understands, best → worst. `FLAC`,
+ * `MP3_320` and `MP3_128` are the classic `9 / 3 / 1` qualities; the rest are
+ * additional tiers (`MP3_256`, `MP3_64`, the `AAC_64` / `MP4_RA*` HE-AAC ladder)
+ * that some accounts and regions expose.
+ */
+exports.DEEZER_FORMATS = [
+    'FLAC',
+    'MP3_320',
+    'MP3_256',
+    'MP3_128',
+    'MP3_64',
+    'AAC_64',
+    'MP4_RA3',
+    'MP4_RA2',
+    'MP4_RA1',
+];
+const FORMAT_FILESIZE_KEY = {
+    FLAC: 'FILESIZE_FLAC',
+    MP3_320: 'FILESIZE_MP3_320',
+    MP3_256: 'FILESIZE_MP3_256',
+    MP3_128: 'FILESIZE_MP3_128',
+    MP3_64: 'FILESIZE_MP3_64',
+    MP3_MISC: 'FILESIZE_MP3_MISC',
+    AAC_64: 'FILESIZE_AAC_64',
+    MP4_RA1: 'FILESIZE_MP4_RA1',
+    MP4_RA2: 'FILESIZE_MP4_RA2',
+    MP4_RA3: 'FILESIZE_MP4_RA3',
+};
+const NUMERIC_FORMAT = { 9: 'FLAC', 3: 'MP3_320', 1: 'MP3_128' };
+/** Normalise a {@link Quality} (number shorthand or format string) to a format string. */
+const toFormat = (quality) => {
+    if (typeof quality === 'number') {
+        const f = NUMERIC_FORMAT[quality];
+        if (!f)
+            throw new Error(`Unknown quality ${quality}`);
+        return f;
     }
+    return quality;
+};
+exports.toFormat = toFormat;
+const getTrackFileSize = (track, quality) => {
+    const key = FORMAT_FILESIZE_KEY[(0, exports.toFormat)(quality)];
+    return key ? Number(track[key]) || 0 : 0;
 };
 const dzAuthenticate = async () => {
     const { data } = await request_1.default.get('https://www.deezer.com/ajax/gw-light.php', {
@@ -66,19 +99,12 @@ const dzAuthenticate = async () => {
     return user_data;
 };
 const MEDIA_MAX_RETRIES = 3;
-/** quality code -> the `format` string the media API expects */
-const formatName = (quality) => {
-    switch (quality) {
-        case 9:
-            return 'FLAC';
-        case 3:
-            return 'MP3_320';
-        case 1:
-            return 'MP3_128';
-        default:
-            throw new Error(`Unknown quality ${quality}`);
-    }
-};
+/**
+ * Quality code (`1 | 3 | 9`) or format string → the `format` string the media
+ * API expects. Format strings pass straight through, so this doubles as a
+ * validator-free identity for `'AAC_64'`, `'MP3_256'`, …
+ */
+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) => {
@@ -104,7 +130,7 @@ const mediaGetUrl = async (track_tokens, formats, attempt = 0) => {
 };
 /** Parse one `data[i]` entry from a get_url response into a source URL (or null / throw). */
 const parseMediaEntry = (entry, token, country) => {
-    var _a, _b;
+    var _a, _b, _c, _d;
     if (entry === null || entry === void 0 ? void 0 : entry.errors) {
         const { code } = entry.errors[0];
         if (code === 2002)
@@ -116,10 +142,11 @@ const parseMediaEntry = (entry, token, country) => {
     const media = (_a = entry === null || entry === void 0 ? void 0 : entry.media) === null || _a === void 0 ? void 0 : _a[0];
     if (!((_b = media === null || media === void 0 ? void 0 : media.sources) === null || _b === void 0 ? void 0 : _b.length))
         return null;
-    return { url: media.sources[0].url, format: media.format };
+    return { url: media.sources[0].url, format: media.format, cipher: (_d = (_c = media.cipher) === null || _c === void 0 ? void 0 : _c.type) !== null && _d !== void 0 ? _d : 'BF_CBC_STRIPE' };
 };
+/** 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) => {
-    var _a, _b;
     const user = user_data ? user_data : await dzAuthenticate();
     if ((format === 'FLAC' && !user.can_stream_lossless) || (format === 'MP3_320' && !user.can_stream_hq)) {
         throw new WrongLicense(format);
@@ -127,7 +154,7 @@ const getTrackUrlFromServer = async (track_token, format) => {
     const { data, country } = await mediaGetUrl([track_token], [{ format, cipher: 'BF_CBC_STRIPE' }]);
     if (!data.length)
         return null;
-    return (_b = (_a = parseMediaEntry(data[0], track_token, country)) === null || _a === void 0 ? void 0 : _a.url) !== null && _b !== void 0 ? _b : null;
+    return parseMediaEntry(data[0], track_token, country);
 };
 /**
  * @param track Track info json returned from `getTrackInfo`
@@ -148,11 +175,11 @@ const getTrackDownloadUrl = async (track, quality) => {
     else {
         // Get URL with the official API
         try {
-            const url = await getTrackUrlFromServer(track.TRACK_TOKEN, format);
-            if (url) {
+            const resolved = await getTrackUrlFromServer(track.TRACK_TOKEN, format);
+            if (resolved) {
                 return {
-                    trackUrl: url,
-                    isEncrypted: url.includes('/mobile/') || url.includes('/media/'),
+                    trackUrl: resolved.url,
+                    isEncrypted: cipherIsEncrypted(resolved.cipher, resolved.url),
                     fileSize: getTrackFileSize(track, quality),
                 };
             }
@@ -213,17 +240,17 @@ const testUrl = async (url) => {
         return 0;
     }
 };
-const QUALITY_OF_FORMAT = { FLAC: 9, MP3_320: 3, MP3_128: 1, MP3_256: 3, MP3_64: 1 };
 /**
  * Resolve download URLs for many tracks in a **single** `get_url` request.
  *
- * `qualities` is an ordered preference list (e.g. `[9, 3, 1]`): Deezer returns
- * the best each track is licensed for, so there is no per-quality retry. The
- * result has one entry per input track, in order; `null` for a track that is
- * geo-blocked, unavailable, or errored.
+ * `qualities` is an ordered preference list: Deezer returns the best each track
+ * is licensed for, so there is no per-quality retry. Entries may be the numeric
+ * `1 | 3 | 9` shorthand **or** any format string from {@link DEEZER_FORMATS}
+ * (e.g. `['FLAC', 'MP3_320', 'AAC_64']`). The result has one entry per input
+ * track, in order; `null` for a track that is geo-blocked, unavailable, or errored.
  *
  * @param tracks    from `getTrackInfo` / `parseInfo` (needs `TRACK_TOKEN`, `SNG_ID`, `FILESIZE_*`)
- * @param qualities preference order — 9 = FLAC, 3 = MP3 320, 1 = MP3 128
+ * @param qualities preference order — default `[9, 3, 1]` (FLAC → MP3 320 → MP3 128)
  */
 const resolveDownloadUrls = async (tracks, qualities = [9, 3, 1]) => {
     if (!tracks.length)
@@ -231,7 +258,6 @@ const resolveDownloadUrls = async (tracks, qualities = [9, 3, 1]) => {
     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);
     return tracks.map((track, i) => {
-        var _a;
         let parsed;
         try {
             parsed = parseMediaEntry(data[i], track.TRACK_TOKEN, country);
@@ -242,12 +268,12 @@ const resolveDownloadUrls = async (tracks, qualities = [9, 3, 1]) => {
         }
         if (!parsed)
             return null;
-        const q = (_a = QUALITY_OF_FORMAT[parsed.format]) !== null && _a !== void 0 ? _a : qualities[0];
         return {
             trackUrl: parsed.url,
-            isEncrypted: parsed.url.includes('/mobile/') || parsed.url.includes('/media/'),
-            fileSize: getTrackFileSize(track, q),
+            isEncrypted: cipherIsEncrypted(parsed.cipher, parsed.url),
+            fileSize: getTrackFileSize(track, parsed.format),
             format: parsed.format,
+            cipher: parsed.cipher,
         };
     });
 };

package/dist/types/browse.d.ts

@@ -0,0 +1,85 @@
+import type { searchResultAlbum, searchResultArtist, searchResultPlaylist, searchResultTrack } from './search';
+/** The `{data, total, next?, prev?}` envelope every paginated public-API list uses. */
+export interface publicApiList<T> {
+    data: T[];
+    total?: number;
+    /** absolute URL of the next page, when there is one */
+    next?: string;
+    prev?: string;
+}
+export interface chartTrack extends searchResultTrack {
+    /** 1-based position in the chart */
+    position: number;
+}
+export interface chartArtist extends searchResultArtist {
+    position: number;
+}
+export interface chartAlbum extends searchResultAlbum {
+    position: number;
+}
+export interface chartPlaylist extends searchResultPlaylist {
+    position: number;
+}
+export interface chartPodcast {
+    id: number;
+    title: string;
+    description?: string;
+    available?: boolean;
+    fans?: number;
+    link?: string;
+    share?: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    position: number;
+    type: 'podcast';
+}
+/** `/chart/{genreId}` — the five ranked lists Deezer publishes per genre (`0` = all genres). */
+export interface chartType {
+    tracks: publicApiList<chartTrack>;
+    albums: publicApiList<chartAlbum>;
+    artists: publicApiList<chartArtist>;
+    playlists: publicApiList<chartPlaylist>;
+    podcasts: publicApiList<chartPodcast>;
+}
+export interface genreType {
+    id: number;
+    name: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    type: 'genre';
+}
+export interface editorialType {
+    id: number;
+    name: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    type: 'editorial';
+}
+/** An album from `/artist/{id}/albums` — the artist's own discography, public-API shape. */
+export interface artistAlbumResult {
+    id: number;
+    title: string;
+    link: string;
+    cover: string;
+    cover_small?: string;
+    cover_medium?: string;
+    cover_big?: string;
+    cover_xl?: string;
+    md5_image: string;
+    genre_id: number;
+    fans?: number;
+    release_date: string;
+    record_type: string;
+    tracklist: string;
+    explicit_lyrics: boolean;
+    type: 'album';
+}

package/dist/types/browse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from './album';
 export * from './artist';
+export * from './browse';
 export * from './show';
 export * from './playlist';
 export * from './playlist-channel';

package/dist/types/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./album"), exports);
 __exportStar(require("./artist"), exports);
+__exportStar(require("./browse"), exports);
 __exportStar(require("./show"), exports);
 __exportStar(require("./playlist"), exports);
 __exportStar(require("./playlist-channel"), exports);

package/dist/types/tracks.d.ts

@@ -1,6 +1,6 @@
 import type { artistType } from './artist';
 interface mediaType {
-    TYPE: 'preview';
+    TYPE: 'preview' | string;
     HREF: string;
 }
 export interface lyricsSync {
@@ -59,15 +59,19 @@ interface songType {
     URL_REWRITING: string;
     VERSION?: string;
     MD5_ORIGIN?: string;
-    FILESIZE_AAC_64: '0';
+    FILESIZE_AAC_64: string;
     FILESIZE_MP3_64: string;
     FILESIZE_MP3_128: string;
-    FILESIZE_MP3_256: '0';
-    FILESIZE_MP3_320: '0';
-    FILESIZE_MP4_RA1: '0';
-    FILESIZE_MP4_RA2: '0';
-    FILESIZE_MP4_RA3: '0';
-    FILESIZE_FLAC: '0';
+    FILESIZE_MP3_256: string;
+    FILESIZE_MP3_320: string;
+    FILESIZE_MP3_MISC?: string;
+    FILESIZE_MP4_RA1: string;
+    FILESIZE_MP4_RA2: string;
+    FILESIZE_MP4_RA3: string;
+    FILESIZE_MHM1_RA1?: string;
+    FILESIZE_MHM1_RA2?: string;
+    FILESIZE_MHM1_RA3?: string;
+    FILESIZE_FLAC: string;
     FILESIZE: string;
     GAIN: string;
     MEDIA_VERSION: string;

package/package.json

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