npm package: @sandesh__07/examshield
Description: Browser-based exam proctoring plugin — silent monitoring, integrity scoring, face detection, and real-time reporting
Author: Sandesh Kandel
Latest version: 1.3.3

# @sandesh__07/examshield

**Silent, high-fidelity exam proctoring SDK for the browser.**

ExamShield is a robust proctoring library designed for easy integration into any Learning Management System (LMS). It monitors candidate behavior in real-time — detecting tab switching, secondary displays, copy-paste attempts, DevTools usage, and webcam anomalies.

## 🚀 Quick Start

Integration is designed to be minimal. You only need two calls:

```javascript
import { ExamShield } from '@sandesh__07/examshield';

// 1. Start proctoring (handles permissions & overlays automatically)
ExamShield.start({
  sessionId:   'exam-session-123',
  apiEndpoint: 'https://api.your-lms.com',
  getToken:    () => userAuthToken,
  onReady:     () => startExam(),      // Called when setup is complete
  onCancelled: () => exitProctoring(), // Called if user denies permissions
  onError:     (msg) => showError(msg)
});

// 2. Stop proctoring (on submit or exit)
ExamShield.stop();
```

## ✨ Key Features

- **Built-in Overlays**: Automatic, themeable UI for screen share, camera access, and fullscreen enforcement.
- **Unified Event Reporting**: All violations and snapshots are sent to a single REST endpoint (`POST /api/proctor/event`).
- **Permission Flow**: Orchestrates browser checks, screen sharing (full-monitor enforcement), and webcam verification.
- **Robust Monitoring**:
  - Tab Switch & Window focus detection
  - Fullscreen Exit enforcement
  - Multiple monitor / Display change detection
  - Keyboard shortcut & Right-click blocking
  - Face detection (TinyFaceDetector + SSD fallback)
  - **Microphone noise detection** (voice / loud / repeated speech — no recording)
- **Automatic Retries**: In-memory event queue with retry logic for zero data loss during network blips.

## ⚙️ Configuration

| Option | Type | Description |
| :--- | :--- | :--- |
| `sessionId` | `string` | **Required**. Unique ID for the exam session. |
| `apiEndpoint` | `string` | **Required**. Base URL for the proctoring API. |
| `getToken` | `function` | **Required**. Function returning the current auth token. |
| `features` | `object` | Toggle specific monitors (webcam, screenShare, **mic**, etc.). |
| `webcam` | `object` | Snapshot interval, quality, and face detection paths. |
| `screenCapture` | `object` | Screen frame capture interval and quality. |
| `mic` | `object` | Microphone monitoring config (see below). |

### Microphone Config (`mic`)

```javascript
ExamShield.start({
  // ...existing config...
  features: {
    mic: true,          // default true — set false to disable entirely
  },
  mic: {
    mandatory:           false, // true = no skip button, retry on denial
    volumeThreshold:     0.5,  // RMS above this → VOICE_DETECTED
    loudThreshold:       0.75, // RMS above this → LOUD_CONVERSATION
    sampleIntervalMs:    1000, // check every 1 s
    repeatedSpeechCount: 3,    // REPEATED_SPEECH after 3 detections in 20 s
  },
});

// To disable mic completely:
// features: { mic: false }  — no overlay, no getUserMedia for audio
```

## 🛠️ Theming

ExamShield UI can be themed using CSS variables:

```css
:root {
  --es-primary: #2563eb;
  --es-bg: #ffffff;
  --es-text: #111827;
  --es-border-radius: 12px;
}
```

## 📜 License

MIT © [sandesh__07](https://www.npmjs.com/~sandesh__07)