unified-analytics/dist/index.d.ts

Unified analytics library for web applications

import { AnalyticsEvent, EventAttributes, AnalyticsSubject, AnalyticsObserver, AnalyticsMiddleware, InitOptions } from "./types";
export * from "./types";
/**
 * Main Analytics class that implements the Observer pattern.
 * Acts as the central hub for tracking events across multiple analytics providers.
 */
declare class Analytics implements AnalyticsSubject {
    private static COMMON_ATTR_KEY;
    private static INHOUSE_ATTR_KEY;
    private _inHouseAttributes;
    private _commonAttributes;
    private _initialized;
    private _observers;
    private _middleware;
    private _debug;
    constructor();
    /**
     * Initialize the analytics system with observers and common attributes.
     * Should be called once early in your application lifecycle.
     *
     * @param observers - Array of analytics providers that will receive events
     * @param options - Configuration options for the analytics system
     */
    initialize(observers?: AnalyticsObserver[], options?: InitOptions): this;
    /**
     * Register a new analytics provider to receive events.
     *
     * @param observer - The analytics provider to add
     */
    attach(observer: AnalyticsObserver): this;
    /**
     * Remove an analytics provider from receiving events.
     *
     * @param observer - The analytics provider to remove
     */
    detach(observer: AnalyticsObserver): this;
    private _notify;
    private _applyMiddleware;
    private _applySingleObserverMiddleware;
    private _notifyObservers;
    private _notifySingleObserver;
    /**
     * Track an analytics event and notify registered providers.
     * Common attributes will be automatically merged with event-specific attributes.
     *
     * @param eventName - Name of the event to track
     * @param attributes - Event-specific attributes to include
     * @param observers - Optional specific observer or array of observers to send the event to instead of all observers
     */
    sendEvent(eventName: AnalyticsEvent["name"], attributes?: EventAttributes, observers?: AnalyticsObserver | AnalyticsObserver[]): this;
    /**
     * Update the common attributes that are included with every tracked event.
     * These will be merged with event-specific attributes.
     *
     * @param attributes - Common attributes to set or update
     */
    setCommonAttributes(attributes: EventAttributes): this;
    /**
     * Get the current common attributes object.
     * @returns The common attributes
     */
    getCommonAttributes(): EventAttributes;
    /**
     * Update the in-house attributes that are included with every tracked event for internal use.
     * These will be merged with existing in-house attributes.
     * @param attributes - In-house attributes to set or update
     * @returns The analytics instance for method chaining
     */
    setInHouseAttributes(attributes: EventAttributes): this;
    /**
     * Get the current in-house attributes object.
     * @returns The in-house attributes
     */
    getInHouseAttributes(): EventAttributes;
    /**
     * Reset all analytics attributes, including both common and in-house attributes.
     *
     * @returns The analytics instance for method chaining
     */
    resetAttributes(): this;
    /**
     * Enable or disable debug mode at runtime
     * @param value - True to enable debug mode, false to disable
     */
    setDebug(value: boolean): this;
    /**
     * Check if analytics has been initialized.
     *
     * @returns True if analytics has been initialized, false otherwise
     */
    isInitialized(): boolean;
    /**
     * Creates a clone of an existing analytics provider.
     * This is useful when you need multiple instances of the same provider
     * with different configurations.
     *
     * @param observer - The original observer to clone
     * @param options - Options for cloning the provider
     * @param options.autoAttach - When true, automatically attaches the cloned provider to the analytics service
     * @returns The cloned observer instance
     *
     * @example
     * // Clone Google Analytics and automatically attach it to analytics
     * const newGAService = analytics.cloneProvider(firebaseGoogleAnalyticsService, { autoAttach: true });
     * newGAService.init({ ...different config... });
     *
     * // Or clone without auto-attaching (original behavior)
     * const anotherService = analytics.cloneProvider(someProvider);
     * anotherService.init({ ...different config... });
     * analytics.attach(anotherService);
     */
    cloneProvider<T extends AnalyticsObserver>(observer: T, options?: {
        autoAttach?: boolean;
    }): T;
    /**
     * Register a middleware function that will process events before they are sent to observers.
     * Middleware functions are executed in the order they are registered.
     *
     * @param middleware - Function that receives the event and a next callback
     * @returns The analytics instance for method chaining
     */
    use(middleware: AnalyticsMiddleware): this;
}
declare const analytics: Analytics;
export default analytics;