gerdur-core 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 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 |

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,4 @@
 export * from './api';
 export * from './request';
 export * from './search';
+export * from './browse';

package/dist/api/index.js

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

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/package.json

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