gerdur 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 2.2.0 - 2026-08-31
+
+### Added
+
+- **CLI search.** New flags — `--search`, `--artist`, `--album`, `--track`,
+  `--label`, `--bpm-min` / `--bpm-max`, `--dur-min` / `--dur-max`,
+  `--search-limit` — are composed into a Deezer advanced-search query. The
+  matches are listed and you tick which to download; `--headless` grabs every
+  match up to `--search-limit`. Hits are resolved to full tracks before
+  downloading, so quality fallback / tagging / `.lrc` sidecars all work.
+- **`search:` prefix** at the interactive prompt (and `-u 'search:…'`) runs the
+  same advanced track search, e.g. `search:artist:"daft punk" bpm_min:120`.
+- When Deezer's advanced operators return nothing (they are unreliable), the CLI
+  automatically retries the same words as a plain free-text query.
+
+### Changed
+
+- **`Session.searchAdvanced`** now falls back to a plain free-text query when the
+  advanced operators match nothing (opt out with `{fallback: false}`), and
+  accepts `fallback` in its options.
+- The interactive prompt now reads "Enter a URL, a search term, or
+  `search:<advanced query>`".
+- Search / filter helpers extracted to `src/lib/search.ts`
+  (`advancedFiltersFromFlags`, `searchAdvancedTracks`, `plainTextQuery`).
+
+## 2.1.0 - 2026-08-31
+
+### Added
+
+- **`gerdur-core@^2.1.0`** — the new search surface is re-exported from the
+  library: `searchPublicApi`, `searchTracks` / `searchAlbums` / `searchArtists` /
+  `searchPlaylists`, `buildAdvancedQuery`, `suggest`, plus the matching types.
+- **`Session.searchAdvanced(filters, options?)`** — structured search against the
+  public REST API — a free-text query plus `{artist, album, track, label, durMin,
+  durMax, bpmMin, bpmMax}`, with `order` / `limit` / `index`. Returns public-API
+  track objects with `isrc` / `preview`; fetch a hit's gw track with
+  `getTrackInfo(id)` to download.
+- **`Session.suggest(query, nb?)`** — `deezer.suggest` autocomplete.
+
+_No CLI changes in this release — the interactive `gerdur` flow is unchanged._
+
 ## 2.0.0 - 2026-08-31
 
 ### Changed

package/README.md

