interview-widget 1.0.0 → 1.0.1

package/README.md

@@ -1,281 +1,272 @@
-# Chat Widget
+# Interview Widget
 
-A simple, customizable React chat widget that can be easily embedded into any website or React application via CDN.
+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
 
-- 🎨 **Customizable themes** (Light/Dark)
-- 📱 **Responsive design** with mobile support
-- 🔧 **Flexible positioning** (inline, fixed bottom-right/left)
-- ⚡ **TypeScript support** with full type definitions
-- 🎯 **CDN-ready** for easy integration into any website
-- 🔄 **Auto-reply functionality** for standalone use
-- 💬 **Controlled/uncontrolled** component modes
-- 🎪 **Tailwind CSS** with prefixed classes to avoid conflicts
-- ✨ **Smooth animations** and modern UI
+- **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
 
-### CDN Integration (Any Website)
-
-Add these scripts to your HTML:
-
-```html
-<!-- Load React and ReactDOM from CDN -->
-<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>
-
-<!-- Load the chat widget CSS -->
-<link rel="stylesheet" href="https://your-cdn.com/chat-widget.css">
-
-<!-- Load the chat widget JavaScript -->
-<script src="https://your-cdn.com/chat-widget.umd.js"></script>
-
-<script>
-document.addEventListener('DOMContentLoaded', function() {
-    const { ChatWidget } = window.ChatWidget;
-    
-    ReactDOM.render(
-        React.createElement(ChatWidget, {
-            title: 'Customer Support',
-            placeholder: 'How can we help you?',
-            position: 'bottom-right'
-        }),
-        document.getElementById('chat-widget-container')
-    );
-});
-</script>
-```
-
-### React Application Integration
+### 1) Install (React apps)
 
 ```bash
-npm install chat-widget
+npm install interview-widget
 ```
 
-```tsx
-import React from 'react';
-import { ChatWidget, Message } from 'chat-widget';
-
-function App() {
-  const [messages, setMessages] = useState<Message[]>([]);
+Minimal usage:
 
-  const handleSendMessage = (messageText: string) => {
-    // Handle sending message to your backend
-    console.log('User sent:', messageText);
-  };
+```tsx
+import React from "react";
+import { InterviewWidget, InterviewWidgetProvider } from "interview-widget";
+import "interview-widget/style.css";
 
+export default function App() {
   return (
-    <div>
-      <ChatWidget
-        title="Support Chat"
-        messages={messages}
-        onSendMessage={handleSendMessage}
-        position="bottom-right"
+    <InterviewWidgetProvider
+      config={{
+        api: { baseUrl: "/api" },
+        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 🎉🎉");
+        }}
       />
-    </div>
+    </InterviewWidgetProvider>
   );
 }
 ```
 
-## API Reference
-
-### ChatWidget Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `string` | `"Chat Support"` | Title displayed in the chat header |
-| `placeholder` | `string` | `"Type your message..."` | Input field placeholder text |
-| `onSendMessage` | `(message: string) => void` | `undefined` | Callback when user sends a message |
-| `messages` | `Message[]` | `[]` | Array of messages for controlled mode |
-| `className` | `string` | `""` | Additional CSS classes |
-| `botName` | `string` | `"Support Bot"` | Name displayed for bot messages |
-| `userName` | `string` | `"You"` | Name displayed for user messages |
-| `height` | `string` | `"400px"` | Height of the chat widget |
-| `width` | `string` | `"350px"` | Width of the chat widget |
-| `position` | `'bottom-right' \| 'bottom-left' \| 'inline'` | `"inline"` | Widget positioning |
-| `theme` | `'light' \| 'dark'` | `"light"` | Color theme |
-
-### Message Interface
-
-```typescript
-interface Message {
-  id: string;
-  text: string;
-  sender: 'user' | 'bot';
-  timestamp: Date;
-}
+```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>
 ```
 
-## Usage Examples
+## Public API
 
-### Standalone Widget (Auto-reply)
+### <InterviewWidget />
 
-```tsx
-<ChatWidget
-  title="AI Assistant"
-  placeholder="Ask me anything..."
-  botName="AI Helper"
-  userName="Visitor"
-/>
-```
+### InterviewWidget Props
 
-### Controlled Widget
+| 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                |
 
-```tsx
-const [messages, setMessages] = useState<Message[]>([]);
-
-const handleMessage = async (text: string) => {
-  // Add user message
-  const userMessage = {
-    id: Date.now().toString(),
-    text,
-    sender: 'user' as const,
-    timestamp: new Date()
-  };
-  setMessages(prev => [...prev, userMessage]);
-
-  // Get bot response from your API
-  const response = await fetch('/api/chat', {
-    method: 'POST',
-    body: JSON.stringify({ message: text })
-  });
-  const data = await response.json();
-
-  // Add bot response
-  const botMessage = {
-    id: (Date.now() + 1).toString(),
-    text: data.reply,
-    sender: 'bot' as const,
-    timestamp: new Date()
-  };
-  setMessages(prev => [...prev, botMessage]);
-};
-
-<ChatWidget
-  messages={messages}
-  onSendMessage={handleMessage}
-/>
-```
+### <InterviewWidgetProvider />
 
