booya-sdk 1.0.0

package/PROMPT.md

@@ -0,0 +1,219 @@
+# PROMPT.md — Booya SDK (AI-Optimized Documentation)
+
+> This file is optimized for AI coding assistants (Cursor, Copilot, Lovable, v0, etc.).
+> Paste or reference this file when building apps with the Booya SDK.
+
+## What is Booya SDK?
+
+A JavaScript SDK for real-time audience measurement and emotion detection. It uses a WebAssembly engine to process video from the user's camera, detects faces, tracks engagement, and measures emotional response — all client-side. Events are automatically logged to the Booya backend.
+
+## Install
+
+```bash
+npm install booya-sdk
+```
+
+## Credentials
+
+You need two values from your Booya dashboard:
+- `apiKey` — starts with `bya_`
+- `appId` — your Base44 application ID
+
+## Vanilla JavaScript — Minimal Example
+
+```html
+<div id="camera" style="width:640px;height:480px"></div>
+<button id="start">Start</button>
+<button id="stop">Stop</button>
+
+<script type="module">
+import { BooyaSDK } from 'booya-sdk';
+
+const booya = new BooyaSDK({
+  apiKey: 'bya_YOUR_KEY',
+  appId: 'YOUR_APP_ID',
+  cdnBase: 'https://cdn.booya.ai/wasm/v1', // or omit to load from /public
+});
+
+await booya.init('#camera');
+
+document.getElementById('start').onclick = async () => {
+  const sessionId = await booya.startSession();
+  console.log('Session:', sessionId);
+};
+
+document.getElementById('stop').onclick = async () => {
+  const summary = await booya.endSession();
+  console.log('Summary:', summary);
+};
+
+booya.onMetrics((m) => {
+  // m.emotions = { happy, sad, surprised, angry, neutral, disgust } (0-100)
+  // m.viewerCount = number of people looking at camera
+  // m.totalPersons = total faces detected
+  // m.engagementScore = 0-100
+  // m.dominantEmotion = string
+});
+</script>
+```
+
+## React — useBooya Hook
+
+```jsx
+import { useBooya } from 'booya-sdk/react';
+
+function MeasurementView() {
+  const {
+    containerRef,  // attach to a <div>
+    metrics,       // real-time BooyaMetrics or null
+    isReady,       // true when WASM loaded
+    isRecording,   // true during active session
+    sessionId,     // current session ID or null
+    error,         // last Error or null
+    start,         // () => Promise<sessionId>
+    stop,          // () => Promise<summary>
+  } = useBooya({
+    apiKey: 'bya_YOUR_KEY',
+    appId: 'YOUR_APP_ID',
+    cdnBase: 'https://cdn.booya.ai/wasm/v1',
+  });
+
+  return (
+    <div>
+      <div ref={containerRef} style={{ width: 640, height: 480 }} />
+
+      {!isReady && <p>Loading engine...</p>}
+
+      {metrics && (
+        <div>
+          <p>Emotion: {metrics.dominantEmotion}</p>
+          <p>Viewers: {metrics.viewerCount}</p>
+          <p>Engagement: {metrics.engagementScore}%</p>
+        </div>
+      )}
+
+      <button onClick={isRecording ? stop : start} disabled={!isReady}>
+        {isRecording ? 'End Session' : 'Start Session'}
+      </button>
+
+      {error && <p style={{color:'red'}}>{error.message}</p>}
+    </div>
+  );
+}
+```
+
+## Data-Only API (No Camera / No WASM)
+
+For dashboards, admin panels, or server-side analysis:
+
+```javascript
+import { BooyaSDK } from 'booya-sdk';
+
+// List sessions
+const { data } = await BooyaSDK.api.getSessions('bya_KEY', 'APP_ID', {
+  dashboardId: 'optional-dashboard-id',
+  limit: 20,
+});
+
+// Get single session with events
+const session = await BooyaSDK.api.getSession('bya_KEY', 'APP_ID', 'session-id');
+
+// Get analytics summary
+const analytics = await BooyaSDK.api.getAnalytics('bya_KEY', 'APP_ID', {
+  startDate: '2026-01-01',
+  endDate: '2026-03-01',
+});
+```
+
+## WASM Assets
+
+Three files must be accessible at runtime:
+- `demo.js` (loader, ~200KB)
+- `demo.wasm` (engine, ~5MB)
+- `demo.data` (models, ~30MB)
+
+Pass `cdnBase` to load from a CDN, or place them in your `/public` folder.
+
+## Key Configuration
+
+| Param | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| apiKey | string | yes | — | Starts with `bya_` |
+| appId | string | yes | — | Base44 app ID |
+| cdnBase | string | no | `''` | CDN URL for WASM files |
+| dashboardId | string | no | null | Scope to a dashboard |
+| skin | string | no | `'default'` | `'default'` / `'minimal'` / `'none'` |
+| metricsInterval | number | no | 200 | ms between metric reads |
+| eventInterval | number | no | 2000 | ms between event logs |
+
+## Metrics Shape
+
+```typescript
+interface BooyaMetrics {
+  emotions: {
+    happy: number;      // 0-100
+    sad: number;        // 0-100
+    surprised: number;  // 0-100
+    angry: number;      // 0-100
+    neutral: number;    // 0-100
+    disgust: number;    // 0-100
+  };
+  viewerCount: number;      // actively looking at camera
+  totalPersons: number;     // faces detected
+  engagementScore: number;  // 0-100
+  dominantEmotion: string;  // key with highest score
+}
+```
+
+## Common Patterns
+
+### Show emotion bars
+
+```jsx
+{metrics && Object.entries(metrics.emotions).map(([name, value]) => (
+  <div key={name} style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+    <span style={{ width: 80 }}>{name}</span>
+    <div style={{ flex: 1, background: '#eee', borderRadius: 4, height: 8 }}>
+      <div style={{ width: `${value}%`, background: '#6366f1', borderRadius: 4, height: 8 }} />
+    </div>
+    <span>{Math.round(value)}%</span>
+  </div>
+))}
+```
+
+### Auto-start on mount
+
+```jsx
+const { containerRef, isReady, start } = useBooya({ apiKey, appId });
+
+useEffect(() => {
+  if (isReady) start();
+}, [isReady]);
+```
+
+### Custom overlay (no built-in skin)
+
+```jsx
+const { containerRef, metrics } = useBooya({ apiKey, appId, skin: 'none' });
+
+return (
+  <div style={{ position: 'relative' }}>
+    <div ref={containerRef} style={{ width: '100%', height: 400 }} />
+    {metrics && (
+      <div style={{ position: 'absolute', top: 10, right: 10, background: '#000a', color: '#fff', padding: 8, borderRadius: 8 }}>
+        {metrics.dominantEmotion} — {metrics.viewerCount} viewers
+      </div>
+    )}
+  </div>
+);
+```
+
+## Troubleshooting
+
+| Issue | Fix |
+|---|---|
+| "container not found" | Pass a valid CSS selector or DOM element to `init()` |
+| Camera permission denied | The browser blocked `getUserMedia` — check HTTPS and permissions |
+| WASM fails to load | Verify `cdnBase` URL or that files exist in `/public` |
+| No metrics | Ensure `startSession()` was called and face is visible to camera |
+| 0 viewers but faces detected | "Viewers" = people looking at camera; check gaze angle |

