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

package/dist/bankRate.d.ts

@@ -0,0 +1,107 @@
+import type { UkDataAdapter } from './types.js';
+/**
+ * The Bank of England's official Bank Rate, published in the Bank's
+ * Interactive Statistical Database (IADB). Keyless: the database answers
+ * without a key, and the series is the one the Bank's own statistics pages
+ * read: <https://www.bankofengland.co.uk/statistics>.
+ */
+export declare const BANK_RATE_SOURCE_ID = "bank-rate";
+/** The IADB series code for the daily official Bank Rate. */
+export declare const BANK_RATE_SERIES_CODE = "IUDBEDR";
+/** The IADB CSV endpoint, before the query string is added. */
+export declare const BANK_RATE_CSV_URL = "https://www.bankofengland.co.uk/boeapps/database/_iadb-fromshowcolumns.asp";
+/**
+ * First date the database holds for the daily series, in the database's own
+ * query format. Asking for an earlier start returns the database's error
+ * page rather than a CSV, so the adapter never asks for one.
+ */
+export declare const BANK_RATE_FIRST_QUERY_DATE = "02/Jan/1975";
+/** One date reading: the rate that stood on that day. */
+export interface BankRateObservation {
+    /** ISO date, e.g. "1975-01-02". */
+    date: string;
+    /** The rate on that day, in per cent per year. */
+    ratePercent: number;
+}
+/** One unbroken run at a single level. */
+export interface BankRateSpell {
+    startDate: string;
+    endDate: string;
+    ratePercent: number;
+    /** Calendar days from the first reading to the last, both counted. */
+    dayCount: number;
+}
+/** Rolled-up shape of the whole series. */
+export interface BankRateSummary {
+    /** Daily readings the series carried. */
+    observationCount: number;
+    /** Times the rate moved to a new level. */
+    changeCount: number;
+    /** How many levels the series has stood at. */
+    levelCount: number;
+    firstObservation: BankRateObservation;
+    latestObservation: BankRateObservation;
+    /** Highest level the series reached, and when it lasted. */
+    highestSpell: BankRateSpell;
+    /** Lowest level the series reached, and when it lasted. */
+    lowestSpell: BankRateSpell;
+    /** The longest run at one level. */
+    longestSpell: BankRateSpell;
+    /** Every run at one level, oldest first. */
+    spells: BankRateSpell[];
+}
+/**
+ * Formats a day the way an IADB query string wants it, e.g. "28/Sep/2026".
+ *
+ * @param day - the day to format
+ * @returns the day as DD/Mon/YYYY, read in UTC
+ */
+export declare function formatBankRateQueryDate(day: Date): string;
+/**
+ * Builds the CSV URL for the Bank Rate series, from the series start to a day.
+ *
+ * @param toQueryDate - the last day to ask for, in the database's DD/Mon/YYYY format
+ * @returns the full CSV URL
+ */
+export declare function buildBankRateCsvUrl(toQueryDate: string): string;
+/**
+ * Parses an IADB CSV body into daily Bank Rate readings.
+ *
+ * The CSV carries one row per business day, oldest first, with the date in
+ * the first column and the rate in the second. Dates must run forwards: a
+ * body that repeats or reorders a day would quietly break the spell counts.
+ *
+ * @param csvText - the raw CSV body from the IADB endpoint
+ * @returns one observation per day the database returned
+ */
+export declare function parseBankRateCsv(csvText: string): BankRateObservation[];
+/**
+ * Collapses the daily readings into the runs the rate held one level for.
+ *
+ * @param observations - daily readings, oldest first
+ * @returns one spell per unbroken level, oldest first
+ */
+export declare function buildBankRateSpells(observations: BankRateObservation[]): BankRateSpell[];
+/**
+ * Totals the series and finds its highest, lowest, and longest spells.
+ *
+ * @param observations - daily readings, oldest first
+ * @returns counts, the first and last readings, and the spells
+ */
+export declare function summarizeBankRateSeries(observations: BankRateObservation[]): BankRateSummary;
+/**
+ * Reads the Bank Rate series from the Bank of England's database.
+ *
+ * The database answers with the whole series up to the day asked for, so the
+ * call runs to today rather than to a fixed end date.
+ *
+ * @param options - an optional fetch implementation and an optional "today"
+ * @returns one observation per day the database returned
+ */
+export declare function fetchBankRateObservations(options?: {
+    fetchImpl?: typeof globalThis.fetch;
+    now?: Date;
+}): Promise<BankRateObservation[]>;
+/** Bank of England Bank Rate readings, keyless, one row per business day. */
+export declare const bankRateAdapter: UkDataAdapter<BankRateObservation[]>;
+//# sourceMappingURL=bankRate.d.ts.map

