@rmdes/indiekit-endpoint-funkwhale 1.0.0

package/README.md

@@ -0,0 +1,116 @@
+# @rmdes/indiekit-endpoint-funkwhale
+
+Funkwhale listening activity endpoint for [Indiekit](https://getindiekit.com/).
+
+Display your Funkwhale listening history, favorite tracks, and listening statistics on your IndieWeb site.
+
+## Features
+
+- **Now Playing Widget** - Shows currently playing or recently played tracks
+- **Listening History** - Browse your listening history with album art
+- **Favorites** - Display your favorite tracks
+- **Statistics** - View listening stats with tabbed interface:
+  - All Time / This Month / This Week views
+  - Top Artists and Albums
+  - Listening trend charts
+- **Public JSON API** - For integration with static site generators like Eleventy
+
+## Installation
+
+```bash
+npm install @rmdes/indiekit-endpoint-funkwhale
+```
+
+## Configuration
+
+Add to your `indiekit.config.js`:
+
+```javascript
+export default {
+  plugins: [
+    "@rmdes/indiekit-endpoint-funkwhale",
+  ],
+
+  "@rmdes/indiekit-endpoint-funkwhale": {
+    mountPath: "/funkwhale",
+    instanceUrl: process.env.FUNKWHALE_INSTANCE,
+    username: process.env.FUNKWHALE_USERNAME,
+    token: process.env.FUNKWHALE_TOKEN,
+    cacheTtl: 900_000,  // 15 minutes
+    syncInterval: 300_000,  // 5 minutes
+    limits: {
+      listenings: 20,
+      favorites: 20,
+      topArtists: 10,
+      topAlbums: 10
+    }
+  },
+};
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `FUNKWHALE_INSTANCE` | Yes | Your Funkwhale instance URL (e.g., `https://funkwhale.example.com`) |
+| `FUNKWHALE_TOKEN` | Yes | API access token (Bearer token) |
+| `FUNKWHALE_USERNAME` | Yes | Your username on the Funkwhale instance |
+
+### Getting an API Token
+
+1. Log in to your Funkwhale instance
+2. Go to Settings > Applications
+3. Create a new application with read permissions
+4. Copy the access token
+
+## Routes
+
+### Protected Routes (require authentication)
+
+| Route | Description |
+|-------|-------------|
+| `GET /funkwhale/` | Dashboard with overview |
+| `GET /funkwhale/listenings` | Full listening history |
+| `GET /funkwhale/favorites` | Favorite tracks |
+| `GET /funkwhale/stats` | Statistics with tabs |
+
+### Public API Routes (JSON)
+
+| Route | Description |
+|-------|-------------|
+| `GET /funkwhale/api/now-playing` | Current/recent track |
+| `GET /funkwhale/api/listenings` | Recent listenings |
+| `GET /funkwhale/api/favorites` | Favorites list |
+| `GET /funkwhale/api/stats` | All statistics |
+| `GET /funkwhale/api/stats/trends` | Trend data for charts |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `mountPath` | `/funkwhale` | URL path for the endpoint |
+| `instanceUrl` | - | Funkwhale instance URL |
+| `token` | - | API access token |
+| `username` | - | User to track |
+| `cacheTtl` | `900000` | Cache TTL in ms (15 min) |
+| `syncInterval` | `300000` | Background sync interval in ms (5 min) |
+| `limits.listenings` | `20` | Listenings per page |
+| `limits.favorites` | `20` | Favorites per page |
+| `limits.topArtists` | `10` | Top artists to show |
+| `limits.topAlbums` | `10` | Top albums to show |
+
+## Now Playing Logic
+
+- **Now Playing**: Track listened to within the last 60 minutes
+- **Recently Played**: Track listened to within the last 24 hours
+- **Last Played**: Older tracks show timestamp only
+
+## Requirements
+
+- Indiekit >= 1.0.0-beta.25
+- MongoDB (for statistics aggregation)
+- Funkwhale instance with API v2
+
+## License
+
+MIT

package/assets/styles.css

@@ -0,0 +1,453 @@
+/* Funkwhale Endpoint Styles */
+
+/* Sections */
+.funkwhale-section {
+  margin-block-end: 2rem;
+}
+
+.funkwhale-section h2 {
+  margin-block-end: 1rem;
+}
+
+/* Now Playing Animation */
+.funkwhale-status {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.funkwhale-status--playing {
+  color: var(--color-accent, #22c55e);
+}
+
+.funkwhale-bars {
+  display: flex;
+  gap: 2px;
+  align-items: flex-end;
+  height: 16px;
+}
+
+.funkwhale-bars span {
+  width: 3px;
+  background: currentColor;
+  animation: funkwhale-bar 0.5s infinite ease-in-out alternate;
+}
+
+.funkwhale-bars span:nth-child(2) {
+  animation-delay: 0.2s;
+}
+
+.funkwhale-bars span:nth-child(3) {
+  animation-delay: 0.4s;
+}
+
+@keyframes funkwhale-bar {
+  from { height: 4px; }
+  to { height: 16px; }
+}
+
+/* Featured Track */
+.funkwhale-track--featured {
+  display: flex;
+  gap: 1rem;
+  padding: 1rem;
+  background: var(--color-offset, #f5f5f5);
+  border-radius: 0.5rem;
+}
+
+.funkwhale-track__cover {
+  width: 80px;
+  height: 80px;
+  object-fit: cover;
+  border-radius: 0.25rem;
+}
+
+.funkwhale-track__cover--placeholder {
+  background: var(--color-border, #ddd);
+}
+
+.funkwhale-track__info {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.funkwhale-track__title {
+  font-weight: 600;
+  text-decoration: none;
+  color: var(--color-text, inherit);
+}
+
+.funkwhale-track__title:hover {
+  text-decoration: underline;
+}
+
+.funkwhale-track__album {
+  margin: 0;
+  color: var(--color-text-muted, #666);
+  font-size: 0.875rem;
+}
+
+/* Stats Grid */
+.funkwhale-stats-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
+  gap: 1rem;
+  margin-block-end: 1rem;
+}
+
+.funkwhale-stat {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 1rem;
+  background: var(--color-offset, #f5f5f5);
+  border-radius: 0.5rem;
+  text-align: center;
+}
+
+.funkwhale-stat__value {
+  font-size: 1.5rem;
+  font-weight: 700;
+  color: var(--color-accent, #3b82f6);
+}
+
+.funkwhale-stat__label {
+  font-size: 0.75rem;
+  color: var(--color-text-muted, #666);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+/* List */
+.funkwhale-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.funkwhale-list__item {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 0.75rem 0;
+  border-bottom: 1px solid var(--color-border, #eee);
+}
+
+.funkwhale-list__item:last-child {
+  border-bottom: none;
+}
+
+.funkwhale-list__cover {
+  width: 48px;
+  height: 48px;
+  object-fit: cover;
+  border-radius: 0.25rem;
+  flex-shrink: 0;
+}
+
+.funkwhale-list__cover--placeholder {
+  background: var(--color-border, #ddd);
+}
+
+.funkwhale-list__info {
+  flex: 1;
+  min-width: 0;
+}
+
+.funkwhale-list__title {
+  display: block;
+  font-weight: 500;
+  text-decoration: none;
+  color: var(--color-text, inherit);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.funkwhale-list__title:hover {
+  text-decoration: underline;
+}
+
+.funkwhale-list__album {
+  margin: 0;
+  font-size: 0.875rem;
+  color: var(--color-text-muted, #666);
+}
+
+.funkwhale-meta {
+  display: flex;
+  gap: 0.5rem;
+  color: var(--color-text-muted, #666);
+  font-size: 0.75rem;
+}
+
+/* Pagination */
+.funkwhale-pagination {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 1rem;
+  margin-block: 1.5rem;
+}
+
+.funkwhale-pagination__info {
+  color: var(--color-text-muted, #666);
+}
+
+/* Tabs */
+.funkwhale-tabs {
+  display: flex;
+  gap: 0.25rem;
+  margin-block-end: 1.5rem;
+  border-bottom: 1px solid var(--color-border, #ddd);
+}
+
+.funkwhale-tab {
+  padding: 0.75rem 1rem;
+  border: none;
+  background: none;
+  color: var(--color-text-muted, #666);
+  cursor: pointer;
+  border-bottom: 2px solid transparent;
+  margin-bottom: -1px;
+  font-size: 0.875rem;
+  font-weight: 500;
+}
+
+.funkwhale-tab:hover {
+  color: var(--color-text, inherit);
+}
+
+.funkwhale-tab--active {
+  color: var(--color-accent, #3b82f6);
+  border-bottom-color: var(--color-accent, #3b82f6);
+}
+
+.funkwhale-tab-content {
+  display: none;
+}
+
+.funkwhale-tab-content--active {
+  display: block;
+}
+
+/* Top List */
+.funkwhale-top-list {
+  list-style: none;
+  padding: 0;
+  margin: 0 0 1.5rem 0;
+  counter-reset: rank;
+}
+
+.funkwhale-top-list__item {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 0.5rem 0;
+  border-bottom: 1px solid var(--color-border, #eee);
+}
+
+.funkwhale-top-list__rank {
+  width: 1.5rem;
+  height: 1.5rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.75rem;
+  font-weight: 600;
+  background: var(--color-offset, #f5f5f5);
+  border-radius: 50%;
+  color: var(--color-text-muted, #666);
+}
+
+.funkwhale-top-list__name {
+  flex: 1;
+  font-weight: 500;
+}
+
+.funkwhale-top-list__count {
+  font-size: 0.875rem;
+  color: var(--color-text-muted, #666);
+}
+
+/* Album Grid */
+.funkwhale-album-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+  gap: 1rem;
+  list-style: none;
+  padding: 0;
+  margin: 0 0 1.5rem 0;
+}
+
+.funkwhale-album {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.funkwhale-album__cover {
+  width: 100%;
+  aspect-ratio: 1;
+  object-fit: cover;
+  border-radius: 0.25rem;
+}
+
+.funkwhale-album__cover--placeholder {
+  background: var(--color-border, #ddd);
+}
+
+.funkwhale-album__info {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+}
+
+.funkwhale-album__title {
+  font-weight: 500;
+  font-size: 0.875rem;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.funkwhale-album__artist {
+  font-size: 0.75rem;
+  color: var(--color-text-muted, #666);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* Trend Chart */
+.funkwhale-chart {
+  margin: 1rem 0;
+}
+
+.funkwhale-chart__bars {
+  display: flex;
+  align-items: flex-end;
+  gap: 2px;
+  height: 120px;
+  padding: 0.5rem 0;
+}
+
+.funkwhale-chart__bar-wrapper {
+  flex: 1;
+  height: 100%;
+  display: flex;
+  align-items: flex-end;
+}
+
+.funkwhale-chart__bar {
+  width: 100%;
+  background: var(--color-accent, #3b82f6);
+  border-radius: 2px 2px 0 0;
+  min-height: 2px;
+  transition: height 0.3s ease;
+}
+
+.funkwhale-chart__bar-wrapper:hover .funkwhale-chart__bar {
+  background: var(--color-accent-hover, #2563eb);
+}
+
+.funkwhale-chart__labels {
+  display: flex;
+  justify-content: space-between;
+  font-size: 0.75rem;
+  color: var(--color-text-muted, #666);
+  margin-top: 0.5rem;
+}
+
+/* Widget Styles (for embeddable widgets) */
+.funkwhale-widget {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem;
+  background: var(--color-offset, #f5f5f5);
+  border-radius: 0.5rem;
+}
+
+.funkwhale-widget--playing {
+  background: linear-gradient(135deg, #22c55e10, #22c55e05);
+  border: 1px solid #22c55e30;
+}
+
+.funkwhale-widget__status {
+  font-size: 0.625rem;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--color-text-muted, #666);
+  width: 100%;
+}
+
+.funkwhale-widget--playing .funkwhale-widget__status {
+  color: #22c55e;
+}
+
+.funkwhale-widget__cover {
+  width: 48px;
+  height: 48px;
+  object-fit: cover;
+  border-radius: 0.25rem;
+}
+
+.funkwhale-widget__info {
+  flex: 1;
+  min-width: 0;
+}
+
+.funkwhale-widget__title {
+  display: block;
+  font-weight: 500;
+  font-size: 0.875rem;
+  text-decoration: none;
+  color: var(--color-text, inherit);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.funkwhale-widget__time {
+  font-size: 0.75rem;
+  color: var(--color-text-muted, #666);
+}
+
+.funkwhale-widget__empty,
+.funkwhale-widget__error {
+  font-size: 0.875rem;
+  color: var(--color-text-muted, #666);
+  margin: 0;
+}
+
+/* Stats Widget */
+.funkwhale-stats-widget__grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 0.5rem;
+}
+
+.funkwhale-stats-widget__stat {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 0.5rem;
+  background: var(--color-offset, #f5f5f5);
+  border-radius: 0.25rem;
+}
+
+.funkwhale-stats-widget__value {
+  font-size: 1.25rem;
+  font-weight: 700;
+  color: var(--color-accent, #3b82f6);
+}
+
+.funkwhale-stats-widget__label {
+  font-size: 0.625rem;
+  color: var(--color-text-muted, #666);
+  text-transform: uppercase;
+}

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

@@ -0,0 +1,83 @@
+{#
+  Now Playing Widget
+  Fetches data from /funkwhale/api/now-playing
+  Include this in your Eleventy templates
+#}
+<div class="funkwhale-now-playing-widget" id="funkwhale-now-playing">
+  <div class="funkwhale-now-playing-widget__loading">
+    Loading...
+  </div>
+</div>
+
+<script>
+(function() {
+  const container = document.getElementById('funkwhale-now-playing');
+  const endpoint = '{{ application.funkwhaleEndpoint or "/funkwhale" }}/api/now-playing';
+
+  fetch(endpoint)
+    .then(res => res.json())
+    .then(data => {
+      container.textContent = '';
+
+      if (!data.track) {
+        const empty = document.createElement('p');
+        empty.className = 'funkwhale-widget__empty';
+        empty.textContent = 'No recent plays';
+        container.appendChild(empty);
+        return;
+      }
+
+      const widget = document.createElement('div');
+      widget.className = 'funkwhale-widget' + (data.status === 'now-playing' ? ' funkwhale-widget--playing' : '');
+
+      if (data.status === 'now-playing') {
+        const bars = document.createElement('div');
+        bars.className = 'funkwhale-bars';
+        for (let i = 0; i < 3; i++) {
+          bars.appendChild(document.createElement('span'));
+        }
+        widget.appendChild(bars);
+      }
+
+      const status = document.createElement('span');
+      status.className = 'funkwhale-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 = 'funkwhale-widget__cover';
+        widget.appendChild(img);
+      }
+
+      const info = document.createElement('div');
+      info.className = 'funkwhale-widget__info';
+
+      const link = document.createElement('a');
+      link.href = data.trackUrl;
+      link.className = 'funkwhale-widget__title';
+      link.target = '_blank';
+      link.rel = 'noopener';
+      link.textContent = data.artist + ' - ' + data.track;
+      info.appendChild(link);
+
+      const time = document.createElement('span');
+      time.className = 'funkwhale-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 = 'funkwhale-widget__error';
+      error.textContent = 'Could not load';
+      container.appendChild(error);
+    });
+})();
+</script>

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

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