gerdur-core 2.11.0 → 2.13.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 2.13.0 - 2026-08-31
+
+### Added
+
+- **`getCoverArtByISRC(isrc, {minSize?, maxTries?})`** and
+  **`getRecordingCoverArt(recording, …)`** — the full ISRC → cover chain with a
+  proper release ranking: `getBestCoverArtUrl` on the *first* release a recording
+  lists often hits a promo comp / bootleg with no art. These walk the
+  release-groups **canonical-first** (Official > Album > earliest date) and
+  return the first real front cover, bounded to `maxTries` (default 4) lookups.
+
+## 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

package/README.md

@@ -437,6 +437,33 @@ 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. |
+| `getCoverArtByISRC(isrc, {minSize?, maxTries?})` | the whole chain — ISRC → recording → **canonical-first** release walk → first real front cover. Use this, not `getBestCoverArtUrl` on `releases[0]` (often a promo comp with no art). |
+| `getRecordingCoverArt(recording, …)` | same, from an already-fetched `MBRecording`. |
+
+```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/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,50 @@
+import type { MBRecording } from './musicbrainz';
+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>;
+/**
+ * The best cover for a MusicBrainz recording — walks its release-groups
+ * canonical-first (Official Album, earliest) and returns the first Cover Art
+ * Archive front cover it finds. `null` when none of the top few have art.
+ * Bounded to `maxTries` release-groups (default 4) to keep the request count low.
+ */
+export declare const getRecordingCoverArt: (rec: MBRecording, { minSize, maxTries }?: {
+    minSize?: number | undefined;
+    maxTries?: number | undefined;
+}) => Promise<string | null>;
+/**
+ * One call: ISRC → MusicBrainz recording → best Cover Art Archive front cover
+ * (larger than Deezer's 1800 px cap). `null` when there's no match or no art.
+ */
+export declare const getCoverArtByISRC: (isrc: string, options?: {
+    minSize?: number;
+    maxTries?: number;
+}) => Promise<string | null>;

package/dist/enrich/coverart.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCoverArtByISRC = exports.getRecordingCoverArt = exports.getBestCoverArtUrl = exports.getCoverArt = void 0;
+const client_1 = require("./client");
+const musicbrainz_1 = require("./musicbrainz");
+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;
+/** Rank a recording's releases so the canonical original album comes first. */
+const rankReleases = (rec) => {
+    const seen = new Set();
+    return rec.releases
+        .filter((r) => r.releaseGroupMbid)
+        .map((r) => {
+        var _a;
+        return ({
+            rgid: r.releaseGroupMbid,
+            // Official beats Promotion/Bootleg/Pseudo-Release; Album beats Single/EP/Compilation;
+            // then earliest date wins.
+            score: (r.status === 'Official' ? 0 : r.status ? 10 : 5) + (r.primaryType === 'Album' ? 0 : r.primaryType ? 2 : 1),
+            date: (_a = r.date) !== null && _a !== void 0 ? _a : '9999',
+        });
+    })
+        .sort((a, b) => a.score - b.score || a.date.localeCompare(b.date))
+        .map((r) => r.rgid)
+        .filter((rgid) => (seen.has(rgid) ? false : seen.add(rgid)));
+};
+/**
+ * The best cover for a MusicBrainz recording — walks its release-groups
+ * canonical-first (Official Album, earliest) and returns the first Cover Art
+ * Archive front cover it finds. `null` when none of the top few have art.
+ * Bounded to `maxTries` release-groups (default 4) to keep the request count low.
+ */
+const getRecordingCoverArt = async (rec, { minSize = 1200, maxTries = 4 } = {}) => {
+    for (const rgid of rankReleases(rec).slice(0, maxTries)) {
+        const url = await (0, exports.getBestCoverArtUrl)(rgid, { entity: 'release-group', minSize });
+        if (url)
+            return url;
+    }
+    return null;
+};
+exports.getRecordingCoverArt = getRecordingCoverArt;
+/**
+ * One call: ISRC → MusicBrainz recording → best Cover Art Archive front cover
+ * (larger than Deezer's 1800 px cap). `null` when there's no match or no art.
+ */
+const getCoverArtByISRC = async (isrc, options = {}) => {
+    const rec = await (0, musicbrainz_1.lookupRecordingByISRC)(isrc);
+    return rec ? (0, exports.getRecordingCoverArt)(rec, options) : null;
+};
+exports.getCoverArtByISRC = getCoverArtByISRC;

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, getRecordingCoverArt, getCoverArtByISRC } from './coverart';
+export type { CoverArt, CoverArtImage } from './coverart';

package/dist/enrich/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCoverArtByISRC = exports.getRecordingCoverArt = 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; } });
+Object.defineProperty(exports, "getRecordingCoverArt", { enumerable: true, get: function () { return coverart_1.getRecordingCoverArt; } });
+Object.defineProperty(exports, "getCoverArtByISRC", { enumerable: true, get: function () { return coverart_1.getCoverArtByISRC; } });

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