@askdialog/dialog-sdk 2.5.0 → 2.6.0

package/dist/types/searchAnalytics.d.ts

@@ -0,0 +1,30 @@
+export declare const SEARCH_SURFACES: readonly ["autocomplete", "search_page", "smart_discovery", "ai_bar"];
+export type SearchSurface = (typeof SEARCH_SURFACES)[number];
+export interface SearchAnalyticsEnvelope {
+    query_id: string;
+    /** Where results are displayed — not the integration technology. */
+    surface: SearchSurface;
+    /** 1-based results page. */
+    page: number;
+    /** Total results for the query, not for the page. */
+    total_hits: number;
+    /** Code points of the trimmed query. */
+    query_length: number;
+}
+export interface SearchResultItem {
+    product_id: string;
+    position: number;
+}
+export interface ViewSearchResultsParams extends SearchAnalyticsEnvelope {
+    items: SearchResultItem[];
+}
+export interface SelectSearchResultParams extends SearchAnalyticsEnvelope {
+    items: [SearchResultItem];
+}
+export interface ViewSearchResultsEventPayload extends ViewSearchResultsParams {
+    userId?: string;
+}
+export interface SelectSearchResultEventPayload extends SelectSearchResultParams {
+    userId?: string;
+}
+//# sourceMappingURL=searchAnalytics.d.ts.map

package/dist/types/searchAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchAnalytics.d.ts","sourceRoot":"","sources":["../../src/types/searchAnalytics.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,eAAe,uEAKlB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAQ7D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,EAAE,aAAa,CAAC;IACvB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;CACtB;AAID,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,MAAM,WAAW,uBAAwB,SAAQ,uBAAuB;IACtE,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAGD,MAAM,WAAW,wBAAyB,SAAQ,uBAAuB;IACvE,KAAK,EAAE,CAAC,gBAAgB,CAAC,CAAC;CAC3B;AAKD,MAAM,WAAW,6BAA8B,SAAQ,uBAAuB;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,8BACf,SAAQ,wBAAwB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/types/searchAnalytics.js

@@ -0,0 +1,10 @@
+// Storefront-search analytics contract (DEC-2448), snake_case end to end:
+// these property names ARE the canonical PostHog properties — the host
+// bridge forwards them verbatim (no camelCase mapping), so any rename here
+// is a breaking change of the cross-repo contract.
+export const SEARCH_SURFACES = [
+    "autocomplete",
+    "search_page",
+    "smart_discovery",
+    "ai_bar",
+];

package/dist/types/searchController.d.ts

