@ansango/lastfm-api 3.3.0 → 3.5.0

package/dist/insights/algorithms/now-playing.js

@@ -0,0 +1,128 @@
+import { createArtistService } from '../../core/services/artist.js';
+import { createUserService } from '../../core/services/user.js';
+/**
+ * Strips Last.fm wiki markup and HTML tags from biography text.
+ */
+export function stripWiki(s) {
+    return s
+        .replace(/\[\[([^|\]]+)\|([^\]]+)\]\]/g, '$2')
+        .replace(/\[\[([^\]]+)\]\]/g, '$1')
+        .replace(/<[^>]+>/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Truncates biography text cleanly on a word boundary.
+ */
+export function summarizeBio(bio, maxChars) {
+    if (!bio)
+        return '';
+    const clean = stripWiki(bio);
+    if (clean.length <= maxChars)
+        return clean;
+    const cut = clean.slice(0, maxChars);
+    const lastSpace = cut.lastIndexOf(' ');
+    return `${lastSpace > 0 ? cut.slice(0, lastSpace) : cut}…`;
+}
+/**
+ * Finds the highest quality image available from a Last.fm image array.
+ */
+export function findBestImage(images) {
+    if (!Array.isArray(images))
+        return undefined;
+    const order = ['mega', 'extralarge', 'large', 'medium', 'small'];
+    for (const size of order) {
+        const hit = images.find((i) => i?.size === size && typeof i['#text'] === 'string' && i['#text'].length > 0);
+        if (hit)
+            return hit['#text'];
+    }
+    return undefined;
+}
+/**
+ * Fetches the user's current (or most recent) track and enriches it with
+ * artist biography and similar artists.
+ */
+export async function getNowPlaying(config, params, init) {
+    const similarLimit = typeof params.similarLimit === 'string' ? Number.parseInt(params.similarLimit, 10) : (params.similarLimit ?? 3);
+    const bioMaxChars = params.bioMaxChars ?? 320;
+    const userService = createUserService(config);
+    const artistService = createArtistService(config);
+    const recentRes = await userService.getRecentTracks({ user: params.user, limit: 1 }, init);
+    const tracks = recentRes.recenttracks?.track ?? [];
+    if (tracks.length === 0) {
+        return {
+            user: params.user,
+            nowPlaying: false,
+            track: { name: '' },
+            artist: { name: '' },
+            bio: '',
+            similar: [],
+        };
+    }
+    const last = tracks[0];
+    const attr = (last['@attr'] ?? recentRes.recenttracks?.['@attr']);
+    const nowPlaying = attr?.nowplaying === 'true' || attr?.nowplaying === true;
+    const trackName = String(last.name ?? '');
+    const rawArtist = last.artist;
+    const artistName = typeof rawArtist === 'object' && rawArtist !== null
+        ? String(rawArtist.name ?? rawArtist['#text'] ?? '')
+        : String(rawArtist ?? '');
+    const rawAlbum = last.album;
+    const album = typeof rawAlbum === 'object' && rawAlbum !== null
+        ? String(rawAlbum['#text'] ?? rawAlbum.title ?? '')
+        : typeof rawAlbum === 'string'
+            ? rawAlbum
+            : undefined;
+    const image = findBestImage(last.image);
+    let bio = '';
+    let artistMbid = typeof rawArtist === 'object' && rawArtist !== null ? rawArtist.mbid : undefined;
+    let artistUrl = typeof rawArtist === 'object' && rawArtist !== null ? rawArtist.url : undefined;
+    const similar = [];
+    if (artistName.length > 0) {
+        try {
+            const [infoRes, similarRes] = await Promise.all([
+                artistService.getInfo({ artist: artistName }, init),
+                artistService.getSimilar({ artist: artistName, limit: similarLimit }, init),
+            ]);
+            const bioSummary = infoRes.artist?.bio?.summary ?? infoRes.artist?.bio?.content ?? '';
+            bio = summarizeBio(bioSummary, bioMaxChars);
+            if (!artistMbid && infoRes.artist?.mbid) {
+                artistMbid = infoRes.artist.mbid;
+            }
+            if (!artistUrl && infoRes.artist?.url) {
+                artistUrl = infoRes.artist.url;
+            }
+            const rawSimilar = similarRes.similarartists?.artist ?? [];
+            for (const s of rawSimilar.slice(0, similarLimit)) {
+                const matchNum = Number(s.match);
+                similar.push({
+                    name: s.name,
+                    url: s.url || undefined,
+                    match: Number.isNaN(matchNum) ? undefined : matchNum,
+                });
+            }
+        }
+        catch {
+            // Best-effort enrichment: if artist lookup fails, still return track & artist data
+        }
+    }
+    return {
+        user: params.user,
+        nowPlaying,
+        track: {
+            name: trackName,
+            mbid: typeof last.mbid === 'string' && last.mbid.length > 0 ? last.mbid : undefined,
+            url: typeof last.url === 'string' && last.url.length > 0 ? last.url : undefined,
+        },
+        artist: {
+            name: artistName,
+            mbid: artistMbid || undefined,
+            url: artistUrl || undefined,
+        },
+        album: album || undefined,
+        image,
+        bio,
+        similar,
+    };
+}
+//# sourceMappingURL=now-playing.js.map

package/dist/insights/algorithms/now-playing.js.map

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

package/dist/insights/algorithms/obscurity.d.ts

@@ -0,0 +1,27 @@
+import type { LastFmConfig } from '../../config.js';
+import type { InsightsObscurityRequest, InsightsObscurityResponse } from '../schemas.js';
+/**
+ * Calculates obscurity score (0-100) for a given global listener count.
+ * Logarithmic mapping where:
+ * <= 10 listeners -> 100 (Ultra obscure)
+ * 100 listeners -> ~82
+ * 1,000 listeners -> ~65
+ * 10,000 listeners -> ~47
+ * 100,000 listeners -> ~30
+ * 1,000,000 listeners -> ~12
+ * >= 5,000,000 listeners -> 0 (Mega mainstream)
+ */
+export declare function calculateArtistObscurity(listeners: number): number;
+/**
+ * Categorizes the overall obscurity score.
+ */
+export declare function categorizeObscurity(score: number): {
+    category: 'Purist Underground' | 'Indie Explorer' | 'Balanced Listener' | 'Mainstream Enthusiast' | 'Chart Chaser';
+    description: string;
+};
+/**
+ * Evaluates the user's top artists against global Last.fm popularity metrics to calculate
+ * an Obscurity / Hipster score.
+ */
+export declare function getObscurityScore(config: LastFmConfig, params: InsightsObscurityRequest, init?: RequestInit): Promise<InsightsObscurityResponse>;
+//# sourceMappingURL=obscurity.d.ts.map

package/dist/insights/algorithms/obscurity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"obscurity.d.ts","sourceRoot":"","sources":["../../../src/insights/algorithms/obscurity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAInD,OAAO,KAAK,EAAwB,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAA;AAE9G;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOlE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG;IACnD,QAAQ,EAAE,oBAAoB,GAAG,gBAAgB,GAAG,mBAAmB,GAAG,uBAAuB,GAAG,cAAc,CAAA;IAClH,WAAW,EAAE,MAAM,CAAA;CACnB,CA6BA;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACtC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,wBAAwB,EAChC,IAAI,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,yBAAyB,CAAC,CA8GpC"}

package/dist/insights/algorithms/obscurity.js

@@ -0,0 +1,158 @@
+import { createArtistService } from '../../core/services/artist.js';
+import { createUserService } from '../../core/services/user.js';
+import { resolvePeriod } from '../lib/periods.js';
+/**
+ * Calculates obscurity score (0-100) for a given global listener count.
+ * Logarithmic mapping where:
+ * <= 10 listeners -> 100 (Ultra obscure)
+ * 100 listeners -> ~82
+ * 1,000 listeners -> ~65
+ * 10,000 listeners -> ~47
+ * 100,000 listeners -> ~30
+ * 1,000,000 listeners -> ~12
+ * >= 5,000,000 listeners -> 0 (Mega mainstream)
+ */
+export function calculateArtistObscurity(listeners) {
+    if (listeners <= 1)
+        return 100;
+    const minLog = 1; // log10(10)
+    const maxLog = 6.7; // log10(5,000,000)
+    const logVal = Math.log10(Math.max(1, listeners));
+    const popularity = Math.min(100, Math.max(0, ((logVal - minLog) / (maxLog - minLog)) * 100));
+    return Math.round((100 - popularity) * 100) / 100;
+}
+/**
+ * Categorizes the overall obscurity score.
+ */
+export function categorizeObscurity(score) {
+    if (score >= 80) {
+        return {
+            category: 'Purist Underground',
+            description: 'Deep underground affinity with predominantly niche, indie, and obscure artists.',
+        };
+    }
+    if (score >= 60) {
+        return {
+            category: 'Indie Explorer',
+            description: 'Strong indie and underground inclination with minimal mainstream exposure.',
+        };
+    }
+    if (score >= 40) {
+        return {
+            category: 'Balanced Listener',
+            description: 'Eclectic balance between popular cultural staples and underground acts.',
+        };
+    }
+    if (score >= 20) {
+        return {
+            category: 'Mainstream Enthusiast',
+            description: 'Tilted towards widely recognized artists, established headliners, and chart staples.',
+        };
+    }
+    return {
+        category: 'Chart Chaser',
+        description: 'Dominated by global superstar acts, viral sensations, and mega-hits.',
+    };
+}
+/**
+ * Evaluates the user's top artists against global Last.fm popularity metrics to calculate
+ * an Obscurity / Hipster score.
+ */
+export async function getObscurityScore(config, params, init) {
+    const limit = Math.min(50, typeof params.limit === 'string' ? Number.parseInt(params.limit, 10) : (params.limit ?? 20));
+    const resolved = resolvePeriod(params.period ?? 'overall');
+    const period = params.period ?? 'overall';
+    const userService = createUserService(config);
+    const artistService = createArtistService(config);
+    // Fetch top artists for user
+    const topRes = await userService.getTopArtists({ user: params.user, period: resolved.lastfm, limit }, init);
+    const rawArtists = topRes.topartists?.artist ?? [];
+    const artistList = Array.isArray(rawArtists) ? rawArtists : [rawArtists];
+    if (artistList.length === 0) {
+        const { category, description } = categorizeObscurity(50);
+        return {
+            user: params.user,
+            period,
+            obscurityScore: 50,
+            category,
+            description,
+            totalArtistsEvaluated: 0,
+            averageGlobalListeners: 0,
+            medianGlobalListeners: 0,
+            hiddenGems: [],
+            mainstreamAnchors: [],
+            artists: [],
+        };
+    }
+    // Fetch global artist info in parallel
+    const infoPromises = artistList.map(async (art) => {
+        const name = art.name;
+        const userPlaycount = Number.parseInt(art.playcount ?? '0', 10) || 0;
+        try {
+            const infoRes = await artistService.getInfo({ artist: name }, init);
+            const globalListeners = Number.parseInt(infoRes.artist?.stats?.listeners ?? '0', 10) || 0;
+            const globalPlaycount = Number.parseInt(infoRes.artist?.stats?.playcount ?? '0', 10) || 0;
+            const obscurityScore = calculateArtistObscurity(globalListeners);
+            return {
+                name,
+                userPlaycount,
+                globalListeners,
+                globalPlaycount,
+                obscurityScore,
+                url: infoRes.artist?.url,
+            };
+        }
+        catch {
+            // Fallback if individual artist info fails
+            const globalListeners = 100000;
+            const obscurityScore = calculateArtistObscurity(globalListeners);
+            return {
+                name,
+                userPlaycount,
+                globalListeners,
+                globalPlaycount: 0,
+                obscurityScore,
+            };
+        }
+    });
+    const evaluatedArtists = await Promise.all(infoPromises);
+    // Calculate weighted obscurity score
+    const totalPlaycount = evaluatedArtists.reduce((acc, a) => acc + a.userPlaycount, 0);
+    let weightedScoreSum = 0;
+    for (const a of evaluatedArtists) {
+        const weight = totalPlaycount > 0 ? a.userPlaycount / totalPlaycount : 1 / evaluatedArtists.length;
+        weightedScoreSum += a.obscurityScore * weight;
+    }
+    const overallObscurity = Math.round(weightedScoreSum * 100) / 100;
+    const { category, description } = categorizeObscurity(overallObscurity);
+    // Global listeners stats
+    const listenerCounts = evaluatedArtists.map((a) => a.globalListeners).sort((a, b) => a - b);
+    const avgListeners = Math.round(listenerCounts.reduce((acc, l) => acc + l, 0) / evaluatedArtists.length);
+    const mid = Math.floor(listenerCounts.length / 2);
+    const medianListeners = listenerCounts.length % 2 !== 0
+        ? listenerCounts[mid]
+        : Math.round((listenerCounts[mid - 1] + listenerCounts[mid]) / 2);
+    // Hidden gems: global listeners < 100,000 (or lowest 3 if all are >= 100k)
+    const gems = evaluatedArtists
+        .filter((a) => a.globalListeners < 100000)
+        .sort((a, b) => a.globalListeners - b.globalListeners);
+    const hiddenGems = gems.length > 0
+        ? gems.slice(0, 5)
+        : [...evaluatedArtists].sort((a, b) => a.globalListeners - b.globalListeners).slice(0, 3);
+    // Mainstream anchors: top 3 highest global listener counts
+    const mainstreamAnchors = [...evaluatedArtists].sort((a, b) => b.globalListeners - a.globalListeners).slice(0, 3);
+    return {
+        user: params.user,
+        period,
+        obscurityScore: overallObscurity,
+        category,
+        description,
+        totalArtistsEvaluated: evaluatedArtists.length,
+        averageGlobalListeners: avgListeners,
+        medianGlobalListeners: medianListeners,
+        hiddenGems,
+        mainstreamAnchors,
+        artists: evaluatedArtists.sort((a, b) => a.obscurityScore - b.obscurityScore),
+    };
+}
+//# sourceMappingURL=obscurity.js.map

package/dist/insights/algorithms/obscurity.js.map

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

package/dist/insights/algorithms/personality.d.ts

@@ -0,0 +1,8 @@
+import type { LastFmConfig } from '../../config.js';
+import type { InsightsPersonalityRequest, InsightsPersonalityResponse } from '../schemas.js';
+/**
+ * Derives a holistic listener personality archetype (The Devotee, The Explorer,
+ * The Drifter, The DJ, The Nocturnal, The Archivist) based on multidimensional feature vectors.
+ */
+export declare function getPersonality(config: LastFmConfig, params: InsightsPersonalityRequest, init?: RequestInit): Promise<InsightsPersonalityResponse>;
+//# sourceMappingURL=personality.d.ts.map

package/dist/insights/algorithms/personality.d.ts.map

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

package/dist/insights/algorithms/personality.js

@@ -0,0 +1,42 @@
+import { ARCHETYPE_INFO, scoreArchetypes } from '../lib/personality.js';
+import { getDiscoveries } from './discoveries.js';
+import { getHoursHistogram } from './hours.js';
+import { getSummary } from './summary.js';
+/**
+ * Derives a holistic listener personality archetype (The Devotee, The Explorer,
+ * The Drifter, The DJ, The Nocturnal, The Archivist) based on multidimensional feature vectors.
+ */
+export async function getPersonality(config, params, init) {
+    const [summary, histogram, discoveries] = await Promise.all([
+        getSummary(config, { user: params.user, period: '1month', limit: 30 }, init),
+        getHoursHistogram(config, { user: params.user, sinceDays: 30 }, init),
+        getDiscoveries(config, { user: params.user, windowDays: 30, baselineLimit: 200, maxResults: 100 }, init),
+    ]);
+    const features = {
+        totalScrobbles: summary.totalScrobbles,
+        uniqueArtists: summary.topArtists.length,
+        top1Share: summary.diversity?.top1Share ?? 0,
+        top3Share: summary.diversity?.top3Share ?? 0,
+        top5Share: summary.diversity?.top5Share ?? 0,
+        normalizedDiversity: summary.diversity?.normalized ?? 0.5,
+        newArtistsLast30d: discoveries.totalDiscovered,
+        totalArtistsLast30d: summary.topArtists.length,
+        nightHourShare: histogram.nightShare,
+        morningHourShare: histogram.morningShare,
+        weekdayShare: 1 - histogram.weekendShare,
+    };
+    const result = scoreArchetypes(features);
+    const archetype = {
+        id: result.winner,
+        ...ARCHETYPE_INFO[result.winner],
+    };
+    return {
+        user: params.user,
+        winner: result.winner,
+        archetype,
+        scores: result.scores,
+        reasons: [...result.reasons],
+        features,
+    };
+}
+//# sourceMappingURL=personality.js.map

package/dist/insights/algorithms/personality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"personality.js","sourceRoot":"","sources":["../../../src/insights/algorithms/personality.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAA4B,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEjG,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,MAAoB,EACpB,MAAkC,EAClC,IAAkB;IAElB,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC3D,UAAU,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC;QAC5E,iBAAiB,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC;QACrE,cAAc,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,aAAa,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,IAAI,CAAC;KACxG,CAAC,CAAA;IAEF,MAAM,QAAQ,GAAwB;QACrC,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,MAAM;QACxC,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,IAAI,CAAC;QAC5C,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,IAAI,CAAC;QAC5C,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,IAAI,CAAC;QAC5C,mBAAmB,EAAE,OAAO,CAAC,SAAS,EAAE,UAAU,IAAI,GAAG;QACzD,iBAAiB,EAAE,WAAW,CAAC,eAAe;QAC9C,mBAAmB,EAAE,OAAO,CAAC,UAAU,CAAC,MAAM;QAC9C,cAAc,EAAE,SAAS,CAAC,UAAU;QACpC,gBAAgB,EAAE,SAAS,CAAC,YAAY;QACxC,YAAY,EAAE,CAAC,GAAG,SAAS,CAAC,YAAY;KACxC,CAAA;IAED,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;IACxC,MAAM,SAAS,GAAG;QACjB,EAAE,EAAE,MAAM,CAAC,MAAM;QACjB,GAAG,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC;KAChC,CAAA;IAED,OAAO;QACN,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS;QACT,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC;QAC5B,QAAQ;KACR,CAAA;AACF,CAAC"}

package/dist/insights/algorithms/recommendations.d.ts

@@ -0,0 +1,11 @@
+import type { LastFmConfig } from '../../config.js';
+import type { InsightsBridgeArtistsRequest, InsightsBridgeArtistsResponse, InsightsRecommendationsRequest, InsightsRecommendationsResponse } from '../schemas.js';
+/**
+ * Traverses Last.fm similarity graphs from user's top artists to recommend unlistened artists.
+ */
+export declare function getSmartRecommendations(config: LastFmConfig, params: InsightsRecommendationsRequest, init?: RequestInit): Promise<InsightsRecommendationsResponse>;
+/**
+ * Finds artists that bridge two distinct genres or tags.
+ */
+export declare function getBridgeArtists(config: LastFmConfig, params: InsightsBridgeArtistsRequest, init?: RequestInit): Promise<InsightsBridgeArtistsResponse>;
+//# sourceMappingURL=recommendations.d.ts.map

package/dist/insights/algorithms/recommendations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendations.d.ts","sourceRoot":"","sources":["../../../src/insights/algorithms/recommendations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAKnD,OAAO,KAAK,EAGX,4BAA4B,EAC5B,6BAA6B,EAC7B,8BAA8B,EAC9B,+BAA+B,EAC/B,MAAM,eAAe,CAAA;AAEtB;;GAEG;AACH,wBAAsB,uBAAuB,CAC5C,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,8BAA8B,EACtC,IAAI,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,+BAA+B,CAAC,CA8E1C;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,4BAA4B,EACpC,IAAI,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,6BAA6B,CAAC,CAsDxC"}

package/dist/insights/algorithms/recommendations.js

@@ -0,0 +1,121 @@
+import { createArtistService } from '../../core/services/artist.js';
+import { createTagService } from '../../core/services/tag.js';
+import { createUserService } from '../../core/services/user.js';
+import { resolvePeriod } from '../lib/periods.js';
+/**
+ * Traverses Last.fm similarity graphs from user's top artists to recommend unlistened artists.
+ */
+export async function getSmartRecommendations(config, params, init) {
+    const seedLimit = Math.min(20, typeof params.seedLimit === 'string' ? Number.parseInt(params.seedLimit, 10) : (params.seedLimit ?? 10));
+    const limit = Math.min(50, typeof params.limit === 'string' ? Number.parseInt(params.limit, 10) : (params.limit ?? 15));
+    const period = params.period ?? 'overall';
+    const resolved = resolvePeriod(period);
+    const userService = createUserService(config);
+    const artistService = createArtistService(config);
+    // Fetch top 50 user artists to identify seeds and known roster
+    const topRes = await userService.getTopArtists({ user: params.user, period: resolved.lastfm, limit: 50 }, init);
+    const rawArtists = topRes.topartists?.artist ?? [];
+    const artistList = Array.isArray(rawArtists) ? rawArtists : [rawArtists];
+    const knownArtists = new Set(artistList.map((a) => a.name.toLowerCase().trim()));
+    const seedArtists = artistList.slice(0, seedLimit);
+    const candidateMap = new Map();
+    const promises = seedArtists.map(async (seed, idx) => {
+        const seedName = seed.name;
+        const seedWeight = Math.max(1, seedLimit - idx);
+        try {
+            const simRes = await artistService.getSimilar({ artist: seedName, limit: 20 }, init);
+            const rawSim = simRes.similarartists?.artist ?? [];
+            const simList = Array.isArray(rawSim) ? rawSim : [rawSim];
+            for (const sim of simList) {
+                const candidateName = sim.name;
+                if (!candidateName)
+                    continue;
+                const lower = candidateName.toLowerCase().trim();
+                if (knownArtists.has(lower))
+                    continue;
+                const matchVal = Number.parseFloat(sim.match ?? '0.5') || 0.5;
+                const contribution = matchVal * seedWeight;
+                const existing = candidateMap.get(lower);
+                if (existing) {
+                    existing.score += contribution;
+                    existing.matchedSeeds.add(seedName);
+                }
+                else {
+                    candidateMap.set(lower, {
+                        name: candidateName,
+                        score: contribution,
+                        matchedSeeds: new Set([seedName]),
+                        url: sim.url,
+                    });
+                }
+            }
+        }
+        catch {
+            // ignore failure for individual seed
+        }
+    });
+    await Promise.allSettled(promises);
+    const scoredCandidates = Array.from(candidateMap.values())
+        .map((c) => ({
+        name: c.name,
+        score: Math.round(c.score * 100) / 100,
+        matchedSeeds: Array.from(c.matchedSeeds),
+        url: c.url,
+    }))
+        .sort((a, b) => b.score - a.score || b.matchedSeeds.length - a.matchedSeeds.length)
+        .slice(0, limit);
+    return {
+        user: params.user,
+        seedArtists: seedArtists.map((s) => s.name),
+        totalRecommendations: scoredCandidates.length,
+        recommendations: scoredCandidates,
+    };
+}
+/**
+ * Finds artists that bridge two distinct genres or tags.
+ */
+export async function getBridgeArtists(config, params, init) {
+    const limit = Math.min(50, typeof params.limit === 'string' ? Number.parseInt(params.limit, 10) : (params.limit ?? 10));
+    const tagService = createTagService(config);
+    const [tagARes, tagBRes] = await Promise.all([
+        tagService.getTopArtists({ tag: params.tagA, limit: 50 }, init),
+        tagService.getTopArtists({ tag: params.tagB, limit: 50 }, init),
+    ]);
+    const rawA = tagARes.topartists?.artist ?? [];
+    const listA = Array.isArray(rawA) ? rawA : [rawA];
+    const rawB = tagBRes.topartists?.artist ?? [];
+    const listB = Array.isArray(rawB) ? rawB : [rawB];
+    const mapA = new Map();
+    listA.forEach((a, idx) => {
+        if (a.name) {
+            mapA.set(a.name.toLowerCase().trim(), { rank: idx + 1, name: a.name, url: a.url });
+        }
+    });
+    const bridges = [];
+    listB.forEach((b, idx) => {
+        if (!b.name)
+            return;
+        const lower = b.name.toLowerCase().trim();
+        const hit = mapA.get(lower);
+        if (hit) {
+            const rankA = hit.rank;
+            const rankB = idx + 1;
+            const combinedScore = Math.round(((1 / rankA + 1 / rankB) / 2) * 10000) / 100;
+            bridges.push({
+                name: hit.name,
+                rankA,
+                rankB,
+                combinedScore,
+                url: hit.url ?? b.url,
+            });
+        }
+    });
+    bridges.sort((a, b) => b.combinedScore - a.combinedScore);
+    return {
+        tagA: params.tagA,
+        tagB: params.tagB,
+        totalBridges: bridges.length,
+        bridgeArtists: bridges.slice(0, limit),
+    };
+}
+//# sourceMappingURL=recommendations.js.map

package/dist/insights/algorithms/recommendations.js.map

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

package/dist/insights/algorithms/streaks.d.ts

@@ -0,0 +1,11 @@
+import type { LastFmConfig } from '../../config.js';
+import type { InsightsHeatmapRequest, InsightsHeatmapResponse, InsightsStreaksRequest, InsightsStreaksResponse } from '../schemas.js';
+/**
+ * Calculates listening streaks (current active streak, longest streak, longest dry spell).
+ */
+export declare function getListeningStreaks(config: LastFmConfig, params: InsightsStreaksRequest, init?: RequestInit): Promise<InsightsStreaksResponse>;
+/**
+ * Returns a daily listening heatmap with normalized intensity levels (0..4).
+ */
+export declare function getListeningHeatmap(config: LastFmConfig, params: InsightsHeatmapRequest, init?: RequestInit): Promise<InsightsHeatmapResponse>;
+//# sourceMappingURL=streaks.d.ts.map

package/dist/insights/algorithms/streaks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaks.d.ts","sourceRoot":"","sources":["../../../src/insights/algorithms/streaks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD,OAAO,KAAK,EAEX,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,MAAM,eAAe,CAAA;AAatB;;GAEG;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,sBAAsB,EAC9B,IAAI,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,uBAAuB,CAAC,CA+GlC;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,sBAAsB,EAC9B,IAAI,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,uBAAuB,CAAC,CAsElC"}