lastfm.ts 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# Last.fm Client (Typed)
+
+A robust, fully typed TypeScript client for the Last.fm API.
+
+## Installation
+
+```bash
+npm install lastfm-client
+```
+
+## Getting Started
+
+Initialize the client with your Last.fm API credentials.
+
+```typescript
+import { LastFmClient } from "lastfm-client";
+
+const client = new LastFmClient({
+  apiKey: "YOUR_API_KEY",
+  apiSecret: "YOUR_API_SECRET",
+  userAgent: "MyApp/1.0.0 (contact@example.com)", // Optional but recommended
+});
+```
+
+## Features
+
+### Authentication
+
+To scrobble or update "Now Playing", you need a user session.
+
+1.  **Get Auth URL**: Redirect the user to this URL to approve your app.
+
+    ```typescript
+    const authUrl = client.getAuthUrl("http://localhost:3000/callback");
+    console.log("Please visit:", authUrl);
+    ```
+
+2.  **Get Session**: Once the user returns with a `token`, exchange it for a session key.
+    ```typescript
+    const session = await client.getSession("TOKEN_FROM_CALLBACK");
+    const sessionKey = session.session.key;
+    ```
+
+### User Methods
+
+#### Get User Info
+
+```typescript
+const user = await client.getUser("rj");
+console.log(`User: ${user.user.realname}, Playcount: ${user.user.playcount}`);
+```
+
+#### Get Recent Tracks & Now Playing
+
+```typescript
+// Get recent tracks
+const recent = await client.getRecentTracks("rj", 10);
+
+// Check if user is currently listening to something
+const nowPlaying = await client.getNowPlaying("rj");
+if (nowPlaying) {
+  console.log(`Listening to: ${nowPlaying.name} by ${nowPlaying.artist["#text"]}`);
+}
+```
+
+### Track Methods
+
+#### Scrobbling (Record a listen)
+
+Requires `sessionKey`.
+
+```typescript
+await client.scrobble(
+  sessionKey,
+  "Daft Punk", // Artist
+  "One More Time", // Track
+  Math.floor(Date.now() / 1000), // Timestamp (in seconds)
+  "Discovery", // Album (Optional)
+);
+```
+
+#### Update Now Playing
+
+Requires `sessionKey`.
+
+```typescript
+await client.updateNowPlaying(sessionKey, "Daft Punk", "Harder, Better, Faster, Stronger");
+```
+
+#### Search & Similar
+
+```typescript
+const searchResults = await client.searchTrack("Believe");
+const similarTracks = await client.getSimilarTracks("Cher", "Believe");
+```
+
+### Other Methods
+
+The client also supports methods for **Albums**, **Artists**, and **Tags**:
+
+- `getAlbumInfo`, `searchAlbum`
+- `getArtistInfo`, `getSimilarArtists`, `searchArtist`
+- `getTagInfo`
+
+## License
+
+ISC

package/dist/LastFmClient.d.ts

@@ -0,0 +1,26 @@
+import { AlbumInfoResponse, AlbumSearchResponse, ArtistInfoResponse, ArtistSearchResponse, ArtistSimilarResponse, AuthSessionResponse, LastFmClientOptions, LastFmTrack, RecentTracksResponse, TagInfoResponse, TrackInfoResponse, TrackSearchResponse, TrackSimilarResponse, UserInfoResponse } from "./types";
+export declare class LastFmClient {
+    private apiKey;
+    private apiSecret;
+    private userAgent;
+    private baseUrl;
+    constructor(options: LastFmClientOptions);
+    private sign;
+    private request;
+    getAuthUrl(callbackUrl?: string): string;
+    getSession(token: string): Promise<AuthSessionResponse>;
+    getUser(username: string): Promise<UserInfoResponse>;
+    getRecentTracks(username: string, limit?: number, page?: number): Promise<RecentTracksResponse>;
+    getNowPlaying(username: string): Promise<LastFmTrack | null>;
+    getTrackInfo(artist: string, track: string, username?: string): Promise<TrackInfoResponse>;
+    updateNowPlaying(sessionKey: string, artist: string, track: string, album?: string, duration?: number): Promise<void>;
+    scrobble(sessionKey: string, artist: string, track: string, timestamp: number, album?: string): Promise<void>;
+    getAlbumInfo(artist: string, album: string, username?: string): Promise<AlbumInfoResponse>;
+    searchAlbum(album: string, limit?: number, page?: number): Promise<AlbumSearchResponse>;
+    getArtistInfo(artist: string, username?: string): Promise<ArtistInfoResponse>;
+    getSimilarArtists(artist: string, limit?: number): Promise<ArtistSimilarResponse>;
+    searchArtist(artist: string, limit?: number, page?: number): Promise<ArtistSearchResponse>;
+    getSimilarTracks(artist: string, track: string, limit?: number): Promise<TrackSimilarResponse>;
+    searchTrack(track: string, limit?: number, page?: number): Promise<TrackSearchResponse>;
+    getTagInfo(tag: string, lang?: string): Promise<TagInfoResponse>;
+}

