helm-analytics 1.0.0

package/README.md

@@ -0,0 +1,38 @@
+# Helm Analytics Node.js SDK
+
+Official Node.js middleware for [Helm Analytics](https://helm-analytics.com).
+
+## Installation
+
+```bash
+npm install helm-analytics
+```
+
+## Quick Start (Express)
+
+```javascript
+const express = require('express');
+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());
+
+app.get('/', (req, res) => {
+  res.send('Hello World');
+});
+
+app.listen(3000);
+```
+
+## Manual Tracking
+
+```javascript
+app.post('/purchase', (req, res) => {
+  // ... process purchase ...
+  helm.track(req, 'conversion', { revenue: 50.00 });
+  res.json({ success: true });
+});
+```

package/index.js

@@ -0,0 +1,54 @@
+const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));
+
+class HelmAnalytics {
+  constructor(options = {}) {
+    this.siteId = options.siteId || process.env.HELM_SITE_ID;
+    this.apiUrl = options.apiUrl || 'https://api-sentinel.getmusterup.com/track';
+    
+    if (!this.siteId) {
+      console.warn('HelmAnalytics: No Site ID provided. Tracking will be disabled.');
+    }
+  }
+
+  // Generic track method
+  async track(req, eventType = 'pageview', metadata = {}) {
+    if (!this.siteId) return;
+
+    try {
+      const payload = {
+        siteId: this.siteId,
+        url: req.originalUrl || req.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,
+        isServerSide: true,
+        ...metadata
+      };
+
+      // Fire and forget (don't await in middleware usually, but here we define the promise)
+      fetch(this.apiUrl, {
+        method: 'POST',
+        body: JSON.stringify(payload),
+        headers: { 'Content-Type': 'application/json' }
+      }).catch(err => {
+        // Silent error in background
+      });
+
+    } catch (err) {
+      // Catch synchronous errors
+    }
+  }
+
+  // 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);
+      next();
+    };
+  }
+}
+
+module.exports = HelmAnalytics;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "helm-analytics",
+  "version": "1.0.0",
+  "description": "Official Node.js Middleware for Helm Analytics",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "analytics",
+    "helm",
+    "middleware",
+    "express"
+  ],
+  "author": "Helm Analytics",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "node-fetch": "^3.3.2"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Sentinel-Analytics/sentinel-mvp/tree/master/sdk/node"
+  }
+}