musicbrainz-api 0.7.0 → 0.8.0

package/README.md

@@ -32,7 +32,7 @@ If you plan to use this module for submitting metadata, please ensure you comply
 
 Import the module
 JavaScript example, how to import 'musicbrainz-api:
-```javascript
+```js
 const MusicBrainzApi = require('musicbrainz-api').MusicBrainzApi;
 
 const mbApi = new MusicBrainzApi({
@@ -43,7 +43,7 @@ const mbApi = new MusicBrainzApi({
 ```
 
 In TypeScript you it would look like this:
-```javascript
+```js
 import {MusicBrainzApi} from 'musicbrainz-api';
 
 const mbApi = new MusicBrainzApi({
@@ -54,7 +54,7 @@ const mbApi = new MusicBrainzApi({
 ```
 
 The following configuration settings can be passed 
-```javascript
+```js
 import {MusicBrainzApi} from '../src/musicbrainz-api';
 
 const config = {
@@ -93,49 +93,76 @@ Arguments:
 *   entity: `'artist'` | `'label'` | `'recording'` | `'release'` | `'release-group'` | `'work'` | `'area'` | `'url'`
 *   MBID [(MusicBrainz identifier)](https://wiki.musicbrainz.org/MusicBrainz_Identifier)
 
-```javascript
-const artist = await mbApi.getEntity('artist', 'ab2528d9-719f-4261-8098-21849222a0f2');
+```js
+const artist = await mbApi.lookupEntity('artist', {query: 'ab2528d9-719f-4261-8098-21849222a0f2'});
 ```
 
 ### Lookup area
 
-```javascript
-const area = await mbApi.getArea('ab2528d9-719f-4261-8098-21849222a0f2');
+```js
+const area = await mbApi.lookupArea({query: 'ab2528d9-719f-4261-8098-21849222a0f2'});
 ```
 
 ### Lookup artist
 
 Lookup an `artist` and include their `releases`, `release-groups` and `aliases`
 
-```javascript
-const artist = await mbApi.getArtist('ab2528d9-719f-4261-8098-21849222a0f2');
+```js
+const artist = await mbApi.lookupArtist({query: 'ab2528d9-719f-4261-8098-21849222a0f2'});
+```
+
+### Lookup instrument
+
+Lookup an instrument
+
+```js
+const artist = await mbApi.lookupInstrument({query: 'b3eac5f9-7859-4416-ac39-7154e2e8d348'});
+```
+
+### Lookup label
+
+Lookup a label
+
+```js
+const artist = await mbApi.lookupInstrument({query: '25dda9f9-f069-4898-82f0-59330a106c7f'});
+```
+
+### Lookup place
+
+```js
+const artist = await mbApi.lookupPlace({query: 'e6cfb74d-d69b-44c3-b890-1b3f509816e4'});
 ```
 
 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:
-```javascript
-const artist = await mbApi.getArtist('ab2528d9-719f-4261-8098-21849222a0f2', ['releases', 'recordings', 'url-rels']);
+```js
+const artist = await mbApi.lookupArtist('ab2528d9-719f-4261-8098-21849222a0f2', ['releases', 'recordings', 'url-rels']);
 ```
 
 ### Lookup recording
 
 The second argument can be used to pass [subqueries](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#Subqueries):
-```javascript
-const artist = await mbApi.getRecording('16afa384-174e-435e-bfa3-5591accda31c', ['artists', 'url-rels']);
+```js
+const artist = await mbApi.lookupRecording({query: '16afa384-174e-435e-bfa3-5591accda31c'}, ['artists', 'url-rels']);
 ```
 
 ### Lookup release
-```javascript
-const release = await mbApi.getRelease('976e0677-a480-4a5e-a177-6a86c1900bbf', ['artists', 'url-rels']);
+```js
+const release = await mbApi.lookupRelease({query: '976e0677-a480-4a5e-a177-6a86c1900bbf'}, ['artists', 'url-rels']);
 ```
 
 ### Lookup release-group
-```javascript
-const releaseGroup = await mbApi.getReleaseGroup('19099ea5-3600-4154-b482-2ec68815883e');
+```js
+const releaseGroup = await mbApi.lookupReleaseGroup({query: '19099ea5-3600-4154-b482-2ec68815883e'});
 ```
 
 ### Lookup work
-```javascript
-const work = await mbApi.getWork('b2aa02f4-6c95-43be-a426-aedb9f9a3805');
+```js
+const work = await mbApi.lookupWork({query: 'b2aa02f4-6c95-43be-a426-aedb9f9a3805'});
+```
+
+### Lookup URL
+```js
+const url = await mbApi.lookupUrl({query: 'c69556a6-7ded-4c54-809c-afb45a1abe7d'});
 ```
 
 ## Search (query)
@@ -164,28 +191,28 @@ Arguments:
     *   `limit.query`: optional, an integer value defining how many entries should be returned. Only values between 1 and 100 (both inclusive) are allowed. If not given, this defaults to 25.
 
 For example, to find any recordings of _'We Will Rock You'_ by Queen:
-```javascript
+```js
 const query = 'query="We Will Rock You" AND arid:0383dadf-2a4e-4d10-a46a-e9e041da8eb3';
 const result = await mbApi.query<mb.IReleaseGroupList>('release-group', {query});
 ```
 
 ##### Example: search Île-de-France
 
-```javascript
+```js
  mbApi.search('area', 'Île-de-France');
 ````
 
 ##### Example: search release by barcode
 
 Search a release with the barcode 602537479870:
-```javascript
- mbApi.search('release', {barcode: 602537479870});
+```js
+ mbApi.search('release', {query: {barcode: 602537479870}});
 ````
 
 ##### Example: search by object
 
 Same as previous example, but automatically serialize parameters to search query
-```javascript
+```js
  mbApi.search('release', 'barcode: 602537479870');
 ````
 
@@ -198,17 +225,17 @@ searchReleaseGroup(query: string | IFormData, offset?: number, limit?: number):
 ```
 
 Search artist:
-```javascript
-const result = await mbApi.searchArtist('Stromae');
+```js
+const result = await mbApi.searchArtist({query: 'Stromae'});
 ```
 
 Search release-group:
-```javascript
-const result = await mbApi.searchReleaseGroup('Racine carrée');
+```js
+const result = await mbApi.searchReleaseGroup({query: 'Racine carrée'});
 ```
 
 Search a combination of a release-group and an artist.
-```javascript
+```js
 const result = await mbApi.searchReleaseGroup({artist: 'Racine carrée', releasegroup: 'Stromae'});
 ```
 
@@ -220,7 +247,7 @@ const result = await mbApi.searchReleaseGroup({artist: 'Racine carrée', release
 
 Using the [XML ISRC submission](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#ISRC_submission) API.
 
-```javascript
+```js
 const mbid_Formidable = '16afa384-174e-435e-bfa3-5591accda31c';
 const isrc_Formidable = 'BET671300161';
 
@@ -239,13 +266,13 @@ For all of the following function you need to use a dedicated bot account.
 <img width="150" src="http://www.clker.com/cliparts/i/w/L/q/u/1/work-in-progress.svg"/>
 Use with caution, and only on a test server, it may clear existing metadata as side effect.
       
-```javascript
+```js
 
 const mbid_Formidable = '16afa384-174e-435e-bfa3-5591accda31c';
 const isrc_Formidable = 'BET671300161';
 
     
-const recording = await mbApi.getRecording(mbid_Formidable);
+const recording = await mbApi.lookupRecording(mbid_Formidable);
 
 // Authentication the http-session against MusicBrainz (as defined in config.baseUrl)
 const succeed = await mbApi.login();
@@ -257,8 +284,8 @@ await mbApi.addIsrc(recording, isrc_Formidable);
 
 ### Submit recording URL
 
-```javascript
-const recording = await mbApi.getRecording('16afa384-174e-435e-bfa3-5591accda31c');
+```js
+const recording = await mbApi.lookupRecording('16afa384-174e-435e-bfa3-5591accda31c');
 
 const succeed = await mbApi.login();
 assert.isTrue(succeed, 'Login successful');
@@ -270,8 +297,8 @@ await mbApi.addUrlToRecording(recording, {
 ```
 
 Actually a Spotify-track-ID can be submitted easier: 
-```javascript
-const recording = await mbApi.getRecording('16afa384-174e-435e-bfa3-5591accda31c');
+```js
+const recording = await mbApi.lookupRecording('16afa384-174e-435e-bfa3-5591accda31c');
 
 const succeed = await mbApi.login();
 assert.isTrue(succeed, 'Login successful');

package/lib/digest-auth.js

@@ -23,12 +23,7 @@ class DigestAuth {
      */
     static ha1Compute(algorithm, user, realm, pass, nonce, cnonce) {
         const ha1 = md5(user + ':' + realm + ':' + pass); // lgtm [js/insufficient-password-hash]
-        if (algorithm && algorithm.toLowerCase() === 'md5-sess') {
-            return md5(ha1 + ':' + nonce + ':' + cnonce);
-        }
-        else {
-            return ha1;
-        }
+        return algorithm && algorithm.toLowerCase() === 'md5-sess' ? md5(ha1 + ':' + nonce + ':' + cnonce) : ha1;
     }
     digest(method, path, authHeader) {
         // TODO: More complete implementation of RFC 2617.

package/lib/musicbrainz-api.d.ts

@@ -58,48 +58,66 @@ export declare class MusicBrainzApi {
      * @param mbid
      * @param inc
      */
-    getEntity<T>(entity: mb.EntityType, mbid: string, inc?: Includes[]): Promise<T>;
+    lookupEntity<T>(entity: mb.EntityType, mbid: string, inc?: Includes[]): Promise<T>;
     /**
      * Lookup area
      * @param areaId Area MBID
      * @param inc Sub-queries
      */
-    getArea(areaId: string, inc?: Includes[]): Promise<mb.IArea>;
+    lookupArea(areaId: string, inc?: Includes[]): Promise<mb.IArea>;
     /**
      * Lookup artist
      * @param artistId Artist MBID
      * @param inc Sub-queries
      */
-    getArtist(artistId: string, inc?: Includes[]): Promise<mb.IArtist>;
+    lookupArtist(artistId: string, inc?: Includes[]): Promise<mb.IArtist>;
+    /**
+     * Lookup instrument
+     * @param artistId Instrument MBID
+     * @param inc Sub-queries
+     */
+    lookupInstrument(instrumentId: string, inc?: Includes[]): Promise<mb.IInstrument>;
+    /**
+     * Lookup label
+     * @param labelId Area MBID
+     * @param inc Sub-queries
+     */
+    lookupLabel(labelId: string, inc?: Includes[]): Promise<mb.ILabel>;
+    /**
+     * Lookup place
+     * @param placeId Area MBID
+     * @param inc Sub-queries
+     */
+    lookupPlace(placeId: string, inc?: Includes[]): Promise<mb.IPlace>;
     /**
      * Lookup release
      * @param releaseId Release MBID
      * @param inc Include: artist-credits, labels, recordings, release-groups, media, discids, isrcs (with recordings)
      * ToDo: ['recordings', 'artists', 'artist-credits', 'isrcs', 'url-rels', 'release-groups']
      */
-    getRelease(releaseId: string, inc?: Includes[]): Promise<mb.IRelease>;
+    lookupRelease(releaseId: string, inc?: Includes[]): Promise<mb.IRelease>;
     /**
      * Lookup release-group
      * @param releaseGroupId Release-group MBID
      * @param inc Include: ToDo
      */
-    getReleaseGroup(releaseGroupId: string, inc?: Includes[]): Promise<mb.IReleaseGroup>;
+    lookupReleaseGroup(releaseGroupId: string, inc?: Includes[]): Promise<mb.IReleaseGroup>;
     /**
-     * Lookup work
-     * @param workId Work MBID
+     * Lookup recording
+     * @param recordingId Label MBID
+     * @param inc Include: artist-credits, isrcs
      */
-    getWork(workId: string): Promise<mb.IWork>;
+    lookupRecording(recordingId: string, inc?: Includes[]): Promise<mb.IRecording>;
     /**
-     * Lookup label
-     * @param labelId Label MBID
+     * Lookup work
+     * @param workId Work MBID
      */
-    getLabel(labelId: string): Promise<mb.ILabel>;
+    lookupWork(workId: string): Promise<mb.IWork>;
     /**
-     * Lookup recording
-     * @param recordingId Label MBID
-     * @param inc Include: artist-credits, isrcs
+     * Lookup URL
+     * @param urlId URL MBID
      */
-    getRecording(recordingId: string, inc?: Includes[]): Promise<mb.IRecording>;
+    lookupUrl(urlId: string): Promise<mb.IUrl>;
     postRecording(xmlMetadata: XmlMetadata): Promise<void>;
     post(entity: mb.EntityType, xmlMetadata: XmlMetadata): Promise<void>;
     login(): Promise<boolean>;
@@ -135,10 +153,9 @@ export declare class MusicBrainzApi {
      * Search an entity using a search query
      * @param query e.g.: '" artist: Madonna, track: Like a virgin"' or object with search terms: {artist: Madonna}
      * @param entity e.g. 'recording'
-     * @param offset
-     * @param limit
+     * @param query Arguments
      */
-    search<T extends mb.ISearchResult>(entity: mb.EntityType, query: string | IFormData, offset?: number, limit?: number): Promise<T>;
+    search<T extends mb.ISearchResult>(entity: mb.EntityType, query: mb.ISearchQuery): Promise<T>;
     /**
      * Add Spotify-ID to MusicBrainz recording.
      * This function will automatically lookup the recording title, which is required to submit the recording URL
@@ -147,11 +164,11 @@ export declare class MusicBrainzApi {
      * @param editNote Comment to add.
      */
     addSpotifyIdToRecording(recording: mb.IRecording, spotifyId: string, editNote: string): Promise<void>;
-    searchArtist(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IArtistList>;
-    searchRelease(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IReleaseList>;
-    searchReleaseGroup(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IReleaseGroupList>;
-    searchArea(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IAreaList>;
-    searchUrl(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IUrlList>;
+    searchArea(query: mb.ISearchQuery & mb.ILinkedEntitiesArea): Promise<mb.IAreaList>;
+    searchArtist(query: mb.ISearchQuery & mb.ILinkedEntitiesArtist): Promise<mb.IArtistList>;
+    searchRelease(query: mb.ISearchQuery & mb.ILinkedEntitiesRelease): Promise<mb.IReleaseList>;
+    searchReleaseGroup(query: mb.ISearchQuery & mb.ILinkedEntitiesReleaseGroup): Promise<mb.IReleaseGroupList>;
+    searchUrl(query: mb.ISearchQuery & mb.ILinkedEntitiesUrl): Promise<mb.IUrlList>;
     private getSession;
 }
 export declare function makeAndQueryString(keyValuePairs: IFormData): string;

package/lib/musicbrainz-api.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[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];
@@ -134,7 +138,7 @@ class MusicBrainzApi {
      * @param mbid
      * @param inc
      */
-    getEntity(entity, mbid, inc = []) {
+    lookupEntity(entity, mbid, inc = []) {
         return this.restGet(`/${entity}/${mbid}`, { inc: inc.join(' ') });
     }
     /**
@@ -142,16 +146,40 @@ class MusicBrainzApi {
      * @param areaId Area MBID
      * @param inc Sub-queries
      */
-    getArea(areaId, inc = []) {
-        return this.getEntity('area', areaId, inc);
+    lookupArea(areaId, inc = []) {
+        return this.lookupEntity('area', areaId, inc);
     }
     /**
      * Lookup artist
      * @param artistId Artist MBID
      * @param inc Sub-queries
      */
-    getArtist(artistId, inc = []) {
-        return this.getEntity('artist', artistId, inc);
+    lookupArtist(artistId, inc = []) {
+        return this.lookupEntity('artist', artistId, inc);
+    }
+    /**
+     * Lookup instrument
+     * @param artistId Instrument MBID
+     * @param inc Sub-queries
+     */
+    lookupInstrument(instrumentId, inc = []) {
+        return this.lookupEntity('instrument', instrumentId, inc);
+    }
+    /**
+     * Lookup label
+     * @param labelId Area MBID
+     * @param inc Sub-queries
+     */
+    lookupLabel(labelId, inc = []) {
+        return this.lookupEntity('label', labelId, inc);
+    }
+    /**
+     * Lookup place
+     * @param placeId Area MBID
+     * @param inc Sub-queries
+     */
+    lookupPlace(placeId, inc = []) {
+        return this.lookupEntity('place', placeId, inc);
     }
     /**
      * Lookup release
@@ -159,38 +187,38 @@ class MusicBrainzApi {
      * @param inc Include: artist-credits, labels, recordings, release-groups, media, discids, isrcs (with recordings)
      * ToDo: ['recordings', 'artists', 'artist-credits', 'isrcs', 'url-rels', 'release-groups']
      */
-    getRelease(releaseId, inc = []) {
-        return this.getEntity('release', releaseId, inc);
+    lookupRelease(releaseId, inc = []) {
+        return this.lookupEntity('release', releaseId, inc);
     }
     /**
      * Lookup release-group
      * @param releaseGroupId Release-group MBID
      * @param inc Include: ToDo
      */
-    getReleaseGroup(releaseGroupId, inc = []) {
-        return this.getEntity('release-group', releaseGroupId, inc);
+    lookupReleaseGroup(releaseGroupId, inc = []) {
+        return this.lookupEntity('release-group', releaseGroupId, inc);
     }
     /**
-     * Lookup work
-     * @param workId Work MBID
+     * Lookup recording
+     * @param recordingId Label MBID
+     * @param inc Include: artist-credits, isrcs
      */
-    getWork(workId) {
-        return this.getEntity('work', workId);
+    lookupRecording(recordingId, inc = []) {
+        return this.lookupEntity('recording', recordingId, inc);
     }
     /**
-     * Lookup label
-     * @param labelId Label MBID
+     * Lookup work
+     * @param workId Work MBID
      */
-    getLabel(labelId) {
-        return this.getEntity('label', labelId);
+    lookupWork(workId) {
+        return this.lookupEntity('work', workId);
     }
     /**
-     * Lookup recording
-     * @param recordingId Label MBID
-     * @param inc Include: artist-credits, isrcs
+     * Lookup URL
+     * @param urlId URL MBID
      */
-    getRecording(recordingId, inc = []) {
-        return this.getEntity('recording', recordingId, inc);
+    lookupUrl(urlId) {
+        return this.lookupEntity('url', urlId);
     }
     async postRecording(xmlMetadata) {
         return this.post('recording', xmlMetadata);
@@ -332,14 +360,17 @@ class MusicBrainzApi {
      * Search an entity using a search query
      * @param query e.g.: '" artist: Madonna, track: Like a virgin"' or object with search terms: {artist: Madonna}
      * @param entity e.g. 'recording'
-     * @param offset
-     * @param limit
+     * @param query Arguments
      */
-    search(entity, query, offset, limit) {
-        if (typeof query === 'object') {
-            query = makeAndQueryString(query);
+    search(entity, query) {
+        const urlQuery = Object.assign({}, query);
+        if (typeof query.query === 'object') {
+            urlQuery.query = makeAndQueryString(query.query);
+        }
+        if (Array.isArray(query.inc)) {
+            urlQuery.inc = urlQuery.inc.join(' ');
         }
-        return this.restGet('/' + entity + '/', { query, offset, limit });
+        return this.restGet('/' + entity + '/', urlQuery);
     }
     // -----------------------------------------------------------------------------------------------------------------
     // Helper functions
@@ -358,20 +389,20 @@ class MusicBrainzApi {
             text: 'https://open.spotify.com/track/' + spotifyId
         }, editNote);
     }
-    searchArtist(query, offset, limit) {
-        return this.search('artist', query, offset, limit);
+    searchArea(query) {
+        return this.search('area', query);
     }
-    searchRelease(query, offset, limit) {
-        return this.search('release', query, offset, limit);
+    searchArtist(query) {
+        return this.search('artist', query);
     }
-    searchReleaseGroup(query, offset, limit) {
-        return this.search('release-group', query, offset, limit);
+    searchRelease(query) {
+        return this.search('release', query);
     }
-    searchArea(query, offset, limit) {
-        return this.search('area', query, offset, limit);
+    searchReleaseGroup(query) {
+        return this.search('release-group', query);
     }
-    searchUrl(query, offset, limit) {
-        return this.search('url', query, offset, limit);
+    searchUrl(query) {
+        return this.search('url', query);
     }
     async getSession(url) {
         const response = await got_1.default.get('login', Object.assign({ followRedirect: false, responseType: 'text' }, this.options));