@seekora-ai/search-sdk 0.2.22 → 0.2.24

package/dist/analytics/activeFilters.d.ts

@@ -0,0 +1,33 @@
+export declare const SEEKORA_FILTERS_TTL_MS: number;
+export declare const SS_KEY_FILTERS = "seekora.activeFilters";
+export interface ActiveFilter {
+    filter_attribute: string;
+    filter_value: string;
+    at: number;
+}
+/**
+ * Record that a filter just became active. Idempotent — toggling the
+ * same (attr, value) pair twice in a row only stamps it once (the
+ * second call refreshes `at`).
+ */
+export declare function recordActiveFilter(attr: string, value: string, at?: number): void;
+/**
+ * Drop a single filter from both layers. Used when the user removes a
+ * facet selection via removeRefinement / clearRefinements.
+ */
+export declare function removeActiveFilter(attr: string, value: string): void;
+/**
+ * Drop every active filter. Used by clearRefinements and by callers
+ * (rare) that want to reset attribution explicitly.
+ */
+export declare function clearActiveFilters(): void;
+/**
+ * Return the non-stale active filter set. Reads from both layers and
+ * merges so the conversion site doesn't care which layer captured the
+ * filter. Stale entries are pruned (and written back to sessionStorage
+ * if any were dropped) so a converting user doesn't accumulate a long
+ * tail of yesterday's filter selections.
+ *
+ * `now` is injectable for deterministic testing.
+ */
+export declare function getActiveFilters(now?: number): Array<Pick<ActiveFilter, "filter_attribute" | "filter_value">>;

package/dist/analytics/activeFilters.js

