@ansango/lastfm-api 3.2.0 → 3.4.0

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

@@ -0,0 +1,39 @@
+/**
+ * Computes the Shannon diversity index over a map of item counts.
+ */
+export function computeDiversity(counts) {
+    const entries = Object.entries(counts).filter(([, c]) => c > 0);
+    const total = entries.reduce((acc, [, c]) => acc + c, 0);
+    const uniqueCount = entries.length;
+    if (total === 0 || uniqueCount === 0) {
+        return { total: 0, uniqueCount: 0, shannon: 0, normalized: 0 };
+    }
+    if (uniqueCount === 1) {
+        return { total, uniqueCount: 1, shannon: 0, normalized: 0 };
+    }
+    let h = 0;
+    for (const [, c] of entries) {
+        const p = c / total;
+        h -= p * Math.log(p);
+    }
+    const normalized = h / Math.log(uniqueCount);
+    return { total, uniqueCount, shannon: h, normalized };
+}
+/**
+ * Fraction of total plays consumed by the top-N entries.
+ * - N larger than uniqueCount returns 1.
+ * - Empty map returns 0.
+ */
+export function topNShare(counts, n) {
+    const sorted = Object.values(counts)
+        .filter((c) => c > 0)
+        .sort((a, b) => b - a);
+    if (sorted.length === 0)
+        return 0;
+    const total = sorted.reduce((acc, c) => acc + c, 0);
+    if (total === 0)
+        return 0;
+    const top = sorted.slice(0, Math.max(0, n)).reduce((acc, c) => acc + c, 0);
+    return top / total;
+}
+//# sourceMappingURL=diversity.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diversity.js","sourceRoot":"","sources":["../../../../src/services/insights/lib/diversity.ts"],"names":[],"mappings":"AAmBA;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAgB;IAChD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IACxD,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAA;IAClC,IAAI,KAAK,KAAK,CAAC,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACtC,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;IAC/D,CAAC;IACD,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;IAC5D,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,CAAA;IACT,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;QACnB,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACrB,CAAC;IACD,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;IAC5C,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAA;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAgB,EAAE,CAAS;IACpD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;SAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SACpB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IACvB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IACjC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IACnD,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IACzB,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IAC1E,OAAO,GAAG,GAAG,KAAK,CAAA;AACnB,CAAC"}

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

@@ -0,0 +1,39 @@
+/**
+ * hours.ts — bucket timestamps by hour-of-day (0..23) and weekday (0..6).
+ *
+ * Weekday indexing follows ISO convention: Mon=0 .. Sun=6.
+ * All bucketing is in UTC for deterministic behavior.
+ */
+export declare const WEEKDAY_LABELS_EN: readonly ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+export declare const WEEKDAY_LABELS_ES: readonly ["lunes", "martes", "miércoles", "jueves", "viernes", "sábado", "domingo"];
+export interface HourBucket {
+    /** Hour of the day in 24h format, 0–23 (UTC). */
+    readonly hour: number;
+    /** Day of the week, 0 = Monday … 6 = Sunday. */
+    readonly weekday: number;
+}
+/**
+ * Convert a UNIX-seconds timestamp to (hour, weekday).
+ */
+export declare function bucketTimestamp(unixSeconds: number): HourBucket;
+export interface HourHistogram {
+    readonly total: number;
+    /** Counts per hour, index = hour (0..23). Length always 24. */
+    readonly byHour: number[];
+    /** Counts per weekday, index = Mon(0)..Sun(6). Length always 7. */
+    readonly byWeekday: number[];
+    /** Hour with the highest count, or null when total === 0. */
+    readonly peakHour: number | null;
+    readonly peakHourCount: number;
+    readonly peakWeekday: number | null;
+    readonly peakWeekdayCount: number;
+    readonly peakWeekdayLabel: string | null;
+    /** Time-of-day shares [0..1] */
+    readonly nightShare: number;
+    readonly morningShare: number;
+    readonly afternoonShare: number;
+    readonly eveningShare: number;
+    readonly weekendShare: number;
+}
+export declare function buildHourHistogram(timestamps: readonly number[]): HourHistogram;
+//# sourceMappingURL=hours.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hours.d.ts","sourceRoot":"","sources":["../../../../src/services/insights/lib/hours.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,4DAA6D,CAAA;AAC3F,eAAO,MAAM,iBAAiB,qFAAsF,CAAA;AAEpH,MAAM,WAAW,UAAU;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAO/D;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;IACzB,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAA;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IACxC,gCAAgC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC7B;AAgBD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CAmC/E"}

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

