@ansango/lastfm-api 3.3.0 → 3.4.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,56 @@ 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 built-in analytics engine providing 9 high-level derived views 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})`);
+```
+
 ## Environment Variables
 
 In Node.js environments, the client automatically loads configuration from environment variables:
@@ -425,6 +482,7 @@ class LastFmClient {
   geo: GeoService;
   library: LibraryService;
   auth: AuthService;
+  insights: InsightsService;
   
   constructor(config?: Partial<LastFmConfig>);
   getConfig(): Readonly<LastFmConfig>;
@@ -450,7 +508,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 +519,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,5 @@
 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 InsightsService, type LibraryService, type TagService, type TrackService, type UserService } from './services/index.js';
 /**
  * Last.fm API Client
  *
@@ -29,6 +29,7 @@ export declare class LastFmClient {
     readonly geo: GeoService;
     readonly library: LibraryService;
     readonly auth: AuthService;
+    readonly insights: InsightsService;
     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,EAWjB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,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;IACjC,SAAgB,QAAQ,EAAE,eAAe,CAAA;IAEzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAgB1C;;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,5 @@
 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, createInsightsService, createLibraryService, createTagService, createTrackService, createUserService, } from './services/index.js';
 /**
  * Last.fm API Client
  *
@@ -29,6 +29,7 @@ export class LastFmClient {
     geo;
     library;
     auth;
+    insights;
     config;
     constructor(config) {
         this.config = config ? createConfig(config) : getGlobalConfig();
@@ -42,6 +43,7 @@ export class LastFmClient {
         this.geo = createGeoService(this.config);
         this.library = createLibraryService(this.config);
         this.auth = createAuthService(this.config);
+        this.insights = createInsightsService(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,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAOjB,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;IACjB,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;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/entrypoints/insights.d.ts

@@ -0,0 +1,4 @@
+export { createInsightsService, type InsightsService } from '../services/insights.js';
+export type * from '../services/insights.schemas.js';
+export * from '../services/insights.schemas.js';
+//# sourceMappingURL=insights.d.ts.map

package/dist/entrypoints/insights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.d.ts","sourceRoot":"","sources":["../../src/entrypoints/insights.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACrF,mBAAmB,iCAAiC,CAAA;AACpD,cAAc,iCAAiC,CAAA"}

package/dist/entrypoints/insights.js

@@ -0,0 +1,3 @@
+export { createInsightsService } from '../services/insights.js';
+export * from '../services/insights.schemas.js';
+//# sourceMappingURL=insights.js.map

package/dist/entrypoints/insights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.js","sourceRoot":"","sources":["../../src/entrypoints/insights.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAwB,MAAM,yBAAyB,CAAA;AAErF,cAAc,iCAAiC,CAAA"}

package/dist/entrypoints/insights.schemas.d.ts

@@ -0,0 +1,2 @@
+export * from '../services/insights.schemas.js';
+//# sourceMappingURL=insights.schemas.d.ts.map

package/dist/entrypoints/insights.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.schemas.d.ts","sourceRoot":"","sources":["../../src/entrypoints/insights.schemas.ts"],"names":[],"mappings":"AACA,cAAc,iCAAiC,CAAA"}

package/dist/entrypoints/insights.schemas.js

@@ -0,0 +1,3 @@
+// Generated schema exports for insights service
+export * from '../services/insights.schemas.js';
+//# sourceMappingURL=insights.schemas.js.map

package/dist/entrypoints/insights.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.schemas.js","sourceRoot":"","sources":["../../src/entrypoints/insights.schemas.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,cAAc,iCAAiC,CAAA"}

package/dist/index.d.ts

@@ -10,8 +10,10 @@ export type * from './services/chart.schemas.js';
 export * from './services/chart.schemas.js';
 export type * from './services/geo.schemas.js';
 export * from './services/geo.schemas.js';
-export type { AlbumService, ArtistService, AuthService, ChartService, GeoService, LibraryService, TagService, TrackService, UserService, } from './services/index.js';
-export { createAlbumService, createArtistService, createAuthService, createChartService, createGeoService, createLibraryService, createTagService, createTrackService, createUserService, } from './services/index.js';
+export type { AlbumService, ArtistService, AuthService, ChartService, GeoService, InsightsService, LibraryService, TagService, TrackService, UserService, } from './services/index.js';
+export { createAlbumService, createArtistService, createAuthService, createChartService, createGeoService, createInsightsService, createLibraryService, createTagService, createTrackService, createUserService, } from './services/index.js';
+export type * from './services/insights.schemas.js';
+export * from './services/insights.schemas.js';
 export type * from './services/library.schemas.js';
 export * from './services/library.schemas.js';
 export type * from './services/schemas/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EACN,YAAY,EACZ,eAAe,EACf,KAAK,YAAY,EACjB,iBAAiB,EACjB,eAAe,GACf,MAAM,aAAa,CAAA;AACpB,mBAAmB,6BAA6B,CAAA;AAChD,cAAc,6BAA6B,CAAA;AAC3C,mBAAmB,8BAA8B,CAAA;AACjD,cAAc,8BAA8B,CAAA;AAC5C,mBAAmB,4BAA4B,CAAA;AAC/C,cAAc,4BAA4B,CAAA;AAC1C,mBAAmB,6BAA6B,CAAA;AAChD,cAAc,6BAA6B,CAAA;AAC3C,mBAAmB,2BAA2B,CAAA;AAC9C,cAAc,2BAA2B,CAAA;AAEzC,YAAY,EACX,YAAY,EACZ,aAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,EACV,cAAc,EACd,UAAU,EACV,YAAY,EACZ,WAAW,GACX,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GACjB,MAAM,qBAAqB,CAAA;AAC5B,mBAAmB,+BAA+B,CAAA;AAClD,cAAc,+BAA+B,CAAA;AAC7C,mBAAmB,6BAA6B,CAAA;AAChD,cAAc,6BAA6B,CAAA;AAC3C,mBAAmB,2BAA2B,CAAA;AAC9C,cAAc,2BAA2B,CAAA;AACzC,mBAAmB,6BAA6B,CAAA;AAChD,cAAc,6BAA6B,CAAA;AAE3C,mBAAmB,4BAA4B,CAAA;AAE/C,cAAc,4BAA4B,CAAA;AAG1C,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EACN,YAAY,EACZ,eAAe,EACf,KAAK,YAAY,EACjB,iBAAiB,EACjB,eAAe,GACf,MAAM,aAAa,CAAA;AACpB,mBAAmB,6BAA6B,CAAA;AAChD,cAAc,6BAA6B,CAAA;AAC3C,mBAAmB,8BAA8B,CAAA;AACjD,cAAc,8BAA8B,CAAA;AAC5C,mBAAmB,4BAA4B,CAAA;AAC/C,cAAc,4BAA4B,CAAA;AAC1C,mBAAmB,6BAA6B,CAAA;AAChD,cAAc,6BAA6B,CAAA;AAC3C,mBAAmB,2BAA2B,CAAA;AAC9C,cAAc,2BAA2B,CAAA;AAEzC,YAAY,EACX,YAAY,EACZ,aAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,cAAc,EACd,UAAU,EACV,YAAY,EACZ,WAAW,GACX,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GACjB,MAAM,qBAAqB,CAAA;AAC5B,mBAAmB,gCAAgC,CAAA;AACnD,cAAc,gCAAgC,CAAA;AAC9C,mBAAmB,+BAA+B,CAAA;AAClD,cAAc,+BAA+B,CAAA;AAC7C,mBAAmB,6BAA6B,CAAA;AAChD,cAAc,6BAA6B,CAAA;AAC3C,mBAAmB,2BAA2B,CAAA;AAC9C,cAAc,2BAA2B,CAAA;AACzC,mBAAmB,6BAA6B,CAAA;AAChD,cAAc,6BAA6B,CAAA;AAE3C,mBAAmB,4BAA4B,CAAA;AAE/C,cAAc,4BAA4B,CAAA;AAG1C,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -8,7 +8,8 @@ export * from './services/auth.schemas.js';
 export * from './services/chart.schemas.js';
 export * from './services/geo.schemas.js';
 // Servicios (para uso avanzado)
-export { createAlbumService, createArtistService, createAuthService, createChartService, createGeoService, createLibraryService, createTagService, createTrackService, createUserService, } from './services/index.js';
+export { createAlbumService, createArtistService, createAuthService, createChartService, createGeoService, createInsightsService, createLibraryService, createTagService, createTrackService, createUserService, } from './services/index.js';
+export * from './services/insights.schemas.js';
 export * from './services/library.schemas.js';
 export * from './services/schemas/index.js';
 export * from './services/tag.schemas.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAEhB,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EACN,YAAY,EACZ,eAAe,EAEf,iBAAiB,EACjB,eAAe,GACf,MAAM,aAAa,CAAA;AAEpB,cAAc,6BAA6B,CAAA;AAE3C,cAAc,8BAA8B,CAAA;AAE5C,cAAc,4BAA4B,CAAA;AAE1C,cAAc,6BAA6B,CAAA;AAE3C,cAAc,2BAA2B,CAAA;AAazC,gCAAgC;AAChC,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GACjB,MAAM,qBAAqB,CAAA;AAE5B,cAAc,+BAA+B,CAAA;AAE7C,cAAc,6BAA6B,CAAA;AAE3C,cAAc,2BAA2B,CAAA;AAEzC,cAAc,6BAA6B,CAAA;AAG3C,mCAAmC;AACnC,cAAc,4BAA4B,CAAA;AAE1C,oCAAoC;AACpC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAEhB,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EACN,YAAY,EACZ,eAAe,EAEf,iBAAiB,EACjB,eAAe,GACf,MAAM,aAAa,CAAA;AAEpB,cAAc,6BAA6B,CAAA;AAE3C,cAAc,8BAA8B,CAAA;AAE5C,cAAc,4BAA4B,CAAA;AAE1C,cAAc,6BAA6B,CAAA;AAE3C,cAAc,2BAA2B,CAAA;AAczC,gCAAgC;AAChC,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GACjB,MAAM,qBAAqB,CAAA;AAE5B,cAAc,gCAAgC,CAAA;AAE9C,cAAc,+BAA+B,CAAA;AAE7C,cAAc,6BAA6B,CAAA;AAE3C,cAAc,2BAA2B,CAAA;AAEzC,cAAc,6BAA6B,CAAA;AAG3C,mCAAmC;AACnC,cAAc,4BAA4B,CAAA;AAE1C,oCAAoC;AACpC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA"}

package/dist/services/index.d.ts

@@ -8,6 +8,8 @@ export * from './chart.js';
 export * from './chart.schemas.js';
 export * from './geo.js';
 export * from './geo.schemas.js';
+export * from './insights.js';
+export * from './insights.schemas.js';
 export * from './library.js';
 export * from './library.schemas.js';
 export * from './schemas/index.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AAEzB,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AAEzB,cAAc,mBAAmB,CAAA"}

package/dist/services/index.js

@@ -8,6 +8,8 @@ export * from './chart.js';
 export * from './chart.schemas.js';
 export * from './geo.js';
 export * from './geo.schemas.js';
+export * from './insights.js';
+export * from './insights.schemas.js';
 export * from './library.js';
 export * from './library.schemas.js';
 export * from './schemas/index.js';

package/dist/services/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,+BAA+B;AAC/B,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,+BAA+B;AAC/B,cAAc,mBAAmB,CAAA"}

package/dist/services/insights/binges.d.ts

@@ -0,0 +1,8 @@
+import type { LastFmConfig } from '../../config.js';
+import type { InsightsBingesRequest, InsightsBingesResponse } from '../insights.schemas.js';
+/**
+ * Detects binge listening streaks (consecutive plays of the same artist or track)
+ * across a user's recent scrobbles.
+ */
+export declare function getBinges(config: LastFmConfig, params: InsightsBingesRequest, init?: RequestInit): Promise<InsightsBingesResponse>;
+//# sourceMappingURL=binges.d.ts.map

