@uk-energy/neso 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,365 @@
+import { RateLimit, HttpClient, HttpClientOptions, Query, DateInput } from '@uk-energy/core';
+
+/**
+ * Shapes of the NESO Data Portal (CKAN 2.8) API and of the datasets this package wraps.
+ * Column names are the portal's own, spaces and all, so rows match what the SQL endpoint and
+ * the CSV downloads show. There is no OpenAPI document for the portal; these are hand-typed
+ * from recorded responses (fixtures/api.neso.energy) and checked by the tests.
+ *
+ * Supported by National Energy SO Open Data.
+ */
+interface CkanSuccess<T> {
+    help: string;
+    success: true;
+    result: T;
+}
+interface CkanFailure {
+    help: string;
+    success: false;
+    error: {
+        message?: string;
+        __type?: string;
+        [field: string]: unknown;
+    };
+}
+type CkanResponse<T> = CkanSuccess<T> | CkanFailure;
+interface CkanResource {
+    id: string;
+    package_id: string;
+    name: string;
+    description: string;
+    format: string;
+    url: string;
+    /** True when the resource is loaded into the datastore (CSV/XLSX pushed to Postgres). */
+    datastore_active: boolean;
+    last_modified: string | null;
+    created: string;
+    size: number | null;
+    position: number;
+    state: string;
+    mimetype: string | null;
+}
+interface CkanPackage {
+    id: string;
+    name: string;
+    title: string;
+    notes: string;
+    license_id: string;
+    license_title: string;
+    license_url?: string;
+    metadata_created: string;
+    metadata_modified: string;
+    num_resources: number;
+    organization: {
+        name: string;
+        title: string;
+    } | null;
+    resources: CkanResource[];
+    tags: {
+        name: string;
+        display_name: string;
+    }[];
+    extras: {
+        key: string;
+        value: string;
+    }[];
+}
+interface CkanPackageSearch {
+    count: number;
+    results: CkanPackage[];
+}
+/** Datastore column: `int4`, `numeric`, `text`, `date`, `timestamp`, `tsvector`… */
+interface DatastoreField {
+    id: string;
+    type: string;
+}
+interface DatastoreSearchResult<Row = DatastoreRow> {
+    resource_id: string;
+    fields: DatastoreField[];
+    records: Row[];
+    total: number;
+    limit?: number;
+    offset?: number;
+    _links?: {
+        start?: string;
+        next?: string;
+        prev?: string;
+    };
+}
+interface DatastoreSqlResult<Row = DatastoreRow> {
+    sql: string;
+    fields: DatastoreField[];
+    records: Row[];
+}
+type DatastoreRow = Record<string, string | number | boolean | null>;
+interface DatastoreSearchOptions {
+    /** Rows per request; the portal returns everything up to 32,000 in one page. */
+    limit?: number;
+    offset?: number;
+    /** e.g. `"_id"` or `"Settlement Date desc"`. */
+    sort?: string;
+    /** Equality filters, `{ "Constraint Group": "ESTEX" }`. */
+    filters?: Record<string, string | number | boolean | (string | number)[]>;
+    /** Columns to return. */
+    fields?: string[];
+    /** Full-text query. */
+    q?: string;
+}
+/** `thermal-constraint-costs`, one row per boundary per day. */
+interface ThermalConstraintCostRow {
+    _id: number;
+    "Settlement Date": string;
+    "Constraint Group": string;
+    "Daily Cost (GBP)": number;
+}
+/** `constraint-breakdown`: daily cost (£) and volume (MWh) by constraint type. */
+interface ConstraintBreakdownRow {
+    _id: number;
+    Date: string;
+    "Reducing largest loss cost": number;
+    "Increasing system inertia cost": number;
+    "Voltage constraints cost": number;
+    "Thermal constraints cost": number;
+    "Reducing largest loss volume": number;
+    "Increasing system inertia volume": number;
+    "Voltage constraints volume": number;
+    "Thermal constraints volume": number;
+}
+/** `24-months-ahead-constraint-cost-forecast`: £m per month. */
+interface ConstraintForecastRow {
+    _id: number;
+    /** "Nov-26" */
+    Month: string;
+    "Constraint Cost": number;
+}
+/** `24-months-ahead-constraint-limits`: MW limit per boundary per week. Boundary columns vary. */
+interface ConstraintLimitRow {
+    _id: number;
+    YEAR: number;
+    "Week No": number;
+    [boundary: string]: number | undefined;
+}
+/** `day-ahead-constraint-flows-and-limits`: half-hourly forecast flow vs limit per boundary. */
+interface DayAheadFlowRow {
+    _id: number;
+    "Constraint Group": string;
+    /** Local time (GMT/BST), no offset: "2026-10-15T00:00:00". */
+    "Date_ Time GMT_BST": string;
+    Limit_MW: number;
+    Flow_MW: number;
+}
+/** `daily-balancing-costs-balancing-services-use-of-system`: £ per settlement period by category. */
+interface DailyBalancingCostRow {
+    _id: number;
+    SETT_DATE: string;
+    SETT_PERIOD: number;
+    "Energy Imbalance": number;
+    "Frequency Control": number;
+    "Positive Reserve": number;
+    Constraints: number;
+    "Negative Reserve": number;
+    Other: number;
+}
+/** Demand Flexibility Service: a requirement published ahead of an event window. */
+interface DfsRequirementRow {
+    _id: number;
+    "Event ID": number;
+    "DFS Submission Time_Local": string;
+    "Event Type": string;
+    "Event Tag": string;
+    "Delivery Date": string;
+    From_Local: string;
+    To_Local: string;
+    From_UTC: string;
+    To_UTC: string;
+    "Service Requirement MW": number;
+    "Service Requirement Type": string;
+    "Guaranteed Acceptance Price GBP per MWh": number;
+    "Dispatch Type": string;
+    "Participant Bids Eligible": string;
+    "Zonal Cap": string;
+}
+/** DFS utilisation: one row per participant unit per event window. */
+interface DfsUtilisationRow {
+    _id: number;
+    "Event ID": number;
+    "Event Type": string;
+    "Event Tag": string;
+    "Delivery Date": string;
+    From_Local: string;
+    To_Local: string;
+    From_UTC: string;
+    To_UTC: string;
+    "Registered DFS Participant": string;
+    "DFS Unit ID": string;
+    Zone: number;
+    "DFS Procured MW": number;
+    "Service Requirement Type": string;
+    "Utilisation Price GBP per MWh": number;
+    Status: string;
+}
+/** DFS utilisation summary: one row per event window. */
+interface DfsSummaryRow {
+    _id: number;
+    "Event ID": number;
+    "Event Type": string;
+    "Event Tag": string;
+    "Delivery Date": string;
+    From_Local: string;
+    To_Local: string;
+    From_UTC: string;
+    To_UTC: string;
+    "Service Requirement Type": string;
+    "Service Requirement MW": number;
+    "DFS Procured MW": number;
+    "DFS Provider Bids Accepted Total Cost GBP": number;
+    "Settled Volume MW": number | null;
+    "Settled Cost GBP": number | null;
+}
+
+/**
+ * Client for the NESO Data Portal (https://www.neso.energy/data-portal), a CKAN 2.8 instance at
+ * https://api.neso.energy/api/3/action/. No API key. Datasets ("packages") hold "resources";
+ * tabular resources are loaded into a Postgres datastore that `datastore_search` and
+ * `datastore_search_sql` query. Many datasets split one resource per GB financial year
+ * (April–March), so the helpers resolve the right resource(s) for a date range.
+ *
+ *   const neso = new NesoClient();
+ *   const costs = await neso.constraints.thermalCosts("2025-04-01", "2025-04-07"); // £/day per boundary
+ *   const dfs = await neso.dfs.summary("2026-10-20", "2026-10-22");
+ *   const rows = await neso.ckan.sql(`SELECT * FROM "407f3e9d-…" WHERE "Settlement Date" = '2025-04-01'`);
+ *
+ * Licence: National Energy SO Open Data Licence v1.0 (OGL v3 based): copy, adapt, use
+ * commercially, with the attribution "Supported by National Energy SO Open Data".
+ */
+
+declare const BASE_URL = "https://api.neso.energy/api/3/action";
+/**
+ * No limit is published; the licence only reserves the right to throttle "excessive use".
+ * 5 rps / burst 10 is comfortably polite for a shared public CKAN.
+ */
+declare const DEFAULT_RATE_LIMIT: RateLimit;
+/** Resources update daily or weekly; package metadata is memoised for this long. */
+declare const DEFAULT_CACHE_TTL_MS: number;
+/** The portal returns up to this many rows per `datastore_search` page. */
+declare const MAX_PAGE_SIZE = 32000;
+/** Dataset (package) names on the portal that the helpers use. */
+declare const PACKAGES: {
+    readonly thermalConstraintCosts: "thermal-constraint-costs";
+    readonly constraintBreakdown: "constraint-breakdown";
+    readonly constraintCostForecast24m: "24-months-ahead-constraint-cost-forecast";
+    readonly constraintLimits24m: "24-months-ahead-constraint-limits";
+    readonly dayAheadConstraintFlows: "day-ahead-constraint-flows-and-limits";
+    readonly dailyBalancingCosts: "daily-balancing-costs-balancing-services-use-of-system";
+    readonly demandFlexibility: "demand-flexibility";
+};
+interface NesoClientOptions extends Omit<HttpClientOptions, "baseUrl"> {
+    baseUrl?: string;
+}
+/**
+ * The SQL endpoint returns `numeric` columns as strings ("252"); `datastore_search` returns
+ * numbers. Make rows consistent: numeric-typed columns become numbers, `_full_text` goes.
+ */
+declare function normaliseRows<Row extends object>(records: readonly DatastoreRow[], fields: readonly DatastoreField[], extraNumeric?: readonly string[]): Row[];
+/** Double-quote an identifier for the SQL endpoint. */
+declare function ident(name: string): string;
+/** Single-quote a literal for the SQL endpoint. */
+declare function literal(value: string | number): string;
+/**
+ * `SELECT * FROM "resource" WHERE "col" >= 'from' AND "col" <= 'to' ORDER BY …` — the shape
+ * every date-range helper uses. `toExclusive` switches the upper bound to `<` for timestamps.
+ */
+declare function rangeSql(resourceId: string, column: string, from: string, to: string, orderBy: readonly string[], opts?: {
+    toExclusive?: boolean;
+    where?: string | undefined;
+}): string;
+declare class NesoClient {
+    readonly http: HttpClient;
+    private readonly packageCache;
+    private readonly packageTtlMs;
+    constructor(opts?: NesoClientOptions);
+    /** Any CKAN action; unwraps `{ success, result }` and throws `UkEnergyError` on `success: false`. */
+    action<T>(name: string, query?: Query): Promise<T>;
+    /** Raw CKAN API. */
+    readonly ckan: {
+        /** Dataset metadata and its resources (memoised for `cacheTtlMs`, default 10 minutes). */
+        packageShow: (id: string) => Promise<CkanPackage>;
+        /** Search datasets by free text. */
+        packageSearch: (q: string, rows?: number) => Promise<CkanPackageSearch>;
+        resourceShow: (id: string) => Promise<CkanResource>;
+        /** One page of a datastore resource (up to 32,000 rows). Rows are normalised (see `normaliseRows`). */
+        datastoreSearch: <Row extends object = DatastoreRow>(resourceId: string, opts?: DatastoreSearchOptions) => Promise<DatastoreSearchResult<Row>>;
+        /** Every row of a datastore resource, paging by `limit` (default 32,000). */
+        datastoreAll: <Row extends object = DatastoreRow>(resourceId: string, opts?: Omit<DatastoreSearchOptions, "offset">) => Promise<Row[]>;
+        /**
+         * `datastore_search_sql`: read-only PostgreSQL over the datastore. Resource ids are the
+         * table names (quote them). Numeric columns come back as strings from this endpoint; they
+         * are converted using the `fields` types, and `_full_text` is dropped.
+         */
+        sql: <Row extends object = DatastoreRow>(sql: string, extraNumeric?: readonly string[]) => Promise<Row[]>;
+    };
+    /** Resolving resources inside datasets. */
+    readonly resources: {
+        /** All datastore-backed resources of a dataset. */
+        datastore: (packageId: string) => Promise<CkanResource[]>;
+        /** The resource for a GB financial year (`2025` = April 2025 – March 2026), by name. */
+        forFinancialYear: (packageId: string, startYear: number) => Promise<CkanResource>;
+        /** The datastore resource whose name matches exactly (or the regex), e.g. "DFS Utilisation Report". */
+        byName: (packageId: string, name: string | RegExp) => Promise<CkanResource>;
+    };
+    /** Rows of a per-financial-year dataset for an inclusive date range, across year boundaries. */
+    private byFinancialYear;
+    /** Transmission constraint costs and forecasts. */
+    readonly constraints: {
+        /**
+         * Thermal constraint cost per boundary per day (£), `thermal-constraint-costs`. One row per
+         * constraint group per settlement date, e.g. SCOTEX, SSHARN, SEIMP (Scottish export
+         * boundaries), ESTEX, SWALEX.
+         */
+        thermalCosts: (from: DateInput, to: DateInput, constraintGroup?: string) => Promise<ThermalConstraintCostRow[]>;
+        /**
+         * Daily constraint cost (£) and volume (MWh) by type: thermal, voltage, inertia, largest
+         * loss (`constraint-breakdown`). Thermal volume is negative (energy turned down).
+         */
+        breakdown: (from: DateInput, to: DateInput) => Promise<ConstraintBreakdownRow[]>;
+        /** NESO's 24-month-ahead constraint cost forecast, £m per month (24 rows). */
+        forecast24m: () => Promise<ConstraintForecastRow[]>;
+        /** 24-month-ahead boundary limits (MW) per week; boundary columns vary by publication. */
+        limits24m: () => Promise<ConstraintLimitRow[]>;
+        /**
+         * Day-ahead forecast flow vs limit per boundary, half-hourly, for a range of local dates
+         * (`day-ahead-constraint-flows-and-limits`, ~750k rows, so always filtered by SQL).
+         */
+        dayAheadFlows: (from: DateInput, to: DateInput, constraintGroup?: string) => Promise<DayAheadFlowRow[]>;
+        /** Daily balancing (BSUoS) costs per settlement period by category, incl. `Constraints` (£). */
+        dailyBalancingCosts: (from: DateInput, to: DateInput) => Promise<DailyBalancingCostRow[]>;
+    };
+    /** Demand Flexibility Service (current season; archives are separate resources). */
+    readonly dfs: {
+        /** Published requirements per event window, by delivery date. */
+        requirements: (from: DateInput, to: DateInput) => Promise<DfsRequirementRow[]>;
+        /** Accepted/rejected bids per participant unit per event window. */
+        utilisation: (from: DateInput, to: DateInput) => Promise<DfsUtilisationRow[]>;
+        /** Procured MW, accepted cost and settled volume/cost per event window. */
+        summary: (from: DateInput, to: DateInput) => Promise<DfsSummaryRow[]>;
+    };
+    private dfsRange;
+}
+
+/**
+ * Financial-year arithmetic and resource-name matching for datasets split one resource per
+ * GB financial year (1 April – 31 March): "Thermal Constraint Costs Data 25-26",
+ * "Constraint Breakdown 2025-2026", "Daily Balancing Costs 2025-2026".
+ */
+
+/** Financial year a date ("YYYY-MM-DD") falls in, as its starting calendar year. */
+declare function financialYearOf(date: string): number;
+/** Starting years of every financial year touched by an inclusive date range. */
+declare function financialYearsBetween(from: string, to: string): number[];
+/** The financial year a resource name refers to ("25-26" / "2025-2026" → 2025), or undefined. */
+declare function financialYearInName(name: string): number | undefined;
+/** The datastore resource of a dataset for one financial year, if any. */
+declare function resourceForFinancialYear(resources: readonly CkanResource[], startYear: number): CkanResource | undefined;
+
+export { BASE_URL, DEFAULT_CACHE_TTL_MS, DEFAULT_RATE_LIMIT, MAX_PAGE_SIZE, NesoClient, PACKAGES, financialYearInName, financialYearOf, financialYearsBetween, ident, literal, normaliseRows, rangeSql, resourceForFinancialYear };
+export type { CkanFailure, CkanPackage, CkanPackageSearch, CkanResource, CkanResponse, CkanSuccess, ConstraintBreakdownRow, ConstraintForecastRow, ConstraintLimitRow, DailyBalancingCostRow, DatastoreField, DatastoreRow, DatastoreSearchOptions, DatastoreSearchResult, DatastoreSqlResult, DayAheadFlowRow, DfsRequirementRow, DfsSummaryRow, DfsUtilisationRow, NesoClientOptions, ThermalConstraintCostRow };

