musicbrainz-api 0.21.0 → 0.23.0

package/lib/musicbrainz-api-node.js

@@ -1,71 +0,0 @@
-import { StatusCodes as HttpStatus } from 'http-status-codes';
-import Debug from 'debug';
-export { XmlMetadata } from './xml/xml-metadata.js';
-export { XmlIsrc } from './xml/xml-isrc.js';
-export { XmlIsrcList } from './xml/xml-isrc-list.js';
-export { XmlRecording } from './xml/xml-recording.js';
-import { HttpClientNode } from "./http-client-node.js";
-import { MusicBrainzApi as MusicBrainzApiDefault } from "./musicbrainz-api.js";
-export * from './musicbrainz.types.js';
-export * from './http-client.js';
-/*
- * https://musicbrainz.org/doc/Development/XML_Web_Service/Version_2#Subqueries
- */
-const debug = Debug('musicbrainz-api-node');
-export class MusicBrainzApi extends MusicBrainzApiDefault {
-    initHttpClient() {
-        return new HttpClientNode({
-            baseUrl: this.config.baseUrl,
-            timeout: 20 * 1000,
-            userAgent: `${this.config.appName}/${this.config.appVersion} ( ${this.config.appContactInfo} )`
-        });
-    }
-    async login() {
-        if (!this.config.botAccount?.username)
-            throw new Error('bot username should be set');
-        if (!this.config.botAccount?.password)
-            throw new Error('bot password should be set');
-        if (this.session?.loggedIn) {
-            const cookies = await this.httpClient.getCookies();
-            return cookies.indexOf('musicbrainz_server_session') !== -1;
-        }
-        this.session = await this.getSession();
-        const redirectUri = '/success';
-        const formData = {
-            username: this.config.botAccount.username,
-            password: this.config.botAccount.password,
-            csrf_session_key: this.session.csrf.sessionKey,
-            csrf_token: this.session.csrf.token,
-            remember_me: '1'
-        };
-        const response = await this.httpClient.postForm('login', formData, {
-            query: {
-                returnto: redirectUri
-            },
-            followRedirects: false
-        });
-        const success = response.status === HttpStatus.MOVED_TEMPORARILY && response.headers.get('location') === redirectUri;
-        if (success) {
-            this.session.loggedIn = true;
-        }
-        return success;
-    }
-    /**
-     * Logout
-     */
-    async logout() {
-        const redirectUri = '/success';
-        const response = await this.httpClient.post('logout', {
-            followRedirects: false,
-            query: {
-                returnto: redirectUri
-            }
-        });
-        const success = response.status === HttpStatus.MOVED_TEMPORARILY && response.headers.get('location') === redirectUri;
-        if (success && this.session) {
-            this.session.loggedIn = true;
-        }
-        return success;
-    }
-}
-//# sourceMappingURL=musicbrainz-api-node.js.map

package/lib/musicbrainz-api.d.ts