package/dist/services/insights/binges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binges.d.ts","sourceRoot":"","sources":["../../../src/services/insights/binges.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAI3F;;;GAGG;AACH,wBAAsB,SAAS,CAC9B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,qBAAqB,EAC7B,IAAI,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,sBAAsB,CAAC,CAwDjC"}

package/dist/services/insights/binges.js

@@ -0,0 +1,53 @@
+import { createUserService } from '../user.js';
+import { findBinges } from './lib/binges.js';
+/**
+ * Detects binge listening streaks (consecutive plays of the same artist or track)
+ * across a user's recent scrobbles.
+ */
+export async function getBinges(config, params, init) {
+    const userService = createUserService(config);
+    const to = params.to ?? Math.floor(Date.now() / 1000);
+    const from = params.from ?? (params.sinceDays ? to - params.sinceDays * 86400 : to - 7 * 86400);
+    const maxPages = params.maxPages ?? 50;
+    const scrobbles = [];
+    let page = 1;
+    while (page <= maxPages) {
+        const res = await userService.getRecentTracks({
+            user: params.user,
+            from: String(from),
+            to: String(to),
+            limit: 200,
+            page,
+        }, init);
+        const tracks = res.recenttracks?.track ?? [];
+        for (const t of tracks) {
+            const rawArtist = t.artist;
+            const artist = typeof rawArtist === 'object' && rawArtist !== null
+                ? String(rawArtist.name ?? rawArtist['#text'] ?? '')
+                : String(rawArtist ?? '');
+            const track = String(t.name ?? '');
+            const uts = t.date?.uts ? Number(t.date.uts) : undefined;
+            if (artist.length > 0 && track.length > 0 && typeof uts === 'number' && !Number.isNaN(uts)) {
+                scrobbles.push({ artist, track, uts });
+            }
+        }
+        if (tracks.length < 200)
+            break;
+        page++;
+    }
+    // Recenttracks returns descending order; sort ascending for consecutive streak detection
+    scrobbles.sort((a, b) => a.uts - b.uts);
+    const trackKey = params.trackKey === true || params.trackKey === 'track' ? 'track' : 'artist';
+    const binges = findBinges(scrobbles, {
+        minLength: params.minLength,
+        maxGapSeconds: params.maxGapSeconds,
+        trackKey,
+        maxResults: params.maxResults,
+    });
+    return {
+        user: params.user,
+        totalScrobbles: scrobbles.length,
+        binges,
+    };
+}
+//# sourceMappingURL=binges.js.map