@@ -0,0 +1,80 @@
+import { SearchHit, SearchOptions, SearchRequest, SearchResponse } from "./search";
+import { SearchSurface, SelectSearchResultParams, ViewSearchResultsParams } from "./searchAnalytics";
+export declare const SearchStatus: {
+    readonly IDLE: "idle";
+    readonly LOADING: "loading";
+    readonly SUCCESS: "success";
+    /** The request succeeded with zero hits — distinct from `success` so views render a no-results state. */
+    readonly EMPTY: "empty";
+    readonly ERROR: "error";
+};
+export type SearchStatus = (typeof SearchStatus)[keyof typeof SearchStatus];
+export interface SearchControllerState {
+    status: SearchStatus;
+    /** Last committed (run) query — not the text currently being typed. */
+    query: string;
+    /** Zero-indexed page of the last run. */
+    page: number;
+    /** Last landed response; kept while the next page loads, cleared on error. */
+    response?: SearchResponse;
+    error?: unknown;
+}
+export type SearchFunction = (request: SearchRequest, options?: SearchOptions) => Promise<SearchResponse>;
+/**
+ * Analytics sinks for the DEC-2448 storefront-search contract — wire the two
+ * track methods to the `Dialog` instance. Impressions (viewport batching,
+ * dedup, click-forced) and the zero-items no-results event are owned by the
+ * controller; integrations only declare where results are displayed.
+ */
+export interface SearchControllerAnalytics {
+    surface: SearchSurface;
+    trackViewSearchResults: (params: ViewSearchResultsParams) => void;
+    trackSelectSearchResult: (params: SelectSearchResultParams) => void;
+}
+export interface SearchControllerOptions {
+    /** The bound `dialog.search` function. */
+    search: SearchFunction;
+    analytics: SearchControllerAnalytics;
+    /**
+     * Platform navigation adapter, called by `selectResult` AFTER attribution
+     * is recorded, with the product URL of the selected hit. Omit it when the
+     * rendering layer navigates natively (plain `<a href>`): attribution still
+     * fires, the events are designed to survive navigation.
+     */
+    navigate?: (url: string, hit: SearchHit) => void;
+    debounceMs?: number;
+    hitsPerPage?: number;
+}
+/**
+ * Framework-agnostic stateful search behavior around the stateless
+ * `dialog.search()` transport: debounce, cancellation, stale-response
+ * protection, pagination, retry and DEC-2448 attribution. Rendering and
+ * routing stay in the integration (raw JavaScript, React, Vue, Shopify).
+ */
+export interface SearchController {
+    /** Debounced entry point for keystrokes. */
+    setQuery(rawQuery: string): void;
+    /** Immediate (non-debounced) submission, e.g. Enter or a search button. */
+    submit(rawQuery: string): void;
+    /** Immediate pagination of the current results (zero-indexed). */
+    setPage(page: number): void;
+    /** Re-run the failed request; no-op unless the state is `error`. */
+    retry(): void;
+    /**
+     * Watch the rendered element of `state.response.hits[index]` for a
+     * viewport impression. Call it for every result element after rendering.
+     */
+    observeResult(element: Element, index: number): void;
+    /**
+     * Record selection attribution for `state.response.hits[index]` (forced
+     * impression + select event), then hand navigation to the `navigate`
+     * adapter. Call it on click AND middle-click/cmd+click.
+     */
+    selectResult(index: number): void;
+    /** Register a state listener; returns its unsubscribe function. */
+    subscribe(listener: (state: SearchControllerState) => void): () => void;
+    getState(): SearchControllerState;
+    /** Cancel everything in flight and detach listeners/observers. */
+    dispose(): void;
+}
+//# sourceMappingURL=searchController.d.ts.map

package/dist/types/searchController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchController.d.ts","sourceRoot":"","sources":["../../src/types/searchController.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,aAAa,EACb,aAAa,EACb,cAAc,EACf,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,eAAO,MAAM,YAAY;;;;IAIvB,yGAAyG;;;CAGjG,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,YAAY,CAAC;IACrB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,CAC3B,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,aAAa,KACpB,OAAO,CAAC,cAAc,CAAC,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,aAAa,CAAC;IACvB,sBAAsB,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAClE,uBAAuB,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAC;CACrE;AAED,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,yBAAyB,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,KAAK,IAAI,CAAC;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kEAAkE;IAClE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oEAAoE;IACpE,KAAK,IAAI,IAAI,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrD;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mEAAmE;IACnE,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACxE,QAAQ,IAAI,qBAAqB,CAAC;IAClC,kEAAkE;IAClE,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/dist/types/searchController.js

@@ -0,0 +1,8 @@
+export const SearchStatus = {
+    IDLE: "idle",
+    LOADING: "loading",
+    SUCCESS: "success",
+    /** The request succeeded with zero hits — distinct from `success` so views render a no-results state. */
+    EMPTY: "empty",
+    ERROR: "error",
+};

package/dist/utils/searchControllerAnalytics.d.ts

@@ -0,0 +1,14 @@
+import { SearchResponse } from "../types/search";
+import { SearchControllerAnalytics } from "../types/searchController";
+/**
+ * Internal DEC-2448 wiring of the search controller: envelope computation,
+ * viewport impressions and selection attribution. Not part of the public API.
+ */
+export interface ControllerAnalyticsBinding {
+    onResponse(response: SearchResponse): void;
+    observeResult(element: Element, response: SearchResponse, index: number): void;
+    select(response: SearchResponse, index: number): void;
+    dispose(): void;
+}
+export declare function createControllerAnalytics(analytics: SearchControllerAnalytics): ControllerAnalyticsBinding;
+//# sourceMappingURL=searchControllerAnalytics.d.ts.map

package/dist/utils/searchControllerAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchControllerAnalytics.d.ts","sourceRoot":"","sources":["../../src/utils/searchControllerAnalytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAKjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAMtE;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAC3C,aAAa,CACX,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,MAAM,GACZ,IAAI,CAAC;IACR,MAAM,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,OAAO,IAAI,IAAI,CAAC;CACjB;AAWD,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,yBAAyB,GACnC,0BAA0B,CAkD5B"}

