@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.
package/README.md CHANGED
@@ -1,44 +1,31 @@
1
1
  # @depwatch/source-rss
2
2
 
3
- Streaming RSS status polling and safe XML parsing for provider-specific availability adapters.
3
+ Safe, bounded RSS status-feed sources for [`@depwatch/core`](https://www.npmjs.com/package/@depwatch/core).
4
4
 
5
- ## Install
5
+ > Pre-release (`alpha`).
6
6
 
7
7
  ```sh
8
- npm install @depwatch/core@next @depwatch/source-rss@next
8
+ npm install @depwatch/core@alpha @depwatch/source-rss@alpha
9
9
  ```
10
10
 
11
- Requires Node.js 18+. Includes ES modules, CommonJS and TypeScript declarations. This is an early preview.
12
-
13
- ## Parse a feed
14
-
15
11
  ```js
16
- import { parseRss, htmlToPlainText } from '@depwatch/source-rss';
17
-
18
- const feed = parseRss('<rss version="2.0"><channel><title>Status</title><item><title>Maintenance</title><description>Scheduled work</description></item></channel></rss>');
19
- for (const item of feed.items) {
20
- console.log(item.title, htmlToPlainText(item.descriptionHtml));
21
- }
12
+ import { createRssSource } from '@depwatch/source-rss';
13
+
14
+ const source = createRssSource({
15
+ id: 'vendor-rss',
16
+ vendor: 'acme',
17
+ url: 'https://status.acme.example/rss',
18
+ httpClient, // from @depwatch/core: createFetchHttpClient() or createAxiosHttpClient(axios)
19
+ mapFeed: (feed, { now }) => feed.items.map((item) => toDowntimeInput(item)), // your vendor rules
20
+ // or: mapItem(item) + optional merge(inputs) for one-item-at-a-time mapping
21
+ });
22
+ // pass to createMonitor({ sources: [source], ingestor, store })
22
23
  ```
23
24
 
24
- CommonJS: `const { parseRss } = require('@depwatch/source-rss')`.
25
-
26
- ## Build a status adapter
27
-
28
- Generic RSS toolkit and abstract `RssStatusAdapter` class extending core's `StatusSourceAdapter`. Imports and construction perform no I/O. Subclasses implement `normalizeItem()` and `reduceIncident()`; optional `finalizeObservations()` handles provider-specific revision conflicts. Inherited `parse()` validates normalized records against the core schema. Pure parsing helpers remain usable independently.
29
-
30
- `poll(context)` performs one request through the core HttpClient port. Selection is adapter `httpClient`, shared `context.httpClient`, legacy `context.fetch` bridge, then default Fetch. The adapter owns cancellation, a timeout covering headers and streamed body reads, byte limits, HTTP status/Retry-After handling, and ETag/Last-Modified validators. Successful polls return normalized observations and validator state; a conditional 304 returns `not_modified`. Error results contain sanitized messages, and caller cancellation is distinct from timeout. The caller persists checkpoints only after successfully processing evidence. A 304 without a prior successful validator is an error. No retry loop, scheduler or database is created. The host owns proxy/agent/client configuration and lifecycle.
31
-
32
- Import `createAxiosHttpClient` or `createFetchHttpClient` from core. An Axios instance must retain its full response and unbuffered stream. Custom transports return lowercase header records, AsyncIterable byte bodies and an idempotent `cancel()` method. `createRssSourceContext` also accepts `httpClient`, while preserving the old `fetch` property when supplied.
33
-
34
- - `parseRss(xml, limits?)`: RSS 2.0 items with string title/descriptionHtml/guid/link/pubDate. Defaults: 1 MB UTF-8, 1,000 items, XML depth 64. Rejects malformed XML, DTD/entity declarations, undeclared entities, invalid characters, duplicate scalar nodes, and non-RSS documents. Description HTML must be escaped or CDATA.
35
- - `htmlToPlainText(html, maxBytes?)`: one HTML decoding pass, no external resources, script/style/image content removed and whitespace collapsed.
36
- - `parsePublicationDate(text)`: strict RFC2822 with explicit numeric offset, GMT or UT; invalid dates return null.
37
- - `parseZonedDateTime(parts, zone)`: full local date/time required. Returns a Date or an issue for invalid, nonexistent, or ambiguous times. No silent DST normalization.
38
- - `RssParseError`: stable error code with no raw payload in its message.
39
-
40
- Dependencies are confined to this package: fast-xml-parser 5.x, html-to-text 9.x (Node 18 compatible), and Luxon 3.x. Vendor phrases, component names and timezone rules belong to your provider adapter. `createRssSourceContext` remains available for compatibility. Scheduling, persistence and retry policy belong to the host. No vendor-specific adapter or current-state evaluator is bundled. Absence of a matching RSS notice must not be interpreted as operational status.
41
-
42
- Licensed under the [MIT License](LICENSE).
25
+ **Safety:**
26
+ - DOCTYPE/ENTITY declarations are rejected.
27
+ - Byte, depth and item limits are enforced.
28
+ - Requests have a timeout, are conditional (ETag / If-Modified-Since), and don't follow redirects.
29
+ - Errors are reported as safe categories (`timeout`, `network`, `http`, `auth`, `parse`), never as raw messages or URLs.
43
30
 
44
-
31
+ **Also exported:** `fetchRss`, `parseRss`, `htmlToPlainText`, `parsePublicationDate`, and `parseZonedDateTime` (DST-safe; rejects gaps and folds).
@@ -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,162 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.parseRetryAfter = parseRetryAfter;
4
+ exports.fetchRss = fetchRss;
5
+ /**
6
+ * One bounded, conditional RSS request. Ported from depwatch 0.0.7 `RssStatusAdapter.poll()` as a plain function.
7
+ * Scheduling, retries and persistence belong to the caller (the depwatch monitor).
8
+ */
9
+ const core_1 = require("@depwatch/core");
10
+ const parse_rss_js_1 = require("./parse-rss.js");
11
+ const ACCEPTED_TYPES = ['application/rss+xml', 'application/xml', 'text/xml'];
12
+ function safeHeaderValue(value) {
13
+ return typeof value === 'string' && value.length > 0 && value.length <= 1024 && !/[\r\n]/.test(value);
14
+ }
15
+ function requestHeaders(validators) {
16
+ const headers = { Accept: ACCEPTED_TYPES.join(', ') };
17
+ if (safeHeaderValue(validators?.etag))
18
+ headers['If-None-Match'] = validators.etag;
19
+ if (safeHeaderValue(validators?.lastModified))
20
+ headers['If-Modified-Since'] = validators.lastModified;
21
+ return headers;
22
+ }
23
+ function responseValidators(headers) {
24
+ const validators = {};
25
+ if (safeHeaderValue(headers['etag']))
26
+ validators.etag = headers['etag'];
27
+ if (safeHeaderValue(headers['last-modified']))
28
+ validators.lastModified = headers['last-modified'];
29
+ return validators;
30
+ }
31
+ /** Parses Retry-After as delay-seconds or an HTTP-date; returns undefined when absent or unusable. */
32
+ function parseRetryAfter(value, now) {
33
+ if (!value)
34
+ return undefined;
35
+ const ms = /^\d+$/.test(value) ? Number(value) * 1000 : Date.parse(value) - now.getTime();
36
+ return Number.isSafeInteger(ms) && ms >= 0 ? ms : undefined;
37
+ }
38
+ function cancelQuietly(response) {
39
+ if (!response)
40
+ return;
41
+ try {
42
+ void Promise.resolve(response.cancel()).catch(() => { });
43
+ }
44
+ catch {
45
+ // Cleanup must not hide the fetch result.
46
+ }
47
+ }
48
+ async function readBody(response, maxBytes, aborted) {
49
+ if (!response.body)
50
+ throw new parse_rss_js_1.RssParseError('empty_response');
51
+ const chunks = [];
52
+ let bytes = 0;
53
+ const iterator = response.body[Symbol.asyncIterator]();
54
+ while (true) {
55
+ const { done, value } = await iterator.next();
56
+ if (aborted())
57
+ throw new Error('request_aborted');
58
+ if (done)
59
+ break;
60
+ if (!(value instanceof Uint8Array))
61
+ throw new parse_rss_js_1.RssParseError('invalid_body_chunk');
62
+ bytes += value.byteLength;
63
+ if (bytes > maxBytes)
64
+ throw new parse_rss_js_1.RssParseError('response_too_large');
65
+ chunks.push(value);
66
+ }
67
+ try {
68
+ return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks, bytes));
69
+ }
70
+ catch {
71
+ throw new parse_rss_js_1.RssParseError('invalid_utf8');
72
+ }
73
+ }
74
+ /**
75
+ * Fetches and parses an RSS feed with a timeout, byte limit, conditional request and no redirects.
76
+ * Never throws for network/HTTP/parse problems; returns `{ outcome: 'error' }` with a safe category instead.
77
+ * Error messages never include URLs, headers or raw exception text.
78
+ */
79
+ async function fetchRss(options) {
80
+ const url = (0, core_1.httpUrl)(options.url);
81
+ const now = (0, core_1.validDate)(options.now, 'now');
82
+ if (!options.httpClient || typeof options.httpClient.request !== 'function') {
83
+ throw new TypeError('httpClient is required');
84
+ }
85
+ const timeoutMs = (0, core_1.positiveInt)(options.requestTimeoutMs ?? 15_000, 'requestTimeoutMs', core_1.MAX_TIMER_MS);
86
+ const limits = (0, parse_rss_js_1.resolveLimits)(options.limits);
87
+ const headers = requestHeaders(options.validators);
88
+ const sentValidators = 'If-None-Match' in headers || 'If-Modified-Since' in headers;
89
+ const controller = new AbortController();
90
+ let timedOut = false;
91
+ let response;
92
+ let rejectAborted = () => { };
93
+ const aborted = new Promise((_, reject) => {
94
+ rejectAborted = reject;
95
+ });
96
+ aborted.catch(() => { });
97
+ const abort = () => {
98
+ controller.abort();
99
+ cancelQuietly(response);
100
+ rejectAborted(new Error('request_aborted'));
101
+ };
102
+ const timer = setTimeout(() => {
103
+ timedOut = true;
104
+ abort();
105
+ }, timeoutMs);
106
+ options.signal?.addEventListener('abort', abort, { once: true });
107
+ if (options.signal?.aborted)
108
+ abort();
109
+ let stage = 'network';
110
+ const run = async () => {
111
+ if (controller.signal.aborted)
112
+ throw new Error('request_aborted');
113
+ response = await options.httpClient.request({ url, method: 'GET', headers, signal: controller.signal });
114
+ if (controller.signal.aborted)
115
+ throw new Error('request_aborted');
116
+ const validators = responseValidators(response.headers);
117
+ const status = response.status;
118
+ if (status === 304) {
119
+ if (!sentValidators)
120
+ return { outcome: 'error', error: { kind: 'http', status, message: 'unexpected_304' } };
121
+ return { outcome: 'not_modified', validators: { ...options.validators, ...validators } };
122
+ }
123
+ if (status < 200 || status >= 300) {
124
+ const retryAfterMs = parseRetryAfter(response.headers['retry-after'], now);
125
+ const kind = status === 401 || status === 403 ? 'auth' : 'http';
126
+ return {
127
+ outcome: 'error',
128
+ error: { kind, status, message: `http_${status}`, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) },
129
+ };
130
+ }
131
+ stage = 'parse';
132
+ const contentType = response.headers['content-type']?.split(';')[0]?.trim().toLowerCase();
133
+ if (contentType && !ACCEPTED_TYPES.includes(contentType))
134
+ throw new parse_rss_js_1.RssParseError('invalid_content_type');
135
+ const length = response.headers['content-length'];
136
+ if (length && Number(length) > limits.maxBytes)
137
+ throw new parse_rss_js_1.RssParseError('response_too_large');
138
+ stage = 'network';
139
+ const xml = await readBody(response, limits.maxBytes, () => controller.signal.aborted).catch((error) => {
140
+ if (error instanceof parse_rss_js_1.RssParseError)
141
+ stage = 'parse';
142
+ throw error;
143
+ });
144
+ stage = 'parse';
145
+ return { outcome: 'ok', feed: (0, parse_rss_js_1.parseRss)(xml, limits), validators };
146
+ };
147
+ try {
148
+ return await Promise.race([run(), aborted]);
149
+ }
150
+ catch (error) {
151
+ const kind = timedOut ? 'timeout' : options.signal?.aborted ? 'cancelled' : stage;
152
+ return {
153
+ outcome: 'error',
154
+ error: { kind, message: error instanceof parse_rss_js_1.RssParseError ? error.code : `rss_${kind}_failure` },
155
+ };
156
+ }
157
+ finally {
158
+ clearTimeout(timer);
159
+ options.signal?.removeEventListener('abort', abort);
160
+ cancelQuietly(response);
161
+ }
162
+ }
@@ -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/cjs/index.js CHANGED
@@ -1,28 +1,17 @@
1
1
  "use strict";
