@tomtom-org/maps-sdk 0.52.0 → 0.54.0

package/services/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ZodError, ZodIssue, ZodObject } from "zod";
-import { AddressProperties, AreaAnalyticsMetricKey, Avoidable, BBox, ChargingPark, ChargingParkWithAvailability, ChargingStation, ChargingStationsAccessType, ChargingStationsAvailability, ChargingStopProps, CommonPlaceProps, Connector, ConnectorType, CurrentType, EVChargingStationWithAvailabilityPlaceProps, EntryPoint, Fuel, GeographyType, GetPositionEntryPointOption, GlobalConfig, HasBBox, HasLngLat, Instruction, MapcodeType, OpeningHours, OpeningHoursMode, POICategory, Place, PlaceType, Places, PlugType, PolygonFeature, PolygonFeatures, RevGeoAddressProps, RoadShieldReference, Route, RoutePlanningLocation, Routes, SearchPlaceProps, TimeZone, TomTomAPIHeaders, TomTomHeaders, TrafficAreaAnalytics, TrafficIncidentDetails, TrafficIncidentRequestCategory, TrafficIncidentTEC, TrafficIncidentTimeValidity, TravelMode, View, inputSectionTypes } from "@tomtom-org/maps-sdk/core";
+import { AddressProperties, AreaAnalyticsMetricKey, Avoidable, BBox, ChargingPark, ChargingParkWithAvailability, ChargingStation, ChargingStationsAccessType, ChargingStationsAvailability, ChargingStopProps, CommonPlaceProps, Connector, ConnectorType, CurrentType, EVChargingStationWithAvailabilityPlaceProps, EntryPoint, Fuel, GeographyType, GetPositionEntryPointOption, GlobalConfig, HasBBox, HasLngLat, MapcodeType, OpeningHours, OpeningHoursMode, POICategory, Place, PlaceType, Places, PlugType, PolygonFeature, PolygonFeatures, RevGeoAddressProps, RoadShieldReference, Route, RoutePlanningLocation, Routes, SearchPlaceProps, TimeZone, TomTomAPIHeaders, TomTomHeaders, TrafficAreaAnalytics, TrafficIncidentDetails, TrafficIncidentRequestCategory, TrafficIncidentTEC, TrafficIncidentTimeValidity, TravelMode, View, inputSectionTypes } from "@tomtom-org/maps-sdk/core";
 //#region src/shared/types/apiResponseErrorTypes.d.ts
 /**
  * @ignore
@@ -65,6 +65,13 @@ export type FetchInput<PostData = void> = ({
 } & GetObject) | ({
   method: 'POST';
 } & PostObject<PostData>);
+/**
+ * Per-call HTTP options threaded from service params down to `fetch`.
+ * @ignore
+ */
+export type RequestOptions = {
+  signal?: AbortSignal;
+};
 export type ParsedFetchResponse<T> = Promise<{
   data: Promise<T>;
   status: number;
@@ -155,6 +162,36 @@ export type CommonServiceParams<ApiRequest = any, ApiResponse = any> = Partial<G
    * @param apiResponse - The received raw (unparsed) API response
    */
   onAPIResponse?: (apiRequest: ApiRequest, apiResponse: ApiResponse) => void;
+  /**
+   * An `AbortSignal` used to cancel the request.
+   *
+   * @remarks
+   * Aborting rejects the call with an {@link SDKAbortError} (its `name` is `'AbortError'`)
+   * and cancels the underlying HTTP request, including while the SDK is waiting to retry
+   * a rate-limited (429) response. Aborting a call that already completed has no effect.
+   *
+   * Compose signals to add a deadline: `AbortSignal.any([mine, AbortSignal.timeout(5000)])`.
+   *
+   * @example
+   * Cancel the previous search whenever a new one starts:
+   * ```ts
+   * let controller: AbortController | undefined;
+   *
+   * const searchForQuery = async (query: string) => {
+   *     controller?.abort();
+   *     controller = new AbortController();
+   *     try {
+   *         return await search({ query, signal: controller.signal });
+   *     } catch (error) {
+   *         if (error instanceof SDKAbortError) return;
+   *         throw error;
+   *     }
+   * };
+   * ```
+   *
+   * @defaultValue `undefined` (the request cannot be cancelled)
+   */
+  signal?: AbortSignal;
 };
 /**
  * Function type for parsing API error responses into SDK service errors.
@@ -217,9 +254,10 @@ export type ServiceTemplate<Params extends CommonServiceParams<ApiRequest, ApiRe
    *
    * @param request - The request object to send
    * @param headers - Custom TomTom headers to include in the request
+   * @param options - Per-call HTTP options, such as the `AbortSignal` used to cancel the request
    * @returns A promise resolving to the parsed fetch response
    */
