@ozzylabs/feedradar 0.1.0

package/dist/core/feeds/html.js

@@ -0,0 +1,263 @@
+import { createHash } from "node:crypto";
+import { parse as parseHtml } from "node-html-parser";
+import { ItemSchema } from "../../schemas/index.js";
+import { deriveItemId, deriveStableKey } from "./derive-id.js";
+const USER_AGENT = "feedradar/0.0.0 (+https://github.com/ozzy-labs/feedradar)";
+/**
+ * Prefix that flags an `lastEtag` slot as carrying a content hash rather than
+ * an actual HTTP ETag. We reuse the `lastEtag` field so this Phase does not
+ * have to migrate `SourceState` (see `docs/design/source-html.md`).
+ */
+const CONTENT_HASH_PREFIX = "sha256:";
+/** Attributes the adapter checks before falling back to text content. */
+const DATETIME_ATTRS = ["datetime", "content", "value"];
+/**
+ * Convert an `HTMLElement | null` to its trimmed text, or `undefined` when
+ * the selector did not match. We always trim because raw scrapes routinely
+ * carry surrounding whitespace from formatted markup.
+ */
+function textOf(el) {
+    if (!el)
+        return undefined;
+    const text = el.text?.trim();
+    return text ? text : undefined;
+}
+/**
+ * Apply a CSS selector relative to `root` and return the first match.
+ * `node-html-parser` returns `null` instead of throwing for invalid input,
+ * which matches what callers want here (a missing field, not a hard error).
+ */
+function queryFirst(root, selector) {
+    return root.querySelector(selector);
+}
+/**
+ * Resolve the `link` selector to an `href` (or text fallback).
+ *
+ * Anchor tags expose the URL via `href` so we prefer the attribute. When the
+ * selector points at a non-anchor (e.g. a `<div data-link>` wrapper used by
+ * some changelog layouts), we fall back to text content so the adapter can
+ * still operate, deferring URL validation to `ItemSchema`.
+ */
+function pickLink(el) {
+    if (!el)
+        return undefined;
+    const href = el.getAttribute("href");
+    if (href && href.trim())
+        return href.trim();
+    return textOf(el);
+}
+/**
+ * Resolve `publishedAt` to a candidate string for `new Date()`.
+ *
+ * `<time datetime="2026-05-12">` and `<meta content="..."/>` markup hide the
+ * canonical timestamp in attributes; the visible text is often a
+ * localized "May 12, 2026" that is harder to parse reliably. We probe the
+ * known attributes first, then fall back to element text.
+ */
+function pickDatetime(el) {
+    if (!el)
+        return undefined;
+    for (const attr of DATETIME_ATTRS) {
+        const value = el.getAttribute(attr);
+        if (value && value.trim())
+            return value.trim();
+    }
+    return textOf(el);
+}
+/**
+ * Try to parse a candidate timestamp into ISO 8601. Returns `undefined` for
+ * unparseable inputs so the item can still be emitted (RSS adapter parity).
+ */
+function toIsoDate(value) {
+    if (!value)
+        return undefined;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    return date.toISOString();
+}
+/** Collect the trimmed text of every match for `selector`. */
+function collectTags(root, selector) {
+    if (!selector)
+        return undefined;
+    const tags = root
+        .querySelectorAll(selector)
+        .map((el) => el.text?.trim())
+        .filter((t) => !!t && t.length > 0);
+    return tags.length > 0 ? tags : undefined;
+}
+/**
+ * Resolve a relative `link` against the source URL.
+ *
+ * Many sites publish `<a href="/changelog/foo">` rather than absolute URLs;
+ * without resolution `ItemSchema`'s `z.string().url()` would drop them. We
+ * intentionally swallow `URL` constructor errors so a malformed `link`
+ * surfaces as a normal validation drop later instead of breaking the whole
+ * fetch.
+ */
+function resolveUrl(raw, base) {
+    try {
+        return new URL(raw, base).toString();
+    }
+    catch {
+        return raw;
+    }
+}
+/** Normalize one matched element into an Item, or `null` to drop it. */
+function parseItem(itemEl, selectors, source, fetchedAt) {
+    const title = textOf(queryFirst(itemEl, selectors.title));
+    const linkRaw = pickLink(queryFirst(itemEl, selectors.link));
+    if (!title || !linkRaw)
+        return null;
+    const url = resolveUrl(linkRaw, source.url);
+    const summary = selectors.summary ? textOf(queryFirst(itemEl, selectors.summary)) : undefined;
+    const body = selectors.body ? textOf(queryFirst(itemEl, selectors.body)) : undefined;
+    const publishedAt = selectors.publishedAt
+        ? toIsoDate(pickDatetime(queryFirst(itemEl, selectors.publishedAt)))
+        : undefined;
+    const tags = collectTags(itemEl, selectors.tags);
+    const stableKey = deriveStableKey({
+        url,
+        fallbackHashInputs: [title, publishedAt],
+    });
+    const id = deriveItemId(title, stableKey);
+    // Preserve a structured snapshot of the raw scrape rather than the
+    // `HTMLElement` instance itself — the watcher serializes `raw` to YAML and
+    // we want the on-disk payload to be diff-friendly.
+    const raw = { title, link: linkRaw };
+    if (summary !== undefined)
+        raw.summary = summary;
+    if (body !== undefined)
+        raw.body = body;
+    if (publishedAt !== undefined)
+        raw.publishedAt = publishedAt;
+    if (tags !== undefined)
+        raw.tags = tags;
+    return validateItem({
+        id,
+        sourceId: source.id,
+        title,
+        url,
+        summary,
+        publishedAt,
+        fetchedAt,
+        raw,
+    });
+}
+function validateItem(candidate) {
+    const result = ItemSchema.safeParse(candidate);
+    // Items that fail validation (e.g. unresolvable URL) are dropped silently —
+    // see rss.ts for the same fail-soft rationale.
+    return result.success ? result.data : null;
+}
+/**
+ * Parse an HTML document into validated `Item[]` using the source's
+ * `selectors`. Exported so tests can drive the parser directly without
+ * needing a fake HTTP layer.
+ */
+export function parseHtmlDocument(html, source, fetchedAt) {
+    if (!source.selectors) {
+        throw new Error(`html adapter: source '${source.id}' has no selectors`);
+    }
+    const selectors = source.selectors;
+    let root;
+    try {
+        root = parseHtml(html);
+    }
+    catch (e) {
+        throw new Error(`html adapter: failed to parse HTML: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const itemEls = root.querySelectorAll(selectors.item);
+    return itemEls
+        .map((el) => parseItem(el, selectors, source, fetchedAt))
+        .filter((i) => i !== null);
+}
+/**
+ * Compute the sha256 of the raw response body, prefixed so callers can tell
+ * it apart from a real ETag inside `SourceState.lastEtag`.
+ */
+function contentHash(body) {
+    return `${CONTENT_HASH_PREFIX}${createHash("sha256").update(body).digest("hex")}`;
+}
+/**
+ * Issue an HTTP GET with conditional headers. The previous `lastEtag` slot
+ * may contain either an actual ETag (mirror RSS behavior) or a `sha256:`
+ * content hash; we only forward real ETags as `If-None-Match`.
+ */
+async function fetchHtml(url, fetchImpl, options = {}) {
+    const headers = {
+        accept: "text/html, application/xhtml+xml;q=0.9, */*;q=0.5",
+        "user-agent": USER_AGENT,
+    };
+    // Only forward the previous value to the server when it looks like a real
+    // ETag; a `sha256:` slot is our own dedup marker, not something the server
+    // sent us.
+    if (options.etag && !options.etag.startsWith(CONTENT_HASH_PREFIX)) {
+        headers["if-none-match"] = options.etag;
+    }
+    const response = await fetchImpl(url, { headers, signal: options.signal });
+    const etag = response.headers.get("etag");
+    if (response.status === 304) {
+        return { status: 304, body: "", etag };
+    }
+    if (response.status < 200 || response.status >= 300) {
+        throw new Error(`html adapter: HTTP ${response.status} from ${url}`);
+    }
+    const body = await response.text();
+    return { status: response.status, body, etag };
+}
+export const htmlAdapter = {
+    kind: "html",
+    fetch: async (source, options = {}) => {
+        if (!source.selectors) {
+            throw new Error(`html adapter: source '${source.id}' has no selectors`);
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new Error("html adapter: no fetch implementation available (Node 22+ required)");
+        }
+        const previous = options.state;
+        const fetchedAt = new Date().toISOString();
+        const response = await fetchHtml(source.url, fetchImpl, {
+            etag: previous?.lastEtag,
+        });
+        if (response.status === 304) {
+            return {
+                items: [],
+                notModified: true,
+                state: {
+                    lastFetchedAt: fetchedAt,
+                    // Preserve whatever marker we had — server may not echo the ETag
+                    // back on 304, in which case we keep the previous content hash too.
+                    lastEtag: response.etag ?? previous?.lastEtag,
+                },
+            };
+        }
+        // Content-hash fallback: when the server does not return an ETag at all,
+        // compare a sha256 of the body against the previous one we recorded so
+        // re-fetches without a real ETag still dedup correctly.
+        const bodyHash = contentHash(response.body);
+        const previousMarker = previous?.lastEtag;
+        if (!response.etag && previousMarker === bodyHash) {
+            return {
+                items: [],
+                notModified: true,
+                state: {
+                    lastFetchedAt: fetchedAt,
+                    lastEtag: bodyHash,
+                },
+            };
+        }
+        const items = parseHtmlDocument(response.body, source, fetchedAt);
+        return {
+            items,
+            state: {
+                lastFetchedAt: fetchedAt,
+                // Prefer the real ETag when the server provides one; otherwise stash
+                // the content hash in the same slot for next-run dedup.
+                lastEtag: response.etag ?? bodyHash,
+            },
+        };
+    },
+};
+//# sourceMappingURL=html.js.map

package/dist/core/feeds/html.js.map

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

package/dist/core/feeds/index.d.ts

@@ -0,0 +1,5 @@
+import type { Source } from "../../schemas/index.js";
+import type { FeedAdapter } from "./types.js";
+export declare function getFeedAdapter(kind: Source["kind"]): FeedAdapter;
+export type { FeedAdapter, FeedAdapterOptions, FeedFetchResult, FetchLike } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/feeds/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAKrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAS9C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,WAAW,CAMhE;AAED,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/feeds/index.js

@@ -0,0 +1,18 @@
+import { githubReleasesAdapter } from "./github-releases.js";
+import { htmlAdapter } from "./html.js";
+import { npmRegistryAdapter } from "./npm-registry.js";
+import { rssAdapter } from "./rss.js";
+const adapters = new Map([
+    [rssAdapter.kind, rssAdapter],
+    [htmlAdapter.kind, htmlAdapter],
+    [githubReleasesAdapter.kind, githubReleasesAdapter],
+    [npmRegistryAdapter.kind, npmRegistryAdapter],
+]);
+export function getFeedAdapter(kind) {
+    const adapter = adapters.get(kind);
+    if (!adapter) {
+        throw new Error(`No feed adapter registered for kind: ${kind}`);
+    }
+    return adapter;
+}
+//# sourceMappingURL=index.js.map

package/dist/core/feeds/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/feeds/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAA8B;IACpD,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC;IAC7B,CAAC,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC;IAC/B,CAAC,qBAAqB,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACnD,CAAC,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,CAAC;CAC9C,CAAC,CAAC;AAEH,MAAM,UAAU,cAAc,CAAC,IAAoB;IACjD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,wCAAwC,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/core/feeds/npm-registry.d.ts

@@ -0,0 +1,36 @@
+import type { Item, Source } from "../../schemas/index.js";
+import type { FeedAdapter } from "./types.js";
+/**
+ * Extract the canonical npm package name from a source URL.
+ *
+ * Accepts both the bare-package form (`@scope/pkg` or `pkg`) and the public
+ * npmjs.com URL form (`https://www.npmjs.com/package/<pkg>` /
+ * `https://npmjs.com/package/<pkg>`). The latter is the only shape the strict
+ * `z.string().url()` validator used to accept, but per #38 the user-guide
+ * documents both forms; the schema now relaxes the constraint for
+ * `kind: "npm-registry"` so the helper here is the single place that knows
+ * about the two shapes.
+ *
+ * Returns `undefined` for inputs that look like an HTTP(S) URL but do not
+ * point at an npm package, so the caller can surface a clear error.
+ */
+export declare function extractPackageName(rawUrl: string): string | undefined;
+/**
+ * Compose the `https://registry.npmjs.org/<pkg>` URL.
+ *
+ * Scoped packages must keep their `@` and slash *unescaped* — the npm registry
+ * routes `@scope%2fname` and `@scope/name` differently and only the latter
+ * resolves. `encodeURIComponent` would mangle the slash, so we pass the name
+ * through verbatim.
+ */
+export declare function buildMetadataUrl(packageName: string): string;
+/**
+ * Parse an npm registry packument response into validated `Item[]`.
+ *
+ * The exported function exists so tests can exercise the normalizer without
+ * round-tripping through the HTTP layer (matching `parseFeedXml` in
+ * `rss.ts`).
+ */
+export declare function parsePackument(body: string, source: Source, fetchedAt: string, packageName: string): Item[];
+export declare const npmRegistryAdapter: FeedAdapter;
+//# sourceMappingURL=npm-registry.d.ts.map

package/dist/core/feeds/npm-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm-registry.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/npm-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,KAAK,EAAE,WAAW,EAAiC,MAAM,YAAY,CAAC;AAsB7E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAqBrE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5D;AA8DD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,IAAI,EAAE,CAiBR;AAkCD,eAAO,MAAM,kBAAkB,EAAE,WAwChC,CAAC"}

package/dist/core/feeds/npm-registry.js

@@ -0,0 +1,200 @@
+import { ItemSchema } from "../../schemas/index.js";
+import { deriveItemId, deriveStableKey } from "./derive-id.js";
+const USER_AGENT = "feedradar/0.0.0 (+https://github.com/ozzy-labs/feedradar)";
+const REGISTRY_BASE = "https://registry.npmjs.org";
+/**
+ * Extract the canonical npm package name from a source URL.
+ *
+ * Accepts both the bare-package form (`@scope/pkg` or `pkg`) and the public
+ * npmjs.com URL form (`https://www.npmjs.com/package/<pkg>` /
+ * `https://npmjs.com/package/<pkg>`). The latter is the only shape the strict
+ * `z.string().url()` validator used to accept, but per #38 the user-guide
+ * documents both forms; the schema now relaxes the constraint for
+ * `kind: "npm-registry"` so the helper here is the single place that knows
+ * about the two shapes.
+ *
+ * Returns `undefined` for inputs that look like an HTTP(S) URL but do not
+ * point at an npm package, so the caller can surface a clear error.
+ */
+export function extractPackageName(rawUrl) {
+    const trimmed = rawUrl.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    // URL form: pull the path segment after `/package/`.
+    if (/^https?:\/\//i.test(trimmed)) {
+        let parsed;
+        try {
+            parsed = new URL(trimmed);
+        }
+        catch {
+            return undefined;
+        }
+        const host = parsed.host.toLowerCase();
+        if (host !== "npmjs.com" && host !== "www.npmjs.com")
+            return undefined;
+        // `/package/<pkg>` and `/package/<pkg>/v/<version>` are both valid; strip
+        // anything after the package segment.
+        const match = parsed.pathname.match(/^\/package\/((?:@[^/]+\/)?[^/]+)/);
+        if (!match)
+            return undefined;
+        return decodeURIComponent(match[1] ?? "") || undefined;
+    }
+    // Bare-package form.
+    return trimmed;
+}
+/**
+ * Compose the `https://registry.npmjs.org/<pkg>` URL.
+ *
+ * Scoped packages must keep their `@` and slash *unescaped* — the npm registry
+ * routes `@scope%2fname` and `@scope/name` differently and only the latter
+ * resolves. `encodeURIComponent` would mangle the slash, so we pass the name
+ * through verbatim.
+ */
+export function buildMetadataUrl(packageName) {
+    return `${REGISTRY_BASE}/${packageName}`;
+}
+/**
+ * Compose the canonical `Item.url` for a specific package version.
+ *
+ * Always uses `www.npmjs.com` (matches the redirect target of the bare
+ * `npmjs.com` host) so re-derivation across re-fetches stays byte-stable.
+ */
+function buildItemUrl(packageName, version) {
+    return `https://www.npmjs.com/package/${packageName}/v/${version}`;
+}
+/** Convert ISO datetime strings from `time[<version>]` into normalized form. */
+function toIsoDate(value) {
+    if (!value)
+        return undefined;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    return date.toISOString();
+}
+/**
+ * Normalize one `<package>@<version>` entry into our `Item` shape.
+ *
+ * `Item.id` is derived via the shared helper so npm-registry items follow the
+ * same `<slug>-<8 hex>` contract as RSS / Atom items (ADR-0002 §Item ID 派生
+ * のコントラクト). The slug source is `<package>@<version>` so ids remain
+ * human-readable in CLI listings.
+ */
+function buildItem(packument, packageName, version, source, fetchedAt) {
+    const versionMeta = packument.versions?.[version];
+    // Drop a version when the packument lies about claiming it but the entry is
+    // missing — the registry sometimes lists tombstoned versions in `time` but
+    // omits them from `versions`. Skipping rather than erroring keeps the run
+    // green for ordinary feeds.
+    if (!versionMeta)
+        return null;
+    const stableKey = deriveStableKey({
+        publisherId: `${packageName}@${version}`,
+    });
+    const title = `${packageName}@${version}`;
+    const id = deriveItemId(title, stableKey);
+    const candidate = {
+        id,
+        sourceId: source.id,
+        title,
+        url: buildItemUrl(packageName, version),
+        fetchedAt,
+        publishedAt: toIsoDate(packument.time?.[version]),
+        summary: versionMeta.description,
+        raw: { package: packageName, version, ...versionMeta },
+    };
+    const result = ItemSchema.safeParse(candidate);
+    // Mirror the rss adapter: drop malformed entries silently rather than
+    // failing the whole feed for one bad version.
+    return result.success ? result.data : null;
+}
+/**
+ * Parse an npm registry packument response into validated `Item[]`.
+ *
+ * The exported function exists so tests can exercise the normalizer without
+ * round-tripping through the HTTP layer (matching `parseFeedXml` in
+ * `rss.ts`).
+ */
+export function parsePackument(body, source, fetchedAt, packageName) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch (e) {
+        throw new Error(`npm-registry adapter: failed to parse JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const versions = parsed.versions;
+    if (!versions)
+        return [];
+    const items = [];
+    for (const version of Object.keys(versions)) {
+        const item = buildItem(parsed, packageName, version, source, fetchedAt);
+        if (item)
+            items.push(item);
+    }
+    return items;
+}
+/**
+ * Fetch the npm registry packument with ETag-aware conditional GET.
+ *
+ * The registry honors `If-None-Match` and replies 304 for unchanged
+ * packuments, which is how we keep `watch run` cheap for stable packages.
+ */
+async function fetchPackument(url, fetchImpl, options = {}) {
+    const headers = {
+        accept: "application/json",
+        "user-agent": USER_AGENT,
+    };
+    if (options.etag)
+        headers["if-none-match"] = options.etag;
+    const response = await fetchImpl(url, { headers, signal: options.signal });
+    const etag = response.headers.get("etag");
+    if (response.status === 304) {
+        return { status: 304, body: "", etag };
+    }
+    if (response.status === 404) {
+        throw new Error(`npm-registry adapter: package not found (HTTP 404) at ${url}`);
+    }
+    if (response.status < 200 || response.status >= 300) {
+        throw new Error(`npm-registry adapter: HTTP ${response.status} from ${url}`);
+    }
+    const body = await response.text();
+    return { status: response.status, body, etag };
+}
+export const npmRegistryAdapter = {
+    kind: "npm-registry",
+    fetch: async (source, options = {}) => {
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new Error("npm-registry adapter: no fetch implementation available (Node 22+ required)");
+        }
+        const packageName = extractPackageName(source.url);
+        if (!packageName) {
+            throw new Error(`npm-registry adapter: cannot extract package name from url '${source.url}' ` +
+                "(expected '<package>' or 'https://www.npmjs.com/package/<package>')");
+        }
+        const previous = options.state;
+        const fetchedAt = new Date().toISOString();
+        const response = await fetchPackument(buildMetadataUrl(packageName), fetchImpl, {
+            etag: previous?.lastEtag,
+        });
+        if (response.status === 304) {
+            return {
+                items: [],
+                notModified: true,
+                state: {
+                    lastFetchedAt: fetchedAt,
+                    lastEtag: response.etag ?? previous?.lastEtag,
+                },
+            };
+        }
+        const items = parsePackument(response.body, source, fetchedAt, packageName);
+        return {
+            items,
+            state: {
+                lastFetchedAt: fetchedAt,
+                lastEtag: response.etag ?? previous?.lastEtag,
+            },
+        };
+    },
+};
+//# sourceMappingURL=npm-registry.js.map

package/dist/core/feeds/npm-registry.js.map

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

package/dist/core/feeds/rss.d.ts

@@ -0,0 +1,12 @@
+import type { Item, Source } from "../../schemas/index.js";
+import type { FeedAdapter } from "./types.js";
+/**
+ * Parse an RSS 2.0 or Atom XML document into validated `Item[]`.
+ *
+ * `fast-xml-parser` is intentionally configured to keep attribute prefixes
+ * (`@_href`) and skip CDATA stripping so we can route through the same
+ * normalizer regardless of which dialect we are reading.
+ */
+export declare function parseFeedXml(xml: string, source: Source, fetchedAt: string): Item[];
+export declare const rssAdapter: FeedAdapter;
+//# sourceMappingURL=rss.d.ts.map

package/dist/core/feeds/rss.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rss.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/rss.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,KAAK,EAAE,WAAW,EAAiC,MAAM,YAAY,CAAC;AAyJ7E;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,CAsCnF;AAgCD,eAAO,MAAM,UAAU,EAAE,WAkCxB,CAAC"}