lastfm-api-lib/dist/index.d.cts

A TypeScript library for interacting with the Last.fm API

import { AxiosInstance } from 'axios';

/**
 * @file httpClient.ts
 * @description HTTP client for making requests to Last.fm API
 * @author Caleb Price
 * @version 1.0.0
 * @date 2025-07-23
 */

interface RequestOptions {
    method?: 'GET' | 'POST';
    params?: Record<string, any>;
    headers?: Record<string, string>;
    retries?: number;
}
declare class LastFmHttpClient {
    private client;
    private apiKey;
    private readonly baseURL;
    constructor(apiKey?: string);
    /**
     * Set API key for requests
     */
    setApiKey(apiKey: string): void;
    /**
     * Clear the API key
     */
    clearApiKey(): void;
    /**
     * Make a request to the Last.fm API
     */
    request(method: string, params?: Record<string, any>, options?: RequestOptions): Promise<any>;
    /**
     * Handle response errors with retries for certain status codes
     */
    private handleResponseError;
    /**
     * Delay helper for rate limiting
     */
    private delay;
    /**
     * Get the HTTP client instance
     */
    getHttpClient(): AxiosInstance;
}

/**
 * @file baseEndpoint.ts
 * @description Base class for Last.fm API endpoints
 * @author Caleb Price
 * @version 1.0.0
 * @date 2025-07-23
 */

declare abstract class BaseEndpoint {
    protected httpClient: LastFmHttpClient;
    constructor(httpClient: LastFmHttpClient);
    /**
     * Make a request to the API
     */
    protected request(method: string, params?: Record<string, any>): Promise<any>;
    /**
     * Clean up undefined/null parameters
     */
    protected cleanParams(params: Record<string, any>): Record<string, any>;
}

/**
 * @file types.ts
 * @description TypeScript types for Last.fm API responses
 * @author Caleb Price
 * @version 1.0.0
 * @date 2025-07-23
 */
interface LastFmImage {
    "#text": string;
    size: "small" | "medium" | "large" | "extralarge" | "mega" | "";
}
interface LastFmTag {
    name: string;
    count: number;
    url?: string;
}
interface LastFmDate {
    "#text": string;
    uts: string;
}
interface LastFmAttr {
    page: string;
    perPage: string;
    totalPages: string;
    total: string;
}
interface LastFmArtist {
    name: string;
    mbid?: string;
    url: string;
    image?: LastFmImage[];
    listeners?: string;
    playcount?: string;
    bio?: {
        summary: string;
        content: string;
    };
    similar?: {
        artist: LastFmArtist[];
    };
    tags?: {
        tag: LastFmTag[];
    };
    stats?: {
        listeners: string;
        playcount: string;
    };
}
interface LastFmAlbum {
    name: string;
    artist: string | LastFmArtist;
    mbid?: string;
    url: string;
    image?: LastFmImage[];
    listeners?: string;
    playcount?: string;
    tracks?: {
        track: LastFmTrack[];
    };
    tags?: {
        tag: LastFmTag[];
    };
    wiki?: {
        published: string;
        summary: string;
        content: string;
    };
}
interface LastFmTrack {
    name: string;
    artist: string | LastFmArtist;
    album?: string | LastFmAlbum;
    mbid?: string;
    url: string;
    duration?: string;
    listeners?: string;
    playcount?: string;
    image?: LastFmImage[];
    tags?: {
        tag: LastFmTag[];
    };
    wiki?: {
        published: string;
        summary: string;
        content: string;
    };
    streamable?: {
        "#text": string;
        fulltrack: string;
    };
    toptags?: {
        tag: LastFmTag[];
    };
}
interface LastFmUser {
    name: string;
    realname?: string;
    url: string;
    image?: LastFmImage[];
    country?: string;
    age?: string;
    gender?: string;
    subscriber?: string;
    playcount?: string;
    playlists?: string;
    bootstrap?: string;
    registered?: LastFmDate;
}
interface LastFmChart {
    artists?: {
        artist: LastFmArtist[];
        "@attr": LastFmAttr;
    };
    tracks?: {
        track: LastFmTrack[];
        "@attr": LastFmAttr;
    };
    tags?: {
        tag: LastFmTag[];
        "@attr": LastFmAttr;
    };
}
interface LastFmSearchResults {
    results: {
        "opensearch:Query": {
            "#text": string;
            role: string;
            searchTerms: string;
            startPage: string;
        };
        "opensearch:totalResults": string;
        "opensearch:startIndex": string;
        "opensearch:itemsPerPage": string;
        artistmatches?: {
            artist: LastFmArtist[];
        };
        albummatches?: {
            album: LastFmAlbum[];
        };
        trackmatches?: {
            track: LastFmTrack[];
        };
        "@attr": {
            for: string;
        };
    };
}
interface LastFmApiResponse<T> {
    [key: string]: T;
}
interface LastFmRequestOptions {
    limit?: number;
    page?: number;
    autocorrect?: 0 | 1;
    user?: string;
    lang?: string;
}
interface ArtistSearchOptions extends LastFmRequestOptions {
    artist: string;
}
interface AlbumSearchOptions extends LastFmRequestOptions {
    album: string;
}
interface TrackSearchOptions extends LastFmRequestOptions {
    track: string;
}
interface TagOptions extends LastFmRequestOptions {
    tag: string;
}
interface GeoOptions extends LastFmRequestOptions {
    country: string;
}
interface SimilarOptions extends LastFmRequestOptions {
    artist?: string;
    track?: string;
    mbid?: string;
}
interface TopTagsOptions extends LastFmRequestOptions {
    artist?: string;
    album?: string;
    track?: string;
    mbid?: string;
}
interface InfoOptions extends LastFmRequestOptions {
    artist?: string;
    album?: string;
    track?: string;
    mbid?: string;
    username?: string;
}