@@ -0,0 +1,66 @@
+/**
+ * hours.ts — bucket timestamps by hour-of-day (0..23) and weekday (0..6).
+ *
+ * Weekday indexing follows ISO convention: Mon=0 .. Sun=6.
+ * All bucketing is in UTC for deterministic behavior.
+ */
+export const WEEKDAY_LABELS_EN = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+export const WEEKDAY_LABELS_ES = ['lunes', 'martes', 'miércoles', 'jueves', 'viernes', 'sábado', 'domingo'];
+/**
+ * Convert a UNIX-seconds timestamp to (hour, weekday).
+ */
+export function bucketTimestamp(unixSeconds) {
+    const date = new Date(unixSeconds * 1000);
+    const hour = date.getUTCHours();
+    // Map JS getUTCDay() (Sun=0..Sat=6) to Mon=0..Sun=6.
+    const jsDow = date.getUTCDay();
+    const weekday = (jsDow + 6) % 7;
+    return { hour, weekday };
+}
+function indexOfMax(arr) {
+    if (arr.length === 0)
+        return null;
+    let maxIdx = 0;
+    let maxVal = arr[0] ?? 0;
+    for (let i = 1; i < arr.length; i++) {
+        const val = arr[i] ?? 0;
+        if (val > maxVal) {
+            maxVal = val;
+            maxIdx = i;
+        }
+    }
+    return maxVal > 0 ? maxIdx : null;
+}
+export function buildHourHistogram(timestamps) {
+    const byHour = new Array(24).fill(0);
+    const byWeekday = new Array(7).fill(0);
+    for (const ts of timestamps) {
+        const b = bucketTimestamp(ts);
+        byHour[b.hour] = (byHour[b.hour] ?? 0) + 1;
+        byWeekday[b.weekday] = (byWeekday[b.weekday] ?? 0) + 1;
+    }
+    const total = timestamps.length;
+    const peakHourIdx = indexOfMax(byHour);
+    const peakWeekdayIdx = indexOfMax(byWeekday);
+    const nightCount = byHour.slice(0, 6).reduce((a, b) => a + b, 0);
+    const morningCount = byHour.slice(6, 12).reduce((a, b) => a + b, 0);
+    const afternoonCount = byHour.slice(12, 18).reduce((a, b) => a + b, 0);
+    const eveningCount = byHour.slice(18, 24).reduce((a, b) => a + b, 0);
+    const weekendCount = (byWeekday[5] ?? 0) + (byWeekday[6] ?? 0);
+    return {
+        total,
+        byHour,
+        byWeekday,
+        peakHour: peakHourIdx,
+        peakHourCount: peakHourIdx !== null ? (byHour[peakHourIdx] ?? 0) : 0,
+        peakWeekday: peakWeekdayIdx,
+        peakWeekdayCount: peakWeekdayIdx !== null ? (byWeekday[peakWeekdayIdx] ?? 0) : 0,
+        peakWeekdayLabel: peakWeekdayIdx !== null ? (WEEKDAY_LABELS_EN[peakWeekdayIdx] ?? null) : null,
+        nightShare: total > 0 ? nightCount / total : 0,
+        morningShare: total > 0 ? morningCount / total : 0,
+        afternoonShare: total > 0 ? afternoonCount / total : 0,
+        eveningShare: total > 0 ? eveningCount / total : 0,
+        weekendShare: total > 0 ? weekendCount / total : 0,
+    };
+}
+//# sourceMappingURL=hours.js.map

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * mood.ts — derive a 2D mood profile from Last.fm tags.
+ *
+ * Axes:
+ *   energy   ∈ [-1, +1]   -1 = ambient/sleep, +1 = hardcore/thrash
+ *   valence  ∈ [-1, +1]   -1 = doom/sad,      +1 = euphoric/uplifting
+ */
+export interface MoodAxes {
+    readonly energy: number;
+    readonly valence: number;
+}
+export interface MoodProfile {
+    readonly axes: MoodAxes;
+    readonly label: string;
+    readonly categories: readonly string[];
+    readonly confidence: number;
+}
+export declare function axesFromTags(tags: readonly string[]): MoodAxes;
+export declare function categoriesFromTags(tags: readonly string[]): readonly string[];
+export declare function labelFromAxes({ energy, valence }: MoodAxes): string;
+export declare function classifyMood(tags: readonly string[]): MoodProfile;
+//# sourceMappingURL=mood.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mood.d.ts","sourceRoot":"","sources":["../../../../src/services/insights/lib/mood.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuHH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC3B;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,CAU9D;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAY7E;AAED,wBAAgB,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,QAAQ,GAAG,MAAM,CAiBnE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAoBjE"}

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

