@armco/analytics 0.2.10 → 0.2.12

package/core/analytics.d.ts

@@ -0,0 +1,48 @@
+import type { AnalyticsConfig, IAnalytics, Plugin, EventData, PageViewEvent, ClickEvent, ErrorEvent, User, StorageManager, Transport } from "./types";
+export declare class AnalyticsBuilder {
+    private config;
+    private plugins;
+    private storage?;
+    private transport?;
+    withApiKey(apiKey: string): this;
+    withEndpoint(endpoint: string): this;
+    withHostProjectName(name: string): this;
+    withLogLevel(level: AnalyticsConfig["logLevel"]): this;
+    withSubmissionStrategy(strategy: AnalyticsConfig["submissionStrategy"]): this;
+    withSamplingRate(rate: number): this;
+    withPlugin(plugin: Plugin): this;
+    withStorage(storage: StorageManager): this;
+    withTransport(transport: Transport): this;
+    withConfig(config: Partial<AnalyticsConfig>): this;
+    build(): Analytics;
+}
+export declare class Analytics implements IAnalytics {
+    private config;
+    private storage;
+    private transport;
+    private beaconTransport;
+    private plugins;
+    private logger;
+    private initialized;
+    private enabled;
+    private eventQueue;
+    private flushInterval?;
+    private sessionPlugin?;
+    private userPlugin?;
+    constructor(config: AnalyticsConfig, storage: StorageManager, transport: Transport, plugins: Plugin[]);
+    private addCorePlugins;
+    init(): void;
+    track<T extends EventData>(eventType: string, data?: T): Promise<void>;
+    trackPageView(data: PageViewEvent): Promise<void>;
+    trackClick(data: ClickEvent): Promise<void>;
+    trackError(data: ErrorEvent): Promise<void>;
+    identify(user: User): Promise<void>;
+    getSessionId(): string | null;
+    getUserId(): string | null;
+    private queueEvent;
+    private sendEvent;
+    flush(): Promise<void>;
+    private handleBeforeUnload;
+    private getEndpoint;
+    destroy(): void;
+}

package/core/analytics.js

