musicbrainz-api 0.25.0 → 0.26.0

package/lib/coverartarchive-api.js

@@ -2,7 +2,7 @@
 import { HttpClient } from "./http-client.js";
 export class CoverArtArchiveApi {
     constructor() {
-        this.httpClient = new HttpClient({ baseUrl: 'https://coverartarchive.org', userAgent: 'Node.js musicbrains-api', timeout: 20000, followRedirects: false });
+        this.httpClient = new HttpClient({ baseUrl: 'https://coverartarchive.org', userAgent: 'Node.js musicbrains-api', timeout: 2000, followRedirects: false });
     }
     async getJson(path) {
         const response = await this.httpClient.get(path, {

package/lib/http-client-node.js

@@ -13,7 +13,7 @@ export class HttpClientNode extends HttpClient {
         return Promise.resolve(undefined);
     }
     getCookies() {
-        return this.cookieJar.getCookieString(this.options.baseUrl); // Get cookies for the request
+        return this.cookieJar.getCookieString(this.httpOptions.baseUrl); // Get cookies for the request
     }
 }
 //# sourceMappingURL=http-client-node.js.map

package/lib/http-client.d.ts

@@ -10,6 +10,9 @@ export type MultiQueryFormData = {
 };
 export interface IHttpClientOptions {
     baseUrl: string;
+    /**
+     * Retry time-out, default 500 ms
+     */
     timeout: number;
     userAgent: string;
     followRedirects?: boolean;
@@ -22,13 +25,15 @@ export interface IFetchOptions {
     followRedirects?: boolean;
 }
 export declare class HttpClient {
-    protected options: IHttpClientOptions;
-    constructor(options: IHttpClientOptions);
+    protected httpOptions: IHttpClientOptions;
+    constructor(httpOptions: IHttpClientOptions);
     get(path: string, options?: IFetchOptions): Promise<Response>;
     post(path: string, options?: IFetchOptions): Promise<Response>;
     postForm(path: string, formData: HttpFormData, options?: IFetchOptions): Promise<Response>;
     postJson(path: string, json: Object, options?: IFetchOptions): Promise<Response>;
     private _fetch;
-    protected registerCookies(response: Response): Promise<Cookie | undefined>;
+    private _buildUrl;
+    private _delay;
+    protected registerCookies(_response: Response): Promise<Cookie | undefined>;
     getCookies(): Promise<string | null>;
 }

package/lib/http-client.js

@@ -1,6 +1,14 @@
+import Debug from "debug";
+const debug = Debug('musicbrainz-api-node');
+function isConnectionReset(err) {
+    // Undici puts the OS error on .cause, with .code like 'ECONNRESET'
+    const code = err?.cause?.code ?? err?.code;
+    // Add other transient codes you consider safe to retry:
+    return typeof code === "string" && code === 'ECONNRESET';
+}
 export class HttpClient {
-    constructor(options) {
-        this.options = options;
+    constructor(httpOptions) {
+        this.httpOptions = httpOptions;
     }
     get(path, options) {
         return this._fetch('get', path, options);
@@ -12,7 +20,6 @@ export class HttpClient {
         const encodedFormData = new URLSearchParams(formData).toString();
         return this._fetch('post', path, { ...options, body: encodedFormData, headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
     }
-    // biome-ignore lint/complexity/noBannedTypes:
     postJson(path, json, options) {
         const encodedJson = JSON.stringify(json);
         return this._fetch('post', path, { ...options, body: encodedJson, headers: { 'Content-Type': 'application/json.' } });
@@ -20,34 +27,69 @@ export class HttpClient {
     async _fetch(method, path, options) {
         if (!options)
             options = {};
-        let url = path.startsWith('/') ? `${this.options.baseUrl}${path}` : `${this.options.baseUrl}/${path}`;
-        if (options.query) {
-            const urlSearchParams = new URLSearchParams();
-            for (const key of Object.keys(options.query)) {
-                const value = options.query[key];
-                (Array.isArray(value) ? value : [value]).forEach(value => {
-                    urlSearchParams.append(key, value);
-                });
-            }
-            url += `?${urlSearchParams.toString()}`;
-        }
+        let retryLimit = options.retryLimit && options.retryLimit > 1 ? options.retryLimit : 1;
+        const retryTimeout = this.httpOptions.timeout ? this.httpOptions.timeout : 500;
+        const url = this._buildUrl(path, options.query);
         const cookies = await this.getCookies();
         const headers = new Headers(options.headers);
-        headers.set('User-Agent', this.options.userAgent);
+        headers.set('User-Agent', this.httpOptions.userAgent);
         if (cookies !== null) {
             headers.set('Cookie', cookies);
         }
-        const response = await fetch(url, {
-            method,
-            ...options,
-            headers,
-            body: options.body,
-            redirect: options.followRedirects === false ? 'manual' : 'follow'
-        });
-        await this.registerCookies(response);
-        return response;
-    }
-    registerCookies(response) {
+        while (retryLimit > 0) {
+            let response;
+            try {
+                response = await fetch(url, {
+                    method,
+                    ...options,
+                    headers,
+                    body: options.body,
+                    redirect: options.followRedirects === false ? 'manual' : 'follow'
+                });
+            }
+            catch (err) {
+                if (isConnectionReset(err)) {
+                    // Retry on TCP connection resets
+                    await this._delay(retryTimeout); // wait 200ms before retry
+                    continue;
+                }
+                throw err;
+            }
+            if (response.status === 429 || response.status === 503) {
+                debug(`Received status=${response.status}, assume reached rate limit, retry in ${retryTimeout} ms`);
+                retryLimit--;
+                if (retryLimit > 0) {
+                    await this._delay(retryTimeout); // wait 200ms before retry
+                    continue;
+                }
+            }
+            await this.registerCookies(response);
+            return response;
+        }
+        throw new Error(`Failed to fetch ${url} after retries`);
+    }
+    // Helper: Builds URL with query string
+    _buildUrl(path, query) {
+        let url = path.startsWith('/')
+            ? `${this.httpOptions.baseUrl}${path}`
+            : `${this.httpOptions.baseUrl}/${path}`;
+        if (query) {
+            const urlSearchParams = new URLSearchParams();
+            for (const key of Object.keys(query)) {
+                const value = query[key];
+                (Array.isArray(value) ? value : [value]).forEach(v => {
+                    urlSearchParams.append(key, v);
+                });
+            }
+            url += `?${urlSearchParams.toString()}`;
+        }
+        return url;
+    }
+    // Helper: Delays execution
+    _delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    registerCookies(_response) {
         return Promise.resolve(undefined);
     }
     async getCookies() {

package/lib/musicbrainz-api-node.js

@@ -1,5 +1,4 @@
 import { StatusCodes as HttpStatus } from 'http-status-codes';
-import Debug from 'debug';
 export { XmlMetadata } from './xml/xml-metadata.js';
 export { XmlIsrc } from './xml/xml-isrc.js';
 export { XmlIsrcList } from './xml/xml-isrc-list.js';
@@ -11,12 +10,11 @@ export * from './http-client.js';
 /*
  * https://musicbrainz.org/doc/Development/XML_Web_Service/Version_2#Subqueries
  */
-const debug = Debug('musicbrainz-api-node');
 export class MusicBrainzApi extends MusicBrainzApiDefault {
     initHttpClient() {
         return new HttpClientNode({
             baseUrl: this.config.baseUrl,
-            timeout: 20 * 1000,
+            timeout: 500,
             userAgent: `${this.config.appName}/${this.config.appVersion} ( ${this.config.appContactInfo} )`
         });
     }

package/lib/musicbrainz-api.js

@@ -41,7 +41,7 @@ export class MusicBrainzApi {
     initHttpClient() {
         return new HttpClient({
             baseUrl: this.config.baseUrl,
-            timeout: 20 * 1000,
+            timeout: 500,
             userAgent: `${this.config.appName}/${this.config.appVersion} ( ${this.config.appContactInfo} )`
         });
     }
@@ -74,6 +74,12 @@ export class MusicBrainzApi {
             // Serialize include parameter
             query.inc = inc.join(' ');
         }
+        for (const pipedFilter of ['type', 'status']) {
+            if (query[pipedFilter]) {
+                // Serialize type parameter
+                query[pipedFilter] = query[pipedFilter].join('|');
+            }
+        }
         return this.restGet(`/${entity}`, query);
     }
     search(entity, query) {

package/lib/musicbrainz.types.d.ts

@@ -46,7 +46,7 @@ export interface IMatch {
     score: number;
 }
 export type Gender = 'male' | 'female' | 'other' | 'not applicable';
-export interface IArtist extends ITypedEntity {
+export interface IArtist extends ITypedEntity, IMayHaveRelations {
     name: string;
     disambiguation: string;
     'sort-name': string;
@@ -60,7 +60,6 @@ export interface IArtist extends ITypedEntity {
     area?: IArea;
     begin_area?: IArea;
     end_area?: IArea;
-    relations?: IRelation[];
     /**
      * Only defined if 'releases' are includes
      */
@@ -104,7 +103,7 @@ export interface IInstrument extends ITypedEntity {
 export type ReleaseQuality = 'normal' | 'high';
 export type ReleaseStatus = 'Official' | 'Promotion' | 'Bootleg' | 'Pseudo-release' | 'Withdrawn' | 'Expunged' | 'Cancelled';
 export type ReleasePackaging = 'Book' | 'Box' | 'Cardboard/Paper Sleeve' | 'Cassette Case' | 'Clamshell Case' | 'Digibook' | 'Digifile' | 'Digipak' | 'Discbox Slider' | 'Fatbox' | 'Gatefold Cover' | 'Jewel case' | 'Keep Case' | 'Longbox' | 'Metal Tin' | 'Plastic sleeve' | 'Slidepack' | 'Slim Jewel Case' | 'Snap Case' | 'SnapPack' | 'Super Jewel Box' | 'Other' | 'None';
-export interface IRelease extends IEntity {
+export interface IRelease extends IEntity, IMayHaveRelations {
     title: string;
     'text-representation': {
         'language': string;
@@ -123,7 +122,6 @@ export interface IRelease extends IEntity {
     country: string;
     quality: ReleaseQuality;
     barcode: string;
-    relations?: IRelation[];
     'artist-credit'?: IArtistCredit[];
     'release-group'?: IReleaseGroup;
     collections?: ICollection[];
@@ -135,14 +133,13 @@ export interface IReleaseEvent {
     date?: string;
 }
 export type MediaFormatType = 'Digital Media';
-export interface IRecording extends IEntity {
+export interface IRecording extends IEntity, IMayHaveRelations {
     video: boolean;
     length: number;
     title: string;
     disambiguation: string;
     isrcs?: string[];
     releases?: IRelease[];
-    relations?: IRelation[];
     'artist-credit'?: IArtistCredit[];
     aliases?: IAlias[];
     'first-release-date': string;
@@ -273,7 +270,7 @@ export interface IRelation {
     url?: IUrl;
     release?: IRelease;
 }
-export interface IRelationList {
+export interface IMayHaveRelations {
     relations: IRelation[];
 }
 export interface IWork extends IEntity {
@@ -301,10 +298,9 @@ export interface ISeries extends ITypedEntity {
 export interface ITag {
     name: string;
 }
-export interface IUrl extends IEntity {
+export interface IUrl extends IEntity, IMayHaveRelations {
     id: string;
     resource: string;
-    relations?: IRelationList[];
 }
 export interface IExernalIds {
     [type: string]: string;
@@ -321,6 +317,14 @@ export type OtherEntityTypes = 'annotation' | 'cdstub' | 'tag';
  */
 export type EntityType = 'annotation' | 'area' | 'artist' | 'collection' | 'event' | 'instrument' | 'label' | 'place' | 'recording' | 'release' | 'release-group' | 'series' | 'work' | 'url';
 export type Relationships = 'area-rels' | 'artist-rels' | 'event-rels' | 'instrument-rels' | 'label-rels' | 'place-rels' | 'recording-rels' | 'release-rels' | 'release-group-rels' | 'series-rels' | 'url-rels' | 'work-rels';
+/**
+ * Ref: https://musicbrainz.org/doc/MusicBrainz_API#Release_.28Group.29_Type_and_Status
+ */
+export type ReleaseStatusQuery = 'official' | 'promotion' | 'bootleg' | 'pseudo-release' | 'withdrawn' | 'cancelled';
+/**
+ * Ref: https://musicbrainz.org/doc/MusicBrainz_API#Release_.28Group.29_Type_and_Status
+ */
+export type ReleaseTypeQuery = 'album' | 'single' | 'ep' | 'broadcast' | 'other' | 'audiobook' | 'compilation' | 'demo' | 'dj-mix' | 'field recording' | 'interview' | 'live' | 'mixtape/street' | 'remix' | 'soundtrack' | 'spokenword';
 export declare enum LinkType {
     license = 302,
     production = 256,
@@ -346,6 +350,13 @@ export interface IPagination {
      */
     limit?: number;
 }
+/**
+ * Release and release-group types
+ */
+export interface IReleaseTypeAndStatus {
+    status?: ReleaseStatusQuery[];
+    type?: ReleaseTypeQuery[];
+}
 /**
  * https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search#Artist
  */
@@ -510,7 +521,7 @@ interface BrowseReleasesEntityParams {
     track_artist: string;
     work: string;
 }
-export type IBrowseReleasesQuery = IPagination & OneOf<BrowseReleasesEntityParams>;
+export type IBrowseReleasesQuery = IPagination & IReleaseTypeAndStatus & OneOf<BrowseReleasesEntityParams>;
 /**
  * List of entity names allowed for browsing artists by a single MBID.
  * Used as a key set for constructing exclusive query types.
@@ -591,7 +602,7 @@ interface BrowseReleaseGroupsEntityParams {
     collection: string;
     release: string;
 }
-export type IBrowseReleaseGroupsQuery = IPagination & OneOf<BrowseReleaseGroupsEntityParams>;
+export type IBrowseReleaseGroupsQuery = IPagination & IReleaseTypeAndStatus & OneOf<BrowseReleaseGroupsEntityParams>;
 /**
  * List of entity names allowed for browsing works by a single MBID.
  * Used as a key set for constructing exclusive query types.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musicbrainz-api",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "MusicBrainz API client for reading and submitting metadata",
   "exports": {
     "node": {
@@ -58,26 +58,26 @@
     "rate-limit-threshold": "^0.2.0",
     "spark-md5": "^3.0.2",
     "tough-cookie": "^5.0.0",
-    "uuid": "^11.0.3"
+    "uuid": "^13.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.8.3",
+    "@biomejs/biome": "2.3.2",
     "@types/chai": "^5.0.0",
     "@types/jsontoxml": "^1.0.5",
     "@types/mocha": "^10.0.4",
-    "@types/node": "^22.5.0",
+    "@types/node": "^24.0.3",
     "@types/sinon": "^17.0.3",
     "@types/source-map-support": "^0",
     "@types/spark-md5": "^3",
     "@types/tough-cookie": "^4.0.5",
     "@types/uuid": "^10.0.0",
     "c8": "^10.1.2",
-    "chai": "^5.1.1",
-    "del-cli": "^6.0.0",
+    "chai": "^6.2.0",
+    "del-cli": "^7.0.0",
     "mocha": "^11.0.1",
     "remark-cli": "^12.0.0",
     "remark-preset-lint-recommended": "^7.0.0",
-    "sinon": "^20.0.0",
+    "sinon": "^21.0.0",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.4"
@@ -89,14 +89,15 @@
     "compile": "yarn run compile-lib && yarn run compile-test",
     "lint:md": "remark -u preset-lint-recommended .",
     "lint:ts": "biome check",
-    "lint:fix": "biome check --fix",
+    "lint:fix": "biome check --write",
     "lint": "yarn run lint:md && yarn run lint:ts",
     "test": "mocha",
     "build": "yarn run clean && yarn run compile",
     "start": "yarn run compile && yarn run lint && yarn run cover-test",
     "test-coverage": "c8 yarn run test",
     "send-codacy": "c8 report --reporter=text-lcov | codacy-coverage",
-    "prepublishOnly": "yarn run build"
+    "prepublishOnly": "yarn run build",
+    "update-biome": "yarn add -D --exact @biomejs/biome && npx @biomejs/biome migrate --write && npm run lint:fix"
   },
   "nyc": {
     "exclude": [