@ziplayer/plugin/dist/SpotifyPlugin.d.ts

A modular Discord voice player with plugin system

import { BasePlugin, Track, SearchResult, StreamInfo } from "ziplayer";
/**
 * A minimal Spotify plugin for metadata extraction and display purposes.
 *
 * This plugin provides support for:
 * - Spotify track URLs/URIs (spotify:track:...)
 * - Spotify playlist URLs/URIs (spotify:playlist:...)
 * - Spotify album URLs/URIs (spotify:album:...)
 * - Metadata extraction using Spotify's public oEmbed endpoint
 *
 * **Important Notes:**
 * - This plugin does NOT provide audio streams (player is expected to redirect/fallback upstream)
 * - This plugin does NOT expand playlists/albums (no SDK; oEmbed doesn't enumerate items)
 * - This plugin only provides display metadata for Spotify content
 *
 * @example
 *
 * const spotifyPlugin = new SpotifyPlugin();
 *
 * // Add to PlayerManager
 * const manager = new PlayerManager({
 *   plugins: [spotifyPlugin]
 * });
 *
 * // Get metadata for a Spotify track
 * const result = await spotifyPlugin.search("spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "user123");
 * console.log(result.tracks[0].metadata); // Contains Spotify metadata
 *
 *
 * @since 1.1.0
 */
export declare class SpotifyPlugin extends BasePlugin {
    name: string;
    version: string;
    /**
     * Determines if this plugin can handle the given query.
     *
     * @param query - The search query or URL to check
     * @returns `true` if the query is a Spotify URL/URI, `false` otherwise
     *
     * @example
     *
     * plugin.canHandle("spotify:track:4iV5W9uYEdYUVa79Axb7Rh"); // true
     * plugin.canHandle("https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh"); // true
     * plugin.canHandle("youtube.com/watch?v=123"); // false
     *
     */
    canHandle(query: string): boolean;
    /**
     * Validates if a URL/URI is a valid Spotify URL/URI.
     *
     * @param url - The URL/URI to validate
     * @returns `true` if the URL/URI is a valid Spotify URL/URI, `false` otherwise
     *
     * @example
     *
     * plugin.validate("spotify:track:4iV5W9uYEdYUVa79Axb7Rh"); // true
     * plugin.validate("https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh"); // true
     * plugin.validate("https://youtube.com/watch?v=123"); // false
     *
     */
    validate(url: string): boolean;
    /**
     * Extracts metadata from Spotify URLs/URIs using the oEmbed API.
     *
     * This method handles Spotify track, playlist, and album URLs/URIs by fetching
     * display metadata from Spotify's public oEmbed endpoint. It does not provide
     * audio streams or expand playlists/albums.
     *
     * @param query - The Spotify URL/URI to extract metadata from
     * @param requestedBy - The user ID who requested the extraction
     * @returns A SearchResult containing a single track with metadata (no audio stream)
     *
     * @example
     *
     * // Extract track metadata
     * const result = await plugin.search("spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "user123");
     * console.log(result.tracks[0].metadata); // Contains Spotify metadata
     *
     * // Extract playlist metadata
     * const playlistResult = await plugin.search("https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M", "user123");
     * console.log(playlistResult.tracks[0].metadata.kind); // "playlist"
     *
     */
    search(query: string, requestedBy: string): Promise<SearchResult>;
    /**
     * Extracts tracks from a Spotify playlist URL.
     *
     * **Note:** This method is not implemented as this plugin does not support
     * playlist expansion. It always returns an empty array.
     *
     * @param _input - The Spotify playlist URL (unused)
     * @param _requestedBy - The user ID who requested the extraction (unused)
     * @returns An empty array (playlist expansion not supported)
     *
     * @example
     *
     * const tracks = await plugin.extractPlaylist("spotify:playlist:123", "user123");
     * console.log(tracks); // [] - empty array
     *
     */
    extractPlaylist(_input: string, _requestedBy: string): Promise<Track[]>;
    /**
     * Extracts tracks from a Spotify album URL.
     *
     * **Note:** This method is not implemented as this plugin does not support
     * album expansion. It always returns an empty array.
     *
     * @param _input - The Spotify album URL (unused)
     * @param _requestedBy - The user ID who requested the extraction (unused)
     * @returns An empty array (album expansion not supported)
     *
     * @example
     *
     * const tracks = await plugin.extractAlbum("spotify:album:123", "user123");
     * console.log(tracks); // [] - empty array
     *
     */
    extractAlbum(_input: string, _requestedBy: string): Promise<Track[]>;
    /**
     * Attempts to get an audio stream for a Spotify track.
     *
     * **Note:** This method always throws an error as this plugin does not support
     * audio streaming. The player is expected to redirect to other plugins or
     * use fallback mechanisms for actual audio playback.
     *
     * @param _track - The Track object (unused)
     * @throws {Error} Always throws "Spotify streaming is not supported by this plugin"
     *
     * @example
     *
     * try {
     *   const stream = await plugin.getStream(track);
     * } catch (error) {
     *   console.log(error.message); // "Spotify streaming is not supported by this plugin"
     * }
     *
     */
    getStream(_track: Track): Promise<StreamInfo>;
    private identifyKind;
    private extractId;
    private buildTrackFromUrlOrUri;
    private buildHeaderItem;
    private toShareUrl;
    private fetchOEmbed;
}
//# sourceMappingURL=SpotifyPlugin.d.ts.map