helm-analytics 1.0.0 → 1.1.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');

package/index.js

@@ -3,16 +3,47 @@ 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 = {
@@ -27,25 +58,38 @@ 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: ${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)
+      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
     }
   }
 
   // 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,6 +1,6 @@
 {
   "name": "helm-analytics",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Official Node.js Middleware for Helm Analytics",
   "main": "index.js",
   "scripts": {