@rmdes/indiekit-endpoint-conversations 1.0.0

package/index.js

@@ -0,0 +1,117 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import express from "express";
+
+import { conversationsController } from "./lib/controllers/conversations.js";
+import { createIndexes } from "./lib/storage/conversation-items.js";
+
+const defaults = {
+  mountPath: "/conversations",
+  directPolling: {
+    mastodon: false,
+    bluesky: false,
+  },
+  useGranary: false,
+  granaryUrl: "https://granary.io",
+};
+
+const router = express.Router();
+
+export default class ConversationsEndpoint {
+  name = "Conversations endpoint";
+
+  /**
+   * @param {object} options - Plugin options
+   * @param {string} [options.mountPath] - Path to mount endpoint
+   * @param {object} [options.directPolling] - Enable direct API polling
+   * @param {boolean} [options.useGranary] - Use Granary REST API for format conversion
+   * @param {string} [options.granaryUrl] - Custom Granary instance URL
+   */
+  constructor(options = {}) {
+    this.options = { ...defaults, ...options };
+    this.mountPath = this.options.mountPath;
+  }
+
+  get localesDirectory() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), "locales");
+  }
+
+  get navigationItems() {
+    return {
+      href: this.options.mountPath,
+      text: "conversations.title",
+      requiresDatabase: true,
+    };
+  }
+
+  get routes() {
+    // Admin UI
+    router.get("/", conversationsController.list);
+    router.get("/post", conversationsController.detail);
+
+    // JSON API (public-ish, for Eleventy client-side fetch)
+    router.get("/api/post", conversationsController.apiPost);
+
+    // Webmention ingestion endpoint
+    router.post("/ingest", conversationsController.ingest);
+
+    return router;
+  }
+
+  get routesPublic() {
+    const publicRouter = express.Router();
+
+    // JSON API must be public for Eleventy client-side JS to fetch
+    publicRouter.get("/api/post", conversationsController.apiPost);
+
+    // Webmention ingestion can be called by Bridgy or webmention.io
+    publicRouter.post("/ingest", conversationsController.ingest);
+
+    return publicRouter;
+  }
+
+  init(indiekit) {
+    console.info("[Conversations] Initializing endpoint-conversations plugin");
+
+    // Register MongoDB collections
+    indiekit.addCollection("conversation_items");
+    indiekit.addCollection("conversation_state");
+
+    console.info("[Conversations] Registered MongoDB collections");
+
+    indiekit.addEndpoint(this);
+
+    // Store options on the application for access by controllers
+    if (!indiekit.config.application.conversations) {
+      indiekit.config.application.conversations = this.options;
+    }
+
+    if (indiekit.database) {
+      // Create indexes
+      createIndexes(indiekit).catch((error) => {
+        console.warn(
+          "[Conversations] Index creation failed:",
+          error.message,
+        );
+      });
+
+      // Start direct polling if enabled
+      if (
+        this.options.directPolling.mastodon ||
+        this.options.directPolling.bluesky
+      ) {
+        import("./lib/polling/scheduler.js")
+          .then(({ startPolling }) => {
+            startPolling(indiekit, this.options);
+          })
+          .catch((error) => {
+            console.error(
+              "[Conversations] Polling scheduler failed to start:",
+              error.message,
+            );
+          });
+      }
+    }
+  }
+}

package/lib/controllers/conversations.js

@@ -0,0 +1,182 @@
+/**
+ * Conversations controller
+ * Admin UI + JSON API for unified conversation views
+ * @module controllers/conversations
+ */
+
+import {
+  classifyWebmention,
+  generatePlatformId,
+} from "../ingestion/webmention-classifier.js";
+import { resolveCanonicalUrl } from "../matching/syndication-map.js";
+import {
+  getConversationItems,
+  getConversationSummaries,
+  upsertConversationItem,
+} from "../storage/conversation-items.js";
+
+/**
+ * List conversations (admin UI)
+ * GET /conversations
+ */
+async function list(request, response) {
+  const { application } = request.app.locals;
+  const page = Number.parseInt(request.query.page) || 1;
+  const limit = 50;
+  const skip = (page - 1) * limit;
+
+  try {
+    const summaries = await getConversationSummaries(application, {
+      limit,
+      skip,
+    });
+
+    response.render("conversations", {
+      title: "Conversations",
+      summaries,
+      page,
+      baseUrl: application.conversations?.mountPath || "/conversations",
+    });
+  } catch (error) {
+    console.error("[Conversations] List error:", error.message);
+    response.status(500).render("conversations", {
+      title: "Conversations",
+      summaries: [],
+      error: error.message,
+    });
+  }
+}
+
+/**
+ * Conversation detail for a post (admin UI)
+ * GET /conversations/post?url=...
+ */
+async function detail(request, response) {
+  const { application } = request.app.locals;
+  const { url } = request.query;
+
+  if (!url) {
+    return response.status(400).render("conversation-detail", {
+      title: "Conversation",
+      items: [],
+      error: "URL parameter required",
+    });
+  }
+
+  try {
+    const items = await getConversationItems(application, url);
+
+    // Group by source
+    const grouped = {
+      webmention: items.filter((i) => i.source === "webmention"),
+      mastodon: items.filter((i) => i.source === "mastodon"),
+      bluesky: items.filter((i) => i.source === "bluesky"),
+    };
+
+    response.render("conversation-detail", {
+      title: "Conversation",
+      canonicalUrl: url,
+      items,
+      grouped,
+      baseUrl: application.conversations?.mountPath || "/conversations",
+    });
+  } catch (error) {
+    console.error("[Conversations] Detail error:", error.message);
+    response.status(500).render("conversation-detail", {
+      title: "Conversation",
+      items: [],
+      error: error.message,
+    });
+  }
+}
+
+/**
+ * JSON API — get conversation items for a canonical URL
+ * GET /conversations/api/post?url=...
+ */
+async function apiPost(request, response) {
+  const { application } = request.app.locals;
+  const { url, source } = request.query;
+
+  if (!url) {
+    return response.status(400).json({ error: "url parameter required" });
+  }
+
+  try {
+    const options = {};
+    if (source) options.source = source;
+
+    const items = await getConversationItems(application, url, options);
+
+    // Group by source for easy consumption
+    const grouped = {};
+    for (const item of items) {
+      if (!grouped[item.source]) grouped[item.source] = [];
+      grouped[item.source].push(item);
+    }
+
+    response.json({
+      canonical_url: url,
+      total: items.length,
+      items,
+      grouped,
+    });
+  } catch (error) {
+    console.error("[Conversations] API error:", error.message);
+    response.status(500).json({ error: error.message });
+  }
+}
+
+/**
+ * Ingest a webmention
+ * POST /conversations/ingest
+ * Accepts webmention data, classifies it, and stores it
+ */
+async function ingest(request, response) {
+  const { application } = request.app.locals;
+  const siteUrl = application.url || process.env.SITE_URL;
+
+  try {
+    const webmention = request.body;
+
+    if (!webmention.source || !webmention.target) {
+      return response.status(400).json({
+        error: "source and target are required",
+      });
+    }
+
+    // Classify the webmention
+    const classification = classifyWebmention(webmention);
+
+    // Resolve canonical URL (target may be a syndication URL)
+    const canonicalUrl = await resolveCanonicalUrl(
+      application,
+      webmention.target,
+      siteUrl,
+    );
+
+    // Build conversation item
+    const item = {
+      canonical_url: canonicalUrl,
+      source: classification.source,
+      type: classification.type,
+      author: webmention.author || {
+        name: "Unknown",
+        url: webmention.source,
+      },
+      content: webmention.content?.text || webmention.content?.html || null,
+      url: webmention.source,
+      bridgy_url: classification.bridgy_url,
+      platform_id: generatePlatformId(webmention),
+    };
+
+    await upsertConversationItem(application, item);
+
+    response.status(202).json({ status: "accepted", classification });
+  } catch (error) {
+    console.error("[Conversations] Ingest error:", error.message);
+    response.status(500).json({ error: error.message });
+  }
+}
+
+export const conversationsController = { list, detail, apiPost, ingest };

