growlytics-tracking 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Growlytics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# Growlytics Node.js Tracking SDK
+
+An enterprise-grade, high-performance, and resilient Node.js SDK for the Growlytics event tracking platform.
+
+[![npm version](https://img.shields.io/npm/v/growlytics-tracking.svg?style=flat-square)](https://www.npmjs.com/package/growlytics-tracking)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+---
+
+## Key Features
+
+- **Zero Dependencies**: Keeps your `node_modules` completely clean and free of supply-chain vulnerabilities.
+- **Dual Package Support**: Native ES Module (`esm`) and CommonJS (`cjs`) builds.
+- **TypeScript Support**: Full, detailed TypeScript declarations out of the box for autocomplete on tracking structures.
+- **In-Memory Buffering & Batching**: Groups events together and transmits them in batches to reduce network overhead.
+- **Network Resilience & Retries**: Automatic HTTP requests retries with **exponential backoff and full jitter** for handling intermittent network failures.
+- **Automatic Context Population**: Automatically populates server OS, runtime version, ISO timestamps, and generates random UUIDs for `anonymous_id` and `request_id` if missing.
+- **Graceful Shutdown**: Automatically flushes queued events when your Node process exits.
+
+---
+
+## Installation
+
+Install via npm:
+
+```bash
+npm install growlytics-tracking
+```
+
+Or via yarn:
+
+```bash
+yarn add growlytics-tracking
+```
+
+---
+
+## Quick Start
+
+### 1. Global Singleton Pattern (Recommended)
+
+Ideal for single-instance web servers (e.g. Express, Koa, NestJS). Call `initiate` once at app startup, then import and track events anywhere.
+
+**CommonJS (JavaScript):**
+```javascript
+const Growlytics = require('growlytics-tracking');
+
+// Initialize the tracker once at application startup
+Growlytics.initiate({
+  clientId: 1001,
+  workspaceId: 2001,
+  applicationId: 3001,
+  apiKey: 'your-api-key-here',
+  debug: false
+});
+
+// Track events anywhere in your code
+Growlytics.track('product_view', {
+  session_id: 'sess_123',
+  user_identifier: {
+    customer_id: 'cust_123',
+    email: 'customer@gmail.com',
+  },
+  product: {
+    product_id: 'SKU123',
+    name: 'Bathroom Mat',
+    price: 499,
+    currency: 'INR'
+  }
+});
+```
+
+**ES Modules (TypeScript / JavaScript):**
+```typescript
+import Growlytics from 'growlytics-tracking';
+
+// Initialize
+Growlytics.initiate({
+  clientId: 1001,
+  workspaceId: 2001,
+  applicationId: 3001,
+  apiKey: 'your-api-key-here',
+  batchSize: 20,
+  flushIntervalMs: 2000
+});
+
+// Track
+Growlytics.track('add_to_cart', {
+  session_id: 'sess_123',
+  cart: {
+    cart_id: 'cart_123',
+    total_items: 1,
+    total_amount: 499
+  }
+});
+```
+
+### 2. Multi-Instance Pattern
+
+If your application needs to connect to multiple workspaces or clients, instantiate the tracker class directly:
+
+```typescript
+import { GrowlyticsTracker } from 'growlytics-tracking';
+
+const trackerA = new GrowlyticsTracker({
+  clientId: 1001,
+  workspaceId: 2001,
+  apiKey: 'key-a'
+});
+
+const trackerB = new GrowlyticsTracker({
+  clientId: 5005,
+  workspaceId: 9009,
+  apiKey: 'key-b'
+});
+
+trackerA.track('custom_event', { data: 'value' });
+```
+
+---
+
+## SDK Configuration Options
+
+Initialize the SDK with the following configuration options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `clientId` | `number` | `0` | Fallback Client ID (if not provided per event payload). |
+| `workspaceId` | `number` | `0` | Fallback Workspace ID (if not provided per event payload). |
+| `applicationId` | `number` | `0` | Fallback Application ID (if not provided per event payload). |
+| `apiKey` | `string` | `""` | Authentication write key passed via the `Authorization` header. |
+| `baseUrl` | `string` | `"https://api.growlytics.co"` | Base URL of the Growlytics event ingestion endpoint. |
+| `path` | `string` | `"/events"` | Ingestion path appended to `baseUrl`. |
+| `batchSize` | `number` | `20` | Max number of events sent in a single HTTP batch. |
+| `flushIntervalMs` | `number` | `2000` | Periodically flushes queued events (in milliseconds). |
+| `maxQueueSize` | `number` | `1000` | Max buffer capacity. Discards oldest events if queue overflows. |
+| `maxRetries` | `number` | `3` | Number of times to retry failed connection drops/5xx responses. |
+| `retryInitialDelayMs` | `number` | `1000` | Base delay for the first exponential retry. |
+| `retryMaxDelayMs` | `number` | `30000` | Maximum cap on retry backoff delay. |
+| `debug` | `boolean` | `false` | Enables logs for troubleshooting. |
+| `disableAutoContext` | `boolean` | `false` | Set to true to disable automatic server environment context capture. |
+| `onError` | `function` | `undefined` | Callback invoked when a batch fails permanently after all retries. |
+
+---
+
+## Automatic Context and Value Generations
+
+To save developer time and ensure data reliability, the SDK automatically generates and merges fields:
+
+- **Timestamps**: If `timestamp` is omitted in the event, the current system ISO time is added.
+- **UUID Generations**:
+  - `anonymous_id`: If not provided, a random, cryptographically secure **UUID v4** is generated for the event.
+  - `request_id`: A unique, random **UUID v4** is generated for every tracked event to prevent duplicate ingestion.
+- **Device Details**: Unless `disableAutoContext` is set to `true`, the SDK gathers the server environment (Node version, OS platform, and OS release) and populates the `device` object:
+  ```json
+  "device": {
+    "device_type": "server",
+    "os": "darwin",
+    "os_version": "21.6.0",
+    "browser": "node",
+    "browser_version": "v18.16.0",
+    "language": "en-US",
+    "user_agent": "growlytics-node-sdk/1.0.0 (node v18.16.0; darwin 21.6.0)"
+  }
+  ```
+  *Note: Any nested values provided inside the event `device` parameter will override these defaults.*
+
+---
+
+## Advanced Usage
+
+### 1. Serverless Environments (AWS Lambda, Vercel)
+
+In serverless execution environments, Node's event loop may be frozen immediately after returning a response. To guarantee that tracked events reach Growlytics before the environment suspends, call `.flush()` synchronously before terminating your function:
+
+```javascript
+exports.handler = async (event) => {
+  Growlytics.track('lambda_execution', { function_name: 'payment-processor' });
+  
+  // Force flush the tracking queue immediately
+  await Growlytics.flush();
+  
+  return { statusCode: 200, body: 'Done' };
+};
+```
+
+### 2. Failure Callbacks (`onError`)
+
+If you want to log permanent failure payloads to a fallback logger, database, or alerting tool, register the `onError` hook:
+
+```javascript
+Growlytics.initiate({
+  clientId: 1001,
+  onError: (error, failedEvents) => {
+    console.error(`Growlytics Delivery Failure: ${error.message}`);
+    // Save to backup file or dispatch to alerting systems
+    backupLogger.log(failedEvents);
+  }
+});
+```
+
+---
+
+## License
+
+MIT License. Copyright (c) Growlytics.

package/dist/cjs/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/cjs/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/cjs/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/cjs/final_payload.js

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

package/dist/cjs/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/cjs/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/cjs/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/cjs/helper_types.js

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

package/dist/cjs/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;
+}

package/dist/cjs/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/cjs/index.d.ts

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

package/dist/cjs/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/cjs/package.json

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

package/dist/cjs/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;
+}