Add the news report model, markers and source

The pure half of a news layer: validated records for a news server's
`/api/news/hotspots|feed|outline` contract, a presentation model and canvas
markers and picture cards, and a fetch client.

- Colour carries severity only (0 no physical event, 1 minor, 2 significant,
  3 major), never a side; the category is the icon, the rim is attestation
  (confirmed, a claim, one side's own press), size grows with sources and
  markers fade with age.
- Cards say "Reported by {side} sources" and mark official channels; a
  machine-read English headline is labelled as such.
- `createNewsSource` reads same-origin routes with a 15 s timeout, a 4 MiB cap
  and record-by-record validation; `NEWS_API_PATHS` and `newsQueryAllowed`
  let a host proxy exactly what the client sends. A 503 marked unavailable
  means "not configured": no retries.
- Exported as `./layers/news/source`, with its own package boundary.
This commit is contained in:
Denis Groshev committed 2026-11-06 00:45:22 +01:00
1 parent dd83812a21
commit 2d9d518946
21 files changed
+2653

No files matched your search

+325
View File
@@ -0,0 +1,325 @@
// Validate /api/news payloads before they reach the scene or the DOM. Every
// string is bounded, every URL is http(s), every position is finite; a record
// that fails is dropped, a payload that fails is rejected whole. A portable
// export (layers/news/source): no i18n here.
const CATEGORY = /^[a-z][a-z-]{1,31}$/;
const CODE = /^[A-Za-z][A-Za-z0-9-]{0,31}$/;
const ID = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
const EVENT_STATUSES = Object.freeze([
'both-sides',
'independent',
'claimed',
'reported',
'side',
'single',
]);
const text = (value, max) =>
typeof value === 'string' && value.trim()
? value.replace(/\s+/g, ' ').trim().slice(0, max)
: null;
const finite = (value, min, max) =>
Number.isFinite(value) && value >= min && value <= max ? value : null;
const iso = (value) => {
const ms = Date.parse(value);
return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
};
const code = (value) =>
typeof value === 'string' && CODE.test(value) ? value : null;
const severity = (value) =>
Number.isInteger(value) && value >= 0 && value <= 3 ? value : null;
/** An http(s) URL without credentials, as its normalised href, or null. */
export function httpUrl(value) {
try {
const url = new URL(value);
return ['http:', 'https:'].includes(url.protocol) &&
!url.username &&
!url.password
? url.href
: null;
} catch {
return null;
}
}
function normalizeBbox(bbox) {
if (!Array.isArray(bbox) || bbox.length !== 4) return null;
const [west, south, east, north] = bbox;
if (
finite(west, -180, 180) === null ||
finite(east, -180, 180) === null ||
finite(south, -90, 90) === null ||
finite(north, -90, 90) === null ||
west >= east ||
south >= north
)
return null;
return [west, south, east, north];
}
/** Beacon position: the curated focus point, else the bbox centre. */
function normalizeFocus(focus, [west, south, east, north]) {
const lat = finite(focus?.lat, south, north);
const lon = finite(focus?.lon, west, east);
return lat !== null && lon !== null
? { lat, lon }
: { lat: (south + north) / 2, lon: (west + east) / 2 };
}
function normalizeDeveloping(items) {
const out = [];
for (const raw of Array.isArray(items) ? items.slice(0, 16) : []) {
const lat = finite(raw?.focus?.lat, -90, 90);
const lon = finite(raw?.focus?.lon, -180, 180);
const country =
typeof raw?.country === 'string' && /^[A-Z]{2}$/.test(raw.country)
? raw.country
: null;
if (lat === null || lon === null || !country) continue;
// A state where the catch-all flags states ("US-FL"), else the country.
const area =
typeof raw.area === 'string' && /^[A-Z]{2}-[A-Z0-9]{1,3}$/.test(raw.area)
? raw.area
: null;
out.push({
country,
key: area || country,
name: text(raw.name, 80) || country,
events: Math.max(0, Math.floor(Number(raw.events) || 0)),
reports: Math.max(0, Math.floor(Number(raw.reports) || 0)),
focus: { lat, lon },
});
}
return out;
}
/**
* `/api/news/hotspots` → `{hotspots, categories, lastRunAt}`, or null when the
* payload has no hotspot list.
*/
export function normalizeHotspotsPayload(payload) {
if (!Array.isArray(payload?.hotspots)) return null;
const hotspots = [];
for (const raw of payload.hotspots.slice(0, 64)) {
const id = typeof raw?.id === 'string' && ID.test(raw.id) ? raw.id : null;
const name = text(raw?.name, 80);
const bbox = normalizeBbox(raw?.bbox);
if (!id || !name || !bbox) continue;
const counts = raw.counts || {};
hotspots.push({
id,
name,
kind: text(raw.kind, 16) || 'conflict',
catchAll: raw.catchAll === true,
developing: normalizeDeveloping(raw.developing),
bbox,
parties: Array.isArray(raw.parties)
? raw.parties.filter((p) => code(p))
: [],
last24h: Math.max(0, Math.floor(Number(counts.last24h) || 0)),
mapped24h: Math.max(0, Math.floor(Number(counts.mapped24h) || 0)),
prev24h: Number.isFinite(counts.prev24h)
? Math.max(0, Math.floor(counts.prev24h))
: null,
focus: normalizeFocus(raw.focus, bbox),
latestAt: iso(raw.latestAt),
});
}
return {
hotspots,
categories: Array.isArray(payload.categories)
? payload.categories.filter(
(c) => typeof c === 'string' && CATEGORY.test(c),
)
: [],
lastRunAt: iso(payload.ingest?.lastRunAt),
};
}
function normalizeGeo(geo) {
if (!geo || typeof geo !== 'object') return null;
const lat = finite(geo.lat, -90, 90);
const lon = finite(geo.lon, -180, 180);
if (lat === null || lon === null) return null;
return {
lat,
lon,
place: text(geo.place, 80),
precision: text(geo.precision, 16) || 'city',
confidence: finite(geo.confidence, 0, 1) ?? 0,
mappable: geo.mappable === true,
byModel: geo.method === 'llm',
};
}
/** The event's picture: an HTTPS URL on the publisher's site, and whose it is. */
function eventImage(image) {
const url = httpUrl(image?.url);
if (!url?.startsWith('https://')) return null;
return { url, publisher: text(image.publisher, 80) || '' };
}
/** An event summary from `/feed?events=1`: size and one report per side. */
function normalizeEvent(event) {
if (!event || typeof event !== 'object') return null;
const count = (value) => Math.max(1, Math.floor(Number(value) || 1));
const sides = [];
for (const side of Array.isArray(event.sides)
? event.sides.slice(0, 8)
: []) {
const url = httpUrl(side?.url);
const title = text(side?.title, 300);
if (!url || !title) continue;
sides.push({
side: code(side.side) || 'unknown',
title,
url,
publisher: text(side.publisher, 80) || '',
publishedAt: iso(side.publishedAt),
});
}
return {
id: typeof event.id === 'string' && ID.test(event.id) ? event.id : null,
status: EVENT_STATUSES.includes(event.status) ? event.status : null,
claimedBy: text(event.claimedBy, 80),
reportedSide: code(event.reportedSide),
size: count(event.size),
reports: count(event.reports),
severity: severity(event.severity),
firstAt: iso(event.firstAt),
lastAt: iso(event.lastAt),
sides,
image: eventImage(event.image),
};
}
function normalizeReport(raw) {
const id = typeof raw?.id === 'string' && ID.test(raw.id) ? raw.id : null;
const title = text(raw?.title, 300);
const url = httpUrl(raw?.url);
const publishedAt = iso(raw?.publishedAt);
if (!id || !title || !url || !publishedAt) return null;
const source = raw.source || {};
const geo = normalizeGeo(raw.geo);
// Map positions: the report's own place plus any other hotspot its title
// names (a roundup is pinned in each).
const pins = [];
for (const place of [
geo,
...(Array.isArray(raw.locations)
? raw.locations.slice(0, 8).map(normalizeGeo)
: []),
])
if (
place?.mappable &&
!pins.some((p) => p.lat === place.lat && p.lon === place.lon)
)
pins.push(place);
const hotspotId = typeof raw.hotspotId === 'string' ? raw.hotspotId : null;
return {
id,
hotspotId,
hotspotIds: Array.isArray(raw.hotspotIds)
? raw.hotspotIds.filter((h) => typeof h === 'string').slice(0, 8)
: [hotspotId].filter(Boolean),
title,
url,
snippet: text(raw.snippet, 400),
publisher: text(raw.publisher, 80) || text(source.name, 80) || '',
sourceName: text(source.name, 80) || text(raw.publisher, 80) || '',
kind: text(raw.kind, 16) || 'rss',
side: code(raw.side) || 'unknown',
affiliation: text(raw.affiliation, 32),
attribution: text(source.attribution, 120),
category:
typeof raw.category === 'string' && CATEGORY.test(raw.category)
? raw.category
: 'other',
publishedAt,
geo,
pins,
event: normalizeEvent(raw.event),
titleEn: text(raw.titleEn, 200),
relevance: ['core', 'related', 'minor'].includes(raw.relevance)
? raw.relevance
: 'related',
severity: severity(raw.severity),
severityBy: raw.severityBy === 'model' ? 'model' : 'rules',
claim:
raw.claim && typeof raw.claim === 'object'
? { by: text(raw.claim.by, 80) }
: null,
media: Array.isArray(raw.media)
? [...new Set(raw.media.filter((m) => m === 'video' || m === 'photo'))]
: [],
};
}
function normalizeRing(ring) {
if (!Array.isArray(ring) || ring.length < 3) return null;
const points = [];
for (const point of ring.slice(0, 20_000)) {
const lon = finite(point?.[0], -180, 180);
const lat = finite(point?.[1], -90, 90);
if (lon !== null && lat !== null) points.push([lon, lat]);
}
return points.length >= 3 ? points : null;
}
/**
* `/api/news/outline` → `{polygons, borders, disputed}`: the dissolved extent
* (`{outer, holes}`), the national borders inside it (rings) and its disputed
* areas, invalid parts dropped.
*/
export function normalizeOutlinePayload(payload) {
const polygons = [];
for (const raw of Array.isArray(payload?.polygons)
? payload.polygons.slice(0, 200)
: []) {
const outer = normalizeRing(raw?.outer);
if (!outer) continue;
const holes = (Array.isArray(raw.holes) ? raw.holes.slice(0, 200) : [])
.map(normalizeRing)
.filter(Boolean);
polygons.push({ outer, holes });
}
const borders = (
Array.isArray(payload?.borders) ? payload.borders.slice(0, 50) : []
)
.map(normalizeRing)
.filter(Boolean);
const KINDS = ['held', 'self', 'un', 'unclaimed'];
const country = (value) =>
typeof value === 'string' && /^[A-Z]{2}$/.test(value) ? value : null;
const disputed = [];
for (const raw of Array.isArray(payload?.disputed)
? payload.disputed.slice(0, 30)
: []) {
const rings = (Array.isArray(raw?.rings) ? raw.rings.slice(0, 20) : [])
.map(normalizeRing)
.filter(Boolean);
const name = text(raw?.name, 60);
if (!rings.length || !name) continue;
disputed.push({
name,
kind: KINDS.includes(raw.kind) ? raw.kind : 'held',
heldBy: country(raw.heldBy),
claimedBy: country(raw.claimedBy),
rings,
});
}
return { polygons, borders, disputed };
}
/** `/api/news/feed` → `{reports, nextBefore}`, or null without a report list. */
export function normalizeFeedPayload(payload) {
if (!Array.isArray(payload?.reports)) return null;
const reports = [];
for (const raw of payload.reports.slice(0, 500)) {
const report = normalizeReport(raw);
if (report) reports.push(report);
}
return { reports, nextBefore: iso(payload.nextBefore) };
}