gerdur-core 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # 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.
+
+### Added
+
+- **`searchPublicApi(query, options?)`** — search the public REST API
+  (`api.deezer.com/search`) rather than the internal `pageSearch` gateway.
+  Returns clean public-API objects (`isrc`, `preview`, `rank`, numeric ids) and
+  takes `type` (`track` | `album` | `artist` | `playlist` | `user` | `radio` |
+  `podcast`), `order`, `strict`, and `limit` / `index` paging. No auth required.
+- **`searchTracks` / `searchAlbums` / `searchArtists` / `searchPlaylists`** —
+  thin typed wrappers over `searchPublicApi` with the entity fixed.
+- **`buildAdvancedQuery(filters)`** — pure helper that composes Deezer's advanced
+  operators into one query string: `{artist, album, track, label}` →
+  `artist:"…"`, `{durMin, durMax, bpmMin, bpmMax}` → `dur_min:NNN` / `bpm_min:NNN`,
+  free-text `query` first. Reliable on the track index only (Deezer's
+  `/search/album` and `/search/artist` ignore the operators).
+- **`suggest(query, nb?)`** — the `deezer.suggest` autocomplete endpoint, for
+  "as you type" UIs; cheaper than a full `searchMusic`.
+- New exported types: `advancedSearchFilters`, `searchOrder`, `searchEntity`,
+  `publicApiSearchOptions`, `publicApiSearchResponse<T>`, `searchResultTrack`,
+  `searchResultAlbum`, `searchResultArtist`, `searchResultPlaylist`,
+  `suggestResult`.
+
+### Fixed
+
+- **`getPlaylistChannel`** returned `MISSING_PARAMETER_PAGE` — the nested
+  `gateway_input` was serialised as `[object Object]`. It is now JSON-stringified
+  before the request, so channel pages resolve again.
+
 ## 2.0.0 - 2026-08-31
 
 Metadata overhaul — extract everything Deezer actually exposes for a track.

package/README.md

@@ -162,6 +162,75 @@ All method returns `Object` or throws `Error`. Make sure to catch error on your
 | `types`    |    No    |  `array` | ['TRACK'] |           array of search types |
 | `limit`    |    No    | `number` |        15 | maximum item to fetch per types |
 
+### `.searchPublicApi(query, options?)` — and `.searchTracks` / `.searchAlbums` / `.searchArtists` / `.searchPlaylists`
+
+Hits the **public** REST API (`api.deezer.com/search`) instead of the internal
+`pageSearch` gateway. Returns clean public-API objects (`isrc`, `preview`,
+`rank`, numeric ids), accepts the advanced query operators, an `order`, and
+`limit` / `index` paging. No auth required.
+
+| Parameters       | Required | Type      | Description                                                                   |
+| ---------------- | :------: | --------- | --------------------------------------------------------------------------- |
+| `query`          | Yes      | `string`  | plain text, or the output of `buildAdvancedQuery`                            |
+| `options.type`   | No       | `string`  | `'track'` (default), `'album'`, `'artist'`, `'playlist'`, `'user'`, `'radio'` |
+| `options.order`  | No       | `string`  | `RANKING`, `TRACK_ASC`, `RATING_DESC`, `DURATION_DESC`, …                    |
+| `options.strict` | No       | `boolean` | send Deezer's `strict=on` (disables the fuzzy fallback)                     |
+| `options.limit`  | No       | `number`  | page size (Deezer caps near 100)                                            |
+| `options.index`  | No       | `number`  | offset into the result set                                                  |
+
+```js
+const {data} = await searchTracks(buildAdvancedQuery({artist: 'daft punk', durMin: 200}), {limit: 25});
+```
+
+### `.buildAdvancedQuery(filters)`
+
+Pure helper — composes Deezer's advanced operators into one query string.
+`{artist, album, track, label}` become `artist:"…"`; `{durMin, durMax, bpmMin, bpmMax}`
+become `dur_min:NNN` / `bpm_min:NNN`; a free-text `query` is emitted first.
+Reliable only on the **track** index — `/search/album` and `/search/artist`
+ignore the operators, so pass a plain string there.
+
+### `.suggest(query, nb?)`
+
+`deezer.suggest` autocomplete — cheaper and faster than `searchMusic`, for
+"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/api.js

@@ -177,6 +177,9 @@ const getPlaylistChannel = async (page) => {
         lang: 'en',
         timezone_offset: '6',
     };
