@objectiv/tracker-browser/dist/index.d.ts

Objectiv Web application analytics tracker for the open analytics taxonomy

import { TrackerConfig, TrackerPluginInterface, TrackerQueueInterface, TrackerTransportInterface, Tracker, ContextsConfig, LocationStack, GlobalContexts, TrackerEventAttributes, TrackerRepositoryInterface } from '@objectiv/tracker-core';
export * from '@objectiv/tracker-core';
import { ContentContext, ExpandableContext, InputContext, LinkContext, MediaPlayerContext, NavigationContext, OverlayContext, PressableContext, RootLocationContext, AbstractLocationContext } from '@objectiv/schema';

/**
 * Browser Tracker can be configured in a easier way, as opposed to the core tracker, by specifying just an `endpoint`.
 * Internally it will automatically configure the Transport layer for the given `endpoint` with sensible defaults.
 * It also accepts a number of options to configure automatic tracking behavior:
 */
declare type BrowserTrackerConfig = Omit<TrackerConfig, 'platform'> & {
    /**
     * Optional. Whether to track application loaded events automatically. Enabled by default.
     */
    trackApplicationLoadedEvent?: boolean;
    /**
     * Optional. Whether to track ApplicationContext automatically. Enabled by default.
     */
    trackApplicationContext?: boolean;
    /**
     * Optional. Whether to automatically create HttpContext based on Document and Navigation APIs. Enabled by default.
     */
    trackHttpContext?: boolean;
    /**
     * Optional. Whether to automatically create PathContext based on URLs. Enabled by default.
     */
    trackPathContextFromURL?: boolean;
    /**
     * Optional. Whether to automatically create RootLocationContext based on URLs first slugs. Enabled by default.
     */
    trackRootLocationContextFromURL?: boolean;
};

/**
 * The default list of Plugins of Browser Tracker
 */
declare const makeBrowserTrackerDefaultPluginsList: (trackerConfig: BrowserTrackerConfig) => TrackerPluginInterface[];

/**
 * A factory to create the default Queue of Browser Tracker.
 */
declare const makeBrowserTrackerDefaultQueue: (trackerConfig: BrowserTrackerConfig) => TrackerQueueInterface;

/**
 * A factory to create the default Transport of Browser Tracker.
 */
declare const makeBrowserTrackerDefaultTransport: () => TrackerTransportInterface;

/**
 * FlushQueue Options for TrackClicks TaggingAttribute
 */
declare type FlushQueueOptions = false | true | 'onTimeout';

/**
 * A type guard to determine if the given options is FlushQueueOptions.
 */
declare const isFlushQueueOptions: (options: Partial<FlushQueueOptions>) => options is FlushQueueOptions;

declare type AnyLocationContext = ContentContext | ExpandableContext | InputContext | LinkContext | MediaPlayerContext | NavigationContext | OverlayContext | PressableContext | RootLocationContext;
/**
 * Union to match any PressableContext
 */
declare type AnyPressableContext = LinkContext | PressableContext;
/**
 * Union to match any Showable Context, that is Overlays and ExpandableContext
 */
declare type AnyShowableContext = OverlayContext | ExpandableContext;

/**
 * A type guard to determine if the given object is a LocationContext.
 */
declare const isLocationContext: (locationContext: AbstractLocationContext) => locationContext is AnyLocationContext;

/**
 * All the attributes that are added to a DOM Element to make it trackable
 */
declare enum TaggingAttribute {
    elementId = "data-objectiv-element-id",
    parentElementId = "data-objectiv-parent-element-id",
    context = "data-objectiv-context",
    trackClicks = "data-objectiv-track-clicks",
    trackBlurs = "data-objectiv-track-blurs",
    trackVisibility = "data-objectiv-track-visibility",
    tagChildren = "data-objectiv-tag-children",
    tracked = "data-objectiv-tracked",
    validate = "data-objectiv-validate"
}

/**
 * The object that Location Taggers return, stringified
 */
declare type TagLocationAttributes = {
    [TaggingAttribute.elementId]: string;
    [TaggingAttribute.parentElementId]?: string;
    [TaggingAttribute.context]: string;
    [TaggingAttribute.trackClicks]?: string;
    [TaggingAttribute.trackBlurs]?: string;
    [TaggingAttribute.trackVisibility]?: string;
    [TaggingAttribute.validate]?: string;
};

/**
 * The object returned by `tagLocation` and its shorthands
 */
declare type TagLocationReturnValue = TagLocationAttributes | undefined;

/**
 * The definition for the `trackBlurs` Tagging Attribute
 */
