feed-slurp 1.0.0

package/LICENSE

@@ -0,0 +1,324 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+    (a) that the initial Contributor has otherwise conditioned the
+         some portion of the Covered Software on it not being
+        available under either of the Secondary Licenses, or
+
+    (b) that the Covered Software was first made available under
+        Mozilla Public License, version 1.1 or earlier, but not also
+        under the Mozilla Public License, version 2.0.
+
+1.6. "Executable Form"
+    means any form other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or other transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary Licenses"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the preferred form of the Covered Software for making
+    modifications to it.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your receiving a
+copy of this License from another Person. Any person as a result of
+developing software that becomes Covered Software or a Larger Work will
+be a Contributor of such Covered Software or Larger Work.
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Code Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be available in Source Code Form, as
+    described in Section 3.1, and You must inform recipients how they
+    can obtain a copy of such Source Code Form by reasonable means in a
+    timely manner, at a charge no more than the cost of distribution to
+    the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipient's rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of such Secondary License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy statutory inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability offered by You. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or judicial order, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+6. Disclaimer of Warranty
+-------------------------
+
+Covered Software is provided under this License on an "as is" basis,
+without warranty of any kind, either expressed, implied, or statutory,
+including, without limitation, warranties that the Covered Software is
+free of defects, merchantable, fit for a particular purpose or
+non-infringing. The entire risk as to the quality and performance of the
+Covered Software is with You. Should any Covered Software prove
+defective in any respect, You (not any Contributor) assume the cost of
+any necessary servicing, repair, or correction. This disclaimer of
+warranty constitutes an essential part of this License. No use of any
+Covered Software is authorized under this License except under this
+disclaimer.
+
+7. Limitation of Liability
+--------------------------
+
+Under no circumstances and under no legal theory, whether tort (including
+negligence), contract, or otherwise, shall any Contributor, or anyone
+who distributes Covered Software as permitted above, be liable to You
+for any direct, indirect, special, incidental, or consequential damages
+of any character including, without limitation, damages for lost
+profits, loss of goodwill, work stoppage, computer failure or
+malfunction, or any and all other commercial damages or losses, even if
+such party shall have been informed of the possibility of such damages.
+This limitation of liability shall not apply to liability for death or
+personal injury resulting from such party's negligence to the extent
+applicable law prohibits such limitation. Some jurisdictions do not
+allow the exclusion or limitation of incidental or consequential
+damages, so this exclusion and limitation may not apply to You.
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Exhibit A - Mozilla Public License Notice
+---------------------------------------------
+
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+If it is inappropriate to include the notice in a particular source code
+file due to its structure, then you may include the notice in a location
+(such as a relevant directory of a notice file) where a recipient would be
+likely to look for such a notice.
+
+You may add additional accurate notices of copyright ownership.

package/README.md