@@ -0,0 +1,311 @@
+import { v4 as uuidv4 } from "uuid";
+import { ConfigurationError, InitializationError } from "./errors";
+import { HybridStorage } from "../storage/hybrid-storage";
+import { MemoryStorage } from "../storage/memory-storage";
+import { FetchTransport } from "../transport/fetch-transport";
+import { BeaconTransport } from "../transport/beacon-transport";
+import { SessionPlugin } from "../plugins/enrichment/session";
+import { UserPlugin } from "../plugins/enrichment/user";
+import { validateConfig, sanitizeEventData } from "../utils/validation";
+import { createLogger } from "../utils/logging";
+import { getEnvironmentType, isDoNotTrackEnabled, getTimestamp, deepMerge, } from "../utils/helpers";
+export class AnalyticsBuilder {
+    constructor() {
+        this.config = {};
+        this.plugins = [];
+    }
+    withApiKey(apiKey) {
+        this.config.apiKey = apiKey;
+        return this;
+    }
+    withEndpoint(endpoint) {
+        this.config.endpoint = endpoint;
+        return this;
+    }
+    withHostProjectName(name) {
+        this.config.hostProjectName = name;
+        return this;
+    }
+    withLogLevel(level) {
+        this.config.logLevel = level;
+        return this;
+    }
+    withSubmissionStrategy(strategy) {
+        this.config.submissionStrategy = strategy;
+        return this;
+    }
+    withSamplingRate(rate) {
+        if (rate < 0 || rate > 1) {
+            throw new ConfigurationError("Sampling rate must be between 0 and 1");
+        }
+        this.config.samplingRate = rate;
+        return this;
+    }
+    withPlugin(plugin) {
+        this.plugins.push(plugin);
+        return this;
+    }
+    withStorage(storage) {
+        this.storage = storage;
+        return this;
+    }
+    withTransport(transport) {
+        this.transport = transport;
+        return this;
+    }
+    withConfig(config) {
+        this.config = deepMerge(this.config, config);
+        return this;
+    }
+    build() {
+        const validatedConfig = validateConfig(this.config);
+        const finalConfig = {
+            submissionStrategy: "ONEVENT",
+            logLevel: "info",
+            samplingRate: 1,
+            enableLocation: false,
+            enableAutoTrack: true,
+            respectDoNotTrack: true,
+            batchSize: 100,
+            flushInterval: 15000,
+            maxRetries: 3,
+            retryDelay: 1000,
+            showConsentPopup: false,
+            maxQueueSize: 1000,
+            ...validatedConfig,
+        };
+        if (!finalConfig.apiKey && !finalConfig.endpoint) {
+            throw new ConfigurationError("Either apiKey or endpoint must be provided");
+        }
+        const storage = this.storage ||
+            (getEnvironmentType() === "node"
+                ? new MemoryStorage()
+                : new HybridStorage());
+        const transport = this.transport || new FetchTransport({
+            apiKey: finalConfig.apiKey,
+            maxRetries: finalConfig.maxRetries,
+            retryDelay: finalConfig.retryDelay,
+        });
+        return new Analytics(finalConfig, storage, transport, this.plugins);
+    }
+}
+export class Analytics {
+    constructor(config, storage, transport, plugins) {
+        this.plugins = [];
+        this.initialized = false;
+        this.enabled = true;
+        this.eventQueue = [];
+        this.config = config;
+        this.storage = storage;
+        this.transport = transport;
+        this.beaconTransport =
+            getEnvironmentType() === "browser"
+                ? new BeaconTransport({ apiKey: config.apiKey })
+                : null;
+        this.plugins = plugins;
+        this.logger = createLogger(config.logLevel || "info");
+        this.addCorePlugins();
+    }
+    addCorePlugins() {
+        const hasSessionPlugin = this.plugins.some((p) => p.name === "SessionPlugin");
+        if (!hasSessionPlugin) {
+            this.sessionPlugin = new SessionPlugin();
+            this.plugins.push(this.sessionPlugin);
+        }
+        const hasUserPlugin = this.plugins.some((p) => p.name === "UserPlugin");
+        if (!hasUserPlugin) {
+            this.userPlugin = new UserPlugin();
+            this.plugins.push(this.userPlugin);
+        }
+    }
+    init() {
+        if (this.initialized) {
+            throw new InitializationError("Analytics already initialized");
+        }
+        if (this.config.respectDoNotTrack && isDoNotTrackEnabled()) {
+            this.logger.warn("Do Not Track is enabled, analytics will be disabled");
+            this.enabled = false;
+            return;
+        }
+        const context = {
+            config: this.config,
+            storage: this.storage,
+            transport: this.transport,
+            track: this.track.bind(this),
+            getSessionId: this.getSessionId.bind(this),
+            getUserId: this.getUserId.bind(this),
+        };
+        for (const plugin of this.plugins) {
+            try {
+                this.logger.debug(`Initializing plugin: ${plugin.name}`);
+                plugin.init(context);
+            }
+            catch (error) {
+                this.logger.error(`Failed to initialize plugin ${plugin.name}:`, error);
+            }
+        }
+        if (this.config.submissionStrategy === "DEFER") {
+            this.flushInterval = setInterval(() => {
+                this.flush();
+            }, this.config.flushInterval);
+        }
+        if (getEnvironmentType() === "browser") {
+            window.addEventListener("beforeunload", () => {
+                this.handleBeforeUnload();
+            });
+            document.addEventListener("visibilitychange", () => {
+                if (document.visibilityState === "hidden") {
+                    this.handleBeforeUnload();
+                }
+            });
+        }
+        this.initialized = true;
+        this.logger.info("Analytics initialized");
+        this.track("ANALYTICS_INITIALIZED");
+    }
+    async track(eventType, data) {
+        if (!this.initialized) {
+            throw new InitializationError("Analytics not initialized. Call init() first");
+        }
+        if (!this.enabled) {
+            this.logger.debug("Analytics disabled, event not tracked");
+            return;
+        }
+        if (Math.random() > (this.config.samplingRate ?? 1)) {
+            this.logger.debug("Event sampled out");
+            return;
+        }
+        const event = {
+            eventType,
+            timestamp: getTimestamp(),
+            eventId: uuidv4(),
+            data: sanitizeEventData(data || {}),
+        };
+        for (const plugin of this.plugins) {
+            if (plugin.processEvent) {
+                try {
+                    await plugin.processEvent(event);
+                }
+                catch (error) {
+                    this.logger.error(`Plugin ${plugin.name} failed to process event:`, error);
+                }
+            }
+        }
+        if (this.config.submissionStrategy === "DEFER") {
+            this.queueEvent(event);
+        }
+        else {
+            await this.sendEvent(event);
+        }
+    }
+    async trackPageView(data) {
+        return this.track("PAGE_VIEW", data);
+    }
+    async trackClick(data) {
+        return this.track("CLICK", data);
+    }
+    async trackError(data) {
+        return this.track("ERROR", data);
+    }
+    async identify(user) {
+        if (!this.initialized) {
+            throw new InitializationError("Analytics not initialized. Call init() first");
+        }
+        if (this.userPlugin) {
+            await this.userPlugin.identify(user);
+        }
+        else {
+            this.logger.error("User plugin not available");
+        }
+    }
+    getSessionId() {
+        if (this.sessionPlugin) {
+            return this.sessionPlugin.getSessionId();
+        }
+        return null;
+    }
+    getUserId() {
+        if (this.userPlugin) {
+            return this.userPlugin.getUserId();
+        }
+        return null;
+    }
+    queueEvent(event) {
+        this.eventQueue.push({
+            event,
+            retries: 0,
+            timestamp: new Date(),
+        });
+        const maxQueueSize = this.config.maxQueueSize ?? 1000;
+        if (this.eventQueue.length > maxQueueSize) {
+            this.logger.warn(`Queue size exceeded ${maxQueueSize}, dropping oldest events`);
+            this.eventQueue = this.eventQueue.slice(-maxQueueSize);
+        }
+        if (this.eventQueue.length >= (this.config.batchSize ?? 100)) {
+            this.flush();
+        }
+    }
+    async sendEvent(event) {
+        const endpoint = this.getEndpoint();
+        try {
+            await this.transport.send(endpoint, event);
+            this.logger.debug("Event sent successfully:", event.eventType);
+        }
+        catch (error) {
+            this.logger.error("Failed to send event:", error);
+        }
+    }
+    async flush() {
+        if (this.eventQueue.length === 0) {
+            return;
+        }
+        const events = this.eventQueue.map((qe) => qe.event);
+        const endpoint = this.getEndpoint();
+        try {
+            await this.transport.sendBatch(endpoint, events);
+            this.logger.debug(`Flushed ${events.length} events`);
+            this.eventQueue = [];
+        }
+        catch (error) {
+            this.logger.error("Failed to flush events:", error);
+        }
+    }
+    handleBeforeUnload() {
+        if (!this.beaconTransport || this.eventQueue.length === 0) {
+            return;
+        }
+        const events = this.eventQueue.map((qe) => qe.event);
+        const endpoint = this.getEndpoint();
+        try {
+            this.beaconTransport.sendBatch(endpoint, events);
+            this.logger.debug("Events sent via beacon on unload");
+        }
+        catch (error) {
+            this.logger.error("Failed to send events on unload:", error);
+        }
+    }
+    getEndpoint() {
+        if (this.config.endpoint) {
+            return this.config.endpoint;
+        }
+        return "https://telemetry.armco.dev/events/add";
+    }
+    destroy() {
+        this.flush();
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+        }
+        for (const plugin of this.plugins) {
+            if (plugin.destroy) {
+                try {
+                    plugin.destroy();
+                }
+                catch (error) {
+                    this.logger.error(`Failed to destroy plugin ${plugin.name}:`, error);
+                }
+            }
+        }
+        this.initialized = false;
+        this.logger.info("Analytics destroyed");
+    }
+}

