@rmdes/indiekit-endpoint-funkwhale 1.0.0

package/lib/funkwhale-client.js

@@ -0,0 +1,187 @@
+import { IndiekitError } from "@indiekit/error";
+
+export class FunkwhaleClient {
+  /**
+   * @param {object} options - Client options
+   * @param {string} options.instanceUrl - Funkwhale instance URL
+   * @param {string} options.token - API access token
+   * @param {string} options.username - Username to filter by
+   * @param {number} [options.cacheTtl] - Cache TTL in milliseconds
+   */
+  constructor(options = {}) {
+    this.instanceUrl = options.instanceUrl?.replace(/\/$/, ""); // Remove trailing slash
+    this.token = options.token;
+    this.username = options.username;
+    this.cacheTtl = options.cacheTtl || 900_000;
+    this.cache = new Map();
+  }
+
+  /**
+   * Fetch from Funkwhale API with caching
+   * @param {string} endpoint - API endpoint path
+   * @param {object} [params] - Query parameters
+   * @returns {Promise<object>} - Response data
+   */
+  async fetch(endpoint, params = {}) {
+    const url = new URL(endpoint, this.instanceUrl);
+    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 headers = {
+      Accept: "application/json",
+    };
+
+    if (this.token) {
+      headers.Authorization = `Bearer ${this.token}`;
+    }
+
+    const response = await fetch(url.toString(), { headers });
+
+    if (!response.ok) {
+      throw await IndiekitError.fromFetch(response);
+    }
+
+    const data = await response.json();
+
+    // Cache result
+    this.cache.set(cacheKey, { data, timestamp: Date.now() });
+
+    return data;
+  }
+
+  /**
+   * Get listening history
+   * @param {number} [page] - Page number
+   * @param {number} [pageSize] - Items per page
+   * @returns {Promise<object>} - Paginated listenings
+   */
+  async getListenings(page = 1, pageSize = 50) {
+    return this.fetch("/api/v2/history/listenings", {
+      page,
+      page_size: pageSize,
+      scope: "all",
+    });
+  }
+
+  /**
+   * Get all listenings by paginating through all pages
+   * @returns {Promise<Array>} - All listenings
+   */
+  async getAllListenings() {
+    const allListenings = [];
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore) {
+      const response = await this.getListenings(page, 100);
+      allListenings.push(...response.results);
+      hasMore = response.next !== null;
+      page++;
+    }
+
+    return allListenings;
+  }
+
+  /**
+   * Get new listenings since a given date
+   * Used for incremental sync
+   * @param {Date} since - Only fetch listenings after this date
+   * @returns {Promise<Array>} - New listenings
+   */
+  async getNewListenings(since) {
+    const newListenings = [];
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore) {
+      const response = await this.getListenings(page, 100);
+
+      for (const listening of response.results) {
+        const listenedAt = new Date(listening.creation_date);
+        if (listenedAt > since) {
+          newListenings.push(listening);
+        } else {
+          // We've reached older listenings, stop
+          hasMore = false;
+          break;
+        }
+      }
+
+      if (hasMore && response.next !== null) {
+        page++;
+      } else {
+        hasMore = false;
+      }
+    }
+
+    return newListenings;
+  }
+
+  /**
+   * Get favorite tracks
+   * @param {number} [page] - Page number
+   * @param {number} [pageSize] - Items per page
+   * @returns {Promise<object>} - Paginated favorites filtered to username
+   */
+  async getFavorites(page = 1, pageSize = 50) {
+    const response = await this.fetch("/api/v2/favorites/tracks", {
+      page,
+      page_size: pageSize,
+    });
+
+    // Filter to configured username only
+    if (this.username) {
+      response.results = response.results.filter(
+        (fav) => fav.actor?.preferred_username === this.username
+      );
+    }
+
+    return response;
+  }
+
+  /**
+   * Get all favorites for the configured user
+   * @returns {Promise<Array>} - All favorites
+   */
+  async getAllFavorites() {
+    const allFavorites = [];
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore) {
+      const response = await this.getFavorites(page, 100);
+      allFavorites.push(...response.results);
+      hasMore = response.next !== null && response.results.length > 0;
+      page++;
+    }
+
+    return allFavorites;
+  }
+
+  /**
+   * Get the most recent listening
+   * @returns {Promise<object|null>} - Most recent listening or null
+   */
+  async getLatestListening() {
+    const response = await this.getListenings(1, 1);
+    return response.results?.[0] || null;
+  }
+
+  /**
+   * Clear the cache
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+}

package/lib/stats.js

@@ -0,0 +1,228 @@
+/**
+ * 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 { listenedAt: { $gte: new Date(now - 7 * 24 * 60 * 60 * 1000) } };
+    case "month":
+      return { listenedAt: { $gte: new Date(now - 30 * 24 * 60 * 60 * 1000) } };
+    default:
+      return {};
+  }
+}
+
+/**
+ * Get top artists for a time period
+ * @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 getTopArtists(db, period = "all", limit = 10) {
+  const match = getDateMatch(period);
+  const collection = db.collection("listenings");
+
+  return collection
+    .aggregate([
+      { $match: match },
+      {
+        $group: {
+          _id: "$artistId",
+          name: { $first: "$artistName" },
+          playCount: { $sum: 1 },
+          totalDuration: { $sum: "$duration" },
+        },
+      },
+      { $match: { _id: { $ne: null } } },
+      { $sort: { playCount: -1 } },
+      { $limit: limit },
+    ])
+    .toArray();
+}
+
+/**
+ * Get top albums for a time period
+ * @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 getTopAlbums(db, period = "all", limit = 10) {
+  const match = getDateMatch(period);
+  const collection = db.collection("listenings");
+
+  return collection
+    .aggregate([
+      { $match: { ...match, albumId: { $ne: null } } },
+      {
+        $group: {
+          _id: "$albumId",
+          title: { $first: "$albumTitle" },
+          artist: { $first: "$artistName" },
+          coverUrl: { $first: "$coverUrl" },
+          playCount: { $sum: 1 },
+          totalDuration: { $sum: "$duration" },
+        },
+      },
+      { $sort: { playCount: -1 } },
+      { $limit: limit },
+    ])
+    .toArray();
+}
+
+/**
+ * Get listening trends (daily counts)
+ * @param {object} db - MongoDB database
+ * @param {number} days - Number of days to look back
+ * @returns {Promise<Array>} - Daily listening counts
+ */
+export async function getListeningTrends(db, days = 30) {
+  const startDate = new Date();
+  startDate.setDate(startDate.getDate() - days);
+  startDate.setHours(0, 0, 0, 0);
+
+  const collection = db.collection("listenings");
+
+  return collection
+    .aggregate([
+      { $match: { listenedAt: { $gte: startDate } } },
+      {
+        $group: {
+          _id: {
+            $dateToString: { format: "%Y-%m-%d", date: "$listenedAt" },
+          },
+          count: { $sum: 1 },
+          duration: { $sum: "$duration" },
+        },
+      },
+      { $sort: { _id: 1 } },
+      {
+        $project: {
+          _id: 0,
+          date: "$_id",
+          count: 1,
+          duration: 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("listenings");
+
+  const result = await collection
+    .aggregate([
+      { $match: match },
+      {
+        $group: {
+          _id: null,
+          totalPlays: { $sum: 1 },
+          totalDuration: { $sum: "$duration" },
+          uniqueTracks: { $addToSet: "$trackId" },
+          uniqueArtists: { $addToSet: "$artistId" },
+          uniqueAlbums: { $addToSet: "$albumId" },
+        },
+      },
+      {
+        $project: {
+          _id: 0,
+          totalPlays: 1,
+          totalDuration: 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,
+      totalDuration: 0,
+      uniqueTracks: 0,
+      uniqueArtists: 0,
+      uniqueAlbums: 0,
+    }
+  );
+}
+
+/**
+ * Get all stats for all time periods
+ * @param {object} db - MongoDB database
+ * @param {object} limits - Limits for top lists
+ * @returns {Promise<object>} - All stats
+ */
+export async function getAllStats(db, limits = {}) {
+  const topArtistsLimit = limits.topArtists || 10;
+  const topAlbumsLimit = limits.topAlbums || 10;
+
+  const [
+    summaryAll,
+    summaryMonth,
+    summaryWeek,
+    topArtistsAll,
+    topArtistsMonth,
+    topArtistsWeek,
+    topAlbumsAll,
+    topAlbumsMonth,
+    topAlbumsWeek,
+    trends,
+  ] = await Promise.all([
+    getSummary(db, "all"),
+    getSummary(db, "month"),
+    getSummary(db, "week"),
+    getTopArtists(db, "all", topArtistsLimit),
+    getTopArtists(db, "month", topArtistsLimit),
+    getTopArtists(db, "week", topArtistsLimit),
+    getTopAlbums(db, "all", topAlbumsLimit),
+    getTopAlbums(db, "month", topAlbumsLimit),
+    getTopAlbums(db, "week", topAlbumsLimit),
+    getListeningTrends(db, 30),
+  ]);
+
+  return {
+    summary: {
+      all: summaryAll,
+      month: summaryMonth,
+      week: summaryWeek,
+    },
+    topArtists: {
+      all: topArtistsAll,
+      month: topArtistsMonth,
+      week: topArtistsWeek,
+    },
+    topAlbums: {
+      all: topAlbumsAll,
+      month: topAlbumsMonth,
+      week: topAlbumsWeek,
+    },
+    trends,
+  };
+}

package/lib/sync.js

@@ -0,0 +1,160 @@
+import { FunkwhaleClient } from "./funkwhale-client.js";
+import { getCoverUrl, getArtistName } from "./utils.js";
+
+let syncInterval = 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("[Funkwhale] Initial sync error:", err.message);
+    });
+  }, 5000);
+
+  // Schedule recurring sync
+  syncInterval = setInterval(() => {
+    runSync(Indiekit, options).catch((err) => {
+      console.error("[Funkwhale] Sync error:", err.message);
+    });
+  }, intervalMs);
+
+  console.log(
+    `[Funkwhale] Background sync started (interval: ${intervalMs / 1000}s)`
+  );
+}
+
+/**
+ * Stop background sync
+ */
+export function stopSync() {
+  if (syncInterval) {
+    clearInterval(syncInterval);
+    syncInterval = null;
+    console.log("[Funkwhale] 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("[Funkwhale] No database available, skipping sync");
+    return { synced: 0, error: "No database" };
+  }
+
+  const client = new FunkwhaleClient({
+    instanceUrl: options.instanceUrl,
+    token: options.token,
+    username: options.username,
+    cacheTtl: 60_000, // Short cache for sync
+  });
+
+  return syncListenings(db, client);
+}
+
+/**
+ * Sync listenings to MongoDB
+ * @param {object} db - MongoDB database instance
+ * @param {FunkwhaleClient} client - Funkwhale API client
+ * @returns {Promise<object>} - Sync result
+ */
+export async function syncListenings(db, client) {
+  const collection = db.collection("listenings");
+
+  // Create index on funkwhaleId for upsert operations
+  await collection.createIndex({ funkwhaleId: 1 }, { unique: true });
+  // Create index on listenedAt for time-based queries
+  await collection.createIndex({ listenedAt: -1 });
+  // Create indexes for aggregation
+  await collection.createIndex({ artistId: 1 });
+  await collection.createIndex({ albumId: 1 });
+
+  // Get the latest synced listening
+  const latest = await collection.findOne({}, { sort: { listenedAt: -1 } });
+  const latestDate = latest?.listenedAt || new Date(0);
+
+  console.log(
+    `[Funkwhale] Syncing listenings since: ${latestDate.toISOString()}`
+  );
+
+  // Fetch new listenings
+  let newListenings;
+  if (latestDate.getTime() === 0) {
+    // First sync: get all
+    console.log("[Funkwhale] First sync, fetching all listenings...");
+    newListenings = await client.getAllListenings();
+  } else {
+    // Incremental sync
+    newListenings = await client.getNewListenings(latestDate);
+  }
+
+  if (newListenings.length === 0) {
+    console.log("[Funkwhale] No new listenings to sync");
+    return { synced: 0 };
+  }
+
+  console.log(`[Funkwhale] Found ${newListenings.length} new listenings`);
+
+  // Transform to our schema
+  const docs = newListenings.map((l) => transformListening(l));
+
+  // Upsert each document (in case of duplicates)
+  let synced = 0;
+  for (const doc of docs) {
+    try {
+      await collection.updateOne(
+        { funkwhaleId: doc.funkwhaleId },
+        { $set: doc },
+        { upsert: true }
+      );
+      synced++;
+    } catch (err) {
+      // Ignore duplicate key errors
+      if (err.code !== 11000) {
+        console.error(`[Funkwhale] Error inserting listening:`, err.message);
+      }
+    }
+  }
+
+  console.log(`[Funkwhale] Synced ${synced} listenings`);
+  return { synced };
+}
+
+/**
+ * Transform Funkwhale listening to our schema
+ * @param {object} listening - Funkwhale listening object
+ * @returns {object} - Transformed document
+ */
+function transformListening(listening) {
+  const track = listening.track;
+  const artist = track.artist_credit?.[0]?.artist;
+  const album = track.album;
+  const upload = track.uploads?.[0];
+
+  return {
+    funkwhaleId: listening.id,
+    trackId: track.id,
+    trackTitle: track.title,
+    trackFid: track.fid,
+    artistName: artist?.name || getArtistName(track),
+    artistId: artist?.id || null,
+    albumTitle: album?.title || null,
+    albumId: album?.id || null,
+    coverUrl: getCoverUrl(track),
+    duration: upload?.duration || 0,
+    listenedAt: new Date(listening.creation_date),
+    syncedAt: new Date(),
+  };
+}