@molecule/api-feed-rss 1.0.0

package/dist/serializeRss2.js

@@ -0,0 +1,231 @@
+/**
+ * RSS 2.0 serializer — accepts a {@link Feed} structure and returns a
+ * complete RSS 2.0 XML document string.
+ *
+ * @module
+ */
+import { escapeAttr, escapeUrl, escapeXml, wrapCdata } from './escape.js';
+import { assertFeedShape, indent, looksLikeHttpUrl, toHhMmSs, toRfc822 } from './utilities.js';
+const ATOM_NS = 'http://www.w3.org/2005/Atom';
+const CONTENT_NS = 'http://purl.org/rss/1.0/modules/content/';
+const ITUNES_NS = 'http://www.itunes.com/dtds/podcast-1.0.dtd';
+/**
+ * Serialize an item to RSS 2.0 `<item>` XML.
+ *
+ * @param item - Feed item.
+ * @param podcastMode - Whether channel-level iTunes metadata is present.
+ * @param pretty - Whether to pretty-print children.
+ * @returns `<item>...</item>` XML string.
+ */
+function renderItem(item, podcastMode, pretty) {
+    const lines = [];
+    lines.push(`<title>${escapeXml(item.title)}</title>`);
+    if (item.link) {
+        lines.push(`<link>${escapeUrl(item.link)}</link>`);
+    }
+    // <guid isPermaLink="true|false">id</guid>
+    const isPermalink = looksLikeHttpUrl(item.id);
+    lines.push(`<guid isPermaLink="${isPermalink ? 'true' : 'false'}">${escapeXml(item.id)}</guid>`);
+    const pubDate = toRfc822(item.publishedAt);
+    if (pubDate) {
+        lines.push(`<pubDate>${escapeXml(pubDate)}</pubDate>`);
+    }
+    // RSS 2.0 <author> per spec is `email@example.com (Display Name)`.
+    if (item.authors && item.authors.length > 0) {
+        const author = item.authors[0];
+        if (author.email && author.name) {
+            lines.push(`<author>${escapeXml(`${author.email} (${author.name})`)}</author>`);
+        }
+        else if (author.email) {
+            lines.push(`<author>${escapeXml(author.email)}</author>`);
+        }
+        else if (author.name) {
+            // No email — fall back to dc:creator below; RSS spec disallows
+            // <author> without an email but consumers tolerate it. We emit
+            // dc:creator instead to stay spec-clean.
+            lines.push(`<dc:creator>${escapeXml(author.name)}</dc:creator>`);
+        }
+    }
+    if (item.categories) {
+        for (const cat of item.categories) {
+            lines.push(`<category>${escapeXml(cat)}</category>`);
+        }
+    }
+    if (item.summary !== undefined) {
+        // Summary is HTML-or-text; CDATA-wrap to preserve markup safely.
+        lines.push(`<description>${wrapCdata(item.summary)}</description>`);
+    }
+    if (item.content !== undefined) {
+        if (item.contentIsHtml === false) {
+            // Plain text — escape and put in description-equivalent slot.
+            // RSS 2.0 has no `<content>` element; use <content:encoded> with text
+            // wrapped in CDATA so reader UIs treat it as preformatted.
+            lines.push(`<content:encoded>${wrapCdata(item.content)}</content:encoded>`);
+        }
+        else {
+            lines.push(`<content:encoded>${wrapCdata(item.content)}</content:encoded>`);
+        }
+    }
+    if (item.enclosures) {
+        for (const enc of item.enclosures) {
+            const url = escapeAttr(enc.url);
+            const type = escapeAttr(enc.type ?? 'application/octet-stream');
+            const length = Number.isFinite(enc.length) ? String(enc.length) : '0';
+            lines.push(`<enclosure url="${url}" length="${escapeAttr(length)}" type="${type}"/>`);
+        }
+    }
+    if (podcastMode && item.itunes) {
+        const it = item.itunes;
+        if (it.author)
+            lines.push(`<itunes:author>${escapeXml(it.author)}</itunes:author>`);
+        const dur = toHhMmSs(it.durationSeconds);
+        if (dur)
+            lines.push(`<itunes:duration>${escapeXml(dur)}</itunes:duration>`);
+        if (it.explicit !== undefined) {
+            lines.push(`<itunes:explicit>${it.explicit ? 'true' : 'false'}</itunes:explicit>`);
+        }
+        if (it.imageUrl) {
+            lines.push(`<itunes:image href="${escapeAttr(it.imageUrl)}"/>`);
+        }
+        if (it.episode !== undefined && Number.isFinite(it.episode)) {
+            lines.push(`<itunes:episode>${escapeXml(String(it.episode))}</itunes:episode>`);
+        }
+        if (it.season !== undefined && Number.isFinite(it.season)) {
+            lines.push(`<itunes:season>${escapeXml(String(it.season))}</itunes:season>`);
+        }
+        if (it.summary) {
+            lines.push(`<itunes:summary>${wrapCdata(it.summary)}</itunes:summary>`);
+        }
+    }
+    const inner = lines.join(pretty ? '\n' : '');
+    if (!pretty)
+        return `<item>${inner}</item>`;
+    return `<item>\n${indent(inner, 2)}\n</item>`;
+}
+/**
+ * Serialize a {@link Feed} to a complete RSS 2.0 XML document.
+ *
+ * The output is valid RSS 2.0 — declares the `dc`, `content`, and `atom`
+ * namespaces always, plus `itunes` when {@link Feed.itunes} is present.
+ *
+ * **All user-supplied content is escaped** — text fields run through
+ * {@link escapeXml}, attribute values through {@link escapeAttr}, URLs
+ * through {@link escapeUrl} (which neutralizes `javascript:` URIs), and
+ * HTML-bearing fields (`description`, `content:encoded`,
+ * `itunes:summary`) are CDATA-wrapped via {@link wrapCdata} with
+ * `]]>` splitting.
+ *
+ * @example
+ * ```ts
+ * import { serializeRss2 } from '@molecule/api-feed-rss'
+ *
+ * const xml = serializeRss2({
+ *   title: 'My Blog',
+ *   link: 'https://example.com',
+ *   description: 'Posts about software',
+ *   feedUrl: 'https://example.com/feed.xml',
+ *   items: [
+ *     {
+ *       id: 'https://example.com/posts/hello',
+ *       title: 'Hello, world!',
+ *       link: 'https://example.com/posts/hello',
+ *       publishedAt: new Date(),
+ *       content: '<p>First post.</p>',
+ *     },
+ *   ],
+ * })
+ * ```
+ *
+ * @param feed - The feed structure to serialize.
+ * @param options - See {@link SerializeRss2Options}.
+ * @returns Complete RSS 2.0 XML document string.
+ * @throws {FeedSerializeError} when required fields are missing.
+ */
+export function serializeRss2(feed, options = {}) {
+    assertFeedShape(feed, 'rss-2.0');
+    const pretty = options.pretty !== false;
+    const xmlDecl = options.xmlDeclaration ?? '<?xml version="1.0" encoding="UTF-8"?>';
+    const podcastMode = feed.itunes !== undefined;
+    const nsAttrs = [
+        `version="2.0"`,
+        `xmlns:dc="http://purl.org/dc/elements/1.1/"`,
+        `xmlns:content="${CONTENT_NS}"`,
+        `xmlns:atom="${ATOM_NS}"`,
+    ];
+    if (podcastMode)
+        nsAttrs.push(`xmlns:itunes="${ITUNES_NS}"`);
+    const channel = [];
+    channel.push(`<title>${escapeXml(feed.title)}</title>`);
+    channel.push(`<link>${escapeUrl(feed.link)}</link>`);
+    channel.push(`<description>${escapeXml(feed.description)}</description>`);
+    if (feed.language)
+        channel.push(`<language>${escapeXml(feed.language)}</language>`);
+    if (feed.copyright)
+        channel.push(`<copyright>${escapeXml(feed.copyright)}</copyright>`);
+    if (feed.authors && feed.authors.length > 0) {
+        const a = feed.authors[0];
+        if (a.email && a.name) {
+            channel.push(`<managingEditor>${escapeXml(`${a.email} (${a.name})`)}</managingEditor>`);
+        }
+        else if (a.email) {
+            channel.push(`<managingEditor>${escapeXml(a.email)}</managingEditor>`);
+        }
+    }
+    const lastBuild = toRfc822(feed.updatedAt);
+    if (lastBuild)
+        channel.push(`<lastBuildDate>${escapeXml(lastBuild)}</lastBuildDate>`);
+    if (feed.feedUrl) {
+        channel.push(`<atom:link href="${escapeAttr(feed.feedUrl)}" rel="self" type="application/rss+xml"/>`);
+    }
+    if (feed.imageUrl) {
+        if (pretty) {
+            channel.push(`<image>\n  <url>${escapeUrl(feed.imageUrl)}</url>\n  <title>${escapeXml(feed.title)}</title>\n  <link>${escapeUrl(feed.link)}</link>\n</image>`);
+        }
+        else {
+            channel.push(`<image><url>${escapeUrl(feed.imageUrl)}</url><title>${escapeXml(feed.title)}</title><link>${escapeUrl(feed.link)}</link></image>`);
+        }
+    }
+    if (feed.categories) {
+        for (const cat of feed.categories) {
+            channel.push(`<category>${escapeXml(cat)}</category>`);
+        }
+    }
+    if (podcastMode && feed.itunes) {
+        const it = feed.itunes;
+        if (it.author)
+            channel.push(`<itunes:author>${escapeXml(it.author)}</itunes:author>`);
+        if (it.summary)
+            channel.push(`<itunes:summary>${wrapCdata(it.summary)}</itunes:summary>`);
+        if (it.explicit !== undefined) {
+            channel.push(`<itunes:explicit>${it.explicit ? 'true' : 'false'}</itunes:explicit>`);
+        }
+        if (it.imageUrl) {
+            channel.push(`<itunes:image href="${escapeAttr(it.imageUrl)}"/>`);
+        }
+        if (it.type) {
+            channel.push(`<itunes:type>${escapeXml(it.type)}</itunes:type>`);
+        }
+        if (it.owner) {
+            const ownerInner = `<itunes:name>${escapeXml(it.owner.name)}</itunes:name><itunes:email>${escapeXml(it.owner.email)}</itunes:email>`;
+            if (pretty) {
+                channel.push(`<itunes:owner>\n  <itunes:name>${escapeXml(it.owner.name)}</itunes:name>\n  <itunes:email>${escapeXml(it.owner.email)}</itunes:email>\n</itunes:owner>`);
+            }
+            else {
+                channel.push(`<itunes:owner>${ownerInner}</itunes:owner>`);
+            }
+        }
+        if (it.categories) {
+            for (const cat of it.categories) {
+                channel.push(`<itunes:category text="${escapeAttr(cat)}"/>`);
+            }
+        }
+    }
+    for (const item of feed.items) {
+        channel.push(renderItem(item, podcastMode, pretty));
+    }
+    if (!pretty) {
+        return `${xmlDecl}<rss ${nsAttrs.join(' ')}><channel>${channel.join('')}</channel></rss>`;
+    }
+    const channelBody = channel.join('\n');
+    return `${xmlDecl}\n<rss ${nsAttrs.join(' ')}>\n  <channel>\n${indent(channelBody, 4)}\n  </channel>\n</rss>`;
+}

