@uk-energy/elexon 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# @uk-energy/elexon
+
+## 0.2.0
+
+- `curtailment.forDay(date, opts)`: bid acceptances per unit per settlement period joined
+  from BOAV (MWh), EBOCF (£) and BOALF (`soFlag`), with fuel type, GSP group and capacity from
+  the reference list; per-unit and day totals. `aggregateCurtailment()` exported.
+- `balancing.acceptanceVolumes(bidOffer, date, filter)` (BOAV) and
+  `balancing.cashflows(bidOffer, date, filter)` (EBOCF), per day or per period; unit lists
+  chunked at `MAX_UNITS_PER_REQUEST` (200).
+- `reference.units({ fuelType, gspGroupId, leadParty })` and `unitId()` (falls back to the NGC
+  id for the 48 wind units without an Elexon id).
+- Four more fixtures (three curtailed units on 15 Oct 2026, one uncurtailed); 7 new tests.
+
+## 0.1.0
+
+- `ElexonClient` with `datasets.*` (`stream` for any `/datasets/{code}/stream`, plus
+  `boalf`, `bod`, `fuelinst`, `pn`, `pnStream`, `mels`, `mils`), `reference.*`
+  (`bmUnits`, `fuelTypes`) and `balancing.*` (`systemPrices`, `marketIndex`, `acceptances`,
+  `bidOffers`, `physical`).
+- Types generated from the Insights OpenAPI 3.0.4 document (`openapi/insights-v1.json`,
+  322 paths); `DatasetRow<"BOALF">` etc. derived from the spec so `stream()` is typed per
+  dataset code.
+- Bare-array (`/stream`) and `{ data }` envelopes unwrapped; wrong shapes throw
+  `UkEnergyError`; settlement periods validated 1–50; date inputs validated or formatted via
+  `@uk-energy/core` dates.
+- Default 10 rps / burst 20 per host; 5-minute cache TTL when a cache is supplied.
+- 14 fixture-backed tests on 20 recorded responses (every method and both FUELINST query
+  modes; one API 400), shared with `uk_energy.elexon`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Serpis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# @uk-energy/elexon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed client for [Elexon Insights](https://bmrs.elexon.co.uk/api-documentation) (BMRS): bid-offer
+acceptances and prices, physical notifications, generation by fuel, BM unit reference data and
+system prices. No API key. Types are generated from Elexon's OpenAPI document, so field names and
+nullability are the API's own.
+
+> Contains BMRS data © Elexon Limited copyright and database right 2026. Keep this line wherever
+> you show the data. The [BMRS data licence](https://www.elexon.co.uk/data/balancing-mechanism-reporting-agent/copyright-licence-bmrs-data/)
+> allows copying, adapting and selling derived works; it does not imply endorsement.
+
+Python mirror: `uk_energy.elexon` in the `uk-energy` distribution.
+
+```bash
+pnpm add @uk-energy/elexon
+```
+
+## Usage
+
+```ts
+import { ElexonClient } from "@uk-energy/elexon";
+
+const ex = new ElexonClient();
+
+// Bid-offer acceptances for one hour, every unit. soFlag=true bids on wind units are curtailment.
+const boalf = await ex.datasets.boalf({ from: "2026-10-15T00:00Z", to: "2026-10-15T01:00Z" });
+const curtailed = boalf.filter((r) => r.soFlag && r.bmUnit?.endsWith("W-1"));
+
+// Or by settlement period: from/to are then dates, not instants.
+await ex.datasets.boalf({
+  from: "2026-10-15", to: "2026-10-15",
+  settlementPeriodFrom: 1, settlementPeriodTo: 4,
+  bmUnit: ["T_ARCHW-1"],
+});
+
+// Submitted bid/offer prices (BOD). Wind units bid negative: they are paid to turn down.
+const bod = await ex.datasets.bod({ from: "2026-10-15T00:00Z", to: "2026-10-15T01:00Z", bmUnit: ["T_ARCHW-1"] });
+
+// Generation by fuel type, 5-minute resolution
+const fuel = await ex.datasets.fuelinst({ publishDateTimeFrom: "2026-10-15T00:00Z", publishDateTimeTo: "2026-10-15T00:30Z" });
+
+// Every BM unit, with fuel type and capacity
+const units = await ex.reference.bmUnits();
+const wind = units.filter((u) => u.fuelType === "WIND");           // 287 on 20 Oct 2026
+
+// System prices for a settlement day or one period
+const prices = await ex.balancing.systemPrices("2026-10-15");       // 48 rows
+const sp1 = await ex.balancing.systemPrices("2026-10-15", 1);
+
+// Any other /datasets/{code}/stream endpoint, typed by code
+const mels = await ex.datasets.stream("MELS", { from: "2026-10-15T00:00Z", to: "2026-10-15T01:00Z" });
+```
+
+### Curtailment
+
+```ts
+// Every WIND unit (287), one settlement day: the reference list + 3 requests per 200 units (BOAV, EBOCF, BOALF)
+const day = await ex.curtailment.forDay("2026-10-15");
+day.total;            // { curtailedMwh, soFlaggedMwh, cashflowGbp, units, acceptances }
+day.units[0];         // biggest curtailed unit: { bmUnit, leadPartyName, gspGroupId, capacityMw, curtailedMwh, cashflowGbp, … }
+day.periods;          // one row per (unit, settlement period) with volume, £ and SO flag counts
+
+// A few units, a few periods
+await ex.curtailment.forDay("2026-10-15", { bmUnit: ["T_AKGLW-3"], settlementPeriodFrom: 1, settlementPeriodTo: 8 });
+
+// The feeds behind it
+await ex.balancing.acceptanceVolumes("bid", "2026-10-15", { bmUnit: ["T_AKGLW-3"] }); // BOAV, MWh per acceptance per period
+await ex.balancing.cashflows("bid", "2026-10-15", { bmUnit: ["T_AKGLW-3"] });         // EBOCF, £ per unit per period
+await ex.reference.units({ fuelType: ["WIND"], gspGroupId: ["_P", "_N"] });           // Scottish wind units
+```
+
+A curtailment is a **bid acceptance**: NESO accepts the unit's (negative-priced) bid to reduce
+output, so the unit is *paid* to turn down and `cashflowGbp` is positive. `soFlaggedMwh` is the
+share from acceptances BOALF marks `soFlag: true` — system (constraint) actions rather than energy
+balancing. On 15 Oct 2026, AKGLW-3 was curtailed in 42 of 48 periods for 1,019 MWh and £49.5k,
+all SO-flagged. `aggregateCurtailment()` is exported for callers with their own rows.
+
+Every method is `async` and returns the API's rows unwrapped: `/stream` endpoints are bare arrays,
+`/datasets/{code}` and `/balancing/*` endpoints come back as `{ data, metadata }` and only `data`
+is returned. A response of the wrong shape throws `UkEnergyError`; an HTTP error throws
+`HttpError` with the API's RFC 9110 problem details in `body`.
+
+### Surface
+
+| Namespace | Methods |
+| --- | --- |
+| `datasets` | `stream(code, query)`, `boalf`, `bod`, `fuelinst`, `pn(date, sp, filter)`, `pnStream`, `mels`, `mils` |
+| `reference` | `bmUnits()`, `fuelTypes()`, `units({ fuelType?, gspGroupId?, leadParty? })` |
+| `balancing` | `systemPrices(date, sp?)`, `marketIndex`, `acceptances(date, sp, filter)`, `bidOffers(date, sp, filter)`, `physical(dataset, date, sp, filter)`, `acceptanceVolumes(bidOffer, date, filter)`, `cashflows(bidOffer, date, filter)` |
+| `curtailment` | `forDay(date, { bmUnit?, fuelType?, settlementPeriodFrom?, settlementPeriodTo? })` |
+
+Row types are exported: `BoalfRow`, `BodRow`, `FuelinstRow`, `PnRow`, `MelsRow`, `BmUnit`,
+`SystemPriceRow`, `MarketIndexRow`, `AcceptanceRow`, `BidOfferRow`, `PhysicalRow`, plus the
+`SettlementWindow` / `UnitFilter` / `FuelinstQuery` argument types; the full
+generated `paths`/`components` are under `@uk-energy/elexon` as well for anything not wrapped.
+
+## Things to know about the API
+
+- **Settlement time is local.** A settlement day starts at Europe/London midnight; in BST,
+  SP1 of 15 Oct starts at `2026-10-14T23:00Z`. Days have 48 periods, 46 on the spring clock
+  change and 50 on the autumn one. `@uk-energy/core` exports `settlementPeriodAt`,
+  `settlementPeriodStart` and friends for the conversion.
+- **`from`/`to` change meaning** on BOALF/BOD: instants normally, but calendar dates when
+  `settlementPeriodFrom`/`To` are given.
+- **BOALF is a volume of levels, not a list of curtailment events.** One hour across all
+  units is ~1,650 rows; one settlement period of acceptances is ~730. Filter by `bmUnit`
+  where you can.
+- **`reference/bmunits/all`** is ~3,100 units with capacities as strings (`"114.000"`), and
+  `gspGroupId` is `null` for 235 of the 287 wind units (transmission-connected), so GSP group
+  cannot place most wind farms on a constraint boundary. 48 wind units have no `elexonBmUnit`;
+  `unitId()` falls back to `nationalGridBmUnit`, which the API accepts as a filter too. The list
+  also has duplicates (`T_WLNYO-4` twice); `curtailment.forDay` de-duplicates ids.
+- **Unit filters can be long.** The API accepted all 287 wind ids in one 4.9 KB URL; the client
+  splits lists at `MAX_UNITS_PER_REQUEST` (200) anyway. Unfiltered daily BOAV is ~9 MB.
+- **Rate limits:** none published and none observed (310 requests at ~120 rps on 20 Oct 2026,
+  all 200). The client defaults to 10 rps / burst 20 per host, shared across clients in the
+  process; pass `rateLimit` to change it.
+- **Errors** are RFC 9110 problem details with a `400` for a `from` later than `to` or a bad
+  dataset code.
+
+## Options
+
+```ts
+new ElexonClient({
+  rateLimit: { requestsPerSecond: 10, burst: 20 }, // default
+  cache: new MemoryCache(),                          // optional; TTL defaults to 5 minutes
+  cacheTtlMs: 5 * 60 * 1000,
+  retry: { retries: 3 }, timeoutMs: 30_000, fetch,   // forwarded to @uk-energy/core HttpClient
+});
+```
+
+## Regenerating the types
+
+`openapi/insights-v1.json` is a snapshot of `https://data.elexon.co.uk/swagger/v1/swagger.json`.
+Replace it and run `pnpm --filter @uk-energy/elexon generate` (TypeScript) and
+`uv run python scripts/gen_elexon_types.py` from `python/` (Python TypedDicts).

package/dist/index.cjs

@@ -0,0 +1,360 @@
+'use strict';
+
+var core = require('@uk-energy/core');
+
+// src/client.ts
+var DEFAULT_FUEL_TYPES = ["WIND"];
+function compareIds(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function num(s) {
+  if (s == null || s === "") return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+}
+function aggregateCurtailment(settlementDate, range, units, volumes, cashflows, boalf) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const u of units) {
+    if (u.elexonBmUnit) byId.set(u.elexonBmUnit, u);
+    if (u.nationalGridBmUnit) byId.set(u.nationalGridBmUnit, u);
+  }
+  const soByAcceptance = /* @__PURE__ */ new Map();
+  for (const r of boalf) {
+    if (r.acceptanceNumber != null) {
+      soByAcceptance.set(
+        r.acceptanceNumber,
+        (soByAcceptance.get(r.acceptanceNumber) ?? false) || r.soFlag === true
+      );
+    }
+  }
+  const cashByKey = /* @__PURE__ */ new Map();
+  for (const c of cashflows) {
+    const sp = c.settlementPeriod;
+    if (!c.bmUnit || sp === void 0 || sp < range.from || sp > range.to) continue;
+    const key = `${c.bmUnit}|${sp}`;
+    cashByKey.set(key, (cashByKey.get(key) ?? 0) + (c.totalCashflow ?? 0));
+  }
+  const periods = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Map();
+  for (const v of volumes) {
+    const sp = v.settlementPeriod;
+    const acceptance = v.acceptanceId;
+    if (!v.bmUnit || sp === void 0 || acceptance === void 0) continue;
+    if (sp < range.from || sp > range.to) continue;
+    const mwh = -(v.totalVolumeAccepted ?? 0);
+    if (!(mwh > 0)) continue;
+    const key = `${v.bmUnit}|${sp}`;
+    let p = periods.get(key);
+    let ids = seen.get(key);
+    if (!p || !ids) {
+      const ref = byId.get(v.bmUnit);
+      p = {
+        settlementDate: v.settlementDate ?? settlementDate,
+        settlementPeriod: sp,
+        startTime: v.startTime ?? "",
+        bmUnit: v.bmUnit,
+        nationalGridBmUnit: v.nationalGridBmUnit ?? ref?.nationalGridBmUnit ?? null,
+        leadPartyName: v.leadPartyName ?? ref?.leadPartyName ?? null,
+        fuelType: ref?.fuelType ?? null,
+        gspGroupId: ref?.gspGroupId ?? null,
+        capacityMw: num(ref?.generationCapacity),
+        curtailedMwh: 0,
+        soFlaggedMwh: 0,
+        cashflowGbp: cashByKey.get(key) ?? null,
+        acceptances: 0,
+        soFlaggedAcceptances: 0
+      };
+      ids = /* @__PURE__ */ new Set();
+      periods.set(key, p);
+      seen.set(key, ids);
+    }
+    p.curtailedMwh += mwh;
+    const so = soByAcceptance.get(acceptance) === true;
+    if (so) p.soFlaggedMwh += mwh;
+    if (!ids.has(acceptance)) {
+      ids.add(acceptance);
+      p.acceptances += 1;
+      if (so) p.soFlaggedAcceptances += 1;
+    }
+  }
+  const rows = [...periods.values()].sort(
+    (a, b) => a.settlementPeriod - b.settlementPeriod || compareIds(a.bmUnit, b.bmUnit)
+  );
+  const unitTotals = /* @__PURE__ */ new Map();
+  const unitAcceptances = /* @__PURE__ */ new Map();
+  const allAcceptances = /* @__PURE__ */ new Set();
+  const total = { curtailedMwh: 0, soFlaggedMwh: 0, cashflowGbp: 0, units: 0, acceptances: 0 };
+  for (const p of rows) {
+    let u = unitTotals.get(p.bmUnit);
+    if (!u) {
+      u = {
+        bmUnit: p.bmUnit,
+        nationalGridBmUnit: p.nationalGridBmUnit,
+        leadPartyName: p.leadPartyName,
+        fuelType: p.fuelType,
+        gspGroupId: p.gspGroupId,
+        capacityMw: p.capacityMw,
+        curtailedMwh: 0,
+        soFlaggedMwh: 0,
+        cashflowGbp: 0,
+        periods: 0,
+        acceptances: 0
+      };
+      unitTotals.set(p.bmUnit, u);
+    }
+    u.curtailedMwh += p.curtailedMwh;
+    u.soFlaggedMwh += p.soFlaggedMwh;
+    u.cashflowGbp += p.cashflowGbp ?? 0;
+    u.periods += 1;
+    const ids = seen.get(`${p.bmUnit}|${p.settlementPeriod}`) ?? /* @__PURE__ */ new Set();
+    let acc = unitAcceptances.get(p.bmUnit);
+    if (!acc) {
+      acc = /* @__PURE__ */ new Set();
+      unitAcceptances.set(p.bmUnit, acc);
+    }
+    for (const id of ids) {
+      acc.add(id);
+      allAcceptances.add(id);
+    }
+    u.acceptances = acc.size;
+    total.curtailedMwh += p.curtailedMwh;
+    total.soFlaggedMwh += p.soFlaggedMwh;
+    total.cashflowGbp += p.cashflowGbp ?? 0;
+  }
+  total.units = unitTotals.size;
+  total.acceptances = allAcceptances.size;
+  return {
+    settlementDate,
+    settlementPeriodFrom: range.from,
+    settlementPeriodTo: range.to,
+    periods: rows,
+    units: [...unitTotals.values()].sort((a, b) => b.curtailedMwh - a.curtailedMwh),
+    total
+  };
+}
+async function curtailmentForDay(client, settlementDate, opts = {}) {
+  const day = core.formatDate(settlementDate);
+  const last = core.settlementPeriodsInDay(day);
+  const from = opts.settlementPeriodFrom ?? 1;
+  const to = opts.settlementPeriodTo ?? last;
+  if (from < 1 || to > last || from > to) {
+    throw new core.UkEnergyError(`Settlement periods ${from}-${to} are outside 1-${last} for ${day}`);
+  }
+  const units = await client.reference.bmUnits();
+  let ids;
+  if (opts.bmUnit) {
+    ids = opts.bmUnit;
+  } else {
+    const fuel = opts.fuelType ?? DEFAULT_FUEL_TYPES;
+    ids = units.filter((u) => u.fuelType != null && fuel.includes(u.fuelType)).map(unitId).filter((id) => id !== "");
+  }
+  ids = [...new Set(ids)];
+  if (ids.length === 0) throw new core.UkEnergyError("No BM units to query");
+  const [volumes, cashflows, boalfParts] = await Promise.all([
+    client.balancing.acceptanceVolumes("bid", day, { bmUnit: ids }),
+    client.balancing.cashflows("bid", day, { bmUnit: ids }),
+    Promise.all(
+      chunk(ids, MAX_UNITS_PER_REQUEST).map(
+        (bmUnit) => client.datasets.boalf({
+          from: day,
+          to: day,
+          settlementPeriodFrom: 1,
+          settlementPeriodTo: last,
+          bmUnit
+        })
+      )
+    )
+  ]);
+  const boalf = boalfParts.flat();
+  return {
+    unitsQueried: ids.length,
+    ...aggregateCurtailment(day, { from, to }, units, volumes, cashflows, boalf)
+  };
+}
+
+// src/client.ts
+var BASE_URL = "https://data.elexon.co.uk/bmrs/api/v1";
+var DEFAULT_RATE_LIMIT = { requestsPerSecond: 10, burst: 20 };
+var DEFAULT_CACHE_TTL_MS = 5 * 60 * 1e3;
+function unitId(u) {
+  return u.elexonBmUnit || u.nationalGridBmUnit || "";
+}
+var MAX_UNITS_PER_REQUEST = 200;
+function chunk(items, size) {
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+function windowQuery(w) {
+  const q = { from: core.formatDateTime(w.from), to: core.formatDateTime(w.to) };
+  if (w.settlementPeriodFrom !== void 0) {
+    core.assertSettlementPeriod(w.settlementPeriodFrom);
+    q.settlementPeriodFrom = w.settlementPeriodFrom;
+  }
+  if (w.settlementPeriodTo !== void 0) {
+    core.assertSettlementPeriod(w.settlementPeriodTo);
+    q.settlementPeriodTo = w.settlementPeriodTo;
+  }
+  return q;
+}
+function periodQuery(settlementDate, settlementPeriod) {
+  core.assertSettlementPeriod(settlementPeriod);
+  return { settlementDate: core.formatDate(settlementDate), settlementPeriod };
+}
+var ElexonClient = class {
+  http;
+  constructor(opts = {}) {
+    this.http = new core.HttpClient({
+      baseUrl: BASE_URL,
+      rateLimit: DEFAULT_RATE_LIMIT,
+      cacheTtlMs: opts.cache ? DEFAULT_CACHE_TTL_MS : 0,
+      ...opts
+    });
+  }
+  /** Endpoints returning a bare array. */
+  async list(path, query) {
+    const res = await this.http.get(path, query);
+    if (!Array.isArray(res)) throw new core.UkEnergyError(`Unexpected response shape for ${path}`);
+    return res;
+  }
+  /** Endpoints returning `{ data: [...] }`. */
+  async data(path, query) {
+    const res = await this.http.get(path, query);
+    if (!res || !Array.isArray(res.data)) {
+      throw new core.UkEnergyError(`Unexpected response shape for ${path}`);
+    }
+    return res.data;
+  }
+  /** `/datasets/{code}` — raw datasets. The `/stream` variants are used: lighter, no envelope. */
+  datasets = {
+    /**
+     * Any stream dataset (77 codes: BOALF, BOD, FUELINST, PN, MELS, WINDFOR, FREQ, …), with the
+     * query parameters typed from the spec. Values are sent as given (strings in API format,
+     * "YYYY-MM-DDTHH:MMZ" or "YYYY-MM-DD"); the named methods below format and validate dates.
+     */
+    stream: async (dataset, query) => this.list(`datasets/${dataset}/stream`, query),
+    /** Bid-offer acceptance levels (BOALF). Curtailment shows as `soFlag: true` bids. */
+    boalf: async (w) => this.list("datasets/BOALF/stream", { ...windowQuery(w), bmUnit: w.bmUnit }),
+    /** Bid-offer data (BOD): submitted bid and offer prices per pair. */
+    bod: async (w) => this.list("datasets/BOD/stream", { ...windowQuery(w), bmUnit: w.bmUnit }),
+    /** Generation by fuel type at 5-minute resolution (FUELINST). */
+    fuelinst: async (q) => {
+      const query = { fuelType: q.fuelType };
+      if ("publishDateTimeFrom" in q) {
+        query.publishDateTimeFrom = core.formatDateTime(q.publishDateTimeFrom);
+        query.publishDateTimeTo = core.formatDateTime(q.publishDateTimeTo);
+      } else {
+        query.settlementDateFrom = core.formatDate(q.settlementDateFrom);
+        query.settlementDateTo = core.formatDate(q.settlementDateTo);
+        if (q.settlementPeriod) {
+          for (const p of q.settlementPeriod) core.assertSettlementPeriod(p);
+          query.settlementPeriod = q.settlementPeriod;
+        }
+      }
+      return this.list("datasets/FUELINST/stream", query);
+    },
+    /** Physical notifications for one settlement period (`/datasets/PN` takes exactly one). */
+    pn: async (settlementDate, settlementPeriod, filter = {}) => this.data("datasets/PN", {
+      ...periodQuery(settlementDate, settlementPeriod),
+      bmUnit: filter.bmUnit
+    }),
+    /** Physical notifications over a window (`/datasets/PN/stream`). */
+    pnStream: async (w) => this.list("datasets/PN/stream", { ...windowQuery(w), bmUnit: w.bmUnit }),
+    /** Maximum export limits (MELS). */
+    mels: async (w) => this.list("datasets/MELS/stream", { ...windowQuery(w), bmUnit: w.bmUnit }),
+    /** Minimum import limits (MILS). */
+    mils: async (w) => this.list("datasets/MILS/stream", { ...windowQuery(w), bmUnit: w.bmUnit })
+  };
+  /** Reference data. */
+  reference = {
+    /** All BM units (~3,100). Capacities are strings; `fuelType` is null for many non-generators. */
+    bmUnits: async () => this.list("reference/bmunits/all"),
+    /** Fuel type codes used across the API. */
+    fuelTypes: async () => this.list("reference/fueltypes/all"),
+    /** BM units matching a filter, e.g. `{ fuelType: ["WIND"] }` (287 units). */
+    units: async (filter = {}) => {
+      const party = filter.leadParty?.toLowerCase();
+      return (await this.reference.bmUnits()).filter(
+        (u) => (!filter.fuelType || u.fuelType != null && filter.fuelType.includes(u.fuelType)) && (!filter.gspGroupId || u.gspGroupId != null && filter.gspGroupId.includes(u.gspGroupId)) && (!party || (u.leadPartyName ?? "").toLowerCase().includes(party))
+      );
+    }
+  };
+  /** Market-wide balancing views (one settlement period per call) and settlement prices. */
+  balancing = {
+    /** System buy/sell prices for a settlement day, or one period of it (DISEBSP). */
+    systemPrices: async (settlementDate, settlementPeriod) => this.data(
+      `balancing/settlement/system-prices/${periodPath(settlementDate, settlementPeriod)}`
+    ),
+    /** Market index (MID) prices and volumes. */
+    marketIndex: async (w) => this.data("balancing/pricing/market-index", {
+      ...windowQuery(w),
+      dataProviders: w.dataProviders
+    }),
+    /** Every acceptance in one settlement period. */
+    acceptances: async (settlementDate, settlementPeriod, filter = {}) => this.data("balancing/acceptances/all", {
+      ...periodQuery(settlementDate, settlementPeriod),
+      bmUnit: filter.bmUnit
+    }),
+    /** Every bid-offer pair in one settlement period. */
+    bidOffers: async (settlementDate, settlementPeriod, filter = {}) => this.data("balancing/bid-offer/all", {
+      ...periodQuery(settlementDate, settlementPeriod),
+      bmUnit: filter.bmUnit
+    }),
+    /**
+     * Settled acceptance volumes (BOAV) for a settlement day, or one period of it: one row per
+     * acceptance per period, `totalVolumeAccepted` in MWh (negative for bids). Long unit lists
+     * are split across requests.
+     */
+    acceptanceVolumes: async (bidOffer, settlementDate, filter = {}) => this.perUnitChunks(
+      `balancing/settlement/acceptance/volumes/all/${bidOffer}/${periodPath(settlementDate, filter.settlementPeriod)}`,
+      filter.bmUnit
+    ),
+    /**
+     * Indicative bid/offer cashflows (EBOCF) for a settlement day or one period: one row per unit
+     * per period, `totalCashflow` in £ paid to the unit (positive for a wind bid at a negative
+     * price).
+     */
+    cashflows: async (bidOffer, settlementDate, filter = {}) => this.perUnitChunks(
+      `balancing/settlement/indicative/cashflows/all/${bidOffer}/${periodPath(settlementDate, filter.settlementPeriod)}`,
+      filter.bmUnit
+    ),
+    /** PN / QPN / MILS / MELS for every unit in one settlement period. */
+    physical: async (dataset, settlementDate, settlementPeriod, filter = {}) => this.data("balancing/physical/all", {
+      dataset,
+      ...periodQuery(settlementDate, settlementPeriod),
+      bmUnit: filter.bmUnit
+    })
+  };
+  /** Wind curtailment: SO-flagged and energy bid acceptances per unit per period, with £. */
+  curtailment = {
+    /**
+     * Curtailment for a GB settlement day (Europe/London), per unit and per settlement period.
+     * Defaults to every WIND unit; the reference list plus three requests per 200 units.
+     */
+    forDay: async (settlementDate, opts = {}) => curtailmentForDay(this, settlementDate, opts)
+  };
+  /** `{data}` endpoints with an optional unit filter, chunked so URLs stay short. */
+  async perUnitChunks(path, bmUnit) {
+    if (!bmUnit?.length) return this.data(path);
+    const parts = await Promise.all(
+      chunk(bmUnit, MAX_UNITS_PER_REQUEST).map((ids) => this.data(path, { bmUnit: ids }))
+    );
+    return parts.flat();
+  }
+};
+function periodPath(settlementDate, settlementPeriod) {
+  if (settlementPeriod !== void 0) core.assertSettlementPeriod(settlementPeriod);
+  const p = settlementPeriod === void 0 ? "" : `/${settlementPeriod}`;
+  return `${core.formatDate(settlementDate)}${p}`;
+}
+
+exports.BASE_URL = BASE_URL;
+exports.DEFAULT_CACHE_TTL_MS = DEFAULT_CACHE_TTL_MS;
+exports.DEFAULT_RATE_LIMIT = DEFAULT_RATE_LIMIT;
+exports.ElexonClient = ElexonClient;
+exports.MAX_UNITS_PER_REQUEST = MAX_UNITS_PER_REQUEST;
+exports.aggregateCurtailment = aggregateCurtailment;
+exports.curtailmentForDay = curtailmentForDay;
+exports.unitId = unitId;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/curtailment.ts","../src/client.ts"],"names":["formatDate","settlementPeriodsInDay","UkEnergyError","formatDateTime","assertSettlementPeriod","HttpClient"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Wind curtailment from settlement data.\n *\n * A curtailment is a *bid acceptance*: NESO accepts a unit's bid to reduce output below its\n * physical notification. Three Elexon feeds describe one:\n *\n * - BOAV (`balancing.acceptanceVolumes(\"bid\", day)`): the settled volume of each acceptance in\n *   each settlement period, in MWh (negative for bids). This is the quantity curtailed.\n * - EBOCF (`balancing.cashflows(\"bid\", day)`): the £ paid to the unit per period. Wind bids are\n *   priced negative (the unit pays to keep generating, so is *paid* to stop), hence the\n *   cashflow is positive and is what consumers fund through BSUoS.\n * - BOALF (`datasets.boalf`): the acceptance's level profile and flags. `soFlag` marks\n *   actions taken for system reasons (transmission constraints: the classic \"wind farm paid\n *   to switch off because the cable to England is full\"); unflagged acceptances are energy\n *   balancing. `rrFlag`/`storFlag`/`deemedBoFlag` are counted, not excluded.\n *\n * `curtailmentForDay` joins the three by (unit, period) and (acceptance number) and adds the\n * unit's fuel type, GSP group and capacity from the reference list.\n *\n * Contains BMRS data © Elexon Limited copyright and database right 2026.\n */\nimport { type DateInput, formatDate, settlementPeriodsInDay, UkEnergyError } from \"@uk-energy/core\";\nimport { chunk, type ElexonClient, MAX_UNITS_PER_REQUEST, unitId } from \"./client.js\";\nimport type { AcceptanceVolumeRow, BmUnit, BoalfRow, CashflowRow } from \"./types.js\";\n\nexport interface CurtailmentOptions {\n  /** Units to include. Default: every unit whose `fuelType` is in `fuelType`. */\n  bmUnit?: string[];\n  /** Used when `bmUnit` is omitted. Default `[\"WIND\"]`. */\n  fuelType?: string[];\n  /** Restrict to a range of settlement periods (1-based, inclusive). Default: the whole day. */\n  settlementPeriodFrom?: number;\n  settlementPeriodTo?: number;\n}\n\n/** One unit in one settlement period. */\nexport interface CurtailmentPeriod {\n  settlementDate: string;\n  settlementPeriod: number;\n  /** UTC start of the period, from the API. */\n  startTime: string;\n  bmUnit: string;\n  nationalGridBmUnit: string | null;\n  leadPartyName: string | null;\n  fuelType: string | null;\n  gspGroupId: string | null;\n  /** `generationCapacity` from the reference list, MW; null when unknown. */\n  capacityMw: number | null;\n  /** MWh curtailed in the period (positive). */\n  curtailedMwh: number;\n  /** Of which from SO-flagged (system / constraint) acceptances. */\n  soFlaggedMwh: number;\n  /**\n   * £ paid to the unit for the period's bids (EBOCF); null when no cashflow row was published\n   * yet. Cashflow rows for periods with no settled bid volume are not reported anywhere.\n   */\n  cashflowGbp: number | null;\n  /** Distinct acceptances contributing to the period. */\n  acceptances: number;\n  /** Acceptances in the period that BOALF reported with `soFlag: true`. */\n  soFlaggedAcceptances: number;\n}\n\n/** A unit's totals over the day. */\nexport interface CurtailmentUnit {\n  bmUnit: string;\n  nationalGridBmUnit: string | null;\n  leadPartyName: string | null;\n  fuelType: string | null;\n  gspGroupId: string | null;\n  capacityMw: number | null;\n  curtailedMwh: number;\n  soFlaggedMwh: number;\n  cashflowGbp: number;\n  /** Settlement periods with any curtailment. */\n  periods: number;\n  /** Distinct acceptances over the day (one acceptance can span several periods). */\n  acceptances: number;\n}\n\nexport interface CurtailmentReport {\n  settlementDate: string;\n  settlementPeriodFrom: number;\n  settlementPeriodTo: number;\n  /** Units that were queried (whether or not they were curtailed). */\n  unitsQueried: number;\n  /** Rows ordered by settlement period then unit id; only (unit, period) pairs with volume. */\n  periods: CurtailmentPeriod[];\n  /** Per-unit totals, largest `curtailedMwh` first. */\n  units: CurtailmentUnit[];\n  total: {\n    curtailedMwh: number;\n    soFlaggedMwh: number;\n    cashflowGbp: number;\n    /** Units with any curtailment. */\n    units: number;\n    /** Distinct acceptances. */\n    acceptances: number;\n  };\n}\n\nconst DEFAULT_FUEL_TYPES = [\"WIND\"];\n\n/** Code-point order (not locale order) so TS and Python sort \"C__X\" and \"CD\" the same way. */\nfunction compareIds(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0;\n}\n\nfunction num(s: string | null | undefined): number | null {\n  if (s == null || s === \"\") return null;\n  const n = Number(s);\n  return Number.isFinite(n) ? n : null;\n}\n\n/** Pure aggregation over already-fetched rows; exported for tests and for callers with their own data. */\nexport function aggregateCurtailment(\n  settlementDate: string,\n  range: { from: number; to: number },\n  units: readonly BmUnit[],\n  volumes: readonly AcceptanceVolumeRow[],\n  cashflows: readonly CashflowRow[],\n  boalf: readonly BoalfRow[],\n): Omit<CurtailmentReport, \"unitsQueried\"> {\n  const byId = new Map<string, BmUnit>();\n  for (const u of units) {\n    if (u.elexonBmUnit) byId.set(u.elexonBmUnit, u);\n    if (u.nationalGridBmUnit) byId.set(u.nationalGridBmUnit, u);\n  }\n  const soByAcceptance = new Map<number, boolean>();\n  for (const r of boalf) {\n    if (r.acceptanceNumber != null) {\n      soByAcceptance.set(\n        r.acceptanceNumber,\n        (soByAcceptance.get(r.acceptanceNumber) ?? false) || r.soFlag === true,\n      );\n    }\n  }\n  const cashByKey = new Map<string, number>();\n  for (const c of cashflows) {\n    const sp = c.settlementPeriod;\n    if (!c.bmUnit || sp === undefined || sp < range.from || sp > range.to) continue;\n    const key = `${c.bmUnit}|${sp}`;\n    cashByKey.set(key, (cashByKey.get(key) ?? 0) + (c.totalCashflow ?? 0));\n  }\n\n  const periods = new Map<string, CurtailmentPeriod>();\n  const seen = new Map<string, Set<number>>();\n  for (const v of volumes) {\n    const sp = v.settlementPeriod;\n    const acceptance = v.acceptanceId;\n    if (!v.bmUnit || sp === undefined || acceptance === undefined) continue;\n    if (sp < range.from || sp > range.to) continue;\n    const mwh = -(v.totalVolumeAccepted ?? 0);\n    if (!(mwh > 0)) continue;\n    const key = `${v.bmUnit}|${sp}`;\n    let p = periods.get(key);\n    let ids = seen.get(key);\n    if (!p || !ids) {\n      const ref = byId.get(v.bmUnit);\n      p = {\n        settlementDate: v.settlementDate ?? settlementDate,\n        settlementPeriod: sp,\n        startTime: v.startTime ?? \"\",\n        bmUnit: v.bmUnit,\n        nationalGridBmUnit: v.nationalGridBmUnit ?? ref?.nationalGridBmUnit ?? null,\n        leadPartyName: v.leadPartyName ?? ref?.leadPartyName ?? null,\n        fuelType: ref?.fuelType ?? null,\n        gspGroupId: ref?.gspGroupId ?? null,\n        capacityMw: num(ref?.generationCapacity),\n        curtailedMwh: 0,\n        soFlaggedMwh: 0,\n        cashflowGbp: cashByKey.get(key) ?? null,\n        acceptances: 0,\n        soFlaggedAcceptances: 0,\n      };\n      ids = new Set();\n      periods.set(key, p);\n      seen.set(key, ids);\n    }\n    p.curtailedMwh += mwh;\n    const so = soByAcceptance.get(acceptance) === true;\n    if (so) p.soFlaggedMwh += mwh;\n    if (!ids.has(acceptance)) {\n      ids.add(acceptance);\n      p.acceptances += 1;\n      if (so) p.soFlaggedAcceptances += 1;\n    }\n  }\n\n  const rows = [...periods.values()].sort(\n    (a, b) => a.settlementPeriod - b.settlementPeriod || compareIds(a.bmUnit, b.bmUnit),\n  );\n\n  const unitTotals = new Map<string, CurtailmentUnit>();\n  const unitAcceptances = new Map<string, Set<number>>();\n  const allAcceptances = new Set<number>();\n  const total = { curtailedMwh: 0, soFlaggedMwh: 0, cashflowGbp: 0, units: 0, acceptances: 0 };\n  for (const p of rows) {\n    let u = unitTotals.get(p.bmUnit);\n    if (!u) {\n      u = {\n        bmUnit: p.bmUnit,\n        nationalGridBmUnit: p.nationalGridBmUnit,\n        leadPartyName: p.leadPartyName,\n        fuelType: p.fuelType,\n        gspGroupId: p.gspGroupId,\n        capacityMw: p.capacityMw,\n        curtailedMwh: 0,\n        soFlaggedMwh: 0,\n        cashflowGbp: 0,\n        periods: 0,\n        acceptances: 0,\n      };\n      unitTotals.set(p.bmUnit, u);\n    }\n    u.curtailedMwh += p.curtailedMwh;\n    u.soFlaggedMwh += p.soFlaggedMwh;\n    u.cashflowGbp += p.cashflowGbp ?? 0;\n    u.periods += 1;\n    const ids = seen.get(`${p.bmUnit}|${p.settlementPeriod}`) ?? new Set<number>();\n    let acc = unitAcceptances.get(p.bmUnit);\n    if (!acc) {\n      acc = new Set();\n      unitAcceptances.set(p.bmUnit, acc);\n    }\n    for (const id of ids) {\n      acc.add(id);\n      allAcceptances.add(id);\n    }\n    u.acceptances = acc.size;\n    total.curtailedMwh += p.curtailedMwh;\n    total.soFlaggedMwh += p.soFlaggedMwh;\n    total.cashflowGbp += p.cashflowGbp ?? 0;\n  }\n  total.units = unitTotals.size;\n  total.acceptances = allAcceptances.size;\n\n  return {\n    settlementDate,\n    settlementPeriodFrom: range.from,\n    settlementPeriodTo: range.to,\n    periods: rows,\n    units: [...unitTotals.values()].sort((a, b) => b.curtailedMwh - a.curtailedMwh),\n    total,\n  };\n}\n\nexport async function curtailmentForDay(\n  client: ElexonClient,\n  settlementDate: DateInput,\n  opts: CurtailmentOptions = {},\n): Promise<CurtailmentReport> {\n  const day = formatDate(settlementDate);\n  const last = settlementPeriodsInDay(day);\n  const from = opts.settlementPeriodFrom ?? 1;\n  const to = opts.settlementPeriodTo ?? last;\n  if (from < 1 || to > last || from > to) {\n    throw new UkEnergyError(`Settlement periods ${from}-${to} are outside 1-${last} for ${day}`);\n  }\n\n  const units = await client.reference.bmUnits();\n  let ids: string[];\n  if (opts.bmUnit) {\n    ids = opts.bmUnit;\n  } else {\n    const fuel = opts.fuelType ?? DEFAULT_FUEL_TYPES;\n    ids = units\n      .filter((u) => u.fuelType != null && fuel.includes(u.fuelType))\n      .map(unitId)\n      .filter((id) => id !== \"\");\n  }\n  ids = [...new Set(ids)]; // the reference list has duplicates (T_WLNYO-4 twice on 20 Oct 2026)\n  if (ids.length === 0) throw new UkEnergyError(\"No BM units to query\");\n\n  // BOALF is fetched for the whole day, not just from..to: an acceptance's level rows are\n  // keyed by the periods they span, so one that started earlier would otherwise lose its flag.\n  const [volumes, cashflows, boalfParts] = await Promise.all([\n    client.balancing.acceptanceVolumes(\"bid\", day, { bmUnit: ids }),\n    client.balancing.cashflows(\"bid\", day, { bmUnit: ids }),\n    Promise.all(\n      chunk(ids, MAX_UNITS_PER_REQUEST).map((bmUnit) =>\n        client.datasets.boalf({\n          from: day,\n          to: day,\n          settlementPeriodFrom: 1,\n          settlementPeriodTo: last,\n          bmUnit,\n        }),\n      ),\n    ),\n  ]);\n  const boalf = boalfParts.flat();\n\n  return {\n    unitsQueried: ids.length,\n    ...aggregateCurtailment(day, { from, to }, units, volumes, cashflows, boalf),\n  };\n}\n","import {\n  assertSettlementPeriod,\n  type DateInput,\n  formatDate,\n  formatDateTime,\n  HttpClient,\n  type HttpClientOptions,\n  type Query,\n  type RateLimit,\n  UkEnergyError,\n} from \"@uk-energy/core\";\nimport {\n  type CurtailmentOptions,\n  type CurtailmentReport,\n  curtailmentForDay,\n} from \"./curtailment.js\";\nimport type {\n  AcceptanceRow,\n  AcceptanceVolumeRow,\n  BidOffer,\n  BidOfferRow,\n  BmUnit,\n  BoalfRow,\n  BodRow,\n  CashflowRow,\n  DatasetQuery,\n  DatasetRow,\n  FuelinstRow,\n  MarketIndexRow,\n  MelsRow,\n  PhysicalDataset,\n  PhysicalRow,\n  PnRow,\n  StreamDataset,\n  SystemPriceRow,\n} from \"./types.js\";\n\nexport const BASE_URL = \"https://data.elexon.co.uk/bmrs/api/v1\";\n\n/**\n * No limit is published and none was observed: 310 requests at ~120 req/s on 20 Oct 2026 all\n * returned 200 with no rate-limit headers (build-board d02). 10 rps / burst 20 keeps us a\n * polite order of magnitude below that; raise it per client if you need to.\n */\nexport const DEFAULT_RATE_LIMIT: RateLimit = { requestsPerSecond: 10, burst: 20 };\n\n/** Most datasets settle within minutes; a short default TTL avoids hammering on retries. */\nexport const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;\n\nexport type ElexonClientOptions = Partial<Omit<HttpClientOptions, \"baseUrl\">> & {\n  baseUrl?: string;\n};\n\n/**\n * Time window for the dataset endpoints. With `settlementPeriodFrom`/`To` set, the API treats\n * `from`/`to` as settlement *dates* (time ignored) and filters by period instead.\n */\nexport interface SettlementWindow {\n  from: DateInput;\n  to: DateInput;\n  settlementPeriodFrom?: number;\n  settlementPeriodTo?: number;\n}\n\nexport interface UnitFilter {\n  /** Elexon BM unit ids, e.g. \"T_ARCHW-1\". Omit for all units. */\n  bmUnit?: string[];\n}\n\n/** Client-side filter over the BM unit reference list. All given fields must match. */\nexport interface UnitsFilter {\n  /** e.g. [\"WIND\"]. */\n  fuelType?: string[];\n  /** GSP group ids, e.g. [\"_P\", \"_N\"] (north / south Scotland). Most wind units have none. */\n  gspGroupId?: string[];\n  /** Case-insensitive substring of `leadPartyName`. */\n  leadParty?: string;\n}\n\n/** The id to query a unit by: `elexonBmUnit`, or `nationalGridBmUnit` for units without one (48 wind units). */\nexport function unitId(u: BmUnit): string {\n  return u.elexonBmUnit || u.nationalGridBmUnit || \"\";\n}\n\n/** The API accepts the whole wind fleet (287 ids, ~4.9 KB URL); chunk well below that. */\nexport const MAX_UNITS_PER_REQUEST = 200;\n\nexport function chunk<T>(items: readonly T[], size: number): T[][] {\n  const out: T[][] = [];\n  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));\n  return out;\n}\n\nexport type FuelinstQuery = (\n  | { publishDateTimeFrom: DateInput; publishDateTimeTo: DateInput }\n  | { settlementDateFrom: DateInput; settlementDateTo: DateInput; settlementPeriod?: number[] }\n) & { fuelType?: string[] };\n\ninterface Envelope<T> {\n  data: T;\n  metadata?: { datasets?: string[] };\n}\n\nfunction windowQuery(w: SettlementWindow): Query {\n  const q: Query = { from: formatDateTime(w.from), to: formatDateTime(w.to) };\n  if (w.settlementPeriodFrom !== undefined) {\n    assertSettlementPeriod(w.settlementPeriodFrom);\n    q.settlementPeriodFrom = w.settlementPeriodFrom;\n  }\n  if (w.settlementPeriodTo !== undefined) {\n    assertSettlementPeriod(w.settlementPeriodTo);\n    q.settlementPeriodTo = w.settlementPeriodTo;\n  }\n  return q;\n}\n\nfunction periodQuery(settlementDate: DateInput, settlementPeriod: number): Query {\n  assertSettlementPeriod(settlementPeriod);\n  return { settlementDate: formatDate(settlementDate), settlementPeriod };\n}\n\n/**\n * Client for Elexon Insights (BMRS). Methods return the API's own row shapes, typed from its\n * OpenAPI spec and unwrapped from the `{ data }` envelope where there is one.\n *\n *   const ex = new ElexonClient();\n *   const rows = await ex.datasets.boalf({ from: \"2026-10-15T00:00Z\", to: \"2026-10-15T01:00Z\" });\n *   const wind = (await ex.reference.bmUnits()).filter((u) => u.fuelType === \"WIND\");\n *\n * Contains BMRS data © Elexon Limited copyright and database right 2026. Keep the attribution.\n */\nexport class ElexonClient {\n  readonly http: HttpClient;\n\n  constructor(opts: ElexonClientOptions = {}) {\n    this.http = new HttpClient({\n      baseUrl: BASE_URL,\n      rateLimit: DEFAULT_RATE_LIMIT,\n      cacheTtlMs: opts.cache ? DEFAULT_CACHE_TTL_MS : 0,\n      ...opts,\n    });\n  }\n\n  /** Endpoints returning a bare array. */\n  private async list<T>(path: string, query?: Query): Promise<T[]> {\n    const res = await this.http.get<T[]>(path, query);\n    if (!Array.isArray(res)) throw new UkEnergyError(`Unexpected response shape for ${path}`);\n    return res;\n  }\n\n  /** Endpoints returning `{ data: [...] }`. */\n  private async data<T>(path: string, query?: Query): Promise<T[]> {\n    const res = await this.http.get<Envelope<T[]>>(path, query);\n    if (!res || !Array.isArray(res.data)) {\n      throw new UkEnergyError(`Unexpected response shape for ${path}`);\n    }\n    return res.data;\n  }\n\n  /** `/datasets/{code}` — raw datasets. The `/stream` variants are used: lighter, no envelope. */\n  readonly datasets = {\n    /**\n     * Any stream dataset (77 codes: BOALF, BOD, FUELINST, PN, MELS, WINDFOR, FREQ, …), with the\n     * query parameters typed from the spec. Values are sent as given (strings in API format,\n     * \"YYYY-MM-DDTHH:MMZ\" or \"YYYY-MM-DD\"); the named methods below format and validate dates.\n     */\n    stream: async <D extends StreamDataset>(\n      dataset: D,\n      query: DatasetQuery<D>,\n    ): Promise<DatasetRow<D>[]> =>\n      this.list<DatasetRow<D>>(`datasets/${dataset}/stream`, query as unknown as Query),\n\n    /** Bid-offer acceptance levels (BOALF). Curtailment shows as `soFlag: true` bids. */\n    boalf: async (w: SettlementWindow & UnitFilter): Promise<BoalfRow[]> =>\n      this.list(\"datasets/BOALF/stream\", { ...windowQuery(w), bmUnit: w.bmUnit }),\n\n    /** Bid-offer data (BOD): submitted bid and offer prices per pair. */\n    bod: async (w: SettlementWindow & UnitFilter): Promise<BodRow[]> =>\n      this.list(\"datasets/BOD/stream\", { ...windowQuery(w), bmUnit: w.bmUnit }),\n\n    /** Generation by fuel type at 5-minute resolution (FUELINST). */\n    fuelinst: async (q: FuelinstQuery): Promise<FuelinstRow[]> => {\n      const query: Query = { fuelType: q.fuelType };\n      if (\"publishDateTimeFrom\" in q) {\n        query.publishDateTimeFrom = formatDateTime(q.publishDateTimeFrom);\n        query.publishDateTimeTo = formatDateTime(q.publishDateTimeTo);\n      } else {\n        query.settlementDateFrom = formatDate(q.settlementDateFrom);\n        query.settlementDateTo = formatDate(q.settlementDateTo);\n        if (q.settlementPeriod) {\n          for (const p of q.settlementPeriod) assertSettlementPeriod(p);\n          query.settlementPeriod = q.settlementPeriod;\n        }\n      }\n      return this.list(\"datasets/FUELINST/stream\", query);\n    },\n\n    /** Physical notifications for one settlement period (`/datasets/PN` takes exactly one). */\n    pn: async (\n      settlementDate: DateInput,\n      settlementPeriod: number,\n      filter: UnitFilter = {},\n    ): Promise<PnRow[]> =>\n      this.data(\"datasets/PN\", {\n        ...periodQuery(settlementDate, settlementPeriod),\n        bmUnit: filter.bmUnit,\n      }),\n\n    /** Physical notifications over a window (`/datasets/PN/stream`). */\n    pnStream: async (w: SettlementWindow & UnitFilter): Promise<PnRow[]> =>\n      this.list(\"datasets/PN/stream\", { ...windowQuery(w), bmUnit: w.bmUnit }),\n\n    /** Maximum export limits (MELS). */\n    mels: async (w: SettlementWindow & UnitFilter): Promise<MelsRow[]> =>\n      this.list(\"datasets/MELS/stream\", { ...windowQuery(w), bmUnit: w.bmUnit }),\n\n    /** Minimum import limits (MILS). */\n    mils: async (w: SettlementWindow & UnitFilter): Promise<MelsRow[]> =>\n      this.list(\"datasets/MILS/stream\", { ...windowQuery(w), bmUnit: w.bmUnit }),\n  };\n\n  /** Reference data. */\n  readonly reference = {\n    /** All BM units (~3,100). Capacities are strings; `fuelType` is null for many non-generators. */\n    bmUnits: async (): Promise<BmUnit[]> => this.list(\"reference/bmunits/all\"),\n    /** Fuel type codes used across the API. */\n    fuelTypes: async (): Promise<string[]> => this.list(\"reference/fueltypes/all\"),\n    /** BM units matching a filter, e.g. `{ fuelType: [\"WIND\"] }` (287 units). */\n    units: async (filter: UnitsFilter = {}): Promise<BmUnit[]> => {\n      const party = filter.leadParty?.toLowerCase();\n      return (await this.reference.bmUnits()).filter(\n        (u) =>\n          (!filter.fuelType || (u.fuelType != null && filter.fuelType.includes(u.fuelType))) &&\n          (!filter.gspGroupId ||\n            (u.gspGroupId != null && filter.gspGroupId.includes(u.gspGroupId))) &&\n          (!party || (u.leadPartyName ?? \"\").toLowerCase().includes(party)),\n      );\n    },\n  };\n\n  /** Market-wide balancing views (one settlement period per call) and settlement prices. */\n  readonly balancing = {\n    /** System buy/sell prices for a settlement day, or one period of it (DISEBSP). */\n    systemPrices: async (\n      settlementDate: DateInput,\n      settlementPeriod?: number,\n    ): Promise<SystemPriceRow[]> =>\n      this.data(\n        `balancing/settlement/system-prices/${periodPath(settlementDate, settlementPeriod)}`,\n      ),\n\n    /** Market index (MID) prices and volumes. */\n    marketIndex: async (\n      w: SettlementWindow & { dataProviders?: string[] },\n    ): Promise<MarketIndexRow[]> =>\n      this.data(\"balancing/pricing/market-index\", {\n        ...windowQuery(w),\n        dataProviders: w.dataProviders,\n      }),\n\n    /** Every acceptance in one settlement period. */\n    acceptances: async (\n      settlementDate: DateInput,\n      settlementPeriod: number,\n      filter: UnitFilter = {},\n    ): Promise<AcceptanceRow[]> =>\n      this.data(\"balancing/acceptances/all\", {\n        ...periodQuery(settlementDate, settlementPeriod),\n        bmUnit: filter.bmUnit,\n      }),\n\n    /** Every bid-offer pair in one settlement period. */\n    bidOffers: async (\n      settlementDate: DateInput,\n      settlementPeriod: number,\n      filter: UnitFilter = {},\n    ): Promise<BidOfferRow[]> =>\n      this.data(\"balancing/bid-offer/all\", {\n        ...periodQuery(settlementDate, settlementPeriod),\n        bmUnit: filter.bmUnit,\n      }),\n\n    /**\n     * Settled acceptance volumes (BOAV) for a settlement day, or one period of it: one row per\n     * acceptance per period, `totalVolumeAccepted` in MWh (negative for bids). Long unit lists\n     * are split across requests.\n     */\n    acceptanceVolumes: async (\n      bidOffer: BidOffer,\n      settlementDate: DateInput,\n      filter: UnitFilter & { settlementPeriod?: number } = {},\n    ): Promise<AcceptanceVolumeRow[]> =>\n      this.perUnitChunks(\n        `balancing/settlement/acceptance/volumes/all/${bidOffer}/${periodPath(settlementDate, filter.settlementPeriod)}`,\n        filter.bmUnit,\n      ),\n    /**\n     * Indicative bid/offer cashflows (EBOCF) for a settlement day or one period: one row per unit\n     * per period, `totalCashflow` in £ paid to the unit (positive for a wind bid at a negative\n     * price).\n     */\n    cashflows: async (\n      bidOffer: BidOffer,\n      settlementDate: DateInput,\n      filter: UnitFilter & { settlementPeriod?: number } = {},\n    ): Promise<CashflowRow[]> =>\n      this.perUnitChunks(\n        `balancing/settlement/indicative/cashflows/all/${bidOffer}/${periodPath(settlementDate, filter.settlementPeriod)}`,\n        filter.bmUnit,\n      ),\n    /** PN / QPN / MILS / MELS for every unit in one settlement period. */\n    physical: async (\n      dataset: PhysicalDataset,\n      settlementDate: DateInput,\n      settlementPeriod: number,\n      filter: UnitFilter = {},\n    ): Promise<PhysicalRow[]> =>\n      this.data(\"balancing/physical/all\", {\n        dataset,\n        ...periodQuery(settlementDate, settlementPeriod),\n        bmUnit: filter.bmUnit,\n      }),\n  };\n\n  /** Wind curtailment: SO-flagged and energy bid acceptances per unit per period, with £. */\n  readonly curtailment = {\n    /**\n     * Curtailment for a GB settlement day (Europe/London), per unit and per settlement period.\n     * Defaults to every WIND unit; the reference list plus three requests per 200 units.\n     */\n    forDay: async (\n      settlementDate: DateInput,\n      opts: CurtailmentOptions = {},\n    ): Promise<CurtailmentReport> => curtailmentForDay(this, settlementDate, opts),\n  };\n\n  /** `{data}` endpoints with an optional unit filter, chunked so URLs stay short. */\n  private async perUnitChunks<T>(path: string, bmUnit?: string[]): Promise<T[]> {\n    if (!bmUnit?.length) return this.data<T>(path);\n    const parts = await Promise.all(\n      chunk(bmUnit, MAX_UNITS_PER_REQUEST).map((ids) => this.data<T>(path, { bmUnit: ids })),\n    );\n    return parts.flat();\n  }\n}\n\nfunction periodPath(settlementDate: DateInput, settlementPeriod?: number): string {\n  if (settlementPeriod !== undefined) assertSettlementPeriod(settlementPeriod);\n  const p = settlementPeriod === undefined ? \"\" : `/${settlementPeriod}`;\n  return `${formatDate(settlementDate)}${p}`;\n}\n"]}