@rmdes/indiekit-endpoint-funkwhale 1.0.0

package/lib/utils.js

@@ -0,0 +1,242 @@
+/**
+ * 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 primary artist name from a track
+ * @param {object} track - Funkwhale track object
+ * @returns {string} - Artist name
+ */
+export function getArtistName(track) {
+  if (!track) return "Unknown Artist";
+
+  const credit = track.artist_credit?.[0];
+  if (credit?.artist?.name) {
+    return credit.artist.name;
+  }
+  if (credit?.credit) {
+    return credit.credit;
+  }
+
+  return "Unknown Artist";
+}
+
+/**
+ * Get the best available cover URL from a track
+ * Prefers medium square crop (200x200) for consistent display
+ * @param {object} track - Funkwhale track object
+ * @param {string} [size] - Size preference: 'small', 'medium', 'large', 'original'
+ * @returns {string|null} - Cover URL or null
+ */
+export function getCoverUrl(track, size = "medium") {
+  if (!track) return null;
+
+  const sizeKey = `${size}_square_crop`;
+
+  // Check track cover
+  if (track.cover?.urls) {
+    return track.cover.urls[sizeKey] || track.cover.urls.original || null;
+  }
+
+  // Check album cover
+  if (track.album?.cover?.urls) {
+    return track.album.cover.urls[sizeKey] || track.album.cover.urls.original || null;
+  }
+
+  // Check artist cover
+  const artist = track.artist_credit?.[0]?.artist;
+  if (artist?.cover?.urls) {
+    return artist.cover.urls[sizeKey] || artist.cover.urls.original || null;
+  }
+
+  return null;
+}
+
+/**
+ * Get the track URL (federation ID)
+ * @param {object} track - Funkwhale track object
+ * @returns {string|null} - Track URL or null
+ */
+export function getTrackUrl(track) {
+  return track?.fid || null;
+}
+
+/**
+ * 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} dateInput - ISO date string or Date object
+ * @param {string} [locale] - Locale for formatting
+ * @returns {string} - Formatted date
+ */
+export function formatDate(dateInput, locale = "en") {
+  const date = new Date(dateInput);
+  return date.toLocaleDateString(locale, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+/**
+ * Format relative time
+ * @param {string|Date} dateInput - ISO date string or Date object
+ * @returns {string} - Relative time string
+ */
+export function formatRelativeTime(dateInput) {
+  const date = new Date(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 when track was listened
+ * @param {string|Date} dateInput - When the track was listened
+ * @returns {string|null} - 'now-playing', 'recently-played', or null
+ */
+export function getPlayingStatus(dateInput) {
+  const date = new Date(dateInput);
+  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 listening entry for API response
+ * @param {object} listening - Funkwhale listening object or MongoDB document
+ * @param {boolean} [fromDb] - Whether the listening is from MongoDB
+ * @returns {object} - Formatted listening
+ */
+export function formatListening(listening, fromDb = false) {
+  if (fromDb) {
+    // From MongoDB
+    const listenedAt = listening.listenedAt;
+    return {
+      id: listening.funkwhaleId,
+      track: listening.trackTitle,
+      artist: listening.artistName,
+      album: listening.albumTitle,
+      coverUrl: listening.coverUrl,
+      trackUrl: listening.trackFid,
+      duration: formatDuration(listening.duration),
+      durationSeconds: listening.duration,
+      listenedAt: listenedAt.toISOString(),
+      relativeTime: formatRelativeTime(listenedAt),
+      status: getPlayingStatus(listenedAt),
+    };
+  }
+
+  // From API
+  const track = listening.track;
+  const listenedAt = listening.creation_date;
+
+  return {
+    id: listening.id,
+    track: track.title,
+    artist: getArtistName(track),
+    album: track.album?.title || null,
+    coverUrl: getCoverUrl(track),
+    trackUrl: getTrackUrl(track),
+    duration: formatDuration(track.uploads?.[0]?.duration),
+    durationSeconds: track.uploads?.[0]?.duration || 0,
+    listenedAt,
+    relativeTime: formatRelativeTime(listenedAt),
+    status: getPlayingStatus(listenedAt),
+  };
+}
+
+/**
+ * Format a favorite entry for API response
+ * @param {object} favorite - Funkwhale favorite object
+ * @returns {object} - Formatted favorite
+ */
+export function formatFavorite(favorite) {
+  const track = favorite.track;
+
+  return {
+    id: favorite.id,
+    track: track.title,
+    artist: getArtistName(track),
+    album: track.album?.title || null,
+    coverUrl: getCoverUrl(track),
+    trackUrl: getTrackUrl(track),
+    duration: formatDuration(track.uploads?.[0]?.duration),
+    durationSeconds: track.uploads?.[0]?.duration || 0,
+    favoritedAt: favorite.creation_date,
+    relativeTime: formatRelativeTime(favorite.creation_date),
+  };
+}

package/locales/en.json

@@ -0,0 +1,29 @@
+{
+  "funkwhale.title": "Funkwhale",
+  "funkwhale.listenings": "Listening History",
+  "funkwhale.favorites": "Favorites",
+  "funkwhale.stats": "Statistics",
+  "funkwhale.nowPlaying": "Now Playing",
+  "funkwhale.recentlyPlayed": "Recently Played",
+  "funkwhale.lastPlayed": "Last Played",
+  "funkwhale.allTime": "All Time",
+  "funkwhale.thisWeek": "This Week",
+  "funkwhale.thisMonth": "This Month",
+  "funkwhale.trends": "Trends",
+  "funkwhale.listeningTrend": "Listening Trend (30 days)",
+  "funkwhale.topArtists": "Top Artists",
+  "funkwhale.topAlbums": "Top Albums",
+  "funkwhale.plays": "plays",
+  "funkwhale.tracks": "tracks",
+  "funkwhale.artists": "artists",
+  "funkwhale.albums": "albums",
+  "funkwhale.listeningTime": "Listening Time",
+  "funkwhale.noRecentPlays": "No music played recently",
+  "funkwhale.noFavorites": "No favorite tracks yet",
+  "funkwhale.viewAll": "View All",
+  "funkwhale.viewStats": "View Statistics",
+  "funkwhale.error.connection": "Could not connect to Funkwhale",
+  "funkwhale.error.noConfig": "Funkwhale endpoint not configured correctly",
+  "funkwhale.widget.description": "View your Funkwhale listening activity",
+  "funkwhale.widget.view": "View Activity"
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@rmdes/indiekit-endpoint-funkwhale",
+  "version": "1.0.0",
+  "description": "Funkwhale listening activity endpoint for Indiekit. Display listening history, favorites, and statistics.",
+  "keywords": [
+    "indiekit",
+    "indiekit-plugin",
+    "indieweb",
+    "funkwhale",
+    "music",
+    "scrobble",
+    "listening",
+    "activity"
+  ],
+  "homepage": "https://github.com/rmdes/indiekit-endpoint-funkwhale",
+  "bugs": {
+    "url": "https://github.com/rmdes/indiekit-endpoint-funkwhale/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rmdes/indiekit-endpoint-funkwhale.git"
+  },
+  "author": {
+    "name": "Ricardo Mendes",
+    "url": "https://rmendes.net"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "assets",
+    "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"
+  }
+}

package/views/favorites.njk

@@ -0,0 +1,60 @@
+{% extends "document.njk" %}
+
+{% block content %}
+  {% if error %}
+    {{ prose({ text: error.message }) }}
+  {% else %}
+    <section class="funkwhale-section">
+      {% if favorites and favorites.length > 0 %}
+      <ul class="funkwhale-list funkwhale-list--full">
+        {% for favorite in favorites %}
+        <li class="funkwhale-list__item">
+          {% if favorite.coverUrl %}
+          <img src="{{ favorite.coverUrl }}" alt="" class="funkwhale-list__cover" loading="lazy">
+          {% else %}
+          <div class="funkwhale-list__cover funkwhale-list__cover--placeholder"></div>
+          {% endif %}
+          <div class="funkwhale-list__info">
+            <a href="{{ favorite.trackUrl }}" class="funkwhale-list__title" target="_blank" rel="noopener">
+              {{ favorite.artist }} - {{ favorite.track }}
+            </a>
+            {% if favorite.album %}
+            <p class="funkwhale-list__album">{{ favorite.album }}</p>
+            {% endif %}
+            <small class="funkwhale-meta">
+              <span>{{ favorite.duration }}</span>
+              <span>Favorited {{ favorite.relativeTime }}</span>
+            </small>
+          </div>
+        </li>
+        {% endfor %}
+      </ul>
+
+      {# Pagination #}
+      {% if pagination %}
+      <nav class="funkwhale-pagination">
+        {% if pagination.hasPrev %}
+        <a href="?page={{ pagination.current - 1 }}" class="button button--secondary">Previous</a>
+        {% endif %}
+        <span class="funkwhale-pagination__info">
+          Page {{ pagination.current }} of {{ pagination.total }}
+        </span>
+        {% if pagination.hasNext %}
+        <a href="?page={{ pagination.current + 1 }}" class="button button--secondary">Next</a>
+        {% endif %}
+      </nav>
+      {% endif %}
+      {% else %}
+      {{ prose({ text: __("funkwhale.noFavorites") }) }}
+      {% endif %}
+    </section>
+
+    <div class="button-grid">
+      {{ button({
+        classes: "button--secondary",
+        href: mountPath,
+        text: "Back to Dashboard"
+      }) }}
+    </div>
+  {% endif %}
+{% endblock %}

package/views/funkwhale.njk

@@ -0,0 +1,145 @@
+{% extends "document.njk" %}
+
+{% block content %}
+  {% if error %}
+    {{ prose({ text: error.message }) }}
+  {% else %}
+    {# Now Playing / Recently Played #}
+    {% if nowPlaying %}
+    <section class="funkwhale-section funkwhale-now-playing">
+      <h2>
+        {% if nowPlaying.status == "now-playing" %}
+          <span class="funkwhale-status funkwhale-status--playing">
+            <span class="funkwhale-bars">
+              <span></span><span></span><span></span>
+            </span>
+            {{ __("funkwhale.nowPlaying") }}
+          </span>
+        {% else %}
+          {{ __("funkwhale.recentlyPlayed") }}
+        {% endif %}
+      </h2>
+      <article class="funkwhale-track funkwhale-track--featured">
+        {% if nowPlaying.coverUrl %}
+        <img src="{{ nowPlaying.coverUrl }}" alt="" class="funkwhale-track__cover" loading="lazy">
+        {% else %}
+        <div class="funkwhale-track__cover funkwhale-track__cover--placeholder"></div>
+        {% endif %}
+        <div class="funkwhale-track__info">
+          <a href="{{ nowPlaying.trackUrl }}" class="funkwhale-track__title" target="_blank" rel="noopener">
+            {{ nowPlaying.artist }} - {{ nowPlaying.track }}
+          </a>
+          {% if nowPlaying.album %}
+          <p class="funkwhale-track__album">{{ nowPlaying.album }}</p>
+          {% endif %}
+          <small class="funkwhale-meta">
+            <span>{{ nowPlaying.duration }}</span>
+            <span>{{ nowPlaying.relativeTime }}</span>
+          </small>
+        </div>
+      </article>
+    </section>
+    {% endif %}
+
+    {# Quick Stats Summary #}
+    {% if summary %}
+    <section class="funkwhale-section funkwhale-summary">
+      <h2>{{ __("funkwhale.stats") }}</h2>
+      <div class="funkwhale-stats-grid">
+        <div class="funkwhale-stat">
+          <span class="funkwhale-stat__value">{{ summary.totalPlays }}</span>
+          <span class="funkwhale-stat__label">{{ __("funkwhale.plays") }}</span>
+        </div>
+        <div class="funkwhale-stat">
+          <span class="funkwhale-stat__value">{{ summary.uniqueTracks }}</span>
+          <span class="funkwhale-stat__label">{{ __("funkwhale.tracks") }}</span>
+        </div>
+        <div class="funkwhale-stat">
+          <span class="funkwhale-stat__value">{{ summary.uniqueArtists }}</span>
+          <span class="funkwhale-stat__label">{{ __("funkwhale.artists") }}</span>
+        </div>
+      </div>
+      <div class="button-grid">
+        {{ button({
+          classes: "button--secondary",
+          href: mountPath + "/stats",
+          text: __("funkwhale.viewStats")
+        }) }}
+      </div>
+    </section>
+    {% endif %}
+
+    {# Recent Listenings #}
+    <section class="funkwhale-section">
+      <h2>{{ __("funkwhale.listenings") }}</h2>
+      {% if listenings and listenings.length > 0 %}
+      <ul class="funkwhale-list">
+        {% for listening in listenings %}
+        <li class="funkwhale-list__item">
+          {% if listening.coverUrl %}
+          <img src="{{ listening.coverUrl }}" alt="" class="funkwhale-list__cover" loading="lazy">
+          {% else %}
+          <div class="funkwhale-list__cover funkwhale-list__cover--placeholder"></div>
+          {% endif %}
+          <div class="funkwhale-list__info">
+            <a href="{{ listening.trackUrl }}" class="funkwhale-list__title" target="_blank" rel="noopener">
+              {{ listening.artist }} - {{ listening.track }}
+            </a>
+            <small class="funkwhale-meta">{{ listening.relativeTime }}</small>
+          </div>
+          {% if listening.status == "now-playing" %}
+          {{ badge({ color: "green", text: __("funkwhale.nowPlaying") }) }}
+          {% elif listening.status == "recently-played" %}
+          {{ badge({ color: "blue", text: __("funkwhale.recentlyPlayed") }) }}
+          {% endif %}
+        </li>
+        {% endfor %}
+      </ul>
+      <div class="button-grid">
+        {{ button({
+          classes: "button--secondary",
+          href: mountPath + "/listenings",
+          text: __("funkwhale.viewAll")
+        }) }}
+      </div>
+      {% else %}
+      {{ prose({ text: __("funkwhale.noRecentPlays") }) }}
+      {% endif %}
+    </section>
+
+    {# Favorites #}
+    <section class="funkwhale-section">
+      <h2>{{ __("funkwhale.favorites") }}</h2>
+      {% if favorites and favorites.length > 0 %}
+      <ul class="funkwhale-list">
+        {% for favorite in favorites %}
+        <li class="funkwhale-list__item">
+          {% if favorite.coverUrl %}
+          <img src="{{ favorite.coverUrl }}" alt="" class="funkwhale-list__cover" loading="lazy">
+          {% else %}
+          <div class="funkwhale-list__cover funkwhale-list__cover--placeholder"></div>
+          {% endif %}
+          <div class="funkwhale-list__info">
+            <a href="{{ favorite.trackUrl }}" class="funkwhale-list__title" target="_blank" rel="noopener">
+              {{ favorite.artist }} - {{ favorite.track }}
+            </a>
+            {% if favorite.album %}
+            <small class="funkwhale-meta">{{ favorite.album }}</small>
+            {% endif %}
+          </div>
+        </li>
+        {% endfor %}
+      </ul>
+      <div class="button-grid">
+        {{ button({
+          classes: "button--secondary",
+          href: mountPath + "/favorites",
+          text: __("funkwhale.viewAll")
+        }) }}
+      </div>
+      {% else %}
+      {{ prose({ text: __("funkwhale.noFavorites") }) }}
+      {% endif %}
+    </section>
+  {% endif %}
+{% endblock %}

package/views/listenings.njk

@@ -0,0 +1,65 @@
+{% extends "document.njk" %}
+
+{% block content %}
+  {% if error %}
+    {{ prose({ text: error.message }) }}
+  {% else %}
+    <section class="funkwhale-section">
+      {% if listenings and listenings.length > 0 %}
+      <ul class="funkwhale-list funkwhale-list--full">
+        {% for listening in listenings %}
+        <li class="funkwhale-list__item">
+          {% if listening.coverUrl %}
+          <img src="{{ listening.coverUrl }}" alt="" class="funkwhale-list__cover" loading="lazy">
+          {% else %}
+          <div class="funkwhale-list__cover funkwhale-list__cover--placeholder"></div>
+          {% endif %}
+          <div class="funkwhale-list__info">
+            <a href="{{ listening.trackUrl }}" class="funkwhale-list__title" target="_blank" rel="noopener">
+              {{ listening.artist }} - {{ listening.track }}
+            </a>
+            {% if listening.album %}
+            <p class="funkwhale-list__album">{{ listening.album }}</p>
+            {% endif %}
+            <small class="funkwhale-meta">
+              <span>{{ listening.duration }}</span>
+              <span>{{ listening.relativeTime }}</span>
+            </small>
+          </div>
+          {% if listening.status == "now-playing" %}
+          {{ badge({ color: "green", text: __("funkwhale.nowPlaying") }) }}
+          {% elif listening.status == "recently-played" %}
+          {{ badge({ color: "blue", text: __("funkwhale.recentlyPlayed") }) }}
+          {% endif %}
+        </li>
+        {% endfor %}
+      </ul>
+
+      {# Pagination #}
+      {% if pagination %}
+      <nav class="funkwhale-pagination">
+        {% if pagination.hasPrev %}
+        <a href="?page={{ pagination.current - 1 }}" class="button button--secondary">Previous</a>
+        {% endif %}
+        <span class="funkwhale-pagination__info">
+          Page {{ pagination.current }} of {{ pagination.total }}
+        </span>
+        {% if pagination.hasNext %}
+        <a href="?page={{ pagination.current + 1 }}" class="button button--secondary">Next</a>
+        {% endif %}
+      </nav>
+      {% endif %}
+      {% else %}
+      {{ prose({ text: __("funkwhale.noRecentPlays") }) }}
+      {% endif %}
+    </section>
+
+    <div class="button-grid">
+      {{ button({
+        classes: "button--secondary",
+        href: mountPath,
+        text: "Back to Dashboard"
+      }) }}
+    </div>
+  {% endif %}
+{% endblock %}

package/views/partials/stats-summary.njk

@@ -0,0 +1,18 @@
+<div class="funkwhale-stats-grid">
+  <div class="funkwhale-stat">
+    <span class="funkwhale-stat__value">{{ summary.totalPlays }}</span>
+    <span class="funkwhale-stat__label">{{ __("funkwhale.plays") }}</span>
+  </div>
+  <div class="funkwhale-stat">
+    <span class="funkwhale-stat__value">{{ summary.uniqueTracks }}</span>
+    <span class="funkwhale-stat__label">{{ __("funkwhale.tracks") }}</span>
+  </div>
+  <div class="funkwhale-stat">
+    <span class="funkwhale-stat__value">{{ summary.uniqueArtists }}</span>
+    <span class="funkwhale-stat__label">{{ __("funkwhale.artists") }}</span>
+  </div>
+  <div class="funkwhale-stat">
+    <span class="funkwhale-stat__value">{{ summary.totalDurationFormatted }}</span>
+    <span class="funkwhale-stat__label">{{ __("funkwhale.listeningTime") }}</span>
+  </div>
+</div>

package/views/partials/top-albums.njk

@@ -0,0 +1,20 @@
+{% if topAlbums and topAlbums.length > 0 %}
+<ul class="funkwhale-album-grid">
+  {% for album in topAlbums %}
+  <li class="funkwhale-album">
+    {% if album.coverUrl %}
+    <img src="{{ album.coverUrl }}" alt="" class="funkwhale-album__cover" loading="lazy">
+    {% else %}
+    <div class="funkwhale-album__cover funkwhale-album__cover--placeholder"></div>
+    {% endif %}
+    <div class="funkwhale-album__info">
+      <span class="funkwhale-album__title">{{ album.title }}</span>
+      <span class="funkwhale-album__artist">{{ album.artist }}</span>
+      <small class="funkwhale-meta">{{ album.playCount }} {{ __("funkwhale.plays") }}</small>
+    </div>
+  </li>
+  {% endfor %}
+</ul>
+{% else %}
+{{ prose({ text: "No data yet" }) }}
+{% endif %}

package/views/partials/top-artists.njk

@@ -0,0 +1,13 @@
+{% if topArtists and topArtists.length > 0 %}
+<ol class="funkwhale-top-list">
+  {% for artist in topArtists %}
+  <li class="funkwhale-top-list__item">
+    <span class="funkwhale-top-list__rank">{{ loop.index }}</span>
+    <span class="funkwhale-top-list__name">{{ artist.name }}</span>
+    <span class="funkwhale-top-list__count">{{ artist.playCount }} {{ __("funkwhale.plays") }}</span>
+  </li>
+  {% endfor %}
+</ol>
+{% else %}
+{{ prose({ text: "No data yet" }) }}
+{% endif %}