package/lib/ingestion/granary-client.js

@@ -0,0 +1,46 @@
+/**
+ * Granary REST API client
+ * Optional format conversion between ActivityStreams/microformats2/AT Protocol
+ * Uses the Granary REST API: https://granary.io/
+ * @module ingestion/granary-client
+ */
+
+/**
+ * Convert content between formats using Granary REST API
+ * @param {string} url - URL of the content to convert
+ * @param {object} options - Conversion options
+ * @param {string} options.input - Input format (activitystreams, html, atom, jsonfeed)
+ * @param {string} options.output - Output format (html, activitystreams, atom, jsonfeed, mf2-json)
+ * @param {string} [options.granaryUrl] - Custom Granary instance URL
+ * @returns {Promise<string>} Converted content
+ */
+export async function convert(url, options) {
+  const {
+    input = "html",
+    output = "mf2-json",
+    granaryUrl = "https://granary.io",
+  } = options;
+
+  const apiUrl = new URL("/url", granaryUrl);
+  apiUrl.searchParams.set("input", input);
+  apiUrl.searchParams.set("output", output);
+  apiUrl.searchParams.set("url", url);
+
+  const response = await fetch(apiUrl.toString(), {
+    headers: {
+      "User-Agent": "IndieKit-Conversations/1.0",
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Granary API ${response.status}: ${response.statusText}`,
+    );
+  }
+
+  if (output === "mf2-json" || output === "activitystreams") {
+    return response.json();
+  }
+
+  return response.text();
+}

package/lib/ingestion/webmention-classifier.js

@@ -0,0 +1,167 @@
+/**
+ * Webmention classifier
+ * Classifies incoming webmentions by source protocol
+ * @module ingestion/webmention-classifier
+ */
+
+/**
+ * Classify a webmention source URL by protocol origin
+ * @param {object} webmention - Webmention data
+ * @param {string} webmention.source - Source URL of the webmention
+ * @param {object} [webmention.author] - Author data if available
+ * @returns {object} Classification result
+ */
+export function classifyWebmention(webmention) {
+  const source = webmention.source || "";
+  const authorUrl = webmention.author?.url || "";
+
+  // Bridgy pattern: https://brid.gy/{action}/{platform}/...
+  const bridgyMatch = source.match(
+    /brid\.gy\/(comment|like|repost|mention)\/(mastodon|bluesky|twitter|flickr|github)\//i,
+  );
+
+  if (bridgyMatch) {
+    const [, action, platform] = bridgyMatch;
+    return {
+      source: mapBridgyPlatform(platform),
+      type: mapBridgyAction(action),
+      bridgy_url: source,
+      confidence: "high",
+    };
+  }
+
+  // Bridgy Fed pattern: https://fed.brid.gy/...
+  if (source.includes("fed.brid.gy")) {
+    return {
+      source: "mastodon",
+      type: inferTypeFromUrl(source),
+      bridgy_url: source,
+      confidence: "high",
+    };
+  }
+
+  // Direct URL pattern matching (non-Bridgy webmentions)
+  if (authorUrl.includes("bsky.app") || source.includes("bsky.app")) {
+    return {
+      source: "bluesky",
+      type: inferTypeFromUrl(source),
+      bridgy_url: null,
+      confidence: "medium",
+    };
+  }
+
+  if (isFediverseUrl(authorUrl) || isFediverseUrl(source)) {
+    return {
+      source: "mastodon",
+      type: inferTypeFromUrl(source),
+      bridgy_url: null,
+      confidence: "medium",
+    };
+  }
+
+  // Default: direct webmention from the open web
+  return {
+    source: "webmention",
+    type: webmention["wm-property"]
+      ? mapWmProperty(webmention["wm-property"])
+      : inferTypeFromUrl(source),
+    bridgy_url: null,
+    confidence: "low",
+  };
+}
+
+/**
+ * Map Bridgy platform names to our source types
+ */
+function mapBridgyPlatform(platform) {
+  const map = {
+    mastodon: "mastodon",
+    bluesky: "bluesky",
+    twitter: "twitter",
+    flickr: "flickr",
+    github: "github",
+  };
+  return map[platform.toLowerCase()] || "webmention";
+}
+
+/**
+ * Map Bridgy action types to interaction types
+ */
+function mapBridgyAction(action) {
+  const map = {
+    comment: "reply",
+    like: "like",
+    repost: "repost",
+    mention: "mention",
+  };
+  return map[action.toLowerCase()] || "mention";
+}
+
+/**
+ * Map webmention.io wm-property to interaction type
+ */
+function mapWmProperty(property) {
+  const map = {
+    "in-reply-to": "reply",
+    "like-of": "like",
+    "repost-of": "repost",
+    "bookmark-of": "bookmark",
+    "mention-of": "mention",
+  };
+  return map[property] || "mention";
+}
+
+/**
+ * Infer interaction type from URL patterns
+ */
+function inferTypeFromUrl(url) {
+  if (!url) return "mention";
+  if (url.includes("/reply") || url.includes("/comment")) return "reply";
+  if (url.includes("/like") || url.includes("/favourite")) return "like";
+  if (url.includes("/repost") || url.includes("/reblog")) return "repost";
+  return "mention";
+}
+
+/**
+ * Check if URL belongs to a known Fediverse instance
+ */
+function isFediverseUrl(url) {
+  if (!url) return false;
+  const lower = url.toLowerCase();
+  return (
+    lower.includes("mastodon.") ||
+    lower.includes("mstdn.") ||
+    lower.includes("fosstodon.") ||
+    lower.includes("pleroma.") ||
+    lower.includes("misskey.") ||
+    lower.includes("pixelfed.")
+  );
+}
+
+/**
+ * Generate a platform-specific dedup key
+ * @param {object} webmention - Classified webmention data
+ * @returns {string} Dedup key like "mastodon:123456" or "webmention:https://..."
+ */
+export function generatePlatformId(webmention) {
+  const source = webmention.source || "";
+
+  // Extract Mastodon status ID from URL
+  const mastodonMatch = source.match(
+    /\/@[^/]+\/(\d+)/,
+  );
+  if (mastodonMatch) {
+    return `mastodon:${mastodonMatch[1]}`;
+  }
+
+  // Extract Bluesky rkey from URL
+  const bskyMatch = source.match(
+    /bsky\.app\/profile\/[^/]+\/post\/([a-z0-9]+)/i,
+  );
+  if (bskyMatch) {
+    return `bluesky:${bskyMatch[1]}`;
+  }
+
+  // Fallback: hash the source URL
+  return `webmention:${source}`;
+}

package/lib/matching/syndication-map.js

@@ -0,0 +1,42 @@
+/**
+ * Syndication URL reverse lookup
+ * Maps syndication URLs back to canonical post URLs
+ * @module matching/syndication-map
+ */
+
+/**
+ * Find the canonical post URL for a syndication URL
+ * Queries the posts collection for posts with matching syndication entries
+ * @param {object} application - Indiekit application
+ * @param {string} syndicationUrl - The syndication URL to look up
+ * @returns {Promise<string|null>} Canonical post URL or null
+ */
+export async function findCanonicalPost(application, syndicationUrl) {
+  const posts = application.collections.get("posts");
+  if (!posts) return null;
+
+  const post = await posts.findOne({
+    "properties.syndication": syndicationUrl,
+  });
+
+  return post?.properties?.url || null;
+}
+
+/**
+ * Find the canonical post URL by matching against multiple possible target URLs
+ * Used when a webmention target could be either the canonical URL or a syndication URL
+ * @param {object} application - Indiekit application
+ * @param {string} targetUrl - The webmention target URL
+ * @param {string} siteUrl - The site's base URL
+ * @returns {Promise<string>} Canonical post URL (may be the target itself)
+ */
+export async function resolveCanonicalUrl(application, targetUrl, siteUrl) {
+  // If the target is already on our domain, it's likely canonical
+  if (targetUrl.startsWith(siteUrl)) {
+    return targetUrl;
+  }
+
+  // Otherwise try to find via syndication reverse lookup
+  const canonical = await findCanonicalPost(application, targetUrl);
+  return canonical || targetUrl;
+}

package/lib/notifications/bluesky.js

@@ -0,0 +1,105 @@
+/**
+ * Bluesky notification fetcher
+ * Optional direct polling of Bluesky notifications
+ * @module notifications/bluesky
+ */
+
+/**
+ * Fetch recent Bluesky notifications
+ * @param {object} options - Bluesky connection options
+ * @param {string} options.identifier - Bluesky handle or DID
+ * @param {string} options.password - App password
+ * @param {string} options.serviceUrl - PDS service URL
+ * @param {string} [options.cursor] - Pagination cursor from previous fetch
+ * @returns {Promise<object>} { items: Array, cursor: string }
+ */
+export async function fetchBlueskyNotifications(options) {
+  const { identifier, password, serviceUrl = "https://bsky.social" } = options;
+
+  if (!identifier || !password) {
+    throw new Error("Bluesky identifier and password required");
+  }
+
+  // Create session
+  const sessionResponse = await fetch(
+    `${serviceUrl}/xrpc/com.atproto.server.createSession`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ identifier, password }),
+    },
+  );
+
+  if (!sessionResponse.ok) {
+    throw new Error(
+      `Bluesky auth failed: ${sessionResponse.status}`,
+    );
+  }
+
+  const session = await sessionResponse.json();
+
+  // Fetch notifications
+  const params = new URLSearchParams({ limit: "50" });
+  if (options.cursor) params.set("cursor", options.cursor);
+
+  const notifResponse = await fetch(
+    `${serviceUrl}/xrpc/app.bsky.notification.listNotifications?${params.toString()}`,
+    {
+      headers: { Authorization: `Bearer ${session.accessJwt}` },
+    },
+  );
+
+  if (!notifResponse.ok) {
+    throw new Error(
+      `Bluesky notifications failed: ${notifResponse.status}`,
+    );
+  }
+
+  const data = await notifResponse.json();
+  const relevantReasons = new Set(["reply", "like", "repost", "mention"]);
+
+  const items = data.notifications
+    .filter((n) => relevantReasons.has(n.reason))
+    .map((notification) => ({
+      platform: "bluesky",
+      platform_id: `bluesky:${notification.uri}`,
+      type: mapNotificationReason(notification.reason),
+      author: {
+        name:
+          notification.author.displayName || notification.author.handle,
+        url: `https://bsky.app/profile/${notification.author.handle}`,
+        photo: notification.author.avatar,
+      },
+      content: notification.record?.text || null,
+      url: uriToUrl(notification.uri, notification.author.handle),
+      created_at: notification.indexedAt,
+      raw_uri: notification.uri,
+    }));
+
+  return {
+    items,
+    cursor: data.cursor,
+  };
+}
+
+function mapNotificationReason(reason) {
+  const map = {
+    reply: "reply",
+    like: "like",
+    repost: "repost",
+    mention: "mention",
+  };
+  return map[reason] || "mention";
+}
+
+/**
+ * Convert AT URI to Bluesky web URL
+ */
+function uriToUrl(uri, handle) {
+  if (!uri) return null;
+  const match = uri.match(/at:\/\/([^/]+)\/app\.bsky\.feed\.post\/(.+)/);
+  if (match) {
+    return `https://bsky.app/profile/${handle}/post/${match[2]}`;
+  }
+  return null;
+}

