unified-analytics/dist/types.d.ts

Unified analytics library for web applications

export type EventAttributes = Record<string, unknown>;
/**
 * Configuration options for initializing analytics
 */
export interface InitOptions {
    /**
     * Enable debug mode to log analytics events to the console
     * @default false
     */
    debug?: boolean;
}
export interface AnalyticsEvent {
    name: string;
    attributes?: EventAttributes;
}
export interface AnalyticsObserver {
    getInstance(): unknown;
    /**
     * Called when an analytics event is tracked.
     * @param event - The analytics event object
     * @param debug - If true, enables debug logging for this event
     * @param inHouseAttributes - In-house attributes for internal use
     */
    onEvent(event: AnalyticsEvent, debug?: boolean, inHouseAttributes?: EventAttributes): void;
    /**
     * Create a new instance of the observer with the same implementation
     * but separate state.
     * @returns A new instance of the observer
     */
    clone(): AnalyticsObserver;
}
/**
 * Middleware function type for processing events before they're sent to observers
 */
export type AnalyticsMiddleware = (event: AnalyticsEvent, next: (event: AnalyticsEvent) => void) => void;
export interface AnalyticsSubject {
    /**
     * Register a new analytics provider to receive events.
     * @param observer - The analytics provider to add
     * @returns The analytics instance for method chaining
     */
    attach(observer: AnalyticsObserver): this;
    /**
     * Remove an analytics provider from receiving events.
     * @param observer - The analytics provider to remove
     * @returns The analytics instance for method chaining
     */
    detach(observer: AnalyticsObserver): this;
    /**
     * Track an analytics event and notify registered providers.
     * @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
     * @returns The analytics instance for method chaining
     */
    sendEvent(eventName: AnalyticsEvent["name"], attributes?: EventAttributes, observers?: AnalyticsObserver | AnalyticsObserver[]): this;
    /**
     * Register a middleware function to process events before they're sent to observers.
     * @param middleware - The middleware function to add
     * @returns The analytics instance for method chaining
     */
    use(middleware: AnalyticsMiddleware): this;
    /**
     * Update the common attributes that are included with every tracked event.
     * @param attributes - Common attributes to set or update
     * @returns The analytics instance for method chaining
     */
    setCommonAttributes(attributes: EventAttributes): this;
    /**
     * Update the in-house attributes that are included with every tracked event for internal use.
     * @param attributes - In-house attributes to set or update
     * @returns The analytics instance for method chaining
     */
    setInHouseAttributes(attributes: EventAttributes): this;
    /**
     * Reset all analytics attributes, including both common and in-house attributes.
     * @returns The analytics instance for method chaining
     */
    resetAttributes(): this;
    /**
     * Check if analytics has been initialized.
     * @returns True if analytics has been initialized, false otherwise
     */
    isInitialized(): boolean;
}