@@ -0,0 +1,187 @@
+/**
+ * mood.ts — derive a 2D mood profile from Last.fm tags.
+ *
+ * Axes:
+ *   energy   ∈ [-1, +1]   -1 = ambient/sleep, +1 = hardcore/thrash
+ *   valence  ∈ [-1, +1]   -1 = doom/sad,      +1 = euphoric/uplifting
+ */
+const ENERGY = {
+    // high energy
+    hardcore: 1,
+    punk: 0.8,
+    'punk rock': 0.8,
+    'hard rock': 0.7,
+    'thrash metal': 1,
+    'speed metal': 1,
+    grindcore: 1,
+    drum: 0.7,
+    'drum and bass': 0.8,
+    dnb: 0.8,
+    techno: 0.6,
+    gabber: 1,
+    'happy hardcore': 1,
+    rave: 0.9,
+    thrash: 0.9,
+    metal: 0.6,
+    'heavy metal': 0.7,
+    'death metal': 0.8,
+    'black metal': 0.6,
+    rock: 0.5,
+    'indie rock': 0.4,
+    pop: 0.3,
+    dance: 0.6,
+    hip: 0.5,
+    rap: 0.4,
+    hiphop: 0.5,
+    // low energy
+    ambient: -1,
+    drone: -0.9,
+    sleep: -1,
+    'new age': -0.8,
+    meditation: -0.9,
+    downtempo: -0.6,
+    chillout: -0.6,
+    chill: -0.6,
+    lounge: -0.5,
+    'trip-hop': -0.4,
+    'slow core': -0.5,
+    slowcore: -0.5,
+    ballad: -0.4,
+    jazz: -0.2,
+    'smooth jazz': -0.4,
+    'bossa nova': -0.3,
+};
+const VALENCE = {
+    // high valence (euphoric / happy)
+    euphoric: 1,
+    happy: 1,
+    uplifting: 0.9,
+    summer: 0.5,
+    sunshine: 0.6,
+    'feel good': 0.8,
+    feelgood: 0.8,
+    dance: 0.6,
+    party: 0.7,
+    pop: 0.4,
+    'power pop': 0.6,
+    'bubblegum pop': 0.5,
+    'k-pop': 0.4,
+    // low valence (sad / dark)
+    doom: -1,
+    sad: -1,
+    melancholic: -0.9,
+    melancholy: -0.9,
+    depressive: -1,
+    black: -0.7,
+    'black metal': -0.7,
+    'dark ambient': -0.8,
+    dark: -0.6,
+    funeral: -1,
+    'funeral doom': -1,
+    'doom metal': -0.9,
+    goth: -0.7,
+    gothic: -0.7,
+    'gothic rock': -0.6,
+    'post-punk': -0.4,
+    coldwave: -0.6,
+    // neutral-ish
+    indie: 0,
+    'indie rock': 0,
+    rock: 0,
+    electronic: 0,
+    experimental: 0,
+};
+const CATEGORIES = {
+    rock: ['rock', 'indie rock', 'post-rock', 'garage rock', 'hard rock'],
+    electronic: ['electronic', 'techno', 'house', 'ambient', 'idm', 'dnb', 'drum and bass', 'dubstep', 'synth'],
+    'hip-hop': ['hip-hop', 'hip hop', 'rap', 'trap'],
+    jazz: ['jazz', 'bebop', 'bossa nova', 'smooth jazz', 'nu jazz', 'free jazz'],
+    folk: ['folk', 'singer-songwriter', 'acoustic', 'indie folk', 'folk rock'],
+    classical: ['classical', 'baroque', 'romantic', 'modern classical', 'opera', 'symphony'],
+    ambient: ['ambient', 'drone', 'new age', 'meditation', 'dark ambient'],
+    experimental: ['experimental', 'noise', 'avant-garde', 'free improvisation'],
+    metal: ['metal', 'thrash metal', 'doom metal', 'death metal', 'black metal', 'heavy metal', 'sludge'],
+    pop: ['pop', 'synth-pop', 'electropop', 'k-pop', 'indie pop', 'dream pop'],
+    world: ['world', 'afrobeat', 'latin', 'flamenco', 'brazilian', 'reggae'],
+    punk: ['punk', 'post-punk', 'hardcore', 'anarcho-punk'],
+    country: ['country', 'bluegrass', 'outlaw country', 'country rock'],
+    soul: ['soul', 'r&b', 'funk', 'motown', 'neo-soul'],
+};
+function normalize(tag) {
+    return tag.toLowerCase().trim();
+}
+function lookup(map, tag) {
+    return map[tag] ?? 0;
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+export function axesFromTags(tags) {
+    if (tags.length === 0)
+        return { energy: 0, valence: 0 };
+    let energy = 0;
+    let valence = 0;
+    for (const t of tags) {
+        energy += lookup(ENERGY, normalize(t));
+        valence += lookup(VALENCE, normalize(t));
+    }
+    const avg = (n) => Math.max(-1, Math.min(1, n / tags.length));
+    return { energy: round2(avg(energy)), valence: round2(avg(valence)) };
+}
+export function categoriesFromTags(tags) {
+    if (tags.length === 0)
+        return [];
+    const counts = new Map();
+    for (const tag of tags) {
+        const norm = normalize(tag);
+        for (const [cat, members] of Object.entries(CATEGORIES)) {
+            if (members.includes(norm)) {
+                counts.set(cat, (counts.get(cat) ?? 0) + 1);
+            }
+        }
+    }
+    return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([cat]) => cat);
+}
+export function labelFromAxes({ energy, valence }) {
+    if (energy === 0 && valence === 0)
+        return 'neutral / undefined';
+    const eHigh = energy > 0.2;
+    const eLow = energy < -0.2;
+    const vHigh = valence > 0.2;
+    const vLow = valence < -0.2;
+    if (eHigh && vHigh)
+        return 'euphoric & energetic';
+    if (eHigh && vLow)
+        return 'intense & dark';
+    if (eLow && vHigh)
+        return 'chill & uplifting';
+    if (eLow && vLow)
+        return 'melancholic & calm';
+    if (eHigh && !vHigh && !vLow)
+        return 'high energy';
+    if (eLow && !vHigh && !vLow)
+        return 'low energy / ambient';
+    if (vHigh && !eHigh && !eLow)
+        return 'positive / bright';
+    if (vLow && !eHigh && !eLow)
+        return 'somber / melancholic';
+    return 'neutral / undefined';
+}
+export function classifyMood(tags) {
+    const axes = axesFromTags(tags);
+    const categories = categoriesFromTags(tags);
+    const recognized = tags.filter((t) => {
+        const norm = normalize(t);
+        return (ENERGY[norm] !== undefined ||
+            VALENCE[norm] !== undefined ||
+            Object.values(CATEGORIES).some((arr) => arr.includes(norm)));
+    }).length;
+    const confidence = tags.length === 0 ? 0 : round2(recognized / tags.length);
+    return {
+        axes,
+        label: labelFromAxes(axes),
+        categories,
+        confidence,
+    };
+}
+//# sourceMappingURL=mood.js.map

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

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

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