-    return await (0, request_1.requestGet)('app_page_get', { gateway_input }, page);
+    // `gateway_input` is a nested object; it must reach the gateway as a JSON
+    // string, otherwise it serialises to `[object Object]` and Deezer reports the
+    // inner `page` as missing (`MISSING_PARAMETER_PAGE`).
+    return await (0, request_1.requestGet)('app_page_get', { gateway_input: JSON.stringify(gateway_input) }, page);
 };
 exports.getPlaylistChannel = getPlaylistChannel;

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

package/dist/api/index.js

@@ -16,3 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./api"), exports);
 __exportStar(require("./request"), exports);
+__exportStar(require("./search"), exports);
+__exportStar(require("./browse"), exports);

package/dist/api/search.d.ts

@@ -0,0 +1,49 @@
+import type { advancedSearchFilters, publicApiSearchOptions, publicApiSearchResponse, searchResultAlbum, searchResultArtist, searchResultPlaylist, searchResultTrack, suggestResult } from '../types';
+/**
+ * Compose Deezer's advanced search operators into one query string.
+ *
+ * ```ts
+ * buildAdvancedQuery({artist: 'daft punk', durMin: 200, durMax: 400});
+ * // => 'artist:"daft punk" dur_min:200 dur_max:400'
+ * ```
+ *
+ * Free-text `query` is emitted first and bare. Deezer treats the operators as
+ * ranking hints rather than hard filters (and honours `track:` only now and
+ * then) — this only builds the string their docs describe. Pair it with
+ * `searchPublicApi(query, {strict: true})` to tighten what Deezer allows.
+ *
+ * The operators are reliable only on the **track** index (`searchPublicApi` /
+ * `searchTracks`). `/search/album` and `/search/artist` ignore or mishandle
+ * `artist:` / `album:` — use a plain string there.
+ */
+export declare const buildAdvancedQuery: (filters: advancedSearchFilters) => string;
+/**
+ * Search the **public** Deezer REST API (`api.deezer.com/search`).
+ *
+ * Unlike `searchMusic` (which drives the internal `deezer.pageSearch` gateway),
+ * this returns clean public-API objects — with `isrc`, `preview`, `rank`, real
+ * numeric ids — and accepts the advanced query operators (see
+ * `buildAdvancedQuery`), an `order`, and `limit` / `index` paging. No auth
+ * required; results are memoised by the api layer.
+ *
+ * @param query a plain string, or the output of `buildAdvancedQuery`
+ * @param options `type` (`'track'` default), `order`, `strict`, `limit`, `index`
+ */
+export declare const searchPublicApi: <T = searchResultTrack>(query: string, options?: publicApiSearchOptions) => Promise<publicApiSearchResponse<T>>;
+/** `searchPublicApi` fixed to tracks. */
+export declare const searchTracks: (query: string, options?: Omit<publicApiSearchOptions, 'type'>) => Promise<publicApiSearchResponse<searchResultTrack>>;
+/** `searchPublicApi` fixed to albums. */
+export declare const searchAlbums: (query: string, options?: Omit<publicApiSearchOptions, 'type'>) => Promise<publicApiSearchResponse<searchResultAlbum>>;
+/** `searchPublicApi` fixed to artists. */
+export declare const searchArtists: (query: string, options?: Omit<publicApiSearchOptions, 'type'>) => Promise<publicApiSearchResponse<searchResultArtist>>;
+/** `searchPublicApi` fixed to playlists. */
+export declare const searchPlaylists: (query: string, options?: Omit<publicApiSearchOptions, 'type'>) => Promise<publicApiSearchResponse<searchResultPlaylist>>;
+/**
+ * `deezer.suggest` — the internal autocomplete endpoint. Cheaper and faster than
+ * a full `searchMusic`, and it powers "as you type" suggestion UIs. Needs an
+ * initialised session (`initDeezerApi`), like every gateway call.
+ *
+ * @param query partial query text
+ * @param nb    max items per type (default 5)
+ */
+export declare const suggest: (query: string, nb?: number) => Promise<suggestResult>;

