gerdur-core 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 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,40 @@ 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`).
+
 ### `.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/index.d.ts

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

package/dist/api/index.js

@@ -16,3 +16,4 @@ 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);

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/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.1.0",
   "description": "Core module for gerdur.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",