@@ -0,0 +1,17 @@
+import type { Period as CanonicalPeriod } from '../../schemas/index.js';
+/**
+ * Supported period inputs for insights (canonical tokens + human aliases)
+ */
+export type InsightsPeriodInput = CanonicalPeriod | 'daily' | 'weekly' | 'monthly' | 'yearly';
+export interface ResolvedPeriod {
+    readonly lastfm: CanonicalPeriod;
+    readonly from?: number;
+    readonly to: number;
+    readonly label: string;
+}
+export declare function periodToLastfm(p: string): CanonicalPeriod;
+/**
+ * Resolves an insight period into a canonical Last.fm period token and time range
+ */
+export declare function resolvePeriod(p?: string, clock?: () => number): ResolvedPeriod;
+//# sourceMappingURL=periods.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"periods.d.ts","sourceRoot":"","sources":["../../../../src/services/insights/lib/periods.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAEvE;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE7F,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACtB;AA6CD,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,CAEzD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAE,MAAe,EAAE,KAAK,GAAE,MAAM,MAAiB,GAAG,cAAc,CAqBhG"}

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

@@ -0,0 +1,66 @@
+const SECOND = 1;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const LASTFM_BY_PERIOD = {
+    daily: '7day',
+    weekly: '7day',
+    monthly: '1month',
+    yearly: '12month',
+    '7day': '7day',
+    '1month': '1month',
+    '3month': '3month',
+    '6month': '6month',
+    '12month': '12month',
+    overall: 'overall',
+};
+const LABEL_BY_PERIOD = {
+    daily: 'last 24 hours',
+    weekly: 'this week',
+    monthly: 'this month',
+    yearly: 'this year',
+    '7day': 'last 7 days',
+    '1month': 'last 30 days',
+    '3month': 'last 90 days',
+    '6month': 'last 180 days',
+    '12month': 'last 365 days',
+    overall: 'all time',
+};
+const WINDOW_SECONDS = {
+    daily: 1 * DAY,
+    weekly: 7 * DAY,
+    monthly: 30 * DAY,
+    yearly: 365 * DAY,
+    '7day': 7 * DAY,
+    '1month': 30 * DAY,
+    '3month': 90 * DAY,
+    '6month': 180 * DAY,
+    '12month': 365 * DAY,
+};
+export function periodToLastfm(p) {
+    return LASTFM_BY_PERIOD[p] ?? '7day';
+}
+/**
+ * Resolves an insight period into a canonical Last.fm period token and time range
+ */
+export function resolvePeriod(p = '7day', clock = Date.now) {
+    const lastfm = periodToLastfm(p);
+    const label = LABEL_BY_PERIOD[p] ?? LABEL_BY_PERIOD[lastfm] ?? p;
+    const to = Math.floor(clock() / 1000);
+    if (p === 'overall' || lastfm === 'overall') {
+        return {
+            lastfm: 'overall',
+            to,
+            label: 'all time',
+        };
+    }
+    const span = WINDOW_SECONDS[p] ?? WINDOW_SECONDS[lastfm] ?? 7 * DAY;
+    const from = to - span;
+    return {
+        lastfm,
+        from,
+        to,
+        label,
+    };
+}
+//# sourceMappingURL=periods.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"periods.js","sourceRoot":"","sources":["../../../../src/services/insights/lib/periods.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,GAAG,CAAC,CAAA;AAChB,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,CAAA;AAC1B,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,CAAA;AACxB,MAAM,GAAG,GAAG,EAAE,GAAG,IAAI,CAAA;AAErB,MAAM,gBAAgB,GAAoC;IACzD,KAAK,EAAE,MAAM;IACb,MAAM,EAAE,MAAM;IACd,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,SAAS;IACjB,MAAM,EAAE,MAAM;IACd,QAAQ,EAAE,QAAQ;IAClB,QAAQ,EAAE,QAAQ;IAClB,QAAQ,EAAE,QAAQ;IAClB,SAAS,EAAE,SAAS;IACpB,OAAO,EAAE,SAAS;CAClB,CAAA;AAED,MAAM,eAAe,GAA2B;IAC/C,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,aAAa;IACrB,QAAQ,EAAE,cAAc;IACxB,QAAQ,EAAE,cAAc;IACxB,QAAQ,EAAE,eAAe;IACzB,SAAS,EAAE,eAAe;IAC1B,OAAO,EAAE,UAAU;CACnB,CAAA;AAED,MAAM,cAAc,GAA2B;IAC9C,KAAK,EAAE,CAAC,GAAG,GAAG;IACd,MAAM,EAAE,CAAC,GAAG,GAAG;IACf,OAAO,EAAE,EAAE,GAAG,GAAG;IACjB,MAAM,EAAE,GAAG,GAAG,GAAG;IACjB,MAAM,EAAE,CAAC,GAAG,GAAG;IACf,QAAQ,EAAE,EAAE,GAAG,GAAG;IAClB,QAAQ,EAAE,EAAE,GAAG,GAAG;IAClB,QAAQ,EAAE,GAAG,GAAG,GAAG;IACnB,SAAS,EAAE,GAAG,GAAG,GAAG;CACpB,CAAA;AAED,MAAM,UAAU,cAAc,CAAC,CAAS;IACvC,OAAO,gBAAgB,CAAC,CAAC,CAAC,IAAI,MAAM,CAAA;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,MAAM,EAAE,QAAsB,IAAI,CAAC,GAAG;IAC/E,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAA;IAChC,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAChE,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAA;IAErC,IAAI,CAAC,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC7C,OAAO;YACN,MAAM,EAAE,SAAS;YACjB,EAAE;YACF,KAAK,EAAE,UAAU;SACjB,CAAA;IACF,CAAC;IAED,MAAM,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAA;IACnE,MAAM,IAAI,GAAG,EAAE,GAAG,IAAI,CAAA;IACtB,OAAO;QACN,MAAM;QACN,IAAI;QACJ,EAAE;QACF,KAAK;KACL,CAAA;AACF,CAAC"}

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