@@ -134,14 +134,65 @@ All options are optional. You can suppress prompts via providing `quality` and `
 | `--config-file`       |     `-conf`     |                               Config location. Example: `gerdur -conf my-gerdur.config.json`                                |                                                    Specify custom location to config file                                                     |
 | `--update`            |      `-U`       |                                                        *Nothing*                                                        |                                                       Download new update (binary only)                                                       |
 | `--help`              |      `-h`       |                                                        *Nothing*                                                        |                                                              Shows the CLI help                                                               |
+| `--search`            |     *None*      |                                                     free-text query                                                     |                                    Search tracks and pick what to download. Combine with the filters below.                                    |
+| `--artist`            |     *None*      |                                                      artist name                                                       |                                                  Search filter — restrict results to this artist                                              |
+| `--album`             |     *None*      |                                                      album title                                                       |                                                   Search filter — restrict results to this album                                              |
+| `--track`             |     *None*      |                                                      track title                                                       |                                                   Search filter — restrict results to this title                                              |
+| `--label`             |     *None*      |                                                     record label                                                      |                                                   Search filter — restrict results to this label                                              |
+| `--bpm-min` / `--bpm-max` | *None*      |                                                        number                                                          |                                                    Search filter — tempo range (beats per minute)                                            |
+| `--dur-min` / `--dur-max` | *None*      |                                                    number (seconds)                                                    |                                                       Search filter — track duration range                                                    |
+| `--search-limit`      |     *None*      |                                                   number (default 50)                                                  |                                                       How many search results to fetch                                                        |
+
+## Search
+
+### From the interactive prompt
+
+When `gerdur` asks for *"a URL, a search term, or `search:<advanced query>`"*:
+
+| Input | Does |
+| :--- | :--- |
+| `Harder Better Faster Stronger` | plain track search — pick tracks to download |
+| `artist:daft punk` | artist search — pick an artist, then its discography |
+| `album:discovery` | album search — pick an album |
+| `playlist:deep focus` | playlist search — pick a playlist |
+| `search:artist:"daft punk" bpm_min:120` | advanced track search (see operators below) |
+
+### From flags (works headless)
+
+The `--search` / `--artist` / `--album` / `--track` / `--label` / `--bpm-min` /
+`--bpm-max` / `--dur-min` / `--dur-max` flags are composed into one Deezer
+advanced-search query, the matches are listed, and — interactively — you pick
+which to download. In `--headless` mode every match (up to `--search-limit`) is
+downloaded.
+
+```bash
+# interactive: search, then tick the tracks you want
+gerdur --artist "Daft Punk" --track "Around the World"
+
+# headless: grab the first 5 matches as FLAC
+gerdur -d -q flac --search "get lucky" --artist "Daft Punk" --search-limit 5
+
+# tempo / duration windows
+gerdur --artist "Justice" --bpm-min 120 --bpm-max 130 --dur-min 180
+```
+
+Search hits are resolved to full tracks (via `getTrackInfo`) before downloading,
+so quality fallback, tagging and `.lrc` sidecars all work as normal.
+
+### Advanced query operators
 
-## Search Parameters
+Usable inside `--search`, after `search:`, or via `buildAdvancedQuery` in code.
+Deezer applies them as ranking hints (not hard filters), and they bite reliably
+only on **track** search:
 
-|   Prefix    |   Description   |
-| :---------: | :-------------: |
-|  `artist:`  |  Search artist  |
-|  `album:`   |  Search album   |
-| `playlist:` | Search playlist |
+| Operator | Example |
+| :--- | :--- |
+| `artist:` | `artist:"daft punk"` |
+| `album:` | `album:"discovery"` |
+| `track:` | `track:"one more time"` |
+| `label:` | `label:"Virgin"` |
+| `dur_min:` / `dur_max:` | `dur_min:200` (seconds) |
+| `bpm_min:` / `bpm_max:` | `bpm_min:120` |
 
 ## Programmatic API
 
@@ -175,12 +226,26 @@ await session.downloadUrl('https://deezer.com/album/302127', 'flac', {
 const {tracks} = await session.parseUrl('https://deezer.com/track/3135556');
 const found = await session.search('daft punk', ['TRACK'], 10);
 const results = await session.downloadTracks(tracks, '320', {output: '{ART_NAME} - {SNG_TITLE}'});
+
+// Structured search against the public REST API (isrc / preview / bpm-aware):
+const hits = await session.searchAdvanced(
+  {query: 'one more time', artist: 'daft punk', durMin: 200},
+  {limit: 25, order: 'RANKING'},
+);
+const suggestions = await session.suggest('daft'); // autocomplete
 ```
 
-Session methods: `parseUrl`, `search`, `getUser`, `getTrackBuffer`, `downloadTrack`,
-`downloadTracks`, `downloadUrl`. Every download call is silent; `downloadTracks` /
-`downloadUrl` accept `concurrency` and an `onProgress` callback and return one
-`{path, written} | null` per track.
+Session methods: `parseUrl`, `search`, `searchAdvanced`, `suggest`, `getUser`,
+`getTrackBuffer`, `downloadTrack`, `downloadTracks`, `downloadUrl`. Every download
+call is silent; `downloadTracks` / `downloadUrl` accept `concurrency` and an
+`onProgress` callback and return one `{path, written} | null` per track.
+
+`searchAdvanced(filters, options?)` builds a Deezer advanced-search query from
+`{query?, artist?, album?, track?, label?, durMin?, durMax?, bpmMin?, bpmMax?}`
+and takes `{order?, strict?, limit?, index?, fallback?}`. Deezer's operators are
+unreliable, so an empty result is retried as a plain free-text query unless
+`fallback: false`. It returns public-API track objects — fetch a hit's gw track
+with `getTrackInfo(id)` before downloading it.
 
 ### Low-level: primitives
 