package/dist/api/search.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggest = exports.searchPlaylists = exports.searchArtists = exports.searchAlbums = exports.searchTracks = exports.searchPublicApi = exports.buildAdvancedQuery = void 0;
+const request_1 = require("./request");
+/**
+ * Compose Deezer's advanced search operators into one query string.
+ *
+ * ```ts
+ * buildAdvancedQuery({artist: 'daft punk', durMin: 200, durMax: 400});
+ * // => 'artist:"daft punk" dur_min:200 dur_max:400'
+ * ```
+ *
+ * Free-text `query` is emitted first and bare. Deezer treats the operators as
+ * ranking hints rather than hard filters (and honours `track:` only now and
+ * then) — this only builds the string their docs describe. Pair it with
+ * `searchPublicApi(query, {strict: true})` to tighten what Deezer allows.
+ *
+ * The operators are reliable only on the **track** index (`searchPublicApi` /
+ * `searchTracks`). `/search/album` and `/search/artist` ignore or mishandle
+ * `artist:` / `album:` — use a plain string there.
+ */
+const buildAdvancedQuery = (filters) => {
+    const { query, artist, album, track, label, durMin, durMax, bpmMin, bpmMax } = filters;
+    const parts = [];
+    if (query && query.trim()) {
+        parts.push(query.trim());
+    }
+    const textOps = [
+        ['artist', artist],
+        ['album', album],
+        ['track', track],
+        ['label', label],
+    ];
+    for (const [op, value] of textOps) {
+        if (value && value.trim()) {
+            parts.push(`${op}:"${value.trim().replace(/"/g, '')}"`);
+        }
+    }
+    const rangeOps = [
+        ['dur_min', durMin],
+        ['dur_max', durMax],
+        ['bpm_min', bpmMin],
+        ['bpm_max', bpmMax],
+    ];
+    for (const [op, value] of rangeOps) {
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+            parts.push(`${op}:${Math.round(value)}`);
+        }
+    }
+    return parts.join(' ');
+};
+exports.buildAdvancedQuery = buildAdvancedQuery;
+const SEARCH_ENTITIES = ['track', 'album', 'artist', 'playlist', 'user', 'radio', 'podcast'];
+/**
+ * Search the **public** Deezer REST API (`api.deezer.com/search`).
+ *
+ * Unlike `searchMusic` (which drives the internal `deezer.pageSearch` gateway),
+ * this returns clean public-API objects — with `isrc`, `preview`, `rank`, real
+ * numeric ids — and accepts the advanced query operators (see
+ * `buildAdvancedQuery`), an `order`, and `limit` / `index` paging. No auth
+ * required; results are memoised by the api layer.
+ *
+ * @param query a plain string, or the output of `buildAdvancedQuery`
+ * @param options `type` (`'track'` default), `order`, `strict`, `limit`, `index`
+ */
+const searchPublicApi = (query, options = {}) => {
+    const { type, order, strict, limit, index } = options;
+    const segment = type && type !== 'track' && SEARCH_ENTITIES.includes(type) ? `/${type}` : '';
+    const search = new URLSearchParams({ q: query });
+    if (strict) {
+        search.set('strict', 'on');
+    }
+    if (order) {
+        search.set('order', order);
+    }
+    if (typeof limit === 'number') {
+        search.set('limit', String(limit));
+    }
+    if (typeof index === 'number') {
+        search.set('index', String(index));
+    }
+    return (0, request_1.requestPublicApi)(`/search${segment}?${search.toString()}`);
+};
+exports.searchPublicApi = searchPublicApi;
+/** `searchPublicApi` fixed to tracks. */
+const searchTracks = (query, options = {}) => (0, exports.searchPublicApi)(query, { ...options, type: 'track' });
+exports.searchTracks = searchTracks;
+/** `searchPublicApi` fixed to albums. */
+const searchAlbums = (query, options = {}) => (0, exports.searchPublicApi)(query, { ...options, type: 'album' });
+exports.searchAlbums = searchAlbums;
+/** `searchPublicApi` fixed to artists. */
+const searchArtists = (query, options = {}) => (0, exports.searchPublicApi)(query, { ...options, type: 'artist' });
+exports.searchArtists = searchArtists;
+/** `searchPublicApi` fixed to playlists. */
+const searchPlaylists = (query, options = {}) => (0, exports.searchPublicApi)(query, { ...options, type: 'playlist' });
+exports.searchPlaylists = searchPlaylists;
+/**
+ * `deezer.suggest` — the internal autocomplete endpoint. Cheaper and faster than
+ * a full `searchMusic`, and it powers "as you type" suggestion UIs. Needs an
+ * initialised session (`initDeezerApi`), like every gateway call.
+ *
+ * @param query partial query text
+ * @param nb    max items per type (default 5)
+ */
+const suggest = (query, nb = 5) => (0, request_1.requestLight)({
+    QUERY: query,
+    NB: nb,
+    TYPES: { ALBUM: true, ARTIST: true, TRACK: true, PLAYLIST: true, RADIO: true, SHOW: true },
+}, 'deezer.suggest');
+exports.suggest = suggest;

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/search.d.ts