package/dist/services/insights/binges.js.map

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

package/dist/services/insights/compare.d.ts

@@ -0,0 +1,8 @@
+import type { LastFmConfig } from '../../config.js';
+import type { InsightsCompareRequest, InsightsCompareResponse } from '../insights.schemas.js';
+/**
+ * Compares two Last.fm users' listening affinity using Jaccard similarity
+ * over mutual top artist rosters.
+ */
+export declare function compareUsers(config: LastFmConfig, params: InsightsCompareRequest, init?: RequestInit): Promise<InsightsCompareResponse>;
+//# sourceMappingURL=compare.d.ts.map

package/dist/services/insights/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/services/insights/compare.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAK7F;;;GAGG;AACH,wBAAsB,YAAY,CACjC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,sBAAsB,EAC9B,IAAI,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,uBAAuB,CAAC,CAmClC"}

package/dist/services/insights/compare.js

@@ -0,0 +1,39 @@
+import { createUserService } from '../user.js';
+import { compareArtists } from './lib/compare.js';
+import { resolvePeriod } from './lib/periods.js';
+/**
+ * Compares two Last.fm users' listening affinity using Jaccard similarity
+ * over mutual top artist rosters.
+ */
+export async function compareUsers(config, params, init) {
+    const userService = createUserService(config);
+    const resolved = resolvePeriod(params.period ?? 'overall');
+    const limit = params.limit ?? 100;
+    const [topArtistsA, topArtistsB] = await Promise.all([
+        userService.getTopArtists({ user: params.userA, period: resolved.lastfm, limit }, init),
+        userService.getTopArtists({ user: params.userB, period: resolved.lastfm, limit }, init),
+    ]);
+    const rosterA = (topArtistsA.topartists?.artist ?? []).map((a) => ({
+        name: a.name,
+        playcount: Number(a.playcount ?? 0),
+    }));
+    const rosterB = (topArtistsB.topartists?.artist ?? []).map((b) => ({
+        name: b.name,
+        playcount: Number(b.playcount ?? 0),
+    }));
+    const comparison = compareArtists(rosterA, rosterB);
+    return {
+        userA: params.userA,
+        userB: params.userB,
+        period: resolved.lastfm,
+        compatibilityScore: comparison.compatibilityScore,
+        jaccard: comparison.jaccard,
+        sharedCount: comparison.intersection.length,
+        userACount: comparison.aCount,
+        userBCount: comparison.bCount,
+        sharedArtists: [...comparison.sharedArtists],
+        onlyUserA: [...comparison.onlyA],
+        onlyUserB: [...comparison.onlyB],
+    };
+}
+//# sourceMappingURL=compare.js.map

