interview-widget 0.0.7 → 0.0.9

package/README.md

@@ -1,27 +1,70 @@
 # Interview Widget
 
-A customizable React interview widget that can be easily embedded into any website or React application.
+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
-- 🔧 **Flexible positioning** (inline, fixed bottom-right/left)
 - 🧩 **TypeScript support** with full type definitions
 - 🎯 **CDN-ready** for easy integration into any website
 - 🔄 **Q&A structured interview flow**
-- 💬 **Configurable questions** for different interview types
-- 🎪 **Tailwind CSS** with prefixed classes to avoid conflicts
-- ✨ **Smooth animations** and modern UI
+- ⏱️ **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)
+### 1) Install (React apps)
 
-Add these scripts to your HTML:
+```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" },
+        interview: {
+          stt: {
+            provider: "groq",
+            model: "whisper-large-v3-turbo",
+            language: "en",
+          },
+          tts: { provider: "piper" },
+          timers: {
+            thinkingDuration: 30,
+            answeringDuration: 120,
+            editingDuration: 30,
+          },
+        },
+      }}
+    >
+      <InterviewWidget
+        title="Technical Interview"
+        onInterviewEnd={() => {
+          console.log("🎉🎉 Interview ended 🎉🎉");
+        }}
+      />
+    </InterviewWidgetProvider>
+  );
+}
+```
+
+### 2) CDN usage (Any website)
 
 ```html
-<!-- Load React and ReactDOM from CDN -->
+<!-- React 18 UMD -->
 <script
   crossorigin
   src="https://unpkg.com/react@18/umd/react.production.min.js"
@@ -31,123 +74,176 @@ Add these scripts to your HTML:
   src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"
 ></script>
 
-<!-- Load the interview widget CSS -->
+<!-- Styles + Widget UMD -->
 <link
   rel="stylesheet"
   href="https://unpkg.com/interview-widget@latest/dist/widget.css"
 />
-
-<!-- Load the interview widget JavaScript -->
 <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 } = window.InterviewWidget;
+    const { InterviewWidget, InterviewWidgetProvider } = window.InterviewWidget;
 
-    // Define your interview questions
-    const questions = [
+    const app = React.createElement(
+      InterviewWidgetProvider,
       {
-        id: "1",
-        text: "Can you please introduce yourself?",
-        timestamp: new Date(),
+        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" },
+          },
+        },
       },
-      {
-        id: "2",
-        text: "What experience do you have with our required technologies?",
-        timestamp: new Date(),
-      },
-      {
-        id: "3",
-        text: "What are your strengths and weaknesses?",
-        timestamp: new Date(),
-      },
-    ];
-
-    ReactDOM.render(
-      React.createElement(InterviewWidget, {
-        title: "Developer Interview",
-        questions: questions,
-        position: "bottom-right",
-      }),
-      document.getElementById("interview-widget-container")
+      React.createElement(InterviewWidget, { title: "Developer Interview" })
     );
+
+    ReactDOM.render(app, document.getElementById("interview-widget-container"));
   });
 </script>
 ```
 
-### React Application Integration
+## Public API
 
-```bash
-npm install interview-widget
-```
+### <InterviewWidget />
 
