@tomtom-org/maps-sdk 0.58.1 → 0.60.0

package/core/dist/index.d.ts

@@ -589,7 +589,7 @@ export declare const currentTypes: readonly ["AC1", "AC3", "DC"];
  */
 export type CurrentType = (typeof currentTypes)[number];
 /**
- * The charging speed classification of this charging connection.
+ * Charging speed class, derived from a rated power.
  *
  * @remarks
  * - `slow`: Typically up to 12 kW (Level 1 AC charging)
@@ -640,13 +640,7 @@ export type Connector = {
    */
   ratedPowerKW: number;
   /**
-   * The charging speed classification of this charging connection.
-   *
-   * @remarks
-   * - `slow`: Typically up to 12 kW (Level 1 AC charging)
-   * - `regular`: Typically between 12 kW and 50 kW (Level 2 AC charging)
-   * - `fast`: Typically between 50 kW and 150 kW (DC fast charging)
-   * - `ultra-fast`: Typically above 150 kW (High-power DC fast charging)
+   * The {@link ChargingSpeed} class of `ratedPowerKW`.
    */
   chargingSpeed: ChargingSpeed;
   /**
@@ -808,9 +802,9 @@ export type ChargingPoint = {
   /**
    * Unique identifier for this charging point (EVSE ID).
    *
-   * Often follows international standards like ISO 15118.
+   * Often follows international standards like ISO 15118. Absent when the operator publishes none.
    */
-  evseId: string;
+  evseId?: string;
   /**
    * Capabilities and features of this charging point.
    *
@@ -836,6 +830,12 @@ export type ChargingPoint = {
    */
   connectors?: Connector[];
 };
+/**
+ * A charging point as the search services describe it: everything but its real-time status.
+ *
+ * @group Place
+ */
+export type StaticChargingPoint = Omit<ChargingPoint, 'status'>;
 /**
  * Electric vehicle charging station.
  *
@@ -853,9 +853,10 @@ export type ChargingPoint = {
  * };
  * ```
  *
+ * @typeParam Point - {@link ChargingPoint} with real-time status, {@link StaticChargingPoint} without.
  * @group Place
  */