package/dist/utils/searchControllerAnalytics.js

@@ -0,0 +1,54 @@
+import { createSearchImpressionTracker, } from "./searchImpressions";
+const resultItem = (response, index) => ({
+    product_id: response.hits[index].product.id,
+    // 1-based and absolute across pages (page 2, first item, 20/page → 21).
+    position: response.page * response.hitsPerPage + index + 1,
+});
+export function createControllerAnalytics(analytics) {
+    let impressions;
+    let envelope;
+    // Lazy: the tracker needs window/IntersectionObserver, so a controller
+    // constructed in a non-browser context stays inert until a response lands.
+    const tracker = () => {
+        impressions ??= createSearchImpressionTracker({
+            emit: analytics.trackViewSearchResults,
+        });
+        return impressions;
+    };
+    return {
+        onResponse(response) {
+            envelope = {
+                // Straight off the response: the controller resends the previous
+                // queryId while the query text is unchanged, so the id is stable
+                // across pagination and rotates with the query.
+                query_id: response.queryId,
+                surface: analytics.surface,
+                // Analytics pages are 1-based; the wire response is 0-based.
+                page: response.page + 1,
+                total_hits: response.nbHits,
+                query_length: [...response.query].length,
+            };
+            tracker().setContext(envelope);
+            if (response.nbHits === 0) {
+                // A rendered no-results state is the view event with zero items; it
+                // shows above the fold, no viewport gating needed.
+                analytics.trackViewSearchResults({ ...envelope, items: [] });
+            }
+        },
+        observeResult(element, response, index) {
+            tracker().observe(element, resultItem(response, index));
+        },
+        select(response, index) {
+            if (envelope === undefined) {
+                return;
+            }
+            const item = resultItem(response, index);
+            // The click forces the item's impression so CTR by position stays ≤100%.
+            tracker().forceImpression(item);
+            analytics.trackSelectSearchResult({ ...envelope, items: [item] });
+        },
+        dispose() {
+            impressions?.disconnect();
+        },
+    };
+}

package/dist/utils/searchImpressions.d.ts

@@ -0,0 +1,21 @@
+import { SearchAnalyticsEnvelope, SearchResultItem, ViewSearchResultsParams } from "../types/searchAnalytics";
+export interface SearchImpressionTrackerOptions {
+    /** Receives each flushed batch — wire it to `dialog.trackViewSearchResults`. */
+    emit: (params: ViewSearchResultsParams) => void;
+    visibilityThreshold?: number;
+    dwellMs?: number;
+    idleFlushMs?: number;
+    maxItemsPerEvent?: number;
+}
+export interface SearchImpressionTracker {
+    /** Declare the envelope of the response being rendered; flushes the previous batch. */
+    setContext(envelope: SearchAnalyticsEnvelope): void;
+    /** Watch a rendered result element for viewport impressions. */
+    observe(element: Element, item: SearchResultItem): void;
+    /** A click counts as an impression, otherwise CTR by position can exceed 100%. */
+    forceImpression(item: SearchResultItem): void;
+    flush(): void;
+    disconnect(): void;
+}
+export declare function createSearchImpressionTracker({ emit, visibilityThreshold, dwellMs, idleFlushMs, maxItemsPerEvent, }: SearchImpressionTrackerOptions): SearchImpressionTracker;
+//# sourceMappingURL=searchImpressions.d.ts.map

package/dist/utils/searchImpressions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchImpressions.d.ts","sourceRoot":"","sources":["../../src/utils/searchImpressions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACxB,MAAM,0BAA0B,CAAC;AAWlC,MAAM,WAAW,8BAA8B;IAC7C,gFAAgF;IAChF,IAAI,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAChD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,uFAAuF;IACvF,UAAU,CAAC,QAAQ,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACpD,gEAAgE;IAChE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACxD,kFAAkF;IAClF,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC9C,KAAK,IAAI,IAAI,CAAC;IACd,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,wBAAgB,6BAA6B,CAAC,EAC5C,IAAI,EACJ,mBAAkD,EAClD,OAA0B,EAC1B,WAAmC,EACnC,gBAA8C,GAC/C,EAAE,8BAA8B,GAAG,uBAAuB,CAsI1D"}

package/dist/utils/searchImpressions.js

