@depwatch/source-rss 0.0.7 → 0.1.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,58 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.htmlToPlainText = htmlToPlainText;
4
+ exports.parsePublicationDate = parsePublicationDate;
5
+ exports.parseZonedDateTime = parseZonedDateTime;
6
+ /** Text and date helpers for vendor notices. Ported from depwatch 0.0.7 `source-rss/src/parsing.ts` (behaviour unchanged). */
7
+ const html_to_text_1 = require("html-to-text");
8
+ const luxon_1 = require("luxon");
9
+ const core_1 = require("@depwatch/core");
10
+ const parse_rss_js_1 = require("./parse-rss.js");
11
+ /** One HTML decoding pass after XML decoding; never decodes recursively, drops scripts/styles/images and link targets. */
12
+ function htmlToPlainText(html, maxBytes = 1_000_000) {
13
+ (0, core_1.positiveInt)(maxBytes, 'maxBytes');
14
+ if (Buffer.byteLength(html, 'utf8') > maxBytes)
15
+ throw new parse_rss_js_1.RssParseError('html_too_large');
16
+ return (0, html_to_text_1.convert)(html, {
17
+ wordwrap: false,
18
+ limits: { maxInputLength: maxBytes, maxDepth: 64 },
19
+ selectors: [
20
+ { selector: 'a', options: { ignoreHref: true } },
21
+ { selector: 'img', format: 'skip' },
22
+ { selector: 'script', format: 'skip' },
23
+ { selector: 'style', format: 'skip' },
24
+ ],
25
+ })
26
+ .replace(/\s+/g, ' ')
27
+ .trim();
28
+ }
29
+ /** RFC 2822 date with an explicit offset (or GMT/UT), including weekday validation. No local-zone fallback. */
30
+ function parsePublicationDate(value) {
31
+ if (!/(?:[+-]\d{4}|GMT|UT)$/i.test(value.trim()))
32
+ return null;
33
+ const parsed = luxon_1.DateTime.fromRFC2822(value, { setZone: true });
34
+ return parsed.isValid ? parsed.toJSDate() : null;
35
+ }
36
+ const FIELDS = ['year', 'month', 'day', 'hour', 'minute'];
37
+ /** Converts a wall-clock time in `zone` to a Date, rejecting DST gaps and folds instead of guessing. */
38
+ function parseZonedDateTime(parts, zone) {
39
+ const valid = !!parts &&
40
+ FIELDS.every((key) => Number.isSafeInteger(parts[key])) &&
41
+ Object.keys(parts).every((key) => FIELDS.includes(key));
42
+ if (!valid)
43
+ return { ok: false, issue: 'invalid_local_time' };
44
+ let parsed;
45
+ try {
46
+ parsed = luxon_1.DateTime.fromObject(parts, { zone });
47
+ }
48
+ catch {
49
+ return { ok: false, issue: 'invalid_local_time' };
50
+ }
51
+ if (!parsed.isValid)
52
+ return { ok: false, issue: 'invalid_local_time' };
53
+ if (FIELDS.some((key) => parsed.get(key) !== parts[key]))
54
+ return { ok: false, issue: 'nonexistent_local_time' };
55
+ if (parsed.getPossibleOffsets().length !== 1)
56
+ return { ok: false, issue: 'ambiguous_local_time' };
57
+ return { ok: true, value: parsed.toJSDate() };
58
+ }
@@ -0,0 +1,42 @@
1
+ import type { HttpClient } from '@depwatch/core';
2
+ import { type ParseLimits, type RssFeed } from './parse-rss.js';
3
+ export interface RssValidators {
4
+ etag?: string;
5
+ lastModified?: string;
6
+ }
7
+ export type RssErrorKind = 'timeout' | 'cancelled' | 'http' | 'auth' | 'parse' | 'network';
8
+ export type FetchRssResult = {
9
+ outcome: 'ok';
10
+ feed: RssFeed;
11
+ validators: RssValidators;
12
+ } | {
13
+ outcome: 'not_modified';
14
+ validators: RssValidators;
15
+ } | {
16
+ outcome: 'error';
17
+ error: {
18
+ kind: RssErrorKind;
19
+ message: string;
20
+ status?: number;
21
+ retryAfterMs?: number;
22
+ };
23
+ };
24
+ export interface FetchRssOptions {
25
+ url: string;
26
+ httpClient: HttpClient;
27
+ /** Current time; used to interpret an HTTP-date Retry-After. */
28
+ now: Date;
29
+ /** Validators from the previous successful response, sent as If-None-Match / If-Modified-Since. */
30
+ validators?: RssValidators;
31
+ signal?: AbortSignal;
32
+ requestTimeoutMs?: number;
33
+ limits?: ParseLimits;
34
+ }
35
+ /** Parses Retry-After as delay-seconds or an HTTP-date; returns undefined when absent or unusable. */
36
+ export declare function parseRetryAfter(value: string | undefined, now: Date): number | undefined;
37
+ /**
38
+ * Fetches and parses an RSS feed with a timeout, byte limit, conditional request and no redirects.
39
+ * Never throws for network/HTTP/parse problems; returns `{ outcome: 'error' }` with a safe category instead.
40
+ * Error messages never include URLs, headers or raw exception text.
41
+ */
42
+ export declare function fetchRss(options: FetchRssOptions): Promise<FetchRssResult>;
@@ -0,0 +1,158 @@
1
+ /**
2
+ * One bounded, conditional RSS request. Ported from depwatch 0.0.7 `RssStatusAdapter.poll()` as a plain function.
3
+ * Scheduling, retries and persistence belong to the caller (the depwatch monitor).
4
+ */
5
+ import { MAX_TIMER_MS, httpUrl, positiveInt, validDate } from '@depwatch/core';
6
+ import { parseRss, resolveLimits, RssParseError } from './parse-rss.js';
7
+ const ACCEPTED_TYPES = ['application/rss+xml', 'application/xml', 'text/xml'];
8
+ function safeHeaderValue(value) {
9
+ return typeof value === 'string' && value.length > 0 && value.length <= 1024 && !/[\r\n]/.test(value);
10
+ }
11
+ function requestHeaders(validators) {
12
+ const headers = { Accept: ACCEPTED_TYPES.join(', ') };
13
+ if (safeHeaderValue(validators?.etag))
14
+ headers['If-None-Match'] = validators.etag;
15
+ if (safeHeaderValue(validators?.lastModified))
16
+ headers['If-Modified-Since'] = validators.lastModified;
17
+ return headers;
18
+ }
19
+ function responseValidators(headers) {
20
+ const validators = {};
21
+ if (safeHeaderValue(headers['etag']))
22
+ validators.etag = headers['etag'];
23
+ if (safeHeaderValue(headers['last-modified']))
24
+ validators.lastModified = headers['last-modified'];
25
+ return validators;
26
+ }
27
+ /** Parses Retry-After as delay-seconds or an HTTP-date; returns undefined when absent or unusable. */
28
+ export function parseRetryAfter(value, now) {
29
+ if (!value)
30
+ return undefined;
31
+ const ms = /^\d+$/.test(value) ? Number(value) * 1000 : Date.parse(value) - now.getTime();
32
+ return Number.isSafeInteger(ms) && ms >= 0 ? ms : undefined;
33
+ }
34
+ function cancelQuietly(response) {
35
+ if (!response)
36
+ return;
37
+ try {
38
+ void Promise.resolve(response.cancel()).catch(() => { });
39
+ }
40
+ catch {
41
+ // Cleanup must not hide the fetch result.
42
+ }
43
+ }
44
+ async function readBody(response, maxBytes, aborted) {
45
+ if (!response.body)
46
+ throw new RssParseError('empty_response');
47
+ const chunks = [];
48
+ let bytes = 0;
49
+ const iterator = response.body[Symbol.asyncIterator]();
50
+ while (true) {
51
+ const { done, value } = await iterator.next();
52
+ if (aborted())
53
+ throw new Error('request_aborted');
54
+ if (done)
55
+ break;
56
+ if (!(value instanceof Uint8Array))
57
+ throw new RssParseError('invalid_body_chunk');
58
+ bytes += value.byteLength;
59
+ if (bytes > maxBytes)
60
+ throw new RssParseError('response_too_large');
61
+ chunks.push(value);
62
+ }
63
+ try {
64
+ return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks, bytes));
65
+ }
66
+ catch {
67
+ throw new RssParseError('invalid_utf8');
68
+ }
69
+ }
70
+ /**
71
+ * Fetches and parses an RSS feed with a timeout, byte limit, conditional request and no redirects.
72
+ * Never throws for network/HTTP/parse problems; returns `{ outcome: 'error' }` with a safe category instead.
73
+ * Error messages never include URLs, headers or raw exception text.
74
+ */
75
+ export async function fetchRss(options) {
76
+ const url = httpUrl(options.url);
77
+ const now = validDate(options.now, 'now');
78
+ if (!options.httpClient || typeof options.httpClient.request !== 'function') {
79
+ throw new TypeError('httpClient is required');
80
+ }
81
+ const timeoutMs = positiveInt(options.requestTimeoutMs ?? 15_000, 'requestTimeoutMs', MAX_TIMER_MS);
82
+ const limits = resolveLimits(options.limits);
83
+ const headers = requestHeaders(options.validators);
84
+ const sentValidators = 'If-None-Match' in headers || 'If-Modified-Since' in headers;
85
+ const controller = new AbortController();
86
+ let timedOut = false;
87
+ let response;
88
+ let rejectAborted = () => { };
89
+ const aborted = new Promise((_, reject) => {
90
+ rejectAborted = reject;
91
+ });
92
+ aborted.catch(() => { });
93
+ const abort = () => {
94
+ controller.abort();
95
+ cancelQuietly(response);
96
+ rejectAborted(new Error('request_aborted'));
97
+ };
98
+ const timer = setTimeout(() => {
99
+ timedOut = true;
100
+ abort();
101
+ }, timeoutMs);
102
+ options.signal?.addEventListener('abort', abort, { once: true });
103
+ if (options.signal?.aborted)
104
+ abort();
105
+ let stage = 'network';
106
+ const run = async () => {
107
+ if (controller.signal.aborted)
108
+ throw new Error('request_aborted');
109
+ response = await options.httpClient.request({ url, method: 'GET', headers, signal: controller.signal });
110
+ if (controller.signal.aborted)
111
+ throw new Error('request_aborted');
112
+ const validators = responseValidators(response.headers);
113
+ const status = response.status;
114
+ if (status === 304) {
115
+ if (!sentValidators)
116
+ return { outcome: 'error', error: { kind: 'http', status, message: 'unexpected_304' } };
117
+ return { outcome: 'not_modified', validators: { ...options.validators, ...validators } };
118
+ }
119
+ if (status < 200 || status >= 300) {
120
+ const retryAfterMs = parseRetryAfter(response.headers['retry-after'], now);
121
+ const kind = status === 401 || status === 403 ? 'auth' : 'http';
122
+ return {
123
+ outcome: 'error',
124
+ error: { kind, status, message: `http_${status}`, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) },
125
+ };
126
+ }
127
+ stage = 'parse';
128
+ const contentType = response.headers['content-type']?.split(';')[0]?.trim().toLowerCase();
129
+ if (contentType && !ACCEPTED_TYPES.includes(contentType))
130
+ throw new RssParseError('invalid_content_type');
131
+ const length = response.headers['content-length'];
132
+ if (length && Number(length) > limits.maxBytes)
133
+ throw new RssParseError('response_too_large');
134
+ stage = 'network';
135
+ const xml = await readBody(response, limits.maxBytes, () => controller.signal.aborted).catch((error) => {
136
+ if (error instanceof RssParseError)
137
+ stage = 'parse';
138
+ throw error;
139
+ });
140
+ stage = 'parse';
141
+ return { outcome: 'ok', feed: parseRss(xml, limits), validators };
142
+ };
143
+ try {
144
+ return await Promise.race([run(), aborted]);
145
+ }
146
+ catch (error) {
147
+ const kind = timedOut ? 'timeout' : options.signal?.aborted ? 'cancelled' : stage;
148
+ return {
149
+ outcome: 'error',
150
+ error: { kind, message: error instanceof RssParseError ? error.code : `rss_${kind}_failure` },
151
+ };
152
+ }
153
+ finally {
154
+ clearTimeout(timer);
155
+ options.signal?.removeEventListener('abort', abort);
156
+ cancelQuietly(response);
157
+ }
158
+ }
@@ -1,17 +1,4 @@
1
- import type { Logger, HttpClient } from '@depwatch/core';
2
- export * from './parsing.js';
3
- export * from './RssStatusAdapter.js';
4
- export interface RssSourceContext {
5
- readonly url: string;
6
- readonly httpClient: HttpClient;
7
- /** @deprecated Use httpClient. */
8
- readonly fetch?: typeof globalThis.fetch;
9
- readonly logger: Logger;
10
- }
11
- /** Compatibility context helper; use adapter options or PollContext.httpClient for polling. */
12
- export declare function createRssSourceContext(options: {
13
- url: string;
14
- httpClient?: HttpClient;
15
- fetch?: typeof globalThis.fetch;
16
- logger: Logger;
17
- }): RssSourceContext;
1
+ export { parseRss, resolveLimits, RssParseError, DEFAULT_LIMITS, type RssItem, type RssFeed, type ParseLimits, } from './parse-rss.js';
2
+ export { htmlToPlainText, parsePublicationDate, parseZonedDateTime, type LocalDateTime, type DateTimeResult, } from './text.js';
3
+ export { fetchRss, parseRetryAfter, type FetchRssOptions, type FetchRssResult, type RssValidators, type RssErrorKind, } from './fetch-rss.js';
4
+ export { createRssSource, type RssSourceOptions } from './rss-source.js';
package/dist/esm/index.js CHANGED
@@ -1,11 +1,4 @@
1
- import { createFetchHttpClient } from '@depwatch/core';
2
- export * from './parsing.js';
3
- export * from './RssStatusAdapter.js';
4
- /** Compatibility context helper; use adapter options or PollContext.httpClient for polling. */
5
- export function createRssSourceContext(options) {
6
- const url = new URL(options.url);
7
- if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
8
- throw new TypeError('RSS URL must be HTTP(S) without embedded credentials');
9
- return Object.freeze({ url: url.href, httpClient: options.httpClient ?? createFetchHttpClient(options.fetch), ...(options.fetch ? { fetch: options.fetch } : {}), logger: options.logger.child({ component: 'depwatch.source-rss' }) });
10
- }
11
- //# sourceMappingURL=index.js.map
1
+ export { parseRss, resolveLimits, RssParseError, DEFAULT_LIMITS, } from './parse-rss.js';
2
+ export { htmlToPlainText, parsePublicationDate, parseZonedDateTime, } from './text.js';
3
+ export { fetchRss, parseRetryAfter, } from './fetch-rss.js';
4
+ export { createRssSource } from './rss-source.js';
@@ -0,0 +1,24 @@
1
+ export interface RssItem {
2
+ title: string;
3
+ descriptionHtml: string;
4
+ guid: string;
5
+ link: string;
6
+ pubDate: string;
7
+ }
8
+ export interface RssFeed {
9
+ title: string;
10
+ items: RssItem[];
11
+ }
12
+ export interface ParseLimits {
13
+ maxBytes?: number;
14
+ maxItems?: number;
15
+ maxDepth?: number;
16
+ }
17
+ export declare const DEFAULT_LIMITS: Readonly<Required<ParseLimits>>;
18
+ /** A parse failure with a stable, safe `code` (never includes feed content). */
19
+ export declare class RssParseError extends Error {
20
+ readonly code: string;
21
+ constructor(code: string);
22
+ }
23
+ export declare function resolveLimits(limits?: ParseLimits): Required<ParseLimits>;
24
+ export declare function parseRss(xml: string, limits?: ParseLimits): RssFeed;
@@ -0,0 +1,131 @@
1
+ /**
2
+ * Pure, bounded RSS 2.0 parsing. Ported from depwatch 0.0.7 `source-rss/src/parsing.ts` (behaviour unchanged).
3
+ * Descriptions must contain escaped HTML or CDATA.
4
+ */
5
+ import { XMLParser, XMLValidator } from 'fast-xml-parser';
6
+ import { positiveInt } from '@depwatch/core';
7
+ export const DEFAULT_LIMITS = Object.freeze({
8
+ maxBytes: 1_000_000,
9
+ maxItems: 1000,
10
+ maxDepth: 64,
11
+ });
12
+ /** A parse failure with a stable, safe `code` (never includes feed content). */
13
+ export class RssParseError extends Error {
14
+ code;
15
+ constructor(code) {
16
+ super(code);
17
+ this.code = code;
18
+ this.name = 'RssParseError';
19
+ }
20
+ }
21
+ export function resolveLimits(limits = {}) {
22
+ return {
23
+ maxBytes: positiveInt(limits.maxBytes ?? DEFAULT_LIMITS.maxBytes, 'maxBytes'),
24
+ maxItems: positiveInt(limits.maxItems ?? DEFAULT_LIMITS.maxItems, 'maxItems'),
25
+ maxDepth: positiveInt(limits.maxDepth ?? DEFAULT_LIMITS.maxDepth, 'maxDepth'),
26
+ };
27
+ }
28
+ function text(value) {
29
+ if (value === undefined || value === '')
30
+ return '';
31
+ if (typeof value === 'string')
32
+ return value;
33
+ if (value && typeof value === 'object' && !Array.isArray(value)) {
34
+ const node = value;
35
+ if (Object.keys(node).every((k) => k === '#text' || k.startsWith('@_')))
36
+ return text(node['#text']);
37
+ }
38
+ throw new RssParseError('invalid_text_node');
39
+ }
40
+ function object(value) {
41
+ if (!value || typeof value !== 'object' || Array.isArray(value))
42
+ throw new RssParseError('invalid_rss_structure');
43
+ return value;
44
+ }
45
+ const INVALID_XML_CHARS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uD800-\uDFFF￾￿]/u;
46
+ const DECLARATION = /<!\s*(?:DOCTYPE|ENTITY)\b/i;
47
+ const OPAQUE_SECTIONS = /<!\[CDATA\[[\s\S]*?\]\]>|<!--[\s\S]*?-->/g;
48
+ const DISALLOWED_ENTITY = /&(?!amp;|lt;|gt;|apos;|quot;|#\d+;|#x[\da-f]+;)/i;
49
+ const NUMERIC_ENTITY = /&#(x[\da-f]+|\d+);/gi;
50
+ const TAG = /<\/?[A-Za-z_][\w.:-]*(?:\s+(?:[^<>"']|"[^"]*"|'[^']*')*)?\s*\/?>/g;
51
+ function isXmlCodePoint(cp) {
52
+ return (cp === 9 ||
53
+ cp === 10 ||
54
+ cp === 13 ||
55
+ (cp >= 32 && cp <= 0xd7ff) ||
56
+ (cp >= 0xe000 && cp <= 0xfffd) ||
57
+ (cp >= 0x10000 && cp <= 0x10ffff));
58
+ }
59
+ function checkSafety(xml, limits) {
60
+ if (Buffer.byteLength(xml, 'utf8') > limits.maxBytes)
61
+ throw new RssParseError('response_too_large');
62
+ if (INVALID_XML_CHARS.test(xml))
63
+ throw new RssParseError('invalid_xml_character');
64
+ // Reject declarations before invoking any XML engine, including internal/external entities.
65
+ if (DECLARATION.test(xml))
66
+ throw new RssParseError('forbidden_xml_declaration');
67
+ // CDATA and comments are opaque to entity processing. Only XML's five named entities are allowed.
68
+ const structural = xml.replace(OPAQUE_SECTIONS, '');
69
+ if (DISALLOWED_ENTITY.test(structural))
70
+ throw new RssParseError('invalid_xml_entity');
71
+ for (const match of structural.matchAll(NUMERIC_ENTITY)) {
72
+ const literal = match[1];
73
+ const cp = /^x/i.test(literal) ? parseInt(literal.slice(1), 16) : Number(literal);
74
+ if (!isXmlCodePoint(cp))
75
+ throw new RssParseError('invalid_xml_character');
76
+ }
77
+ let depth = 0;
78
+ for (const match of structural.matchAll(TAG)) {
79
+ const tag = match[0];
80
+ if (tag.startsWith('</'))
81
+ depth--;
82
+ else if (!tag.endsWith('/>'))
83
+ depth++;
84
+ if (depth > limits.maxDepth)
85
+ throw new RssParseError('xml_too_deep');
86
+ }
87
+ }
88
+ export function parseRss(xml, limits = {}) {
89
+ const resolved = resolveLimits(limits);
90
+ if (typeof xml !== 'string')
91
+ throw new TypeError('XML must be a string');
92
+ checkSafety(xml, resolved);
93
+ if (XMLValidator.validate(xml) !== true)
94
+ throw new RssParseError('malformed_xml');
95
+ const parser = new XMLParser({
96
+ ignoreAttributes: false,
97
+ parseTagValue: false,
98
+ parseAttributeValue: false,
99
+ trimValues: false,
100
+ processEntities: true,
101
+ });
102
+ let document;
103
+ try {
104
+ document = object(parser.parse(xml));
105
+ }
106
+ catch {
107
+ throw new RssParseError('malformed_xml');
108
+ }
109
+ if (Object.keys(document).some((k) => k !== 'rss' && k !== '?xml'))
110
+ throw new RssParseError('invalid_rss_structure');
111
+ const rss = object(document.rss);
112
+ if (rss['@_version'] !== '2.0')
113
+ throw new RssParseError('unsupported_rss_version');
114
+ const channel = object(rss.channel);
115
+ const raw = channel.item === undefined ? [] : Array.isArray(channel.item) ? channel.item : [channel.item];
116
+ if (raw.length > resolved.maxItems)
117
+ throw new RssParseError('too_many_items');
118
+ return {
119
+ title: text(channel.title),
120
+ items: raw.map((value) => {
121
+ const item = object(value);
122
+ return {
123
+ title: text(item.title),
124
+ descriptionHtml: text(item.description),
125
+ guid: text(item.guid).trim(),
126
+ link: text(item.link).trim(),
127
+ pubDate: text(item.pubDate).trim(),
128
+ };
129
+ }),
130
+ };
131
+ }
@@ -0,0 +1,31 @@
1
+ import type { DowntimeInput, HttpClient, PollSource } from '@depwatch/core';
2
+ import type { ParseLimits, RssFeed, RssItem } from './parse-rss.js';
3
+ export interface RssSourceOptions {
4
+ id: string;
5
+ vendor: string;
6
+ url: string;
7
+ httpClient: HttpClient;
8
+ /** Default 5 min. */
9
+ pollIntervalMs?: number;
10
+ /** Default 3 × pollIntervalMs. */
11
+ staleAfterMs?: number;
12
+ requestTimeoutMs?: number;
13
+ limits?: ParseLimits;
14
+ /** One feed item → zero, one or several downtime inputs. Return null to ignore an item (e.g. not a downtime). */
15
+ mapItem?(item: RssItem, context: {
16
+ now: Date;
17
+ feed: RssFeed;
18
+ }): DowntimeInput | DowntimeInput[] | null;
19
+ /**
20
+ * Combines `mapItem` inputs that share an externalId (e.g. several updates of one incident).
21
+ * Default: keep the first one in feed order (RSS feeds list newest first).
22
+ */
23
+ merge?(inputs: DowntimeInput[], context: {
24
+ now: Date;
25
+ }): DowntimeInput;
26
+ /** The whole feed → downtime inputs with unique externalIds. */
27
+ mapFeed?(feed: RssFeed, context: {
28
+ now: Date;
29
+ }): DowntimeInput[];
30
+ }
31
+ export declare function createRssSource(options: RssSourceOptions): PollSource;
@@ -0,0 +1,77 @@
1
+ /**
2
+ * An RSS feed as a depwatch PollSource: fetchRss + a vendor mapper. Vendor wording rules live in the mapper (host code).
3
+ *
4
+ * Give exactly one of:
5
+ * - `mapItem` (+ optional `merge`): one item at a time; inputs sharing an externalId are merged.
6
+ * - `mapFeed`: the whole parsed feed at once, for vendors whose updates must be combined with full context.
7
+ */
8
+ import { httpUrl, positiveInt } from '@depwatch/core';
9
+ import { fetchRss } from './fetch-rss.js';
10
+ function viaMapItem(options, feed, now) {
11
+ const merge = options.merge ?? ((inputs) => inputs[0]);
12
+ const groups = new Map();
13
+ for (const item of feed.items) {
14
+ const mapped = options.mapItem(item, { now, feed });
15
+ for (const input of mapped === null ? [] : Array.isArray(mapped) ? mapped : [mapped]) {
16
+ const group = groups.get(input.externalId);
17
+ if (group)
18
+ group.push(input);
19
+ else
20
+ groups.set(input.externalId, [input]);
21
+ }
22
+ }
23
+ return [...groups.values()].map((group) => (group.length === 1 ? group[0] : merge(group, { now })));
24
+ }
25
+ export function createRssSource(options) {
26
+ const url = httpUrl(options.url);
27
+ if (!options.httpClient || typeof options.httpClient.request !== 'function') {
28
+ throw new TypeError('httpClient is required');
29
+ }
30
+ const hasItem = typeof options.mapItem === 'function';
31
+ const hasFeed = typeof options.mapFeed === 'function';
32
+ if (hasItem === hasFeed)
33
+ throw new TypeError('Provide exactly one of mapItem or mapFeed');
34
+ if (hasFeed && options.merge)
35
+ throw new TypeError('merge only applies to mapItem');
36
+ const pollIntervalMs = positiveInt(options.pollIntervalMs ?? 300_000, 'pollIntervalMs');
37
+ const staleAfterMs = positiveInt(options.staleAfterMs ?? pollIntervalMs * 3, 'staleAfterMs');
38
+ return {
39
+ id: options.id,
40
+ vendor: options.vendor,
41
+ type: 'rss',
42
+ pollIntervalMs,
43
+ staleAfterMs,
44
+ async poll({ now, signal, validators }) {
45
+ const fetched = await fetchRss({
46
+ url,
47
+ httpClient: options.httpClient,
48
+ now,
49
+ signal,
50
+ validators,
51
+ ...(options.requestTimeoutMs !== undefined ? { requestTimeoutMs: options.requestTimeoutMs } : {}),
52
+ ...(options.limits !== undefined ? { limits: options.limits } : {}),
53
+ });
54
+ if (fetched.outcome === 'not_modified')
55
+ return { outcome: 'not_modified', validators: fetched.validators };
56
+ if (fetched.outcome === 'error') {
57
+ const { kind, status, retryAfterMs } = fetched.error;
58
+ return {
59
+ outcome: 'error',
60
+ error: {
61
+ kind,
62
+ ...(status !== undefined ? { status } : {}),
63
+ ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
64
+ },
65
+ };
66
+ }
67
+ try {
68
+ const items = hasFeed ? options.mapFeed(fetched.feed, { now }) : viaMapItem(options, fetched.feed, now);
69
+ return { outcome: 'ok', items, validators: fetched.validators };
70
+ }
71
+ catch {
72
+ // A mapper bug must not partially apply a complete batch.
73
+ return { outcome: 'error', error: { kind: 'parse' } };
74
+ }
75
+ },
76
+ };
77
+ }
@@ -0,0 +1,20 @@
1
+ /** One HTML decoding pass after XML decoding; never decodes recursively, drops scripts/styles/images and link targets. */
2
+ export declare function htmlToPlainText(html: string, maxBytes?: number): string;
3
+ /** RFC 2822 date with an explicit offset (or GMT/UT), including weekday validation. No local-zone fallback. */
4
+ export declare function parsePublicationDate(value: string): Date | null;
5
+ export interface LocalDateTime {
6
+ year: number;
7
+ month: number;
8
+ day: number;
9
+ hour: number;
10
+ minute: number;
11
+ }
12
+ export type DateTimeResult = {
13
+ ok: true;
14
+ value: Date;
15
+ } | {
16
+ ok: false;
17
+ issue: 'invalid_local_time' | 'nonexistent_local_time' | 'ambiguous_local_time';
18
+ };
19
+ /** Converts a wall-clock time in `zone` to a Date, rejecting DST gaps and folds instead of guessing. */
20
+ export declare function parseZonedDateTime(parts: LocalDateTime, zone: string): DateTimeResult;
@@ -0,0 +1,53 @@
1
+ /** Text and date helpers for vendor notices. Ported from depwatch 0.0.7 `source-rss/src/parsing.ts` (behaviour unchanged). */
2
+ import { convert } from 'html-to-text';
3
+ import { DateTime } from 'luxon';
4
+ import { positiveInt } from '@depwatch/core';
5
+ import { RssParseError } from './parse-rss.js';
6
+ /** One HTML decoding pass after XML decoding; never decodes recursively, drops scripts/styles/images and link targets. */
7
+ export function htmlToPlainText(html, maxBytes = 1_000_000) {
8
+ positiveInt(maxBytes, 'maxBytes');
9
+ if (Buffer.byteLength(html, 'utf8') > maxBytes)
10
+ throw new RssParseError('html_too_large');
11
+ return convert(html, {
12
+ wordwrap: false,
13
+ limits: { maxInputLength: maxBytes, maxDepth: 64 },
14
+ selectors: [
15
+ { selector: 'a', options: { ignoreHref: true } },
16
+ { selector: 'img', format: 'skip' },
17
+ { selector: 'script', format: 'skip' },
18
+ { selector: 'style', format: 'skip' },
19
+ ],
20
+ })
21
+ .replace(/\s+/g, ' ')
22
+ .trim();
23
+ }
24
+ /** RFC 2822 date with an explicit offset (or GMT/UT), including weekday validation. No local-zone fallback. */
25
+ export function parsePublicationDate(value) {
26
+ if (!/(?:[+-]\d{4}|GMT|UT)$/i.test(value.trim()))
27
+ return null;
28
+ const parsed = DateTime.fromRFC2822(value, { setZone: true });
29
+ return parsed.isValid ? parsed.toJSDate() : null;
30
+ }
31
+ const FIELDS = ['year', 'month', 'day', 'hour', 'minute'];
32
+ /** Converts a wall-clock time in `zone` to a Date, rejecting DST gaps and folds instead of guessing. */
33
+ export function parseZonedDateTime(parts, zone) {
34
+ const valid = !!parts &&
35
+ FIELDS.every((key) => Number.isSafeInteger(parts[key])) &&
36
+ Object.keys(parts).every((key) => FIELDS.includes(key));
37
+ if (!valid)
38
+ return { ok: false, issue: 'invalid_local_time' };
39
+ let parsed;
40
+ try {
41
+ parsed = DateTime.fromObject(parts, { zone });
42
+ }
43
+ catch {
44
+ return { ok: false, issue: 'invalid_local_time' };
45
+ }
46
+ if (!parsed.isValid)
47
+ return { ok: false, issue: 'invalid_local_time' };
48
+ if (FIELDS.some((key) => parsed.get(key) !== parts[key]))
49
+ return { ok: false, issue: 'nonexistent_local_time' };
50
+ if (parsed.getPossibleOffsets().length !== 1)
51
+ return { ok: false, issue: 'ambiguous_local_time' };
52
+ return { ok: true, value: parsed.toJSDate() };
53
+ }