@@ -0,0 +1,92 @@
+# feed-slurp 🥤
+
+A lightweight, universal RSS and Atom feed fetcher for the browser. Targeted for speed, reliability, and zero-dependency vibe (built on the `BaryoDev` stack).
+
+## Why feed-slurp?
+
+- **Zero Heavy Dependencies**: Instead of 50KB+ XML libraries, it uses the browser's native `DOMParser`.
+- **BaryoDev Powered**: Leverages `resilient-fetcher` for automatic retries and `nano-safe-storage` for robust caching.
+- **Normalized Schema**: No more worrying about the differences between RSS item tags and Atom entry tags. One clean JSON schema for everything.
+- **CORS Friendly**: Built-in support for popular proxies to bypass browser restrictions.
+- **Smart Cache**: Stale-while-revalidate inspired behavior via `localStorage`.
+
+## Installation
+
+```bash
+npm install feed-slurp
+```
+
+## Basic Usage
+
+```typescript
+import { slurp } from 'feed-slurp';
+
+// Slurp a feed with default settings (auto-cache for 1 hour)
+const feed = await slurp('https://medium.com/feed/@BaryoDev');
+
+console.log(feed.title); // "BaryoDev - Medium"
+console.log(feed.items[0].thumbnail); // Auto-extracted from content or tags!
+```
+
+## Advanced Configuration
+
+### CORS Proxies
+Most RSS feeds require a proxy for browser-based fetching. `feed-slurp` makes this easy:
+
+```typescript
+const feed = await slurp(url, {
+  proxy: 'allorigins' // Built-in: api.allorigins.win
+  // OR
+  proxy: 'corsproxy'  // Built-in: corsproxy.io
+  // OR
+  proxy: 'https://my-proxy.com/?url='
+  // OR custom function
+  proxy: (url) => `https://custom.worker.dev/fetch?target=${encodeURIComponent(url)}`
+});
+```
+
+### Caching Strategy
+Caching is enabled by default to save bandwidth and improve performance.
+
+```typescript
+const feed = await slurp(url, {
+  cache: true,
+  cacheTTL: 3600,       // 1 hour in seconds
+  cacheKey: 'my-feed'   // Custom key for localStorage
+});
+
+// Manual cache cleanup
+import { clearSlurpCache } from 'feed-slurp';
+clearSlurpCache('my-feed'); // Clear specific
+clearSlurpCache();          // Clear all
+```
+
+## Output Schema
+
+Regardless of whether the source is RSS 2.0 or Atom 1.0, you get this consistent structure:
+
+```typescript
+interface SlurpFeed {
+  title: string;
+  description: string;
+  link: string;
+  lastBuildDate: string;
+  items: SlurpItem[];
+}
+
+interface SlurpItem {
+  title: string;
+  link: string;
+  pubDate: string;        // ISO 8601 string
+  description: string;   // Plain text / snippet
+  content: string;       // Full HTML content
+  author: string;
+  categories: string[];
+  thumbnail: string | null; // Extracted thumbnail URL
+  guid: string;
+}
+```
+
+## License
+
+MPL-2.0 © Arnel I. Robles

package/dist/index.d.mts

@@ -0,0 +1,44 @@
+interface SlurpItem {
+    title: string;
+    link: string;
+    pubDate: string;
+    description: string;
+    content: string;
+    author: string;
+    categories: string[];
+    thumbnail: string | null;
+    guid: string;
+}
+interface SlurpFeed {
+    title: string;
+    description: string;
+    link: string;
+    lastBuildDate: string;
+    items: SlurpItem[];
+}
+interface SlurpOptions {
+    cache?: boolean;
+    cacheTTL?: number;
+    cacheKey?: string;
+    proxy?: string | ((url: string) => string);
+    timeout?: number;
+    retries?: number;
+}
+
+declare function clearSlurpCache(key?: string): void;
+
+/**
+ * Slurp an RSS or Atom feed.
+ * @param url The RSS/Atom feed URL
+ * @param options Configuration options
+ */
+declare function slurp(url: string, options?: SlurpOptions): Promise<SlurpFeed>;
+/**
+ * Fluent API for slurp
+ */
+declare function createSlurper(defaultOptions?: SlurpOptions): {
+    slurp: (url: string, options?: SlurpOptions) => Promise<SlurpFeed>;
+    clearCache: (key?: string) => void;
+};
+
+export { type SlurpFeed, type SlurpItem, type SlurpOptions, clearSlurpCache, createSlurper, slurp };

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+interface SlurpItem {
+    title: string;
+    link: string;
+    pubDate: string;
+    description: string;
+    content: string;
+    author: string;
+    categories: string[];
+    thumbnail: string | null;
+    guid: string;
+}
+interface SlurpFeed {
+    title: string;
+    description: string;
+    link: string;
+    lastBuildDate: string;
+    items: SlurpItem[];
+}
+interface SlurpOptions {
+    cache?: boolean;
+    cacheTTL?: number;
+    cacheKey?: string;
+    proxy?: string | ((url: string) => string);
+    timeout?: number;
+    retries?: number;
+}
+
+declare function clearSlurpCache(key?: string): void;
+
+/**
+ * Slurp an RSS or Atom feed.
+ * @param url The RSS/Atom feed URL
+ * @param options Configuration options
+ */
+declare function slurp(url: string, options?: SlurpOptions): Promise<SlurpFeed>;
+/**
+ * Fluent API for slurp
+ */
+declare function createSlurper(defaultOptions?: SlurpOptions): {
+    slurp: (url: string, options?: SlurpOptions) => Promise<SlurpFeed>;
+    clearCache: (key?: string) => void;
+};
+
+export { type SlurpFeed, type SlurpItem, type SlurpOptions, clearSlurpCache, createSlurper, slurp };

package/dist/index.js

@@ -0,0 +1,201 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  clearSlurpCache: () => clearSlurpCache,
+  createSlurper: () => createSlurper,
+  slurp: () => slurp
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/fetcher.ts
+var import_resilient_fetcher = require("resilient-fetcher");
+async function fetchFeedXml(url, options = {}) {
+  const { proxy, timeout = 1e4, retries = 3 } = options;
+  let requestUrl = url;
+  if (proxy) {
+    if (typeof proxy === "function") {
+      requestUrl = proxy(url);
+    } else {
+      switch (proxy) {
+        case "allorigins":
+          requestUrl = `https://api.allorigins.win/raw?url=${encodeURIComponent(url)}`;
+          break;
+        case "corsproxy":
+          requestUrl = `https://corsproxy.io/?${encodeURIComponent(url)}`;
+          break;
+        default:
+          requestUrl = `${proxy}${encodeURIComponent(url)}`;
+      }
+    }
+  }
+  const response = await (0, import_resilient_fetcher.resilientFetch)(requestUrl, {
+    retries,
+    timeout
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch feed: ${response.status} ${response.statusText}`);
+  }
+  return response.text();
+}
+
+// src/parser/xml.ts
+function parseXml(xmlString) {
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(xmlString, "text/xml");
+  const parseError = doc.getElementsByTagName("parsererror");
+  if (parseError.length > 0) {
+    throw new Error(`XML parsing failed: ${parseError[0].textContent}`);
+  }
+  return doc;
+}
+function getText(node, selector) {
+  if (!node) return "";
+  const el = node.querySelector(selector);
+  return el?.textContent?.trim() || "";
+}
+function getCDataOrText(node, selectors) {
+  if (!node) return "";
+  for (const selector of selectors) {
+    const el = node.querySelector(selector.replace(":", "\\:"));
+    if (el) return el.textContent?.trim() || "";
+  }
+  return "";
+}
+
+// src/parser/rss.ts
+function parseRss(doc) {
+  const channel = doc.querySelector("channel");
+  if (!channel) throw new Error("Invalid RSS feed: Missing <channel>");
+  const items = Array.from(doc.querySelectorAll("item")).map((item) => {
+    const description = getText(item, "description");
+    const content = getCDataOrText(item, ["content:encoded", "description"]);
+    return {
+      title: getText(item, "title"),
+      link: getText(item, "link"),
+      pubDate: new Date(getText(item, "pubDate")).toISOString(),
+      description,
+      content,
+      author: getText(item, "dc\\:creator") || "Unknown",
+      categories: Array.from(item.querySelectorAll("category")).map((c) => c.textContent || ""),
+      guid: getText(item, "guid") || getText(item, "link"),
+      thumbnail: extractThumbnail(item, content)
+    };
+  });
+  return {
+    title: getText(channel, "title"),
+    description: getText(channel, "description"),
+    link: getText(channel, "link"),
+    lastBuildDate: getText(channel, "lastBuildDate") || (/* @__PURE__ */ new Date()).toISOString(),
+    items
+  };
+}
+function extractThumbnail(item, content) {
+  const media = item.querySelector("media\\:content, media\\:thumbnail, enclosure[type^='image']");
+  if (media) {
+    return media.getAttribute("url") || media.getAttribute("src");
+  }
+  const match = content.match(/<img[^>]+src="([^">]+)"/);
+  return match ? match[1] : null;
+}
+
+// src/parser/atom.ts
+function parseAtom(doc) {
+  const feed = doc.querySelector("feed");
+  if (!feed) throw new Error("Invalid Atom feed: Missing <feed>");
+  const items = Array.from(doc.querySelectorAll("entry")).map((entry) => {
+    const content = getText(entry, "content") || getText(entry, "summary");
+    return {
+      title: getText(entry, "title"),
+      link: entry.querySelector("link[rel='alternate']")?.getAttribute("href") || entry.querySelector("link")?.getAttribute("href") || "",
+      pubDate: new Date(getText(entry, "updated") || getText(entry, "published")).toISOString(),
+      description: getText(entry, "summary"),
+      content,
+      author: getText(entry, "author name") || "Unknown",
+      categories: Array.from(entry.querySelectorAll("category")).map((c) => c.getAttribute("term") || ""),
+      guid: getText(entry, "id"),
+      thumbnail: extractThumbnail2(entry, content)
+    };
+  });
+  return {
+    title: getText(feed, "title"),
+    description: getText(feed, "subtitle") || "",
+    link: feed.querySelector("link[rel='alternate']")?.getAttribute("href") || feed.querySelector("link")?.getAttribute("href") || "",
+    lastBuildDate: getText(feed, "updated"),
+    items
+  };
+}
+function extractThumbnail2(entry, content) {
+  const enclosure = entry.querySelector("link[rel='enclosure'][type^='image']");
+  if (enclosure) return enclosure.getAttribute("href");
+  const match = content.match(/<img[^>]+src="([^">]+)"/);
+  return match ? match[1] : null;
+}
+
+// src/cache.ts
+var import_nano_safe_storage = require("nano-safe-storage");
+var storage = (0, import_nano_safe_storage.createStorage)({
+  prefix: "slurp_",
+  ttl: 3600
+  // Default 1 hour
+});
+function getCachedFeed(key) {
+  return storage.get(key);
+}
+function setCachedFeed(key, feed, ttl) {
+  storage.set(key, feed, ttl ? { ttl } : void 0);
+}
+function clearSlurpCache(key) {
+  if (key) {
+    storage.remove(key);
+  } else {
+    storage.clear();
+  }
+}
+
+// src/index.ts
+async function slurp(url, options = {}) {
+  const { cache = true, cacheTTL, cacheKey = url } = options;
+  if (cache) {
+    const cached = getCachedFeed(cacheKey);
+    if (cached) return cached;
+  }
+  const xml = await fetchFeedXml(url, options);
+  const doc = parseXml(xml);
+  const isAtom = doc.querySelector("feed") !== null;
+  const feed = isAtom ? parseAtom(doc) : parseRss(doc);
+  if (cache) {
+    setCachedFeed(cacheKey, feed, cacheTTL);
+  }
+  return feed;
+}
+function createSlurper(defaultOptions = {}) {
+  return {
+    slurp: (url, options = {}) => slurp(url, { ...defaultOptions, ...options }),
+    clearCache: (key) => clearSlurpCache(key)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearSlurpCache,
+  createSlurper,
+  slurp
+});

package/dist/index.mjs

@@ -0,0 +1,172 @@
+// src/fetcher.ts
+import { resilientFetch } from "resilient-fetcher";
+async function fetchFeedXml(url, options = {}) {
+  const { proxy, timeout = 1e4, retries = 3 } = options;
+  let requestUrl = url;
+  if (proxy) {
+    if (typeof proxy === "function") {
+      requestUrl = proxy(url);
+    } else {
+      switch (proxy) {
+        case "allorigins":
+          requestUrl = `https://api.allorigins.win/raw?url=${encodeURIComponent(url)}`;
+          break;
+        case "corsproxy":
+          requestUrl = `https://corsproxy.io/?${encodeURIComponent(url)}`;
+          break;
+        default:
+          requestUrl = `${proxy}${encodeURIComponent(url)}`;
+      }
+    }
+  }
+  const response = await resilientFetch(requestUrl, {
+    retries,
+    timeout
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch feed: ${response.status} ${response.statusText}`);
+  }
+  return response.text();
+}
+
+// src/parser/xml.ts
+function parseXml(xmlString) {
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(xmlString, "text/xml");
+  const parseError = doc.getElementsByTagName("parsererror");
+  if (parseError.length > 0) {
+    throw new Error(`XML parsing failed: ${parseError[0].textContent}`);
+  }
+  return doc;
+}
+function getText(node, selector) {
+  if (!node) return "";
+  const el = node.querySelector(selector);
+  return el?.textContent?.trim() || "";
+}
+function getCDataOrText(node, selectors) {
+  if (!node) return "";
+  for (const selector of selectors) {
+    const el = node.querySelector(selector.replace(":", "\\:"));
+    if (el) return el.textContent?.trim() || "";
+  }
+  return "";
+}
+
+// src/parser/rss.ts
+function parseRss(doc) {
+  const channel = doc.querySelector("channel");
+  if (!channel) throw new Error("Invalid RSS feed: Missing <channel>");
+  const items = Array.from(doc.querySelectorAll("item")).map((item) => {
+    const description = getText(item, "description");
+    const content = getCDataOrText(item, ["content:encoded", "description"]);
+    return {
+      title: getText(item, "title"),
+      link: getText(item, "link"),
+      pubDate: new Date(getText(item, "pubDate")).toISOString(),
+      description,
+      content,
+      author: getText(item, "dc\\:creator") || "Unknown",
+      categories: Array.from(item.querySelectorAll("category")).map((c) => c.textContent || ""),
+      guid: getText(item, "guid") || getText(item, "link"),
+      thumbnail: extractThumbnail(item, content)
+    };
+  });
+  return {
+    title: getText(channel, "title"),
+    description: getText(channel, "description"),
+    link: getText(channel, "link"),
+    lastBuildDate: getText(channel, "lastBuildDate") || (/* @__PURE__ */ new Date()).toISOString(),
+    items
+  };
+}
+function extractThumbnail(item, content) {
+  const media = item.querySelector("media\\:content, media\\:thumbnail, enclosure[type^='image']");
+  if (media) {
+    return media.getAttribute("url") || media.getAttribute("src");
+  }
+  const match = content.match(/<img[^>]+src="([^">]+)"/);
+  return match ? match[1] : null;
+}
+
+// src/parser/atom.ts
+function parseAtom(doc) {
+  const feed = doc.querySelector("feed");
+  if (!feed) throw new Error("Invalid Atom feed: Missing <feed>");
+  const items = Array.from(doc.querySelectorAll("entry")).map((entry) => {
+    const content = getText(entry, "content") || getText(entry, "summary");
+    return {
+      title: getText(entry, "title"),
+      link: entry.querySelector("link[rel='alternate']")?.getAttribute("href") || entry.querySelector("link")?.getAttribute("href") || "",
+      pubDate: new Date(getText(entry, "updated") || getText(entry, "published")).toISOString(),
+      description: getText(entry, "summary"),
+      content,
+      author: getText(entry, "author name") || "Unknown",
+      categories: Array.from(entry.querySelectorAll("category")).map((c) => c.getAttribute("term") || ""),
+      guid: getText(entry, "id"),
+      thumbnail: extractThumbnail2(entry, content)
+    };
+  });
+  return {
+    title: getText(feed, "title"),
+    description: getText(feed, "subtitle") || "",
+    link: feed.querySelector("link[rel='alternate']")?.getAttribute("href") || feed.querySelector("link")?.getAttribute("href") || "",
+    lastBuildDate: getText(feed, "updated"),
+    items
+  };
+}
+function extractThumbnail2(entry, content) {
+  const enclosure = entry.querySelector("link[rel='enclosure'][type^='image']");
+  if (enclosure) return enclosure.getAttribute("href");
+  const match = content.match(/<img[^>]+src="([^">]+)"/);
+  return match ? match[1] : null;
+}
+
+// src/cache.ts
+import { createStorage } from "nano-safe-storage";
+var storage = createStorage({
+  prefix: "slurp_",
+  ttl: 3600
+  // Default 1 hour
+});
+function getCachedFeed(key) {
+  return storage.get(key);
+}
+function setCachedFeed(key, feed, ttl) {
+  storage.set(key, feed, ttl ? { ttl } : void 0);
+}
+function clearSlurpCache(key) {
+  if (key) {
+    storage.remove(key);
+  } else {
+    storage.clear();
+  }
+}
+
+// src/index.ts
+async function slurp(url, options = {}) {
+  const { cache = true, cacheTTL, cacheKey = url } = options;
+  if (cache) {
+    const cached = getCachedFeed(cacheKey);
+    if (cached) return cached;
+  }
+  const xml = await fetchFeedXml(url, options);
+  const doc = parseXml(xml);
+  const isAtom = doc.querySelector("feed") !== null;
+  const feed = isAtom ? parseAtom(doc) : parseRss(doc);
+  if (cache) {
+    setCachedFeed(cacheKey, feed, cacheTTL);
+  }
+  return feed;
+}
+function createSlurper(defaultOptions = {}) {
+  return {
+    slurp: (url, options = {}) => slurp(url, { ...defaultOptions, ...options }),
+    clearCache: (key) => clearSlurpCache(key)
+  };
+}
+export {
+  clearSlurpCache,
+  createSlurper,
+  slurp
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "feed-slurp",
+    "version": "1.0.0",
+    "description": "A lightweight, zero-dependency (well, almost!) RSS/Atom feed fetcher and parser with built-in caching and proxy support.",
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+        "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+        "test": "vitest run",
+        "lint": "eslint src/**/*.ts"
+    },
+    "keywords": [
+        "rss",
+        "atom",
+        "feed",
+        "parser",
+        "fetcher",
+        "proxy",
+        "cache",
+        "slurp"
+    ],
+    "author": "Arnel I. Robles",
+    "license": "MPL-2.0",
+    "dependencies": {
+        "nano-safe-storage": "^1.0.0",
+        "resilient-fetcher": "^1.0.0"
+    },
+    "devDependencies": {
+        "tsup": "^8.0.0",
+        "typescript": "^5.0.0",
+        "vitest": "^1.0.0",
+        "jsdom": "^22.0.0",
+        "@types/node": "^20.0.0"
+    }
+}