@ansango/lastfm-api 3.2.0 → 3.4.0

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"binges.d.ts","sourceRoot":"","sources":["../../../../src/services/insights/lib/binges.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE/C,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAChC;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC5B;AAMD;;GAEG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,EAAE,OAAO,GAAE,iBAAsB,GAAG,SAAS,EAAE,CAyD3G"}

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

@@ -0,0 +1,61 @@
+function keyOf(s, k) {
+    return k === 'artist' ? s.artist : `${s.artist}::${s.track}`;
+}
+/**
+ * Finds consecutive listening runs in a chronologically ordered array of scrobbles.
+ */
+export function findBinges(scrobbles, options = {}) {
+    const minLength = options.minLength ?? 2;
+    const maxGap = options.maxGapSeconds ?? 3600;
+    const trackKey = options.trackKey ?? 'artist';
+    const out = [];
+    let runKey = null;
+    let runArtist = null;
+    let runTrack = null;
+    let runStart = 0;
+    let runEnd = 0;
+    let runLen = 0;
+    const flush = () => {
+        if (runLen >= minLength && runKey !== null && runArtist !== null) {
+            out.push({
+                artist: runArtist,
+                ...(trackKey === 'track' && runTrack !== null ? { track: runTrack } : {}),
+                length: runLen,
+                startUts: runStart,
+                endUts: runEnd,
+                durationSeconds: runEnd - runStart,
+            });
+        }
+        runKey = null;
+        runLen = 0;
+    };
+    for (const s of scrobbles) {
+        const k = keyOf(s, trackKey);
+        if (runKey === null) {
+            runKey = k;
+            runArtist = s.artist;
+            runTrack = s.track;
+            runStart = s.uts;
+            runEnd = s.uts;
+            runLen = 1;
+            continue;
+        }
+        if (k !== runKey || s.uts - runEnd > maxGap) {
+            flush();
+            runKey = k;
+            runArtist = s.artist;
+            runTrack = s.track;
+            runStart = s.uts;
+            runEnd = s.uts;
+            runLen = 1;
+            continue;
+        }
+        runEnd = s.uts;
+        runLen++;
+    }
+    flush();
+    // Sort primarily by run length descending, secondarily by most recent
+    out.sort((a, b) => b.length - a.length || b.endUts - a.endUts);
+    return options.maxResults !== undefined ? out.slice(0, options.maxResults) : out;
+}
+//# sourceMappingURL=binges.js.map

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

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

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

@@ -0,0 +1,31 @@
+/**
+ * compare.ts — compare two ranked artist lists and compute Jaccard similarity.
+ */
+export interface NamedArtistEntry {
+    readonly name: string;
+    readonly playcount: number;
+}
+export interface CompareArtistsResult {
+    readonly aCount: number;
+    readonly bCount: number;
+    readonly intersection: readonly string[];
+    readonly sharedArtists: ReadonlyArray<{
+        readonly name: string;
+        readonly userAPlaycount: number;
+        readonly userBPlaycount: number;
+        readonly weight: number;
+    }>;
+    readonly onlyA: readonly string[];
+    readonly onlyB: readonly string[];
+    readonly jaccard: number;
+    readonly compatibilityScore: number;
+}
+/**
+ * Computes Jaccard similarity: |A ∩ B| / |A ∪ B|.
+ */
+export declare function jaccard<T>(a: ReadonlySet<T>, b: ReadonlySet<T>): number;
+/**
+ * Compares two artist rosters, calculating mutual artist overlap and affinity metrics.
+ */
+export declare function compareArtists(a: readonly NamedArtistEntry[], b: readonly NamedArtistEntry[]): CompareArtistsResult;
+//# sourceMappingURL=compare.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../../src/services/insights/lib/compare.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;QACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;QAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;QAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KACvB,CAAC,CAAA;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;CACnC;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,CASvE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,gBAAgB,EAAE,EAAE,CAAC,EAAE,SAAS,gBAAgB,EAAE,GAAG,oBAAoB,CA+CnH"}

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

@@ -0,0 +1,68 @@
+/**
+ * Computes Jaccard similarity: |A ∩ B| / |A ∪ B|.
+ */
+export function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const x of a) {
+        if (b.has(x))
+            inter++;
+    }
+    const union = a.size + b.size - inter;
+    if (union === 0)
+        return 0;
+    return inter / union;
+}
+/**
+ * Compares two artist rosters, calculating mutual artist overlap and affinity metrics.
+ */
+export function compareArtists(a, b) {
+    const mapA = new Map();
+    const mapB = new Map();
+    for (const x of a)
+        mapA.set(x.name, x.playcount);
+    for (const x of b)
+        mapB.set(x.name, x.playcount);
+    const intersection = [];
+    const onlyA = [];
+    const onlyB = [];
+    for (const [name] of mapA) {
+        if (mapB.has(name))
+            intersection.push(name);
+        else
+            onlyA.push(name);
+    }
+    for (const [name] of mapB) {
+        if (!mapA.has(name))
+            onlyB.push(name);
+    }
+    const sharedArtists = intersection
+        .map((name) => {
+        const userAPlaycount = mapA.get(name) ?? 0;
+        const userBPlaycount = mapB.get(name) ?? 0;
+        const weight = Math.min(userAPlaycount, userBPlaycount);
+        return {
+            name,
+            userAPlaycount,
+            userBPlaycount,
+            weight,
+        };
+    })
+        .sort((x, y) => y.weight - x.weight);
+    const setA = new Set(mapA.keys());
+    const setB = new Set(mapB.keys());
+    const j = jaccard(setA, setB);
+    const compatibilityScore = Math.round(j * 100);
+    return {
+        aCount: a.length,
+        bCount: b.length,
+        intersection: intersection.sort(),
+        sharedArtists,
+        onlyA: onlyA.sort(),
+        onlyB: onlyB.sort(),
+        jaccard: Math.round(j * 1000) / 1000,
+        compatibilityScore,
+    };
+}
+//# sourceMappingURL=compare.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../../../src/services/insights/lib/compare.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,MAAM,UAAU,OAAO,CAAI,CAAiB,EAAE,CAAiB;IAC9D,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAC1C,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,KAAK,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,KAAK,EAAE,CAAA;IACtB,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,GAAG,KAAK,CAAA;IACrC,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IACzB,OAAO,KAAK,GAAG,KAAK,CAAA;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,CAA8B,EAAE,CAA8B;IAC5F,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAA;IACtC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAA;IACtC,KAAK,MAAM,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,CAAA;IAChD,KAAK,MAAM,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,CAAA;IAEhD,MAAM,YAAY,GAAa,EAAE,CAAA;IACjC,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;;YACtC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACtB,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACtC,CAAC;IAED,MAAM,aAAa,GAAG,YAAY;SAChC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACb,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC1C,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,cAAc,CAAC,CAAA;QACvD,OAAO;YACN,IAAI;YACJ,cAAc;YACd,cAAc;YACd,MAAM;SACN,CAAA;IACF,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAA;IAErC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;IACjC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAC7B,MAAM,kBAAkB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,CAAA;IAE9C,OAAO;QACN,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,YAAY,EAAE,YAAY,CAAC,IAAI,EAAE;QACjC,aAAa;QACb,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE;QACnB,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE;QACnB,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI;QACpC,kBAAkB;KAClB,CAAA;AACF,CAAC"}

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

