growlytics-tracking 1.0.0

package/dist/cjs/queue.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventQueue = void 0;
+class EventQueue {
+    client;
+    config;
+    queue = [];
+    timer = null;
+    isFlushing = false;
+    activeFlushPromise = null;
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+        this.startTimer();
+    }
+    log(message, ...args) {
+        if (this.config.debug) {
+            console.log(`[Growlytics-SDK][Queue] ${message}`, ...args);
+        }
+    }
+    /**
+     * Add a tracking event to the queue. If the queue is full, the oldest event is discarded.
+     */
+    add(event) {
+        if (this.queue.length >= this.config.maxQueueSize) {
+            const dropped = this.queue.shift();
+            this.log(`Queue full (${this.config.maxQueueSize}). Dropped oldest event to prevent OOM:`, dropped ? dropped.event_type : 'unknown');
+        }
+        this.queue.push(event);
+        this.log(`Event '${event.event_type}' added. Queue size: ${this.queue.length}`);
+        // If batch size is reached, trigger an asynchronous flush immediately
+        if (this.queue.length >= this.config.batchSize) {
+            this.flush().catch(() => { });
+        }
+    }
+    /**
+     * Manually trigger a flush of all currently queued events.
+     * Returns a promise that resolves when the flush is complete.
+     */
+    async flush() {
+        if (this.isFlushing) {
+            this.log('Flush already in progress, waiting for it to complete...');
+            return this.activeFlushPromise || Promise.resolve();
+        }
+        this.isFlushing = true;
+        this.activeFlushPromise = this.performFlush();
+        try {
+            await this.activeFlushPromise;
+        }
+        finally {
+            this.isFlushing = false;
+            this.activeFlushPromise = null;
+        }
+    }
+    /**
+     * Performs the flush logic, calling the HttpClient to send batches of events.
+     */
+    async performFlush() {
+        this.resetTimer();
+        while (this.queue.length > 0) {
+            // Dequeue a batch of events
+            const batch = this.queue.splice(0, this.config.batchSize);
+            if (batch.length === 0) {
+                break;
+            }
+            this.log(`Flushing batch of ${batch.length} events...`);
+            try {
+                await this.client.sendEvents(batch);
+            }
+            catch (error) {
+                this.log(`Error flushing batch of ${batch.length} events:`, error.message || error);
+                // Trigger error callback for custom handling (e.g. write to fallback log file, emit metric)
+                if (this.config.onError) {
+                    try {
+                        this.config.onError(error, batch);
+                    }
+                    catch (callbackErr) {
+                        this.log('Error inside user-defined onError handler:', callbackErr);
+                    }
+                }
+            }
+        }
+    }
+    startTimer() {
+        this.resetTimer();
+    }
+    /**
+     * Resets the background interval timer.
+     */
+    resetTimer() {
+        if (this.timer) {
+            clearInterval(this.timer);
+        }
+        this.timer = setInterval(() => {
+            if (this.queue.length > 0) {
+                this.log(`Flush interval of ${this.config.flushIntervalMs}ms reached. Flushing...`);
+                this.flush().catch(() => { });
+            }
+        }, this.config.flushIntervalMs);
+        // Unref the timer so it doesn't block process exit if there is no other work in Node's event loop
+        if (this.timer && typeof this.timer.unref === 'function') {
+            this.timer.unref();
+        }
+    }
+    /**
+     * Stops the background timer.
+     */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Get the current count of events in the queue.
+     */
+    get length() {
+        return this.queue.length;
+    }
+}
+exports.EventQueue = EventQueue;

package/dist/cjs/tracker.d.ts

@@ -0,0 +1,28 @@
+import { GrowlyticsConfig, TrackingEventPayload } from './types';
+export declare class GrowlyticsTracker {
+    private config;
+    private client;
+    private queue;
+    constructor(options?: GrowlyticsConfig);
+    private log;
+    /**
+     * Tracks an event by compiling client metadata and placing it in the buffer queue.
+     *
+     * @param eventType Name of the event, e.g. 'product_view' or 'add_to_cart'
+     * @param payload Custom event details and parameters
+     */
+    track(eventType: string, payload?: TrackingEventPayload): void;
+    /**
+     * Triggers a manual flush to send all currently buffered events.
+     * Useful for serverless functions (like AWS Lambda) before finishing execution.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shuts down the tracker, flushing any remaining events and stopping the interval timers.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Set up hooks to flush the queue when the Node process is exiting.
+     */
+    private setupExitHandlers;
+}

package/dist/cjs/tracker.js

