@releval/tracker 1.0.0-bootstrap.0

package/dist/ResultImpressionCollector.d.mts

@@ -0,0 +1,762 @@
+//#region src/logging/Logger.d.ts
+/**
+ * Logging interface for internal tracker diagnostics. Implement this to
+ * integrate the tracker's log output with your application's logging system,
+ * then pass it as the `logger` option. To fan out to several destinations
+ * (e.g. the console AND your own service), pass a logger that wraps both.
+ */
+interface Logger {
+  /**
+   * Logs a debug message
+   * @param msg the message
+   * @param data the additional data
+   */
+  debug(msg: string, ...data: any[]): void;
+  /**
+   * Logs an info message
+   * @param msg the message
+   * @param data the additional data
+   */
+  info(msg: string, ...data: any[]): void;
+  /**
+   * Logs a warn message
+   * @param msg the message
+   * @param data the additional data
+   */
+  warn(msg: string, ...data: any[]): void;
+  /**
+   * Logs an error message
+   * @param msg the message
+   * @param data the additional data
+   */
+  error(msg: string, ...data: any[]): void;
+}
+//#endregion
+//#region src/attribution/AttributionStore.d.ts
+/**
+ * The search context recorded for a result when it was clicked, used to
+ * attribute later conversion events (add_to_cart, purchase) for the same
+ * object back to the originating query.
+ */
+type AttributionRecord = {
+  /** The server-issued query id of the search that produced the result. */
+  queryId: string;
+  /** The absolute 1-based rank the result was clicked at, if recorded. */
+  ordinal?: number;
+  /** The query text as the user entered it, if recorded. */
+  query?: string;
+};
+//#endregion
+//#region src/types/Event.d.ts
+/**
+ * The core UBI event structure that is enriched and emitted to sinks.
+ *
+ * Only `action_name` is required when dispatching - the dispatcher auto-sets
+ * `timestamp` and enrichers populate contextual fields like `application`,
+ * `session_id`, `client_id`, and browser/page metadata before the event
+ * reaches the sink.
+ *
+ * @see https://o19s.github.io/ubi/schema/1.3.0/event.schema.json
+ */
+interface Event {
+  /**
+   * Name of the application integrated with UBI. Distinguishes event sources
+   * when multiple search UIs feed into the same backend.
+   * @example "primary-search"
+   * @example "type-ahead"
+   */
+  application?: string;
+  /**
+   * The name of the action that triggered the event.
+   * Common values: `"click"`, `"add_to_cart"`, `"purchase"`, `"impression"`, `"view"`, `"watch"`.
+   * Any custom string is also accepted.
+   */
+  action_name: string;
+  /**
+   * The unique identifier of the query that this event is associated with,
+   * typically a UUID. Links events back to the originating search.
+   * @example "00112233-4455-6677-8899-aabbccddeeff"
+   * @example "1234-user-5678"
+   */
+  query_id?: string;
+  /**
+   * The session identifier, used to correlate interactions across page navigations
+   * and to track unique visits for both authenticated and anonymous users.
+   * Populated automatically by the SessionEnricher.
+   * @example "84266fdbd31d4c2c6d0665f7e8380fa3"
+   */
+  session_id?: string;
+  /**
+   * A stable anonymous identifier for the client issuing events.
+   * This could be a unique browser, a microservice, or a crawling bot.
+   * Populated automatically by the ClientIdEnricher.
+   * @example "5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"
+   * @example "quepid-nightly-bot"
+   */
+  client_id?: string;
+  /**
+   * The authenticated user identifier, if available.
+   * May be `undefined` for anonymous/unauthenticated users.
+   * @example "5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"
+   */
+  user_id?: string;
+  /**
+   * When the event took place, formatted as an ISO 8601 date-time string.
+   * Auto-set by the dispatcher if not provided.
+   * @example "2018-11-13T20:20:39+00:00"
+   * @example "2018-11-13T20:20:39Z"
+   */
+  timestamp?: string;
+  /**
+   * Groups related `action_name` values into logical categories.
+   * @example "QUERY"
+   * @example "CONVERSION"
+   */
+  message_type?: string;
+  /**
+   * Optional text message for the log entry. For a `message_type` of `"QUERY"`,
+   * this would typically contain the search text.
+   */
+  message?: string;
+  /** The query as the user entered it, before any normalization or processing. */
+  user_query?: string;
+  /**
+   * Contextual data attached to a tracked event describing what was interacted with
+   * and where it appeared on the page. Additional custom properties can be added via
+   * the index signature.
+   */
+  event_attributes?: EventAttributes;
+  /**
+   * The public Site identifier issued by Releval when registering a Site.
+   * Stamped automatically by the OptionsEnricher from `TrackerOptions.siteId`.
+   * A Releval extension to the UBI schema: the server drops events whose
+   * `site_id` does not match a registered Site.
+   * @example "01J8ZP4Q9K7X2M5N6R8T0V3W1Y"
+   */
+  site_id?: string;
+}
+/**
+ * Contextual data attached to a tracked event describing what was interacted with
+ * and where it appeared on the page. Additional custom properties can be added via
+ * the index signature.
+ */
+interface EventAttributes {
+  /**
+   * Identifies the object (e.g. product, document) that was interacted with.
+   * Additional custom properties can be added via the index signature.
+   */
+  object?: EventObject;
+  /**
+   * Describes where an interaction occurred relative to other items on the page.
+   * Use `ordinal` for list/grid rank and `x`/`y` for coordinate-based positioning.
+   * Additional custom properties can be added via the index signature.
+   */
+  position?: EventPosition;
+  /**
+   * A stable per-event identifier, set once by the dispatcher when the event
+   * is created. A Releval extension to the UBI schema. It lives under
+   * `event_attributes` because that is where the server preserves unknown
+   * fields, so delivery retries (which can duplicate) stay deduplicable in
+   * analysis: `LIMIT 1 BY event_attributes.event_id`.
+   * @example "01J8ZP4Q9K7X2M5N6R8T0V3W1Y"
+   */
+  event_id?: string;
+  /**
+   * The tracker build that produced the event (`{ version }`), stamped by the
+   * dispatcher. A Releval extension, for supportability once several tracker
+   * versions are deployed across customer sites.
+   */
+  tracker?: any;
+  [key: string]: any;
+}
+/**
+ * Identifies the object (e.g. product, document) that was interacted with.
+ * Additional custom properties can be added via the index signature.
+ */
+interface EventObject {
+  /**
+   * The identifier that uniquely locates the object within the document corpus.
+   * Variants should be incorporated, so for a red t-shirt use the SKU-level identifier.
+   * Always a string on the wire: the Releval server binds it strictly and rejects
+   * the whole batch when a number arrives.
+   * @example "XYZ-12345"
+   * @example "ISBN 0-061-96436-0"
+   */
+  object_id: string;
+  /**
+   * The type/namespace of the object identifier.
+   * Common values: `"product"`, `"user"`, `"post"`, `"comment"`, `"video"`.
+   */
+  object_id_type?: string;
+  /**
+   * The name of the field that stores the object identifier in the backend data store.
+   * If omitted, the search index's default primary identifier is used (e.g. `_id` in OpenSearch).
+   */
+  object_id_field?: string;
+  /**
+   * The internal identifier that the search engine uses to index the object.
+   * For example, the `_id` field in OpenSearch indices - pass numeric ids as
+   * strings. Always a string on the wire: the Releval server binds it strictly
+   * and a number would reject the whole batch, the same hole `object_id` closes.
+   * @example "1"
+   * @example "123456"
+   */
+  internal_id?: string;
+  [key: string]: any;
+}
+/**
+ * Describes where an interaction occurred relative to other items on the page.
+ * Use `ordinal` for list/grid rank and `x`/`y` for coordinate-based positioning.
+ * Additional custom properties can be added via the index signature.
+ */
+interface EventPosition {
+  /**
+   * The absolute, 1-based rank of the item across pagination:
+   * `(page - 1) * pageSize + positionOnPage` with `page` 1-based. It must equal
+   * index + 1 of the object in the `query_response_hit_ids` the backend sent to
+   * track-query for this `query_id`. For grid layouts this is left to right,
+   * ignoring wrapping.
+   * @example 1
+   * @example 21
+   */
+  ordinal?: number;
+  /**
+   * The x coordinate on the screen where the event was triggered.
+   * Matches the Releval server's flat `x` field.
+   */
+  x?: number;
+  /**
+   * The y coordinate on the screen where the event was triggered.
+   * Matches the Releval server's flat `y` field.
+   */
+  y?: number;
+  [key: string]: any;
+}
+//#endregion
+//#region src/enrichers/Enricher.d.ts
+/**
+ * Mutates a UBI event to add contextual data before it reaches the sink. Built-in enrichers
+ * add fields like `application`, `session_id`, `client_id`, and browser metadata. Implement
+ * this interface to add custom fields (e.g. A/B test variant, feature flags) and register
+ * via `tracker.addEnricher()`.
+ */
+interface Enricher {
+  /**
+   * Enriches the event.
+   * @param event the event to enrich
+   */
+  enrich(event: Event): void;
+}
+//#endregion
+//#region src/sinks/Sink.d.ts
+/**
+ * A destination that receives enriched UBI events. Built-in sinks send events to an API
+ * endpoint (BatchSink) or to the browser console (ConsoleSink). Implement this
+ * interface to send events to a custom destination and register via `tracker.addSink()`.
+ */
+interface Sink {
+  /**
+   * Emit the specified event to the destination.
+   * @remarks Implementations should allow errors to propagate. These are logged by the configured tracker logger.
+   * @param event The event to emit
+   */
+  emit(event: Event): void;
+}
+//#endregion
+//#region src/collectors/resolveResult.d.ts
+/**
+ * The result data resolved from a DOM element by the default data-attribute
+ * convention shared by the declarative collectors.
+ */
+type ResolvedResultData = {
+  /** The identifier of the result object (e.g. product/SKU) - `data-object-id`. */
+  objectId: string;
+  /**
+   * The absolute, 1-based rank of the result across pagination -
+   * `data-ordinal`. `undefined` when missing, empty or not a positive
+   * integer; the collectors validate before anything is emitted.
+   */
+  ordinal?: number;
+  /** The backend field the object id maps to - `data-object-id-field`. */
+  objectIdField?: string;
+  /**
+   * Overrides the emitted `action_name` (e.g. `"add_to_cart"`) -
+   * `data-action-name`. Clicks default to `"click"`.
+   */
+  actionName?: string;
+  /**
+   * The server-issued `query_id` that produced the result - `data-query-id`
+   * on the nearest ancestor carrying it (the element itself counts).
+   */
+  queryId?: string;
+  /** The query text as the user entered it - `data-query` on that ancestor. */
+  query?: string;
+  /**
+   * Any additional keys - `data-event-*` attributes read by the default
+   * resolver, or extra keys returned by a custom one - are persisted as-is
+   * under the event's `event_attributes`.
+   */
+  [key: string]: unknown;
+};
+/**
+ * Reads the documented data-attribute convention off a result element:
+ *
+ * - `data-object-id`, `data-ordinal`, `data-object-id-field` and (optionally)
+ *   `data-action-name` on the result element itself;
+ * - `data-event-*` on the result element for custom event attributes:
+ *   `data-event-badge="sale"` becomes `badge: "sale"` (hyphens camelCase,
+ *   underscores survive - `data-event-sale_price` -> `sale_price`); a value
+ *   that looks like a JSON object or array is parsed as one
+ *   (`data-event-filters='{"brand":"acme"}'`), any other value - scalars
+ *   included - stays a string;
+ * - `data-query-id` and `data-query` on the nearest ancestor carrying
+ *   `data-query-id` (typically the results container, rendered server-side).
+ *
+ * A missing, empty or non-positive-integer `data-ordinal` yields
+ * `undefined`, never 0 - a
+ * fabricated rank is indistinguishable from data downstream. The collectors
+ * validate what they need and warn (once) when a required field is absent.
+ *
+ * @param logger receives the one-time malformed-JSON warning; the collectors
+ *   pass the tracker's logger.
+ */
+declare const readResultData: (element: HTMLElement, logger?: Logger) => ResolvedResultData;
+//#endregion
+//#region src/collectors/ResultClickCollector.d.ts
+/**
+ * The result data resolved for a clicked element. `actionName` defaults to
+ * `"click"`; a click resolved to any other action (e.g. `"add_to_cart"`) is
+ * routed through `trackResultEvent`, where a missing `queryId`/`ordinal` is
+ * resolved from the attribution recorded when the result was clicked.
+ */
+type ResolvedResultClick = ResolvedResultData;
+/**
+ * Resolves the result data for a clicked element. Return `undefined` to skip
+ * the click entirely. The default implementation reads the data-attribute
+ * convention described on {@link readResultData}.
+ */
+type ResultClickResolve = (element: HTMLElement, event: MouseEvent) => ResolvedResultClick | undefined;
+/** Options for `Tracker.trackResultClicks`. */
+type TrackResultClicksOptions = {
+  /**
+   * CSS selector of result elements. Clicks are matched via `closest()`, so a
+   * click on any descendant of a matching element counts.
+   */
+  selector: string;
+  /** The root the single delegated listener attaches to. Defaults to `document`. */
+  root?: Document | Element;
+  /**
+   * Selector for elements whose clicks must NOT be reported as result clicks,
+   * checked inside the matched result (e.g. `'[data-add-to-cart]'` for a
+   * button nested in the card). Without it a click on the nested button would
+   * emit both its own event and a result click, inflating CTR.
+   */
+  ignore?: string;
+  /** Custom resolver; defaults to the data-attribute convention. */
+  resolve?: ResultClickResolve;
+};
+//#endregion
+//#region src/tracker.d.ts
+/**
+ * Options shared by every {@link TrackerOptions} variant. Not used directly -
+ * see {@link TrackerOptions} for the endpoint pairing rules.
+ */
+type TrackerBaseOptions = {
+  /** The name of the application */
+  application: string;
+  /**
+   * The initial user id attached to events (`user_id`). Must be an opaque,
+   * pseudonymous identifier - never an email address or name. Change it
+   * mid-session (login/logout) with {@link Tracker.setUserId}.
+   */
+  userId?: string;
+  /** Session inactivity timeout in milliseconds. Defaults to 30 minutes. */
+  sessionInactivityTimeoutMs?: number;
+  /** Maximum session duration in milliseconds. Defaults to 24 hours. */
+  maxSessionDurationMs?: number;
+  /**
+   * When true, the default console logger also prints debug/info
+   * diagnostics: every dispatched event and every delivery outcome. This is
+   * the one-line install check against a server that answers 202 to
+   * everything. Warnings and errors are printed regardless. Applies to the
+   * default `ConsoleLogger` only - a supplied `logger` receives all levels
+   * and filters for itself. Defaults to false.
+   */
+  debug?: boolean;
+  /**
+   * A logger to receive internal diagnostics. Replaces the default
+   * `ConsoleLogger`, so pass one here to route (or silence) tracker logging
+   * instead of writing to the console. To fan out to several destinations,
+   * pass a logger that wraps them.
+   */
+  logger?: Logger;
+};
+/**
+ * Configuration passed to `new Tracker()`. Delivering to Releval requires the
+ * pair: `endpointHost` (the base URL browsers use to reach the Releval
+ * deployment - not your site's own origin) and `siteId` (the public Site
+ * identifier issued by Releval). The server silently drops events whose
+ * `site_id` does not match a registered Site, so the type requires the two
+ * together. Omit `endpointHost` for development mode: events go to the
+ * console - or only to sinks added with `addSink`, once any are added - and
+ * nothing leaves the page.
+ */
+type TrackerOptions = TrackerBaseOptions & ({
+  /**
+   * Base URL browsers use to reach the Releval deployment, e.g.
+   * `"https://releval.example.com"` - not your site's own origin. A
+   * path prefix for a reverse proxy is allowed; events POST to
+   * `<endpointHost>/api/v1/ubi/track-event`.
+   */
+  endpointHost: string;
+  /**
+   * The public Site identifier issued by Releval when registering a
+   * Site. Stamped on every event in the request body; identity travels
+   * in the payload, not a header, because `navigator.sendBeacon`
+   * cannot set custom headers on the unload path.
+   */
+  siteId: string;
+} | {
+  /** Omit to log events to the console instead of delivering (development mode). */
+  endpointHost?: undefined;
+  /** Without an endpoint the site id is optional; it is stamped when present. */
+  siteId?: string;
+});
+/**
+ * A reference to a search result that was interacted with. Used by the
+ * high-level `trackResult*` methods to build the UBI `object` + `position`
+ * attributes so callers do not hand-roll the event shape.
+ */
+type ResultRef = {
+  /** The identifier of the object (e.g. product/SKU) that was interacted with. */
+  objectId: string;
+  /**
+   * The absolute, 1-based rank of the result across pagination -
+   * `(page - 1) * pageSize + positionOnPage` with `page` 1-based - not the
+   * per-page position. It must equal index + 1 of this object in the
+   * `query_response_hit_ids` your backend sent to track-query for this
+   * `query_id`: either one query_id spans all pages with absolute ordinals,
+   * or each page fetch is its own track-query call with its own query_id.
+   */
+  ordinal: number;
+  /** The backend field the object id maps to (UBI `object_id_field`). Optional. */
+  objectIdField?: string;
+  /**
+   * Any additional keys are persisted as-is under the event's
+   * `event_attributes` (e.g. `badge: "sale"`). Values must be
+   * JSON-serialisable. Keys the tracker itself owns - `object`, `position`,
+   * `event_id`, `tracker`, `page`, `browser` - are overwritten by it; use
+   * {@link Tracker.dispatch} for full control of the event shape.
+   */
+  [key: string]: unknown;
+};
+/** Options for {@link Tracker.trackResultEvent}. */
+type TrackResultEventOptions = {
+  /** The UBI `action_name` (e.g. `"add_to_cart"`, `"purchase"`, `"view"`). */
+  actionName: string;
+  /** The identifier of the object (e.g. product/SKU) the event is about. */
+  objectId: string;
+  /** The backend field the object id maps to (UBI `object_id_field`). Optional. */
+  objectIdField?: string;
+  /**
+   * The absolute, 1-based rank the result was returned at. Optional: when
+   * omitted it is resolved from the attribution recorded by
+   * {@link Tracker.trackResultClick} for the same `objectId`. When neither is
+   * available the event carries no position.
+   */
+  ordinal?: number;
+  /**
+   * The server-issued `query_id` that produced this result. Optional: when
+   * omitted it is resolved from the attribution recorded by
+   * {@link Tracker.trackResultClick} for the same `objectId`, so a conversion
+   * on a later page joins to the originating query without the integrator
+   * threading it by hand. When neither is available the event is sent
+   * unattributed and a warning is logged once.
+   */
+  queryId?: string;
+  /** The query text as the user entered it, if known (populates `user_query`). */
+  query?: string;
+  /**
+   * Any additional keys are persisted as-is under the event's
+   * `event_attributes` (e.g. `badge: "sale"`). Values must be
+   * JSON-serialisable. Keys the tracker itself owns - `object`, `position`,
+   * `event_id`, `tracker`, `page`, `browser` - are overwritten by it; use
+   * {@link Tracker.dispatch} for full control of the event shape.
+   */
+  [key: string]: unknown;
+};
+/** Options for {@link Tracker.trackResultClick}. */
+type TrackResultClickOptions = ResultRef & {
+  /** The server-issued `query_id` that produced this result. Required. */
+  queryId: string;
+  /** The query text as the user entered it, if known (populates `user_query`). */
+  query?: string;
+  /** Override the `action_name`. Defaults to `"click"`. */
+  actionName?: string;
+};
+/** Options for {@link Tracker.trackResultImpression}. */
+type TrackResultImpressionOptions = {
+  /** The results that became visible, each with its object id and absolute rank. */
+  items: ResultRef[];
+  /** The server-issued `query_id` that produced these results. Required. */
+  queryId: string;
+  /** The query text as the user entered it, if known (populates `user_query`). */
+  query?: string;
+};
+/** Options for {@link Tracker.trackSearch}. */
+type TrackSearchOptions = {
+  /** The query text as the user entered it. */
+  query: string;
+  /** The server-issued `query_id` for this search. Required. */
+  queryId: string;
+  /**
+   * Any additional keys are persisted as-is under the event's
+   * `event_attributes` (e.g. `badge: "sale"`). Values must be
+   * JSON-serialisable. Keys the tracker itself owns - `object`, `position`,
+   * `event_id`, `tracker`, `page`, `browser` - are overwritten by it; use
+   * {@link Tracker.dispatch} for full control of the event shape.
+   */
+  [key: string]: unknown;
+};
+/**
+ * The entry point of `@releval/tracker`: collects User Behavior Insights
+ * events - searches, result impressions, result clicks and the conversions
+ * that follow - in the canonical joinable shape
+ * (`query_id` + `object_id` + `ordinal`) and delivers them to a Releval
+ * deployment's track-event API.
+ *
+ * Events flow through a small pipeline: the high-level `track*` methods (or
+ * the declarative collectors) build canonical events, enrichers stamp
+ * context (application, session, client id, page, browser), and sinks
+ * deliver - batched with retry to the endpoint, or to the console in
+ * development. Nothing is delivered before {@link Tracker.start}; earlier
+ * dispatches are buffered and replayed.
+ *
+ * @example
+ * ```ts
+ * const tracker = new Tracker({
+ *   application: "primary-search",
+ *   siteId: "YOUR_SITE_ID",
+ *   endpointHost: "https://releval.example.com",
+ * });
+ * tracker.start();
+ *
+ * tracker.trackSearch({ query, queryId }); // ids come from your backend
+ * tracker.trackResultClick({ objectId, ordinal, queryId });
+ * tracker.trackResultEvent({ actionName: "add_to_cart", objectId });
+ * ```
+ *
+ * The full integration flow is documented at
+ * https://releval.co/docs/user-behavior-insights/browser-tracker
+ */
+declare class Tracker {
+  private readonly enrichers;
+  private readonly options;
+  private readonly _sessionManager;
+  private started;
+  private hasEverStarted;
+  private collectors;
+  private readonly detaches;
+  private sink?;
+  private batchSink?;
+  private readonly logger;
+  private dispatcher?;
+  private _clientId?;
+  private _userId?;
+  private _attribution?;
+  private hasWarnedMissingQueryId;
+  private hasWarnedUnattributedResult;
+  private hasWarnedInvalidOrdinal;
+  private readonly preStartBuffer;
+  private hasWarnedPreStartOverflow;
+  private readonly seenImpressions;
+  private readonly extraSinks;
+  constructor(options: TrackerOptions);
+  private _localStorage?;
+  /**
+   * The tracker's local storage (with fallbacks when Web Storage is
+   * unavailable). Internal: collectors and stores receive it via options.
+   */
+  private get localStorage();
+  private _sessionStorage?;
+  /**
+   * The tracker's session storage (with fallbacks when Web Storage is
+   * unavailable). Internal: collectors and stores receive it via options.
+   */
+  private get sessionStorage();
+  /**
+   * Gets the session identifier. Automatically rotates on inactivity or max duration.
+   */
+  get sessionId(): string;
+  /**
+   * Gets the stable anonymous client/device ID. Persisted in localStorage across sessions.
+   */
+  get clientId(): string;
+  /**
+   * Sets (or clears, with `undefined`) the user id stamped on events - for a
+   * login or logout that happens without a page reload. Applies to events
+   * dispatched after the call; events already queued or persisted for retry
+   * keep the identity they were stamped with. An explicit `user_id` on a
+   * dispatched event still wins. Callable before `start()`. Does not rotate
+   * the session or touch the client id. The value must be an opaque,
+   * pseudonymous identifier - never an email address or name.
+   */
+  setUserId(userId: string | undefined): void;
+  /**
+   * The object-keyed attribution store, created on first use so construction
+   * performs no storage IO for it.
+   */
+  private get attribution();
+  /**
+   * Returns the attribution recorded by {@link Tracker.trackResultClick} for
+   * an object in the current session, or undefined. Use it to build custom
+   * conversion payloads (e.g. a checkout page resolving several line items).
+   */
+  getResultAttribution(objectId: string): AttributionRecord | undefined;
+  /**
+   * Reports that a search ran, with the server-issued `query_id`. Call this
+   * after your search backend returns results.
+   *
+   * Dispatches a `search` event (`message_type: "QUERY"`) carrying `query_id`
+   * and `user_query`. Without it a query that gets no impression and no click
+   * leaves no event at all, so abandonment and reformulation cannot be
+   * analysed downstream.
+   */
+  trackSearch(options: TrackSearchOptions): void;
+  /**
+   * Dispatches a UBI event for a search result in the canonical shape
+   * (`query_id`, `event_attributes.object.object_id`, `event_attributes.position.ordinal`),
+   * so callers never hand-build it. Prefer {@link Tracker.trackResultClick} /
+   * {@link Tracker.trackResultImpression}; use this directly for conversions
+   * (e.g. `actionName: "add_to_cart"` or `"purchase"`), where `queryId` and
+   * `ordinal` may be omitted and are resolved from the attribution recorded
+   * when the result was clicked - including on a later page. When `queryId`
+   * IS supplied and matches the recorded click, a missing `ordinal`/`query`
+   * is still borrowed from it, so the row shape does not depend on which
+   * page supplied the id.
+   */
+  trackResultEvent(options: TrackResultEventOptions): void;
+  /**
+   * Dispatches a `click` event for a clicked search result, attributed to
+   * `queryId` (required at the call site by design), and records the
+   * attribution for the object so later conversion events for it - on this
+   * page or a later one - resolve the originating query automatically.
+   */
+  trackResultClick(options: TrackResultClickOptions): void;
+  /**
+   * Dispatches an `impression` event for each result that became visible,
+   * attributed to `queryId`. Emits one canonical event per item so impressions
+   * join to clicks on `object_id`/`ordinal`.
+   *
+   * Each `(queryId, objectId)` pair is reported ONCE per Tracker instance:
+   * re-renders, virtualized-list remounts and re-discovered elements do not
+   * inflate the impression count (the CTR denominator), while a new `queryId`
+   * re-fires for results returned by consecutive searches. A full page load
+   * builds a fresh Tracker and so starts fresh; when revisits matter,
+   * deduplicate downstream on distinct `(query_id, object_id)`.
+   */
+  trackResultImpression(options: TrackResultImpressionOptions): void;
+  /**
+   * Adds an enricher that runs on every event before emission (e.g. stamping
+   * an A/B variant, store or locale - the split key for any comparison).
+   * Returns a disposer that removes it again.
+   */
+  addEnricher(enricher: Enricher): () => void;
+  /**
+   * Registers a collector so it attaches at start() (or immediately when the
+   * tracker is already started), and returns a function that detaches and
+   * unregisters it again.
+   */
+  private registerCollector;
+  /**
+   * Binds declarative result-click collection to the DOM: one delegated
+   * listener reports clicks on elements matching `selector` in the canonical
+   * joinable shape, reading `data-object-id` / `data-ordinal` from the result
+   * element and `data-query-id` from its nearest ancestor (or a custom
+   * `resolve`). A resolved `data-action-name` other than `click` (e.g.
+   * `add_to_cart`) is routed through {@link Tracker.trackResultEvent}, so its
+   * attribution can resolve from the recorded click.
+   *
+   * Use `ignore` for interactive descendants of a result (an add-to-cart
+   * button inside the card) so their clicks are not double-reported as result
+   * clicks.
+   *
+   * @returns a function that stops this collection again.
+   */
+  trackResultClicks(options: TrackResultClicksOptions): () => void;
+  /** Routes a resolved declarative click through the high-level API. */
+  private emitResolvedResultClick;
+  /**
+   * Binds declarative result-impression collection to the DOM: each element
+   * matching `selector` emits one canonical `impression` event the first time
+   * it enters the viewport, attributed via the same data-attribute convention
+   * as {@link Tracker.trackResultClicks} (or a custom `resolve`). Elements
+   * added or re-rendered after `start()` are discovered automatically.
+   *
+   * @returns a function that stops this collection again.
+   */
+  trackResultImpressions(options: TrackResultImpressionsOptions): () => void;
+  /**
+   * Adds a sink that receives every emitted event (e.g. mirroring into your
+   * own analytics, or a test spy). Returns a disposer that removes it again.
+   */
+  addSink(sink: Sink): () => void;
+  /**
+   * starts the tracker and attaches all collectors.
+   */
+  start(): void;
+  /**
+   * Builds the effective sink from the configured endpoint plus any user sinks.
+   * ConsoleSink is used only when there is neither an endpoint nor a user sink
+   * (the development default). The result is always an AggregateSink so its
+   * reference stays stable across addSink() calls.
+   */
+  private buildSink;
+  /**
+   * Dispatches an event through the tracker pipeline (enrichers → sinks).
+   * Use this to send custom events that aren't captured by a collector.
+   * Safe to call before start(): the event is buffered (bounded), stamped
+   * with the timestamp of the moment it happened, and replayed once start()
+   * runs.
+   * @param event The event to dispatch.
+   */
+  dispatch(event: Event): void;
+  /**
+   * Forces immediate delivery of any queued events, rather than waiting for the
+   * next batch interval. Useful before a critical action or a hard navigation.
+   * Resolves once the current batch has been sent (or scheduled for retry).
+   * A no-op that resolves immediately when there is no batching sink (events go
+   * to the console) or the tracker is stopped.
+   */
+  flush(): Promise<void>;
+  /**
+   * stops the tracker and detaches all collectors.
+   */
+  stop(): void;
+}
+//#endregion
+//#region src/collectors/ResultImpressionCollector.d.ts
+/**
+ * The result data resolved for an element that became visible: the shared
+ * {@link ResolvedResultData} shape. `actionName` is ignored here - an
+ * impression is always an `impression`.
+ */
+type ResolvedResultImpression = ResolvedResultData;
+/**
+ * Resolves the result data for a visible element. Return `undefined` to skip
+ * it. The default implementation reads the data-attribute convention described
+ * on {@link readResultData}.
+ */
+type ResultImpressionResolve = (element: HTMLElement) => ResolvedResultImpression | undefined;
+/** Options for `Tracker.trackResultImpressions`. */
+type TrackResultImpressionsOptions = {
+  /** CSS selector of result elements to observe for viewport visibility. */
+  selector: string;
+  /** The root observed for matching elements. Defaults to `document`. */
+  root?: Document | Element;
+  /** Custom resolver; defaults to the data-attribute convention. */
+  resolve?: ResultImpressionResolve;
+};
+//#endregion
+export { AttributionRecord as C, EventPosition as S, Sink as _, TrackResultClickOptions as a, EventAttributes as b, TrackSearchOptions as c, TrackerOptions as d, ResolvedResultClick as f, readResultData as g, ResolvedResultData as h, ResultRef as i, Tracker as l, TrackResultClicksOptions as m, ResultImpressionResolve as n, TrackResultEventOptions as o, ResultClickResolve as p, TrackResultImpressionsOptions as r, TrackResultImpressionOptions as s, ResolvedResultImpression as t, TrackerBaseOptions as u, Enricher as v, Logger as w, EventObject as x, Event as y };
+//# sourceMappingURL=ResultImpressionCollector.d.mts.map