declare type TrackBlursAttribute = boolean | {
    trackValue: boolean;
};

/**
 * WaitUntilTracked Options for TrackClick TaggingAttribute
 */
declare type WaitUntilTrackedOptions = {
    intervalMs?: number;
    timeoutMs?: number;
    flushQueue?: FlushQueueOptions;
};

/**
 * The definition for the `trackClicks` Tagging Attribute
 */
declare type TrackClicksAttribute = boolean | {
    waitUntilTracked: true | WaitUntilTrackedOptions;
};

/**
 * The definition of the `trackVisibility` Tagging Attribute
 */
declare type TrackVisibilityAttribute = boolean | {
    mode: 'auto';
} | {
    mode: 'manual';
    isVisible: boolean;
};

/**
 * The definition of the `validate` Tagging Attribute
 */
declare type ValidateAttribute = {
    locationUniqueness: boolean;
};

/**
 * The options object that tagLocation and its shorthands accept
 */
declare type TagLocationOptions = {
    trackClicks?: TrackClicksAttribute;
    trackBlurs?: TrackBlursAttribute;
    trackVisibility?: TrackVisibilityAttribute;
    parent?: TagLocationReturnValue;
    validate?: ValidateAttribute;
};

/**
 * Generic onError callback definition used by `trackerErrorHandler`.
 */
declare type TrackerErrorHandlerCallback = <T = unknown>(error: unknown, parameters?: T) => void;

/**
 * LocationTaggers are shorthands around tagLocation.
 */
declare type LocationTaggerParameters = {
    id: string;
    options?: TagLocationOptions;
    onError?: TrackerErrorHandlerCallback;
};

/**
 * A type guard to determine if the given object is a LocationTaggerParameters.
 */
declare const isLocationTaggerParameters: (object: Partial<LocationTaggerParameters>) => object is LocationTaggerParameters;

/**
 * The type of Elements the type guards can work with
 */
declare type GuardableElement = Node | EventTarget | null;

/**
 * A Taggable Element is an HTMLElement or an SVGElement
 */
declare type TaggableElement = HTMLElement | SVGElement;

/**
 * A ParentTaggedElement is a TaggedElement with the TaggingAttribute.parentElementId
 */
declare type ParentTaggedElement = TaggableElement & Pick<TagLocationAttributes, TaggingAttribute.parentElementId>;

/**
 * A type guard to determine if the given Element is a TaggableElement decorated with LocationTaggingAttributes.parentElementId.
 */
declare const isParentTaggedElement: (element: GuardableElement) => element is ParentTaggedElement;

/**
 * A type guard to determine if the given LocationContext supports PressEvent.
 */
declare const isPressableContext: (locationContext: AnyLocationContext) => locationContext is AnyPressableContext;

/**
 * A type guard to determine if the given LocationContext supports HiddenEvent and VisibleEvent.
 */
declare const isShowableContext: (locationContext: AnyLocationContext) => locationContext is AnyShowableContext;

/**
 * The stringified version of the `ChildrenTaggingAttributes`
 */
declare type TagChildrenAttributes = {
    [TaggingAttribute.tagChildren]: string;
};

/**
 * A TagChildrenElement is a TaggableElement already decorated with our ChildrenTaggingAttributes
 */
declare type TagChildrenElement = TaggableElement & TagChildrenAttributes;

/**
 * A type guard to determine if the given Element is a TaggableElement decorated with ChildrenLocationTaggingAttributes.
 */
declare const isTagChildrenElement: (element: GuardableElement) => element is TagChildrenElement;

/**
 * A type guard to determine if a the given Element is an HTMLElement or SVGElement.
 * In general we can only tag Elements supporting dataset attributes.
 */
declare const isTaggableElement: (element: GuardableElement) => element is TaggableElement;

/**
 * A TaggedElement is a TaggableElement already decorated with our LocationTaggingAttributes
 */
declare type TaggedElement = TaggableElement & TagLocationAttributes;

/**
 * A type guard to determine if the given Element is a TaggableElement decorated with LocationTaggingAttributes.
 * Note: For performance and simplicity we only check if `context` is present. Assume all other attributes are there.
 */
declare const isTaggedElement: (element: GuardableElement) => element is TaggedElement;

/**
 * A type guard to determine if the given object is a isTagLocationAttributes.
 */
declare const isTagLocationAttributes: (object: Partial<TagLocationAttributes>) => object is TagLocationAttributes;

/**
 * A type guard to determine if the given object is a TagLocationOptions.
 */
declare const isTagLocationOptions: (object: Partial<TagLocationOptions>) => object is TagLocationOptions;

