@molecule/api-feed-rss-parser 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-feed-rss-parser` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-feed-rss-parser is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure-function feed parser for molecule.dev — RSS 2.0, Atom 1.0, RSS 1.0
+ * (RDF), and JSON Feed 1.0 / 1.1, normalized into a single `{ feed, items[] }`
+ * shape. Used by `news-aggregator`, `blog`, and `podcast` apps for ingesting
+ * external feeds and dedup'ing items by stable id.
+ *
+ * @example
+ * ```ts
+ * import { parseFeed } from '@molecule/api-feed-rss-parser'
+ *
+ * const res = await fetch('https://example.com/feed.xml')
+ * const { feed, items } = parseFeed(await res.text(), {
+ *   contentType: res.headers.get('content-type') ?? undefined,
+ * })
+ *
+ * for (const item of items) {
+ *   console.log(item.id, item.title, item.publishedAt)
+ *   for (const enclosure of item.enclosures ?? []) {
+ *     console.log(' ↳', enclosure.url, enclosure.type, enclosure.durationSeconds)
+ *   }
+ * }
+ * ```
+ *
+ * @remarks
+ * The parser is a pure function — it accepts the response body string plus
+ * optional `contentType` / `format` hints and returns a normalized result.
+ * No fetch, no state, no caching: callers fetch the document themselves
+ * (native `fetch` or the bonded `@molecule/api-http` provider) and can
+ * layer `@molecule/api-cache` on top for TTL caching.
+ *
+ * iTunes podcast namespace fields (`<itunes:duration>`, `<itunes:author>`,
+ * `<itunes:image>`, `<itunes:category>`) are extracted into the normalized
+ * shape — duration ends up on the matching `<enclosure>` as
+ * `enclosure.durationSeconds`. Dublin Core (`dc:creator`, `dc:date`,
+ * `dc:subject`) is also recognized for RSS 1.0 / RDF feeds.
+ *
+ * Item content fields are sanitized by default — `<script>` blocks, inline
+ * event handlers, and `javascript:` URLs are stripped. Pass
+ * `sanitizeHtml: false` to opt out (e.g. when sanitization happens further
+ * down the pipeline).
+ *
+ * Item identifiers are derived in priority order: explicit GUID / Atom id /
+ * JSON Feed id → item link URL → SHA-1 of `title + publishedAt`. The result
+ * is always non-empty and stable across re-parses, so deduplication on
+ * `item.id` is safe.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './parseFeed.js';
+export * from './sanitize.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,52 @@
+/**
+ * Pure-function feed parser for molecule.dev — RSS 2.0, Atom 1.0, RSS 1.0
+ * (RDF), and JSON Feed 1.0 / 1.1, normalized into a single `{ feed, items[] }`
+ * shape. Used by `news-aggregator`, `blog`, and `podcast` apps for ingesting
+ * external feeds and dedup'ing items by stable id.
+ *
+ * @example
+ * ```ts
+ * import { parseFeed } from '@molecule/api-feed-rss-parser'
+ *
+ * const res = await fetch('https://example.com/feed.xml')
+ * const { feed, items } = parseFeed(await res.text(), {
+ *   contentType: res.headers.get('content-type') ?? undefined,
+ * })
+ *
+ * for (const item of items) {
+ *   console.log(item.id, item.title, item.publishedAt)
+ *   for (const enclosure of item.enclosures ?? []) {
+ *     console.log(' ↳', enclosure.url, enclosure.type, enclosure.durationSeconds)
+ *   }
+ * }
+ * ```
+ *
+ * @remarks
+ * The parser is a pure function — it accepts the response body string plus
+ * optional `contentType` / `format` hints and returns a normalized result.
+ * No fetch, no state, no caching: callers fetch the document themselves
+ * (native `fetch` or the bonded `@molecule/api-http` provider) and can
+ * layer `@molecule/api-cache` on top for TTL caching.
+ *
+ * iTunes podcast namespace fields (`<itunes:duration>`, `<itunes:author>`,
+ * `<itunes:image>`, `<itunes:category>`) are extracted into the normalized
+ * shape — duration ends up on the matching `<enclosure>` as
+ * `enclosure.durationSeconds`. Dublin Core (`dc:creator`, `dc:date`,
+ * `dc:subject`) is also recognized for RSS 1.0 / RDF feeds.
+ *
+ * Item content fields are sanitized by default — `<script>` blocks, inline
+ * event handlers, and `javascript:` URLs are stripped. Pass
+ * `sanitizeHtml: false` to opt out (e.g. when sanitization happens further
+ * down the pipeline).
+ *
+ * Item identifiers are derived in priority order: explicit GUID / Atom id /
+ * JSON Feed id → item link URL → SHA-1 of `title + publishedAt`. The result
+ * is always non-empty and stable across re-parses, so deduplication on
+ * `item.id` is safe.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './parseFeed.js';
+export * from './sanitize.js';
+export * from './types.js';

package/dist/parseAtom.d.ts

@@ -0,0 +1,18 @@
+import type { ParsedFeed } from './types.js';
+interface ParseAtomArgs {
+    /** The fast-xml-parser document — already known to contain a `<feed>` root. */
+    doc: Record<string, unknown>;
+    /** Whether to run {@link sanitizeHtml} on `summary` / `content` fields. */
+    sanitize: boolean;
+}
+/**
+ * Parse an Atom 1.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 parseAtom({ doc, sanitize }: ParseAtomArgs): ParsedFeed;
+export {};
+//# sourceMappingURL=parseAtom.d.ts.map

package/dist/parseAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseAtom.d.ts","sourceRoot":"","sources":["../src/parseAtom.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqD,UAAU,EAAE,MAAM,YAAY,CAAA;AAG/F,UAAU,aAAa;IACrB,+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,SAAS,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,aAAa,GAAG,UAAU,CAgCtE"}

package/dist/parseAtom.js

@@ -0,0 +1,151 @@
+import { sanitizeHtml } from './sanitize.js';
+import { attrOf, synthesizeItemId, textOf, toArray, toIsoDate } from './utilities.js';
+/**
+ * Parse an Atom 1.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 parseAtom({ doc, sanitize }) {
+    const atom = (doc['feed'] ?? {});
+    const links = toArray(atom['link']);
+    const alternateLink = pickLink(links, 'alternate') ?? pickLink(links, undefined);
+    const selfLink = pickLink(links, 'self');
+    const updated = toIsoDate(textOf(atom['updated']));
+    const language = attrOf(atom, 'xml:lang') ??
+        textOf(atom['language']) ??
+        atom['@_xml:lang'];
+    const feed = {
+        title: textOf(atom['title']) ?? '',
+        description: textOf(atom['subtitle']) ?? textOf(atom['summary']),
+        link: alternateLink,
+        feedUrl: selfLink,
+        language,
+        updatedAt: updated,
+        author: extractAtomAuthor(atom['author']),
+        copyright: textOf(atom['rights']),
+        imageUrl: textOf(atom['logo']) ?? textOf(atom['icon']),
+        format: 'atom-1.0',
+    };
+    const rawEntries = toArray(atom['entry']);
+    const items = rawEntries.map((raw) => buildAtomEntry(raw, sanitize));
+    return { feed, items };
+}
+/**
+ * Select the first href from an array of Atom link objects that matches the given `rel` value.
+ *
+ * @param links
+ * @param rel
+ */
+function pickLink(links, rel) {
+    for (const link of links) {
+        if (typeof link === 'string') {
+            if (rel === undefined || rel === 'alternate') {
+                const trimmed = link.trim();
+                if (trimmed)
+                    return trimmed;
+            }
+            continue;
+        }
+        if (link && typeof link === 'object') {
+            const obj = link;
+            const linkRel = obj['@_rel'] ?? 'alternate';
+            const href = obj['@_href'];
+            if (!href)
+                continue;
+            if (rel === undefined && linkRel === 'alternate')
+                return href;
+            if (rel !== undefined && linkRel === rel)
+                return href;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract a display name or email string from an Atom `<author>` value.
+ *
+ * @param value
+ */
+function extractAtomAuthor(value) {
+    if (value == null)
+        return undefined;
+    const candidate = Array.isArray(value) ? value[0] : value;
+    if (typeof candidate === 'string')
+        return candidate.trim() || undefined;
+    if (candidate && typeof candidate === 'object') {
+        const obj = candidate;
+        return textOf(obj['name']) ?? textOf(obj['email']);
+    }
+    return undefined;
+}
+/**
+ * Build a `NormalizedFeedItem` from a raw Atom `<entry>` object.
+ *
+ * @param raw
+ * @param sanitize
+ */
+function buildAtomEntry(raw, sanitize) {
+    const title = textOf(raw['title']) ?? '';
+    const links = toArray(raw['link']);
+    const link = pickLink(links, 'alternate') ?? pickLink(links, undefined);
+    const guid = textOf(raw['id']);
+    const publishedAt = toIsoDate(textOf(raw['published']) ?? textOf(raw['issued']));
+    const updatedAt = toIsoDate(textOf(raw['updated']) ?? textOf(raw['modified']));
+    const rawSummary = textOf(raw['summary']);
+    const rawContent = textOf(raw['content']);
+    const summary = sanitize ? sanitizeHtml(rawSummary) : rawSummary;
+    const content = sanitize ? sanitizeHtml(rawContent) : rawContent;
+    const author = extractAtomAuthor(raw['author']);
+    const categories = [];
+    for (const cat of toArray(raw['category'])) {
+        const term = attrOf(cat, 'term') ?? attrOf(cat, 'label') ?? textOf(cat);
+        if (term)
+            categories.push(term);
+    }
+    const enclosures = [];
+    for (const link of links) {
+        if (!link || typeof link !== 'object')
+            continue;
+        const obj = link;
+        if (obj['@_rel'] !== 'enclosure')
+            continue;
+        const url = obj['@_href'];
+        if (!url)
+            continue;
+        const enclosure = { url };
+        const type = obj['@_type'];
+        if (type)
+            enclosure.type = type;
+        const length = obj['@_length'];
+        if (length) {
+            const n = Number(length);
+            if (Number.isFinite(n) && n >= 0)
+                enclosure.length = n;
+        }
+        const title = obj['@_title'];
+        if (title)
+            enclosure.title = title;
+        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 (categories.length > 0)
+        item.categories = categories;
+    if (enclosures.length > 0)
+        item.enclosures = enclosures;
+    return item;
+}

package/dist/parseFeed.d.ts

@@ -0,0 +1,43 @@
+import type { FeedFormat, ParsedFeed, ParseFeedOptions } from './types.js';
+/**
+ * Detect the source format of a feed body.
+ *
+ * Detection runs in this order:
+ * 1. If `contentType` includes `json`, OR the trimmed body begins with `{`/`[`,
+ *    return `'json-feed'` without parsing XML.
+ * 2. Otherwise the XML root element selects the format:
+ *    - `rss` → `'rss-2.0'`
+ *    - `feed` → `'atom-1.0'`
+ *    - `rdf:RDF` (or `RDF`) → `'rdf-1.0'`
+ *
+ * @param body - Raw body string.
+ * @param contentType - Optional `Content-Type` header value from the HTTP response.
+ * @returns Detected format, or `undefined` when the body cannot be classified.
+ */
+export declare function detectFeedFormat(body: string, contentType: string | undefined): FeedFormat | undefined;
+/**
+ * Parse an RSS / Atom / RDF / JSON Feed body into a normalized
+ * `{ feed, items[] }` shape.
+ *
+ * Pure function — no I/O, no state. Pass the response body and (optionally)
+ * the HTTP `Content-Type` header. Format detection is automatic; pass
+ * `options.format` to override.
+ *
+ * @example
+ * ```ts
+ * import { parseFeed } from '@molecule/api-feed-rss-parser'
+ *
+ * const res = await fetch('https://example.com/feed.xml')
+ * const { feed, items } = parseFeed(await res.text(), {
+ *   contentType: res.headers.get('content-type') ?? undefined,
+ * })
+ * console.log(feed.title, items.length)
+ * ```
+ *
+ * @param body - The full HTTP response body. Required, must be non-empty.
+ * @param options - Parser options. See {@link ParseFeedOptions}.
+ * @returns Normalized feed + items.
+ * @throws {FeedParseError} when the body cannot be classified or parsed.
+ */
+export declare function parseFeed(body: string, options?: ParseFeedOptions): ParsedFeed;
+//# sourceMappingURL=parseFeed.d.ts.map

package/dist/parseFeed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseFeed.d.ts","sourceRoot":"","sources":["../src/parseFeed.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AA4B1E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,UAAU,GAAG,SAAS,CAaxB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,UAAU,CA2BlF"}

package/dist/parseFeed.js

@@ -0,0 +1,113 @@
+import { XMLParser } from 'fast-xml-parser';
+import { parseAtom } from './parseAtom.js';
+import { parseJsonFeed } from './parseJsonFeed.js';
+import { parseRdf } from './parseRdf.js';
+import { parseRss } from './parseRss.js';
+import { FeedParseError } from './types.js';
+const xmlParser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    textNodeName: '#text',
+    // Preserve namespace prefixes (`itunes:duration`, `dc:creator`, `content:encoded`)
+    // so each parser can pick out the metadata it needs.
+    removeNSPrefix: false,
+    // Atom + RSS commonly contain CDATA-wrapped HTML in description/content
+    // fields. Flag those so callers see the inner string verbatim.
+    cdataPropName: false,
+    parseTagValue: false,
+    parseAttributeValue: false,
+    trimValues: true,
+    // Normalize duplicate <link> / <category> / <enclosure> elements into arrays
+    // so the downstream parsers can iterate consistently.
+    isArray: (name) => name === 'item' ||
+        name === 'entry' ||
+        name === 'link' ||
+        name === 'category' ||
+        name === 'enclosure' ||
+        name === 'author' ||
+        name === 'itunes:category',
+});
+/**
+ * Detect the source format of a feed body.
+ *
+ * Detection runs in this order:
+ * 1. If `contentType` includes `json`, OR the trimmed body begins with `{`/`[`,
+ *    return `'json-feed'` without parsing XML.
+ * 2. Otherwise the XML root element selects the format:
+ *    - `rss` → `'rss-2.0'`
+ *    - `feed` → `'atom-1.0'`
+ *    - `rdf:RDF` (or `RDF`) → `'rdf-1.0'`
+ *
+ * @param body - Raw body string.
+ * @param contentType - Optional `Content-Type` header value from the HTTP response.
+ * @returns Detected format, or `undefined` when the body cannot be classified.
+ */
+export function detectFeedFormat(body, contentType) {
+    const ctLower = (contentType ?? '').toLowerCase();
+    const trimmed = body.trimStart();
+    if (ctLower.includes('json') || trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        return 'json-feed';
+    }
+    // Cheap-but-deterministic root-element sniff before paying for a full parse.
+    // We still parse for the actual extraction; this just selects a parser.
+    const head = trimmed.slice(0, 2048);
+    if (/<rss\b/i.test(head))
+        return 'rss-2.0';
+    if (/<feed\b/i.test(head))
+        return 'atom-1.0';
+    if (/<rdf:RDF\b/i.test(head) || /<RDF\b/i.test(head))
+        return 'rdf-1.0';
+    return undefined;
+}
+/**
+ * Parse an RSS / Atom / RDF / JSON Feed body into a normalized
+ * `{ feed, items[] }` shape.
+ *
+ * Pure function — no I/O, no state. Pass the response body and (optionally)
+ * the HTTP `Content-Type` header. Format detection is automatic; pass
+ * `options.format` to override.
+ *
+ * @example
+ * ```ts
+ * import { parseFeed } from '@molecule/api-feed-rss-parser'
+ *
+ * const res = await fetch('https://example.com/feed.xml')
+ * const { feed, items } = parseFeed(await res.text(), {
+ *   contentType: res.headers.get('content-type') ?? undefined,
+ * })
+ * console.log(feed.title, items.length)
+ * ```
+ *
+ * @param body - The full HTTP response body. Required, must be non-empty.
+ * @param options - Parser options. See {@link ParseFeedOptions}.
+ * @returns Normalized feed + items.
+ * @throws {FeedParseError} when the body cannot be classified or parsed.
+ */
+export function parseFeed(body, options = {}) {
+    if (typeof body !== 'string' || body.trim() === '') {
+        throw new FeedParseError('Feed body is empty');
+    }
+    const sanitize = options.sanitizeHtml !== false;
+    const format = options.format ?? detectFeedFormat(body, options.contentType);
+    if (!format) {
+        throw new FeedParseError('Unable to detect feed format — pass options.format to override');
+    }
+    if (format === 'json-feed') {
+        return parseJsonFeed({ body, sanitize });
+    }
+    let doc;
+    try {
+        doc = xmlParser.parse(body);
+    }
+    catch (err) {
+        throw new FeedParseError(`XML parse error: ${err.message}`, format);
+    }
+    if (format === 'rss-2.0')
+        return parseRss({ doc, sanitize });
+    if (format === 'atom-1.0')
+        return parseAtom({ doc, sanitize });
+    if (format === 'rdf-1.0')
+        return parseRdf({ doc, sanitize });
+    // Defensive — exhaustiveness guard for new FeedFormat values.
+    throw new FeedParseError(`Unsupported feed format: ${format}`);
+}

package/dist/parseJsonFeed.d.ts

@@ -0,0 +1,19 @@
+import type { ParsedFeed } from './types.js';
+interface ParseJsonFeedArgs {
+    /** The raw response body. */
+    body: string;
+    /** Whether to run {@link sanitizeHtml} on `summary` / `content` fields. */
+    sanitize: boolean;
+}
+/**
+ * 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 declare function parseJsonFeed({ body, sanitize }: ParseJsonFeedArgs): ParsedFeed;
+export {};
+//# sourceMappingURL=parseJsonFeed.d.ts.map

package/dist/parseJsonFeed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseJsonFeed.d.ts","sourceRoot":"","sources":["../src/parseJsonFeed.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqD,UAAU,EAAE,MAAM,YAAY,CAAA;AAI/F,UAAU,iBAAiB;IACzB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,iBAAiB,GAAG,UAAU,CA6B/E"}