/**
 * Automatic event bridge from `vt.capture()` into `gtag('event', ...)`.
 *
 * Two layers run in order on every captured event:
 *
 * 1. **GA4 forwarder** (`forwardToGtag`) — applies the admin's
 *    `event_filter`, then an explicit `event_mappings` row, then a built-in
 *    preset (e.g. `$pageview` → `page_view`), then the `autoForward`
 *    default-on fallback. Fires `gtag('event', mapped_name, params)` on
 *    success. This is the primary path: because most customers link GA4 to
 *    Google Ads, the GA4 event flows to Ads automatically when marked as a
 *    conversion.
 * 2. **Ads-only conversions** (`forwardEvent`) — for customers who
 *    configured direct Ads conversion mappings on the destination. Fires
 *    `gtag('event', 'conversion', {send_to: 'AW-.../...'})`. Unchanged by
 *    design so existing deployments keep working.
 *
 * Matching on both layers is by exact event name. vTilt's own internal
 * events (`$identify`, `$set`, etc.) are skipped unless the admin wired
 * them up explicitly.
 */
import type { GoogleAdsConversionMapping, GoogleTagClientConfig } from "../../types";
import type { GtagFn } from "./consent-bridge";
export interface ConversionBuildOptions {
    mapping: GoogleAdsConversionMapping;
    payload: Record<string, unknown>;
}
export interface BuiltConversion {
    send_to: string;
    params: Record<string, unknown>;
}
export declare function buildConversionParams({ mapping, payload, }: ConversionBuildOptions): BuiltConversion;
/**
 * Bridge a single captured event to gtag using the Ads conversion mappings
 * that match `eventName`. Each matching mapping results in one
 * `gtag('event', 'conversion', ...)` call.
 */
export declare function forwardEvent(gtag: GtagFn, eventName: string, payload: Record<string, unknown>, config: GoogleTagClientConfig): BuiltConversion[];
/**
 * Check whether a captured event name is allowed by the admin's
 * `event_filter`. `exclude` wins over `include`; an empty/missing
 * `include` means "all events pass". Mirrors the server-side filter
 * semantics exactly.
 */
export declare function isEventAllowed(eventName: string, filter: GoogleTagClientConfig["eventFilter"]): boolean;
export interface ForwardToGtagResult {
    /** `true` when a `gtag('event', ...)` call was made. */
    fired: boolean;
    /** The event name that was forwarded (post-mapping/preset), if fired. */
    eventName?: string;
    /** The params object that was passed to gtag, if fired. */
    params?: Record<string, unknown>;
    /** Which rule produced the forward. */
    source?: "mapping" | "preset" | "auto";
}
/**
 * Forward one captured event to gtag as a GA4 event. Resolution order:
 *
 * 1. Filter — `event_filter.exclude` drops, then `event_filter.include`
 *    (when non-empty) whitelists. Same as the server-side filter.
 * 2. Explicit mapping — an `event_mappings` row with matching `source`
 *    wins and always fires, regardless of `autoForward`. This is the
 *    admin's "force fire" path.
 * 3. Built-in preset — when no explicit mapping is set and
 *    `autoForward !== false`, `$pageview`/`$pageleave` fire their GA4
 *    analogues with sensibly-named params.
 * 4. Auto-forward fallback — when `autoForward !== false` and the event
 *    is not a `$*` internal event, fire `gtag('event', eventName, payload)`
 *    with reserved/internal keys stripped.
 *
 * Admins who want a strict allowlist set `autoForward: false` and use
 * `event_mappings` to enumerate the events they care about.
 */
export declare function forwardToGtag(gtag: GtagFn, eventName: string, payload: Record<string, unknown>, config: GoogleTagClientConfig): ForwardToGtagResult;