@@ -1,180 +0,0 @@
-export { XmlMetadata } from './xml/xml-metadata.js';
-export { XmlIsrc } from './xml/xml-isrc.js';
-export { XmlIsrcList } from './xml/xml-isrc-list.js';
-export { XmlRecording } from './xml/xml-recording.js';
-import type { XmlMetadata } from './xml/xml-metadata.js';
-import { RateLimitThreshold } from 'rate-limit-threshold';
-import * as mb from './musicbrainz.types.js';
-import { HttpClient } from "./http-client.js";
-export * from './musicbrainz.types.js';
-export type RelationsIncludes = 'area-rels' | 'artist-rels' | 'event-rels' | 'instrument-rels' | 'label-rels' | 'place-rels' | 'recording-rels' | 'release-rels' | 'release-group-rels' | 'series-rels' | 'url-rels' | 'work-rels';
-export type SubQueryIncludes = 
-/**
- * include discids for all media in the releases
- */
-'discids'
-/**
- * include media for all releases, this includes the # of tracks on each medium and its format.
- */
- | 'media'
-/**
- * include isrcs for all recordings
- */
- | 'isrcs'
-/**
- * include artists credits for all releases and recordings
- */
- | 'artist-credits'
-/**
- * include only those releases where the artist appears on one of the tracks, only valid on artists in combination with `releases`
- */
- | 'various-artists';
-export type MiscIncludes = 'aliases' | 'annotation' | 'tags' | 'genres' | 'ratings' | 'media';
-export type AreaIncludes = MiscIncludes | RelationsIncludes;
-export type ArtistIncludes = MiscIncludes | RelationsIncludes | 'recordings' | 'releases' | 'release-groups' | 'works';
-export type CollectionIncludes = MiscIncludes | RelationsIncludes | 'user-collections';
-export type EventIncludes = MiscIncludes | RelationsIncludes;
-export type GenreIncludes = MiscIncludes;
-export type InstrumentIncludes = MiscIncludes | RelationsIncludes;
-export type LabelIncludes = MiscIncludes | RelationsIncludes | 'releases';
-export type PlaceIncludes = MiscIncludes | RelationsIncludes;
-export type RecordingIncludes = MiscIncludes | RelationsIncludes | SubQueryIncludes | 'artists' | 'releases' | 'isrcs';
-export type ReleaseIncludes = MiscIncludes | SubQueryIncludes | RelationsIncludes | 'artists' | 'collections' | 'labels' | 'recordings' | 'release-groups';
-export type ReleaseGroupIncludes = MiscIncludes | SubQueryIncludes | RelationsIncludes | 'artists' | 'releases';
-export type SeriesIncludes = MiscIncludes | RelationsIncludes;
-export type WorkIncludes = MiscIncludes | RelationsIncludes;
-export type UrlIncludes = RelationsIncludes;
-export type IFormData = {
-    [key: string]: string | number;
-};
-export interface IMusicBrainzConfig {
-    botAccount?: {
-        username?: string;
-        password?: string;
-    };
-    baseUrl?: string;
-    appName?: string;
-    appVersion?: string;
-    /**
-     * HTTP Proxy
-     */
-    proxy?: string;
-    /**
-     * User e-mail address or application URL
-     */
-    appContactInfo?: string;
-    disableRateLimiting?: boolean;
-}
-interface IInternalConfig extends IMusicBrainzConfig {
-    baseUrl: string;
-}
-export interface ICsrfSession {
-    sessionKey: string;
-    token: string;
-}
-export interface ISessionInformation {
-    csrf: ICsrfSession;
-    loggedIn?: boolean;
-}
-export declare class MusicBrainzApi {
-    readonly config: IInternalConfig;
-    protected rateLimiter: RateLimitThreshold;
-    protected httpClient: HttpClient;
-    protected session?: ISessionInformation;
-    static fetchCsrf(html: string): ICsrfSession;
-    private static fetchValue;
-    constructor(_config?: IMusicBrainzConfig);
-    protected initHttpClient(): HttpClient;
-    restGet<T>(relUrl: string, query?: {
-        [key: string]: string;
-    }): Promise<T>;
-    /**
-     * Lookup entity
-     * @param entity 'area', 'artist', collection', 'instrument', 'label', 'place', 'release', 'release-group', 'recording', 'series', 'work', 'url' or 'event'
-     * @param mbid Entity MBID
-     * @param inc Query, like: {<entity>: <MBID:}
-     */
-    lookup(entity: 'area', mbid: string, inc?: AreaIncludes[]): Promise<mb.IArea>;
-    lookup(entity: 'artist', mbid: string, inc?: ArtistIncludes[]): Promise<mb.IArtist>;
-    lookup(entity: 'collection', mbid: string, inc?: CollectionIncludes[]): Promise<mb.ICollection>;
-    lookup(entity: 'instrument', mbid: string, inc?: InstrumentIncludes[]): Promise<mb.IInstrument>;
-    lookup(entity: 'label', mbid: string, inc?: LabelIncludes[]): Promise<mb.ILabel>;
-    lookup(entity: 'place', mbid: string, inc?: PlaceIncludes[]): Promise<mb.IPlace>;
-    lookup(entity: 'release', mbid: string, inc?: ReleaseIncludes[]): Promise<mb.IRelease>;
-    lookup(entity: 'release-group', mbid: string, inc?: ReleaseGroupIncludes[]): Promise<mb.IReleaseGroup>;
-    lookup(entity: 'recording', mbid: string, inc?: RecordingIncludes[]): Promise<mb.IRecording>;
-    lookup(entity: 'series', mbid: string, inc?: SeriesIncludes[]): Promise<mb.ISeries>;
-    lookup(entity: 'work', mbid: string, inc?: WorkIncludes[]): Promise<mb.IWork>;
-    lookup(entity: 'url', mbid: string, inc?: UrlIncludes[]): Promise<mb.IUrl>;
-    lookup(entity: 'event', mbid: string, inc?: EventIncludes[]): Promise<mb.IEvent>;
-    /**
-     * Browse entity
-     * https://wiki.musicbrainz.org/MusicBrainz_API#Browse
-     * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
-     * https://wiki.musicbrainz.org/Development/JSON_Web_Service#Browse_Requests
-     * For example: http://musicbrainz.org/ws/2/release?label=47e718e1-7ee4-460c-b1cc-1192a841c6e5&offset=12&limit=2
-     * @param entity MusicBrainz entity
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browse(entity: 'area', query?: mb.IBrowseAreasQuery): Promise<mb.IBrowseAreasResult>;
-    browse(entity: 'artist', query?: mb.IBrowseArtistsQuery): Promise<mb.IBrowseArtistsResult>;
-    browse(entity: 'collection', query?: mb.IBrowseCollectionsQuery): Promise<mb.IBrowseCollectionsResult>;
-    browse(entity: 'event', query?: mb.IBrowseEventsQuery): Promise<mb.IBrowseEventsResult>;
-    browse(entity: 'label', query?: mb.IBrowseLabelsQuery): Promise<mb.IBrowseLabelsResult>;
-    browse(entity: 'instrument', query?: mb.IBrowseInstrumentsQuery): Promise<mb.IBrowseInstrumentsResult>;
-    browse(entity: 'place', query?: mb.IBrowsePlacesQuery): Promise<mb.IBrowsePlacesResult>;
-    browse(entity: 'recording', query?: mb.IBrowseRecordingsQuery): Promise<mb.IBrowseRecordingsResult>;
-    browse(entity: 'release', query?: mb.IBrowseReleasesQuery): Promise<mb.IBrowseReleasesResult>;
-    browse(entity: 'release-group', query?: mb.IBrowseReleaseGroupsQuery): Promise<mb.IBrowseReleaseGroupsResult>;
-    browse(entity: 'series', query?: mb.IBrowseSeriesQuery): Promise<mb.IBrowseSeriesResult>;
-    browse(entity: 'url', query?: mb.IBrowseUrlsQuery): Promise<mb.IUrl>;
-    browse(entity: 'work', query?: mb.IBrowseWorksQuery): Promise<mb.IBrowseWorksResult>;
-    /**
-     * 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 query Arguments
-     */
-    search(entity: 'area', query: mb.ISearchQuery<AreaIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IAreaList>;
-    search(artist: 'artist', query: mb.ISearchQuery<ArtistIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IArtistList>;
-    search(artist: 'recording', query: mb.ISearchQuery<AreaIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IRecordingList>;
-    search(artist: 'release', query: mb.ISearchQuery<ReleaseIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IReleaseList>;
-    search(artist: 'release-group', query: mb.ISearchQuery<ReleaseGroupIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IReleaseGroupList>;
-    search(artist: 'url', query: mb.ISearchQuery<UrlIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IUrlList>;
-    postRecording(xmlMetadata: XmlMetadata): Promise<void>;
-    post(entity: mb.EntityType, xmlMetadata: XmlMetadata): Promise<void>;
-    /**
-     * Submit entity
-     * @param entity Entity type e.g. 'recording'
-     * @param mbid
-     * @param formData
-     */
-    editEntity(entity: mb.EntityType, mbid: string, formData: Record<string, any>): Promise<void>;
-    /**
-     * Set URL to recording
-     * @param recording Recording to update
-     * @param url2add URL to add to the recording
-     * @param editNote Edit note
-     */
-    addUrlToRecording(recording: mb.IRecording, url2add: {
-        linkTypeId: mb.LinkType;
-        text: string;
-    }, editNote?: string): Promise<void>;
-    /**
-     * Add ISRC to recording
-     * @param recording Recording to update
-     * @param isrc ISRC code to add
-     */
-    addIsrc(recording: mb.IRecording, isrc: string): Promise<void>;
-    /**
-     * Add Spotify-ID to MusicBrainz recording.
-     * This function will automatically lookup the recording title, which is required to submit the recording URL
-     * @param recording MBID of the recording
-     * @param spotifyId Spotify ID
-     * @param editNote Comment to add.
-     */
-    addSpotifyIdToRecording(recording: mb.IRecording, spotifyId: string, editNote: string): Promise<void>;
-    protected getSession(): Promise<ISessionInformation>;
-    protected applyRateLimiter(): Promise<void>;
-}
-export declare function makeAndQueryString(keyValuePairs: IFormData): string;

package/lib/musicbrainz-api.js

@@ -1,207 +0,0 @@
-import { StatusCodes as HttpStatus } from 'http-status-codes';
-import Debug from 'debug';
-export { XmlMetadata } from './xml/xml-metadata.js';
-export { XmlIsrc } from './xml/xml-isrc.js';
-export { XmlIsrcList } from './xml/xml-isrc-list.js';
-export { XmlRecording } from './xml/xml-recording.js';
-import { DigestAuth } from './digest-auth.js';
-import { RateLimitThreshold } from 'rate-limit-threshold';
-import * as mb from './musicbrainz.types.js';
-import { HttpClient } from "./http-client.js";
-export * from './musicbrainz.types.js';
-const debug = Debug('musicbrainz-api');
-export class MusicBrainzApi {
-    static fetchCsrf(html) {
-        return {
-            sessionKey: MusicBrainzApi.fetchValue(html, 'csrf_session_key'),
-            token: MusicBrainzApi.fetchValue(html, 'csrf_token')
-        };
-    }
-    static fetchValue(html, key) {
-        let pos = html.indexOf(`name="${key}"`);
-        if (pos >= 0) {
-            pos = html.indexOf('value="', pos + key.length + 7);
-            if (pos >= 0) {
-                pos += 7;
-                const endValuePos = html.indexOf('"', pos);
-                return html.substring(pos, endValuePos);
-            }
-        }
-    }
-    constructor(_config) {
-        this.config = {
-            ...{
-                baseUrl: 'https://musicbrainz.org'
-            },
-            ..._config
-        };
-        this.httpClient = this.initHttpClient();
-        this.rateLimiter = new RateLimitThreshold(15, 18);
-    }
-    initHttpClient() {
-        return new HttpClient({
-            baseUrl: this.config.baseUrl,
-            timeout: 20 * 1000,
-            userAgent: `${this.config.appName}/${this.config.appVersion} ( ${this.config.appContactInfo} )`
-        });
-    }
-    async restGet(relUrl, query = {}) {
-        query.fmt = 'json';
-        await this.applyRateLimiter();
-        const response = await this.httpClient.get(`ws/2${relUrl}`, {
-            query,
-            retryLimit: 10
-        });
-        return response.json();
-    }
-    lookup(entity, mbid, inc = []) {
-        return this.restGet(`/${entity}/${mbid}`, { inc: inc.join(' ') });
-    }
-    browse(entity, query) {
-        return this.restGet(`/${entity}`, query);
-    }
-    search(entity, query) {
-        const urlQuery = { ...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}/`, urlQuery);
-    }
-    // ---------------------------------------------------------------------------
-    async postRecording(xmlMetadata) {
-        return this.post('recording', xmlMetadata);
-    }
-    async post(entity, xmlMetadata) {
-        if (!this.config.appName || !this.config.appVersion) {
-            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}/`;
-        // Get digest challenge
-        let digest = '';
-        let n = 1;
-        const postData = xmlMetadata.toXml();
-        do {
-            await this.applyRateLimiter();
-            const response = await this.httpClient.post(path, {
-                query: { client: clientId },
-                headers: {
-                    authorization: digest,
-                    'Content-Type': 'application/xml'
-                },
-                body: postData
-            });
-            if (response.statusCode === HttpStatus.UNAUTHORIZED) {
-                // Respond to digest challenge
-                const auth = new DigestAuth(this.config.botAccount);
-                const relPath = response.requestUrl.pathname; // Ensure path is relative
-                digest = auth.digest(response.request.method, relPath, response.headers['www-authenticate']);
-                ++n;
-            }
-            else {
-                break;
-            }
-        } while (n++ < 5);
-    }
-    /**
-     * Submit entity
-     * @param entity Entity type e.g. 'recording'
-     * @param mbid
-     * @param formData
-     */
-    async editEntity(entity, mbid, formData) {
-        await this.applyRateLimiter();
-        this.session = await this.getSession();
-        formData.csrf_session_key = this.session.csrf.sessionKey;
-        formData.csrf_token = this.session.csrf.token;
-        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, {
-            followRedirects: false
-        });
-        if (response.status === HttpStatus.OK)
-            throw new Error("Failed to submit form data");
-        if (response.status === HttpStatus.MOVED_TEMPORARILY)
-            return;
-        throw new Error(`Unexpected status code: ${response.status}`);
-    }
-    /**
-     * Set URL to recording
-     * @param recording Recording to update
-     * @param url2add URL to add to the recording
-     * @param editNote Edit note
-     */
-    async addUrlToRecording(recording, url2add, editNote = '') {
-        const formData = {};
-        formData['edit-recording.name'] = recording.title; // Required
-        formData['edit-recording.comment'] = recording.disambiguation;
-        formData['edit-recording.make_votable'] = true;
-        formData['edit-recording.url.0.link_type_id'] = url2add.linkTypeId;
-        formData['edit-recording.url.0.text'] = url2add.text;
-        recording.isrcs?.forEach((isrcs, i) => {
-            formData[`edit-recording.isrcs.${i}`] = isrcs;
-        });
-        formData['edit-recording.edit_note'] = editNote;
-        return this.editEntity('recording', recording.id, formData);
-    }
-    /**
-     * Add ISRC to recording
-     * @param recording Recording to update
-     * @param isrc ISRC code to add
-     */
-    async addIsrc(recording, isrc) {
-        const formData = {};
-        formData["edit-recording.name"] = recording.title; // Required
-        if (!recording.isrcs) {
-            throw new Error('You must retrieve recording with existing ISRC values');
-        }
-        if (recording.isrcs.indexOf(isrc) === -1) {
-            recording.isrcs.push(isrc);
-            for (const i in recording.isrcs) {
-                formData[`edit-recording.isrcs.${i}`] = recording.isrcs[i];
-            }
-            return this.editEntity('recording', recording.id, formData);
-        }
-    }
-    // -----------------------------------------------------------------------------------------------------------------
-    // Helper functions
-    // -----------------------------------------------------------------------------------------------------------------
-    /**
-     * Add Spotify-ID to MusicBrainz recording.
-     * This function will automatically lookup the recording title, which is required to submit the recording URL
-     * @param recording MBID of the recording
-     * @param spotifyId Spotify ID
-     * @param editNote Comment to add.
-     */
-    addSpotifyIdToRecording(recording, spotifyId, editNote) {
-        if (spotifyId.length !== 22) {
-            throw new Error('Invalid Spotify ID length');
-        }
-        return this.addUrlToRecording(recording, {
-            linkTypeId: mb.LinkType.stream_for_free,
-            text: `https://open.spotify.com/track/${spotifyId}`
-        }, editNote);
-    }
-    async getSession() {
-        const response = await this.httpClient.get('login', {
-            followRedirects: false
-        });
-        return {
-            csrf: MusicBrainzApi.fetchCsrf(await response.text())
-        };
-    }
-    async applyRateLimiter() {
-        if (!this.config.disableRateLimiting) {
-            const delay = await this.rateLimiter.limit();
-            debug(`Client side rate limiter activated: cool down for ${Math.round(delay / 100) / 10} s...`);
-        }
-    }
-}
-export function makeAndQueryString(keyValuePairs) {
-    return Object.keys(keyValuePairs).map(key => `${key}:"${keyValuePairs[key]}"`).join(' AND ');
-}
-//# sourceMappingURL=musicbrainz-api.js.map