@@ -0,0 +1,145 @@
+"use strict";
+// Session-state for the "currently active filter set".
+//
+// Algolia Filter Converted semantics: on every conversion (addToCart /
+// purchase / wishlist / etc.), one Filter Converted event is emitted PER
+// active filter that was applied in the recent window. Funnel queries
+// then answer "conversion rate per filter value" — the only correct way
+// to attribute revenue to faceted browsing.
+//
+// To support that, every Facet Applied tick must leave a breadcrumb the
+// conversion site can read later. This module is that breadcrumb.
+//
+// Mirrors the searchId.ts pattern intentionally:
+//   - In-memory layer (fastest, lost on tab close)
+//   - sessionStorage layer (survives in-tab navigation; needed because
+//     the typical conversion happens on a PDP after the user navigates
+//     away from the search/results page)
+//   - No URL layer — filter sets are too noisy to URL-stamp; the
+//     sessionStorage layer covers the only realistic propagation path.
+//
+// TTL: same 30-min window as search_id, so Filter Converted and Object
+// Converted share an attribution horizon. Each entry tracks its own
+// `at` so stale individual filters get pruned on read even if the
+// session has fresher ones.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SS_KEY_FILTERS = exports.SEEKORA_FILTERS_TTL_MS = void 0;
+exports.recordActiveFilter = recordActiveFilter;
+exports.removeActiveFilter = removeActiveFilter;
+exports.clearActiveFilters = clearActiveFilters;
+exports.getActiveFilters = getActiveFilters;
+exports.SEEKORA_FILTERS_TTL_MS = 30 * 60 * 1000;
+exports.SS_KEY_FILTERS = "seekora.activeFilters";
+let inMemoryFilters = [];
+function keyOf(attr, value) {
+    return `${attr}::${value}`;
+}
+function loadFromStorage() {
+    if (typeof window === "undefined" || !window.sessionStorage)
+        return [];
+    try {
+        const raw = window.sessionStorage.getItem(exports.SS_KEY_FILTERS);
+        if (!raw)
+            return [];
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((x) => x &&
+            typeof x.filter_attribute === "string" &&
+            typeof x.filter_value === "string" &&
+            typeof x.at === "number");
+    }
+    catch {
+        return [];
+    }
+}
+function writeToStorage(filters) {
+    if (typeof window === "undefined" || !window.sessionStorage)
+        return;
+    try {
+        window.sessionStorage.setItem(exports.SS_KEY_FILTERS, JSON.stringify(filters));
+    }
+    catch {
+        // Private mode / quota — silently ignore; in-memory still works.
+    }
+}
+function mergeUnique(a, b) {
+    const seen = new Map();
+    // `a` wins on conflict — caller passes the fresher list first.
+    for (const f of a)
+        seen.set(keyOf(f.filter_attribute, f.filter_value), f);
+    for (const f of b) {
+        const k = keyOf(f.filter_attribute, f.filter_value);
+        if (!seen.has(k))
+            seen.set(k, f);
+    }
+    return Array.from(seen.values());
+}
+/**
+ * Record that a filter just became active. Idempotent — toggling the
+ * same (attr, value) pair twice in a row only stamps it once (the
+ * second call refreshes `at`).
+ */
+function recordActiveFilter(attr, value, at = Date.now()) {
+    const entry = {
+        filter_attribute: attr,
+        filter_value: value,
+        at,
+    };
+    const k = keyOf(attr, value);
+    inMemoryFilters = [
+        entry,
+        ...inMemoryFilters.filter((f) => keyOf(f.filter_attribute, f.filter_value) !== k),
+    ];
+    // Merge with sessionStorage so we don't clobber filters set in a
+    // sibling tab event handler before our in-memory bootstrapped.
+    const merged = mergeUnique(inMemoryFilters, loadFromStorage());
+    writeToStorage(merged);
+}
+/**
+ * Drop a single filter from both layers. Used when the user removes a
+ * facet selection via removeRefinement / clearRefinements.
+ */
+function removeActiveFilter(attr, value) {
+    const k = keyOf(attr, value);
+    inMemoryFilters = inMemoryFilters.filter((f) => keyOf(f.filter_attribute, f.filter_value) !== k);
+    const next = loadFromStorage().filter((f) => keyOf(f.filter_attribute, f.filter_value) !== k);
+    writeToStorage(next);
+}
+/**
+ * Drop every active filter. Used by clearRefinements and by callers
+ * (rare) that want to reset attribution explicitly.
+ */
+function clearActiveFilters() {
+    inMemoryFilters = [];
+    if (typeof window !== "undefined" && window.sessionStorage) {
+        try {
+            window.sessionStorage.removeItem(exports.SS_KEY_FILTERS);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+/**
+ * Return the non-stale active filter set. Reads from both layers and
+ * merges so the conversion site doesn't care which layer captured the
+ * filter. Stale entries are pruned (and written back to sessionStorage
+ * if any were dropped) so a converting user doesn't accumulate a long
+ * tail of yesterday's filter selections.
+ *
+ * `now` is injectable for deterministic testing.
+ */
+function getActiveFilters(now = Date.now()) {
+    const merged = mergeUnique(inMemoryFilters, loadFromStorage());
+    const fresh = merged.filter((f) => now - f.at < exports.SEEKORA_FILTERS_TTL_MS);
+    if (fresh.length !== merged.length) {
+        // Pruning happened — persist the trimmed list so next read is fast.
+        inMemoryFilters = fresh;
+        writeToStorage(fresh);
+    }
+    return fresh.map((f) => ({
+        filter_attribute: f.filter_attribute,
+        filter_value: f.filter_value,
+    }));
+}

package/dist/analytics/events.d.ts

@@ -0,0 +1,26 @@
+import type { components } from "./types.gen";
+/** Discriminated union of all 17 V4 analytics events. */
+export type AnalyticsEvent = components["schemas"]["AnalyticsEvent"];
+/** Canonical event-name string constants (spec Section 5A). */
+export declare const EVENT_NAMES: {
+    readonly ObjectClicked: "Object Clicked";
+    readonly ObjectClickedOutsideSearch: "Object Clicked (Outside Search)";
+    readonly FacetApplied: "Facet Applied";
+    readonly ObjectConverted: "Object Converted";
+    readonly ObjectConvertedOutsideSearch: "Object Converted (Outside Search)";
+    readonly FilterConverted: "Filter Converted";
+    readonly ProductAdded: "Product Added";
+    readonly OrderCompleted: "Order Completed";
+    readonly OrderLineCompleted: "Order Line Completed";
+    readonly ProductViewed: "Product Viewed";
+    readonly ObjectViewed: "Object Viewed";
+    readonly FilterViewed: "Filter Viewed";
+    readonly SearchSubmitted: "Search Submitted";
+    readonly SearchImpression: "Search Impression";
+    readonly SearchRefined: "Search Refined";
+    readonly SearchEmpty: "Search Empty";
+    readonly SuggestionClicked: "Suggestion Clicked";
+};
+export type EventName = (typeof EVENT_NAMES)[keyof typeof EVENT_NAMES];
+/** Flat array of every event-name — handy for whitelist checks and iteration. */
+export declare const ALL_EVENT_NAMES: EventName[];

package/dist/analytics/events.js

@@ -0,0 +1,38 @@
+"use strict";
+// Event-name constants + types for the V4 analytics pipeline.
+//
+// Re-exports the canonical AnalyticsEvent discriminated union from the
+// codegen'd types.gen.ts (which is regenerated from
+// docs/specs/2026-05-15-clickstream-and-search-id-threading.schema.yml via
+// scripts/codegen-events.sh). DO NOT hand-roll types here — every event
+// shape MUST come from the codegen so a schema YAML change is the single
+// source of truth.
+//
+// EVENT_NAMES is the only thing this file owns: the 17 canonical string
+// names that the SDK callers compare/emit against. The drift-pin test
+// (src/analytics/__tests__/schema-drift.test.ts) keeps this list in sync
+// with the YAML discriminator mapping.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_EVENT_NAMES = exports.EVENT_NAMES = void 0;
+/** Canonical event-name string constants (spec Section 5A). */
+exports.EVENT_NAMES = {
+    ObjectClicked: "Object Clicked",
+    ObjectClickedOutsideSearch: "Object Clicked (Outside Search)",
+    FacetApplied: "Facet Applied",
+    ObjectConverted: "Object Converted",
+    ObjectConvertedOutsideSearch: "Object Converted (Outside Search)",
+    FilterConverted: "Filter Converted",
+    ProductAdded: "Product Added",
+    OrderCompleted: "Order Completed",
+    OrderLineCompleted: "Order Line Completed",
+    ProductViewed: "Product Viewed",
+    ObjectViewed: "Object Viewed",
+    FilterViewed: "Filter Viewed",
+    SearchSubmitted: "Search Submitted",
+    SearchImpression: "Search Impression",
+    SearchRefined: "Search Refined",
+    SearchEmpty: "Search Empty",
+    SuggestionClicked: "Suggestion Clicked",
+};
+/** Flat array of every event-name — handy for whitelist checks and iteration. */
+exports.ALL_EVENT_NAMES = Object.values(exports.EVENT_NAMES);

package/dist/analytics/index.d.ts

@@ -0,0 +1,6 @@
+export { EVENT_NAMES, ALL_EVENT_NAMES, type EventName, type AnalyticsEvent, } from "./events";
+export { SEEKORA_SID_TTL_MS, SS_KEY_SID, SS_KEY_AT, URL_PARAM_SID, URL_PARAM_SIT, setActiveSearchId, resolveSearchId, stampSearchIdOnUrl, } from "./searchId";
+export { SEEKORA_FILTERS_TTL_MS, SS_KEY_FILTERS, recordActiveFilter, removeActiveFilter, clearActiveFilters, getActiveFilters, type ActiveFilter, } from "./activeFilters";
+export { track, trackSearchSubmitted, trackSearchImpression, trackObjectClicked, trackFacetApplied, trackSearchEmpty, trackSearchRefined, trackSuggestionClicked, trackObjectClickedOutsideSearch, trackObjectConverted, trackObjectConvertedOutsideSearch, trackFilterConverted, trackProductAdded, trackOrderCompleted, trackProductViewed, trackObjectViewed, trackFilterViewed, emitFilterConvertedForActiveFilters, type TrackContext, } from "./track";
+export { loadJitsuAnalytics, type LoadJitsuAnalyticsOptions, } from "./loadAnalytics";
+export type { components, paths } from "./types.gen";

package/dist/analytics/index.js

@@ -0,0 +1,55 @@
+"use strict";
+// Public surface of the V4 analytics emission module.
+//
+// Importable as `@seekora-ai/search-sdk/analytics` once the package exports
+// map is updated (see package.json "exports" key — added in a follow-up
+// commit so this module is reachable without deep-importing src/).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadJitsuAnalytics = exports.emitFilterConvertedForActiveFilters = exports.trackFilterViewed = exports.trackObjectViewed = exports.trackProductViewed = exports.trackOrderCompleted = exports.trackProductAdded = exports.trackFilterConverted = exports.trackObjectConvertedOutsideSearch = exports.trackObjectConverted = exports.trackObjectClickedOutsideSearch = exports.trackSuggestionClicked = exports.trackSearchRefined = exports.trackSearchEmpty = exports.trackFacetApplied = exports.trackObjectClicked = exports.trackSearchImpression = exports.trackSearchSubmitted = exports.track = exports.getActiveFilters = exports.clearActiveFilters = exports.removeActiveFilter = exports.recordActiveFilter = exports.SS_KEY_FILTERS = exports.SEEKORA_FILTERS_TTL_MS = exports.stampSearchIdOnUrl = exports.resolveSearchId = exports.setActiveSearchId = exports.URL_PARAM_SIT = exports.URL_PARAM_SID = exports.SS_KEY_AT = exports.SS_KEY_SID = exports.SEEKORA_SID_TTL_MS = exports.ALL_EVENT_NAMES = exports.EVENT_NAMES = void 0;
+var events_1 = require("./events");
+Object.defineProperty(exports, "EVENT_NAMES", { enumerable: true, get: function () { return events_1.EVENT_NAMES; } });
+Object.defineProperty(exports, "ALL_EVENT_NAMES", { enumerable: true, get: function () { return events_1.ALL_EVENT_NAMES; } });
+var searchId_1 = require("./searchId");
+Object.defineProperty(exports, "SEEKORA_SID_TTL_MS", { enumerable: true, get: function () { return searchId_1.SEEKORA_SID_TTL_MS; } });
+Object.defineProperty(exports, "SS_KEY_SID", { enumerable: true, get: function () { return searchId_1.SS_KEY_SID; } });
+Object.defineProperty(exports, "SS_KEY_AT", { enumerable: true, get: function () { return searchId_1.SS_KEY_AT; } });
+Object.defineProperty(exports, "URL_PARAM_SID", { enumerable: true, get: function () { return searchId_1.URL_PARAM_SID; } });
+Object.defineProperty(exports, "URL_PARAM_SIT", { enumerable: true, get: function () { return searchId_1.URL_PARAM_SIT; } });
+Object.defineProperty(exports, "setActiveSearchId", { enumerable: true, get: function () { return searchId_1.setActiveSearchId; } });
+Object.defineProperty(exports, "resolveSearchId", { enumerable: true, get: function () { return searchId_1.resolveSearchId; } });
+Object.defineProperty(exports, "stampSearchIdOnUrl", { enumerable: true, get: function () { return searchId_1.stampSearchIdOnUrl; } });
+// Filter Converted session-state (parallel resolver to searchId).
+// Captures the active filter set so conversion sites can emit one
+// Filter Converted event per active filter — Algolia hybrid pattern.
+var activeFilters_1 = require("./activeFilters");
+Object.defineProperty(exports, "SEEKORA_FILTERS_TTL_MS", { enumerable: true, get: function () { return activeFilters_1.SEEKORA_FILTERS_TTL_MS; } });
+Object.defineProperty(exports, "SS_KEY_FILTERS", { enumerable: true, get: function () { return activeFilters_1.SS_KEY_FILTERS; } });
+Object.defineProperty(exports, "recordActiveFilter", { enumerable: true, get: function () { return activeFilters_1.recordActiveFilter; } });
+Object.defineProperty(exports, "removeActiveFilter", { enumerable: true, get: function () { return activeFilters_1.removeActiveFilter; } });
+Object.defineProperty(exports, "clearActiveFilters", { enumerable: true, get: function () { return activeFilters_1.clearActiveFilters; } });
+Object.defineProperty(exports, "getActiveFilters", { enumerable: true, get: function () { return activeFilters_1.getActiveFilters; } });
+var track_1 = require("./track");
+Object.defineProperty(exports, "track", { enumerable: true, get: function () { return track_1.track; } });
+Object.defineProperty(exports, "trackSearchSubmitted", { enumerable: true, get: function () { return track_1.trackSearchSubmitted; } });
+Object.defineProperty(exports, "trackSearchImpression", { enumerable: true, get: function () { return track_1.trackSearchImpression; } });
+Object.defineProperty(exports, "trackObjectClicked", { enumerable: true, get: function () { return track_1.trackObjectClicked; } });
+Object.defineProperty(exports, "trackFacetApplied", { enumerable: true, get: function () { return track_1.trackFacetApplied; } });
+Object.defineProperty(exports, "trackSearchEmpty", { enumerable: true, get: function () { return track_1.trackSearchEmpty; } });
+Object.defineProperty(exports, "trackSearchRefined", { enumerable: true, get: function () { return track_1.trackSearchRefined; } });
+Object.defineProperty(exports, "trackSuggestionClicked", { enumerable: true, get: function () { return track_1.trackSuggestionClicked; } });
+Object.defineProperty(exports, "trackObjectClickedOutsideSearch", { enumerable: true, get: function () { return track_1.trackObjectClickedOutsideSearch; } });
+Object.defineProperty(exports, "trackObjectConverted", { enumerable: true, get: function () { return track_1.trackObjectConverted; } });
+Object.defineProperty(exports, "trackObjectConvertedOutsideSearch", { enumerable: true, get: function () { return track_1.trackObjectConvertedOutsideSearch; } });
+Object.defineProperty(exports, "trackFilterConverted", { enumerable: true, get: function () { return track_1.trackFilterConverted; } });
+Object.defineProperty(exports, "trackProductAdded", { enumerable: true, get: function () { return track_1.trackProductAdded; } });
+Object.defineProperty(exports, "trackOrderCompleted", { enumerable: true, get: function () { return track_1.trackOrderCompleted; } });
+Object.defineProperty(exports, "trackProductViewed", { enumerable: true, get: function () { return track_1.trackProductViewed; } });
+Object.defineProperty(exports, "trackObjectViewed", { enumerable: true, get: function () { return track_1.trackObjectViewed; } });
+Object.defineProperty(exports, "trackFilterViewed", { enumerable: true, get: function () { return track_1.trackFilterViewed; } });
+Object.defineProperty(exports, "emitFilterConvertedForActiveFilters", { enumerable: true, get: function () { return track_1.emitFilterConvertedForActiveFilters; } });
+// Canonical factory for an analytics-next AnalyticsBrowser pointed at Jitsu.
+// ALWAYS batches -- /v1/t has no CORS, /v1/batch does. Every browser
+// consumer should use this helper instead of hand-rolling AnalyticsBrowser.load().
+// See feedback_analytics_batching_always.md for the rule and rationale.
+var loadAnalytics_1 = require("./loadAnalytics");
+Object.defineProperty(exports, "loadJitsuAnalytics", { enumerable: true, get: function () { return loadAnalytics_1.loadJitsuAnalytics; } });

package/dist/analytics/loadAnalytics.d.ts

@@ -0,0 +1,37 @@
+import { AnalyticsBrowser } from "@segment/analytics-next";
+export interface LoadJitsuAnalyticsOptions {
+    /**
+     * Per-stream write key (= Jitsu Stream.ID per the SCRUM-263 convention).
+     * Provisioned by RegisterJitsuHook at tenant onboarding.
+     */
+    writeKey: string;
+    /**
+     * Full Jitsu Ingest URL with protocol (e.g. "https://jitsu-dev.cptsd.in").
+     * The factory strips the protocol + trailing slash and appends "/v1" for
+     * `apiHost`, then sets `cdnURL` to the same host. analytics-next's
+     * `apiHost` controls where events POST to; `cdnURL` only affects where
+     * the library bundle is fetched from -- both matter when redirecting to
+     * Jitsu away from Segment defaults.
+     */
+    jitsuHost: string;
+    /**
+     * Per-batch event count threshold. Default 20 -- coalesces rapid bursts
+     * (Search Submitted + N per-card Search Impression on the same render
+     * tick) without holding too long. Lower this for sandboxed contexts
+     * (Shopify Web Pixel) where the page can close during checkout.
+     */
+    batchSize?: number;
+    /**
+     * Max time between flushes, in ms. Default 500 -- short enough for
+     * interactive testing, long enough to coalesce. Lower this for short-
+     * lived contexts (e.g. set to 100 for Web Pixel on checkout pages
+     * where the tab closes immediately after Order Completed).
+     */
+    batchTimeoutMs?: number;
+}
+/**
+ * Construct an analytics-next AnalyticsBrowser routed at a Jitsu Ingest.
+ *
+ * Batching is forced ON. See file-level comment for the CORS rationale.
+ */
+export declare function loadJitsuAnalytics(options: LoadJitsuAnalyticsOptions): AnalyticsBrowser;

package/dist/analytics/loadAnalytics.js

@@ -0,0 +1,70 @@
+"use strict";
+// Canonical factory for an analytics-next AnalyticsBrowser instance pointed
+// at a Jitsu Ingest. Centralises the Jitsu-vs-Segment routing knobs so every
+// browser consumer (cartello, demo-stores, ui-sdk built-in widgets, the
+// shopify-app theme JS) inherits the same configuration without copy-pasting.
+//
+// ALWAYS enables batching. Jitsu Ingest exposes CORS
+// (Access-Control-Allow-Origin) on /v1/batch but NOT on /v1/t -- unbatched
+// single events get silently dropped by the browser preflight before they
+// ever leave the page. Verified May 2026 against jitsu-dev.cptsd.in +
+// local-stack. Hard rule: if you emit analytics from a browser, batching is
+// on. No exceptions. See memory/feedback_analytics_batching_always.md.
+//
+// Usage (replaces hand-rolled `AnalyticsBrowser.load()` calls):
+//
+//   import { loadJitsuAnalytics } from "@seekora-ai/search-sdk";
+//   const analytics = loadJitsuAnalytics({
+//     writeKey: SEEKORA_JITSU_WRITE_KEY,
+//     jitsuHost: SEEKORA_JITSU_HOST,
+//   });
+//   <SearchProvider trackContext={{ analytics, orgcode, xstoreid }}>
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadJitsuAnalytics = loadJitsuAnalytics;
+const analytics_next_1 = require("@segment/analytics-next");
+/**
+ * Construct an analytics-next AnalyticsBrowser routed at a Jitsu Ingest.
+ *
+ * Batching is forced ON. See file-level comment for the CORS rationale.
+ */
+function loadJitsuAnalytics(options) {
+    const apiHost = options.jitsuHost.replace(/^https?:\/\//, "").replace(/\/+$/, "") + "/v1";
+    return analytics_next_1.AnalyticsBrowser.load({
+        writeKey: options.writeKey,
+        cdnURL: options.jitsuHost,
+    }, {
+        integrations: {
+            "Segment.io": {
+                apiHost,
+                // MANDATORY: batching forces /v1/batch routing where Jitsu has
+                // CORS. Unbatched /v1/t is silently CORS-dropped by browsers.
+                deliveryStrategy: {
+                    strategy: "batching",
+                    config: {
+                        size: options.batchSize ?? 20,
+                        timeout: options.batchTimeoutMs ?? 500,
+                    },
+                },
+            },
+        },
+        // Disable analytics-next's internal RemoteMetrics telemetry. It
+        // sends `analytics_js.invoke` counters to `${apiHost}/m`; with our
+        // apiHost redirected to Jitsu, those POSTs go to /v1/m which
+        // Jitsu's ingest doesn't expose (returns 401) -- noise in the
+        // console + wasted bandwidth. The metrics config lives on
+        // CDNSettings (NOT InitOptions, despite looking similar in the
+        // .d.ts -- `metrics?: MetricsOptions` is a CDNSettings field).
+        // Override it via updateCDNSettings, which fires right after the
+        // settings fetch resolves -- before RemoteMetrics is constructed.
+        // sampleRate: 0 short-circuits the flusher entirely.
+        updateCDNSettings: (cdnSettings) => {
+            return {
+                ...cdnSettings,
+                metrics: {
+                    ...(cdnSettings.metrics ?? {}),
+                    sampleRate: 0,
+                },
+            };
+        },
+    });
+}

package/dist/analytics/searchId.d.ts

@@ -0,0 +1,26 @@
+export declare const SEEKORA_SID_TTL_MS: number;
+export declare const SS_KEY_SID = "seekora.searchId";
+export declare const SS_KEY_AT = "seekora.searchAt";
+export declare const URL_PARAM_SID = "seekora_sid";
+export declare const URL_PARAM_SIT = "seekora_sit";
+/**
+ * Record the active search_id at `at` (default = now). Writes to both the
+ * in-memory layer and sessionStorage so subsequent reads in this tab — even
+ * after navigation — can resolve the same search_id.
+ */
+export declare function setActiveSearchId(id: string, at?: number): void;
+/**
+ * Walk the three layers and return the first non-stale search_id, or null.
+ * `now` is injectable for deterministic testing.
+ */
+export declare function resolveSearchId(now?: number): string | null;
+/**
+ * Stamp `?seekora_sid=<id>&seekora_sit=<at>` onto a destination URL. Used
+ * at click time so PDP / cross-tab navigation can recover the originating
+ * search_id from the URL even when sessionStorage is unavailable
+ * (Shopify Web Pixel sandbox, new browser tab, etc.).
+ *
+ * Returns a URL string with the two params merged in. Falls back to a
+ * manual query-string append if URL parsing fails (rare — defensive).
+ */
+export declare function stampSearchIdOnUrl(url: string, id: string, at?: number): string;

package/dist/analytics/searchId.js

@@ -0,0 +1,102 @@
+"use strict";
+// Three-layer search_id resolver: in-memory → sessionStorage → URL ?seekora_sid.
+// 30-min TTL guard on every layer. See spec Section 6C / plan Phase 5 Task 5.2.
+//
+// Order of resolution:
+//   1. In-memory (current page state) — set by the SDK when /v1/search returns
+//      a search_id, or by the caller via setActiveSearchId().
+//   2. sessionStorage (same-tab persistence) — survives in-tab navigation but
+//      not new tabs (intentional — that's what the URL stamp is for).
+//   3. URL params `?seekora_sid=<id>&seekora_sit=<unix_ms>` — set by
+//      stampSearchIdOnUrl() on result-card clicks so attribution survives
+//      cmd-click new tab / shared link clicks within the TTL window.
+//
+// First non-stale hit wins. If every layer is stale or absent, returns null
+// and the caller emits the event without a search_id (out-of-search context).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.URL_PARAM_SIT = exports.URL_PARAM_SID = exports.SS_KEY_AT = exports.SS_KEY_SID = exports.SEEKORA_SID_TTL_MS = void 0;
+exports.setActiveSearchId = setActiveSearchId;
+exports.resolveSearchId = resolveSearchId;
+exports.stampSearchIdOnUrl = stampSearchIdOnUrl;
+exports.SEEKORA_SID_TTL_MS = 30 * 60 * 1000;
+exports.SS_KEY_SID = "seekora.searchId";
+exports.SS_KEY_AT = "seekora.searchAt";
+exports.URL_PARAM_SID = "seekora_sid";
+exports.URL_PARAM_SIT = "seekora_sit";
+let inMemorySearchId = null;
+let inMemoryAt = 0;
+/**
+ * Record the active search_id at `at` (default = now). Writes to both the
+ * in-memory layer and sessionStorage so subsequent reads in this tab — even
+ * after navigation — can resolve the same search_id.
+ */
+function setActiveSearchId(id, at = Date.now()) {
+    inMemorySearchId = id;
+    inMemoryAt = at;
+    if (typeof window !== "undefined" && window.sessionStorage) {
+        try {
+            window.sessionStorage.setItem(exports.SS_KEY_SID, id);
+            window.sessionStorage.setItem(exports.SS_KEY_AT, String(at));
+        }
+        catch {
+            // Private mode / quota — silently ignore; in-memory still works.
+        }
+    }
+}
+/**
+ * Walk the three layers and return the first non-stale search_id, or null.
+ * `now` is injectable for deterministic testing.
+ */
+function resolveSearchId(now = Date.now()) {
+    // Layer 1 — in-memory.
+    if (inMemorySearchId && now - inMemoryAt < exports.SEEKORA_SID_TTL_MS) {
+        return inMemorySearchId;
+    }
+    // Layer 2 — sessionStorage.
+    if (typeof window !== "undefined" && window.sessionStorage) {
+        try {
+            const stored = window.sessionStorage.getItem(exports.SS_KEY_SID);
+            const at = parseInt(window.sessionStorage.getItem(exports.SS_KEY_AT) || "0", 10);
+            if (stored && now - at < exports.SEEKORA_SID_TTL_MS)
+                return stored;
+        }
+        catch {
+            // ignore
+        }
+    }
+    // Layer 3 — URL ?seekora_sid + ?seekora_sit.
+    if (typeof window !== "undefined" && window.location) {
+        try {
+            const params = new URLSearchParams(window.location.search);
+            const urlSid = params.get(exports.URL_PARAM_SID);
+            const urlSit = parseInt(params.get(exports.URL_PARAM_SIT) || "0", 10);
+            if (urlSid && now - urlSit < exports.SEEKORA_SID_TTL_MS)
+                return urlSid;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return null;
+}
+/**
+ * Stamp `?seekora_sid=<id>&seekora_sit=<at>` onto a destination URL. Used
+ * at click time so PDP / cross-tab navigation can recover the originating
+ * search_id from the URL even when sessionStorage is unavailable
+ * (Shopify Web Pixel sandbox, new browser tab, etc.).
+ *
+ * Returns a URL string with the two params merged in. Falls back to a
+ * manual query-string append if URL parsing fails (rare — defensive).
+ */
+function stampSearchIdOnUrl(url, id, at = Date.now()) {
+    try {
+        const u = new URL(url, typeof window !== "undefined" ? window.location.href : "https://x");
+        u.searchParams.set(exports.URL_PARAM_SID, id);
+        u.searchParams.set(exports.URL_PARAM_SIT, String(at));
+        return u.toString();
+    }
+    catch {
+        const sep = url.indexOf("?") === -1 ? "?" : "&";
+        return `${url}${sep}${exports.URL_PARAM_SID}=${encodeURIComponent(id)}&${exports.URL_PARAM_SIT}=${at}`;
+    }
+}

package/dist/analytics/track.d.ts

@@ -0,0 +1,59 @@
+import type { AnalyticsBrowser } from "@segment/analytics-next";
+import { type EventName } from "./events";
+/**
+ * Per-request tracking context. Supplied by the SDK client (or the host
+ * app) on every emit so the wrapper knows which @segment/analytics-next
+ * instance to talk to and which tenant to stamp.
+ */
+export interface TrackContext {
+    analytics: AnalyticsBrowser;
+    orgcode: string;
+    xstoreid: string;
+}
+/**
+ * Emit a track event with canonical Seekora fields auto-stamped.
+ *
+ * - Tenant context (orgcode, xstoreid) is always merged in.
+ * - search_id is auto-resolved via resolveSearchId() when absent. Callers
+ *   that already know the search_id should pass it explicitly to skip the
+ *   resolver work.
+ */
+export declare function track(ctx: TrackContext, event: EventName, properties?: Record<string, unknown>): void;
+export declare const trackSearchSubmitted: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackSearchImpression: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackObjectClicked: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackFacetApplied: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackSearchEmpty: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackSearchRefined: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackSuggestionClicked: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackObjectClickedOutsideSearch: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackObjectConverted: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackObjectConvertedOutsideSearch: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackFilterConverted: (ctx: TrackContext, p: Record<string, unknown>) => void;
+/**
+ * Emit one `Filter Converted` event per currently-active filter.
+ *
+ * Algolia hybrid pattern: a single conversion (addToCart / purchase /
+ * wishlist) gets attributed to EVERY filter that was active in the
+ * 30-min attribution window — one event per filter so funnel queries
+ * can answer "which filter values converted at what rate".
+ *
+ * `baseProps` carry the conversion metadata that's identical across
+ * all of the emitted events (conversion_type, value, currency, plus
+ * any extras the caller wants threaded through). Each emit then
+ * stamps the per-filter `filter_attribute` + `filter_value`.
+ *
+ * If no filters are active (empty session-state OR every filter
+ * expired), this is a no-op — the regular Object Converted / Product
+ * Added event still goes out (the caller's responsibility), but no
+ * Filter Converted gets emitted.
+ *
+ * Returns the number of events emitted, which is handy for unit tests
+ * and for callers that want to log "attributed N filters".
+ */
+export declare function emitFilterConvertedForActiveFilters(ctx: TrackContext, baseProps?: Record<string, unknown>): number;
+export declare const trackProductAdded: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackOrderCompleted: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackProductViewed: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackObjectViewed: (ctx: TrackContext, p: Record<string, unknown>) => void;
+export declare const trackFilterViewed: (ctx: TrackContext, p: Record<string, unknown>) => void;