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

package/lib/feeds/jsonfeed.js

@@ -0,0 +1,43 @@
+/**
+ * JSON Feed parser
+ * @module feeds/jsonfeed
+ */
+
+import { normalizeJsonFeedItem, normalizeJsonFeedMeta } from "./normalizer.js";
+
+/**
+ * Parse JSON Feed content
+ * @param {string} content - JSON Feed content
+ * @param {string} feedUrl - URL of the feed
+ * @returns {Promise<object>} Parsed feed with metadata and items
+ */
+export async function parseJsonFeed(content, feedUrl) {
+  let feed;
+
+  try {
+    feed = typeof content === "string" ? JSON.parse(content) : content;
+  } catch (error) {
+    throw new Error(`JSON Feed parse error: ${error.message}`);
+  }
+
+  // Validate JSON Feed structure
+  if (!feed.version || !feed.version.includes("jsonfeed.org")) {
+    throw new Error("Invalid JSON Feed: missing or invalid version");
+  }
+
+  if (!Array.isArray(feed.items)) {
+    throw new TypeError("Invalid JSON Feed: items must be an array");
+  }
+
+  const normalizedMeta = normalizeJsonFeedMeta(feed, feedUrl);
+  const normalizedItems = feed.items.map((item) =>
+    normalizeJsonFeedItem(item, feedUrl),
+  );
+
+  return {
+    type: "feed",
+    url: feedUrl,
+    ...normalizedMeta,
+    items: normalizedItems,
+  };
+}

package/lib/feeds/normalizer.js