package/dist/services/insights/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../../src/services/insights/compare.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,cAAc,EAAyB,MAAM,kBAAkB,CAAA;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAEhD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,MAAoB,EACpB,MAA8B,EAC9B,IAAkB;IAElB,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAA;IAC7C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,IAAI,SAAS,CAAC,CAAA;IAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,GAAG,CAAA;IAEjC,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACpD,WAAW,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC;QACvF,WAAW,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC;KACvF,CAAC,CAAA;IAEF,MAAM,OAAO,GAAuB,CAAC,WAAW,CAAC,UAAU,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtF,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC;KACnC,CAAC,CAAC,CAAA;IAEH,MAAM,OAAO,GAAuB,CAAC,WAAW,CAAC,UAAU,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtF,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC;KACnC,CAAC,CAAC,CAAA;IAEH,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAEnD,OAAO;QACN,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,kBAAkB,EAAE,UAAU,CAAC,kBAAkB;QACjD,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,WAAW,EAAE,UAAU,CAAC,YAAY,CAAC,MAAM;QAC3C,UAAU,EAAE,UAAU,CAAC,MAAM;QAC7B,UAAU,EAAE,UAAU,CAAC,MAAM;QAC7B,aAAa,EAAE,CAAC,GAAG,UAAU,CAAC,aAAa,CAAC;QAC5C,SAAS,EAAE,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC;QAChC,SAAS,EAAE,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC;KAChC,CAAA;AACF,CAAC"}

