@uk-energy/elexon 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# @uk-energy/elexon
+
+## 0.3.0
+
+- `curtailment.wastedWind(date, opts)`: Octopus's "Wasted Wind" definition from the settlement
+  bid/offer stacks — SO-flagged wind bids (MWh, £ at bid price) plus the curtailed volume
+  re-bought from the cheapest non-SO offers. Matches wastedwind.energy to the penny on the
+  recorded periods; `aggregateWastedWind()` exported.
+- `balancing.settlementStack(bidOffer, date, sp)` (ISPSTACK) and the `SettlementStackRow` type.
+- Fixtures for 30 Sep 2026 SP20–21; 5 new tests.
+
+## 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,151 @@
-# 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
+```
+
+### Octopus's "Wasted Wind" figure
+
+```ts
+const day = await ex.curtailment.wastedWind("2026-09-30");
+day.total; // { curtailedMwh: 124226, curtailmentCostGbp: 4040737, turnUpMwh, turnUpCostGbp: 25986249, totalCostGbp: 30026986 }
+day.periods[19]; // SP20 (09:30 BST): 2,415.70 MWh, £72,256.84 to switch off, £506,067.61 to replace
+```
+
+[wastedwind.energy](https://wastedwind.energy)'s definition, reproduced from the settlement bid
+and offer stacks (`balancing.settlementStack`): SO-flagged wind bids priced at their bid price,
+plus the curtailed volume re-bought from the cheapest non-SO offers in the same period. Two
+requests per settlement period. It is a definition, not settlement truth — see
+[`examples/`](../../examples) for a month reproduced to 0.2% and a comparison with the settled
+view below.
+
+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)`, `settlementStack(bidOffer, date, sp)` |
+| `curtailment` | `forDay(date, { bmUnit?, fuelType?, settlementPeriodFrom?, settlementPeriodTo? })`, `wastedWind(date, { settlementPeriodFrom?, settlementPeriodTo?, fuelType?, concurrency? })` |
+
+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).