@@ -0,0 +1,30 @@
+/**
+ * personality.ts — classify the user into a listening personality archetype.
+ */
+export type ArchetypeId = 'Devotee' | 'Explorer' | 'Drifter' | 'DJ' | 'Nocturnal' | 'Archivist';
+export declare const ARCHETYPE_ORDER: readonly ArchetypeId[];
+export interface PersonalityFeatures {
+    readonly totalScrobbles: number;
+    readonly uniqueArtists: number;
+    readonly top1Share: number;
+    readonly top3Share: number;
+    readonly top5Share: number;
+    readonly normalizedDiversity: number;
+    readonly newArtistsLast30d: number;
+    readonly totalArtistsLast30d: number;
+    readonly nightHourShare: number;
+    readonly morningHourShare: number;
+    readonly weekdayShare: number;
+}
+export interface PersonalityResult {
+    readonly scores: Record<ArchetypeId, number>;
+    readonly winner: ArchetypeId;
+    readonly reasons: readonly string[];
+}
+export declare const ARCHETYPE_INFO: Record<ArchetypeId, {
+    name: string;
+    emoji: string;
+    blurb: string;
+}>;
+export declare function scoreArchetypes(features: PersonalityFeatures): PersonalityResult;
+//# sourceMappingURL=personality.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"personality.d.ts","sourceRoot":"","sources":["../../../../src/services/insights/lib/personality.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,IAAI,GAAG,WAAW,GAAG,WAAW,CAAA;AAE/F,eAAO,MAAM,eAAe,EAAE,SAAS,WAAW,EAOjD,CAAA;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;IAC5C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAMD,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA+B9F,CAAA;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,mBAAmB,GAAG,iBAAiB,CA2FhF"}

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