/**
 * The parameters of `tagLocation` and its shorthands
 */
declare type TagLocationParameters = {
    instance: AnyLocationContext;
    options?: TagLocationOptions;
    onError?: TrackerErrorHandlerCallback;
};

/**
 * A type guard to determine if the given object is a TagLocationParameters.
 */
declare const isTagLocationParameters: (object: Partial<TagLocationParameters>) => object is TagLocationParameters;

/**
 * A type guard to determine if the given object is TrackBlursAttribute.
 */
declare const isTrackBlursAttribute: (attribute: Partial<TrackBlursAttribute>) => attribute is TrackBlursAttribute;

/**
 * A type guard to determine if the given object is TrackClicksAttribute.
 */
declare const isTrackClicksAttribute: (attribute: Partial<TrackClicksAttribute>) => attribute is TrackClicksAttribute;

/**
 * A type guard to determine if the given object is a TrackVisibilityAttribute.
 */
declare const isTrackVisibilityAttribute: (attribute: Partial<TrackVisibilityAttribute>) => attribute is TrackVisibilityAttribute;

/**
 * A type guard to determine if the given object is a ValidateAttribute.
 */
declare const isValidateAttribute: (object: Partial<ValidateAttribute>) => object is ValidateAttribute;

/**
 * The parameters of `tagChild` where `tagAs` is a valid TagLocationAttributes
 */
declare type ValidChildrenTaggingQuery = {
    queryAll: string;
    tagAs: TagLocationAttributes;
};

/**
 * A type guard to determine if the given object is a TagChildrenParameters.
 */
declare const isValidChildrenTaggingQuery: (object: Partial<ValidChildrenTaggingQuery>) => object is ValidChildrenTaggingQuery;

/**
 * A type guard to determine if the given object is WaitUntilTrackedOptions.
 */
declare const isWaitUntilTrackedOptions: (object: Partial<WaitUntilTrackedOptions>) => object is WaitUntilTrackedOptions;

/**
 * JSON Objects parser
 */
declare const parseJson: (stringifiedObject: string | null) => any;

/**
 * LocationContexts parser
 */
declare const parseLocationContext: (stringifiedContext: string | null) => AnyLocationContext;

/**
 * ChildrenTaggingAttribute parser
 */
declare const parseTagChildren: (stringifiedChildrenTaggingAttribute: string | null) => ValidChildrenTaggingQuery[];

/**
 * The Options attribute of the TrackBlurs TaggingAttribute
 */
declare type TrackBlursOptions = undefined | {
    trackValue?: boolean;
};

/**
 * `trackBlurs` Tagging Attribute to TrackBlursOptions parser
 */
declare const parseTrackBlurs: (stringifiedTrackBlursAttribute: string | null) => TrackBlursOptions;

/**
 * WaitForQueueOptions Options for TrackClicks TaggingAttribute
 */
declare type WaitForQueueOptions = {
    intervalMs?: number;
    timeoutMs?: number;
};

/**
 * The Options attribute of the TrackClicks TaggingAttribute
 */
declare type TrackClicksOptions = undefined | {
    waitForQueue?: WaitForQueueOptions;
    flushQueue?: FlushQueueOptions;
};

/**
 * `trackClicks` Tagging Attribute to TrackClicksOptions parser
 * Differently than other simplistic parsers, this one transforms the `trackClicks` attribute in a different format.
 */
declare const parseTrackClicks: (stringifiedTrackClicksAttribute: string | null) => TrackClicksOptions;

/**
 * The definition of a parsed `trackVisibility` Tagging Attribute
 */
declare type TrackVisibilityOptions = undefined | {
    mode: 'auto';
} | {
    mode: 'manual';
    isVisible: boolean;
};

/**
 * `trackVisibility` Tagging Attribute parser
 */
declare const parseTrackVisibility: (stringifiedTrackVisibilityAttribute: string | null) => TrackVisibilityOptions;

/**
 * `validate` Tagging Attribute parser
 */
declare const parseValidate: (stringifiedValidateAttribute: string | null) => ValidateAttribute;

/**
 * JSON Objects stringifier
 */
declare const stringifyJson: (object: unknown) => string;

/**
 * LocationContexts stringifier
 */
declare const stringifyLocationContext: (contextObject: AnyLocationContext) => string;

/**
 * The parameters of `tagChild`
 */
declare type ChildrenTaggingQuery = {
    queryAll: string;
    tagAs?: TagLocationAttributes;
};

/**
 * The parameters of `tagChildren`
 */
declare type ChildrenTaggingQueries = ChildrenTaggingQuery[];