/**
 * @file artist.ts
 * @description Artist endpoints for Last.fm API
 * @author Caleb Price
 * @version 1.0.0
 * @date 2025-07-23
 */

declare class ArtistEndpoints extends BaseEndpoint {
    /**
     * Get artist correction
     */
    getCorrection(artist: string): Promise<{
        corrections?: {
            correction: {
                artist: LastFmArtist;
            };
        };
    }>;
    /**
     * Get artist information
     */
    getInfo(artist: string, options?: InfoOptions): Promise<{
        artist: LastFmArtist;
    }>;
    /**
     * Get similar artists
     */
    getSimilar(artist: string, options?: SimilarOptions): Promise<{
        similarartists: {
            artist: LastFmArtist[];
        };
    }>;
    /**
     * Get top albums for an artist
     */
    getTopAlbums(artist: string, options?: LastFmRequestOptions): Promise<{
        topalbums: {
            album: LastFmAlbum[];
        };
    }>;
    /**
     * Get top tags for an artist
     */
    getTopTags(artist: string, options?: TopTagsOptions): Promise<{
        toptags: {
            tag: LastFmTag[];
        };
    }>;
    /**
     * Get top tracks for an artist
     */
    getTopTracks(artist: string, options?: LastFmRequestOptions): Promise<{
        toptracks: {
            track: LastFmTrack[];
        };
    }>;
    /**
     * Search for an artist
     */
    search(artist: string, options?: LastFmRequestOptions): Promise<LastFmSearchResults>;
}

/**
 * @file album.ts
 * @description Album endpoints for Last.fm API
 * @author Caleb Price
 * @version 1.0.0
 * @date 2025-07-23
 */

declare class AlbumEndpoints extends BaseEndpoint {
    /**
     * Get album information
     */
    getInfo(artist: string, album: string, options?: InfoOptions): Promise<{
        album: LastFmAlbum;
    }>;
    /**
     * Get top tags for an album
     */
    getTopTags(artist: string, album: string, options?: TopTagsOptions): Promise<{
        toptags: {
            tag: LastFmTag[];
        };
    }>;
    /**
     * Search for an album
     */
    search(album: string, options?: LastFmRequestOptions): Promise<LastFmSearchResults>;
}

/**
 * @file track.ts
 * @description Track endpoints for Last.fm API
 * @author Caleb Price
 * @version 1.0.0
 * @date 2025-07-23
 */

declare class TrackEndpoints extends BaseEndpoint {
    /**
     * Get track correction
     */
    getCorrection(artist: string, track: string): Promise<{
        corrections?: {
            correction: {
                track: LastFmTrack;
            };
        };
    }>;
    /**
     * Get track information
     */
    getInfo(artist: string, track: string, options?: InfoOptions): Promise<{
        track: LastFmTrack;
    }>;
    /**
     * Get similar tracks
     */
    getSimilar(artist: string, track: string, options?: SimilarOptions): Promise<{
        similartracks: {
            track: LastFmTrack[];
        };
    }>;
    /**
     * Get top tags for a track
     */
    getTopTags(artist: string, track: string, options?: TopTagsOptions): Promise<{
        toptags: {
            tag: LastFmTag[];
        };
    }>;
    /**
     * Search for a track
     */
    search(track: string, options?: LastFmRequestOptions): Promise<LastFmSearchResults>;
}

