@molecule/api-feed-rss-parser 1.0.0

package/dist/parseJsonFeed.js

@@ -0,0 +1,131 @@
+import { sanitizeHtml } from './sanitize.js';
+import { FeedParseError } from './types.js';
+import { synthesizeItemId, toIsoDate } from './utilities.js';
+/**
+ * Parse a JSON Feed 1.0 / 1.1 body into the normalized {@link ParsedFeed} shape.
+ *
+ * @param args - Raw body plus options.
+ * @param args.body
+ * @param args.sanitize
+ * @returns Normalized feed + items.
+ * @throws {FeedParseError} when the body is not valid JSON or lacks a `feed` shape.
+ */
+export function parseJsonFeed({ body, sanitize }) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch (err) {
+        throw new FeedParseError(`Invalid JSON Feed body: ${err.message}`, 'json-feed');
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new FeedParseError('JSON Feed body is not an object', 'json-feed');
+    }
+    const obj = parsed;
+    const feed = {
+        title: typeof obj['title'] === 'string' ? obj['title'] : '',
+        description: stringOrUndefined(obj['description']),
+        link: stringOrUndefined(obj['home_page_url']),
+        feedUrl: stringOrUndefined(obj['feed_url']),
+        language: stringOrUndefined(obj['language']),
+        author: extractJsonAuthor(obj['author'] ?? obj['authors']),
+        imageUrl: stringOrUndefined(obj['icon']) ?? stringOrUndefined(obj['favicon']),
+        format: 'json-feed',
+    };
+    const rawItems = Array.isArray(obj['items']) ? obj['items'] : [];
+    const items = rawItems
+        .filter((it) => !!it && typeof it === 'object')
+        .map((raw) => buildJsonFeedItem(raw, sanitize));
+    return { feed, items };
+}
+/**
+ * Returns the trimmed string value, or undefined if the value is not a non-empty string.
+ * @param value
+ */
+function stringOrUndefined(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/**
+ * Extracts a displayable author name from a JSON Feed author object, array, or string.
+ * @param value
+ */
+function extractJsonAuthor(value) {
+    if (!value)
+        return undefined;
+    if (Array.isArray(value))
+        return extractJsonAuthor(value[0]);
+    if (typeof value === 'object') {
+        const obj = value;
+        return stringOrUndefined(obj['name']) ?? stringOrUndefined(obj['url']);
+    }
+    return stringOrUndefined(value);
+}
+/**
+ * Maps a raw JSON Feed item object to a normalized {@link NormalizedFeedItem}.
+ * @param raw
+ * @param sanitize
+ */
+function buildJsonFeedItem(raw, sanitize) {
+    const title = stringOrUndefined(raw['title']) ?? '';
+    const link = stringOrUndefined(raw['url']) ?? stringOrUndefined(raw['external_url']);
+    const guid = stringOrUndefined(raw['id']);
+    const publishedAt = toIsoDate(stringOrUndefined(raw['date_published']));
+    const updatedAt = toIsoDate(stringOrUndefined(raw['date_modified']));
+    const rawSummary = stringOrUndefined(raw['summary']);
+    const rawContent = stringOrUndefined(raw['content_html']) ?? stringOrUndefined(raw['content_text']);
+    const summary = sanitize ? sanitizeHtml(rawSummary) : rawSummary;
+    const content = sanitize ? sanitizeHtml(rawContent) : rawContent;
+    const author = extractJsonAuthor(raw['author'] ?? raw['authors']);
+    const tags = Array.isArray(raw['tags'])
+        ? raw['tags'].filter((t) => typeof t === 'string' && t !== '')
+        : [];
+    const enclosures = [];
+    if (Array.isArray(raw['attachments'])) {
+        for (const att of raw['attachments']) {
+            if (!att || typeof att !== 'object')
+                continue;
+            const obj = att;
+            const url = stringOrUndefined(obj['url']);
+            if (!url)
+                continue;
+            const enclosure = { url };
+            const mime = stringOrUndefined(obj['mime_type']);
+            if (mime)
+                enclosure.type = mime;
+            const sizeBytes = obj['size_in_bytes'];
+            if (typeof sizeBytes === 'number' && Number.isFinite(sizeBytes) && sizeBytes >= 0) {
+                enclosure.length = sizeBytes;
+            }
+            const title = stringOrUndefined(obj['title']);
+            if (title)
+                enclosure.title = title;
+            const duration = obj['duration_in_seconds'];
+            if (typeof duration === 'number' && Number.isFinite(duration) && duration >= 0) {
+                enclosure.durationSeconds = duration;
+            }
+            enclosures.push(enclosure);
+        }
+    }
+    const id = guid ?? link ?? synthesizeItemId(title, publishedAt);
+    const item = { id, title };
+    if (link)
+        item.link = link;
+    if (summary)
+        item.summary = summary;
+    if (content)
+        item.content = content;
+    if (author)
+        item.author = author;
+    if (publishedAt)
+        item.publishedAt = publishedAt;
+    if (updatedAt)
+        item.updatedAt = updatedAt;
+    if (tags.length > 0)
+        item.categories = tags;
+    if (enclosures.length > 0)
+        item.enclosures = enclosures;
+    return item;
+}

package/dist/parseRdf.d.ts

@@ -0,0 +1,18 @@
+import type { ParsedFeed } from './types.js';
+interface ParseRdfArgs {
+    /** The fast-xml-parser document — already known to contain a `<rdf:RDF>` root. */
+    doc: Record<string, unknown>;
+    /** Whether to run {@link sanitizeHtml} on `summary` / `content` fields. */
+    sanitize: boolean;
+}
+/**
+ * Parse an RSS 1.0 / RDF document into the normalized {@link ParsedFeed} shape.
+ *
+ * @param args - Parsed XML document plus options.
+ * @param args.doc
+ * @param args.sanitize
+ * @returns Normalized feed + items.
+ */
+export declare function parseRdf({ doc, sanitize }: ParseRdfArgs): ParsedFeed;
+export {};
+//# sourceMappingURL=parseRdf.d.ts.map

package/dist/parseRdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseRdf.d.ts","sourceRoot":"","sources":["../src/parseRdf.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAsC,UAAU,EAAE,MAAM,YAAY,CAAA;AAGhF,UAAU,YAAY;IACpB,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,YAAY,GAAG,UAAU,CAoDpE"}

package/dist/parseRdf.js

@@ -0,0 +1,65 @@
+import { sanitizeHtml } from './sanitize.js';
+import { firstText, synthesizeItemId, textOf, toArray, toIsoDate } from './utilities.js';
+/**
+ * Parse an RSS 1.0 / RDF document into the normalized {@link ParsedFeed} shape.
+ *
+ * @param args - Parsed XML document plus options.
+ * @param args.doc
+ * @param args.sanitize
+ * @returns Normalized feed + items.
+ */
+export function parseRdf({ doc, sanitize }) {
+    // fast-xml-parser strips the `rdf:` prefix when `removeNSPrefix: true` is
+    // set; we run with prefixes preserved so detection is unambiguous, then
+    // index either form here.
+    const rdf = (doc['rdf:RDF'] ?? doc['RDF'] ?? {});
+    const channel = (rdf['channel'] ?? {});
+    const feed = {
+        title: textOf(channel['title']) ?? '',
+        description: textOf(channel['description']),
+        link: firstText(channel['link']),
+        language: textOf(channel['dc:language']) ?? textOf(channel['language']),
+        updatedAt: toIsoDate(textOf(channel['dc:date']) ?? textOf(channel['lastBuildDate'])),
+        author: textOf(channel['dc:creator']) ?? textOf(channel['managingEditor']),
+        copyright: textOf(channel['dc:rights']) ?? textOf(channel['copyright']),
+        format: 'rdf-1.0',
+    };
+    const rawItems = toArray(rdf['item']);
+    const items = rawItems.map((raw) => {
+        const title = textOf(raw['title']) ?? '';
+        const link = firstText(raw['link']);
+        const publishedAt = toIsoDate(textOf(raw['dc:date']) ?? textOf(raw['pubDate']));
+        const rawSummary = textOf(raw['description']);
+        const rawContent = textOf(raw['content:encoded']);
+        const summary = sanitize ? sanitizeHtml(rawSummary) : rawSummary;
+        const content = sanitize ? sanitizeHtml(rawContent) : rawContent;
+        const author = textOf(raw['dc:creator']);
+        const categories = [];
+        for (const cat of toArray(raw['dc:subject'])) {
+            const text = textOf(cat);
+            if (text)
+                categories.push(text);
+        }
+        for (const cat of toArray(raw['category'])) {
+            const text = textOf(cat);
+            if (text)
+                categories.push(text);
+        }
+        const id = link ?? synthesizeItemId(title, publishedAt);
+        const item = { id, title };
+        if (link)
+            item.link = link;
+        if (summary)
+            item.summary = summary;
+        if (content)
+            item.content = content;
+        if (author)
+            item.author = author;
+        if (publishedAt)
+            item.publishedAt = publishedAt;
+        if (categories.length > 0)
+            item.categories = categories;
+        return item;
+    });
+    return { feed, items };
+}

package/dist/parseRss.d.ts

@@ -0,0 +1,18 @@
+import type { ParsedFeed } from './types.js';
+interface ParseRssArgs {
+    /** The fast-xml-parser document — already known to contain an `<rss>` root. */
+    doc: Record<string, unknown>;
+    /** Whether to run {@link sanitizeHtml} on `summary` / `content` fields. */
+    sanitize: boolean;
+}
+/**
+ * Parse an RSS 2.0 document into the normalized {@link ParsedFeed} shape.
+ *
+ * @param args - Parsed XML document plus options.
+ * @param args.doc
+ * @param args.sanitize
+ * @returns Normalized feed + items.
+ */
+export declare function parseRss({ doc, sanitize }: ParseRssArgs): ParsedFeed;
+export {};
+//# sourceMappingURL=parseRss.d.ts.map

package/dist/parseRss.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseRss.d.ts","sourceRoot":"","sources":["../src/parseRss.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqD,UAAU,EAAE,MAAM,YAAY,CAAA;AAU/F,UAAU,YAAY;IACpB,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,YAAY,GAAG,UAAU,CAwBpE"}

package/dist/parseRss.js

@@ -0,0 +1,151 @@
+import { sanitizeHtml } from './sanitize.js';
+import { attrOf, parseItunesDuration, synthesizeItemId, textOf, toArray, toIsoDate, } from './utilities.js';
+/**
+ * Parse an RSS 2.0 document into the normalized {@link ParsedFeed} shape.
+ *
+ * @param args - Parsed XML document plus options.
+ * @param args.doc
+ * @param args.sanitize
+ * @returns Normalized feed + items.
+ */
+export function parseRss({ doc, sanitize }) {
+    const rss = (doc['rss'] ?? {});
+    const channel = (rss['channel'] ?? {});
+    const feed = {
+        title: textOf(channel['title']) ?? '',
+        description: textOf(channel['description']),
+        link: extractRssLink(channel),
+        language: textOf(channel['language']),
+        updatedAt: toIsoDate(textOf(channel['lastBuildDate'])) ?? toIsoDate(textOf(channel['pubDate'])),
+        author: textOf(channel['managingEditor']) ?? textOf(channel['itunes:author']),
+        copyright: textOf(channel['copyright']),
+        imageUrl: extractRssImage(channel),
+        feedUrl: attrOf((channel['atom:link'] ?? channel['atom10:link']), 'href'),
+        format: 'rss-2.0',
+    };
+    const rawItems = toArray(channel['item']);
+    const items = rawItems.map((raw) => buildRssItem(raw, sanitize));
+    return { feed, items };
+}
+/**
+ * Extract the primary HTML link URL from an RSS channel or item element.
+ * @param channel
+ */
+function extractRssLink(channel) {
+    const link = channel['link'];
+    if (Array.isArray(link)) {
+        for (const candidate of link) {
+            const text = textOf(candidate);
+            if (text)
+                return text;
+        }
+        return undefined;
+    }
+    if (typeof link === 'string')
+        return link.trim() || undefined;
+    return textOf(link);
+}
+/**
+ * Extract the feed image URL from RSS `<image>` or iTunes `<itunes:image>` elements.
+ * @param channel
+ */
+function extractRssImage(channel) {
+    const image = channel['image'];
+    if (image && typeof image === 'object') {
+        const url = textOf(image['url']);
+        if (url)
+            return url;
+    }
+    const itunesImage = channel['itunes:image'];
+    if (itunesImage) {
+        const href = attrOf(itunesImage, 'href');
+        if (href)
+            return href;
+    }
+    return undefined;
+}
+/**
+ * Map a raw RSS `<item>` element into a {@link NormalizedFeedItem}.
+ * @param raw
+ * @param sanitize
+ */
+function buildRssItem(raw, sanitize) {
+    const title = textOf(raw['title']) ?? '';
+    const link = extractRssLink(raw);
+    const guid = textOf(raw['guid']);
+    const publishedAt = toIsoDate(textOf(raw['pubDate']));
+    const updatedAt = toIsoDate(textOf(raw['atom:updated']) ?? textOf(raw['dc:date']) ?? textOf(raw['updated']));
+    const rawSummary = textOf(raw['description']);
+    const rawContent = textOf(raw['content:encoded']) ?? textOf(raw['content']) ?? textOf(raw['xhtml:body']);
+    const summary = sanitize ? sanitizeHtml(rawSummary) : rawSummary;
+    const content = sanitize ? sanitizeHtml(rawContent) : rawContent;
+    const author = textOf(raw['author']) ?? textOf(raw['dc:creator']) ?? textOf(raw['itunes:author']);
+    const categories = extractRssCategories(raw);
+    const enclosures = extractRssEnclosures(raw);
+    const id = guid ?? link ?? synthesizeItemId(title, publishedAt);
+    const item = { id, title };
+    if (link)
+        item.link = link;
+    if (summary)
+        item.summary = summary;
+    if (content)
+        item.content = content;
+    if (author)
+        item.author = author;
+    if (publishedAt)
+        item.publishedAt = publishedAt;
+    if (updatedAt)
+        item.updatedAt = updatedAt;
+    if (categories.length > 0)
+        item.categories = categories;
+    if (enclosures.length > 0)
+        item.enclosures = enclosures;
+    return item;
+}
+/**
+ * Collect all category strings from RSS `<category>` and iTunes `<itunes:category>` elements.
+ * @param raw
+ */
+function extractRssCategories(raw) {
+    const out = [];
+    for (const cat of toArray(raw['category'])) {
+        const text = textOf(cat);
+        if (text)
+            out.push(text);
+    }
+    // iTunes categories live under <itunes:category text="...">; collect
+    // the top-level text attributes for podcast feeds.
+    for (const cat of toArray(raw['itunes:category'])) {
+        const text = attrOf(cat, 'text');
+        if (text)
+            out.push(text);
+    }
+    return out;
+}
+/**
+ * Collect all enclosures from RSS `<enclosure>` elements, enriched with iTunes duration.
+ * @param raw
+ */
+function extractRssEnclosures(raw) {
+    const out = [];
+    const itunesDuration = parseItunesDuration(textOf(raw['itunes:duration']));
+    for (const enc of toArray(raw['enclosure'])) {
+        const url = attrOf(enc, 'url');
+        if (!url)
+            continue;
+        const length = attrOf(enc, 'length');
+        const type = attrOf(enc, 'type');
+        const enclosure = { url };
+        if (type)
+            enclosure.type = type;
+        if (length) {
+            const n = Number(length);
+            if (Number.isFinite(n) && n >= 0)
+                enclosure.length = n;
+        }
+        if (itunesDuration !== undefined)
+            enclosure.durationSeconds = itunesDuration;
+        out.push(enclosure);
+    }
+    return out;
+}

package/dist/sanitize.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Lightweight HTML sanitization helpers.
+ *
+ * @remarks
+ * This module is intentionally minimal — strip `<script>`, `<style>`,
+ * inline `on*` event handlers, and `javascript:` URLs. Callers wiring this
+ * into a full UI should still run a proper sanitizer (e.g. DOMPurify) on
+ * the output. The goal here is "feed parser cannot smuggle a `<script>`
+ * tag through to a downstream consumer that forgot to sanitize."
+ */
+/**
+ * Strip dangerous content from an HTML string. Returns plain text unchanged.
+ *
+ * Removes:
+ * - Complete `<script>...</script>` and `<style>...</style>` blocks.
+ * - Stray opening/closing tags of those elements (in malformed HTML).
+ * - Inline event handlers (`onclick="..."`, `onerror="..."`, etc.).
+ * - `javascript:` URLs in `href` / `src` / `xlink:href` / `(form)action`.
+ *
+ * Idempotent: `sanitizeHtml(sanitizeHtml(x)) === sanitizeHtml(x)`.
+ *
+ * @param html - HTML or plain-text string. `undefined` and `null` short-circuit
+ *               to `undefined` so callers can chain safely.
+ * @returns Sanitized HTML string, or `undefined` when the input was nullish.
+ */
+export declare function sanitizeHtml(html: string | undefined | null): string | undefined;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAYhF"}

package/dist/sanitize.js

@@ -0,0 +1,47 @@
+/**
+ * Lightweight HTML sanitization helpers.
+ *
+ * @remarks
+ * This module is intentionally minimal — strip `<script>`, `<style>`,
+ * inline `on*` event handlers, and `javascript:` URLs. Callers wiring this
+ * into a full UI should still run a proper sanitizer (e.g. DOMPurify) on
+ * the output. The goal here is "feed parser cannot smuggle a `<script>`
+ * tag through to a downstream consumer that forgot to sanitize."
+ */
+const SCRIPT_BLOCK = /<script\b[^>]*>[\s\S]*?<\/script\s*>/gi;
+const SCRIPT_OPEN = /<script\b[^>]*>/gi;
+const SCRIPT_CLOSE = /<\/script\s*>/gi;
+const STYLE_BLOCK = /<style\b[^>]*>[\s\S]*?<\/style\s*>/gi;
+const STYLE_OPEN = /<style\b[^>]*>/gi;
+const STYLE_CLOSE = /<\/style\s*>/gi;
+const EVENT_HANDLER = /\son[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi;
+const JS_URL = /(\s(?:href|src|xlink:href|action|formaction))\s*=\s*("|')\s*javascript:[^"']*\2/gi;
+/**
+ * Strip dangerous content from an HTML string. Returns plain text unchanged.
+ *
+ * Removes:
+ * - Complete `<script>...</script>` and `<style>...</style>` blocks.
+ * - Stray opening/closing tags of those elements (in malformed HTML).
+ * - Inline event handlers (`onclick="..."`, `onerror="..."`, etc.).
+ * - `javascript:` URLs in `href` / `src` / `xlink:href` / `(form)action`.
+ *
+ * Idempotent: `sanitizeHtml(sanitizeHtml(x)) === sanitizeHtml(x)`.
+ *
+ * @param html - HTML or plain-text string. `undefined` and `null` short-circuit
+ *               to `undefined` so callers can chain safely.
+ * @returns Sanitized HTML string, or `undefined` when the input was nullish.
+ */
+export function sanitizeHtml(html) {
+    if (html == null)
+        return undefined;
+    let out = html;
+    out = out.replace(SCRIPT_BLOCK, '');
+    out = out.replace(SCRIPT_OPEN, '');
+    out = out.replace(SCRIPT_CLOSE, '');
+    out = out.replace(STYLE_BLOCK, '');
+    out = out.replace(STYLE_OPEN, '');
+    out = out.replace(STYLE_CLOSE, '');
+    out = out.replace(EVENT_HANDLER, '');
+    out = out.replace(JS_URL, '$1=$2#$2');
+    return out;
+}

package/dist/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Discriminator for the source feed format detected by {@link parseFeed}.
+ *
+ * - `rss-2.0` — RSS 2.0 (`<rss version="2.0"><channel>...`)
+ * - `atom-1.0` — Atom 1.0 (`<feed xmlns="http://www.w3.org/2005/Atom">...`)
+ * - `rdf-1.0` — RSS 1.0 / RDF (`<rdf:RDF ...><channel>...<item>`)
+ * - `json-feed` — JSON Feed 1.0 / 1.1 (https://www.jsonfeed.org/version/1.1/)
+ */
+export type FeedFormat = 'rss-2.0' | 'atom-1.0' | 'rdf-1.0' | 'json-feed';
+/**
+ * A normalized media enclosure attached to a feed item (podcast audio,
+ * video, image, etc.). Source: RSS `<enclosure>`, Atom `<link rel="enclosure">`,
+ * JSON Feed `attachments[]`.
+ */
+export interface FeedEnclosure {
+    /** Direct URL to the media resource. Required. */
+    url: string;
+    /** MIME type (e.g. `audio/mpeg`, `video/mp4`, `image/png`) when known. */
+    type?: string;
+    /** Length in bytes when reported by the source feed. */
+    length?: number;
+    /** Display title or alt text for the enclosure when supplied. */
+    title?: string;
+    /** Duration in seconds — derived from iTunes `<itunes:duration>` for podcasts. */
+    durationSeconds?: number;
+}
+/**
+ * Normalized feed-level metadata. The exact subset of fields populated
+ * depends on what the source feed publishes; only `title` is guaranteed.
+ */
+export interface NormalizedFeed {
+    /** Feed/channel title. Empty string if the source omitted a title. */
+    title: string;
+    /** Long-form description / subtitle / tagline. */
+    description?: string;
+    /** Canonical website URL (NOT the feed self-link). */
+    link?: string;
+    /** Self-referential URL of the feed document, when supplied. */
+    feedUrl?: string;
+    /** RFC 5646 / BCP 47 language tag (e.g. `en`, `en-US`). */
+    language?: string;
+    /** ISO 8601 timestamp of the feed's last update. */
+    updatedAt?: string;
+    /** Author / managing editor name reported by the feed. */
+    author?: string;
+    /** Copyright notice / rights statement. */
+    copyright?: string;
+    /** Feed-level image / logo / icon URL. */
+    imageUrl?: string;
+    /** Detected source format. */
+    format: FeedFormat;
+}
+/**
+ * Normalized feed item. The exact subset of fields populated depends on
+ * what the source feed publishes; only `id` is guaranteed (synthesized from
+ * `link` or content hash if no GUID is present).
+ */
+export interface NormalizedFeedItem {
+    /**
+     * Stable, opaque identifier for deduplication.
+     * Source-of-truth order: `<guid>` / `<id>` / JSON Feed `id` →
+     * `link` URL → SHA-1 hash of `title + publishedAt`. Always non-empty.
+     */
+    id: string;
+    /** Item title. Empty string if the source omitted a title. */
+    title: string;
+    /** Canonical URL the item points to. */
+    link?: string;
+    /** Short summary / description / excerpt — sanitized HTML or plain text. */
+    summary?: string;
+    /**
+     * Full content body — sanitized HTML (`<script>` tags stripped at minimum).
+     * Source: `<content:encoded>`, Atom `<content>`, JSON Feed `content_html`/`content_text`.
+     */
+    content?: string;
+    /** Author display name reported by the item. */
+    author?: string;
+    /** ISO 8601 timestamp of publication. */
+    publishedAt?: string;
+    /** ISO 8601 timestamp of the last update / modification. */
+    updatedAt?: string;
+    /** Tags / categories / keywords assigned to the item. */
+    categories?: string[];
+    /** Attached media (podcast audio, embedded images, etc.). */
+    enclosures?: FeedEnclosure[];
+}
+/**
+ * Parsed feed result returned by {@link parseFeed}.
+ */
+export interface ParsedFeed {
+    /** Normalized feed-level metadata. */
+    feed: NormalizedFeed;
+    /** Items in source order (NOT re-sorted by date). */
+    items: NormalizedFeedItem[];
+}
+/**
+ * Options controlling {@link parseFeed} behavior.
+ */
+export interface ParseFeedOptions {
+    /**
+     * Hint for the source format. When omitted, format detection runs:
+     * 1. If `contentType` includes `json` or body trims to `{` / `[` → JSON Feed.
+     * 2. XML is parsed and the root element selects `rss-2.0` / `atom-1.0` / `rdf-1.0`.
+     *
+     * Pass `contentType` from the HTTP response when available; it short-circuits
+     * the JSON vs. XML guess on ambiguous payloads.
+     */
+    contentType?: string;
+    /**
+     * Optional explicit format override. Skips detection entirely.
+     */
+    format?: FeedFormat;
+    /**
+     * When `true` (default), strips `<script>` blocks from any HTML content
+     * fields (`summary`, `content`). Set to `false` only when the caller
+     * performs sanitization downstream.
+     */
+    sanitizeHtml?: boolean;
+}
+/**
+ * Error raised when {@link parseFeed} cannot determine the source format
+ * or the body is malformed.
+ */
+export declare class FeedParseError extends Error {
+    /** Detected or supplied format hint at the point of failure, if any. */
+    format?: FeedFormat;
+    constructor(message: string, format?: FeedFormat);
+}
+//# 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":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAA;AAEzE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAA;IAEX,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IAEb,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,8BAA8B;IAC9B,MAAM,EAAE,UAAU,CAAA;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAA;IAEV,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAA;IAEb,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IAErB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,IAAI,EAAE,cAAc,CAAA;IAEpB,qDAAqD;IACrD,KAAK,EAAE,kBAAkB,EAAE,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;IAEnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,wEAAwE;IACxE,MAAM,CAAC,EAAE,UAAU,CAAA;gBAEP,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU;CAKjD"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Error raised when {@link parseFeed} cannot determine the source format
+ * or the body is malformed.
+ */
+export class FeedParseError extends Error {
+    /** Detected or supplied format hint at the point of failure, if any. */
+    format;
+    constructor(message, format) {
+        super(message);
+        this.name = 'FeedParseError';
+        this.format = format;
+    }
+}