musicbrainz-api 0.11.0 → 0.12.0

package/README.md

@@ -115,6 +115,20 @@ Lookup an `artist` and include their `releases`, `release-groups` and `aliases`
 const artist = await mbApi.lookupArtist('ab2528d9-719f-4261-8098-21849222a0f2');
 ```
 
+### Lookup collection
+
+Lookup an instrument
+
+```js
+const collection = await mbApi.lookupCollection('de4fdfc4-53aa-458a-b463-8761cc7f5af8');
+```
+
+Lookup an event
+
+```js
+const event = await mbApi.lookupEvent('6d32c658-151e-45ec-88c4-fb8787524d61');
+```
+
 ### Lookup instrument
 
 Lookup an instrument
@@ -137,6 +151,10 @@ const label = await mbApi.lookupLabel('25dda9f9-f069-4898-82f0-59330a106c7f');
 const place = await mbApi.lookupPlace('e6cfb74d-d69b-44c3-b890-1b3f509816e4');
 ```
 
+```js
+const place = await mbApi.lookupSeries('1ae6c9bc-2931-4d75-bee4-3dc53dfd246a');
+```
+
 The second argument can be used to pass [subqueries](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#Subqueries), which will return more (nested) information:
 ```js
 const artist = await mbApi.lookupArtist('ab2528d9-719f-4261-8098-21849222a0f2', ['releases', 'recordings', 'url-rels']);
@@ -475,6 +493,27 @@ assert.isTrue(succeed, 'Login successful');
 await mbApi.addSpotifyIdToRecording(recording, '2AMysGXOe0zzZJMtH3Nizb');
 ```
 
+## Cover Art Archive API
+
+Implementation of the [Cover Art Archive API](https://musicbrainz.org/doc/Cover_Art_Archive/API).
+
+```js
+import {CoverArtArchiveApi} from 'musicbrainz-api';
+
+coverArtArchiveApiClient.getReleaseCovers(releaseMbid).then(releaseCoverInfo => {
+    console.log('Release cover info', releaseCoverInfo);
+});
+
+coverArtArchiveApiClient.getReleaseCovers(releaseMbid, 'front').then(releaseCoverInfo => {
+    console.log('Get best front cover', releaseCoverInfo);
+});
+
+coverArtArchiveApiClient.getReleaseCovers(releaseMbid, 'back').then(releaseCoverInfo => {
+    console.log('Get best back cover', releaseCoverInfo);
+});
+
+```
+
 ## Compatibility
 
 The JavaScript in runtime is compliant with [ECMAScript 2017 (ES8)](https://en.wikipedia.org/wiki/ECMAScript#8th_Edition_-_ECMAScript_2017).

package/lib/coverartarchive-api.d.ts

@@ -0,0 +1,31 @@
+export type CovertType = 'Front' | 'Back' | 'Booklet' | 'Medium' | 'Obi' | 'Spine' | 'Track' | 'Tray' | 'Sticker' | 'Poster' | 'Liner' | 'Watermark' | 'Raw/Unedited' | 'Matrix/Runout' | 'Top' | 'Bottom' | 'Other';
+export interface IImage {
+    types: CovertType[];
+    front: boolean;
+    back: boolean;
+    edit: number;
+    image: string;
+    comment: string;
+    approved: boolean;
+    id: string;
+    thumbnails: {
+        large: string;
+        small: string;
+        '250': string;
+        '500'?: string;
+        '1200'?: string;
+    };
+}
+export interface ICoverInfo {
+    images: IImage[];
+    release: string;
+}
+export declare class CoverArtArchiveApi {
+    private host;
+    private getJson;
+    /**
+     *
+     * @param releaseId MusicBrainz Release MBID
+     */
+    getReleaseCovers(releaseId: string, coverType?: 'front' | 'back'): Promise<ICoverInfo>;
+}

package/lib/coverartarchive-api.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoverArtArchiveApi = void 0;
+/* eslint-disable-next-line */
+const got_1 = require("got");
+class CoverArtArchiveApi {
+    constructor() {
+        this.host = 'coverartarchive.org';
+    }
+    async getJson(path) {
+        const response = await got_1.default.get('https://' + this.host + path, {
+            headers: {
+                Accept: `application/json`
+            },
+            responseType: 'json'
+        });
+        return response.body;
+    }
+    /**
+     *
+     * @param releaseId MusicBrainz Release MBID
+     */
+    async getReleaseCovers(releaseId, coverType) {
+        const path = ['release', releaseId];
+        if (coverType) {
+            path.push(coverType);
+        }
+        const info = await this.getJson('/' + path.join('/'));
+        // Hack to correct http addresses into https
+        if (info.release && info.release.startsWith('http:')) {
+            info.release = 'https' + info.release.substring(4);
+        }
+        return info;
+    }
+}
+exports.CoverArtArchiveApi = CoverArtArchiveApi;
+//# sourceMappingURL=coverartarchive-api.js.map

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './coverartarchive-api';
+export * from './musicbrainz-api';

package/lib/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./coverartarchive-api"), exports);
+__exportStar(require("./musicbrainz-api"), exports);
+//# sourceMappingURL=index.js.map

package/lib/musicbrainz-api.d.ts

@@ -145,6 +145,11 @@ export declare class MusicBrainzApi {
      * @param inc Include: artist-credits, isrcs
      */
     lookupRecording(recordingId: string, inc?: RecordingIncludes[]): Promise<mb.IRecording>;
+    /**
+     * Lookup series
+     * @param seriesId Series MBID
+     */
+    lookupSeries(seriesId: string): Promise<mb.ISeries>;
     /**
      * Lookup work
      * @param workId Work MBID

package/lib/musicbrainz-api.js

@@ -35,7 +35,6 @@ const got_1 = require("got");
 const tough_cookie_1 = require("tough-cookie");
 __exportStar(require("./musicbrainz.types"), exports);
 const util_1 = require("util");
-const retries = 3;
 const debug = Debug('musicbrainz-api');
 class MusicBrainzApi {
     static escapeText(text) {
@@ -101,35 +100,15 @@ class MusicBrainzApi {
             },
             cookieJar: cookieJar
         };
-        this.rateLimiter = new rate_limiter_1.RateLimiter(60, 50);
+        this.rateLimiter = new rate_limiter_1.RateLimiter(15, 18);
     }
     async restGet(relUrl, query = {}, attempt = 1) {
         query.fmt = 'json';
-        let response;
         await this.rateLimiter.limit();
-        do {
-            response = await got_1.default.get('ws/2' + relUrl, Object.assign({ searchParams: query, responseType: 'json' }, this.options));
-            if (response.statusCode !== 503)
-                break;
-            debug('Rate limiter kicked in, slowing down...');
-            await rate_limiter_1.RateLimiter.sleep(500);
-        } while (true);
-        switch (response.statusCode) {
-            case http_status_codes_1.StatusCodes.OK:
-                return response.body;
-            case http_status_codes_1.StatusCodes.BAD_REQUEST:
-            case http_status_codes_1.StatusCodes.NOT_FOUND:
-                throw new Error(`Got response status ${response.statusCode}: ${(0, http_status_codes_1.getReasonPhrase)(response.status)}`);
-            case http_status_codes_1.StatusCodes.SERVICE_UNAVAILABLE: // 503
-            default:
-                const msg = `Got response status ${response.statusCode} on attempt #${attempt} (${(0, http_status_codes_1.getReasonPhrase)(response.status)})`;
-                debug(msg);
-                if (attempt < retries) {
-                    return this.restGet(relUrl, query, attempt + 1);
-                }
-                else
-                    throw new Error(msg);
-        }
+        const response = await got_1.default.get('ws/2' + relUrl, Object.assign(Object.assign({}, this.options), { searchParams: query, responseType: 'json', retry: {
+                limit: 10
+            } }));
+        return response.body;
     }
     // -----------------------------------------------------------------------------------------------------------------
     // Lookup functions
@@ -216,6 +195,13 @@ class MusicBrainzApi {
     lookupRecording(recordingId, inc = []) {
         return this.lookupEntity('recording', recordingId, inc);
     }
+    /**
+     * Lookup series
+     * @param seriesId Series MBID
+     */
+    lookupSeries(seriesId) {
+        return this.lookupEntity('series', seriesId);
+    }
     /**
      * Lookup work
      * @param workId Work MBID
@@ -360,10 +346,10 @@ class MusicBrainzApi {
         const postData = xmlMetadata.toXml();
         do {
             await this.rateLimiter.limit();
-            const response = await got_1.default.post(path, Object.assign({ searchParams: { client: clientId }, headers: {
+            const response = await got_1.default.post(path, Object.assign(Object.assign({}, this.options), { searchParams: { client: clientId }, headers: {
                     authorization: digest,
                     'Content-Type': 'application/xml'
-                }, body: postData, throwHttpErrors: false }, this.options));
+                }, body: postData, throwHttpErrors: false }));
             if (response.statusCode === http_status_codes_1.StatusCodes.UNAUTHORIZED) {
                 // Respond to digest challenge
                 const auth = new digest_auth_1.DigestAuth(this.config.botAccount);
@@ -395,9 +381,9 @@ class MusicBrainzApi {
             csrf_token: this.session.csrf.token,
             remember_me: 1
         };
-        const response = await got_1.default.post('login', Object.assign({ followRedirect: false, searchParams: {
+        const response = await got_1.default.post('login', Object.assign(Object.assign({}, this.options), { followRedirect: false, searchParams: {
                 returnto: redirectUri
-            }, form: formData }, this.options));
+            }, form: formData }));
         const success = response.statusCode === http_status_codes_1.StatusCodes.MOVED_TEMPORARILY && response.headers.location === redirectUri;
         if (success) {
             this.session.loggedIn = true;
@@ -409,9 +395,9 @@ class MusicBrainzApi {
      */
     async logout() {
         const redirectUri = '/success';
-        const response = await got_1.default.get('logout', Object.assign({ followRedirect: false, searchParams: {
+        const response = await got_1.default.get('logout', Object.assign(Object.assign({}, this.options), { followRedirect: false, searchParams: {
                 returnto: redirectUri
-            } }, this.options));
+            } }));
         const success = response.statusCode === http_status_codes_1.StatusCodes.MOVED_TEMPORARILY && response.headers.location === redirectUri;
         if (success && this.session) {
             this.session.loggedIn = true;
@@ -432,7 +418,7 @@ class MusicBrainzApi {
         formData.username = this.config.botAccount.username;
         formData.password = this.config.botAccount.password;
         formData.remember_me = 1;
-        const response = await got_1.default.post(`${entity}/${mbid}/edit`, Object.assign({ form: formData, followRedirect: false }, this.options));
+        const response = await got_1.default.post(`${entity}/${mbid}/edit`, Object.assign(Object.assign({}, this.options), { form: formData, followRedirect: false }));
         if (response.statusCode === http_status_codes_1.StatusCodes.OK)
             throw new Error(`Failed to submit form data`);
         if (response.statusCode === http_status_codes_1.StatusCodes.MOVED_TEMPORARILY)
@@ -531,7 +517,7 @@ class MusicBrainzApi {
         return this.search('url', query);
     }
     async getSession() {
-        const response = await got_1.default.get('login', Object.assign({ followRedirect: false, responseType: 'text' }, this.options));
+        const response = await got_1.default.get('login', Object.assign(Object.assign({}, this.options), { followRedirect: false, responseType: 'text' }));
         return {
             csrf: MusicBrainzApi.fetchCsrf(response.body)
         };

package/lib/musicbrainz.types.d.ts

@@ -220,6 +220,12 @@ export interface ILabel extends IEntity {
 export interface IPlace extends IEntity {
     name: string;
 }
+export interface ISeries extends IEntity {
+    name: string;
+    type: string;
+    disambiguation: string;
+    'type-id': string;
+}
 export interface IUrl extends IEntity {
     id: string;
     resource: string;

package/lib/rate-limiter.d.ts

@@ -3,6 +3,6 @@ export declare class RateLimiter {
     static sleep(ms: number): Promise<void>;
     queue: number[];
     private readonly period;
-    constructor(period: number, maxCalls: number);
+    constructor(maxCalls: number, period: number);
     limit(): Promise<void>;
 }

package/lib/rate-limiter.js

@@ -7,9 +7,10 @@ class RateLimiter {
     static sleep(ms) {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
-    constructor(period, maxCalls) {
+    constructor(maxCalls, period) {
         this.maxCalls = maxCalls;
         this.queue = [];
+        debug(`Rate limiter initialized with max ${maxCalls} calls in ${period} seconds.`);
         this.period = 1000 * period;
     }
     async limit() {
@@ -18,6 +19,7 @@ class RateLimiter {
         while (this.queue.length > 0 && this.queue[0] < t0) {
             this.queue.shift();
         }
+        // debug(`Current rate is  ${this.queue.length} per ${this.period / 1000} sec`);
         if (this.queue.length >= this.maxCalls) {
             const delay = this.queue[0] + this.period - now;
             debug(`Client side rate limiter activated: cool down for ${delay / 1000} s...`);

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "musicbrainz-api",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "MusicBrainz API client for reading and submitting metadata",
-  "main": "lib/musicbrainz-api",
-  "types": "lib/musicbrainz-api",
+  "main": "lib/index",
+  "types": "lib/index",
   "author": {
     "name": "Borewit",
     "url": "https://github.com/Borewit"
@@ -20,7 +20,13 @@
     "web",
     "service",
     "submit",
-    "metabrainz"
+    "metabrainz",
+    "Cover Art Archive",
+    "coverartarchive",
+    "coverartarchive.org",
+    "album art",
+    "covers",
+    "download covers"
   ],
   "license": "MIT",
   "private": false,