@seekora-ai/search-sdk 0.2.21 → 0.2.23

package/dist/analytics/track.js

@@ -0,0 +1,130 @@
+"use strict";
+// Canonical V4 emission wrapper around @segment/analytics-next.
+//
+// Every Seekora SDK callsite that emits a clickstream event MUST go through
+// `track()` (or one of the named helpers below). The wrapper guarantees:
+//
+//   - Tenant context (orgcode + xstoreid) is stamped on every event so
+//     downstream Rotor functions don't have to infer it.
+//   - search_id is auto-resolved from the 3-layer chain (in-memory →
+//     sessionStorage → URL) when the caller hasn't supplied it. Callers can
+//     override by passing an explicit `search_id` in properties.
+//
+// The wrapper is intentionally tiny — type checking lives in the codegen'd
+// AnalyticsEvent union (re-exported from ./events), and validation happens
+// downstream in the Rotor `seekora-event-validate` function. This wrapper
+// is the lightest possible shim so unit-level tests can drive it.
+Object.defineProperty(exports, "__esModule", { value: true });
+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 = void 0;
+exports.track = track;
+exports.emitFilterConvertedForActiveFilters = emitFilterConvertedForActiveFilters;
+const events_1 = require("./events");
+const searchId_1 = require("./searchId");
+const activeFilters_1 = require("./activeFilters");
+/**
+ * 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.
+ */
+function track(ctx, event, properties = {}) {
+    const enriched = {
+        ...properties,
+        orgcode: ctx.orgcode,
+        xstoreid: ctx.xstoreid,
+    };
+    // Auto-resolve search_id when the caller didn't supply a non-empty
+    // value. Treating `search_id: undefined` (or `null`/`""`) as "supplied"
+    // would skip the 3-layer resolver and the event would land in
+    // ClickHouse with no search_id -- breaking funnel attribution for
+    // every Object Clicked that came from a ProductCard which doesn't pass
+    // searchId explicitly (the common case). The `in` operator alone
+    // returns true for `{search_id: undefined}` because the key is
+    // present, so check the value too.
+    const explicit = enriched.search_id;
+    if (explicit == null || explicit === "") {
+        const sid = (0, searchId_1.resolveSearchId)();
+        if (sid) {
+            enriched.search_id = sid;
+        }
+        else {
+            // Drop the empty key entirely so analytics-next doesn't ship a
+            // `"search_id": null` that downstream queries can confuse with
+            // an explicit "no-attribution" intent.
+            delete enriched.search_id;
+        }
+    }
+    ctx.analytics.track(event, enriched);
+}
+// --- Named helpers --------------------------------------------------------
+// Thin sugar so callsites don't have to import EVENT_NAMES alongside track().
+const trackSearchSubmitted = (ctx, p) => track(ctx, events_1.EVENT_NAMES.SearchSubmitted, p);
+exports.trackSearchSubmitted = trackSearchSubmitted;
+const trackSearchImpression = (ctx, p) => track(ctx, events_1.EVENT_NAMES.SearchImpression, p);
+exports.trackSearchImpression = trackSearchImpression;
+const trackObjectClicked = (ctx, p) => track(ctx, events_1.EVENT_NAMES.ObjectClicked, p);
+exports.trackObjectClicked = trackObjectClicked;
+const trackFacetApplied = (ctx, p) => track(ctx, events_1.EVENT_NAMES.FacetApplied, p);
+exports.trackFacetApplied = trackFacetApplied;
+const trackSearchEmpty = (ctx, p) => track(ctx, events_1.EVENT_NAMES.SearchEmpty, p);
+exports.trackSearchEmpty = trackSearchEmpty;
+const trackSearchRefined = (ctx, p) => track(ctx, events_1.EVENT_NAMES.SearchRefined, p);
+exports.trackSearchRefined = trackSearchRefined;
+const trackSuggestionClicked = (ctx, p) => track(ctx, events_1.EVENT_NAMES.SuggestionClicked, p);
+exports.trackSuggestionClicked = trackSuggestionClicked;
+const trackObjectClickedOutsideSearch = (ctx, p) => track(ctx, events_1.EVENT_NAMES.ObjectClickedOutsideSearch, p);
+exports.trackObjectClickedOutsideSearch = trackObjectClickedOutsideSearch;
+const trackObjectConverted = (ctx, p) => track(ctx, events_1.EVENT_NAMES.ObjectConverted, p);
+exports.trackObjectConverted = trackObjectConverted;
+const trackObjectConvertedOutsideSearch = (ctx, p) => track(ctx, events_1.EVENT_NAMES.ObjectConvertedOutsideSearch, p);
+exports.trackObjectConvertedOutsideSearch = trackObjectConvertedOutsideSearch;
+const trackFilterConverted = (ctx, p) => track(ctx, events_1.EVENT_NAMES.FilterConverted, p);
+exports.trackFilterConverted = trackFilterConverted;
+/**
+ * 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".
+ */
+function emitFilterConvertedForActiveFilters(ctx, baseProps = {}) {
+    const filters = (0, activeFilters_1.getActiveFilters)();
+    for (const f of filters) {
+        track(ctx, events_1.EVENT_NAMES.FilterConverted, {
+            ...baseProps,
+            filter_attribute: f.filter_attribute,
+            filter_value: f.filter_value,
+        });
+    }
+    return filters.length;
+}
+const trackProductAdded = (ctx, p) => track(ctx, events_1.EVENT_NAMES.ProductAdded, p);
+exports.trackProductAdded = trackProductAdded;
+// NOTE: Order Line Completed is synthesized downstream by the rotor
+// seekora-orderline-explode function from each Order Completed's
+// `products[]` array. There is NO client helper for it -- callsites
+// only emit Order Completed.
+const trackOrderCompleted = (ctx, p) => track(ctx, events_1.EVENT_NAMES.OrderCompleted, p);
+exports.trackOrderCompleted = trackOrderCompleted;
+const trackProductViewed = (ctx, p) => track(ctx, events_1.EVENT_NAMES.ProductViewed, p);
+exports.trackProductViewed = trackProductViewed;
+const trackObjectViewed = (ctx, p) => track(ctx, events_1.EVENT_NAMES.ObjectViewed, p);
+exports.trackObjectViewed = trackObjectViewed;
+const trackFilterViewed = (ctx, p) => track(ctx, events_1.EVENT_NAMES.FilterViewed, p);
+exports.trackFilterViewed = trackFilterViewed;