@ansango/lastfm-api 3.5.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,9 +298,85 @@ 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 comprehensive, built-in analytics engine providing 20 high-level derived views and statistical metrics computed over Last.fm data:
@@ -536,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
 
@@ -600,6 +703,7 @@ The main client class with all services:
 
 ```typescript
 class LastFmClient {
+  core: LastFmCoreClient;
   user: UserService;
   album: AlbumService;
   artist: ArtistService;
@@ -610,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>;
@@ -635,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`¹
@@ -645,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.
 
@@ -701,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
@@ -726,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
@@ -745,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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"}

package/dist/cache/schemas.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export declare const cacheStoreStatsSchema: z.ZodObject<{
+    hits: z.ZodNumber;
+    misses: z.ZodNumber;
+    size: z.ZodNumber;
+}, z.core.$strip>;
+export declare const cacheOptionsSchema: z.ZodObject<{
+    defaultTtlMs: z.ZodOptional<z.ZodNumber>;
+    ttlByNamespace: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    ttlByMethod: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CacheStoreStatsPayload = z.infer<typeof cacheStoreStatsSchema>;
+export type CacheOptionsSchema = z.infer<typeof cacheOptionsSchema>;
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/cache/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,qBAAqB;;;;iBAIhC,CAAA;AAEF,eAAO,MAAM,kBAAkB;;;;;iBAK7B,CAAA;AAEF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAC1E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA"}

package/dist/cache/schemas.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export const cacheStoreStatsSchema = z.object({
+    hits: z.number().int().nonnegative(),
+    misses: z.number().int().nonnegative(),
+    size: z.number().int().nonnegative(),
+});
+export const cacheOptionsSchema = z.object({
+    defaultTtlMs: z.number().positive().optional(),
+    ttlByNamespace: z.record(z.string(), z.number().positive()).optional(),
+    ttlByMethod: z.record(z.string(), z.number().positive()).optional(),
+    enabled: z.boolean().optional(),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/cache/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/cache/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACpC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACpC,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC9C,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtE,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE;IACnE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAA"}

package/dist/cache/service.d.ts

@@ -0,0 +1,13 @@
+import type { CacheStoreStats } from './interface.js';
+import type { CacheManager } from './manager.js';
+export interface CacheService {
+    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;
+    manager: CacheManager;
+}
+export declare function createCacheService(manager: CacheManager): CacheService;
+//# sourceMappingURL=service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/cache/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IACzD,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1E,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACzC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACtC,KAAK,EAAE,MAAM,eAAe,GAAG,SAAS,CAAA;IACxC,OAAO,EAAE,YAAY,CAAA;CACrB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAUtE"}

package/dist/cache/service.js

@@ -0,0 +1,12 @@
+export function createCacheService(manager) {
+    return {
+        get: (key) => manager.get(key),
+        set: (key, value, ttlMs) => manager.set(key, value, ttlMs),
+        delete: (key) => manager.delete(key),
+        clear: () => manager.clear(),
+        has: (key) => manager.has(key),
+        stats: () => manager.stats(),
+        manager,
+    };
+}
+//# sourceMappingURL=service.js.map

package/dist/cache/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/cache/service.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,kBAAkB,CAAC,OAAqB;IACvD,OAAO;QACN,GAAG,EAAE,CAAc,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAI,GAAG,CAAC;QACtD,GAAG,EAAE,CAAc,GAAW,EAAE,KAAQ,EAAE,KAAc,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC;QAC3F,MAAM,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;QAC5C,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE;QAC5B,GAAG,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;QACtC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE;QAC5B,OAAO;KACP,CAAA;AACF,CAAC"}

package/dist/cache/stores/memory.d.ts

@@ -0,0 +1,33 @@
+import type { CacheStore, CacheStoreStats } from '../interface.js';
+export interface MemoryCacheStoreOptions {
+    /**
+     * Maximum number of entries before oldest entries are evicted (default: 500)
+     */
+    maxEntries?: number;
+    /**
+     * Default TTL in milliseconds (default: 300,000 / 5 minutes)
+     */
+    defaultTtlMs?: number;
+}
+/**
+ * High-performance in-memory cache store with TTL expiration and LRU eviction.
+ */
+export declare class MemoryCacheStore implements CacheStore {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly defaultTtlMs;
+    private hitCount;
+    private missCount;
+    constructor(options?: MemoryCacheStoreOptions);
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T, ttlMs?: number): void;
+    delete(key: string): boolean;
+    clear(): void;
+    has(key: string): boolean;
+    stats(): CacheStoreStats;
+    /**
+     * Removes all expired entries from memory
+     */
+    pruneExpired(): number;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/cache/stores/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/cache/stores/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAElE,MAAM,WAAW,uBAAuB;IACvC;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAOD;;GAEG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;IAClE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,SAAS,CAAI;gBAET,OAAO,GAAE,uBAA4B;IAK1C,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAoB5C,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAgB7D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,KAAK,IAAI,IAAI;IAMb,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAUzB,KAAK,IAAI,eAAe;IAS/B;;OAEG;IACI,YAAY,IAAI,MAAM;CAW7B"}