@@ -0,0 +1,177 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrowlyticsTracker = void 0;
+const os = __importStar(require("os"));
+const http_1 = require("./http");
+const queue_1 = require("./queue");
+const utils_1 = require("./utils");
+const SDK_NAME = 'growlytics-node-sdk';
+const SDK_VERSION = '1.0.0';
+class GrowlyticsTracker {
+    config;
+    client;
+    queue;
+    constructor(options = {}) {
+        // Standardize configurations with robust default values
+        this.config = {
+            clientId: options.clientId || 0,
+            workspaceId: options.workspaceId || 0,
+            applicationId: options.applicationId || 0,
+            apiKey: options.apiKey || '',
+            baseUrl: options.baseUrl || 'https://api.growlytics.co',
+            path: options.path || '/events',
+            batchSize: options.batchSize ?? 20,
+            flushIntervalMs: options.flushIntervalMs ?? 2000,
+            maxQueueSize: options.maxQueueSize ?? 1000,
+            debug: options.debug ?? false,
+            maxRetries: options.maxRetries ?? 3,
+            retryInitialDelayMs: options.retryInitialDelayMs ?? 1000,
+            retryMaxDelayMs: options.retryMaxDelayMs ?? 30000,
+            onError: options.onError || (() => { }),
+            disableAutoContext: options.disableAutoContext ?? false,
+        };
+        // Initialize the HTTP Client
+        this.client = new http_1.HttpClient({
+            baseUrl: this.config.baseUrl,
+            path: this.config.path,
+            apiKey: this.config.apiKey,
+            maxRetries: this.config.maxRetries,
+            retryInitialDelayMs: this.config.retryInitialDelayMs,
+            retryMaxDelayMs: this.config.retryMaxDelayMs,
+            debug: this.config.debug,
+        });
+        // Initialize the Event Queue
+        this.queue = new queue_1.EventQueue(this.client, {
+            batchSize: this.config.batchSize,
+            flushIntervalMs: this.config.flushIntervalMs,
+            maxQueueSize: this.config.maxQueueSize,
+            debug: this.config.debug,
+            onError: this.config.onError,
+        });
+        this.log('Tracker initialized successfully.');
+        this.setupExitHandlers();
+    }
+    log(message, ...args) {
+        if (this.config.debug) {
+            console.log(`[Growlytics-SDK] ${message}`, ...args);
+        }
+    }
+    /**
+     * Tracks an event by compiling client metadata and placing it in the buffer queue.
+     *
+     * @param eventType Name of the event, e.g. 'product_view' or 'add_to_cart'
+     * @param payload Custom event details and parameters
+     */
+    track(eventType, payload = {}) {
+        if (!eventType) {
+            throw new Error("Event tracking requires a valid 'event_type' / event name.");
+        }
+        this.log(`Track called for event: ${eventType}`);
+        // Auto-detect server device metadata if enabled
+        let autoDevice = {};
+        if (!this.config.disableAutoContext) {
+            try {
+                autoDevice = {
+                    device_type: 'server',
+                    os: os.platform(),
+                    os_version: os.release(),
+                    browser: 'node',
+                    browser_version: process.version,
+                    language: process.env.LANG || 'en-US',
+                    user_agent: `${SDK_NAME}/${SDK_VERSION} (node ${process.version}; ${os.platform()} ${os.release()})`,
+                };
+            }
+            catch (err) {
+                this.log('Failed to auto-gather server context details:', err);
+            }
+        }
+        // Prepare SDK library details
+        const libraryMetadata = {
+            name: SDK_NAME,
+            version: SDK_VERSION,
+        };
+        // Construct the base tracking event with required system keys and auto-generated defaults
+        const defaultFields = {
+            event_type: eventType,
+            client_id: this.config.clientId,
+            workspace_id: this.config.workspaceId,
+            application_id: this.config.applicationId,
+            timestamp: new Date().toISOString(),
+            anonymous_id: (0, utils_1.generateUUID)(),
+            request_id: (0, utils_1.generateUUID)(),
+            library: libraryMetadata,
+        };
+        // Deep merge payload into defaults. User provided fields will take precedence.
+        const compiledEvent = (0, utils_1.mergeDeep)(defaultFields, payload);
+        // Explicitly override sub-objects if they need merged device context
+        if (!this.config.disableAutoContext) {
+            compiledEvent.device = (0, utils_1.mergeDeep)(autoDevice, payload.device || {});
+        }
+        // Add back the required event_type just in case payload modified it
+        compiledEvent.event_type = eventType;
+        // Enqueue the finalized event
+        this.queue.add(compiledEvent);
+    }
+    /**
+     * Triggers a manual flush to send all currently buffered events.
+     * Useful for serverless functions (like AWS Lambda) before finishing execution.
+     */
+    async flush() {
+        this.log('Manual flush triggered.');
+        await this.queue.flush();
+    }
+    /**
+     * Shuts down the tracker, flushing any remaining events and stopping the interval timers.
+     */
+    async shutdown() {
+        this.log('Shutdown initiated.');
+        await this.flush();
+        this.queue.stop();
+        this.log('Tracker stopped.');
+    }
+    /**
+     * Set up hooks to flush the queue when the Node process is exiting.
+     */
+    setupExitHandlers() {
+        process.once('beforeExit', () => {
+            this.log('Process beforeExit hook triggered. Flushing queue...');
+            this.flush().catch((err) => {
+                this.log('Failed to flush queue on beforeExit:', err);
+            });
+        });
+    }
+}
+exports.GrowlyticsTracker = GrowlyticsTracker;

