@rmdes/indiekit-endpoint-lastfm 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# @rmdes/indiekit-endpoint-lastfm
+
+Last.fm scrobble and listening activity endpoint for [Indiekit](https://getindiekit.com).
+
+## Features
+
+- Display scrobble history from Last.fm
+- Now playing / recently played status
+- Loved tracks
+- Listening statistics (top artists, albums, trends)
+- Background sync to MongoDB for offline access
+- Public JSON API for frontend integration
+
+## Installation
+
+```bash
+npm install @rmdes/indiekit-endpoint-lastfm
+```
+
+## Configuration
+
+Add to your Indiekit config:
+
+```javascript
+import LastFmEndpoint from "@rmdes/indiekit-endpoint-lastfm";
+
+export default {
+  plugins: [
+    "@rmdes/indiekit-endpoint-lastfm",
+    // ... other plugins
+  ],
+
+  "@rmdes/indiekit-endpoint-lastfm": {
+    mountPath: "/lastfmapi",
+    apiKey: process.env.LASTFM_API_KEY,
+    username: process.env.LASTFM_USERNAME,
+    cacheTtl: 900_000,        // 15 minutes
+    syncInterval: 300_000,    // 5 minutes
+    limits: {
+      scrobbles: 20,
+      loved: 20,
+      topArtists: 10,
+      topAlbums: 10,
+    },
+  },
+};
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LASTFM_API_KEY` | Your Last.fm API key ([get one here](https://www.last.fm/api/account/create)) |
+| `LASTFM_USERNAME` | Last.fm username to track |
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/now-playing` | Current or recently played track |
+| `GET /api/scrobbles` | Paginated scrobble history |
+| `GET /api/loved` | Paginated loved tracks |
+| `GET /api/stats` | Listening statistics |
+| `GET /api/stats/trends` | Daily scrobble trends |
+
+## Requirements
+
+- Node.js >= 20
+- Indiekit >= 1.0.0-beta.25
+- MongoDB (for background sync and statistics)
+
+## License
+
+MIT

package/includes/@indiekit-endpoint-lastfm-now-playing.njk

@@ -0,0 +1,90 @@
+{#
+  Now Playing Widget
+  Fetches data from /lastfm/api/now-playing
+  Include this in your Eleventy templates
+#}
+<div class="lastfm-now-playing-widget" id="lastfm-now-playing">
+  <div class="lastfm-now-playing-widget__loading">
+    Loading...
+  </div>
+</div>
+
+<script>
+(function() {
+  const container = document.getElementById('lastfm-now-playing');
+  const endpoint = '{{ application.lastfmEndpoint or "/lastfm" }}/api/now-playing';
+
+  fetch(endpoint)
+    .then(res => res.json())
+    .then(data => {
+      container.textContent = '';
+
+      if (!data.track) {
+        const empty = document.createElement('p');
+        empty.className = 'lastfm-widget__empty';
+        empty.textContent = 'No recent plays';
+        container.appendChild(empty);
+        return;
+      }
+
+      const widget = document.createElement('div');
+      widget.className = 'lastfm-widget' + (data.status === 'now-playing' ? ' lastfm-widget--playing' : '');
+
+      if (data.status === 'now-playing') {
+        const bars = document.createElement('div');
+        bars.className = 'lastfm-bars';
+        for (let i = 0; i < 3; i++) {
+          bars.appendChild(document.createElement('span'));
+        }
+        widget.appendChild(bars);
+      }
+
+      const status = document.createElement('span');
+      status.className = 'lastfm-widget__status';
+      status.textContent = data.status === 'now-playing' ? 'Now Playing' :
+                           data.status === 'recently-played' ? 'Recently Played' : 'Last Played';
+      widget.appendChild(status);
+
+      if (data.coverUrl) {
+        const img = document.createElement('img');
+        img.src = data.coverUrl;
+        img.alt = '';
+        img.className = 'lastfm-widget__cover';
+        widget.appendChild(img);
+      }
+
+      const info = document.createElement('div');
+      info.className = 'lastfm-widget__info';
+
+      const link = document.createElement('a');
+      link.href = data.trackUrl;
+      link.className = 'lastfm-widget__title';
+      link.target = '_blank';
+      link.rel = 'noopener';
+      link.textContent = data.artist + ' - ' + data.track;
+      info.appendChild(link);
+
+      if (data.loved) {
+        const heart = document.createElement('span');
+        heart.className = 'lastfm-widget__loved';
+        heart.textContent = ' \u2665';
+        link.appendChild(heart);
+      }
+
+      const time = document.createElement('span');
+      time.className = 'lastfm-widget__time';
+      time.textContent = data.relativeTime;
+      info.appendChild(time);
+
+      widget.appendChild(info);
+      container.appendChild(widget);
+    })
+    .catch(err => {
+      container.textContent = '';
+      const error = document.createElement('p');
+      error.className = 'lastfm-widget__error';
+      error.textContent = 'Could not load';
+      container.appendChild(error);
+    });
+})();
+</script>

package/includes/@indiekit-endpoint-lastfm-stats.njk

@@ -0,0 +1,75 @@
+{#
+  Stats Widget
+  Fetches data from /lastfm/api/stats
+  Include this in your Eleventy templates for a sidebar widget
+#}
+<div class="lastfm-stats-widget" id="lastfm-stats">
+  <div class="lastfm-stats-widget__loading">
+    Loading stats...
+  </div>
+</div>
+
+<script>
+(function() {
+  const container = document.getElementById('lastfm-stats');
+  const endpoint = '{{ application.lastfmEndpoint or "/lastfm" }}/api/stats';
+
+  fetch(endpoint)
+    .then(res => res.json())
+    .then(data => {
+      container.textContent = '';
+      const all = data.summary?.all || {};
+
+      const grid = document.createElement('div');
+      grid.className = 'lastfm-stats-widget__grid';
+
+      // Plays stat
+      const playsStat = document.createElement('div');
+      playsStat.className = 'lastfm-stats-widget__stat';
+      const playsValue = document.createElement('span');
+      playsValue.className = 'lastfm-stats-widget__value';
+      playsValue.textContent = all.totalPlays || 0;
+      const playsLabel = document.createElement('span');
+      playsLabel.className = 'lastfm-stats-widget__label';
+      playsLabel.textContent = 'scrobbles';
+      playsStat.appendChild(playsValue);
+      playsStat.appendChild(playsLabel);
+      grid.appendChild(playsStat);
+
+      // Artists stat
+      const artistsStat = document.createElement('div');
+      artistsStat.className = 'lastfm-stats-widget__stat';
+      const artistsValue = document.createElement('span');
+      artistsValue.className = 'lastfm-stats-widget__value';
+      artistsValue.textContent = all.uniqueArtists || 0;
+      const artistsLabel = document.createElement('span');
+      artistsLabel.className = 'lastfm-stats-widget__label';
+      artistsLabel.textContent = 'artists';
+      artistsStat.appendChild(artistsValue);
+      artistsStat.appendChild(artistsLabel);
+      grid.appendChild(artistsStat);
+
+      // Loved stat
+      const lovedStat = document.createElement('div');
+      lovedStat.className = 'lastfm-stats-widget__stat';
+      const lovedValue = document.createElement('span');
+      lovedValue.className = 'lastfm-stats-widget__value';
+      lovedValue.textContent = all.lovedCount || 0;
+      const lovedLabel = document.createElement('span');
+      lovedLabel.className = 'lastfm-stats-widget__label';
+      lovedLabel.textContent = 'loved';
+      lovedStat.appendChild(lovedValue);
+      lovedStat.appendChild(lovedLabel);
+      grid.appendChild(lovedStat);
+
+      container.appendChild(grid);
+    })
+    .catch(err => {
+      container.textContent = '';
+      const error = document.createElement('p');
+      error.className = 'lastfm-widget__error';
+      error.textContent = 'Could not load stats';
+      container.appendChild(error);
+    });
+})();
+</script>

package/includes/@indiekit-endpoint-lastfm-widget.njk

@@ -0,0 +1,12 @@
+{% call widget({
+  title: __("lastfm.title")
+}) %}
+  <p class="prose">{{ __("lastfm.widget.description") }}</p>
+  <div class="button-grid">
+    {{ button({
+      classes: "button--secondary-on-offset",
+      href: application.lastfmEndpoint or "/lastfm",
+      text: __("lastfm.widget.view")
+    }) }}
+  </div>
+{% endcall %}

package/index.js

@@ -0,0 +1,110 @@
+import express from "express";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { dashboardController } from "./lib/controllers/dashboard.js";
+import { scrobblesController } from "./lib/controllers/scrobbles.js";
+import { lovedController } from "./lib/controllers/loved.js";
+import { statsController } from "./lib/controllers/stats.js";
+import { nowPlayingController } from "./lib/controllers/now-playing.js";
+import { startSync } from "./lib/sync.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const protectedRouter = express.Router();
+const publicRouter = express.Router();
+
+const defaults = {
+  mountPath: "/lastfm",
+  apiKey: process.env.LASTFM_API_KEY,
+  username: process.env.LASTFM_USERNAME,
+  cacheTtl: 900_000, // 15 minutes in ms
+  syncInterval: 300_000, // 5 minutes in ms
+  limits: {
+    scrobbles: 20,
+    loved: 20,
+    topArtists: 10,
+    topAlbums: 10,
+  },
+};
+
+export default class LastFmEndpoint {
+  name = "Last.fm listening activity endpoint";
+
+  constructor(options = {}) {
+    this.options = { ...defaults, ...options };
+    this.mountPath = this.options.mountPath;
+  }
+
+  get environment() {
+    return ["LASTFM_API_KEY", "LASTFM_USERNAME"];
+  }
+
+  get localesDirectory() {
+    return path.join(__dirname, "locales");
+  }
+
+  get navigationItems() {
+    return {
+      href: this.options.mountPath,
+      text: "lastfm.title",
+      requiresDatabase: true,
+    };
+  }
+
+  get shortcutItems() {
+    return {
+      url: this.options.mountPath,
+      name: "lastfm.scrobbles",
+      iconName: "syndicate",
+      requiresDatabase: true,
+    };
+  }
+
+  /**
+   * Protected routes (require authentication)
+   * Admin dashboard only - detailed views are on the public frontend
+   */
+  get routes() {
+    // Dashboard overview
+    protectedRouter.get("/", dashboardController.get);
+
+    // Manual sync trigger
+    protectedRouter.post("/sync", dashboardController.sync);
+
+    return protectedRouter;
+  }
+
+  /**
+   * Public routes (no authentication required)
+   * JSON API endpoints for Eleventy frontend
+   */
+  get routesPublic() {
+    publicRouter.get("/api/now-playing", nowPlayingController.api);
+    publicRouter.get("/api/scrobbles", scrobblesController.api);
+    publicRouter.get("/api/loved", lovedController.api);
+    publicRouter.get("/api/stats", statsController.api);
+    publicRouter.get("/api/stats/trends", statsController.apiTrends);
+
+    return publicRouter;
+  }
+
+  init(Indiekit) {
+    Indiekit.addEndpoint(this);
+
+    // Add MongoDB collection for scrobbles sync
+    Indiekit.addCollection("scrobbles");
+
+    // Store Last.fm config in application for controller access
+    Indiekit.config.application.lastfmConfig = this.options;
+    Indiekit.config.application.lastfmEndpoint = this.mountPath;
+
+    // Store database getter for controller access
+    Indiekit.config.application.getLastfmDb = () => Indiekit.database;
+
+    // Start background sync if database is available
+    if (Indiekit.config.application.mongodbUrl) {
+      startSync(Indiekit, this.options);
+    }
+  }
+}

package/lib/controllers/dashboard.js

@@ -0,0 +1,140 @@
+import { LastFmClient } from "../lastfm-client.js";
+import { runSync, getCachedStats, refreshStatsCache } from "../sync.js";
+import * as utils from "../utils.js";
+
+/**
+ * Dashboard controller
+ */
+export const dashboardController = {
+  /**
+   * Render dashboard page
+   * @type {import("express").RequestHandler}
+   */
+  async get(request, response, next) {
+    try {
+      const { lastfmConfig, lastfmEndpoint } = request.app.locals.application;
+
+      if (!lastfmConfig) {
+        return response.status(500).render("lastfm", {
+          title: "Last.fm",
+          error: { message: "Last.fm endpoint not configured" },
+        });
+      }
+
+      const { apiKey, username, cacheTtl, limits } = lastfmConfig;
+
+      if (!apiKey || !username) {
+        return response.render("lastfm", {
+          title: response.locals.__("lastfm.title"),
+          error: { message: response.locals.__("lastfm.error.noConfig") },
+        });
+      }
+
+      const client = new LastFmClient({
+        apiKey,
+        username,
+        cacheTtl,
+      });
+
+      // Fetch recent data from API
+      let scrobbles = [];
+      let lovedTracks = [];
+      let nowPlaying = null;
+      let userInfo = null;
+
+      try {
+        const [scrobblesRes, lovedRes, userRes] = await Promise.all([
+          client.getRecentTracks(1, limits.scrobbles || 10),
+          client.getLovedTracks(1, limits.loved || 5),
+          client.getUserInfo(),
+        ]);
+
+        const tracks = scrobblesRes.recenttracks?.track || [];
+        scrobbles = tracks.map((s) => utils.formatScrobble(s));
+        lovedTracks = (lovedRes.lovedtracks?.track || []).map((t) =>
+          utils.formatLovedTrack(t)
+        );
+        userInfo = userRes.user || null;
+
+        // Check for now playing
+        if (scrobbles.length > 0 && scrobbles[0].status) {
+          nowPlaying = scrobbles[0];
+        }
+      } catch (apiError) {
+        console.error("[Last.fm] API error:", apiError.message);
+        return response.render("lastfm", {
+          title: response.locals.__("lastfm.title"),
+          error: { message: response.locals.__("lastfm.error.connection") },
+        });
+      }
+
+      // Get stats from cache (same source as public API)
+      // If cache is empty, try to refresh it from database
+      let cachedStats = getCachedStats();
+      if (!cachedStats) {
+        const getDb = request.app.locals.application.getLastfmDb;
+        if (getDb) {
+          const db = getDb();
+          if (db) {
+            cachedStats = await refreshStatsCache(db, limits, client);
+          }
+        }
+      }
+      const summary = cachedStats?.summary?.all || null;
+
+      // Determine public frontend URL (strip 'api' from mount path)
+      // e.g., /lastfmapi -> /lastfm
+      const publicUrl = lastfmEndpoint
+        ? lastfmEndpoint.replace(/api$/, "")
+        : "/lastfm";
+
+      response.render("lastfm", {
+        title: response.locals.__("lastfm.title"),
+        nowPlaying,
+        scrobbles: scrobbles.slice(0, 5),
+        lovedTracks: lovedTracks.slice(0, 5),
+        totalPlays: summary?.totalPlays || userInfo?.playcount || 0,
+        uniqueTracks: summary?.uniqueTracks || 0,
+        uniqueArtists: summary?.uniqueArtists || 0,
+        hasStats: !!summary,
+        userInfo,
+        publicUrl,
+        mountPath: request.baseUrl,
+      });
+    } catch (error) {
+      console.error("[Last.fm] Dashboard error:", error);
+      next(error);
+    }
+  },
+
+  /**
+   * Trigger manual sync
+   * @type {import("express").RequestHandler}
+   */
+  async sync(request, response, next) {
+    try {
+      const { lastfmConfig } = request.app.locals.application;
+
+      if (!lastfmConfig) {
+        return response.status(500).json({ error: "Not configured" });
+      }
+
+      // Get Indiekit instance from app
+      const Indiekit = request.app.locals.indiekit;
+      if (!Indiekit || !Indiekit.database) {
+        return response.status(500).json({ error: "Database not available" });
+      }
+
+      const result = await runSync(Indiekit, lastfmConfig);
+
+      response.json({
+        success: true,
+        synced: result.synced,
+        message: `Synced ${result.synced} new scrobbles`,
+      });
+    } catch (error) {
+      console.error("[Last.fm] Manual sync error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};

package/lib/controllers/loved.js

@@ -0,0 +1,52 @@
+import { LastFmClient } from "../lastfm-client.js";
+import * as utils from "../utils.js";
+
+/**
+ * Loved tracks controller
+ */
+export const lovedController = {
+  /**
+   * JSON API for loved tracks
+   * @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" });
+      }
+
+      const { apiKey, username, cacheTtl, limits } = lastfmConfig;
+      const page = parseInt(request.query.page) || 1;
+      const limit = Math.min(
+        parseInt(request.query.limit) || limits.loved || 20,
+        200
+      );
+
+      const client = new LastFmClient({
+        apiKey,
+        username,
+        cacheTtl,
+      });
+
+      const lovedRes = await client.getLovedTracks(page, limit);
+      const tracks = lovedRes.lovedtracks?.track || [];
+      const loved = tracks.map((t) => utils.formatLovedTrack(t));
+
+      const attrs = lovedRes.lovedtracks?.["@attr"] || {};
+      const totalPages = parseInt(attrs.totalPages) || 1;
+
+      response.json({
+        loved,
+        total: parseInt(attrs.total) || loved.length,
+        page: parseInt(attrs.page) || page,
+        hasNext: page < totalPages,
+        hasPrev: page > 1,
+      });
+    } catch (error) {
+      console.error("[Last.fm] Loved API error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};

package/lib/controllers/now-playing.js

@@ -0,0 +1,57 @@
+import { LastFmClient } from "../lastfm-client.js";
+import * as utils from "../utils.js";
+
+/**
+ * Now Playing controller
+ */
+export const nowPlayingController = {
+  /**
+   * JSON API for now playing / recently played
+   * @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" });
+      }
+
+      const { apiKey, username, cacheTtl } = lastfmConfig;
+
+      const client = new LastFmClient({
+        apiKey,
+        username,
+        cacheTtl: Math.min(cacheTtl, 60_000), // Max 1 minute cache for now playing
+      });
+
+      const track = await client.getLatestScrobble();
+
+      if (!track) {
+        return response.json({
+          playing: false,
+          status: null,
+          message: "No recent plays",
+        });
+      }
+
+      const formatted = utils.formatScrobble(track);
+
+      response.json({
+        playing: formatted.status === "now-playing",
+        status: formatted.status,
+        track: formatted.track,
+        artist: formatted.artist,
+        album: formatted.album,
+        coverUrl: formatted.coverUrl,
+        trackUrl: formatted.trackUrl,
+        loved: formatted.loved,
+        scrobbledAt: formatted.scrobbledAt,
+        relativeTime: formatted.relativeTime,
+      });
+    } catch (error) {
+      console.error("[Last.fm] Now Playing API error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};

package/lib/controllers/scrobbles.js

@@ -0,0 +1,52 @@
+import { LastFmClient } from "../lastfm-client.js";
+import * as utils from "../utils.js";
+
+/**
+ * Scrobbles controller
+ */
+export const scrobblesController = {
+  /**
+   * JSON API for scrobbles
+   * @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" });
+      }
+
+      const { apiKey, username, cacheTtl, limits } = lastfmConfig;
+      const page = parseInt(request.query.page) || 1;
+      const limit = Math.min(
+        parseInt(request.query.limit) || limits.scrobbles || 20,
+        200
+      );
+
+      const client = new LastFmClient({
+        apiKey,
+        username,
+        cacheTtl,
+      });
+
+      const scrobblesRes = await client.getRecentTracks(page, limit);
+      const tracks = scrobblesRes.recenttracks?.track || [];
+      const scrobbles = tracks.map((s) => utils.formatScrobble(s));
+
+      const attrs = scrobblesRes.recenttracks?.["@attr"] || {};
+      const totalPages = parseInt(attrs.totalPages) || 1;
+
+      response.json({
+        scrobbles,
+        total: parseInt(attrs.total) || scrobbles.length,
+        page: parseInt(attrs.page) || page,
+        hasNext: page < totalPages,
+        hasPrev: page > 1,
+      });
+    } catch (error) {
+      console.error("[Last.fm] Scrobbles API error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};