musicbrainz-api 0.20.2 → 0.22.0

package/LICENSE.txt

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 Borewit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -425,26 +425,40 @@ await mbApi.addSpotifyIdToRecording(recording, '2AMysGXOe0zzZJMtH3Nizb');
 This library also supports the [Cover Art Archive API](https://musicbrainz.org/doc/Cover_Art_Archive/API).
 
 ### Fetch Release Cover Art
+
+#### Fetch available cover art information
+
 ```js
 import { CoverArtArchiveApi } from 'musicbrainz-api';
 
 const coverArtArchiveApiClient = new CoverArtArchiveApi();
 
-async function getReleaseCoverArt(releaseMbid, coverType = '') {
-    try {
-        const coverInfo = await coverArtArchiveApiClient.getReleaseCovers(releaseMbid, coverType);
-        console.log(`Cover info for ${coverType || 'all covers'}`, coverInfo);
-    } catch (error) {
-        console.error(`Failed to fetch ${coverType || 'all covers'}:`, error);
+async function fetchCoverArt(releaseMbid, coverType = '') {
+    const coverInfo = await coverArtArchiveApiClient.getReleaseCovers(releaseMbid);
+    for(const image of coverInfo.images) {
+        console.log(`Cover art front=${image.front} back=${image.back} url=${image.image}`);
     }
 }
 
-(async () => {
-    const releaseMbid = 'your-release-mbid-here';  // Replace with actual MBID
-    await getReleaseCoverArt(releaseMbid); // Get all covers
-    await getReleaseCoverArt(releaseMbid, 'front'); // Get best front cover
-    await getReleaseCoverArt(releaseMbid, 'back'); // Get best back cover
-})();
+fetchCoverArt('976e0677-a480-4a5e-a177-6a86c1900bbf').catch(error => {
+    console.error(`Failed to fetch cover art: ${error.message}`);
+})
+```
+
+#### Fetch front or back cover for a release
+```js
+import { CoverArtArchiveApi } from 'musicbrainz-api';
+
+const coverArtArchiveApiClient = new CoverArtArchiveApi();
+
+async function fetchCoverArt(releaseMbid, coverType = '') {
+    const coverInfo = await coverArtArchiveApiClient.getReleaseCover(releaseMbid, 'front');
+    console.log(`Cover art url=${coverInfo.url}`);
+}
+
+fetchCoverArt('976e0677-a480-4a5e-a177-6a86c1900bbf').catch(error => {
+    console.error(`Failed to fetch cover art: ${error.message}`);
+})
 ```
 
 ### Release Group Cover Art
@@ -453,47 +467,69 @@ import { CoverArtArchiveApi } from 'musicbrainz-api';
 
 const coverArtArchiveApiClient = new CoverArtArchiveApi();
 
-async function getCoverArt(releaseGroupMbid, coverType = '') {
-    try {
-        const coverInfo = await coverArtArchiveApiClient.getReleaseGroupCovers(releaseGroupMbid, coverType);
-        console.log(`Cover info for ${coverType || 'all covers'}`, coverInfo);
-    } catch (error) {
-        console.error(`Failed to fetch ${coverType || 'all covers'}:`, error);
+async function fetchCoverArt(releaseMbid, coverType = '') {
+    const coverInfo = await coverArtArchiveApiClient.getReleaseGroupCovers(releaseMbid);
+    for(const image of coverInfo.images) {
+        console.log(`Cover art front=${image.front} back=${image.back} url=${image.image}`);
     }
 }
 
-(async () => {
-    const releaseGroupMbid = 'your-release-group-mbid-here';  // Replace with actual MBID
-    await getCoverArt(releaseGroupMbid); // Get all covers
-    await getCoverArt(releaseGroupMbid, 'front'); // Get best front cover
-    await getCoverArt(releaseGroupMbid, 'back'); // Get best back cover
-})();
+fetchCoverArt('976e0677-a480-4a5e-a177-6a86c1900bbf').catch(error => {
+    console.error(`Failed to fetch cover art: ${error.message}`);
+})
+```
+
+#### Fetch front or back cover for a release-group
+```js
+import { CoverArtArchiveApi } from 'musicbrainz-api';
 
+const coverArtArchiveApiClient = new CoverArtArchiveApi();
+
+async function fetchCoverArt(releaseMbid, coverType = '') {
+    const coverInfo = await coverArtArchiveApiClient.getReleaseGroupCover(releaseMbid, 'front');
+    console.log(`Cover art url=${coverInfo.url}`);
+}
+
+fetchCoverArt('976e0677-a480-4a5e-a177-6a86c1900bbf').catch(error => {
+    console.error(`Failed to fetch cover art: ${error.message}`);
+})
 ```
 
 ## CommonJS backward compatibility
 
-For legacy CommonJS projects needing to load the `music-metadata` ESM module, you can use the `loadMusicMetadata` function:
+I recommend CommonJS projects to consider upgrading their project to ECMAScript Module (ESM).
+Please continue reading how to use **musicbrainz-api** in a CommonJS project.
+
+Using Node.js ≥ 22, which is support loading ESM module via require, you can use:
 ```js
-const { loadMusicBrainzApi } = require('musicbrainz-api');
+const { MusicBrainzApi } = require('musicbrainz-api');
+```
 
-(async () => {
+Other CommonJS projects have to use [dynamic import](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/import) to load the **musicbrainz-api** pure ESM module:
+```js
+async function run() {
+  // Dynamically loads the ESM module in a CommonJS project  
+  const { MusicBrainzApi } = await import('musicbrainz-api');
+};
 
-    // Dynamically loads the ESM module in a CommonJS project
-    const  {MusicBrainzApi} = await loadMusicBrainzApi();
+run();
+```
 
-    const mbApi = new MusicBrainzApi({
-        appName: 'my-app',
-        appVersion: '0.1.0',
-        appContactInfo: 'user@mail.org',
-    });
+This is known not to work in TypeScript CommonJS projects, as the TypeScript compiler, in my opinion,
+incorrectly converts the [dynamic import](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/import) 
+to `require()`. To perform the dynamic import in TypeScript, you can use [load-esm](https://github.com/Borewit/load-esm):
 
-    const releaseList = await mbApi.search('release', {query: {barcode: 602537479870}});
-    for(const release of releaseList.releases) {
-        console.log(release.title);
-    }
-})();
+```js
+import {loadEsm} from 'load-esm';
+
+async function run() {
+    // Dynamically loads the ESM module in a TypeScript CommonJS project  
+  const { MusicBrainzApi } = await loadEsm<typeof import('musicbrainz-api')>('musicbrainz-api');
+};
+
+run();
 ```
 
-> [!NOTE]
-> The `loadMusicMetadata` function is experimental.
+## Licence
+
+This project is licensed under the [MIT License](LICENSE.txt). Feel free to use, modify, and distribute as needed.

package/lib/coverartarchive-api.d.ts

@@ -16,27 +16,45 @@ export interface IImage {
         '1200'?: string;
     };
 }
-export interface ICoverInfo {
+export type CoverType = 'front' | 'back';
+export interface ICoversInfo {
     images: IImage[];
     release: string;
 }
+export interface ICoverInfo {
+    url: string | null;
+}
 export declare class CoverArtArchiveApi {
     private httpClient;
     private getJson;
+    private getCoverRedirect;
     /**
      * Fetch release
      * @releaseId Release MBID
      * @param releaseId MusicBrainz Release MBID
-     * @param coverType Cover type
      */
-    getReleaseCovers(releaseId: string, coverType?: 'front' | 'back'): Promise<ICoverInfo>;
+    getReleaseCovers(releaseId: string): Promise<ICoversInfo>;
     /**
      * Fetch release-group
      * @releaseGroupId Release-group MBID
      * @param releaseGroupId MusicBrainz Release Group MBID
-     * @param coverType Cover type
      */
-    getReleaseGroupCovers(releaseGroupId: string, coverType?: 'front' | 'back'): Promise<ICoverInfo>;
+    getReleaseGroupCovers(releaseGroupId: string): Promise<ICoversInfo>;
+    /**
+     * Fetch release cover
+     * @releaseId Release MBID
+     * @param releaseId MusicBrainz Release MBID
+     * @param coverType Front or back cover
+     */
+    getReleaseCover(releaseId: string, coverType: CoverType): Promise<ICoverInfo>;
+    /**
+     * Fetch release-group cover
+     * @releaseId Release-group MBID
+     * @param releaseGroupId MusicBrainz Release-group MBID
+     * @param coverType Front or back cover
+     */
+    getReleaseGroupCover(releaseGroupId: string, coverType: CoverType): Promise<ICoverInfo>;
+    private static makePath;
     /**
      * Fetch covers
      * @releaseId MBID
@@ -45,4 +63,12 @@ export declare class CoverArtArchiveApi {
      * @param coverType Cover type
      */
     private getCovers;
+    /**
+     * Fetch covers
+     * @releaseId MBID
+     * @param releaseId MusicBrainz Release Group MBID
+     * @param releaseType Fetch covers for specific release or release-group
+     * @param coverType Cover type
+     */
+    private getCover;
 }

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 });
+        this.httpClient = new HttpClient({ baseUrl: 'https://coverartarchive.org', userAgent: 'Node.js musicbrains-api', timeout: 20000, followRedirects: false });
     }
     async getJson(path) {
         const response = await this.httpClient.get(path, {
@@ -19,23 +19,66 @@ export class CoverArtArchiveApi {
         }
         return response.json();
     }
+    async getCoverRedirect(path) {
+        const response = await this.httpClient.get(path, {
+            followRedirects: false
+        });
+        switch (response.status) {
+            case 307:
+                return response.headers.get('LOCATION');
+            case 400:
+                throw new Error('Invalid UUID');
+            case 404:
+                // No release with this MBID
+                return null;
+            case 405:
+                throw new Error('Invalid HTTP method');
+            case 503:
+                return null;
+            default:
+                throw new Error(`Unexpected HTTP-status response: ${response.status}`);
+        }
+    }
     /**
      * Fetch release
      * @releaseId Release MBID
      * @param releaseId MusicBrainz Release MBID
-     * @param coverType Cover type
      */
-    getReleaseCovers(releaseId, coverType) {
-        return this.getCovers(releaseId, 'release', coverType);
+    getReleaseCovers(releaseId) {
+        return this.getCovers(releaseId, 'release');
     }
     /**
      * Fetch release-group
      * @releaseGroupId Release-group MBID
      * @param releaseGroupId MusicBrainz Release Group MBID
-     * @param coverType Cover type
      */
-    getReleaseGroupCovers(releaseGroupId, coverType) {
-        return this.getCovers(releaseGroupId, 'release-group', coverType);
+    getReleaseGroupCovers(releaseGroupId) {
+        return this.getCovers(releaseGroupId, 'release-group');
+    }
+    /**
+     * Fetch release cover
+     * @releaseId Release MBID
+     * @param releaseId MusicBrainz Release MBID
+     * @param coverType Front or back cover
+     */
+    getReleaseCover(releaseId, coverType) {
+        return this.getCover(releaseId, 'release', coverType);
+    }
+    /**
+     * Fetch release-group cover
+     * @releaseId Release-group MBID
+     * @param releaseGroupId MusicBrainz Release-group MBID
+     * @param coverType Front or back cover
+     */
+    getReleaseGroupCover(releaseGroupId, coverType) {
+        return this.getCover(releaseGroupId, 'release-group', coverType);
+    }
+    static makePath(releaseId, releaseType = 'release', coverType) {
+        const path = [releaseType, releaseId];
+        if (coverType) {
+            path.push(coverType);
+        }
+        return `/${path.join('/')}`;
     }
     /**
      * Fetch covers
@@ -44,17 +87,24 @@ export class CoverArtArchiveApi {
      * @param releaseType Fetch covers for specific release or release-group
      * @param coverType Cover type
      */
-    async getCovers(releaseId, releaseType = 'release', coverType) {
-        const path = [releaseType, releaseId];
-        if (coverType) {
-            path.push(coverType);
-        }
-        const info = await this.getJson(`/${path.join('/')}`);
+    async getCovers(releaseId, releaseType = 'release') {
+        const info = await this.getJson(CoverArtArchiveApi.makePath(releaseId, releaseType));
         // Hack to correct http addresses into https
         if (info.release?.startsWith('http:')) {
             info.release = `https${info.release.substring(4)}`;
         }
         return info;
     }
+    /**
+     * Fetch covers
+     * @releaseId MBID
+     * @param releaseId MusicBrainz Release Group MBID
+     * @param releaseType Fetch covers for specific release or release-group
+     * @param coverType Cover type
+     */
+    async getCover(releaseId, releaseType = 'release', coverType) {
+        const url = await this.getCoverRedirect(CoverArtArchiveApi.makePath(releaseId, releaseType, coverType));
+        return { url: url };
+    }
 }
 //# sourceMappingURL=coverartarchive-api.js.map

package/lib/entry-default.d.ts

@@ -1,6 +1,2 @@
 export * from './coverartarchive-api.js';
 export * from './musicbrainz-api.js';
-/**
- * CommonJS (only) function to load `musicbrainz-api` ESM module
- */
-export declare function loadMusicBrainzApi(): Promise<typeof import('musicbrainz-api')>;

package/lib/http-client.d.ts

@@ -6,6 +6,7 @@ export interface IHttpClientOptions {
     baseUrl: string;
     timeout: number;
     userAgent: string;
+    followRedirects?: boolean;
 }
 export interface IFetchOptions {
     query?: HttpFormData;

package/lib/http-client.js

@@ -20,7 +20,7 @@ export class HttpClient {
     async _fetch(method, path, options) {
         if (!options)
             options = {};
-        let url = `${this.options.baseUrl}/${path}`;
+        let url = path.startsWith('/') ? `${this.options.baseUrl}${path}` : `${this.options.baseUrl}/${path}`;
         if (options.query) {
             url += `?${new URLSearchParams(options.query)}`;
         }

package/lib/musicbrainz-api.js

@@ -48,7 +48,7 @@ export class MusicBrainzApi {
     async restGet(relUrl, query = {}) {
         query.fmt = 'json';
         await this.applyRateLimiter();
-        const response = await this.httpClient.get(`ws/2${relUrl}`, {
+        const response = await this.httpClient.get(`/ws/2${relUrl}`, {
             query,
             retryLimit: 10
         });
@@ -79,7 +79,7 @@ export class MusicBrainzApi {
             throw new Error("XML-Post requires the appName & appVersion to be defined");
         }
         const clientId = `${this.config.appName.replace(/-/g, '.')}-${this.config.appVersion}`;
-        const path = `ws/2/${entity}/`;
+        const path = `/ws/2/${entity}/`;
         // Get digest challenge
         let digest = '';
         let n = 1;
@@ -120,7 +120,7 @@ export class MusicBrainzApi {
         formData.username = this.config.botAccount?.username;
         formData.password = this.config.botAccount?.password;
         formData.remember_me = 1;
-        const response = await this.httpClient.postForm(`${entity}/${mbid}/edit`, formData, {
+        const response = await this.httpClient.postForm(`/${entity}/${mbid}/edit`, formData, {
             followRedirects: false
         });
         if (response.status === HttpStatus.OK)

package/lib/musicbrainz.types.d.ts

@@ -5,21 +5,32 @@ export interface IPeriod {
     'ended': boolean;
     'end': string;
 }
+export interface ITypedEntity extends IEntity {
+    'type-id': string;
+    type: string;
+    id: string;
+}
 export interface IEntity {
     id: string;
 }
-export interface IArea extends IEntity {
-    'iso-3166-1-codes': string[];
+export interface LifeSpan {
+    ended: boolean;
+    begin: null | string;
+    end: null | string;
+}
+export interface IArea extends ITypedEntity {
+    type: 'Country' | 'Subdivision' | 'Municipality' | 'City' | 'District' | 'Island';
+    'iso-3166-1-codes'?: string[];
+    primary: boolean;
     name: string;
     'sort-name': string;
     disambiguation: string;
+    'life-span': LifeSpan;
 }
-export interface IAlias extends IEntity {
+export interface IAlias extends ITypedEntity {
     name: string;
     'sort-name': string;
     ended: boolean;
-    'type-id': string;
-    type: string;
     locale: string;
     primary: string;
     begin: string;
@@ -28,19 +39,18 @@ export interface IAlias extends IEntity {
 export interface IMatch {
     score: number;
 }
-export interface IArtist extends IEntity {
+export type Gender = 'male' | 'female' | 'other' | 'not applicable';
+export interface IArtist extends ITypedEntity {
     name: string;
     disambiguation: string;
     'sort-name': string;
-    'type-id'?: string;
     'gender-id'?: string;
     'life-span'?: IPeriod;
     country?: string;
     ipis?: string[];
     isnis?: string[];
     aliases?: IAlias[];
-    gender?: string;
-    type?: string;
+    gender?: Gender;
     area?: IArea;
     begin_area?: IArea;
     end_area?: IArea;
@@ -56,32 +66,31 @@ export interface IArtistCredit {
     joinphrase: string;
     name: string;
 }
-export interface ICollection extends IEntity {
-    type: string;
+export interface ICollection extends ITypedEntity {
+    type: 'Recording collection';
     name: string;
-    'type-id': string;
     'recording-count': number;
     editor: string;
     'entity-type': string;
 }
-export interface IEvent extends IEntity {
+export interface IEvent extends ITypedEntity {
     cancelled: boolean;
-    type: string;
     'life-span': IPeriod;
     disambiguation: string;
-    'type-id': string;
     time: string;
     setlist: string;
     name: string;
 }
-export interface IInstrument extends IEntity {
+export type InstrumentType = 'Wind instrument' | 'String instrument' | 'Percussion instrument' | 'Electronic instrument' | 'Family' | 'Ensemble' | 'Other instrument';
+export interface IInstrument extends ITypedEntity {
     disambiguation: string;
     name: string;
-    'type-id': string;
-    type: string;
+    type: InstrumentType;
     description: string;
 }
-export type ReleaseQuality = 'normal';
+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 {
     title: string;
     'text-representation': {
@@ -89,22 +98,23 @@ export interface IRelease extends IEntity {
         'script': string;
     };
     disambiguation: string;
-    asin: string;
+    asin: null | string;
+    status: ReleaseStatus;
     'status-id': string;
-    packaging?: string;
-    status: string;
+    packaging?: ReleasePackaging;
     'packaging-id'?: string;
     'release-events'?: IReleaseEvent[];
     date: string;
     media: IMedium[];
     'cover-art-archive': ICoverArtArchive;
     country: string;
-    quality: string;
+    quality: ReleaseQuality;
     barcode: string;
     relations?: IRelation[];
     'artist-credit'?: IArtistCredit[];
     'release-group'?: IReleaseGroup;
     collections?: ICollection[];
+    'track-count'?: number;
 }
 export interface IReleaseEvent {
     area?: IArea;
@@ -121,6 +131,7 @@ export interface IRecording extends IEntity {
     relations?: IRelation[];
     'artist-credit'?: IArtistCredit[];
     aliases?: IAlias[];
+    'first-release-date': string;
 }
 export interface ITrack extends IEntity {
     position: number;
@@ -172,6 +183,7 @@ export interface IRecordingMatch extends IRecording, IMatch {
 export interface IReleaseGroupMatch extends IReleaseGroup, IMatch {
 }
 export interface IReleaseMatch extends IRelease, IMatch {
+    count: number;
 }
 export interface ISearchResult {
     created: DateTimeFormat;
@@ -223,16 +235,23 @@ export interface IWork extends IEntity {
     title: string;
 }
 export interface ILabel extends IEntity {
+    asin: null | string;
+    barcode: null | string;
+    country: null | string;
     name: string;
+    'sort-name': string;
+    'life-span': LifeSpan;
+    disambiguation?: string;
+    'label-code': null | string;
+    ipis: string[];
+    area: IArea;
 }
 export interface IPlace extends IEntity {
     name: string;
 }
-export interface ISeries extends IEntity {
+export interface ISeries extends ITypedEntity {
     name: string;
-    type: string;
     disambiguation: string;
-    'type-id': string;
 }
 export interface IUrl extends IEntity {
     id: string;

package/package.json

@@ -1,23 +1,21 @@
 {
   "name": "musicbrainz-api",
-  "version": "0.20.2",
+  "version": "0.22.0",
   "description": "MusicBrainz API client for reading and submitting metadata",
   "exports": {
     "node": {
-      "import": "./lib/entry-node.js",
-      "require": "./lib/entry-node.cjs"
+      "types": "./lib/entry-node.d.ts",
+      "default": "./lib/entry-node.js"
     },
     "default": {
-      "import": "./lib/entry-default.js",
-      "require": "./lib/entry-default.cjs"
+      "types": "./lib/entry-default.d.ts",
+      "default": "./lib/entry-default.js"
     }
   },
-  "types": "lib/index.d.ts",
+  "types": "lib/entry-default.d.ts",
   "files": [
     "lib/**/*.js",
-    "lib/**/*.d.ts",
-    "lib/entry-node.cjs",
-    "lib/entry-default.cjs"
+    "lib/**/*.d.ts"
   ],
   "type": "module",
   "author": {
@@ -92,9 +90,10 @@
     "compile-lib": "tsc -p lib",
     "compile-test": "tsc -p test",
     "compile": "yarn run compile-lib && yarn run compile-test",
-    "lint-md": "remark -u preset-lint-recommended .",
-    "lint-ts": "biome check",
-    "lint": "yarn run lint-md && yarn run lint-ts",
+    "lint:md": "remark -u preset-lint-recommended .",
+    "lint:ts": "biome check",
+    "lint:fix": "biome check --fix",
+    "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",

package/lib/entry-default.cjs

@@ -1,5 +0,0 @@
-// CommonJS entry point
-"use strict";
-module.exports = {
-  loadMusicBrainzApi: () => import('./entry-default.js'),
-};

package/lib/entry-node.cjs

@@ -1,5 +0,0 @@
-// Node.js CommonJS entry point
-"use strict";
-module.exports = {
-    loadMusicBrainzApi: () => import('./entry-node.js'),
-};