lastfm-nodejs-client 1.5.6 → 1.6.1

package/README.md

@@ -5,129 +5,195 @@
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/ba3b73c24e06433fabe0efed8b43d026)](https://www.codacy.com/gh/mannuelf/lastfm-nodejs-client/dashboard?utm_source=github.com&utm_medium=referral&utm_content=mannuelf/lastfm-nodejs-client&utm_campaign=Badge_Grade)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-A Node JS wrapper client for fetching public data from [LastFm API](https://www.last.fm/api).
+A TypeScript client for the [Last.fm API](https://www.last.fm/api). Works in Node.js ≥18 and all modern browsers — no polyfills required.
 
-Fetch server side or client side, thanks to [cross-fetch](https://github.com/lquixada/cross-fetch)
+## Why use this
 
-## How to use the client
+**Zero dependencies.** The library ships no third-party runtime dependencies. HTTP requests use the native `fetch` API built into Node.js ≥18, and API signatures are generated with the built-in `node:crypto` module. Installing it won't bloat your `node_modules` or introduce supply-chain risk.
 
-Install the npm package in your project.
+**Fully typed.** Every API response has a hand-written TypeScript interface, so you get autocomplete and type safety straight out of the box — no extra `@types` packages needed.
+
+**Dual ESM + CJS.** The package ships both ES module and CommonJS builds, so it works in any Node.js project regardless of whether you use `import` or `require`.
+
+## Install
 
 ```bash
-pnpm install
+pnpm add lastfm-nodejs-client
 ```
 
-Consider [PNPM](https://pnpm.io/) ▶️
+```bash
+npm install lastfm-nodejs-client
+```
 
-### Import it
+```bash
+yarn add lastfm-nodejs-client
+```
 
-Import the client module:
+```bash
+bun add lastfm-nodejs-client
+```
 
-```js
-import { lastFm } from 'lastfm-nodejs-client';
+```ts
+// Deno
+import LastFmApi from 'jsr:@mannuelf/lastfm-nodejs-client';
 ```
 
-Import the Types as type:
+## Setup
+
+Create a `.env` file in your project root:
 
-```js
-import type {
-  Artist,
-  Track,
-  User,
-  WeeklyAlbum,
-} from 'lastfm-nodejs-client/dist/@types/lastfm.types';
+```bash
+LASTFM_API_BASE_URL="https://ws.audioscrobbler.com/2.0/"
+LASTFM_USER="your_username"
+LASTFM_API_KEY="your_api_key"
+LASTFM_APPNAME="your_app_name"
+LASTFM_SHARED_SECRET="your_shared_secret"
 ```
 
-_Working on getting these into [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped)_
+Get your API key at [last.fm/api/account/create](https://www.last.fm/api/account/create).
+
+## Usage
 
-### Use it
+```ts
+import LastFmApi from 'lastfm-nodejs-client';
 
-```js
 const lastFm = LastFmApi();
-const { config, method } = lastFm;
-
-const getTopArtists = async () => {
-  const data = await lastFm.getTopArtists(
-    method.user.top_artists,
-    config.username,
-    'overall',
-    '200',
-  );
-  const { topartists } = data;
-  return topartists;
-};
+const { method } = lastFm;
 ```
 
-🚀 Gives you:
-
-![user](https://res.cloudinary.com/mannuel/image/upload/v1668059500/topartist.png)
+### Get a user's top artists
 
-## Developing client
+```ts
+import LastFmApi from 'lastfm-nodejs-client';
+import type { TopArtistsResponse } from 'lastfm-nodejs-client';
 
-Written in TypeScript, compiles down to ES2015, provides the types for the lastFm entities.
+const lastFm = LastFmApi();
+const { method } = lastFm;
 
-## Fork repo
+const data: TopArtistsResponse = await lastFm.getTopArtists(
+  method.user.getTopArtists,
+  'your_username',
+  'overall', // period: overall | 7day | 1month | 3month | 6month | 12month
+  '10', // limit
+);
 
-```bash
-gh repo fork mannuelf/lastfm-nodejs-client
+console.log(data.topartists.artist);
 ```
 
-What's gh? [Get it here](https://cli.github.com/manual/gh_repo_fork)
+### Get a user's recent tracks
 
-### Postman collections
+```ts
+import LastFmApi from 'lastfm-nodejs-client';
+import type { RecentTracksResponse } from 'lastfm-nodejs-client';
 
-A list of endpoints currently mapped to this client. Still under development, not feature complete.
+const lastFm = LastFmApi();
+const { method } = lastFm;
 
-[View collections](https://documenter.getpostman.com/view/4217/2s8YKJELqJ) ▶️
+const data: RecentTracksResponse = await lastFm.getRecentTracks(
+  method.user.getRecentTracks,
+  'your_username',
+  '10', // limit
+);
 
-### ENV
+console.log(data.recenttracks.track);
+```
 
-Create `.env` file in project root:
+### Get artist info
 
-You do not need an API key to query the public USER entity, add only base url and a username to env file.
+```ts
+import LastFmApi from 'lastfm-nodejs-client';
+import type { ArtistInfoResponse } from 'lastfm-nodejs-client';
 
-```bash
-LASTFM_API_BASE_URL=""
-LASTFM_USER=""
-```
+const lastFm = LastFmApi();
+const { method } = lastFm;
 
-For everything else you will need to include:
+const data: ArtistInfoResponse = await lastFm.artist.artistGetInfo(
+  method.artist.getInfo,
+  'Radiohead',
+);
 
-```bash
-LASTFM_API_KEY=""
-LASTFM_APPNAME=""
+console.log(data.artist);
 ```
 
-Create them [here](https://www.last.fm/api/account/create).
+### Get album info
 
-### Develop
+```ts
+import LastFmApi from 'lastfm-nodejs-client';
+import type { AlbumInfoResponse } from 'lastfm-nodejs-client';
 
-```bash
-pnpm test
+const lastFm = LastFmApi();
+const { method } = lastFm;
+
+const data: AlbumInfoResponse = await lastFm.album.albumGetInfo(
+  method.album.getInfo,
+  'Radiohead',
+  'OK Computer',
+);
+
+console.log(data.album);
 ```
 
-```bash
-pnpm lint
-pnpm lint-fix
+### Search for a track
+
+```ts
+import LastFmApi from 'lastfm-nodejs-client';
+import type { TrackSearchResponse } from 'lastfm-nodejs-client';
+
+const lastFm = LastFmApi();
+const { method } = lastFm;
+
+const data: TrackSearchResponse = await lastFm.track.trackSearch(
+  method.track.search,
+  'Creep',
+  'Radiohead', // optional artist filter
+  '5', // limit
+);
+
+console.log(data.results.trackmatches.track);
 ```
 
-### Build
+### Love a track (authenticated)
 
-```bash
-pnpm build
+Requires a session key (`sk`) obtained via `auth.getMobileSession` or `auth.getSession`.
+
+```ts
+import LastFmApi from 'lastfm-nodejs-client';
+
+const lastFm = LastFmApi();
+const { method } = lastFm;
+
+await lastFm.track.trackLove(method.track.love, 'Radiohead', 'Creep', 'your_session_key');
 ```
 
-### Publish
+## All available namespaces
+
+| Namespace | Methods                                                                                                                                                                                                           |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `album`   | `albumGetInfo`, `albumGetTags`, `albumGetTopTags`, `albumSearch`, `albumAddTags`, `albumRemoveTag`                                                                                                                |
+| `artist`  | `artistGetInfo`, `artistGetSimilar`, `artistGetTags`, `artistGetTopAlbums`, `artistGetTopTags`, `artistGetTopTracks`, `artistSearch`, `artistAddTags`, `artistRemoveTag`, `artistGetCorrection`                   |
+| `auth`    | `getToken`, `getSession`, `getMobileSession`                                                                                                                                                                      |
+| `chart`   | `chartTopArtists`, `chartTopTracks`, `chartTopTags`                                                                                                                                                               |
+| `geo`     | `geoGetTopArtists`, `geoGetTopTracks`                                                                                                                                                                             |
+| `library` | `libraryGetArtists`                                                                                                                                                                                               |
+| `tag`     | `tagGetInfo`, `tagGetSimilar`, `tagGetTopAlbums`, `tagGetTopArtists`, `tagGetTopTags`, `tagGetWeeklyChartList`, `tagTopTracks`                                                                                    |
+| `track`   | `trackGetInfo`, `trackGetSimilar`, `trackGetTags`, `trackGetTopTags`, `trackSearch`, `trackLove`, `trackUnlove`, `trackAddTags`, `trackRemoveTag`, `trackScrobble`, `trackUpdateNowPlaying`, `trackGetCorrection` |
+| `user`    | `userGetPersonalTags`                                                                                                                                                                                             |
+
+Legacy flat methods also available: `getTopArtists`, `getTopTracks`, `getRecentTracks`, `getLovedTracks`, `getInfo`, `getFriends`, `getUserTopTags`, `getWeeklyAlbumChart`, `getWeeklyArtistChart`, `getWeeklyChartList`, `getWeeklyTrackChart`, `getTopAlbums`.
+
+## Developing
 
 ```bash
-pnpm prepare
-pnpm publish
+gh repo fork mannuelf/lastfm-nodejs-client
 ```
 
-### Why I built this?
-
-I was building a scrobbles page [https://mannuelferreira.com/scrobbles](https://mannuelferreira.com/scrobbles) and I thought others might want it to.
+```bash
+pnpm install
+pnpm test
+pnpm lint
+pnpm build
+```
 
-### TODO
+### Why I built this
 
-- move types into [DefinitelyTyped](https://github.com/mannuelf/DefinitelyTyped)
+I was building a scrobbles page at [mannuelferreira.com/scrobbles](https://mannuelferreira.com/scrobbles) and thought others might find it useful.

package/dist/@types/album/addTags.d.ts

@@ -1,2 +1,13 @@
 import type { AuthResponse } from '../lastfm.types.js';
+/**
+ * Tag an album using a list of user-supplied tags. Requires authentication.
+ *
+ * @see https://www.last.fm/api/show/album.addTags
+ * @param method - The Last.fm API method string (`method.album.addTags`)
+ * @param artist - The artist name
+ * @param album - The album name
+ * @param tags - A comma-separated list of tags to apply (max 10)
+ * @param sk - A session key obtained via the auth flow
+ * @returns Authentication response confirming the operation
+ */
 export declare function albumAddTags(method: string, artist: string, album: string, tags: string, sk: string): Promise<AuthResponse>;

package/dist/@types/album/getInfo.d.ts

@@ -1,2 +1,13 @@
 import type { AlbumInfoResponse } from '../lastfm.types.js';
+/**
+ * Get the metadata and tracklist for an album on Last.fm.
+ *
+ * @see https://www.last.fm/api/show/album.getInfo
+ * @param method - The Last.fm API method string (`method.album.getInfo`)
+ * @param artist - The artist name
+ * @param album - The album name
+ * @param autocorrect - Set to `'1'` to auto-correct misspelled names (default `'1'`)
+ * @param lang - ISO 639 alpha-2 language code for the biography text (default `'en'`)
+ * @returns Album metadata including tracklist, wiki, and tags
+ */
 export declare function albumGetInfo(method: string, artist: string, album: string, autocorrect?: string, lang?: string): Promise<AlbumInfoResponse>;

package/dist/@types/album/getTags.d.ts

@@ -1,2 +1,13 @@
 import type { AlbumTagsResponse } from '../lastfm.types.js';
+/**
+ * Get the tags applied by an individual user to an album on Last.fm.
+ *
+ * @see https://www.last.fm/api/show/album.getTags
+ * @param method - The Last.fm API method string (`method.album.getTags`)
+ * @param artist - The artist name
+ * @param album - The album name
+ * @param user - The Last.fm username whose tags to retrieve
+ * @param autocorrect - Set to `'1'` to auto-correct misspelled names (default `'1'`)
+ * @returns Tags applied by the user to this album
+ */
 export declare function albumGetTags(method: string, artist: string, album: string, user: string, autocorrect?: string): Promise<AlbumTagsResponse>;

package/dist/@types/album/getTopTags.d.ts

@@ -1,2 +1,12 @@
 import type { AlbumTopTagsResponse } from '../lastfm.types.js';
+/**
+ * Get the top tags applied to an album on Last.fm, ordered by tag count.
+ *
+ * @see https://www.last.fm/api/show/album.getTopTags
+ * @param method - The Last.fm API method string (`method.album.getTopTags`)
+ * @param artist - The artist name
+ * @param album - The album name
+ * @param autocorrect - Set to `'1'` to auto-correct misspelled names (default `'1'`)
+ * @returns Top tags for the album ordered by tag count
+ */
 export declare function albumGetTopTags(method: string, artist: string, album: string, autocorrect?: string): Promise<AlbumTopTagsResponse>;

package/dist/@types/album/removeTag.d.ts

@@ -1,2 +1,13 @@
 import type { AuthResponse } from '../lastfm.types.js';
+/**
+ * Remove a user-applied tag from an album. Requires authentication.
+ *
+ * @see https://www.last.fm/api/show/album.removeTag
+ * @param method - The Last.fm API method string (`method.album.removeTag`)
+ * @param artist - The artist name
+ * @param album - The album name
+ * @param tag - A single tag to remove from the album
+ * @param sk - A session key obtained via the auth flow
+ * @returns Authentication response confirming the operation
+ */
 export declare function albumRemoveTag(method: string, artist: string, album: string, tag: string, sk: string): Promise<AuthResponse>;

package/dist/@types/album/search.d.ts

@@ -1,2 +1,12 @@
 import type { AlbumSearchResponse } from '../lastfm.types.js';
+/**
+ * Search for an album by name on Last.fm. Returns paginated results.
+ *
+ * @see https://www.last.fm/api/show/album.search
+ * @param method - The Last.fm API method string (`method.album.search`)
+ * @param album - The album name to search for
+ * @param limit - Number of results per page (default `'30'`)
+ * @param page - Page number to fetch (default `'1'`)
+ * @returns Paginated album search results
+ */
 export declare function albumSearch(method: string, album: string, limit?: string, page?: string): Promise<AlbumSearchResponse>;

package/dist/@types/artist/addTags.d.ts

@@ -1,2 +1,12 @@
 import type { AuthResponse } from '../lastfm.types.js';
+/**
+ * Tag an artist using a list of user-supplied tags. Requires authentication.
+ *
+ * @see https://www.last.fm/api/show/artist.addTags
+ * @param method - The Last.fm API method string (`method.artist.addTags`)
+ * @param artist - The artist name
+ * @param tags - A comma-separated list of tags to apply (max 10)
+ * @param sk - A session key obtained via the auth flow
+ * @returns Authentication response confirming the operation
+ */
 export declare function artistAddTags(method: string, artist: string, tags: string, sk: string): Promise<AuthResponse>;

package/dist/@types/artist/getCorrection.d.ts

@@ -1,2 +1,11 @@
 import type { ArtistCorrectionResponse } from '../lastfm.types.js';
+/**
+ * Use the Last.fm corrections data to check whether the supplied artist has a correction
+ * to a canonical artist name.
+ *
+ * @see https://www.last.fm/api/show/artist.getCorrection
+ * @param method - The Last.fm API method string (`method.artist.getCorrection`)
+ * @param artist - The artist name to check for a correction
+ * @returns The corrected canonical artist name if one exists
+ */
 export declare function artistGetCorrection(method: string, artist: string): Promise<ArtistCorrectionResponse>;

package/dist/@types/artist/getInfo.d.ts

@@ -1,2 +1,12 @@
 import type { ArtistInfoResponse } from '../lastfm.types.js';
+/**
+ * Get the metadata for an artist on Last.fm. Includes biography, tags, and similar artists.
+ *
+ * @see https://www.last.fm/api/show/artist.getInfo
+ * @param method - The Last.fm API method string (`method.artist.getInfo`)
+ * @param artist - The artist name
+ * @param autocorrect - Set to `'1'` to auto-correct misspelled names (default `'1'`)
+ * @param lang - ISO 639 alpha-2 language code for the biography text (default `'en'`)
+ * @returns Artist metadata including biography, similar artists, and top tags
+ */
 export declare function artistGetInfo(method: string, artist: string, autocorrect?: string, lang?: string): Promise<ArtistInfoResponse>;

package/dist/@types/artist/getSimilar.d.ts

@@ -1,2 +1,12 @@
 import type { ArtistSimilarResponse } from '../lastfm.types.js';
+/**
+ * Get all the artists similar to this artist.
+ *
+ * @see https://www.last.fm/api/show/artist.getSimilar
+ * @param method - The Last.fm API method string (`method.artist.getSimilar`)
+ * @param artist - The artist name
+ * @param limit - Maximum number of similar artists to return (default `'30'`)
+ * @param autocorrect - Set to `'1'` to auto-correct misspelled names (default `'1'`)
+ * @returns A list of similar artists with match scores
+ */
 export declare function artistGetSimilar(method: string, artist: string, limit?: string, autocorrect?: string): Promise<ArtistSimilarResponse>;

package/dist/@types/artist/getTags.d.ts

@@ -1,2 +1,12 @@
 import type { ArtistTagsResponse } from '../lastfm.types.js';
+/**
+ * Get the tags applied by an individual user to an artist on Last.fm.
+ *
+ * @see https://www.last.fm/api/show/artist.getTags
+ * @param method - The Last.fm API method string (`method.artist.getTags`)
+ * @param artist - The artist name
+ * @param user - The Last.fm username whose tags to retrieve
+ * @param autocorrect - Set to `'1'` to auto-correct misspelled names (default `'1'`)
+ * @returns Tags applied by the user to this artist
+ */
 export declare function artistGetTags(method: string, artist: string, user: string, autocorrect?: string): Promise<ArtistTagsResponse>;

package/dist/@types/artist/getTopAlbums.d.ts

@@ -1,2 +1,13 @@
 import type { ArtistTopAlbumsResponse } from '../lastfm.types.js';
+/**
+ * Get the top albums for an artist on Last.fm, ordered by popularity.
+ *
+ * @see https://www.last.fm/api/show/artist.getTopAlbums
+ * @param method - The Last.fm API method string (`method.artist.getTopAlbums`)
+ * @param artist - The artist name
+ * @param limit - Number of results per page (default `'50'`)
+ * @param page - Page number to fetch (default `'1'`)
+ * @param autocorrect - Set to `'1'` to auto-correct misspelled names (default `'1'`)
+ * @returns Paginated list of the artist's top albums
+ */
 export declare function artistGetTopAlbums(method: string, artist: string, limit?: string, page?: string, autocorrect?: string): Promise<ArtistTopAlbumsResponse>;

package/dist/@types/artist/getTopTags.d.ts

@@ -1,2 +1,11 @@
 import type { ArtistTopTagsResponse } from '../lastfm.types.js';
+/**
+ * Get the top tags for an artist on Last.fm, ordered by popularity.
+ *
+ * @see https://www.last.fm/api/show/artist.getTopTags
+ * @param method - The Last.fm API method string (`method.artist.getTopTags`)
+ * @param artist - The artist name
+ * @param autocorrect - Set to `'1'` to auto-correct misspelled names (default `'1'`)
+ * @returns Top tags for the artist ordered by tag count
+ */
 export declare function artistGetTopTags(method: string, artist: string, autocorrect?: string): Promise<ArtistTopTagsResponse>;

package/dist/@types/artist/getTopTracks.d.ts

@@ -1,2 +1,13 @@
 import type { ArtistTopTracksResponse } from '../lastfm.types.js';
+/**
+ * Get the top tracks for an artist on Last.fm, ordered by popularity.
+ *
+ * @see https://www.last.fm/api/show/artist.getTopTracks
+ * @param method - The Last.fm API method string (`method.artist.getTopTracks`)
+ * @param artist - The artist name
+ * @param limit - Number of results per page (default `'50'`)
+ * @param page - Page number to fetch (default `'1'`)
+ * @param autocorrect - Set to `'1'` to auto-correct misspelled names (default `'1'`)
+ * @returns Paginated list of the artist's top tracks
+ */
 export declare function artistGetTopTracks(method: string, artist: string, limit?: string, page?: string, autocorrect?: string): Promise<ArtistTopTracksResponse>;

package/dist/@types/artist/removeTag.d.ts

@@ -1,2 +1,12 @@
 import type { AuthResponse } from '../lastfm.types.js';
+/**
+ * Remove a user-applied tag from an artist. Requires authentication.
+ *
+ * @see https://www.last.fm/api/show/artist.removeTag
+ * @param method - The Last.fm API method string (`method.artist.removeTag`)
+ * @param artist - The artist name
+ * @param tag - A single tag to remove from the artist
+ * @param sk - A session key obtained via the auth flow
+ * @returns Authentication response confirming the operation
+ */
 export declare function artistRemoveTag(method: string, artist: string, tag: string, sk: string): Promise<AuthResponse>;

package/dist/@types/artist/search.d.ts

@@ -1,2 +1,12 @@
 import type { ArtistSearchResponse } from '../lastfm.types.js';
+/**
+ * Search for an artist by name on Last.fm. Returns paginated results.
+ *
+ * @see https://www.last.fm/api/show/artist.search
+ * @param method - The Last.fm API method string (`method.artist.search`)
+ * @param artist - The artist name to search for
+ * @param limit - Number of results per page (default `'30'`)
+ * @param page - Page number to fetch (default `'1'`)
+ * @returns Paginated artist search results
+ */
 export declare function artistSearch(method: string, artist: string, limit?: string, page?: string): Promise<ArtistSearchResponse>;

package/dist/@types/auth/getMobileSession.d.ts

@@ -1,2 +1,13 @@
 import type { AuthMobileSessionResponse } from '../lastfm.types.js';
+/**
+ * Create a session for a user using their username and password (mobile auth flow).
+ *
+ * The returned session key can be used for authenticated write operations.
+ *
+ * @see https://www.last.fm/api/show/auth.getMobileSession
+ * @param method - The Last.fm API method string (`method.auth.getMobileSession`)
+ * @param username - The Last.fm username
+ * @param password - The user's plaintext password
+ * @returns A session key valid for write operations
+ */
 export declare function authGetMobileSession(method: string, username: string, password: string): Promise<AuthMobileSessionResponse>;

package/dist/@types/auth/getSession.d.ts

@@ -1,2 +1,12 @@
 import type { AuthSessionResponse } from '../lastfm.types.js';
+/**
+ * Fetch a session key for a user after they have authorised a token via the Last.fm web auth flow.
+ *
+ * Tokens are valid for 60 minutes and can only be used once.
+ *
+ * @see https://www.last.fm/api/show/auth.getSession
+ * @param method - The Last.fm API method string (`method.auth.getSession`)
+ * @param token - The token previously granted by `auth.getToken` and authorised by the user
+ * @returns A session key valid for write operations
+ */
 export declare function authGetSession(method: string, token: string): Promise<AuthSessionResponse>;

package/dist/@types/auth.d.ts

@@ -1,12 +1,15 @@
 import { type AuthResponse } from './lastfm.types.js';
 /**
- * POST: Auth - LastFM
+ * Fetch an unauthenticated token for the web auth flow.
  *
- * https://www.last.fm/api/show/auth.getToken
+ * Tokens are API-account-specific, valid for 60 minutes, and consumed
+ * once a session is created via `auth.getSession`.
  *
- * Authentication tokens are API account specific.
- * They are valid for 60 minutes from the moment they are granted.
- * Can only used once (they are consumed when a session is created).
- * @returns Auth token
+ * @see https://www.last.fm/api/show/auth.getToken
+ * @param method - The Last.fm API method string (`method.auth.getToken`)
+ * @param user - The Last.fm username
+ * @param period - The time period parameter
+ * @param limit - The limit parameter
+ * @returns An unauthenticated token to redirect the user to the Last.fm auth page
  */
 export declare function auth(method: string, user: string, period: string, limit: string): Promise<AuthResponse>;

package/dist/@types/chart/topArtists.d.ts

@@ -1,2 +1,13 @@
 import type { ChartTopArtistResponse } from '../lastfm.types.js';
+/**
+ * Get the top artists chart on Last.fm.
+ *
+ * @see https://www.last.fm/api/show/chart.getTopArtists
+ * @param method - The Last.fm API method string (`method.chart.getTopArtists`)
+ * @param user - The Last.fm username
+ * @param period - The time period over which to retrieve the chart
+ * @param page - Page number to fetch
+ * @param limit - Number of results per page
+ * @returns Paginated list of the most popular artists globally
+ */
 export declare function chartTopArtists(method: string, user: string, period: string, page: string, limit: string): Promise<ChartTopArtistResponse>;

package/dist/@types/chart/topTags.d.ts

@@ -1,2 +1,10 @@
 import type { ChartTopTagsResponse } from '../lastfm.types.js';
+/**
+ * Get the top tags chart on Last.fm, ordered by tag popularity.
+ *
+ * @see https://www.last.fm/api/show/chart.getTopTags
+ * @param method - The Last.fm API method string (`method.chart.getTopTags`)
+ * @param page - Page number to fetch
+ * @returns Paginated list of the most popular tags globally
+ */
 export declare function chartTopTags(method: string, page: string): Promise<ChartTopTagsResponse>;

package/dist/@types/chart/topTracks.d.ts

@@ -1,2 +1,10 @@
 import type { ChartTopTracksResponse } from '../lastfm.types.js';
+/**
+ * Get the top tracks chart on Last.fm.
+ *
+ * @see https://www.last.fm/api/show/chart.getTopTracks
+ * @param method - The Last.fm API method string (`method.chart.getTopTracks`)
+ * @param page - Page number to fetch
+ * @returns Paginated list of the most popular tracks globally
+ */
 export declare function chartTopTracks(method: string, page: string): Promise<ChartTopTracksResponse>;

package/dist/@types/config.d.ts

@@ -1,13 +1,4 @@
-/**
- * @description Stores the Last.fm API key, app name, base url, format, shared secret, and username.
- * Simply add a .env file to the root of the project and add the following:
- * LASTFM_API_KEY=your_api_key
- * LASTFM_APPNAME=your_app_name
- * LASTFM_API_BASE_URL=your_base_url
- * LASTFM_SHARED_SECRET=your_shared_secret
- * LASTFM_USER=your_username
- */
-export declare const config: {
+interface Config {
     api_key: string;
     app_name: string;
     base_url: string;
@@ -17,4 +8,15 @@ export declare const config: {
     };
     share_secret: string;
     username: string;
-};
+}
+/**
+ * @description Stores the Last.fm API key, app name, base url, format, shared secret, and username.
+ * Simply add a .env file to the root of the project and add the following:
+ * LASTFM_API_KEY=your_api_key
+ * LASTFM_APPNAME=your_app_name
+ * LASTFM_API_BASE_URL=your_base_url
+ * LASTFM_SHARED_SECRET=your_shared_secret
+ * LASTFM_USER=your_username
+ */
+export declare const config: Config;
+export {};

package/dist/@types/createOptions.d.ts

@@ -1,3 +1,26 @@
+/**
+ * Builds a request options object for use with `request` or `signedRequest`.
+ *
+ * @param method - The Last.fm API method string (e.g. `'user.getInfo'`)
+ * @param user - Last.fm username
+ * @param period - Time period (`overall`, `7day`, `1month`, `3month`, `6month`, `12month`)
+ * @param limit - Number of results to return per page
+ * @param page - Page number for paginated results (1-indexed)
+ * @param from - Unix timestamp; only return scrobbles after this time
+ * @param tag - Tag name
+ * @param artist - Artist name
+ * @param album - Album title
+ * @param track - Track title
+ * @param country - Country name as defined by the ISO 3166-1 standard
+ * @param autocorrect - Set to `'1'` to auto-correct misspelled artist/track names
+ * @param mbid - MusicBrainz ID for the resource
+ * @param lang - ISO 639 alpha-2 language code for localised text (default `'en'`)
+ * @param sk - Session key obtained via the auth flow
+ * @param token - Authentication token from `auth.getToken`
+ * @param tags - Comma-separated list of user-supplied tags (max 10)
+ * @param timestamp - Unix timestamp of the scrobble
+ * @returns A request options object ready to pass to `request` or `signedRequest`
+ */
 export declare function createOptions(method: string, user: string, period?: string, limit?: string, page?: string, from?: string, tag?: string, artist?: string, album?: string, track?: string, country?: string, autocorrect?: string, mbid?: string, lang?: string, sk?: string, token?: string, tags?: string, timestamp?: string): {
     method: string;
     page: string | undefined;