Last.FM TypeScript API Client

Common errors

• ERR_REQUIRE_ESM: Must use import to load ES Module

  cause Attempting to use `require()` to import `lastfm-ts-api` in a CommonJS context, but the package is ESM-only since v2.0.0.
  fix Change your import statements from `const { LastFMAlbum } = require('lastfm-ts-api');` to `import { LastFMAlbum } from 'lastfm-ts-api';`. Also, ensure your `package.json` contains `"type": "module"` or your file has a `.mjs` extension.

• TypeError: Cannot read properties of undefined (reading 'track')

  cause Incorrectly parsing the `track.scrobble` response, especially when scrobbling a single track, due to the response structure changing to an object in v2.3.0.
  fix Update your code to expect an object response from `track.scrobble` when scrobbling a single track, rather than assuming it's always an array or a different structure.

• Property 'OldTypeName' does not exist on type 'NewTypeName'. Did you mean 'NewTypeName'?

  cause Using old type names in a TypeScript project after upgrading to v2.0.0, where several types were renamed.
  fix Update your TypeScript code to use the new type names introduced in v2.0.0. Refer to the library's type definitions for the correct names.

Warnings

• breaking Version 2.0.0 introduced a significant breaking change, making the package pure ESM. This means CommonJS `require()` statements will no longer work, and you must use ES module `import` syntax.
  Fix: Migrate all `require()` statements to `import` statements. Ensure your project's `package.json` has `"type": "module"` or uses `.mjs` file extensions for ESM files.
• breaking With version 2.0.0, some internal types were renamed to improve consistency and clarity. This may cause type errors in existing TypeScript projects.
  Fix: Consult the library's official documentation or your IDE's type hints to update any affected type names in your codebase.
• gotcha The response structure for the `track.scrobble` endpoint changed in v2.3.0 when scrobbling a single track. It now returns an object instead of a plain string or array of objects.
  Fix: Update your code to correctly parse the `track.scrobble` response, expecting an object for single track scrobbles.
• gotcha The `User` API's `getInfo` method was updated in v2.2.0 to include the correct way of signing requests using the session secret. Previous implementations might fail authentication.
  Fix: Ensure that `user.getInfo` calls correctly pass the session secret for signing as per the updated API requirements.
• gotcha Error handling was improved in versions 2.3.0 and 2.5.0 to account for API responses possibly containing an error object instead of a plain string. This changes how you should parse API errors.
  Fix: Adjust error parsing logic to check for both string and object error formats in API responses, especially when integrating with third-party Last.FM compatible services.
• gotcha Version 2.6.2 noted that the album field within a track object can be missing in some Last.FM API responses, which might affect applications assuming its presence.
  Fix: Implement defensive programming by checking for the existence of the `album` property before attempting to access its sub-properties, e.g., `track.album?.title`.

Install

• npm install lastfm-ts-api npm
• yarn add lastfm-ts-api yarn
• pnpm add lastfm-ts-api pnpm

Imports

• LastFMTrack
  wrong:

  const { LastFMTrack } = require('lastfm-ts-api');

  correct:

  import { LastFMTrack } from 'lastfm-ts-api';

  The package became pure ESM in v2.0.0. CommonJS 'require' is not supported.
• LastFMAuth
  wrong:

  import LastFMAuth from 'lastfm-ts-api';

  correct:

  import { LastFMAuth } from 'lastfm-ts-api';

  Classes are exposed as named exports, not default exports.
• LastFMAlbum
  wrong:

  const album = new (require('lastfm-ts-api')).LastFMAlbum(...);

  correct:

  import { LastFMAlbum } from 'lastfm-ts-api';

  Directly destructure named exports for clarity and correct ESM usage.

Quickstart

Demonstrates initializing the LastFMTrack client and fetching the top tracks for an artist, handling API key retrieval from environment variables.

import { LastFMTrack } from 'lastfm-ts-api';

const API_KEY = process.env.LASTFM_API_KEY ?? '';
const SECRET = process.env.LASTFM_SHARED_SECRET ?? ''; // Optional for some endpoints
const SESSION_KEY = process.env.LASTFM_SESSION_KEY ?? ''; // Optional for some endpoints

if (!API_KEY) {
  console.error('LASTFM_API_KEY environment variable is required.');
  process.exit(1);
}

async function getTopTracks() {
  try {
    const trackClient = new LastFMTrack(API_KEY, SECRET, SESSION_KEY);
    const topTracks = await trackClient.getTopTracks({
      artist: 'Radiohead',
      limit: 5
    });
    console.log(`Top tracks by Radiohead:`);
    topTracks.tracks.track.forEach((track: any) => {
      console.log(`- ${track.name} (Playcount: ${track.playcount})`);
    });
  } catch (error) {
    console.error('Error fetching top tracks:', error);
  }
}

getTopTracks();