@ansango/lastfm-api 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -9,6 +9,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > [ansango/lastfm-api](https://github.com/ansango/lastfm-api). Entries below preserve the
 > historical package and repository names used by their original releases.
 
+## [3.6.0] - 2026-08-29
+
+### ✨ Features
+
+- **watcher**: implement real-time scrobble watcher and event emitter (closes #164, #165) (#167) ([a9545a1](https://github.com/ansango/lastfm-api/commit/a9545a1))
+- **cache**: implement pluggable cache layer (closes #163) (#166) ([4eaa1e0](https://github.com/ansango/lastfm-api/commit/4eaa1e0))
+
+### ♻️ Code Refactoring
+
+- **index**: remove dotenv loading for environment variables ([57236a6](https://github.com/ansango/lastfm-api/commit/57236a6))
+
+### 🔧 Chores
+
+- **docs**: update README with complete v3.5.0 features and remove dotenv and test-real ([e2abeb9](https://github.com/ansango/lastfm-api/commit/e2abeb9))
+
+
+## [3.5.0] - 2026-08-29
+
+### ✨ Features
+
+- **exporter**: implement exporter namespace (closes #157) (#161) ([d7385ff](https://github.com/ansango/lastfm-api/commit/d7385ff))
+- **playlists**: implement playlists namespace (closes #156) (#160) ([9113b17](https://github.com/ansango/lastfm-api/commit/9113b17))
+- **reports**: implement reports namespace (closes #155) (#159) ([b5524e1](https://github.com/ansango/lastfm-api/commit/b5524e1))
+- **core**: implement automatic async pagination and streaming iterators (closes #154) (#158) ([406caa0](https://github.com/ansango/lastfm-api/commit/406caa0))
+- **insights**: implement compareTasteGroup (closes #143) (#150) ([49b69b4](https://github.com/ansango/lastfm-api/commit/49b69b4))
+- **insights**: implement getSmartRecommendations and getBridgeArtists (closes #142) (#149) ([3b2b2f2](https://github.com/ansango/lastfm-api/commit/3b2b2f2))
+- **insights**: implement getGenreBreakdown and getGenreEvolution (closes #141) (#148) ([4c82e23](https://github.com/ansango/lastfm-api/commit/4c82e23))
+- **insights**: implement getAlbumHabits (closes #140) (#147) ([0b9ceeb](https://github.com/ansango/lastfm-api/commit/0b9ceeb))
+- **insights**: implement getListeningStreaks and getListeningHeatmap (closes #139) (#146) ([756b4de](https://github.com/ansango/lastfm-api/commit/756b4de))
+- **insights**: implement getForgottenFavorites and getObsessions (closes #138) (#145) ([aac4776](https://github.com/ansango/lastfm-api/commit/aac4776))
+- **insights**: implement getObscurityScore (closes #137) (#144) ([83be889](https://github.com/ansango/lastfm-api/commit/83be889))
+
+### 🐛 Bug Fixes
+
+- **ci**: point test-real to src and smoke-test core entrypoints ([847da33](https://github.com/ansango/lastfm-api/commit/847da33))
+
+### ♻️ Code Refactoring
+
+- **arch**: decouple core canonical API from insights engine (closes #151) (#152) ([6e3b261](https://github.com/ansango/lastfm-api/commit/6e3b261))
+
+### 📚 Documentation
+
+- **insights**: document 11 new analytical methods in README and api-coverage (closes #136) ([35f5d60](https://github.com/ansango/lastfm-api/commit/35f5d60))
+
+### 🔧 Chores
+
+- **release**: bump version to v3.5.0 ([abcc3c7](https://github.com/ansango/lastfm-api/commit/abcc3c7))
+
+
+## [3.5.0] - 2026-08-29
+
+### ✨ Features
+
+- **watcher**: implement real-time scrobble watcher and event emitter (closes #164, #165) (#167) ([a9545a1](https://github.com/ansango/lastfm-api/commit/a9545a1))
+- **cache**: implement pluggable cache layer (closes #163) (#166) ([4eaa1e0](https://github.com/ansango/lastfm-api/commit/4eaa1e0))
+
+### ♻️ Code Refactoring
+
+- **index**: remove dotenv loading for environment variables ([57236a6](https://github.com/ansango/lastfm-api/commit/57236a6))
+
+### 🔧 Chores
+
+- **docs**: update README with complete v3.5.0 features and remove dotenv and test-real ([e2abeb9](https://github.com/ansango/lastfm-api/commit/e2abeb9))
+
+
 ## [3.4.0] - 2026-08-28
 
 ### ✨ Features

package/README.md

@@ -15,7 +15,13 @@ A universal Last.fm API client for Node.js and Browser, written in TypeScript.
 
 - ✅ **Universal**: Works in Node.js (≥20.0.0) and Browser
 - ✅ **Complete coverage**: All 56 canonical Last.fm API methods across 9 namespaces
-- ✅ **Insights & Analytics Engine**: 9 high-level derived analytical views (Shannon diversity, enriched Now Playing, diurnal histograms, binge runs, ranking diffs, new discoveries, 2D mood classification, personality archetypes, and Jaccard user comparison)
+- ✅ **Insights & Analytics Engine**: 20 high-level derived analytical views (Shannon diversity, enriched Now Playing, diurnal histograms, binge runs, ranking diffs, new discoveries, 2D mood classification, personality archetypes, obscurity scores, streaks, heatmaps, album habits, genre breakdown & evolution, smart recommendations, bridge artists, and user/group comparison)
+- ✅ **Pluggable Cache Layer**: Zero-dependency caching for GET/read requests with `MemoryCacheStore` (LRU) and `StorageCacheStore` (localStorage), plus granular TTL by namespace/method
+- ✅ **Real-Time Scrobble Watcher**: Isomorphic event-driven listening monitor emitting `nowPlaying`, `nowPlayingEnd`, `scrobble`, and `idle` events
+- ✅ **Reports & Wrapped Engine**: Custom Year-in-Review, historical milestone projections, and monthly digests
+- ✅ **Smart Playlists Generator**: Algorithmic playlist generation (heavy rotation, time capsule, deep cuts, discovery radar) with M3U and CSV exports
+- ✅ **Bulk Data Exporter & Backup**: Resilient scrobble, loved tracks, and library catalog backup with UTS checkpointing and ListenBrainz/JSONL/CSV formats
+- ✅ **Async Pagination & Streaming**: Native `for await` streaming iterators (`iterateItems`, `collectAll`, `iteratePages`) with automatic rate limiting and boundary controls
 - ✅ **TypeScript**: Full type safety with comprehensive type definitions
 - ✅ **Zod Schemas**: Runtime validation schemas for all types
 - ✅ **ESM**: Modern ES modules with tree-shaking support
@@ -31,6 +37,14 @@ A universal Last.fm API client for Node.js and Browser, written in TypeScript.
   - [Using the Client Class](#using-the-client-class)
   - [Using Global Configuration](#using-global-configuration)
   - [Using Individual Services](#using-individual-services)
+- [Zod Schema Validation](#zod-schema-validation)
+- [Pluggable Cache Layer](#pluggable-cache-layer)
+- [Real-Time Scrobble Watcher](#real-time-scrobble-watcher)
+- [Insights & Analytics Engine](#insights--analytics-engine)
+- [Reports & Wrapped Engine](#reports--wrapped-engine)
+- [Smart Playlists Generator](#smart-playlists-generator)
+- [Bulk Data Exporter & Backup](#bulk-data-exporter--backup)
+- [Async Pagination & Streaming Iterators](#async-pagination--streaming-iterators)
 - [Environment Variables](#environment-variables)
 - [Authentication & Scrobbling](#authentication--scrobbling)
 - [Error Handling](#error-handling)
@@ -213,6 +227,7 @@ const tracks = await trackService.search({ track: 'Come Together' });
 ```
 
 **Available service imports:**
+- `@ansango/lastfm-api/core` (canonical methods + pagination)
 - `@ansango/lastfm-api/user`
 - `@ansango/lastfm-api/album`
 - `@ansango/lastfm-api/artist`
@@ -222,7 +237,12 @@ const tracks = await trackService.search({ track: 'Come Together' });
 - `@ansango/lastfm-api/geo`
 - `@ansango/lastfm-api/library`
 - `@ansango/lastfm-api/auth`
+- `@ansango/lastfm-api/cache`
+- `@ansango/lastfm-api/watcher`
 - `@ansango/lastfm-api/insights`
+- `@ansango/lastfm-api/reports`
+- `@ansango/lastfm-api/playlists`
+- `@ansango/lastfm-api/exporter`
 
 ## Zod Schema Validation
 
@@ -236,6 +256,12 @@ Schemas are available through modular imports, following the same pattern as the
 import { userGetInfoRequestSchema, userGetInfoResponseSchema } from '@ansango/lastfm-api/user/schemas';
 import { albumSearchRequestSchema } from '@ansango/lastfm-api/album/schemas';
 import { trackGetInfoResponseSchema } from '@ansango/lastfm-api/track/schemas';
+import { cacheOptionsSchema } from '@ansango/lastfm-api/cache/schemas';
+import { watcherOptionsSchema } from '@ansango/lastfm-api/watcher/schemas';
+import { insightsSummaryResponseSchema } from '@ansango/lastfm-api/insights/schemas';
+import { reportsWrappedResponseSchema } from '@ansango/lastfm-api/reports/schemas';
+import { playlistsGenerateResponseSchema } from '@ansango/lastfm-api/playlists/schemas';
+import { exporterScrobblesResponseSchema } from '@ansango/lastfm-api/exporter/schemas';
 ```
 
 ### Usage Example
@@ -262,6 +288,7 @@ if (result.success) {
 ```
 
 **Available schema imports:**
+- `@ansango/lastfm-api/core/schemas`
 - `@ansango/lastfm-api/user/schemas`
 - `@ansango/lastfm-api/album/schemas`
 - `@ansango/lastfm-api/artist/schemas`
@@ -271,12 +298,88 @@ if (result.success) {
 - `@ansango/lastfm-api/geo/schemas`
 - `@ansango/lastfm-api/library/schemas`
 - `@ansango/lastfm-api/auth/schemas`
+- `@ansango/lastfm-api/cache/schemas`
+- `@ansango/lastfm-api/watcher/schemas`
 - `@ansango/lastfm-api/insights/schemas`
+- `@ansango/lastfm-api/reports/schemas`
+- `@ansango/lastfm-api/playlists/schemas`
+- `@ansango/lastfm-api/exporter/schemas`
 - `@ansango/lastfm-api/schemas` (base types like `imageSchema`, `datePropSchema`, etc.)
 
+## Pluggable Cache Layer
+
+Transparent caching for read (`GET`) operations with configurable TTLs, LRU eviction, and interchangeable storage backends:
+
+```typescript
+import { LastFmClient, MemoryCacheStore, StorageCacheStore } from '@ansango/lastfm-api';
+
+// 1. Enable in-memory cache with granular TTL policies
+const client = new LastFmClient({
+  apiKey: 'YOUR_API_KEY',
+  cache: {
+    defaultTtlMs: 300_000, // 5 minutes default
+    ttlByNamespace: {
+      artist: 86_400_000, // 24 hours for artist metadata
+      user: 60_000,       // 1 minute for user endpoints
+    },
+    ttlByMethod: {
+      'user.getRecentTracks': 15_000, // 15 seconds for recent tracks
+    },
+  },
+});
+
+// 2. First call performs network fetch; second call hits cache instantly
+const artist1 = await client.artist.getInfo({ artist: 'Radiohead' });
+const artist2 = await client.artist.getInfo({ artist: 'Radiohead' }); // Cache hit!
+
+// 3. Inspect or manage cache metrics directly
+console.log(client.cache.stats()); // { hits: 1, misses: 1, size: 1 }
+await client.cache.clear();
+```
+
+## Real-Time Scrobble Watcher
+
+Isomorphic event-driven listening monitor emitting events as playback updates in real time:
+
+```typescript
+import { LastFmClient } from '@ansango/lastfm-api';
+
+const client = new LastFmClient({ apiKey: 'YOUR_API_KEY' });
+
+// Create a watcher for a user with 10-second polling
+const watcher = client.watcher.watchUser({
+  user: 'ansango',
+  intervalMs: 10_000,
+  idleThresholdMs: 300_000, // 5 minutes without activity triggers idle
+});
+
+// Event listeners
+watcher.on('nowPlaying', (track) => {
+  console.log(`🎵 Now Playing: ${track.name} by ${track.artist}`);
+});
+
+watcher.on('nowPlayingEnd', (track) => {
+  console.log(`⏹️ Finished: ${track.name}`);
+});
+
+watcher.on('scrobble', (track) => {
+  console.log(`✅ Scrobble recorded: ${track.name} (UTS: ${track.uts})`);
+});
+
+watcher.on('idle', ({ idleMinutes }) => {
+  console.log(`💤 User has been idle for ${idleMinutes} minutes`);
+});
+
+// Start polling
+watcher.start();
+
+// Stop when done
+// watcher.stop();
+```
+
 ## Insights & Analytics Engine
 
-The package includes a built-in analytics engine providing 9 high-level derived views computed over Last.fm data:
+The package includes a comprehensive, built-in analytics engine providing 20 high-level derived views and statistical metrics computed over Last.fm data:
 
 ```typescript
 import { createClient } from '@ansango/lastfm-api';
@@ -319,6 +422,133 @@ console.log(`Archetype: ${personality.archetype.emoji} ${personality.archetype.n
 // 9. User-to-User Taste Clash (Jaccard Similarity)
 const comparison = await client.insights.compareUsers({ userA: 'ansango', userB: 'friend' });
 console.log(`Taste Compatibility: ${comparison.compatibilityScore}% (Jaccard: ${comparison.jaccard})`);
+
+// 10. Obscurity & Hipster Score (Hidden Gems & Mainstream Anchors)
+const obscurity = await client.insights.getObscurityScore({ user: 'ansango', limit: 20 });
+console.log(`Score: ${obscurity.obscurityScore}/100 (${obscurity.category})`);
+
+// 11. Forgotten Favorites (Revival Candidates)
+const forgotten = await client.insights.getForgottenFavorites({ user: 'ansango', historicPeriod: '12month', recentPeriod: '1month' });
+
+// 12. Listening Obsession Episodes
+const obsessions = await client.insights.getObsessions({ user: 'ansango', windowSize: 20, thresholdRatio: 0.35 });
+
+// 13. Consecutive Daily Streaks & Dry Spells
+const streaks = await client.insights.getListeningStreaks({ user: 'ansango' });
+console.log(`Longest Streak: ${streaks.longestStreakDays} days`);
+
+// 14. 365-Day Daily Heatmap
+const heatmap = await client.insights.getListeningHeatmap({ user: 'ansango', days: 90 });
+
+// 15. Album Habits & Cohesion Score (Album Purist vs Playlist Shuffler)
+const habits = await client.insights.getAlbumHabits({ user: 'ansango', minSessionTracks: 3 });
+console.log(`Cohesion: ${habits.cohesionScore}% (${habits.profile})`);
+
+// 16. Genre Breakdown with HHI Concentration Index
+const genres = await client.insights.getGenreBreakdown({ user: 'ansango', period: 'overall' });
+console.log(`Specialization: ${genres.specializationLevel} (HHI: ${genres.hhiIndex})`);
+
+// 17. Genre Evolution & Temporal Shifts (Rising, Fading, New)
+const evolution = await client.insights.getGenreEvolution({ user: 'ansango', currentPeriod: '1month', previousPeriod: '12month' });
+
+// 18. Smart Similarity Graph Recommendations
+const recs = await client.insights.getSmartRecommendations({ user: 'ansango', seedLimit: 5, limit: 10 });
+
+// 19. Bridge Artists Connecting Two Disparate Genres
+const bridges = await client.insights.getBridgeArtists({ tagA: 'post-punk', tagB: 'electronic' });
+
+// 20. Multi-User Taste Group Comparison (Consensus & Outlier Detection)
+const group = await client.insights.compareTasteGroup({ users: ['alice', 'bob', 'carol'], period: 'overall' });
+console.log(`Group Average Compatibility: ${group.groupAverageCompatibility}%`);
+```
+
+## Reports & Wrapped Engine
+
+Generate shareable annual recaps, historical milestones, and monthly digests:
+
+```typescript
+import { createClient } from '@ansango/lastfm-api';
+
+const client = createClient();
+
+// 1. Year in Review / Wrapped
+const wrapped = await client.reports.getWrapped({ user: 'ansango', year: 2024 });
+console.log(`Top Artist of the Year: ${wrapped.topArtists[0].name}`);
+console.log(`Summer Anthem: ${wrapped.seasons.summer.topTrack} by ${wrapped.seasons.summer.topArtist}`);
+console.log(`Busiest Day: ${wrapped.busiestDay.date} (${wrapped.busiestDay.scrobbles} plays)`);
+
+// 2. Scrobble Milestones Tracker & Projection
+const milestones = await client.reports.getMilestones({ user: 'ansango', targets: [1000, 5000, 10000, 50000] });
+console.log(`Next milestone: ${milestones.nextMilestone.target} scrobbles (ETA: ${milestones.nextMilestone.projectedDate})`);
+
+// 3. Monthly Comparative Digest
+const digest = await client.reports.getMonthlyDigest({ user: 'ansango', year: 2024, month: 2 });
+console.log(`Growth vs previous month: ${digest.growthPercentage}%`);
+```
+
+## Smart Playlists Generator
+
+Algorithmic playlist creation with direct export to standard formats:
+
+```typescript
+import { createClient } from '@ansango/lastfm-api';
+
+const client = createClient();
+
+// Generate smart playlist (time-capsule, deep-cuts, heavy-rotation, discovery-radar)
+const playlist = await client.playlists.generate({
+  user: 'ansango',
+  mode: 'time-capsule',
+  limit: 25,
+});
+
+// Pre-rendered standard formats:
+console.log(playlist.formats.m3u); // Standard #EXTM3U playlist file content
+console.log(playlist.formats.csv); // CSV spreadsheet
+console.log(playlist.formats.spotifyQueries); // Spotify search query list
+```
+
+## Bulk Data Exporter & Backup
+
+Resilient scrobble history export with checkpointing and multiple output formats:
+
+```typescript
+import { createClient } from '@ansango/lastfm-api';
+
+const client = createClient();
+
+// Export scrobbles with ListenBrainz / JSONL / CSV formatting & checkpointing
+const exportData = await client.exporter.exportScrobbles({
+  user: 'ansango',
+  format: 'listenbrainz', // 'json' | 'jsonl' | 'csv' | 'listenbrainz'
+  limit: 1000,
+});
+
+// Resumable checkpoint timestamp
+console.log(`Resume from: ${exportData.nextCheckpointUts}`);
+```
+
+## Async Pagination & Streaming Iterators
+
+Stream large Last.fm datasets seamlessly using standard `for await` loops:
+
+```typescript
+import { createClient, iterateItems } from '@ansango/lastfm-api';
+
+const client = createClient();
+
+for await (const track of iterateItems(
+  (params) => client.user.getRecentTracks(params),
+  (res) => ({
+    items: res.recenttracks?.track ?? [],
+    totalPages: Number(res.recenttracks?.['@attr']?.totalPages ?? 1),
+    currentPage: Number(res.recenttracks?.['@attr']?.page ?? 1),
+  }),
+  { user: 'ansango', limit: 200 },
+  { maxItems: 1000 }
+)) {
+  console.log(`${track.name} - ${track.artist['#text']}`);
+}
 ```
 
 ## Environment Variables
@@ -409,7 +639,7 @@ Before the browser flow works end-to-end, set a callback URL on your API account
 
 If you skip this step, the redirect after **Allow access** lands on a Last.fm error page instead of your URL, and the token is lost. You have to call `auth.getToken` again and re-authorize.
 
-> **Note:** `auth.getMobileSession` was removed in v4.0.0. Last.fm restricts that endpoint to mobile-classified API keys, which are not exposed through the public self-service create form; the browser flow above works for every API key Last.fm issues today.
+> **Note:** `auth.getMobileSession` was removed in v3.3.0. Last.fm restricts that endpoint to mobile-classified API keys, which are not exposed through the public self-service create form; the browser flow above works for every API key Last.fm issues today.
 
 ### Passing the session key to write methods
 
@@ -473,6 +703,7 @@ The main client class with all services:
 
 ```typescript
 class LastFmClient {
+  core: LastFmCoreClient;
   user: UserService;
   album: AlbumService;
   artist: ArtistService;
@@ -483,6 +714,11 @@ class LastFmClient {
   library: LibraryService;
   auth: AuthService;
   insights: InsightsService;
+  reports: ReportsService;
+  playlists: PlaylistsService;
+  exporter: ExporterService;
+  cache: CacheService;
+  watcher: WatcherService;
   
   constructor(config?: Partial<LastFmConfig>);
   getConfig(): Readonly<LastFmConfig>;
@@ -508,8 +744,9 @@ function resetGlobalConfig(): void;
 
 ### Services
 
-The package covers all 56 canonical Last.fm API methods across 9 namespaces, plus 9 derived analytical methods in the `InsightsService`. See [docs/api-coverage.md](docs/api-coverage.md) for the full table.
+The package covers all 56 canonical Last.fm API methods across 9 namespaces, plus 20 derived analytical methods in `InsightsService`, 3 reporting methods in `ReportsService`, 3 smart playlist methods in `PlaylistsService`, and 3 data export engines in `ExporterService` (83 total endpoints). See [docs/api-coverage.md](docs/api-coverage.md) for the full table.
 
+- **CoreClient (`core`)**: Bundle of all 56 canonical Last.fm methods with built-in async pagination (`iterateItems`, `collectAll`, `iteratePages`)
 - **UserService**: 13 methods — `getInfo`, `getFriends`, `getLovedTracks`, `getRecentTracks`, `getTopAlbums`, `getTopArtists`, `getTopTags`, `getTopTracks`, `getWeeklyAlbumChart`, `getWeeklyArtistChart`, `getWeeklyChartList`, `getWeeklyTrackChart`, `getPersonalTags`
 - **AlbumService**: 6 methods — `getInfo`, `getTags`, `getTopTags`, `search`, `addTags`¹, `removeTag`¹
 - **ArtistService**: 10 methods — `getInfo`, `getTags`, `getSimilar`, `getTopTags`, `getTopAlbums`, `getTopTracks`, `search`, `getCorrection`, `addTags`¹, `removeTag`¹
@@ -518,8 +755,11 @@ The package covers all 56 canonical Last.fm API methods across 9 namespaces, plu
 - **ChartService**: 3 methods — `getTopArtists`, `getTopTags`, `getTopTracks`
 - **GeoService**: 2 methods — `getTopArtists`, `getTopTracks`
 - **LibraryService**: 1 method — `getArtists`
-- **AuthService**: 2 methods — `getSession`, `getToken` (removed `getMobileSession` in v4.0.0)
-- **InsightsService**: 9 methods — `getSummary`, `getNowPlaying`, `getHoursHistogram`, `getBinges`, `getTrends`, `getDiscoveries`, `getMood`, `getPersonality`, `compareUsers`
+- **AuthService**: 2 methods — `getSession`, `getToken` (removed `getMobileSession` in v3.3.0)
+- **InsightsService**: 20 methods — `getSummary`, `getNowPlaying`, `getHoursHistogram`, `getBinges`, `getTrends`, `getDiscoveries`, `getMood`, `getPersonality`, `compareUsers`, `getObscurityScore`, `getObsessions`, `getForgottenFavorites`, `getListeningStreaks`, `getListeningHeatmap`, `getAlbumHabits`, `getGenreBreakdown`, `getGenreEvolution`, `getSmartRecommendations`, `getBridgeArtists`, `compareTasteGroup`
+- **ReportsService**: 3 methods — `getWrapped`, `getMilestones`, `getMonthlyDigest`
+- **PlaylistsService**: 3 methods — `generate`, `exportM3U`, `exportCsv`
+- **ExporterService**: 3 methods — `exportScrobbles`, `exportLovedTracks`, `exportLibrary`
 
 ¹ Requires an authenticated session.
 
@@ -574,10 +814,7 @@ bun run build
 bun run typecheck
 
 # Run deterministic unit tests (no network, mocked fetch)
-bun run test:unit
-
-# Run live integration (requires Last.fm credentials in .env)
-bun run test:integration:live
+bun run test:unit # or simply 'bun test'
 
 # Lint (Biome — formatter + linter, single command)
 bun run lint
@@ -599,10 +836,10 @@ bun run clean
 ## Interactive API Explorer
 
 The repo ships with a local Hono + Scalar server under `tool/api-scalar/`
-that turns the package into a fully interactive OpenAPI explorer. All 57
-canonical Last.fm methods are wired declaratively from the package's own
-Zod schemas and service functions — no method is hand-written, no schema
-is duplicated.
+that turns the package into a fully interactive OpenAPI explorer. All 56
+canonical Last.fm methods and 27 extension methods (83 total operations)
+are wired declaratively into 5 collapsible sections from the package's
+own Zod schemas and service functions.
 
 ```sh
 bun install --cwd tool/api-scalar
@@ -618,14 +855,10 @@ for the design notes.
 
 ### Testing
 
-The test suite is split into two layers:
-
-- **`bun run test:unit`** — deterministic tests with mocked `globalThis.fetch`. They cover every canonical Last.fm method that the package implements, assert the correct `namespace.method` routing, validate that `api_key`/`format=json` are present, and verify that Last.fm error envelopes surface as `LastFmApiError`. They do not require an API key or any network access, and they run as part of CI on every push and pull request.
-- **`bun run test:integration:live`** — runs `test-real.ts` against the real Last.fm API. It is **not** part of CI and must be invoked manually by a developer with valid credentials in `.env`.
-
-The `bun test` alias points to the deterministic suite, so a normal `bun test` is safe to run anywhere.
+The test suite consists of deterministic unit tests with mocked `globalThis.fetch`:
 
-An `inventory.test.ts` file asserts the **57/57 canonical-method baseline** — every namespace.method pair listed in the official Last.fm API index is exposed on the `LastFmClient` and callable. The per-namespace breakdown is mirrored in [docs/api-coverage.md](docs/api-coverage.md) and stays in sync with the inventory test.
+- **`bun test`** (or **`bun run test:unit`**) — covers every method that the package implements, asserts the correct `namespace.method` routing, validates that `api_key`/`format=json` are present, and verifies that Last.fm error envelopes surface as `LastFmApiError`. They do not require an API key or any network access, and they run as part of CI on every push and pull request.
+- **`inventory.test.ts`** — asserts the **56/56 canonical-method baseline** ensuring every namespace.method pair listed in the official Last.fm API index is exposed on the `LastFmClient` and callable. The per-namespace breakdown is mirrored in [docs/api-coverage.md](docs/api-coverage.md).
 
 ### Release Process
 

package/dist/cache/index.d.ts

@@ -0,0 +1,7 @@
+export * from './interface.js';
+export * from './manager.js';
+export * from './schemas.js';
+export * from './service.js';
+export * from './stores/memory.js';
+export * from './stores/storage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA"}

package/dist/cache/index.js

@@ -0,0 +1,7 @@
+export * from './interface.js';
+export * from './manager.js';
+export * from './schemas.js';
+export * from './service.js';
+export * from './stores/memory.js';
+export * from './stores/storage.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA"}

package/dist/cache/interface.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Interface definition for Cache Stores in @ansango/lastfm-api
+ */
+export interface CacheStoreStats {
+    hits: number;
+    misses: number;
+    size: number;
+}
+export interface CacheStore {
+    /**
+     * Retrieve a cached value by key
+     */
+    get<T = unknown>(key: string): Promise<T | undefined> | T | undefined;
+    /**
+     * Store a value in the cache with an optional TTL in milliseconds
+     */
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void> | void;
+    /**
+     * Remove a specific key from the cache
+     */
+    delete(key: string): Promise<boolean> | boolean;
+    /**
+     * Clear all cached values
+     */
+    clear(): Promise<void> | void;
+    /**
+     * Check if a non-expired key exists in the cache
+     */
+    has(key: string): Promise<boolean> | boolean;
+    /**
+     * Get cache metrics if supported
+     */
+    stats?(): CacheStoreStats;
+}
+export interface CacheOptions {
+    /**
+     * Custom cache store implementation (defaults to MemoryCacheStore)
+     */
+    store?: CacheStore;
+    /**
+     * Default TTL in milliseconds for all read requests (default: 300,000 ms / 5 minutes)
+     */
+    defaultTtlMs?: number;
+    /**
+     * Granular TTL overrides by namespace (e.g. { artist: 86_400_000, user: 60_000 })
+     */
+    ttlByNamespace?: Record<string, number>;
+    /**
+     * Granular TTL overrides by method (e.g. { 'user.getRecentTracks': 10_000 })
+     */
+    ttlByMethod?: Record<string, number>;
+    /**
+     * Whether caching is enabled (default: true)
+     */
+    enabled?: boolean;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/cache/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/cache/interface.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,UAAU;IAC1B;;OAEG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,SAAS,CAAA;IAErE;;OAEG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAE7E;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IAE/C;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAE7B;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IAE5C;;OAEG;IACH,KAAK,CAAC,IAAI,eAAe,CAAA;CACzB;AAED,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAElB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEvC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEpC;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB"}

package/dist/cache/interface.js

@@ -0,0 +1,5 @@
+/**
+ * Interface definition for Cache Stores in @ansango/lastfm-api
+ */
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/cache/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/cache/interface.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/cache/manager.d.ts

@@ -0,0 +1,19 @@
+import type { CacheOptions, CacheStoreStats } from './interface.js';
+export declare class CacheManager {
+    private readonly store;
+    private readonly defaultTtlMs;
+    private readonly ttlByNamespace;
+    private readonly ttlByMethod;
+    private readonly enabled;
+    constructor(options?: CacheOptions);
+    isEnabled(): boolean;
+    resolveTtl(methodId?: string): number;
+    wrap<T>(key: string, fetcherFn: () => Promise<T>, ttlMs?: number): Promise<T>;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    stats(): CacheStoreStats | undefined;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/cache/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/cache/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAc,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAG/E,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,GAAE,YAAiB;IAQ/B,SAAS,IAAI,OAAO;IAIpB,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IAiB/B,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAe7E,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAIrD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxC,KAAK,IAAI,eAAe,GAAG,SAAS;CAG3C"}

package/dist/cache/manager.js

@@ -0,0 +1,63 @@
+import { MemoryCacheStore } from './stores/memory.js';
+export class CacheManager {
+    store;
+    defaultTtlMs;
+    ttlByNamespace;
+    ttlByMethod;
+    enabled;
+    constructor(options = {}) {
+        this.store = options.store ?? new MemoryCacheStore({ defaultTtlMs: options.defaultTtlMs });
+        this.defaultTtlMs = options.defaultTtlMs ?? 300_000;
+        this.ttlByNamespace = options.ttlByNamespace ?? {};
+        this.ttlByMethod = options.ttlByMethod ?? {};
+        this.enabled = options.enabled ?? true;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    resolveTtl(methodId) {
+        if (!methodId)
+            return this.defaultTtlMs;
+        // 1. Direct method match (e.g. 'user.getRecentTracks' or 'user.getInfo')
+        if (this.ttlByMethod[methodId] !== undefined) {
+            return this.ttlByMethod[methodId];
+        }
+        // 2. Namespace match (e.g. 'user', 'artist', 'album')
+        const [ns] = methodId.split('.');
+        if (ns && this.ttlByNamespace[ns] !== undefined) {
+            return this.ttlByNamespace[ns];
+        }
+        return this.defaultTtlMs;
+    }
+    async wrap(key, fetcherFn, ttlMs) {
+        if (!this.enabled) {
+            return fetcherFn();
+        }
+        const cached = await this.store.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const fresh = await fetcherFn();
+        await this.store.set(key, fresh, ttlMs ?? this.defaultTtlMs);
+        return fresh;
+    }
+    async get(key) {
+        return this.store.get(key);
+    }
+    async set(key, value, ttlMs) {
+        return this.store.set(key, value, ttlMs ?? this.defaultTtlMs);
+    }
+    async delete(key) {
+        return this.store.delete(key);
+    }
+    async clear() {
+        return this.store.clear();
+    }
+    async has(key) {
+        return this.store.has(key);
+    }
+    stats() {
+        return this.store.stats?.();
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/cache/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/cache/manager.ts"],"names":[],"mappings":"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"}