@toffee-at/sdk 0.1.0

package/src/transport/batch.ts

@@ -0,0 +1,119 @@
+const BATCH_INTERVAL_MS = 5000;
+const BATCH_MAX_SIZE = 20;
+
+export interface EventBatch {
+  siteId: string;
+  sessionId: string;
+  events: unknown[];
+  metadata?: Record<string, string>;
+  timestamp: number;
+}
+
+export class BatchQueue {
+  private queue: unknown[] = [];
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private endpoint: string;
+  private siteId: string;
+  private sessionId: string;
+  private apiKey: string;
+  private metadata?: Record<string, string>;
+  private onClassification?: (classifications: Record<string, { classification: string; probabilities: { human: number; bot: number; agent: number } }>) => void;
+
+  constructor(opts: {
+    endpoint: string;
+    siteId: string;
+    sessionId: string;
+    apiKey: string;
+    onClassification?: (classifications: Record<string, { classification: string; probabilities: { human: number; bot: number; agent: number } }>) => void;
+  }) {
+    this.endpoint = opts.endpoint;
+    this.siteId = opts.siteId;
+    this.sessionId = opts.sessionId;
+    this.apiKey = opts.apiKey;
+    this.onClassification = opts.onClassification;
+  }
+
+  start() {
+    this.timer = setInterval(() => this.flush(), BATCH_INTERVAL_MS);
+  }
+
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  setMetadata(metadata: Record<string, string>) {
+    this.metadata = metadata;
+  }
+
+  push(event: unknown) {
+    this.queue.push(event);
+    if (this.queue.length >= BATCH_MAX_SIZE) {
+      this.flush();
+    }
+  }
+
+  flush() {
+    if (this.queue.length === 0) return;
+
+    const batch: EventBatch = {
+      siteId: this.siteId,
+      sessionId: this.sessionId,
+      events: this.queue.splice(0),
+      metadata: this.metadata,
+      timestamp: Date.now(),
+    };
+
+    const body = JSON.stringify(batch);
+    this.send(body);
+  }
+
+  flushBeacon() {
+    if (this.queue.length === 0) return;
+
+    const batch: EventBatch = {
+      siteId: this.siteId,
+      sessionId: this.sessionId,
+      events: this.queue.splice(0),
+      metadata: this.metadata,
+      timestamp: Date.now(),
+    };
+
+    const body = JSON.stringify(batch);
+    // sendBeacon doesn't support custom headers, so append apiKey as query param
+    const url = `${this.endpoint}?apiKey=${encodeURIComponent(this.apiKey)}`;
+    navigator.sendBeacon(url, body);
+  }
+
+  private send(body: string) {
+    try {
+      fetch(this.endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Api-Key': this.apiKey,
+        },
+        body,
+        keepalive: true,
+      })
+        .then((resp) => {
+          if (resp.ok && this.onClassification) {
+            return resp.json();
+          }
+          return null;
+        })
+        .then((data) => {
+          if (data?.classifications && this.onClassification) {
+            this.onClassification(data.classifications);
+          }
+        })
+        .catch(() => {
+          // Network error — SDK continues with heuristic fallback
+        });
+    } catch {
+      // silently drop
+    }
+  }
+}

package/src/transport/index.ts

@@ -0,0 +1,60 @@
+import { BatchQueue } from './batch';
+
+export function createTransport(opts: {
+  endpoint: string;
+  siteId: string;
+  sessionId: string;
+  apiKey: string;
+  onClassification?: (classifications: Record<string, { classification: string; probabilities: { human: number; bot: number; agent: number } }>) => void;
+}) {
+  const batch = new BatchQueue(opts);
+  batch.start();
+
+  let sessionStart = Date.now();
+  let pageCount = 0;
+  let interactionCount = 0;
+
+  const onVisibilityChange = () => {
+    if (document.visibilityState === 'hidden') {
+      emitSessionEnd();
+      batch.flushBeacon();
+    }
+  };
+
+  const onPageHide = () => {
+    emitSessionEnd();
+    batch.flushBeacon();
+  };
+
+  function emitSessionEnd() {
+    batch.push({
+      type: 'session_end',
+      timestamp: Date.now(),
+      url: location.href,
+      duration: Date.now() - sessionStart,
+      pageCount,
+      interactionCount,
+    });
+  }
+
+  document.addEventListener('visibilitychange', onVisibilityChange);
+  window.addEventListener('pagehide', onPageHide);
+
+  return {
+    push: (event: unknown) => {
+      const e = event as { type?: string };
+      if (e.type === 'pageview') pageCount++;
+      if (e.type === 'interaction') interactionCount++;
+      batch.push(event);
+    },
+    setMetadata: (metadata: Record<string, string>) => batch.setMetadata(metadata),
+    flush: () => batch.flush(),
+    destroy: () => {
+      batch.stop();
+      emitSessionEnd();
+      batch.flush();
+      document.removeEventListener('visibilitychange', onVisibilityChange);
+      window.removeEventListener('pagehide', onPageHide);
+    },
+  };
+}