@@ -204,9 +269,11 @@ const {path, written} = (await downloadTrackToFile(track, 'flac', {output: '{ART
 So you don't need `gerdur-core` as a second dependency (call after `initDeezerApi`
 or `createSession`):
 
-`parseInfo`, `searchMusic`, `getUser`, `getTrackInfo`, `getAlbumInfo`, `getAlbumTracks`,
-`getPlaylistInfo`, `getPlaylistTracks`, `getArtistInfo`, `getDiscography`, `getLyrics`,
-`getTrackDownloadUrl`, `GeoBlocked`.
+`parseInfo`, `searchMusic`, `searchPublicApi`, `searchTracks`, `searchAlbums`,
+`searchArtists`, `searchPlaylists`, `buildAdvancedQuery`, `suggest`, `getUser`,
+`getTrackInfo`, `getAlbumInfo`, `getAlbumTracks`, `getPlaylistInfo`,
+`getPlaylistTracks`, `getArtistInfo`, `getDiscography`, `getLyrics`,
+`getTrackDownloadUrl`, `resolveDownloadUrls`, `GeoBlocked`.
 
 ### Auth & config helpers
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gerdur",
-    "version": "2.0.0",
+    "version": "2.2.0",
     "description": "The crucial streaming module for dabox systems.",
     "author": "Christian",
     "license": "SEE LICENSE IN LICENSE",
@@ -48,7 +48,7 @@
         "adm-zip": "^0.5.16",
         "chalk": "^4.1.2",
         "commander": "^9.5.0",
-        "gerdur-core": "^2.0.0",
+        "gerdur-core": "^2.1.0",
         "dot-prop": "^6.0.1",
         "got": "^11.8.6",
         "gradient-string": "^2.0.2",

package/dist/src/gerdur.js

@@ -22,6 +22,7 @@ const update_check_1 = __importDefault(require("./lib/update-check"));
 const auto_updater_1 = __importDefault(require("./lib/auto-updater"));
 const arl_setup_1 = require("./lib/arl-setup");
 const util_1 = require("./lib/util");
+const search_1 = require("./lib/search");
 const package_json_1 = __importDefault(require("../package.json"));
 // App info
 console.log((0, gradient_string_1.default)('red', 'yellow', 'orange')(`             ♥ gerdur - ${package_json_1.default.version} ♥         `) +
@@ -46,7 +47,17 @@ const cmd = new commander_1.Command()
     .option('-d, --headless', 'Run in headless mode for scripting automation', false)
     .option('-conf, --config-file <file>', 'Custom location to your config file', 'gerdur.config.json')
     .option('-rfp, --resolve-full-path', 'Use absolute path for playlists')
-    .option('-cp, --create-playlist', 'Force create a playlist file for non playlists');
+    .option('-cp, --create-playlist', 'Force create a playlist file for non playlists')
+    .option('--search <query>', 'Search tracks by free text (combine with the filters below)')
+    .option('--artist <name>', 'Search filter: artist name')
+    .option('--album <name>', 'Search filter: album title')
+    .option('--track <name>', 'Search filter: track title')
+    .option('--label <name>', 'Search filter: record label')
+    .option('--bpm-min <n>', 'Search filter: minimum BPM')
+    .option('--bpm-max <n>', 'Search filter: maximum BPM')
+    .option('--dur-min <seconds>', 'Search filter: minimum duration')
+    .option('--dur-max <seconds>', 'Search filter: maximum duration')
+    .option('--search-limit <n>', 'Max search results to fetch', '50');
 if (process.pkg) {
     cmd.option('-U, --update', 'Update this program to latest version');
 }
@@ -59,14 +70,23 @@ if (cmd.args[0] && cmd.args[0].toLowerCase() === 'setup') {
 if (!options.url && cmd.args[0]) {
     options.url = cmd.args[0];
 }
+const toFiniteNumber = (value) => {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+};
+const advancedFilters = (0, search_1.advancedFiltersFromFlags)(options);
+let advancedFiltersConsumed = false;
 if (options.headless && !options.quality) {
     console.error(signale_1.default.error('Missing parameters --quality'));
     console.error(signale_1.default.note('Quality must be provided with headless mode'));
     process.exit(1);
 }
-if (options.headless && !options.url && !options.inputFile) {
+if (options.headless && !options.url && !options.inputFile && !advancedFilters) {
     console.error(signale_1.default.error('Missing parameters --url'));
-    console.error(signale_1.default.note('URL must be provided with headless mode'));
+    console.error(signale_1.default.note('Provide --url, --input-file, or a --search / --artist / … filter with headless mode'));
     process.exit(1);
 }
 const conf = new config_1.default(options.configFile);
@@ -79,8 +99,62 @@ const onCancel = () => {
     console.info(signale_1.default.note('Aborted!'));
     process.exit();
 };
+const stampVersion = (t) => {
+    if (t.VERSION && !t.SNG_TITLE.includes(t.VERSION)) {
+        t.SNG_TITLE += ' ' + t.VERSION;
+    }
+    return t;
+};
+/**
+ * Run an advanced (public-REST) track search, let the user pick, and hydrate the
+ * picks into download-ready gw tracks via `getTrackInfo`. Returns `null` when
+ * nothing was matched or selected.
+ */
+const resolveAdvancedSearch = async (filters) => {
+    const limit = toFiniteNumber(options.searchLimit) ?? 50;
+    const { data: results, query, usedFallback } = await (0, search_1.searchAdvancedTracks)(filters, { limit });
+    if (!query) {
+        return null;
+    }
+    console.log(signale_1.default.info(`Searching Deezer for: ${chalk_1.default.cyan(query)}`));
+    if (usedFallback) {
+        console.log(signale_1.default.note('No matches for the operators — retried as a plain-text search.'));
+    }
+    if (!results.length) {
+        console.log(signale_1.default.warn('No tracks matched that search.'));
+        return null;
+    }
+    let picks = results;
+    if (!options.headless) {
+        const choice = await (0, prompts_1.default)([
+            {
+                type: 'multiselect',
+                name: 'items',
+                message: `Select tracks to download. ${results.length} matched.`,
+                choices: results.map((r) => ({
+                    title: `${r.title} — ${r.artist?.name ?? 'Unknown'}`,
+                    value: r,
+                    description: `Album: ${r.album?.title ?? 'Unknown'} · ${(0, util_1.formatSecondsReadable)(r.duration)}${r.explicit_lyrics ? ' · explicit' : ''}`,
+                })),
+            },
+        ], { onCancel });
+        picks = choice.items ?? [];
+    }
+    if (!picks.length) {
+        return null;
+    }
+    console.log(signale_1.default.info(`Fetching track data for ${picks.length} ${picks.length === 1 ? 'track' : 'tracks'}…`));
+    const hydrated = await Promise.all(picks.map((r) => (0, gerdur_core_1.getTrackInfo)(String(r.id)).catch(() => null)));
+    const tracks = hydrated.filter((t) => Boolean(t && t.SNG_ID)).map(stampVersion);
+    if (!tracks.length) {
+        console.log(signale_1.default.warn('None of the selected tracks could be resolved.'));
+        return null;
+    }
+    return { info: { type: 'track', id: query }, linktype: 'track', linkinfo: {}, tracks };
+};
 const startDownload = async (saveLayout, url, skipPrompt) => {
     try {
+        url = url ?? '';
         if (!options.quality) {
             const { musicQuality } = await (0, prompts_1.default)([
                 {
@@ -97,19 +171,38 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
             ], { onCancel });
             options.quality = musicQuality;
         }
-        if (!url) {
+        let searchData = null;
+        // `--search` / `--artist` / `--bpm-min` … flags: structured search, no URL needed.
+        // Consumed once — the interactive re-prompt loop must not re-run it.
+        if (!url && advancedFilters && !advancedFiltersConsumed) {
+            advancedFiltersConsumed = true;
+            searchData = await resolveAdvancedSearch(advancedFilters);
+            if (!searchData) {
+                if (options.headless) {
+                    throw new Error('No tracks matched the search filters.');
+                }
+                return;
+            }
+        }
+        if (!searchData && !url) {
             const { query } = await (0, prompts_1.default)([
                 {
                     type: 'text',
                     name: 'query',
-                    message: 'Enter URL or search:',
+                    message: 'Enter a URL, a search term, or `search:<advanced query>`:',
                     validate: (value) => (value ? true : false),
                 },
             ], { onCancel });
             url = query;
         }
-        let searchData = null;
-        if (!url.match(urlRegex)) {
+        // `search:` prefix — advanced track search from the prompt or `-u search:…`.
+        if (!searchData && url && url.startsWith('search:')) {
+            searchData = await resolveAdvancedSearch({ query: url.slice('search:'.length).trim() });
+            if (!searchData) {
+                throw new Error('No tracks matched that search.');
+            }
+        }
+        if (!searchData && !url.match(urlRegex)) {
             if (options.headless) {
                 throw new Error('Please provide a valid URL. Unknown URL: ' + url);
             }
@@ -168,12 +261,7 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                     info: { type: 'track', id: url },
                     linktype: 'track',
                     linkinfo: {},
-                    tracks: TRACK.data.map((t) => {
-                        if (t.VERSION && !t.SNG_TITLE.includes(t.VERSION)) {
-                            t.SNG_TITLE += ' ' + t.VERSION;
-                        }
-                        return t;
-                    }),
+                    tracks: TRACK.data.map(stampVersion),
                 };
             }
         }

package/dist/src/index.d.ts

@@ -59,5 +59,6 @@ export type { SessionOptions, DownloadTracksOptions, SearchType } from './lib/se
 export { getTrackBuffer, getTaggedTrack, downloadTrackToFile } from './lib/api-download';
 export type { Quality, GetTrackBufferOptions, DownloadTrackOptions, DownloadResult } from './lib/api-download';
 export { default as Config, globalConfigPath, resolveConfigFile } from './lib/config';
-export { initDeezerApi, parseInfo, searchMusic, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, addTrackTags, getRichAlbum, normalizeContributors, toLrc, GeoBlocked, } from 'gerdur-core';
+export { initDeezerApi, parseInfo, searchMusic, searchPublicApi, searchTracks, searchAlbums, searchArtists, searchPlaylists, buildAdvancedQuery, suggest, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, addTrackTags, getRichAlbum, normalizeContributors, toLrc, GeoBlocked, } from 'gerdur-core';
 export type { AddTrackTagsOptions, TaggedTrack, TrackTagModel, RichAlbum, ResolvedUrl, NormalizedContributors, } from 'gerdur-core';
+export type { advancedSearchFilters, searchOrder, searchEntity, publicApiSearchOptions, publicApiSearchResponse, searchResultTrack, searchResultAlbum, searchResultArtist, searchResultPlaylist, suggestResult, } from 'gerdur-core/types';

package/dist/src/index.js

@@ -33,7 +33,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GeoBlocked = exports.toLrc = exports.normalizeContributors = exports.getRichAlbum = exports.addTrackTags = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.getLyrics = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getTrackInfo = exports.getUser = exports.searchMusic = exports.parseInfo = exports.initDeezerApi = exports.resolveConfigFile = exports.globalConfigPath = exports.Config = exports.downloadTrackToFile = exports.getTaggedTrack = exports.getTrackBuffer = exports.Session = exports.createSession = exports.getArl = exports.LoginError = exports.loginWithEmail = void 0;
+exports.GeoBlocked = exports.toLrc = exports.normalizeContributors = exports.getRichAlbum = exports.addTrackTags = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.getLyrics = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getTrackInfo = exports.getUser = exports.suggest = exports.buildAdvancedQuery = exports.searchPlaylists = exports.searchArtists = exports.searchAlbums = exports.searchTracks = exports.searchPublicApi = exports.searchMusic = exports.parseInfo = exports.initDeezerApi = exports.resolveConfigFile = exports.globalConfigPath = exports.Config = exports.downloadTrackToFile = exports.getTaggedTrack = exports.getTrackBuffer = exports.Session = exports.createSession = exports.getArl = exports.LoginError = exports.loginWithEmail = void 0;
 // ─── Authentication ────────────────────────────────────────────────────────
 const email_login_1 = require("./lib/email-login");
 Object.defineProperty(exports, "loginWithEmail", { enumerable: true, get: function () { return email_login_1.loginWithEmail; } });
@@ -89,6 +89,13 @@ var gerdur_core_1 = require("gerdur-core");
 Object.defineProperty(exports, "initDeezerApi", { enumerable: true, get: function () { return gerdur_core_1.initDeezerApi; } });
 Object.defineProperty(exports, "parseInfo", { enumerable: true, get: function () { return gerdur_core_1.parseInfo; } });
 Object.defineProperty(exports, "searchMusic", { enumerable: true, get: function () { return gerdur_core_1.searchMusic; } });
+Object.defineProperty(exports, "searchPublicApi", { enumerable: true, get: function () { return gerdur_core_1.searchPublicApi; } });
+Object.defineProperty(exports, "searchTracks", { enumerable: true, get: function () { return gerdur_core_1.searchTracks; } });
+Object.defineProperty(exports, "searchAlbums", { enumerable: true, get: function () { return gerdur_core_1.searchAlbums; } });
+Object.defineProperty(exports, "searchArtists", { enumerable: true, get: function () { return gerdur_core_1.searchArtists; } });
+Object.defineProperty(exports, "searchPlaylists", { enumerable: true, get: function () { return gerdur_core_1.searchPlaylists; } });
+Object.defineProperty(exports, "buildAdvancedQuery", { enumerable: true, get: function () { return gerdur_core_1.buildAdvancedQuery; } });
+Object.defineProperty(exports, "suggest", { enumerable: true, get: function () { return gerdur_core_1.suggest; } });
 Object.defineProperty(exports, "getUser", { enumerable: true, get: function () { return gerdur_core_1.getUser; } });
 Object.defineProperty(exports, "getTrackInfo", { enumerable: true, get: function () { return gerdur_core_1.getTrackInfo; } });
 Object.defineProperty(exports, "getAlbumInfo", { enumerable: true, get: function () { return gerdur_core_1.getAlbumInfo; } });

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

@@ -0,0 +1,39 @@
+import type { advancedSearchFilters, publicApiSearchOptions, publicApiSearchResponse, searchResultTrack } from 'gerdur-core/types';
+/** The raw `--search` / `--artist` / `--bpm-min` … values as `commander` parses them (strings). */
+export interface SearchFlags {
+    search?: string;
+    artist?: string;
+    album?: string;
+    track?: string;
+    label?: string;
+    bpmMin?: string | number;
+    bpmMax?: string | number;
+    durMin?: string | number;
+    durMax?: string | number;
+}
+/**
+ * Fold the CLI search flags into a {@link advancedSearchFilters} bag for
+ * `buildAdvancedQuery` / `searchTracks`. Returns `null` when none were supplied,
+ * so the caller can tell "no search requested" from "empty search".
+ */
+export declare const advancedFiltersFromFlags: (flags: SearchFlags) => advancedSearchFilters | null;
+/** The words in a filter bag, for a free-text retry when the operators come back empty. */
+export declare const plainTextQuery: (filters: advancedSearchFilters) => string;
+export interface AdvancedSearchOptions extends Omit<publicApiSearchOptions, 'type'> {
+    /**
+     * Deezer's advanced operators are unreliable. When they return nothing, retry
+     * with the same words as a plain free-text query. Default `true`.
+     */
+    fallback?: boolean;
+}
+export interface AdvancedSearchResult extends publicApiSearchResponse<searchResultTrack> {
+    /** the advanced-operator query that was built */
+    query: string;
+    /** whether the free-text fallback was used */
+    usedFallback: boolean;
+}
+/**
+ * `buildAdvancedQuery` + `searchTracks`, with an automatic free-text retry when
+ * the operators match nothing (unless `fallback: false`).
+ */
+export declare const searchAdvancedTracks: (filters: advancedSearchFilters, options?: AdvancedSearchOptions) => Promise<AdvancedSearchResult>;

package/dist/src/lib/search.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchAdvancedTracks = exports.plainTextQuery = exports.advancedFiltersFromFlags = void 0;
+const gerdur_core_1 = require("gerdur-core");
+const toFiniteNumber = (value) => {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+};
+const trimmed = (value) => {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const s = value.trim();
+    return s ? s : undefined;
+};
+/**
+ * Fold the CLI search flags into a {@link advancedSearchFilters} bag for
+ * `buildAdvancedQuery` / `searchTracks`. Returns `null` when none were supplied,
+ * so the caller can tell "no search requested" from "empty search".
+ */
+const advancedFiltersFromFlags = (flags) => {
+    const filters = {
+        query: trimmed(flags.search),
+        artist: trimmed(flags.artist),
+        album: trimmed(flags.album),
+        track: trimmed(flags.track),
+        label: trimmed(flags.label),
+        durMin: toFiniteNumber(flags.durMin),
+        durMax: toFiniteNumber(flags.durMax),
+        bpmMin: toFiniteNumber(flags.bpmMin),
+        bpmMax: toFiniteNumber(flags.bpmMax),
+    };
+    return Object.values(filters).some((v) => v !== undefined) ? filters : null;
+};
+exports.advancedFiltersFromFlags = advancedFiltersFromFlags;
+/** The words in a filter bag, for a free-text retry when the operators come back empty. */
+const plainTextQuery = (filters) => [filters.query, filters.artist, filters.album, filters.track, filters.label]
+    .filter((v) => Boolean(v))
+    .join(' ')
+    .trim();
+exports.plainTextQuery = plainTextQuery;
+/**
+ * `buildAdvancedQuery` + `searchTracks`, with an automatic free-text retry when
+ * the operators match nothing (unless `fallback: false`).
+ */
+const searchAdvancedTracks = async (filters, options = {}) => {
+    const { fallback = true, ...searchOptions } = options;
+    const query = (0, gerdur_core_1.buildAdvancedQuery)(filters);
+    // `query` already contains every text field, so an empty query means nothing to search.
+    if (!query) {
+        return { data: [], total: 0, query, usedFallback: false };
+    }
+    let response = await (0, gerdur_core_1.searchTracks)(query, searchOptions);
+    let usedFallback = false;
+    if (!response.data.length && fallback) {
+        const plain = (0, exports.plainTextQuery)(filters);
+        if (plain && plain !== query) {
+            response = await (0, gerdur_core_1.searchTracks)(plain, searchOptions);
+            usedFallback = true;
+        }
+    }
+    return { ...response, query, usedFallback };
+};
+exports.searchAdvancedTracks = searchAdvancedTracks;

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

@@ -1,7 +1,8 @@
 /// <reference types="node" />
 import { parseInfo, searchMusic } from 'gerdur-core';
+import type { AdvancedSearchOptions } from './search';
 import type { Quality, DownloadTrackOptions, DownloadResult } from './api-download';
-import type { trackType, userType } from 'gerdur-core/types';
+import type { trackType, userType, advancedSearchFilters, publicApiSearchResponse, searchResultTrack, suggestResult } from 'gerdur-core/types';
 /** Search result categories accepted by {@link Session.search}. */
 export type SearchType = 'ALBUM' | 'ARTIST' | 'TRACK' | 'PLAYLIST' | 'RADIO' | 'SHOW' | 'USER' | 'LIVESTREAM' | 'CHANNEL';
 export interface SessionOptions {
@@ -52,6 +53,18 @@ export declare class Session {
     parseUrl(url: string): ReturnType<typeof parseInfo>;
     /** Search Deezer. Defaults to track results. */
     search(query: string, types?: SearchType[], limit?: number): ReturnType<typeof searchMusic>;
+    /**
+     * Search the public REST API with structured filters (`{artist, album, track,
+     * label, durMin, durMax, bpmMin, bpmMax}`) plus a free-text `query`. Returns
+     * public-API track objects (with `isrc`, `preview`); to download a result,
+     * fetch its gw track first with the re-exported `getTrackInfo(id)`.
+     *
+     * Deezer's advanced operators are unreliable, so an empty result is retried as
+     * a plain free-text query unless `options.fallback` is `false`.
+     */
+    searchAdvanced(filters: advancedSearchFilters, options?: AdvancedSearchOptions): Promise<publicApiSearchResponse<searchResultTrack>>;
+    /** `deezer.suggest` autocomplete — for "as you type" UIs. `nb` caps items per type. */
+    suggest(query: string, nb?: number): Promise<suggestResult>;
     /** Return a fully tagged audio Buffer for a track (nothing written to disk). */
     getTrackBuffer(track: trackType, quality?: Quality, options?: {}): Promise<Buffer | null>;
     /** Download a single track to disk. */

package/dist/src/lib/session.js

@@ -8,6 +8,7 @@ const p_queue_1 = __importDefault(require("p-queue"));
 const gerdur_core_1 = require("gerdur-core");
 const email_login_1 = require("./email-login");
 const api_download_1 = require("./api-download");
+const search_1 = require("./search");
 /**
  * An authenticated Deezer session exposing high-level query and download
  * helpers. Create one with {@link createSession}. All methods are silent (no
@@ -57,6 +58,23 @@ class Session {
     search(query, types = ['TRACK'], limit) {
         return (0, gerdur_core_1.searchMusic)(query, types, limit);
     }
+    /**
+     * Search the public REST API with structured filters (`{artist, album, track,
+     * label, durMin, durMax, bpmMin, bpmMax}`) plus a free-text `query`. Returns
+     * public-API track objects (with `isrc`, `preview`); to download a result,
+     * fetch its gw track first with the re-exported `getTrackInfo(id)`.
+     *
+     * Deezer's advanced operators are unreliable, so an empty result is retried as
+     * a plain free-text query unless `options.fallback` is `false`.
+     */
+    async searchAdvanced(filters, options = {}) {
+        const { query: _query, usedFallback: _usedFallback, ...response } = await (0, search_1.searchAdvancedTracks)(filters, options);
+        return response;
+    }
+    /** `deezer.suggest` autocomplete — for "as you type" UIs. `nb` caps items per type. */
+    suggest(query, nb) {
+        return (0, gerdur_core_1.suggest)(query, nb);
+    }
     /** Return a fully tagged audio Buffer for a track (nothing written to disk). */
     getTrackBuffer(track, quality = '320', options = {}) {
         return (0, api_download_1.getTrackBuffer)(track, quality, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "The crucial streaming module for dabox systems.",
   "author": "Christian",
   "license": "SEE LICENSE IN LICENSE",
@@ -48,7 +48,7 @@
     "adm-zip": "^0.5.16",
     "chalk": "^4.1.2",
     "commander": "^9.5.0",
-    "gerdur-core": "^2.0.0",
+    "gerdur-core": "^2.1.0",
     "dot-prop": "^6.0.1",
     "got": "^11.8.6",
     "gradient-string": "^2.0.2",