@tomtom-org/maps-sdk 0.45.8 → 0.45.9

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tomtom-org/maps-sdk",
   "author": "TomTom International B.V.",
   "license": "See in LICENSE.txt",
-  "version": "0.45.8",
+  "version": "0.45.9",
   "description": "TomTom Maps for JavaScript",
   "keywords": [
     "tomtom",

package/services/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { AddressProperties } from '@tomtom-org/maps-sdk/core';
 import { Avoidable } from '@tomtom-org/maps-sdk/core';
+import { BBox } from '@tomtom-org/maps-sdk/core';
 import { ChargingPark } from '@tomtom-org/maps-sdk/core';
 import { ChargingParkWithAvailability } from '@tomtom-org/maps-sdk/core';
 import { ChargingStation } from '@tomtom-org/maps-sdk/core';
@@ -25,6 +26,7 @@ import { inputSectionTypes } from '@tomtom-org/maps-sdk/core';
 import { Instruction } from '@tomtom-org/maps-sdk/core';
 import { LaneDirection } from '@tomtom-org/maps-sdk/core';
 import { LegSummary } from '@tomtom-org/maps-sdk/core';
+import { LineString } from 'geojson';
 import { Mapcode } from '@tomtom-org/maps-sdk/core';
 import { MapcodeType } from '@tomtom-org/maps-sdk/core';
 import { MultiPolygon } from 'geojson';
@@ -38,6 +40,7 @@ import { Places as Places_2 } from '@tomtom-org/maps-sdk/core';
 import { PlaceType } from '@tomtom-org/maps-sdk/core';
 import { PlugType } from '@tomtom-org/maps-sdk/core';
 import { POICategory } from '@tomtom-org/maps-sdk/core';
+import { Point } from 'geojson';
 import { Polygon } from 'geojson';
 import { PolygonFeature } from '@tomtom-org/maps-sdk/core';
 import { PolygonFeatures } from '@tomtom-org/maps-sdk/core';
@@ -56,7 +59,10 @@ import { SearchPlaceProps as SearchPlaceProps_2 } from '@tomtom-org/maps-sdk/cor
 import { SideOfStreet } from '@tomtom-org/maps-sdk/core';
 import { TimeZone } from '@tomtom-org/maps-sdk/core';
 import { TomTomHeaders } from '@tomtom-org/maps-sdk/core';
+import { TrafficIncidentCategory } from '@tomtom-org/maps-sdk/core';
+import { TrafficIncidentDetails } from '@tomtom-org/maps-sdk/core';
 import { TrafficIncidentTEC } from '@tomtom-org/maps-sdk/core';
+import { TrafficIncidentTimeValidity } from '@tomtom-org/maps-sdk/core';
 import { TravelMode } from '@tomtom-org/maps-sdk/core';
 import { View } from '@tomtom-org/maps-sdk/core';
 import { ZodError } from 'zod';
@@ -814,6 +820,12 @@ export declare const buildResponseError: (error: unknown, serviceName: ServiceNa
  */
 declare const buildRevGeoRequest: (params: ReverseGeocodingParams) => URL;
 
+/**
+ * Default method for building a traffic incident details request from {@link TrafficIncidentDetailsParams}.
+ * @param params The traffic incident details parameters, with global configuration already merged into them.
+ */
+declare const buildTrafficIncidentDetailsRequest: (params: TrafficIncidentDetailsParams) => FetchInput<TrafficIncidentDetailsPostBody>;
+
 /**
  * @ignore
  * @param error
@@ -3085,6 +3097,13 @@ declare const customize: {
     reverseGeocodingTemplate: ReverseGeocodingTemplate;
 };
 
+declare const customize_10: {
+    autocompleteSearch: typeof autocompleteSearch;
+    buildAutocompleteSearchRequest: typeof buildAutocompleteSearchRequest;
+    parseAutocompleteSearchResponse: typeof parseAutocompleteSearchResponse;
+    autocompleteSearchTemplate: AutocompleteSearchTemplate;
+};
+
 declare const customize_2: {
     buildGeocodingRequest: typeof buildGeocodingRequest;
     parseGeocodingResponse: typeof parseGeocodingResponse;
@@ -3123,16 +3142,15 @@ declare const customize_7: {
 };
 
 declare const customize_8: {
-    buildPlaceByIdRequest: typeof buildPlaceByIdRequest;
-    parsePlaceByIdResponse: typeof parsePlaceByIdResponse;
-    placeByIdTemplate: PlaceByIdTemplate;
+    buildTrafficIncidentDetailsRequest: typeof buildTrafficIncidentDetailsRequest;
+    parseTrafficIncidentDetailsResponse: typeof parseTrafficIncidentDetailsResponse;
+    trafficIncidentDetailsTemplate: TrafficIncidentDetailsTemplate;
 };
 
 declare const customize_9: {
-    autocompleteSearch: typeof autocompleteSearch;
-    buildAutocompleteSearchRequest: typeof buildAutocompleteSearchRequest;
-    parseAutocompleteSearchResponse: typeof parseAutocompleteSearchResponse;
-    autocompleteSearchTemplate: AutocompleteSearchTemplate;
+    buildPlaceByIdRequest: typeof buildPlaceByIdRequest;
+    parsePlaceByIdResponse: typeof parsePlaceByIdResponse;
+    placeByIdTemplate: PlaceByIdTemplate;
 };
 
 /**
@@ -3185,8 +3203,9 @@ export declare const customizeService: {
     calculateRoute: typeof customize_5;
     reachableRange: typeof customize_6;
     evChargingStationsAvailability: typeof customize_7;
-    placeByID: typeof customize_8;
-    autocompleteSearch: typeof customize_9;
+    trafficIncidentDetails: typeof customize_8;
+    placeByID: typeof customize_9;
+    autocompleteSearch: typeof customize_10;
 };
 
 /**
@@ -4822,6 +4841,77 @@ export declare type GuidanceParams = {
  */
 export declare const hasChargingAvailability: (chargingPark: ChargingPark | ChargingParkWithAvailability | undefined) => chargingPark is ChargingParkWithAvailability;
 
+/**
+ * @ignore
+ */
+declare type IncidentAPI = {
+    type: 'Feature';
+    geometry: IncidentGeometryAPI;
+    properties: IncidentPropertiesAPI;
+};
+
+/**
+ * @ignore
+ */
+declare type IncidentDetailsResponseAPI = {
+    incidents: (IncidentAPI | null)[];
+};
+
+/**
+ * @ignore
+ */
+declare type IncidentEventAPI = {
+    description: string;
+    code: number;
+    iconCategory: number;
+};
+
+/**
+ * @ignore
+ */
+declare type IncidentGeometryAPI = Point | LineString;
+
+/**
+ * @ignore
+ */
+declare type IncidentPropertiesAPI = {
+    id: string;
+    iconCategory: number;
+    magnitudeOfDelay: number;
+    events: IncidentEventAPI[];
+    startTime?: string;
+    endTime?: string;
+    from?: string;
+    to?: string;
+    length?: number;
+    delay?: number;
+    roadNumbers?: string[];
+    timeValidity: string;
+    probabilityOfOccurrence?: string;
+    numberOfReports?: number;
+    lastReportTime?: string;
+    tmc?: IncidentTMCAPI;
+};
+
+/**
+ * @ignore
+ */
+declare type IncidentTMCAPI = {
+    countryCode: string;
+    tableNumber: string;
+    tableVersion: string;
+    direction: string;
+    points: IncidentTMCPointAPI[];
+};
+
+/**
+ * @ignore
+ */
+declare type IncidentTMCPointAPI = {
+    location: number;
+    offset?: number;
+};
+
 /**
  * Route section type that can be requested in routing parameters.
  *
@@ -5160,6 +5250,12 @@ export declare type ParseResponseError<T = DefaultAPIResponseErrorBody> = (apiEr
  */
 declare const parseRevGeoResponse: (apiResponse: ReverseGeocodingResponseAPI, params: ReverseGeocodingParams) => ReverseGeocodingResponse;
 
+/**
+ * Default method for parsing a traffic incident details API response.
+ * @param apiResponse The raw Traffic Incident Details API response.
+ */
+declare const parseTrafficIncidentDetailsResponse: (apiResponse: IncidentDetailsResponseAPI) => TrafficIncidentDetails;
+
 /**
  * Retrieve detailed information about a place using its unique identifier.
  *
@@ -6880,6 +6976,214 @@ export declare type TimeZoneRequest = 'iana';
  */
 declare type TrafficCategoryAPI = 'JAM' | 'ROAD_WORK' | 'ROAD_CLOSURE' | 'OTHER';
 
+/**
+ * Fetch detailed information about traffic incidents.
+ *
+ * Query incidents either by a geographic bounding box or by a list of incident IDs.
+ * Results are GeoJSON Features whose geometry is a `Point` (localised incidents) or
+ * a `LineString` (incidents spanning a stretch of road).
+ *
+ * @remarks
+ * **Two query modes:**
+ *
+ * - **Bounding box** (`bbox`): Returns all incidents within the given area.
+ *   Maximum area is 10,000 km².
+ * - **By IDs** (`ids`): Returns the specified incidents directly.
+ *   GET is used automatically for up to 5 IDs; POST for up to 100 IDs.
+ *
+ * **Key data provided per incident:**
+ * - Category (`iconCategory`): type of incident (accident, roadworks, jam, etc.)
+ * - Delay magnitude: severity of the delay (`minor`, `moderate`, `major`, …)
+ * - Geometry: exact location or extent of the incident on the road network
+ * - Time information: start/end times and whether the incident is `present` or `future`
+ * - Events: one or more detailed event descriptions
+ *
+ * @param params - Traffic Incident Details parameters (bbox or ids)
+ * @param customTemplate - Advanced customization for request/response handling
+ *
+ * @returns Promise resolving to a {@link TrafficIncidentDetails} object containing the matching incidents
+ *
+ * @example
+ * ```typescript
+ * // Query by bounding box (Amsterdam area)
+ * const result = await trafficIncidentDetails({
+ *   bbox: [4.728, 52.278, 5.080, 52.479]
+ * });
+ *
+ * result.incidents.forEach(incident => {
+ *   console.log(incident.properties.iconCategory);    // 'accident' | 'jam' | …
+ *   console.log(incident.properties.magnitudeOfDelay); // 'minor' | 'major' | …
+ *   console.log(incident.geometry);                    // Point or LineString
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Query up to 5 specific incidents by ID (GET)
+ * const result = await trafficIncidentDetails({
+ *   ids: ['incident-id-1', 'incident-id-2']
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Query many incident IDs — POST is used automatically when ids.length > 5
+ * const result = await trafficIncidentDetails({
+ *   ids: largeIdArray
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Filter by category and include future incidents
+ * const result = await trafficIncidentDetails({
+ *   bbox: [4.728, 52.278, 5.080, 52.479],
+ *   categoryFilter: [1, 8],           // accidents and road closures only
+ *   timeValidityFilter: ['present', 'future']
+ * });
+ * ```
+ *
+ * @see [Incident Details API Documentation](https://docs.tomtom.com/traffic-api/documentation/tomtom-orbis-maps/traffic-incidents/incident-details)
+ * @see [Incident Details Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/traffic/incident-details)
+ *
+ * @group Traffic
+ */
+export declare const trafficIncidentDetails: (params: TrafficIncidentDetailsParams, customTemplate?: Partial<TrafficIncidentDetailsTemplate>) => Promise<TrafficIncidentDetails>;
+
+/**
+ * Base parameters shared by all Traffic Incident Details query modes.
+ *
+ * @group Traffic
+ */
+declare type TrafficIncidentDetailsBaseParams = CommonServiceParams & {
+    /**
+     * Traffic Model ID used to obtain consistent traffic data.
+     *
+     * @remarks
+     * The Traffic Model ID is obtained from the Traffic Flow service and
+     * is valid for approximately 2 minutes. Using the same ID across
+     * different traffic API calls ensures temporal consistency.
+     *
+     * @example
+     * ```typescript
+     * trafficModelId: '1234567890'
+     * ```
+     */
+    trafficModelId?: string;
+    /**
+     * Filter results to specific incident categories.
+     *
+     * @remarks
+     * Provide {@link TrafficIncidentCategory} values to include. When omitted, all categories are returned.
+     *
+     * @example
+     * ```typescript
+     * // Only accidents and road closures
+     * categoryFilter: ['accident', 'road-closed']
+     * ```
+     */
+    categoryFilter?: TrafficIncidentCategory[];
+    /**
+     * Filter incidents by their temporal validity.
+     *
+     * @remarks
+     * - `'present'`: Only return currently active incidents
+     * - `'future'`: Only return scheduled or predicted incidents
+     *
+     * When omitted, only `'present'` incidents are returned.
+     *
+     * @example
+     * ```typescript
+     * // Include both present and future incidents
+     * timeValidityFilter: ['present', 'future']
+     * ```
+     */
+    timeValidityFilter?: TrafficIncidentTimeValidity[];
+};
+
+/**
+ * Parameters for fetching incidents within a bounding box.
+ *
+ * @remarks
+ * The bounding box must cover an area no larger than 10,000 km².
+ * Coordinates follow GeoJSON order: `[minLon, minLat, maxLon, maxLat]`.
+ *
+ * @example
+ * ```typescript
+ * // Amsterdam area
+ * const params: TrafficIncidentDetailsByBBoxParams = {
+ *   bbox: [4.728, 52.278, 5.080, 52.479]
+ * };
+ * ```
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentDetailsByBBoxParams = TrafficIncidentDetailsBaseParams & {
+    /**
+     * Bounding box to query for incidents.
+     *
+     * Format: `[minLon, minLat, maxLon, maxLat]` (GeoJSON order).
+     * Maximum area: 10,000 km².
+     */
+    bbox: BBox;
+    ids?: never;
+};
+
+/**
+ * Parameters for fetching specific incidents by their IDs.
+ *
+ * The HTTP method is chosen automatically: GET for up to 5 IDs, POST for more.
+ *
+ * @example
+ * ```typescript
+ * // Up to 5 IDs — sent as GET
+ * const params: TrafficIncidentDetailsByIdsParams = {
+ *   ids: ['incident-id-1', 'incident-id-2']
+ * };
+ *
+ * // More than 5 IDs — sent as POST automatically
+ * const params: TrafficIncidentDetailsByIdsParams = {
+ *   ids: manyIds
+ * };
+ * ```
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentDetailsByIdsParams = TrafficIncidentDetailsBaseParams & {
+    /**
+     * List of incident IDs to fetch.
+     *
+     * @remarks
+     * Up to 5 IDs are sent via GET; more than 5 are sent via POST (maximum 100).
+     */
+    ids: string[];
+    bbox?: never;
+};
+
+/**
+ * Parameters for the Traffic Incident Details service.
+ *
+ * Provide either a `bbox` to search within an area, or a list of `ids` to
+ * look up specific incidents.
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentDetailsParams = TrafficIncidentDetailsByBBoxParams | TrafficIncidentDetailsByIdsParams;
+
+declare type TrafficIncidentDetailsPostBody = {
+    ids: string[];
+};
+
+declare type TrafficIncidentDetailsPostBody_2 = {
+    ids: string[];
+};
+
+/**
+ * Traffic Incident Details service template type.
+ * @ignore
+ */
+declare type TrafficIncidentDetailsTemplate = ServiceTemplate<TrafficIncidentDetailsParams, FetchInput<TrafficIncidentDetailsPostBody_2>, IncidentDetailsResponseAPI, TrafficIncidentDetails>;
+
 /**
  * Traffic consideration mode for route calculation.
  *