@rmdes/indiekit-endpoint-funkwhale 1.0.0

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

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

package/index.js

@@ -0,0 +1,108 @@
+import express from "express";
+
+import { dashboardController } from "./lib/controllers/dashboard.js";
+import { listeningsController } from "./lib/controllers/listenings.js";
+import { favoritesController } from "./lib/controllers/favorites.js";
+import { statsController } from "./lib/controllers/stats.js";
+import { nowPlayingController } from "./lib/controllers/now-playing.js";
+import { startSync } from "./lib/sync.js";
+
+const protectedRouter = express.Router();
+const publicRouter = express.Router();
+
+const defaults = {
+  mountPath: "/funkwhale",
+  instanceUrl: "",
+  username: "",
+  token: process.env.FUNKWHALE_TOKEN,
+  cacheTtl: 900_000, // 15 minutes in ms
+  syncInterval: 300_000, // 5 minutes in ms
+  limits: {
+    listenings: 20,
+    favorites: 20,
+    topArtists: 10,
+    topAlbums: 10,
+  },
+};
+
+export default class FunkwhaleEndpoint {
+  name = "Funkwhale listening activity endpoint";
+
+  constructor(options = {}) {
+    this.options = { ...defaults, ...options };
+    this.mountPath = this.options.mountPath;
+  }
+
+  get environment() {
+    return ["FUNKWHALE_TOKEN", "FUNKWHALE_INSTANCE", "FUNKWHALE_USERNAME"];
+  }
+
+  get navigationItems() {
+    return {
+      href: this.options.mountPath,
+      text: "funkwhale.title",
+      requiresDatabase: true,
+    };
+  }
+
+  get shortcutItems() {
+    return {
+      url: this.options.mountPath,
+      name: "funkwhale.listenings",
+      iconName: "syndicate",
+      requiresDatabase: true,
+    };
+  }
+
+  /**
+   * Protected routes (require authentication)
+   * HTML pages for admin dashboard
+   */
+  get routes() {
+    // Dashboard
+    protectedRouter.get("/", dashboardController.get);
+
+    // Individual sections (HTML pages)
+    protectedRouter.get("/listenings", listeningsController.get);
+    protectedRouter.get("/favorites", favoritesController.get);
+    protectedRouter.get("/stats", statsController.get);
+
+    // Manual sync trigger
+    protectedRouter.post("/sync", dashboardController.sync);
+
+    return protectedRouter;
+  }
+
+  /**
+   * Public routes (no authentication required)
+   * JSON API endpoints for Eleventy widgets
+   */
+  get routesPublic() {
+    // Now playing widget
+    publicRouter.get("/api/now-playing", nowPlayingController.api);
+
+    // JSON API for widgets
+    publicRouter.get("/api/listenings", listeningsController.api);
+    publicRouter.get("/api/favorites", favoritesController.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 listenings sync
+    Indiekit.addCollection("listenings");
+
+    // Store Funkwhale config in application for controller access
+    Indiekit.config.application.funkwhaleConfig = this.options;
+    Indiekit.config.application.funkwhaleEndpoint = this.mountPath;
+
+    // Start background sync if database is available
+    if (Indiekit.config.application.mongodbUrl) {
+      startSync(Indiekit, this.options);
+    }
+  }
+}

package/lib/controllers/dashboard.js

@@ -0,0 +1,122 @@
+import { FunkwhaleClient } from "../funkwhale-client.js";
+import { runSync } from "../sync.js";
+import { getSummary } from "../stats.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 { funkwhaleConfig } = request.app.locals.application;
+
+      if (!funkwhaleConfig) {
+        return response.status(500).render("funkwhale", {
+          title: "Funkwhale",
+          error: { message: "Funkwhale endpoint not configured" },
+        });
+      }
+
+      const { instanceUrl, token, username, cacheTtl, limits } = funkwhaleConfig;
+
+      if (!instanceUrl || !token) {
+        return response.render("funkwhale", {
+          title: response.locals.__("funkwhale.title"),
+          error: { message: response.locals.__("funkwhale.error.noConfig") },
+        });
+      }
+
+      const client = new FunkwhaleClient({
+        instanceUrl,
+        token,
+        username,
+        cacheTtl,
+      });
+
+      // Fetch recent data from API
+      let listenings = [];
+      let favorites = [];
+      let nowPlaying = null;
+
+      try {
+        const [listeningsRes, favoritesRes] = await Promise.all([
+          client.getListenings(1, limits.listenings || 10),
+          client.getFavorites(1, limits.favorites || 5),
+        ]);
+
+        listenings = listeningsRes.results.map((l) => utils.formatListening(l));
+        favorites = favoritesRes.results.map((f) => utils.formatFavorite(f));
+
+        // Check for now playing
+        if (listenings.length > 0 && listenings[0].status) {
+          nowPlaying = listenings[0];
+        }
+      } catch (apiError) {
+        console.error("[Funkwhale] API error:", apiError.message);
+        return response.render("funkwhale", {
+          title: response.locals.__("funkwhale.title"),
+          error: { message: response.locals.__("funkwhale.error.connection") },
+        });
+      }
+
+      // Get stats summary from database if available
+      let summary = null;
+      const db = request.app.locals.database;
+      if (db) {
+        try {
+          summary = await getSummary(db, "all");
+        } catch (dbError) {
+          console.error("[Funkwhale] DB error:", dbError.message);
+        }
+      }
+
+      response.render("funkwhale", {
+        title: response.locals.__("funkwhale.title"),
+        nowPlaying,
+        listenings: listenings.slice(0, 5),
+        favorites: favorites.slice(0, 5),
+        summary,
+        mountPath: request.baseUrl,
+      });
+    } catch (error) {
+      console.error("[Funkwhale] Dashboard error:", error);
+      next(error);
+    }
+  },
+
+  /**
+   * Trigger manual sync
+   * @type {import("express").RequestHandler}
+   */
+  async sync(request, response, next) {
+    try {
+      const { funkwhaleConfig } = request.app.locals.application;
+
+      if (!funkwhaleConfig) {
+        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, funkwhaleConfig);
+
+      response.json({
+        success: true,
+        synced: result.synced,
+        message: `Synced ${result.synced} new listenings`,
+      });
+    } catch (error) {
+      console.error("[Funkwhale] Manual sync error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};

package/lib/controllers/favorites.js

@@ -0,0 +1,110 @@
+import { FunkwhaleClient } from "../funkwhale-client.js";
+import * as utils from "../utils.js";
+
+/**
+ * Favorites controller
+ */
+export const favoritesController = {
+  /**
+   * Render favorites page
+   * @type {import("express").RequestHandler}
+   */
+  async get(request, response, next) {
+    try {
+      const { funkwhaleConfig } = request.app.locals.application;
+
+      if (!funkwhaleConfig) {
+        return response.status(500).render("favorites", {
+          title: "Favorites",
+          error: { message: "Funkwhale endpoint not configured" },
+        });
+      }
+
+      const { instanceUrl, token, username, cacheTtl, limits } = funkwhaleConfig;
+      const page = parseInt(request.query.page) || 1;
+      const pageSize = limits.favorites || 20;
+
+      const client = new FunkwhaleClient({
+        instanceUrl,
+        token,
+        username,
+        cacheTtl,
+      });
+
+      try {
+        const favoritesRes = await client.getFavorites(page, pageSize);
+        const favorites = favoritesRes.results.map((f) =>
+          utils.formatFavorite(f)
+        );
+
+        // Note: count may not reflect filtered count
+        const totalPages = Math.ceil(favoritesRes.count / pageSize);
+
+        response.render("favorites", {
+          title: response.locals.__("funkwhale.favorites"),
+          favorites,
+          pagination: {
+            current: page,
+            total: totalPages,
+            hasNext: favoritesRes.next !== null,
+            hasPrev: favoritesRes.previous !== null,
+          },
+          mountPath: request.baseUrl,
+        });
+      } catch (apiError) {
+        console.error("[Funkwhale] API error:", apiError.message);
+        return response.render("favorites", {
+          title: response.locals.__("funkwhale.favorites"),
+          error: { message: response.locals.__("funkwhale.error.connection") },
+        });
+      }
+    } catch (error) {
+      console.error("[Funkwhale] Favorites error:", error);
+      next(error);
+    }
+  },
+
+  /**
+   * JSON API for favorites
+   * @type {import("express").RequestHandler}
+   */
+  async api(request, response, next) {
+    try {
+      const { funkwhaleConfig } = request.app.locals.application;
+
+      if (!funkwhaleConfig) {
+        return response.status(500).json({ error: "Not configured" });
+      }
+
+      const { instanceUrl, token, username, cacheTtl, limits } = funkwhaleConfig;
+      const page = parseInt(request.query.page) || 1;
+      const limit = Math.min(
+        parseInt(request.query.limit) || limits.favorites || 20,
+        100
+      );
+
+      const client = new FunkwhaleClient({
+        instanceUrl,
+        token,
+        username,
+        cacheTtl,
+      });
+
+      const favoritesRes = await client.getFavorites(page, limit);
+      const favorites = favoritesRes.results.map((f) =>
+        utils.formatFavorite(f)
+      );
+
+      response.json({
+        favorites,
+        total: favoritesRes.count,
+        page,
+        hasNext: favoritesRes.next !== null,
+        hasPrev: favoritesRes.previous !== null,
+      });
+    } catch (error) {
+      console.error("[Funkwhale] Favorites API error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};

package/lib/controllers/listenings.js

@@ -0,0 +1,109 @@
+import { FunkwhaleClient } from "../funkwhale-client.js";
+import * as utils from "../utils.js";
+
+/**
+ * Listenings controller
+ */
+export const listeningsController = {
+  /**
+   * Render listenings page
+   * @type {import("express").RequestHandler}
+   */
+  async get(request, response, next) {
+    try {
+      const { funkwhaleConfig } = request.app.locals.application;
+
+      if (!funkwhaleConfig) {
+        return response.status(500).render("listenings", {
+          title: "Listening History",
+          error: { message: "Funkwhale endpoint not configured" },
+        });
+      }
+
+      const { instanceUrl, token, username, cacheTtl, limits } = funkwhaleConfig;
+      const page = parseInt(request.query.page) || 1;
+      const pageSize = limits.listenings || 20;
+
+      const client = new FunkwhaleClient({
+        instanceUrl,
+        token,
+        username,
+        cacheTtl,
+      });
+
+      try {
+        const listeningsRes = await client.getListenings(page, pageSize);
+        const listenings = listeningsRes.results.map((l) =>
+          utils.formatListening(l)
+        );
+
+        const totalPages = Math.ceil(listeningsRes.count / pageSize);
+
+        response.render("listenings", {
+          title: response.locals.__("funkwhale.listenings"),
+          listenings,
+          pagination: {
+            current: page,
+            total: totalPages,
+            hasNext: listeningsRes.next !== null,
+            hasPrev: listeningsRes.previous !== null,
+          },
+          mountPath: request.baseUrl,
+        });
+      } catch (apiError) {
+        console.error("[Funkwhale] API error:", apiError.message);
+        return response.render("listenings", {
+          title: response.locals.__("funkwhale.listenings"),
+          error: { message: response.locals.__("funkwhale.error.connection") },
+        });
+      }
+    } catch (error) {
+      console.error("[Funkwhale] Listenings error:", error);
+      next(error);
+    }
+  },
+
+  /**
+   * JSON API for listenings
+   * @type {import("express").RequestHandler}
+   */
+  async api(request, response, next) {
+    try {
+      const { funkwhaleConfig } = request.app.locals.application;
+
+      if (!funkwhaleConfig) {
+        return response.status(500).json({ error: "Not configured" });
+      }
+
+      const { instanceUrl, token, username, cacheTtl, limits } = funkwhaleConfig;
+      const page = parseInt(request.query.page) || 1;
+      const limit = Math.min(
+        parseInt(request.query.limit) || limits.listenings || 20,
+        100
+      );
+
+      const client = new FunkwhaleClient({
+        instanceUrl,
+        token,
+        username,
+        cacheTtl,
+      });
+
+      const listeningsRes = await client.getListenings(page, limit);
+      const listenings = listeningsRes.results.map((l) =>
+        utils.formatListening(l)
+      );
+
+      response.json({
+        listenings,
+        total: listeningsRes.count,
+        page,
+        hasNext: listeningsRes.next !== null,
+        hasPrev: listeningsRes.previous !== null,
+      });
+    } catch (error) {
+      console.error("[Funkwhale] Listenings API error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};

package/lib/controllers/now-playing.js

@@ -0,0 +1,58 @@
+import { FunkwhaleClient } from "../funkwhale-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 { funkwhaleConfig } = request.app.locals.application;
+
+      if (!funkwhaleConfig) {
+        return response.status(500).json({ error: "Not configured" });
+      }
+
+      const { instanceUrl, token, username, cacheTtl } = funkwhaleConfig;
+
+      const client = new FunkwhaleClient({
+        instanceUrl,
+        token,
+        username,
+        cacheTtl: Math.min(cacheTtl, 60_000), // Max 1 minute cache for now playing
+      });
+
+      const listening = await client.getLatestListening();
+
+      if (!listening) {
+        return response.json({
+          playing: false,
+          status: null,
+          message: "No recent plays",
+        });
+      }
+
+      const formatted = utils.formatListening(listening);
+
+      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,
+        duration: formatted.duration,
+        listenedAt: formatted.listenedAt,
+        relativeTime: formatted.relativeTime,
+      });
+    } catch (error) {
+      console.error("[Funkwhale] Now Playing API error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};

package/lib/controllers/stats.js

@@ -0,0 +1,138 @@
+import { getAllStats, getListeningTrends } from "../stats.js";
+import { formatTotalTime } from "../utils.js";
+
+/**
+ * Stats controller
+ */
+export const statsController = {
+  /**
+   * Render stats page with tabs
+   * @type {import("express").RequestHandler}
+   */
+  async get(request, response, next) {
+    try {
+      const { funkwhaleConfig } = request.app.locals.application;
+
+      if (!funkwhaleConfig) {
+        return response.status(500).render("stats", {
+          title: "Statistics",
+          error: { message: "Funkwhale endpoint not configured" },
+        });
+      }
+
+      const db = request.app.locals.database;
+      if (!db) {
+        return response.render("stats", {
+          title: response.locals.__("funkwhale.stats"),
+          error: { message: "Database not available for statistics" },
+          mountPath: request.baseUrl,
+        });
+      }
+
+      try {
+        const stats = await getAllStats(db, funkwhaleConfig.limits);
+
+        // Format durations for display
+        const formattedStats = {
+          summary: {
+            all: {
+              ...stats.summary.all,
+              totalDurationFormatted: formatTotalTime(stats.summary.all.totalDuration),
+            },
+            month: {
+              ...stats.summary.month,
+              totalDurationFormatted: formatTotalTime(stats.summary.month.totalDuration),
+            },
+            week: {
+              ...stats.summary.week,
+              totalDurationFormatted: formatTotalTime(stats.summary.week.totalDuration),
+            },
+          },
+          topArtists: stats.topArtists,
+          topAlbums: stats.topAlbums,
+          trends: stats.trends,
+        };
+
+        response.render("stats", {
+          title: response.locals.__("funkwhale.stats"),
+          stats: formattedStats,
+          mountPath: request.baseUrl,
+        });
+      } catch (dbError) {
+        console.error("[Funkwhale] Stats DB error:", dbError.message);
+        return response.render("stats", {
+          title: response.locals.__("funkwhale.stats"),
+          error: { message: "Could not load statistics" },
+          mountPath: request.baseUrl,
+        });
+      }
+    } catch (error) {
+      console.error("[Funkwhale] Stats error:", error);
+      next(error);
+    }
+  },
+
+  /**
+   * JSON API for all stats
+   * @type {import("express").RequestHandler}
+   */
+  async api(request, response, next) {
+    try {
+      const { funkwhaleConfig } = request.app.locals.application;
+
+      if (!funkwhaleConfig) {
+        return response.status(500).json({ error: "Not configured" });
+      }
+
+      const db = request.app.locals.database;
+      if (!db) {
+        return response.status(500).json({ error: "Database not available" });
+      }
+
+      const stats = await getAllStats(db, funkwhaleConfig.limits);
+
+      // Add formatted durations
+      stats.summary.all.totalDurationFormatted = formatTotalTime(
+        stats.summary.all.totalDuration
+      );
+      stats.summary.month.totalDurationFormatted = formatTotalTime(
+        stats.summary.month.totalDuration
+      );
+      stats.summary.week.totalDurationFormatted = formatTotalTime(
+        stats.summary.week.totalDuration
+      );
+
+      response.json(stats);
+    } catch (error) {
+      console.error("[Funkwhale] 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 { funkwhaleConfig } = request.app.locals.application;
+
+      if (!funkwhaleConfig) {
+        return response.status(500).json({ error: "Not configured" });
+      }
+
+      const db = request.app.locals.database;
+      if (!db) {
+        return response.status(500).json({ error: "Database not available" });
+      }
+
+      const days = Math.min(parseInt(request.query.days) || 30, 90);
+      const trends = await getListeningTrends(db, days);
+
+      response.json({ trends, days });
+    } catch (error) {
+      console.error("[Funkwhale] Trends API error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};