@vepler/sdk 2.39.0 → 2.45.0

package/src/sdk/energy.ts

@@ -0,0 +1,299 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { energyFindNearestSubstations } from "../funcs/energyFindNearestSubstations.js";
+import { energyFindSupplyAreaByPoint } from "../funcs/energyFindSupplyAreaByPoint.js";
+import { energyGetByProperty } from "../funcs/energyGetByProperty.js";
+import { energyGetCapacity } from "../funcs/energyGetCapacity.js";
+import { energyGetConnectionQueueBySubstation } from "../funcs/energyGetConnectionQueueBySubstation.js";
+import { energyGetConnectionQueueEntry } from "../funcs/energyGetConnectionQueueEntry.js";
+import { energyGetDFES } from "../funcs/energyGetDFES.js";
+import { energyGetSubstation } from "../funcs/energyGetSubstation.js";
+import { energySearchConnectionQueue } from "../funcs/energySearchConnectionQueue.js";
+import { energySearchECR } from "../funcs/energySearchECR.js";
+import { energySearchSubstations } from "../funcs/energySearchSubstations.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as operations from "./models/operations/index.js";
+import { unwrapAsync } from "./types/fp.js";
+
+export class Energy extends ClientSDK {
+  /**
+   * Find nearest substations
+   *
+   * @remarks
+   * Find electricity substations within a given radius of a geographic point, ordered by distance from closest to furthest.
+   *
+   * Use this endpoint to identify which substations serve a particular location and assess the available capacity nearby. You can optionally filter by substation type or country.
+   *
+   * **Parameters:**
+   * - `lat`, `lon` — coordinates of the search centre point (WGS84)
+   * - `radius` — search radius in kilometres (default: 5 km, max: 50 km)
+   * - `limit` — maximum results (default: 10, max: 100)
+   * - `substationType` — optional filter (primary, grid, distribution, etc.)
+   * - `country` — optional ISO 3166-1 alpha-2 country code filter
+   */
+  async findNearestSubstations(
+    request?: operations.FindNearestSubstationsRequest | undefined,
+    options?: RequestOptions,
+  ): Promise<operations.FindNearestSubstationsResponseBody> {
+    return unwrapAsync(energyFindNearestSubstations(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Find supply areas by point
+   *
+   * @remarks
+   * Find all supply area boundaries that contain a given geographic point.
+   *
+   * A supply area defines the geographic region served by a specific substation. Multiple boundaries may overlap at a single point because the network is hierarchical — a location can fall within a distribution area, a primary area, a bulk supply point area, and a grid supply point area simultaneously.
+   *
+   * Results are returned from most specific (distribution) to broadest (grid supply point).
+   */
+  async findSupplyAreaByPoint(
+    request?: operations.FindSupplyAreaByPointRequest | undefined,
+    options?: RequestOptions,
+  ): Promise<operations.FindSupplyAreaByPointResponseBody> {
+    return unwrapAsync(energyFindSupplyAreaByPoint(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get energy infrastructure for a property
+   *
+   * @remarks
+   * Get the complete energy infrastructure context for a specific property location.
+   *
+   * This endpoint resolves a property's coordinates to its serving electricity substation and supply area, then enriches the response with:
+   *
+   * - **Supply area** — the geographic boundary served by the substation
+   * - **Substation** — current capacity, demand, and available headroom
+   * - **Capacity history** — quarterly snapshots showing how headroom has changed
+   * - **Embedded connections** — registered generation and storage sites nearby
+   * - **Future forecasts** — projected demand and generation growth
+   * - **Connection queue** — grid connection queue entries at the serving substation
+   *
+   * The `lat` and `lon` query parameters specify the property's coordinates in WGS84.
+   *
+   * Use the `include` parameter to select which layers to return. Defaults to all layers (`supplyArea,substation,capacity,ecr,dfes,connections`). Omitting layers you don't need reduces response size and improves performance.
+   */
+  async getByProperty(
+    request: operations.GetEnergyForPropertyRequest,
+    options?: RequestOptions,
+  ): Promise<operations.GetEnergyForPropertyEnergyForProperty> {
+    return unwrapAsync(energyGetByProperty(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get capacity time-series
+   *
+   * @remarks
+   * Get historical capacity snapshots for a substation, ordered chronologically.
+   *
+   * Each snapshot records the substation's demand, firm capacity, and available headroom at a point in time (typically quarterly). Use this data to track how available capacity has changed and identify trends in network utilisation.
+   *
+   * **Headroom** is the spare capacity available for new connections:
+   * - **Demand headroom** — capacity available for new electricity consumers (e.g. data centres, EV charging)
+   * - **Generation headroom** — capacity available for new generators (e.g. solar farms, wind turbines)
+   *
+   * Optionally filter by date range using `from` and `to` parameters.
+   */
+  async getCapacity(
+    request: operations.GetSubstationCapacityRequest,
+    options?: RequestOptions,
+  ): Promise<operations.GetSubstationCapacityResponseBody> {
+    return unwrapAsync(energyGetCapacity(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get connection queue entries for a substation
+   *
+   * @remarks
+   * Get all grid connection queue entries associated with a specific substation.
+   *
+   * Returns projects from both the TEC Register (transmission) and Embedded Register (distribution) that connect at this substation. Ordered by capacity (largest first).
+   */
+  async getConnectionQueueBySubstation(
+    request: operations.GetConnectionQueueBySubstationRequest,
+    options?: RequestOptions,
+  ): Promise<operations.GetConnectionQueueBySubstationResponseBody> {
+    return unwrapAsync(energyGetConnectionQueueBySubstation(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get connection queue entry by project ID
+   *
+   * @remarks
+   * Retrieve a single connection queue entry by its project identifier.
+   *
+   * Returns the full entry including all technology components from the junction table. Multi-technology projects (e.g. solar + battery co-location) will include each technology as a separate item in the `technologies` array.
+   *
+   * Optionally pass `sourceDataset` as a query parameter to disambiguate entries that appear in both TEC and Embedded registers.
+   */
+  async getConnectionQueueEntry(
+    request: operations.GetConnectionQueueEntryRequest,
+    options?: RequestOptions,
+  ): Promise<operations.GetConnectionQueueEntryConnectionQueueEntry> {
+    return unwrapAsync(energyGetConnectionQueueEntry(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get future energy scenario forecasts
+   *
+   * @remarks
+   * Get energy scenario forecasts for a substation.
+   *
+   * Forecasts project how electricity demand, generation, and storage capacity will evolve at each substation over time. Each country's energy planning framework defines its own scenarios — for example, GB uses Distribution Future Energy Scenarios (DFES) with pathways such as:
+   *
+   * - **Leading the Way** — fastest decarbonisation, highest electrification
+   * - **Consumer Transformation** — consumer-led change with high energy efficiency
+   * - **System Transformation** — hydrogen-heavy, centralised generation
+   * - **Falling Short** — slowest progress towards net zero
+   * - **Best View** — the operator's central planning estimate
+   *
+   * Other countries define their own scenario sets. Optionally filter by scenario and/or year range.
+   */
+  async getDFES(
+    request: operations.GetSubstationDFESRequest,
+    options?: RequestOptions,
+  ): Promise<operations.GetSubstationDFESResponseBody> {
+    return unwrapAsync(energyGetDFES(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get substation by code
+   *
+   * @remarks
+   * Retrieve a single electricity substation by its unique code.
+   *
+   * Substation codes are prefixed with the operator identifier — for example `ukpn:PRI-1234` for a UK Power Networks primary substation, or `npg:12345` for a Northern Powergrid substation.
+   *
+   * The response includes the substation's current capacity ratings, peak demand, and available headroom (spare capacity for new connections).
+   */
+  async getSubstation(
+    request: operations.GetSubstationByCodeRequest,
+    options?: RequestOptions,
+  ): Promise<operations.GetSubstationByCodeSubstation> {
+    return unwrapAsync(energyGetSubstation(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Search connection queue
+   *
+   * @remarks
+   * Search the national grid connection queue for projects awaiting or holding connection agreements to the electricity network.
+   *
+   * Covers both transmission-level connections (TEC Register) and distribution-level connections (Embedded Register) from NESO.
+   *
+   * **Available filters:**
+   * - `country` — filter by ISO 3166-1 alpha-2 country code
+   * - `operator` — filter by network operator code
+   * - `technologyType` — filter by canonical technology (e.g. `solar`, `battery`, `wind_onshore`)
+   * - `technologyCategory` — filter by category (generation, storage, thermal, demand)
+   * - `connectionStatus` — filter by lifecycle stage (e.g. `offer_accepted`, `connected`)
+   * - `networkLevel` — filter by voltage level (transmission, distribution)
+   * - `sourceDataset` — filter by source register (neso_tec, neso_embedded)
+   * - `substationCode` — filter by resolved substation
+   * - `minCapacityMw` / `maxCapacityMw` — filter by capacity range
+   *
+   * Results are ordered by capacity (largest first) and paginated using `limit` and `offset`.
+   */
+  async searchConnectionQueue(
+    request?:
+      | operations.SearchConnectionQueueConnectionQueueSearchInput
+      | undefined,
+    options?: RequestOptions,
+  ): Promise<operations.SearchConnectionQueueResponseBody> {
+    return unwrapAsync(energySearchConnectionQueue(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Search embedded capacity register
+   *
+   * @remarks
+   * Search the Embedded Capacity Register (ECR) for generation and storage connections to the electricity distribution network.
+   *
+   * The ECR is a public record of all distributed generation (solar, wind, gas, biomass) and storage (battery) sites connected to the distribution network. Each entry includes the installed capacity, technology type, connection status, and location.
+   *
+   * **Available filters:**
+   * - `operator` — limit to a specific network operator
+   * - `operatingRegion` — limit to a specific operating region
+   * - `country` — filter by ISO 3166-1 alpha-2 country code
+   * - `technologyType` — filter by technology (e.g. `solar`, `wind`, `battery`)
+   * - `connectionStatus` — filter by lifecycle stage (e.g. `connected`, `accepted`)
+   *
+   * Results are ordered by installed capacity (largest first) and paginated using `limit` and `offset`.
+   */
+  async searchECR(
+    request?: operations.SearchECRRequest | undefined,
+    options?: RequestOptions,
+  ): Promise<operations.SearchECRResponseBody> {
+    return unwrapAsync(energySearchECR(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Search substations
+   *
+   * @remarks
+   * Search for substations across all network operators with optional filters.
+   *
+   * **Available filters:**
+   * - `operator` — limit to a specific network operator (e.g. `ukpn`, `npg`, `nged`)
+   * - `operatingRegion` — filter by operating region name
+   * - `country` — filter by ISO 3166-1 alpha-2 country code (e.g. `GB`, `IE`, `FR`)
+   * - `substationType` — filter by hierarchy level (primary, grid, distribution, etc.)
+   * - `minDemandHeadroomMw` / `maxDemandHeadroomMw` — filter by available demand headroom range
+   * - `minGenerationHeadroomMw` — filter by minimum generation headroom
+   *
+   * All filters are combined with AND logic. Results are paginated using `limit` and `offset`.
+   */
+  async searchSubstations(
+    request?: operations.SearchSubstationsSearchSubstationsInput | undefined,
+    options?: RequestOptions,
+  ): Promise<operations.SearchSubstationsResponseBody> {
+    return unwrapAsync(energySearchSubstations(
+      this,
+      request,
+      options,
+    ));
+  }
+}