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

package/dist/policeCrimes.js

@@ -0,0 +1,262 @@
+import { z } from 'zod';
+import { UkSourceApiError, UkSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/**
+ * Street-level recorded crime from the Home Office's police.uk open data API.
+ * Every police force in England, Wales and Northern Ireland publishes to it,
+ * keyless and monthly, under the Open Government Licence v3:
+ * <https://data.police.uk/docs/>
+ */
+export const POLICE_CRIMES_SOURCE_ID = 'police-crimes';
+/** The API root every call here is built from. */
+export const POLICE_API_BASE_URL = 'https://data.police.uk/api';
+/** Street-level crime within a mile of a point, for one published month. */
+export const POLICE_STREET_CRIMES_URL = `${POLICE_API_BASE_URL}/crimes-street/all-crime`;
+/** The months the API holds, newest first, with the forces behind each. */
+export const POLICE_STREET_DATES_URL = `${POLICE_API_BASE_URL}/crimes-street-dates`;
+/** The crime types the API uses, with the label it gives each one. */
+export const POLICE_CRIME_CATEGORIES_URL = `${POLICE_API_BASE_URL}/crime-categories`;
+/**
+ * The radius the API answers for. Its street-level endpoints take a point and
+ * return everything within one mile of it; there is no way to ask for less.
+ */
+export const POLICE_STREET_CRIMES_RADIUS_MILES = 1;
+/** How many published months the summary covers by default. */
+export const DEFAULT_POLICE_CRIME_MONTH_COUNT = 12;
+/** The point the story counts around, and the name the page gives it. */
+export const DEFAULT_POLICE_CRIME_LOCATION = {
+    label: 'Leeds city centre',
+    latitude: 53.7997,
+    longitude: -1.5492,
+};
+const POLICE_CATEGORY_SCHEMA = z.object({ url: z.string(), name: z.string() });
+const POLICE_RECORD_SCHEMA = z.object({
+    month: z.string(),
+    category: z.string(),
+    // The API writes no outcome at all for offences still without one.
+    outcome_status: z.object({ category: z.string() }).nullable().optional(),
+});
+const POLICE_RESPONSES_SCHEMA = z.object({
+    categories: z.array(POLICE_CATEGORY_SCHEMA),
+    months: z.array(z.object({ month: z.string(), records: z.array(POLICE_RECORD_SCHEMA) })),
+});
+const POLICE_DATES_SCHEMA = z.array(z.object({ date: z.string() }));
+const POLICE_MONTH_PATTERN = /^\d{4}-(0[1-9]|1[0-2])$/;
+/** Counts records per crime type, biggest first, ties broken by label. */
+function countByCategory(records, namesBySlug) {
+    const counts = new Map();
+    for (const record of records) {
+        counts.set(record.category, (counts.get(record.category) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([slug, recordCount]) => ({
+        slug,
+        name: namesBySlug.get(slug) ?? slug,
+        recordCount,
+    }))
+        .sort((left, right) => right.recordCount - left.recordCount || left.name.localeCompare(right.name));
+}
+/** Counts records per outcome, biggest first, ties broken by label. */
+function countByOutcome(records) {
+    const counts = new Map();
+    for (const record of records) {
+        const key = record.outcomeCategory ?? '';
+        const existing = counts.get(key);
+        if (existing === undefined) {
+            counts.set(key, { outcome: record.outcomeCategory, recordCount: 1 });
+        }
+        else {
+            existing.recordCount += 1;
+        }
+    }
+    return [...counts.values()].sort((left, right) => right.recordCount - left.recordCount ||
+        (left.outcome ?? '').localeCompare(right.outcome ?? ''));
+}
+/**
+ * Parses the API responses behind one window into the counts the chart draws.
+ *
+ * The API writes one record per offence, so the counts come from the same read
+ * the page renders. Every check here is one the page would otherwise show as a
+ * wrong number: a month that came back empty, a record filed under a month
+ * other than the one it was asked for, or a crime type the category list does
+ * not carry all throw rather than quietly changing the totals.
+ *
+ * @param payload - the raw responses, or the committed fixture of them
+ * @returns the counts, with months oldest first
+ */
+export function parsePoliceCrimeSummary(payload) {
+    const parsed = POLICE_RESPONSES_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UkSourceParseError(POLICE_CRIMES_SOURCE_ID, parsed.error.message);
+    }
+    const { categories, months } = parsed.data;
+    if (months.length === 0) {
+        throw new UkSourceParseError(POLICE_CRIMES_SOURCE_ID, 'the window covers no months');
+    }
+    const namesBySlug = new Map();
+    for (const category of categories) {
+        if (!namesBySlug.has(category.url)) {
+            namesBySlug.set(category.url, category.name);
+        }
+    }
+    const oldestFirst = [...months].sort((left, right) => left.month.localeCompare(right.month));
+    for (const [index, entry] of oldestFirst.entries()) {
+        if (!POLICE_MONTH_PATTERN.test(entry.month)) {
+            throw new UkSourceParseError(POLICE_CRIMES_SOURCE_ID, `expected a month as YYYY-MM, got ${JSON.stringify(entry.month)}`);
+        }
+        const previous = oldestFirst[index - 1];
+        if (previous?.month === entry.month) {
+            throw new UkSourceParseError(POLICE_CRIMES_SOURCE_ID, `two answers for ${entry.month}`);
+        }
+        if (entry.records.length === 0) {
+            throw new UkSourceParseError(POLICE_CRIMES_SOURCE_ID, `the API returned no records for ${entry.month}`);
+        }
+    }
+    const allRecords = [];
+    const monthCounts = oldestFirst.map((entry) => {
+        const records = entry.records.map((record) => {
+            if (record.month !== entry.month) {
+                throw new UkSourceParseError(POLICE_CRIMES_SOURCE_ID, `a record filed under ${entry.month} carries the month ${record.month}`);
+            }
+            if (!namesBySlug.has(record.category)) {
+                throw new UkSourceParseError(POLICE_CRIMES_SOURCE_ID, `unrecognised crime type ${JSON.stringify(record.category)}`);
+            }
+            return {
+                category: record.category,
+                outcomeCategory: record.outcome_status?.category ?? null,
+            };
+        });
+        allRecords.push(...records);
+        return {
+            month: entry.month,
+            recordCount: records.length,
+            categoryCounts: countByCategory(records, namesBySlug),
+        };
+    });
+    const byMonthSize = [...monthCounts].sort((left, right) => right.recordCount - left.recordCount || left.month.localeCompare(right.month));
+    const categoryCounts = countByCategory(allRecords, namesBySlug);
+    const outcomeCounts = countByOutcome(allRecords);
+    const busiestMonth = byMonthSize[0];
+    const quietestMonth = byMonthSize.at(-1);
+    const topCategory = categoryCounts[0];
+    const topOutcome = outcomeCounts[0];
+    const firstMonth = monthCounts[0];
+    const latestMonth = monthCounts.at(-1);
+    if (busiestMonth === undefined ||
+        quietestMonth === undefined ||
+        topCategory === undefined ||
+        topOutcome === undefined ||
+        firstMonth === undefined ||
+        latestMonth === undefined) {
+        throw new UkSourceParseError(POLICE_CRIMES_SOURCE_ID, 'the window holds no counts');
+    }
+    return {
+        monthCount: monthCounts.length,
+        recordCount: allRecords.length,
+        firstMonth: firstMonth.month,
+        latestMonth: latestMonth.month,
+        categoryCounts,
+        outcomeCounts,
+        months: monthCounts,
+        busiestMonth,
+        quietestMonth,
+        topCategory,
+        topOutcome,
+    };
+}
+/**
+ * Builds the street-level crime URL for one point and one month.
+ *
+ * @param options - where to count, and which month to ask for
+ * @returns the full query URL
+ */
+export function buildPoliceStreetCrimesUrl(options) {
+    const url = new URL(POLICE_STREET_CRIMES_URL);
+    url.searchParams.set('lat', String(options.latitude));
+    url.searchParams.set('lng', String(options.longitude));
+    url.searchParams.set('date', options.month);
+    return url.href;
+}
+/**
+ * Lists the months the API holds street-level crime for, newest first.
+ *
+ * @param options - an optional fetch implementation
+ * @returns the published months as YYYY-MM
+ */
+export async function fetchPoliceCrimeMonths(options = {}) {
+    const { fetchImpl = globalThis.fetch } = options;
+    const response = await fetchImpl(POLICE_STREET_DATES_URL);
+    if (!response.ok) {
+        throw new UkSourceApiError(POLICE_CRIMES_SOURCE_ID, `HTTP ${response.status} listing the published months`);
+    }
+    const parsed = POLICE_DATES_SCHEMA.safeParse(await response.json());
+    if (!parsed.success) {
+        throw new UkSourceParseError(POLICE_CRIMES_SOURCE_ID, parsed.error.message);
+    }
+    const months = parsed.data
+        .map((entry) => entry.date)
+        .filter((month) => POLICE_MONTH_PATTERN.test(month));
+    if (months.length === 0) {
+        throw new UkSourceParseError(POLICE_CRIMES_SOURCE_ID, 'the API listed no published months');
+    }
+    return months;
+}
+/**
+ * Reads the crime types the API uses.
+ *
+ * @param options - an optional fetch implementation
+ * @returns one entry per crime type
+ */
+export async function fetchPoliceCrimeCategories(options = {}) {
+    const { fetchImpl = globalThis.fetch } = options;
+    const response = await fetchImpl(POLICE_CRIME_CATEGORIES_URL);
+    if (!response.ok) {
+        throw new UkSourceApiError(POLICE_CRIMES_SOURCE_ID, `HTTP ${response.status} listing the crime types`);
+    }
+    return response.json();
+}
+/** One month's raw records, or a throw naming the month that failed. */
+async function fetchPoliceStreetCrimeRecords(options) {
+    const url = buildPoliceStreetCrimesUrl(options);
+    const response = await options.fetchImpl(url);
+    if (!response.ok) {
+        throw new UkSourceApiError(POLICE_CRIMES_SOURCE_ID, `HTTP ${response.status} reading ${options.month}`);
+    }
+    return response.json();
+}
+/**
+ * Counts recorded crime within a mile of a point over the latest months.
+ *
+ * The months are read one at a time rather than in one burst, because the API
+ * is free to use and rate-limited per caller. A window of a year is 13 calls.
+ *
+ * @param options - where to count, how many months, and an optional fetch implementation
+ * @returns the counts for the window
+ */
+export async function fetchPoliceCrimeSummary(options = {}) {
+    const { latitude = DEFAULT_POLICE_CRIME_LOCATION.latitude, longitude = DEFAULT_POLICE_CRIME_LOCATION.longitude, monthCount = DEFAULT_POLICE_CRIME_MONTH_COUNT, fetchImpl = globalThis.fetch, } = options;
+    const published = await fetchPoliceCrimeMonths({ fetchImpl });
+    const months = published.slice(0, monthCount);
+    const categories = await fetchPoliceCrimeCategories({ fetchImpl });
+    const responses = [];
+    for (const month of months) {
+        responses.push({
+            month,
+            records: await fetchPoliceStreetCrimeRecords({ latitude, longitude, month, fetchImpl }),
+        });
+    }
+    return parsePoliceCrimeSummary({ categories, months: responses });
+}
+/** Home Office street-level recorded crime, keyless. */
+export const policeCrimesAdapter = {
+    id: POLICE_CRIMES_SOURCE_ID,
+    name: 'Home Office police.uk recorded crime',
+    auth: 'none',
+    description: 'Street-level crime recorded within a mile of a point, counted by crime type and by outcome.',
+    fetchLive: (options) => fetchPoliceCrimeSummary({
+        ...(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    }),
+    parse: parsePoliceCrimeSummary,
+    loadFixture: () => parsePoliceCrimeSummary(readFixtureJson('police-crimes.json')),
+};
+//# sourceMappingURL=policeCrimes.js.map

package/dist/policeCrimes.js.map

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

package/dist/registry.d.ts

@@ -0,0 +1,17 @@
+import type { UkDataAdapter, UkSourceProbe } from './types.js';
+/** Every UK data source behind the uniform adapter interface. */
+export declare const UK_DATA_SOURCES: UkDataAdapter<unknown>[];
+/** Looks up a source adapter by id. */
+export declare function getUkDataSource<T>(id: string): UkDataAdapter<T> | undefined;
+/** Probes one source with a live fetch and reports the outcome. */
+export declare function probeUkDataSource<T>(adapter: UkDataAdapter<T>, options?: {
+    apiKey?: string;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<UkSourceProbe>;
+/** Probes every registered source in parallel, with optional per-source keys. */
+export declare function probeAllUkDataSources(options?: {
+    apiKey?: string;
+    apiKeys?: Record<string, string>;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<UkSourceProbe[]>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAkB,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/E,iEAAiE;AACjE,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,OAAO,CAAC,EAYnD,CAAC;AAEF,uCAAuC;AACvC,wBAAgB,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAE3E;AAED,mEAAmE;AACnE,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAAE,GACjE,OAAO,CAAC,aAAa,CAAC,CAwBxB;AAED,iFAAiF;AACjF,wBAAsB,qBAAqB,CAAC,OAAO,CAAC,EAAE;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAW3B"}

package/dist/registry.js

@@ -0,0 +1,67 @@
+import { ancientWoodlandAdapter } from './ancientWoodland.js';
+import { bankRateAdapter } from './bankRate.js';
+import { carbonIntensityAdapter } from './carbonIntensity.js';
+import { floodReadingsAdapter, floodStationsAdapter } from './floodMonitoring.js';
+import { foodHygieneAuthoritiesAdapter } from './foodHygiene.js';
+import { onsDatasetsAdapter } from './onsDatasets.js';
+import { parliamentSeatsAdapter } from './parliamentSeats.js';
+import { planningDatasetsAdapter } from './planningDatasets.js';
+import { policeCrimesAdapter } from './policeCrimes.js';
+import { tflBikePointsAdapter } from './tflBikePoints.js';
+/** Every UK data source behind the uniform adapter interface. */
+export const UK_DATA_SOURCES = [
+    floodStationsAdapter,
+    floodReadingsAdapter,
+    onsDatasetsAdapter,
+    foodHygieneAuthoritiesAdapter,
+    tflBikePointsAdapter,
+    planningDatasetsAdapter,
+    ancientWoodlandAdapter,
+    bankRateAdapter,
+    policeCrimesAdapter,
+    carbonIntensityAdapter,
+    parliamentSeatsAdapter,
+];
+/** Looks up a source adapter by id. */
+export function getUkDataSource(id) {
+    return UK_DATA_SOURCES.find((source) => source.id === id);
+}
+/** Probes one source with a live fetch and reports the outcome. */
+export async function probeUkDataSource(adapter, options) {
+    try {
+        const fetchOptions = {
+            ...(options?.apiKey === undefined ? {} : { apiKey: options.apiKey }),
+            ...(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+        };
+        const data = await adapter.fetchLive(fetchOptions);
+        return {
+            id: adapter.id,
+            name: adapter.name,
+            auth: adapter.auth,
+            ok: true,
+            status: 'ok',
+            sample: JSON.stringify(data).slice(0, 120),
+        };
+    }
+    catch (error) {
+        return {
+            id: adapter.id,
+            name: adapter.name,
+            auth: adapter.auth,
+            ok: false,
+            status: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** Probes every registered source in parallel, with optional per-source keys. */
+export async function probeAllUkDataSources(options) {
+    const { apiKey, apiKeys, fetchImpl } = options ?? {};
+    return Promise.all(UK_DATA_SOURCES.map((source) => {
+        const key = apiKeys?.[source.id] ?? apiKey;
+        return probeUkDataSource(source, {
+            ...(key === undefined ? {} : { apiKey: key }),
+            ...(fetchImpl === undefined ? {} : { fetchImpl }),
+        });
+    }));
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

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

package/dist/tflBikePoints.d.ts

@@ -0,0 +1,65 @@
+import type { UkDataAdapter } from './types.js';
+/**
+ * Transport for London's Santander Cycles docking station list. Keyless: the
+ * endpoint answers without an app key, and TfL asks for one only above the
+ * free rate limit. Published as TfL Open Data.
+ */
+export declare const TFL_BIKE_POINTS_URL = "https://api.tfl.gov.uk/BikePoint";
+/** How many of the largest docking stations the summary keeps by default. */
+export declare const DEFAULT_LARGEST_STATION_LIMIT = 10;
+/** One Santander Cycles docking station, as TfL lists it. */
+export interface DockingStation {
+    id: string;
+    /** TfL's own station name, with the spacing around commas tidied. */
+    name: string;
+    /** Docking points the station has, empty or full. */
+    dockCount: number;
+    /** Bikes docked at the time of the call. */
+    bikeCount: number;
+    /** Electric bikes among the docked bikes. */
+    electricBikeCount: number;
+    emptyDockCount: number;
+    /** True for TfL's pop-up stations, which come and go with events. */
+    temporary: boolean;
+}
+/** Rolled-up counts across every docking station TfL lists. */
+export interface DockingStationSummary {
+    stationCount: number;
+    /** Docking points summed across every station. */
+    dockCount: number;
+    bikeCount: number;
+    electricBikeCount: number;
+    /** The stations with the most docking points, largest first. */
+    largestStations: DockingStation[];
+}
+/**
+ * Parses a TfL BikePoint payload into docking stations.
+ *
+ * Stations TfL has marked for removal are dropped: they still appear in the
+ * list after they close, and they carry no docking points to count.
+ *
+ * @param payload - the raw JSON body from the BikePoint endpoint
+ * @returns one docking station per live station in the payload
+ */
+export declare function parseTflBikePoints(payload: unknown): DockingStation[];
+/**
+ * Totals the network and keeps the largest stations.
+ *
+ * @param stations - stations from {@link parseTflBikePoints}
+ * @param largestStationLimit - how many stations to keep in `largestStations`
+ * @returns station, dock, and bike counts plus the largest stations
+ */
+export declare function summarizeTflBikePoints(stations: DockingStation[], largestStationLimit?: number): DockingStationSummary;
+/**
+ * Lists every Santander Cycles docking station from TfL.
+ *
+ * @param options - an optional app key and fetch implementation
+ * @returns the docking stations the endpoint returns
+ */
+export declare function fetchTflBikePoints(options?: {
+    apiKey?: string;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<DockingStation[]>;
+/** Transport for London Santander Cycles docking stations, keyless. */
+export declare const tflBikePointsAdapter: UkDataAdapter<DockingStation[]>;
+//# sourceMappingURL=tflBikePoints.d.ts.map

package/dist/tflBikePoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tflBikePoints.d.ts","sourceRoot":"","sources":["../src/tflBikePoints.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,qCAAqC,CAAC;AAEtE,6EAA6E;AAC7E,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,eAAe,EAAE,cAAc,EAAE,CAAC;CACnC;AAwED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,EAAE,CAwBrE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,EAAE,EAC1B,mBAAmB,GAAE,MAAsC,GAC1D,qBAAqB,CAYvB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAAO,GACrE,OAAO,CAAC,cAAc,EAAE,CAAC,CAc3B;AAED,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,cAAc,EAAE,CAYhE,CAAC"}

package/dist/tflBikePoints.js

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+import { UkSourceApiError, UkSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/**
+ * Transport for London's Santander Cycles docking station list. Keyless: the
+ * endpoint answers without an app key, and TfL asks for one only above the
+ * free rate limit. Published as TfL Open Data.
+ */
+export const TFL_BIKE_POINTS_URL = 'https://api.tfl.gov.uk/BikePoint';
+/** How many of the largest docking stations the summary keeps by default. */
+export const DEFAULT_LARGEST_STATION_LIMIT = 10;
+const TFL_PLACE_SCHEMA = z.object({
+    id: z.string(),
+    commonName: z.string(),
+    additionalProperties: z.array(z.object({
+        key: z.string(),
+        value: z.string(),
+    })),
+});
+const TFL_PLACES_SCHEMA = z.array(TFL_PLACE_SCHEMA);
+/** The station fields this adapter reads out of TfL's key/value property list. */
+const DOCK_COUNT_KEY = 'NbDocks';
+const BIKE_COUNT_KEY = 'NbBikes';
+const ELECTRIC_BIKE_COUNT_KEY = 'NbEBikes';
+const EMPTY_DOCK_COUNT_KEY = 'NbEmptyDocks';
+const TEMPORARY_KEY = 'Temporary';
+const REMOVAL_DATE_KEY = 'RemovalDate';
+/**
+ * Indexes TfL's key/value property list for one station.
+ *
+ * @param station - one place from the BikePoint payload
+ * @returns the station's properties by key
+ */
+function readProperties(station) {
+    return new Map(station.additionalProperties.map((property) => [property.key, property.value]));
+}
+/**
+ * Reads one numeric property, naming the station when it is missing.
+ *
+ * @param properties - the station's properties
+ * @param key - the property key to read
+ * @param stationName - the station name, for the error message
+ * @returns the property as a number
+ */
+function readCountProperty(properties, key, stationName) {
+    const raw = properties.get(key);
+    if (raw === undefined || raw.trim() === '') {
+        throw new UkSourceParseError('tfl-bike-points', `no ${key} on ${stationName}`);
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new UkSourceParseError('tfl-bike-points', `${key} "${raw}" on ${stationName} is not a number`);
+    }
+    return value;
+}
+/**
+ * Tidies the spacing TfL leaves around commas in station names, so
+ * "River Street , Clerkenwell" reads as "River Street, Clerkenwell". The words
+ * are TfL's own.
+ *
+ * @param name - the station name as TfL publishes it
+ * @returns the name with collapsed spaces and tidy commas
+ */
+function tidyStationName(name) {
+    return name.replace(/\s+/g, ' ').replace(/\s+,/g, ',').trim();
+}
+/**
+ * Parses a TfL BikePoint payload into docking stations.
+ *
+ * Stations TfL has marked for removal are dropped: they still appear in the
+ * list after they close, and they carry no docking points to count.
+ *
+ * @param payload - the raw JSON body from the BikePoint endpoint
+ * @returns one docking station per live station in the payload
+ */
+export function parseTflBikePoints(payload) {
+    const parsed = TFL_PLACES_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UkSourceParseError('tfl-bike-points', parsed.error.message);
+    }
+    const stations = [];
+    for (const place of parsed.data) {
+        const name = tidyStationName(place.commonName);
+        const properties = readProperties(place);
+        if ((properties.get(REMOVAL_DATE_KEY) ?? '').trim() !== '') {
+            continue;
+        }
+        stations.push({
+            id: place.id,
+            name,
+            dockCount: readCountProperty(properties, DOCK_COUNT_KEY, name),
+            bikeCount: readCountProperty(properties, BIKE_COUNT_KEY, name),
+            electricBikeCount: readCountProperty(properties, ELECTRIC_BIKE_COUNT_KEY, name),
+            emptyDockCount: readCountProperty(properties, EMPTY_DOCK_COUNT_KEY, name),
+            temporary: properties.get(TEMPORARY_KEY) === 'true',
+        });
+    }
+    return stations;
+}
+/**
+ * Totals the network and keeps the largest stations.
+ *
+ * @param stations - stations from {@link parseTflBikePoints}
+ * @param largestStationLimit - how many stations to keep in `largestStations`
+ * @returns station, dock, and bike counts plus the largest stations
+ */
+export function summarizeTflBikePoints(stations, largestStationLimit = DEFAULT_LARGEST_STATION_LIMIT) {
+    const largestStations = [...stations]
+        .sort((left, right) => right.dockCount - left.dockCount || left.name.localeCompare(right.name))
+        .slice(0, largestStationLimit);
+    return {
+        stationCount: stations.length,
+        dockCount: stations.reduce((total, station) => total + station.dockCount, 0),
+        bikeCount: stations.reduce((total, station) => total + station.bikeCount, 0),
+        electricBikeCount: stations.reduce((total, station) => total + station.electricBikeCount, 0),
+        largestStations,
+    };
+}
+/**
+ * Lists every Santander Cycles docking station from TfL.
+ *
+ * @param options - an optional app key and fetch implementation
+ * @returns the docking stations the endpoint returns
+ */
+export async function fetchTflBikePoints(options = {}) {
+    const { apiKey, fetchImpl = globalThis.fetch } = options;
+    const url = apiKey === undefined
+        ? TFL_BIKE_POINTS_URL
+        : `${TFL_BIKE_POINTS_URL}?app_key=${encodeURIComponent(apiKey)}`;
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new UkSourceApiError('tfl-bike-points', `HTTP ${response.status} listing docking stations`);
+    }
+    return parseTflBikePoints(await response.json());
+}
+/** Transport for London Santander Cycles docking stations, keyless. */
+export const tflBikePointsAdapter = {
+    id: 'tfl-bike-points',
+    name: 'Transport for London Santander Cycles docking stations',
+    auth: 'none',
+    description: 'Every Santander Cycles docking station, with its docking points and docked bikes.',
+    fetchLive: (options) => fetchTflBikePoints({
+        ...(options?.apiKey === undefined ? {} : { apiKey: options.apiKey }),
+        ...(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    }),
+    parse: parseTflBikePoints,
+    loadFixture: () => parseTflBikePoints(readFixtureJson('tfl-bike-points.json')),
+};
+//# sourceMappingURL=tflBikePoints.js.map

package/dist/tflBikePoints.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/** What a UK source needs before it will answer a request. */
+export type UkSourceAuth = 'none' | 'key';
+/** Options shared by every adapter's live fetch. */
+export interface UkFetchOptions {
+    apiKey?: string;
+    fetchImpl?: typeof globalThis.fetch;
+}
+/**
+ * One UK data source behind a uniform interface: a live fetch, a strict
+ * parse, and a committed fixture fallback so builds work offline.
+ */
+export interface UkDataAdapter<T> {
+    readonly id: string;
+    readonly name: string;
+    readonly auth: UkSourceAuth;
+    readonly description: string;
+    fetchLive(options?: UkFetchOptions): Promise<T>;
+    parse(payload: unknown): T;
+    loadFixture(): T;
+}
+/** Result of a live verification probe against one source. */
+export interface UkSourceProbe {
+    id: string;
+    name: string;
+    auth: UkSourceAuth;
+    ok: boolean;
+    status: string;
+    sample?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,CAAC;AAE1C,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,SAAS,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,CAAC;IAC3B,WAAW,IAAI,CAAC,CAAC;CAClB;AAED,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}