/**
 * ChildrenTaggingAttribute stringifier
 */
declare const stringifyTagChildren: (queries: ChildrenTaggingQueries) => string;

/**
 * `trackBlurs` Tagging Attribute stringifier
 */
declare const stringifyTrackBlurs: (trackBlursAttribute: TrackBlursAttribute) => string;

/**
 * `trackClicks` Tagging Attribute stringifier
 */
declare const stringifyTrackClicks: (trackClicksAttribute: TrackClicksAttribute) => string;

/**
 * `trackVisibility` Tagging Attribute stringifier
 */
declare const stringifyTrackVisibility: (trackVisibilityAttribute: TrackVisibilityAttribute) => string;

/**
 * `validate` Tagging Attribute stringifier
 */
declare const stringifyValidate: (validateAttribute: ValidateAttribute) => string;

/**
 * Walk the DOM upwards looking for Tagged Elements. The resulting array can be used to reconstruct a Location Stack.
 */
declare const findParentTaggedElements: (element: TaggableElement | null, parentElements?: TaggedElement[]) => TaggedElement[];

/**
 * Browser Tracker is a Tracker Core constructor with simplified parameters and some preconfigured Plugins.
 * It initializes with a Queued Fetch and XMLHttpRequest Transport Switch wrapped in a Retry Transport automatically.
 * The resulting Queue has some sensible defaults (10 events every 100ms) for sending events in batches.
 * The Retry logic is configured for 10 retries with exponential backoff starting at 1000ms.
 *
 * This statement:
 *
 *  const tracker = new BrowserTracker({ applicationId: 'app-id', endpoint: '/endpoint' });
 *
 * is equivalent to:
 *
 *  const trackerId = trackerConfig.trackerId ?? trackerConfig.applicationId;
 *  const fetchTransport = new FetchTransport({ endpoint: '/endpoint' });
 *  const xhrTransport = new XHRTransport({ endpoint: '/endpoint' });
 *  const transportSwitch = new TransportSwitch({ transports: [fetchTransport, xhrTransport] });
 *  const transport = new RetryTransport({ transport: transportSwitch });
 *  const queueStorage = new LocalStorageQueueStore({ trackerId })
 *  const trackerQueue = new TrackerQueue({ storage: trackerStorage });
 *  const applicationContextPlugin = new ApplicationContextPlugin({ applicationId: 'app-id' });
 *  const httpContextPlugin = new HttpContextPlugin();
 *  const pathContextFromURLPlugin = new PathContextFromURLPlugin();
 *  const rootLocationContextFromURLPlugin = new RootLocationContextFromURLPlugin();
 *  const plugins = [
 *    applicationContextPlugin,
 *    httpContextPlugin,
 *    pathContextFromURLPlugin,
 *    rootLocationContextFromURLPlugin
 *  ];
 *  const tracker = new Tracker({ transport, queue, plugins });
 *
 *  @see makeBrowserTrackerDefaultPluginsList
 *  @see makeBrowserTrackerDefaultQueue
 *  @see makeBrowserTrackerDefaultTransport
 */
declare class BrowserTracker extends Tracker {
    readonly trackerConfig: TrackerConfig;
    constructor(trackerConfig: BrowserTrackerConfig, ...contextConfigs: ContextsConfig[]);
}

/**
 * A TrackedElement is either a TaggedElement or an EventTarget
 */
declare type TrackedElement = TaggableElement | EventTarget;

/**
 * Generates a location stack for the given Element. If a Tracker instance is provided, also predicts its mutations.
 *
 * 1. Traverses the DOM to reconstruct the component stack
 * 2. If a Tracker instance is provided, retrieves the Tracker's Location Stack
 * 3. Merges the two Location Stacks to reconstruct the full Location
 * 4. If a Tracker instance is provided, runs the Tracker's plugins `enrich` lifecycle on the locationStack
 */
declare const getElementLocationStack: (parameters: {
    element: TrackedElement;
    tracker?: BrowserTracker;
}) => LocationStack;

/**
 * Helper function to get the current Location href
 */
declare const getLocationHref: () => string | undefined;

/**
 * Executes `functionToRun(value)` only if the given `value` is not `undefined`
 */
declare const runIfValueIsNotUndefined: (functionToRun: Function, value: unknown) => any;

/**
 * Generic onError callback, parameter and error handler for tag and track functions.
 * Allows developers to provide an onError callback to handle errors themselves.
 * Default behavior is to TrackerConsole.error.
 */
declare const trackerErrorHandler: (error: unknown, parameters?: unknown, onError?: TrackerErrorHandlerCallback) => undefined;