package/lib/notifications/mastodon.js

@@ -0,0 +1,67 @@
+/**
+ * Mastodon notification fetcher
+ * Optional direct polling of Mastodon notifications
+ * @module notifications/mastodon
+ */
+
+/**
+ * Fetch recent Mastodon notifications
+ * @param {object} options - Mastodon connection options
+ * @param {string} options.url - Mastodon instance URL
+ * @param {string} options.accessToken - Access token
+ * @param {string} [options.sinceId] - Only fetch notifications newer than this ID
+ * @returns {Promise<Array>} Normalized notification items
+ */
+export async function fetchMastodonNotifications(options) {
+  const { url, accessToken, sinceId } = options;
+
+  if (!url || !accessToken) {
+    throw new Error("Mastodon URL and access token required");
+  }
+
+  const params = new URLSearchParams({
+    limit: "40",
+    types: ["mention", "favourite", "reblog"].join(","),
+  });
+  if (sinceId) params.set("since_id", sinceId);
+
+  const response = await fetch(
+    `${url}/api/v1/notifications?${params.toString()}`,
+    {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    },
+  );
+
+  if (!response.ok) {
+    throw new Error(`Mastodon API ${response.status}: ${response.statusText}`);
+  }
+
+  const notifications = await response.json();
+
+  return notifications.map((notification) => ({
+    platform: "mastodon",
+    platform_id: `mastodon:${notification.id}`,
+    type: mapNotificationType(notification.type),
+    author: {
+      name: notification.account.display_name || notification.account.username,
+      url: notification.account.url,
+      photo: notification.account.avatar,
+    },
+    content: notification.status?.content || null,
+    url: notification.status?.url || notification.account.url,
+    status_url: notification.status?.url,
+    created_at: notification.created_at,
+    raw_id: notification.id,
+  }));
+}
+
+function mapNotificationType(type) {
+  const map = {
+    mention: "reply",
+    favourite: "like",
+    reblog: "repost",
+  };
+  return map[type] || "mention";
+}