package/core/errors.d.ts

@@ -0,0 +1,26 @@
+export declare class AnalyticsError extends Error {
+    constructor(message: string);
+}
+export declare class ConfigurationError extends AnalyticsError {
+    constructor(message: string);
+}
+export declare class ValidationError extends AnalyticsError {
+    readonly field?: string;
+    readonly value?: unknown;
+    constructor(message: string, field?: string, value?: unknown);
+}
+export declare class NetworkError extends AnalyticsError {
+    readonly statusCode?: number;
+    readonly endpoint?: string;
+    constructor(message: string, statusCode?: number, endpoint?: string);
+}
+export declare class StorageError extends AnalyticsError {
+    constructor(message: string);
+}
+export declare class PluginError extends AnalyticsError {
+    readonly pluginName?: string;
+    constructor(message: string, pluginName?: string);
+}
+export declare class InitializationError extends AnalyticsError {
+    constructor(message: string);
+}

package/core/errors.js

@@ -0,0 +1,54 @@
+export class AnalyticsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AnalyticsError";
+        Object.setPrototypeOf(this, AnalyticsError.prototype);
+    }
+}
+export class ConfigurationError extends AnalyticsError {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigurationError";
+        Object.setPrototypeOf(this, ConfigurationError.prototype);
+    }
+}
+export class ValidationError extends AnalyticsError {
+    constructor(message, field, value) {
+        super(message);
+        this.name = "ValidationError";
+        this.field = field;
+        this.value = value;
+        Object.setPrototypeOf(this, ValidationError.prototype);
+    }
+}
+export class NetworkError extends AnalyticsError {
+    constructor(message, statusCode, endpoint) {
+        super(message);
+        this.name = "NetworkError";
+        this.statusCode = statusCode;
+        this.endpoint = endpoint;
+        Object.setPrototypeOf(this, NetworkError.prototype);
+    }
+}
+export class StorageError extends AnalyticsError {
+    constructor(message) {
+        super(message);
+        this.name = "StorageError";
+        Object.setPrototypeOf(this, StorageError.prototype);
+    }
+}
+export class PluginError extends AnalyticsError {
+    constructor(message, pluginName) {
+        super(message);
+        this.name = "PluginError";
+        this.pluginName = pluginName;
+        Object.setPrototypeOf(this, PluginError.prototype);
+    }
+}
+export class InitializationError extends AnalyticsError {
+    constructor(message) {
+        super(message);
+        this.name = "InitializationError";
+        Object.setPrototypeOf(this, InitializationError.prototype);
+    }
+}