package/dist/services/insights/discoveries.d.ts

@@ -0,0 +1,8 @@
+import type { LastFmConfig } from '../../config.js';
+import type { InsightsDiscoveriesRequest, InsightsDiscoveriesResponse } from '../insights.schemas.js';
+/**
+ * Detects newly discovered artists in a recent time window by comparing
+ * against the user's historical baseline roster.
+ */
+export declare function getDiscoveries(config: LastFmConfig, params: InsightsDiscoveriesRequest, init?: RequestInit): Promise<InsightsDiscoveriesResponse>;
+//# sourceMappingURL=discoveries.d.ts.map

package/dist/services/insights/discoveries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discoveries.d.ts","sourceRoot":"","sources":["../../../src/services/insights/discoveries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,KAAK,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAA;AAIrG;;;GAGG;AACH,wBAAsB,cAAc,CACnC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,0BAA0B,EAClC,IAAI,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,2BAA2B,CAAC,CA0DtC"}

package/dist/services/insights/discoveries.js

@@ -0,0 +1,53 @@
+import { createUserService } from '../user.js';
+import { findNewArtists } from './lib/discoveries.js';
+/**
+ * Detects newly discovered artists in a recent time window by comparing
+ * against the user's historical baseline roster.
+ */
+export async function getDiscoveries(config, params, init) {
+    const userService = createUserService(config);
+    const windowDays = params.windowDays ?? 7;
+    const to = params.to ?? Math.floor(Date.now() / 1000);
+    const from = params.from ?? to - windowDays * 86400;
+    const baselineLimit = params.baselineLimit ?? 200;
+    const maxPages = params.maxPages ?? 20;
+    const maxResults = params.maxResults ?? 20;
+    // 1. Fetch baseline overall top artists
+    const baselineRes = await userService.getTopArtists({ user: params.user, period: 'overall', limit: baselineLimit }, init);
+    const baselineSet = new Set((baselineRes.topartists?.artist ?? []).map((a) => a.name));
+    // 2. Fetch window recent tracks
+    const windowScrobbles = [];
+    let page = 1;
+    while (page <= maxPages) {
+        const recentRes = await userService.getRecentTracks({
+            user: params.user,
+            from: String(from),
+            to: String(to),
+            limit: 200,
+            page,
+        }, init);
+        const tracks = recentRes.recenttracks?.track ?? [];
+        for (const t of tracks) {
+            const rawArtist = t.artist;
+            const artistName = typeof rawArtist === 'object' && rawArtist !== null
+                ? String(rawArtist.name ?? rawArtist['#text'] ?? '')
+                : String(rawArtist ?? '');
+            const uts = t.date?.uts ? Number(t.date.uts) : undefined;
+            if (artistName.length > 0 && typeof uts === 'number' && !Number.isNaN(uts)) {
+                windowScrobbles.push({ name: artistName, firstSeen: uts });
+            }
+        }
+        if (tracks.length < 200)
+            break;
+        page++;
+    }
+    const discoveries = findNewArtists(windowScrobbles, baselineSet, { maxResults });
+    return {
+        user: params.user,
+        windowDays,
+        baselineSize: baselineSet.size,
+        totalDiscovered: discoveries.length,
+        discoveries,
+    };
+}
+//# sourceMappingURL=discoveries.js.map

