@beatsphere/lastfm-client

Last.fm API client with Zod runtime validation. Covers auth, now-playing, top tracks/artists/albums, recent tracks, and weekly reports. Battle-tested in BeatSphere.

Install

npm install @beatsphere/lastfm-client

Quick Start

import {
  getMobileSession,
  getUserInfo,
  getListeningStatus,
  getTopTracks,
  getRecentTracks,
  getWeeklyReport,
} from '@beatsphere/lastfm-client';

// You must provide an MD5 function for API signature generation.
// Examples: crypto.createHash('md5') (Node), react-native-quick-md5, js-md5, etc.
import { createHash } from 'crypto';
const md5 = (input: string) => createHash('md5').update(input).digest('hex');

// Authenticate
const { sessionKey, username } = await getMobileSession(
  'YOUR_API_KEY',
  'YOUR_SHARED_SECRET',
  oauthToken,     // from Last.fm callback URL
  md5,
);

// Get user info
const user = await getUserInfo('YOUR_API_KEY', sessionKey);

// Check what someone is listening to
const status = await getListeningStatus('YOUR_API_KEY', username);
if (status) {
  console.log(`${status.track.name} — ${status.status}`); // 'live' or 'recent'
}

// Top tracks
const tracks = await getTopTracks('YOUR_API_KEY', username, sessionKey, 10);

// Weekly report
const report = await getWeeklyReport('YOUR_API_KEY', username);
// { totalScrobbles: 142, uniqueArtists: 38, topArtist: { name: 'Radiohead' } }

API

Function	Description
getMobileSession(apiKey, secret, token, md5)	OAuth → session key. Prevents double-processing of single-use tokens
getUserInfo(apiKey, sessionKey)	User profile (name, playcount, image, etc.)
getListeningStatus(apiKey, username, threshold?)	Currently playing or recently scrobbled track
getTopTracks(apiKey, username, sessionKey?, limit?)	User's top tracks
getTopArtists(apiKey, username, sessionKey?, period?, limit?)	User's top artists
getTopAlbums(apiKey, username, sessionKey?, period?, limit?)	User's top albums
getRecentTracks(apiKey, username, sessionKey?, limit?)	Recently scrobbled tracks
getUserRecentTrack(apiKey, username)	Single most recent track
getWeeklyReport(apiKey, username)	Weekly scrobble summary
createApiSignature(params, secret, md5)	Generate Last.fm API signature

Period values

For getTopArtists and getTopAlbums:

• '1month' | '3month' | '6month' | '12month' | 'overall'

MD5 function

Last.fm requires MD5-signed requests. Since MD5 implementations vary by platform, you provide your own:

// Node.js
import { createHash } from 'crypto';
const md5 = (s: string) => createHash('md5').update(s).digest('hex');

// React Native
import { stringMd5 } from 'react-native-quick-md5';
const md5 = stringMd5;

// Browser
import md5 from 'js-md5';

Zod schemas

All response schemas are exported for direct use:

import {
  LastFmTrackSchema,
  LastFmUserSchema,
  LastFmAlbumSchema,
  // ... all schemas and types
} from '@beatsphere/lastfm-client';

License

MIT