/**
 * The parameters of the Event Tracker shorthand functions
 */
declare type InteractiveEventTrackerParameters = {
    element: TrackedElement;
    locationStack?: LocationStack;
    globalContexts?: GlobalContexts;
    tracker?: BrowserTracker;
    onError?: TrackerErrorHandlerCallback;
};

/**
 * The same parameters of regular Event Trackers, but all attributes are optional.
 */
declare type NonInteractiveEventTrackerParameters = Partial<InteractiveEventTrackerParameters>;

/**
 * The definition of the object returned by `tagChildren` and `tagChild`
 */
declare type TagChildrenReturnValue = TagChildrenAttributes | undefined;

/**
 * tagLink has one extra attribute, `href`, as mandatory parameter.
 */
declare type TagLinkParameters = LocationTaggerParameters & {
    href: string;
};

/**
 * trackFailureEvent has an extra attribute, `message`, as mandatory parameter.
 */
declare type TrackFailureEventParameters = NonInteractiveEventTrackerParameters & {
    message: string;
};

/**
 * trackSuccessEvent has an extra attribute, `message`, as mandatory parameter.
 */
declare type TrackSuccessEventParameters = NonInteractiveEventTrackerParameters & {
    message: string;
};

/**
 * trackFailureEvent is a shorthand for trackEvent. It eases triggering FailureEvent programmatically.
 */
declare const trackFailureEvent: (parameters: TrackFailureEventParameters) => void;

/**
 * trackApplicationLoadedEvent is a shorthand for trackEvent. It eases triggering ApplicationLoadedEvent
 * programmatically.
 */
declare const trackApplicationLoadedEvent: (parameters?: NonInteractiveEventTrackerParameters) => void;

/**
 * trackPressEvent is a shorthand for trackEvent. It eases triggering PressEvent programmatically.
 */
declare const trackPressEvent: ({ element, locationStack, globalContexts, tracker, onError, }: InteractiveEventTrackerParameters) => void;

/**
 * trackSuccessEvent is a shorthand for trackEvent. It eases triggering SuccessEvent programmatically.
 */
declare const trackSuccessEvent: (parameters: TrackSuccessEventParameters) => void;

/**
 * 1. Reconstruct a LocationStack for the given Element by traversing its DOM parents
 * 2. Factors a new Event with the given `_type`
 * 3. Tracks the new Event via WebTracker
 */
declare const trackEvent: (parameters: {
    event: TrackerEventAttributes;
    element?: TrackedElement;
    tracker?: BrowserTracker;
    trackerId?: string;
    onError?: TrackerErrorHandlerCallback;
}) => void;

/**
 * trackInputChangeEvent is a shorthand for trackEvent. It eases triggering InputChangeEvent programmatically.
 */
declare const trackInputChangeEvent: ({ element, locationStack, globalContexts, tracker, onError, }: InteractiveEventTrackerParameters) => void;

/**
 * trackInteractiveEvent is a shorthand for trackEvent. It eases triggering InteractiveEvent programmatically.
 */
declare const trackInteractiveEvent: ({ element, locationStack, globalContexts, tracker, onError, }: InteractiveEventTrackerParameters) => void;

/**
 * trackHiddenEvent is a shorthand for trackEvent. It eases triggering HiddenEvent programmatically.
 */
declare const trackHiddenEvent: ({ element, locationStack, globalContexts, tracker, onError, }: InteractiveEventTrackerParameters) => void;

/**
 * trackVisibleEvent is a shorthand for trackEvent. It eases triggering VisibleEvent programmatically.
 */
declare const trackVisibleEvent: ({ element, locationStack, globalContexts, tracker, onError, }: InteractiveEventTrackerParameters) => void;

/**
 * trackMediaEvent is a shorthand for trackEvent. It eases triggering MediaEvent programmatically.
 */
declare const trackMediaEvent: ({ element, locationStack, globalContexts, tracker, onError, }: InteractiveEventTrackerParameters) => void;

/**
 * trackMediaLoadEvent is a shorthand for trackEvent. It eases triggering MediaLoadEvent programmatically.
 */
declare const trackMediaLoadEvent: ({ element, locationStack, globalContexts, tracker, onError, }: InteractiveEventTrackerParameters) => void;

/**
 * trackMediaPauseEvent is a shorthand for trackEvent. It eases triggering MediaPauseEvent programmatically.
 */
declare const trackMediaPauseEvent: ({ element, locationStack, globalContexts, tracker, onError, }: InteractiveEventTrackerParameters) => void;

/**
 * trackMediaStartEvent is a shorthand for trackEvent. It eases triggering MediaStartEvent programmatically.
 */
