{"id":16100,"library":"lastfm-ts-api","title":"Last.FM TypeScript API Client","description":"lastfm-ts-api is a TypeScript-first API client for the Last.FM API, currently stable at version 2.6.2. It provides strongly typed interfaces for interacting with various Last.FM API endpoints, including Album, Artist, Auth, Chart, Geo, Library, Tag, Track, and User APIs. The library maintains an active release cadence, frequently adding new features, improving error handling, and enhancing type definitions. A key differentiator is its comprehensive TypeScript support, ensuring parameter and response types are well-defined. It also supports integration with third-party scrobbling services like Libre.FM since version 2.3.0 and offers user-configurable request timeouts. The library transitioned to a pure ESM module in version 2.0.0, aligning with modern JavaScript practices.","status":"active","version":"2.6.2","language":"javascript","source_language":"en","source_url":"https://github.com/scriptex/lastfm-ts-api","tags":["javascript","Last.FM","Last.FM API","Last.FM API Client","Last.FM TypeScript API","typescript"],"install":[{"cmd":"npm install lastfm-ts-api","lang":"bash","label":"npm"},{"cmd":"yarn add lastfm-ts-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add lastfm-ts-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package became pure ESM in v2.0.0. CommonJS 'require' is not supported.","wrong":"const { LastFMTrack } = require('lastfm-ts-api');","symbol":"LastFMTrack","correct":"import { LastFMTrack } from 'lastfm-ts-api';"},{"note":"Classes are exposed as named exports, not default exports.","wrong":"import LastFMAuth from 'lastfm-ts-api';","symbol":"LastFMAuth","correct":"import { LastFMAuth } from 'lastfm-ts-api';"},{"note":"Directly destructure named exports for clarity and correct ESM usage.","wrong":"const album = new (require('lastfm-ts-api')).LastFMAlbum(...);","symbol":"LastFMAlbum","correct":"import { LastFMAlbum } from 'lastfm-ts-api';"}],"quickstart":{"code":"import { LastFMTrack } from 'lastfm-ts-api';\n\nconst API_KEY = process.env.LASTFM_API_KEY ?? '';\nconst SECRET = process.env.LASTFM_SHARED_SECRET ?? ''; // Optional for some endpoints\nconst SESSION_KEY = process.env.LASTFM_SESSION_KEY ?? ''; // Optional for some endpoints\n\nif (!API_KEY) {\n  console.error('LASTFM_API_KEY environment variable is required.');\n  process.exit(1);\n}\n\nasync function getTopTracks() {\n  try {\n    const trackClient = new LastFMTrack(API_KEY, SECRET, SESSION_KEY);\n    const topTracks = await trackClient.getTopTracks({\n      artist: 'Radiohead',\n      limit: 5\n    });\n    console.log(`Top tracks by Radiohead:`);\n    topTracks.tracks.track.forEach((track: any) => {\n      console.log(`- ${track.name} (Playcount: ${track.playcount})`);\n    });\n  } catch (error) {\n    console.error('Error fetching top tracks:', error);\n  }\n}\n\ngetTopTracks();","lang":"typescript","description":"Demonstrates initializing the LastFMTrack client and fetching the top tracks for an artist, handling API key retrieval from environment variables."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Consult the library's official documentation or your IDE's type hints to update any affected type names in your codebase.","message":"With version 2.0.0, some internal types were renamed to improve consistency and clarity. This may cause type errors in existing TypeScript projects.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your code to correctly parse the `track.scrobble` response, expecting an object for single track scrobbles.","message":"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.","severity":"gotcha","affected_versions":">=2.3.0"},{"fix":"Ensure that `user.getInfo` calls correctly pass the session secret for signing as per the updated API requirements.","message":"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.","severity":"gotcha","affected_versions":">=2.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.3.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=2.6.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `require()` to import `lastfm-ts-api` in a CommonJS context, but the package is ESM-only since v2.0.0.","error":"ERR_REQUIRE_ESM: Must use import to load ES Module"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'track')"},{"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.","cause":"Using old type names in a TypeScript project after upgrading to v2.0.0, where several types were renamed.","error":"Property 'OldTypeName' does not exist on type 'NewTypeName'. Did you mean 'NewTypeName'?"}],"ecosystem":"npm"}