-  sendRequest: (request: ApiRequest, headers: TomTomHeaders) => ParsedFetchResponse<ApiResponse>;
+  sendRequest: (request: ApiRequest, headers: TomTomHeaders, options?: RequestOptions) => ParsedFetchResponse<ApiResponse>;
   /**
    * Parses the successful API response into the expected return type.
    *
@@ -336,6 +374,35 @@ export declare class SDKServiceError extends SDKError {
    */
   constructor(message: string, service: string, status?: number);
 }
+/**
+ * Error class for cancelled service calls.
+ *
+ * Thrown when the `signal` passed to a service call is aborted, either before the
+ * request is sent or while it is in flight. Its `name` is `'AbortError'`, matching
+ * the convention used by `fetch`, and the original abort reason — including a custom
+ * value passed to `AbortController.abort(reason)` — is available on `cause`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await search({ query: 'cafe', signal: controller.signal });
+ * } catch (error) {
+ *   if (error instanceof SDKAbortError) return; // superseded by a newer search
+ *   throw error;
+ * }
+ * ```
+ *
+ * @group Errors
+ */
+export declare class SDKAbortError extends SDKError {
+  /**
+   * Creates a new SDKAbortError instance.
+   *
+   * @param service - Name of the service whose call was cancelled
+   * @param cause - The abort reason carried by the signal
+   */
+  constructor(service: string, cause?: unknown);
+}
 /**
  * @ignore
  * @param error
@@ -348,8 +415,9 @@ export declare const parseDefaultResponseError: ParseResponseError<DefaultAPIRes
  * @param error The error captured by a catch function.
  * @param serviceName The name of the service.
  * @param parseResponseError
+ * @param signal The signal given to the call, used to recognise a cancellation.
  */
-export declare const buildResponseError: (error: unknown, serviceName: ServiceName, parseResponseError?: ParseResponseError<unknown>) => SDKError;
+export declare const buildResponseError: (error: unknown, serviceName: ServiceName, parseResponseError?: ParseResponseError<unknown>, signal?: AbortSignal) => SDKError;
 /**
  * @ignore
  * @param error
@@ -1507,10 +1575,35 @@ export type ElectricVehiclePreferences = {
 export type VehiclePreferences<E extends VehicleEngineType = undefined> = E extends 'electric' ? ElectricVehiclePreferences : {};
 //#endregion
 //#region src/shared/types/vehicleRestrictionParams.d.ts
+/**
+ * Whether the vehicle carries an electronic toll collection transponder.
+ *
+ * Determines which toll roads the routing engine may use: some tolls can only be paid by
+ * transponder, others only without one.
+ *
+ * @group Vehicle
+ */
+export declare const tollTransponderOptions: readonly ["all", "unknown", "none"];
+/**
+ * Whether the vehicle carries an electronic toll collection transponder.
+ *
+ * @remarks
+ * - `all` — the vehicle has a transponder accepted by every toll operator on the route
+ * - `unknown` — transponder availability is unknown, so no assumption is made
+ * - `none` — the vehicle has no transponder
+ *
+ * @example
+ * ```typescript
+ * const transponder: TollTransponder = 'all';
+ * ```
+ *
+ * @group Vehicle
+ */
+export type TollTransponder = (typeof tollTransponderOptions)[number];
 /**
  * Parameters for a vehicle which are related to restrictions applied during route planning.
  */
