interview-widget 1.0.12 → 1.0.14

package/README.md

@@ -1,306 +1,306 @@
-# Interview Widget
-
-A modern React interview experience widget with built‑in timer flow, STT (speech‑to‑text), and TTS (text‑to‑speech). It can be embedded via NPM or a CDN and configured through a single provider.
-
-## Features
-
-- **Video capture** with camera integration
-- **Responsive design** with mobile support
-- **TypeScript support** with full type definitions
-- **CDN-ready** for easy integration into any website
-- **Q&A structured interview flow**
-- **Advanced Timer System** with phase management
-- **Text-to-Speech integration** for transcribing
-- **Speech-to-Text integration** for voice answers
-- **Automatic phase transitions** (thinking → answering → editing)
-- **Time validation** before starting new questions
-
-## Quick Start
-
-### 1) Environment Setup
-
-The Interview Widget uses encryption for session storage integrity. Set up your encryption secret based on your environment:
-
-#### Vite React
-
-```env
-# .env
-VITE_IW_SECRET=your-secure-encryption-seed-here
-```
-
-#### Next.js
-
-```env
-# .env.local
-NEXT_PUBLIC_IW_SECRET=your-secure-encryption-seed-here
-```
-
-#### Vanilla JS / Custom Framework
-
-```html
-<script>
-  // Define the secret before loading your widget
-  window.__IW_SECRET__ = "your-secure-encryption-seed-here";
-</script>
-```
-
-### 2) Install (React apps)
-
-```bash
-npm install interview-widget
-```
-
-Minimal usage:
-
-```tsx
-import React from "react";
-import { InterviewWidget, InterviewWidgetProvider } from "interview-widget";
-import "interview-widget/style.css";
-
-export default function App() {
-  return (
-    <InterviewWidgetProvider
-      config={{
-        api: {
-          baseUrl: "/api" // Your backend endpoint
-          authToken: getTokenFromYourAuthSystem(), // Get from secure backend
-        },
-        interview: {
-          stt: {
-            provider: "groq",
-            model: "whisper-large-v3-turbo",
-            language: "en",
-          },
-          tts: { provider: "piper" },
-          timers: {
-            thinkingDuration: 30,
-            answeringDuration: 120,
-            editingDuration: 30,
-          },
-        },
-      }}
-    >
-      <InterviewWidget
-        interviewId="your_interview_id"
-        title="Interview for JS developer"
-        className="iw-rounded-none iw-shadow-none"
-        onInterviewEnd={() => {
-          console.log("🎉🎉 Interview ended 🎉🎉");
-        }}
-      />
-    </InterviewWidgetProvider>
-  );
-}
-```
-
-```html
-<!-- React 18 UMD -->
-<script
-  crossorigin
-  src="https://unpkg.com/react@18/umd/react.production.min.js"
-></script>
-<script
-  crossorigin
-  src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"
-></script>
-
-<!-- Styles + Widget UMD -->
-<link
-  rel="stylesheet"
-  href="https://unpkg.com/interview-widget@latest/dist/widget.css"
-/>
-<script src="https://unpkg.com/interview-widget@latest/dist/widget.umd.js"></script>
-
-<div id="interview-widget-container"></div>
-<script>
-  document.addEventListener("DOMContentLoaded", function () {
-    const { InterviewWidget, InterviewWidgetProvider } = window.InterviewWidget;
-
-    const app = React.createElement(
-      InterviewWidgetProvider,
-      {
-        config: {
-          api: { baseUrl: "/api" },
-          interview: {
-            timers: {
-              thinkingDuration: 30,
-              answeringDuration: 120,
-              editingDuration: 30,
-            },
-            stt: {
-              provider: "groq",
-              model: "whisper-large-v3-turbo",
-              language: "en",
-            },
-            tts: { provider: "piper" },
-          },
-        },
-      },
-      React.createElement(InterviewWidget, { interviewId="your_interview_id", title: "Developer Interview",  onInterviewEnd={() => {}} }
-    );
-
-    ReactDOM.render(app, document.getElementById("interview-widget-container"));
-  });
-</script>
-```
-
-## Public API
-
-### <InterviewWidget />
-
-### InterviewWidget Props
-
-| Prop                    | Type         | Default       | Description                                                                 |
-| ----------------------- | ------------ | ------------- | --------------------------------------------------------------------------- |
-| `interviewId`           | `string`     | Required      | Unique interview identifier used for backend API calls                      |
-| `title`                 | `string`     | `"Interview"` | Title displayed in the interview header                                     |
-| `onInterviewEnd`        | `() => void` | `undefined`   | Called when the interview completes or the user exits                       |
-| `onInterviewDisqualify` | `() => void` | `undefined`   | Called when the interview is disqualified (e.g., due to cheating detection) |
-| `className`             | `string`     | `""`          | Additional CSS classes applied to the outer widget container                |
-
-### <InterviewWidgetProvider />
-
-Wrap your app (or the widget) to provide configuration. See full config reference below.
-
-```tsx
-<InterviewWidgetProvider config={{ api: { baseUrl: "/api" } }}>
-  <InterviewWidget />
-</InterviewWidgetProvider>
-```
-
-## Configuration reference (Provider)
-
-Pass this object to `InterviewWidgetProvider` via the `config` prop. Tables list all keys, types, and defaults.
-
-### Top-level
-
-| Prop      | Type     | Default                 | Description                                    |
-| --------- | -------- | ----------------------- | ---------------------------------------------- |
-| api       | `object` | [see below](#api)       | Backend/API configuration                      |
-| ui        | `object` | [see below](#ui)        | UI customization tokens                        |
-| interview | `object` | [see below](#interview) | Interview behavior settings (timers, STT, TTS) |
-
-### API
-
-| Prop        | Type     | Default                    | Description                                            |
-| ----------- | -------- | -------------------------- | ------------------------------------------------------ |
-| baseUrl     | `string` | "/api"                     | Base URL for backend endpoints                         |
-| authToken   | `string` | undefined                  | Optional bearer token appended as Authorization header |
-| retryConfig | `object` | [see below](#retry-config) | Retry policy for fetch calls                           |
-
-#### Retry Config
-
-| Prop      | Type                       | Default       | Description                                |
-| --------- | -------------------------- | ------------- | ------------------------------------------ |
-| attempts  | `number`                   | 3             | Number of retry attempts                   |
-| backoff   | `"fixed" \| "exponential"` | "exponential" | Backoff strategy                           |
-| baseDelay | `number (ms)`              | 1000          | Base delay between retries in milliseconds |
-
-### UI
-
-| Prop         | Type           | Default   | Description                            |
-| ------------ | -------------- | --------- | -------------------------------------- |
-| baseColor    | `string (hex)` | "#3B82F6" | Primary brand color used by the widget |
-| borderRadius | `string (CSS)` | "8px"     | Global corner radius for components    |
-
-### Interview
-
-| Prop       | Type     | Default                          | Description                                |
-| ---------- | -------- | -------------------------------- | ------------------------------------------ |
-| timers     | `object` | [see below](#timers)             | Per-phase and global timing configuration  |
-| stt        | `object` | [see below](#stt-speech-to-text) | Speech-to-Text provider settings           |
-| tts        | `object` | [see below](#tts-text-to-speech) | Text-to-Speech provider settings           |
-| proctoring | `object` | [see below](#proctoring)         | Proctoring settings and cheating detection |
-
-#### Timers
-
-| Prop                       | Type     | Default | Description                                               |
-| -------------------------- | -------- | ------- | --------------------------------------------------------- |
-| thinkingDuration           | `number` | 30s     | Timebox for the Thinking phase                            |
-| answeringDuration          | `number` | 120s    | Timebox for the Answering phase                           |
-| editingDuration            | `number` | 30s     | Timebox for the Editing phase                             |
-| totalInterviewDuration     | `number` | 600s    | Overall interview time cap                                |
-| minimumTimeForNextQuestion | `number` | 120s    | Minimum time required to allow starting the next question |
-
-#### STT (Speech-To-Text)
-
-| Prop     | Type                                 | Default                  | Description                            |
-| -------- | ------------------------------------ | ------------------------ | -------------------------------------- |
-| provider | `"groq" \| "deepgram"`               | "groq"                   | STT vendor to use                      |
-| model    | `"whisper-large-v3-turbo" \| string` | "whisper-large-v3-turbo" | STT model identifier                   |
-| language | `string`                             | "en"                     | Language code passed to the STT engine |
-
-#### TTS (Text-To-Speech)
-
-| Prop     | Type      | Default | Description       |
-| -------- | --------- | ------- | ----------------- |
-| provider | `"piper"` | "piper" | TTS vendor to use |
-
-#### Proctoring
-
-| Prop    | Type      | Default | Description                                               |
-| ------- | --------- | ------- | --------------------------------------------------------- |
-| enabled | `boolean` | true    | Enable/disable proctoring and cheating detection features |
-| gazeAnalysisEnabled  | `boolean` | true    | Enable/disable gaze tracking and analysis                 |
-| showControls         | `boolean` | false    | Show/hide proctoring control panel                        |
-| showEngagementBar    | `boolean` | true    | Show/hide engagement metrics bar                          |
-| showLandmarks        | `boolean` | false    | Show/hide facial landmark visualization                   |
-
-## How it works
-
-The widget composes several parts:
-
-- TimerService controls phases and timeboxes
-- TTS speaks the question in the Reading phase
-- STT records and transcribes the answer in the Answering/Transcribing phases
-- A resilient API client hits your backend to fetch the next question and submit answers
-
-## Backend API Interface
-
-The Interview Widget interacts with a backend endpoint to fetch questions and submit answers. The main endpoint is:
-
-### Endpoint
-
-**POST** `/interview/questions/next`
-
-#### Request Body
-
-Uses the `InterviewQuestionPayload` interface:
-
-```json
-{
-  "interviewId": "string",
-  "isInterviewDone": false,
-  "qnaId": "string",
-  "question": "string",
-  "answer": "string",
-  "answerDuration": "string"
-}
-```
-
-#### Response Body
-
-Uses the `InterviewQuestionResponse` interface:
-
-```json
-{
-  "success": true,
-  "message": "Question generated successfully",
-  "data": {
-    "interview_id": "string",
-    "qna_id": "string",
-    "question": "What is your experience with React?",
-    "question_audio_data_base64": null,
-    "audio_length_in_milliseconds": 0,
-    "estimated_answering_duration": "00:00:30"
-  },
-  "error": null,
-  "code": 200
-}
-```
-
-### Timer phases
-
-`idle → fetching_question → reading_question → thinking → answering → transcribing → editing → submitting → completed`
-
-You’ll see a Start button, a Next Phase button during active phases, a live countdown, and a completion screen.
+# Interview Widget
+
+A modern React interview experience widget with built‑in timer flow, STT (speech‑to‑text), and TTS (text‑to‑speech). It can be embedded via NPM or a CDN and configured through a single provider.
+
+## Features
+
+- **Video capture** with camera integration
+- **Responsive design** with mobile support
+- **TypeScript support** with full type definitions
+- **CDN-ready** for easy integration into any website
+- **Q&A structured interview flow**
+- **Advanced Timer System** with phase management
+- **Text-to-Speech integration** for transcribing
+- **Speech-to-Text integration** for voice answers
+- **Automatic phase transitions** (thinking → answering → editing)
+- **Time validation** before starting new questions
+
+## Quick Start
+
+### 1) Environment Setup
+
+The Interview Widget uses encryption for session storage integrity. Set up your encryption secret based on your environment:
+
+#### Vite React
+
+```env
+# .env
+VITE_IW_SECRET=your-secure-encryption-seed-here
+```
+
+#### Next.js
+
+```env
+# .env.local
+NEXT_PUBLIC_IW_SECRET=your-secure-encryption-seed-here
+```
+
+#### Vanilla JS / Custom Framework
+
+```html
+<script>
+  // Define the secret before loading your widget
+  window.__IW_SECRET__ = "your-secure-encryption-seed-here";
+</script>
+```
+
+### 2) Install (React apps)
+
+```bash
+npm install interview-widget
+```
+
+Minimal usage:
+
+```tsx
+import React from "react";
+import { InterviewWidget, InterviewWidgetProvider } from "interview-widget";
+import "interview-widget/style.css";
+
+export default function App() {
+  return (
+    <InterviewWidgetProvider
+      config={{
+        api: {
+          baseUrl: "/api" // Your backend endpoint
+          authToken: getTokenFromYourAuthSystem(), // Get from secure backend
+        },
+        interview: {
+          stt: {
+            provider: "groq",
+            model: "whisper-large-v3-turbo",
+            language: "en",
+          },
+          tts: { provider: "piper" },
+          timers: {
+            thinkingDuration: 30,
+            answeringDuration: 120,
+            editingDuration: 30,
+          },
+        },
+      }}
+    >
+      <InterviewWidget
+        interviewId="your_interview_id"
+        title="Interview for JS developer"
+        className="iw-rounded-none iw-shadow-none"
+        onInterviewEnd={() => {
+          console.log("🎉🎉 Interview ended 🎉🎉");
+        }}
+      />
+    </InterviewWidgetProvider>
+  );
+}
+```
+
+```html
+<!-- React 18 UMD -->
+<script
+  crossorigin
+  src="https://unpkg.com/react@18/umd/react.production.min.js"
+></script>
+<script
+  crossorigin
+  src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"
+></script>
+
+<!-- Styles + Widget UMD -->
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/interview-widget@latest/dist/widget.css"
+/>
+<script src="https://unpkg.com/interview-widget@latest/dist/widget.umd.js"></script>
+
+<div id="interview-widget-container"></div>
+<script>
+  document.addEventListener("DOMContentLoaded", function () {
+    const { InterviewWidget, InterviewWidgetProvider } = window.InterviewWidget;
+
+    const app = React.createElement(
+      InterviewWidgetProvider,
+      {
+        config: {
+          api: { baseUrl: "/api" },
+          interview: {
+            timers: {
+              thinkingDuration: 30,
+              answeringDuration: 120,
+              editingDuration: 30,
+            },
+            stt: {
+              provider: "groq",
+              model: "whisper-large-v3-turbo",
+              language: "en",
+            },
+            tts: { provider: "piper" },
+          },
+        },
+      },
+      React.createElement(InterviewWidget, { interviewId="your_interview_id", title: "Developer Interview",  onInterviewEnd={() => {}} }
+    );
+
+    ReactDOM.render(app, document.getElementById("interview-widget-container"));
+  });
+</script>
+```
+
+## Public API
+
+### <InterviewWidget />
+
+### InterviewWidget Props
+
+| Prop                    | Type         | Default       | Description                                                                 |
+| ----------------------- | ------------ | ------------- | --------------------------------------------------------------------------- |
+| `interviewId`           | `string`     | Required      | Unique interview identifier used for backend API calls                      |
+| `title`                 | `string`     | `"Interview"` | Title displayed in the interview header                                     |
+| `onInterviewEnd`        | `() => void` | `undefined`   | Called when the interview completes or the user exits                       |
+| `onInterviewDisqualify` | `() => void` | `undefined`   | Called when the interview is disqualified (e.g., due to cheating detection) |
+| `className`             | `string`     | `""`          | Additional CSS classes applied to the outer widget container                |
+
+### <InterviewWidgetProvider />
+
+Wrap your app (or the widget) to provide configuration. See full config reference below.
+
+```tsx
+<InterviewWidgetProvider config={{ api: { baseUrl: "/api" } }}>
+  <InterviewWidget />
+</InterviewWidgetProvider>
+```
+
+## Configuration reference (Provider)
+
+Pass this object to `InterviewWidgetProvider` via the `config` prop. Tables list all keys, types, and defaults.
+
+### Top-level
+
+| Prop      | Type     | Default                 | Description                                    |
+| --------- | -------- | ----------------------- | ---------------------------------------------- |
+| api       | `object` | [see below](#api)       | Backend/API configuration                      |
+| ui        | `object` | [see below](#ui)        | UI customization tokens                        |
+| interview | `object` | [see below](#interview) | Interview behavior settings (timers, STT, TTS) |
+
+### API
+
+| Prop        | Type     | Default                    | Description                                            |
+| ----------- | -------- | -------------------------- | ------------------------------------------------------ |
+| baseUrl     | `string` | "/api"                     | Base URL for backend endpoints                         |
+| authToken   | `string` | undefined                  | Optional bearer token appended as Authorization header |
+| retryConfig | `object` | [see below](#retry-config) | Retry policy for fetch calls                           |
+
+#### Retry Config
+
+| Prop      | Type                       | Default       | Description                                |
+| --------- | -------------------------- | ------------- | ------------------------------------------ |
+| attempts  | `number`                   | 3             | Number of retry attempts                   |
+| backoff   | `"fixed" \| "exponential"` | "exponential" | Backoff strategy                           |
+| baseDelay | `number (ms)`              | 1000          | Base delay between retries in milliseconds |
+
+### UI
+
+| Prop         | Type           | Default   | Description                            |
+| ------------ | -------------- | --------- | -------------------------------------- |
+| baseColor    | `string (hex)` | "#3B82F6" | Primary brand color used by the widget |
+| borderRadius | `string (CSS)` | "8px"     | Global corner radius for components    |
+
+### Interview
+
+| Prop       | Type     | Default                          | Description                                |
+| ---------- | -------- | -------------------------------- | ------------------------------------------ |
+| timers     | `object` | [see below](#timers)             | Per-phase and global timing configuration  |
+| stt        | `object` | [see below](#stt-speech-to-text) | Speech-to-Text provider settings           |
+| tts        | `object` | [see below](#tts-text-to-speech) | Text-to-Speech provider settings           |
+| proctoring | `object` | [see below](#proctoring)         | Proctoring settings and cheating detection |
+
+#### Timers
+
+| Prop                       | Type     | Default | Description                                               |
+| -------------------------- | -------- | ------- | --------------------------------------------------------- |
+| thinkingDuration           | `number` | 30s     | Timebox for the Thinking phase                            |
+| answeringDuration          | `number` | 120s    | Timebox for the Answering phase                           |
+| editingDuration            | `number` | 30s     | Timebox for the Editing phase                             |
+| totalInterviewDuration     | `number` | 600s    | Overall interview time cap                                |
+| minimumTimeForNextQuestion | `number` | 120s    | Minimum time required to allow starting the next question |
+
+#### STT (Speech-To-Text)
+
+| Prop     | Type                                 | Default                  | Description                            |
+| -------- | ------------------------------------ | ------------------------ | -------------------------------------- |
+| provider | `"groq" \| "deepgram"`               | "groq"                   | STT vendor to use                      |
+| model    | `"whisper-large-v3-turbo" \| string` | "whisper-large-v3-turbo" | STT model identifier                   |
+| language | `string`                             | "en"                     | Language code passed to the STT engine |
+
+#### TTS (Text-To-Speech)
+
+| Prop     | Type      | Default | Description       |
+| -------- | --------- | ------- | ----------------- |
+| provider | `"piper"` | "piper" | TTS vendor to use |
+
+#### Proctoring
+
+| Prop    | Type      | Default | Description                                               |
+| ------- | --------- | ------- | --------------------------------------------------------- |
+| enabled | `boolean` | true    | Enable/disable proctoring and cheating detection features |
+| gazeAnalysisEnabled  | `boolean` | true    | Enable/disable gaze tracking and analysis                 |
+| showControls         | `boolean` | false    | Show/hide proctoring control panel                        |
+| showEngagementBar    | `boolean` | true    | Show/hide engagement metrics bar                          |
+| showLandmarks        | `boolean` | false    | Show/hide facial landmark visualization                   |
+
+## How it works
+
+The widget composes several parts:
+
+- TimerService controls phases and timeboxes
+- TTS speaks the question in the Reading phase
+- STT records and transcribes the answer in the Answering/Transcribing phases
+- A resilient API client hits your backend to fetch the next question and submit answers
+
+## Backend API Interface
+
+The Interview Widget interacts with a backend endpoint to fetch questions and submit answers. The main endpoint is:
+
+### Endpoint
+
+**POST** `/interview/questions/next`
+
+#### Request Body
+
+Uses the `InterviewQuestionPayload` interface:
+
+```json
+{
+  "interviewId": "string",
+  "isInterviewDone": false,
+  "qnaId": "string",
+  "question": "string",
+  "answer": "string",
+  "answerDuration": "string"
+}
+```
+
+#### Response Body
+
+Uses the `InterviewQuestionResponse` interface:
+
+```json
+{
+  "success": true,
+  "message": "Question generated successfully",
+  "data": {
+    "interview_id": "string",
+    "qna_id": "string",
+    "question": "What is your experience with React?",
+    "question_audio_data_base64": null,
+    "audio_length_in_milliseconds": 0,
+    "estimated_answering_duration": "00:00:30"
+  },
+  "error": null,
+  "code": 200
+}
+```
+
+### Timer phases
+
+`idle → fetching_question → reading_question → thinking → answering → transcribing → editing → submitting → completed`
+
+You’ll see a Start button, a Next Phase button during active phases, a live countdown, and a completion screen.

package/dist/components/media/video-feed.d.ts

@@ -1,7 +1,5 @@
-import { default as React } from 'react';
 export interface VideoFeedHandle {
     setReference: () => void;
-    faceLandmarkerRef?: React.RefObject<any>;
 }
 interface VideoFeedProps {
     className?: string;
@@ -9,5 +7,5 @@ interface VideoFeedProps {
     interview_duration?: number | undefined;
     showProctoringUI?: boolean;
 }
-declare const VideoFeed: React.ForwardRefExoticComponent<VideoFeedProps & React.RefAttributes<VideoFeedHandle>>;
+declare const VideoFeed: import('react').ForwardRefExoticComponent<VideoFeedProps & import('react').RefAttributes<VideoFeedHandle>>;
 export default VideoFeed;