package/dist/bankRate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bankRate.d.ts","sourceRoot":"","sources":["../src/bankRate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAE/C,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,YAAY,CAAC;AAE/C,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,+EACgD,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AAExD,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,mBAAmB,CAAC;IACtC,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,4DAA4D;IAC5D,YAAY,EAAE,aAAa,CAAC;IAC5B,2DAA2D;IAC3D,WAAW,EAAE,aAAa,CAAC;IAC3B,oCAAoC;IACpC,YAAY,EAAE,aAAa,CAAC;IAC5B,4CAA4C;IAC5C,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAuCD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAOzD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAW/D;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAiCvE;AAeD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,mBAAmB,EAAE,GAAG,aAAa,EAAE,CAiBxF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,mBAAmB,EAAE,GAAG,eAAe,CAyC5F;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,GAChE,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAQhC;AAED,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,mBAAmB,EAAE,CAWhE,CAAC"}

package/dist/bankRate.js

@@ -0,0 +1,251 @@
+import { UkSourceApiError, UkSourceParseError } from './errors.js';
+import { readFixtureText } from './fixtures.js';
+/**
+ * The Bank of England's official Bank Rate, published in the Bank's
+ * Interactive Statistical Database (IADB). Keyless: the database answers
+ * without a key, and the series is the one the Bank's own statistics pages
+ * read: <https://www.bankofengland.co.uk/statistics>.
+ */
+export const BANK_RATE_SOURCE_ID = 'bank-rate';
+/** The IADB series code for the daily official Bank Rate. */
+export const BANK_RATE_SERIES_CODE = 'IUDBEDR';
+/** The IADB CSV endpoint, before the query string is added. */
+export const BANK_RATE_CSV_URL = 'https://www.bankofengland.co.uk/boeapps/database/_iadb-fromshowcolumns.asp';
+/**
+ * First date the database holds for the daily series, in the database's own
+ * query format. Asking for an earlier start returns the database's error
+ * page rather than a CSV, so the adapter never asks for one.
+ */
+export const BANK_RATE_FIRST_QUERY_DATE = '02/Jan/1975';
+/** The two CSV columns the database writes: date then series code. */
+const BANK_RATE_CSV_COLUMNS = 2;
+const CSV_DATE_COLUMN = 0;
+const CSV_RATE_COLUMN = 1;
+/** Milliseconds in a day, for turning a date span into a day count. */
+const MILLISECONDS_PER_DAY = 86_400_000;
+/** The three-letter month names the database writes, January first. */
+const BANK_RATE_MONTH_NAMES = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+];
+/** Month numbers by the name the database writes, e.g. "Jan" to "01". */
+const BANK_RATE_MONTHS = Object.fromEntries(BANK_RATE_MONTH_NAMES.map((name, index) => [name, String(index + 1).padStart(2, '0')]));
+/** Splits a CSV body into rows, tolerating CRLF line endings and a blank tail. */
+function splitCsvRows(csvText) {
+    return csvText
+        .split(/\r?\n/)
+        .map((row) => row.trim())
+        .filter((row) => row !== '');
+}
+/**
+ * Formats a day the way an IADB query string wants it, e.g. "28/Sep/2026".
+ *
+ * @param day - the day to format
+ * @returns the day as DD/Mon/YYYY, read in UTC
+ */
+export function formatBankRateQueryDate(day) {
+    const month = BANK_RATE_MONTH_NAMES[day.getUTCMonth()];
+    const dayOfMonth = String(day.getUTCDate()).padStart(2, '0');
+    if (month === undefined) {
+        throw new UkSourceParseError(BANK_RATE_SOURCE_ID, 'the query date fell outside a year');
+    }
+    return `${dayOfMonth}/${month}/${String(day.getUTCFullYear())}`;
+}
+/**
+ * Builds the CSV URL for the Bank Rate series, from the series start to a day.
+ *
+ * @param toQueryDate - the last day to ask for, in the database's DD/Mon/YYYY format
+ * @returns the full CSV URL
+ */
+export function buildBankRateCsvUrl(toQueryDate) {
+    const url = new URL(BANK_RATE_CSV_URL);
+    url.searchParams.set('csv.x', 'yes');
+    url.searchParams.set('Datefrom', BANK_RATE_FIRST_QUERY_DATE);
+    url.searchParams.set('Dateto', toQueryDate);
+    url.searchParams.set('SeriesCodes', BANK_RATE_SERIES_CODE);
+    url.searchParams.set('CSVF', 'TN');
+    url.searchParams.set('UsingCodes', 'Y');
+    url.searchParams.set('VPD', 'Y');
+    url.searchParams.set('VFD', 'N');
+    return url.href;
+}
+/**
+ * Converts one database date, e.g. "02 Jan 1975", to an ISO date.
+ *
+ * @param value - the date as the database writes it
+ * @returns the same day as YYYY-MM-DD
+ */
+function parseObservationDate(value) {
+    const parts = value.split(' ');
+    const [dayPart, monthPart, yearPart] = parts;
+    const month = monthPart === undefined ? undefined : BANK_RATE_MONTHS[monthPart];
+    if (parts.length !== 3 ||
+        dayPart === undefined ||
+        month === undefined ||
+        yearPart === undefined) {
+        throw new UkSourceParseError(BANK_RATE_SOURCE_ID, `"${value}" is not a database date`);
+    }
+    const day = dayPart.padStart(2, '0');
+    if (!/^\d{2}$/.test(day) || !/^\d{4}$/.test(yearPart)) {
+        throw new UkSourceParseError(BANK_RATE_SOURCE_ID, `"${value}" is not a database date`);
+    }
+    return `${yearPart}-${month}-${day}`;
+}
+/**
+ * Parses an IADB CSV body into daily Bank Rate readings.
+ *
+ * The CSV carries one row per business day, oldest first, with the date in
+ * the first column and the rate in the second. Dates must run forwards: a
+ * body that repeats or reorders a day would quietly break the spell counts.
+ *
+ * @param csvText - the raw CSV body from the IADB endpoint
+ * @returns one observation per day the database returned
+ */
+export function parseBankRateCsv(csvText) {
+    const rows = splitCsvRows(csvText);
+    const header = rows[0]?.split(',') ?? [];
+    if (header[CSV_RATE_COLUMN] !== BANK_RATE_SERIES_CODE) {
+        throw new UkSourceParseError(BANK_RATE_SOURCE_ID, `the CSV header does not name the ${BANK_RATE_SERIES_CODE} series`);
+    }
+    const observations = [];
+    for (const row of rows.slice(1)) {
+        const columns = row.split(',');
+        if (columns.length !== BANK_RATE_CSV_COLUMNS) {
+            throw new UkSourceParseError(BANK_RATE_SOURCE_ID, `"${row}" is not a date and a rate`);
+        }
+        const date = parseObservationDate(columns[CSV_DATE_COLUMN] ?? '');
+        const rawRate = (columns[CSV_RATE_COLUMN] ?? '').trim();
+        const rate = Number(rawRate);
+        if (rawRate === '' || !Number.isFinite(rate)) {
+            throw new UkSourceParseError(BANK_RATE_SOURCE_ID, `"${row}" carries no rate`);
+        }
+        const previous = observations.at(-1);
+        if (previous !== undefined && previous.date >= date) {
+            throw new UkSourceParseError(BANK_RATE_SOURCE_ID, `${date} does not follow ${previous.date}`);
+        }
+        observations.push({ date, ratePercent: rate });
+    }
+    if (observations.length === 0) {
+        throw new UkSourceParseError(BANK_RATE_SOURCE_ID, 'the CSV carried no readings');
+    }
+    return observations;
+}
+/**
+ * Days between two ISO dates, counting both ends.
+ *
+ * @param startDate - the first day of the run
+ * @param endDate - the last day of the run
+ * @returns how many calendar days the run covers
+ */
+function countDaysBetween(startDate, endDate) {
+    const start = Date.parse(`${startDate}T00:00:00Z`);
+    const end = Date.parse(`${endDate}T00:00:00Z`);
+    return Math.round((end - start) / MILLISECONDS_PER_DAY) + 1;
+}
+/**
+ * Collapses the daily readings into the runs the rate held one level for.
+ *
+ * @param observations - daily readings, oldest first
+ * @returns one spell per unbroken level, oldest first
+ */
+export function buildBankRateSpells(observations) {
+    const spells = [];
+    for (const observation of observations) {
+        const open = spells.at(-1);
+        if (open?.ratePercent === observation.ratePercent) {
+            open.endDate = observation.date;
+            open.dayCount = countDaysBetween(open.startDate, observation.date);
+            continue;
+        }
+        spells.push({
+            startDate: observation.date,
+            endDate: observation.date,
+            ratePercent: observation.ratePercent,
+            dayCount: 1,
+        });
+    }
+    return spells;
+}
+/**
+ * Totals the series and finds its highest, lowest, and longest spells.
+ *
+ * @param observations - daily readings, oldest first
+ * @returns counts, the first and last readings, and the spells
+ */
+export function summarizeBankRateSeries(observations) {
+    const spells = buildBankRateSpells(observations);
+    const firstObservation = observations[0];
+    const latestObservation = observations.at(-1);
+    const firstSpell = spells[0];
+    const lastSpell = spells.at(-1);
+    if (firstObservation === undefined ||
+        latestObservation === undefined ||
+        firstSpell === undefined ||
+        lastSpell === undefined) {
+        throw new UkSourceParseError(BANK_RATE_SOURCE_ID, 'the series carried no readings');
+    }
+    let highestSpell = firstSpell;
+    let lowestSpell = firstSpell;
+    let longestSpell = firstSpell;
+    for (const spell of spells) {
+        if (spell.ratePercent > highestSpell.ratePercent) {
+            highestSpell = spell;
+        }
+        if (spell.ratePercent < lowestSpell.ratePercent) {
+            lowestSpell = spell;
+        }
+        if (spell.dayCount > longestSpell.dayCount) {
+            longestSpell = spell;
+        }
+    }
+    return {
+        observationCount: observations.length,
+        changeCount: spells.length - 1,
+        levelCount: new Set(spells.map((spell) => spell.ratePercent)).size,
+        firstObservation,
+        latestObservation,
+        highestSpell,
+        lowestSpell,
+        longestSpell,
+        spells,
+    };
+}
+/**
+ * Reads the Bank Rate series from the Bank of England's database.
+ *
+ * The database answers with the whole series up to the day asked for, so the
+ * call runs to today rather than to a fixed end date.
+ *
+ * @param options - an optional fetch implementation and an optional "today"
+ * @returns one observation per day the database returned
+ */
+export async function fetchBankRateObservations(options = {}) {
+    const { fetchImpl = globalThis.fetch, now = new Date() } = options;
+    const url = buildBankRateCsvUrl(formatBankRateQueryDate(now));
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new UkSourceApiError(BANK_RATE_SOURCE_ID, `HTTP ${response.status} reading Bank Rate`);
+    }
+    return parseBankRateCsv(await response.text());
+}
+/** Bank of England Bank Rate readings, keyless, one row per business day. */
+export const bankRateAdapter = {
+    id: BANK_RATE_SOURCE_ID,
+    name: 'Bank of England Bank Rate',
+    auth: 'none',
+    description: 'The daily official Bank Rate, from 2 January 1975 to the latest published day.',
+    fetchLive: (options) => fetchBankRateObservations(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: parseBankRateCsv,
+    loadFixture: () => parseBankRateCsv(readFixtureText('bank-rate.csv')),
+};
+//# sourceMappingURL=bankRate.js.map

package/dist/bankRate.js.map

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

package/dist/carbonIntensity.d.ts

@@ -0,0 +1,151 @@
+import type { UkDataAdapter } from './types.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 declare const CARBON_INTENSITY_SOURCE_ID = "carbon-intensity";
+/** Root every call here is built from. */
+export declare const CARBON_INTENSITY_API_BASE_URL = "https://api.carbonintensity.org.uk";
+/** Half-hourly readings between two instants. */
+export declare const CARBON_INTENSITY_RANGE_URL = "https://api.carbonintensity.org.uk/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 declare const CARBON_INTENSITY_MAX_WINDOW_DAYS = 30;
+/** How many complete days the default window covers. */
+export declare const DEFAULT_CARBON_INTENSITY_WINDOW_DAYS = 30;
+/** How long one reading covers. */
+export declare const CARBON_INTENSITY_PERIOD_MINUTES = 30;
+/**
+ * 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 declare const CARBON_INTENSITY_INDEX_BANDS: readonly ["very low", "low", "moderate", "high", "very high"];
+/** One of the grades the API labels a half hour with. */
+export type CarbonIntensityIndex = (typeof CARBON_INTENSITY_INDEX_BANDS)[number];
+/** One half hour of the series, with the reading the API holds for it. */
+export interface CarbonIntensityPeriod {
+    /** Start of the half hour, as an ISO instant in UTC. */
+    from: string;
+    /** End of the half hour, as an ISO instant in UTC. */
+    to: string;
+    /** The estimated actual intensity over the half hour, in gCO2/kWh. */
+    intensity: number;
+    /** The grade the API puts that reading in. */
+    index: CarbonIntensityIndex;
+}
+/** How many half hours the window holds at one grade. */
+export interface CarbonIntensityBandCount {
+    index: CarbonIntensityIndex;
+    periodCount: number;
+}
+/** A window of half-hourly readings, rolled up into the numbers a page prints. */
+export interface CarbonIntensityWindow {
+    /** Half hours the window holds. */
+    periodCount: number;
+    /** Complete days the window covers. */
+    dayCount: number;
+    /** Start of the oldest half hour in the window. */
+    firstPeriodFrom: string;
+    /** End of the newest half hour in the window. */
+    lastPeriodTo: string;
+    /** Mean intensity across the window, rounded to a whole number. */
+    averageIntensity: number;
+    /** The cleanest half hour in the window. */
+    lowestPeriod: CarbonIntensityPeriod;
+    /** The dirtiest half hour in the window. */
+    highestPeriod: CarbonIntensityPeriod;
+    /** Half hours per grade, lowest grade first. */
+    bandCounts: CarbonIntensityBandCount[];
+    /** Every reading, oldest first. */
+    periods: CarbonIntensityPeriod[];
+}
+/**
+ * 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 declare function formatCarbonIntensityInstant(date: Date): string;
+/**
+ * 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 declare function resolveCarbonIntensityWindow(options?: {
+    windowDays?: number;
+    now?: Date;
+}): {
+    from: string;
+    to: string;
+};
+/**
+ * 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 declare function validateCarbonIntensityWindow(window: {
+    from?: string | undefined;
+    to?: string | undefined;
+}): {
+    from: string;
+    to: string;
+};
+/**
+ * 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 declare function buildCarbonIntensityWindowUrl(window: {
+    from: string;
+    to: string;
+}): string;
+/**
+ * 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 declare function parseCarbonIntensityWindow(payload: unknown): CarbonIntensityWindow;
+/**
+ * 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 declare function fetchCarbonIntensityWindow(options?: {
+    windowDays?: number;
+    now?: Date;
+    from?: string | undefined;
+    to?: string | undefined;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<CarbonIntensityWindow>;
+/** National Energy System Operator half-hourly carbon intensity, keyless. */
+export declare const carbonIntensityAdapter: UkDataAdapter<CarbonIntensityWindow>;
+//# sourceMappingURL=carbonIntensity.d.ts.map

package/dist/carbonIntensity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carbonIntensity.d.ts","sourceRoot":"","sources":["../src/carbonIntensity.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAE7D,0CAA0C;AAC1C,eAAO,MAAM,6BAA6B,uCAAuC,CAAC;AAElF,iDAAiD;AACjD,eAAO,MAAM,0BAA0B,iDAA+C,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAEnD,wDAAwD;AACxD,eAAO,MAAM,oCAAoC,KAAK,CAAC;AAEvD,mCAAmC;AACnC,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAWlD;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,+DAM/B,CAAC;AAEX,yDAAyD;AACzD,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjF,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AAED,yDAAyD;AACzD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,kFAAkF;AAClF,MAAM,WAAW,qBAAqB;IACpC,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,YAAY,EAAE,qBAAqB,CAAC;IACpC,4CAA4C;IAC5C,aAAa,EAAE,qBAAqB,CAAC;IACrC,gDAAgD;IAChD,UAAU,EAAE,wBAAwB,EAAE,CAAC;IACvC,mCAAmC;IACnC,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAuBD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,GAAG;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAkBA;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE;IACpD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB,GAAG;IACF,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAoCA;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE1F;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,qBAAqB,CA8ElF;AAgBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,GAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAChC,GACL,OAAO,CAAC,qBAAqB,CAAC,CAkBhC;AAED,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,qBAAqB,CAYvE,CAAC"}