-type VehicleRestrictions = {
+export type VehicleRestrictions = {
   /**
    * Vehicle restrictions applied during route planning.
    */
@@ -1523,6 +1616,24 @@ type VehicleRestrictions = {
      * @default 0
      */
     maxSpeedKMH?: number;
+    /**
+     * Whether the vehicle carries an electronic toll collection transponder.
+     *
+     * @remarks
+     * Affects which toll roads are considered usable: a toll that can only be paid by
+     * transponder is avoided when this is `none`, and a toll that cannot be paid by
+     * transponder is avoided when this is `all`.
+     *
+     * @default 'unknown'
+     *
+     * @example
+     * ```typescript
+     * restrictions: {
+     *   tollTransponder: 'all'
+     * }
+     * ```
+     */
+    tollTransponder?: TollTransponder;
   };
 };
 //#endregion
@@ -5302,12 +5413,12 @@ type ReachableRangeRequestAPI = FetchInput;
 //#endregion
 //#region src/routing/types/apiResponseTypes.d.ts
 /**
- * V3 traffic section icon categories.
+ * Traffic section icon categories.
  * @ignore
  */
 type IconCategoryAPI = 'jam' | 'accident' | 'brokenDownVehicle' | 'dangerousConditions' | 'flooding' | 'fog' | 'ice' | 'laneClosed' | 'rain' | 'roadClosed' | 'roadWorks' | 'wind';
 /**
- * V3 delay magnitude values. `'undefined'` is the raw API value mapped to SDK `'indefinite'`.
+ * Delay magnitude values. `'undefined'` is the raw API value mapped to SDK `'indefinite'`.
  * @ignore
  */
 type DelayMagnitudeAPI = 'unknown' | 'minor' | 'moderate' | 'major' | 'undefined';
@@ -5352,7 +5463,7 @@ type ChargingStopAPI = Omit<ChargingStopProps, 'targetChargeInPCT' | 'chargingCo
   };
 };
 /**
- * V3 summary — field names changed from V2.
+ * Route summary as the API returns it.
  * @ignore
  */
 type SummaryAPI = {
@@ -5365,6 +5476,7 @@ type SummaryAPI = {
   deviationDistanceInMeters?: number;
   deviationDurationInSeconds?: number;
   deviationPoint?: Point;
+  originalWaypointIndexAtEndOfLeg?: number;
   historicTrafficTravelTimeInSeconds?: number;
   liveTrafficIncidentsTravelTimeInSeconds?: number;
   noTrafficTravelTimeInSeconds?: number;
@@ -5376,7 +5488,7 @@ type SummaryAPI = {
   chargingInformationAtEndOfLeg?: ChargingStopAPI;
 };
 /**
- * V3 leg — path is now a GeoJSON LineString instead of a points array.
+ * Route leg. Its path is a GeoJSON LineString, not a points array.
  * @ignore
  */
 type LegAPI = {
@@ -5384,7 +5496,7 @@ type LegAPI = {
   summary: SummaryAPI;
 };
 /**
- * V3 basic section — uses pathIndex instead of pointIndex.
+ * Basic section. Spans are expressed with pathIndex, not pointIndex.
  * @ignore
  */
 type BasicSectionAPI = {
@@ -5415,7 +5527,7 @@ type TrafficSectionAPI = BasicSectionAPI & {
   eventId?: string;
 };
 /**
- * V3 speed limit section — speed values live under `speedRestrictions` (typed maximum/minimum)
+ * Speed limit section — speed values live under `speedRestrictions` (typed maximum/minimum)
  * instead of the V2 flat `maxSpeedLimitInKmh`.
  * @ignore
  */
@@ -5426,7 +5538,7 @@ type SpeedLimitSectionAPI = BasicSectionAPI & {
   }[];
 };
 /**
- * V3 lanes section — directions/separators are camelCase strings (mapped to the SDK's
+ * Lanes section — directions/separators are camelCase strings (mapped to the SDK's
  * UPPER_SNAKE enums during parsing), and lanes are objects rather than flat direction lists.
  * @ignore
  */
@@ -5453,7 +5565,7 @@ type ImportantRoadStretchSectionAPI = BasicSectionAPI & {
   }[];
 };
 /**
- * V3 sections object — already grouped by type (no flat array + discriminator).
+ * Sections object, grouped by type rather than a flat array with a discriminator.
  * @ignore
  */
 type SectionsAPI = {
@@ -5475,11 +5587,12 @@ type SectionsAPI = {
   roadShields?: (BasicSectionAPI & {
     roadShieldReferences?: RoadShieldReference[];
   })[];
+  tollRoad?: BasicSectionAPI[];
   tollVignette?: CountrySectionAPI[];
   importantRoadStretch?: ImportantRoadStretchSectionAPI[];
 };
 /**
- * V3 lat/lon point used in guidance instructions (different from GeoJSON used elsewhere).
+ * Lat/lon point used in guidance instructions (different from the GeoJSON used elsewhere).
  * @ignore
  */
 type LatLonPointAPI = {
@@ -5487,7 +5600,7 @@ type LatLonPointAPI = {
   longitude: number;
 };
 /**
- * V3 routePath point — field names changed from V2.
+ * A point on the route path.
  * @ignore
  */
 type RoutePathPointAPI = {
@@ -5496,24 +5609,17 @@ type RoutePathPointAPI = {
   travelTimeFromRouteStartInSeconds: number;
 };
 /**
- * V3 phonetic transcription — an object keyed by phonetic alphabet, not a flat string as in V2.
- * @ignore
- */
-type PhoneticAPI = {
-  lhp?: string;
-  ipa?: string;
-};
-/**
- * V3 text-with-phonetics — `phonetic` is now an object (mapped to a flat string during parsing).
+ * Text with phonetics. `phonetic` is a flat string, already transcribed in the alphabet the
+ * request asked for via `instructionPhonetics` — there is no per-alphabet object to choose from.
  * @ignore
  */
 type TextWithPhoneticsAPI = {
   text: string;
-  phonetic?: PhoneticAPI;
+  phonetic?: string;
   phoneticLanguageCode?: string;
 };
 /**
- * V3 icon reference — same shape as the SDK's RoadShieldReference.
+ * Icon reference — same shape as the SDK's RoadShieldReference.
  * @ignore
  */
 type IconReferenceAPI = {
@@ -5522,7 +5628,7 @@ type IconReferenceAPI = {
   affixes?: string[];
 };
 /**
- * V3 road shield inside an instruction's road information. `iconReference` is EXPLICIT.
+ * Road shield inside an instruction's road information. `iconReference` is EXPLICIT.
  * @ignore
  */
 type InstructionRoadShieldAPI = {
@@ -5532,7 +5638,25 @@ type InstructionRoadShieldAPI = {
   iconReference?: IconReferenceAPI;
 };
 /**
- * V3 road information inside an instruction — field names changed from V2.
+ * Side road. `side` is lowercase on the wire, mapped to the SDK's UPPER_SNAKE `SideRoadSide`.
+ * @ignore
+ */
+type SideRoadAPI = {
+  side: string;
+  offsetFromManeuverInMeters: number;
+  isDrivable?: boolean;
+};
+/**
+ * Maneuver view. Both angle fields are relative-direction strings (`slightLeft`, `back`, …),
+ * not degrees, and are mapped to the SDK's UPPER_SNAKE `ManeuverAngle`.
+ * @ignore
+ */
+type ManeuverViewAPI = {
+  onRouteAngle?: string;
+  offRouteAngles?: string[];
+};
+/**
+ * Road information inside an instruction.
  * @ignore
  */
 type InstructionRoadInformationAPI = {
@@ -5540,13 +5664,16 @@ type InstructionRoadInformationAPI = {
   roadShields?: InstructionRoadShieldAPI[];
   roadNames?: Array<{
     identifier: TextWithPhoneticsAPI;
+    source?: string;
   }>;
   roadNumbers?: Array<{
     identifier: TextWithPhoneticsAPI;
+    source?: string;
   }>;
+  countryCodeIso2?: string;
 };
 /**
- * V3 signpost — adds an EXPLICIT `exitIconReference` (mapped to signpostRoadShieldReferences).
+ * Signpost. Carries an EXPLICIT `exitIconReference`, mapped to signpostRoadShieldReferences.
  * @ignore
  */
 type SignpostAPI = {
@@ -5556,7 +5683,7 @@ type SignpostAPI = {
   exitIconReference?: IconReferenceAPI;
 };
 /**
- * V3 instruction — raw response shape. Coordinates are lat/lon (not GeoJSON), and several field
+ * Instruction — raw response shape. Coordinates are lat/lon (not GeoJSON), and several field
  * names / value casings differ from the SDK's {@link Instruction}; the parser converts them.
  * @ignore
  */
@@ -5582,10 +5709,14 @@ type InstructionAPI = {
   countryCrossingFromCodeIso2?: string;
   countryCrossingToName?: TextWithPhoneticsAPI;
   countryCrossingToCodeIso2?: string;
-  sideRoads?: Instruction['sideRoads'];
+  sideRoads?: SideRoadAPI[];
+  /** Generated, localised instruction text. Present on every instruction. */
+  message?: string;
+  maneuverView?: ManeuverViewAPI;
+  roundaboutType?: string;
 };
 /**
- * V3 progress point — field names differ from the SDK's RouteProgressPoint.
+ * Progress point. Its field names differ from the SDK's RouteProgressPoint.
  * @ignore
  */
 type ProgressPointAPI = {
@@ -6251,7 +6382,7 @@ declare const customize$3: {
 //#endregion
 //#region src/routing/types/apiRequestTypes.d.ts
 /**
- * V3 charging model sent in the POST body of the LDEVR endpoint.
+ * Charging model sent in the POST body of the LDEVR endpoint.
  * @ignore
  */
 type ChargingParametersAPI = {
@@ -6268,7 +6399,7 @@ type RoutePlanningLocationsAPI = {
   waypoints?: MultiPoint;
 };
 /**
- * V3 avoid area rectangle expressed as a GeoJSON Feature with a bbox.
+ * Avoid area rectangle expressed as a GeoJSON Feature with a bbox.
  * @ignore
  */
 type AvoidRectangleAPI = {
@@ -6283,14 +6414,28 @@ type AvoidAreasAPI = {
   rectangles: AvoidRectangleAPI[];
 };
 /**
- * V3 per-leg request (used in the `legs` array for route reconstruction).
+ * Per-stop request options, nested under the leg that arrives at the stop.
+ * @ignore
+ */
+type RouteStopRequestAPI = {
+  pauseDurationInSeconds?: number;
+  entryPoints?: MultiPoint;
+  preferredEntryPointIndex?: number;
+};
+/**
+ * Per-leg request, used in the `legs` array for route reconstruction and per-stop options.
  * @ignore
  */
 type LegRequestAPI = {
   path?: LineString;
+  routeType?: RouteType;
+  avoids?: {
+    name: string;
+  }[];
+  routeStop?: RouteStopRequestAPI;
 };
 /**
- * V3 POST body for /routing/routes/calculate and (partially) /routing/calculateLongDistanceEVRoute.
+ * POST body for /routing/routes/calculate and (partially) /routing/calculateLongDistanceEVRoute.
  * Consumption model parameters are sent as URL query params, not in the POST body.
  * @ignore
  */
@@ -6298,7 +6443,7 @@ type CalculateRoutePOSTDataAPI = {
   routePlanningLocations: RoutePlanningLocationsAPI;
   path?: LineString;
   legs?: LegRequestAPI[];
-  routeType?: string;
+  routeType?: RouteType;
   traffic?: string;
   avoids?: string[];
   travelMode?: string;
@@ -6309,6 +6454,8 @@ type CalculateRoutePOSTDataAPI = {
   vehicleWeightInKilograms?: number;
   vehicleMaxSpeedInKilometersPerHour?: number;
   vehicleHeadingInDegrees?: number;
+  vehicleHasElectronicTollCollectionTransponder?: string;
+  arrivalSidePreference?: 'anySide' | 'curbSide';
   chargingParameters?: ChargingParametersAPI;
   guidance?: 'none' | 'instructions';
   instructionPhonetics?: 'ipa' | 'lhp';
@@ -6378,6 +6525,36 @@ type InputSectionType = (typeof inputSectionTypes)[number];
  * @group Routing
  */
 type InputSectionTypes = InputSectionType[];
+/**
+ * The phonetic alphabet street names are transcribed in.
+ *
+ * @remarks
+ * - `LHP`: Language-specific phonetic representation
+ * - `IPA`: International Phonetic Alphabet
+ *
+ * @group Routing
+ */
+type Phonetics = 'LHP' | 'IPA';
+/**
+ * The accepted values of {@link ChargingStopsStrategy}.
+ * @group Routing
+ */
+declare const chargingStopsStrategies: readonly ["automaticFastest", "manualFastest", "automaticFastestWithFallbackToManual"];
+/**
+ * How the routing service should plan charging stops on an electric route.
+ *
+ * @remarks
+ * - `automaticFastest`: the service picks charging stops for the fastest journey. The default.
+ * - `manualFastest`: the service plans no charging stops of its own; only stops you pass as
+ *   waypoints are charged at.
+ * - `automaticFastestWithFallbackToManual`: automatic, falling back to manual when no chargeable
+ *   route exists.
+ *
+ * Requires `vehicle.preferences.chargingPreferences` to be set as well: the endpoint also needs a
+ * minimum charge at the destination, which only the preferences supply.
+ * @group Routing
+ */
+type ChargingStopsStrategy = (typeof chargingStopsStrategies)[number];
 /**
  * Configuration for turn-by-turn guidance instructions.
  *
@@ -6410,7 +6587,7 @@ type GuidanceParams = {
    *
    * @default 'IPA'
    */
-  phonetics?: 'LHP' | 'IPA';
+  phonetics?: Phonetics;
 };
 /**
  * Extended route representation options.
@@ -6455,6 +6632,29 @@ type ExtendedRouteRepresentation = 'distance' | 'travelTime';
  * @group Routing
  */
 type ComputeTravelTimeFor = 'none' | 'all';
+/**
+ * Side of the road to arrive on.
+ *
+ * @group Routing
+ */
+declare const arrivalSides: readonly ["any", "curb"];
+/**
+ * Which side of the road the route should arrive on at each stop.
+ *
+ * @remarks
+ * - `any`: arrive from either side, whichever is faster
+ * - `curb`: arrive on the curb side for the country's driving direction
+ *
+ * @example
+ * ```typescript
+ * const arrivalSide: ArrivalSide = 'curb';
+ * ```
+ *
+ * @default 'any'
+ *
+ * @group Routing
+ */
+type ArrivalSide = (typeof arrivalSides)[number];
 /**
  * Maximum number of alternative routes to calculate.
  *
@@ -6597,7 +6797,26 @@ type CalculateRouteParams = CommonServiceParams<CalculateRouteRequestAPI, Calcul
    */
   useEntryPoints?: GetPositionEntryPointOption;
   /**
-   * Request additional travel time calculations for different traffic scenarios.
+   * Which side of the road the route should arrive on.
+   *
+   * @remarks
+   * - `any`: arrive from either side, whichever is faster
+   * - `curb`: arrive on the curb side for the country's driving direction, so passengers or
+   *   deliveries can leave the vehicle without crossing the road
+   *
+   * Applies to the destination and to every intermediate stop.
+   *
+   * @default 'any'
+   *
+   * @example
+   * ```typescript
+   * // Pull up on the passenger side at each stop
+   * arrivalSide: 'curb'
+   * ```
+   */
+  arrivalSide?: ArrivalSide;
+  /**
+   * Request travel time calculations for different traffic scenarios.
    *
    * When set to 'all', the returned route summary will contain extra fields:
    * - `noTrafficTravelTimeInSeconds` – Free-flow (no traffic)
@@ -6610,10 +6829,25 @@ type CalculateRouteParams = CommonServiceParams<CalculateRouteRequestAPI, Calcul
    *
    * @example
    * ```typescript
-   * computeAdditionalTravelTimeFor: 'all'
+   * computeTravelTimeFor: 'all'
+   * ```
+   */
+  computeTravelTimeFor?: ComputeTravelTimeFor;
+  /**
+   * How the service should plan charging stops on an electric route.
+   *
+   * Only applies to electric routes, so `vehicle.preferences.chargingPreferences` must be set
+   * too — validation says so before the request is sent.
+   *
+   * @default 'automaticFastest' (the service's own default when unset)
+   *
+   * @example
+   * ```typescript
+   * // Plan the fastest journey, choosing charging stops along the way
+   * chargingStopsStrategy: 'automaticFastest'
    * ```
    */
-  computeAdditionalTravelTimeFor?: ComputeTravelTimeFor;
+  chargingStopsStrategy?: ChargingStopsStrategy;
   /**
    * Request extended progress information at route polyline points.
    *
@@ -6708,7 +6942,7 @@ type CalculateRouteTemplate = ServiceTemplate<CalculateRouteParams, FetchInput<C
 //#region src/routing/requestBuilder.d.ts
 /**
  * Default function for building calculate route request from {@link CalculateRouteParams}
- * targeting the OrbisV3 routing API.
+ * targeting the Orbis routing API.
  * @param params The calculate route parameters, with global configuration already merged into them.
  */
 declare const buildCalculateRouteRequest: (params: CalculateRouteParams) => FetchInput<CalculateRoutePOSTDataAPI>;
@@ -8375,7 +8609,8 @@ export declare const calculateReachableRange: (params: ReachableRangeParams, cus
  * consider implementing your own parallel processing with appropriate throttling.
  *
  * @param paramsArray Array of reachable range parameters, one for each area to calculate
- * @param options.signal An `AbortSignal` to cancel in-flight requests between iterations.
+ * @param options.signal An `AbortSignal` to cancel the in-flight request and skip the remaining ones.
+ *   Composed with any per-entry `signal`, so either one cancels.
  * @param customTemplate Advanced customization for request/response handling
  *
  * @returns Promise resolving to a FeatureCollection of reachable area polygons
@@ -8436,6 +8671,101 @@ export declare const calculateReachableRanges: (paramsArray: ReachableRangeParam
  */
 export declare const calculateRoute: (params: CalculateRouteParams, customTemplate?: Partial<CalculateRouteTemplate>) => Promise<Routes>;
 //#endregion
+//#region src/routing/types/routeStopOptions.d.ts
+/**
+ * Cost model overrides that apply to a single leg of a route.
+ *
+ * @remarks
+ * A subset of {@link CostModel}: only the route type and the avoid list can vary per leg.
+ * Traffic, avoid areas and departure time are route-wide.
+ *
+ * @group Routing
+ */
+type LegCostModel = Pick<CostModel, 'routeType' | 'avoid'>;
+/**
+ * Per-stop routing options, carried on the `properties` of a route stop.
+ *
+ * Attach these to any waypoint in {@link CalculateRouteParams.locations} to control how the
+ * route reaches that stop, and how long it waits there.
+ *
+ * @remarks
+ * **Leg attribution.** Options describe the leg *arriving at* this stop. Reading them that way
+ * is what keeps them attached to the right stop when another stop is inserted earlier in the
+ * list. `legCostModel` on the origin has no leg to describe and is ignored.
+ *
+ * **The wait at a stop** is {@link WaypointProps.pauseDurationSeconds}, which every waypoint
+ * carries — the map reads it too, to label the stop's pin.
+ *
+ * **Entry points.** Explicit `candidateEntryPoints` hand the routing engine a set of approach
+ * points and let it choose; this takes precedence over the route-wide
+ * {@link CalculateRouteParams.useEntryPoints}, which only resolves a single position
+ * client-side.
+ *
+ * @example
+ * ```typescript
+ * import type { Waypoint } from '@tomtom-org/maps-sdk/core';
+ * import type { RouteStopOptions } from '@tomtom-org/maps-sdk/services';
+ *
+ * const stop: Waypoint<RouteStopOptions> = {
+ *     type: 'Feature',
+ *     geometry: { type: 'Point', coordinates: [4.7, 52.1] },
+ *     properties: {
+ *         // wait 20 minutes at this stop
+ *         pauseDurationSeconds: 1200,
+ *         // reach this stop without using motorways
+ *         legCostModel: { routeType: 'short', avoid: ['motorways'] },
+ *     },
+ * };
+ *
+ * const route = await calculateRoute({ locations: [origin, stop, destination] });
+ * ```
+ *
+ * @group Routing
+ */
+type RouteStopOptions = {
+  /**
+   * Candidate approach points for this stop, for the routing engine to choose between.
+   *
+   * @remarks
+   * Use this when a place has several usable entrances and you want the engine to pick the one
+   * that suits the route, rather than resolving a single entry point yourself. Takes precedence
+   * over {@link CalculateRouteParams.useEntryPoints} for this stop.
+   *
+   * Deliberately not called `entryPoints`: a {@link Place} already carries `entryPoints` of its
+   * own in `properties`, describing entrances found by search, and those are not sent to the
+   * routing API. These are positions you choose to offer the router.
+   *
+   * @example
+   * ```typescript
+   * // Let the router choose between the main and the delivery entrance
+   * candidateEntryPoints: [[4.701, 52.101], [4.703, 52.099]]
+   * ```
+   */
+  candidateEntryPoints?: HasLngLat[];
+  /**
+   * Index into {@link RouteStopOptions.candidateEntryPoints} of the preferred approach point.
+   *
+   * @remarks
+   * The routing engine uses this entry point unless another one produces a materially better
+   * route. Ignored when `candidateEntryPoints` is not set.
+   */
+  preferredEntryPointIndex?: number;
+  /**
+   * Cost model overrides for the leg *arriving at* this stop.
+   *
+   * @remarks
+   * Falls back to the route-wide {@link CostModel} for anything not set here. Ignored on the
+   * origin, which has no arriving leg.
+   *
+   * @example
+   * ```typescript
+   * // Take the scenic way to this one stop
+   * legCostModel: { routeType: 'thrilling', avoid: ['motorways'] }
+   * ```
+   */
+  legCostModel?: LegCostModel;
+};
+//#endregion
 //#region src/fuzzy-search/types/fuzzySearchResponse.d.ts
 /**
  * Response from the fuzzy search service.
@@ -9079,4 +9409,4 @@ export declare const trafficAreaAnalytics: (params: TrafficAreaAnalyticsParams,
  */
 export declare const trafficIncidentDetails: (params: TrafficIncidentDetailsParams, customTemplate?: Partial<TrafficIncidentDetailsTemplate>) => Promise<TrafficIncidentDetails>;
 //#endregion
-export type { AdditionalDataAPI, AlongRouteSearchParams, AlongRouteSearchPayloadAPI, AlongRouteSearchRequestAPI, AlongRouteSearchResponse, AlongRouteSearchResponseAPI, AlongRouteSearchResultAPI, AlongRouteSortBy, AreaAnalyticsDateInput, AreaTag, AutocompleteGenericSearchSegment, AutocompleteSearchBrandSegment, AutocompleteSearchCategorySegment, AutocompleteSearchCategorySegmentAPI, AutocompleteSearchContext, AutocompleteSearchContextAPI, AutocompleteSearchMatch, AutocompleteSearchMatches, AutocompleteSearchParams, AutocompleteSearchPlaintextSegment, AutocompleteSearchResponse, AutocompleteSearchResponseAPI, AutocompleteSearchResult, AutocompleteSearchResultAPI, AutocompleteSearchResultGeoBias, AutocompleteSearchResultGeoBiasAPI, AutocompleteSearchSegment, AutocompleteSearchSegmentAPI, AutocompleteSearchSegmentType, BookmarkIntent, BookmarkIntentDetails, CalculateRouteParams, CanonicalAreaTag, ChargingStationsAvailabilityParams, Circle, CircleAPI, CommonServiceParamsWithZoom, ComputeTravelTimeFor, CoordinateIntent, CoordinateIntentAPI, CoordinateIntentDetails, CoordinateIntentDetailsAPI, ExplorationBrandAPI, ExplorationChargingParkAPI, ExplorationClassificationAPI, ExplorationOpeningHoursAPI, ExplorationOpeningIntervalAPI, ExplorationPOIAPI, ExplorationPlaceProps, ExplorationRecordType, ExplorationSearchParams, ExplorationSearchPayloadAPI, ExplorationSearchRequestAPI, ExplorationSearchResponse, ExplorationSearchResponseAPI, ExplorationSearchResultAPI, ExplorationViewportAPI, ExtendedRouteRepresentation, FunctionalRoadClass, FuzzySearchParams, FuzzySearchResponse, FuzzySearchResponseAPI, FuzzySearchResultAPI, GeocodingParams, GeocodingProps, GeocodingResponse, GeometriesInput, GeometryAPI, GeometryDataParams, GeometryDataResponseAPI, GeometryParams, GeometryPlaceParams, GeometrySearchFeatureCollectionProps, GeometrySearchParams, GeometrySearchPayloadAPI, GeometrySearchRequestAPI, GeometrySearchResponse, GeometrySearchResponseAPI, GeometrySearchResultAPI, GuidanceParams, InputSectionType, InputSectionTypes, MaxNumberOfAlternatives, NearAPI, NearbyIntent, NearbyIntentAPI, NearbyIntentDetails, NearbyIntentDetailsAPI, POICategoriesParams, POICategoriesResponse, POICategoryResult, PlaceByIdMandatoryParams, PlaceByIdOptionalParams, PlaceByIdParams, PlaceByIdResponse, PlaceByIdResponseAPI, PlaceByIdResultAPI, PoiCategoriesResponseAPI, PoiCategoryAPI, PolygonAPI, PopulatedAreaTag, QueryIntent, QueryIntentAPI, ReverseGeocodingMandatoryParams, ReverseGeocodingOptionalParams, ReverseGeocodingParams, RoutePointAPI, SearchGeometryInput, TrafficAreaAnalyticsDateRange, TrafficAreaAnalyticsDays, TrafficAreaAnalyticsParams, TrafficIncidentDetailsByBBoxParams, TrafficIncidentDetailsByIdsParams, TrafficIncidentDetailsParams, W3WIntent, W3WIntentDetails, functionalRoadClasses, metricKeyToApiDataType };
+export type { AdditionalDataAPI, AlongRouteSearchParams, AlongRouteSearchPayloadAPI, AlongRouteSearchRequestAPI, AlongRouteSearchResponse, AlongRouteSearchResponseAPI, AlongRouteSearchResultAPI, AlongRouteSortBy, AreaAnalyticsDateInput, AreaTag, ArrivalSide, AutocompleteGenericSearchSegment, AutocompleteSearchBrandSegment, AutocompleteSearchCategorySegment, AutocompleteSearchCategorySegmentAPI, AutocompleteSearchContext, AutocompleteSearchContextAPI, AutocompleteSearchMatch, AutocompleteSearchMatches, AutocompleteSearchParams, AutocompleteSearchPlaintextSegment, AutocompleteSearchResponse, AutocompleteSearchResponseAPI, AutocompleteSearchResult, AutocompleteSearchResultAPI, AutocompleteSearchResultGeoBias, AutocompleteSearchResultGeoBiasAPI, AutocompleteSearchSegment, AutocompleteSearchSegmentAPI, AutocompleteSearchSegmentType, BookmarkIntent, BookmarkIntentDetails, CalculateRouteParams, CanonicalAreaTag, ChargingStationsAvailabilityParams, ChargingStopsStrategy, Circle, CircleAPI, CommonServiceParamsWithZoom, ComputeTravelTimeFor, CoordinateIntent, CoordinateIntentAPI, CoordinateIntentDetails, CoordinateIntentDetailsAPI, ExplorationBrandAPI, ExplorationChargingParkAPI, ExplorationClassificationAPI, ExplorationOpeningHoursAPI, ExplorationOpeningIntervalAPI, ExplorationPOIAPI, ExplorationPlaceProps, ExplorationRecordType, ExplorationSearchParams, ExplorationSearchPayloadAPI, ExplorationSearchRequestAPI, ExplorationSearchResponse, ExplorationSearchResponseAPI, ExplorationSearchResultAPI, ExplorationViewportAPI, ExtendedRouteRepresentation, FunctionalRoadClass, FuzzySearchParams, FuzzySearchResponse, FuzzySearchResponseAPI, FuzzySearchResultAPI, GeocodingParams, GeocodingProps, GeocodingResponse, GeometriesInput, GeometryAPI, GeometryDataParams, GeometryDataResponseAPI, GeometryParams, GeometryPlaceParams, GeometrySearchFeatureCollectionProps, GeometrySearchParams, GeometrySearchPayloadAPI, GeometrySearchRequestAPI, GeometrySearchResponse, GeometrySearchResponseAPI, GeometrySearchResultAPI, GuidanceParams, InputSectionType, InputSectionTypes, LegCostModel, MaxNumberOfAlternatives, NearAPI, NearbyIntent, NearbyIntentAPI, NearbyIntentDetails, NearbyIntentDetailsAPI, POICategoriesParams, POICategoriesResponse, POICategoryResult, Phonetics, PlaceByIdMandatoryParams, PlaceByIdOptionalParams, PlaceByIdParams, PlaceByIdResponse, PlaceByIdResponseAPI, PlaceByIdResultAPI, PoiCategoriesResponseAPI, PoiCategoryAPI, PolygonAPI, PopulatedAreaTag, QueryIntent, QueryIntentAPI, ReverseGeocodingMandatoryParams, ReverseGeocodingOptionalParams, ReverseGeocodingParams, RoutePointAPI, RouteStopOptions, SearchGeometryInput, TrafficAreaAnalyticsDateRange, TrafficAreaAnalyticsDays, TrafficAreaAnalyticsParams, TrafficIncidentDetailsByBBoxParams, TrafficIncidentDetailsByIdsParams, TrafficIncidentDetailsParams, W3WIntent, W3WIntentDetails, arrivalSides, chargingStopsStrategies, functionalRoadClasses, metricKeyToApiDataType };