@ansango/lastfm-api 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -9,6 +9,31 @@ 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.4.0] - 2026-08-28
+
+### ✨ Features
+
+- **insights**: implement compareUsers with Jaccard affinity index (closes #125) ([95f39d6](https://github.com/ansango/lastfm-api/commit/95f39d6))
+- **insights**: implement getMood psychometric classifier and getPersonality archetypes (closes #124) ([0aae0e8](https://github.com/ansango/lastfm-api/commit/0aae0e8))
+- **insights**: implement getTrends ranking diff and getDiscoveries new-artist detector (closes #123) ([1a07234](https://github.com/ansango/lastfm-api/commit/1a07234))
+- **insights**: implement getHoursHistogram and getBinges temporal analytics (closes #122) ([7615ba9](https://github.com/ansango/lastfm-api/commit/7615ba9))
+- **insights**: implement getNowPlaying with artist bio and similarity enrichment (closes #121) ([9de9213](https://github.com/ansango/lastfm-api/commit/9de9213))
+- **insights**: register getSummary route in method registry and Scalar OpenAPI docs ([875bafe](https://github.com/ansango/lastfm-api/commit/875bafe))
+- **insights**: implement getSummary with Shannon diversity index (closes #120) ([28b03b0](https://github.com/ansango/lastfm-api/commit/28b03b0))
+- **insights**: wire insights namespace in method registry ([2d1db4d](https://github.com/ansango/lastfm-api/commit/2d1db4d))
+- **insights**: base architecture, Zod schemas infrastructure, and client wiring (closes #119) ([6ce9d4e](https://github.com/ansango/lastfm-api/commit/6ce9d4e))
+
+### 📚 Documentation
+
+- **insights**: add dedicated OpenAPI descriptions in Scalar for all 9 insight methods ([1115785](https://github.com/ansango/lastfm-api/commit/1115785))
+- **insights**: documentation, OpenAPI Scalar integration, and CLI migration guide (closes #126) ([f325696](https://github.com/ansango/lastfm-api/commit/f325696))
+
+### 🔧 Chores
+
+- remove PROJECT_IDEAS.md ([a837c39](https://github.com/ansango/lastfm-api/commit/a837c39))
+- update dependencies and configuration files - Bump @types/node to version 26.4.0 in package.json and bun.lock - Modify build script in package.json to use tsconfig.build.json - Update changelog script to handle undefined tags - Refactor recent tracks test for better readability - Adjust tsconfig files for improved build and development settings - Add tsconfig.build.json for build-specific configurations - Update .gitignore to exclude AGENTS.md ([2a1687f](https://github.com/ansango/lastfm-api/commit/2a1687f))
+
+
 ## [3.3.0] - 2026-08-28
 
 ### ✨ Features

package/README.md

@@ -14,7 +14,8 @@ A universal Last.fm API client for Node.js and Browser, written in TypeScript.
 ## Features
 
 - ✅ **Universal**: Works in Node.js (≥20.0.0) and Browser
-- ✅ **Complete coverage**: All 57 canonical Last.fm API methods across 9 namespaces
+- ✅ **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)
 - ✅ **TypeScript**: Full type safety with comprehensive type definitions
 - ✅ **Zod Schemas**: Runtime validation schemas for all types
 - ✅ **ESM**: Modern ES modules with tree-shaking support
@@ -130,7 +131,14 @@ const libraryArtists = await client.library.getArtists({ user: 'ansango' });
 // Auth service (for scrobbling and authenticated methods)
 const session = await client.auth.getSession({ token: 'AUTH_TOKEN' });
 // Request an auth token (signed GET, no sk)
-const { token } = await client.auth.getToken();
+const { token, authUrl } = await client.auth.getToken();
+
+// Insights & analytics engine
+const summary = await client.insights.getSummary({ user: 'ansango', period: '7day' });
+const nowPlaying = await client.insights.getNowPlaying({ user: 'ansango' });
+const mood = await client.insights.getMood({ user: 'ansango', period: '1month' });
+const personality = await client.insights.getPersonality({ user: 'ansango' });
+const comparison = await client.insights.compareUsers({ userA: 'ansango', userB: 'friend' });
 
 // Now-playing and tag/love mutations (all require an authenticated session)
 await client.track.updateNowPlaying({
@@ -214,6 +222,7 @@ const tracks = await trackService.search({ track: 'Come Together' });
 - `@ansango/lastfm-api/geo`
 - `@ansango/lastfm-api/library`
 - `@ansango/lastfm-api/auth`
+- `@ansango/lastfm-api/insights`
 
 ## Zod Schema Validation
 
@@ -262,8 +271,183 @@ if (result.success) {
 - `@ansango/lastfm-api/geo/schemas`
 - `@ansango/lastfm-api/library/schemas`
 - `@ansango/lastfm-api/auth/schemas`
+- `@ansango/lastfm-api/insights/schemas`
 - `@ansango/lastfm-api/schemas` (base types like `imageSchema`, `datePropSchema`, etc.)
 
+## 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:
+
+```typescript
+import { createClient } from '@ansango/lastfm-api';
+
+const client = createClient();
+
+// 1. Summary & Shannon Diversity
+const summary = await client.insights.getSummary({ user: 'ansango', period: '7day' });
+console.log(`Total Scrobbles: ${summary.totalScrobbles}, Normalized Diversity: ${summary.diversity?.normalized}`);
+
+// 2. Enriched Now Playing with Artist Biography and Similar Artists
+const nowPlaying = await client.insights.getNowPlaying({ user: 'ansango', similarLimit: 3 });
+
+// 3. Diurnal & Weekday Histogram
+const histogram = await client.insights.getHoursHistogram({ user: 'ansango', sinceDays: 30 });
+console.log(`Peak Hour: ${histogram.peakHour}:00, Night Share: ${(histogram.nightShare * 100).toFixed(0)}%`);
+
+// 4. Binge Listening Streak Detection
+const binges = await client.insights.getBinges({ user: 'ansango', minLength: 3, maxGapSeconds: 1800 });
+
+// 5. Ranking Trends Differentials (Risers, Fallers, Newcomers, Departures)
+const trends = await client.insights.getTrends({
+  user: 'ansango',
+  target: 'artists',
+  currentPeriod: '7day',
+  previousPeriod: '1month'
+});
+
+// 6. New Artist Discoveries
+const discoveries = await client.insights.getDiscoveries({ user: 'ansango', windowDays: 7 });
+
+// 7. 2D Mood Classification (Energy vs. Valence)
+const mood = await client.insights.getMood({ user: 'ansango', period: '1month' });
+console.log(`Mood: ${mood.label} (Energy: ${mood.axes.energy}, Valence: ${mood.axes.valence})`);
+
+// 8. Listener Personality Archetype
+const personality = await client.insights.getPersonality({ user: 'ansango' });
+console.log(`Archetype: ${personality.archetype.emoji} ${personality.archetype.name} - ${personality.archetype.blurb}`);
+
+// 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
 
 In Node.js environments, the client automatically loads configuration from environment variables:
@@ -425,6 +609,7 @@ class LastFmClient {
   geo: GeoService;
   library: LibraryService;
   auth: AuthService;
+  insights: InsightsService;
   
   constructor(config?: Partial<LastFmConfig>);
   getConfig(): Readonly<LastFmConfig>;
@@ -450,7 +635,7 @@ function resetGlobalConfig(): void;
 
 ### Services
 
-The package covers all 57 canonical Last.fm API methods across 9 namespaces. 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 9 derived analytical methods in the `InsightsService`. See [docs/api-coverage.md](docs/api-coverage.md) for the full table.
 
 - **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`¹
@@ -461,6 +646,7 @@ The package covers all 57 canonical Last.fm API methods across 9 namespaces. See
 - **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`
 
 ¹ Requires an authenticated session.
 

package/dist/client.d.ts

@@ -1,5 +1,9 @@
 import type { LastFmConfig } from './config.js';
-import { type AlbumService, type ArtistService, type AuthService, type ChartService, type GeoService, type LibraryService, type TagService, type TrackService, type UserService } from './services/index.js';
+import { type AlbumService, type ArtistService, type AuthService, type ChartService, type GeoService, type LibraryService, type TagService, type TrackService, type UserService } from './core/services/index.js';
+import { type ExporterService } from './exporter/index.js';
+import { type InsightsService } from './insights/index.js';
+import { type PlaylistsService } from './playlists/index.js';
+import { type ReportsService } from './reports/index.js';
 /**
  * Last.fm API Client
  *
@@ -29,6 +33,10 @@ export declare class LastFmClient {
     readonly geo: GeoService;
     readonly library: LibraryService;
     readonly auth: AuthService;
+    readonly insights: InsightsService;
+    readonly reports: ReportsService;
+    readonly playlists: PlaylistsService;
+    readonly exporter: ExporterService;
     private readonly config;
     constructor(config?: Partial<LastFmConfig>);
     /**

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EAUjB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,MAAM,qBAAqB,CAAA;AAE5B;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY;IACxB,SAAgB,IAAI,EAAE,WAAW,CAAA;IACjC,SAAgB,KAAK,EAAE,YAAY,CAAA;IACnC,SAAgB,MAAM,EAAE,aAAa,CAAA;IACrC,SAAgB,KAAK,EAAE,YAAY,CAAA;IACnC,SAAgB,GAAG,EAAE,UAAU,CAAA;IAC/B,SAAgB,KAAK,EAAE,YAAY,CAAA;IACnC,SAAgB,GAAG,EAAE,UAAU,CAAA;IAC/B,SAAgB,OAAO,EAAE,cAAc,CAAA;IACvC,SAAgB,IAAI,EAAE,WAAW,CAAA;IAEjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAe1C;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,YAAY,CAAC;CAGnC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAEzE"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EAUjB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACjF,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACjF,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAE9E;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY;IACxB,SAAgB,IAAI,EAAE,WAAW,CAAA;IACjC,SAAgB,KAAK,EAAE,YAAY,CAAA;IACnC,SAAgB,MAAM,EAAE,aAAa,CAAA;IACrC,SAAgB,KAAK,EAAE,YAAY,CAAA;IACnC,SAAgB,GAAG,EAAE,UAAU,CAAA;IAC/B,SAAgB,KAAK,EAAE,YAAY,CAAA;IACnC,SAAgB,GAAG,EAAE,UAAU,CAAA;IAC/B,SAAgB,OAAO,EAAE,cAAc,CAAA;IACvC,SAAgB,IAAI,EAAE,WAAW,CAAA;IACjC,SAAgB,QAAQ,EAAE,eAAe,CAAA;IACzC,SAAgB,OAAO,EAAE,cAAc,CAAA;IACvC,SAAgB,SAAS,EAAE,gBAAgB,CAAA;IAC3C,SAAgB,QAAQ,EAAE,eAAe,CAAA;IAEzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAmB1C;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,YAAY,CAAC;CAGnC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAEzE"}

package/dist/client.js

@@ -1,5 +1,9 @@
 import { createConfig, getGlobalConfig } from './config.js';
-import { createAlbumService, createArtistService, createAuthService, createChartService, createGeoService, createLibraryService, createTagService, createTrackService, createUserService, } from './services/index.js';
+import { createAlbumService, createArtistService, createAuthService, createChartService, createGeoService, createLibraryService, createTagService, createTrackService, createUserService, } from './core/services/index.js';
+import { createExporterService } from './exporter/index.js';
+import { createInsightsService } from './insights/index.js';
+import { createPlaylistsService } from './playlists/index.js';
+import { createReportsService } from './reports/index.js';
 /**
  * Last.fm API Client
  *
@@ -29,6 +33,10 @@ export class LastFmClient {
     geo;
     library;
     auth;
+    insights;
+    reports;
+    playlists;
+    exporter;
     config;
     constructor(config) {
         this.config = config ? createConfig(config) : getGlobalConfig();
@@ -42,6 +50,10 @@ export class LastFmClient {
         this.geo = createGeoService(this.config);
         this.library = createLibraryService(this.config);
         this.auth = createAuthService(this.config);
+        this.insights = createInsightsService(this.config);
+        this.reports = createReportsService(this.config);
+        this.playlists = createPlaylistsService(this.config);
+        this.exporter = createExporterService(this.config);
     }
     /**
      * Get the current configuration (read-only)

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EAKN,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAMjB,MAAM,qBAAqB,CAAA;AAE5B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,YAAY;IACR,IAAI,CAAa;IACjB,KAAK,CAAc;IACnB,MAAM,CAAe;IACrB,KAAK,CAAc;IACnB,GAAG,CAAY;IACf,KAAK,CAAc;IACnB,GAAG,CAAY;IACf,OAAO,CAAgB;IACvB,IAAI,CAAa;IAEhB,MAAM,CAAc;IAErC,YAAY,MAA8B;QACzC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAAA;QAE/D,0BAA0B;QAC1B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC1C,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,IAAI,CAAC,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC9C,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,IAAI,CAAC,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,IAAI,CAAC,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,CAAC,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAChD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC3C,CAAC;IAED;;OAEG;IACH,SAAS;QACR,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;IAC1B,CAAC;CACD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,MAA8B;IAC1D,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,CAAA;AAChC,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EAKN,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAMjB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,qBAAqB,EAAwB,MAAM,qBAAqB,CAAA;AACjF,OAAO,EAAE,qBAAqB,EAAwB,MAAM,qBAAqB,CAAA;AACjF,OAAO,EAAE,sBAAsB,EAAyB,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAE,oBAAoB,EAAuB,MAAM,oBAAoB,CAAA;AAE9E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,YAAY;IACR,IAAI,CAAa;IACjB,KAAK,CAAc;IACnB,MAAM,CAAe;IACrB,KAAK,CAAc;IACnB,GAAG,CAAY;IACf,KAAK,CAAc;IACnB,GAAG,CAAY;IACf,OAAO,CAAgB;IACvB,IAAI,CAAa;IACjB,QAAQ,CAAiB;IACzB,OAAO,CAAgB;IACvB,SAAS,CAAkB;IAC3B,QAAQ,CAAiB;IAExB,MAAM,CAAc;IAErC,YAAY,MAA8B;QACzC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAAA;QAE/D,0BAA0B;QAC1B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC1C,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,IAAI,CAAC,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC9C,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,IAAI,CAAC,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,IAAI,CAAC,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,CAAC,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAChD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC1C,IAAI,CAAC,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAClD,IAAI,CAAC,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAChD,IAAI,CAAC,SAAS,GAAG,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACpD,IAAI,CAAC,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACnD,CAAC;IAED;;OAEG;IACH,SAAS;QACR,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;IAC1B,CAAC;CACD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,MAA8B;IAC1D,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,CAAA;AAChC,CAAC"}

package/dist/core/canonical-methods.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Canonical Last.fm method inventory.
+ *
+ * Single source of truth for the "56/56" coverage of the Last.fm API.
+ * (was 57/57; `auth.getMobileSession` removed in v4.0.0 — see #117.)
+ * Consumed by:
+ *  - `src/__tests__/inventory.test.ts` — verifies that each method exists on the client
+ *  - `src/method-registry.ts` — wires the docs tool (Hono + Scalar)
+ *
+ * Rules:
+ *  - Only canonical Last.fm `namespace.method` pairs go here.
+ *  - Wrapper/alias methods (e.g. `scrobbleMany`, `postTrackScrobble`,
+ *    `postBatchTrackScrobble`) are excluded because they all target the
+ *    same canonical endpoint (`track.scrobble`) and must not be
+ *    double-counted.
+ *
+ * The per-namespace breakdown:
+ *  - artist (10), album (6), track (12), user (13), tag (7),
+ *    chart (3), geo (2), library (1), auth (3) = 57
+ */
+export declare const CANONICAL_METHODS: readonly ["artist.getInfo", "artist.getTags", "artist.getSimilar", "artist.getTopTags", "artist.getTopAlbums", "artist.getTopTracks", "artist.search", "artist.getCorrection", "artist.addTags", "artist.removeTag", "album.getInfo", "album.getTags", "album.getTopTags", "album.search", "album.addTags", "album.removeTag", "track.getInfo", "track.getSimilar", "track.getTags", "track.getTopTags", "track.search", "track.getCorrection", "track.addTags", "track.removeTag", "track.love", "track.unlove", "track.updateNowPlaying", "track.scrobble", "user.getInfo", "user.getFriends", "user.getLovedTracks", "user.getRecentTracks", "user.getTopAlbums", "user.getTopArtists", "user.getTopTags", "user.getTopTracks", "user.getWeeklyAlbumChart", "user.getWeeklyArtistChart", "user.getWeeklyChartList", "user.getWeeklyTrackChart", "user.getPersonalTags", "tag.getInfo", "tag.getSimilar", "tag.getTopAlbums", "tag.getTopArtists", "tag.getTopTags", "tag.getTopTracks", "tag.getWeeklyChartList", "chart.getTopArtists", "chart.getTopTags", "chart.getTopTracks", "geo.getTopArtists", "geo.getTopTracks", "library.getArtists", "auth.getSession", "auth.getToken"];
+export type CanonicalMethodId = (typeof CANONICAL_METHODS)[number];
+export type CanonicalMethod = CanonicalMethodId;
+export type Namespace = CanonicalMethodId extends `${infer N}.${string}` ? N : never;
+//# sourceMappingURL=canonical-methods.d.ts.map

package/dist/core/canonical-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-methods.d.ts","sourceRoot":"","sources":["../../src/core/canonical-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,0nCAkEpB,CAAA;AAEV,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA;AAClE,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAC/C,MAAM,MAAM,SAAS,GAAG,iBAAiB,SAAS,GAAG,MAAM,CAAC,IAAI,MAAM,EAAE,GAAG,CAAC,GAAG,KAAK,CAAA"}

package/dist/core/canonical-methods.js

@@ -0,0 +1,88 @@
+/**
+ * Canonical Last.fm method inventory.
+ *
+ * Single source of truth for the "56/56" coverage of the Last.fm API.
+ * (was 57/57; `auth.getMobileSession` removed in v4.0.0 — see #117.)
+ * Consumed by:
+ *  - `src/__tests__/inventory.test.ts` — verifies that each method exists on the client
+ *  - `src/method-registry.ts` — wires the docs tool (Hono + Scalar)
+ *
+ * Rules:
+ *  - Only canonical Last.fm `namespace.method` pairs go here.
+ *  - Wrapper/alias methods (e.g. `scrobbleMany`, `postTrackScrobble`,
+ *    `postBatchTrackScrobble`) are excluded because they all target the
+ *    same canonical endpoint (`track.scrobble`) and must not be
+ *    double-counted.
+ *
+ * The per-namespace breakdown:
+ *  - artist (10), album (6), track (12), user (13), tag (7),
+ *    chart (3), geo (2), library (1), auth (3) = 57
+ */
+export const CANONICAL_METHODS = [
+    // artist (10)
+    'artist.getInfo',
+    'artist.getTags',
+    'artist.getSimilar',
+    'artist.getTopTags',
+    'artist.getTopAlbums',
+    'artist.getTopTracks',
+    'artist.search',
+    'artist.getCorrection',
+    'artist.addTags',
+    'artist.removeTag',
+    // album (6)
+    'album.getInfo',
+    'album.getTags',
+    'album.getTopTags',
+    'album.search',
+    'album.addTags',
+    'album.removeTag',
+    // track (12)
+    'track.getInfo',
+    'track.getSimilar',
+    'track.getTags',
+    'track.getTopTags',
+    'track.search',
+    'track.getCorrection',
+    'track.addTags',
+    'track.removeTag',
+    'track.love',
+    'track.unlove',
+    'track.updateNowPlaying',
+    'track.scrobble',
+    // user (13)
+    'user.getInfo',
+    'user.getFriends',
+    'user.getLovedTracks',
+    'user.getRecentTracks',
+    'user.getTopAlbums',
+    'user.getTopArtists',
+    'user.getTopTags',
+    'user.getTopTracks',
+    'user.getWeeklyAlbumChart',
+    'user.getWeeklyArtistChart',
+    'user.getWeeklyChartList',
+    'user.getWeeklyTrackChart',
+    'user.getPersonalTags',
+    // tag (7)
+    'tag.getInfo',
+    'tag.getSimilar',
+    'tag.getTopAlbums',
+    'tag.getTopArtists',
+    'tag.getTopTags',
+    'tag.getTopTracks',
+    'tag.getWeeklyChartList',
+    // chart (3)
+    'chart.getTopArtists',
+    'chart.getTopTags',
+    'chart.getTopTracks',
+    // geo (2)
+    'geo.getTopArtists',
+    'geo.getTopTracks',
+    // library (1)
+    'library.getArtists',
+    // auth (2)
+    'auth.getSession',
+    'auth.getToken',
+];
+//# sourceMappingURL=canonical-methods.js.map

package/dist/core/canonical-methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-methods.js","sourceRoot":"","sources":["../../src/core/canonical-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAChC,cAAc;IACd,gBAAgB;IAChB,gBAAgB;IAChB,mBAAmB;IACnB,mBAAmB;IACnB,qBAAqB;IACrB,qBAAqB;IACrB,eAAe;IACf,sBAAsB;IACtB,gBAAgB;IAChB,kBAAkB;IAClB,YAAY;IACZ,eAAe;IACf,eAAe;IACf,kBAAkB;IAClB,cAAc;IACd,eAAe;IACf,iBAAiB;IACjB,aAAa;IACb,eAAe;IACf,kBAAkB;IAClB,eAAe;IACf,kBAAkB;IAClB,cAAc;IACd,qBAAqB;IACrB,eAAe;IACf,iBAAiB;IACjB,YAAY;IACZ,cAAc;IACd,wBAAwB;IACxB,gBAAgB;IAChB,YAAY;IACZ,cAAc;IACd,iBAAiB;IACjB,qBAAqB;IACrB,sBAAsB;IACtB,mBAAmB;IACnB,oBAAoB;IACpB,iBAAiB;IACjB,mBAAmB;IACnB,0BAA0B;IAC1B,2BAA2B;IAC3B,yBAAyB;IACzB,0BAA0B;IAC1B,sBAAsB;IACtB,UAAU;IACV,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,mBAAmB;IACnB,gBAAgB;IAChB,kBAAkB;IAClB,wBAAwB;IACxB,YAAY;IACZ,qBAAqB;IACrB,kBAAkB;IAClB,oBAAoB;IACpB,UAAU;IACV,mBAAmB;IACnB,kBAAkB;IAClB,cAAc;IACd,oBAAoB;IACpB,WAAW;IACX,iBAAiB;IACjB,eAAe;CACN,CAAA"}

package/dist/core/client.d.ts

@@ -0,0 +1,33 @@
+import { type LastFmConfig } from '../config.js';
+import { type AlbumService, type ArtistService, type AuthService, type ChartService, type GeoService, type LibraryService, type TagService, type TrackService, type UserService } from './services/index.js';
+/**
+ * Lightweight Last.fm Core API client.
+ *
+ * Provides access strictly to the 56 canonical Last.fm REST API methods
+ * across the 9 official namespaces.
+ */
+export declare class LastFmCoreClient {
+    readonly user: UserService;
+    readonly album: AlbumService;
+    readonly artist: ArtistService;
+    readonly track: TrackService;
+    readonly tag: TagService;
+    readonly chart: ChartService;
+    readonly geo: GeoService;
+    readonly library: LibraryService;
+    readonly auth: AuthService;
+    private readonly config;
+    constructor(config?: Partial<LastFmConfig>);
+    /**
+     * Get the current configuration (read-only)
+     */
+    getConfig(): Readonly<LastFmConfig>;
+}
+/**
+ * Helper function to create a Last.fm core client instance
+ *
+ * @param config - Optional configuration. If not provided, uses global config.
+ * @returns A new LastFmCoreClient instance
+ */
+export declare function createCoreClient(config?: Partial<LastFmConfig>): LastFmCoreClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,YAAY,EAAE,MAAM,cAAc,CAAA;AAC/E,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EAUjB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,MAAM,qBAAqB,CAAA;AAE5B;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC5B,SAAgB,IAAI,EAAE,WAAW,CAAA;IACjC,SAAgB,KAAK,EAAE,YAAY,CAAA;IACnC,SAAgB,MAAM,EAAE,aAAa,CAAA;IACrC,SAAgB,KAAK,EAAE,YAAY,CAAA;IACnC,SAAgB,GAAG,EAAE,UAAU,CAAA;IAC/B,SAAgB,KAAK,EAAE,YAAY,CAAA;IACnC,SAAgB,GAAG,EAAE,UAAU,CAAA;IAC/B,SAAgB,OAAO,EAAE,cAAc,CAAA;IACvC,SAAgB,IAAI,EAAE,WAAW,CAAA;IAEjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAc1C;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,YAAY,CAAC;CAGnC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,gBAAgB,CAEjF"}

package/dist/core/client.js

@@ -0,0 +1,48 @@
+import { createConfig, getGlobalConfig } from '../config.js';
+import { createAlbumService, createArtistService, createAuthService, createChartService, createGeoService, createLibraryService, createTagService, createTrackService, createUserService, } from './services/index.js';
+/**
+ * Lightweight Last.fm Core API client.
+ *
+ * Provides access strictly to the 56 canonical Last.fm REST API methods
+ * across the 9 official namespaces.
+ */
+export class LastFmCoreClient {
+    user;
+    album;
+    artist;
+    track;
+    tag;
+    chart;
+    geo;
+    library;
+    auth;
+    config;
+    constructor(config) {
+        this.config = config ? createConfig(config) : getGlobalConfig();
+        this.user = createUserService(this.config);
+        this.album = createAlbumService(this.config);
+        this.artist = createArtistService(this.config);
+        this.track = createTrackService(this.config);
+        this.tag = createTagService(this.config);
+        this.chart = createChartService(this.config);
+        this.geo = createGeoService(this.config);
+        this.library = createLibraryService(this.config);
+        this.auth = createAuthService(this.config);
+    }
+    /**
+     * Get the current configuration (read-only)
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+/**
+ * Helper function to create a Last.fm core client instance
+ *
+ * @param config - Optional configuration. If not provided, uses global config.
+ * @returns A new LastFmCoreClient instance
+ */
+export function createCoreClient(config) {
+    return new LastFmCoreClient(config);
+}
+//# sourceMappingURL=client.js.map

package/dist/core/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAqB,MAAM,cAAc,CAAA;AAC/E,OAAO,EAKN,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAMjB,MAAM,qBAAqB,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IACZ,IAAI,CAAa;IACjB,KAAK,CAAc;IACnB,MAAM,CAAe;IACrB,KAAK,CAAc;IACnB,GAAG,CAAY;IACf,KAAK,CAAc;IACnB,GAAG,CAAY;IACf,OAAO,CAAgB;IACvB,IAAI,CAAa;IAEhB,MAAM,CAAc;IAErC,YAAY,MAA8B;QACzC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAAA;QAE/D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC1C,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,IAAI,CAAC,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC9C,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,IAAI,CAAC,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5C,IAAI,CAAC,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,CAAC,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAChD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC3C,CAAC;IAED;;OAEG;IACH,SAAS;QACR,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;IAC1B,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA8B;IAC9D,OAAO,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAA;AACpC,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,6 @@
+export * from './canonical-methods.js';
+export * from './client.js';
+export * from './pagination.js';
+export * from './schemas/index.js';
+export * from './services/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA"}

package/dist/core/index.js

@@ -0,0 +1,6 @@
+export * from './canonical-methods.js';
+export * from './client.js';
+export * from './pagination.js';
+export * from './schemas/index.js';
+export * from './services/index.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA"}

package/dist/core/pagination.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Generic pagination and async iterator utilities for Last.fm API endpoints.
+ */
+export interface PaginationOptions {
+    /** Starting page number (1-indexed). Defaults to 1. */
+    startPage?: number;
+    /** Maximum number of pages to fetch. Defaults to Infinity. */
+    maxPages?: number;
+    /** Maximum total items to yield or collect. Defaults to Infinity. */
+    maxItems?: number;
+    /** Optional delay in milliseconds between page requests (for gentle rate limiting). Defaults to 0. */
+    delayMs?: number;
+}
+export interface PageExtraction<TItem> {
+    items: TItem[];
+    totalPages: number;
+    currentPage: number;
+}
+/**
+ * Async generator yielding items across all paginated responses one by one.
+ *
+ * @example
+ * ```typescript
+ * for await (const track of iterateItems(
+ *   (p) => client.user.getRecentTracks(p),
+ *   (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);
+ * }
+ * ```
+ */
+export declare function iterateItems<TItem, TParams extends Record<string, unknown>, TResponse>(fetchPage: (params: TParams & {
+    page: number;
+    limit?: number;
+}) => Promise<TResponse>, extract: (response: TResponse) => PageExtraction<TItem>, params: TParams, options?: PaginationOptions): AsyncGenerator<TItem, void, undefined>;
+/**
+ * Collects all items from paginated requests into an in-memory array.
+ */
+export declare function collectAll<TItem, TParams extends Record<string, unknown>, TResponse>(fetchPage: (params: TParams & {
+    page: number;
+    limit?: number;
+}) => Promise<TResponse>, extract: (response: TResponse) => PageExtraction<TItem>, params: TParams, options?: PaginationOptions): Promise<TItem[]>;
+/**
+ * Async generator yielding whole page responses one by one.
+ */
+export declare function iteratePages<TParams extends Record<string, unknown>, TResponse>(fetchPage: (params: TParams & {
+    page: number;
+    limit?: number;
+}) => Promise<TResponse>, extractPagination: (response: TResponse) => {
+    totalPages: number;
+    currentPage: number;
+}, params: TParams, options?: PaginationOptions): AsyncGenerator<TResponse, void, undefined>;
+//# sourceMappingURL=pagination.d.ts.map