/**
 * @file tag.ts
 * @description Tag endpoints for Last.fm API
 * @author Caleb Price
 * @version 1.0.0
 * @date 2025-07-23
 */

declare class TagEndpoints extends BaseEndpoint {
    /**
     * Get tag information
     */
    getInfo(tag: string, options?: InfoOptions): Promise<{
        tag: LastFmTag;
    }>;
    /**
     * Get similar tags
     */
    getSimilar(tag: string): Promise<{
        similartags: {
            tag: LastFmTag[];
        };
    }>;
    /**
     * Get top albums for a tag
     */
    getTopAlbums(tag: string, options?: LastFmRequestOptions): Promise<{
        albums: {
            album: LastFmAlbum[];
        };
    }>;
    /**
     * Get top artists for a tag
     */
    getTopArtists(tag: string, options?: LastFmRequestOptions): Promise<{
        topartists: {
            artist: LastFmArtist[];
        };
    }>;
    /**
     * Get top tracks for a tag
     */
    getTopTracks(tag: string, options?: LastFmRequestOptions): Promise<{
        tracks: {
            track: LastFmTrack[];
        };
    }>;
    /**
     * Get top tags
     */
    getTopTags(): Promise<{
        toptags: {
            tag: LastFmTag[];
        };
    }>;
}

/**
 * @file chart.ts
 * @description Chart endpoints for Last.fm API
 * @author Caleb Price
 * @version 1.0.0
 * @date 2025-07-23
 */

declare class ChartEndpoints extends BaseEndpoint {
    /**
     * Get top artists chart
     */
    getTopArtists(options?: LastFmRequestOptions): Promise<{
        artists: {
            artist: LastFmArtist[];
        };
    }>;
    /**
     * Get top tracks chart
     */
    getTopTracks(options?: LastFmRequestOptions): Promise<{
        tracks: {
            track: LastFmTrack[];
        };
    }>;
    /**
     * Get top tags chart
     */
    getTopTags(options?: LastFmRequestOptions): Promise<{
        tags: {
            tag: LastFmTag[];
        };
    }>;
}

/**
 * @file main.ts
 * @description Main Last.fm API class with constructor pattern for organized API access
 * @author Caleb Price
 * @version 1.0.0
 * @date 2025-07-23
 *
 * @description
 * Constructor-based Last.fm API wrapper that provides organized methods for
 * interacting with the Last.fm Web API. Supports artists, albums, tracks, tags, and charts.
 *
 * @usage
 * ```javascript
 * const lastfm = new LastFm(apiKey);
 * const artistInfo = await lastfm.artist.getInfo('Radiohead');
 * const albumInfo = await lastfm.album.getInfo('Radiohead', 'OK Computer');
 * const topTracks = await lastfm.track.search('Creep');
 * ```
 */

declare class LastFm {
    private httpClient;
    artist: ArtistEndpoints;
    album: AlbumEndpoints;
    track: TrackEndpoints;
    tag: TagEndpoints;
    chart: ChartEndpoints;
    constructor(apiKey?: string);
    /**
     * Initialize all endpoint groups
     */
    private initializeEndpoints;
    /**
     * Basic API key format validation
     */
    private isValidApiKeyFormat;
    /**
     * Set API key for API requests
     */
    setApiKey(apiKey: string): void;
    /**
     * Clear the API key
     */
    clearApiKey(): void;
    /**
     * Make a raw API request
     */
    request(method: string, params?: Record<string, any>): Promise<any>;
    /**
     * Get the HTTP client instance for advanced usage
     */
    getHttpClient(): LastFmHttpClient;
    /**
     * Clean up resources and clear API key
     */
    destroy(): void;
}

export { AlbumEndpoints, type AlbumSearchOptions, ArtistEndpoints, type ArtistSearchOptions, ChartEndpoints, type GeoOptions, type InfoOptions, LastFm, type LastFmAlbum, type LastFmApiResponse, type LastFmArtist, type LastFmAttr, type LastFmChart, type LastFmDate, LastFmHttpClient, type LastFmImage, type LastFmRequestOptions, type LastFmSearchResults, type LastFmTag, type LastFmTrack, type LastFmUser, type SimilarOptions, TagEndpoints, type TagOptions, type TopTagsOptions, TrackEndpoints, type TrackSearchOptions, LastFm as default };