@@ -0,0 +1,586 @@
+/**
+ * Feed normalizer - converts all feed formats to jf2
+ * @module feeds/normalizer
+ */
+
+import crypto from "node:crypto";
+
+import sanitizeHtml from "sanitize-html";
+
+/**
+ * Sanitize HTML options
+ */
+const SANITIZE_OPTIONS = {
+  allowedTags: [
+    "a",
+    "abbr",
+    "b",
+    "blockquote",
+    "br",
+    "code",
+    "em",
+    "figcaption",
+    "figure",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "hr",
+    "i",
+    "img",
+    "li",
+    "ol",
+    "p",
+    "pre",
+    "s",
+    "span",
+    "strike",
+    "strong",
+    "sub",
+    "sup",
+    "table",
+    "tbody",
+    "td",
+    "th",
+    "thead",
+    "tr",
+    "u",
+    "ul",
+    "video",
+    "audio",
+    "source",
+  ],
+  allowedAttributes: {
+    a: ["href", "title", "rel"],
+    img: ["src", "alt", "title", "width", "height"],
+    video: ["src", "poster", "controls", "width", "height"],
+    audio: ["src", "controls"],
+    source: ["src", "type"],
+    "*": ["class"],
+  },
+  allowedSchemes: ["http", "https", "mailto"],
+};
+
+/**
+ * Generate unique ID for an item
+ * @param {string} feedUrl - Feed URL
+ * @param {string} itemId - Item identifier (URL or ID)
+ * @returns {string} Unique ID hash
+ */
+export function generateItemUid(feedUrl, itemId) {
+  const hash = crypto.createHash("sha256");
+  hash.update(`${feedUrl}::${itemId}`);
+  return hash.digest("hex").slice(0, 24);
+}
+
+/**
+ * Normalize RSS/Atom item from feedparser
+ * @param {object} item - Feedparser item
+ * @param {string} feedUrl - Feed URL
+ * @param {string} feedType - 'rss' or 'atom'
+ * @returns {object} Normalized jf2 item
+ */
+export function normalizeItem(item, feedUrl, feedType) {
+  const url = item.link || item.origlink || item.guid;
+  const uid = generateItemUid(feedUrl, item.guid || url || item.title);
+
+  const normalized = {
+    type: "entry",
+    uid,
+    url,
+    name: item.title || undefined,
+    published: item.pubdate ? new Date(item.pubdate).toISOString() : undefined,
+    updated: item.date ? new Date(item.date).toISOString() : undefined,
+    _source: {
+      feedUrl,
+      feedType,
+      originalId: item.guid,
+    },
+  };
+
+  // Content
+  if (item.description || item.summary) {
+    const html = item.description || item.summary;
+    normalized.content = {
+      html: sanitizeHtml(html, SANITIZE_OPTIONS),
+      text: sanitizeHtml(html, { allowedTags: [] }).trim(),
+    };
+  }
+
+  // Summary (prefer explicit summary over truncated content)
+  if (item.summary && item.description && item.summary !== item.description) {
+    normalized.summary = sanitizeHtml(item.summary, { allowedTags: [] }).trim();
+  }
+
+  // Author
+  if (item.author || item["dc:creator"]) {
+    const authorName = item.author || item["dc:creator"];
+    normalized.author = {
+      type: "card",
+      name: authorName,
+    };
+  }
+
+  // Categories/tags
+  if (item.categories && item.categories.length > 0) {
+    normalized.category = item.categories;
+  }
+
+  // Enclosures (media)
+  if (item.enclosures && item.enclosures.length > 0) {
+    for (const enclosure of item.enclosures) {
+      const mediaUrl = enclosure.url;
+      const mediaType = enclosure.type || "";
+
+      if (mediaType.startsWith("image/")) {
+        normalized.photo = normalized.photo || [];
+        normalized.photo.push(mediaUrl);
+      } else if (mediaType.startsWith("video/")) {
+        normalized.video = normalized.video || [];
+        normalized.video.push(mediaUrl);
+      } else if (mediaType.startsWith("audio/")) {
+        normalized.audio = normalized.audio || [];
+        normalized.audio.push(mediaUrl);
+      }
+    }
+  }
+
+  // Featured image from media content
+  if (item["media:content"] && item["media:content"].url) {
+    const mediaType = item["media:content"].type || "";
+    if (
+      mediaType.startsWith("image/") ||
+      item["media:content"].medium === "image"
+    ) {
+      normalized.photo = normalized.photo || [];
+      if (!normalized.photo.includes(item["media:content"].url)) {
+        normalized.photo.push(item["media:content"].url);
+      }
+    }
+  }
+
+  // Image from item.image
+  if (item.image && item.image.url) {
+    normalized.photo = normalized.photo || [];
+    if (!normalized.photo.includes(item.image.url)) {
+      normalized.photo.push(item.image.url);
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize feed metadata from feedparser
+ * @param {object} meta - Feedparser meta object
+ * @param {string} feedUrl - Feed URL
+ * @returns {object} Normalized feed metadata
+ */
+export function normalizeFeedMeta(meta, feedUrl) {
+  const normalized = {
+    name: meta.title || feedUrl,
+  };
+
+  if (meta.description) {
+    normalized.summary = meta.description;
+  }
+
+  if (meta.link) {
+    normalized.url = meta.link;
+  }
+
+  if (meta.image && meta.image.url) {
+    normalized.photo = meta.image.url;
+  }
+
+  if (meta.favicon) {
+    normalized.photo = normalized.photo || meta.favicon;
+  }
+
+  // Author/publisher
+  if (meta.author) {
+    normalized.author = {
+      type: "card",
+      name: meta.author,
+    };
+  }
+
+  // Hub for WebSub
+  if (meta.cloud && meta.cloud.href) {
+    normalized._hub = meta.cloud.href;
+  }
+
+  // Look for hub in links
+  if (meta.link && meta["atom:link"]) {
+    const links = Array.isArray(meta["atom:link"])
+      ? meta["atom:link"]
+      : [meta["atom:link"]];
+    for (const link of links) {
+      if (link["@"] && link["@"].rel === "hub") {
+        normalized._hub = link["@"].href;
+        break;
+      }
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize JSON Feed item
+ * @param {object} item - JSON Feed item
+ * @param {string} feedUrl - Feed URL
+ * @returns {object} Normalized jf2 item
+ */
+export function normalizeJsonFeedItem(item, feedUrl) {
+  const url = item.url || item.external_url;
+  const uid = generateItemUid(feedUrl, item.id || url);
+
+  const normalized = {
+    type: "entry",
+    uid,
+    url,
+    name: item.title || undefined,
+    published: item.date_published
+      ? new Date(item.date_published).toISOString()
+      : undefined,
+    updated: item.date_modified
+      ? new Date(item.date_modified).toISOString()
+      : undefined,
+    _source: {
+      feedUrl,
+      feedType: "jsonfeed",
+      originalId: item.id,
+    },
+  };
+
+  // Content
+  if (item.content_html || item.content_text) {
+    normalized.content = {};
+    if (item.content_html) {
+      normalized.content.html = sanitizeHtml(
+        item.content_html,
+        SANITIZE_OPTIONS,
+      );
+      normalized.content.text = sanitizeHtml(item.content_html, {
+        allowedTags: [],
+      }).trim();
+    } else if (item.content_text) {
+      normalized.content.text = item.content_text;
+    }
+  }
+
+  // Summary
+  if (item.summary) {
+    normalized.summary = item.summary;
+  }
+
+  // Author
+  if (item.author || item.authors) {
+    const author = item.author || (item.authors && item.authors[0]);
+    if (author) {
+      normalized.author = {
+        type: "card",
+        name: author.name,
+        url: author.url,
+        photo: author.avatar,
+      };
+    }
+  }
+
+  // Tags
+  if (item.tags && item.tags.length > 0) {
+    normalized.category = item.tags;
+  }
+
+  // Featured image
+  if (item.image) {
+    normalized.photo = [item.image];
+  }
+
+  if (item.banner_image && !normalized.photo) {
+    normalized.photo = [item.banner_image];
+  }
+
+  // Attachments
+  if (item.attachments && item.attachments.length > 0) {
+    for (const attachment of item.attachments) {
+      const mediaType = attachment.mime_type || "";
+
+      if (mediaType.startsWith("image/")) {
+        normalized.photo = normalized.photo || [];
+        normalized.photo.push(attachment.url);
+      } else if (mediaType.startsWith("video/")) {
+        normalized.video = normalized.video || [];
+        normalized.video.push(attachment.url);
+      } else if (mediaType.startsWith("audio/")) {
+        normalized.audio = normalized.audio || [];
+        normalized.audio.push(attachment.url);
+      }
+    }
+  }
+
+  // External URL
+  if (item.external_url && item.url !== item.external_url) {
+    normalized["bookmark-of"] = [item.external_url];
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize JSON Feed metadata
+ * @param {object} feed - JSON Feed object
+ * @param {string} feedUrl - Feed URL
+ * @returns {object} Normalized feed metadata
+ */
+export function normalizeJsonFeedMeta(feed, feedUrl) {
+  const normalized = {
+    name: feed.title || feedUrl,
+  };
+
+  if (feed.description) {
+    normalized.summary = feed.description;
+  }
+
+  if (feed.home_page_url) {
+    normalized.url = feed.home_page_url;
+  }
+
+  if (feed.icon) {
+    normalized.photo = feed.icon;
+  } else if (feed.favicon) {
+    normalized.photo = feed.favicon;
+  }
+
+  if (feed.author || feed.authors) {
+    const author = feed.author || (feed.authors && feed.authors[0]);
+    if (author) {
+      normalized.author = {
+        type: "card",
+        name: author.name,
+        url: author.url,
+        photo: author.avatar,
+      };
+    }
+  }
+
+  // Hub for WebSub
+  if (feed.hubs && feed.hubs.length > 0) {
+    normalized._hub = feed.hubs[0].url;
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize h-feed entry
+ * @param {object} entry - Microformats h-entry
+ * @param {string} feedUrl - Feed URL
+ * @returns {object} Normalized jf2 item
+ */
+export function normalizeHfeedItem(entry, feedUrl) {
+  const properties = entry.properties || {};
+  const url = getFirst(properties.url) || getFirst(properties.uid);
+  const uid = generateItemUid(feedUrl, getFirst(properties.uid) || url);
+
+  const normalized = {
+    type: "entry",
+    uid,
+    url,
+    _source: {
+      feedUrl,
+      feedType: "hfeed",
+      originalId: getFirst(properties.uid),
+    },
+  };
+
+  // Name/title
+  if (properties.name) {
+    const name = getFirst(properties.name);
+    // Only include name if it's not just the content
+    if (
+      name &&
+      (!properties.content || name !== getContentText(properties.content))
+    ) {
+      normalized.name = name;
+    }
+  }
+
+  // Published
+  if (properties.published) {
+    const published = getFirst(properties.published);
+    normalized.published = new Date(published).toISOString();
+  }
+
+  // Updated
+  if (properties.updated) {
+    const updated = getFirst(properties.updated);
+    normalized.updated = new Date(updated).toISOString();
+  }
+
+  // Content
+  if (properties.content) {
+    const content = getFirst(properties.content);
+    if (typeof content === "object") {
+      normalized.content = {
+        html: content.html
+          ? sanitizeHtml(content.html, SANITIZE_OPTIONS)
+          : undefined,
+        text: content.value || undefined,
+      };
+    } else if (typeof content === "string") {
+      normalized.content = { text: content };
+    }
+  }
+
+  // Summary
+  if (properties.summary) {
+    normalized.summary = getFirst(properties.summary);
+  }
+
+  // Author
+  if (properties.author) {
+    const author = getFirst(properties.author);
+    normalized.author = normalizeHcard(author);
+  }
+
+  // Categories
+  if (properties.category) {
+    normalized.category = properties.category;
+  }
+
+  // Photos
+  if (properties.photo) {
+    normalized.photo = properties.photo.map((p) =>
+      typeof p === "object" ? p.value || p.url : p,
+    );
+  }
+
+  // Videos
+  if (properties.video) {
+    normalized.video = properties.video.map((v) =>
+      typeof v === "object" ? v.value || v.url : v,
+    );
+  }
+
+  // Audio
+  if (properties.audio) {
+    normalized.audio = properties.audio.map((a) =>
+      typeof a === "object" ? a.value || a.url : a,
+    );
+  }
+
+  // Interaction types
+  if (properties["like-of"]) {
+    normalized["like-of"] = properties["like-of"];
+  }
+  if (properties["repost-of"]) {
+    normalized["repost-of"] = properties["repost-of"];
+  }
+  if (properties["bookmark-of"]) {
+    normalized["bookmark-of"] = properties["bookmark-of"];
+  }
+  if (properties["in-reply-to"]) {
+    normalized["in-reply-to"] = properties["in-reply-to"];
+  }
+
+  // RSVP
+  if (properties.rsvp) {
+    normalized.rsvp = getFirst(properties.rsvp);
+  }
+
+  // Syndication
+  if (properties.syndication) {
+    normalized.syndication = properties.syndication;
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize h-feed metadata
+ * @param {object} hfeed - h-feed microformat object
+ * @param {string} feedUrl - Feed URL
+ * @returns {object} Normalized feed metadata
+ */
+export function normalizeHfeedMeta(hfeed, feedUrl) {
+  const properties = hfeed.properties || {};
+
+  const normalized = {
+    name: getFirst(properties.name) || feedUrl,
+  };
+
+  if (properties.summary) {
+    normalized.summary = getFirst(properties.summary);
+  }
+
+  if (properties.url) {
+    normalized.url = getFirst(properties.url);
+  }
+
+  if (properties.photo) {
+    normalized.photo = getFirst(properties.photo);
+    if (typeof normalized.photo === "object") {
+      normalized.photo = normalized.photo.value || normalized.photo.url;
+    }
+  }
+
+  if (properties.author) {
+    const author = getFirst(properties.author);
+    normalized.author = normalizeHcard(author);
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize h-card author
+ * @param {object|string} hcard - h-card or author name string
+ * @returns {object} Normalized author object
+ */
+function normalizeHcard(hcard) {
+  if (typeof hcard === "string") {
+    return { type: "card", name: hcard };
+  }
+
+  if (!hcard || !hcard.properties) {
+    return;
+  }
+
+  const properties = hcard.properties;
+
+  return {
+    type: "card",
+    name: getFirst(properties.name),
+    url: getFirst(properties.url),
+    photo: getFirst(properties.photo),
+  };
+}
+
+/**
+ * Get first item from array or return the value itself
+ * @param {Array|*} value - Value or array of values
+ * @returns {*} First value or the value itself
+ */
+function getFirst(value) {
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return value;
+}
+
+/**
+ * Get text content from content property
+ * @param {Array} content - Content property array
+ * @returns {string} Text content
+ */
+function getContentText(content) {
+  const first = getFirst(content);
+  if (typeof first === "object") {
+    return first.value || first.text || "";
+  }
+  return first || "";
+}