@uk-open-data-connectors/uk-sources 0.1.0

package/dist/carbonIntensity.js

@@ -0,0 +1,257 @@
+import { z } from 'zod';
+import { UkSourceApiError, UkSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/**
+ * Half-hourly carbon intensity for Great Britain's electricity grid, from the
+ * National Energy System Operator's Carbon Intensity API. Every call answers
+ * without a key, and the API's own terms place the data under the Creative
+ * Commons Attribution 4.0 licence: <https://carbonintensity.org.uk/>
+ */
+export const CARBON_INTENSITY_SOURCE_ID = 'carbon-intensity';
+/** Root every call here is built from. */
+export const CARBON_INTENSITY_API_BASE_URL = 'https://api.carbonintensity.org.uk';
+/** Half-hourly readings between two instants. */
+export const CARBON_INTENSITY_RANGE_URL = `${CARBON_INTENSITY_API_BASE_URL}/intensity`;
+/**
+ * The API refuses a range longer than 31 days ("The date range you have
+ * specified is greater than 31 days"). The window stays a day inside that.
+ */
+export const CARBON_INTENSITY_MAX_WINDOW_DAYS = 30;
+/** How many complete days the default window covers. */
+export const DEFAULT_CARBON_INTENSITY_WINDOW_DAYS = 30;
+/** How long one reading covers. */
+export const CARBON_INTENSITY_PERIOD_MINUTES = 30;
+/** Milliseconds in a day, for turning a window length into an instant. */
+const MILLISECONDS_PER_DAY = 86_400_000;
+/** Milliseconds in the half hour one reading covers. */
+const MILLISECONDS_PER_PERIOD = CARBON_INTENSITY_PERIOD_MINUTES * 60 * 1000;
+/** Half-hour readings in a whole day. */
+const PERIODS_PER_DAY = (24 * 60) / CARBON_INTENSITY_PERIOD_MINUTES;
+/**
+ * The grades the API puts each half hour in, lowest intensity first. They are
+ * the operator's own words: "The index is a measure of the Carbon Intensity
+ * represented on a scale between 'very low', 'low', 'moderate', 'high', 'very
+ * high'."
+ */
+export const CARBON_INTENSITY_INDEX_BANDS = [
+    'very low',
+    'low',
+    'moderate',
+    'high',
+    'very high',
+];
+const CARBON_INTENSITY_RESPONSE_SCHEMA = z.object({
+    data: z.array(z.object({
+        from: z.string(),
+        to: z.string(),
+        intensity: z.object({
+            forecast: z.number().nullable(),
+            actual: z.number().nullable(),
+            index: z.string(),
+        }),
+    })),
+});
+const CARBON_INTENSITY_INSTANT_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}Z$/;
+/** Milliseconds for an ISO instant, or NaN when the string is not one. */
+function instantMilliseconds(instant) {
+    return CARBON_INTENSITY_INSTANT_PATTERN.test(instant) ? Date.parse(instant) : Number.NaN;
+}
+/**
+ * Writes a Date as the ISO instant the API takes in its path, e.g.
+ * `2026-08-30T00:00Z`.
+ *
+ * @param date - the instant to write
+ * @returns the instant as `YYYY-MM-DDThh:mmZ`
+ */
+export function formatCarbonIntensityInstant(date) {
+    return `${date.toISOString().slice(0, 16)}Z`;
+}
+/**
+ * Works out the window a build reads: whole UTC days, ending at the start of
+ * today, so every reading in it is settled rather than a forecast.
+ *
+ * @param options - how many days, and the clock to measure back from
+ * @returns the window's start and end as ISO instants
+ */
+export function resolveCarbonIntensityWindow(options = {}) {
+    const windowDays = options.windowDays ?? DEFAULT_CARBON_INTENSITY_WINDOW_DAYS;
+    if (!Number.isInteger(windowDays) || windowDays < 1) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `a window of ${String(windowDays)} days is not a whole number of days`);
+    }
+    if (windowDays > CARBON_INTENSITY_MAX_WINDOW_DAYS) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `the API refuses a range longer than ${String(CARBON_INTENSITY_MAX_WINDOW_DAYS)} days`);
+    }
+    const now = options.now ?? new Date();
+    const to = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+    const from = new Date(to.getTime() - windowDays * MILLISECONDS_PER_DAY);
+    return { from: formatCarbonIntensityInstant(from), to: formatCarbonIntensityInstant(to) };
+}
+/**
+ * Checks a window a caller passed in rather than one the adapter worked out.
+ *
+ * The API refuses a range longer than 31 days and answers in half hours, so a
+ * window that is not a whole number of half hours, or that runs past the
+ * limit, throws here rather than at the API.
+ *
+ * @param window - the start and end a caller asked for
+ * @returns the same window, once it has been checked
+ */
+export function validateCarbonIntensityWindow(window) {
+    const { from, to } = window;
+    if (from === undefined || to === undefined) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, 'a window needs both a start and an end');
+    }
+    const fromMilliseconds = instantMilliseconds(from);
+    const toMilliseconds = instantMilliseconds(to);
+    if (Number.isNaN(fromMilliseconds) || Number.isNaN(toMilliseconds)) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `expected instants as YYYY-MM-DDThh:mmZ, got ${from} and ${to}`);
+    }
+    const span = toMilliseconds - fromMilliseconds;
+    if (span <= 0) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `the window ends at ${to}, before it starts at ${from}`);
+    }
+    if (span % MILLISECONDS_PER_PERIOD !== 0) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `the window ${from} to ${to} is not a whole number of half hours`);
+    }
+    if (span > CARBON_INTENSITY_MAX_WINDOW_DAYS * MILLISECONDS_PER_DAY) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `the API refuses a range longer than ${String(CARBON_INTENSITY_MAX_WINDOW_DAYS)} days`);
+    }
+    return { from, to };
+}
+/**
+ * Builds the URL for one window of half-hourly readings.
+ *
+ * @param window - the start and end of the window, as ISO instants
+ * @returns the full range URL
+ */
+export function buildCarbonIntensityWindowUrl(window) {
+    return `${CARBON_INTENSITY_RANGE_URL}/${window.from}/${window.to}`;
+}
+/** Counts the half hours the window holds at each grade, lowest grade first. */
+function countByBand(periods) {
+    return CARBON_INTENSITY_INDEX_BANDS.map((index) => ({
+        index,
+        periodCount: periods.filter((period) => period.index === index).length,
+    }));
+}
+/**
+ * Parses a range response into the readings the page draws.
+ *
+ * Every check here is one the page would otherwise show as a wrong number: a
+ * half hour with no settled reading, a period that does not run for half an
+ * hour, an instant that does not move forwards, or a grade the API's own band
+ * list does not carry all throw rather than quietly changing the counts.
+ *
+ * @param payload - the range response, or the committed fixture of one
+ * @returns every reading in the window, oldest first, with its totals
+ */
+export function parseCarbonIntensityWindow(payload) {
+    const parsed = CARBON_INTENSITY_RESPONSE_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, parsed.error.message);
+    }
+    const responses = parsed.data.data;
+    if (responses.length === 0) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, 'the window returned no readings');
+    }
+    const bands = new Set(CARBON_INTENSITY_INDEX_BANDS);
+    let previousFrom = Number.NEGATIVE_INFINITY;
+    const periods = responses.map((response) => {
+        const from = instantMilliseconds(response.from);
+        const to = instantMilliseconds(response.to);
+        if (Number.isNaN(from) || Number.isNaN(to)) {
+            throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `expected an instant as YYYY-MM-DDThh:mmZ, got ${JSON.stringify(response.from)}`);
+        }
+        if (to - from !== MILLISECONDS_PER_PERIOD) {
+            throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `the half hour starting ${response.from} runs for ${String((to - from) / 60_000)} minutes`);
+        }
+        if (from <= previousFrom) {
+            throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `the readings do not move forwards at ${response.from}`);
+        }
+        previousFrom = from;
+        if (response.intensity.actual === null) {
+            throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `the half hour starting ${response.from} carries no settled reading`);
+        }
+        if (!bands.has(response.intensity.index)) {
+            throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, `unrecognised intensity grade ${JSON.stringify(response.intensity.index)}`);
+        }
+        return {
+            from: response.from,
+            to: response.to,
+            intensity: response.intensity.actual,
+            index: response.intensity.index,
+        };
+    });
+    const total = periods.reduce((sum, period) => sum + period.intensity, 0);
+    const lowestPeriod = periods.reduce((lowest, period) => period.intensity < lowest.intensity ? period : lowest);
+    const highestPeriod = periods.reduce((highest, period) => period.intensity > highest.intensity ? period : highest);
+    const firstPeriod = periods[0];
+    const lastPeriod = periods.at(-1);
+    if (firstPeriod === undefined || lastPeriod === undefined) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, 'the window holds no readings');
+    }
+    return {
+        periodCount: periods.length,
+        dayCount: Math.floor(periods.length / PERIODS_PER_DAY),
+        firstPeriodFrom: firstPeriod.from,
+        lastPeriodTo: lastPeriod.to,
+        averageIntensity: Math.round(total / periods.length),
+        lowestPeriod,
+        highestPeriod,
+        bandCounts: countByBand(periods),
+        periods,
+    };
+}
+/** One window of half-hourly readings, or a throw naming what failed. */
+async function fetchCarbonIntensityPayload(options) {
+    const url = buildCarbonIntensityWindowUrl({ from: options.from, to: options.to });
+    const response = await options.fetchImpl(url, { headers: { accept: 'application/json' } });
+    if (!response.ok) {
+        throw new UkSourceApiError(CARBON_INTENSITY_SOURCE_ID, `HTTP ${response.status} from ${url}`);
+    }
+    return response.json();
+}
+/**
+ * Reads a window of half-hourly carbon intensity.
+ *
+ * The range endpoint also returns the half hour that ends at the window's
+ * start, so the first response is dropped: without that, the window is a half
+ * hour longer than the whole days it claims to cover.
+ *
+ * A caller can also pass the window's own start and end, which is how a page
+ * aligns the window to whole days in its own time zone rather than to UTC.
+ *
+ * @param options - how many days, or an explicit window, and an optional fetch implementation
+ * @returns every reading in the window, oldest first, with its totals
+ */
+export async function fetchCarbonIntensityWindow(options = {}) {
+    const { from, to } = options.from === undefined && options.to === undefined
+        ? resolveCarbonIntensityWindow(options)
+        : validateCarbonIntensityWindow({ from: options.from, to: options.to });
+    const payload = await fetchCarbonIntensityPayload({
+        from,
+        to,
+        fetchImpl: options.fetchImpl ?? globalThis.fetch,
+    });
+    const parsed = CARBON_INTENSITY_RESPONSE_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UkSourceParseError(CARBON_INTENSITY_SOURCE_ID, parsed.error.message);
+    }
+    const windowStart = Date.parse(from);
+    return parseCarbonIntensityWindow({
+        data: parsed.data.data.filter((response) => instantMilliseconds(response.from) >= windowStart),
+    });
+}
+/** National Energy System Operator half-hourly carbon intensity, keyless. */
+export const carbonIntensityAdapter = {
+    id: CARBON_INTENSITY_SOURCE_ID,
+    name: 'National Energy System Operator carbon intensity',
+    auth: 'none',
+    description: 'Half-hourly carbon intensity for Great Britain, with the cleanest and dirtiest half hours in the window.',
+    fetchLive: (options) => fetchCarbonIntensityWindow({
+        ...(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    }),
+    parse: parseCarbonIntensityWindow,
+    loadFixture: () => parseCarbonIntensityWindow(readFixtureJson('carbon-intensity.json')),
+};
+//# sourceMappingURL=carbonIntensity.js.map

package/dist/carbonIntensity.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+/** Base error for any UK data source client in this package. */
+export declare class UkSourceError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The remote API rejected the request (HTTP error or bad payload). */
+export declare class UkSourceApiError extends UkSourceError {
+    readonly source: string;
+    constructor(source: string, message: string, options?: ErrorOptions);
+}
+/** The remote payload did not match the expected shape. */
+export declare class UkSourceParseError extends UkSourceError {
+    readonly source: string;
+    constructor(source: string, message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,uEAAuE;AACvE,qBAAa,gBAAiB,SAAQ,aAAa;aAE/B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAKzB;AAED,2DAA2D;AAC3D,qBAAa,kBAAmB,SAAQ,aAAa;aAEjC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAKzB"}

package/dist/errors.js

@@ -0,0 +1,26 @@
+/** Base error for any UK data source client in this package. */
+export class UkSourceError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'UkSourceError';
+    }
+}
+/** The remote API rejected the request (HTTP error or bad payload). */
+export class UkSourceApiError extends UkSourceError {
+    source;
+    constructor(source, message, options) {
+        super(`${source}: ${message}`, options);
+        this.source = source;
+        this.name = 'UkSourceApiError';
+    }
+}
+/** The remote payload did not match the expected shape. */
+export class UkSourceParseError extends UkSourceError {
+    source;
+    constructor(source, message, options) {
+        super(`${source}: ${message}`, options);
+        this.source = source;
+        this.name = 'UkSourceParseError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,gBAAiB,SAAQ,aAAa;IAE/B;IADlB,YACkB,MAAc,EAC9B,OAAe,EACf,OAAsB;QAEtB,KAAK,CAAC,GAAG,MAAM,KAAK,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;QAJxB,WAAM,GAAN,MAAM,CAAQ;QAK9B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,2DAA2D;AAC3D,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IAEjC;IADlB,YACkB,MAAc,EAC9B,OAAe,EACf,OAAsB;QAEtB,KAAK,CAAC,GAAG,MAAM,KAAK,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;QAJxB,WAAM,GAAN,MAAM,CAAQ;QAK9B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/fixtures.d.ts

@@ -0,0 +1,5 @@
+/** Reads a committed fixture from src/fixtures as parsed JSON. */
+export declare function readFixtureJson(filename: string): unknown;
+/** Reads a committed fixture from src/fixtures as raw text. */
+export declare function readFixtureText(filename: string): string;
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../src/fixtures.ts"],"names":[],"mappings":"AAGA,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/fixtures.js

@@ -0,0 +1,11 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+/** Reads a committed fixture from src/fixtures as parsed JSON. */
+export function readFixtureJson(filename) {
+    return JSON.parse(readFileSync(path.join(process.cwd(), 'src/fixtures', filename), 'utf8'));
+}
+/** Reads a committed fixture from src/fixtures as raw text. */
+export function readFixtureText(filename) {
+    return readFileSync(path.join(process.cwd(), 'src/fixtures', filename), 'utf8');
+}
+//# sourceMappingURL=fixtures.js.map

package/dist/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../src/fixtures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,kEAAkE;AAClE,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AAC9F,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;AAClF,CAAC"}

package/dist/floodMonitoring.d.ts

@@ -0,0 +1,70 @@
+import type { UkDataAdapter } from './types.js';
+/** One measure a station publishes, such as water level at 15 minute steps. */
+export interface FloodMeasure {
+    id: string;
+    parameter: string;
+    parameterName: string;
+    qualifier: string;
+    unitName: string;
+    periodSeconds: number;
+}
+/** One monitoring station in the Environment Agency network. */
+export interface FloodStation {
+    id: string;
+    notation: string;
+    label: string;
+    riverName: string;
+    catchmentName: string;
+    /** Null for the handful of groundwater stations that publish no coordinates. */
+    latitude: number | null;
+    /** Null for the handful of groundwater stations that publish no coordinates. */
+    longitude: number | null;
+    measures: FloodMeasure[];
+}
+/** One reading from a station measure. */
+export interface FloodReading {
+    measureId: string;
+    dateTime: string;
+    value: number;
+}
+/** Rolled-up facts about a run of readings. */
+export interface FloodReadingSummary {
+    count: number;
+    latest: FloodReading | undefined;
+    earliest: FloodReading | undefined;
+    minValue: number | undefined;
+    maxValue: number | undefined;
+    trend: 'rising' | 'falling' | 'steady' | 'unknown';
+}
+/**
+ * Station the readings adapter probes by default: Bourton Dickler on the
+ * River Dikler, which publishes level readings every 15 minutes.
+ */
+export declare const DEFAULT_FLOOD_STATION_REFERENCE = "1029TH";
+/** Parses an Environment Agency /id/stations payload into stations. */
+export declare function parseFloodStations(payload: unknown): FloodStation[];
+/** Parses an Environment Agency /readings payload into readings. */
+export declare function parseFloodReadings(payload: unknown): FloodReading[];
+/** Summarizes a run of readings: count, ends, range, and direction. */
+export declare function summarizeFloodReadings(readings: FloodReading[]): FloodReadingSummary;
+/**
+ * Lists monitoring stations from the Environment Agency flood-monitoring
+ * API. Keyless, Open Government Licence v3.
+ */
+export declare function fetchFloodStations(options?: {
+    limit?: number;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<FloodStation[]>;
+/**
+ * Reads the most recent readings for one station. `_sorted` returns the
+ * newest first, so the first item is the current level.
+ */
+export declare function fetchFloodStationReadings(stationReference?: string, options?: {
+    limit?: number;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<FloodReading[]>;
+/** Flood-monitoring station list adapter, keyless. */
+export declare const floodStationsAdapter: UkDataAdapter<FloodStation[]>;
+/** Flood-monitoring readings adapter for the default station, keyless. */
+export declare const floodReadingsAdapter: UkDataAdapter<FloodReading[]>;
+//# sourceMappingURL=floodMonitoring.d.ts.map

package/dist/floodMonitoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"floodMonitoring.d.ts","sourceRoot":"","sources":["../src/floodMonitoring.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gFAAgF;IAChF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC;IACjC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAC;IACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;CACpD;AAED;;;GAGG;AACH,eAAO,MAAM,+BAA+B,WAAW,CAAC;AAoDxD,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,EAAE,CAsBnE;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,EAAE,CAUnE;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,mBAAmB,CA8BpF;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAAO,GACpE,OAAO,CAAC,YAAY,EAAE,CAAC,CASzB;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,gBAAgB,GAAE,MAAwC,EAC1D,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAAO,GACpE,OAAO,CAAC,YAAY,EAAE,CAAC,CAUzB;AAED,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,YAAY,EAAE,CAS9D,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,YAAY,EAAE,CAY9D,CAAC"}

package/dist/floodMonitoring.js

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+import { UkSourceApiError, UkSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/**
+ * Station the readings adapter probes by default: Bourton Dickler on the
+ * River Dikler, which publishes level readings every 15 minutes.
+ */
+export const DEFAULT_FLOOD_STATION_REFERENCE = '1029TH';
+/** How close two readings must be to count as steady, in metres. */
+const STEADY_LEVEL_TOLERANCE_METRES = 0.01;
+const FLOOD_MEASURE_SCHEMA = z.object({
+    '@id': z.string(),
+    parameter: z.string(),
+    parameterName: z.string(),
+    qualifier: z.string(),
+    unitName: z.string(),
+    period: z.number().optional(),
+});
+// The agency returns a bare string for most fields but wraps a few in an
+// array, so both shapes have to be accepted.
+const FLOOD_TEXT_SCHEMA = z.union([z.string(), z.array(z.string())]);
+const FLOOD_STATION_SCHEMA = z.object({
+    '@id': z.string(),
+    notation: z.string(),
+    label: FLOOD_TEXT_SCHEMA,
+    riverName: FLOOD_TEXT_SCHEMA.optional(),
+    catchmentName: FLOOD_TEXT_SCHEMA.optional(),
+    lat: z.number().optional(),
+    long: z.number().optional(),
+    measures: z.array(FLOOD_MEASURE_SCHEMA).optional(),
+});
+/** Flattens a field that the agency publishes as a string or an array. */
+function readFloodText(value) {
+    if (value === undefined) {
+        return '';
+    }
+    return Array.isArray(value) ? value.join(' / ') : value;
+}
+const FLOOD_STATIONS_RESPONSE_SCHEMA = z.object({
+    items: z.array(FLOOD_STATION_SCHEMA),
+});
+const FLOOD_READING_SCHEMA = z.object({
+    '@id': z.string(),
+    dateTime: z.string(),
+    measure: z.string(),
+    value: z.number(),
+});
+const FLOOD_READINGS_RESPONSE_SCHEMA = z.object({
+    items: z.array(FLOOD_READING_SCHEMA),
+});
+/** Parses an Environment Agency /id/stations payload into stations. */
+export function parseFloodStations(payload) {
+    const parsed = FLOOD_STATIONS_RESPONSE_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UkSourceParseError('flood-monitoring', parsed.error.message);
+    }
+    return parsed.data.items.map((station) => ({
+        id: station['@id'],
+        notation: station.notation,
+        label: readFloodText(station.label),
+        riverName: readFloodText(station.riverName),
+        catchmentName: readFloodText(station.catchmentName),
+        latitude: station.lat ?? null,
+        longitude: station.long ?? null,
+        measures: (station.measures ?? []).map((measure) => ({
+            id: measure['@id'],
+            parameter: measure.parameter,
+            parameterName: measure.parameterName,
+            qualifier: measure.qualifier,
+            unitName: measure.unitName,
+            periodSeconds: measure.period ?? 0,
+        })),
+    }));
+}
+/** Parses an Environment Agency /readings payload into readings. */
+export function parseFloodReadings(payload) {
+    const parsed = FLOOD_READINGS_RESPONSE_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UkSourceParseError('flood-monitoring', parsed.error.message);
+    }
+    return parsed.data.items.map((reading) => ({
+        measureId: reading.measure,
+        dateTime: reading.dateTime,
+        value: reading.value,
+    }));
+}
+/** Summarizes a run of readings: count, ends, range, and direction. */
+export function summarizeFloodReadings(readings) {
+    if (readings.length === 0) {
+        return {
+            count: 0,
+            latest: undefined,
+            earliest: undefined,
+            minValue: undefined,
+            maxValue: undefined,
+            trend: 'unknown',
+        };
+    }
+    const ordered = [...readings].sort((left, right) => left.dateTime.localeCompare(right.dateTime));
+    const first = ordered[0];
+    const last = ordered[ordered.length - 1];
+    const values = ordered.map((reading) => reading.value);
+    const movement = last !== undefined && first !== undefined ? last.value - first.value : 0;
+    const trend = Math.abs(movement) <= STEADY_LEVEL_TOLERANCE_METRES
+        ? 'steady'
+        : movement > 0
+            ? 'rising'
+            : 'falling';
+    return {
+        count: ordered.length,
+        latest: last,
+        earliest: first,
+        minValue: Math.min(...values),
+        maxValue: Math.max(...values),
+        trend,
+    };
+}
+/**
+ * Lists monitoring stations from the Environment Agency flood-monitoring
+ * API. Keyless, Open Government Licence v3.
+ */
+export async function fetchFloodStations(options = {}) {
+    const { limit = 25, fetchImpl = globalThis.fetch } = options;
+    const response = await fetchImpl(`https://environment.data.gov.uk/flood-monitoring/id/stations?_limit=${limit}`);
+    if (!response.ok) {
+        throw new UkSourceApiError('flood-monitoring', `HTTP ${response.status} listing stations`);
+    }
+    return parseFloodStations(await response.json());
+}
+/**
+ * Reads the most recent readings for one station. `_sorted` returns the
+ * newest first, so the first item is the current level.
+ */
+export async function fetchFloodStationReadings(stationReference = DEFAULT_FLOOD_STATION_REFERENCE, options = {}) {
+    const { limit = 96, fetchImpl = globalThis.fetch } = options;
+    const url = `https://environment.data.gov.uk/flood-monitoring/id/stations/${stationReference}` +
+        `/readings?_limit=${limit}&_sorted`;
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new UkSourceApiError('flood-monitoring', `HTTP ${response.status} reading station`);
+    }
+    return parseFloodReadings(await response.json());
+}
+/** Flood-monitoring station list adapter, keyless. */
+export const floodStationsAdapter = {
+    id: 'flood-stations',
+    name: 'Environment Agency flood-monitoring stations',
+    auth: 'none',
+    description: 'Monitoring stations with their river, catchment, and published measures.',
+    fetchLive: (options) => fetchFloodStations(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: parseFloodStations,
+    loadFixture: () => parseFloodStations(readFixtureJson('flood-stations.json')),
+};
+/** Flood-monitoring readings adapter for the default station, keyless. */
+export const floodReadingsAdapter = {
+    id: 'flood-readings',
+    name: 'Environment Agency flood-monitoring readings',
+    auth: 'none',
+    description: 'Recent water level readings for one station, newest first.',
+    fetchLive: (options) => fetchFloodStationReadings(DEFAULT_FLOOD_STATION_REFERENCE, options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: parseFloodReadings,
+    loadFixture: () => parseFloodReadings(readFixtureJson('flood-station-readings.json')),
+};
+//# sourceMappingURL=floodMonitoring.js.map

package/dist/floodMonitoring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"floodMonitoring.js","sourceRoot":"","sources":["../src/floodMonitoring.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AA4ChD;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,QAAQ,CAAC;AAExD,oEAAoE;AACpE,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAE3C,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAEH,yEAAyE;AACzE,6CAA6C;AAC7C,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;AAErE,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,KAAK,EAAE,iBAAiB;IACxB,SAAS,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACvC,aAAa,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IAC3C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC1B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,QAAQ,EAAE;CACnD,CAAC,CAAC;AAEH,0EAA0E;AAC1E,SAAS,aAAa,CAAC,KAAoC;IACzD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC1D,CAAC;AAED,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC;CACrC,CAAC,CAAC;AAEH,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAC;AAEH,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC;CACrC,CAAC,CAAC;AAEH,uEAAuE;AACvE,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,MAAM,MAAM,GAAG,8BAA8B,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACjE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,kBAAkB,CAAC,kBAAkB,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACzC,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC;QACnC,SAAS,EAAE,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC;QAC3C,aAAa,EAAE,aAAa,CAAC,OAAO,CAAC,aAAa,CAAC;QACnD,QAAQ,EAAE,OAAO,CAAC,GAAG,IAAI,IAAI;QAC7B,SAAS,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI;QAC/B,QAAQ,EAAE,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACnD,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC;YAClB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,aAAa,EAAE,OAAO,CAAC,MAAM,IAAI,CAAC;SACnC,CAAC,CAAC;KACJ,CAAC,CAAC,CAAC;AACN,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,MAAM,MAAM,GAAG,8BAA8B,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACjE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,kBAAkB,CAAC,kBAAkB,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACzC,SAAS,EAAE,OAAO,CAAC,OAAO;QAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC,CAAC,CAAC;AACN,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,sBAAsB,CAAC,QAAwB;IAC7D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,SAAS;YACnB,QAAQ,EAAE,SAAS;YACnB,QAAQ,EAAE,SAAS;YACnB,KAAK,EAAE,SAAS;SACjB,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjG,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1F,MAAM,KAAK,GACT,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,6BAA6B;QACjD,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,QAAQ,GAAG,CAAC;YACZ,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,SAAS,CAAC;IAClB,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,MAAM;QACrB,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;QAC7B,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;QAC7B,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,UAAmE,EAAE;IAErE,MAAM,EAAE,KAAK,GAAG,EAAE,EAAE,SAAS,GAAG,UAAU,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC;IAC7D,MAAM,QAAQ,GAAG,MAAM,SAAS,CAC9B,uEAAuE,KAAK,EAAE,CAC/E,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,EAAE,QAAQ,QAAQ,CAAC,MAAM,mBAAmB,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,kBAAkB,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,mBAA2B,+BAA+B,EAC1D,UAAmE,EAAE;IAErE,MAAM,EAAE,KAAK,GAAG,EAAE,EAAE,SAAS,GAAG,UAAU,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC;IAC7D,MAAM,GAAG,GACP,gEAAgE,gBAAgB,EAAE;QAClF,oBAAoB,KAAK,UAAU,CAAC;IACtC,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,EAAE,QAAQ,QAAQ,CAAC,MAAM,kBAAkB,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,kBAAkB,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAkC;IACjE,EAAE,EAAE,gBAAgB;IACpB,IAAI,EAAE,8CAA8C;IACpD,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,0EAA0E;IACvF,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE,CACrB,kBAAkB,CAAC,OAAO,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;IAC9F,KAAK,EAAE,kBAAkB;IACzB,WAAW,EAAE,GAAG,EAAE,CAAC,kBAAkB,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC;CAC9E,CAAC;AAEF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,oBAAoB,GAAkC;IACjE,EAAE,EAAE,gBAAgB;IACpB,IAAI,EAAE,8CAA8C;IACpD,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,4DAA4D;IACzE,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE,CACrB,yBAAyB,CACvB,+BAA+B,EAC/B,OAAO,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CACzE;IACH,KAAK,EAAE,kBAAkB;IACzB,WAAW,EAAE,GAAG,EAAE,CAAC,kBAAkB,CAAC,eAAe,CAAC,6BAA6B,CAAC,CAAC;CACtF,CAAC"}