-### Fixed Position Widget
+Wrap your app (or the widget) to provide configuration. See full config reference below.
 
 ```tsx
-<ChatWidget
-  title="Help & Support"
-  position="bottom-right"
-  height="500px"
-  width="300px"
-/>
+<InterviewWidgetProvider config={{ api: { baseUrl: "/api" } }}>
+  <InterviewWidget />
+</InterviewWidgetProvider>
 ```
 
-### Dark Theme
+## Configuration reference (Provider)
 
-```tsx
-<ChatWidget
-  theme="dark"
-  title="Night Support"
-  botName="Night Owl Bot"
-/>
-```
+Pass this object to `InterviewWidgetProvider` via the `config` prop. Tables list all keys, types, and defaults.
 
-## Development
+### Top-level
 
-### Setup
+| 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) |
 
-```bash
-git clone https://github.com/your-username/chat-widget.git
-cd chat-widget
-npm install
-```
+### API
 
-### Development Server
+| 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                           |
 
-```bash
-npm run dev
-```
+#### Retry Config
 
-Open http://localhost:5173 to see the development examples.
+| 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 |
 
-### Build
+### UI
 
-```bash
-npm run build
-```
+| Prop         | Type           | Default   | Description                            |
+| ------------ | -------------- | --------- | -------------------------------------- |
+| baseColor    | `string (hex)` | "#3B82F6" | Primary brand color used by the widget |
+| borderRadius | `string (CSS)` | "8px"     | Global corner radius for components    |
 
-This creates:
-- `dist/chat-widget.umd.js` - UMD build for CDN
-- `dist/chat-widget.es.js` - ES modules build
-- `dist/chat-widget.css` - Styles
-- `dist/index.d.ts` - TypeScript definitions
+### Interview
 
-### Testing Examples
+| 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 |
 
-After building, you can test the CDN integration by opening `examples/cdn-example.html` in your browser.
+#### Timers
 
-## Customization
+| 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 |
 
-### Custom Styles
+#### STT (Speech-To-Text)
 
-The widget uses Tailwind CSS with the `cw-` prefix to avoid conflicts. You can override styles:
+| 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 |
 
-```css
-.chat-widget-container {
-  /* Your custom styles */
-}
+#### TTS (Text-To-Speech)
 
-.cw-bg-primary-500 {
-  background-color: your-brand-color !important;
-}
-```
+| Prop     | Type      | Default | Description       |
+| -------- | --------- | ------- | ----------------- |
+| provider | `"piper"` | "piper" | TTS vendor to use |
 
-### API Integration
+#### Proctoring
 
-For production use, implement your chat API:
+| Prop    | Type      | Default | Description                                               |
+| ------- | --------- | ------- | --------------------------------------------------------- |
+| enabled | `boolean` | false   | Enable/disable proctoring and cheating detection features |
 
-```tsx
-const handleSendMessage = async (message: string) => {
-  try {
-    const response = await fetch('/api/chat', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        message,
-        sessionId: 'user-session-id',
-        timestamp: new Date().toISOString()
-      })
-    });
-    
-    const data = await response.json();
-    // Handle response...
-  } catch (error) {
-    // Handle error...
-  }
-};
-```
+## 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
 
-## Browser Support
+The Interview Widget interacts with a backend endpoint to fetch questions and submit answers. The main endpoint is:
 
-- Chrome (latest)
-- Firefox (latest)
-- Safari (latest)
-- Edge (latest)
-- IE 11+ (with polyfills)
+### Endpoint
 
-## License
+**POST** `/interview/questions/next`
 
-MIT License - see LICENSE file for details.
+#### Request Body
 
