@tomtom-org/maps-sdk 0.56.0 → 0.57.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tomtom-org/maps-sdk",
   "author": "TomTom International B.V.",
   "license": "See in LICENSE.txt",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "TomTom maps, search, geocoding, routing, isochrones, EV and traffic for JavaScript — typed GeoJSON services and a MapLibre GL JS map.",
   "homepage": "https://docs.tomtom.com/maps-sdk-js/introduction/overview",
   "repository": {

package/services/dist/index.d.ts

@@ -3186,7 +3186,7 @@ type SummaryQueryType = 'NEARBY' | 'NON_NEAR';
  * });
  *
  * const summary = results.summary;
- * console.log(`Found ${summary.totalResults} total results`);
+ * console.log(`Found ${summary.totalResults ?? 'an unknown number of'} total results`);
  * console.log(`Showing ${summary.numResults} results`);
  * console.log(`Query type: ${summary.queryType}`); // 'NEARBY'
  * console.log(`Search took ${summary.queryTime}ms`);
@@ -3233,7 +3233,8 @@ export type SearchSummary = {
    * Number of results included in this response.
    *
    * This is the actual count of features in the results array,
-   * which may be less than `totalResults` due to pagination limits.
+   * which may be less than `totalResults` due to pagination limits. Unlike `totalResults` this
+   * is always present — it is the length of the array you were given.
    *
    * @remarks
    * Controlled by the `limit` parameter in the search request.
@@ -3275,10 +3276,11 @@ export type SearchSummary = {
    * regardless of pagination limits.
    *
    * @remarks
-   * Use this with `offset` and `numResults` to implement pagination:
+   * Optional — a total is not guaranteed, so guard it rather than assuming a number. Where it
+   * is present, use it with `offset` and `numResults` to paginate:
    * - Current page: `offset / limit + 1`
-   * - Total pages: `Math.ceil(totalResults / limit)`
-   * - Has more results: `offset + numResults < totalResults`
+   * - Total pages: `totalResults === undefined ? undefined : Math.ceil(totalResults / limit)`
+   * - Has more results: `totalResults !== undefined && offset + numResults < totalResults`
    *
    * @example
    * ```typescript
@@ -3289,7 +3291,7 @@ export type SearchSummary = {
    * // Can fetch more with offset: 10, 20, 30, 40
    * ```
    */
-  totalResults: number;
+  totalResults?: number;
   /**
    * Maximum fuzzy matching level used to find results.
    *
@@ -3306,6 +3308,9 @@ export type SearchSummary = {
    * If results are found with exact or near-exact matching, this will be low.
    * If the query has typos, this increases to find matches.
    *
+   * Optional — where match strictness is not reported the field is absent rather than `0`, so
+   * read a missing value as "not reported" rather than as an exact match.
+   *
    * @example
    * ```typescript
    * // Query: "amstrdam" (typo)
@@ -3315,7 +3320,7 @@ export type SearchSummary = {
    * fuzzyLevel: 0  // Exact match, no fuzzy matching needed
    * ```
    */
-  fuzzyLevel: number;
+  fuzzyLevel?: number;
   /**
    * Geographic position used to bias search results.
    *
@@ -3436,9 +3441,17 @@ type AddressRangesAPI = {
   to: LatLonAPI;
 };
 /**
+ * The summary envelope as the places endpoints send it.
+ *
+ * @remarks
+ * Derived from {@link SearchSummary}, but `totalResults` and `fuzzyLevel` are pinned back to
+ * required here. They are optional on the public type so that consumers guard them; the endpoints
+ * we call always send them, and this type is what asserts that. Relaxing it would let a parser
+ * silently stop populating them.
+ *
  * @ignore
  */
-type SummaryAPI$1 = Omit<SearchSummary, 'geoBias'> & {
+type SummaryAPI$1 = Omit<SearchSummary, 'geoBias'> & Required<Pick<SearchSummary, 'totalResults' | 'fuzzyLevel'>> & {
   geoBias?: LatLonAPI;
 };
 /**
@@ -4033,7 +4046,7 @@ type AutocompleteSearchSegmentType = 'brand' | 'category' | 'plaintext';
  *
  * @group Autocomplete Search
  */
-type AutocompleteSearchParams = CommonServiceParams<URL, AutocompleteSearchResponseAPI> & {
+type AutocompleteSearchParams = CommonServiceParams<GetObject, AutocompleteSearchResponseAPI> & {
   /**
    * Search query string (partial user input).
    *
@@ -4131,7 +4144,7 @@ type AutocompleteSearchParams = CommonServiceParams<URL, AutocompleteSearchRespo
  * Autocomplete service template type.
  * @ignore
  */
-type AutocompleteSearchTemplate = ServiceTemplate<AutocompleteSearchParams, URL, AutocompleteSearchResponseAPI, AutocompleteSearchResponse>;
+type AutocompleteSearchTemplate = ServiceTemplate<AutocompleteSearchParams, GetObject, AutocompleteSearchResponseAPI, AutocompleteSearchResponse>;
 //#endregion
 //#region src/autocomplete-search/autocompleteSearch.d.ts
 /**
@@ -4220,7 +4233,7 @@ declare const customize$11: {
  * Default function for building autocomplete request from {@link AutocompleteSearchParams}
  * @param params The autocomplete parameters, with global configuration already merged into them.
  */
-declare const buildAutocompleteSearchRequest: (params: AutocompleteSearchParams) => URL;
+declare const buildAutocompleteSearchRequest: (params: AutocompleteSearchParams) => GetObject;
 //#endregion
 //#region src/autocomplete-search/responseParser.d.ts
 /**
@@ -4333,6 +4346,13 @@ type EVChargingStationsAvailabilityTemplate = ServiceTemplate<ChargingStationsAv
 /**
  * Default method for building ev charging stations availability request from {@link ChargingStationsAvailabilityParams}
  * @param params The charging availability parameters, with global configuration already merged into them.
+ *
+ * @remarks
+ * Unlike the other places services, this one keeps `key=` and `apiVersion=` in the query string.
+ * `/maps/orbis/places/ev/id` answers 401 to a header-only credential, while `search`,
+ * `poiCategories`, `geocode`, `place` and `additionalData` all accept one — probed against
+ * production. Moving this one to headers breaks it outright rather than subtly, so it stays until
+ * the endpoint catches up.
  */
 declare const buildEVChargingStationsAvailabilityRequest: (params: ChargingStationsAvailabilityParams) => URL;
 //#endregion
@@ -4462,7 +4482,7 @@ type GeocodingIndexTypesAbbreviation = Exclude<SearchIndexType, 'POI'>;
  *
  * @group Geocoding
  */
-type GeocodingParams = Omit<CommonPlacesParams<URL, GeocodingResponseAPI> & CommonGeocodeAndFuzzySearchParams, 'extendedPostalCodesFor'> & {
+type GeocodingParams = Omit<CommonPlacesParams<GetObject, GeocodingResponseAPI> & CommonGeocodeAndFuzzySearchParams, 'extendedPostalCodesFor'> & {
   /**
    * Address or location query to geocode.
    *
@@ -4522,14 +4542,14 @@ type GeocodingParams = Omit<CommonPlacesParams<URL, GeocodingResponseAPI> & Comm
  * Geocoding service template type.
  * @ignore
  */
-type GeocodingTemplate = ServiceTemplate<GeocodingParams, URL, GeocodingResponseAPI, GeocodingResponse>;
+type GeocodingTemplate = ServiceTemplate<GeocodingParams, GetObject, GeocodingResponseAPI, GeocodingResponse>;
 //#endregion
 //#region src/geocode/requestBuilder.d.ts
 /**
  * Default method for building geocoding request from {@link GeocodingParams}
  * @param params The geocoding parameters, with global configuration already merged into them.
  */
-declare const buildGeocodingRequest: (params: GeocodingParams) => URL;
+declare const buildGeocodingRequest: (params: GeocodingParams) => GetObject;
 //#endregion
 //#region src/geocode/responseParser.d.ts
 /**
@@ -4584,7 +4604,7 @@ type GeometriesInput = string[];
  *
  * @group Geometry
  */
-type CommonServiceParamsWithZoom = CommonServiceParams<URL, GeometryDataResponseAPI> & {
+type CommonServiceParamsWithZoom = CommonServiceParams<GetObject, GeometryDataResponseAPI> & {
   /**
    * Optional zoom level for geometry detail.
    *
@@ -4738,14 +4758,14 @@ type GeometryParams = GeometryDataParams | GeometryPlaceParams;
 /**
  * @ignore
  */
-type GeometryDataTemplate = ServiceTemplate<GeometryParams, URL, GeometryDataResponseAPI, PolygonFeatures>;
+type GeometryDataTemplate = ServiceTemplate<GeometryParams, GetObject, GeometryDataResponseAPI, PolygonFeatures>;
 //#endregion
 //#region src/geometry-data/requestBuilder.d.ts
 /**
  * Default function for building a geometry data request from {@link GeometryDataParams}
  * @param params The geometry data parameters, with global configuration already merged into them.
  */
-declare const buildGeometryDataRequest: (params: GeometryParams) => URL;
+declare const buildGeometryDataRequest: (params: GeometryParams) => GetObject;
 //#endregion
 //#region src/geometry-data/responseParser.d.ts
 /**
@@ -5339,7 +5359,7 @@ type PlaceByIdMandatoryParams = {
  *
  * @group Place
  */
-type PlaceByIdParams = CommonServiceParams<URL, PlaceByIdResponseAPI> & PlaceByIdMandatoryParams & PlaceByIdOptionalParams;
+type PlaceByIdParams = CommonServiceParams<GetObject, PlaceByIdResponseAPI> & PlaceByIdMandatoryParams & PlaceByIdOptionalParams;
 //#endregion
 //#region src/place-by-id/types/placeByIdResponse.d.ts
 /**
@@ -5361,14 +5381,14 @@ type PlaceByIdResponse = Place<SearchPlaceProps> | undefined;
  * Place By Is template type.
  * @ignore
  */
-type PlaceByIdTemplate = ServiceTemplate<PlaceByIdParams, URL, PlaceByIdResponseAPI, PlaceByIdResponse>;
+type PlaceByIdTemplate = ServiceTemplate<PlaceByIdParams, GetObject, PlaceByIdResponseAPI, PlaceByIdResponse>;
 //#endregion
 //#region src/place-by-id/requestBuilder.d.ts
 /**
  * Default method for building place by id request from {@link PlaceByIdParams}
  * @param params The place by id parameters, with global configuration already merged into them.
  */
-declare const buildPlaceByIdRequest: (params: PlaceByIdParams) => URL;
+declare const buildPlaceByIdRequest: (params: PlaceByIdParams) => GetObject;
 //#endregion
 //#region src/place-by-id/responseParser.d.ts
 /**
@@ -7552,16 +7572,23 @@ declare const customize: {
  *
  * @example
  * ```typescript
- * import { mergeFromGlobal } from '@tomtom-org/maps-sdk/core';
+ * import { isProxyCredentialsMode, mergeFromGlobal } from '@tomtom-org/maps-sdk/core';
  * import { customizeService } from '@tomtom-org/maps-sdk/services';
  *
  * const { buildGeocodingRequest, parseGeocodingResponse } = customizeService.geocode;
  *
  * // Request builders expect the global configuration to be merged in already
- * const url = buildGeocodingRequest(mergeFromGlobal({ query: 'Amsterdam' }));
- *
- * // Send the request yourself, then parse the raw API payload
- * const apiResponse = await fetch(url);
+ * const config = mergeFromGlobal({ query: 'Amsterdam' });
+ * const { url, headers } = buildGeocodingRequest(config);
+ *
+ * // Send the request yourself, then parse the raw API payload. The credential travels in
+ * // `headers` — pass them on, or the request is unauthenticated. With a credentials proxy
+ * // (no `apiKey`, custom `commonBaseURL`) the proxy's session cookie has to travel instead,
+ * // so send `credentials: 'include'` the way the SDK's own fetch does.
+ * const apiResponse = await fetch(url, {
+ *     headers,
+ *     ...(isProxyCredentialsMode(config) && { credentials: 'include' }),
+ * });
  * const places = parseGeocodingResponse(await apiResponse.json());
  * ```
  *
@@ -7949,7 +7976,7 @@ type PoiCategoriesResponseAPI = {
  *
  * @group POI Categories
  */
-type POICategoriesParams = CommonServiceParams<URL, PoiCategoriesResponseAPI> & {
+type POICategoriesParams = CommonServiceParams<GetObject, PoiCategoriesResponseAPI> & {
   /**
    * One or more filter strings applied client-side against the text index.
    *
@@ -8344,8 +8371,12 @@ type FuzzySearchFeatureCollectionProps = SearchSummary & {
    *
    * Indicates how the search engine interpreted the query
    * (e.g., as coordinates, nearby search, what3words, or bookmark).
+   *
+   * @remarks
+   * Optional — query-intent detection is not guaranteed, so guard it rather than assuming it is
+   * present.
    */
-  queryIntent: QueryIntent[];
+  queryIntent?: QueryIntent[];
 };
 /**
  * Union type for all possible query intents.
@@ -8533,7 +8564,7 @@ type FuzzySearchResponseAPI = {
    * Summary information about the search that was performed.
    */
   summary: SummaryAPI$1 & {
-    queryIntent: QueryIntentAPI[];
+    queryIntent?: QueryIntentAPI[];
   };
   /**
    * The result list, sorted in descending order by score.
@@ -8640,7 +8671,7 @@ type NearbyIntentDetailsAPI = Omit<NearbyIntentDetails, 'position'> & {
  *
  * @group Search
  */
-type FuzzySearchParams = CommonSearchParams<URL, FuzzySearchResponseAPI> & CommonGeocodeAndFuzzySearchParams & {
+type FuzzySearchParams = CommonSearchParams<GetObject, FuzzySearchResponseAPI> & CommonGeocodeAndFuzzySearchParams & {
   /**
    * Minimum fuzziness level to be used.
    *
@@ -8698,7 +8729,7 @@ type FuzzySearchParams = CommonSearchParams<URL, FuzzySearchResponseAPI> & Commo
  * Fuzzy search service template type.
  * @ignore
  */
-type FuzzySearchTemplate = ServiceTemplate<FuzzySearchParams, URL, FuzzySearchResponseAPI, FuzzySearchResponse>;
+type FuzzySearchTemplate = ServiceTemplate<FuzzySearchParams, GetObject, FuzzySearchResponseAPI, FuzzySearchResponse>;
 //#endregion
 //#region src/search/search.d.ts
 type SearchFeatureCollectionProps = SearchSummary & {