-export type ChargingStation = {
+export type ChargingStation<Point = ChargingPoint> = {
   /**
    * Unique identifier for the charging station.
    */
@@ -865,7 +866,7 @@ export type ChargingStation = {
    *
    * Each charging point can serve one vehicle at a time.
    */
-  chargingPoints: ChargingPoint[];
+  chargingPoints: Point[];
 };
 //#endregion
 //#region src/types/place/poi/openingHours.d.ts
@@ -1756,6 +1757,12 @@ type ChargingPark = {
    * This field shows total counts regardless of current operational status.
    */
   connectors: ConnectorCount[];
+  /**
+   * The charging stations and their charging points (EVSEs), without real-time status.
+   *
+   * Present on places returned by the search services.
+   */
+  chargingStations?: ChargingStation<StaticChargingPoint>[];
 };
 /**
  * Charging park with optional real-time availability data.
@@ -1780,17 +1787,12 @@ type ChargingPark = {
  */
 type ChargingParkWithAvailability = ChargingPark & {
   /**
-   * Real-time availability information for this charging park.
-   *
-   * Present only if availability data has been fetched from the
-   * EV Charging Station Availability service. Contains current
-   * operational status for all charging points and connectors.
+   * Real-time availability information for this charging park: the status of every charging point,
+   * and counts per connector type and power.
    *
    * @remarks
-   * To get availability data:
-   * 1. Extract the chargingAvailability ID from place.dataSources
-   * 2. Call the EV Charging Stations Availability service
-   * 3. Merge the result into this property
+   * `getPlaceWithEVAvailability` and `getPlacesWithEVAvailability` from `@tomtom-org/maps-sdk/services`
+   * fetch it with the place's `dataSources.chargingAvailability.id` and merge it in.
    */
   availability: ChargingStationsAvailability;
 };
@@ -1854,7 +1856,7 @@ type PlaceDataSources = {
   /**
    * Data source for EV charging station availability.
    *
-   * Present only for places that are EV charging stations (type === POI).
+   * Present only for EV charging stations: search results and route charging stops.
    * Use the ID to fetch real-time availability from the
    * EV Charging Stations Availability service.
    */
@@ -1862,8 +1864,9 @@ type PlaceDataSources = {
   /**
    * Data source for geometric shape information.
    *
-   * Present for places with geometric representations (type === Geography or POI).
-   * Use the ID to fetch boundary polygons from the Geometry Data service.
+   * Present on search results for places with geometric representations (type === Geography or POI).
+   * Use the ID to fetch boundary polygons from the Geometry Data service. A reverse geocoded place
+   * has none; search it by name, with its `geographyType`, to get one.
    *
    * @remarks
    * Useful for:
@@ -1897,8 +1900,7 @@ type ChargingAvailabilityDataSource = {
   /**
    * Charging availability ID for the EV Charging Stations Availability service.
    *
-   * Pass this value as the chargingAvailability parameter to fetch
-   * real-time status of charging points and connectors.
+   * Pass this value as the `id` parameter to fetch real-time status of charging points and connectors.
    */
   id?: string;
 };
@@ -2218,13 +2220,7 @@ export type ChargingConnectionInfo = {
    */
   chargingPowerInkW?: number;
   /**
-   * The charging speed classification of this charging connection.
-   *
-   * @remarks
-   * - `slow`: Typically up to 12 kW (Level 1 AC charging)
-   * - `regular`: Typically between 12 kW and 50 kW (Level 2 AC charging)
-   * - `fast`: Typically between 50 kW and 150 kW (DC fast charging)
-   * - `ultra-fast`: Typically above 150 kW (High-power DC fast charging)
+   * The {@link ChargingSpeed} class of `chargingPowerInkW`.
    */
   chargingSpeed?: ChargingSpeed;
 };
@@ -2326,23 +2322,9 @@ export type ChargingStopProps = CommonPlaceProps & {
   /**
    * The unique UUID identifier of this charging park.
    *
-   * This universally unique identifier can be used to:
-   * - Check real-time availability of charging stations
-   * - Query detailed charging park information
-   * - Track charging park status and updates
-   * - Cross-reference with TomTom EV Charging Stations API
-   *
    * @remarks
-   * Use this UUID with the EV Charging Stations Availability API to get
-   * real-time connector availability before arriving at the charging stop.
-   *
-   * @example
-   * ```typescript
-   * // Use UUID to check availability
-   * const availability = await evChargingAvailability.get({
-   *   chargingAvailability: chargingStop.chargingParkUuid
-   * });
-   * ```
+   * The same ID as `dataSources.chargingAvailability.id`, so `getPlaceWithEVAvailability(chargingStop)`
+   * adds the park's charging stations and their real-time status, as it does for a search result.
    */
   chargingParkUuid: string;
   /**
@@ -2408,13 +2390,7 @@ export type ChargingStopProps = CommonPlaceProps & {
    */
   chargingParkPowerInkW?: number;
   /**
-   * The best charging speed classification of this charging park amongst its connectors.
-   *
-   * @remarks
-   * - `slow`: Typically up to 12 kW (Level 1 AC charging)
-   * - `regular`: Typically between 12 kW and 50 kW (Level 2 AC charging)
-   * - `fast`: Typically between 50 kW and 150 kW (DC fast charging)
-   * - `ultra-fast`: Typically above 150 kW (High-power DC fast charging)
+   * The {@link ChargingSpeed} class of `chargingParkPowerInkW`: the park's fastest connector.
    */
   chargingParkSpeed?: ChargingSpeed;
   /**
@@ -4554,9 +4530,10 @@ export type AreaAnalyticsAnomaly = {
  */
 export type AreaAnalyticsFeatureProperties = {
   /**
-   * Name of the analysis region.
+   * Name of the analysis region, which the API echoes from a request that names one; the SDK names none, so this is
+   * absent.
    */
-  name: string;
+  name?: string;
   /**
    * IANA timezone the API echoes from a request that names one; the SDK names none, so this is absent.
    */
@@ -5729,20 +5706,6 @@ export type GlobalConfig = {
    */
   retry?: RetryConfig;
 };
-/**
- * {@link GlobalConfig} plus the options the SDK honours but keeps off the public types.
- *
- * `put` and every service call still accept them at runtime; only {@link mergeFromGlobal} types them.
- * @ignore
- */
-export type InternalGlobalConfig = GlobalConfig & {
-  /**
-   * API version for service endpoints. Services that need another one pin it themselves.
-   *
-   * @default 1
-   */
-  apiVersion: number;
-};
 /**
  * Default base URL for TomTom APIs. A `commonBaseURL` other than this signals a
  * proxy or custom backend.
@@ -5839,7 +5802,7 @@ export declare class TomTomConfig {
  * Merges the global configuration into the given one, with the latter having priority.
  * @ignore
  */
-export declare const mergeFromGlobal: <T extends Partial<InternalGlobalConfig>>(givenConfig?: T) => InternalGlobalConfig & T;
+export declare const mergeFromGlobal: <T extends Partial<GlobalConfig>>(givenConfig?: T) => GlobalConfig & T;
 /**
  * Whether the SDK is configured for a credentials proxy such as the demos proxy
  * — no `apiKey` (the
@@ -5848,11 +5811,10 @@ export declare const mergeFromGlobal: <T extends Partial<InternalGlobalConfig>>(
  *
  * In this mode SDK requests attach `credentials: 'include'` so the proxy's
  * session cookie travels with them. In all other cases — direct TomTom usage
- * and customer-owned `customServiceBaseURL` integrations — credentials stay at
+ * and a customer-owned proxy that keeps a real `apiKey` — credentials stay at
  * the browser default, so we don't break consumers whose backend responds with
  * `Access-Control-Allow-Origin: *` (the browser rejects credentialed responses
- * against a wildcard origin). A customer using `customServiceBaseURL` keeps a
- * real `apiKey`, so this stays false for them.
+ * against a wildcard origin).
  *
  * The `apiKey` test is a falsy check (not `=== ''`) on purpose: a proxy build
  * may overwrite the bootstrap's `apiKey: ''` with `apiKey: undefined` (e.g.