package/dist/index.js

@@ -0,0 +1,310 @@
+import { HttpClient, UkEnergyError, pages, offsetCursor, londonDate } from '@uk-energy/core';
+
+// src/client.ts
+
+// src/resources.ts
+function financialYearOf(date) {
+  const year = Number(date.slice(0, 4));
+  const month = Number(date.slice(5, 7));
+  return month >= 4 ? year : year - 1;
+}
+function financialYearsBetween(from, to) {
+  const first = financialYearOf(from);
+  const last = financialYearOf(to);
+  const out = [];
+  for (let y = first; y <= last; y++) out.push(y);
+  return out;
+}
+var YEAR_SPAN = /(?<!\d)(\d{4}|\d{2})\s*[-/–]\s*(\d{4}|\d{2})(?!\d)/g;
+function financialYearInName(name) {
+  for (const m of name.matchAll(YEAR_SPAN)) {
+    if (!m[1] || !m[2]) continue;
+    const start = m[1].length === 2 ? 2e3 + Number(m[1]) : Number(m[1]);
+    const end = m[2].length === 2 ? 2e3 + Number(m[2]) : Number(m[2]);
+    if (end === start + 1) return start;
+  }
+  return void 0;
+}
+function resourceForFinancialYear(resources, startYear) {
+  return resources.find((r) => r.datastore_active && financialYearInName(r.name) === startYear);
+}
+
+// src/client.ts
+var BASE_URL = "https://api.neso.energy/api/3/action";
+var DEFAULT_RATE_LIMIT = { requestsPerSecond: 5, burst: 10 };
+var DEFAULT_CACHE_TTL_MS = 10 * 60 * 1e3;
+var MAX_PAGE_SIZE = 32e3;
+var PACKAGES = {
+  thermalConstraintCosts: "thermal-constraint-costs",
+  constraintBreakdown: "constraint-breakdown",
+  constraintCostForecast24m: "24-months-ahead-constraint-cost-forecast",
+  constraintLimits24m: "24-months-ahead-constraint-limits",
+  dayAheadConstraintFlows: "day-ahead-constraint-flows-and-limits",
+  dailyBalancingCosts: "daily-balancing-costs-balancing-services-use-of-system",
+  demandFlexibility: "demand-flexibility"
+};
+var DECIMAL = /^-?\d+(\.\d+)?([eE][-+]?\d+)?$/;
+var NUMERIC_TYPES = /* @__PURE__ */ new Set([
+  "numeric",
+  "int4",
+  "int8",
+  "float8",
+  "float4",
+  "int",
+  "double precision"
+]);
+function normaliseRows(records, fields, extraNumeric = []) {
+  const numeric = new Set(extraNumeric);
+  for (const f of fields) if (NUMERIC_TYPES.has(f.type)) numeric.add(f.id);
+  return records.map((r) => {
+    const out = {};
+    for (const [k, v] of Object.entries(r)) {
+      if (k === "_full_text") continue;
+      if (numeric.has(k) && typeof v === "string" && DECIMAL.test(v.trim())) {
+        const n = Number(v);
+        out[k] = Number.isFinite(n) ? n : v;
+      } else {
+        out[k] = v;
+      }
+    }
+    return out;
+  });
+}
+function ident(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+function literal(value) {
+  return typeof value === "number" ? String(value) : `'${value.replace(/'/g, "''")}'`;
+}
+function rangeSql(resourceId, column, from, to, orderBy, opts = {}) {
+  const upper = opts.toExclusive ? "<" : "<=";
+  const extra = opts.where ? ` AND ${opts.where}` : "";
+  const order = orderBy.length ? ` ORDER BY ${orderBy.map(ident).join(", ")}` : "";
+  return `SELECT * FROM ${ident(resourceId)} WHERE ${ident(column)} >= ${literal(from)} AND ${ident(column)} ${upper} ${literal(to)}${extra}${order}`;
+}
+function localRange(from, to) {
+  const f = londonDate(from);
+  const t = londonDate(to);
+  if (f > t) throw new UkEnergyError(`from (${f}) is after to (${t})`);
+  return [f, t];
+}
+function nextDay(date) {
+  const d = /* @__PURE__ */ new Date(`${date}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + 1);
+  return d.toISOString().slice(0, 10);
+}
+var NesoClient = class {
+  http;
+  packageCache = /* @__PURE__ */ new Map();
+  packageTtlMs;
+  constructor(opts = {}) {
+    this.http = new HttpClient({
+      baseUrl: BASE_URL,
+      rateLimit: DEFAULT_RATE_LIMIT,
+      cacheTtlMs: opts.cache ? DEFAULT_CACHE_TTL_MS : 0,
+      ...opts
+    });
+    this.packageTtlMs = opts.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+  }
+  /** Any CKAN action; unwraps `{ success, result }` and throws `UkEnergyError` on `success: false`. */
+  async action(name, query) {
+    const res = await this.http.get(name, query);
+    if (!res || typeof res !== "object" || !("success" in res)) {
+      throw new UkEnergyError(`Unexpected response shape for ${name}`);
+    }
+    if (!res.success) {
+      throw new UkEnergyError(`${name}: ${res.error?.message ?? JSON.stringify(res.error)}`);
+    }
+    return res.result;
+  }
+  /** Raw CKAN API. */
+  ckan = {
+    /** Dataset metadata and its resources (memoised for `cacheTtlMs`, default 10 minutes). */
+    packageShow: async (id) => {
+      const hit = this.packageCache.get(id);
+      if (hit && Date.now() - hit.at < this.packageTtlMs) return hit.value;
+      const value = this.action("package_show", { id }).then((pkg) => {
+        if (!pkg || !Array.isArray(pkg.resources)) {
+          throw new UkEnergyError(`package_show: unexpected shape for ${id}`);
+        }
+        return pkg;
+      });
+      this.packageCache.set(id, { at: Date.now(), value });
+      value.catch(() => this.packageCache.delete(id));
+      return value;
+    },
+    /** Search datasets by free text. */
+    packageSearch: async (q, rows = 20) => this.action("package_search", { q, rows }),
+    resourceShow: async (id) => this.action("resource_show", { id }),
+    /** One page of a datastore resource (up to 32,000 rows). Rows are normalised (see `normaliseRows`). */
+    datastoreSearch: async (resourceId, opts = {}) => {
+      const query = {
+        resource_id: resourceId,
+        limit: opts.limit ?? MAX_PAGE_SIZE,
+        sort: opts.sort ?? "_id"
+      };
+      if (opts.offset !== void 0) query.offset = opts.offset;
+      if (opts.filters) query.filters = JSON.stringify(opts.filters);
+      if (opts.fields) query.fields = opts.fields.join(",");
+      if (opts.q) query.q = opts.q;
+      const res = await this.action("datastore_search", query);
+      if (!Array.isArray(res?.records)) {
+        throw new UkEnergyError("Unexpected response shape for datastore_search");
+      }
+      return { ...res, records: normaliseRows(res.records, res.fields ?? []) };
+    },
+    /** Every row of a datastore resource, paging by `limit` (default 32,000). */
+    datastoreAll: async (resourceId, opts = {}) => {
+      const pageSize = Math.min(opts.limit ?? MAX_PAGE_SIZE, MAX_PAGE_SIZE);
+      const out = [];
+      for await (const page of pages({
+        fetchPage: (offset) => this.ckan.datastoreSearch(resourceId, {
+          ...opts,
+          limit: pageSize,
+          offset: offset ?? 0
+        }),
+        items: (p) => p.records,
+        nextCursor: offsetCursor(pageSize, (p) => p.records.length)
+      })) {
+        out.push(...page.records);
+      }
+      return out;
+    },
+    /**
+     * `datastore_search_sql`: read-only PostgreSQL over the datastore. Resource ids are the
+     * table names (quote them). Numeric columns come back as strings from this endpoint; they
+     * are converted using the `fields` types, and `_full_text` is dropped.
+     */
+    sql: async (sql, extraNumeric = []) => {
+      const res = await this.action("datastore_search_sql", {
+        sql
+      });
+      if (!Array.isArray(res?.records)) {
+        throw new UkEnergyError("Unexpected response shape for datastore_search_sql");
+      }
+      return normaliseRows(res.records, res.fields ?? [], extraNumeric);
+    }
+  };
+  /** Resolving resources inside datasets. */
+  resources = {
+    /** All datastore-backed resources of a dataset. */
+    datastore: async (packageId) => (await this.ckan.packageShow(packageId)).resources.filter((r) => r.datastore_active),
+    /** The resource for a GB financial year (`2025` = April 2025 – March 2026), by name. */
+    forFinancialYear: async (packageId, startYear) => {
+      const pkg = await this.ckan.packageShow(packageId);
+      const r = resourceForFinancialYear(pkg.resources, startYear);
+      if (!r) {
+        throw new UkEnergyError(
+          `${packageId}: no datastore resource for financial year ${startYear}/${(startYear + 1) % 100}`
+        );
+      }
+      return r;
+    },
+    /** The datastore resource whose name matches exactly (or the regex), e.g. "DFS Utilisation Report". */
+    byName: async (packageId, name) => {
+      const list = await this.resources.datastore(packageId);
+      const r = list.find(
+        (x) => typeof name === "string" ? x.name.trim() === name.trim() : name.test(x.name)
+      );
+      if (!r) throw new UkEnergyError(`${packageId}: no datastore resource named ${String(name)}`);
+      return r;
+    }
+  };
+  /** Rows of a per-financial-year dataset for an inclusive date range, across year boundaries. */
+  async byFinancialYear(packageId, column, range, orderBy, opts = {}) {
+    const [from, to] = localRange(range.from, range.to);
+    const out = [];
+    for (const fy of financialYearsBetween(from, to)) {
+      const resource = await this.resources.forFinancialYear(packageId, fy);
+      const sql = rangeSql(resource.id, column, from, to, orderBy, { where: opts.where });
+      out.push(...await this.ckan.sql(sql, opts.extraNumeric));
+    }
+    return out;
+  }
+  /** Transmission constraint costs and forecasts. */
+  constraints = {
+    /**
+     * Thermal constraint cost per boundary per day (£), `thermal-constraint-costs`. One row per
+     * constraint group per settlement date, e.g. SCOTEX, SSHARN, SEIMP (Scottish export
+     * boundaries), ESTEX, SWALEX.
+     */
+    thermalCosts: async (from, to, constraintGroup) => this.byFinancialYear(
+      PACKAGES.thermalConstraintCosts,
+      "Settlement Date",
+      { from, to },
+      ["Settlement Date", "Constraint Group"],
+      constraintGroup ? { where: `${ident("Constraint Group")} = ${literal(constraintGroup)}` } : {}
+    ),
+    /**
+     * Daily constraint cost (£) and volume (MWh) by type: thermal, voltage, inertia, largest
+     * loss (`constraint-breakdown`). Thermal volume is negative (energy turned down).
+     */
+    breakdown: async (from, to) => this.byFinancialYear(PACKAGES.constraintBreakdown, "Date", { from, to }, ["Date"], {
+      // "Thermal constraints cost" is typed text in some years
+      extraNumeric: ["Thermal constraints cost"]
+    }),
+    /** NESO's 24-month-ahead constraint cost forecast, £m per month (24 rows). */
+    forecast24m: async () => {
+      const r = await this.resources.byName(PACKAGES.constraintCostForecast24m, /Forecast/);
+      return this.ckan.datastoreAll(r.id);
+    },
+    /** 24-month-ahead boundary limits (MW) per week; boundary columns vary by publication. */
+    limits24m: async () => {
+      const r = await this.resources.byName(PACKAGES.constraintLimits24m, /limits/i);
+      return this.ckan.datastoreAll(r.id);
+    },
+    /**
+     * Day-ahead forecast flow vs limit per boundary, half-hourly, for a range of local dates
+     * (`day-ahead-constraint-flows-and-limits`, ~750k rows, so always filtered by SQL).
+     */
+    dayAheadFlows: async (from, to, constraintGroup) => {
+      const [f, t] = localRange(from, to);
+      const r = await this.resources.byName(PACKAGES.dayAheadConstraintFlows, /Flows and Limits/);
+      const sql = rangeSql(
+        r.id,
+        "Date_ Time GMT_BST",
+        `${f}T00:00:00`,
+        `${nextDay(t)}T00:00:00`,
+        ["Constraint Group", "Date_ Time GMT_BST"],
+        {
+          toExclusive: true,
+          where: constraintGroup ? `${ident("Constraint Group")} = ${literal(constraintGroup)}` : void 0
+        }
+      );
+      return this.ckan.sql(sql);
+    },
+    /** Daily balancing (BSUoS) costs per settlement period by category, incl. `Constraints` (£). */
+    dailyBalancingCosts: async (from, to) => this.byFinancialYear(PACKAGES.dailyBalancingCosts, "SETT_DATE", { from, to }, [
+      "SETT_DATE",
+      "SETT_PERIOD"
+    ])
+  };
+  /** Demand Flexibility Service (current season; archives are separate resources). */
+  dfs = {
+    /** Published requirements per event window, by delivery date. */
+    requirements: async (from, to) => this.dfsRange("DFS Service Requirement", from, to, [
+      "Event ID",
+      "From_UTC"
+    ]),
+    /** Accepted/rejected bids per participant unit per event window. */
+    utilisation: async (from, to) => this.dfsRange("DFS Utilisation Report", from, to, [
+      "Event ID",
+      "From_UTC",
+      "DFS Unit ID"
+    ]),
+    /** Procured MW, accepted cost and settled volume/cost per event window. */
+    summary: async (from, to) => this.dfsRange("DFS Utilisation Report Summary", from, to, [
+      "Event ID",
+      "From_UTC"
+    ])
+  };
+  async dfsRange(name, from, to, orderBy) {
+    const [f, t] = localRange(from, to);
+    const r = await this.resources.byName(PACKAGES.demandFlexibility, name);
+    return this.ckan.sql(rangeSql(r.id, "Delivery Date", f, t, orderBy));
+  }
+};
+
+export { BASE_URL, DEFAULT_CACHE_TTL_MS, DEFAULT_RATE_LIMIT, MAX_PAGE_SIZE, NesoClient, PACKAGES, financialYearInName, financialYearOf, financialYearsBetween, ident, literal, normaliseRows, rangeSql, resourceForFinancialYear };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map