-```tsx
-import React, { useState } from "react";
-import {
-  InterviewWidget,
-  InterviewQuestion,
-  InterviewAnswer,
-} from "interview-widget";
-import "interview-widget/style.css";
+### InterviewWidget Props
 
-export function InterviewWidgetDemo() {
-  const questions: InterviewQuestion[] = [
-    {
-      id: "1",
-      text: "Can you please introduce yourself?",
-      timestamp: new Date(),
-    },
-    {
-      id: "2",
-      text: "What experience do you have with our required technologies?",
-      timestamp: new Date(),
-    },
-  ];
-
-  const handleAnswerSubmit = (answer: InterviewAnswer) => {
-    // Handle submitting answer to your backend
-    console.log("User answered:", answer);
-  };
-
-  const handleComplete = (answers: InterviewAnswer[]) => {
-    // Handle interview completion
-    console.log("All answers:", answers);
-  };
+| 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        |
+| `className`      | `string`     | `""`          | Additional CSS classes applied to the outer widget container |
 
-  return (
-    <div>
-      <InterviewWidget
-        title="Technical Interview"
-        questions={questions}
-        onAnswerSubmit={handleAnswerSubmit}
-        onComplete={handleComplete}
-      />
-    </div>
-  );
-}
+Notes:
+
+- Internally uses an InterviewController that orchestrates the full flow using the configured API/STT/TTS/Timer.
+- The interview id is currently derived internally; integrate with your backend by configuring the API base and auth.
+
+### <InterviewWidgetProvider />
+
+Wrap your app (or the widget) to provide configuration. See full config reference below.
+
+```tsx
+<InterviewWidgetProvider config={{ api: { baseUrl: "/api" } }}>
+  <InterviewWidget />
+</InterviewWidgetProvider>
 ```
 
-## API Reference
+## Configuration reference (Provider)
 
-### InterviewWidget Props
+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 | Backend/API configuration                      |
+| ui        | object | see below | UI customization tokens                        |
+| interview | object | see below | 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 policy for fetch calls                           |
+
+retryConfig
+
+| 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 | Per-phase and global timing configuration |
+| stt    | object | see below | Speech-to-Text provider settings          |
+| tts    | object | see below | Text-to-Speech provider settings          |
+
+timers
+
+| Prop                       | Type       | Default | Description                                               |
+| -------------------------- | ---------- | ------- | --------------------------------------------------------- |
+| thinkingDuration           | number (s) | 30      | Timebox for the Thinking phase                            |
+| answeringDuration          | number (s) | 120     | Timebox for the Answering phase                           |
+| editingDuration            | number (s) | 30      | Timebox for the Editing phase                             |
+| totalInterviewDuration     | number (s) | 600     | Overall interview time cap                                |
+| minimumTimeForNextQuestion | number (s) | 120     | Minimum time required to allow starting the next question |
+
+stt
+
+| 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 | "en"                               | "en"                     | Language code passed to the STT engine |
+
+tts
+
+| Prop     | Type    | Default | Description       |
+| -------- | ------- | ------- | ----------------- |
+| provider | "piper" | "piper" | TTS vendor to use |
+
+Notes on defaults:
+
+- Base defaults come from `src/utils/constants.ts` (`defaultConfig`).
+- `totalInterviewDuration` and `minimumTimeForNextQuestion` default to 600s and 120s respectively via the TimerService if not explicitly provided.
+
+## 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
+
+### 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.
+
+## Documentation
+
+- Timer system: `docs/timer.md`
+- STT integration: `docs/stt-integration.md`
+- TTS integration: `docs/tts-integration.md`
+- API layer overview: `docs/api-layer.md`
+- Flow simulation and diagrams: `docs/flow-simulation.md`
+
+## Development
+
+Local scripts:
 
-| Prop             | Type                                   | Default       | Description                             |
-| ---------------- | -------------------------------------- | ------------- | --------------------------------------- |
-| `title`          | `string`                               | `"Interview"` | Title displayed in the interview header |
-| `candidateName`  | `string`                               | `""`          | Optional name of the candidate          |
-| `questions`      | `InterviewQuestion[]`                  | Required      | Array of interview questions            |
-| `onAnswerSubmit` | `(answer: InterviewAnswer) => void`    | `undefined`   | Callback when user submits an answer    |
-| `onComplete`     | `(answers: InterviewAnswer[]) => void` | `undefined`   | Callback when interview is completed    |
-| `className`      | `string`                               | `""`          | Additional CSS classes                  |
-| `height`         | `string`                               | `"600px"`     | Height of the interview widget          |
-| `width`          | `string`                               | `"100%"`      | Width of the interview widget           |
-
-## Browser Support
-
-- Chrome (latest)
-- Firefox (latest)
-- Safari (latest)
-- Edge (latest)
+- `npm run dev` – Start Vite dev server
+- `npm run build` – Type-check and build library bundles (UMD/ESM)
+- `npm run preview` – Preview the production build
 
 ## Contributing
 

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

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

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

@@ -1,6 +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/question-display.d.ts

@@ -1,7 +1,8 @@
 import { default as React } from 'react';
-import { InterviewQuestion } from '../../types';
+import { InterviewQuestionData } from '../../types';
 interface QuestionDisplayProps {
-    question: InterviewQuestion;
+    question: InterviewQuestionData | null;
+    isLoading?: boolean;
 }
 declare const QuestionDisplay: React.FC<QuestionDisplayProps>;
 export default QuestionDisplay;

package/dist/components/modals/exit-confirmation-modal.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    confirmExitInterview: () => void;
+    isOpen: boolean;
+    onClose: () => void;
+}
+export declare const ExitConfirmationModal: ({ confirmExitInterview, isOpen, onClose, }: Props) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/timer/timer-display.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { TimerState } from '../../services/timer/timer-service';
+interface TimerDisplayProps {
+    state: TimerState;
+    className?: string;
+    defaultTimers?: {
+        thinking?: number;
+        answering?: number;
+        editing?: number;
+    };
+}
+declare const TimerDisplay: React.FC<TimerDisplayProps>;
+export default TimerDisplay;

package/dist/components/ui/dialog.d.ts

@@ -0,0 +1,13 @@
+import { default as React, ReactNode } from 'react';
+interface DialogProps {
+    isOpen: boolean;
+    onClose: () => void;
+    children: ReactNode;
+    title?: string;
+    showCloseButton?: boolean;
+    closeOnOverlayClick?: boolean;
+    closeOnEscape?: boolean;
+    className?: string;
+}
+declare const Dialog: React.FC<DialogProps>;
+export default Dialog;

package/dist/context/interview-widget-context.d.ts

@@ -0,0 +1,34 @@
+import { ReactNode } from 'react';
+import { InterviewWidgetConfig } from '../types';
+interface InterviewWidgetProviderProps {
+    config?: InterviewWidgetConfig;
+    children: ReactNode;
+}
+export declare function InterviewWidgetProvider({ config, children, }: InterviewWidgetProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useInterviewConfig(): InterviewWidgetConfig;
+/**
+ * Hook to access specific config sections
+ */
+export declare function useAPIConfig(): {
+    baseUrl?: string;
+    authToken?: string;
+    retryConfig?: {
+        attempts?: number;
+        backoff?: "fixed" | "exponential";
+        baseDelay?: number;
+    };
+};
+export declare function useUIConfig(): {
+    baseColor?: string;
+    borderRadius?: string;
+};
+export declare function useInterviewConfigSection(): NonNullable<InterviewWidgetConfig["interview"]>;
+export declare function useSTTConfig(): {
+    provider?: "groq" | "deepgram";
+    model?: "whisper-large-v3-turbo" | (string & {});
+    language?: "en";
+} | undefined;
+export declare function useTTSConfig(): {
+    provider?: "piper";
+} | undefined;
+export {};

package/dist/hooks/use-api.d.ts

@@ -0,0 +1,26 @@
+import { APIError, APIHookState } from '../types';
+type UseQueryAPIOptions<T> = {
+    immediate?: boolean;
+    enabled?: boolean;
+    onError?: (error: APIError) => void;
+    onSuccess?: (data: T) => void;
+    onSettled?: (data: T | null, error: APIError | null) => void;
+};
+type UseMutationAPIOptions<T> = {
+    onError?: (error: APIError) => void;
+    onSuccess?: (data: T) => void;
+    onSettled?: (data: T | null, error: APIError | null) => void;
+};
+/**
+ * Hook for GET requests (queries) - auto-executes and provides refetch
+ */
+export declare function useQueryAPI<T>(apiCall: () => Promise<T>, options?: UseQueryAPIOptions<T>): APIHookState<T> & {
+    refetch: () => Promise<void>;
+};
+/**
+ * Hook for mutations (POST/PUT/PATCH/DELETE) - manual execution with parameters
+ */
+export declare function useMutationAPI<T, P extends any[] = []>(apiCall: (...args: P) => Promise<T>, options?: UseMutationAPIOptions<T>): APIHookState<T> & {
+    execute: (...args: P) => Promise<void>;
+};
+export {};

package/dist/hooks/use-dialog.d.ts

@@ -0,0 +1,6 @@
+export declare const useDialog: (initialState?: boolean) => {
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+};

package/dist/hooks/use-interview-api.d.ts

@@ -0,0 +1,5 @@
+import { InterviewAPI } from '../services/api/interview-api';
+/**
+ *  Provides a configured InterviewAPI instance
+ */
+export declare function useInterviewAPI(): InterviewAPI;

package/dist/hooks/use-stt.d.ts

@@ -0,0 +1,20 @@
+import { STTConfig, STTError, STTRequest, STTResponse } from '../services/stt';
+export interface UseSTTReturn {
+    startRecording: (maxDuration?: number) => Promise<void>;
+    stopRecording: () => Promise<Blob>;
+    transcribe: (audioBlob: Blob, options?: Partial<STTRequest>) => Promise<STTResponse>;
+    cancelRecording: () => void;
+    isRecording: boolean;
+    isTranscribing: boolean;
+    transcript: string | null;
+    error: STTError | null;
+    audioBlob: Blob | null;
+}
+export interface UseSTTOptions {
+    config?: Partial<STTConfig>;
+    onStart?: () => void;
+    onStop?: () => void;
+    onTranscriptionComplete?: (result: STTResponse) => void;
+    onError?: (error: STTError) => void;
+}
+export declare const useSTT: (options?: UseSTTOptions) => UseSTTReturn;

package/dist/hooks/use-timer.d.ts

@@ -0,0 +1,12 @@
+import { TimerService, TimerState, TimerConfig, TimerCallbacks } from '../services/timer/timer-service';
+export interface UseTimerOptions {
+    config?: Partial<TimerConfig>;
+    callbacks?: TimerCallbacks;
+}
+export interface UseTimerReturn {
+    state: TimerState;
+    startQuestion: () => void;
+    nextPhase: () => void;
+    timerService: TimerService;
+}
+export declare function useTimer(options?: UseTimerOptions): UseTimerReturn;

package/dist/hooks/use-tts.d.ts

@@ -0,0 +1,15 @@
+import { TTSConfig, TTSRequest } from '../services/tts';
+export interface UseTTSReturn {
+    speak: (text: string, options?: Partial<TTSRequest>) => Promise<void>;
+    stop: () => void;
+    isPlaying: boolean;
+    isLoading: boolean;
+    error: Error | null;
+}
+export interface UseTTSOptions {
+    config?: Partial<TTSConfig>;
+    onStart?: () => void;
+    onEnd?: () => void;
+    onError?: (error: Error) => void;
+}
+export declare const useTTS: (options?: UseTTSOptions) => UseTTSReturn;

package/dist/index.d.ts

@@ -1,11 +1,12 @@
+import { InterviewWidgetProvider } from './context/interview-widget-context';
 import { default as InterviewWidget } from './interview-widget';
-export { InterviewWidget };
 export * from './types';
-export { InterviewWidget as default };
+export { InterviewWidget as default, InterviewWidget, InterviewWidgetProvider };
 declare global {
     interface Window {
         InterviewWidget: {
             InterviewWidget: typeof InterviewWidget;
+            InterviewWidgetProvider: typeof InterviewWidgetProvider;
         };
         React: any;
         ReactDOM: any;

package/dist/services/api/index.d.ts

@@ -0,0 +1,2 @@
+export { interviewAPI, InterviewAPI } from './interview-api';
+export type { APIError, APIErrorType, APIHookState } from '../../types';

package/dist/services/api/interview-api.d.ts

@@ -0,0 +1,23 @@
+import { InterviewQuestionPayload, InterviewQuestionResponse, InterviewWidgetConfig } from '../../types';
+declare class InterviewAPI {
+    private config;
+    constructor(config?: InterviewWidgetConfig["api"]);
+    /**
+     * Update configuration
+     */
+    updateConfig(config: InterviewWidgetConfig["api"]): void;
+    /**
+     * Get default headers for API requests
+     */
+    private getHeaders;
+    /**
+     * Get base URL from config with fallback
+     */
+    private getBaseUrl;
+    /**
+     * Get questions for an interview
+     */
+    generateQuestion({ interviewId, isInterviewDone, qnaId, question, answer, answerDuration, }: InterviewQuestionPayload): Promise<InterviewQuestionResponse>;
+}
+export declare const interviewAPI: InterviewAPI;
+export { InterviewAPI };

package/dist/services/stt/index.d.ts

@@ -0,0 +1 @@
+export { sttService, STTService, STTError, type STTConfig, type STTRequest, type STTResponse, type RecordingEvents, } from './stt-service';

package/dist/services/stt/stt-service.d.ts

@@ -0,0 +1,78 @@
+export interface STTConfig {
+    baseUrl?: string;
+    provider?: string;
+    model?: string;
+    language?: string;
+    includeTimestamps?: boolean;
+    temperature?: number;
+}
+export interface STTRequest {
+    audioBlob: Blob;
+    model?: string;
+    language?: string;
+    includeTimestamps?: boolean;
+    temperature?: number;
+}
+export interface STTResponse {
+    transcript: string;
+    confidence?: number;
+    language?: string;
+    duration?: number;
+}
+export interface RecordingEvents {
+    onStart?: () => void;
+    onStop?: () => void;
+    onDataAvailable?: (blob: Blob) => void;
+    onError?: (error: Error) => void;
+}
+export declare class STTError extends Error {
+    readonly code: string;
+    readonly recoverable: boolean;
+    constructor(message: string, code: string, recoverable?: boolean);
+}
+declare class STTService {
+    private config;
+    private mediaRecorder;
+    private audioChunks;
+    private recordingStream;
+    private autoStopTimeoutId;
+    constructor(config?: STTConfig);
+    /**
+     * Update STT configuration
+     */
+    updateConfig(config: Partial<STTConfig>): void;
+    /**
+     * Check if browser supports audio recording
+     */
+    isRecordingSupported(): boolean;
+    /**
+     * Start recording audio from user's microphone
+     */
+    startRecording(maxDuration?: number, events?: RecordingEvents): Promise<void>;
+    /**
+     * Stop recording and return the audio blob
+     */
+    stopRecording(): Promise<Blob>;
+    /**
+     * Transcribe audio blob using the STT API
+     */
+    transcribe(request: STTRequest): Promise<STTResponse>;
+    /**
+     * Cancel current recording without processing
+     */
+    cancelRecording(): void;
+    /**
+     * Check if currently recording
+     */
+    isRecording(): boolean;
+    /**
+     * Get supported MIME type for recording
+     */
+    private getSupportedMimeType;
+    /**
+     * Clean up recording resources
+     */
+    private cleanup;
+}
+export declare const sttService: STTService;
+export { STTService };