@rmdes/indiekit-endpoint-lastfm 1.0.0

package/lib/sync.js

@@ -0,0 +1,226 @@
+import { LastFmClient } from "./lastfm-client.js";
+import { getCoverUrl, getArtistName, getAlbumName, parseDate, getMbid, getTrackUrl } from "./utils.js";
+import { getAllStats } from "./stats.js";
+
+let syncInterval = null;
+
+// In-memory cache for stats (accessible to public routes)
+let cachedStats = null;
+let cachedStatsTime = null;
+const STATS_CACHE_TTL = 300_000; // 5 minutes
+
+/**
+ * Get cached stats (for public API routes that can't access DB)
+ * @returns {object|null} - Cached stats or null
+ */
+export function getCachedStats() {
+  if (!cachedStats) return null;
+  if (cachedStatsTime && Date.now() - cachedStatsTime > STATS_CACHE_TTL) {
+    return cachedStats; // Return stale cache, sync will refresh
+  }
+  return cachedStats;
+}
+
+/**
+ * Update stats cache
+ * @param {object} stats - Stats to cache
+ */
+export function setCachedStats(stats) {
+  cachedStats = stats;
+  cachedStatsTime = Date.now();
+}
+
+/**
+ * Refresh stats cache from database (for when cache is empty)
+ * @param {object} db - MongoDB database instance
+ * @param {object} limits - Limits for top lists
+ * @param {object} client - LastFmClient instance for API-based stats
+ * @returns {Promise<object|null>} - Stats or null if failed
+ */
+export async function refreshStatsCache(db, limits = {}, client = null) {
+  if (!db) return null;
+  try {
+    const stats = await getAllStats(db, limits, client);
+    setCachedStats(stats);
+    console.log("[Last.fm] Stats cache refreshed on-demand");
+    return stats;
+  } catch (err) {
+    console.error("[Last.fm] Failed to refresh stats cache:", err.message);
+    return null;
+  }
+}
+
+/**
+ * Start background sync process
+ * @param {object} Indiekit - Indiekit instance
+ * @param {object} options - Plugin options
+ */
+export function startSync(Indiekit, options) {
+  const intervalMs = options.syncInterval || 300_000; // 5 minutes default
+
+  // Initial sync after a short delay
+  setTimeout(() => {
+    runSync(Indiekit, options).catch((err) => {
+      console.error("[Last.fm] Initial sync error:", err.message);
+    });
+  }, 5000);
+
+  // Schedule recurring sync
+  syncInterval = setInterval(() => {
+    runSync(Indiekit, options).catch((err) => {
+      console.error("[Last.fm] Sync error:", err.message);
+    });
+  }, intervalMs);
+
+  console.log(
+    `[Last.fm] Background sync started (interval: ${intervalMs / 1000}s)`
+  );
+}
+
+/**
+ * Stop background sync
+ */
+export function stopSync() {
+  if (syncInterval) {
+    clearInterval(syncInterval);
+    syncInterval = null;
+    console.log("[Last.fm] Background sync stopped");
+  }
+}
+
+/**
+ * Run a single sync operation
+ * @param {object} Indiekit - Indiekit instance
+ * @param {object} options - Plugin options
+ * @returns {Promise<object>} - Sync result
+ */
+export async function runSync(Indiekit, options) {
+  const db = Indiekit.database;
+  if (!db) {
+    console.log("[Last.fm] No database available, skipping sync");
+    return { synced: 0, error: "No database" };
+  }
+
+  const client = new LastFmClient({
+    apiKey: options.apiKey,
+    username: options.username,
+    cacheTtl: 60_000, // Short cache for sync
+  });
+
+  const result = await syncScrobbles(db, client);
+
+  // Update stats cache after sync
+  try {
+    const stats = await getAllStats(db, options.limits || {}, client);
+    setCachedStats(stats);
+    console.log("[Last.fm] Stats cache updated");
+  } catch (err) {
+    console.error("[Last.fm] Failed to cache stats:", err.message);
+  }
+
+  return result;
+}
+
+/**
+ * Sync scrobbles to MongoDB
+ * @param {object} db - MongoDB database instance
+ * @param {LastFmClient} client - Last.fm API client
+ * @returns {Promise<object>} - Sync result
+ */
+export async function syncScrobbles(db, client) {
+  const collection = db.collection("scrobbles");
+
+  // Create indexes for efficient queries
+  await collection.createIndex({ lastfmId: 1 }, { unique: true, sparse: true });
+  // Create compound index for deduplication (same track at same time)
+  await collection.createIndex(
+    { trackTitle: 1, artistName: 1, scrobbledAt: 1 },
+    { unique: true }
+  );
+  // Create index on scrobbledAt for time-based queries
+  await collection.createIndex({ scrobbledAt: -1 });
+  // Create indexes for aggregation
+  await collection.createIndex({ artistName: 1 });
+  await collection.createIndex({ albumTitle: 1 });
+
+  // Get the latest synced scrobble
+  const latest = await collection.findOne({}, { sort: { scrobbledAt: -1 } });
+  const latestDate = latest?.scrobbledAt || new Date(0);
+
+  console.log(
+    `[Last.fm] Syncing scrobbles since: ${latestDate.toISOString()}`
+  );
+
+  // Fetch new scrobbles
+  let newScrobbles;
+  if (latestDate.getTime() === 0) {
+    // First sync: get recent history (not all-time to avoid rate limits)
+    console.log("[Last.fm] First sync, fetching recent scrobbles...");
+    newScrobbles = await client.getAllRecentTracks(10); // ~2000 tracks max
+  } else {
+    // Incremental sync
+    newScrobbles = await client.getNewScrobbles(latestDate);
+  }
+
+  if (newScrobbles.length === 0) {
+    console.log("[Last.fm] No new scrobbles to sync");
+    return { synced: 0 };
+  }
+
+  console.log(`[Last.fm] Found ${newScrobbles.length} new scrobbles`);
+
+  // Transform to our schema
+  const docs = newScrobbles.map((s) => transformScrobble(s));
+
+  // Upsert each document (in case of duplicates)
+  let synced = 0;
+  for (const doc of docs) {
+    try {
+      await collection.updateOne(
+        {
+          trackTitle: doc.trackTitle,
+          artistName: doc.artistName,
+          scrobbledAt: doc.scrobbledAt,
+        },
+        { $set: doc },
+        { upsert: true }
+      );
+      synced++;
+    } catch (err) {
+      // Ignore duplicate key errors
+      if (err.code !== 11000) {
+        console.error(`[Last.fm] Error inserting scrobble:`, err.message);
+      }
+    }
+  }
+
+  console.log(`[Last.fm] Synced ${synced} scrobbles`);
+  return { synced };
+}
+
+/**
+ * Transform Last.fm scrobble to our schema
+ * @param {object} scrobble - Last.fm track object
+ * @returns {object} - Transformed document
+ */
+function transformScrobble(scrobble) {
+  const scrobbledAt = parseDate(scrobble.date);
+  const artistName = getArtistName(scrobble);
+  const albumTitle = getAlbumName(scrobble);
+
+  return {
+    // Create a unique ID from track info and timestamp
+    lastfmId: `${artistName}:${scrobble.name}:${scrobbledAt.getTime()}`,
+    trackTitle: scrobble.name,
+    trackUrl: getTrackUrl(scrobble),
+    artistName,
+    artistMbid: scrobble.artist?.mbid || null,
+    albumTitle,
+    albumMbid: scrobble.album?.mbid || null,
+    mbid: getMbid(scrobble),
+    coverUrl: getCoverUrl(scrobble),
+    loved: scrobble.loved === "1",
+    scrobbledAt,
+    syncedAt: new Date(),
+  };
+}