2
- var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
- if (k2 === undefined) k2 = k;
4
- var desc = Object.getOwnPropertyDescriptor(m, k);
5
- if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
- desc = { enumerable: true, get: function() { return m[k]; } };
7
- }
8
- Object.defineProperty(o, k2, desc);
9
- }) : (function(o, m, k, k2) {
10
- if (k2 === undefined) k2 = k;
11
- o[k2] = m[k];
12
- }));
13
- var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
- for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
- };
16
2
  Object.defineProperty(exports, "__esModule", { value: true });
17
- exports.createRssSourceContext = createRssSourceContext;
18
- const core_1 = require("@depwatch/core");
19
- __exportStar(require("./parsing.js"), exports);
20
- __exportStar(require("./RssStatusAdapter.js"), exports);
21
- /** Compatibility context helper; use adapter options or PollContext.httpClient for polling. */
22
- function createRssSourceContext(options) {
23
- const url = new URL(options.url);
24
- if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
25
- throw new TypeError('RSS URL must be HTTP(S) without embedded credentials');
26
- return Object.freeze({ url: url.href, httpClient: options.httpClient ?? (0, core_1.createFetchHttpClient)(options.fetch), ...(options.fetch ? { fetch: options.fetch } : {}), logger: options.logger.child({ component: 'depwatch.source-rss' }) });
27
- }
28
- //# sourceMappingURL=index.js.map
3
+ exports.createRssSource = exports.parseRetryAfter = exports.fetchRss = exports.parseZonedDateTime = exports.parsePublicationDate = exports.htmlToPlainText = exports.DEFAULT_LIMITS = exports.RssParseError = exports.resolveLimits = exports.parseRss = void 0;
4
+ var parse_rss_js_1 = require("./parse-rss.js");
5
+ Object.defineProperty(exports, "parseRss", { enumerable: true, get: function () { return parse_rss_js_1.parseRss; } });
6
+ Object.defineProperty(exports, "resolveLimits", { enumerable: true, get: function () { return parse_rss_js_1.resolveLimits; } });
7
+ Object.defineProperty(exports, "RssParseError", { enumerable: true, get: function () { return parse_rss_js_1.RssParseError; } });
8
+ Object.defineProperty(exports, "DEFAULT_LIMITS", { enumerable: true, get: function () { return parse_rss_js_1.DEFAULT_LIMITS; } });
9
+ var text_js_1 = require("./text.js");
10
+ Object.defineProperty(exports, "htmlToPlainText", { enumerable: true, get: function () { return text_js_1.htmlToPlainText; } });
11
+ Object.defineProperty(exports, "parsePublicationDate", { enumerable: true, get: function () { return text_js_1.parsePublicationDate; } });
12
+ Object.defineProperty(exports, "parseZonedDateTime", { enumerable: true, get: function () { return text_js_1.parseZonedDateTime; } });
13
+ var fetch_rss_js_1 = require("./fetch-rss.js");
14
+ Object.defineProperty(exports, "fetchRss", { enumerable: true, get: function () { return fetch_rss_js_1.fetchRss; } });
15
+ Object.defineProperty(exports, "parseRetryAfter", { enumerable: true, get: function () { return fetch_rss_js_1.parseRetryAfter; } });
16
+ var rss_source_js_1 = require("./rss-source.js");
17
+ Object.defineProperty(exports, "createRssSource", { enumerable: true, get: function () { return rss_source_js_1.createRssSource; } });
@@ -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,137 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.RssParseError = exports.DEFAULT_LIMITS = void 0;
4
+ exports.resolveLimits = resolveLimits;
5
+ exports.parseRss = parseRss;
6
+ /**
7
+ * Pure, bounded RSS 2.0 parsing. Ported from depwatch 0.0.7 `source-rss/src/parsing.ts` (behaviour unchanged).
8
+ * Descriptions must contain escaped HTML or CDATA.
9
+ */
10
+ const fast_xml_parser_1 = require("fast-xml-parser");
11
+ const core_1 = require("@depwatch/core");
12
+ exports.DEFAULT_LIMITS = Object.freeze({
13
+ maxBytes: 1_000_000,
14
+ maxItems: 1000,
15
+ maxDepth: 64,
16
+ });
17
+ /** A parse failure with a stable, safe `code` (never includes feed content). */
18
+ class RssParseError extends Error {
19
+ code;
20
+ constructor(code) {
21
+ super(code);
22
+ this.code = code;
23
+ this.name = 'RssParseError';
24
+ }
25
+ }
26
+ exports.RssParseError = RssParseError;
27
+ function resolveLimits(limits = {}) {
28
+ return {
29
+ maxBytes: (0, core_1.positiveInt)(limits.maxBytes ?? exports.DEFAULT_LIMITS.maxBytes, 'maxBytes'),
30
+ maxItems: (0, core_1.positiveInt)(limits.maxItems ?? exports.DEFAULT_LIMITS.maxItems, 'maxItems'),
31
+ maxDepth: (0, core_1.positiveInt)(limits.maxDepth ?? exports.DEFAULT_LIMITS.maxDepth, 'maxDepth'),
32
+ };
33
+ }
34
+ function text(value) {
35
+ if (value === undefined || value === '')
36
+ return '';
37
+ if (typeof value === 'string')
38
+ return value;
39
+ if (value && typeof value === 'object' && !Array.isArray(value)) {
40
+ const node = value;
41
+ if (Object.keys(node).every((k) => k === '#text' || k.startsWith('@_')))
42
+ return text(node['#text']);
43
+ }
44
+ throw new RssParseError('invalid_text_node');
45
+ }
46
+ function object(value) {
47
+ if (!value || typeof value !== 'object' || Array.isArray(value))
48
+ throw new RssParseError('invalid_rss_structure');
49
+ return value;
50
+ }
51
+ const INVALID_XML_CHARS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uD800-\uDFFF￾￿]/u;
52
+ const DECLARATION = /<!\s*(?:DOCTYPE|ENTITY)\b/i;
53
+ const OPAQUE_SECTIONS = /<!\[CDATA\[[\s\S]*?\]\]>|<!--[\s\S]*?-->/g;
54
+ const DISALLOWED_ENTITY = /&(?!amp;|lt;|gt;|apos;|quot;|#\d+;|#x[\da-f]+;)/i;
55
+ const NUMERIC_ENTITY = /&#(x[\da-f]+|\d+);/gi;
56
+ const TAG = /<\/?[A-Za-z_][\w.:-]*(?:\s+(?:[^<>"']|"[^"]*"|'[^']*')*)?\s*\/?>/g;
57
+ function isXmlCodePoint(cp) {
58
+ return (cp === 9 ||
59
+ cp === 10 ||
60
+ cp === 13 ||
61
+ (cp >= 32 && cp <= 0xd7ff) ||
62
+ (cp >= 0xe000 && cp <= 0xfffd) ||
63
+ (cp >= 0x10000 && cp <= 0x10ffff));
64
+ }
65
+ function checkSafety(xml, limits) {
66
+ if (Buffer.byteLength(xml, 'utf8') > limits.maxBytes)
67
+ throw new RssParseError('response_too_large');
68
+ if (INVALID_XML_CHARS.test(xml))
69
+ throw new RssParseError('invalid_xml_character');
70
+ // Reject declarations before invoking any XML engine, including internal/external entities.
71
+ if (DECLARATION.test(xml))
72
+ throw new RssParseError('forbidden_xml_declaration');
73
+ // CDATA and comments are opaque to entity processing. Only XML's five named entities are allowed.
74
+ const structural = xml.replace(OPAQUE_SECTIONS, '');
75
+ if (DISALLOWED_ENTITY.test(structural))
76
+ throw new RssParseError('invalid_xml_entity');
77
+ for (const match of structural.matchAll(NUMERIC_ENTITY)) {
78
+ const literal = match[1];
79
+ const cp = /^x/i.test(literal) ? parseInt(literal.slice(1), 16) : Number(literal);
80
+ if (!isXmlCodePoint(cp))
81
+ throw new RssParseError('invalid_xml_character');
82
+ }
83
+ let depth = 0;
84
+ for (const match of structural.matchAll(TAG)) {
85
+ const tag = match[0];
86
+ if (tag.startsWith('</'))
87
+ depth--;
88
+ else if (!tag.endsWith('/>'))
89
+ depth++;
90
+ if (depth > limits.maxDepth)
91
+ throw new RssParseError('xml_too_deep');
92
+ }
93
+ }
94
+ function parseRss(xml, limits = {}) {
95
+ const resolved = resolveLimits(limits);
96
+ if (typeof xml !== 'string')
97
+ throw new TypeError('XML must be a string');
98
+ checkSafety(xml, resolved);
99
+ if (fast_xml_parser_1.XMLValidator.validate(xml) !== true)
100
+ throw new RssParseError('malformed_xml');
101
+ const parser = new fast_xml_parser_1.XMLParser({
102
+ ignoreAttributes: false,
103
+ parseTagValue: false,
104
+ parseAttributeValue: false,
105
+ trimValues: false,
106
+ processEntities: true,
107
+ });
108
+ let document;
109
+ try {
110
+ document = object(parser.parse(xml));
111
+ }
112
+ catch {
113
+ throw new RssParseError('malformed_xml');
114
+ }
115
+ if (Object.keys(document).some((k) => k !== 'rss' && k !== '?xml'))
116
+ throw new RssParseError('invalid_rss_structure');
117
+ const rss = object(document.rss);
118
+ if (rss['@_version'] !== '2.0')
119
+ throw new RssParseError('unsupported_rss_version');
120
+ const channel = object(rss.channel);
121
+ const raw = channel.item === undefined ? [] : Array.isArray(channel.item) ? channel.item : [channel.item];
122
+ if (raw.length > resolved.maxItems)
123
+ throw new RssParseError('too_many_items');
124
+ return {
125
+ title: text(channel.title),
126
+ items: raw.map((value) => {
127
+ const item = object(value);
128
+ return {
129
+ title: text(item.title),
130
+ descriptionHtml: text(item.description),
131
+ guid: text(item.guid).trim(),
132
+ link: text(item.link).trim(),
133
+ pubDate: text(item.pubDate).trim(),
134
+ };
135
+ }),
136
+ };
137
+ }
@@ -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,80 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.createRssSource = createRssSource;
4
+ /**
5
+ * An RSS feed as a depwatch PollSource: fetchRss + a vendor mapper. Vendor wording rules live in the mapper (host code).
6
+ *
7
+ * Give exactly one of:
8
+ * - `mapItem` (+ optional `merge`): one item at a time; inputs sharing an externalId are merged.
9
+ * - `mapFeed`: the whole parsed feed at once, for vendors whose updates must be combined with full context.
10
+ */
11
+ const core_1 = require("@depwatch/core");
12
+ const fetch_rss_js_1 = require("./fetch-rss.js");
13
+ function viaMapItem(options, feed, now) {
14
+ const merge = options.merge ?? ((inputs) => inputs[0]);
15
+ const groups = new Map();
16
+ for (const item of feed.items) {
17
+ const mapped = options.mapItem(item, { now, feed });
18
+ for (const input of mapped === null ? [] : Array.isArray(mapped) ? mapped : [mapped]) {
19
+ const group = groups.get(input.externalId);
20
+ if (group)
21
+ group.push(input);
22
+ else
23
+ groups.set(input.externalId, [input]);
24
+ }
25
+ }
26
+ return [...groups.values()].map((group) => (group.length === 1 ? group[0] : merge(group, { now })));
27
+ }
28
+ function createRssSource(options) {
29
+ const url = (0, core_1.httpUrl)(options.url);
30
+ if (!options.httpClient || typeof options.httpClient.request !== 'function') {
31
+ throw new TypeError('httpClient is required');
32
+ }
33
+ const hasItem = typeof options.mapItem === 'function';
34
+ const hasFeed = typeof options.mapFeed === 'function';
35
+ if (hasItem === hasFeed)
36
+ throw new TypeError('Provide exactly one of mapItem or mapFeed');
37
+ if (hasFeed && options.merge)
38
+ throw new TypeError('merge only applies to mapItem');
39
+ const pollIntervalMs = (0, core_1.positiveInt)(options.pollIntervalMs ?? 300_000, 'pollIntervalMs');
40
+ const staleAfterMs = (0, core_1.positiveInt)(options.staleAfterMs ?? pollIntervalMs * 3, 'staleAfterMs');
41
+ return {
42
+ id: options.id,
43
+ vendor: options.vendor,
44
+ type: 'rss',
45
+ pollIntervalMs,
46
+ staleAfterMs,
47
+ async poll({ now, signal, validators }) {
48
+ const fetched = await (0, fetch_rss_js_1.fetchRss)({
49
+ url,
50
+ httpClient: options.httpClient,
51
+ now,
52
+ signal,
53
+ validators,
54
+ ...(options.requestTimeoutMs !== undefined ? { requestTimeoutMs: options.requestTimeoutMs } : {}),
55
+ ...(options.limits !== undefined ? { limits: options.limits } : {}),
56
+ });
57
+ if (fetched.outcome === 'not_modified')
58
+ return { outcome: 'not_modified', validators: fetched.validators };
59
+ if (fetched.outcome === 'error') {
60
+ const { kind, status, retryAfterMs } = fetched.error;
61
+ return {
62
+ outcome: 'error',
63
+ error: {
64
+ kind,
65
+ ...(status !== undefined ? { status } : {}),
66
+ ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
67
+ },
68
+ };
69
+ }
70
+ try {
71
+ const items = hasFeed ? options.mapFeed(fetched.feed, { now }) : viaMapItem(options, fetched.feed, now);
72
+ return { outcome: 'ok', items, validators: fetched.validators };
73
+ }
74
+ catch {
75
+ // A mapper bug must not partially apply a complete batch.
76
+ return { outcome: 'error', error: { kind: 'parse' } };
77
+ }
78
+ },
79
+ };
80
+ }
@@ -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;