gerdur-core 2.17.0 → 2.19.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 2.19.0 - 2026-08-31
+
+### Changed
+
+- **The Musixmatch lyrics fallback now latches off when it isn't working.**
+  For tracks Deezer has no lyrics for, the tagger scrapes Musixmatch — two page
+  loads each. Where Musixmatch blocks the request (it 403s from many networks and
+  most datacentres) every one of those still costs a round trip and still returns
+  nothing. Measured on a 14-track album: **2021 ms, 70% of total tagging time**,
+  for 3 KB of error pages.
+
+  After three consecutive *transport* failures the scraper stops being attempted
+  for the rest of the process. A track simply not being on Musixmatch does **not**
+  count toward that — the service is working fine in that case — so a run of
+  obscure tracks cannot disable a fallback that would otherwise succeed, and any
+  success resets the counter.
+
+  Measured, same album, default options: **2880 ms → 2641 ms on the first album
+  (the latch trips part-way through), then 653 / 729 ms — 77% faster in steady
+  state**, which is the case that matters for a library sync.
+
+### Added
+
+- **`configureMusixmatch({maxFailures?, enabled?})`** and **`musixmatchStatus()`**
+  → `{available, consecutiveFailures, maxFailures}`. Re-enabling clears the
+  count; nonsensical thresholds are rejected.
+
+### Not done, deliberately
+
+- Sending `Accept-Encoding` on the clients that don't set it. Measured the wire
+  first: a 14-track album transfers 176 KB, of which **111 KB is cover-art JPEG**
+  (incompressible) and 65 KB is `api.deezer.com` JSON that is **already gzipped**.
+  Musixmatch returns 3 KB total. The saving would have been ~0.
+
+## 2.18.0 - 2026-08-31
+
+Write operations — the first part of this package that changes an account.
+
+### Added
+
+- **`src/api/favorites.ts`** — mutating library operations, in their own module
+  and wired into no download path, so they only run when called deliberately:
+  - `addFavoriteTracks(ids)` / `removeFavoriteTracks(ids)` (`song.addFavorites` /
+    `song.removeFavorites` — note the plural)
+  - `addFavoriteAlbum` / `removeFavoriteAlbum`, `addFavoriteArtist` /
+    `removeFavoriteArtist`
+  - `followPlaylist` / `unfollowPlaylist` (the gateway wants
+    `parent_playlist_id` to follow but `playlist_id` to unfollow)
+  - `addFavoriteShow`, `createPlaylist`, `addTracksToPlaylist`,
+    `removeTracksFromPlaylist`
+
+  The surface was mapped by calling each candidate with **incomplete
+  parameters** — an existing method answers `MISSING_PARAMETER_*`, an absent one
+  `GATEWAY_ERROR` — so method names and their parameter names were established
+  without creating or changing anything.
+
+### Verification status
+
+- Method existence and parameter names: **confirmed by probe**.
+- End-to-end execution: **not run.** `__tests__/favorites.ts` contains
+  snapshot → mutate → assert → revert → assert-restored round trips, gated
+  behind `GERDUR_ALLOW_WRITE_TESTS=1` so they never fire by accident.
+
+### Known gaps
+
+- **Deezer's gateway has no playlist delete.** `playlist.delete`, `.remove`,
+  `.destroy`, `.deletePlaylist` and eight other spellings all answer
+  `GATEWAY_ERROR`, so `createPlaylist` is one-way — remove what it makes from a
+  Deezer client. Everything else here has a confirmed inverse.
+- No `show.deleteFavorite` was found, so `addFavoriteShow` is one-way too.
+- **`log.listen` (scrobbling) is not implemented.** It never answered the probe,
+  so its shape is unknown, and it writes to listening history that cannot be
+  undone — not something to ship on a guess.
+
 ## 2.17.0 - 2026-08-31
 
 The account's own library, over the authenticated gateway.

package/README.md