package/dist/services/insights/discoveries.js.map

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

package/dist/services/insights/hours.d.ts

@@ -0,0 +1,8 @@
+import type { LastFmConfig } from '../../config.js';
+import type { InsightsHoursRequest, InsightsHoursResponse } from '../insights.schemas.js';
+/**
+ * Buckets a user's recent scrobbles by hour-of-day (0..23) and weekday (0..6),
+ * calculating diurnal distribution and peak listening times.
+ */
+export declare function getHoursHistogram(config: LastFmConfig, params: InsightsHoursRequest, init?: RequestInit): Promise<InsightsHoursResponse>;
+//# sourceMappingURL=hours.d.ts.map

package/dist/services/insights/hours.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hours.d.ts","sourceRoot":"","sources":["../../../src/services/insights/hours.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAIzF;;;GAGG;AACH,wBAAsB,iBAAiB,CACtC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,oBAAoB,EAC5B,IAAI,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,qBAAqB,CAAC,CA0ChC"}

package/dist/services/insights/hours.js

@@ -0,0 +1,43 @@
+import { createUserService } from '../user.js';
+import { buildHourHistogram } from './lib/hours.js';
+/**
+ * Buckets a user's recent scrobbles by hour-of-day (0..23) and weekday (0..6),
+ * calculating diurnal distribution and peak listening times.
+ */
+export async function getHoursHistogram(config, params, init) {
+    const userService = createUserService(config);
+    const to = params.to ?? Math.floor(Date.now() / 1000);
+    const from = params.from ?? (params.sinceDays ? to - params.sinceDays * 86400 : to - 30 * 86400);
+    const maxPages = params.maxPages ?? 50;
+    const timestamps = [];
+    let page = 1;
+    while (page <= maxPages) {
+        const res = await userService.getRecentTracks({
+            user: params.user,
+            from: String(from),
+            to: String(to),
+            limit: 200,
+            page,
+        }, init);
+        const tracks = res.recenttracks?.track ?? [];
+        for (const t of tracks) {
+            const uts = t.date?.uts;
+            if (uts) {
+                const num = Number(uts);
+                if (!Number.isNaN(num))
+                    timestamps.push(num);
+            }
+        }
+        if (tracks.length < 200)
+            break;
+        page++;
+    }
+    const histogram = buildHourHistogram(timestamps);
+    return {
+        user: params.user,
+        from,
+        to,
+        ...histogram,
+    };
+}
+//# sourceMappingURL=hours.js.map