package/dist/LastFmClient.js

@@ -0,0 +1,186 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LastFmClient = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+class LastFmClient {
+    constructor(options) {
+        this.baseUrl = "https://ws.audioscrobbler.com/2.0/";
+        this.apiKey = options.apiKey;
+        this.apiSecret = options.apiSecret;
+        this.userAgent = options.userAgent || "LastFmClient/1.0.0";
+    }
+    sign(params) {
+        const str = Object.keys(params)
+            .sort()
+            .filter((k) => params[k] !== undefined)
+            .map((k) => `${k}${params[k]}`)
+            .join("") + this.apiSecret;
+        return crypto_1.default.createHash("md5").update(str).digest("hex");
+    }
+    async request(method, params, signed = false) {
+        const searchParams = new URLSearchParams();
+        const allParams = {
+            api_key: this.apiKey,
+            format: "json",
+            ...params,
+        };
+        if (signed) {
+            allParams.api_sig = this.sign(allParams);
+        }
+        for (const [key, value] of Object.entries(allParams)) {
+            if (value !== undefined)
+                searchParams.append(key, String(value));
+        }
+        if (method === "GET") {
+            const url = `${this.baseUrl}?${searchParams.toString()}`;
+            const res = await fetch(url, {
+                headers: { "User-Agent": this.userAgent },
+            });
+            if (!res.ok) {
+                throw new Error(`Last.fm API Error: ${res.status} ${res.statusText}`);
+            }
+            return (await res.json());
+        }
+        else {
+            const res = await fetch(this.baseUrl, {
+                method: "POST",
+                body: searchParams,
+                headers: { "User-Agent": this.userAgent },
+            });
+            if (!res.ok) {
+                throw new Error(`Last.fm API Error: ${res.status} ${res.statusText}`);
+            }
+            return (await res.json());
+        }
+    }
+    getAuthUrl(callbackUrl) {
+        let url = `https://www.last.fm/api/auth/?api_key=${this.apiKey}`;
+        if (callbackUrl) {
+            url += `&cb=${encodeURIComponent(callbackUrl)}`;
+        }
+        return url;
+    }
+    async getSession(token) {
+        return this.request("GET", { method: "auth.getSession", token }, true);
+    }
+    async getUser(username) {
+        return this.request("GET", {
+            method: "user.getInfo",
+            user: username,
+        });
+    }
+    // Track methods
+    async getRecentTracks(username, limit = 50, page = 1) {
+        return this.request("GET", {
+            method: "user.getRecentTracks",
+            user: username,
+            limit,
+            page,
+        });
+    }
+    async getNowPlaying(username) {
+        const recentTracks = await this.getRecentTracks(username, 2);
+        const track = recentTracks.recenttracks.track[0];
+        if (track && track["@attr"]?.nowplaying === "true") {
+            return track;
+        }
+        return null;
+    }
+    async getTrackInfo(artist, track, username) {
+        return this.request("GET", {
+            method: "track.getInfo",
+            artist,
+            track,
+            username,
+        });
+    }
+    async updateNowPlaying(sessionKey, artist, track, album, duration) {
+        await this.request("POST", {
+            method: "track.updateNowPlaying",
+            sk: sessionKey,
+            artist,
+            track,
+            album,
+            duration,
+        }, true);
+    }
+    async scrobble(sessionKey, artist, track, timestamp, album) {
+        await this.request("POST", {
+            method: "track.scrobble",
+            sk: sessionKey,
+            artist,
+            track,
+            timestamp,
+            album,
+        }, true);
+    }
+    // Album Methods
+    async getAlbumInfo(artist, album, username) {
+        return this.request("GET", {
+            method: "album.getInfo",
+            artist,
+            album,
+            username,
+        });
+    }
+    async searchAlbum(album, limit, page) {
+        return this.request("GET", {
+            method: "album.search",
+            album,
+            limit,
+            page,
+        });
+    }
+    // Artist Methods
+    async getArtistInfo(artist, username) {
+        return this.request("GET", {
+            method: "artist.getInfo",
+            artist,
+            username,
+        });
+    }
+    async getSimilarArtists(artist, limit) {
+        return this.request("GET", {
+            method: "artist.getSimilar",
+            artist,
+            limit,
+        });
+    }
+    async searchArtist(artist, limit, page) {
+        return this.request("GET", {
+            method: "artist.search",
+            artist,
+            limit,
+            page,
+        });
+    }
+    // Track Methods
+    async getSimilarTracks(artist, track, limit) {
+        return this.request("GET", {
+            method: "track.getSimilar",
+            artist,
+            track,
+            limit,
+        });
+    }
+    async searchTrack(track, limit, page) {
+        return this.request("GET", {
+            method: "track.search",
+            track,
+            limit,
+            page,
+        });
+    }
+    // Tag Methods
+    async getTagInfo(tag, lang) {
+        return this.request("GET", {
+            method: "tag.getInfo",
+            tag,
+            lang,
+        });
+    }
+}
+exports.LastFmClient = LastFmClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./LastFmClient";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./LastFmClient"), exports);
+__exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -0,0 +1,195 @@
+export type LastFmImage = {
+    size: "small" | "medium" | "large" | "extralarge";
+    "#text": string;
+};
+export type LastFmArtistRef = {
+    mbid: string;
+    name: string;
+    "#text": string;
+    url?: string;
+};
+export type LastFmAlbumRef = {
+    "#text": string;
+    mbid: string;
+};
+export type LastFmTrack = {
+    name: string;
+    mbid: string;
+    url: string;
+    artist: LastFmArtistRef;
+    album: LastFmAlbumRef;
+    playcount: number | string;
+    duration?: string;
+    image?: LastFmImage[];
+    date?: {
+        uts: string;
+        "#text": string;
+    };
+    "@attr"?: {
+        nowplaying: "true" | "false";
+    };
+};
+export type LastFmUser = {
+    user: {
+        id: string;
+        name: string;
+        realname: string;
+        gender: string;
+        country: string;
+        url: string;
+        playcount: string;
+        playlists: string;
+        bootstrap: string;
+        image: LastFmImage[];
+        registered: {
+            unixtime: string;
+            "#text": number;
+        };
+    };
+};
+export type TrackInfoResponse = {
+    track: LastFmTrack;
+};
+export type RecentTracksResponse = {
+    recenttracks: {
+        track: LastFmTrack[];
+        "@attr": {
+            user: string;
+            page: string;
+            perPage: string;
+            totalPages: string;
+            total: string;
+        };
+    };
+};
+export type AuthSessionResponse = {
+    session: {
+        name: string;
+        key: string;
+        subscriber: number;
+    };
+};
+export type UserInfoResponse = LastFmUser;
+export interface LastFmClientOptions {
+    apiKey: string;
+    apiSecret: string;
+    userAgent?: string;
+}
+export type AlbumInfoResponse = {
+    album: {
+        name: string;
+        artist: string;
+        mbid?: string;
+        url: string;
+        image?: LastFmImage[];
+        listeners?: string;
+        playcount?: string;
+        tracks?: {
+            track: LastFmTrack[];
+        };
+        tags?: {
+            tag: LastFmTag[];
+        };
+        wiki?: {
+            published: string;
+            summary: string;
+            content: string;
+        };
+    };
+};
+export type AlbumSearchResponse = {
+    results: {
+        albummatches: {
+            album: Array<{
+                name: string;
+                artist: string;
+                url: string;
+                image: LastFmImage[];
+                streamable: string;
+                mbid: string;
+            }>;
+        };
+    };
+};
+export type ArtistInfoResponse = {
+    artist: {
+        name: string;
+        mbid?: string;
+        url: string;
+        image?: LastFmImage[];
+        streamable?: string;
+        ontour?: string;
+        stats?: {
+            listeners: string;
+            playcount: string;
+        };
+        similar?: {
+            artist: LastFmArtistRef[];
+        };
+        tags?: {
+            tag: LastFmTag[];
+        };
+        bio?: {
+            published: string;
+            summary: string;
+            content: string;
+        };
+    };
+};
+export type ArtistSimilarResponse = {
+    similarartists: {
+        artist: LastFmArtistRef[];
+    };
+};
+export type ArtistSearchResponse = {
+    results: {
+        artistmatches: {
+            artist: Array<{
+                name: string;
+                listeners: string;
+                mbid: string;
+                url: string;
+                streamable: string;
+                image: LastFmImage[];
+            }>;
+        };
+    };
+};
+export type TrackSimilarResponse = {
+    similartracks: {
+        track: LastFmTrack[];
+    };
+};
+export type TrackSearchResponse = {
+    results: {
+        trackmatches: {
+            track: Array<{
+                name: string;
+                artist: string;
+                url: string;
+                streamable: string;
+                listeners: string;
+                image: LastFmImage[];
+                mbid: string;
+            }>;
+        };
+    };
+};
+export type LastFmTag = {
+    name: string;
+    url: string;
+    reach?: string;
+    taggings?: string;
+    streamable?: string;
+    wiki?: {
+        published: string;
+        summary: string;
+        content: string;
+    };
+};
+export type TagInfoResponse = {
+    tag: LastFmTag & {
+        total?: number;
+        reach?: number;
+    };
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "lastfm.ts",
+  "version": "1.0.0",
+  "description": "A typed Last.fm API client",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "lastfm",
+    "scrobbler",
+    "typescript"
+  ],
+  "files": [
+    "dist"
+  ],
+  "author": "Rafael",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.9.3"
+  }
+}