gerdur-core 2.12.0 → 2.13.1

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,7 +1,24 @@
 {
   "name": "gerdur-core",
-  "version": "2.12.0",
-  "description": "Core module for gerdur.",
+  "version": "2.13.1",
+  "description": "Deezer API client, cross-service URL resolution, Blowfish track decryption and MP3/FLAC metadata tagging — the engine behind the gerdur CLI.",
+  "keywords": [
+    "deezer",
+    "deezer-api",
+    "spotify",
+    "tidal",
+    "isrc",
+    "music",
+    "metadata",
+    "id3",
+    "flac",
+    "lyrics",
+    "lrc",
+    "musicbrainz",
+    "cover-art",
+    "decrypt",
+    "blowfish"
+  ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {