@rmdes/indiekit-endpoint-lastfm 1.0.0

package/lib/controllers/stats.js

@@ -0,0 +1,89 @@
+import { LastFmClient } from "../lastfm-client.js";
+import { getAllStats, getScrobbleTrends } from "../stats.js";
+import { getCachedStats } from "../sync.js";
+
+/**
+ * Stats controller
+ */
+export const statsController = {
+  /**
+   * JSON API for all stats
+   * @type {import("express").RequestHandler}
+   */
+  async api(request, response, next) {
+    try {
+      const { lastfmConfig } = request.app.locals.application;
+
+      if (!lastfmConfig) {
+        return response.status(500).json({ error: "Not configured" });
+      }
+
+      // Try database first, fall back to cache for public routes
+      const db = request.app.locals.database;
+      let stats;
+
+      if (db) {
+        // Create client for API-based top artists/albums
+        const client = new LastFmClient({
+          apiKey: lastfmConfig.apiKey,
+          username: lastfmConfig.username,
+          cacheTtl: lastfmConfig.cacheTtl,
+        });
+
+        stats = await getAllStats(db, lastfmConfig.limits, client);
+      } else {
+        // Public routes don't have DB access, use cached stats
+        stats = getCachedStats();
+        if (!stats) {
+          return response.status(503).json({
+            error: "Stats not available yet",
+            message:
+              "Stats are computed during background sync. Please try again shortly.",
+          });
+        }
+      }
+
+      response.json(stats);
+    } catch (error) {
+      console.error("[Last.fm] Stats API error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+
+  /**
+   * JSON API for trends only (for charts)
+   * @type {import("express").RequestHandler}
+   */
+  async apiTrends(request, response, next) {
+    try {
+      const { lastfmConfig } = request.app.locals.application;
+
+      if (!lastfmConfig) {
+        return response.status(500).json({ error: "Not configured" });
+      }
+
+      const db = request.app.locals.database;
+      const days = Math.min(parseInt(request.query.days) || 30, 90);
+
+      if (db) {
+        const trends = await getScrobbleTrends(db, days);
+        return response.json({ trends, days });
+      }
+
+      // Fall back to cached stats for public routes
+      const cachedStats = getCachedStats();
+      if (cachedStats?.trends) {
+        return response.json({ trends: cachedStats.trends, days: 30 });
+      }
+
+      return response.status(503).json({
+        error: "Trends not available yet",
+        message:
+          "Trends are computed during background sync. Please try again shortly.",
+      });
+    } catch (error) {
+      console.error("[Last.fm] Trends API error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};

package/lib/lastfm-client.js

@@ -0,0 +1,258 @@
+import { IndiekitError } from "@indiekit/error";
+
+const API_BASE = "https://ws.audioscrobbler.com/2.0/";
+
+export class LastFmClient {
+  /**
+   * @param {object} options - Client options
+   * @param {string} options.apiKey - Last.fm API key
+   * @param {string} options.username - Last.fm username to fetch data for
+   * @param {number} [options.cacheTtl] - Cache TTL in milliseconds
+   */
+  constructor(options = {}) {
+    this.apiKey = options.apiKey;
+    this.username = options.username;
+    this.cacheTtl = options.cacheTtl || 900_000;
+    this.cache = new Map();
+  }
+
+  /**
+   * Fetch from Last.fm API with caching
+   * @param {string} method - API method name
+   * @param {object} [params] - Additional query parameters
+   * @returns {Promise<object>} - Response data
+   */
+  async fetch(method, params = {}) {
+    const url = new URL(API_BASE);
+    url.searchParams.set("method", method);
+    url.searchParams.set("api_key", this.apiKey);
+    url.searchParams.set("format", "json");
+    url.searchParams.set("user", this.username);
+
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== undefined && value !== null) {
+        url.searchParams.set(key, String(value));
+      }
+    });
+
+    const cacheKey = url.toString();
+
+    // Check cache first
+    const cached = this.cache.get(cacheKey);
+    if (cached && Date.now() - cached.timestamp < this.cacheTtl) {
+      return cached.data;
+    }
+
+    const response = await fetch(url.toString(), {
+      headers: {
+        Accept: "application/json",
+        "User-Agent": "indiekit-endpoint-lastfm/1.0.0",
+      },
+    });
+
+    if (!response.ok) {
+      throw await IndiekitError.fromFetch(response);
+    }
+
+    const data = await response.json();
+
+    // Check for Last.fm API errors
+    if (data.error) {
+      throw new Error(`Last.fm API error ${data.error}: ${data.message}`);
+    }
+
+    // Cache result
+    this.cache.set(cacheKey, { data, timestamp: Date.now() });
+
+    return data;
+  }
+
+  /**
+   * Get recent tracks (scrobbles)
+   * @param {number} [page] - Page number
+   * @param {number} [limit] - Items per page (max 200)
+   * @param {number} [from] - Start timestamp (UNIX)
+   * @param {number} [to] - End timestamp (UNIX)
+   * @returns {Promise<object>} - Recent tracks response
+   */
+  async getRecentTracks(page = 1, limit = 50, from = null, to = null) {
+    const params = {
+      page,
+      limit: Math.min(limit, 200),
+      extended: 1, // Include loved status and artist info
+    };
+
+    if (from) params.from = from;
+    if (to) params.to = to;
+
+    return this.fetch("user.getRecentTracks", params);
+  }
+
+  /**
+   * Get all recent tracks by paginating through all pages
+   * @param {number} [maxPages] - Maximum pages to fetch (safety limit)
+   * @returns {Promise<Array>} - All recent tracks
+   */
+  async getAllRecentTracks(maxPages = 50) {
+    const allTracks = [];
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore && page <= maxPages) {
+      const response = await this.getRecentTracks(page, 200);
+      const tracks = response.recenttracks?.track || [];
+
+      // Filter out "now playing" track (has @attr.nowplaying)
+      const scrobbledTracks = tracks.filter((t) => !t["@attr"]?.nowplaying);
+      allTracks.push(...scrobbledTracks);
+
+      const totalPages = parseInt(response.recenttracks?.["@attr"]?.totalPages) || 1;
+      hasMore = page < totalPages;
+      page++;
+    }
+
+    return allTracks;
+  }
+
+  /**
+   * Get new scrobbles since a given timestamp
+   * Used for incremental sync
+   * @param {Date} since - Only fetch scrobbles after this date
+   * @returns {Promise<Array>} - New scrobbles
+   */
+  async getNewScrobbles(since) {
+    const fromTimestamp = Math.floor(since.getTime() / 1000);
+    const newScrobbles = [];
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore) {
+      const response = await this.getRecentTracks(page, 200, fromTimestamp);
+      const tracks = response.recenttracks?.track || [];
+
+      // Filter out "now playing" track
+      const scrobbledTracks = tracks.filter((t) => !t["@attr"]?.nowplaying);
+      newScrobbles.push(...scrobbledTracks);
+
+      const totalPages = parseInt(response.recenttracks?.["@attr"]?.totalPages) || 1;
+      hasMore = page < totalPages;
+      page++;
+    }
+
+    return newScrobbles;
+  }
+
+  /**
+   * Get loved tracks
+   * @param {number} [page] - Page number
+   * @param {number} [limit] - Items per page
+   * @returns {Promise<object>} - Loved tracks response
+   */
+  async getLovedTracks(page = 1, limit = 50) {
+    return this.fetch("user.getLovedTracks", {
+      page,
+      limit: Math.min(limit, 200),
+    });
+  }
+
+  /**
+   * Get all loved tracks
+   * @param {number} [maxPages] - Maximum pages to fetch
+   * @returns {Promise<Array>} - All loved tracks
+   */
+  async getAllLovedTracks(maxPages = 20) {
+    const allTracks = [];
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore && page <= maxPages) {
+      const response = await this.getLovedTracks(page, 200);
+      const tracks = response.lovedtracks?.track || [];
+      allTracks.push(...tracks);
+
+      const totalPages = parseInt(response.lovedtracks?.["@attr"]?.totalPages) || 1;
+      hasMore = page < totalPages;
+      page++;
+    }
+
+    return allTracks;
+  }
+
+  /**
+   * Get top artists for a time period
+   * @param {string} [period] - Time period: overall, 7day, 1month, 3month, 6month, 12month
+   * @param {number} [limit] - Number of artists to return
+   * @returns {Promise<object>} - Top artists response
+   */
+  async getTopArtists(period = "overall", limit = 10) {
+    return this.fetch("user.getTopArtists", {
+      period,
+      limit,
+    });
+  }
+
+  /**
+   * Get top albums for a time period
+   * @param {string} [period] - Time period: overall, 7day, 1month, 3month, 6month, 12month
+   * @param {number} [limit] - Number of albums to return
+   * @returns {Promise<object>} - Top albums response
+   */
+  async getTopAlbums(period = "overall", limit = 10) {
+    return this.fetch("user.getTopAlbums", {
+      period,
+      limit,
+    });
+  }
+
+  /**
+   * Get top tracks for a time period
+   * @param {string} [period] - Time period: overall, 7day, 1month, 3month, 6month, 12month
+   * @param {number} [limit] - Number of tracks to return
+   * @returns {Promise<object>} - Top tracks response
+   */
+  async getTopTracks(period = "overall", limit = 10) {
+    return this.fetch("user.getTopTracks", {
+      period,
+      limit,
+    });
+  }
+
+  /**
+   * Get user info
+   * @returns {Promise<object>} - User info response
+   */
+  async getUserInfo() {
+    return this.fetch("user.getInfo");
+  }
+
+  /**
+   * Get the most recent scrobble (or now playing)
+   * @returns {Promise<object|null>} - Most recent track or null
+   */
+  async getLatestScrobble() {
+    const response = await this.getRecentTracks(1, 1);
+    return response.recenttracks?.track?.[0] || null;
+  }
+
+  /**
+   * Check if currently playing
+   * @returns {Promise<object|null>} - Now playing track or null
+   */
+  async getNowPlaying() {
+    const response = await this.getRecentTracks(1, 1);
+    const track = response.recenttracks?.track?.[0];
+
+    if (track && track["@attr"]?.nowplaying === "true") {
+      return track;
+    }
+
+    return null;
+  }
+
+  /**
+   * Clear the cache
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+}

package/lib/stats.js

@@ -0,0 +1,308 @@
+import { formatTopArtist, formatTopAlbum, mapPeriodToLastfm } from "./utils.js";
+
+/**
+ * Get date match filter for a time period
+ * @param {string} period - 'all', 'week', or 'month'
+ * @returns {object} - MongoDB match filter
+ */
+function getDateMatch(period) {
+  const now = new Date();
+  switch (period) {
+    case "week":
+      return { scrobbledAt: { $gte: new Date(now - 7 * 24 * 60 * 60 * 1000) } };
+    case "month":
+      return { scrobbledAt: { $gte: new Date(now - 30 * 24 * 60 * 60 * 1000) } };
+    default:
+      return {};
+  }
+}
+
+/**
+ * Get top artists from MongoDB (fallback if API unavailable)
+ * @param {object} db - MongoDB database
+ * @param {string} period - 'all', 'week', or 'month'
+ * @param {number} limit - Number of artists to return
+ * @returns {Promise<Array>} - Top artists
+ */
+export async function getTopArtistsFromDb(db, period = "all", limit = 10) {
+  const match = getDateMatch(period);
+  const collection = db.collection("scrobbles");
+
+  return collection
+    .aggregate([
+      { $match: match },
+      {
+        $group: {
+          _id: "$artistName",
+          name: { $first: "$artistName" },
+          playCount: { $sum: 1 },
+          mbid: { $first: "$artistMbid" },
+        },
+      },
+      { $match: { _id: { $ne: null } } },
+      { $sort: { playCount: -1 } },
+      { $limit: limit },
+      {
+        $project: {
+          _id: 0,
+          name: 1,
+          playCount: 1,
+          mbid: 1,
+        },
+      },
+    ])
+    .toArray();
+}
+
+/**
+ * Get top albums from MongoDB (fallback if API unavailable)
+ * @param {object} db - MongoDB database
+ * @param {string} period - 'all', 'week', or 'month'
+ * @param {number} limit - Number of albums to return
+ * @returns {Promise<Array>} - Top albums
+ */
+export async function getTopAlbumsFromDb(db, period = "all", limit = 10) {
+  const match = getDateMatch(period);
+  const collection = db.collection("scrobbles");
+
+  return collection
+    .aggregate([
+      { $match: { ...match, albumTitle: { $ne: null } } },
+      {
+        $group: {
+          _id: { album: "$albumTitle", artist: "$artistName" },
+          title: { $first: "$albumTitle" },
+          artist: { $first: "$artistName" },
+          coverUrl: { $first: "$coverUrl" },
+          playCount: { $sum: 1 },
+          mbid: { $first: "$albumMbid" },
+        },
+      },
+      { $sort: { playCount: -1 } },
+      { $limit: limit },
+      {
+        $project: {
+          _id: 0,
+          title: 1,
+          artist: 1,
+          coverUrl: 1,
+          playCount: 1,
+          mbid: 1,
+        },
+      },
+    ])
+    .toArray();
+}
+
+/**
+ * Get top artists from Last.fm API
+ * @param {object} client - LastFmClient instance
+ * @param {string} period - 'all', 'week', or 'month'
+ * @param {number} limit - Number of artists to return
+ * @returns {Promise<Array>} - Top artists
+ */
+export async function getTopArtistsFromApi(client, period = "all", limit = 10) {
+  const lastfmPeriod = mapPeriodToLastfm(period);
+  const response = await client.getTopArtists(lastfmPeriod, limit);
+  const artists = response.topartists?.artist || [];
+
+  return artists.map((artist, index) => formatTopArtist(artist, index + 1));
+}
+
+/**
+ * Get top albums from Last.fm API
+ * @param {object} client - LastFmClient instance
+ * @param {string} period - 'all', 'week', or 'month'
+ * @param {number} limit - Number of albums to return
+ * @returns {Promise<Array>} - Top albums
+ */
+export async function getTopAlbumsFromApi(client, period = "all", limit = 10) {
+  const lastfmPeriod = mapPeriodToLastfm(period);
+  const response = await client.getTopAlbums(lastfmPeriod, limit);
+  const albums = response.topalbums?.album || [];
+
+  return albums.map((album, index) => formatTopAlbum(album, index + 1));
+}
+
+/**
+ * Get scrobble trends (daily counts)
+ * @param {object} db - MongoDB database
+ * @param {number} days - Number of days to look back
+ * @returns {Promise<Array>} - Daily scrobble counts
+ */
+export async function getScrobbleTrends(db, days = 30) {
+  const startDate = new Date();
+  startDate.setDate(startDate.getDate() - days);
+  startDate.setHours(0, 0, 0, 0);
+
+  const collection = db.collection("scrobbles");
+
+  return collection
+    .aggregate([
+      { $match: { scrobbledAt: { $gte: startDate } } },
+      {
+        $group: {
+          _id: {
+            $dateToString: { format: "%Y-%m-%d", date: "$scrobbledAt" },
+          },
+          count: { $sum: 1 },
+        },
+      },
+      { $sort: { _id: 1 } },
+      {
+        $project: {
+          _id: 0,
+          date: "$_id",
+          count: 1,
+        },
+      },
+    ])
+    .toArray();
+}
+
+/**
+ * Get summary statistics for a time period
+ * @param {object} db - MongoDB database
+ * @param {string} period - 'all', 'week', or 'month'
+ * @returns {Promise<object>} - Summary stats
+ */
+export async function getSummary(db, period = "all") {
+  const match = getDateMatch(period);
+  const collection = db.collection("scrobbles");
+
+  const result = await collection
+    .aggregate([
+      { $match: match },
+      {
+        $group: {
+          _id: null,
+          totalPlays: { $sum: 1 },
+          uniqueTracks: { $addToSet: { $concat: ["$artistName", ":", "$trackTitle"] } },
+          uniqueArtists: { $addToSet: "$artistName" },
+          uniqueAlbums: { $addToSet: "$albumTitle" },
+          lovedCount: {
+            $sum: { $cond: [{ $eq: ["$loved", true] }, 1, 0] },
+          },
+        },
+      },
+      {
+        $project: {
+          _id: 0,
+          totalPlays: 1,
+          lovedCount: 1,
+          uniqueTracks: { $size: "$uniqueTracks" },
+          uniqueArtists: {
+            $size: {
+              $filter: {
+                input: "$uniqueArtists",
+                cond: { $ne: ["$$this", null] },
+              },
+            },
+          },
+          uniqueAlbums: {
+            $size: {
+              $filter: {
+                input: "$uniqueAlbums",
+                cond: { $ne: ["$$this", null] },
+              },
+            },
+          },
+        },
+      },
+    ])
+    .toArray();
+
+  return (
+    result[0] || {
+      totalPlays: 0,
+      lovedCount: 0,
+      uniqueTracks: 0,
+      uniqueArtists: 0,
+      uniqueAlbums: 0,
+    }
+  );
+}
+
+/**
+ * Get all stats for all time periods
+ * Uses Last.fm API for top artists/albums (more accurate) with DB fallback
+ * @param {object} db - MongoDB database
+ * @param {object} limits - Limits for top lists
+ * @param {object} [client] - LastFmClient instance (optional, for API-based stats)
+ * @returns {Promise<object>} - All stats
+ */
+export async function getAllStats(db, limits = {}, client = null) {
+  const topArtistsLimit = limits.topArtists || 10;
+  const topAlbumsLimit = limits.topAlbums || 10;
+
+  // Get summaries from database
+  const [summaryAll, summaryMonth, summaryWeek, trends] = await Promise.all([
+    getSummary(db, "all"),
+    getSummary(db, "month"),
+    getSummary(db, "week"),
+    getScrobbleTrends(db, 30),
+  ]);
+
+  // Get top artists/albums - prefer API (more accurate), fall back to DB
+  let topArtists = { all: [], month: [], week: [] };
+  let topAlbums = { all: [], month: [], week: [] };
+
+  if (client) {
+    try {
+      const [
+        topArtistsAll,
+        topArtistsMonth,
+        topArtistsWeek,
+        topAlbumsAll,
+        topAlbumsMonth,
+        topAlbumsWeek,
+      ] = await Promise.all([
+        getTopArtistsFromApi(client, "all", topArtistsLimit),
+        getTopArtistsFromApi(client, "month", topArtistsLimit),
+        getTopArtistsFromApi(client, "week", topArtistsLimit),
+        getTopAlbumsFromApi(client, "all", topAlbumsLimit),
+        getTopAlbumsFromApi(client, "month", topAlbumsLimit),
+        getTopAlbumsFromApi(client, "week", topAlbumsLimit),
+      ]);
+
+      topArtists = { all: topArtistsAll, month: topArtistsMonth, week: topArtistsWeek };
+      topAlbums = { all: topAlbumsAll, month: topAlbumsMonth, week: topAlbumsWeek };
+    } catch (err) {
+      console.warn("[Last.fm] API stats failed, using DB fallback:", err.message);
+      // Fall through to DB-based stats
+    }
+  }
+
+  // Fall back to DB if API failed or client not provided
+  if (topArtists.all.length === 0) {
+    const [
+      topArtistsAll,
+      topArtistsMonth,
+      topArtistsWeek,
+      topAlbumsAll,
+      topAlbumsMonth,
+      topAlbumsWeek,
+    ] = await Promise.all([
+      getTopArtistsFromDb(db, "all", topArtistsLimit),
+      getTopArtistsFromDb(db, "month", topArtistsLimit),
+      getTopArtistsFromDb(db, "week", topArtistsLimit),
+      getTopAlbumsFromDb(db, "all", topAlbumsLimit),
+      getTopAlbumsFromDb(db, "month", topAlbumsLimit),
+      getTopAlbumsFromDb(db, "week", topAlbumsLimit),
+    ]);
+
+    topArtists = { all: topArtistsAll, month: topArtistsMonth, week: topArtistsWeek };
+    topAlbums = { all: topAlbumsAll, month: topAlbumsMonth, week: topAlbumsWeek };
+  }
+
+  return {
+    summary: {
+      all: summaryAll,
+      month: summaryMonth,
+      week: summaryWeek,
+    },
+    topArtists,
+    topAlbums,
+    trends,
+  };
+}