package/README.md

@@ -0,0 +1,130 @@
+# booya-sdk
+
+Real-time audience measurement and emotion detection SDK powered by [Booya AI](https://booya.ai).
+
+Detect faces, track engagement, and measure emotional response in real-time using WebAssembly — all client-side. Events are logged to the Booya backend for analytics and dashboards.
+
+## Install
+
+```bash
+npm install booya-sdk
+```
+
+## Quick Start
+
+```javascript
+import { BooyaSDK } from 'booya-sdk';
+
+const booya = new BooyaSDK({
+  apiKey: 'bya_your_api_key',
+  appId: 'your-base44-app-id',
+});
+
+await booya.init('#camera');
+const sessionId = await booya.startSession();
+
+booya.onMetrics((m) => {
+  console.log(m.emotions);      // { happy, sad, surprised, angry, neutral, disgust }
+  console.log(m.viewerCount);   // people actively looking at camera
+  console.log(m.totalPersons);  // total faces detected
+});
+
+// When done:
+const summary = await booya.endSession();
+```
+
+```html
+<div id="camera" style="width: 640px; height: 480px;"></div>
+```
+
+## React
+
+```jsx
+import { useBooya } from 'booya-sdk/react';
+
+function MeasurementView() {
+  const { containerRef, metrics, isRecording, start, stop, error } = useBooya({
+    apiKey: 'bya_your_api_key',
+    appId: 'your-base44-app-id',
+  });
+
+  return (
+    <div>
+      <div ref={containerRef} style={{ width: 640, height: 480 }} />
+      {metrics && <p>Emotion: {metrics.dominantEmotion}</p>}
+      <button onClick={isRecording ? stop : start}>
+        {isRecording ? 'Stop' : 'Start'}
+      </button>
+    </div>
+  );
+}
+```
+
+## WASM Assets
+
+The SDK requires three WASM engine files at runtime:
+- `demo.js` — loader script
+- `demo.wasm` — WebAssembly binary
+- `demo.data` — model data (~30MB)
+
+**Option A** — Host on your own CDN and pass `cdnBase`:
+
+```javascript
+new BooyaSDK({ apiKey, appId, cdnBase: 'https://cdn.booya.ai/wasm/v1' });
+```
+
+**Option B** — Place files in your public directory (e.g. `/public/demo.js`).
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | *required* | Your Booya API key |
+| `appId` | `string` | *required* | Base44 application ID |
+| `cdnBase` | `string` | `''` | CDN URL for WASM assets |
+| `dashboardId` | `string` | `null` | Scope session to a dashboard |
+| `skin` | `string` | `'default'` | Overlay: `'default'`, `'minimal'`, `'none'` |
+| `metricsInterval` | `number` | `200` | Read metrics every N ms |
+| `eventInterval` | `number` | `2000` | Log events every N ms |
+| `onMetrics` | `function` | `null` | Callback for real-time metrics |
+| `onError` | `function` | `null` | Callback for errors |
+
+## API Methods
+
+### `BooyaSDK`
+
+| Method | Returns | Description |
+|---|---|---|
+| `init(container)` | `Promise<void>` | Load WASM and attach to a container element |
+| `startSession()` | `Promise<string>` | Start camera, create session, return session_id |
+| `endSession()` | `Promise<SessionSummary>` | Stop recording and return session summary |
+| `onMetrics(cb)` | `void` | Register real-time metrics callback |
+| `onError(cb)` | `void` | Register error callback |
+| `getMetrics()` | `BooyaMetrics \| null` | Latest metrics snapshot |
+| `isReady()` | `boolean` | Whether the engine is loaded |
+| `isRecording()` | `boolean` | Whether a session is active |
+| `destroy()` | `void` | Clean up all resources |
+
+### Static API (data-only, no WASM)
+
+```javascript
+const sessions = await BooyaSDK.api.getSessions(apiKey, appId, { dashboardId });
+const session  = await BooyaSDK.api.getSession(apiKey, appId, sessionId);
+const analytics = await BooyaSDK.api.getAnalytics(apiKey, appId, { startDate, endDate });
+```
+
+## Metrics Object
+
+```typescript
+{
+  emotions: { happy, sad, surprised, angry, neutral, disgust }, // 0-100
+  viewerCount: number,     // people actively looking at camera
+  totalPersons: number,    // total faces detected
+  engagementScore: number, // 0-100 aggregate score
+  dominantEmotion: string  // highest-scored emotion
+}
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,101 @@
+export interface BooyaConfig {
+  /** Booya API key (required) */
+  apiKey: string;
+  /** Base44 app ID (required) */
+  appId: string;
+  /** Base44 server URL (default: https://base44.app) */
+  serverUrl?: string;
+  /** CDN base URL for WASM assets (demo.js, demo.wasm, demo.data) */
+  cdnBase?: string;
+  /** Dashboard ID to scope the session */
+  dashboardId?: string;
+  /** Overlay skin: 'default' | 'minimal' | 'none' (default: 'default') */
+  skin?: 'default' | 'minimal' | 'none';
+  /** Custom CSS injected into the container */
+  customCss?: string;
+  /** Callback for real-time metrics */
+  onMetrics?: (metrics: BooyaMetrics) => void;
+  /** Callback for errors */
+  onError?: (error: Error) => void;
+  /** Frequency of metrics reads in ms (default: 200) */
+  metricsInterval?: number;
+  /** Frequency of event logging in ms (default: 2000) */
+  eventInterval?: number;
+}
+
+export interface BooyaMetrics {
+  emotions: {
+    happy: number;
+    sad: number;
+    surprised: number;
+    angry: number;
+    neutral: number;
+    disgust: number;
+  };
+  viewerCount: number;
+  totalPersons: number;
+  engagementScore: number;
+  dominantEmotion: string;
+  [key: string]: unknown;
+}
+
+export interface SessionSummary {
+  session_id: string;
+  duration: number;
+  total_events: number;
+  [key: string]: unknown;
+}
+
+export declare class BooyaSDK {
+  constructor(config: BooyaConfig);
+
+  /** Initialize: load WASM engine and attach to a container */
+  init(container: string | HTMLElement): Promise<void>;
+
+  /** Register a metrics callback */
+  onMetrics(callback: (metrics: BooyaMetrics) => void): void;
+
+  /** Register an error callback */
+  onError(callback: (error: Error) => void): void;
+
+  /** Start camera, create a session, begin processing */
+  startSession(): Promise<string>;
+
+  /** End the session and return a summary */
+  endSession(): Promise<SessionSummary | null>;
+
+  /** Get the latest metrics snapshot */
+  getMetrics(): BooyaMetrics | null;
+
+  /** Check if the SDK is initialized */
+  isReady(): boolean;
+
+  /** Check if a session is active */
+  isRecording(): boolean;
+
+  /** Clean up all resources */
+  destroy(): void;
+
+  static api: {
+    getSessions(
+      apiKey: string,
+      appId: string,
+      options?: { serverUrl?: string; dashboardId?: string; limit?: number; offset?: number }
+    ): Promise<any>;
+
+    getSession(
+      apiKey: string,
+      appId: string,
+      sessionId: string,
+      options?: { serverUrl?: string }
+    ): Promise<any>;
+
+    getAnalytics(
+      apiKey: string,
+      appId: string,
+      options?: { serverUrl?: string; dashboardId?: string; startDate?: string; endDate?: string }
+    ): Promise<any>;
+  };
+}
+
+export default BooyaSDK;

package/index.js

@@ -0,0 +1,460 @@
+/**
+ * Booya SDK v1.0
+ *
+ * Real-time audience measurement and emotion detection.
+ *
+ * @example
+ * import { BooyaSDK } from 'booya-sdk';
+ *
+ * const booya = new BooyaSDK({
+ *   apiKey: 'bya_...',
+ *   appId: 'your-base44-app-id'
+ * });
+ * await booya.init('#camera-container');
+ * const sessionId = await booya.startSession();
+ * booya.onMetrics(m => console.log(m.emotions));
+ * const summary = await booya.endSession();
+ */
+
+const DEFAULT_SERVER = 'https://base44.app';
+const PROCESS_SCALE = 0.5;
+
+export class BooyaSDK {
+  constructor(config = {}) {
+    if (!config.apiKey) throw new Error('BooyaSDK: apiKey is required');
+    if (!config.appId) throw new Error('BooyaSDK: appId is required');
+
+    this._apiKey = config.apiKey;
+    this._appId = config.appId;
+    this._serverUrl = config.serverUrl || DEFAULT_SERVER;
+    this._cdnBase = config.cdnBase || '';
+    this._skin = config.skin || 'default';
+    this._customCss = config.customCss || '';
+    this._onMetrics = config.onMetrics || null;
+    this._onError = config.onError || null;
+    this._metricsInterval = config.metricsInterval || 200;
+    this._eventInterval = config.eventInterval || 2000;
+
+    this._container = null;
+    this._videoEl = null;
+    this._canvasEl = null;
+    this._stream = null;
+    this._engine = null;
+    this._sessionId = null;
+    this._dashboardId = config.dashboardId || null;
+    this._running = false;
+    this._animFrame = null;
+    this._srcMat = null;
+    this._dstMat = null;
+    this._captureCanvas = null;
+    this._captureCtx = null;
+    this._outCtx = null;
+    this._frameSize = { width: 0, height: 0 };
+    this._resultImageData = null;
+    this._lastMetricsTime = 0;
+    this._lastEventTime = 0;
+    this._metricsOverlay = null;
+    this._latestMetrics = null;
+    this._ready = false;
+  }
+
+  /**
+   * Initialize the SDK: load WASM engine and set up the container.
+   * @param {string|HTMLElement} container - CSS selector or DOM element
+   */
+  async init(container) {
+    if (typeof container === 'string') {
+      this._container = document.querySelector(container);
+    } else {
+      this._container = container;
+    }
+
+    if (!this._container) throw new Error('BooyaSDK: container not found');
+
+    this._container.style.position = 'relative';
+    this._container.style.overflow = 'hidden';
+
+    this._videoEl = document.createElement('video');
+    this._videoEl.setAttribute('playsinline', '');
+    this._videoEl.setAttribute('autoplay', '');
+    this._videoEl.setAttribute('muted', '');
+    this._videoEl.muted = true;
+    this._videoEl.style.display = 'none';
+
+    this._canvasEl = document.createElement('canvas');
+    this._canvasEl.style.width = '100%';
+    this._canvasEl.style.height = '100%';
+    this._canvasEl.style.objectFit = 'cover';
+
+    this._container.appendChild(this._videoEl);
+    this._container.appendChild(this._canvasEl);
+
+    if (this._skin !== 'none') {
+      this._createOverlay();
+    }
+
+    if (this._customCss) {
+      const style = document.createElement('style');
+      style.textContent = this._customCss;
+      this._container.appendChild(style);
+    }
+
+    await this._loadWasm();
+    this._ready = true;
+  }
+
+  /** Register a callback for real-time metrics. */
+  onMetrics(callback) {
+    this._onMetrics = callback;
+  }
+
+  /** Register a callback for errors. */
+  onError(callback) {
+    this._onError = callback;
+  }
+
+  /**
+   * Start camera and processing. Creates a session via the API.
+   * @returns {Promise<string>} session_id
+   */
+  async startSession() {
+    if (!this._ready) throw new Error('BooyaSDK: call init() first');
+
+    await this._startCamera();
+    this._initEngine();
+
+    const res = await this._apiCall('apiCreateSession', {
+      dashboard_id: this._dashboardId,
+      metadata: { source: 'sdk', skin: this._skin }
+    });
+
+    this._sessionId = res.data.session_id;
+    this._running = true;
+    this._processFrame();
+
+    return this._sessionId;
+  }
+
+  /**
+   * End the current session.
+   * @returns {Promise<Object>} session summary
+   */
+  async endSession() {
+    this._running = false;
+    if (this._animFrame) {
+      cancelAnimationFrame(this._animFrame);
+      this._animFrame = null;
+    }
+
+    this._stopCamera();
+
+    if (!this._sessionId) return null;
+
+    const res = await this._apiCall('apiEndSession', {
+      session_id: this._sessionId
+    });
+
+    const sessionId = this._sessionId;
+    this._sessionId = null;
+
+    return { session_id: sessionId, ...res.data };
+  }
+
+  /** Get the latest metrics snapshot. */
+  getMetrics() {
+    return this._latestMetrics;
+  }
+
+  /** Check if the SDK is initialized and ready. */
+  isReady() {
+    return this._ready;
+  }
+
+  /** Check if a session is currently active. */
+  isRecording() {
+    return this._running && !!this._sessionId;
+  }
+
+  /** Destroy the SDK and clean up resources. */
+  destroy() {
+    this._running = false;
+    if (this._animFrame) cancelAnimationFrame(this._animFrame);
+    this._stopCamera();
+    if (this._srcMat) { try { this._srcMat.delete(); } catch (_) {} }
+    if (this._dstMat) { try { this._dstMat.delete(); } catch (_) {} }
+    this._engine = null;
+    if (this._container) {
+      this._container.innerHTML = '';
+    }
+  }
+
+  // ── Private ──────────────────────────────────────────────
+
+  async _loadWasm() {
+    return new Promise((resolve, reject) => {
+      const Module = window.Module;
+
+      if (Module && typeof Module.Engine === 'function') {
+        resolve();
+        return;
+      }
+
+      window.Module = {
+        ...(Module || {}),
+        preloadResults: (Module && Module.preloadResults) || {},
+        dataFileDownloads: (Module && Module.dataFileDownloads) || {},
+        expectedDataFileDownloads: (Module && Module.expectedDataFileDownloads) || 0,
+        locateFile: (path) => {
+          const filename = path.split('/').pop();
+          return this._cdnBase ? `${this._cdnBase}/${filename}` : `/${filename}`;
+        },
+        onRuntimeInitialized: () => resolve()
+      };
+
+      const existing = document.querySelector('script[data-booya-wasm="demo-js"]');
+      if (existing) { resolve(); return; }
+
+      const script = document.createElement('script');
+      script.src = this._cdnBase ? `${this._cdnBase}/demo.js` : '/demo.js';
+      script.async = true;
+      script.dataset.booyaWasm = 'demo-js';
+      script.onerror = () => reject(new Error('Failed to load WASM engine'));
+      document.head.appendChild(script);
+    });
+  }
+
+  _initEngine() {
+    if (this._engine) return;
+    const Module = window.Module;
+    this._engine = new Module.Engine();
+    this._engine.init('resources');
+  }
+
+  async _startCamera() {
+    const stream = await navigator.mediaDevices.getUserMedia({
+      video: { facingMode: 'user', width: { ideal: 1280 }, height: { ideal: 720 } },
+      audio: false
+    });
+    this._stream = stream;
+    this._videoEl.srcObject = stream;
+    await new Promise((resolve) => { this._videoEl.onloadedmetadata = resolve; });
+    await this._videoEl.play();
+  }
+
+  _stopCamera() {
+    if (this._stream) {
+      this._stream.getTracks().forEach(t => t.stop());
+      this._stream = null;
+    }
+    if (this._videoEl) {
+      this._videoEl.srcObject = null;
+    }
+  }
+
+  _processFrame() {
+    if (!this._running) return;
+
+    const video = this._videoEl;
+    const canvas = this._canvasEl;
+    const engine = this._engine;
+    const Module = window.Module;
+
+    if (!video || !canvas || !engine || video.readyState < 4) {
+      this._animFrame = requestAnimationFrame(() => this._processFrame());
+      return;
+    }
+
+    const width = video.videoWidth;
+    const height = video.videoHeight;
+    const pw = Math.max(1, Math.floor(width * PROCESS_SCALE));
+    const ph = Math.max(1, Math.floor(height * PROCESS_SCALE));
+
+    if (width === 0 || height === 0) {
+      this._animFrame = requestAnimationFrame(() => this._processFrame());
+      return;
+    }
+
+    if (!this._captureCanvas) {
+      this._captureCanvas = document.createElement('canvas');
+    }
+    if (this._captureCanvas.width !== pw || this._captureCanvas.height !== ph) {
+      this._captureCanvas.width = pw;
+      this._captureCanvas.height = ph;
+      this._captureCtx = this._captureCanvas.getContext('2d', { willReadFrequently: true });
+    }
+
+    const sizeChanged = this._frameSize.width !== pw || this._frameSize.height !== ph;
+    if (!this._srcMat || !this._dstMat || sizeChanged) {
+      if (this._srcMat) { try { this._srcMat.delete(); } catch (_) {} }
+      if (this._dstMat) { try { this._dstMat.delete(); } catch (_) {} }
+      this._srcMat = new Module.Mat(ph, pw);
+      this._dstMat = new Module.Mat(ph, pw);
+      this._frameSize = { width: pw, height: ph };
+      this._resultImageData = null;
+    }
+
+    try {
+      this._captureCtx.drawImage(video, 0, 0, pw, ph);
+      const imageData = this._captureCtx.getImageData(0, 0, pw, ph);
+      this._srcMat.data.set(imageData.data);
+
+      engine.process(this._srcMat, this._dstMat);
+
+      if (!this._outCtx || canvas.width !== pw || canvas.height !== ph) {
+        canvas.width = pw;
+        canvas.height = ph;
+        this._outCtx = canvas.getContext('2d');
+        this._outCtx.imageSmoothingEnabled = true;
+        this._resultImageData = null;
+      }
+
+      if (!this._resultImageData) {
+        this._resultImageData = new ImageData(pw, ph);
+      }
+      this._resultImageData.data.set(this._dstMat.data);
+      this._outCtx.putImageData(this._resultImageData, 0, 0);
+
+      const now = Date.now();
+      if (now - this._lastMetricsTime > this._metricsInterval) {
+        this._lastMetricsTime = now;
+        try {
+          const jsonStr = engine.getMetricsJson();
+          const parsed = JSON.parse(jsonStr);
+          this._latestMetrics = parsed;
+
+          if (this._onMetrics) this._onMetrics(parsed);
+          if (this._metricsOverlay) this._updateOverlay(parsed);
+
+          if (this._sessionId && (now - this._lastEventTime > this._eventInterval)) {
+            this._lastEventTime = now;
+            this._logEvent(parsed);
+          }
+        } catch (_) {}
+      }
+    } catch (err) {
+      if (this._onError) this._onError(err);
+    }
+
+    this._animFrame = requestAnimationFrame(() => this._processFrame());
+  }
+
+  async _logEvent(parsed) {
+    if (!this._sessionId) return;
+    try {
+      await this._apiCall('apiLogEvent', {
+        session_id: this._sessionId,
+        emotions: parsed.emotions || {},
+        viewer_count: parsed.viewerCount || 0,
+        attention_score: parsed.engagementScore || 0,
+        timestamp: new Date().toISOString()
+      });
+    } catch (_) {}
+  }
+
+  _buildFunctionUrl(functionName) {
+    return `${this._serverUrl}/api/apps/${this._appId}/functions/${functionName}`;
+  }
+
+  async _apiCall(functionName, body = {}) {
+    const url = this._buildFunctionUrl(functionName);
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': this._apiKey
+      },
+      body: JSON.stringify(body)
+    });
+    const data = await res.json();
+    if (!res.ok) throw new Error(data.error || 'API request failed');
+    return data;
+  }
+
+  _createOverlay() {
+    this._metricsOverlay = document.createElement('div');
+    this._metricsOverlay.className = 'booya-metrics-overlay';
+
+    const baseStyles = `
+      position: absolute; bottom: 16px; left: 16px;
+      padding: 12px 16px; border-radius: 12px;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      font-size: 13px; line-height: 1.5; pointer-events: none; z-index: 10;
+    `;
+
+    if (this._skin === 'default') {
+      this._metricsOverlay.style.cssText = baseStyles +
+        'background: rgba(0,0,0,0.75); color: #fff; backdrop-filter: blur(10px);';
+    } else if (this._skin === 'minimal') {
+      this._metricsOverlay.style.cssText = baseStyles +
+        'background: transparent; color: #fff; text-shadow: 0 1px 3px rgba(0,0,0,0.8);';
+    }
+
+    this._metricsOverlay.innerHTML = '<div class="booya-metrics-content">Initializing...</div>';
+    this._container.appendChild(this._metricsOverlay);
+  }
+
+  _updateOverlay(metrics) {
+    if (!this._metricsOverlay) return;
+
+    let dominant = 'neutral';
+    let maxVal = 0;
+    if (metrics.emotions) {
+      for (const [k, v] of Object.entries(metrics.emotions)) {
+        if (v > maxVal) { maxVal = v; dominant = k; }
+      }
+    }
+
+    const icons = {
+      happy: '\u{1F60A}', surprised: '\u{1F632}', angry: '\u{1F621}',
+      sad: '\u{1F622}', disgust: '\u{1F922}', neutral: '\u{1F610}'
+    };
+
+    const content = this._metricsOverlay.querySelector('.booya-metrics-content') || this._metricsOverlay;
+    content.innerHTML = `
+      <div style="font-weight:600;margin-bottom:4px">${icons[dominant] || ''} ${dominant}</div>
+      <div>Viewers: ${metrics.viewerCount || 0}</div>
+      <div>Engagement: ${Math.round(metrics.engagementScore || 0)}%</div>
+    `;
+  }
+}
+
+/** Static API helpers — data-only access, no WASM needed. */
+BooyaSDK.api = {
+  _buildUrl(appId, fn, serverUrl) {
+    return `${serverUrl || DEFAULT_SERVER}/api/apps/${appId}/functions/${fn}`;
+  },
+
+  async getSessions(apiKey, appId, options = {}) {
+    const { serverUrl, dashboardId, limit, offset } = options;
+    const params = new URLSearchParams();
+    if (dashboardId) params.set('dashboard_id', dashboardId);
+    if (limit) params.set('limit', limit);
+    if (offset) params.set('offset', offset);
+    const url = this._buildUrl(appId, 'apiGetSessions', serverUrl);
+    const res = await fetch(`${url}?${params}`, { headers: { 'X-API-Key': apiKey } });
+    return res.json();
+  },
+
+  async getSession(apiKey, appId, sessionId, options = {}) {
+    const url = this._buildUrl(appId, 'apiGetSession', options.serverUrl);
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
+      body: JSON.stringify({ session_id: sessionId })
+    });
+    return res.json();
+  },
+
+  async getAnalytics(apiKey, appId, options = {}) {
+    const { serverUrl, dashboardId, startDate, endDate } = options;
+    const params = new URLSearchParams();
+    if (dashboardId) params.set('dashboard_id', dashboardId);
+    if (startDate) params.set('start_date', startDate);
+    if (endDate) params.set('end_date', endDate);
+    const url = this._buildUrl(appId, 'apiGetAnalytics', serverUrl);
+    const res = await fetch(`${url}?${params}`, { headers: { 'X-API-Key': apiKey } });
+    return res.json();
+  }
+};
+
+export default BooyaSDK;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "booya-sdk",
+  "version": "1.0.0",
+  "description": "Real-time audience measurement and emotion detection SDK powered by Booya AI",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    },
+    "./react": {
+      "import": "./react.js",
+      "types": "./react.d.ts"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "react.js",
+    "react.d.ts",
+    "PROMPT.md",
+    "README.md"
+  ],
+  "keywords": [
+    "booya",
+    "emotion-detection",
+    "facial-recognition",
+    "audience-measurement",
+    "engagement-analytics",
+    "wasm",
+    "real-time",
+    "ai"
+  ],
+  "author": "Booya AI",
+  "license": "MIT",
+  "homepage": "https://booya.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/booya-ai/booya-sdk"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/react.d.ts

@@ -0,0 +1,45 @@
+import { RefObject } from 'react';
+import { BooyaSDK, BooyaMetrics, SessionSummary } from './index';
+
+export interface UseBooyaConfig {
+  /** Booya API key (required) */
+  apiKey: string;
+  /** Base44 app ID (required) */
+  appId: string;
+  /** CDN base URL for WASM assets */
+  cdnBase?: string;
+  /** Dashboard ID to scope the session */
+  dashboardId?: string;
+  /** Overlay skin: 'default' | 'minimal' | 'none' */
+  skin?: 'default' | 'minimal' | 'none';
+  /** Frequency of metrics reads in ms (default: 200) */
+  metricsInterval?: number;
+  /** Frequency of event logging in ms (default: 2000) */
+  eventInterval?: number;
+  /** Automatically initialize on mount (default: true) */
+  autoInit?: boolean;
+}
+
+export interface UseBooyaResult {
+  /** Attach this ref to the container div */
+  containerRef: RefObject<HTMLDivElement>;
+  /** Latest real-time metrics (null until first frame) */
+  metrics: BooyaMetrics | null;
+  /** true when WASM engine is loaded and ready */
+  isReady: boolean;
+  /** true when a session is active */
+  isRecording: boolean;
+  /** Current session ID, or null */
+  sessionId: string | null;
+  /** Last error, or null */
+  error: Error | null;
+  /** Start a new session */
+  start(): Promise<string>;
+  /** End the current session */
+  stop(): Promise<SessionSummary | null>;
+  /** Direct access to the underlying SDK instance */
+  sdk: BooyaSDK | null;
+}
+
+export declare function useBooya(config: UseBooyaConfig): UseBooyaResult;
+export default useBooya;

package/react.js

@@ -0,0 +1,138 @@
+/**
+ * Booya SDK React Hook
+ *
+ * @example
+ * import { useBooya } from 'booya-sdk/react';
+ *
+ * function MeasurementView() {
+ *   const { containerRef, metrics, isRecording, start, stop, error } = useBooya({
+ *     apiKey: 'bya_...',
+ *     appId: 'your-app-id'
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <div ref={containerRef} style={{ width: 640, height: 480 }} />
+ *       {metrics && <p>Dominant: {metrics.dominantEmotion}</p>}
+ *       <button onClick={isRecording ? stop : start}>
+ *         {isRecording ? 'Stop' : 'Start'}
+ *       </button>
+ *       {error && <p>Error: {error.message}</p>}
+ *     </div>
+ *   );
+ * }
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { BooyaSDK } from './index.js';
+
+/**
+ * @param {Object} config
+ * @param {string} config.apiKey - Booya API key
+ * @param {string} config.appId - Base44 app ID
+ * @param {string} [config.cdnBase] - CDN URL for WASM assets
+ * @param {string} [config.dashboardId] - Scope to a dashboard
+ * @param {string} [config.skin='default'] - 'default' | 'minimal' | 'none'
+ * @param {number} [config.metricsInterval=200] - How often to read metrics (ms)
+ * @param {number} [config.eventInterval=2000] - How often to log events (ms)
+ * @param {boolean} [config.autoInit=true] - Initialize on mount
+ */
+export function useBooya(config) {
+  const {
+    apiKey,
+    appId,
+    cdnBase,
+    dashboardId,
+    skin,
+    metricsInterval,
+    eventInterval,
+    autoInit = true,
+  } = config;
+
+  const containerRef = useRef(null);
+  const sdkRef = useRef(null);
+  const mountedRef = useRef(true);
+
+  const [isReady, setIsReady] = useState(false);
+  const [isRecording, setIsRecording] = useState(false);
+  const [metrics, setMetrics] = useState(null);
+  const [sessionId, setSessionId] = useState(null);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => { mountedRef.current = false; };
+  }, []);
+
+  useEffect(() => {
+    if (!autoInit || !containerRef.current || sdkRef.current) return;
+
+    const sdk = new BooyaSDK({
+      apiKey,
+      appId,
+      cdnBase,
+      dashboardId,
+      skin,
+      metricsInterval,
+      eventInterval,
+      onMetrics: (m) => { if (mountedRef.current) setMetrics(m); },
+      onError: (e) => { if (mountedRef.current) setError(e); },
+    });
+
+    sdkRef.current = sdk;
+
+    sdk.init(containerRef.current)
+      .then(() => { if (mountedRef.current) setIsReady(true); })
+      .catch((e) => { if (mountedRef.current) setError(e); });
+
+    return () => {
+      sdk.destroy();
+      sdkRef.current = null;
+    };
+  }, [apiKey, appId, cdnBase, dashboardId, skin, metricsInterval, eventInterval, autoInit]);
+
+  const start = useCallback(async () => {
+    if (!sdkRef.current) return;
+    setError(null);
+    try {
+      const sid = await sdkRef.current.startSession();
+      if (mountedRef.current) {
+        setSessionId(sid);
+        setIsRecording(true);
+      }
+      return sid;
+    } catch (e) {
+      if (mountedRef.current) setError(e);
+      throw e;
+    }
+  }, []);
+
+  const stop = useCallback(async () => {
+    if (!sdkRef.current) return;
+    try {
+      const summary = await sdkRef.current.endSession();
+      if (mountedRef.current) {
+        setIsRecording(false);
+        setSessionId(null);
+      }
+      return summary;
+    } catch (e) {
+      if (mountedRef.current) setError(e);
+      throw e;
+    }
+  }, []);
+
+  return {
+    containerRef,
+    metrics,
+    isReady,
+    isRecording,
+    sessionId,
+    error,
+    start,
+    stop,
+    sdk: sdkRef.current,
+  };
+}
+
+export default useBooya;