@rmdes/indiekit-endpoint-podroll 1.0.0

package/README.md

@@ -0,0 +1,122 @@
+# @rmdes/indiekit-endpoint-podroll
+
+Podcast roll endpoint for Indiekit. Aggregates podcast episodes from a FreshRSS instance and provides JSON APIs for displaying a podroll page with episode listings and OPML sidebar.
+
+## Features
+
+- Syncs podcast episodes from FreshRSS greader API
+- Syncs podcast sources from OPML export
+- Caches data in MongoDB for fast API responses
+- Background sync at configurable intervals
+- Public JSON APIs for frontend consumption
+- Admin dashboard for manual sync and status
+
+## Installation
+
+```bash
+npm install @rmdes/indiekit-endpoint-podroll
+```
+
+## Configuration
+
+Add to your Indiekit config:
+
+```javascript
+import PodrollEndpoint from "@rmdes/indiekit-endpoint-podroll";
+
+export default {
+  plugins: [
+    new PodrollEndpoint({
+      episodesUrl: "https://your-freshrss.example/api/query.php?user=USER&t=TOKEN&f=greader",
+      opmlUrl: "https://your-freshrss.example/api/query.php?user=USER&t=TOKEN&f=opml",
+      syncInterval: 900000, // 15 minutes (default)
+      maxEpisodes: 100,     // Maximum episodes to cache (default)
+    }),
+  ],
+};
+```
+
+## API Endpoints
+
+### Public (no auth required)
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /podrollapi/api/episodes` | List episodes. Params: `limit`, `offset`, `source` |
+| `GET /podrollapi/api/episodes/:id` | Get single episode |
+| `GET /podrollapi/api/sources` | List podcast sources from OPML. Params: `category` |
+| `GET /podrollapi/api/status` | Sync status and counts |
+
+### Protected (requires auth)
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /podrollapi/` | Admin dashboard |
+| `POST /podrollapi/sync` | Trigger manual sync |
+| `POST /podrollapi/clear-resync` | Clear cache and re-sync |
+
+## Episode Response Schema
+
+```json
+{
+  "items": [
+    {
+      "id": "unique-episode-id",
+      "title": "Episode Title",
+      "url": "https://podcast.example/episode",
+      "published": "2026-01-31T12:00:00.000Z",
+      "content": "<p>Episode description HTML</p>",
+      "author": "Author Name",
+      "enclosure": {
+        "url": "https://cdn.example/episode.mp3",
+        "type": "audio/mpeg",
+        "length": 12345678
+      },
+      "podcast": {
+        "title": "Podcast Name",
+        "url": "https://podcast.example",
+        "feedUrl": "https://podcast.example/feed.xml"
+      }
+    }
+  ],
+  "total": 100,
+  "limit": 50,
+  "offset": 0,
+  "hasMore": true
+}
+```
+
+## Sources Response Schema
+
+```json
+{
+  "items": [
+    {
+      "title": "Podcast Name",
+      "xmlUrl": "https://podcast.example/feed.xml",
+      "htmlUrl": "https://podcast.example",
+      "category": "Technology"
+    }
+  ],
+  "total": 70,
+  "categories": ["Technology", "Culture", "Politics"]
+}
+```
+
+## Frontend Integration
+
+The APIs are designed for client-side fetching. Example with vanilla JavaScript:
+
+```javascript
+// Fetch episodes
+const response = await fetch('/podrollapi/api/episodes?limit=20');
+const { items, hasMore } = await response.json();
+
+// Fetch sources for sidebar
+const sourcesResponse = await fetch('/podrollapi/api/sources');
+const { items: sources } = await sourcesResponse.json();
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,111 @@
+import express from "express";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { dashboardController } from "./lib/controllers/dashboard.js";
+import { episodesController } from "./lib/controllers/episodes.js";
+import { sourcesController } from "./lib/controllers/sources.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: "/podrollapi",
+  syncInterval: 900_000, // 15 minutes
+  maxEpisodes: 100,
+  fetchTimeout: 15_000,
+  // These should be overridden in config
+  episodesUrl: "",
+  opmlUrl: "",
+};
+
+export default class PodrollEndpoint {
+  name = "Podcast roll endpoint";
+
+  constructor(options = {}) {
+    this.options = { ...defaults, ...options };
+    this.mountPath = this.options.mountPath;
+  }
+
+  get localesDirectory() {
+    return path.join(__dirname, "locales");
+  }
+
+  get navigationItems() {
+    return {
+      href: this.options.mountPath,
+      text: "podroll.title",
+      requiresDatabase: true,
+    };
+  }
+
+  get shortcutItems() {
+    return {
+      url: this.options.mountPath,
+      name: "podroll.title",
+      iconName: "syndicate",
+      requiresDatabase: true,
+    };
+  }
+
+  /**
+   * Protected routes (require authentication)
+   * Admin dashboard and management
+   */
+  get routes() {
+    // Dashboard
+    protectedRouter.get("/", dashboardController.get);
+
+    // Manual sync trigger
+    protectedRouter.post("/sync", dashboardController.sync);
+
+    // Clear and re-sync
+    protectedRouter.post("/clear-resync", dashboardController.clearResync);
+
+    return protectedRouter;
+  }
+
+  /**
+   * Public routes (no authentication required)
+   * Read-only JSON API endpoints for frontend
+   */
+  get routesPublic() {
+    // Episodes API (read-only)
+    publicRouter.get("/api/episodes", episodesController.list);
+    publicRouter.get("/api/episodes/:id", episodesController.get);
+
+    // Sources/OPML API (read-only)
+    publicRouter.get("/api/sources", sourcesController.list);
+
+    // Status API
+    publicRouter.get("/api/status", dashboardController.status);
+
+    return publicRouter;
+  }
+
+  init(Indiekit) {
+    Indiekit.addEndpoint(this);
+
+    // Add MongoDB collections
+    Indiekit.addCollection("podrollEpisodes");
+    Indiekit.addCollection("podrollSources");
+    Indiekit.addCollection("podrollMeta");
+
+    // Store config in application for controller access
+    Indiekit.config.application.podrollConfig = this.options;
+    Indiekit.config.application.podrollEndpoint = this.mountPath;
+
+    // Store database getter for controller access
+    Indiekit.config.application.getPodrollDb = () => Indiekit.database;
+
+    // Start background sync if database is available and URLs are configured
+    if (Indiekit.config.application.mongodbUrl && this.options.episodesUrl) {
+      startSync(Indiekit, this.options);
+    } else if (!this.options.episodesUrl) {
+      console.warn("[Podroll] No episodesUrl configured, sync disabled");
+    }
+  }
+}

package/lib/controllers/dashboard.js

@@ -0,0 +1,153 @@
+import { runSync } from "../sync.js";
+
+/**
+ * Dashboard controller for admin UI
+ */
+export const dashboardController = {
+  /**
+   * Render dashboard
+   * GET /
+   */
+  async get(request, response) {
+    try {
+      const { application } = request.app.locals;
+      const db = application.getPodrollDb();
+
+      let stats = {
+        episodeCount: 0,
+        sourceCount: 0,
+        lastEpisodesSync: null,
+        lastSourcesSync: null,
+      };
+
+      if (db) {
+        const [episodeCount, sourceCount, episodesMeta, sourcesMeta] = await Promise.all([
+          db.collection("podrollEpisodes").countDocuments(),
+          db.collection("podrollSources").countDocuments(),
+          db.collection("podrollMeta").findOne({ key: "lastEpisodesSync" }),
+          db.collection("podrollMeta").findOne({ key: "lastSourcesSync" }),
+        ]);
+
+        stats = {
+          episodeCount,
+          sourceCount,
+          lastEpisodesSync: episodesMeta?.timestamp || null,
+          lastSourcesSync: sourcesMeta?.timestamp || null,
+        };
+      }
+
+      response.render("dashboard", {
+        title: response.__("podroll.title"),
+        stats,
+        config: {
+          episodesUrl: application.podrollConfig?.episodesUrl ? "Configured" : "Not set",
+          opmlUrl: application.podrollConfig?.opmlUrl ? "Configured" : "Not set",
+          syncInterval: application.podrollConfig?.syncInterval || 900000,
+        },
+      });
+    } catch (error) {
+      console.error("[Podroll] Dashboard error:", error);
+      response.status(500).render("error", {
+        title: "Error",
+        message: error.message,
+      });
+    }
+  },
+
+  /**
+   * Manual sync trigger
+   * POST /sync
+   */
+  async sync(request, response) {
+    try {
+      const { application } = request.app.locals;
+      const db = application.getPodrollDb();
+
+      if (!db) {
+        return response.status(503).json({ error: "Database not available" });
+      }
+
+      const result = await runSync(db, application.podrollConfig);
+
+      // Redirect back to dashboard with success message
+      response.redirect(application.podrollEndpoint + "?synced=true");
+    } catch (error) {
+      console.error("[Podroll] Sync error:", error);
+      response.redirect(application.podrollEndpoint + "?error=" + encodeURIComponent(error.message));
+    }
+  },
+
+  /**
+   * Clear all data and re-sync
+   * POST /clear-resync
+   */
+  async clearResync(request, response) {
+    try {
+      const { application } = request.app.locals;
+      const db = application.getPodrollDb();
+
+      if (!db) {
+        return response.status(503).json({ error: "Database not available" });
+      }
+
+      // Clear collections
+      await Promise.all([
+        db.collection("podrollEpisodes").deleteMany({}),
+        db.collection("podrollSources").deleteMany({}),
+        db.collection("podrollMeta").deleteMany({}),
+      ]);
+
+      console.log("[Podroll] Cleared all data, starting fresh sync...");
+
+      // Run fresh sync
+      const result = await runSync(db, application.podrollConfig);
+
+      response.redirect(application.podrollEndpoint + "?cleared=true");
+    } catch (error) {
+      console.error("[Podroll] Clear/resync error:", error);
+      response.redirect(application.podrollEndpoint + "?error=" + encodeURIComponent(error.message));
+    }
+  },
+
+  /**
+   * Status API (public)
+   * GET /api/status
+   */
+  async status(request, response) {
+    try {
+      const { application } = request.app.locals;
+      const db = application.getPodrollDb();
+
+      if (!db) {
+        return response.json({
+          status: "unavailable",
+          message: "Database not connected",
+        });
+      }
+
+      const [episodeCount, sourceCount, episodesMeta, sourcesMeta] = await Promise.all([
+        db.collection("podrollEpisodes").countDocuments(),
+        db.collection("podrollSources").countDocuments(),
+        db.collection("podrollMeta").findOne({ key: "lastEpisodesSync" }),
+        db.collection("podrollMeta").findOne({ key: "lastSourcesSync" }),
+      ]);
+
+      response.json({
+        status: "ok",
+        episodes: {
+          count: episodeCount,
+          lastSync: episodesMeta?.timestamp || null,
+        },
+        sources: {
+          count: sourceCount,
+          lastSync: sourcesMeta?.timestamp || null,
+        },
+      });
+    } catch (error) {
+      response.status(500).json({
+        status: "error",
+        message: error.message,
+      });
+    }
+  },
+};

package/lib/controllers/episodes.js

@@ -0,0 +1,121 @@
+/**
+ * Episodes API controller
+ */
+export const episodesController = {
+  /**
+   * List episodes
+   * GET /api/episodes
+   * Query params: limit, offset, source (filter by origin title)
+   */
+  async list(request, response) {
+    try {
+      const { application } = request.app.locals;
+      const db = application.getPodrollDb();
+
+      if (!db) {
+        return response.status(503).json({
+          error: "Database not available",
+        });
+      }
+
+      const limit = Math.min(parseInt(request.query.limit) || 50, 200);
+      const offset = parseInt(request.query.offset) || 0;
+      const source = request.query.source || null;
+
+      const collection = db.collection("podrollEpisodes");
+
+      // Build query
+      const query = {};
+      if (source) {
+        query["origin.title"] = { $regex: source, $options: "i" };
+      }
+
+      // Get total count
+      const total = await collection.countDocuments(query);
+
+      // Get episodes
+      const episodes = await collection
+        .find(query)
+        .sort({ published: -1 })
+        .skip(offset)
+        .limit(limit)
+        .toArray();
+
+      // Transform for API response
+      const items = episodes.map((ep) => ({
+        id: ep.id,
+        title: ep.title,
+        url: ep.url,
+        published: ep.published,
+        content: ep.content,
+        author: ep.author,
+        enclosure: ep.enclosure,
+        podcast: ep.origin
+          ? {
+              title: ep.origin.title,
+              url: ep.origin.htmlUrl,
+              feedUrl: ep.origin.feedUrl,
+            }
+          : null,
+      }));
+
+      response.json({
+        items,
+        total,
+        limit,
+        offset,
+        hasMore: offset + items.length < total,
+      });
+    } catch (error) {
+      console.error("[Podroll] Episodes list error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+
+  /**
+   * Get single episode
+   * GET /api/episodes/:id
+   */
+  async get(request, response) {
+    try {
+      const { application } = request.app.locals;
+      const db = application.getPodrollDb();
+
+      if (!db) {
+        return response.status(503).json({
+          error: "Database not available",
+        });
+      }
+
+      const { id } = request.params;
+      const collection = db.collection("podrollEpisodes");
+
+      const episode = await collection.findOne({ id });
+
+      if (!episode) {
+        return response.status(404).json({ error: "Episode not found" });
+      }
+
+      response.json({
+        id: episode.id,
+        title: episode.title,
+        url: episode.url,
+        published: episode.published,
+        content: episode.content,
+        author: episode.author,
+        enclosure: episode.enclosure,
+        podcast: episode.origin
+          ? {
+              title: episode.origin.title,
+              url: episode.origin.htmlUrl,
+              feedUrl: episode.origin.feedUrl,
+            }
+          : null,
+        categories: episode.categories,
+      });
+    } catch (error) {
+      console.error("[Podroll] Episode get error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};

package/lib/controllers/sources.js

@@ -0,0 +1,57 @@
+/**
+ * Sources (OPML) API controller
+ */
+export const sourcesController = {
+  /**
+   * List podcast sources from OPML
+   * GET /api/sources
+   * Query params: category (filter by category)
+   */
+  async list(request, response) {
+    try {
+      const { application } = request.app.locals;
+      const db = application.getPodrollDb();
+
+      if (!db) {
+        return response.status(503).json({
+          error: "Database not available",
+        });
+      }
+
+      const category = request.query.category || null;
+      const collection = db.collection("podrollSources");
+
+      // Build query
+      const query = {};
+      if (category) {
+        query.category = { $regex: category, $options: "i" };
+      }
+
+      // Get sources sorted by order (original OPML order)
+      const sources = await collection
+        .find(query)
+        .sort({ category: 1, order: 1 })
+        .toArray();
+
+      // Group by category if multiple categories exist
+      const categories = [...new Set(sources.map((s) => s.category).filter(Boolean))];
+
+      // Transform for API response
+      const items = sources.map((s) => ({
+        title: s.title,
+        xmlUrl: s.xmlUrl,
+        htmlUrl: s.htmlUrl,
+        category: s.category,
+      }));
+
+      response.json({
+        items,
+        total: items.length,
+        categories: categories.length > 0 ? categories : null,
+      });
+    } catch (error) {
+      console.error("[Podroll] Sources list error:", error);
+      response.status(500).json({ error: error.message });
+    }
+  },
+};

package/lib/sync.js

@@ -0,0 +1,334 @@
+import { parseString } from "xml2js";
+import { promisify } from "node:util";
+
+const parseXml = promisify(parseString);
+
+/**
+ * Fetch episodes from FreshRSS greader API
+ * @param {string} url - FreshRSS API URL
+ * @param {number} timeout - Fetch timeout in ms
+ * @returns {Promise<Array>} Array of episode objects
+ */
+async function fetchEpisodes(url, timeout) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        "User-Agent": "Indiekit-Podroll/1.0",
+        Accept: "application/json",
+      },
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    return data.items || [];
+  } catch (error) {
+    clearTimeout(timeoutId);
+    throw error;
+  }
+}
+
+/**
+ * Fetch OPML sources from FreshRSS
+ * @param {string} url - OPML URL
+ * @param {number} timeout - Fetch timeout in ms
+ * @returns {Promise<Array>} Array of source objects
+ */
+async function fetchOpmlSources(url, timeout) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        "User-Agent": "Indiekit-Podroll/1.0",
+        Accept: "application/xml, text/xml",
+      },
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const xml = await response.text();
+    const result = await parseXml(xml, { explicitArray: false });
+
+    // Extract outlines from OPML
+    const sources = [];
+    const body = result?.opml?.body;
+
+    if (body?.outline) {
+      const outlines = Array.isArray(body.outline) ? body.outline : [body.outline];
+
+      for (const outline of outlines) {
+        // Handle nested outlines (categories)
+        if (outline.outline) {
+          const children = Array.isArray(outline.outline) ? outline.outline : [outline.outline];
+          for (const child of children) {
+            if (child.$ && child.$.xmlUrl) {
+              sources.push({
+                title: child.$.text || child.$.title || "Unknown",
+                xmlUrl: child.$.xmlUrl,
+                htmlUrl: child.$.htmlUrl || "",
+                type: child.$.type || "rss",
+                category: outline.$.text || outline.$.title || "",
+              });
+            }
+          }
+        } else if (outline.$ && outline.$.xmlUrl) {
+          // Direct feed outline
+          sources.push({
+            title: outline.$.text || outline.$.title || "Unknown",
+            xmlUrl: outline.$.xmlUrl,
+            htmlUrl: outline.$.htmlUrl || "",
+            type: outline.$.type || "rss",
+            category: "",
+          });
+        }
+      }
+    }
+
+    return sources;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    throw error;
+  }
+}
+
+/**
+ * Transform FreshRSS episode to our schema
+ * @param {object} item - FreshRSS item
+ * @returns {object} Transformed episode
+ */
+function transformEpisode(item) {
+  // Extract enclosure (audio file)
+  let enclosure = null;
+  if (item.enclosure && item.enclosure.length > 0) {
+    const enc = item.enclosure[0];
+    enclosure = {
+      url: enc.href || enc.url,
+      type: enc.type || "audio/mpeg",
+      length: enc.length ? parseInt(enc.length, 10) : 0,
+    };
+  }
+
+  // Extract origin (podcast source)
+  let origin = null;
+  if (item.origin) {
+    origin = {
+      streamId: item.origin.streamId || "",
+      title: item.origin.title || "",
+      htmlUrl: item.origin.htmlUrl || "",
+      feedUrl: item.origin.feedUrl || "",
+    };
+  }
+
+  // Get canonical URL
+  let url = "";
+  if (item.canonical && item.canonical.length > 0) {
+    url = item.canonical[0].href || "";
+  } else if (item.alternate && item.alternate.length > 0) {
+    url = item.alternate[0].href || "";
+  }
+
+  return {
+    id: item["frss:id"] || item.id || item.guid,
+    guid: item.guid || item.id,
+    title: item.title || "Untitled Episode",
+    url: url,
+    published: item.published ? new Date(item.published * 1000) : new Date(),
+    content: item.content?.content || item.summary?.content || "",
+    author: item.author || "",
+    enclosure: enclosure,
+    origin: origin,
+    categories: item.categories || [],
+    fetchedAt: new Date(),
+  };
+}
+
+/**
+ * Sync episodes from FreshRSS to MongoDB
+ * @param {object} db - MongoDB database instance
+ * @param {object} options - Sync options
+ * @returns {Promise<object>} Sync result stats
+ */
+async function syncEpisodes(db, options) {
+  const { episodesUrl, fetchTimeout, maxEpisodes } = options;
+
+  if (!episodesUrl) {
+    return { success: false, error: "No episodesUrl configured" };
+  }
+
+  try {
+    console.log("[Podroll] Fetching episodes from FreshRSS...");
+    const rawEpisodes = await fetchEpisodes(episodesUrl, fetchTimeout);
+    console.log(`[Podroll] Fetched ${rawEpisodes.length} episodes`);
+
+    const episodes = rawEpisodes
+      .map(transformEpisode)
+      .slice(0, maxEpisodes);
+
+    const collection = db.collection("podrollEpisodes");
+
+    // Upsert episodes
+    let inserted = 0;
+    let updated = 0;
+
+    for (const episode of episodes) {
+      const result = await collection.updateOne(
+        { id: episode.id },
+        { $set: episode },
+        { upsert: true }
+      );
+
+      if (result.upsertedCount > 0) {
+        inserted++;
+      } else if (result.modifiedCount > 0) {
+        updated++;
+      }
+    }
+
+    // Update sync metadata
+    await db.collection("podrollMeta").updateOne(
+      { key: "lastEpisodesSync" },
+      {
+        $set: {
+          key: "lastEpisodesSync",
+          timestamp: new Date(),
+          episodeCount: episodes.length,
+          inserted,
+          updated,
+        },
+      },
+      { upsert: true }
+    );
+
+    console.log(`[Podroll] Synced episodes: ${inserted} new, ${updated} updated`);
+
+    return {
+      success: true,
+      total: episodes.length,
+      inserted,
+      updated,
+    };
+  } catch (error) {
+    console.error("[Podroll] Episode sync failed:", error.message);
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Sync OPML sources to MongoDB
+ * @param {object} db - MongoDB database instance
+ * @param {object} options - Sync options
+ * @returns {Promise<object>} Sync result stats
+ */
+async function syncSources(db, options) {
+  const { opmlUrl, fetchTimeout } = options;
+
+  if (!opmlUrl) {
+    return { success: false, error: "No opmlUrl configured" };
+  }
+
+  try {
+    console.log("[Podroll] Fetching OPML sources...");
+    const sources = await fetchOpmlSources(opmlUrl, fetchTimeout);
+    console.log(`[Podroll] Fetched ${sources.length} podcast sources`);
+
+    const collection = db.collection("podrollSources");
+
+    // Clear existing and insert fresh
+    await collection.deleteMany({});
+    if (sources.length > 0) {
+      await collection.insertMany(
+        sources.map((s, index) => ({
+          ...s,
+          order: index,
+          fetchedAt: new Date(),
+        }))
+      );
+    }
+
+    // Update sync metadata
+    await db.collection("podrollMeta").updateOne(
+      { key: "lastSourcesSync" },
+      {
+        $set: {
+          key: "lastSourcesSync",
+          timestamp: new Date(),
+          sourceCount: sources.length,
+        },
+      },
+      { upsert: true }
+    );
+
+    console.log(`[Podroll] Synced ${sources.length} podcast sources`);
+
+    return {
+      success: true,
+      total: sources.length,
+    };
+  } catch (error) {
+    console.error("[Podroll] Source sync failed:", error.message);
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Run full sync (episodes + sources)
+ * @param {object} db - MongoDB database instance
+ * @param {object} options - Sync options
+ * @returns {Promise<object>} Combined sync results
+ */
+export async function runSync(db, options) {
+  const [episodesResult, sourcesResult] = await Promise.all([
+    syncEpisodes(db, options),
+    options.opmlUrl ? syncSources(db, options) : { success: true, skipped: true },
+  ]);
+
+  return {
+    episodes: episodesResult,
+    sources: sourcesResult,
+    timestamp: new Date(),
+  };
+}
+
+/**
+ * Start background sync interval
+ * @param {object} Indiekit - Indiekit instance
+ * @param {object} options - Sync options
+ */
+export function startSync(Indiekit, options) {
+  const { syncInterval } = options;
+
+  // Initial sync after short delay
+  setTimeout(async () => {
+    const db = Indiekit.database;
+    if (db) {
+      console.log("[Podroll] Running initial sync...");
+      await runSync(db, options);
+    }
+  }, 5000);
+
+  // Periodic sync
+  setInterval(async () => {
+    const db = Indiekit.database;
+    if (db) {
+      console.log("[Podroll] Running scheduled sync...");
+      await runSync(db, options);
+    }
+  }, syncInterval);
+
+  console.log(`[Podroll] Background sync started (interval: ${syncInterval / 1000}s)`);
+}

package/locales/en.json

@@ -0,0 +1,28 @@
+{
+  "podroll": {
+    "title": "Podroll",
+    "description": "Podcast subscriptions aggregated from FreshRSS",
+    "stats": "Statistics",
+    "episodeCount": "Episodes",
+    "sourceCount": "Podcast Sources",
+    "lastEpisodesSync": "Last Episodes Sync",
+    "lastSourcesSync": "Last Sources Sync",
+    "never": "Never",
+    "configuration": "Configuration",
+    "episodesUrl": "Episodes Feed URL",
+    "opmlUrl": "OPML URL",
+    "syncInterval": "Sync Interval",
+    "minutes": "minutes",
+    "actions": "Actions",
+    "syncNow": "Sync Now",
+    "clearResync": "Clear & Re-sync",
+    "clearConfirm": "This will delete all cached episodes and sources, then re-fetch from FreshRSS. Continue?",
+    "syncSuccess": "Sync completed successfully",
+    "clearSuccess": "Data cleared and re-synced successfully",
+    "syncError": "Sync failed",
+    "apiEndpoints": "API Endpoints",
+    "apiEpisodes": "List podcast episodes (supports limit, offset, source params)",
+    "apiSources": "List podcast sources from OPML (supports category param)",
+    "apiStatus": "Sync status and counts"
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@rmdes/indiekit-endpoint-podroll",
+  "version": "1.0.0",
+  "description": "Podcast roll endpoint for Indiekit. Aggregates podcast episodes from FreshRSS, displays on frontend with OPML sidebar.",
+  "keywords": [
+    "indiekit",
+    "indiekit-plugin",
+    "indieweb",
+    "podcast",
+    "podroll",
+    "opml",
+    "rss"
+  ],
+  "homepage": "https://github.com/rmdes/indiekit-endpoint-podroll",
+  "bugs": {
+    "url": "https://github.com/rmdes/indiekit-endpoint-podroll/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rmdes/indiekit-endpoint-podroll.git"
+  },
+  "author": {
+    "name": "Ricardo Mendes",
+    "url": "https://rmendes.net"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "lib",
+    "locales",
+    "views",
+    "index.js"
+  ],
+  "dependencies": {
+    "@indiekit/error": "^1.0.0-beta.25",
+    "express": "^5.0.0",
+    "sanitize-html": "^2.13.0",
+    "xml2js": "^0.6.2"
+  },
+  "peerDependencies": {
+    "@indiekit/indiekit": ">=1.0.0-beta.25"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/views/dashboard.njk

@@ -0,0 +1,93 @@
+{% extends "document.njk" %}
+
+{% block content %}
+<header class="page-header">
+  <h1 class="page-header__title">{{ __("podroll.title") }}</h1>
+  <p class="page-header__description">{{ __("podroll.description") }}</p>
+</header>
+
+{% if request.query.synced %}
+<div class="notification notification--success">
+  {{ __("podroll.syncSuccess") }}
+</div>
+{% endif %}
+
+{% if request.query.cleared %}
+<div class="notification notification--success">
+  {{ __("podroll.clearSuccess") }}
+</div>
+{% endif %}
+
+{% if request.query.error %}
+<div class="notification notification--error">
+  {{ __("podroll.syncError") }}: {{ request.query.error }}
+</div>
+{% endif %}
+
+<div class="dashboard">
+  <section class="dashboard__section">
+    <h2>{{ __("podroll.stats") }}</h2>
+    <dl class="definition-list">
+      <div class="definition-list__item">
+        <dt>{{ __("podroll.episodeCount") }}</dt>
+        <dd>{{ stats.episodeCount }}</dd>
+      </div>
+      <div class="definition-list__item">
+        <dt>{{ __("podroll.sourceCount") }}</dt>
+        <dd>{{ stats.sourceCount }}</dd>
+      </div>
+      <div class="definition-list__item">
+        <dt>{{ __("podroll.lastEpisodesSync") }}</dt>
+        <dd>{{ stats.lastEpisodesSync | date("PPpp") if stats.lastEpisodesSync else __("podroll.never") }}</dd>
+      </div>
+      <div class="definition-list__item">
+        <dt>{{ __("podroll.lastSourcesSync") }}</dt>
+        <dd>{{ stats.lastSourcesSync | date("PPpp") if stats.lastSourcesSync else __("podroll.never") }}</dd>
+      </div>
+    </dl>
+  </section>
+
+  <section class="dashboard__section">
+    <h2>{{ __("podroll.configuration") }}</h2>
+    <dl class="definition-list">
+      <div class="definition-list__item">
+        <dt>{{ __("podroll.episodesUrl") }}</dt>
+        <dd>{{ config.episodesUrl }}</dd>
+      </div>
+      <div class="definition-list__item">
+        <dt>{{ __("podroll.opmlUrl") }}</dt>
+        <dd>{{ config.opmlUrl }}</dd>
+      </div>
+      <div class="definition-list__item">
+        <dt>{{ __("podroll.syncInterval") }}</dt>
+        <dd>{{ (config.syncInterval / 60000) | round }} {{ __("podroll.minutes") }}</dd>
+      </div>
+    </dl>
+  </section>
+
+  <section class="dashboard__section">
+    <h2>{{ __("podroll.actions") }}</h2>
+    <div class="button-group">
+      <form method="post" action="{{ application.podrollEndpoint }}/sync" style="display: inline;">
+        <button type="submit" class="button button--primary">
+          {{ __("podroll.syncNow") }}
+        </button>
+      </form>
+      <form method="post" action="{{ application.podrollEndpoint }}/clear-resync" style="display: inline;" onsubmit="return confirm('{{ __("podroll.clearConfirm") }}');">
+        <button type="submit" class="button button--secondary">
+          {{ __("podroll.clearResync") }}
+        </button>
+      </form>
+    </div>
+  </section>
+
+  <section class="dashboard__section">
+    <h2>{{ __("podroll.apiEndpoints") }}</h2>
+    <ul class="api-list">
+      <li><code>GET {{ application.podrollEndpoint }}/api/episodes</code> - {{ __("podroll.apiEpisodes") }}</li>
+      <li><code>GET {{ application.podrollEndpoint }}/api/sources</code> - {{ __("podroll.apiSources") }}</li>
+      <li><code>GET {{ application.podrollEndpoint }}/api/status</code> - {{ __("podroll.apiStatus") }}</li>
+    </ul>
+  </section>
+</div>
+{% endblock %}