@rmdes/indiekit-endpoint-microsub 1.0.0-beta.1

package/lib/controllers/follow.js

@@ -0,0 +1,108 @@
+/**
+ * Follow/unfollow controller
+ * @module controllers/follow
+ */
+
+import { IndiekitError } from "@indiekit/error";
+
+import { refreshFeedNow } from "../polling/scheduler.js";
+import { getChannel } from "../storage/channels.js";
+import {
+  createFeed,
+  deleteFeed,
+  getFeedsForChannel,
+} from "../storage/feeds.js";
+import { createFeedResponse } from "../utils/jf2.js";
+import { validateChannel, validateUrl } from "../utils/validation.js";
+
+/**
+ * List followed feeds for a channel
+ * GET ?action=follow&channel=<uid>
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function list(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { channel } = request.query;
+
+  validateChannel(channel);
+
+  const channelDocument = await getChannel(application, channel, userId);
+  if (!channelDocument) {
+    throw new IndiekitError("Channel not found", { status: 404 });
+  }
+
+  const feeds = await getFeedsForChannel(application, channelDocument._id);
+  const items = feeds.map((feed) => createFeedResponse(feed));
+
+  response.json({ items });
+}
+
+/**
+ * Follow a feed URL
+ * POST ?action=follow
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function follow(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { channel, url } = request.body;
+
+  validateChannel(channel);
+  validateUrl(url);
+
+  const channelDocument = await getChannel(application, channel, userId);
+  if (!channelDocument) {
+    throw new IndiekitError("Channel not found", { status: 404 });
+  }
+
+  // Create feed subscription
+  const feed = await createFeed(application, {
+    channelId: channelDocument._id,
+    url,
+    title: undefined, // Will be populated on first fetch
+    photo: undefined,
+  });
+
+  // Trigger immediate fetch in background (don't await)
+  refreshFeedNow(application, feed._id).catch((error) => {
+    console.error(`[Microsub] Error fetching new feed ${url}:`, error.message);
+  });
+
+  // TODO: Attempt WebSub subscription
+
+  response.status(201).json(createFeedResponse(feed));
+}
+
+/**
+ * Unfollow a feed URL
+ * POST ?action=unfollow
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function unfollow(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { channel, url } = request.body;
+
+  validateChannel(channel);
+  validateUrl(url);
+
+  const channelDocument = await getChannel(application, channel, userId);
+  if (!channelDocument) {
+    throw new IndiekitError("Channel not found", { status: 404 });
+  }
+
+  const deleted = await deleteFeed(application, channelDocument._id, url);
+  if (!deleted) {
+    throw new IndiekitError("Feed not found", { status: 404 });
+  }
+
+  // TODO: Cancel WebSub subscription if active
+
+  response.json({ result: "ok" });
+}
+
+export const followController = { list, follow, unfollow };

package/lib/controllers/microsub.js

@@ -0,0 +1,138 @@
+/**
+ * Main Microsub action router
+ * @module controllers/microsub
+ */
+
+import { IndiekitError } from "@indiekit/error";
+
+import { validateAction } from "../utils/validation.js";
+
+import { list as listBlocked, block, unblock } from "./block.js";
+import { list as listChannels, action as channelAction } from "./channels.js";
+import { stream as eventsStream } from "./events.js";
+import { list as listFollows, follow, unfollow } from "./follow.js";
+import { list as listMuted, mute, unmute } from "./mute.js";
+import { get as getPreview, preview } from "./preview.js";
+import { discover, search } from "./search.js";
+import { get as getTimeline, action as timelineAction } from "./timeline.js";
+
+/**
+ * Route GET requests to appropriate action handler
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ * @param {Function} next - Express next function
+ */
+export async function get(request, response, next) {
+  try {
+    const { action } = request.query;
+    validateAction(action);
+
+    switch (action) {
+      case "channels": {
+        return listChannels(request, response);
+      }
+
+      case "timeline": {
+        return getTimeline(request, response);
+      }
+
+      case "follow": {
+        return listFollows(request, response);
+      }
+
+      case "preview": {
+        return getPreview(request, response);
+      }
+
+      case "mute": {
+        return listMuted(request, response);
+      }
+
+      case "block": {
+        return listBlocked(request, response);
+      }
+
+      case "events": {
+        return eventsStream(request, response);
+      }
+
+      case "search": {
+        // Search is typically POST, but GET is allowed for feed discovery
+        return discover(request, response);
+      }
+
+      default: {
+        throw new IndiekitError(`Unsupported GET action: ${action}`, {
+          status: 400,
+        });
+      }
+    }
+  } catch (error) {
+    next(error);
+  }
+}
+
+/**
+ * Route POST requests to appropriate action handler
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ * @param {Function} next - Express next function
+ */
+export async function post(request, response, next) {
+  try {
+    const action = request.body.action || request.query.action;
+    validateAction(action);
+
+    switch (action) {
+      case "channels": {
+        return channelAction(request, response);
+      }
+
+      case "timeline": {
+        return timelineAction(request, response);
+      }
+
+      case "follow": {
+        return follow(request, response);
+      }
+
+      case "unfollow": {
+        return unfollow(request, response);
+      }
+
+      case "search": {
+        return search(request, response);
+      }
+
+      case "preview": {
+        return preview(request, response);
+      }
+
+      case "mute": {
+        return mute(request, response);
+      }
+
+      case "unmute": {
+        return unmute(request, response);
+      }
+
+      case "block": {
+        return block(request, response);
+      }
+
+      case "unblock": {
+        return unblock(request, response);
+      }
+
+      default: {
+        throw new IndiekitError(`Unsupported POST action: ${action}`, {
+          status: 400,
+        });
+      }
+    }
+  } catch (error) {
+    next(error);
+  }
+}
+
+export const microsubController = { get, post };

