@vepler/sdk 2.42.0 → 2.46.0

package/src/funcs/energySearchSubstations.ts

@@ -0,0 +1,208 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { SDKCore } from "../core.js";
+import { encodeJSON } from "../lib/encodings.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../sdk/models/errors/httpclienterrors.js";
+import * as errors from "../sdk/models/errors/index.js";
+import { ResponseValidationError } from "../sdk/models/errors/responsevalidationerror.js";
+import { SDKBaseError } from "../sdk/models/errors/sdkbaseerror.js";
+import { SDKValidationError } from "../sdk/models/errors/sdkvalidationerror.js";
+import * as operations from "../sdk/models/operations/index.js";
+import { APICall, APIPromise } from "../sdk/types/async.js";
+import { Result } from "../sdk/types/fp.js";
+
+/**
+ * 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`.
+ */
+export function energySearchSubstations(
+  client: SDKCore,
+  request?: operations.SearchSubstationsSearchSubstationsInput | undefined,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    operations.SearchSubstationsResponseBody,
+    | errors.SearchSubstationsResponseBody
+    | errors.SearchSubstationsEnergyResponseBody
+    | errors.SearchSubstationsEnergyResponseResponseBody
+    | errors.SearchSubstationsEnergyResponse500ResponseBody
+    | errors.SearchSubstationsEnergyResponse503ResponseBody
+    | SDKBaseError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: SDKCore,
+  request?: operations.SearchSubstationsSearchSubstationsInput | undefined,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      operations.SearchSubstationsResponseBody,
+      | errors.SearchSubstationsResponseBody
+      | errors.SearchSubstationsEnergyResponseBody
+      | errors.SearchSubstationsEnergyResponseResponseBody
+      | errors.SearchSubstationsEnergyResponse500ResponseBody
+      | errors.SearchSubstationsEnergyResponse503ResponseBody
+      | SDKBaseError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) =>
+      operations.SearchSubstationsSearchSubstationsInput$outboundSchema
+        .optional().parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = payload === undefined
+    ? null
+    : encodeJSON("body", payload, { explode: true });
+
+  const path = pathToFunc("/v1/energy/substations/query")();
+
+  const headers = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+
+  const secConfig = await extractSecurity(client._options.apiKeyAuth);
+  const securityInput = secConfig == null ? {} : { apiKeyAuth: secConfig };
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "searchSubstations",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.apiKeyAuth,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    errorCodes: ["401", "403", "429", "4XX", "500", "503", "5XX"],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    operations.SearchSubstationsResponseBody,
+    | errors.SearchSubstationsResponseBody
+    | errors.SearchSubstationsEnergyResponseBody
+    | errors.SearchSubstationsEnergyResponseResponseBody
+    | errors.SearchSubstationsEnergyResponse500ResponseBody
+    | errors.SearchSubstationsEnergyResponse503ResponseBody
+    | SDKBaseError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, operations.SearchSubstationsResponseBody$inboundSchema),
+    M.jsonErr(401, errors.SearchSubstationsResponseBody$inboundSchema),
+    M.jsonErr(403, errors.SearchSubstationsEnergyResponseBody$inboundSchema),
+    M.jsonErr(
+      429,
+      errors.SearchSubstationsEnergyResponseResponseBody$inboundSchema,
+    ),
+    M.jsonErr(
+      500,
+      errors.SearchSubstationsEnergyResponse500ResponseBody$inboundSchema,
+    ),
+    M.jsonErr(
+      503,
+      errors.SearchSubstationsEnergyResponse503ResponseBody$inboundSchema,
+    ),
+    M.fail("4XX"),
+    M.fail("5XX"),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

package/src/funcs/propertySearchProperties.ts

@@ -29,7 +29,10 @@ import { Result } from "../sdk/types/fp.js";
  * Query properties with advanced filters
  *
  * @remarks
- * Search for properties using location, price, and other criteria
+ * Search for properties using location, price, and other criteria. By default, only residential properties are returned. To include commercial properties, add a `propertyCategory` condition to your query:
+ *
+ * - Commercial only: `{ "field": "propertyCategory", "comparator": "eq", "value": "commercial" }`
+ * - All categories: omit the default by adding `{ "field": "propertyCategory", "comparator": "exists" }`
  */
 export function propertySearchProperties(
   client: SDKCore,

package/src/funcs/searchSearchSuggest.ts

@@ -94,6 +94,7 @@ async function $do(
   const path = pathToFunc("/v1/search/suggest")();
 
   const query = encodeFormQuery({
+    "classification": payload.classification,
     "limit": payload.limit,
     "offset": payload.offset,
     "q": payload.q,

package/src/lib/config.ts

@@ -60,8 +60,8 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 
 export const SDK_METADATA = {
   language: "typescript",
-  openapiDocVersion: "2.42.0",
+  openapiDocVersion: "2.46.0",
   sdkVersion: "0.10.0",
-  genVersion: "2.844.2",
-  userAgent: "speakeasy-sdk/typescript 0.10.0 2.844.2 2.42.0 @vepler/sdk",
+  genVersion: "2.866.0",
+  userAgent: "speakeasy-sdk/typescript 0.10.0 2.866.0 2.46.0 @vepler/sdk",
 } as const;

package/src/lib/matchers.ts

@@ -248,8 +248,9 @@ export function match<T, E>(
         raw = body;
         break;
       default:
-        encoding satisfies never;
-        throw new Error(`Unsupported response type: ${encoding}`);
+        throw new Error(
+          `Unsupported response type: ${encoding satisfies never}`,
+        );
     }
 
     if (matcher.enc === "fail") {

package/src/lib/security.ts

@@ -197,8 +197,7 @@ export function resolveSecurity(
         applyBearer(state, spec);
         break;
       default:
-        spec satisfies never;
-        throw SecurityError.unrecognizedType(type);
+        throw SecurityError.unrecognizedType((spec satisfies never, type));
     }
   });
 

package/src/sdk/address.ts

@@ -124,9 +124,11 @@ export class Address extends ClientSDK {
    *
    * @remarks
    * AI-powered address resolution that converts address strings to UPRNs (Unique Property Reference Numbers). Uses advanced LLM parsing to handle complex multi-unit addresses, ranges, incomplete addresses, and various formatting styles. Combines Elasticsearch search with intelligent postcode-based fallback for maximum accuracy.
+   *
+   * By default, only residential addresses are matched. Pass `classification: 'commercial'` to match commercial premises, or `classification: 'all'` to match all address types.
    */
   async resolveAddress(
-    request?: operations.ResolveAddressRequestBody | undefined,
+    request?: shared.AddressResolveRequest | undefined,
     options?: RequestOptions,
   ): Promise<operations.ResolveAddressResponseBody> {
     return unwrapAsync(addressResolveAddress(

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,
+    ));
+  }
+}