package/lib/utils.js

@@ -0,0 +1,364 @@
+/**
+ * Truncate text with ellipsis
+ * @param {string} text - Text to truncate
+ * @param {number} [maxLength] - Maximum length
+ * @returns {string} - Truncated text
+ */
+export function truncate(text, maxLength = 80) {
+  if (!text || text.length <= maxLength) return text || "";
+  return text.slice(0, maxLength - 1) + "...";
+}
+
+/**
+ * Get the artist name from a Last.fm track
+ * @param {object} track - Last.fm track object
+ * @returns {string} - Artist name
+ */
+export function getArtistName(track) {
+  if (!track) return "Unknown Artist";
+
+  // Extended format has artist.name
+  if (track.artist?.name) {
+    return track.artist.name;
+  }
+
+  // Standard format has artist["#text"]
+  if (track.artist?.["#text"]) {
+    return track.artist["#text"];
+  }
+
+  // Sometimes it's just a string
+  if (typeof track.artist === "string") {
+    return track.artist;
+  }
+
+  return "Unknown Artist";
+}
+
+/**
+ * Get the album name from a Last.fm track
+ * @param {object} track - Last.fm track object
+ * @returns {string|null} - Album name or null
+ */
+export function getAlbumName(track) {
+  if (!track?.album) return null;
+
+  if (track.album["#text"]) {
+    return track.album["#text"];
+  }
+
+  if (typeof track.album === "string") {
+    return track.album;
+  }
+
+  return null;
+}
+
+/**
+ * Get the best available cover URL from a Last.fm track
+ * @param {object} track - Last.fm track object
+ * @param {string} [preferredSize] - Size preference: 'small', 'medium', 'large', 'extralarge'
+ * @returns {string|null} - Cover URL or null
+ */
+export function getCoverUrl(track, preferredSize = "extralarge") {
+  if (!track?.image || !Array.isArray(track.image)) return null;
+
+  // Size priority order
+  const sizePriority = ["extralarge", "large", "medium", "small"];
+  const startIndex = sizePriority.indexOf(preferredSize);
+  const orderedSizes = [
+    ...sizePriority.slice(startIndex),
+    ...sizePriority.slice(0, startIndex),
+  ];
+
+  for (const size of orderedSizes) {
+    const img = track.image.find((i) => i.size === size);
+    if (img?.["#text"]) {
+      return img["#text"];
+    }
+  }
+
+  // Fall back to any available image
+  const anyImg = track.image.find((i) => i["#text"]);
+  return anyImg?.["#text"] || null;
+}
+
+/**
+ * Get the track URL on Last.fm
+ * @param {object} track - Last.fm track object
+ * @returns {string|null} - Track URL or null
+ */
+export function getTrackUrl(track) {
+  return track?.url || null;
+}
+
+/**
+ * Get the MusicBrainz ID if available
+ * @param {object} track - Last.fm track object
+ * @returns {string|null} - MBID or null
+ */
+export function getMbid(track) {
+  return track?.mbid || null;
+}
+
+/**
+ * Parse Unix timestamp from Last.fm date object
+ * @param {object|string} dateInput - Last.fm date object or ISO string
+ * @returns {Date} - JavaScript Date object
+ */
+export function parseDate(dateInput) {
+  if (!dateInput) return new Date();
+
+  // If it's a Last.fm date object with uts (Unix timestamp)
+  if (dateInput.uts) {
+    return new Date(parseInt(dateInput.uts) * 1000);
+  }
+
+  // If it's already a Date or ISO string
+  return new Date(dateInput);
+}
+
+/**
+ * Format duration in seconds to human-readable string
+ * @param {number} seconds - Duration in seconds
+ * @returns {string} - Formatted duration (e.g., "3:45" or "1h 23m")
+ */
+export function formatDuration(seconds) {
+  if (!seconds || seconds < 0) return "0:00";
+
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const secs = Math.floor(seconds % 60);
+
+  if (hours > 0) {
+    return `${hours}h ${minutes}m`;
+  }
+
+  return `${minutes}:${secs.toString().padStart(2, "0")}`;
+}
+
+/**
+ * Format total listening time for stats display
+ * @param {number} seconds - Total seconds
+ * @returns {string} - Human-readable duration
+ */
+export function formatTotalTime(seconds) {
+  if (!seconds || seconds < 0) return "0 minutes";
+
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+
+  if (hours > 24) {
+    const days = Math.floor(hours / 24);
+    const remainingHours = hours % 24;
+    if (remainingHours > 0) {
+      return `${days}d ${remainingHours}h`;
+    }
+    return `${days} days`;
+  }
+
+  if (hours > 0) {
+    if (minutes > 0) {
+      return `${hours}h ${minutes}m`;
+    }
+    return `${hours} hours`;
+  }
+
+  return `${minutes} minutes`;
+}
+
+/**
+ * Format date for display
+ * @param {string|Date|object} dateInput - ISO date string, Date object, or Last.fm date
+ * @param {string} [locale] - Locale for formatting
+ * @returns {string} - Formatted date
+ */
+export function formatDate(dateInput, locale = "en") {
+  const date = parseDate(dateInput);
+  return date.toLocaleDateString(locale, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+/**
+ * Format relative time
+ * @param {string|Date|object} dateInput - ISO date string, Date object, or Last.fm date
+ * @returns {string} - Relative time string
+ */
+export function formatRelativeTime(dateInput) {
+  const date = parseDate(dateInput);
+  const now = new Date();
+  const diffMs = now - date;
+  const diffMins = Math.floor(diffMs / 60_000);
+  const diffHours = Math.floor(diffMs / 3_600_000);
+  const diffDays = Math.floor(diffMs / 86_400_000);
+
+  if (diffMins < 1) return "just now";
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 7) return `${diffDays}d ago`;
+
+  return formatDate(dateInput);
+}
+
+/**
+ * Determine the playing status based on track attributes or timestamp
+ * @param {object} track - Last.fm track object
+ * @returns {string|null} - 'now-playing', 'recently-played', or null
+ */
+export function getPlayingStatus(track) {
+  // Check if currently playing via Last.fm attribute
+  if (track["@attr"]?.nowplaying === "true") {
+    return "now-playing";
+  }
+
+  // Otherwise check based on timestamp
+  const date = parseDate(track.date);
+  const now = new Date();
+  const diffMs = now - date;
+  const diffMins = diffMs / 60_000;
+
+  if (diffMins < 60) {
+    return "now-playing";
+  }
+
+  if (diffMins < 24 * 60) {
+    return "recently-played";
+  }
+
+  return null;
+}
+
+/**
+ * Format a scrobble entry for API response
+ * @param {object} scrobble - Last.fm track object or MongoDB document
+ * @param {boolean} [fromDb] - Whether the scrobble is from MongoDB
+ * @returns {object} - Formatted scrobble
+ */
+export function formatScrobble(scrobble, fromDb = false) {
+  if (fromDb) {
+    // From MongoDB
+    const scrobbledAt = scrobble.scrobbledAt;
+    return {
+      id: scrobble.lastfmId || scrobble._id?.toString(),
+      track: scrobble.trackTitle,
+      artist: scrobble.artistName,
+      album: scrobble.albumTitle,
+      coverUrl: scrobble.coverUrl,
+      trackUrl: scrobble.trackUrl,
+      mbid: scrobble.mbid,
+      loved: scrobble.loved || false,
+      scrobbledAt: scrobbledAt.toISOString(),
+      relativeTime: formatRelativeTime(scrobbledAt),
+      status: getPlayingStatus({ date: scrobbledAt }),
+    };
+  }
+
+  // From API
+  const scrobbledAt = parseDate(scrobble.date);
+  const isNowPlaying = scrobble["@attr"]?.nowplaying === "true";
+
+  return {
+    id: `${scrobble.artist?.mbid || ""}:${scrobble.mbid || scrobble.name}:${scrobbledAt.getTime()}`,
+    track: scrobble.name,
+    artist: getArtistName(scrobble),
+    album: getAlbumName(scrobble),
+    coverUrl: getCoverUrl(scrobble),
+    trackUrl: getTrackUrl(scrobble),
+    mbid: getMbid(scrobble),
+    loved: scrobble.loved === "1",
+    scrobbledAt: isNowPlaying ? new Date().toISOString() : scrobbledAt.toISOString(),
+    relativeTime: isNowPlaying ? "now" : formatRelativeTime(scrobbledAt),
+    status: getPlayingStatus(scrobble),
+  };
+}
+
+/**
+ * Format a loved track entry for API response
+ * @param {object} track - Last.fm loved track object
+ * @returns {object} - Formatted loved track
+ */
+export function formatLovedTrack(track) {
+  const lovedAt = parseDate(track.date);
+
+  return {
+    id: track.mbid || `${getArtistName(track)}:${track.name}`,
+    track: track.name,
+    artist: getArtistName(track),
+    coverUrl: getCoverUrl(track),
+    trackUrl: getTrackUrl(track),
+    mbid: getMbid(track),
+    lovedAt: lovedAt.toISOString(),
+    relativeTime: formatRelativeTime(lovedAt),
+  };
+}
+
+/**
+ * Format a top artist entry for API response
+ * @param {object} artist - Last.fm top artist object
+ * @param {number} rank - Artist rank
+ * @returns {object} - Formatted artist
+ */
+export function formatTopArtist(artist, rank) {
+  return {
+    rank,
+    name: artist.name,
+    playCount: parseInt(artist.playcount) || 0,
+    url: artist.url,
+    mbid: artist.mbid || null,
+    imageUrl: getCoverUrl(artist),
+  };
+}
+
+/**
+ * Format a top album entry for API response
+ * @param {object} album - Last.fm top album object
+ * @param {number} rank - Album rank
+ * @returns {object} - Formatted album
+ */
+export function formatTopAlbum(album, rank) {
+  return {
+    rank,
+    title: album.name,
+    artist: album.artist?.name || album.artist?.["#text"] || album.artist,
+    playCount: parseInt(album.playcount) || 0,
+    url: album.url,
+    mbid: album.mbid || null,
+    coverUrl: getCoverUrl(album),
+  };
+}
+
+/**
+ * Map Last.fm period to internal period name
+ * @param {string} period - Last.fm period (7day, 1month, 3month, 6month, 12month, overall)
+ * @returns {string} - Internal period name (week, month, all)
+ */
+export function mapPeriodToInternal(period) {
+  switch (period) {
+    case "7day":
+      return "week";
+    case "1month":
+    case "3month":
+      return "month";
+    default:
+      return "all";
+  }
+}
+
+/**
+ * Map internal period to Last.fm period
+ * @param {string} period - Internal period (week, month, all)
+ * @returns {string} - Last.fm period
+ */
+export function mapPeriodToLastfm(period) {
+  switch (period) {
+    case "week":
+      return "7day";
+    case "month":
+      return "1month";
+    default:
+      return "overall";
+  }
+}

package/locales/en.json

@@ -0,0 +1,37 @@
+{
+  "lastfm": {
+    "title": "Last.fm",
+    "scrobbles": "Scrobble History",
+    "loved": "Loved Tracks",
+    "stats": "Statistics",
+    "nowPlaying": "Now Playing",
+    "recentlyPlayed": "Recently Played",
+    "lastPlayed": "Last Played",
+    "allTime": "All Time",
+    "thisWeek": "This Week",
+    "thisMonth": "This Month",
+    "trends": "Trends",
+    "scrobbleTrend": "Scrobble Trend (30 days)",
+    "topArtists": "Top Artists",
+    "topAlbums": "Top Albums",
+    "plays": "plays",
+    "tracks": "tracks",
+    "artists": "artists",
+    "albums": "albums",
+    "scrobbleTime": "Scrobble Time",
+    "noRecentPlays": "No music scrobbled recently",
+    "noLoved": "No loved tracks yet",
+    "viewAll": "View All",
+    "viewStats": "View Statistics",
+    "sync": "Sync Now",
+    "lastSync": "Last sync",
+    "error": {
+      "connection": "Could not connect to Last.fm",
+      "noConfig": "Last.fm endpoint not configured correctly"
+    },
+    "widget": {
+      "description": "View full scrobble activity on the public page",
+      "view": "View Public Page"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@rmdes/indiekit-endpoint-lastfm",
+  "version": "1.0.0",
+  "description": "Last.fm scrobble and listening activity endpoint for Indiekit. Display listening history, loved tracks, and statistics.",
+  "keywords": [
+    "indiekit",
+    "indiekit-plugin",
+    "indieweb",
+    "lastfm",
+    "last.fm",
+    "music",
+    "scrobble",
+    "listening",
+    "activity"
+  ],
+  "homepage": "https://github.com/rmdes/indiekit-endpoint-lastfm",
+  "bugs": {
+    "url": "https://github.com/rmdes/indiekit-endpoint-lastfm/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rmdes/indiekit-endpoint-lastfm.git"
+  },
+  "author": {
+    "name": "Ricardo Mendes",
+    "url": "https://rmendes.net"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "includes",
+    "lib",
+    "locales",
+    "views",
+    "index.js"
+  ],
+  "dependencies": {
+    "@indiekit/error": "^1.0.0-beta.25",
+    "express": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@indiekit/indiekit": ">=1.0.0-beta.25"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}