@agent-analytics/core 0.1.0

package/src/handler.js

@@ -0,0 +1,267 @@
+/**
+ * Core analytics handler — platform-agnostic.
+ *
+ * Consumers provide { db, validateWrite, validateRead } to plug in
+ * their own auth and database layer.
+ */
+
+import { TRACKER_JS } from './tracker.js';
+
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, X-API-Key',
+  'Access-Control-Allow-Credentials': 'false',
+};
+
+function json(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json', ...CORS_HEADERS },
+  });
+}
+
+/**
+ * Create an analytics request handler.
+ *
+ * @param {Object} opts
+ * @param {import('./db/adapter.js').DbAdapter} opts.db
+ * @param {(request: Request, body: any) => { valid: boolean, error?: string }} opts.validateWrite — required
+ * @param {(request: Request, url: URL) => { valid: boolean }} opts.validateRead — required
+ * @param {boolean} [opts.useQueue=false]
+ * @param {Object} [opts.healthExtra={}]
+ * @returns {(request: Request) => Promise<{ response: Response, writeOps?: Promise[], queueMessages?: any[] }>}
+ */
+export function createAnalyticsHandler({ db, validateWrite, validateRead, useQueue = false, healthExtra = {} }) {
+  if (!validateWrite) throw new Error('validateWrite is required — provide an auth function for write endpoints');
+  if (!validateRead) throw new Error('validateRead is required — provide an auth function for read endpoints');
+
+  return async function handleRequest(request) {
+    const url = new URL(request.url);
+    const path = url.pathname;
+
+    // CORS preflight
+    if (request.method === 'OPTIONS') {
+      return { response: new Response(null, { headers: CORS_HEADERS }) };
+    }
+
+    try {
+      // POST /track
+      if (path === '/track' && request.method === 'POST') {
+        return await handleTrack(request, db, validateWrite, useQueue);
+      }
+
+      // POST /track/batch
+      if (path === '/track/batch' && request.method === 'POST') {
+        return await handleTrackBatch(request, db, validateWrite, useQueue);
+      }
+
+      // GET /projects
+      if (path === '/projects' && request.method === 'GET') {
+        return await handleListProjects(request, url, db, validateRead);
+      }
+
+      // GET /stats
+      if (path === '/stats' && request.method === 'GET') {
+        return await handleStats(request, url, db, validateRead);
+      }
+
+      // GET /sessions
+      if (path === '/sessions' && request.method === 'GET') {
+        return await handleSessions(request, url, db, validateRead);
+      }
+
+      // GET /events
+      if (path === '/events' && request.method === 'GET') {
+        return await handleEvents(request, url, db, validateRead);
+      }
+
+      // POST /query
+      if (path === '/query' && request.method === 'POST') {
+        return await handleQuery(request, url, db, validateRead);
+      }
+
+      // GET /properties
+      if (path === '/properties' && request.method === 'GET') {
+        return await handleProperties(request, url, db, validateRead);
+      }
+
+      // GET /health
+      if (path === '/health') {
+        return { response: json({ status: 'ok', service: 'agent-analytics', ...healthExtra }) };
+      }
+
+      // GET /tracker.js
+      if (path === '/tracker.js') {
+        return {
+          response: new Response(TRACKER_JS, {
+            headers: { 'Content-Type': 'application/javascript', ...CORS_HEADERS },
+          }),
+        };
+      }
+
+      return { response: json({ error: 'not found' }, 404) };
+    } catch (err) {
+      console.error('Error:', err);
+      return { response: json({ error: 'internal error' }, 500) };
+    }
+  };
+}
+
+// --- Individual handlers ---
+
+async function handleTrack(request, db, validateWrite, useQueue) {
+  const body = await request.json();
+  const { project, event, properties, user_id, session_id, timestamp } = body;
+
+  if (!project || !event) {
+    return { response: json({ error: 'project and event required' }, 400) };
+  }
+
+  const auth = validateWrite(request, body);
+  if (!auth.valid) {
+    return { response: json({ error: auth.error || 'forbidden' }, 403) };
+  }
+
+  const eventData = { project, event, properties, user_id, session_id, timestamp: timestamp || Date.now() };
+
+  if (useQueue) {
+    return { response: json({ ok: true }), queueMessages: [eventData] };
+  }
+
+  const writeOp = db.trackEvent(eventData)
+    .catch(err => console.error('Track write failed:', err));
+
+  return { response: json({ ok: true }), writeOps: [writeOp] };
+}
+
+async function handleTrackBatch(request, db, validateWrite, useQueue) {
+  const body = await request.json();
+  const { events } = body;
+
+  if (!Array.isArray(events) || events.length === 0) {
+    return { response: json({ error: 'events array required' }, 400) };
+  }
+  if (events.length > 100) {
+    return { response: json({ error: 'max 100 events per batch' }, 400) };
+  }
+
+  const auth = validateWrite(request, body);
+  if (!auth.valid) {
+    return { response: json({ error: auth.error || 'forbidden' }, 403) };
+  }
+
+  const normalized = events.map(e => ({
+    project: e.project,
+    event: e.event,
+    properties: e.properties,
+    user_id: e.user_id,
+    session_id: e.session_id,
+    timestamp: e.timestamp || Date.now(),
+  }));
+
+  if (useQueue) {
+    return { response: json({ ok: true, count: events.length }), queueMessages: normalized };
+  }
+
+  const writeOp = db.trackBatch(normalized)
+    .catch(err => console.error('Batch write failed:', err));
+
+  return { response: json({ ok: true, count: events.length }), writeOps: [writeOp] };
+}
+
+async function handleListProjects(request, url, db, validateRead) {
+  const auth = validateRead(request, url);
+  if (!auth.valid) {
+    return { response: json({ error: 'unauthorized - API key required' }, 401) };
+  }
+
+  const projects = await db.listProjects();
+  return { response: json({ projects }) };
+}
+
+async function handleStats(request, url, db, validateRead) {
+  const auth = validateRead(request, url);
+  if (!auth.valid) {
+    return { response: json({ error: 'unauthorized - API key required' }, 401) };
+  }
+
+  const project = url.searchParams.get('project');
+  if (!project) return { response: json({ error: 'project required' }, 400) };
+
+  const since = url.searchParams.get('since') || undefined;
+  const groupBy = url.searchParams.get('groupBy') || 'day';
+  const stats = await db.getStats({ project, since, groupBy });
+
+  return { response: json({ project, ...stats }) };
+}
+
+async function handleEvents(request, url, db, validateRead) {
+  const auth = validateRead(request, url);
+  if (!auth.valid) {
+    return { response: json({ error: 'unauthorized - API key required' }, 401) };
+  }
+
+  const project = url.searchParams.get('project');
+  if (!project) return { response: json({ error: 'project required' }, 400) };
+
+  const event = url.searchParams.get('event');
+  const session_id = url.searchParams.get('session_id');
+  const since = url.searchParams.get('since') || undefined;
+  const limit = Math.min(Math.max(parseInt(url.searchParams.get('limit')) || 100, 1), 1000);
+
+  const events = await db.getEvents({ project, event, session_id, since, limit });
+  return { response: json({ project, events }) };
+}
+
+async function handleQuery(request, url, db, validateRead) {
+  const auth = validateRead(request, url);
+  if (!auth.valid) {
+    return { response: json({ error: 'unauthorized - API key required' }, 401) };
+  }
+
+  const body = await request.json();
+  if (!body.project) return { response: json({ error: 'project required' }, 400) };
+
+  try {
+    const result = await db.query(body);
+    return { response: json({ project: body.project, ...result }) };
+  } catch (err) {
+    console.error('Query error:', err);
+    return { response: json({ error: 'query failed' }, 400) };
+  }
+}
+
+async function handleSessions(request, url, db, validateRead) {
+  const auth = validateRead(request, url);
+  if (!auth.valid) {
+    return { response: json({ error: 'unauthorized - API key required' }, 401) };
+  }
+
+  const project = url.searchParams.get('project');
+  if (!project) return { response: json({ error: 'project required' }, 400) };
+
+  const since = url.searchParams.get('since') || undefined;
+  const limit = Math.min(Math.max(parseInt(url.searchParams.get('limit')) || 100, 1), 1000);
+  const user_id = url.searchParams.get('user_id');
+  const is_bounce_raw = url.searchParams.get('is_bounce');
+  const is_bounce = is_bounce_raw !== null ? Number(is_bounce_raw) : undefined;
+
+  const sessions = await db.getSessions({ project, since, user_id, is_bounce, limit });
+  return { response: json({ project, sessions }) };
+}
+
+async function handleProperties(request, url, db, validateRead) {
+  const auth = validateRead(request, url);
+  if (!auth.valid) {
+    return { response: json({ error: 'unauthorized - API key required' }, 401) };
+  }
+
+  const project = url.searchParams.get('project');
+  if (!project) return { response: json({ error: 'project required' }, 400) };
+
+  const since = url.searchParams.get('since') || undefined;
+  const result = await db.getProperties({ project, since });
+
+  return { response: json({ project, ...result }) };
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { createAnalyticsHandler } from './handler.js'
+export { D1Adapter, validatePropertyKey } from './db/d1.js'
+export { today, daysAgo, parseSince, parseSinceMs } from './db/adapter.js'
+export { TRACKER_JS } from './tracker.js'

package/src/tracker.js

@@ -0,0 +1,198 @@
+/**
+ * Embedded tracker.js - client-side analytics snippet
+ * Served as plain JavaScript from GET /tracker.js
+ *
+ * Auth token is passed in the request body for server-side validation.
+ * No custom headers = no CORS preflight = zero issues.
+ */
+export const TRACKER_JS = `
+(function() {
+  'use strict';
+
+  var script = document.currentScript;
+  var ENDPOINT = script && script.src
+    ? new URL(script.src).origin + '/track'
+    : '/track';
+  var PROJECT = (script && script.dataset.project) || 'default';
+  var TOKEN = (script && script.dataset.token) || null;
+
+  // --- Anon ID ---
+  function getAnonId() {
+    var id = localStorage.getItem('aa_uid');
+    if (!id) {
+      id = 'anon_' + Math.random().toString(36).substr(2, 9) + Date.now().toString(36);
+      localStorage.setItem('aa_uid', id);
+    }
+    return id;
+  }
+  var userId = getAnonId();
+
+  // --- Session ID (30min inactivity timeout) ---
+  var SESSION_TIMEOUT = 30 * 60 * 1000; // 30 minutes
+  function getSessionId() {
+    var now = Date.now();
+    var lastActivity = parseInt(sessionStorage.getItem('aa_last_activity') || '0', 10);
+    var sid = sessionStorage.getItem('aa_sid');
+    if (!sid || (lastActivity && (now - lastActivity) > SESSION_TIMEOUT)) {
+      sid = 'sess_' + Math.random().toString(36).substr(2, 9) + now.toString(36);
+      sessionStorage.setItem('aa_sid', sid);
+    }
+    sessionStorage.setItem('aa_last_activity', String(now));
+    return sid;
+  }
+
+  // --- UTM params ---
+  function getUtm() {
+    var p = new URLSearchParams(location.search);
+    var u = {}, keys = ['utm_source','utm_medium','utm_campaign','utm_content','utm_term'];
+    for (var i = 0; i < keys.length; i++) {
+      var v = p.get(keys[i]);
+      if (v) u[keys[i]] = v;
+    }
+    return u;
+  }
+  var utm = getUtm();
+
+  // --- Browser & OS detection ---
+  function detect(ua) {
+    var b = 'Unknown', bv = '', os = 'Unknown';
+    var m;
+    if (m = ua.match(/(Edge|Edg)\\/([\\d.]+)/)) { b = 'Edge'; bv = m[2]; }
+    else if (m = ua.match(/OPR\\/([\\d.]+)/)) { b = 'Opera'; bv = m[1]; }
+    else if (m = ua.match(/Chrome\\/([\\d.]+)/)) { b = 'Chrome'; bv = m[1]; }
+    else if (m = ua.match(/Safari\\/([\\d.]+)/) ) {
+      if (m = ua.match(/Version\\/([\\d.]+)/)) { b = 'Safari'; bv = m[1]; }
+    }
+    else if (m = ua.match(/Firefox\\/([\\d.]+)/)) { b = 'Firefox'; bv = m[1]; }
+
+    if (/iPhone|iPad|iPod/.test(ua)) os = 'iOS';
+    else if (/Windows/.test(ua)) os = 'Windows';
+    else if (/Android/.test(ua)) os = 'Android';
+    else if (/CrOS/.test(ua)) os = 'ChromeOS';
+    else if (/Mac OS X/.test(ua)) os = 'macOS';
+    else if (/Linux/.test(ua)) os = 'Linux';
+
+    return { browser: b, browser_version: bv.split('.')[0], os: os };
+  }
+  var ua = navigator.userAgent || '';
+  var dev = detect(ua);
+
+  // --- Device type ---
+  function deviceType() {
+    var w = screen.width;
+    if (/Tablet|iPad/i.test(ua) || (w >= 768 && w < 1024 && !/Mobi/i.test(ua))) return 'tablet';
+    if (/Mobi/i.test(ua) || w < 768) return 'mobile';
+    return 'desktop';
+  }
+  dev.device = deviceType();
+
+  // --- Event queue ---
+  var queue = [];
+  var flushTimer = null;
+
+  function send(url, data) {
+    if (navigator.sendBeacon) {
+      if (navigator.sendBeacon(url, new Blob([data], {type: 'text/plain'}))) return;
+    }
+    fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: data,
+      keepalive: true,
+      credentials: 'omit'
+    }).catch(function() {});
+  }
+
+  function flush() {
+    if (!queue.length) return;
+    var batch = queue.splice(0);
+    if (batch.length === 1) {
+      send(ENDPOINT, JSON.stringify(batch[0]));
+    } else {
+      send(ENDPOINT.replace('/track', '/track/batch'), JSON.stringify({ events: batch }));
+    }
+  }
+
+  function scheduleFlush() {
+    if (!flushTimer) flushTimer = setTimeout(function() { flushTimer = null; flush(); }, 5000);
+  }
+
+  // Flush on visibility hidden / beforeunload
+  document.addEventListener('visibilitychange', function() {
+    if (document.visibilityState === 'hidden') flush();
+  });
+  window.addEventListener('beforeunload', flush);
+
+  // --- Common properties ---
+  function baseProps(extra) {
+    var p = {
+      url: location.href,
+      path: location.pathname,
+      hostname: location.hostname,
+      referrer: document.referrer,
+      title: document.title,
+      screen: screen.width + 'x' + screen.height,
+      language: navigator.language || '',
+      browser: dev.browser,
+      browser_version: dev.browser_version,
+      os: dev.os,
+      device: dev.device
+    };
+    // Merge UTM
+    for (var k in utm) p[k] = utm[k];
+    // Merge extra
+    if (extra) for (var k2 in extra) p[k2] = extra[k2];
+    return p;
+  }
+
+  var aa = {
+    track: function(event, properties) {
+      queue.push({
+        project: PROJECT,
+        token: TOKEN,
+        event: event,
+        properties: baseProps(properties),
+        user_id: userId,
+        session_id: getSessionId(),
+        timestamp: Date.now()
+      });
+      scheduleFlush();
+    },
+
+    identify: function(id) {
+      userId = id;
+      localStorage.setItem('aa_uid', id);
+    },
+
+    page: function(name) {
+      this.track('page_view', { page: name || document.title });
+    }
+  };
+
+  // --- SPA route tracking ---
+  var lastPath = location.pathname + location.search;
+  function onRoute() {
+    var cur = location.pathname + location.search;
+    if (cur !== lastPath) {
+      lastPath = cur;
+      utm = getUtm(); // re-parse UTM on navigation
+      aa.page();
+    }
+  }
+  window.addEventListener('popstate', onRoute);
+  // Monkey-patch pushState / replaceState
+  ['pushState', 'replaceState'].forEach(function(fn) {
+    var orig = history[fn];
+    history[fn] = function() {
+      var r = orig.apply(this, arguments);
+      onRoute();
+      return r;
+    };
+  });
+
+  // Auto track initial page view
+  aa.page();
+
+  window.aa = aa;
+})();
+`;

package/src/ulid.js

@@ -0,0 +1,28 @@
+/**
+ * Minimal ULID generator — zero dependencies.
+ * Time-sortable, 26 chars, Crockford Base32.
+ */
+
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+function encodeTime(now, len) {
+  let str = '';
+  for (let i = len; i > 0; i--) {
+    str = ENCODING[now % 32] + str;
+    now = Math.floor(now / 32);
+  }
+  return str;
+}
+
+function encodeRandom(len) {
+  let str = '';
+  const bytes = crypto.getRandomValues(new Uint8Array(len));
+  for (let i = 0; i < len; i++) {
+    str += ENCODING[bytes[i] % 32];
+  }
+  return str;
+}
+
+export function ulid() {
+  return encodeTime(Date.now(), 10) + encodeRandom(16);
+}