gerdur-core 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 2.12.0 - 2026-08-31
+
+Phase 4 — an optional, read-only **enrichment** layer against open databases.
+Off by default, never touches `addTrackTags`.
+
+### Added
+
+- **MusicBrainz** (`src/enrich/`): `lookupRecordingByISRC(isrc)` — canonical
+  recording (title, artist credits, length, every known ISRC, the releases it's
+  on); `getMusicBrainzRecording(mbid)` / `getMusicBrainzRelease(mbid, inc?)` —
+  direct MBID lookups with label / catalogue number / barcode.
+  `configureMusicBrainz({userAgent, minIntervalMs})` — they require a descriptive
+  UA and ≤ 1 req/s.
+- **Cover Art Archive**: `getCoverArt(mbid, entity?)` and
+  `getBestCoverArtUrl(mbid, {minSize})` — higher-resolution covers than Deezer's
+  1800 px ceiling. `null` when there's no art.
+- **`PoliteJsonClient`** — the serialised, rate-limited, `503`/`429`-retrying,
+  `404`→`null` JSON client both use; exported for building your own.
+
+## 2.11.0 - 2026-08-31
+
+### Added
+
+- **`searchFacets(result)`** — flatten the per-type hit counts + Deezer's
+  relevance `order` out of a `searchMusic` result.
+
+### Internal
+
+- The live-API test suite skips more gracefully when an upstream (Deezer public
+  REST, Tidal, YouTube) rate-limits or consent-walls the runner — the
+  `--> DEEZER` converter tests and YouTube tests now degrade to a skip instead
+  of a hard fail.
+
 ## 2.10.0 - 2026-08-31
 
 Leftovers — batch token refresh + podcast episodes. Additive.

package/README.md

