/**
 * useCardAnalytics — V4 batched-event wiring for product/item card primitives.
 *
 * Bundles the impression + click events every product/item card should
 * emit. The pair of events fired depends on the card's `surface`:
 *
 *   * `"results_page"` / `"dropdown"` — search-attributed. Records the
 *     card's viewport entry into the `SearchImpressionBuffer` and its
 *     click into the `ObjectClickedBuffer` (search-attributed bucket).
 *     The buffers flush ONE batched event with parallel arrays per
 *     `(search_id, surface)` bucket — never per card.
 *   * `"recommendation_widget"` / `"outside_search"` — not search-attributed.
 *     Records visibility into the `ObjectViewedBuffer` and clicks into
 *     the outside-search bucket of `ObjectClickedBuffer`. Flushes ONE
 *     `Object Viewed` and ONE `Object Clicked Outside Search` per
 *     `(surface)` bucket.
 *
 * Returns a `ref` to attach to the card root + a wrapped click handler.
 * Consumer components (ProductCard, ItemCard, etc.) keep their own
 * markup; this hook owns the tracker plumbing so we don't repeat it.
 *
 * Requires a `<BufferProvider>` above (which `SearchResults` and other
 * consumers wrap automatically). If no provider is above, the buffer
 * hooks return no-op shims so descendant cards still render and click
 * handlers still navigate — the only thing that goes silent is the V4
 * analytics emission.
 *
 * Phase 2b — SCRUM-259 V4 pivot (replaces the per-card emission model).
 */
import type { RefObject } from "react";
/**
 * Card surfaces.
 *
 * `"recommendation_widget"` and `"outside_search"` route through the
 * outside-search buckets of the click + viewed buffers. The string is
 * preserved on the wire as the event's `surface` property.
 */
export type CardSurface = "results_page" | "dropdown" | "recommendation_widget" | "outside_search";
export interface UseCardAnalyticsProps {
    /** Canonical object id (typically `product.id` or `item.id`). */
    objectId: string;
    /**
     * 1-based position in the result set (accounts for pagination so a
     * card on page 2 row 3 reports position=23 not position=3 when
     * itemsPerPage=10). Consumer is responsible for this math.
     */
    position: number;
    /** Object kind. Defaults to `"product"`. Threaded into `objectData.object_type`. */
    objectType?: string;
    /**
     * Where the card is rendered. Drives downstream funnel attribution
     * AND which buffer the impression/click lands in:
     *   - "results_page"          — search-attributed (impression + click buffers)
     *   - "dropdown"              — search-attributed (impression + click buffers)
     *   - "recommendation_widget" — outside-search (viewed + click-outside buffers)
     *   - "outside_search"        — outside-search (viewed + click-outside buffers)
     * Defaults to "results_page".
     */
    surface?: CardSurface;
    /**
     * Search session id (search_id, the Seekora-canonical attribution UUID).
     * Required for search-attributed surfaces — without it the buffer
     * can't bucket the event. Outside-search surfaces ignore this field.
     */
    searchId?: string;
    /**
     * Optional per-card `objectData[i]` payload (price, name, image_url,
     * category, etc.). Stamped into the parallel `objectData[]` array on
     * the flushed batched event.
     */
    objectData?: Record<string, unknown>;
    /**
     * Consumer's click callback. Invoked AFTER the V4 click event has
     * been recorded into the buffer, so analytics is correct even if the
     * callback navigates away synchronously.
     */
    onSelect?: () => void;
    /**
     * Master enable flag. When false, neither impression nor click events
     * are recorded (consumer's onSelect still runs on click). Defaults
     * to true.
     */
    enabled?: boolean;
}
export interface UseCardAnalyticsReturn {
    /** Attach to the card's root element. */
    ref: RefObject<HTMLElement | null>;
    /** Replacement for the card root's `onClick` — records V4 then calls onSelect. */
    onClick: () => void;
}
export declare function useCardAnalytics(props: UseCardAnalyticsProps): UseCardAnalyticsReturn;
//# sourceMappingURL=useCardAnalytics.d.ts.map