declare const trackMediaStartEvent: ({ element, locationStack, globalContexts, tracker, onError, }: InteractiveEventTrackerParameters) => void;

/**
 * trackMediaStopEvent is a shorthand for trackEvent. It eases triggering MediaStopEvent programmatically.
 */
declare const trackMediaStopEvent: ({ element, locationStack, globalContexts, tracker, onError, }: InteractiveEventTrackerParameters) => void;

/**
 * trackNonInteractiveEvent is a shorthand for trackEvent. It eases triggering NonInteractiveEvent programmatically.
 */
declare const trackNonInteractiveEvent: ({ element, locationStack, globalContexts, tracker, onError, }: NonInteractiveEventTrackerParameters) => void;

/**
 * trackVisibility is a shorthand for trackEvent. It eases triggering visibility events programmatically
 */
declare const trackVisibility: ({ element, locationStack, globalContexts, tracker, isVisible, onError, }: InteractiveEventTrackerParameters & {
    isVisible: boolean;
}) => void;

/**
 * Syntactic sugar to track only one child.
 *
 * Examples
 *
 *    tagChild({
 *      query: '#button1',
 *      tagAs: tagPressable({ id: 'button1', text: 'Button 1' })
 *    })
 *
 *    tagChild({
 *      query: '#button2',
 *      tagAs: tagPressable({ id: 'button2', text: 'Button 2' })
 *    })
 *
 */
declare const tagChild: (parameters: ChildrenTaggingQuery, onError?: TrackerErrorHandlerCallback) => TagChildrenReturnValue;

/**
 * Used to decorate a TaggableElement with our Children Tagging Attributes.
 *
 * Returns an object containing the Children Tagging Attribute only.
 * This attribute is a serialized list of ChildrenTaggingQuery objects and will be parsed and executed by our Observer
 * as soon as the elements gets rendered.
 *
 * Examples
 *
 *    tagChildren([
 *      {
 *        queryAll: 'button[aria-label="Previous"]',
 *        tagAs: tagPressable({ id: 'prev', text: 'Previous' })
 *      },
 *      {
 *        queryAll: 'button[aria-label="Next"]',
 *        tagAs: tagPressable({ id: 'next', text: 'Next' })
 *      }
 *    ])
 */
declare const tagChildren: (parameters: ChildrenTaggingQueries, onError?: TrackerErrorHandlerCallback) => TagChildrenReturnValue;

/**
 * tagContent is a shorthand for tagLocation. It eases the tagging of ContentContext bound Elements.
 */
declare const tagContent: (parameters: LocationTaggerParameters) => TagLocationReturnValue;

/**
 * tagExpandable is a shorthand for tagLocation. It eases the tagging of ExpandableContext bound Elements
 */
declare const tagExpandable: (parameters: LocationTaggerParameters) => TagLocationReturnValue;

/**
 * tagInput is a shorthand for tagLocation. It eases the tagging of InputContext bound Elements
 */
declare const tagInput: (parameters: LocationTaggerParameters) => TagLocationReturnValue;

/**
 * tagLink is a shorthand for tagLocation. It eases the tagging of LinkContext bound Elements
 */
declare const tagLink: (parameters: TagLinkParameters) => TagLocationReturnValue;

/**
 * Used to decorate a Taggable Element with our Tagging Attributes.
 *
 * Returns an object containing the Tagging Attributes. It's properties are supposed to be spread on the target HTML
 * Element. This allows us to identify elements uniquely in a Document and to reconstruct their Location.
 *
 * For a higher level api see the tagLocationHelpers module.
 *
 * Examples
 *
 *    tagLocation({ instance: makeElementContext({ id: 'section-id' }) })
 *    tagLocation({ instance: makeElementContext({ id: 'section-id' }), { trackClicks: true } })
 *
 */
declare const tagLocation: (parameters: TagLocationParameters) => TagLocationReturnValue;

/**
 * tagMediaPlayer is a shorthand for tagLocation. It eases the tagging of MediaPlayerContext bound Elements
 */
declare const tagMediaPlayer: (parameters: LocationTaggerParameters) => TagLocationReturnValue;

/**
 * tagNavigation is a shorthand for tagLocation. It eases the tagging of NavigationContext bound Elements
 */
declare const tagNavigation: (parameters: LocationTaggerParameters) => TagLocationReturnValue;

/**
 * tagOverlay is a shorthand for tagLocation. It eases the tagging of OverlayContext bound Elements
 */
declare const tagOverlay: (parameters: LocationTaggerParameters) => TagLocationReturnValue;

