growlytics-tracking 1.0.0

package/dist/esm/http.js

@@ -0,0 +1,176 @@
+"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.HttpClient = void 0;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const url_1 = require("url");
+class HttpClient {
+    options;
+    url;
+    isHttps;
+    constructor(options) {
+        this.options = options;
+        // Standardize baseline endpoint
+        const urlString = options.baseUrl.endsWith('/')
+            ? options.baseUrl.slice(0, -1) + options.path
+            : options.baseUrl + options.path;
+        this.url = new url_1.URL(urlString);
+        this.isHttps = this.url.protocol === 'https:';
+    }
+    log(message, ...args) {
+        if (this.options.debug) {
+            console.log(`[Growlytics-SDK][HTTP] ${message}`, ...args);
+        }
+    }
+    logError(message, ...args) {
+        if (this.options.debug) {
+            console.error(`[Growlytics-SDK][HTTP][ERROR] ${message}`, ...args);
+        }
+    }
+    /**
+     * Sends a batch of tracking events with automatic retries and exponential backoff.
+     */
+    async sendEvents(events) {
+        let attempt = 0;
+        const maxAttempts = this.options.maxRetries + 1;
+        while (attempt < maxAttempts) {
+            try {
+                await this.post(events);
+                this.log(`Successfully sent batch of ${events.length} events.`);
+                return; // Success!
+            }
+            catch (error) {
+                attempt++;
+                const isRetryable = this.isRetryableError(error);
+                if (attempt >= maxAttempts || !isRetryable) {
+                    this.logError(`Failed to send batch of ${events.length} events after ${attempt} attempts. Permanent failure.`);
+                    throw error;
+                }
+                // Calculate backoff delay with jitter
+                const delay = this.calculateBackoff(attempt);
+                this.logError(`Attempt ${attempt} failed: ${error.message || error}. Retrying in ${delay}ms...`);
+                await this.sleep(delay);
+            }
+        }
+    }
+    /**
+     * Determine if the error is retryable (network drops, 5xx server errors, or 429 rate limits)
+     */
+    isRetryableError(error) {
+        // If it's a network-level connection error, it's retryable
+        if (error.code) {
+            const retryableCodes = ['ECONNRESET', 'EADDRINUSE', 'ETIMEDOUT', 'ECONNREFUSED', 'ENOTFOUND', 'EPIPE'];
+            if (retryableCodes.includes(error.code)) {
+                return true;
+            }
+        }
+        // Check status code if it's an HTTP response error
+        if (error.statusCode) {
+            const status = error.statusCode;
+            // Retry on 429 (Rate Limit) and any 5xx (Server Error)
+            return status === 429 || (status >= 500 && status < 600);
+        }
+        return false;
+    }
+    /**
+     * Calculate exponential backoff delay with full jitter
+     */
+    calculateBackoff(attempt) {
+        const delay = this.options.retryInitialDelayMs * Math.pow(2, attempt - 1);
+        const cappedDelay = Math.min(this.options.retryMaxDelayMs, delay);
+        // Apply jitter: randomize between 50% and 100% of the calculated delay
+        const jitter = 0.5 + Math.random() * 0.5;
+        return Math.floor(cappedDelay * jitter);
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Performs the HTTP/HTTPS POST request.
+     */
+    post(events) {
+        return new Promise((resolve, reject) => {
+            const payloadString = JSON.stringify(events);
+            const headers = {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(payloadString),
+                'User-Agent': 'growlytics-node-sdk/1.0.0',
+            };
+            if (this.options.apiKey) {
+                headers['Authorization'] = `Bearer ${this.options.apiKey}`;
+                headers['X-Growlytics-Key'] = this.options.apiKey; // Alternate standard tracking header
+            }
+            const requestOptions = {
+                hostname: this.url.hostname,
+                port: this.url.port || (this.isHttps ? 443 : 80),
+                path: this.url.pathname + this.url.search,
+                method: 'POST',
+                headers: headers,
+                timeout: 10000, // 10 second timeout
+            };
+            const requestModule = this.isHttps ? https : http;
+            const req = requestModule.request(requestOptions, (res) => {
+                let responseBody = '';
+                res.on('data', (chunk) => {
+                    responseBody += chunk;
+                });
+                res.on('end', () => {
+                    const status = res.statusCode || 0;
+                    if (status >= 200 && status < 300) {
+                        resolve();
+                    }
+                    else {
+                        const error = new Error(`HTTP Error Status ${status}: ${responseBody || res.statusMessage}`);
+                        error.statusCode = status;
+                        reject(error);
+                    }
+                });
+            });
+            req.on('error', (err) => {
+                reject(err);
+            });
+            req.on('timeout', () => {
+                req.destroy();
+                const err = new Error('Request timed out');
+                err.code = 'ETIMEDOUT';
+                reject(err);
+            });
+            req.write(payloadString);
+            req.end();
+        });
+    }
+}
+exports.HttpClient = HttpClient;

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export { Growlytic } from "./growlytics";

package/dist/esm/index.js

@@ -0,0 +1,20 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Growlytic = void 0;
+__exportStar(require("./types"), exports);
+var growlytics_1 = require("./growlytics");
+Object.defineProperty(exports, "Growlytic", { enumerable: true, get: function () { return growlytics_1.Growlytic; } });

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/queue.d.ts

@@ -0,0 +1,45 @@
+import { TrackingEvent } from './types';
+import { HttpClient } from './http';
+export interface QueueConfig {
+    batchSize: number;
+    flushIntervalMs: number;
+    maxQueueSize: number;
+    debug?: boolean;
+    onError?: (error: Error, events: TrackingEvent[]) => void;
+}
+export declare class EventQueue {
+    private client;
+    private config;
+    private queue;
+    private timer;
+    private isFlushing;
+    private activeFlushPromise;
+    constructor(client: HttpClient, config: QueueConfig);
+    private log;
+    /**
+     * Add a tracking event to the queue. If the queue is full, the oldest event is discarded.
+     */
+    add(event: TrackingEvent): void;
+    /**
+     * Manually trigger a flush of all currently queued events.
+     * Returns a promise that resolves when the flush is complete.
+     */
+    flush(): Promise<void>;
+    /**
+     * Performs the flush logic, calling the HttpClient to send batches of events.
+     */
+    private performFlush;
+    private startTimer;
+    /**
+     * Resets the background interval timer.
+     */
+    private resetTimer;
+    /**
+     * Stops the background timer.
+     */
+    stop(): void;
+    /**
+     * Get the current count of events in the queue.
+     */
+    get length(): number;
+}

package/dist/esm/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/esm/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/esm/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/esm/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/esm/types.js

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

package/dist/esm/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;