@@ -261,6 +261,16 @@ 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`).
 
+### `.searchFacets(result)`
+
+Flattens the per-type hit counts + Deezer's relevance `order` out of a
+`searchMusic` result — for "207 tracks · 99 albums · 17 artists" UIs.
+
+```js
+const r = await searchMusic('daft punk', ['TRACK', 'ALBUM', 'ARTIST']);
+searchFacets(r); // {track: 207, album: 99, artist: 17, …, order: ['TOP_RESULT','TRACK',…]}
+```
+
 ### Browse & discovery
 
 Public REST endpoints — no `arl` needed, memoised like the rest. All return a
@@ -427,6 +437,31 @@ the audio (ID3v2.3 for MP3, Vorbis comments for FLAC). Returns
 | `track`    |   Yes    | `object` | track object from `getTrackInfo` / `parseInfo` |
 | `options`  |    No    | `object` | `AddTrackTagsOptions` — `coverSize` (56–1800), pre-fetched `album`/`lyrics`/`cover`, and toggles (`richCredits`, `embedArtistImage`, `deezerIds`, …) |
 
+### Enrichment (optional, read-only)
+
+Fill gaps Deezer leaves, from open databases — **off by default, never wired into
+`addTrackTags`**. Both services rate-limit and want a descriptive `User-Agent`;
+call `configureMusicBrainz({userAgent})` once at startup.
+
+| Method | |
+| :--- | :--- |
+| `lookupRecordingByISRC(isrc)` | canonical MusicBrainz recording — title, artist credits, length, **all** known ISRCs, and the releases it's on (each with a `releaseGroupMbid`). `null` if unknown. |
+| `getMusicBrainzRecording(mbid)` / `getMusicBrainzRelease(mbid, inc?)` | direct MBID lookups — the release adds label, catalogue number, barcode. |
+| `getCoverArt(mbid, entity = 'release-group')` | Cover Art Archive images (`front` / `approved` / `thumbnails`). `null` when there's no art. |
+| `getBestCoverArtUrl(mbid, {entity?, minSize = 1200})` | one URL — the approved front cover at ≥ `minSize` px, else full-res. Deezer caps its own art at 1800 px; this goes bigger. |
+
+```js
+configureMusicBrainz({userAgent: 'myapp/1.0 ( me@example.com )'});
+const rec = await lookupRecordingByISRC(track.isrc);
+if (rec?.releases[0]?.releaseGroupMbid) {
+  const cover = await getBestCoverArtUrl(rec.releases[0].releaseGroupMbid, {minSize: 1200});
+}
+```
+
+Errors: a persistent MusicBrainz `503` ("server busy") surfaces as
+`HttpStatusError` after 3 backed-off retries — catch and fall back to Deezer's
+data.
+
 ###
 
 > We are not responsible for any misuse of this library by any third party. Please make sure to respect the artists and the music industry when using this library.

package/dist/api/search.d.ts

@@ -1,4 +1,4 @@
-import type { advancedSearchFilters, publicApiSearchOptions, publicApiSearchResponse, searchResultAlbum, searchResultArtist, searchResultPlaylist, searchResultTrack, suggestResult } from '../types';
+import type { advancedSearchFilters, publicApiSearchOptions, publicApiSearchResponse, searchResultAlbum, searchResultArtist, searchResultPlaylist, searchResultTrack, searchType, suggestResult } from '../types';
 /**
  * Compose Deezer's advanced search operators into one query string.
  *
@@ -47,3 +47,21 @@ export declare const searchPlaylists: (query: string, options?: Omit<publicApiSe
  * @param nb    max items per type (default 5)
  */
 export declare const suggest: (query: string, nb?: number) => Promise<suggestResult>;
+/** Per-type total hit counts + Deezer's own relevance ordering, from a `searchMusic` result. */
+export interface SearchFacets {
+    track: number;
+    album: number;
+    artist: number;
+    playlist: number;
+    radio: number;
+    show: number;
+    user: number;
+    /** the type order Deezer considers most relevant for this query, e.g. `['TOP_RESULT','ARTIST','TRACK',…]` */
+    order: string[];
+}
+/**
+ * Pull the facet counts out of a `searchMusic` (`deezer.pageSearch`) result —
+ * `pageSearch` already returns `TRACK.total`, `ALBUM.total`, … and an `ORDER`;
+ * this just surfaces them in one flat object for "N tracks · M albums · …" UIs.
+ */
+export declare const searchFacets: (result: searchType) => SearchFacets;

package/dist/api/search.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.suggest = exports.searchPlaylists = exports.searchArtists = exports.searchAlbums = exports.searchTracks = exports.searchPublicApi = exports.buildAdvancedQuery = void 0;
+exports.searchFacets = 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.
@@ -108,3 +108,22 @@ const suggest = (query, nb = 5) => (0, request_1.requestLight)({
     TYPES: { ALBUM: true, ARTIST: true, TRACK: true, PLAYLIST: true, RADIO: true, SHOW: true },
 }, 'deezer.suggest');
 exports.suggest = suggest;
+/**
+ * Pull the facet counts out of a `searchMusic` (`deezer.pageSearch`) result —
+ * `pageSearch` already returns `TRACK.total`, `ALBUM.total`, … and an `ORDER`;
+ * this just surfaces them in one flat object for "N tracks · M albums · …" UIs.
+ */
+const searchFacets = (result) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+    return ({
+        track: (_b = (_a = result.TRACK) === null || _a === void 0 ? void 0 : _a.total) !== null && _b !== void 0 ? _b : 0,
+        album: (_d = (_c = result.ALBUM) === null || _c === void 0 ? void 0 : _c.total) !== null && _d !== void 0 ? _d : 0,
+        artist: (_f = (_e = result.ARTIST) === null || _e === void 0 ? void 0 : _e.total) !== null && _f !== void 0 ? _f : 0,
+        playlist: (_h = (_g = result.PLAYLIST) === null || _g === void 0 ? void 0 : _g.total) !== null && _h !== void 0 ? _h : 0,
+        radio: (_k = (_j = result.RADIO) === null || _j === void 0 ? void 0 : _j.total) !== null && _k !== void 0 ? _k : 0,
+        show: (_m = (_l = result.SHOW) === null || _l === void 0 ? void 0 : _l.total) !== null && _m !== void 0 ? _m : 0,
+        user: (_p = (_o = result.USER) === null || _o === void 0 ? void 0 : _o.total) !== null && _p !== void 0 ? _p : 0,
+        order: (_q = result.ORDER) !== null && _q !== void 0 ? _q : [],
+    });
+};
+exports.searchFacets = searchFacets;

package/dist/enrich/client.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Small polite JSON client for the third-party enrichment services (MusicBrainz,
+ * Cover Art Archive). Each service gets its own instance so it can enforce its
+ * own minimum request interval and identify itself with a `User-Agent`.
+ *
+ * - serialises requests and spaces them by `minIntervalMs` (MusicBrainz asks for
+ *   ≤ 1 req/s per IP)
+ * - retries `503` (their "server busy") and `429` with exponential backoff
+ * - returns `null` on `404` rather than throwing (no data for that id)
+ */
+export declare class PoliteJsonClient {
+    userAgent: string;
+    minIntervalMs: number;
+    private queue;
+    private lastAt;
+    constructor(opts: {
+        userAgent: string;
+        minIntervalMs?: number;
+    });
+    /** GET `url` as JSON. Resolves `null` on 404. */
+    get<T>(url: string, { retries }?: {
+        retries?: number;
+    }): Promise<T | null>;
+    private fetch;
+}

package/dist/enrich/client.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoliteJsonClient = void 0;
+const delay_1 = __importDefault(require("delay"));
+const http_1 = require("../lib/http");
+/**
+ * Small polite JSON client for the third-party enrichment services (MusicBrainz,
+ * Cover Art Archive). Each service gets its own instance so it can enforce its
+ * own minimum request interval and identify itself with a `User-Agent`.
+ *
+ * - serialises requests and spaces them by `minIntervalMs` (MusicBrainz asks for
+ *   ≤ 1 req/s per IP)
+ * - retries `503` (their "server busy") and `429` with exponential backoff
+ * - returns `null` on `404` rather than throwing (no data for that id)
+ */
+class PoliteJsonClient {
+    constructor(opts) {
+        var _a;
+        this.queue = Promise.resolve();
+        this.lastAt = 0;
+        this.userAgent = opts.userAgent;
+        this.minIntervalMs = (_a = opts.minIntervalMs) !== null && _a !== void 0 ? _a : 1100;
+    }
+    /** GET `url` as JSON. Resolves `null` on 404. */
+    get(url, { retries = 3 } = {}) {
+        const run = this.queue.then(() => this.fetch(url, retries));
+        // keep the chain alive even if this call rejects
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    async fetch(url, retries) {
+        const wait = this.minIntervalMs - (Date.now() - this.lastAt);
+        if (wait > 0)
+            await (0, delay_1.default)(wait);
+        for (let attempt = 0;; attempt++) {
+            try {
+                const data = await (0, http_1.getJson)(url, { headers: { 'User-Agent': this.userAgent, Accept: 'application/json' } });
+                this.lastAt = Date.now();
+                return data;
+            }
+            catch (err) {
+                this.lastAt = Date.now();
+                const status = err instanceof http_1.HttpStatusError ? err.statusCode : 0;
+                if (status === 404) {
+                    return null;
+                }
+                if ((status === 503 || status === 429 || status >= 500) && attempt < retries) {
+                    await (0, delay_1.default)(Math.min(1000 * 2 ** attempt, 8000) + Math.random() * 400);
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+}
+exports.PoliteJsonClient = PoliteJsonClient;

package/dist/enrich/coverart.d.ts

@@ -0,0 +1,31 @@
+export interface CoverArtImage {
+    id: string;
+    front: boolean;
+    back: boolean;
+    approved: boolean;
+    /** full-resolution image URL (redirects to archive.org) */
+    image: string;
+    /** `{small, large, '250', '500', '1200'}` — not every size is present */
+    thumbnails: Record<string, string>;
+    types: string[];
+}
+export interface CoverArt {
+    images: CoverArtImage[];
+    /** the MusicBrainz release the art belongs to */
+    release?: string;
+}
+/**
+ * Cover Art Archive images for a MusicBrainz release-group (default) or release.
+ * `null` when there's no art — very common, so always handle it. Feed the MBID
+ * from `lookupRecordingByISRC(...).releases[i].releaseGroupMbid`.
+ */
+export declare const getCoverArt: (mbid: string, entity?: 'release' | 'release-group') => Promise<CoverArt | null>;
+/**
+ * The single best front-cover URL — the approved front image, preferring a
+ * thumbnail at least `minSize` px wide, else the full-resolution original.
+ * Deezer caps its own art at 1800 px, so this is how you go bigger.
+ */
+export declare const getBestCoverArtUrl: (mbid: string, { entity, minSize }?: {
+    entity?: "release-group" | "release" | undefined;
+    minSize?: number | undefined;
+}) => Promise<string | null>;

package/dist/enrich/coverart.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBestCoverArtUrl = exports.getCoverArt = void 0;
+const client_1 = require("./client");
+const client = new client_1.PoliteJsonClient({
+    userAgent: 'gerdur-core (+https://github.com/soulwax/gerdur-core)',
+    minIntervalMs: 200,
+});
+const BASE = 'https://coverartarchive.org';
+/**
+ * Cover Art Archive images for a MusicBrainz release-group (default) or release.
+ * `null` when there's no art — very common, so always handle it. Feed the MBID
+ * from `lookupRecordingByISRC(...).releases[i].releaseGroupMbid`.
+ */
+const getCoverArt = async (mbid, entity = 'release-group') => {
+    const data = await client.get(`${BASE}/${entity}/${encodeURIComponent(mbid)}`);
+    if (!(data === null || data === void 0 ? void 0 : data.images)) {
+        return null;
+    }
+    return {
+        release: data.release,
+        images: data.images.map((i) => {
+            var _a, _b;
+            return ({
+                id: String(i.id),
+                front: Boolean(i.front),
+                back: Boolean(i.back),
+                approved: Boolean(i.approved),
+                image: i.image,
+                thumbnails: (_a = i.thumbnails) !== null && _a !== void 0 ? _a : {},
+                types: (_b = i.types) !== null && _b !== void 0 ? _b : [],
+            });
+        }),
+    };
+};
+exports.getCoverArt = getCoverArt;
+/**
+ * The single best front-cover URL — the approved front image, preferring a
+ * thumbnail at least `minSize` px wide, else the full-resolution original.
+ * Deezer caps its own art at 1800 px, so this is how you go bigger.
+ */
+const getBestCoverArtUrl = async (mbid, { entity = 'release-group', minSize = 1200 } = {}) => {
+    var _a, _b;
+    const art = await (0, exports.getCoverArt)(mbid, entity);
+    if (!art) {
+        return null;
+    }
+    const front = (_b = (_a = art.images.find((i) => i.front && i.approved)) !== null && _a !== void 0 ? _a : art.images.find((i) => i.front)) !== null && _b !== void 0 ? _b : art.images[0];
+    if (!front) {
+        return null;
+    }
+    const sized = Object.entries(front.thumbnails)
+        .map(([k, url]) => [Number(k), url])
+        .filter(([n]) => Number.isFinite(n) && n >= minSize)
+        .sort((a, b) => a[0] - b[0])[0];
+    return sized ? sized[1] : front.image;
+};
+exports.getBestCoverArtUrl = getBestCoverArtUrl;

package/dist/enrich/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Optional, pluggable **enrichment** against third-party open databases —
+ * strictly read-only, off by default, never wired into `addTrackTags`. Use it to
+ * fill gaps Deezer leaves: canonical release/label data (MusicBrainz, by ISRC)
+ * and higher-resolution cover art (Cover Art Archive).
+ *
+ * Both services are rate-limited and want a descriptive `User-Agent` —
+ * `configureMusicBrainz({userAgent})` before first use.
+ */
+export { PoliteJsonClient } from './client';
+export { configureMusicBrainz, lookupRecordingByISRC, getMusicBrainzRecording, getMusicBrainzRelease, } from './musicbrainz';
+export type { MBRecording, MBRelease, MBArtistCredit } from './musicbrainz';
+export { getCoverArt, getBestCoverArtUrl } from './coverart';
+export type { CoverArt, CoverArtImage } from './coverart';

package/dist/enrich/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBestCoverArtUrl = exports.getCoverArt = exports.getMusicBrainzRelease = exports.getMusicBrainzRecording = exports.lookupRecordingByISRC = exports.configureMusicBrainz = exports.PoliteJsonClient = void 0;
+/**
+ * Optional, pluggable **enrichment** against third-party open databases —
+ * strictly read-only, off by default, never wired into `addTrackTags`. Use it to
+ * fill gaps Deezer leaves: canonical release/label data (MusicBrainz, by ISRC)
+ * and higher-resolution cover art (Cover Art Archive).
+ *
+ * Both services are rate-limited and want a descriptive `User-Agent` —
+ * `configureMusicBrainz({userAgent})` before first use.
+ */
+var client_1 = require("./client");
+Object.defineProperty(exports, "PoliteJsonClient", { enumerable: true, get: function () { return client_1.PoliteJsonClient; } });
+var musicbrainz_1 = require("./musicbrainz");
+Object.defineProperty(exports, "configureMusicBrainz", { enumerable: true, get: function () { return musicbrainz_1.configureMusicBrainz; } });
+Object.defineProperty(exports, "lookupRecordingByISRC", { enumerable: true, get: function () { return musicbrainz_1.lookupRecordingByISRC; } });
+Object.defineProperty(exports, "getMusicBrainzRecording", { enumerable: true, get: function () { return musicbrainz_1.getMusicBrainzRecording; } });
+Object.defineProperty(exports, "getMusicBrainzRelease", { enumerable: true, get: function () { return musicbrainz_1.getMusicBrainzRelease; } });
+var coverart_1 = require("./coverart");
+Object.defineProperty(exports, "getCoverArt", { enumerable: true, get: function () { return coverart_1.getCoverArt; } });
+Object.defineProperty(exports, "getBestCoverArtUrl", { enumerable: true, get: function () { return coverart_1.getBestCoverArtUrl; } });

package/dist/enrich/musicbrainz.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Set the `User-Agent` (MusicBrainz requires a descriptive one that identifies
+ * your application and a contact URL/email) and the minimum request interval
+ * (they ask for ≤ 1 req/s per IP; default 1100 ms). Call once at startup.
+ */
+export declare const configureMusicBrainz: (opts: {
+    userAgent?: string;
+    minIntervalMs?: number;
+}) => void;
+export interface MBArtistCredit {
+    name: string;
+    mbid?: string;
+    /** text that joins this credit to the next, e.g. `' feat. '` */
+    joinPhrase?: string;
+}
+export interface MBRelease {
+    mbid: string;
+    title: string;
+    /** YYYY / YYYY-MM / YYYY-MM-DD */
+    date?: string;
+    /** ISO 3166 country code */
+    country?: string;
+    status?: string;
+    barcode?: string;
+    releaseGroupMbid?: string;
+    primaryType?: string;
+    /** first label + catalogue number, when a full release lookup was done */
+    label?: string;
+    catalogNumber?: string;
+}
+export interface MBRecording {
+    mbid: string;
+    title: string;
+    disambiguation?: string;
+    /** track length in milliseconds */
+    lengthMs?: number;
+    /** every ISRC MusicBrainz has for this recording */
+    isrcs: string[];
+    /** search relevance 0–100 */
+    score?: number;
+    artistCredit: MBArtistCredit[];
+    /** the artist credit rendered as one display string */
+    artist: string;
+    /** earliest release date across the releases MB returned */
+    firstReleaseDate?: string;
+    releases: MBRelease[];
+}
+/**
+ * The best-matching MusicBrainz recording for an ISRC — canonical title, artist
+ * credits, length, every known ISRC, and the releases it appears on. `null` when
+ * MusicBrainz has nothing for the code.
+ */
+export declare const lookupRecordingByISRC: (isrc: string) => Promise<MBRecording | null>;
+/**
+ * A full MusicBrainz release — with `inc` (default `labels`, `release-groups`)
+ * you get the label, catalogue number, barcode and release-group MBID (which
+ * feeds `getCoverArt`). `null` when the MBID is unknown.
+ */
+export declare const getMusicBrainzRelease: (releaseMbid: string, inc?: string[]) => Promise<MBRelease | null>;
+/** Look up a recording by its own MBID (rather than by ISRC). */
+export declare const getMusicBrainzRecording: (recordingMbid: string) => Promise<MBRecording | null>;

package/dist/enrich/musicbrainz.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMusicBrainzRecording = exports.getMusicBrainzRelease = exports.lookupRecordingByISRC = exports.configureMusicBrainz = void 0;
+const client_1 = require("./client");
+const DEFAULT_UA = 'gerdur-core (+https://github.com/soulwax/gerdur-core)';
+let client = new client_1.PoliteJsonClient({ userAgent: DEFAULT_UA, minIntervalMs: 1100 });
+/**
+ * Set the `User-Agent` (MusicBrainz requires a descriptive one that identifies
+ * your application and a contact URL/email) and the minimum request interval
+ * (they ask for ≤ 1 req/s per IP; default 1100 ms). Call once at startup.
+ */
+const configureMusicBrainz = (opts) => {
+    var _a, _b;
+    client = new client_1.PoliteJsonClient({
+        userAgent: (_a = opts.userAgent) !== null && _a !== void 0 ? _a : client.userAgent,
+        minIntervalMs: (_b = opts.minIntervalMs) !== null && _b !== void 0 ? _b : client.minIntervalMs,
+    });
+};
+exports.configureMusicBrainz = configureMusicBrainz;
+const BASE = 'https://musicbrainz.org/ws/2';
+const renderCredit = (credits) => credits.map((c, i) => { var _a; return c.name + (i < credits.length - 1 ? (_a = c.joinPhrase) !== null && _a !== void 0 ? _a : ', ' : ''); }).join('');
+const mapCredit = (raw) => (raw !== null && raw !== void 0 ? raw : []).map((c) => {
+    var _a, _b, _c;
+    return ({
+        name: (_a = c.name) !== null && _a !== void 0 ? _a : (_b = c.artist) === null || _b === void 0 ? void 0 : _b.name,
+        mbid: (_c = c.artist) === null || _c === void 0 ? void 0 : _c.id,
+        joinPhrase: c.joinphrase || undefined,
+    });
+});
+const mapRelease = (r) => {
+    var _a, _b, _c, _d, _e, _f, _g;
+    return ({
+        mbid: r.id,
+        title: r.title,
+        date: r.date || undefined,
+        country: r.country || undefined,
+        status: r.status || undefined,
+        barcode: r.barcode || undefined,
+        releaseGroupMbid: (_a = r['release-group']) === null || _a === void 0 ? void 0 : _a.id,
+        primaryType: ((_b = r['release-group']) === null || _b === void 0 ? void 0 : _b['primary-type']) || undefined,
+        label: (_e = (_d = (_c = r['label-info']) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.label) === null || _e === void 0 ? void 0 : _e.name,
+        catalogNumber: ((_g = (_f = r['label-info']) === null || _f === void 0 ? void 0 : _f[0]) === null || _g === void 0 ? void 0 : _g['catalog-number']) || undefined,
+    });
+};
+/**
+ * The best-matching MusicBrainz recording for an ISRC — canonical title, artist
+ * credits, length, every known ISRC, and the releases it appears on. `null` when
+ * MusicBrainz has nothing for the code.
+ */
+const lookupRecordingByISRC = async (isrc) => {
+    var _a, _b, _c;
+    const data = await client.get(`${BASE}/recording?query=isrc:${encodeURIComponent(isrc)}&fmt=json&limit=5&inc=releases`);
+    const raw = (_a = data === null || data === void 0 ? void 0 : data.recordings) === null || _a === void 0 ? void 0 : _a[0];
+    if (!raw) {
+        return null;
+    }
+    const releases = ((_b = raw.releases) !== null && _b !== void 0 ? _b : []).map(mapRelease);
+    const firstReleaseDate = releases
+        .map((r) => r.date)
+        .filter(Boolean)
+        .sort()[0];
+    return {
+        mbid: raw.id,
+        title: raw.title,
+        disambiguation: raw.disambiguation || undefined,
+        lengthMs: typeof raw.length === 'number' ? raw.length : undefined,
+        isrcs: (_c = raw.isrcs) !== null && _c !== void 0 ? _c : [isrc],
+        score: typeof raw.score === 'number' ? raw.score : undefined,
+        artistCredit: mapCredit(raw['artist-credit']),
+        artist: renderCredit(mapCredit(raw['artist-credit'])),
+        firstReleaseDate,
+        releases,
+    };
+};
+exports.lookupRecordingByISRC = lookupRecordingByISRC;
+/**
+ * A full MusicBrainz release — with `inc` (default `labels`, `release-groups`)
+ * you get the label, catalogue number, barcode and release-group MBID (which
+ * feeds `getCoverArt`). `null` when the MBID is unknown.
+ */
+const getMusicBrainzRelease = async (releaseMbid, inc = ['labels', 'release-groups']) => {
+    const data = await client.get(`${BASE}/release/${encodeURIComponent(releaseMbid)}?fmt=json&inc=${inc.join('+')}`);
+    return data ? mapRelease(data) : null;
+};
+exports.getMusicBrainzRelease = getMusicBrainzRelease;
+/** Look up a recording by its own MBID (rather than by ISRC). */
+const getMusicBrainzRecording = async (recordingMbid) => {
+    var _a, _b;
+    const raw = await client.get(`${BASE}/recording/${encodeURIComponent(recordingMbid)}?fmt=json&inc=artist-credits+isrcs+releases`);
+    if (!raw) {
+        return null;
+    }
+    const releases = ((_a = raw.releases) !== null && _a !== void 0 ? _a : []).map(mapRelease);
+    return {
+        mbid: raw.id,
+        title: raw.title,
+        disambiguation: raw.disambiguation || undefined,
+        lengthMs: typeof raw.length === 'number' ? raw.length : undefined,
+        isrcs: (_b = raw.isrcs) !== null && _b !== void 0 ? _b : [],
+        artistCredit: mapCredit(raw['artist-credit']),
+        artist: renderCredit(mapCredit(raw['artist-credit'])),
+        firstReleaseDate: releases
+            .map((r) => r.date)
+            .filter(Boolean)
+            .sort()[0],
+        releases,
+    };
+};
+exports.getMusicBrainzRecording = getMusicBrainzRecording;

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './converter';
 export * from './lib/decrypt';
 export * from './lib/get-url';
 export * from './lib/stream-download';
+export * from './enrich';
 export { httpAgent, httpsAgent, getBuffer, getJson, getText, getStream } from './lib/http';
 export type { StreamResponse } from './lib/http';
 export * from './metadata-writer';

package/dist/index.js

@@ -30,6 +30,7 @@ __exportStar(require("./converter"), exports);
 __exportStar(require("./lib/decrypt"), exports);
 __exportStar(require("./lib/get-url"), exports);
 __exportStar(require("./lib/stream-download"), exports);
+__exportStar(require("./enrich"), exports);
 var http_1 = require("./lib/http");
 Object.defineProperty(exports, "httpAgent", { enumerable: true, get: function () { return http_1.httpAgent; } });
 Object.defineProperty(exports, "httpsAgent", { enumerable: true, get: function () { return http_1.httpsAgent; } });

package/package.json

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