gerdur-core 2.12.0 → 2.13.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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.

package/README.md

@@ -449,6 +449,8 @@ call `configureMusicBrainz({userAgent})` once at startup.
 | `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 )'});

package/dist/enrich/coverart.d.ts

@@ -1,3 +1,4 @@
+import type { MBRecording } from './musicbrainz';
 export interface CoverArtImage {
     id: string;
     front: boolean;
@@ -29,3 +30,21 @@ 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

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBestCoverArtUrl = exports.getCoverArt = void 0;
+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,
@@ -56,3 +57,46 @@ const getBestCoverArtUrl = async (mbid, { entity = 'release-group', minSize = 12
     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

@@ -10,5 +10,5 @@
 export { PoliteJsonClient } from './client';
 export { configureMusicBrainz, lookupRecordingByISRC, getMusicBrainzRecording, getMusicBrainzRelease, } from './musicbrainz';
 export type { MBRecording, MBRelease, MBArtistCredit } from './musicbrainz';
-export { getCoverArt, getBestCoverArtUrl } from './coverart';
+export { getCoverArt, getBestCoverArtUrl, getRecordingCoverArt, getCoverArtByISRC } from './coverart';
 export type { CoverArt, CoverArtImage } from './coverart';

package/dist/enrich/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBestCoverArtUrl = exports.getCoverArt = exports.getMusicBrainzRelease = exports.getMusicBrainzRecording = exports.lookupRecordingByISRC = exports.configureMusicBrainz = exports.PoliteJsonClient = void 0;
+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
@@ -20,3 +20,5 @@ Object.defineProperty(exports, "getMusicBrainzRelease", { enumerable: true, get:
 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/package.json

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