/**
 * tagPressable is a shorthand for tagLocation. It eases the tagging of ButtonContext bound Elements
 */
declare const tagPressable: (parameters: LocationTaggerParameters) => TagLocationReturnValue;

/**
 * tagRootLocation is a shorthand for tagLocation. It eases the tagging of RootLocationContext bound Elements.
 */
declare const tagRootLocation: (parameters: LocationTaggerParameters) => TagLocationReturnValue;

/**
 * Hold an instance of the Mutation Observer and some state for some global events, like URLs and Application Loaded.
 */
declare const AutoTrackingState: {
    observerInstance: MutationObserver | null;
    applicationLoaded: boolean;
    previousURL: string | undefined;
};

/**
 * A factory to make the event handler to attach to new TaggedElements with the `trackBlurs` attributes set
 */
declare const makeBlurEventHandler: (element: TaggedElement, tracker?: BrowserTracker, trackBlursOptions?: TrackBlursOptions, locationId?: string) => (event: Event) => void;

/**
 * A factory to make the event handler to attach to new TaggedElements with the `trackClicks` attributes set
 */
declare const makeClickEventHandler: (element: TaggedElement, tracker: BrowserTracker, trackClicksOptions?: TrackClicksOptions) => (event: Event) => Promise<void>;

/**
 * A factory to generate our mutation observer callback. It will observe:
 *
 * New DOM nodes added.
 * We use a Mutation Observer to monitor the DOM for subtrees being added.
 * When that happens we traverse the new Nodes and scout for Elements that have been enriched with our Tagging
 * Attributes. For those Elements we attach Event listeners which will automatically handle their tracking.
 * New Elements are also added to TrackerElementLocations and their Location Stack is validated for uniqueness.
 *
 * Existing nodes changing.
 * The same Observer is also configured to monitor changes in our visibility and element id attributes.
 * When we detect a change in the visibility of a tagged element we trigger the corresponding visibility events.
 * Element id changes are used to keep the TrackerElementLocations in sync with the DOM.
 *
 * Existing nodes being removed.
 * We also monitor nodes that are removed. If those nodes are Tagged Elements of which we were tracking visibility
 * we will trigger visibility: hidden events for them.
 * We also clean them up from TrackerElementLocations.
 */
declare const makeMutationCallback: () => MutationCallback;

/**
 * Check if Element is a ChildrenTaggingElement. If so:
 * - Run its children tracking queries
 * - Decorate matching Elements into TaggedElements
 * - Return a list of the decorated Elements
 */
declare const processTagChildrenElement: (element: Element) => TaggedElement[];

/**
 * Attaches event handlers to the given Element and triggers visibility Events for it if the Tagging Attributes allow.
 * - All Elements will be checked for visibility tracking and appropriate events will be triggered for them.
 * - Elements with the Objectiv Track Click attribute are bound to EventListener for Buttons, Links.
 * - Elements with the Objectiv Track Blur attribute are bound to EventListener for Inputs.
 * - All processed Elements are decorated with the `tracked` Tagging Attribute so we won't process them again.
 */
declare const trackNewElement: (element: Element, tracker: BrowserTracker) => void;

/**
 * Given a Mutation Observer node containing newly added nodes it will track visibility and attach events to them:
 */
declare const trackNewElements: (element: Element, tracker: BrowserTracker) => void;

/**
 * Given a removed GuardableElement node it will:
 *
 *   1. Determine whether to track a visibility:hidden event for it.
 *      Hidden Events are triggered only for automatically tracked Elements.
 *
 *   2. Remove the Element from the TrackerElementLocations state.
 *      This is both a clean-up and a way to allow it to be re-rendered as-is, as it happens with some UI libraries.
 */
declare const trackRemovedElement: (element: GuardableElement, tracker: BrowserTracker) => void;

/**
 * Invokes `trackRemovedElement` for given node and all of its children if they have the `elementId` Tagging Attribute.
 */
declare const trackRemovedElements: (element: Element, tracker: BrowserTracker) => void;

/**
 * Checks whether to trigger a visibility: hidden event for the given TaggedElement.
 * Hidden Events are triggered only for Elements that have their visibility manually set to not visible.
 */
declare const trackVisibilityHiddenEvent: (element: TaggedElement, tracker: BrowserTracker) => void;

/**
 * Checks whether to trigger a visibility: visible event for the given TaggedElement.
 * Visible Events are triggered only for Elements that have their visibility auto-tracked or manually set to visible.
 */
declare const trackVisibilityVisibleEvent: (element: TaggedElement, tracker: BrowserTracker) => void;