package/lib/controllers/mute.js

@@ -0,0 +1,124 @@
+/**
+ * Mute controller
+ * @module controllers/mute
+ */
+
+import { IndiekitError } from "@indiekit/error";
+
+import { validateChannel, validateUrl } from "../utils/validation.js";
+
+/**
+ * Get muted collection
+ * @param {object} application - Indiekit application
+ * @returns {object} MongoDB collection
+ */
+function getCollection(application) {
+  return application.collections.get("microsub_muted");
+}
+
+/**
+ * List muted URLs for a channel
+ * GET ?action=mute&channel=<uid>
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function list(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { channel } = request.query;
+
+  // Channel can be "global" or a specific channel UID
+  const isGlobal = channel === "global";
+
+  const collection = getCollection(application);
+  const filter = { userId };
+
+  if (!isGlobal && channel) {
+    // Get channel-specific mutes
+    const channelsCollection = application.collections.get("microsub_channels");
+    const channelDocument = await channelsCollection.findOne({ uid: channel });
+    if (channelDocument) {
+      filter.channelId = channelDocument._id;
+    }
+  }
+  // For global mutes, we query without channelId (matches all channels)
+
+  // eslint-disable-next-line unicorn/no-array-callback-reference -- filter is MongoDB query object
+  const muted = await collection.find(filter).toArray();
+  const items = muted.map((m) => ({ url: m.url }));
+
+  response.json({ items });
+}
+
+/**
+ * Mute a URL
+ * POST ?action=mute
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function mute(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { channel, url } = request.body;
+
+  validateUrl(url);
+
+  const collection = getCollection(application);
+  const isGlobal = channel === "global" || !channel;
+
+  let channelId;
+  if (!isGlobal) {
+    validateChannel(channel);
+    const channelsCollection = application.collections.get("microsub_channels");
+    const channelDocument = await channelsCollection.findOne({ uid: channel });
+    if (!channelDocument) {
+      throw new IndiekitError("Channel not found", { status: 404 });
+    }
+    channelId = channelDocument._id;
+  }
+
+  // Check if already muted
+  const existing = await collection.findOne({ userId, channelId, url });
+  if (!existing) {
+    await collection.insertOne({
+      userId,
+      channelId,
+      url,
+      createdAt: new Date(),
+    });
+  }
+
+  response.json({ result: "ok" });
+}
+
+/**
+ * Unmute a URL
+ * POST ?action=unmute
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function unmute(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { channel, url } = request.body;
+
+  validateUrl(url);
+
+  const collection = getCollection(application);
+  const isGlobal = channel === "global" || !channel;
+
+  let channelId;
+  if (!isGlobal) {
+    const channelsCollection = application.collections.get("microsub_channels");
+    const channelDocument = await channelsCollection.findOne({ uid: channel });
+    if (channelDocument) {
+      channelId = channelDocument._id;
+    }
+  }
+
+  await collection.deleteOne({ userId, channelId, url });
+
+  response.json({ result: "ok" });
+}
+
+export const muteController = { list, mute, unmute };

package/lib/controllers/preview.js

@@ -0,0 +1,67 @@
+/**
+ * Preview controller
+ * @module controllers/preview
+ */
+
+import { IndiekitError } from "@indiekit/error";
+
+import { fetchAndParseFeed } from "../feeds/fetcher.js";
+import { validateUrl } from "../utils/validation.js";
+
+const MAX_PREVIEW_ITEMS = 10;
+
+/**
+ * Fetch and preview a feed
+ * @param {string} url - Feed URL
+ * @returns {Promise<object>} Preview response
+ */
+async function fetchPreview(url) {
+  try {
+    const parsed = await fetchAndParseFeed(url);
+
+    // Return feed metadata and sample items
+    return {
+      type: "feed",
+      url: parsed.url,
+      name: parsed.name,
+      photo: parsed.photo,
+      items: parsed.items.slice(0, MAX_PREVIEW_ITEMS),
+    };
+  } catch (error) {
+    throw new IndiekitError(`Failed to preview feed: ${error.message}`, {
+      status: 502,
+    });
+  }
+}
+
+/**
+ * Preview a feed URL (GET)
+ * GET ?action=preview&url=<feed>
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function get(request, response) {
+  const { url } = request.query;
+
+  validateUrl(url);
+
+  const preview = await fetchPreview(url);
+  response.json(preview);
+}
+
+/**
+ * Preview a feed URL (POST)
+ * POST ?action=preview
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function preview(request, response) {
+  const { url } = request.body;
+
+  validateUrl(url);
+
+  const previewData = await fetchPreview(url);
+  response.json(previewData);
+}
+
+export const previewController = { get, preview };

package/lib/controllers/reader.js

@@ -0,0 +1,218 @@
+/**
+ * Reader UI controller
+ * @module controllers/reader
+ */
+
+import {
+  getChannels,
+  getChannel,
+  createChannel,
+  updateChannelSettings,
+} from "../storage/channels.js";
+import { getTimelineItems, getItemById } from "../storage/items.js";
+import {
+  validateChannelName,
+  validateExcludeTypes,
+  validateExcludeRegex,
+} from "../utils/validation.js";
+
+/**
+ * Reader index - redirect to channels
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function index(request, response) {
+  response.redirect(`${request.baseUrl}/channels`);
+}
+
+/**
+ * List channels
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function channels(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+
+  const channelList = await getChannels(application, userId);
+
+  response.render("reader", {
+    title: request.__("microsub.reader.title"),
+    channels: channelList,
+  });
+}
+
+/**
+ * New channel form
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function newChannel(request, response) {
+  response.render("channel-new", {
+    title: request.__("microsub.channels.new"),
+  });
+}
+
+/**
+ * Create channel
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function createChannelAction(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { name } = request.body;
+
+  validateChannelName(name);
+
+  await createChannel(application, { name, userId });
+
+  response.redirect(`${request.baseUrl}/channels`);
+}
+
+/**
+ * View channel timeline
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function channel(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { uid } = request.params;
+  const { before, after } = request.query;
+
+  const channelDocument = await getChannel(application, uid, userId);
+  if (!channelDocument) {
+    return response.status(404).render("404");
+  }
+
+  const timeline = await getTimelineItems(application, channelDocument._id, {
+    before,
+    after,
+    userId,
+  });
+
+  response.render("channel", {
+    title: channelDocument.name,
+    channel: channelDocument,
+    items: timeline.items,
+    paging: timeline.paging,
+  });
+}
+
+/**
+ * Channel settings form
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function settings(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { uid } = request.params;
+
+  const channelDocument = await getChannel(application, uid, userId);
+  if (!channelDocument) {
+    return response.status(404).render("404");
+  }
+
+  response.render("settings", {
+    title: request.__("microsub.settings.title", {
+      channel: channelDocument.name,
+    }),
+    channel: channelDocument,
+  });
+}
+
+/**
+ * Update channel settings
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function updateSettings(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { uid } = request.params;
+  const { excludeTypes, excludeRegex } = request.body;
+
+  const channelDocument = await getChannel(application, uid, userId);
+  if (!channelDocument) {
+    return response.status(404).render("404");
+  }
+
+  const validatedTypes = validateExcludeTypes(
+    Array.isArray(excludeTypes) ? excludeTypes : [excludeTypes].filter(Boolean),
+  );
+  const validatedRegex = validateExcludeRegex(excludeRegex);
+
+  await updateChannelSettings(
+    application,
+    uid,
+    {
+      excludeTypes: validatedTypes,
+      excludeRegex: validatedRegex,
+    },
+    userId,
+  );
+
+  response.redirect(`${request.baseUrl}/channels/${uid}`);
+}
+
+/**
+ * View single item
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function item(request, response) {
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+  const { id } = request.params;
+
+  const itemDocument = await getItemById(application, id, userId);
+  if (!itemDocument) {
+    return response.status(404).render("404");
+  }
+
+  response.render("item", {
+    title: itemDocument.name || "Item",
+    item: itemDocument,
+  });
+}
+
+/**
+ * Compose response form
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function compose(request, response) {
+  const { replyTo, likeOf, repostOf } = request.query;
+
+  response.render("compose", {
+    title: request.__("microsub.compose.title"),
+    replyTo,
+    likeOf,
+    repostOf,
+  });
+}
+
+/**
+ * Submit composed response
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function submitCompose(request, response) {
+  // TODO: Submit via Micropub
+  response.redirect(`${request.baseUrl}/channels`);
+}
+
+export const readerController = {
+  index,
+  channels,
+  newChannel,
+  createChannel: createChannelAction,
+  channel,
+  settings,
+  updateSettings,
+  item,
+  compose,
+  submitCompose,
+};