web-agent-bridge 1.0.0

package/server/models/adapters/postgresql.js

@@ -0,0 +1,172 @@
+/**
+ * PostgreSQL Adapter for WAB
+ *
+ * Prerequisites: npm install pg
+ * Set DATABASE_URL=postgres://user:pass@host:5432/wab
+ *
+ * This adapter implements the same interface as the SQLite adapter
+ * so it can be used as a drop-in replacement.
+ */
+
+const { Pool } = require('pg');
+const bcrypt = require('bcryptjs');
+const { v4: uuidv4 } = require('uuid');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+// Initialize tables
+async function initDB() {
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS users (
+      id TEXT PRIMARY KEY,
+      email TEXT UNIQUE NOT NULL,
+      password TEXT NOT NULL,
+      name TEXT NOT NULL,
+      company TEXT,
+      created_at TIMESTAMPTZ DEFAULT NOW(),
+      updated_at TIMESTAMPTZ DEFAULT NOW()
+    );
+
+    CREATE TABLE IF NOT EXISTS sites (
+      id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+      domain TEXT NOT NULL,
+      name TEXT NOT NULL,
+      description TEXT,
+      tier TEXT DEFAULT 'free' CHECK(tier IN ('free','starter','pro','enterprise')),
+      license_key TEXT UNIQUE NOT NULL,
+      api_key TEXT UNIQUE,
+      config JSONB DEFAULT '{}',
+      active BOOLEAN DEFAULT TRUE,
+      created_at TIMESTAMPTZ DEFAULT NOW(),
+      updated_at TIMESTAMPTZ DEFAULT NOW()
+    );
+
+    CREATE TABLE IF NOT EXISTS analytics (
+      id SERIAL PRIMARY KEY,
+      site_id TEXT NOT NULL REFERENCES sites(id) ON DELETE CASCADE,
+      action_name TEXT NOT NULL,
+      agent_id TEXT,
+      trigger_type TEXT,
+      success BOOLEAN,
+      metadata JSONB DEFAULT '{}',
+      created_at TIMESTAMPTZ DEFAULT NOW()
+    );
+
+    CREATE TABLE IF NOT EXISTS subscriptions (
+      id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+      site_id TEXT NOT NULL REFERENCES sites(id) ON DELETE CASCADE,
+      tier TEXT NOT NULL CHECK(tier IN ('free','starter','pro','enterprise')),
+      status TEXT DEFAULT 'active' CHECK(status IN ('active','cancelled','expired','trial')),
+      started_at TIMESTAMPTZ DEFAULT NOW(),
+      expires_at TIMESTAMPTZ
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sites_domain ON sites(domain);
+    CREATE INDEX IF NOT EXISTS idx_sites_license ON sites(license_key);
+    CREATE INDEX IF NOT EXISTS idx_analytics_site ON analytics(site_id);
+    CREATE INDEX IF NOT EXISTS idx_analytics_created ON analytics(created_at);
+  `);
+}
+
+initDB().catch(console.error);
+
+function generateLicenseKey() {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  const segments = [];
+  for (let s = 0; s < 4; s++) {
+    let seg = '';
+    for (let i = 0; i < 5; i++) seg += chars[Math.floor(Math.random() * chars.length)];
+    segments.push(seg);
+  }
+  return `WAB-${segments.join('-')}`;
+}
+
+function generateApiKey() {
+  return `wab_${uuidv4().replace(/-/g, '')}`;
+}
+
+// ─── User Operations ──────────────────────────────────────────────────
+async function registerUser({ email, password, name, company }) {
+  const id = uuidv4();
+  const hashed = bcrypt.hashSync(password, 12);
+  await pool.query(
+    'INSERT INTO users (id, email, password, name, company) VALUES ($1, $2, $3, $4, $5)',
+    [id, email, hashed, name, company || null]
+  );
+  return { id, email, name, company };
+}
+
+async function loginUser({ email, password }) {
+  const { rows } = await pool.query('SELECT * FROM users WHERE email = $1', [email]);
+  const user = rows[0];
+  if (!user) return null;
+  if (!bcrypt.compareSync(password, user.password)) return null;
+  return { id: user.id, email: user.email, name: user.name, company: user.company };
+}
+
+// ─── Site Operations ──────────────────────────────────────────────────
+async function addSite({ userId, domain, name, description, tier }) {
+  const id = uuidv4();
+  const licenseKey = generateLicenseKey();
+  const apiKey = generateApiKey();
+  const config = {
+    agentPermissions: { readContent: true, click: true, fillForms: false, scroll: true, navigate: false, apiAccess: false, automatedLogin: false, extractData: false },
+    features: { advancedAnalytics: false, realTimeUpdates: false },
+    restrictions: { allowedSelectors: [], blockedSelectors: ['.private', '[data-private]'], rateLimit: { maxCallsPerMinute: 60 } },
+    logging: { enabled: false, level: 'basic' }
+  };
+  await pool.query(
+    'INSERT INTO sites (id, user_id, domain, name, description, tier, license_key, api_key, config) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)',
+    [id, userId, domain, name, description || '', tier || 'free', licenseKey, apiKey, JSON.stringify(config)]
+  );
+  return { id, domain, name, licenseKey, apiKey, tier: tier || 'free' };
+}
+
+// ─── Analytics ────────────────────────────────────────────────────────
+async function recordAnalytic({ siteId, actionName, agentId, triggerType, success, metadata }) {
+  await pool.query(
+    'INSERT INTO analytics (site_id, action_name, agent_id, trigger_type, success, metadata) VALUES ($1,$2,$3,$4,$5,$6)',
+    [siteId, actionName, agentId || null, triggerType || null, success, JSON.stringify(metadata || {})]
+  );
+}
+
+// ─── License Verification ─────────────────────────────────────────────
+async function verifyLicense(domain, licenseKey) {
+  const { rows } = await pool.query(
+    'SELECT * FROM sites WHERE domain = $1 AND license_key = $2 AND active = TRUE', [domain, licenseKey]
+  );
+  const site = rows[0];
+  if (!site) {
+    const { rows: byKey } = await pool.query('SELECT * FROM sites WHERE license_key = $1 AND active = TRUE', [licenseKey]);
+    if (byKey[0]) return { valid: false, error: 'Domain mismatch', tier: 'free' };
+    return { valid: false, error: 'Invalid license key', tier: 'free' };
+  }
+
+  const tierPermissions = {
+    free: { apiAccess: false, automatedLogin: false, extractData: false, advancedAnalytics: false },
+    starter: { apiAccess: false, automatedLogin: true, extractData: false, advancedAnalytics: true },
+    pro: { apiAccess: true, automatedLogin: true, extractData: true, advancedAnalytics: true },
+    enterprise: { apiAccess: true, automatedLogin: true, extractData: true, advancedAnalytics: true }
+  };
+
+  const config = typeof site.config === 'string' ? JSON.parse(site.config) : site.config;
+  return {
+    valid: true,
+    tier: site.tier,
+    permissions: { ...config.agentPermissions, ...tierPermissions[site.tier] },
+    restrictions: config.restrictions,
+    features: config.features,
+    siteId: site.id
+  };
+}
+
+module.exports = {
+  registerUser,
+  loginUser,
+  addSite,
+  recordAnalytic,
+  verifyLicense,
+  pool
+};

package/server/models/adapters/sqlite.js

@@ -0,0 +1,7 @@
+/**
+ * SQLite Adapter — Default database backend
+ *
+ * Re-exports the existing db.js module as an adapter.
+ */
+const db = require('../db');
+module.exports = db;

package/server/models/db.js

@@ -0,0 +1,205 @@
+const Database = require('better-sqlite3');
+const path = require('path');
+const fs = require('fs');
+const bcrypt = require('bcryptjs');
+const { v4: uuidv4 } = require('uuid');
+
+const isTest = process.env.NODE_ENV === 'test';
+const DATA_DIR = isTest
+  ? path.join(__dirname, '..', '..', 'data-test')
+  : path.join(__dirname, '..', '..', 'data');
+if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR, { recursive: true });
+
+const dbFile = isTest ? 'wab-test.db' : 'wab.db';
+const db = new Database(path.join(DATA_DIR, dbFile));
+
+db.pragma('journal_mode = WAL');
+db.pragma('foreign_keys = ON');
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS users (
+    id TEXT PRIMARY KEY,
+    email TEXT UNIQUE NOT NULL,
+    password TEXT NOT NULL,
+    name TEXT NOT NULL,
+    company TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS sites (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL,
+    domain TEXT NOT NULL,
+    name TEXT NOT NULL,
+    description TEXT,
+    tier TEXT DEFAULT 'free' CHECK(tier IN ('free','starter','pro','enterprise')),
+    license_key TEXT UNIQUE NOT NULL,
+    api_key TEXT UNIQUE,
+    config TEXT DEFAULT '{}',
+    active INTEGER DEFAULT 1,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now')),
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+  );
+
+  CREATE TABLE IF NOT EXISTS analytics (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    site_id TEXT NOT NULL,
+    action_name TEXT NOT NULL,
+    agent_id TEXT,
+    trigger_type TEXT,
+    success INTEGER,
+    metadata TEXT DEFAULT '{}',
+    created_at TEXT DEFAULT (datetime('now')),
+    FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE
+  );
+
+  CREATE TABLE IF NOT EXISTS subscriptions (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL,
+    site_id TEXT NOT NULL,
+    tier TEXT NOT NULL CHECK(tier IN ('free','starter','pro','enterprise')),
+    status TEXT DEFAULT 'active' CHECK(status IN ('active','cancelled','expired','trial')),
+    started_at TEXT DEFAULT (datetime('now')),
+    expires_at TEXT,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+    FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_sites_domain ON sites(domain);
+  CREATE INDEX IF NOT EXISTS idx_sites_license ON sites(license_key);
+  CREATE INDEX IF NOT EXISTS idx_analytics_site ON analytics(site_id);
+  CREATE INDEX IF NOT EXISTS idx_analytics_created ON analytics(created_at);
+`);
+
+function generateLicenseKey() {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  const segments = [];
+  for (let s = 0; s < 4; s++) {
+    let seg = '';
+    for (let i = 0; i < 5; i++) seg += chars[Math.floor(Math.random() * chars.length)];
+    segments.push(seg);
+  }
+  return `WAB-${segments.join('-')}`;
+}
+
+function generateApiKey() {
+  return `wab_${uuidv4().replace(/-/g, '')}`;
+}
+
+// ─── User Operations ──────────────────────────────────────────────────
+const createUser = db.prepare(`
+  INSERT INTO users (id, email, password, name, company) VALUES (?, ?, ?, ?, ?)
+`);
+
+const findUserByEmail = db.prepare(`SELECT * FROM users WHERE email = ?`);
+const findUserById = db.prepare(`SELECT id, email, name, company, created_at FROM users WHERE id = ?`);
+
+function registerUser({ email, password, name, company }) {
+  const id = uuidv4();
+  const hashed = bcrypt.hashSync(password, 12);
+  createUser.run(id, email, hashed, name, company || null);
+  return { id, email, name, company };
+}
+
+function loginUser({ email, password }) {
+  const user = findUserByEmail.get(email);
+  if (!user) return null;
+  if (!bcrypt.compareSync(password, user.password)) return null;
+  return { id: user.id, email: user.email, name: user.name, company: user.company };
+}
+
+// ─── Site Operations ──────────────────────────────────────────────────
+const createSite = db.prepare(`
+  INSERT INTO sites (id, user_id, domain, name, description, tier, license_key, api_key, config)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+`);
+
+const findSitesByUser = db.prepare(`SELECT * FROM sites WHERE user_id = ? ORDER BY created_at DESC`);
+const findSiteById = db.prepare(`SELECT * FROM sites WHERE id = ?`);
+const findSiteByLicense = db.prepare(`SELECT * FROM sites WHERE license_key = ? AND active = 1`);
+const findSiteByDomainAndLicense = db.prepare(`SELECT * FROM sites WHERE domain = ? AND license_key = ? AND active = 1`);
+const updateSiteConfig = db.prepare(`UPDATE sites SET config = ?, updated_at = datetime('now') WHERE id = ? AND user_id = ?`);
+const updateSiteTier = db.prepare(`UPDATE sites SET tier = ?, updated_at = datetime('now') WHERE id = ? AND user_id = ?`);
+const deleteSite = db.prepare(`UPDATE sites SET active = 0, updated_at = datetime('now') WHERE id = ? AND user_id = ?`);
+
+function addSite({ userId, domain, name, description, tier }) {
+  const id = uuidv4();
+  const licenseKey = generateLicenseKey();
+  const apiKey = generateApiKey();
+  const config = JSON.stringify({
+    agentPermissions: { readContent: true, click: true, fillForms: false, scroll: true, navigate: false, apiAccess: false, automatedLogin: false, extractData: false },
+    features: { advancedAnalytics: false, realTimeUpdates: false },
+    restrictions: { allowedSelectors: [], blockedSelectors: ['.private', '[data-private]'], rateLimit: { maxCallsPerMinute: 60 } },
+    logging: { enabled: false, level: 'basic' }
+  });
+  createSite.run(id, userId, domain, name, description || '', tier || 'free', licenseKey, apiKey, config);
+  return { id, domain, name, licenseKey, apiKey, tier: tier || 'free' };
+}
+
+// ─── Analytics ────────────────────────────────────────────────────────
+const insertAnalytic = db.prepare(`
+  INSERT INTO analytics (site_id, action_name, agent_id, trigger_type, success, metadata)
+  VALUES (?, ?, ?, ?, ?, ?)
+`);
+
+const getAnalyticsBySite = db.prepare(`
+  SELECT action_name, trigger_type, COUNT(*) as count, SUM(success) as successes
+  FROM analytics WHERE site_id = ? AND created_at >= ? GROUP BY action_name, trigger_type
+  ORDER BY count DESC
+`);
+
+const getAnalyticsTimeline = db.prepare(`
+  SELECT date(created_at) as day, COUNT(*) as count
+  FROM analytics WHERE site_id = ? AND created_at >= ?
+  GROUP BY day ORDER BY day
+`);
+
+function recordAnalytic({ siteId, actionName, agentId, triggerType, success, metadata }) {
+  insertAnalytic.run(siteId, actionName, agentId || null, triggerType || null, success ? 1 : 0, JSON.stringify(metadata || {}));
+}
+
+// ─── License Verification ─────────────────────────────────────────────
+function verifyLicense(domain, licenseKey) {
+  const site = findSiteByDomainAndLicense.get(domain, licenseKey);
+  if (!site) {
+    const siteByKey = findSiteByLicense.get(licenseKey);
+    if (siteByKey) return { valid: false, error: 'Domain mismatch', tier: 'free' };
+    return { valid: false, error: 'Invalid license key', tier: 'free' };
+  }
+
+  const tierPermissions = {
+    free: { apiAccess: false, automatedLogin: false, extractData: false, advancedAnalytics: false },
+    starter: { apiAccess: false, automatedLogin: true, extractData: false, advancedAnalytics: true },
+    pro: { apiAccess: true, automatedLogin: true, extractData: true, advancedAnalytics: true },
+    enterprise: { apiAccess: true, automatedLogin: true, extractData: true, advancedAnalytics: true }
+  };
+
+  return {
+    valid: true,
+    tier: site.tier,
+    domain: site.domain,
+    allowedPermissions: tierPermissions[site.tier] || tierPermissions.free
+  };
+}
+
+module.exports = {
+  db,
+  registerUser,
+  loginUser,
+  findUserById,
+  addSite,
+  findSitesByUser,
+  findSiteById,
+  findSiteByLicense,
+  updateSiteConfig,
+  updateSiteTier,
+  deleteSite,
+  recordAnalytic,
+  getAnalyticsBySite,
+  getAnalyticsTimeline,
+  verifyLicense,
+  generateLicenseKey,
+  generateApiKey
+};

package/server/routes/api.js

@@ -0,0 +1,121 @@
+const express = require('express');
+const router = express.Router();
+const { authenticateToken } = require('../middleware/auth');
+const {
+  addSite, findSitesByUser, findSiteById,
+  updateSiteConfig, updateSiteTier, deleteSite,
+  getAnalyticsBySite, getAnalyticsTimeline
+} = require('../models/db');
+
+// ─── Sites ──────────────────────────────────────────────────────────────
+
+router.get('/sites', authenticateToken, (req, res) => {
+  const sites = findSitesByUser.all(req.user.id);
+  res.json({
+    sites: sites.filter(s => s.active).map(s => ({
+      ...s,
+      config: JSON.parse(s.config || '{}')
+    }))
+  });
+});
+
+router.post('/sites', authenticateToken, (req, res) => {
+  const { domain, name, description, tier } = req.body;
+
+  if (!domain || !name) {
+    return res.status(400).json({ error: 'Domain and name are required' });
+  }
+
+  try {
+    const site = addSite({ userId: req.user.id, domain, name, description, tier });
+    res.status(201).json({ site });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to create site' });
+  }
+});
+
+router.get('/sites/:id', authenticateToken, (req, res) => {
+  const site = findSiteById.get(req.params.id);
+  if (!site || site.user_id !== req.user.id) {
+    return res.status(404).json({ error: 'Site not found' });
+  }
+  res.json({ site: { ...site, config: JSON.parse(site.config || '{}') } });
+});
+
+router.put('/sites/:id/config', authenticateToken, (req, res) => {
+  const { config } = req.body;
+  if (!config) return res.status(400).json({ error: 'Config is required' });
+
+  try {
+    updateSiteConfig.run(JSON.stringify(config), req.params.id, req.user.id);
+    res.json({ success: true });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to update config' });
+  }
+});
+
+router.put('/sites/:id/tier', authenticateToken, (req, res) => {
+  const { tier } = req.body;
+  if (!['free', 'starter', 'pro', 'enterprise'].includes(tier)) {
+    return res.status(400).json({ error: 'Invalid tier' });
+  }
+
+  try {
+    updateSiteTier.run(tier, req.params.id, req.user.id);
+    res.json({ success: true, tier });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to update tier' });
+  }
+});
+
+router.delete('/sites/:id', authenticateToken, (req, res) => {
+  try {
+    deleteSite.run(req.params.id, req.user.id);
+    res.json({ success: true });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to delete site' });
+  }
+});
+
+// ─── Analytics ──────────────────────────────────────────────────────────
+
+router.get('/sites/:id/analytics', authenticateToken, (req, res) => {
+  const site = findSiteById.get(req.params.id);
+  if (!site || site.user_id !== req.user.id) {
+    return res.status(404).json({ error: 'Site not found' });
+  }
+
+  const days = parseInt(req.query.days) || 30;
+  const since = new Date(Date.now() - days * 86400000).toISOString();
+
+  const summary = getAnalyticsBySite.all(site.id, since);
+  const timeline = getAnalyticsTimeline.all(site.id, since);
+
+  res.json({ summary, timeline, period: `${days} days` });
+});
+
+// ─── Script Generation ──────────────────────────────────────────────────
+
+router.get('/sites/:id/snippet', authenticateToken, (req, res) => {
+  const site = findSiteById.get(req.params.id);
+  if (!site || site.user_id !== req.user.id) {
+    return res.status(404).json({ error: 'Site not found' });
+  }
+
+  const config = JSON.parse(site.config || '{}');
+  const snippet = `<!-- Web Agent Bridge -->
+<script>
+window.AIBridgeConfig = {
+  licenseKey: "${site.license_key}",
+  subscriptionTier: "${site.tier}",
+  agentPermissions: ${JSON.stringify(config.agentPermissions || {}, null, 4)},
+  restrictions: ${JSON.stringify(config.restrictions || {}, null, 4)},
+  logging: ${JSON.stringify(config.logging || {}, null, 4)}
+};
+</script>
+<script src="/script/ai-agent-bridge.js"></script>`;
+
+  res.json({ snippet, licenseKey: site.license_key });
+});
+
+module.exports = router;

package/server/routes/auth.js

@@ -0,0 +1,51 @@
+const express = require('express');
+const router = express.Router();
+const { registerUser, loginUser, findUserById } = require('../models/db');
+const { generateToken, authenticateToken } = require('../middleware/auth');
+
+router.post('/register', (req, res) => {
+  const { email, password, name, company } = req.body;
+
+  if (!email || !password || !name) {
+    return res.status(400).json({ error: 'Email, password, and name are required' });
+  }
+
+  if (password.length < 8) {
+    return res.status(400).json({ error: 'Password must be at least 8 characters' });
+  }
+
+  try {
+    const user = registerUser({ email, password, name, company });
+    const token = generateToken(user);
+    res.status(201).json({ user, token });
+  } catch (err) {
+    if (err.message.includes('UNIQUE constraint')) {
+      return res.status(409).json({ error: 'Email already registered' });
+    }
+    res.status(500).json({ error: 'Registration failed' });
+  }
+});
+
+router.post('/login', (req, res) => {
+  const { email, password } = req.body;
+
+  if (!email || !password) {
+    return res.status(400).json({ error: 'Email and password are required' });
+  }
+
+  const user = loginUser({ email, password });
+  if (!user) {
+    return res.status(401).json({ error: 'Invalid email or password' });
+  }
+
+  const token = generateToken(user);
+  res.json({ user, token });
+});
+
+router.get('/me', authenticateToken, (req, res) => {
+  const user = findUserById.get(req.user.id);
+  if (!user) return res.status(404).json({ error: 'User not found' });
+  res.json({ user });
+});
+
+module.exports = router;

package/server/routes/license.js

@@ -0,0 +1,51 @@
+const express = require('express');
+const router = express.Router();
+const { verifyLicense, recordAnalytic, findSiteByLicense } = require('../models/db');
+const { broadcastAnalytic } = require('../ws');
+
+router.post('/verify', (req, res) => {
+  const { domain, licenseKey } = req.body;
+
+  if (!domain || !licenseKey) {
+    return res.status(400).json({ valid: false, error: 'Domain and licenseKey are required', tier: 'free' });
+  }
+
+  const result = verifyLicense(domain, licenseKey);
+  res.json(result);
+});
+
+router.post('/track', (req, res) => {
+  const { licenseKey, actionName, agentId, triggerType, success, metadata } = req.body;
+
+  if (!licenseKey || !actionName) {
+    return res.status(400).json({ error: 'licenseKey and actionName are required' });
+  }
+
+  try {
+    const site = findSiteByLicense.get(licenseKey);
+    if (!site) return res.status(404).json({ error: 'Site not found' });
+
+    recordAnalytic({
+      siteId: site.id,
+      actionName,
+      agentId,
+      triggerType,
+      success: success !== false,
+      metadata
+    });
+
+    // Broadcast real-time analytics via WebSocket
+    broadcastAnalytic(site.id, {
+      actionName,
+      agentId,
+      triggerType,
+      success: success !== false
+    });
+
+    res.json({ recorded: true });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to record analytics' });
+  }
+});
+
+module.exports = router;

package/server/ws.js

@@ -0,0 +1,81 @@
+const WebSocket = require('ws');
+const jwt = require('jsonwebtoken');
+
+const JWT_SECRET = process.env.JWT_SECRET || 'dev-secret-change-in-production';
+
+// Map of siteId → Set of WebSocket clients
+const siteClients = new Map();
+
+function setupWebSocket(server) {
+  const wss = new WebSocket.Server({ server, path: '/ws/analytics' });
+
+  wss.on('connection', (ws, req) => {
+    let authenticatedSiteId = null;
+
+    ws.isAlive = true;
+    ws.on('pong', () => { ws.isAlive = true; });
+
+    ws.on('message', (data) => {
+      try {
+        const msg = JSON.parse(data);
+
+        if (msg.type === 'auth') {
+          // Authenticate via JWT token and subscribe to a site
+          const decoded = jwt.verify(msg.token, JWT_SECRET);
+          if (decoded && msg.siteId) {
+            authenticatedSiteId = msg.siteId;
+            if (!siteClients.has(msg.siteId)) {
+              siteClients.set(msg.siteId, new Set());
+            }
+            siteClients.get(msg.siteId).add(ws);
+            ws.send(JSON.stringify({ type: 'auth:success', siteId: msg.siteId }));
+          }
+        }
+      } catch (e) {
+        ws.send(JSON.stringify({ type: 'error', message: 'Invalid message or auth failed' }));
+      }
+    });
+
+    ws.on('close', () => {
+      if (authenticatedSiteId && siteClients.has(authenticatedSiteId)) {
+        siteClients.get(authenticatedSiteId).delete(ws);
+        if (siteClients.get(authenticatedSiteId).size === 0) {
+          siteClients.delete(authenticatedSiteId);
+        }
+      }
+    });
+  });
+
+  // Heartbeat to clean up dead connections
+  const interval = setInterval(() => {
+    wss.clients.forEach((ws) => {
+      if (!ws.isAlive) return ws.terminate();
+      ws.isAlive = false;
+      ws.ping();
+    });
+  }, 30000);
+
+  wss.on('close', () => clearInterval(interval));
+
+  return wss;
+}
+
+// Broadcast an analytics event to all clients watching a specific site
+function broadcastAnalytic(siteId, eventData) {
+  const clients = siteClients.get(siteId);
+  if (!clients || clients.size === 0) return;
+
+  const message = JSON.stringify({
+    type: 'analytic',
+    timestamp: new Date().toISOString(),
+    ...eventData
+  });
+
+  clients.forEach((ws) => {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(message);
+    }
+  });
+}
+
+module.exports = { setupWebSocket, broadcastAnalytic };