@magicx-eng/ai-autocomplete-vanilla 0.32.2 → 0.33.0

package/README.md

@@ -647,6 +647,7 @@ unsub();
 | `removeLastParam()` | Remove the last completed param from state. The text stays in the input as plain text. |
 | `clearNewParamId()` | Clear shimmer animation state. |
 | `reset()` | Clear all state, re-fetch initial suggestions, and start a new session (rotates `session_id`). Call this after handling submit. |
+| `recordSubmit(result)` | Record a submit from a button you render. Enter and the built-in button are recorded for you; call this once per submit from your own button. |
 | `setValue(text)` | Set text (controlled mode). |
 | `setCompletedParams(params)` | Set completed params (controlled mode). |
 | `setMode(mode)` | Switch color mode at runtime. |
@@ -982,6 +983,12 @@ const ac = new AIAutocomplete(container, {
 });
 ```
 
+### Visitor id and submits
+
+Pass `visitorId` to tie searches to what the same visitor does later: a UUID v4 you keep across page loads (for example a first-party cookie), or a function that returns one. A function is called only when the id is needed, so it is safe to create the id lazily inside it.
+
+Submits from Enter and from the built-in submit button are recorded for you. If you render your own submit button (Tier 2 or 3), call `recordSubmit(result)` from it, once per submit, with the result you pass to your own submit handler.
+
 ## Option Overrides
 
 Supply the options for a parameter yourself instead of taking the server's. Each entry is keyed by the suggestion `type` and is a function of the phrase the user has typed for that parameter:

package/dist/index.d.mts

@@ -109,6 +109,8 @@ interface AutocompleteResponse {
     meta: {
         request_id: string;
         request_at: string;
+        /** The server's funnel-telemetry switch. Absent means off: send no funnel events. */
+        funnel_telemetry?: boolean;
     };
 }
 /** Comparison an {@link ExpressedFilter} applies to its value. */
@@ -880,6 +882,16 @@ interface CoreOptions {
      * parameters and options to them.
      */
     additionalContext?: Record<string, unknown>;
+    /**
+     * Stable id for this visitor, kept by the host across page loads (e.g. a
+     * first-party cookie). Rides on funnel telemetry so searches can be joined
+     * to what the visitor does afterwards. Must be a UUID v4; omit to send none.
+     *
+     * A function is called only once the server has switched funnel telemetry
+     * on, so a host that creates the id lazily (sets a cookie) creates nothing
+     * while it is off.
+     */
+    visitorId?: string | (() => string | undefined);
     columns?: number;
     /** Where pills render in "full" mode. Default: "dropdown". Ignored in "dropdown" mode (always in dropdown). */
     pillPlacement?: "inline" | "dropdown" | "hidden";
@@ -1064,6 +1076,19 @@ declare class AIAutocomplete {
     private subscriberCount;
     private emitter;
     private sessionId;
+    /** The /suggest request whose response is on screen; telemetry echoes it. */
+    private lastRequestId;
+    /** Session that already sent `search_started`, so it fires once per session. */
+    private searchStartedSessionId;
+    /**
+     * The server's funnel-telemetry switch, from the latest response's meta.
+     * `null` until a response says; no funnel event goes out before that.
+     */
+    private funnelTelemetry;
+    /** A `search_started` that happened before any response said whether to send it. */
+    private pendingSearchStarted;
+    /** What the last `impression` showed, so an identical response doesn't resend it. */
+    private lastImpressionKey;
     private readonly emitSubmit;
     private readonly emitError;
     constructor(container: HTMLElement, opts?: CoreOptions);
@@ -1174,6 +1199,12 @@ declare class AIAutocomplete {
      * highlight the keyboard has since moved elsewhere is left alone.
      */
     clearHighlight(index: number): void;
+    /**
+     * Records a submit in telemetry. The SDK does this itself when it runs the
+     * submit (Enter, or Tier 1's button); call it only from a submit path you
+     * own — a button you render — so each submit is counted once.
+     */
+    recordSubmit(result: AutocompleteResult): void;
     /**
      * Announce a product selection. The rendered cards call this on activation;
      * headless consumers rendering their own strip call it themselves.
@@ -1252,7 +1283,13 @@ declare class AIAutocomplete {
     update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
+    private resolveVisitorId;
     private resolveSource;
+    /**
+     * Records what a response put on screen: pills and their options in display
+     * order, and the product cards. Positions are 1-based array order.
+     */
+    private fireImpression;
     private fireTelemetry;
     private setupContainer;
     private buildAndRenderFull;

package/dist/index.d.ts

@@ -109,6 +109,8 @@ interface AutocompleteResponse {
     meta: {
         request_id: string;
         request_at: string;
+        /** The server's funnel-telemetry switch. Absent means off: send no funnel events. */
+        funnel_telemetry?: boolean;
     };
 }
 /** Comparison an {@link ExpressedFilter} applies to its value. */
@@ -880,6 +882,16 @@ interface CoreOptions {
      * parameters and options to them.
      */
     additionalContext?: Record<string, unknown>;
+    /**
+     * Stable id for this visitor, kept by the host across page loads (e.g. a
+     * first-party cookie). Rides on funnel telemetry so searches can be joined
+     * to what the visitor does afterwards. Must be a UUID v4; omit to send none.
+     *
+     * A function is called only once the server has switched funnel telemetry
+     * on, so a host that creates the id lazily (sets a cookie) creates nothing
+     * while it is off.
+     */
+    visitorId?: string | (() => string | undefined);
     columns?: number;
     /** Where pills render in "full" mode. Default: "dropdown". Ignored in "dropdown" mode (always in dropdown). */
     pillPlacement?: "inline" | "dropdown" | "hidden";
@@ -1064,6 +1076,19 @@ declare class AIAutocomplete {
     private subscriberCount;
     private emitter;
     private sessionId;
+    /** The /suggest request whose response is on screen; telemetry echoes it. */
+    private lastRequestId;
+    /** Session that already sent `search_started`, so it fires once per session. */
+    private searchStartedSessionId;
+    /**
+     * The server's funnel-telemetry switch, from the latest response's meta.
+     * `null` until a response says; no funnel event goes out before that.
+     */
+    private funnelTelemetry;
+    /** A `search_started` that happened before any response said whether to send it. */
+    private pendingSearchStarted;
+    /** What the last `impression` showed, so an identical response doesn't resend it. */
+    private lastImpressionKey;
     private readonly emitSubmit;
     private readonly emitError;
     constructor(container: HTMLElement, opts?: CoreOptions);
@@ -1174,6 +1199,12 @@ declare class AIAutocomplete {
      * highlight the keyboard has since moved elsewhere is left alone.
      */
     clearHighlight(index: number): void;
+    /**
+     * Records a submit in telemetry. The SDK does this itself when it runs the
+     * submit (Enter, or Tier 1's button); call it only from a submit path you
+     * own — a button you render — so each submit is counted once.
+     */
+    recordSubmit(result: AutocompleteResult): void;
     /**
      * Announce a product selection. The rendered cards call this on activation;
      * headless consumers rendering their own strip call it themselves.
@@ -1252,7 +1283,13 @@ declare class AIAutocomplete {
     update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
+    private resolveVisitorId;
     private resolveSource;
+    /**
+     * Records what a response put on screen: pills and their options in display
+     * order, and the product cards. Positions are 1-based array order.
+     */
+    private fireImpression;
     private fireTelemetry;
     private setupContainer;
     private buildAndRenderFull;