package/lib/polling/scheduler.js

@@ -0,0 +1,178 @@
+/**
+ * Background polling scheduler
+ * Only active when direct polling is enabled via config
+ * @module polling/scheduler
+ */
+
+import { findCanonicalPost } from "../matching/syndication-map.js";
+import { upsertConversationItem } from "../storage/conversation-items.js";
+
+const POLL_INTERVAL = 5 * 60 * 1000; // 5 minutes
+let pollTimer = null;
+
+/**
+ * Start the background polling loop
+ * @param {object} application - Indiekit application
+ * @param {object} options - Plugin options
+ */
+export function startPolling(application, options) {
+  console.info("[Conversations] Starting direct polling scheduler");
+
+  // Run immediately, then on interval
+  runPollCycle(application, options).catch((error) => {
+    console.error("[Conversations] Initial poll cycle error:", error.message);
+  });
+
+  pollTimer = setInterval(() => {
+    runPollCycle(application, options).catch((error) => {
+      console.error("[Conversations] Poll cycle error:", error.message);
+    });
+  }, POLL_INTERVAL);
+}
+
+/**
+ * Stop the polling scheduler
+ */
+export function stopPolling() {
+  if (pollTimer) {
+    clearInterval(pollTimer);
+    pollTimer = null;
+    console.info("[Conversations] Polling scheduler stopped");
+  }
+}
+
+/**
+ * Run a single poll cycle
+ * @param {object} application - Indiekit application
+ * @param {object} options - Plugin options
+ */
+async function runPollCycle(application, options) {
+  const stateCollection = application.collections.get("conversation_state");
+  const state =
+    (await stateCollection.findOne({ _id: "poll_cursors" })) || {};
+
+  // Poll Mastodon
+  if (options.directPolling?.mastodon) {
+    try {
+      const { fetchMastodonNotifications } = await import(
+        "../notifications/mastodon.js"
+      );
+
+      const mastodonUrl =
+        process.env.MASTODON_URL || process.env.MASTODON_INSTANCE;
+      const mastodonToken = process.env.MASTODON_ACCESS_TOKEN;
+
+      if (mastodonUrl && mastodonToken) {
+        const notifications = await fetchMastodonNotifications({
+          url: mastodonUrl,
+          accessToken: mastodonToken,
+          sinceId: state.mastodon_since_id,
+        });
+
+        let stored = 0;
+        for (const notification of notifications) {
+          const canonicalUrl = notification.status_url
+            ? await findCanonicalPost(application, notification.status_url)
+            : null;
+
+          if (canonicalUrl) {
+            await upsertConversationItem(application, {
+              canonical_url: canonicalUrl,
+              source: "mastodon",
+              type: notification.type,
+              author: notification.author,
+              content: notification.content,
+              url: notification.url,
+              bridgy_url: null,
+              platform_id: notification.platform_id,
+            });
+            stored++;
+          }
+        }
+
+        // Update cursor
+        if (notifications.length > 0) {
+          const latestId = notifications[0].raw_id;
+          await stateCollection.findOneAndUpdate(
+            { _id: "poll_cursors" },
+            { $set: { mastodon_since_id: latestId } },
+            { upsert: true },
+          );
+        }
+
+        if (stored > 0) {
+          console.info(
+            `[Conversations] Mastodon: stored ${stored} new interactions`,
+          );
+        }
+      }
+    } catch (error) {
+      console.error(
+        "[Conversations] Mastodon poll error:",
+        error.message,
+      );
+    }
+  }
+
+  // Poll Bluesky
+  if (options.directPolling?.bluesky) {
+    try {
+      const { fetchBlueskyNotifications } = await import(
+        "../notifications/bluesky.js"
+      );
+
+      const bskyIdentifier =
+        process.env.BLUESKY_IDENTIFIER || process.env.BLUESKY_HANDLE;
+      const bskyPassword = process.env.BLUESKY_PASSWORD;
+
+      if (bskyIdentifier && bskyPassword) {
+        const result = await fetchBlueskyNotifications({
+          identifier: bskyIdentifier,
+          password: bskyPassword,
+          cursor: state.bluesky_cursor,
+        });
+
+        let stored = 0;
+        for (const notification of result.items) {
+          const canonicalUrl = notification.url
+            ? await findCanonicalPost(application, notification.url)
+            : null;
+
+          if (canonicalUrl) {
+            await upsertConversationItem(application, {
+              canonical_url: canonicalUrl,
+              source: "bluesky",
+              type: notification.type,
+              author: notification.author,
+              content: notification.content,
+              url: notification.url,
+              bridgy_url: null,
+              platform_id: notification.platform_id,
+            });
+            stored++;
+          }
+        }
+
+        // Update cursor
+        if (result.cursor) {
+          await stateCollection.findOneAndUpdate(
+            { _id: "poll_cursors" },
+            { $set: { bluesky_cursor: result.cursor } },
+            { upsert: true },
+          );
+        }
+
+        if (stored > 0) {
+          console.info(
+            `[Conversations] Bluesky: stored ${stored} new interactions`,
+          );
+        }
+      }
+    } catch (error) {
+      console.error(
+        "[Conversations] Bluesky poll error:",
+        error.message,
+      );
+    }
+  }
+}