package/tests/features.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import { extractModelFeatures } from '../src/detect/features';
+
+describe('extractModelFeatures', () => {
+  it('returns zeros for empty state', () => {
+    const result = extractModelFeatures({
+      mousePoints: [],
+      clicks: [],
+      clickDurations: [],
+      scrollTimestamps: [],
+      keyTimings: [],
+      allEventTimestamps: [],
+    });
+    expect(result.action_burst_ratio).toBe(0);
+    expect(result.click_duration_std).toBe(0);
+    expect(result.inter_event_entropy).toBe(0);
+    expect(result.mouse_teleportation).toBe(0);
+  });
+
+  it('detects mouse teleportation (jumps > 100px)', () => {
+    const result = extractModelFeatures({
+      mousePoints: [
+        { x: 0, y: 0, t: 0 },
+        { x: 200, y: 0, t: 100 },
+        { x: 210, y: 0, t: 200 },
+        { x: 500, y: 0, t: 300 },
+      ],
+      clicks: [],
+      clickDurations: [],
+      scrollTimestamps: [],
+      keyTimings: [],
+      allEventTimestamps: [],
+    });
+    expect(result.mouse_teleportation).toBe(2);
+  });
+
+  it('computes action burst ratio', () => {
+    const result = extractModelFeatures({
+      mousePoints: [],
+      clicks: [{ x: 0, y: 0, t: 100 }, { x: 0, y: 0, t: 200 }],
+      clickDurations: [],
+      scrollTimestamps: [300],
+      keyTimings: [400],
+      allEventTimestamps: [],
+    });
+    expect(result.action_burst_ratio).toBe(1.0);
+  });
+
+  it('computes click duration std', () => {
+    const result = extractModelFeatures({
+      mousePoints: [],
+      clicks: [],
+      clickDurations: [100, 100, 100],
+      scrollTimestamps: [],
+      keyTimings: [],
+      allEventTimestamps: [],
+    });
+    expect(result.click_duration_std).toBe(0);
+
+    const result2 = extractModelFeatures({
+      mousePoints: [],
+      clicks: [],
+      clickDurations: [50, 150],
+      scrollTimestamps: [],
+      keyTimings: [],
+      allEventTimestamps: [],
+    });
+    expect(result2.click_duration_std).toBe(50);
+  });
+
+  it('computes inter-event entropy > 0 for varied gaps', () => {
+    const result = extractModelFeatures({
+      mousePoints: [],
+      clicks: [],
+      clickDurations: [],
+      scrollTimestamps: [],
+      keyTimings: [],
+      allEventTimestamps: [0, 10, 50, 200, 201, 500, 2000, 2001, 5000],
+    });
+    expect(result.inter_event_entropy).toBeGreaterThan(0);
+  });
+
+  it('returns entropy 0 for uniform gaps', () => {
+    const result = extractModelFeatures({
+      mousePoints: [],
+      clicks: [],
+      clickDurations: [],
+      scrollTimestamps: [],
+      keyTimings: [],
+      allEventTimestamps: [0, 100, 200, 300, 400],
+    });
+    expect(result.inter_event_entropy).toBe(0);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs', 'iife'],
+  globalName: 'AgentRadar',
+  dts: true,
+  clean: true,
+  minify: true,
+});