@@ -0,0 +1,131 @@
+/**
+ * personality.ts — classify the user into a listening personality archetype.
+ */
+export const ARCHETYPE_ORDER = [
+    'Devotee',
+    'Explorer',
+    'Drifter',
+    'DJ',
+    'Nocturnal',
+    'Archivist',
+];
+function clamp01(n) {
+    return Math.max(0, Math.min(1, n));
+}
+export const ARCHETYPE_INFO = {
+    Devotee: {
+        name: 'The Devotee',
+        emoji: '🛐',
+        blurb: 'Extreme loyalty to your favorite artists. High concentration, low dispersion.',
+    },
+    Explorer: {
+        name: 'The Explorer',
+        emoji: '🧭',
+        blurb: 'Always discovering new music. Your musical radar is constantly searching.',
+    },
+    Drifter: {
+        name: 'The Drifter',
+        emoji: '🍂',
+        blurb: 'Balanced listening across varied genres without strong fixations.',
+    },
+    DJ: {
+        name: 'The DJ',
+        emoji: '🎧',
+        blurb: 'High listening velocity across a broad and rotating selection of artists.',
+    },
+    Nocturnal: {
+        name: 'The Nocturnal',
+        emoji: '🌙',
+        blurb: 'Your music comes alive at night. The late hours are your peak listening zone.',
+    },
+    Archivist: {
+        name: 'The Archivist',
+        emoji: '📚',
+        blurb: 'A massive, eclectic, and deep personal music library with balanced play counts.',
+    },
+};
+export function scoreArchetypes(features) {
+    const scores = {
+        Devotee: 0,
+        Explorer: 0,
+        Drifter: 0,
+        DJ: 0,
+        Nocturnal: 0,
+        Archivist: 0,
+    };
+    const reasons = {
+        Devotee: [],
+        Explorer: [],
+        Drifter: [],
+        DJ: [],
+        Nocturnal: [],
+        Archivist: [],
+    };
+    // Devotee: high top1Share + low diversity + small unique roster
+    {
+        const focus = clamp01((features.top1Share - 0.15) / 0.5);
+        const monotony = clamp01((0.6 - features.normalizedDiversity) / 0.6);
+        const smallness = clamp01((20 - features.uniqueArtists) / 20);
+        scores.Devotee = Math.round((0.5 * focus + 0.3 * monotony + 0.2 * smallness) * 100) / 100;
+        if (focus > 0.5)
+            reasons.Devotee.push(`Top artist accounts for ${(features.top1Share * 100).toFixed(0)}% of scrobbles.`);
+        if (monotony > 0.5)
+            reasons.Devotee.push(`Low diversity score (${features.normalizedDiversity.toFixed(2)}).`);
+    }
+    // Explorer: high diversity + many new artists relative to total roster
+    {
+        const diversity = features.normalizedDiversity;
+        const newRatio = features.totalArtistsLast30d > 0 ? clamp01(features.newArtistsLast30d / features.totalArtistsLast30d) : 0;
+        scores.Explorer = Math.round((0.5 * diversity + 0.5 * newRatio) * 100) / 100;
+        if (diversity > 0.7)
+            reasons.Explorer.push(`High diversity score (${diversity.toFixed(2)}).`);
+        if (newRatio > 0.2)
+            reasons.Explorer.push(`${features.newArtistsLast30d} new artists discovered this month out of ${features.totalArtistsLast30d} played.`);
+    }
+    // Drifter: middle of the road on diversity and low novelty
+    {
+        const midDiversity = 1 - Math.abs(features.normalizedDiversity - 0.65) / 0.35;
+        const lowNovelty = clamp01((0.15 - (features.totalArtistsLast30d > 0 ? features.newArtistsLast30d / features.totalArtistsLast30d : 0)) /
+            0.15);
+        const lowFocus = clamp01((0.4 - features.top3Share) / 0.4);
+        scores.Drifter = Math.round((0.4 * midDiversity + 0.3 * lowNovelty + 0.3 * lowFocus) * 100) / 100;
+        if (midDiversity > 0.7)
+            reasons.Drifter.push(`Moderate diversity (${features.normalizedDiversity.toFixed(2)}).`);
+    }
+    // DJ: high velocity + many artists
+    {
+        const velocity = clamp01((features.totalScrobbles - 200) / 1800);
+        const breadth = clamp01((features.uniqueArtists - 20) / 80);
+        scores.DJ = Math.round((0.5 * velocity + 0.3 * breadth + 0.2 * features.normalizedDiversity) * 100) / 100;
+        if (velocity > 0.5)
+            reasons.DJ.push(`${features.totalScrobbles} total scrobbles in the window.`);
+    }
+    // Nocturnal: nightHourShare dominant
+    {
+        const nightness = clamp01((features.nightHourShare - 0.4) / 0.2);
+        const antiDaytime = clamp01((0.3 - features.morningHourShare) / 0.3);
+        scores.Nocturnal = Math.round((0.7 * nightness + 0.3 * antiDaytime) * 100) / 100;
+        if (nightness > 0.5)
+            reasons.Nocturnal.push(`${(features.nightHourShare * 100).toFixed(0)}% of scrobbles occurred during night hours.`);
+    }
+    // Archivist: massive library, spread across many artists
+    {
+        const massive = clamp01((features.totalScrobbles - 1500) / 3500);
+        const hugeRoster = clamp01((features.uniqueArtists - 100) / 200);
+        const spread = clamp01((1 - features.top5Share) / 0.5);
+        scores.Archivist = Math.round((0.4 * massive + 0.4 * hugeRoster + 0.2 * spread) * 100) / 100;
+        if (hugeRoster > 0.5)
+            reasons.Archivist.push(`${features.uniqueArtists} unique artists in window.`);
+    }
+    let winner = 'Devotee';
+    let best = -Number.POSITIVE_INFINITY;
+    for (const id of ARCHETYPE_ORDER) {
+        const s = scores[id];
+        if (s > best) {
+            best = s;
+            winner = id;
+        }
+    }
+    return { scores, winner, reasons: reasons[winner] ?? [] };
+}
+//# sourceMappingURL=personality.js.map