package/dist/types.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Output format discriminator for {@link serializeFeed} and the
+ * {@link createFeedHandler} HTTP handler.
+ *
+ * - `rss-2.0` — RSS 2.0 XML, served as `application/rss+xml`.
+ * - `atom-1.0` — Atom 1.0 XML, served as `application/atom+xml`.
+ * - `json-feed` — JSON Feed 1.1, served as `application/feed+json`.
+ */
+export type FeedOutputFormat = 'rss-2.0' | 'atom-1.0' | 'json-feed';
+/**
+ * Optional iTunes podcast metadata for an item.
+ *
+ * When supplied AND the channel-level {@link Feed.itunes} block is also
+ * present, the RSS 2.0 serializer emits the iTunes podcast namespace
+ * (`xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd"`) and per-item
+ * `<itunes:duration>`, `<itunes:author>`, `<itunes:explicit>`,
+ * `<itunes:image>`, `<itunes:episode>`, `<itunes:season>`, `<itunes:summary>`
+ * elements.
+ */
+export interface FeedItemItunes {
+    /** Episode duration in seconds. Serialized as HH:MM:SS. */
+    durationSeconds?: number;
+    /** Episode artwork URL. Emitted as `<itunes:image href="...">`. */
+    imageUrl?: string;
+    /** Author display name (overrides item-level `<itunes:author>`). */
+    author?: string;
+    /** Whether the episode contains explicit material. */
+    explicit?: boolean;
+    /** Episode number within the season / series. */
+    episode?: number;
+    /** Season number. */
+    season?: number;
+    /** Plain-text episode summary (`<itunes:summary>`). */
+    summary?: string;
+}
+/**
+ * Channel-level iTunes podcast metadata.
+ *
+ * Trigger condition: when present (even as `{}`), the RSS 2.0 serializer
+ * declares the iTunes namespace and emits the configured `<itunes:*>`
+ * channel elements.
+ */
+export interface FeedChannelItunes {
+    /** Show author / host name (`<itunes:author>`). */
+    author?: string;
+    /** Show owner contact info — both fields required by Apple Podcasts. */
+    owner?: {
+        /** Owner's display name. */
+        name: string;
+        /** Owner's email address. */
+        email: string;
+    };
+    /** Show artwork URL (`<itunes:image href="...">`). 1400x1400+ recommended. */
+    imageUrl?: string;
+    /** Whether the show contains explicit material. */
+    explicit?: boolean;
+    /**
+     * iTunes show categories — top-level only (subcategories not currently
+     * supported by this serializer).
+     */
+    categories?: string[];
+    /** Long-form show summary. */
+    summary?: string;
+    /** Show type — `episodic` (default) or `serial`. */
+    type?: 'episodic' | 'serial';
+}
+/**
+ * Media enclosure (podcast audio, video, image, etc.).
+ */
+export interface FeedItemEnclosure {
+    /** Direct URL to the media resource. Required. */
+    url: string;
+    /**
+     * MIME type. Required by RSS 2.0 spec — defaults to
+     * `application/octet-stream` when omitted.
+     */
+    type?: string;
+    /** Length in bytes. Required by RSS 2.0 spec — defaults to `0` when omitted. */
+    length?: number;
+    /** Display title or alt text. JSON Feed only. */
+    title?: string;
+    /** Duration in seconds. Used by JSON Feed `attachments[].duration_in_seconds`. */
+    durationSeconds?: number;
+}
+/**
+ * Author of a feed or item.
+ */
+export interface FeedAuthor {
+    /** Display name. Required for Atom; optional everywhere else. */
+    name: string;
+    /** Author email address. Optional. */
+    email?: string;
+    /** Author profile / homepage URL. Optional. */
+    url?: string;
+    /** Avatar URL (JSON Feed only). */
+    avatarUrl?: string;
+}
+/**
+ * A single feed item / entry / post.
+ */
+export interface FeedItem {
+    /**
+     * Stable, opaque identifier. Required.
+     *
+     * RSS 2.0 emits this as `<guid>`; Atom as `<id>`; JSON Feed as `id`.
+     * If {@link FeedItem.link} is set and `id` looks like an HTTP(S) URL,
+     * RSS will mark `<guid isPermaLink="true">`.
+     */
+    id: string;
+    /** Item title. Required. */
+    title: string;
+    /** Canonical URL the item points to. */
+    link?: string;
+    /** Short summary / excerpt. Plain text or HTML. */
+    summary?: string;
+    /**
+     * Full content body. HTML is allowed; the serializer wraps it in CDATA
+     * for RSS / Atom and escapes it for JSON Feed.
+     */
+    content?: string;
+    /**
+     * Whether {@link FeedItem.content} is HTML (`true`, default) or plain text.
+     * Drives JSON Feed `content_html` vs `content_text` selection and Atom
+     * `<content type="html">` vs `<content type="text">`.
+     */
+    contentIsHtml?: boolean;
+    /** Item author(s). RSS uses the first entry; Atom and JSON Feed list all. */
+    authors?: FeedAuthor[];
+    /** Publication timestamp. ISO 8601 string or `Date`. */
+    publishedAt?: string | Date;
+    /** Last modification timestamp. ISO 8601 string or `Date`. */
+    updatedAt?: string | Date;
+    /** Tags / categories / keywords. */
+    categories?: string[];
+    /** Media enclosures (podcast audio, attachments, etc.). */
+    enclosures?: FeedItemEnclosure[];
+    /** Per-item iTunes podcast metadata. See {@link FeedItemItunes}. */
+    itunes?: FeedItemItunes;
+}
+/**
+ * Feed-level metadata + items, format-agnostic input shape consumed by
+ * every serializer.
+ */
+export interface Feed {
+    /** Channel / feed title. Required. */
+    title: string;
+    /** Canonical website URL (NOT the feed self-link). Required. */
+    link: string;
+    /** Long-form description / subtitle / tagline. Required by RSS 2.0. */
+    description: string;
+    /** Self-referential URL of the feed document. Recommended for Atom + JSON Feed. */
+    feedUrl?: string;
+    /** RFC 5646 / BCP 47 language tag (e.g. `en`, `en-US`). */
+    language?: string;
+    /** ISO 8601 / `Date` of the feed's last update. Defaults to "now" for Atom. */
+    updatedAt?: string | Date;
+    /** Channel author(s). */
+    authors?: FeedAuthor[];
+    /** Copyright / rights statement. */
+    copyright?: string;
+    /** Channel image / logo / icon URL. */
+    imageUrl?: string;
+    /** Channel-level categories (RSS only). */
+    categories?: string[];
+    /**
+     * Channel-level iTunes podcast metadata. Presence of this field switches
+     * the RSS 2.0 serializer into "podcast mode" — it declares
+     * `xmlns:itunes` and emits per-item `<itunes:*>` elements.
+     */
+    itunes?: FeedChannelItunes;
+    /** Items in display order. The serializer does not re-sort by date. */
+    items: FeedItem[];
+}
+/**
+ * Options controlling {@link serializeRss2}.
+ */
+export interface SerializeRss2Options {
+    /** XML declaration. Defaults to `<?xml version="1.0" encoding="UTF-8"?>`. */
+    xmlDeclaration?: string;
+    /** Pretty-print with 2-space indentation. Defaults to `true`. */
+    pretty?: boolean;
+}
+/**
+ * Options controlling {@link serializeAtom1}.
+ */
+export interface SerializeAtom1Options {
+    /** XML declaration. Defaults to `<?xml version="1.0" encoding="UTF-8"?>`. */
+    xmlDeclaration?: string;
+    /** Pretty-print with 2-space indentation. Defaults to `true`. */
+    pretty?: boolean;
+}
+/**
+ * Options controlling {@link serializeJsonFeed}.
+ */
+export interface SerializeJsonFeedOptions {
+    /** Pretty-print with 2-space indentation. Defaults to `false`. */
+    pretty?: boolean;
+}
+/**
+ * Error raised when the {@link Feed} input fails minimum-viability checks
+ * (missing required `title` / `link` / `description`, missing item `id` or
+ * `title`, etc.).
+ */
+export declare class FeedSerializeError extends Error {
+    /** Output format hint at the point of failure, if known. */
+    format?: FeedOutputFormat;
+    constructor(message: string, format?: FeedOutputFormat);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * Error raised when the {@link Feed} input fails minimum-viability checks
+ * (missing required `title` / `link` / `description`, missing item `id` or
+ * `title`, etc.).
+ */
+export class FeedSerializeError extends Error {
+    /** Output format hint at the point of failure, if known. */
+    format;
+    constructor(message, format) {
+        super(message);
+        this.name = 'FeedSerializeError';
+        this.format = format;
+    }
+}

package/dist/utilities.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Internal helpers shared by every serializer.
+ *
+ * @module
+ */
+import type { Feed, FeedOutputFormat } from './types.js';
+/**
+ * Coerce a `Date` / ISO string / arbitrary string into an ISO 8601 string.
+ *
+ * Returns `undefined` if the input is missing or unparseable. Unparseable
+ * arbitrary strings fall back to `undefined` rather than throwing — the
+ * serializer simply omits the timestamp element rather than emitting
+ * `Invalid Date`.
+ *
+ * @param value - Raw `Date`, ISO string, or other date-like string.
+ * @returns ISO 8601 timestamp (`2026-04-28T15:00:00.000Z`) or `undefined`.
+ */
+export declare function toIso(value: string | Date | undefined | null): string | undefined;
+/**
+ * Coerce a `Date` / ISO string into an RFC 822 date string suitable for
+ * RSS 2.0 `<pubDate>` / `<lastBuildDate>` fields.
+ *
+ * Always returns GMT / `+0000`. Returns `undefined` for unparseable input.
+ *
+ * @param value - Raw `Date`, ISO string, or RFC 822 string.
+ * @returns RFC 822 timestamp (`Mon, 28 Apr 2026 15:00:00 GMT`) or `undefined`.
+ */
+export declare function toRfc822(value: string | Date | undefined | null): string | undefined;
+/**
+ * Format a duration in seconds as `HH:MM:SS`, used for `<itunes:duration>`.
+ *
+ * Returns `undefined` for non-finite or negative input.
+ *
+ * @param seconds - Whole or fractional seconds.
+ * @returns `HH:MM:SS` string or `undefined`.
+ */
+export declare function toHhMmSs(seconds: number | undefined | null): string | undefined;
+/**
+ * Validate {@link Feed} input has the minimum required fields for the
+ * given output format.
+ *
+ * @param feed - Feed input.
+ * @param format - Target serialization format.
+ * @throws {FeedSerializeError} if a required field is missing.
+ */
+export declare function assertFeedShape(feed: Feed, format: FeedOutputFormat): void;
+/**
+ * Indent each newline of `body` by `pad` spaces. Used for pretty-printing.
+ *
+ * @param body - Multi-line text. Empty input returns empty string.
+ * @param pad - Number of spaces to prepend to each line.
+ * @returns Indented text.
+ */
+export declare function indent(body: string, pad: number): string;
+/**
+ * Whether a string looks like an HTTP(S) URL — used to set
+ * `<guid isPermaLink>` and to fall back to `link` for `<id>` synthesis.
+ *
+ * @param value - Candidate string.
+ * @returns `true` if the value parses as `http:` or `https:` URL.
+ */
+export declare function looksLikeHttpUrl(value: string | undefined | null): boolean;
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAGxD;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAUjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAgCpF;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAS/E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CA2B1E;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAG1E"}