package/lib/storage/conversation-items.js

@@ -0,0 +1,161 @@
+/**
+ * Conversation items storage
+ * MongoDB CRUD for conversation items with deduplication
+ * @module storage/conversation-items
+ */
+
+/**
+ * Get the conversation_items collection
+ * @param {object} application - Indiekit application
+ * @returns {object} MongoDB collection
+ */
+function getCollection(application) {
+  return application.collections.get("conversation_items");
+}
+
+/**
+ * Upsert a conversation item (insert or update, dedup by platform_id)
+ * @param {object} application - Indiekit application
+ * @param {object} item - Conversation item data
+ * @returns {Promise<object>} Upserted item
+ */
+export async function upsertConversationItem(application, item) {
+  const collection = getCollection(application);
+
+  const result = await collection.findOneAndUpdate(
+    {
+      canonical_url: item.canonical_url,
+      platform_id: item.platform_id,
+    },
+    {
+      $set: {
+        ...item,
+        updated_at: new Date().toISOString(),
+      },
+      $setOnInsert: {
+        received_at: new Date().toISOString(),
+      },
+    },
+    {
+      upsert: true,
+      returnDocument: "after",
+    },
+  );
+
+  return result;
+}
+
+/**
+ * Get conversation items for a canonical URL
+ * @param {object} application - Indiekit application
+ * @param {string} canonicalUrl - The canonical post URL
+ * @param {object} [options] - Query options
+ * @param {string} [options.source] - Filter by source protocol
+ * @param {string} [options.type] - Filter by interaction type
+ * @param {number} [options.limit] - Max items to return
+ * @returns {Promise<Array>} Array of conversation items
+ */
+export async function getConversationItems(
+  application,
+  canonicalUrl,
+  options = {},
+) {
+  const collection = getCollection(application);
+  const query = { canonical_url: canonicalUrl };
+
+  if (options.source) query.source = options.source;
+  if (options.type) query.type = options.type;
+
+  return collection
+    .find(query)
+    .sort({ received_at: -1 })
+    .limit(options.limit || 100)
+    .toArray();
+}
+
+/**
+ * Get conversation summaries (posts with interaction counts)
+ * @param {object} application - Indiekit application
+ * @param {object} [options] - Query options
+ * @param {number} [options.limit] - Max posts to return
+ * @param {number} [options.skip] - Number of posts to skip
+ * @returns {Promise<Array>} Array of post summaries with counts
+ */
+export async function getConversationSummaries(application, options = {}) {
+  const collection = getCollection(application);
+
+  return collection
+    .aggregate([
+      {
+        $group: {
+          _id: "$canonical_url",
+          total: { $sum: 1 },
+          replies: {
+            $sum: { $cond: [{ $eq: ["$type", "reply"] }, 1, 0] },
+          },
+          likes: {
+            $sum: { $cond: [{ $eq: ["$type", "like"] }, 1, 0] },
+          },
+          reposts: {
+            $sum: { $cond: [{ $eq: ["$type", "repost"] }, 1, 0] },
+          },
+          mentions: {
+            $sum: { $cond: [{ $eq: ["$type", "mention"] }, 1, 0] },
+          },
+          sources: { $addToSet: "$source" },
+          last_activity: { $max: "$received_at" },
+        },
+      },
+      { $sort: { last_activity: -1 } },
+      { $skip: options.skip || 0 },
+      { $limit: options.limit || 50 },
+    ])
+    .toArray();
+}
+
+/**
+ * Get total count of conversation items
+ * @param {object} application - Indiekit application
+ * @returns {Promise<number>} Total count
+ */
+export async function getConversationCount(application) {
+  const collection = getCollection(application);
+  return collection.countDocuments();
+}
+
+/**
+ * Delete conversation items for a canonical URL
+ * @param {object} application - Indiekit application
+ * @param {string} canonicalUrl - The canonical post URL
+ * @returns {Promise<number>} Number of deleted items
+ */
+export async function deleteConversationItems(application, canonicalUrl) {
+  const collection = getCollection(application);
+  const result = await collection.deleteMany({ canonical_url: canonicalUrl });
+  return result.deletedCount;
+}
+
+/**
+ * Create MongoDB indexes for conversation_items
+ * @param {object} application - Indiekit application
+ */
+export async function createIndexes(application) {
+  const collection = getCollection(application);
+
+  await collection.createIndex(
+    { canonical_url: 1, platform_id: 1 },
+    { unique: true, name: "dedup_index" },
+  );
+
+  await collection.createIndex(
+    { canonical_url: 1, received_at: -1 },
+    { name: "conversation_thread" },
+  );
+
+  await collection.createIndex(
+    { source: 1, received_at: -1 },
+    { name: "source_filter" },
+  );
+
+  console.info("[Conversations] MongoDB indexes created");
+}