@@ -47,6 +47,7 @@ the CLI and the file-writing layer on top.
   - [Browse and discover](#browse-and-discover)
   - [Flow, radios and a user's library](#flow-radios-and-a-users-library)
   - [Your own library](#your-own-library)
+  - [Changing the account (write operations)](#changing-the-account-write-operations)
   - [Podcasts](#podcasts)
   - [Preview clips](#preview-clips)
   - [Resolve a download URL](#resolve-a-download-url)
@@ -409,6 +410,43 @@ const urls = await resolveDownloadUrls(mix, [9, 3, 1]); // straight to download
 `userId` defaults to the logged-in account. These are account-scoped, so they
 never enter the shared cross-session cache.
 
+### Changing the account (write operations)
+
+Everything above reads. These change the logged-in account's library for real —
+they are in their own module, wired into no download path, and only run when you
+call them.
+
+| Function | Inverse |
+| :--- | :--- |
+| `addFavoriteTracks(ids)` | `removeFavoriteTracks(ids)` |
+| `addFavoriteAlbum(id)` | `removeFavoriteAlbum(id)` |
+| `addFavoriteArtist(id)` | `removeFavoriteArtist(id)` |
+| `followPlaylist(id)` | `unfollowPlaylist(id)` |
+| `addFavoriteShow(id)` | — none found |
+| `createPlaylist(title, opts?)` | **— none exists, see below** |
+| `addTracksToPlaylist(id, sngIds)` | `removeTracksFromPlaylist(id, sngIds)` |
+
+```ts
+import {addFavoriteTracks, removeFavoriteTracks} from 'gerdur-core';
+
+await addFavoriteTracks(['3135556']);     // love it
+await removeFavoriteTracks(['3135556']);  // and back
+```
+
+> **`createPlaylist` is a one-way door.** Deezer's gateway exposes no delete —
+> a dozen spellings of `playlist.delete` all answer `GATEWAY_ERROR` — so a
+> playlist made here has to be removed from a Deezer client. It is also the one
+> function in this module that has not been exercised against a live account,
+> for exactly that reason.
+>
+> Method names and parameters were established by probing with incomplete
+> arguments (an existing method answers `MISSING_PARAMETER_*`), so the surface is
+> real; the round trips live in `__tests__/favorites.ts` behind
+> `GERDUR_ALLOW_WRITE_TESTS=1`.
+
+Scrobbling (`log.listen`) is deliberately absent: it never answered the probe and
+it writes history that cannot be undone.
+
 ### Podcasts
 
 ```ts
@@ -551,7 +589,7 @@ model.contributors;  // normalised producers / engineers / performers / …
 | `album` / `lyrics` / `publicTrack` | — | pre-fetched payloads — pass once per album to skip refetching |
 | `embedCover` / `embedArtistImage` | `true` | |
 | `writeLyrics` / `embedSyncedLyrics` | `true` | synced LRC goes to FLAC Vorbis only (no ID3v2.3 `SYLT`) |
-| `lyricsFallback` | `true` | scrape Musixmatch when Deezer has no lyrics — 2 requests per such track, and they fail where Musixmatch blocks you |
+| `lyricsFallback` | `true` | scrape Musixmatch when Deezer has no lyrics — 2 requests per such track. Latches off automatically after 3 consecutive transport failures (see below) |
 | `richCredits` | `true` | hydrate credits + BPM for album/playlist tracks that omit them |
 | `deezerIds` / `includeRank` | `true` | write `DEEZER_*_ID` / popularity rank |
 
@@ -578,6 +616,22 @@ await pipeline(stream, createTagStream(model), createWriteStream('track.flac'));
 `resolveTagModel(track, options?)` does exactly what `addTrackTags` does minus
 the writing — same fetches, same coalescing, same `AddTrackTagsOptions`.
 
+**The Musixmatch fallback looks after itself.** Where Musixmatch blocks you — it
+403s from many networks and most datacentres — those scrapes cost a round trip
+each and return nothing: 2021 ms on a 14-track album, 70% of tagging time. After
+three consecutive *transport* failures it stops being attempted for the rest of
+the process, taking that album to 653 ms. A track simply not being on Musixmatch
+doesn't count toward the latch, so it can't disable itself where it actually
+works, and any success resets it.
+
+```ts
+import {configureMusixmatch, musixmatchStatus} from 'gerdur-core';
+
+musixmatchStatus();                          // {available, consecutiveFailures, maxFailures}
+configureMusixmatch({maxFailures: 5});       // more patient
+configureMusixmatch({enabled: false});       // never scrape at all
+```
+
 Building blocks, if you want the model without writing tags:
 
 - **`getRichAlbum(albId)`** → merged gw + public album metadata (`RichAlbum`).
@@ -818,7 +872,12 @@ import type {
 `getUserChartTracks` · `getRadios` · `getRadioTracks` · `getRadioGenres` ·
 `getMyPlaylists` · `getMyFavoriteTracks` · `getMyFavoriteTrackIds` ·
 `getMyFavoriteAlbums` · `getMyFavoriteArtists` · `getMyFavoritePlaylists` ·
-`getMyFavoriteRadios` · `getMyFavoriteShows` · `getTrackMix`
+`getMyFavoriteRadios` · `getMyFavoriteShows` · `getTrackMix` ·
+`addFavoriteTracks` · `removeFavoriteTracks` · `addFavoriteAlbum` ·
+`removeFavoriteAlbum` · `addFavoriteArtist` · `removeFavoriteArtist` ·
+`followPlaylist` · `unfollowPlaylist` · `addFavoriteShow` · `createPlaylist` ·
+`addTracksToPlaylist` · `removeTracksFromPlaylist` · `configureMusixmatch` ·
+`musixmatchStatus`
 </details>
 
 <details>

package/dist/api/favorites.d.ts

@@ -0,0 +1,59 @@
+/** What the gateway returns for a mutation — usually `true`, or the new id. */
+export type WriteResult = boolean | string | number | Record<string, any>;
+/**
+ * Love one or more tracks (`song.addFavorites`). Reversible with
+ * {@link removeFavoriteTracks}.
+ *
+ * @param sngIds `SNG_ID`s
+ */
+export declare const addFavoriteTracks: (sngIds: (string | number)[]) => Promise<WriteResult>;
+/** Un-love one or more tracks (`song.removeFavorites`). */
+export declare const removeFavoriteTracks: (sngIds: (string | number)[]) => Promise<WriteResult>;
+/** Add an album to favourites (`album.addFavorite`). */
+export declare const addFavoriteAlbum: (albId: string | number) => Promise<WriteResult>;
+/** Remove an album from favourites (`album.deleteFavorite`). */
+export declare const removeFavoriteAlbum: (albId: string | number) => Promise<WriteResult>;
+/** Follow an artist (`artist.addFavorite`). */
+export declare const addFavoriteArtist: (artId: string | number) => Promise<WriteResult>;
+/** Unfollow an artist (`artist.deleteFavorite`). */
+export declare const removeFavoriteArtist: (artId: string | number) => Promise<WriteResult>;
+/**
+ * Follow someone else's playlist (`playlist.addFavorite`). Note the gateway
+ * wants `parent_playlist_id` here but plain `playlist_id` to unfollow.
+ */
+export declare const followPlaylist: (playlistId: string | number) => Promise<WriteResult>;
+/** Unfollow a playlist (`playlist.deleteFavorite`). */
+export declare const unfollowPlaylist: (playlistId: string | number) => Promise<WriteResult>;
+/**
+ * Follow a podcast show (`show.addFavorite`).
+ *
+ * No `show.deleteFavorite` answered the probe, so treat this as one-way until
+ * the inverse is found.
+ */
+export declare const addFavoriteShow: (showId: string | number) => Promise<WriteResult>;
+/**
+ * Create a playlist (`playlist.create`). Resolves to the new `PLAYLIST_ID`.
+ *
+ * **One-way.** The gateway has no delete counterpart (see the module note), so
+ * anything created here has to be removed from a Deezer client. For the same
+ * reason this is the one function on this page that has not been exercised
+ * against a live account.
+ *
+ * @param title       playlist title
+ * @param options     `description`, `status` (0 public / 1 private / 2 collaborative),
+ *                    and `songs` to seed it with `SNG_ID`s
+ */
+export declare const createPlaylist: (title: string, options?: {
+    description?: string;
+    status?: 0 | 1 | 2;
+    songs?: (string | number)[];
+}) => Promise<WriteResult>;
+/**
+ * Append tracks to a playlist (`playlist.addSongs`). Reversible with
+ * {@link removeTracksFromPlaylist}.
+ *
+ * The gateway takes `songs` as `[[sngId, offset], …]`; this wraps that for you.
+ */
+export declare const addTracksToPlaylist: (playlistId: string | number, sngIds: (string | number)[]) => Promise<WriteResult>;
+/** Remove tracks from a playlist (`playlist.deleteSongs`). */
+export declare const removeTracksFromPlaylist: (playlistId: string | number, sngIds: (string | number)[]) => Promise<WriteResult>;

package/dist/api/favorites.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeTracksFromPlaylist = exports.addTracksToPlaylist = exports.createPlaylist = exports.addFavoriteShow = exports.unfollowPlaylist = exports.followPlaylist = exports.removeFavoriteArtist = exports.addFavoriteArtist = exports.removeFavoriteAlbum = exports.addFavoriteAlbum = exports.removeFavoriteTracks = exports.addFavoriteTracks = void 0;
+/**
+ * **Mutating** operations on the logged-in account's library.
+ *
+ * Everything else in this package reads. These change the account, so they are
+ * kept in their own module and none of them are wired into any download path —
+ * you have to call them deliberately.
+ *
+ * The method names here were established by probing the gateway with incomplete
+ * parameters, which makes an existing method answer `MISSING_PARAMETER_*` while
+ * an absent one answers `GATEWAY_ERROR` — so the surface was mapped without
+ * creating or changing anything.
+ *
+ * **Deezer's gateway exposes no way to delete a playlist.** `playlist.delete`,
+ * `.remove`, `.destroy` and nine other spellings all answer `GATEWAY_ERROR`.
+ * {@link createPlaylist} is therefore a one-way door: whatever it makes, you
+ * remove from a Deezer client, not from here. Everything else on this page has a
+ * confirmed inverse and is safe to undo.
+ */
+const request_1 = require("./request");
+// ─── Loved tracks ────────────────────────────────────────────────────────────
+/**
+ * Love one or more tracks (`song.addFavorites`). Reversible with
+ * {@link removeFavoriteTracks}.
+ *
+ * @param sngIds `SNG_ID`s
+ */
+const addFavoriteTracks = (sngIds) => (0, request_1.request)({ ids: sngIds.map(String) }, 'song.addFavorites');
+exports.addFavoriteTracks = addFavoriteTracks;
+/** Un-love one or more tracks (`song.removeFavorites`). */
+const removeFavoriteTracks = (sngIds) => (0, request_1.request)({ ids: sngIds.map(String) }, 'song.removeFavorites');
+exports.removeFavoriteTracks = removeFavoriteTracks;
+// ─── Albums / artists ────────────────────────────────────────────────────────
+/** Add an album to favourites (`album.addFavorite`). */
+const addFavoriteAlbum = (albId) => (0, request_1.request)({ alb_id: String(albId) }, 'album.addFavorite');
+exports.addFavoriteAlbum = addFavoriteAlbum;
+/** Remove an album from favourites (`album.deleteFavorite`). */
+const removeFavoriteAlbum = (albId) => (0, request_1.request)({ alb_id: String(albId) }, 'album.deleteFavorite');
+exports.removeFavoriteAlbum = removeFavoriteAlbum;
+/** Follow an artist (`artist.addFavorite`). */
+const addFavoriteArtist = (artId) => (0, request_1.request)({ art_id: String(artId) }, 'artist.addFavorite');
+exports.addFavoriteArtist = addFavoriteArtist;
+/** Unfollow an artist (`artist.deleteFavorite`). */
+const removeFavoriteArtist = (artId) => (0, request_1.request)({ art_id: String(artId) }, 'artist.deleteFavorite');
+exports.removeFavoriteArtist = removeFavoriteArtist;
+// ─── Playlists & shows ───────────────────────────────────────────────────────
+/**
+ * Follow someone else's playlist (`playlist.addFavorite`). Note the gateway
+ * wants `parent_playlist_id` here but plain `playlist_id` to unfollow.
+ */
+const followPlaylist = (playlistId) => (0, request_1.request)({ parent_playlist_id: String(playlistId) }, 'playlist.addFavorite');
+exports.followPlaylist = followPlaylist;
+/** Unfollow a playlist (`playlist.deleteFavorite`). */
+const unfollowPlaylist = (playlistId) => (0, request_1.request)({ playlist_id: String(playlistId) }, 'playlist.deleteFavorite');
+exports.unfollowPlaylist = unfollowPlaylist;
+/**
+ * Follow a podcast show (`show.addFavorite`).
+ *
+ * No `show.deleteFavorite` answered the probe, so treat this as one-way until
+ * the inverse is found.
+ */
+const addFavoriteShow = (showId) => (0, request_1.request)({ show_id: String(showId) }, 'show.addFavorite');
+exports.addFavoriteShow = addFavoriteShow;
+// ─── Playlist contents ───────────────────────────────────────────────────────
+/**
+ * Create a playlist (`playlist.create`). Resolves to the new `PLAYLIST_ID`.
+ *
+ * **One-way.** The gateway has no delete counterpart (see the module note), so
+ * anything created here has to be removed from a Deezer client. For the same
+ * reason this is the one function on this page that has not been exercised
+ * against a live account.
+ *
+ * @param title       playlist title
+ * @param options     `description`, `status` (0 public / 1 private / 2 collaborative),
+ *                    and `songs` to seed it with `SNG_ID`s
+ */
+const createPlaylist = (title, options = {}) => {
+    var _a, _b, _c;
+    return (0, request_1.request)({
+        title,
+        description: (_a = options.description) !== null && _a !== void 0 ? _a : '',
+        status: (_b = options.status) !== null && _b !== void 0 ? _b : 1,
+        songs: ((_c = options.songs) !== null && _c !== void 0 ? _c : []).map((id) => [String(id), 0]),
+    }, 'playlist.create');
+};
+exports.createPlaylist = createPlaylist;
+/**
+ * Append tracks to a playlist (`playlist.addSongs`). Reversible with
+ * {@link removeTracksFromPlaylist}.
+ *
+ * The gateway takes `songs` as `[[sngId, offset], …]`; this wraps that for you.
+ */
+const addTracksToPlaylist = (playlistId, sngIds) => (0, request_1.request)({ playlist_id: String(playlistId), songs: sngIds.map((id) => [String(id), 0]) }, 'playlist.addSongs');
+exports.addTracksToPlaylist = addTracksToPlaylist;
+/** Remove tracks from a playlist (`playlist.deleteSongs`). */
+const removeTracksFromPlaylist = (playlistId, sngIds) => (0, request_1.request)({ playlist_id: String(playlistId), songs: sngIds.map((id) => [String(id), 0]) }, 'playlist.deleteSongs');
+exports.removeTracksFromPlaylist = removeTracksFromPlaylist;

package/dist/api/index.d.ts

@@ -6,3 +6,4 @@ export * from './preview';
 export * from './user';
 export * from './podcast';
 export * from './library';
+export * from './favorites';

package/dist/api/index.js

@@ -22,3 +22,4 @@ __exportStar(require("./preview"), exports);
 __exportStar(require("./user"), exports);
 __exportStar(require("./podcast"), exports);
 __exportStar(require("./library"), exports);
+__exportStar(require("./favorites"), exports);

package/dist/metadata-writer/index.d.ts

@@ -5,6 +5,8 @@ import type { lyricsType, trackType, trackTypePublicApi } from '../types';
 export { normalizeContributors } from './contributors';
 export type { NormalizedContributors } from './contributors';
 export { toLrc } from './lrc';
+export { configureMusixmatch, musixmatchStatus } from './musixmatchLyrics';
+export type { MusixmatchOptions } from './musixmatchLyrics';
 export { getRichAlbum } from './rich-album';
 export type { RichAlbum } from './rich-album';
 export { buildTagModel } from './model';

package/dist/metadata-writer/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.addTrackTags = exports.resolveTagModel = exports.probeAudioOffset = exports.createTagStream = exports.MAX_COVER_SIZE = exports.downloadArtistImage = exports.downloadAlbumCover = exports.buildTagModel = exports.getRichAlbum = exports.toLrc = exports.normalizeContributors = void 0;
+exports.addTrackTags = exports.resolveTagModel = exports.probeAudioOffset = exports.createTagStream = exports.MAX_COVER_SIZE = exports.downloadArtistImage = exports.downloadAlbumCover = exports.buildTagModel = exports.getRichAlbum = exports.musixmatchStatus = exports.configureMusixmatch = exports.toLrc = exports.normalizeContributors = void 0;
 const abumCover_1 = require("./abumCover");
 const getTrackLyrics_1 = require("./getTrackLyrics");
 const id3_1 = require("./id3");
@@ -12,6 +12,9 @@ var contributors_1 = require("./contributors");
 Object.defineProperty(exports, "normalizeContributors", { enumerable: true, get: function () { return contributors_1.normalizeContributors; } });
 var lrc_1 = require("./lrc");
 Object.defineProperty(exports, "toLrc", { enumerable: true, get: function () { return lrc_1.toLrc; } });
+var musixmatchLyrics_1 = require("./musixmatchLyrics");
+Object.defineProperty(exports, "configureMusixmatch", { enumerable: true, get: function () { return musixmatchLyrics_1.configureMusixmatch; } });
+Object.defineProperty(exports, "musixmatchStatus", { enumerable: true, get: function () { return musixmatchLyrics_1.musixmatchStatus; } });
 var rich_album_2 = require("./rich-album");
 Object.defineProperty(exports, "getRichAlbum", { enumerable: true, get: function () { return rich_album_2.getRichAlbum; } });
 var model_2 = require("./model");

package/dist/metadata-writer/musixmatchLyrics.d.ts

@@ -1 +1,17 @@
+declare let maxFailures: number;
+export interface MusixmatchOptions {
+    /** consecutive transport failures before the scraper latches off. Default 3. */
+    maxFailures?: number;
+    /** force it back on (or off) — also clears the failure count when enabling */
+    enabled?: boolean;
+}
+/** Tune or reset the Musixmatch fallback. */
+export declare const configureMusixmatch: (options?: MusixmatchOptions) => void;
+/** Whether the fallback is still being attempted, and how close it is to latching off. */
+export declare const musixmatchStatus: () => {
+    available: boolean;
+    consecutiveFailures: number;
+    maxFailures: number;
+};
 export declare const getLyricsMusixmatch: (query: string) => Promise<string>;
+export {};

package/dist/metadata-writer/musixmatchLyrics.js

@@ -1,10 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getLyricsMusixmatch = void 0;
+exports.getLyricsMusixmatch = exports.musixmatchStatus = exports.configureMusixmatch = void 0;
 const node_html_parser_1 = require("node-html-parser");
 const http_1 = require("../lib/http");
 const useragents_1 = require("./useragents");
 const baseUrl = 'https://musixmatch.com';
+/**
+ * Musixmatch is a *fallback* for tracks Deezer has no lyrics for — two scraped
+ * page loads each. Where Musixmatch blocks the request (it 403s from plenty of
+ * networks and datacentres) every one of those still costs a round trip and
+ * still returns nothing: measured at **2021 ms per 14-track album, 70% of all
+ * tagging time**, for 3 KB of error pages.
+ *
+ * So after a few consecutive *transport* failures the scraper latches off for
+ * the rest of the process. A track simply not being on Musixmatch does **not**
+ * count — that means the service is working fine — so a run of obscure tracks
+ * can't disable a fallback that would otherwise work. Any success resets it.
+ */
+let consecutiveTransportFailures = 0;
+let latchedOff = false;
+let maxFailures = 3;
+/** Errors we raise ourselves for a legitimate miss, as opposed to the service failing. */
+const MISS = /^No (song|lyrics) found!$/;
+/** Tune or reset the Musixmatch fallback. */
+const configureMusixmatch = (options = {}) => {
+    if (typeof options.maxFailures === 'number' && options.maxFailures > 0) {
+        maxFailures = Math.floor(options.maxFailures);
+    }
+    if (options.enabled !== undefined) {
+        latchedOff = !options.enabled;
+        if (options.enabled) {
+            consecutiveTransportFailures = 0;
+        }
+    }
+};
+exports.configureMusixmatch = configureMusixmatch;
+/** Whether the fallback is still being attempted, and how close it is to latching off. */
+const musixmatchStatus = () => ({
+    available: !latchedOff,
+    consecutiveFailures: consecutiveTransportFailures,
+    maxFailures,
+});
+exports.musixmatchStatus = musixmatchStatus;
 const getUrlMusixmatch = async (query) => {
     var _a;
     const data = await (0, http_1.getText)(`${baseUrl}/search/${encodeURI(query)}/tracks`, {
@@ -20,7 +57,7 @@ const getUrlMusixmatch = async (query) => {
     }
     throw new Error('No song found!');
 };
-const getLyricsMusixmatch = async (query) => {
+const scrape = async (query) => {
     const url = await getUrlMusixmatch(query);
     const data = await (0, http_1.getText)(url, {
         headers: {
@@ -36,4 +73,25 @@ const getLyricsMusixmatch = async (query) => {
     lyrics = lyrics.replace('"body":"', '').replace('","language"', '');
     return lyrics.split('\\n').join('\n');
 };
+const getLyricsMusixmatch = async (query) => {
+    var _a;
+    if (latchedOff) {
+        throw new Error('Musixmatch fallback is unavailable from this network (latched off)');
+    }
+    try {
+        const lyrics = await scrape(query);
+        consecutiveTransportFailures = 0; // it works — forget any earlier trouble
+        return lyrics;
+    }
+    catch (err) {
+        // a track that simply isn't there says nothing about the service
+        if (!MISS.test((_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : '')) {
+            consecutiveTransportFailures += 1;
+            if (consecutiveTransportFailures >= maxFailures) {
+                latchedOff = true;
+            }
+        }
+        throw err;
+    }
+};
 exports.getLyricsMusixmatch = getLyricsMusixmatch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur-core",
-  "version": "2.17.0",
+  "version": "2.19.0",
   "description": "Deezer API client, cross-service URL resolution, Blowfish track decryption and MP3/FLAC metadata tagging — the engine behind the gerdur CLI.",
   "keywords": [
     "deezer",