-## Contributing
+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
+}
+```
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
+### Timer phases
 
-## Support
+`idle → fetching_question → reading_question → thinking → answering → transcribing → editing → submitting → completed`
 
-- 📧 Email: support@yourcompany.com
-- 🐛 Issues: [GitHub Issues](https://github.com/your-username/chat-widget/issues)
-- 📖 Docs: [Documentation](https://your-docs-site.com)
+You’ll see a Start button, a Next Phase button during active phases, a live countdown, and a completion screen.

package/dist/assets/alert-triangle-icon.d.ts

@@ -0,0 +1 @@
+export declare const AlertTriangleIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/bot-icon.d.ts

@@ -0,0 +1 @@
+export declare const BotIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/circle-play-icon.d.ts

@@ -0,0 +1 @@
+export declare const CirclePlayIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/clock-fading-icon.d.ts

@@ -0,0 +1 @@
+export declare const ClockFadingIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/clock-icon.d.ts

@@ -0,0 +1 @@
+export declare const ClockIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/eye-icon.d.ts

@@ -0,0 +1 @@
+export declare const EyeIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/focus-icon.d.ts

@@ -0,0 +1 @@
+export declare const FocusIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/index.d.ts

@@ -0,0 +1,12 @@
+export * from './alert-triangle-icon';
+export * from './bot-icon';
+export * from './clock-fading-icon';
+export * from './clock-icon';
+export * from './eye-icon';
+export * from './focus-icon';
+export * from './keyboard-icon';
+export * from './loader-icon';
+export * from './monitor-icon';
+export * from './mouse-pointer-click-icon';
+export * from './shield-icon';
+export * from './speak-icon';

package/dist/assets/keyboard-icon.d.ts

@@ -0,0 +1 @@
+export declare const KeyboardIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/loader-icon.d.ts

@@ -0,0 +1 @@
+export declare const LoaderIcon: ({ className, ...props }: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/monitor-icon.d.ts

@@ -0,0 +1 @@
+export declare const MonitorIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/mouse-pointer-click-icon.d.ts

@@ -0,0 +1 @@
+export declare const MousePointerClickIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/shield-icon.d.ts

@@ -0,0 +1,2 @@
+import { default as React } from 'react';
+export declare const ShieldIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/assets/speak-icon.d.ts

@@ -0,0 +1 @@
+export declare const SpeakIcon: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element;

package/dist/components/interview/answer-area.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+import { TimerState } from '../../services/timer';
+interface AnswerAreaProps {
+    value: string;
+    onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+    onSubmit: () => void;
+    isSubmitDisabled: boolean;
+    state: TimerState;
+    editingTime: number;
+}
+declare const AnswerArea: React.FC<AnswerAreaProps>;
+export default AnswerArea;

package/dist/components/interview/interview-content.d.ts

@@ -0,0 +1,11 @@
+import { default as React, ReactNode } from 'react';
+import { TimerPhase } from '../../services/timer/timer-service';
+import { InterviewQuestionData } from '../../types';
+interface InterviewContentProps {
+    currentQuestion: InterviewQuestionData | null;
+    phase: TimerPhase;
+    className?: string;
+    children: ReactNode;
+}
+export declare const InterviewContent: React.FC<InterviewContentProps>;
+export {};

package/dist/components/interview/interview-controller.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+interface InterviewControllerProps {
+    interviewTitle: string;
+    interviewId: string;
+    onComplete?: (() => void) | undefined;
+    onDisqualify?: (() => void) | undefined;
+    className?: string;
+}
+declare const InterviewController: React.FC<InterviewControllerProps>;
+export default InterviewController;

package/dist/components/interview/interview-header.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+interface InterviewHeaderProps {
+    title: string;
+    onExit: () => void;
+}
+declare const InterviewHeader: React.FC<InterviewHeaderProps>;
+export default InterviewHeader;

package/dist/components/interview/phases/animated-blob.d.ts

@@ -0,0 +1,13 @@
+interface SiriOrbProps {
+    size?: string;
+    className?: string;
+    colors?: {
+        bg?: string;
+        c1?: string;
+        c2?: string;
+        c3?: string;
+    };
+    animationDuration?: number;
+}
+declare const AnimatedOrb: React.FC<SiriOrbProps>;
+export default AnimatedOrb;

package/dist/components/interview/phases/answering-phase.d.ts

@@ -0,0 +1,10 @@
+import { STTError } from '../../../services/stt';
+import { TimerState } from '../../../services/timer';
+interface Props {
+    state: TimerState;
+    answeringTime: number;
+    nextPhase: () => void;
+    sttError: STTError | null;
+}
+export declare const AnsweringPhase: ({ state, answeringTime, nextPhase, sttError, }: Props) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/interview/phases/file-generation-animation.d.ts

@@ -0,0 +1 @@
+export default function FileGenerationAnimation(): import("react/jsx-runtime").JSX.Element;

package/dist/components/interview/phases/interview-completion-modal.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+interface InterviewCompletionModalProps {
+    open: boolean;
+    onClose?: () => void;
+}
+declare const InterviewCompletionModal: React.FC<InterviewCompletionModalProps>;
+export { InterviewCompletionModal };

package/dist/components/interview/phases/question-reading-animation.d.ts

@@ -0,0 +1,5 @@
+interface Props {
+    ttsError: Error | null;
+}
+export default function QuestionReadingAnimation({ ttsError }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/interview/phases/thinking-phase.d.ts

@@ -0,0 +1,8 @@
+import { TimerState } from '../../../services/timer';
+interface Props {
+    state: TimerState;
+    thinkingTime: number;
+    nextPhase: () => void;
+}
+export declare const ThinkingPhase: ({ state, thinkingTime, nextPhase }: Props) => import("react/jsx-runtime").JSX.Element;
+export {};