package/core/types.d.ts

@@ -0,0 +1,133 @@
+export type Environment = "browser" | "node" | "unknown";
+export type SubmissionStrategy = "ONEVENT" | "DEFER";
+export type LogLevel = "debug" | "info" | "warn" | "error" | "none";
+export interface EventData {
+    [key: string]: unknown;
+}
+export interface TrackingEvent<T extends EventData = EventData> {
+    eventType: string;
+    timestamp: Date;
+    eventId: string;
+    sessionId?: string;
+    userId?: string;
+    data: T;
+}
+export interface PageViewEvent extends EventData {
+    pageName: string;
+    url: string;
+    referrer?: string;
+    title?: string;
+}
+export interface ClickEvent extends EventData {
+    elementId?: string;
+    elementType: string;
+    elementText?: string;
+    elementClasses?: string[];
+    elementPath?: string;
+    href?: string;
+    value?: string;
+}
+export interface FormEvent extends EventData {
+    formId?: string;
+    formName?: string;
+    formAction?: string;
+    formMethod?: string;
+}
+export interface ErrorEvent extends EventData {
+    errorMessage: string;
+    errorStack?: string;
+    errorType?: string;
+}
+export interface User {
+    email: string;
+    id?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+export interface LocationData {
+    region?: string;
+    timezone?: string;
+    latitude?: number;
+    longitude?: number;
+    city?: string;
+    country?: string;
+}
+export interface AnalyticsConfig {
+    apiKey?: string;
+    endpoint?: string;
+    updateEndpoint?: string;
+    hostProjectName?: string;
+    trackEvents?: string[];
+    submissionStrategy?: SubmissionStrategy;
+    showConsentPopup?: boolean;
+    logLevel?: LogLevel;
+    samplingRate?: number;
+    enableLocation?: boolean;
+    enableAutoTrack?: boolean;
+    respectDoNotTrack?: boolean;
+    batchSize?: number;
+    flushInterval?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+    maxQueueSize?: number;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export interface Plugin {
+    name: string;
+    version?: string;
+    init(context: PluginContext): void | Promise<void>;
+    processEvent?(event: TrackingEvent): void | Promise<void>;
+    destroy?(): void | Promise<void>;
+}
+export interface PluginContext {
+    config: AnalyticsConfig;
+    storage: StorageManager;
+    transport: Transport;
+    track(eventType: string, data?: EventData): void;
+    getSessionId(): string | null;
+    getUserId(): string | null;
+}
+export interface StorageManager {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string, options?: StorageOptions): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+export interface StorageOptions {
+    expires?: Date;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+}
+export interface Transport {
+    send(endpoint: string, event: TrackingEvent): Promise<TransportResponse>;
+    sendBatch(endpoint: string, events: TrackingEvent[]): Promise<TransportResponse>;
+    update?(endpoint: string, payload: {
+        email: string;
+        anonymousId: string;
+    }): Promise<TransportResponse>;
+}
+export interface TransportResponse {
+    success: boolean;
+    statusCode?: number;
+    error?: string;
+}
+export interface QueuedEvent {
+    event: TrackingEvent;
+    retries: number;
+    timestamp: Date;
+}
+export interface IAnalytics {
+    init(): void;
+    track<T extends EventData>(eventType: string, data?: T): Promise<void>;
+    trackPageView(data: PageViewEvent): Promise<void>;
+    trackClick(data: ClickEvent): Promise<void>;
+    trackError(data: ErrorEvent): Promise<void>;
+    identify(user: User): Promise<void>;
+    getSessionId(): string | null;
+    getUserId(): string | null;
+    flush(): Promise<void>;
+    destroy(): void;
+}

package/index.d.ts

@@ -1,2 +1,24 @@
-import { init, identify, getEnvironment, getEnvironmentType, trackEvent, trackPageView, trackError, enableTracking, generateAnonymousId, sendHostProjectName, getSessionId, startSession } from "./analytics";
-export { init, identify, getEnvironment, getEnvironmentType, trackEvent, trackPageView, trackError, enableTracking, generateAnonymousId, sendHostProjectName, getSessionId, startSession, };
+export { Analytics, AnalyticsBuilder } from "./core/analytics";
+export type { AnalyticsConfig, IAnalytics, EventData, TrackingEvent, PageViewEvent, ClickEvent, FormEvent, ErrorEvent, User, Plugin, PluginContext, StorageManager, StorageOptions, Transport, TransportResponse, LogLevel, SubmissionStrategy, Environment, } from "./core/types";
+export { AnalyticsError, ConfigurationError, ValidationError, NetworkError, StorageError, PluginError, InitializationError, } from "./core/errors";
+export { CookieStorage } from "./storage/cookie-storage";
+export { LocalStorage } from "./storage/local-storage";
+export { HybridStorage } from "./storage/hybrid-storage";
+export { MemoryStorage } from "./storage/memory-storage";
+export { FetchTransport } from "./transport/fetch-transport";
+export { BeaconTransport } from "./transport/beacon-transport";
+export { SessionPlugin } from "./plugins/enrichment/session";
+export { UserPlugin } from "./plugins/enrichment/user";
+export { ClickTrackingPlugin } from "./plugins/auto-track/click";
+export { PageTrackingPlugin } from "./plugins/auto-track/page";
+export { FormTrackingPlugin } from "./plugins/auto-track/form";
+export { ErrorTrackingPlugin } from "./plugins/auto-track/error";
+export { HTTPRequestTrackingPlugin } from "./plugins/node/http-request-tracking";
+export type { HTTPRequestEvent, HTTPRequestMetadata } from "./plugins/node/http-request-tracking";
+export { validateConfig, validateUser, validatePageView, validateClickEvent, validateFormEvent, validateErrorEvent, sanitizeEventData, } from "./utils/validation";
+export { Logger, getLogger, createLogger } from "./utils/logging";
+export { generateId, getEnvironmentType, getEnvironment, isDoNotTrackEnabled, isBrowser, areCookiesAvailable, isLocalStorageAvailable, debounce, throttle, deepClone, deepMerge, } from "./utils/helpers";
+export { loadConfigFromFile, loadConfig } from "./utils/config-loader";
+import { AnalyticsBuilder as Builder } from "./core/analytics";
+export declare function createAnalytics(): Builder;
+export default Builder;

package/index.js

@@ -1,13 +1,24 @@
-import { init, identify, getEnvironment, getEnvironmentType, trackEvent, trackPageView, trackError, enableTracking, generateAnonymousId, sendHostProjectName, getSessionId, startSession, } from "./analytics";
-document.addEventListener("DOMContentLoaded", function (event) {
-    const environment = getEnvironment();
-    console.info("[ANALYTICS] Idenfitied environment: ", environment);
-    if (!environment || environment === "development") {
-        console.info("[ANALYTICS] Attempting to auto-load analytics configurations from environment...");
-        init();
-    }
-    else {
-        console.info("[ANALYTICS] Identified non-dev environment, analytics auto load wouldn't be attempted.");
-    }
-});
-export { init, identify, getEnvironment, getEnvironmentType, trackEvent, trackPageView, trackError, enableTracking, generateAnonymousId, sendHostProjectName, getSessionId, startSession, };
+export { Analytics, AnalyticsBuilder } from "./core/analytics";
+export { AnalyticsError, ConfigurationError, ValidationError, NetworkError, StorageError, PluginError, InitializationError, } from "./core/errors";
+export { CookieStorage } from "./storage/cookie-storage";
+export { LocalStorage } from "./storage/local-storage";
+export { HybridStorage } from "./storage/hybrid-storage";
+export { MemoryStorage } from "./storage/memory-storage";
+export { FetchTransport } from "./transport/fetch-transport";
+export { BeaconTransport } from "./transport/beacon-transport";
+export { SessionPlugin } from "./plugins/enrichment/session";
+export { UserPlugin } from "./plugins/enrichment/user";
+export { ClickTrackingPlugin } from "./plugins/auto-track/click";
+export { PageTrackingPlugin } from "./plugins/auto-track/page";
+export { FormTrackingPlugin } from "./plugins/auto-track/form";
+export { ErrorTrackingPlugin } from "./plugins/auto-track/error";
+export { HTTPRequestTrackingPlugin } from "./plugins/node/http-request-tracking";
+export { validateConfig, validateUser, validatePageView, validateClickEvent, validateFormEvent, validateErrorEvent, sanitizeEventData, } from "./utils/validation";
+export { Logger, getLogger, createLogger } from "./utils/logging";
+export { generateId, getEnvironmentType, getEnvironment, isDoNotTrackEnabled, isBrowser, areCookiesAvailable, isLocalStorageAvailable, debounce, throttle, deepClone, deepMerge, } from "./utils/helpers";
+export { loadConfigFromFile, loadConfig } from "./utils/config-loader";
+import { AnalyticsBuilder as Builder } from "./core/analytics";
+export function createAnalytics() {
+    return new Builder();
+}
+export default Builder;