helm-analytics 1.1.0 → 5.0.1

package/README.md

@@ -36,3 +36,37 @@ app.post('/purchase', (req, res) => {
   res.json({ success: true });
 });
 ```
+
+## Custom Event Tracking (NEW v5)
+
+Track specific business events with custom properties:
+
+```javascript
+app.post('/signup', (req, res) => {
+  // ... logic ...
+  helm.trackEvent(req, 'signup_success', { plan: 'growth', method: 'google' });
+  res.json({ status: 'ok' });
+});
+```
+
+## Session Stitching
+
+To link server-side events back to the browser session, ensure you pass the `sessionId` (retrieved from `sessionStorage.getItem('helm_session_id')`) in the `X-Helm-Session-Id` header of your frontend API calls.
+
+## Features
+
+- **Non-blocking**: Uses non-blocking fetch calls for event ingestion.
+- **Shield Mode**: Active defense against bots and malicious traffic.
+- **Auto-UTM Extraction**: Automatically captures marketing campaign data from query strings.
+- **Web Vitals**: Track LCP, CLS, and FID performance metrics from the server.
+- **Custom Events**: Track business milestones beyond pageviews.
+- **Session Stitching**: Maintain user journey continuity via headers.
+
+## Configuration
+
+You can also set the Site ID and API URL via environment variables:
+
+```bash
+export HELM_SITE_ID="your-uuid"
+export HELM_API_URL="https://analytics.your-domain.com"
+```

package/index.js

@@ -3,7 +3,9 @@ const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch
 class HelmAnalytics {
   constructor(options = {}) {
     this.siteId = options.siteId || process.env.HELM_SITE_ID;
-    this.apiUrl = (options.apiUrl || 'https://api-sentinel.getmusterup.com').replace(/\/$/, '').replace(/\/track$/, '');
+    this.apiKey = options.apiKey || process.env.HELM_API_KEY;
+    const baseApi = options.apiUrl || process.env.HELM_API_URL || 'https://api.helm-analytics.com';
+    this.apiUrl = baseApi.replace(/\/$/, '').replace(/\/track$/, '');
     
     if (!this.siteId) {
       console.warn('HelmAnalytics: No Site ID provided. Tracking will be disabled.');
@@ -22,10 +24,15 @@ class HelmAnalytics {
             url: payload.url
         };
 
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+
         const res = await fetch(`${this.apiUrl}/api/shield/decision`, {
             method: 'POST',
             body: JSON.stringify(checkPayload),
-            headers: { 'Content-Type': 'application/json' }
+            headers: headers
         });
 
         if (res.ok) {
@@ -42,19 +49,34 @@ class HelmAnalytics {
   }
 
   // Generic track method
-  async track(req, eventType = 'pageview', metadata = {}, shield = false) {
+  async track(req, eventType = 'pageview', options = {}) {
     if (!this.siteId) return true;
+    
+    const { metadata = {}, shield = false, pageTitle = '', screenWidth = 0, performance = {} } = options;
 
     try {
+      const url = req.originalUrl || req.url || '';
+      const query = req.query || {};
+      
+      // Auto-extract UTMs
+      const utmParams = {};
+      Object.keys(query).forEach(key => {
+        if (key.startsWith('utm_')) utmParams[key] = query[key];
+      });
+
       const payload = {
         siteId: this.siteId,
-        url: req.originalUrl || req.url,
+        sessionId: req.headers['x-helm-session-id'] || req.sessionId || '', 
+        url: url,
         userAgent: req.headers['user-agent'] || '',
         referrer: req.headers['referer'] || req.headers['referrer'] || '',
-        // ClientIP logic: Headers or socket
         clientIp: req.headers['x-forwarded-for'] ? req.headers['x-forwarded-for'].split(',')[0].trim() : (req.socket ? req.socket.remoteAddress : ''),
         eventType: eventType,
+        pageTitle: pageTitle,
+        screenWidth: screenWidth,
         isServerSide: true,
+        ...utmParams,
+        ...performance,
         ...metadata
       };
 
@@ -62,16 +84,21 @@ class HelmAnalytics {
       if (shield) {
         const { allowed, reason } = await this.checkShield(payload);
         if (!allowed) {
-            console.warn(`Helm Shield Blocked: ${payload.clientIp} Reason: ${reason}`);
+            console.warn(`[Helm Shield] Blocked IP: ${payload.clientIp} Reason: ${reason}`);
             return false;
         }
       }
 
-      // Fire and forget (don't await unless we want to ensure delivery, usually non-blocking is preferred for tracking)
+      const headers = { 'Content-Type': 'application/json' };
+      if (this.apiKey) {
+          headers['Authorization'] = `Bearer ${this.apiKey}`;
+      }
+
+      // Fire and forget
       fetch(`${this.apiUrl}/track`, {
         method: 'POST',
         body: JSON.stringify(payload),
-        headers: { 'Content-Type': 'application/json' }
+        headers: headers
       }).catch(err => {});
 
       return true;
@@ -81,6 +108,38 @@ class HelmAnalytics {
     }
   }
 
+  // Custom event tracking
+  async trackEvent(req, eventName, properties = {}) {
+    if (!this.siteId) return true;
+
+    try {
+      const payload = {
+        siteId: this.siteId,
+        sessionId: req.headers['x-helm-session-id'] || req.sessionId || '',
+        eventName: eventName,
+        properties: properties,
+        url: req.originalUrl || req.url,
+        referrer: req.headers['referer'] || req.headers['referrer'] || '',
+        isServerSide: true
+      };
+
+      const headers = { 'Content-Type': 'application/json' };
+      if (this.apiKey) {
+          headers['Authorization'] = `Bearer ${this.apiKey}`;
+      }
+
+      fetch(`${this.apiUrl}/track/event`, {
+        method: 'POST',
+        body: JSON.stringify(payload),
+        headers: headers
+      }).catch(err => {});
+
+      return true;
+    } catch (err) {
+      return true;
+    }
+  }
+
   // Express Middleware
   middleware(options = {}) {
     const shield = options.shield || false;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "helm-analytics",
-  "version": "1.1.0",
-  "description": "Official Node.js Middleware for Helm Analytics",
+  "version": "5.0.1",
+  "description": "Official Node.js SDK for Helm Analytics",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -22,6 +22,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Sentinel-Analytics/sentinel-mvp/tree/master/sdk/node"
+    "url": "https://github.com/Helm-Analytics/sentinel-mvp/tree/main/sdk/node"
   }
 }