@@ -0,0 +1,17 @@
+/**
+ * discoveries.ts — detect newly discovered artists inside a time window
+ * relative to an overall baseline roster.
+ */
+export interface ArtistTimestampItem {
+    readonly name: string;
+    /** UNIX seconds; the earliest occurrence of this artist in the window. */
+    readonly firstSeen: number;
+}
+export interface FindNewArtistsOptions {
+    readonly maxResults?: number;
+}
+/**
+ * Filters and sorts artists first scrobbled in the window that do not exist in the baseline set.
+ */
+export declare function findNewArtists(window: readonly ArtistTimestampItem[], baseline: ReadonlySet<string>, options?: FindNewArtistsOptions): ArtistTimestampItem[];
+//# sourceMappingURL=discoveries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discoveries.d.ts","sourceRoot":"","sources":["../../../../src/services/insights/lib/discoveries.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,EAC7B,OAAO,GAAE,qBAA0B,GACjC,mBAAmB,EAAE,CAqBvB"}

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

@@ -0,0 +1,24 @@
+/**
+ * Filters and sorts artists first scrobbled in the window that do not exist in the baseline set.
+ */
+export function findNewArtists(window, baseline, options = {}) {
+    // Dedupe by name; keep earliest firstSeen
+    const earliest = new Map();
+    for (const a of window) {
+        const prev = earliest.get(a.name);
+        if (prev === undefined || a.firstSeen < prev) {
+            earliest.set(a.name, a.firstSeen);
+        }
+    }
+    const newbies = [];
+    for (const [name, firstSeen] of earliest) {
+        if (!baseline.has(name)) {
+            newbies.push({ name, firstSeen });
+        }
+    }
+    // Sort chronologically by first seen
+    newbies.sort((a, b) => a.firstSeen - b.firstSeen);
+    const max = options.maxResults ?? newbies.length;
+    return newbies.slice(0, max);
+}
+//# sourceMappingURL=discoveries.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discoveries.js","sourceRoot":"","sources":["../../../../src/services/insights/lib/discoveries.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,UAAU,cAAc,CAC7B,MAAsC,EACtC,QAA6B,EAC7B,UAAiC,EAAE;IAEnC,0CAA0C;IAC1C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAA;IAC1C,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACjC,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,GAAG,IAAI,EAAE,CAAC;YAC9C,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,CAAA;QAClC,CAAC;IACF,CAAC;IAED,MAAM,OAAO,GAA0B,EAAE,CAAA;IACzC,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC1C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAA;QAClC,CAAC;IACF,CAAC;IAED,qCAAqC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAA;IACjD,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,MAAM,CAAA;IAChD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;AAC7B,CAAC"}

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

@@ -0,0 +1,28 @@
+/**
+ * diversity.ts — Shannon entropy + top-N concentration over a count map.
+ *
+ * Pure: takes a {name: count} map and returns normalized metrics.
+ *
+ * Shannon entropy H = -Σ pᵢ ln(pᵢ) where pᵢ = countᵢ / total.
+ * Normalized H / ln(uniqueCount) puts it on [0, 1].
+ */
+export type CountMap = Readonly<Record<string, number>>;
+export interface Diversity {
+    readonly total: number;
+    readonly uniqueCount: number;
+    /** Raw Shannon entropy in nats. */
+    readonly shannon: number;
+    /** Shannon normalized to [0, 1] by dividing by ln(uniqueCount). 1 = perfectly even. */
+    readonly normalized: number;
+}
+/**
+ * Computes the Shannon diversity index over a map of item counts.
+ */
+export declare function computeDiversity(counts: CountMap): Diversity;
+/**
+ * Fraction of total plays consumed by the top-N entries.
+ * - N larger than uniqueCount returns 1.
+ * - Empty map returns 0.
+ */
+export declare function topNShare(counts: CountMap, n: number): number;
+//# sourceMappingURL=diversity.d.ts.map

package/dist/services/insights/lib/diversity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diversity.d.ts","sourceRoot":"","sources":["../../../../src/services/insights/lib/diversity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAEvD,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC3B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAiB5D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAS7D"}