package/dist/services/insights/hours.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hours.js","sourceRoot":"","sources":["../../../src/services/insights/hours.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,MAAoB,EACpB,MAA4B,EAC5B,IAAkB;IAElB,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAA;IAC7C,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;IACrD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,CAAA;IAChG,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAA;IAEtC,MAAM,UAAU,GAAa,EAAE,CAAA;IAC/B,IAAI,IAAI,GAAG,CAAC,CAAA;IAEZ,OAAO,IAAI,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,eAAe,CAC5C;YACC,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC;YAClB,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC;YACd,KAAK,EAAE,GAAG;YACV,IAAI;SACJ,EACD,IAAI,CACJ,CAAA;QAED,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,EAAE,KAAK,IAAI,EAAE,CAAA;QAC5C,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACxB,MAAM,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,CAAA;YACvB,IAAI,GAAG,EAAE,CAAC;gBACT,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;gBACvB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;oBAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YAC7C,CAAC;QACF,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,GAAG,GAAG;YAAE,MAAK;QAC9B,IAAI,EAAE,CAAA;IACP,CAAC;IAED,MAAM,SAAS,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAA;IAEhD,OAAO;QACN,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI;QACJ,EAAE;QACF,GAAG,SAAS;KACZ,CAAA;AACF,CAAC"}

package/dist/services/insights/lib/binges.d.ts

@@ -0,0 +1,31 @@
+/**
+ * binges.ts — detect binge listening runs from a list of scrobbles.
+ *
+ * Groups consecutive plays of the same artist or track where the gap
+ * between adjacent scrobbles does not exceed maxGapSeconds (default 1h).
+ */
+export interface ScrobbleItem {
+    readonly artist: string;
+    readonly track: string;
+    readonly uts: number;
+}
+export type BingesTrackKey = 'artist' | 'track';
+export interface BingeItem {
+    readonly artist: string;
+    readonly track?: string;
+    readonly length: number;
+    readonly startUts: number;
+    readonly endUts: number;
+    readonly durationSeconds: number;
+}
+export interface FindBingesOptions {
+    readonly minLength?: number;
+    readonly maxGapSeconds?: number;
+    readonly trackKey?: BingesTrackKey;
+    readonly maxResults?: number;
+}
+/**
+ * Finds consecutive listening runs in a chronologically ordered array of scrobbles.
+ */
+export declare function findBinges(scrobbles: readonly ScrobbleItem[], options?: FindBingesOptions): BingeItem[];
+//# sourceMappingURL=binges.d.ts.map