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

package/lib/storage/read-state.js

@@ -0,0 +1,109 @@
+/**
+ * Read state tracking utilities
+ * @module storage/read-state
+ */
+
+import { markItemsRead, markItemsUnread, getUnreadCount } from "./items.js";
+
+/**
+ * Mark entries as read for a user
+ * @param {object} application - Indiekit application
+ * @param {string} channelUid - Channel UID
+ * @param {Array} entries - Entry IDs to mark as read
+ * @param {string} userId - User ID
+ * @returns {Promise<number>} Number of entries marked
+ */
+export async function markRead(application, channelUid, entries, userId) {
+  const channelsCollection = application.collections.get("microsub_channels");
+  const channel = await channelsCollection.findOne({ uid: channelUid });
+
+  if (!channel) {
+    return 0;
+  }
+
+  return markItemsRead(application, channel._id, entries, userId);
+}
+
+/**
+ * Mark entries as unread for a user
+ * @param {object} application - Indiekit application
+ * @param {string} channelUid - Channel UID
+ * @param {Array} entries - Entry IDs to mark as unread
+ * @param {string} userId - User ID
+ * @returns {Promise<number>} Number of entries marked
+ */
+export async function markUnread(application, channelUid, entries, userId) {
+  const channelsCollection = application.collections.get("microsub_channels");
+  const channel = await channelsCollection.findOne({ uid: channelUid });
+
+  if (!channel) {
+    return 0;
+  }
+
+  return markItemsUnread(application, channel._id, entries, userId);
+}
+
+/**
+ * Get unread count for a channel
+ * @param {object} application - Indiekit application
+ * @param {string} channelUid - Channel UID
+ * @param {string} userId - User ID
+ * @returns {Promise<number>} Unread count
+ */
+export async function getChannelUnreadCount(application, channelUid, userId) {
+  const channelsCollection = application.collections.get("microsub_channels");
+  const channel = await channelsCollection.findOne({ uid: channelUid });
+
+  if (!channel) {
+    return 0;
+  }
+
+  return getUnreadCount(application, channel._id, userId);
+}
+
+/**
+ * Get unread counts for all channels
+ * @param {object} application - Indiekit application
+ * @param {string} userId - User ID
+ * @returns {Promise<Map>} Map of channel UID to unread count
+ */
+export async function getAllUnreadCounts(application, userId) {
+  const channelsCollection = application.collections.get("microsub_channels");
+  const itemsCollection = application.collections.get("microsub_items");
+
+  // Aggregate unread counts per channel
+  const pipeline = [
+    {
+      $match: {
+        readBy: { $ne: userId },
+      },
+    },
+    {
+      $group: {
+        _id: "$channelId",
+        count: { $sum: 1 },
+      },
+    },
+  ];
+
+  const results = await itemsCollection.aggregate(pipeline).toArray();
+
+  // Get channel UIDs
+  const channelIds = results.map((r) => r._id);
+  const channels = await channelsCollection
+    .find({ _id: { $in: channelIds } })
+    .toArray();
+
+  const channelMap = new Map(channels.map((c) => [c._id.toString(), c.uid]));
+
+  // Build result map
+  const unreadCounts = new Map();
+  for (const result of results) {
+    const uid = channelMap.get(result._id.toString());
+    if (uid) {
+      unreadCounts.set(uid, result.count);
+    }
+  }
+
+  return unreadCounts;
+}

package/lib/utils/jf2.js

