@tomtom-org/maps-sdk-plugin-agent-toolkit 0.4.3 → 0.5.0

package/dist/index.d.ts

@@ -83,6 +83,11 @@ export declare type AffectedEntry = {
     kind: 'places' | 'customGeometries';
 };
 
+/**
+ * @module agent-toolkit-tools
+ */
+export declare const AGENT_TOOLKIT_USER_AGENT = "AgentToolkit";
+
 /**
  * Canonical ordering for {@link EntryDataKind}. Used wherever per-kind doc fragments or
  * field lists are concatenated — keeps the layout stable regardless of the order kinds
@@ -2077,7 +2082,7 @@ export declare const locationInputSchema: z.ZodUnion<readonly [z.ZodObject<{
         lat: z.ZodNumber;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
-    placeId: z.ZodString;
+    placeIdOrEntryId: z.ZodString;
 }, z.core.$strip>]>;
 
 /**
@@ -3920,7 +3925,15 @@ export declare type ToolEntry<S extends ToolState = ToolState, Scope = unknown>
     inputSchema: z.ZodType;
     /** Optional Zod schema describing the tool's structured output. */
     outputSchema?: z.ZodType;
-    /** Function that executes the tool. Receives parsed input and the agent's state. */
+    /**
+     * Function that executes the tool. Receives parsed input and the agent's state.
+     *
+     * If this calls a `@tomtom-org/maps-sdk/services` function directly, wrap its params with
+     * `withAgentToolkitHeaders` (`tools/shared/agent-headers.ts`) before passing them in — e.g.
+     * `const requestParams = withAgentToolkitHeaders({ position }); await reverseGeocode(requestParams);`.
+     * This tags the request so TomTom's traffic analytics attribute it to agent-toolkit; an
+     * untagged call is picked up by the guard test in `tools/shared/tests/agent-headers.test.ts`.
+     */
     execute: (input: any, state: S) => Promise<any>;
     /** Compact one-liner for the intent classifier prompt. */
     classificationPrompt?: string;
@@ -4674,6 +4687,18 @@ export declare const whereSchema: z.ZodUnion<readonly [z.ZodObject<{
     mode: z.ZodLiteral<"global">;
 }, z.core.$strip>]>;
 
+/**
+ * Tags an SDK service call as coming from agent-toolkit, via the SDK's own supported per-call
+ * `tomtom-user-agent` override (see `generateTomTomHeaders`, `core/src/util/headers.ts`) — reuses
+ * an existing, already-allow-listed header rather than adding a new one.
+ *
+ * Not applicable to `searchOne`/`geocodeOne` (and the `searchOneFn`/`geocodeOneFn` dispatch in
+ * `locate-places.ts`) — those take a bare query string with no params object to tag.
+ *
+ * @ignore
+ */
+export declare const withAgentToolkitHeaders: <P extends object>(params: P) => P;
+
 /**
  * Fields shared by both locatePlace's and discoverPlaces' `within` schemas — `mode` and the
  * `viewport` flag. Spread into each consumer's `z.object({...})`.