beatprints.js/lib/spotify.d.ts

A Node.js version of the original Python BeatPrints project (https://github.com/TrueMyst/BeatPrints/) by TrueMyst. Create eye-catching, Pinterest-style music posters effortlessly. BeatPrints integrates with Spotify and LRClib API to help you design custom

import { Client, Track, Album } from 'spotify-api.js';
export declare const SpotifyURI: RegExp;
export declare const SpotifyURL: RegExp;
export declare const SpotifyID: RegExp;
/**
 * A class for interacting with the Spotify API to search and retrieve track and alnum metadata.
 */
export declare class Spotify {
    CLIENT_ID: string;
    CLIENT_SECRET: string;
    client: Client;
    /**
     * Initializes the Spotify client with credentials and obtains an access token.
     * @param {string} CLIENT_ID Spotify web API client ID.
     * @param {string} CLIENT_SECRET Spotify web API client secret.
     */
    constructor(CLIENT_ID: string, CLIENT_SECRET: string);
    /**
     * Checks if the provided string is a valid Spotify ID, URI, or URL.
     *
     * A valid Spotify identifier can be one of the following formats:
     * - Spotify URI: "spotify:{type}:{id}"
     * - Spotify URL: "https://open.spotify.com/{type}/{id}"
     * - Spotify ID: A 22-character Base62 string
     *
     * @param {string} id The string to be checked.
     * @returns {boolean} True if the string is a valid Spotify identifier, false otherwise.
     */
    isSpotifyID(id: string): boolean;
    extractSpotifyID(input: string): {
        id: string;
        type: SpotifySearchType;
    } | null;
    /**
     * Searches for tracks based on a query or Spotify ID/URI/URL and retrieves their metadata.
     * @param {string} query The search query or Spotify ID/URI/URL for the track.
     * @param {number} limit Max number of tracks to retrieve (only applies to search by text).
     * @returns {Promise<TrackMetadata[] | TrackMetadata>} An array of track metadata or a single track metadata (if limit = 1 or query is URI/URl/ID).
     * @throws `InvalidSearchLimit` If the limit is less than 1.
     * @throws `NoMathcingTrackFound` If no matching tracks are found.
     * @example ```ts
     * spotify.getTrack('Romantic Homicide - d4vd') // TrackMetadata[]
     * spotify.getTrack('spotify:track:3N6OVnOAKr9op19GcbxB4g') // TrackMetadata
     * spotify.getTrack('https://open.spotify.com/track/3N6OVnOAKr9op19GcbxB4g')
     * ```
     */
    getTrack(query: string, limit: 1): Promise<TrackMetadata>;
    getTrack(query: string, limit?: number): Promise<TrackMetadata[]>;
    /**
    * Searches for album based on a query or Spotify ID/URI/URL and retrieves their metadata.
    * @param {string} query The search query or Spotify ID/URI/URL for the album.
    * @param {number} limit Max number of albums to retrieve (only applies to search by text).
    * @returns {Promise<AlbumMetadata[] | AlbumMetadata>} An array of album metadata with track listings.
    * @throws `InvalidSearchLimit` If the limit is less than 1.
    * @throws `NoMatchingAlbumFound` If no matching albums are found.
    */
    getAlbum(query: string, limit: 1): Promise<AlbumMetadata>;
    getAlbum(query: string, limit?: number): Promise<AlbumMetadata[]>;
    /**
     * Returns TrackMetadata from a Spotify track object.
     * @param {Track} track Spotify track object.
     */
    getTrackMetadata(track: Track): Promise<TrackMetadata>;
    /**
     * Returns AlbumMetadata from a Spotify album object.
     * @param {Album} album Spotify album object
     * @param {boolean} shuffle Whether to shuffle the tracks in the album
     */
    getAlbumMetadata(album: Album, shuffle: boolean): Promise<AlbumMetadata>;
    formatReleased(releaseDate: string, precision: string): string;
    /**
     * Formats the duration of a track from milliseconds to `mm:ss` format.
     * @param {number} duration Duration of the track in milliseconds.
     * @returns {string} Formatted duration in `mm:ss` format.
     */
    formatDuration(duration: number): string;
}
export type SpotifySearchType = 'track' | 'album' | null;
export interface AlbumMetadata {
    name: string;
    artist: string;
    released: string;
    image: string;
    label: string;
    id: string;
    tracks: string[];
}
export interface TrackMetadata {
    name: string;
    artist: string;
    album: string;
    released: string;
    duration: string;
    image: string;
    label: string;
    id: string;
}