helm-analytics 1.1.0 → 5.0.0

package/README.md

@@ -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

@@ -48,6 +48,7 @@ class HelmAnalytics {
     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'] || '',
@@ -62,12 +63,12 @@ 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)
+      // Fire and forget
       fetch(`${this.apiUrl}/track`, {
         method: 'POST',
         body: JSON.stringify(payload),
@@ -81,6 +82,33 @@ 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
+      };
+
+      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(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.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"
   }
 }