helm-analytics 1.0.0 → 5.0.0

package/README.md

@@ -17,8 +17,8 @@ const HelmAnalytics = require('helm-analytics');
 const app = express();
 const helm = new HelmAnalytics({ siteId: 'YOUR_SITE_ID' });
 
-// Use as middleware for all routes
-app.use(helm.middleware());
+// Use as middleware (with optional Shield filtering)
+app.use(helm.middleware({ shield: true })); // Set to true to block requests from bad actors
 
 app.get('/', (req, res) => {
   res.send('Hello World');
@@ -36,3 +36,26 @@ 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.
+- **Custom Events**: Track business milestones beyond pageviews.
+- **Session Stitching**: Maintain user journey continuity via headers.

package/index.js

@@ -3,20 +3,52 @@ 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/track';
+    this.apiUrl = (options.apiUrl || 'https://api-sentinel.getmusterup.com').replace(/\/$/, '').replace(/\/track$/, '');
     
     if (!this.siteId) {
       console.warn('HelmAnalytics: No Site ID provided. Tracking will be disabled.');
     }
   }
 
+  // Check if request should be blocked
+  async checkShield(payload) {
+    if (!this.siteId) return { allowed: true };
+
+    try {
+        const checkPayload = {
+            siteId: payload.siteId,
+            ip: payload.clientIp,
+            userAgent: payload.userAgent,
+            url: payload.url
+        };
+
+        const res = await fetch(`${this.apiUrl}/api/shield/decision`, {
+            method: 'POST',
+            body: JSON.stringify(checkPayload),
+            headers: { 'Content-Type': 'application/json' }
+        });
+
+        if (res.ok) {
+            const decision = await res.json();
+            if (decision.action === 'block') {
+                return { allowed: false, reason: decision.reason };
+            }
+        }
+    } catch (err) {
+        // Fail open
+        console.error('Helm Shield Error:', err);
+    }
+    return { allowed: true };
+  }
+
   // Generic track method
-  async track(req, eventType = 'pageview', metadata = {}) {
-    if (!this.siteId) return;
+  async track(req, eventType = 'pageview', metadata = {}, shield = false) {
+    if (!this.siteId) return true;
 
     try {
       const payload = {
         siteId: this.siteId,
+        sessionId: req.headers['x-helm-session-id'] || req.sessionId || '', // Support session stitching
         url: req.originalUrl || req.url,
         userAgent: req.headers['user-agent'] || '',
         referrer: req.headers['referer'] || req.headers['referrer'] || '',
@@ -27,25 +59,65 @@ class HelmAnalytics {
         ...metadata
       };
 
-      // Fire and forget (don't await in middleware usually, but here we define the promise)
-      fetch(this.apiUrl, {
+      // Shield Checking (Blocking)
+      if (shield) {
+        const { allowed, reason } = await this.checkShield(payload);
+        if (!allowed) {
+            console.warn(`[Helm Shield] Blocked IP: ${payload.clientIp} Reason: ${reason}`);
+            return false;
+        }
+      }
+
+      // Fire and forget
+      fetch(`${this.apiUrl}/track`, {
         method: 'POST',
         body: JSON.stringify(payload),
         headers: { 'Content-Type': 'application/json' }
-      }).catch(err => {
-        // Silent error in background
-      });
+      }).catch(err => {});
+
+      return true;
 
     } catch (err) {
-      // Catch synchronous errors
+      return true; // Fail open
+    }
+  }
+
+  // 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
+      };
+
+      fetch(`${this.apiUrl}/track/event`, {
+        method: 'POST',
+        body: JSON.stringify(payload),
+        headers: { 'Content-Type': 'application/json' }
+      }).catch(err => {});
+
+      return true;
+    } catch (err) {
+      return true;
     }
   }
 
   // Express Middleware
-  middleware() {
-    return (req, res, next) => {
-      // don't track static files if easy to detect, but usually backend handles API routes
-      this.track(req);
+  middleware(options = {}) {
+    const shield = options.shield || false;
+    
+    return async (req, res, next) => {
+      const allowed = await this.track(req, 'pageview', {}, shield);
+      if (!allowed) {
+        return res.status(403).send('Forbidden by Helm Aegis');
+      }
       next();
     };
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "helm-analytics",
-  "version": "1.0.0",
-  "description": "Official Node.js Middleware for Helm Analytics",
+  "version": "5.0.0",
+  "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"
   }
 }