@@ -0,0 +1,170 @@
+/**
+ * jf2 utility functions for Microsub
+ * @module utils/jf2
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * Generate a unique ID for an item based on feed URL and item identifier
+ * @param {string} feedUrl - Feed URL
+ * @param {string} itemId - Item ID or URL
+ * @returns {string} Unique item ID
+ */
+export function generateItemUid(feedUrl, itemId) {
+  const input = `${feedUrl}:${itemId}`;
+  return createHash("sha256").update(input).digest("hex").slice(0, 24);
+}
+
+/**
+ * Generate a random channel UID
+ * @returns {string} 24-character random string
+ */
+export function generateChannelUid() {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  for (let index = 0; index < 24; index++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+/**
+ * Create a jf2 Item from normalized feed data
+ * @param {object} data - Normalized item data
+ * @param {object} source - Feed source metadata
+ * @returns {object} jf2 Item object
+ */
+export function createJf2Item(data, source) {
+  return {
+    type: "entry",
+    uid: data.uid,
+    url: data.url,
+    name: data.name || undefined,
+    content: data.content || undefined,
+    summary: data.summary || undefined,
+    published: data.published,
+    updated: data.updated || undefined,
+    author: data.author || undefined,
+    category: data.category || [],
+    photo: data.photo || [],
+    video: data.video || [],
+    audio: data.audio || [],
+    // Interaction types
+    "like-of": data.likeOf || [],
+    "repost-of": data.repostOf || [],
+    "bookmark-of": data.bookmarkOf || [],
+    "in-reply-to": data.inReplyTo || [],
+    // Internal properties (prefixed with _)
+    _id: data._id,
+    _is_read: data._is_read || false,
+    _source: source,
+  };
+}
+
+/**
+ * Create a jf2 Card (author/person)
+ * @param {object} data - Author data
+ * @returns {object} jf2 Card object
+ */
+export function createJf2Card(data) {
+  if (!data) return;
+
+  return {
+    type: "card",
+    name: data.name || undefined,
+    url: data.url || undefined,
+    photo: data.photo || undefined,
+  };
+}
+
+/**
+ * Create a jf2 Content object
+ * @param {string} text - Plain text content
+ * @param {string} html - HTML content
+ * @returns {object|undefined} jf2 Content object
+ */
+export function createJf2Content(text, html) {
+  if (!text && !html) return;
+
+  return {
+    text: text || stripHtml(html),
+    html: html || undefined,
+  };
+}
+
+/**
+ * Strip HTML tags from string
+ * @param {string} html - HTML string
+ * @returns {string} Plain text
+ */
+export function stripHtml(html) {
+  if (!html) return "";
+  return html.replaceAll(/<[^>]*>/g, "").trim();
+}
+
+/**
+ * Create a jf2 Feed response
+ * @param {object} options - Feed options
+ * @param {Array} options.items - Array of jf2 items
+ * @param {object} options.paging - Pagination cursors
+ * @returns {object} jf2 Feed object
+ */
+export function createJf2Feed({ items, paging }) {
+  const feed = {
+    items: items || [],
+  };
+
+  if (paging) {
+    feed.paging = {};
+    if (paging.before) feed.paging.before = paging.before;
+    if (paging.after) feed.paging.after = paging.after;
+  }
+
+  return feed;
+}
+
+/**
+ * Create a Channel response object
+ * @param {object} channel - Channel data
+ * @param {number} unreadCount - Number of unread items
+ * @returns {object} Channel object for API response
+ */
+export function createChannelResponse(channel, unreadCount = 0) {
+  return {
+    uid: channel.uid,
+    name: channel.name,
+    unread: unreadCount > 0 ? unreadCount : false,
+  };
+}
+
+/**
+ * Create a Feed response object
+ * @param {object} feed - Feed data
+ * @returns {object} Feed object for API response
+ */
+export function createFeedResponse(feed) {
+  return {
+    type: "feed",
+    url: feed.url,
+    name: feed.title || undefined,
+    photo: feed.photo || undefined,
+  };
+}
+
+/**
+ * Detect interaction type from item properties
+ * @param {object} item - jf2 item
+ * @returns {string|undefined} Interaction type
+ */
+export function detectInteractionType(item) {
+  if (item["like-of"]?.length > 0 || item.likeOf?.length > 0) return "like";
+  if (item["repost-of"]?.length > 0 || item.repostOf?.length > 0)
+    return "repost";
+  if (item["bookmark-of"]?.length > 0 || item.bookmarkOf?.length > 0)
+    return "bookmark";
+  if (item["in-reply-to"]?.length > 0 || item.inReplyTo?.length > 0)
+    return "reply";
+  if (item.checkin) return "checkin";
+  return;
+}

package/lib/utils/pagination.js

@@ -0,0 +1,157 @@
+/**
+ * Cursor-based pagination utilities for Microsub
+ * @module utils/pagination
+ */
+
+import { ObjectId } from "mongodb";
+
+/**
+ * Encode a cursor from timestamp and ID
+ * @param {Date} timestamp - Item timestamp
+ * @param {string} id - Item ID
+ * @returns {string} Base64-encoded cursor
+ */
+export function encodeCursor(timestamp, id) {
+  const data = {
+    t: timestamp instanceof Date ? timestamp.toISOString() : timestamp,
+    i: id.toString(),
+  };
+  return Buffer.from(JSON.stringify(data)).toString("base64url");
+}
+
+/**
+ * Decode a cursor string
+ * @param {string} cursor - Base64-encoded cursor
+ * @returns {object|null} Decoded cursor with timestamp and id
+ */
+export function decodeCursor(cursor) {
+  if (!cursor) return;
+
+  try {
+    const decoded = Buffer.from(cursor, "base64url").toString("utf8");
+    const data = JSON.parse(decoded);
+    return {
+      timestamp: new Date(data.t),
+      id: data.i,
+    };
+  } catch {
+    return;
+  }
+}
+
+/**
+ * Build MongoDB query for cursor-based pagination
+ * @param {object} options - Pagination options
+ * @param {string} [options.before] - Before cursor
+ * @param {string} [options.after] - After cursor
+ * @param {object} [options.baseQuery] - Base query to extend
+ * @returns {object} MongoDB query object
+ */
+export function buildPaginationQuery({ before, after, baseQuery = {} }) {
+  const query = { ...baseQuery };
+
+  if (before) {
+    const cursor = decodeCursor(before);
+    if (cursor) {
+      // Items newer than cursor (for scrolling up)
+      query.$or = [
+        { published: { $gt: cursor.timestamp } },
+        {
+          published: cursor.timestamp,
+          _id: { $gt: new ObjectId(cursor.id) },
+        },
+      ];
+    }
+  } else if (after) {
+    const cursor = decodeCursor(after);
+    if (cursor) {
+      // Items older than cursor (for scrolling down)
+      query.$or = [
+        { published: { $lt: cursor.timestamp } },
+        {
+          published: cursor.timestamp,
+          _id: { $lt: new ObjectId(cursor.id) },
+        },
+      ];
+    }
+  }
+
+  return query;
+}
+
+/**
+ * Build sort options for cursor pagination
+ * @param {string} [before] - Before cursor (ascending order)
+ * @returns {object} MongoDB sort object
+ */
+export function buildPaginationSort(before) {
+  // When using 'before', we fetch newer items, so sort ascending then reverse
+  // Otherwise, sort descending (newest first)
+  if (before) {
+    return { published: 1, _id: 1 };
+  }
+  return { published: -1, _id: -1 };
+}
+
+/**
+ * Generate pagination cursors from items
+ * @param {Array} items - Array of items
+ * @param {number} limit - Items per page
+ * @param {boolean} hasMore - Whether more items exist
+ * @param {string} [before] - Original before cursor
+ * @returns {object} Pagination object with before/after cursors
+ */
+export function generatePagingCursors(items, limit, hasMore, before) {
+  if (!items || items.length === 0) {
+    return {};
+  }
+
+  const paging = {};
+
+  // If we fetched with 'before', results are in ascending order
+  // Reverse them and set cursors accordingly
+  if (before) {
+    items.reverse();
+    // There are older items (the direction we came from)
+    paging.after = encodeCursor(items.at(-1).published, items.at(-1)._id);
+    if (hasMore) {
+      // There are newer items ahead
+      paging.before = encodeCursor(items[0].published, items[0]._id);
+    }
+  } else {
+    // Normal descending order
+    if (hasMore) {
+      // There are older items
+      paging.after = encodeCursor(items.at(-1).published, items.at(-1)._id);
+    }
+    // If we have items, there might be newer ones
+    if (items.length > 0) {
+      paging.before = encodeCursor(items[0].published, items[0]._id);
+    }
+  }
+
+  return paging;
+}
+
+/**
+ * Default pagination limit
+ */
+export const DEFAULT_LIMIT = 20;
+
+/**
+ * Maximum pagination limit
+ */
+export const MAX_LIMIT = 100;
+
+/**
+ * Parse and validate limit parameter
+ * @param {string|number} limit - Requested limit
+ * @returns {number} Validated limit
+ */
+export function parseLimit(limit) {
+  const parsed = Number.parseInt(limit, 10);
+  if (Number.isNaN(parsed) || parsed < 1) {
+    return DEFAULT_LIMIT;
+  }
+  return Math.min(parsed, MAX_LIMIT);
+}

package/lib/utils/validation.js

@@ -0,0 +1,217 @@
+/**
+ * Input validation utilities for Microsub
+ * @module utils/validation
+ */
+
+import { IndiekitError } from "@indiekit/error";
+
+/**
+ * Valid Microsub actions
+ */
+export const VALID_ACTIONS = [
+  "channels",
+  "timeline",
+  "follow",
+  "unfollow",
+  "search",
+  "preview",
+  "mute",
+  "unmute",
+  "block",
+  "unblock",
+  "events",
+];
+
+/**
+ * Valid channel methods
+ */
+export const VALID_CHANNEL_METHODS = ["delete", "order"];
+
+/**
+ * Valid timeline methods
+ */
+export const VALID_TIMELINE_METHODS = ["mark_read", "mark_unread", "remove"];
+
+/**
+ * Valid exclude types for channel filtering
+ */
+export const VALID_EXCLUDE_TYPES = [
+  "like",
+  "repost",
+  "bookmark",
+  "reply",
+  "checkin",
+];
+
+/**
+ * Validate action parameter
+ * @param {string} action - Action to validate
+ * @throws {IndiekitError} If action is invalid
+ */
+export function validateAction(action) {
+  if (!action) {
+    throw new IndiekitError("Missing required parameter: action", {
+      status: 400,
+    });
+  }
+
+  if (!VALID_ACTIONS.includes(action)) {
+    throw new IndiekitError(`Invalid action: ${action}`, {
+      status: 400,
+    });
+  }
+}
+
+/**
+ * Validate channel UID
+ * @param {string} channel - Channel UID to validate
+ * @param {boolean} [required] - Whether channel is required
+ * @throws {IndiekitError} If channel is invalid
+ */
+export function validateChannel(channel, required = true) {
+  if (required && !channel) {
+    throw new IndiekitError("Missing required parameter: channel", {
+      status: 400,
+    });
+  }
+
+  if (channel && typeof channel !== "string") {
+    throw new IndiekitError("Invalid channel parameter", {
+      status: 400,
+    });
+  }
+}
+
+/**
+ * Validate URL parameter
+ * @param {string} url - URL to validate
+ * @param {string} [paramName] - Parameter name for error message
+ * @param parameterName
+ * @throws {IndiekitError} If URL is invalid
+ */
+export function validateUrl(url, parameterName = "url") {
+  if (!url) {
+    throw new IndiekitError(`Missing required parameter: ${parameterName}`, {
+      status: 400,
+    });
+  }
+
+  try {
+    new URL(url);
+  } catch {
+    throw new IndiekitError(`Invalid URL: ${url}`, {
+      status: 400,
+    });
+  }
+}
+
+/**
+ * Validate entry/entries parameter
+ * @param {string|Array} entry - Entry ID(s) to validate
+ * @returns {Array} Array of entry IDs
+ * @throws {IndiekitError} If entry is invalid
+ */
+export function validateEntries(entry) {
+  if (!entry) {
+    throw new IndiekitError("Missing required parameter: entry", {
+      status: 400,
+    });
+  }
+
+  // Normalize to array
+  const entries = Array.isArray(entry) ? entry : [entry];
+
+  if (entries.length === 0) {
+    throw new IndiekitError("Entry parameter cannot be empty", {
+      status: 400,
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Validate channel name
+ * @param {string} name - Channel name to validate
+ * @throws {IndiekitError} If name is invalid
+ */
+export function validateChannelName(name) {
+  if (!name || typeof name !== "string") {
+    throw new IndiekitError("Missing required parameter: name", {
+      status: 400,
+    });
+  }
+
+  if (name.length > 100) {
+    throw new IndiekitError("Channel name must be 100 characters or less", {
+      status: 400,
+    });
+  }
+}
+
+/**
+ * Validate exclude types array
+ * @param {Array} types - Array of exclude types
+ * @returns {Array} Validated exclude types
+ */
+export function validateExcludeTypes(types) {
+  if (!types || !Array.isArray(types)) {
+    return [];
+  }
+
+  return types.filter((type) => VALID_EXCLUDE_TYPES.includes(type));
+}
+
+/**
+ * Validate regex pattern
+ * @param {string} pattern - Regex pattern to validate
+ * @returns {string|null} Valid pattern or null
+ */
+export function validateExcludeRegex(pattern) {
+  if (!pattern || typeof pattern !== "string") {
+    return;
+  }
+
+  try {
+    new RegExp(pattern);
+    return pattern;
+  } catch {
+    return;
+  }
+}
+
+/**
+ * Parse array parameter from request
+ * Handles both array[] and array[0], array[1] formats
+ * @param {object} body - Request body
+ * @param {string} paramName - Parameter name
+ * @param parameterName
+ * @returns {Array} Parsed array
+ */
+export function parseArrayParameter(body, parameterName) {
+  // Direct array
+  if (Array.isArray(body[parameterName])) {
+    return body[parameterName];
+  }
+
+  // Single value
+  if (body[parameterName]) {
+    return [body[parameterName]];
+  }
+
+  // Indexed values (param[0], param[1], ...)
+  const result = [];
+  let index = 0;
+  while (body[`${parameterName}[${index}]`] !== undefined) {
+    result.push(body[`${parameterName}[${index}]`]);
+    index++;
+  }
+
+  // Array notation (param[])
+  if (body[`${parameterName}[]`]) {
+    const values = body[`${parameterName}[]`];
+    return Array.isArray(values) ? values : [values];
+  }
+
+  return result;
+}