musicbrainz-api 0.7.0 → 0.7.1

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,55 @@ 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.getEntity('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.getArea({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.getArtist({query: 'ab2528d9-719f-4261-8098-21849222a0f2'});
+```
+
+or use the browse API:
+
+```js
+const artist = await mbApi.getArtist({artist: 'ab2528d9-719f-4261-8098-21849222a0f2'});
 ```
 
 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
+```js
 const artist = await mbApi.getArtist('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.getRecording({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.getRelease({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.getReleaseGroup({query: '19099ea5-3600-4154-b482-2ec68815883e'});
 ```
 
 ### Lookup work
-```javascript
-const work = await mbApi.getWork('b2aa02f4-6c95-43be-a426-aedb9f9a3805');
+```js
+const work = await mbApi.getWork({query: 'b2aa02f4-6c95-43be-a426-aedb9f9a3805'});
 ```
 
 ## Search (query)
@@ -164,28 +170,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 +204,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 +226,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,7 +245,7 @@ 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';
@@ -257,7 +263,7 @@ await mbApi.addIsrc(recording, isrc_Formidable);
 
 ### Submit recording URL
 
-```javascript
+```js
 const recording = await mbApi.getRecording('16afa384-174e-435e-bfa3-5591accda31c');
 
 const succeed = await mbApi.login();
@@ -270,7 +276,7 @@ await mbApi.addUrlToRecording(recording, {
 ```
 
 Actually a Spotify-track-ID can be submitted easier: 
-```javascript
+```js
 const recording = await mbApi.getRecording('16afa384-174e-435e-bfa3-5591accda31c');
 
 const succeed = await mbApi.login();

package/lib/musicbrainz-api.d.ts

@@ -135,10 +135,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 +146,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

@@ -332,14 +332,14 @@ 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);
         }
-        return this.restGet('/' + entity + '/', { query, offset, limit });
+        return this.restGet('/' + entity + '/', urlQuery);
     }
     // -----------------------------------------------------------------------------------------------------------------
     // Helper functions
@@ -358,20 +358,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));

package/lib/musicbrainz.types.d.ts

@@ -1,4 +1,5 @@
 import DateTimeFormat = Intl.DateTimeFormat;
+import { IFormData, Includes } from './musicbrainz-api';
 export interface IPeriod {
     'begin': string;
     'ended': boolean;
@@ -249,5 +250,130 @@ export interface ISearchQuery extends IPagination {
     /**
      * Lucene search query, this is mandatory
      */
-    query: string;
+    query?: string | IFormData;
+    inc?: Includes[];
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Browse
+ * /ws/2/area              collection
+ */
+export interface ILinkedEntitiesArea {
+    collection?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Browse
+ * /ws/2/artist            area, collection, recording, release, release-group, work
+ */
+export interface ILinkedEntitiesArtist {
+    area?: string;
+    collection?: string;
+    recording?: string;
+    release?: string;
+    'release-group'?: string;
+    work?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Browse
+ * /ws/2/collection        area, artist, editor, event, label, place, recording, release, release-group, work
+ */
+export interface ILinkedEntitiesCollection {
+    area?: string;
+    artist?: string;
+    editor?: string;
+    event?: string;
+    label?: string;
+    place?: string;
+    recording?: string;
+    release?: string;
+    'release-group'?: string;
+    work?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Subqueries
+ * /ws/2/event             area, artist, collection, place
+ */
+export interface ILinkedEntitiesEvent {
+    area?: string;
+    artist?: string;
+    collection?: string;
+    place?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Subqueries
+ * /ws/2/instrument        collection
+ */
+export interface ILinkedEntitiesInstrument {
+    collection?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Subqueries
+ * /ws/2/label             area, collection, release
+ */
+export interface ILinkedEntitiesLabel {
+    area?: string;
+    collection?: string;
+    release?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Subqueries
+ * /ws/2/place             area, collection
+ */
+export interface IBrowseArgumentPlace {
+    area?: string;
+    collection?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Subqueries
+ * /ws/2/recording         artist, collection, release, work
+ */
+export interface ILinkedEntitiesRecording {
+    area?: string;
+    collection?: string;
+    release?: string;
+    work?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Subqueries
+ * /ws/2/release           area, artist, collection, label, track, track_artist, recording, release-group
+ */
+export interface ILinkedEntitiesRelease {
+    area?: string;
+    artist?: string;
+    collection?: string;
+    label?: string;
+    track?: string;
+    track_artist?: string;
+    recording?: string;
+    'release-group'?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Subqueries
+ * /ws/2/release-group     artist, collection, release
+ */
+export interface ILinkedEntitiesReleaseGroup {
+    artist?: string;
+    collection?: string;
+    release?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Subqueries
+ * /ws/2/series            collection
+ */
+export interface ILinkedEntitiesSeries {
+    collection?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Browse
+ * /ws/2/work              artist, collection
+ */
+export interface ILinkedEntitiesWork {
+    artist?: string;
+    collection?: string;
+}
+/**
+ * https://musicbrainz.org/doc/MusicBrainz_API#Browse
+ * /ws/2/url               resource
+ */
+export interface ILinkedEntitiesUrl {
+    resource?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musicbrainz-api",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "MusicBrainz API client for reading and submitting metadata",
   "main": "lib/musicbrainz-api",
   "types": "lib/musicbrainz-api",