@tomtom-org/maps-sdk-plugin-agent-toolkit 0.10.0 → 0.10.1

package/README.md

@@ -556,3 +556,7 @@ For the complete, always-current list of exports — factories, tool-registry he
 - [AI SDK v6 documentation](https://ai-sdk.dev/)
 - [TomTom Maps SDK documentation](https://docs.tomtom.com/maps-sdk-js)
 - [Example application](../../examples/map-traffic-agent-react) — full chat interface implementation
+
+## License
+
+See `LICENSE.txt`.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { BaseMapModule, CustomGeoJSONLayerSpec, CustomGeoJSONModule, GeometriesModule, GeometryFillStyle, POIsModule, PlaceConnectionDisplay, PlacesModule, PlanningWaypoint, RoutingModule, StylingModule, TomTomMap, TrafficAreaAnalyticsModule, TrafficAreaAnalyticsModuleConfig, TrafficFlowModule, TrafficIncidentOverlayModule, TrafficIncidentsModule } from "@tomtom-org/maps-sdk/map";
-import { BBox, CommonPlaceProps, GeographyType, POICategory, Place, Places, PolygonFeature, PolygonFeatures, Route, Routes, TrafficAreaAnalytics, TrafficIncident, WaypointLike } from "@tomtom-org/maps-sdk/core";
+import { BBox, CommonPlaceProps, GeographyType, Place, Places, PolygonFeature, PolygonFeatures, Route, Routes, TrafficAreaAnalytics, TrafficIncident, WaypointLike } from "@tomtom-org/maps-sdk/core";
 import { ChartConfiguration } from "chart.js";
 import { Map as Map$1 } from "maplibre-gl";
 import { z } from "zod";
@@ -1141,7 +1141,7 @@ type PlacesAnalysis = EntryAnalysis;
 //#region src/state/places/state.d.ts
 /**
  * The marker looks an entry can be rendered with: individual pins, base-map POIs, or clustered
- * pins. A type-checked subset of the SDK's {@link PlacesTheme} — `circle-icon` is not offered to
+ * pins. A type-checked subset of the SDK's `PlacesMarkerType` — `circle-icon` is not offered to
  * the agent. Every tool enum for marker types derives from this array rather than repeating it.
  */
 declare const placesMarkerTypes: readonly ["pin", "base-map", "pin-clustered"];
@@ -1177,10 +1177,10 @@ type PlacesStateEvents = {
  * State for the places layer: an append-only history of place results plus per-entry display
  * modules.
  *
- * Each entry owns a single PlacesModule (rethemed in-place via `applyTheme` when the marker
- * type changes — an entry only renders under one theme at a time) and a dedicated
+ * Each entry owns a single PlacesModule (switched in place via `applyMarkerType` when the marker
+ * type changes — an entry only renders under one marker type at a time) and a dedicated
  * GeometriesModule, lazy-initialised on first show. Display state lives on the entry, so two
- * entries can be rendered side by side under different themes without sharing a single source.
+ * entries can be rendered side by side under different marker types without sharing a single source.
  *
  * @group Agent Toolkit
  */
@@ -1204,9 +1204,9 @@ declare class PlacesState implements StateSlice {
    */
   setEntryMode(mode: EntryMode): Promise<void>;
   /**
-   * Lazy-init and return the entry's PlacesModule, rethemed to `markerType`. An entry only
-   * ever renders under one theme at a time, so the same module is reused — flipping themes
-   * calls `applyTheme` in place. Throws when the entry id is unknown.
+   * Lazy-init and return the entry's PlacesModule, switched to `markerType`. An entry only
+   * ever renders under one marker type at a time, so the same module is reused — flipping marker
+   * types calls `applyMarkerType` in place. Throws when the entry id is unknown.
    */
   getEntryPlacesModule(entryId: string, markerType: PlacesMarkerType): Promise<PlacesModule>;
   /**
@@ -1283,8 +1283,8 @@ declare class PlacesState implements StateSlice {
   setShownEntries(ids: readonly string[], markerType: PlacesMarkerType): Promise<Place[]>;
   /**
    * Add ids to the shown set under `markerType`. Any id previously shown as
-   * a different marker type is moved (its previous module is cleared, the
-   * new theme's module renders).
+   * a different marker type is moved (its module switches to the new
+   * marker type).
    *
    * Under `entryMode === 'single'` everything else is hidden first, so the
    * effective behaviour collapses to "show exactly the last id in the list".
@@ -1301,7 +1301,7 @@ declare class PlacesState implements StateSlice {
   clearShown(): Promise<void>;
   clearShownGeometries(ids?: readonly string[]): Promise<void>;
   /**
-   * Drop a single entry from history. Hides it from the map first (clears every theme module
+   * Drop a single entry from history. Hides it from the map first (clears every module
    * it owns) then removes it from `_entries`. Emits `entries-change` and, when the entry was
    * shown, `shown-change`. No-op when the id is unknown.
    */
@@ -1334,8 +1334,8 @@ type PlacesEntry = BaseEntry<Place[]> & {
   /** Lazy place-id → boundary polygon index, built on first lookup through PlacesState.getGeometryForPlace. */
   _geometryByPlaceId?: Record<string, PolygonFeature<CommonPlaceProps>>;
   /**
-   * Per-entry display modules. An entry is rendered under at most one marker theme at a time,
-   * so a single PlacesModule covers all themes — `_showEntryAs` rethemes it via `applyTheme`.
+   * Per-entry display modules. An entry is rendered under at most one marker type at a time,
+   * so a single PlacesModule covers all of them — `_showEntryAs` switches it via `applyMarkerType`.
    * A dedicated GeometriesModule renders the entry's boundary polygons.
    * Lazy-initialised via PlacesState helpers — undefined until first show.
    */
@@ -1343,7 +1343,7 @@ type PlacesEntry = BaseEntry<Place[]> & {
     places?: PlacesModule;
     geometries?: GeometriesModule;
   };
-  /** The marker theme currently rendering this entry, or undefined when hidden. */
+  /** The marker type currently rendering this entry, or undefined when hidden. */
   _shownAs?: PlacesMarkerType;
 };
 //#endregion
@@ -2567,6 +2567,12 @@ declare class TrafficTilesState implements StateSlice {
 export declare const hidePreviousShownEntries: (slice: ShownEntriesSlice, keepEntryIds: readonly string[], selector: "all" | readonly string[] | undefined) => Promise<void>;
 //#endregion
 //#region src/tools/shared/locate-places.d.ts
+/**
+ * How {@link locatePlace} resolves a query: `'poi'` searches points of interest by name, `'place'` geocodes
+ * an address or an area.
+ *
+ * @group Agent Toolkit
+ */
 export type QueryAs = 'poi' | 'place';
 /**
  * Resolves a query string to up to `limit` Places. POI search when `queryAs === 'poi'`, geocoding
@@ -2576,7 +2582,25 @@ export declare const locatePlaces: (query: string, queryAs: QueryAs, options: {
   limit: number;
   bias?: GeoBias;
 }, execOptions?: ToolExecuteOptions) => Promise<Place[]>;
-/** Convenience wrapper around {@link locatePlaces} for the single-result case. */
+/**
+ * The best match for a query, as the `locatePlace` tool resolves it, for a custom tool that needs one place.
+ * A failed or cancelled request rejects, so catch it in `execute`.
+ *
+ * @param bias - Favours results near a position, such as the map centre from {@link getViewportBias}.
+ * @param execOptions - The `execute` options, whose `signal` cancels the request with the turn.
+ * @returns The first match, or `null` when nothing matches.
+ *
+ * @example
+ * ```ts
+ * execute: async ({ name }, state, options) => {
+ *     const position = getViewportBias(state.baseMap);
+ *     const place = await locatePlace(name, 'poi', position && { position }, options);
+ *     // ...
+ * },
+ * ```
+ *
+ * @group Agent Toolkit
+ */
 export declare const locatePlace: (query: string, queryAs: QueryAs, bias?: GeoBias, execOptions?: ToolExecuteOptions) => Promise<Place | null>;
 //#endregion
 //#region src/tools/shared/location-input.d.ts
@@ -2876,25 +2900,6 @@ export declare const buildPlacesSchemaDoc: (_flags: FeatureFlags) => string;
  */
 export declare const PLACES_SCHEMA_DOC: string;
 //#endregion
-//#region src/tools/shared/resolve-poi-categories.d.ts
-/** Outcome of {@link resolvePoiCategories}. @ignore */
-export type ResolvedPoiCategories = {
-  /** Final search filter — known codes plus codes resolved from natural-language synonyms. */
-  resolved: POICategory[] | undefined;
-  /** Inputs that matched neither an exact code nor any synonym. */
-  unresolved: string[];
-};
-/**
- * Resolve a mixed list of POI inputs to canonical {@link POICategory} codes.
- *
- * Each input is either an exact catalog code (kept as-is) or a natural-language term that is
- * resolved via the POI categories service. Inputs that produce zero matches are reported in
- * `unresolved` so callers can surface a precise error.
- *
- * @ignore
- */
-export declare const resolvePoiCategories: (poiCategories: string[] | undefined, options?: ToolExecuteOptions) => Promise<ResolvedPoiCategories>;
-//#endregion
 //#region src/tools/shared/resolve-range.d.ts
 export declare const getRangePolygons: (state: ToolState, rangeId: string) => {
   polygons: (Polygon | MultiPolygon)[];
@@ -3324,9 +3329,21 @@ export declare const showResultsOnMap: (state: ToolState, placesEntryIds: readon
 export declare const toolStateToWhereContext: (state: ToolState, options?: ToolExecuteOptions) => WhereContext;
 //#endregion
 //#region src/tools/shared/viewport-bias.d.ts
-/** @ignore */
+/**
+ * Lowest zoom at which {@link getViewportBias} returns the map centre.
+ *
+ * @group Agent Toolkit
+ */
 export declare const MIN_VIEWPORT_BIAS_ZOOM = 6;
-/** @ignore */
+/**
+ * The map centre, to favour search results in view: pass it as `{ position }` to a service's `geoBias` or to
+ * {@link locatePlace}'s `bias`. Below `minZoom` the view spans too wide an area to say where the user means.
+ *
+ * @param map - The agent's base-map slice, `state.baseMap` in a tool's `execute`.
+ * @returns The centre as `[longitude, latitude]`, or `undefined` below `minZoom`.
+ *
+ * @group Agent Toolkit
+ */
 export declare const getViewportBias: (map: BaseMapState, minZoom?: number) => Position | undefined;
 /** @ignore */
 export declare const getViewportBoundingBox: (map: BaseMapState) => BBox;