@@ -47,6 +47,163 @@ export interface discographyType {
     start: number;
     nb: number;
 }
+/**
+ * Deezer's advanced search operators. Compose these into one query string with
+ * `buildAdvancedQuery()` — e.g. `{artist: 'daft punk', durMin: 200}` becomes
+ * `artist:"daft punk" dur_min:200`.
+ *
+ * Deezer applies these as ranking hints, not hard filters, and honours `track:`
+ * only intermittently on their side — this type just mirrors the syntax they
+ * document.
+ */
+export interface advancedSearchFilters {
+    /** free-text terms, emitted first and bare */
+    query?: string;
+    artist?: string;
+    album?: string;
+    track?: string;
+    label?: string;
+    /** minimum duration, seconds */
+    durMin?: number;
+    /** maximum duration, seconds */
+    durMax?: number;
+    /** minimum beats-per-minute */
+    bpmMin?: number;
+    /** maximum beats-per-minute */
+    bpmMax?: number;
+}
+export type searchOrder = 'RANKING' | 'TRACK_ASC' | 'TRACK_DESC' | 'ARTIST_ASC' | 'ARTIST_DESC' | 'ALBUM_ASC' | 'ALBUM_DESC' | 'RATING_ASC' | 'RATING_DESC' | 'DURATION_ASC' | 'DURATION_DESC';
+export type searchEntity = 'track' | 'album' | 'artist' | 'playlist' | 'user' | 'radio' | 'podcast';
+export interface publicApiSearchOptions {
+    /** which index to hit — `track` (default), `album`, `artist`, `playlist`, `user`, `radio`, `podcast` */
+    type?: searchEntity;
+    order?: searchOrder;
+    /** send Deezer's `strict=on` — disables the fuzzy fallback */
+    strict?: boolean;
+    /** page size; Deezer caps this near 100 */
+    limit?: number;
+    /** offset into the result set */
+    index?: number;
+}
+export interface publicApiSearchResponse<T> {
+    data: T[];
+    total: number;
+    /** absolute URL of the next page, when there is one */
+    next?: string;
+    prev?: string;
+}
+interface searchArtistRef {
+    id: number;
+    name: string;
+    link?: string;
+    picture?: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    tracklist?: string;
+    type: 'artist';
+}
+interface searchAlbumRef {
+    id: number;
+    title: string;
+    cover?: string;
+    cover_small?: string;
+    cover_medium?: string;
+    cover_big?: string;
+    cover_xl?: string;
+    md5_image?: string;
+    tracklist?: string;
+    type: 'album';
+}
+export interface searchResultTrack {
+    id: number;
+    readable: boolean;
+    title: string;
+    title_short: string;
+    title_version?: string;
+    link: string;
+    duration: number;
+    rank: number;
+    explicit_lyrics: boolean;
+    explicit_content_lyrics: number;
+    explicit_content_cover: number;
+    preview: string;
+    md5_image: string;
+    isrc?: string;
+    artist: searchArtistRef;
+    album: searchAlbumRef;
+    type: 'track';
+}
+export interface searchResultAlbum {
+    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;
+    nb_tracks: number;
+    record_type: string;
+    explicit_lyrics: boolean;
+    artist: searchArtistRef;
+    type: 'album';
+}
+export interface searchResultArtist {
+    id: number;
+    name: string;
+    link: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    nb_album: number;
+    nb_fan: number;
+    radio: boolean;
+    tracklist: string;
+    type: 'artist';
+}
+export interface searchResultPlaylist {
+    id: number;
+    title: string;
+    public: boolean;
+    nb_tracks: number;
+    link: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    checksum?: string;
+    tracklist: string;
+    creation_date?: string;
+    user?: {
+        id: number;
+        name: string;
+        tracklist?: string;
+        type: 'user';
+    };
+    type: 'playlist';
+}
+/**
+ * `deezer.suggest` — lightweight autocomplete off the internal gateway. Each
+ * per-type array is gw-shaped (uppercase keys), same as `searchMusic`'s.
+ */
+export interface suggestResult {
+    QUERY: string;
+    TOP_RESULT: unknown[];
+    ORDER: string[];
+    ALBUM?: albumTypeMinimal[];
+    ARTIST?: artistInfoTypeMinimal[];
+    TRACK?: trackType[];
+    PLAYLIST?: playlistInfoMinimal[];
+    SHOW?: unknown[];
+    RADIO?: radioType[];
+}
 export interface searchType {
     QUERY: string;
     FUZZINNESS: boolean;

package/package.json

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