import { AutoActivityEvent } from '@particle-academy/fancy-auto-common';

/**
 * In-browser heuristics analytics sink for agent traffic.
 *
 * Agent bridge mutations emit `AutoActivityEvent`s into the in-page
 * `@particle-academy/fancy-auto-common` activity bus (presence / cursors).
 * This sink — living in THIS package so it shares the SAME bundled
 * `fancy-auto-common` module instance the bridges emit into — subscribes to
 * that bus and POSTs each event to the `fancy-heuristics` `/collect` endpoint
 * as `actor:"agent"`, so agent traffic shows up in the heuristics dashboard.
 *
 * It does NOT depend on `fancy-heuristics` / `fancy-heuristics-js`: it only
 * emits the frozen wire shape over HTTP. The mapping mirrors
 * `fancy-heuristics-js/src/agent.ts` `mapActivityToEvent` — keep parity.
 */

/** What kind of interaction an event captures (mirrors fancy-heuristics-js). */
type HeuristicsEventKind = "pageview" | "click" | "scroll" | "pointer" | "dwell";
/** Who produced the interaction. */
type HeuristicsActor = "human" | "agent";
/**
 * A single interaction event — mirrors `fancy-heuristics-js` `HeuristicsEvent`.
 * Optional fields are omitted (never `null`) when not relevant to the `kind`.
 */
interface HeuristicsEvent {
    kind: HeuristicsEventKind;
    actor: HeuristicsActor;
    /** location.pathname at capture time. */
    path: string;
    /** ms epoch. */
    ts: number;
    x?: number;
    y?: number;
    vw?: number;
    vh?: number;
    scrollPct?: number;
    dwellMs?: number;
    targetId?: string;
    label?: string;
    meta?: Record<string, unknown>;
}
/** The batched POST body sent to `${endpoint}/collect`. */
interface CollectBatch {
    siteKey: string;
    sessionId: string;
    events: HeuristicsEvent[];
}
interface AttachHeuristicsSinkOptions {
    /** Base URL, e.g. "/heuristics". POSTs to `${endpoint}/collect`. */
    endpoint: string;
    /** Identifies the site to the ingestion endpoint. */
    siteKey: string;
    /** Stable session id. Default: a generated "agent-<rand>" per attach. */
    sessionId?: string;
    /** Resolves the current path. Default: `() => location.pathname`. */
    path?: () => string;
    /** Which activity sources to record. Default "all". */
    source?: "agent" | "flow" | "all";
    /** Flush interval in ms. Default 2000. */
    batchMs?: number;
}
/**
 * Map one activity event to an `actor:"agent"` HeuristicsEvent. Activities
 * carrying a finite `meta.dwellMs` become `kind:"dwell"`; everything else is a
 * discrete `kind:"click"` with x/y/vw/vh pulled from numeric meta (default 0).
 * Mirrors `fancy-heuristics-js/src/agent.ts` `mapActivityToEvent`.
 */
declare function mapActivityToEvent(e: AutoActivityEvent, path: string): HeuristicsEvent;
/**
 * Subscribe to the in-page agent activity bus and forward each matching event
 * to the heuristics `/collect` endpoint as `actor:"agent"`. SSR-safe (returns a
 * no-op when there is no `window`). Returns an unsubscribe that flushes the
 * buffer and detaches all listeners/timers.
 */
declare function attachHeuristicsSink(opts: AttachHeuristicsSinkOptions): () => void;

export { type AttachHeuristicsSinkOptions, type CollectBatch, type HeuristicsEvent, attachHeuristicsSink, mapActivityToEvent };