@@ -0,0 +1,126 @@
+// An item counts as seen after being ≥50% visible for ≥500ms; qualified items
+// are batched and flushed on qualification inactivity, context change,
+// pagehide or the batch cap — in practice 1-3 events per search, not one per
+// item.
+const DEFAULT_VISIBILITY_THRESHOLD = 0.5;
+const DEFAULT_DWELL_MS = 500;
+const DEFAULT_IDLE_FLUSH_MS = 1500;
+const DEFAULT_MAX_ITEMS_PER_EVENT = 100;
+export function createSearchImpressionTracker({ emit, visibilityThreshold = DEFAULT_VISIBILITY_THRESHOLD, dwellMs = DEFAULT_DWELL_MS, idleFlushMs = DEFAULT_IDLE_FLUSH_MS, maxItemsPerEvent = DEFAULT_MAX_ITEMS_PER_EVENT, }) {
+    let envelope;
+    let pending = [];
+    const seen = new Set();
+    const observedItems = new Map();
+    const dwellTimers = new Map();
+    let idleTimer;
+    const flush = () => {
+        clearTimeout(idleTimer);
+        if (envelope === undefined || pending.length === 0) {
+            return;
+        }
+        emit({ ...envelope, items: pending });
+        pending = [];
+    };
+    const record = (item) => {
+        if (envelope === undefined) {
+            return;
+        }
+        const key = `${envelope.query_id}:${item.product_id}`;
+        if (seen.has(key)) {
+            return;
+        }
+        seen.add(key);
+        pending.push(item);
+        if (pending.length >= maxItemsPerEvent) {
+            flush();
+            return;
+        }
+        clearTimeout(idleTimer);
+        idleTimer = setTimeout(flush, idleFlushMs);
+    };
+    const cancelDwell = (element) => {
+        const timer = dwellTimers.get(element);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            dwellTimers.delete(element);
+        }
+    };
+    const observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+            const item = observedItems.get(entry.target);
+            if (item === undefined) {
+                continue;
+            }
+            if (entry.intersectionRatio >= visibilityThreshold) {
+                if (!dwellTimers.has(entry.target)) {
+                    dwellTimers.set(entry.target, setTimeout(() => {
+                        dwellTimers.delete(entry.target);
+                        record(item);
+                    }, dwellMs));
+                }
+            }
+            else {
+                cancelDwell(entry.target);
+            }
+        }
+    }, { threshold: visibilityThreshold });
+    const stopObserving = () => {
+        observer.disconnect();
+        for (const timer of dwellTimers.values()) {
+            clearTimeout(timer);
+        }
+        dwellTimers.clear();
+        observedItems.clear();
+    };
+    // The page can die mid-batch: ship what already qualified. The host bridge
+    // captures this last event with a beacon-capable transport.
+    const handlePagehide = () => {
+        flush();
+    };
+    // A back/forward-cache restore is a new exposure: re-qualify what is on
+    // screen instead of keeping it deduplicated forever. Dwell timers frozen
+    // mid-count resume with their remaining delay, so cancel them — the
+    // restored exposure must earn its full dwell.
+    const handlePageshow = (event) => {
+        if (!event.persisted) {
+            return;
+        }
+        seen.clear();
+        for (const element of observedItems.keys()) {
+            cancelDwell(element);
+            observer.unobserve(element);
+            observer.observe(element);
+        }
+    };
+    window.addEventListener("pagehide", handlePagehide);
+    window.addEventListener("pageshow", handlePageshow);
+    return {
+        setContext(nextEnvelope) {
+            // Pending impressions belong to the envelope they qualified under.
+            flush();
+            // Dedup only needs to span one query's lifetime (pagination keeps its
+            // query_id): dropping older keys bounds the set across search-as-you-type.
+            if (envelope !== undefined &&
+                envelope.query_id !== nextEnvelope.query_id) {
+                seen.clear();
+            }
+            envelope = nextEnvelope;
+            stopObserving();
+        },
+        observe(element, item) {
+            observedItems.set(element, item);
+            observer.observe(element);
+        },
+        forceImpression(item) {
+            record(item);
+            flush();
+        },
+        flush,
+        disconnect() {
+            flush();
+            stopObserving();
+            window.removeEventListener("pagehide", handlePagehide);
+            window.removeEventListener("pageshow", handlePageshow);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askdialog/dialog-sdk",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "private": false,
   "description": "Dialog SDK",
   "main": "dist/index.js",