@armco/analytics 0.2.12 → 0.3.1

package/core/analytics.d.ts

@@ -44,5 +44,6 @@ export declare class Analytics implements IAnalytics {
     flush(): Promise<void>;
     private handleBeforeUnload;
     private getEndpoint;
+    resolveEndpointAsync(): Promise<void>;
     destroy(): void;
 }

package/core/analytics.js

@@ -9,6 +9,7 @@ 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";
+import { resolveEndpoint, detectEnvironment } from "../utils/config-loader";
 export class AnalyticsBuilder {
     constructor() {
         this.config = {};
@@ -122,11 +123,19 @@ export class Analytics {
         if (this.initialized) {
             throw new InitializationError("Analytics already initialized");
         }
+        this.logger.info("Loading Configuration");
+        this.logger.info("Check if Analytics enabled");
         if (this.config.respectDoNotTrack && isDoNotTrackEnabled()) {
             this.logger.warn("Do Not Track is enabled, analytics will be disabled");
             this.enabled = false;
             return;
         }
+        this.logger.info("Configuration loaded");
+        const currentEnv = this.config.environment || detectEnvironment();
+        this.logger.info(`Identified environment: ${currentEnv}`);
+        if (currentEnv !== "development" && currentEnv !== "local") {
+            this.logger.info("Identified non-dev environment, analytics auto load wouldn't be attempted.");
+        }
         const context = {
             config: this.config,
             storage: this.storage,
@@ -135,6 +144,10 @@ export class Analytics {
             getSessionId: this.getSessionId.bind(this),
             getUserId: this.getUserId.bind(this),
         };
+        if (this.config.showConsentPopup) {
+            this.logger.info("Display Tracker Popup");
+        }
+        this.logger.info("Hook Event Trackers");
         for (const plugin of this.plugins) {
             try {
                 this.logger.debug(`Initializing plugin: ${plugin.name}`);
@@ -145,10 +158,15 @@ export class Analytics {
             }
         }
         if (this.config.submissionStrategy === "DEFER") {
+            this.logger.info('Hook Handlers to flush events (use when submissionStrategy is configured as "DEFER"');
             this.flushInterval = setInterval(() => {
                 this.flush();
             }, this.config.flushInterval);
         }
+        if (this.config.enableLocation) {
+            this.logger.info("Find User Location Details");
+        }
+        this.logger.info("Initiate Session and Anonymous User ID");
         if (getEnvironmentType() === "browser") {
             window.addEventListener("beforeunload", () => {
                 this.handleBeforeUnload();
@@ -285,10 +303,35 @@ export class Analytics {
         }
     }
     getEndpoint() {
-        if (this.config.endpoint) {
+        if (this.config.resolvedEndpoint) {
+            return this.config.resolvedEndpoint;
+        }
+        if (typeof this.config.endpoint === "string") {
             return this.config.endpoint;
         }
-        return "https://telemetry.armco.dev/events/add";
+        if (this.config.endpoint && typeof this.config.endpoint === "object") {
+            const endpoints = this.config.endpoint;
+            const currentEnv = this.config.environment || detectEnvironment();
+            if (endpoints[currentEnv]) {
+                return endpoints[currentEnv];
+            }
+            const fallbackOrder = ["development", "local", "staging", "production"];
+            for (const fallbackEnv of fallbackOrder) {
+                if (endpoints[fallbackEnv]) {
+                    return endpoints[fallbackEnv];
+                }
+            }
+        }
+        if (this.config.apiKey) {
+            return "https://telemetry.armco.dev/events/add";
+        }
+        return "http://localhost:5001/events/add";
+    }
+    async resolveEndpointAsync() {
+        this.logger.info("Resolving endpoint with health check...");
+        const resolved = await resolveEndpoint(this.config);
+        this.config.resolvedEndpoint = resolved;
+        this.logger.info(`Resolved endpoint: ${resolved}`);
     }
     destroy() {
         this.flush();

package/core/types.d.ts

@@ -1,4 +1,6 @@
 export type Environment = "browser" | "node" | "unknown";
+export type EnvironmentName = "development" | "staging" | "production" | "test" | "local" | string;
+export type EndpointConfig = Record<EnvironmentName, string>;
 export type SubmissionStrategy = "ONEVENT" | "DEFER";
 export type LogLevel = "debug" | "info" | "warn" | "error" | "none";
 export interface EventData {
@@ -54,8 +56,10 @@ export interface LocationData {
 }
 export interface AnalyticsConfig {
     apiKey?: string;
-    endpoint?: string;
+    endpoint?: string | EndpointConfig;
+    resolvedEndpoint?: string;
     updateEndpoint?: string;
+    environment?: EnvironmentName;
     hostProjectName?: string;
     trackEvents?: string[];
     submissionStrategy?: SubmissionStrategy;

package/index.d.ts

@@ -18,7 +18,7 @@ export type { HTTPRequestEvent, HTTPRequestMetadata } from "./plugins/node/http-
 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";
+export { loadConfigFromFile, loadConfig, detectEnvironment, checkEndpointHealth, resolveEndpoint } from "./utils/config-loader";
 import { AnalyticsBuilder as Builder } from "./core/analytics";
 export declare function createAnalytics(): Builder;
 export default Builder;

package/index.js

@@ -16,7 +16,7 @@ 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";
+export { loadConfigFromFile, loadConfig, detectEnvironment, checkEndpointHealth, resolveEndpoint } from "./utils/config-loader";
 import { AnalyticsBuilder as Builder } from "./core/analytics";
 export function createAnalytics() {
     return new Builder();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armco/analytics",
-  "version": "0.2.12",
+  "version": "0.3.1",
   "description": "Universal Analytics Library for Browser and Node.js",
   "main": "index.js",
   "types": "index.d.ts",

package/plugins/auto-track/click.js

@@ -22,8 +22,12 @@ export class ClickTrackingPlugin {
             return;
         }
         this.context = context;
+        this.logger.info("Attaching Click handlers");
         this.attachHandlers();
-        this.logger.info("Click tracking initialized");
+        const trackableElements = document.querySelectorAll(TRACKED_ELEMENTS.join(", "));
+        this.logger.info(`Found ${trackableElements.length} items that can be clicked!`);
+        this.logger.info("Dynamically added elements will be added to this list.");
+        this.logger.info("Click handlers Attached");
     }
     attachHandlers() {
         this.boundHandler = this.handleClick.bind(this);

package/plugins/auto-track/page.js

@@ -13,6 +13,7 @@ export class PageTrackingPlugin {
         }
         this.context = context;
         this.attachHandlers();
+        this.logger.info("Logging page load");
         this.trackCurrentPage();
         this.logger.info("Page tracking initialized");
     }

package/plugins/enrichment/user.js

@@ -17,6 +17,10 @@ export class UserPlugin {
         if (!this.user) {
             this.generateAnonymousId();
         }
+        const userId = this.getUserId();
+        if (userId) {
+            this.logger.info(`Tracking User as ${userId}`);
+        }
     }
     processEvent(event) {
         if (this.user) {
@@ -120,7 +124,10 @@ export class UserPlugin {
             if (config.apiKey) {
                 updateEndpoint = "https://telemetry.armco.dev/events/tag";
             }
-            else if (config.endpoint) {
+            else if (config.resolvedEndpoint) {
+                updateEndpoint = config.resolvedEndpoint.replace("/add", "/tag");
+            }
+            else if (typeof config.endpoint === "string") {
                 updateEndpoint = config.endpoint.replace("/add", "/tag");
             }
             else {

package/utils/config-loader.d.ts

@@ -1,3 +1,6 @@
-import type { AnalyticsConfig } from "../core/types";
+import type { AnalyticsConfig, EnvironmentName } from "../core/types";
 export declare function loadConfigFromFile(): Promise<Partial<AnalyticsConfig> | null>;
 export declare function loadConfig(overrides?: Partial<AnalyticsConfig>): Promise<Partial<AnalyticsConfig>>;
+export declare function detectEnvironment(): EnvironmentName;
+export declare function checkEndpointHealth(url: string): Promise<boolean>;
+export declare function resolveEndpoint(config: Partial<AnalyticsConfig>): Promise<string>;

package/utils/config-loader.js

@@ -1,6 +1,7 @@
 import { getEnvironmentType } from "./helpers";
 import { getLogger } from "./logging";
 const CONFIG_FILE_NAME = "analyticsrc";
+const DEFAULT_FALLBACK_ENDPOINT = "http://localhost:5001/events/add";
 const logger = getLogger();
 export async function loadConfigFromFile() {
     const envType = getEnvironmentType();
@@ -57,3 +58,111 @@ export async function loadConfig(overrides) {
         ...overrides,
     };
 }
+export function detectEnvironment() {
+    const envType = getEnvironmentType();
+    if (envType === "node") {
+        const nodeEnv = process.env.NODE_ENV?.toLowerCase();
+        if (nodeEnv) {
+            return nodeEnv;
+        }
+        return "development";
+    }
+    if (envType === "browser") {
+        const hostname = window.location.hostname;
+        if (hostname === "localhost" || hostname === "127.0.0.1") {
+            return "development";
+        }
+        if (hostname.includes("staging") || hostname.includes("stage")) {
+            return "staging";
+        }
+        if (hostname.includes("test") || hostname.includes("qa")) {
+            return "test";
+        }
+        return "production";
+    }
+    return "development";
+}
+export async function checkEndpointHealth(url) {
+    try {
+        const envType = getEnvironmentType();
+        if (envType === "node") {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            try {
+                const response = await fetch(url.replace("/events/add", "/health"), {
+                    method: "GET",
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                return response.ok || response.status === 404;
+            }
+            catch {
+                clearTimeout(timeout);
+                return false;
+            }
+        }
+        else if (envType === "browser") {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            try {
+                const response = await fetch(url.replace("/events/add", "/health"), {
+                    method: "GET",
+                    mode: "no-cors",
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                return true;
+            }
+            catch {
+                clearTimeout(timeout);
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolveEndpoint(config) {
+    const currentEnv = config.environment || detectEnvironment();
+    logger.info(`Identified environment: ${currentEnv}`);
+    if (typeof config.endpoint === "string") {
+        logger.debug(`Using single endpoint: ${config.endpoint}`);
+        return config.endpoint;
+    }
+    if (config.endpoint && typeof config.endpoint === "object") {
+        const endpoints = config.endpoint;
+        const envEndpoint = endpoints[currentEnv];
+        if (envEndpoint) {
+            logger.info(`Found endpoint for environment '${currentEnv}': ${envEndpoint}`);
+            const isHealthy = await checkEndpointHealth(envEndpoint);
+            if (isHealthy) {
+                logger.info(`Endpoint ${envEndpoint} is reachable`);
+                return envEndpoint;
+            }
+            else {
+                logger.warn(`Endpoint ${envEndpoint} is not reachable, falling back to ${DEFAULT_FALLBACK_ENDPOINT}`);
+                return DEFAULT_FALLBACK_ENDPOINT;
+            }
+        }
+        else {
+            const fallbackOrder = ["development", "local", "staging", "production"];
+            for (const fallbackEnv of fallbackOrder) {
+                if (endpoints[fallbackEnv]) {
+                    logger.warn(`No endpoint configured for '${currentEnv}', using '${fallbackEnv}' endpoint: ${endpoints[fallbackEnv]}`);
+                    return endpoints[fallbackEnv];
+                }
+            }
+            logger.warn(`No endpoint found in configuration, using fallback: ${DEFAULT_FALLBACK_ENDPOINT}`);
+            return DEFAULT_FALLBACK_ENDPOINT;
+        }
+    }
+    if (config.apiKey) {
+        const defaultEndpoint = "https://telemetry.armco.dev/events/add";
+        logger.info(`Using default Armco endpoint: ${defaultEndpoint}`);
+        return defaultEndpoint;
+    }
+    logger.warn(`No endpoint configured, using fallback: ${DEFAULT_FALLBACK_ENDPOINT}`);
+    return DEFAULT_FALLBACK_ENDPOINT;
+}

package/utils/logging.js

@@ -1,5 +1,5 @@
 export class Logger {
-    constructor(level = "info", prefix = "[Analytics]") {
+    constructor(level = "info", prefix = "[ANALYTICS]") {
         this.level = level;
         this.prefix = prefix;
     }