events: add recordEvent helper

src/events.js

@@ -0,0 +1,33 @@
+// ─────────────────────────────────────────────────────────────
+// src/events.js — landmark engagement event recorder.
+//
+// One function: recordEvent(req, {type, email, sessionId, meta}).
+// Pulls the UA off the request, parses to {device_type, os, browser},
+// and inserts a row into the `events` table (see src/db.js).
+//
+// Synchronous — better-sqlite3 is sync and the volume on this site
+// is too low to justify any queueing or try/catch. If a future event
+// becomes hot-path or recording becomes a failure mode, revisit.
+//
+// `sessionId` is passed in explicitly (rather than read from
+// req.cookies) because the `login` event happens before req.cookies
+// reflects the freshly-issued session cookie.
+// ─────────────────────────────────────────────────────────────
+import { q } from './db.js';
+import { parseUA } from './ua.js';
+
+export function recordEvent(req, { type, email, sessionId, meta = null }) {
+  const ua = req.headers['user-agent'] || '';
+  const { device_type, os, browser } = parseUA(ua);
+  q.recordEvent.run(
+    type,
+    email,
+    Date.now(),
+    sessionId || null,
+    device_type,
+    os,
+    browser,
+    ua || null,
+    meta ? JSON.stringify(meta) : null
+  );
+}