/**
 * Retrieves a specific Tracker's instance from the TrackerRepository or creates one if it doesn't exist yet.
 * Logs an error to console if the given Tracker ID exists but its configuration doesn't match the given one.
 */
declare const getOrMakeTracker: (trackerConfig: BrowserTrackerConfig) => BrowserTracker;

/**
 * Retrieves a specific instance of the tracker from the TrackerRepository.
 */
declare const getTracker: (trackerId?: string) => BrowserTracker;

/**
 * Retrieves the TrackerRepository
 */
declare const getTrackerRepository: () => TrackerRepositoryInterface<BrowserTracker>;

/**
 * Allows to easily create and configure a new BrowserTracker instance and also starts auto tracking
 */
declare const makeTracker: (trackerConfig: BrowserTrackerConfig) => BrowserTracker;

/**
 * Helper method to easily set a different default Tracker in the TrackerRepository.
 */
declare const setDefaultTracker: (parameters: string | {
    trackerId: string;
    waitForQueue?: false | WaitForQueueOptions;
    flushQueue?: FlushQueueOptions;
}) => Promise<void>;

/**
 * Initializes our automatic tracking, based on Mutation Observer.
 * Also tracks application Loaded.
 * Safe to call multiple times: it will auto-track only once.
 */
declare const startAutoTracking: (options?: Pick<BrowserTrackerConfig, 'trackApplicationLoadedEvent'>) => void;

/**
 * Stops autoTracking
 */
declare const stopAutoTracking: () => void;

export { AnyLocationContext, AnyPressableContext, AnyShowableContext, AutoTrackingState, BrowserTracker, BrowserTrackerConfig, ChildrenTaggingQueries, ChildrenTaggingQuery, FlushQueueOptions, GuardableElement, InteractiveEventTrackerParameters, LocationTaggerParameters, NonInteractiveEventTrackerParameters, ParentTaggedElement, TagChildrenAttributes, TagChildrenElement, TagChildrenReturnValue, TagLinkParameters, TagLocationAttributes, TagLocationOptions, TagLocationParameters, TagLocationReturnValue, TaggableElement, TaggedElement, TaggingAttribute, TrackBlursAttribute, TrackBlursOptions, TrackClicksAttribute, TrackClicksOptions, TrackFailureEventParameters, TrackSuccessEventParameters, TrackVisibilityAttribute, TrackVisibilityOptions, TrackedElement, TrackerErrorHandlerCallback, ValidChildrenTaggingQuery, ValidateAttribute, WaitForQueueOptions, WaitUntilTrackedOptions, findParentTaggedElements, getElementLocationStack, getLocationHref, getOrMakeTracker, getTracker, getTrackerRepository, isFlushQueueOptions, isLocationContext, isLocationTaggerParameters, isParentTaggedElement, isPressableContext, isShowableContext, isTagChildrenElement, isTagLocationAttributes, isTagLocationOptions, isTagLocationParameters, isTaggableElement, isTaggedElement, isTrackBlursAttribute, isTrackClicksAttribute, isTrackVisibilityAttribute, isValidChildrenTaggingQuery, isValidateAttribute, isWaitUntilTrackedOptions, makeBlurEventHandler, makeBrowserTrackerDefaultPluginsList, makeBrowserTrackerDefaultQueue, makeBrowserTrackerDefaultTransport, makeClickEventHandler, makeMutationCallback, makeTracker, parseJson, parseLocationContext, parseTagChildren, parseTrackBlurs, parseTrackClicks, parseTrackVisibility, parseValidate, processTagChildrenElement, runIfValueIsNotUndefined, setDefaultTracker, startAutoTracking, stopAutoTracking, stringifyJson, stringifyLocationContext, stringifyTagChildren, stringifyTrackBlurs, stringifyTrackClicks, stringifyTrackVisibility, stringifyValidate, tagChild, tagChildren, tagContent, tagExpandable, tagInput, tagLink, tagLocation, tagMediaPlayer, tagNavigation, tagOverlay, tagPressable, tagRootLocation, trackApplicationLoadedEvent, trackEvent, trackFailureEvent, trackHiddenEvent, trackInputChangeEvent, trackInteractiveEvent, trackMediaEvent, trackMediaLoadEvent, trackMediaPauseEvent, trackMediaStartEvent, trackMediaStopEvent, trackNewElement, trackNewElements, trackNonInteractiveEvent, trackPressEvent, trackRemovedElement, trackRemovedElements, trackSuccessEvent, trackVisibility, trackVisibilityHiddenEvent, trackVisibilityVisibleEvent, trackVisibleEvent, trackerErrorHandler };