musicbrainz-api 0.18.0 → 0.18.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +66 -61
  2. package/lib/musicbrainz-api.d.ts +5 -2
  3. package/lib/musicbrainz-api.js +4 -2
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -14,98 +14,108 @@
14
14
  A MusicBrainz-API-client for reading and submitting metadata
15
15
 
16
16
  ## Features
17
- - Access metadata from MusicBrainz
18
- - Submit metadata
19
- - Smart and adjustable throttling, like MusicBrainz, it allows a bursts of requests
20
- - Build in TypeScript definitions
17
+ - **Access Metadata**: Retrieve detailed metadata from the [MusicBrainz database](https://musicbrainz.org/).
18
+ - **Submit metadata**: Easily submit new metadata to [MusicBrainz](https://musicbrainz.org/).
19
+ - **Smart throttling**: Implements intelligent throttling, allowing bursts of requests while adhering to [MusicBrainz rate limits](https://musicbrainz.org/doc/MusicBrainz_API/Rate_Limiting).
20
+ - **TypeScript Definitions**: Fully typed with built-in [TypeScript](https://www.typescriptlang.org/) definitions for a seamless development experience.
21
21
 
22
22
  ## Compatibility
23
23
 
24
- Module: [Pure ECMAScript Module (ESM)](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
24
+ Module: version 8 migrated from [CommonJS](https://en.wikipedia.org/wiki/CommonJS) to [pure ECMAScript Module (ESM)](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
25
25
  The distributed JavaScript codebase is compliant with the [ECMAScript 2020 (11th Edition)](https://en.wikipedia.org/wiki/ECMAScript_version_history#11th_Edition_%E2%80%93_ECMAScript_2020) standard.
26
26
 
27
- This module requires a [Node.js ≥ 20](https://nodejs.org/en/about/previous-releases) engine.
27
+ ### Requirements
28
+ - Node.js: Requires [Node.js version 16](https://nodejs.org/en/about/previous-releases) or higher.
29
+ - Browser: Can be used in browser environments when bundled with a module bundler (not actively tested).
28
30
 
29
31
  > [!NOTE]
30
32
  > We are looking into making this package usable in the browser as well.
31
33
 
32
- ## Sponsor
33
- If you appreciate my work and want to support the development of open-source projects like [musicbrainz-api](https://github.com/Borewit/musicbrainz-api), [music-metadata](https://github.com/Borewit/music-metadata), [file-type](https://github.com/sindresorhus/file-type), [listFix()](https://github.com/Borewit/listFix), [lizzy](https://github.com/Borewit/lizzy), [strtok3](https://github.com/Borewit/strtok3), or [tokenizer-s3](https://github.com/Borewit/tokenizer-s3), please consider becoming a sponsor or making a small contribution.
34
- Your support helps sustain ongoing development and improvements.
35
- [Become a sponsor to Borewit](https://github.com/sponsors/Borewit)
34
+ ## Support the Project
35
+ If you find this project useful and would like to support its development, consider sponsoring or contributing:
36
+
37
+ - [Become a sponsor to Borewit](https://github.com/sponsors/Borewit)
38
+
39
+ - Buy me a coffee:
40
+
41
+ <a href="https://www.buymeacoffee.com/borewit" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy me A coffee" height="41" width="174"></a>
36
42
 
37
- This package is currently only developed for the use in a [node.js environment](http://nodejs.org/).
38
- We are looking into making this package usable in the browser as well.
43
+ ## Getting Started
39
44
 
40
- ## Before using this library
45
+ ### Identifying Your Application
41
46
 
42
- MusicBrainz asks that you to [identify your application](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#User%20Data) by filling in the ['User-Agent' Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent).
43
- By passing `appName`, `appVersion`, `appMail` musicbrainz-api takes care of that.
47
+ MusicBrainz requires all API clients to [identify their application](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#User%20Data).
48
+ Ensure you set the User-Agent header by providing `appName`, `appVersion`, and `appContactInfo` when configuring the client.
49
+ This library will automatically handle this for you.
44
50
 
45
- ## Submitting metadata
51
+ ### Submitting metadata
46
52
 
47
53
  If you plan to use this module for submitting metadata, please ensure you comply with [the MusicBrainz Code of conduct/Bots](https://wiki.musicbrainz.org/Code_of_Conduct/Bots).
48
54
 
49
- ## Example
55
+ ## Example Usage
56
+
57
+ ### Importing the Library
50
58
 
51
- Example, how to import 'musicbrainz-api:
52
59
  ```js
53
- import {MusicBrainzApi} from 'musicbrainz-api';
60
+ import { MusicBrainzApi } from 'musicbrainz-api';
54
61
 
55
62
  const mbApi = new MusicBrainzApi({
56
- appName: 'my-app',
57
- appVersion: '0.1.0',
58
- appContactInfo: 'user@mail.org'
63
+ appName: 'my-app',
64
+ appVersion: '0.1.0',
65
+ appContactInfo: 'user@mail.org',
59
66
  });
60
67
  ```
61
68
 
62
- The following configuration settings can be passed
63
- ```js
64
- import {MusicBrainzApi} from 'musicbrainz-api';
69
+ ### Configuration Options
65
70
 
71
+ ```js
66
72
  const config = {
67
- // MusicBrainz bot account username & password (optional)
68
- botAccount: {
69
- username: 'myUserName_bot',
70
- password: 'myPassword'
71
- },
72
-
73
- // API base URL, default: 'https://musicbrainz.org' (optional)
74
- baseUrl: 'https://musicbrainz.org',
75
-
76
- appName: 'my-app',
77
- appVersion: '0.1.0',
78
-
79
- // Optional, default: no proxy server
80
- proxy: {
81
- host: 'localhost',
82
- port: 8888
83
- },
73
+ // Optional: MusicBrainz bot account credentials
74
+ botAccount: {
75
+ username: 'myUserName_bot',
76
+ password: 'myPassword',
77
+ },
78
+
79
+ // Optional: API base URL (default: 'https://musicbrainz.org')
80
+ baseUrl: 'https://musicbrainz.org',
81
+
82
+ // Required: Application details
83
+ appName: 'my-app',
84
+ appVersion: '0.1.0',
85
+ appMail: 'user@mail.org',
86
+
87
+ // Optional: Proxy settings (default: no proxy server)
88
+ proxy: {
89
+ host: 'localhost',
90
+ port: 8888,
91
+ },
92
+
93
+ // Optional: Disable rate limiting (default: false)
94
+ disableRateLimiting: false,
95
+ };
96
+
97
+ const mbApi = new MusicBrainzApi(config);
98
+ ```
84
99
 
85
- // Your e-mail address, required for submitting ISRCs
86
- appMail: string,
100
+ ## Accessing MusicBrainz Data
87
101
 
88
- // Helpful if you have your own MusicBrainz server, default: false (optional)
89
- disableRateLimiting: false,
90
- }
91
-
92
- const mbApi = new MusicbrainzApi(config);
93
- ```
102
+ The MusicBrainz API allows you to look up various entities. Here’s how to use the lookup function:
94
103
 
95
104
  ## Lookup MusicBrainz Entities
96
105
 
97
106
  MusicBrainz API documentation: [XML Web Service/Version 2 Lookups](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#Lookups)
98
107
 
99
- ### Generic lookup function
108
+ ### Lookup Function
109
+
110
+ ```js
111
+ const artist = await mbApi.lookup('artist', 'ab2528d9-719f-4261-8098-21849222a0f2');
112
+ ```
100
113
 
101
114
  Arguments:
102
115
  - entity: `'area'` | `'artist'` | `'collection'` | `'instrument'` | `'label'` | `'place'` | `'release'` | `'release-group'` | `'recording'` | `'series'` | `'work'` | `'url'` | `'event'`
103
116
  - MBID [(MusicBrainz identifier)](https://wiki.musicbrainz.org/MusicBrainz_Identifier)
104
117
  - query
105
118
 
106
- ```js
107
- const artist = await mbApi.lookup('artist', 'ab2528d9-719f-4261-8098-21849222a0f2');
108
- ```
109
119
 
110
120
  | Query argument | Query value |
111
121
  |-----------------------|-----------------|
@@ -404,9 +414,9 @@ await mbApi.addSpotifyIdToRecording(recording, '2AMysGXOe0zzZJMtH3Nizb');
404
414
 
405
415
  ## Cover Art Archive API
406
416
 
407
- Implementation of the [Cover Art Archive API](https://musicbrainz.org/doc/Cover_Art_Archive/API).
417
+ This library also supports the [Cover Art Archive API](https://musicbrainz.org/doc/Cover_Art_Archive/API).
408
418
 
409
- ### Release Cover Art
419
+ ### Fetch Release Cover Art
410
420
  ```js
411
421
  import { CoverArtArchiveApi } from 'musicbrainz-api';
412
422
 
@@ -453,8 +463,3 @@ async function getCoverArt(releaseGroupMbid, coverType = '') {
453
463
 
454
464
  ```
455
465
 
456
-
457
- ## Compatibility
458
-
459
- The JavaScript in runtime is compliant with [ECMAScript 2017 (ES8)](https://en.wikipedia.org/wiki/ECMAScript#8th_Edition_-_ECMAScript_2017).
460
- Requires [Node.js®](https://nodejs.org/) version 6 or higher.
package/lib/musicbrainz-api.d.ts CHANGED
@@ -50,7 +50,7 @@ export interface IMusicBrainzConfig {
50
50
  username?: string;
51
51
  password?: string;
52
52
  };
53
- baseUrl: string;
53
+ baseUrl?: string;
54
54
  appName?: string;
55
55
  appVersion?: string;
56
56
  /**
@@ -63,6 +63,9 @@ export interface IMusicBrainzConfig {
63
63
  appContactInfo?: string;
64
64
  disableRateLimiting?: boolean;
65
65
  }
66
+ interface IInternalConfig extends IMusicBrainzConfig {
67
+ baseUrl: string;
68
+ }
66
69
  export interface ICsrfSession {
67
70
  sessionKey: string;
68
71
  token: string;
@@ -72,7 +75,7 @@ export interface ISessionInformation {
72
75
  loggedIn?: boolean;
73
76
  }
74
77
  export declare class MusicBrainzApi {
75
- readonly config: IMusicBrainzConfig;
78
+ readonly config: IInternalConfig;
76
79
  private rateLimiter;
77
80
  private httpClient;
78
81
  private session?;
package/lib/musicbrainz-api.js CHANGED
@@ -30,9 +30,11 @@ export class MusicBrainzApi {
30
30
  }
31
31
  constructor(_config) {
32
32
  this.config = {
33
- baseUrl: 'https://musicbrainz.org'
33
+ ...{
34
+ baseUrl: 'https://musicbrainz.org'
35
+ },
36
+ ..._config
34
37
  };
35
- Object.assign(this.config, _config);
36
38
  this.httpClient = new HttpClient({
37
39
  baseUrl: this.config.baseUrl,
38
40
  timeout: 20 * 1000,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "musicbrainz-api",
3
- "version": "0.18.0",
3
+ "version": "0.18.2",
4
4
  "description": "MusicBrainz API client for reading and submitting metadata",
5
5
  "exports": "./lib/index.js",
6
6
  "types": "lib/index.d.ts",