helm-analytics 5.0.0 → 5.0.2

package/README.md

@@ -57,5 +57,16 @@ To link server-side events back to the browser session, ensure you pass the `ses
 
 - **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,20 +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,
-        sessionId: req.headers['x-helm-session-id'] || req.sessionId || '', // Support session stitching
-        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
       };
 
@@ -68,11 +89,20 @@ class HelmAnalytics {
         }
       }
 
+      const headers = { 
+        'Content-Type': 'application/json',
+        'User-Agent': payload.userAgent || 'HelmAnalytics/NodeSDK',
+        'X-Forwarded-For': payload.clientIp || ''
+      };
+      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;
@@ -97,10 +127,19 @@ class HelmAnalytics {
         isServerSide: true
       };
 
+      const headers = { 
+        'Content-Type': 'application/json',
+        'User-Agent': payload.userAgent || 'HelmAnalytics/NodeSDK',
+        'X-Forwarded-For': payload.clientIp || ''
+      };
+      if (this.apiKey) {
+          headers['Authorization'] = `Bearer ${this.apiKey}`;
+      }
+
       fetch(`${this.apiUrl}/track/event`, {
         method: 'POST',
         body: JSON.stringify(payload),
-        headers: { 'Content-Type': 'application/json' }
+        headers: headers
       }).catch(err => {});
 
       return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helm-analytics",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Official Node.js SDK for Helm Analytics",
   "main": "index.js",
   "scripts": {