package/dist/cjs/types.d.ts

@@ -0,0 +1,16 @@
+export interface UserIdentifier {
+    customer_id?: string;
+    external_id?: string;
+    email?: string;
+    phone?: string;
+}
+export interface InitOptions {
+    client_id: number;
+    workspace_id: number;
+    app_id: number;
+    debug?: boolean;
+}
+export interface TrackPayload {
+    user_identifier?: UserIdentifier;
+    custom?: Record<string, any>;
+}

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Generate a cryptographically secure random UUID (v4)
+ * Uses native crypto.randomUUID if available (Node 14.17.0+),
+ * falls back to a math-based generator for older Node environments.
+ */
+export declare function generateUUID(): string;
+/**
+ * Check if a value is a plain object
+ */
+export declare function isObject(item: any): item is Record<string, any>;
+/**
+ * Deep merges two objects. User-provided values (source) will overwrite target values,
+ * but nested structures will be recursively merged rather than replaced entirely.
+ */
+export declare function mergeDeep<T extends Record<string, any>>(target: T, source: Record<string, any>): T;

package/dist/cjs/utils.js

@@ -0,0 +1,88 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUUID = generateUUID;
+exports.isObject = isObject;
+exports.mergeDeep = mergeDeep;
+const crypto = __importStar(require("crypto"));
+/**
+ * Generate a cryptographically secure random UUID (v4)
+ * Uses native crypto.randomUUID if available (Node 14.17.0+),
+ * falls back to a math-based generator for older Node environments.
+ */
+function generateUUID() {
+    try {
+        if (typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+    }
+    catch (e) {
+        // Ignore error and fall back
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Check if a value is a plain object
+ */
+function isObject(item) {
+    return item && typeof item === 'object' && !Array.isArray(item);
+}
+/**
+ * Deep merges two objects. User-provided values (source) will overwrite target values,
+ * but nested structures will be recursively merged rather than replaced entirely.
+ */
+function mergeDeep(target, source) {
+    const output = { ...target };
+    if (isObject(target) && isObject(source)) {
+        Object.keys(source).forEach((key) => {
+            if (isObject(source[key])) {
+                if (!(key in target)) {
+                    Object.assign(output, { [key]: source[key] });
+                }
+                else {
+                    output[key] = mergeDeep(target[key], source[key]);
+                }
+            }
+            else if (source[key] !== undefined) {
+                Object.assign(output, { [key]: source[key] });
+            }
+        });
+    }
+    return output;
+}

package/dist/esm/engagement.d.ts

@@ -0,0 +1,6 @@
+import { SectionConfig } from "./helper_types";
+export declare function registerSections(configs: SectionConfig[]): void;
+export declare function buildSections(): {
+    section_id: string;
+    visible_time_ms: number;
+}[];

package/dist/esm/engagement.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSections = registerSections;
+exports.buildSections = buildSections;
+const sections = new Map();
+function registerSections(configs) {
+    const observer = new IntersectionObserver((entries) => {
+        entries.forEach((entry) => {
+            const element = entry.target;
+            const sectionId = element.dataset.growlyticId;
+            let section = sections.get(sectionId);
+            if (!section) {
+                section = { id: sectionId, visible_time_ms: 0 };
+                sections.set(sectionId, section);
+            }
+            if (entry.isIntersecting) {
+                section.start_time = Date.now();
+            }
+            else {
+                if (section.start_time) {
+                    section.visible_time_ms += Date.now() - section.start_time;
+                    section.start_time = undefined;
+                }
+            }
+        });
+    }, {
+        threshold: 0.5
+    });
+    configs.forEach((config) => {
+        const element = document.querySelector(config.selector);
+        if (!element) {
+            return;
+        }
+        element.dataset.growlyticId = config.id;
+        observer.observe(element);
+    });
+}
+function buildSections() {
+    return Array.from(sections.values()).map((section) => {
+        let totalTime = section.visible_time_ms;
+        if (section.start_time) {
+            totalTime += Date.now() - section.start_time;
+        }
+        return { section_id: section.id, visible_time_ms: totalTime };
+    });
+}

package/dist/esm/final_payload.d.ts

@@ -0,0 +1,13 @@
+import { UserIdentifier } from "./types";
+import { Engagement } from "./helper_types";
+export interface FinalEventPayload {
+    application_id: number;
+    event_type: string;
+    timestamp: string;
+    anonymous_id: string;
+    session_id: string;
+    request_id: string;
+    user_identifier?: UserIdentifier;
+    engagement?: Engagement;
+    custom?: Record<string, any>;
+}

package/dist/esm/final_payload.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/growlytics.d.ts

@@ -0,0 +1,16 @@
+import { InitOptions, TrackPayload } from "./types";
+declare class GrowlyticSDK {
+    private clientId;
+    private workspaceId;
+    private appId;
+    private sessionId;
+    private anonymousId;
+    init(options: InitOptions): void;
+    registerSections(sections: {
+        id: string;
+        selector: string;
+    }[]): void;
+    track(eventType: string, payload: TrackPayload): void;
+}
+export declare const Growlytic: GrowlyticSDK;
+export {};

package/dist/esm/growlytics.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Growlytic = void 0;
+const engagement_1 = require("./engagement");
+class GrowlyticSDK {
+    clientId;
+    workspaceId;
+    appId;
+    sessionId;
+    anonymousId;
+    init(options) {
+        this.clientId = options.client_id;
+        this.workspaceId = options.workspace_id;
+        this.appId = options.app_id;
+        const existingAnonymousId = localStorage.getItem("growlytic_anonymous_id");
+        const existingSessionId = sessionStorage.getItem("growlytic_session_id");
+        if (existingAnonymousId) {
+            this.anonymousId = existingAnonymousId;
+        }
+        else {
+            this.anonymousId = crypto.randomUUID();
+            localStorage.setItem("growlytic_anonymous_id", this.anonymousId);
+        }
+        if (existingSessionId) {
+            this.sessionId = existingSessionId;
+        }
+        else {
+            this.sessionId = crypto.randomUUID();
+            sessionStorage.setItem("growlytic_session_id", this.sessionId);
+        }
+        console.log("[Nexora] Initialized", options);
+    }
+    registerSections(sections) {
+        (0, engagement_1.registerSections)(sections);
+    }
+    track(eventType, payload) {
+        const event = {
+            client_id: this.clientId,
+            workspace_id: this.workspaceId,
+            app_id: this.appId,
+            event_type: eventType,
+            timestamp: new Date().toISOString(),
+            anonymous_id: this.anonymousId,
+            session_id: this.sessionId,
+            request_id: crypto.randomUUID(),
+            user_identifier: payload.user_identifier,
+            engagement: {
+                sections: (0, engagement_1.buildSections)()
+            },
+            custom: payload.custom
+        };
+        console.log(event);
+    }
+}
+exports.Growlytic = new GrowlyticSDK();

package/dist/esm/helper_types.d.ts

@@ -0,0 +1,16 @@
+export interface SectionState {
+    id: string;
+    visible_time_ms: number;
+    start_time?: number;
+}
+export interface SectionConfig {
+    id: string;
+    selector: string;
+}
+export interface SectionEngagement {
+    section_id: string;
+    visible_time_ms: number;
+}
+export interface Engagement {
+    sections: SectionEngagement[];
+}

package/dist/esm/helper_types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/http.d.ts

@@ -0,0 +1,35 @@
+import { TrackingEvent } from './types';
+export interface HttpClientOptions {
+    baseUrl: string;
+    path: string;
+    apiKey?: string;
+    maxRetries: number;
+    retryInitialDelayMs: number;
+    retryMaxDelayMs: number;
+    debug?: boolean;
+}
+export declare class HttpClient {
+    private options;
+    private url;
+    private isHttps;
+    constructor(options: HttpClientOptions);
+    private log;
+    private logError;
+    /**
+     * Sends a batch of tracking events with automatic retries and exponential backoff.
+     */
+    sendEvents(events: TrackingEvent[]): Promise<void>;
+    /**
+     * Determine if the error is retryable (network drops, 5xx server errors, or 429 rate limits)
+     */
+    private isRetryableError;
+    /**
+     * Calculate exponential backoff delay with full jitter
+     */
+    private calculateBackoff;
+    private sleep;
+    /**
+     * Performs the HTTP/HTTPS POST request.
+     */
+    private post;
+}