package/locales/en.json

@@ -0,0 +1,24 @@
+{
+  "conversations": {
+    "title": "Conversations",
+    "list": {
+      "title": "Conversations",
+      "empty": "No conversations yet. Interactions from Mastodon, Bluesky, and the web will appear here.",
+      "total": "{{count}} interactions",
+      "lastActivity": "Last activity"
+    },
+    "detail": {
+      "title": "Conversation",
+      "empty": "No interactions for this post yet.",
+      "replies": "Replies",
+      "likes": "Likes",
+      "reposts": "Reposts",
+      "mentions": "Mentions"
+    },
+    "source": {
+      "webmention": "Webmention",
+      "mastodon": "Mastodon",
+      "bluesky": "Bluesky"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rmdes/indiekit-endpoint-conversations",
+  "version": "1.0.0",
+  "description": "Conversation aggregation endpoint for Indiekit. Unified cross-protocol conversation views with Bridgy-primary webmention ingestion and optional direct API polling.",
+  "keywords": [
+    "indiekit",
+    "indiekit-plugin",
+    "indieweb",
+    "conversations",
+    "webmention",
+    "textcasting"
+  ],
+  "homepage": "https://github.com/rmdes/indiekit-endpoint-conversations",
+  "author": {
+    "name": "Ricardo Mendes",
+    "url": "https://rmendes.net"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "lib",
+    "locales",
+    "views",
+    "index.js"
+  ],
+  "bugs": {
+    "url": "https://github.com/rmdes/indiekit-endpoint-conversations/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rmdes/indiekit-endpoint-conversations.git"
+  },
+  "dependencies": {
+    "@indiekit/error": "^1.0.0-beta.25",
+    "@indiekit/frontend": "^1.0.0-beta.25",
+    "express": "^5.0.0"
+  },
+  "optionalDependencies": {
+    "masto": "^7.0.0",
+    "@atproto/api": "^0.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/views/conversation-detail.njk

@@ -0,0 +1,116 @@
+{% extends "document.njk" %}
+
+{% block content %}
+<div class="panel">
+  <nav class="breadcrumbs" style="margin-bottom: 1rem">
+    <a href="{{ baseUrl }}">&larr; {{ __("conversations.list.title") }}</a>
+  </nav>
+
+  <h1>{{ __("conversations.detail.title") }}</h1>
+
+  {% if canonicalUrl %}
+  <p style="margin-bottom: 1.5rem">
+    <a href="{{ canonicalUrl }}" target="_blank" rel="noopener">
+      {{ canonicalUrl | replace("https://", "") | truncate(80) }}
+    </a>
+  </p>
+  {% endif %}
+
+  {% if error %}
+  <p class="badge badge--error">{{ error }}</p>
+  {% endif %}
+
+  {% if items.length > 0 %}
+  {# Summary counts #}
+  <div style="display: flex; gap: 1.5rem; margin-bottom: 2rem; flex-wrap: wrap">
+    {% if grouped.webmention.length > 0 %}
+    <span class="badge">
+      <svg style="width:12px;height:12px;vertical-align:middle;margin-right:4px" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="2" y1="12" x2="22" y2="12"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/></svg>
+      {{ grouped.webmention.length }} web
+    </span>
+    {% endif %}
+    {% if grouped.mastodon.length > 0 %}
+    <span class="badge" style="color: #6364ff">
+      <svg style="width:12px;height:12px;vertical-align:middle;margin-right:4px" viewBox="0 0 24 24" fill="#6364ff"><path d="M23.268 5.313c-.35-2.578-2.617-4.61-5.304-5.004C17.51.242 15.792 0 11.813 0h-.03c-3.98 0-4.835.242-5.288.309C3.882.692 1.496 2.518.917 5.127.64 6.412.61 7.837.661 9.143c.074 1.874.088 3.745.26 5.611.118 1.24.325 2.47.62 3.68.55 2.237 2.777 4.098 4.96 4.857 2.336.792 4.849.923 7.256.38.265-.061.527-.132.786-.213.585-.184 1.27-.39 1.774-.753a.057.057 0 0 0 .023-.043v-1.809a.052.052 0 0 0-.02-.041.053.053 0 0 0-.046-.01 20.282 20.282 0 0 1-4.709.545c-2.73 0-3.463-1.284-3.674-1.818a5.593 5.593 0 0 1-.319-1.433.053.053 0 0 1 .066-.054c1.517.363 3.072.546 4.632.546.376 0 .75 0 1.125-.01 1.57-.044 3.224-.124 4.768-.422.038-.008.077-.015.11-.024 2.435-.464 4.753-1.92 4.989-5.604.008-.145.03-1.52.03-1.67.002-.512.167-3.63-.024-5.545zm-3.748 9.195h-2.561V8.29c0-1.309-.55-1.976-1.67-1.976-1.23 0-1.846.79-1.846 2.35v3.403h-2.546V8.663c0-1.56-.617-2.35-1.848-2.35-1.112 0-1.668.668-1.668 1.977v6.218H4.822V8.102c0-1.31.337-2.35 1.011-3.12.696-.77 1.608-1.164 2.74-1.164 1.311 0 2.302.5 2.962 1.498l.638 1.06.638-1.06c.66-.999 1.65-1.498 2.96-1.498 1.13 0 2.043.395 2.74 1.164.675.77 1.012 1.81 1.012 3.12z"/></svg>
+      {{ grouped.mastodon.length }} Mastodon
+    </span>
+    {% endif %}
+    {% if grouped.bluesky.length > 0 %}
+    <span class="badge" style="color: #0085ff">
+      <svg style="width:12px;height:12px;vertical-align:middle;margin-right:4px" viewBox="0 0 568 501" fill="#0085ff"><path d="M123.121 33.664C188.241 82.553 258.281 181.68 284 234.873c25.719-53.192 95.759-152.32 160.879-201.21C491.866-1.611 568-28.906 568 57.947c0 17.346-9.945 145.713-15.778 166.555-20.275 72.453-94.155 90.933-159.875 79.748C507.222 323.8 536.444 388.56 473.333 453.32c-119.86 122.992-172.272-30.859-185.702-70.281-2.462-7.227-3.614-10.608-3.631-7.733-.017-2.875-1.169.506-3.631 7.733-13.43 39.422-65.842 193.273-185.702 70.281-63.111-64.76-33.89-129.52 80.986-149.071-65.72 11.185-139.6-7.295-159.875-79.748C9.945 203.659 0 75.291 0 57.946 0-28.906 76.135-1.612 123.121 33.664Z"/></svg>
+      {{ grouped.bluesky.length }} Bluesky
+    </span>
+    {% endif %}
+  </div>
+
+  {# Interaction list #}
+  <ul class="flow" style="list-style: none; padding: 0">
+    {% for item in items %}
+    <li style="display: flex; gap: 0.75rem; padding: 0.75rem 0; border-bottom: 1px solid var(--color-border, #e5e7eb)">
+      {# Author avatar #}
+      {% if item.author and item.author.photo %}
+      <img src="{{ item.author.photo }}" alt="" style="width: 36px; height: 36px; border-radius: 50%; flex-shrink: 0" loading="lazy" onerror="this.style.display='none'">
+      {% else %}
+      <div style="width: 36px; height: 36px; border-radius: 50%; background: #e5e7eb; flex-shrink: 0"></div>
+      {% endif %}
+
+      <div style="flex: 1; min-width: 0">
+        <div style="display: flex; align-items: center; gap: 0.5rem; flex-wrap: wrap">
+          {# Author name #}
+          {% if item.author %}
+          <strong>
+            {% if item.author.url %}
+            <a href="{{ item.author.url }}" target="_blank" rel="noopener">{{ item.author.name or "Unknown" }}</a>
+            {% else %}
+            {{ item.author.name or "Unknown" }}
+            {% endif %}
+          </strong>
+          {% endif %}
+
+          {# Protocol icon #}
+          {% if item.source == "bluesky" %}
+          <svg style="width:14px;height:14px" viewBox="0 0 568 501" fill="#0085ff" aria-label="Bluesky">
+            <path d="M123.121 33.664C188.241 82.553 258.281 181.68 284 234.873c25.719-53.192 95.759-152.32 160.879-201.21C491.866-1.611 568-28.906 568 57.947c0 17.346-9.945 145.713-15.778 166.555-20.275 72.453-94.155 90.933-159.875 79.748C507.222 323.8 536.444 388.56 473.333 453.32c-119.86 122.992-172.272-30.859-185.702-70.281-2.462-7.227-3.614-10.608-3.631-7.733-.017-2.875-1.169.506-3.631 7.733-13.43 39.422-65.842 193.273-185.702 70.281-63.111-64.76-33.89-129.52 80.986-149.071-65.72 11.185-139.6-7.295-159.875-79.748C9.945 203.659 0 75.291 0 57.946 0-28.906 76.135-1.612 123.121 33.664Z"/>
+          </svg>
+          {% elif item.source == "mastodon" %}
+          <svg style="width:14px;height:14px" viewBox="0 0 24 24" fill="#6364ff" aria-label="Mastodon">
+            <path d="M23.268 5.313c-.35-2.578-2.617-4.61-5.304-5.004C17.51.242 15.792 0 11.813 0h-.03c-3.98 0-4.835.242-5.288.309C3.882.692 1.496 2.518.917 5.127.64 6.412.61 7.837.661 9.143c.074 1.874.088 3.745.26 5.611.118 1.24.325 2.47.62 3.68.55 2.237 2.777 4.098 4.96 4.857 2.336.792 4.849.923 7.256.38.265-.061.527-.132.786-.213.585-.184 1.27-.39 1.774-.753a.057.057 0 0 0 .023-.043v-1.809a.052.052 0 0 0-.02-.041.053.053 0 0 0-.046-.01 20.282 20.282 0 0 1-4.709.545c-2.73 0-3.463-1.284-3.674-1.818a5.593 5.593 0 0 1-.319-1.433.053.053 0 0 1 .066-.054c1.517.363 3.072.546 4.632.546.376 0 .75 0 1.125-.01 1.57-.044 3.224-.124 4.768-.422.038-.008.077-.015.11-.024 2.435-.464 4.753-1.92 4.989-5.604.008-.145.03-1.52.03-1.67.002-.512.167-3.63-.024-5.545zm-3.748 9.195h-2.561V8.29c0-1.309-.55-1.976-1.67-1.976-1.23 0-1.846.79-1.846 2.35v3.403h-2.546V8.663c0-1.56-.617-2.35-1.848-2.35-1.112 0-1.668.668-1.668 1.977v6.218H4.822V8.102c0-1.31.337-2.35 1.011-3.12.696-.77 1.608-1.164 2.74-1.164 1.311 0 2.302.5 2.962 1.498l.638 1.06.638-1.06c.66-.999 1.65-1.498 2.96-1.498 1.13 0 2.043.395 2.74 1.164.675.77 1.012 1.81 1.012 3.12z"/>
+          </svg>
+          {% else %}
+          <svg style="width:14px;height:14px" viewBox="0 0 24 24" fill="none" stroke="#888" stroke-width="2" aria-label="Web">
+            <circle cx="12" cy="12" r="10"/><line x1="2" y1="12" x2="22" y2="12"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/>
+          </svg>
+          {% endif %}
+
+          {# Interaction type #}
+          <span class="badge badge--{{ item.type }}">{{ item.type }}</span>
+
+          {# Timestamp #}
+          {% if item.received_at %}
+          <time datetime="{{ item.received_at }}" style="font-size: 0.8em; color: #6b7280">
+            {{ item.received_at | date("PP") }}
+          </time>
+          {% endif %}
+        </div>
+
+        {# Content #}
+        {% if item.content %}
+        <p style="margin-top: 0.25rem">{{ item.content | truncate(300) }}</p>
+        {% endif %}
+
+        {# Link to original #}
+        {% if item.url %}
+        <a href="{{ item.url }}" target="_blank" rel="noopener" style="font-size: 0.8em">
+          View original
+        </a>
+        {% endif %}
+      </div>
+    </li>
+    {% endfor %}
+  </ul>
+
+  {% else %}
+  <p>{{ __("conversations.detail.empty") }}</p>
+  {% endif %}
+</div>
+{% endblock %}

package/views/conversations.njk

@@ -0,0 +1,64 @@
+{% extends "document.njk" %}
+
+{% block content %}
+<div class="panel">
+  <h1>{{ __("conversations.list.title") }}</h1>
+
+  {% if error %}
+  <p class="badge badge--error">{{ error }}</p>
+  {% endif %}
+
+  {% if summaries.length > 0 %}
+  <table class="table">
+    <thead>
+      <tr>
+        <th>Post</th>
+        <th>Replies</th>
+        <th>Likes</th>
+        <th>Reposts</th>
+        <th>Sources</th>
+        <th>{{ __("conversations.list.lastActivity") }}</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for summary in summaries %}
+      <tr>
+        <td>
+          <a href="{{ baseUrl }}/post?url={{ summary._id | urlencode }}">
+            {{ summary._id | replace("https://", "") | truncate(60) }}
+          </a>
+        </td>
+        <td>{{ summary.replies }}</td>
+        <td>{{ summary.likes }}</td>
+        <td>{{ summary.reposts }}</td>
+        <td>
+          {% for src in summary.sources %}
+            {% if src == "bluesky" %}
+            <svg style="width:14px;height:14px;vertical-align:middle" viewBox="0 0 568 501" fill="#0085ff" aria-label="Bluesky">
+              <path d="M123.121 33.664C188.241 82.553 258.281 181.68 284 234.873c25.719-53.192 95.759-152.32 160.879-201.21C491.866-1.611 568-28.906 568 57.947c0 17.346-9.945 145.713-15.778 166.555-20.275 72.453-94.155 90.933-159.875 79.748C507.222 323.8 536.444 388.56 473.333 453.32c-119.86 122.992-172.272-30.859-185.702-70.281-2.462-7.227-3.614-10.608-3.631-7.733-.017-2.875-1.169.506-3.631 7.733-13.43 39.422-65.842 193.273-185.702 70.281-63.111-64.76-33.89-129.52 80.986-149.071-65.72 11.185-139.6-7.295-159.875-79.748C9.945 203.659 0 75.291 0 57.946 0-28.906 76.135-1.612 123.121 33.664Z"/>
+            </svg>
+            {% elif src == "mastodon" %}
+            <svg style="width:14px;height:14px;vertical-align:middle" viewBox="0 0 24 24" fill="#6364ff" aria-label="Mastodon">
+              <path d="M23.268 5.313c-.35-2.578-2.617-4.61-5.304-5.004C17.51.242 15.792 0 11.813 0h-.03c-3.98 0-4.835.242-5.288.309C3.882.692 1.496 2.518.917 5.127.64 6.412.61 7.837.661 9.143c.074 1.874.088 3.745.26 5.611.118 1.24.325 2.47.62 3.68.55 2.237 2.777 4.098 4.96 4.857 2.336.792 4.849.923 7.256.38.265-.061.527-.132.786-.213.585-.184 1.27-.39 1.774-.753a.057.057 0 0 0 .023-.043v-1.809a.052.052 0 0 0-.02-.041.053.053 0 0 0-.046-.01 20.282 20.282 0 0 1-4.709.545c-2.73 0-3.463-1.284-3.674-1.818a5.593 5.593 0 0 1-.319-1.433.053.053 0 0 1 .066-.054c1.517.363 3.072.546 4.632.546.376 0 .75 0 1.125-.01 1.57-.044 3.224-.124 4.768-.422.038-.008.077-.015.11-.024 2.435-.464 4.753-1.92 4.989-5.604.008-.145.03-1.52.03-1.67.002-.512.167-3.63-.024-5.545zm-3.748 9.195h-2.561V8.29c0-1.309-.55-1.976-1.67-1.976-1.23 0-1.846.79-1.846 2.35v3.403h-2.546V8.663c0-1.56-.617-2.35-1.848-2.35-1.112 0-1.668.668-1.668 1.977v6.218H4.822V8.102c0-1.31.337-2.35 1.011-3.12.696-.77 1.608-1.164 2.74-1.164 1.311 0 2.302.5 2.962 1.498l.638 1.06.638-1.06c.66-.999 1.65-1.498 2.96-1.498 1.13 0 2.043.395 2.74 1.164.675.77 1.012 1.81 1.012 3.12z"/>
+            </svg>
+            {% elif src == "webmention" %}
+            <svg style="width:14px;height:14px;vertical-align:middle" viewBox="0 0 24 24" fill="none" stroke="#888" stroke-width="2" aria-label="Web">
+              <circle cx="12" cy="12" r="10"/><line x1="2" y1="12" x2="22" y2="12"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/>
+            </svg>
+            {% endif %}
+          {% endfor %}
+        </td>
+        <td>
+          {% if summary.last_activity %}
+            {{ summary.last_activity | date("PP") }}
+          {% endif %}
+        </td>
+      </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+  {% else %}
+  <p>{{ __("conversations.list.empty") }}</p>
+  {% endif %}
+</div>
+{% endblock %}