@tinyweb_dev/oe-exam-sdk 0.1.3 → 0.1.4

package/dist/components/exams/take/hooks/useExamTimer.d.ts

@@ -0,0 +1,21 @@
+export type WarningLevel = 'none' | 'warning' | 'critical';
+export interface WarningThreshold {
+    seconds: number;
+    level: WarningLevel;
+    callback?: () => void;
+}
+interface UseExamTimerOptions {
+    onTimeExpired: () => void;
+    /** @deprecated Use warningThresholds[] instead */
+    onWarningThreshold?: () => void;
+    /** @deprecated Use warningThresholds[] instead */
+    warningThresholdSeconds?: number;
+    /** Multiple warning thresholds for TOEIC (15min + 5min). Highest severity wins. */
+    warningThresholds?: WarningThreshold[];
+}
+interface UseExamTimerReturn {
+    remainingSeconds: number;
+    warningLevel: WarningLevel;
+}
+export declare function useExamTimer(options: UseExamTimerOptions): UseExamTimerReturn;
+export {};

package/dist/components/exams/take/hooks/useExamTimer.js

@@ -0,0 +1 @@
+import{useEffect as n,useRef as e}from"react";import{useExamTakingStore as r}from"../../../../shared/lib/stores/examTakingStore";export function useExamTimer(t){const i=r(),c=e(null),o=e(!1),s=(()=>{const n=t.warningThresholds??[];if(0===n.length&&void 0!==t.warningThresholdSeconds){const n=[];return t.onWarningThreshold&&n.push({seconds:t.warningThresholdSeconds,level:"critical",callback:t.onWarningThreshold}),n}return n})(),l=e(new Set),a=e(t.onTimeExpired);a.current=t.onTimeExpired,n(()=>{if(!i.isInitialized)return;c.current&&clearInterval(c.current),o.current=!1,l.current=new Set;const n=()=>{const n=i.syncRemainingSeconds();for(const e of s)n<=e.seconds&&!l.current.has(e.seconds)&&(l.current.add(e.seconds),e.callback?.());n<=0&&(c.current&&(clearInterval(c.current),c.current=null),o.current||(o.current=!0,a.current()))};c.current=setInterval(n,1e3);const e=()=>{"visible"===document.visibilityState&&n()};return document.addEventListener("visibilitychange",e),window.addEventListener("focus",e),()=>{c.current&&(clearInterval(c.current),c.current=null),document.removeEventListener("visibilitychange",e),window.removeEventListener("focus",e)}},[i.isInitialized]);const u=function(n,e){let r="none";for(const t of e)if(n<=t.seconds&&"none"!==t.level){if("critical"===t.level)return"critical";"warning"===t.level&&(r="warning")}return r}(i.remainingSeconds,s);return{remainingSeconds:i.remainingSeconds,warningLevel:u}}

package/dist/components/exams/take/hooks/useProctoringCamera.d.ts

@@ -0,0 +1,19 @@
+import type { ExamTakingSdkApi } from '../../../../api/exam-taking';
+interface UseProctoringCameraProps {
+    /** Injected API adapter (replaces the host app's `attemptsApi`). */
+    api: ExamTakingSdkApi;
+    attemptId: string | null;
+    intervalMs?: number;
+    /**
+     * Gate camera capture. The host app previously gated on
+     * `NEXT_PUBLIC_ENABLE_PROCTORING_CAMERA`; expose it as a prop so the SDK does
+     * not read host env vars. Defaults to `false` (disabled).
+     */
+    enabled?: boolean;
+}
+export declare function useProctoringCamera({ api, attemptId, intervalMs, enabled, }: UseProctoringCameraProps): {
+    isCameraActive: boolean;
+    cameraError: string;
+    snapshotCount: number;
+};
+export {};

package/dist/components/exams/take/hooks/useProctoringCamera.js

@@ -0,0 +1 @@
+import{useEffect as e,useRef as r,useState as t}from"react";export function useProctoringCamera({api:n,attemptId:a,intervalMs:o=1e4,enabled:c=!1}){const[i,u]=t(!1),[l,s]=t(null),[d,m]=t(0),p=r(null),h=r(null),g=r(null);return e(()=>{if("undefined"==typeof window)return;if(!c)return;let e=!0;return(async()=>{try{const r=await navigator.mediaDevices.getUserMedia({video:{facingMode:"user"},audio:!1});if(!e)return void r.getTracks().forEach(e=>e.stop());h.current=r;const t=document.createElement("video");t.srcObject=r,t.muted=!0,t.playsInline=!0,t.onloadedmetadata=()=>{e&&(t.play().catch(console.error),u(!0),s(null))},p.current=t}catch(r){console.error("Camera permission denied or error:",r),e&&(u(!1),s(r.message||"Camera access denied"))}})(),()=>{e=!1,h.current&&(h.current.getTracks().forEach(e=>e.stop()),h.current=null),u(!1),p.current=null}},[c]),e(()=>{if(!a||!i||!p.current)return void(g.current&&(clearInterval(g.current),g.current=null));return g.current=setInterval(async()=>{const e=p.current;if(e&&e.videoWidth)try{const r=document.createElement("canvas");r.width=e.videoWidth,r.height=e.videoHeight;const t=r.getContext("2d");if(!t)return;t.drawImage(e,0,0,r.width,r.height),r.toBlob(async e=>{if(e)try{await(n.uploadProctoringSnapshot?.({attemptId:a,imageBlob:e})),m(e=>e+1)}catch(e){console.error("Failed to upload proctoring snapshot:",e)}},"image/jpeg",.6)}catch(e){console.error("Error in capture process:",e)}},o),()=>{g.current&&(clearInterval(g.current),g.current=null)}},[n,a,i,o]),{isCameraActive:i,cameraError:l,snapshotCount:d}}

package/dist/components/exams/take/hooks/useProctoringSnapshot.d.ts

@@ -0,0 +1,25 @@
+import type { ExamTakingSdkApi } from '../../../../api/exam-taking';
+export interface UseProctoringSnapshotOptions {
+    /** API adapter; snapshots are skipped when `uploadProctoringSnapshot` is undefined. */
+    api: ExamTakingSdkApi;
+    /** Active attempt id, or null while loading. */
+    attemptId: string | null;
+    /** Whether proctoring is active (attempt loaded, room requires proctoring). */
+    enabled: boolean;
+    /** Interval between snapshot uploads in milliseconds. */
+    intervalMs?: number;
+    /** Notified when a snapshot capture/upload fails (best-effort logging). */
+    onError?: (error: unknown) => void;
+}
+export interface UseProctoringSnapshotResult {
+    /** Attach to a `<video>` element rendering the proctoring webcam stream. */
+    videoRef: React.RefObject<HTMLVideoElement | null>;
+    /** `true` once the webcam stream is live and snapshots are being captured. */
+    isActiveRef: React.MutableRefObject<boolean>;
+}
+/**
+ * Captures periodic webcam snapshots and uploads them for proctoring. Owns the
+ * camera stream lifecycle (request on enable, stop on cleanup) and encodes
+ * frames off a hidden canvas, mirroring the host app's proctoring loop.
+ */
+export declare function useProctoringSnapshot({ api, attemptId, enabled, intervalMs, onError, }: UseProctoringSnapshotOptions): UseProctoringSnapshotResult;

package/dist/components/exams/take/hooks/useProctoringSnapshot.js

@@ -0,0 +1 @@
+"use client";import{useEffect as t,useRef as e}from"react";export function useProctoringSnapshot({api:r,attemptId:n,enabled:a,intervalMs:i=6e4,onError:o}){const c=e(null),s=e(!1),u=e(o);return u.current=o,t(()=>{if(!a||!n||!r.uploadProctoringSnapshot)return;if("undefined"==typeof navigator||!navigator.mediaDevices?.getUserMedia)return;let t=null,e=null,o=!1;const d=async()=>{const t=c.current;if(!t||0===t.videoWidth||!r.uploadProctoringSnapshot)return;const e=document.createElement("canvas");e.width=t.videoWidth,e.height=t.videoHeight;const a=e.getContext("2d");if(!a)return;a.drawImage(t,0,0,e.width,e.height);const i=await new Promise(t=>e.toBlob(t,"image/jpeg",.7));if(i)try{await r.uploadProctoringSnapshot({attemptId:n,imageBlob:i})}catch(t){u.current?.(t)}};return(async()=>{try{if(t=await navigator.mediaDevices.getUserMedia({video:!0,audio:!1}),o)return void t.getTracks().forEach(t=>t.stop());c.current&&(c.current.srcObject=t,await c.current.play().catch(()=>{})),s.current=!0,d(),e=setInterval(()=>{d()},i)}catch(t){u.current?.(t)}})(),()=>{o=!0,s.current=!1,e&&clearInterval(e),t&&t.getTracks().forEach(t=>t.stop())}},[r,n,a,i]),{videoRef:c,isActiveRef:s}}

package/dist/components/exams/take/hooks/useSpeakingConversationAudio.d.ts

@@ -0,0 +1,19 @@
+export type ConversationPlaybackPhase = 'idle' | 'playing-interlocutor' | 'playing-partner' | 'ready';
+export interface UseSpeakingConversationAudioOptions {
+    /** S3 key or direct URL for the interlocutor's audio */
+    interlocutorAudioUrl?: string;
+    /** S3 key or direct URL for the partner's audio */
+    partnerAudioUrl?: string;
+    /** Called once when the full sequence has finished */
+    onSequenceComplete: () => void;
+}
+export interface UseSpeakingConversationAudioReturn {
+    phase: ConversationPlaybackPhase;
+    isPlaying: boolean;
+    replayAll: () => void;
+    togglePlayPause: () => void;
+    currentAudioUrl: string;
+    currentTime: number;
+    duration: number;
+}
+export declare function useSpeakingConversationAudio({ interlocutorAudioUrl, partnerAudioUrl, onSequenceComplete, }: UseSpeakingConversationAudioOptions): UseSpeakingConversationAudioReturn;

package/dist/components/exams/take/hooks/useSpeakingConversationAudio.js

@@ -0,0 +1 @@
+import{useCallback as e,useEffect as r,useRef as t,useState as n}from"react";import{usePresignedFileUrl as u}from"../../../../shared/lib/hooks/usePresignedFileUrl";export function useSpeakingConversationAudio({interlocutorAudioUrl:a,partnerAudioUrl:i,onSequenceComplete:o}){const[c,l]=n("idle"),[d,s]=n(0),[p,y]=n(0),{previewUrl:m}=u(a??""),{previewUrl:g}=u(i??""),v=t(null),A=t(o);r(()=>{A.current=o},[o]);const E=t(m),L=t(g);r(()=>{E.current=m},[m]),r(()=>{L.current=g},[g]);const U=e(()=>{const e=v.current;e&&(e.pause(),e.src="")},[]),h=e(e=>{let r=v.current;r||(r=new Audio,v.current=r),r.src=e,r.play().catch(()=>{})},[]);r(()=>{let e=v.current;e||(e=new Audio,v.current=e);const r=()=>{l(e=>{if("playing-interlocutor"===e){const e=L.current;e?setTimeout(()=>{l("playing-partner"),h(e)},0):setTimeout(()=>{l("ready"),A.current()},0)}else"playing-partner"===e&&setTimeout(()=>{l("ready"),A.current()},0);return e})},t=()=>{e&&s(e.currentTime)},n=()=>{e&&(y(e.duration),s(0))};return e.addEventListener("ended",r),e.addEventListener("timeupdate",t),e.addEventListener("loadedmetadata",n),()=>{e.removeEventListener("ended",r),e.removeEventListener("timeupdate",t),e.removeEventListener("loadedmetadata",n)}},[h]),r(()=>(U(),l("idle"),m||g?(m?(l("playing-interlocutor"),h(m)):g&&(l("playing-partner"),h(g)),()=>{U()}):(l("ready"),void A.current())),[m,g]),r(()=>()=>{U()},[]);const T=e(()=>{U(),E.current?(l("playing-interlocutor"),h(E.current)):L.current?(l("playing-partner"),h(L.current)):(l("ready"),A.current())},[U,h]),f=e(()=>{const e=v.current;e&&(e.paused?e.play().catch(()=>{}):e.pause())},[]);return{phase:c,isPlaying:Boolean(v.current&&!v.current.paused),replayAll:T,togglePlayPause:f,currentAudioUrl:"playing-interlocutor"===c?m??"":"playing-partner"===c?g??"":"",currentTime:d,duration:p}}

package/dist/components/exams/take/hooks/useSpeakingNavigation.d.ts

@@ -0,0 +1,37 @@
+import type { ApiQuestion } from '../utils/question-transformers';
+/**
+ * A speaking question enriched with part metadata.
+ * Extends ApiQuestion with part display info and a stable exam-wide index.
+ */
+export interface SpeakingQuestion extends ApiQuestion {
+    partName: string;
+    /** 0-based index within the full flattened exam question list */
+    questionIndex: number;
+}
+export interface UseSpeakingNavigationOptions {
+    questions: SpeakingQuestion[];
+    initialIndex?: number;
+}
+export interface UseSpeakingNavigationReturn {
+    /** 0-based index of the currently displayed question */
+    currentIndex: number;
+    /** Currently displayed question, or null if questions list is empty */
+    currentQuestion: SpeakingQuestion | null;
+    /** Total number of questions across all parts */
+    totalQuestions: number;
+    /** part_no of the current question */
+    currentPartNo: number;
+    /** Display name of the current part (e.g. "Part 1") */
+    currentPartName: string;
+    /**
+     * 1-based question number within the current part.
+     * Used for "CÂU HỎI SỐ [N]" display label.
+     */
+    questionNumberInPart: number;
+    canGoPrev: boolean;
+    canGoNext: boolean;
+    goNext: () => void;
+    goPrev: () => void;
+    goTo: (index: number) => void;
+}
+export declare function useSpeakingNavigation(options: UseSpeakingNavigationOptions): UseSpeakingNavigationReturn;

package/dist/components/exams/take/hooks/useSpeakingNavigation.js

@@ -0,0 +1 @@
+import{useState as t,useCallback as n,useMemo as r}from"react";export function useSpeakingNavigation(e){const{questions:o,initialIndex:a=0}=e,[i,u]=t(a),c=o.length,s=o[i]??null,l=s?.part_no??1,g=s?.partName??"",m=r(()=>{if(!s)return 1;return o.slice(0,i).filter(t=>t.part_no===s.part_no).length+1},[i,s,o]),p=i>0,N=i<c-1,x=n(()=>{u(t=>Math.min(t+1,c-1))},[c]),P=n(()=>{u(t=>Math.max(t-1,0))},[]),f=n(t=>{t>=0&&t<c&&u(t)},[c]);return{currentIndex:i,currentQuestion:s,totalQuestions:c,currentPartNo:l,currentPartName:g,questionNumberInPart:m,canGoPrev:p,canGoNext:N,goNext:x,goPrev:P,goTo:f}}

package/dist/components/exams/take/hooks/useSpeakingRecorder.d.ts

@@ -1,8 +1,48 @@
-export type SpeakingRecorderStatus = 'idle' | 'recording' | 'recorded' | 'uploading' | 'uploaded' | 'error';
-export declare function useSpeakingRecorder(_options?: unknown): {
-    status: SpeakingRecorderStatus;
-    previewUrl: string;
+export type RecordingStatus = 'idle' | 'recording' | 'recorded' | 'uploading' | 'uploaded' | 'error';
+export interface UseSpeakingRecorderOptions {
+    /** Attempt ID — needed for upload endpoint */
+    attemptId: string;
+    /** Question ID — needed for upload endpoint */
+    questionId: string;
+    /** Max recording duration in ms (default: 30000) */
+    maxDurationMs?: number;
+    /** Called with S3 key when upload completes */
+    onRecordingComplete: (audioKey: string, forQuestionId?: string) => void;
+    /** Called on any non-retryable error */
+    onError?: (error: string) => void;
+    /** Existing S3 key from a previous recording (used to restore playback on navigation) */
+    existingAnswerKey?: string;
+}
+export interface UseSpeakingRecorderReturn {
+    /** Current recording status */
+    status: RecordingStatus;
+    /** Countdown while recording (counts down from maxDurationMs/1000) */
     remainingSeconds: number;
+    /** True when remainingSeconds <= 5 */
+    isWarning: boolean;
+    /** Elapsed seconds while recording */
+    durationSeconds: number;
+    /** Local blob URL for playback preview (available after recording stops) */
+    previewUrl: string | null;
+    /** Uploaded S3 key (available after upload completes) */
+    uploadedKey: string | null;
+    /** Error message if status === 'error' */
+    error: string | null;
+    /** Whether the browser supports MediaRecorder API */
+    isSupported: boolean;
+    /** True when attempt has expired — caller should redirect */
+    isAttemptExpired: boolean;
+    /** Live transcript text (STREAMING mode only — null in RECORDING mode) */
+    liveTranscript: string | null;
+    /** Start recording. Requests microphone permission if not granted. */
     startRecording: () => Promise<void>;
+    /** Stop recording. Automatically triggers upload. */
     stopRecording: () => void;
-};
+    /** Discard current recording and reset to idle */
+    resetRecording: () => void;
+    /** Re-record: discard current recording and start a new one */
+    reRecord: () => Promise<void>;
+    /** Retry upload with the existing blob (no re-record required) */
+    retryUpload: () => Promise<void>;
+}
+export declare function useSpeakingRecorder(options: UseSpeakingRecorderOptions): UseSpeakingRecorderReturn;

package/dist/components/exams/take/hooks/useSpeakingRecorder.js

@@ -1 +1 @@
-"use client";import{useRef as e,useState as r}from"react";export function useSpeakingRecorder(t){const n=e(null),a=e([]),[o,c]=r("idle"),[i,s]=r(null);return{status:o,previewUrl:i,remainingSeconds:0,startRecording:async()=>{const e=await navigator.mediaDevices.getUserMedia({audio:!0});a.current=[];const r=new MediaRecorder(e);n.current=r,r.ondataavailable=e=>a.current.push(e.data),r.onstop=()=>{e.getTracks().forEach(e=>e.stop()),s(URL.createObjectURL(new Blob(a.current,{type:"audio/webm"}))),c("recorded")},r.start(),c("recording")},stopRecording:()=>n.current?.stop()}}
+import{useState as r,useRef as e,useEffect as n,useCallback as t}from"react";import{usePresignedFileUrl as u}from"../../../../shared/lib/hooks";import{useExamTakingApi as o}from"../ExamTakingApiContext";export function useSpeakingRecorder(i){const c=i.maxDurationMs??3e4,a=Math.floor(c/1e3),d=o(),s=e(d);s.current=d;const l=e(i.onRecordingComplete),p=e(i.onError);l.current=i.onRecordingComplete,p.current=i.onError;const g=e(i.attemptId),m=e(i.questionId);g.current=i.attemptId,m.current=i.questionId;const[h,y]=r("idle"),[w,f]=r(a),[A,v]=r(0),[R,T]=r(null),[E,x]=r(null),[I,b]=r(null),[K,M]=r(!1),k=e(null),P=e(null),D=e([]),S=e(null),U=e(null),O=e(""),_=e(0),q=e(null),L=e(void 0),B=e(0),V=e(!0),C=e(""),G="undefined"!=typeof MediaRecorder,{previewUrl:j}=u(i.existingAnswerKey),N=t(()=>{S.current&&(clearInterval(S.current),S.current=null)},[]),F=t(()=>{U.current&&(U.current.startsWith("blob:")&&URL.revokeObjectURL(U.current),U.current=null)},[]),W=t(()=>{P.current&&(P.current.getTracks().forEach(r=>r.stop()),P.current=null)},[]),X=t(async(r,e,n,t)=>{if(!V.current)return;const u=t||C.current||m.current;m.current===u&&y("uploading");const o=g.current;if("mock-attempt-speaking"===o){if(await new Promise(r=>setTimeout(r,500)),!V.current)return;const r=`mock-audio-key-${u}`;return m.current===u&&(y("uploaded"),x(r)),l.current(r,u),q.current=null,void(L.current=void 0)}try{if(!s.current.uploadAudioAnswer)throw new Error("uploadAudioAnswer is not implemented by the provided API adapter.");const n=(i=await s.current.uploadAudioAnswer({attemptId:o,questionId:u,audioBlob:r,durationMs:e}))&&"object"==typeof i&&"data"in i?i.data:i;if(!V.current)return;const t=n.audioKey??"";m.current===u&&(y("uploaded"),x(t)),l.current(t,u),q.current=null,L.current=void 0,B.current=0,s.current.realtimeGradeSingle?.({attemptId:o,questionId:u,audioKey:t}).catch(r=>{console.debug("[Realtime Grading] Skipped or failed:",r?.response?.status??r?.message)})}catch(u){if(!V.current)return;const o=u,i=o?.response?.data?.code;if("ATTEMPT_EXPIRED"===i||"ATTEMPT_NOT_IN_PROGRESS"===i){const r="ATTEMPT_EXPIRED"===i?"Bài thi đã hết giờ":"Bài thi đã được nộp.";return y("error"),b(r),M(!0),void p.current?.(r)}if("AUDIO_FILE_TOO_LARGE"===i){const r="Bài ghi âm quá dài. Vui lòng ghi âm ngắn hơn.";return y("error"),b(r),void p.current?.(r)}if(n<3){const u=1e3*Math.pow(2,n);if(await new Promise(r=>setTimeout(r,u)),!V.current)return;B.current=n+1,await X(r,e,n+1,t)}else{const r="Tải lên bản ghi âm thất bại. Vui lòng thử lại.";y("error"),b(r),p.current?.(r)}}var i},[]),z=t(async(r,e,n)=>{q.current=r,L.current=e,B.current=0,await X(r,e,0,n)},[X]),$=t(async()=>{if(i.existingAnswerKey)return y("uploaded"),void x(i.existingAnswerKey);if(!G){const r="Trình duyệt này không hỗ trợ ghi âm. Vui lòng dùng Chrome, Firefox hoặc Edge.";return y("error"),b(r),void p.current?.(r)}const r=function(){if("undefined"==typeof MediaRecorder)return null;const r=["audio/webm;codecs=opus","audio/webm","audio/mp4","audio/ogg;codecs=opus","audio/ogg"];for(const e of r)if(MediaRecorder.isTypeSupported(e))return e;return null}();if(!r){const r="Trình duyệt không hỗ trợ định dạng ghi âm.";return y("error"),b(r),void p.current?.(r)}try{const e=await navigator.mediaDevices.getUserMedia({audio:!0});P.current=e,O.current=r;const n=new MediaRecorder(e,{mimeType:r});k.current=n,D.current=[],n.ondataavailable=r=>{r.data.size>0&&D.current.push(r.data)},n.onstop=()=>{const r=Date.now()-_.current,e=new Blob(D.current,{type:O.current}),n=URL.createObjectURL(e),t=C.current;F(),U.current=n,T(n),y("recorded"),z(e,r,t)},n.start(),_.current=Date.now(),C.current=m.current,y("recording"),v(0),f(a),b(null),x(null),T(null),M(!1),S.current=setInterval(()=>{v(r=>r+1),f(r=>{const e=Math.max(0,r-1);return 0===e&&(N(),k.current&&"recording"===k.current.state&&k.current.stop(),W()),e})},1e3)}catch(r){W();const e=r instanceof DOMException&&("NotAllowedError"===r.name||"PermissionDeniedError"===r.name)?"Vui lòng cấp quyền truy cập microphone trong trình duyệt.":"Không thể truy cập microphone. Vui lòng thử lại.";y("error"),b(e),p.current?.(e)}},[G,a,i.existingAnswerKey,N,W,z,F]),H=t(()=>{N(),k.current&&"recording"===k.current.state&&k.current.stop(),W()},[N,W]),J=t(()=>{N(),W(),k.current&&"recording"===k.current.state&&k.current.stop(),k.current=null,D.current=[],q.current=null,L.current=void 0,B.current=0,F(),T(null),x(null),v(0),f(a),b(null),y("idle"),M(!1)},[N,W,F,a]),Q=t(async()=>{if(i.existingAnswerKey)return y("uploaded"),void x(i.existingAnswerKey);J(),await $()},[i.existingAnswerKey,J,$]),Y=t(async()=>{const r=q.current;r&&(B.current=0,await X(r,L.current,0,C.current||void 0))},[X]);n(()=>{J()},[i.questionId]),n(()=>{"idle"===h&&j&&i.existingAnswerKey&&!R&&(T(j),U.current=j,x(i.existingAnswerKey),y("uploaded"))},[h,j,i.existingAnswerKey,R]),n(()=>(V.current=!0,()=>{V.current=!1,N(),k.current&&"recording"===k.current.state&&k.current.stop(),W(),F()}),[]);return{status:h,remainingSeconds:w,isWarning:w<=5&&"recording"===h,durationSeconds:A,previewUrl:R,uploadedKey:E,error:I,isSupported:G,isAttemptExpired:K,liveTranscript:null,startRecording:$,stopRecording:H,resetRecording:J,reRecord:Q,retryUpload:Y}}

package/dist/components/exams/take/hooks/useSpeakingRendererSetup.d.ts

@@ -0,0 +1,39 @@
+import { type SpeakingQuestion } from './useSpeakingNavigation';
+import type { QuestionPart } from '../utils/question-transformers';
+export interface UseSpeakingRendererSetupOptions {
+    part: QuestionPart;
+    answers: Record<string, unknown>;
+    onAnswerChange: (questionId: string, value: unknown) => void;
+    onPartComplete?: () => void;
+    onPartBack?: () => void;
+    maxDurationMs?: number;
+    hasMic?: boolean;
+    initialQuestionIndex?: number;
+    currentQuestionIndex?: number;
+}
+export declare function useSpeakingRendererSetup({ part, answers, onAnswerChange, onPartComplete, onPartBack, maxDurationMs, hasMic, initialQuestionIndex, currentQuestionIndex, }: UseSpeakingRendererSetupOptions): {
+    nav: {
+        showPrev: boolean;
+        showNext: boolean;
+        canGoPrev: boolean;
+        canGoNext: boolean;
+        currentIndex: number;
+        currentQuestion: SpeakingQuestion | null;
+        totalQuestions: number;
+        currentPartNo: number;
+        currentPartName: string;
+        questionNumberInPart: number;
+        goNext: () => void;
+        goPrev: () => void;
+        goTo: (index: number) => void;
+    };
+    recorder: import("./useSpeakingRecorder").UseSpeakingRecorderReturn;
+    currentQuestion: SpeakingQuestion;
+    handleNext: () => void;
+    handlePrev: () => void;
+    showExistingBadge: boolean;
+    isRecordingInProgress: boolean;
+    isQuestionLocked: boolean;
+    isPostRecordingDelayActive: boolean;
+    onAudioPlayingChange: (playing: boolean) => void;
+};

package/dist/components/exams/take/hooks/useSpeakingRendererSetup.js

@@ -0,0 +1 @@
+import{useEffect as e,useMemo as r,useCallback as t,useRef as n,useState as o}from"react";import{toast as i}from"../../../../shared/lib/toast";import{useExamTakingStore as s}from"../../../../shared/lib/stores/examTakingStore";import{useSpeakingNavigation as a}from"./useSpeakingNavigation";import{useSpeakingRecorder as c}from"./useSpeakingRecorder";export function useSpeakingRendererSetup({part:u,answers:d,onAnswerChange:m,onPartComplete:l,onPartBack:p,maxDurationMs:x=3e4,hasMic:g=!0,initialQuestionIndex:v=0,currentQuestionIndex:h}){const P=r(()=>u.questions.map((e,r)=>({...e,partName:u.name||`Part ${e.part_no}`,questionIndex:r})),[u.questions,u.name]),I=a({questions:P,initialIndex:v});e(()=>{void 0!==h&&h>=0&&h!==I.currentIndex&&I.goTo(h)},[h,I.currentIndex,I]);const N=I.currentQuestion,{attemptId:G}=s(),f=N?d[N.id]:void 0,k=!!f,w=c({attemptId:G??"",questionId:N?.id??"",maxDurationMs:x,existingAnswerKey:g?f:void 0,onRecordingComplete:(e,r)=>{const t=r||N?.id;t&&m(t,e)},onError:e=>i.error(e)});e(()=>{g&&w.isAttemptExpired&&i.error("Bài thi đã hết giờ hoặc đã được nộp.")},[g,w.isAttemptExpired]);const A=g&&"recording"===w.status,T=n(A),q=n(null),[Q,R]=o(!1);e(()=>{g?(T.current&&!A&&(R(!0),q.current&&clearTimeout(q.current),q.current=setTimeout(()=>{R(!1),q.current=null},500)),A&&q.current&&(clearTimeout(q.current),q.current=null,R(!1)),T.current=A):R(!1)},[g,A]),e(()=>()=>{q.current&&clearTimeout(q.current)},[]);const[S,C]=o(!1),D=t(e=>{C(e)},[]);e(()=>{C(!1)},[N?.id]);const E=A||Q||S,{setIsNavDisabled:b}=s();e(()=>(b(E),()=>b(!1)),[E,b]);const y=t(()=>{E||(I.canGoNext?I.goNext():l?.())},[I,E,l]),B=t(()=>{E||(I.canGoPrev?I.goPrev():p?.())},[I,E,p]),M=r(()=>({...I,showPrev:I.canGoPrev||!!p,showNext:I.canGoNext||!!l,canGoPrev:!E&&(I.canGoPrev||!!p),canGoNext:!E&&(I.canGoNext||!!l)}),[I,E,p,l]),K=!(!f||g&&"idle"!==w.status);return{nav:M,recorder:g?w:null,currentQuestion:N,handleNext:y,handlePrev:B,showExistingBadge:K,isRecordingInProgress:A,isQuestionLocked:k,isPostRecordingDelayActive:Q,onAudioPlayingChange:D}}

package/dist/components/exams/take/hooks/useToeicAudio.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Hook to manage TOEIC audio playback state across questions
+ *
+ * Features:
+ * - Track current audio URL for the part
+ * - Pause audio when switching questions
+ * - Reset audio state when part changes
+ * - Provide audio loading state
+ */
+export declare function useToeicAudio(): {
+    currentAudioUrl: string;
+    isPlayingPartAudio: boolean;
+    isAudioLoading: boolean;
+    setPartAudio: (audioUrl: string | null) => void;
+    setAudioLoading: (loading: boolean) => void;
+    setAudioPlaying: (playing: boolean) => void;
+};

package/dist/components/exams/take/hooks/useToeicAudio.js

@@ -0,0 +1 @@
+import{useState as i,useCallback as o}from"react";export function useToeicAudio(){const[t,u]=i(null),[r,n]=i(!1),[d,e]=i(!1);return{currentAudioUrl:t,isPlayingPartAudio:r,isAudioLoading:d,setPartAudio:o(i=>{u(i),n(!1),e(!1)},[]),setAudioLoading:o(i=>{e(i)},[]),setAudioPlaying:o(i=>{n(i)},[])}}

package/dist/components/exams/take/index.d.ts

@@ -3,4 +3,12 @@ export type { ExamTakingPageContainerProps } from './ExamTakingPageContainer';
 export { GenericQuestionRenderer } from './GenericQuestionRenderer';
 export type { GenericQuestionRendererProps } from './GenericQuestionRenderer';
 export type { ExamTakingPart } from './exam-taking.utils';
-export type { ExamTakingAnswerValue, ExamTakingAttempt, ExamTakingQuestion, ExamTakingQuestionsResult, ExamTakingSdkApi, ExamTakingTemplatePart, SaveExamTakingAnswersInput } from './types';
+export type { ExamTakingAnswerValue, ExamTakingAttempt, ExamTakingQuestion, ExamTakingQuestionsResult, ExamTakingSdkApi, ExamTakingTemplatePart, SaveExamTakingAnswersInput } from '../../../api/exam-taking';
+export { useExamCountdown } from './hooks/useExamCountdown';
+export type { UseExamCountdownOptions, UseExamCountdownResult } from './hooks/useExamCountdown';
+export { useAnswerAutosave } from './hooks/useAnswerAutosave';
+export type { UseAnswerAutosaveOptions, UseAnswerAutosaveResult } from './hooks/useAnswerAutosave';
+export { useProctoringSnapshot } from './hooks/useProctoringSnapshot';
+export type { UseProctoringSnapshotOptions, UseProctoringSnapshotResult } from './hooks/useProctoringSnapshot';
+export { useAttemptSubmit } from './hooks/useAttemptSubmit';
+export type { UseAttemptSubmitOptions, UseAttemptSubmitResult, SubmittedSummary } from './hooks/useAttemptSubmit';

package/dist/components/exams/take/index.js

@@ -1 +1 @@
-export{ExamTakingPageContainer}from"./ExamTakingPageContainer";export{GenericQuestionRenderer}from"./GenericQuestionRenderer";
+export{ExamTakingPageContainer}from"./ExamTakingPageContainer";export{GenericQuestionRenderer}from"./GenericQuestionRenderer";export{useExamCountdown}from"./hooks/useExamCountdown";export{useAnswerAutosave}from"./hooks/useAnswerAutosave";export{useProctoringSnapshot}from"./hooks/useProctoringSnapshot";export{useAttemptSubmit}from"./hooks/useAttemptSubmit";

package/dist/components/exams/take/types/speaking-cue-card.types.d.ts

@@ -0,0 +1,10 @@
+export interface SpeakingCueCardContent {
+    /** Rich text HTML content of the cue card — generated by Tiptap Editor */
+    cueCardHtml: string;
+    /** Preparation time in seconds (default: 60) */
+    prepTimeSeconds?: number;
+    /** Max speaking time in seconds (default: 120) */
+    speakingTimeSeconds?: number;
+    /** Backup question flag */
+    isBackup?: boolean;
+}

package/dist/components/exams/take/types/speaking-cue-card.types.js

@@ -0,0 +1 @@
+export{};

package/dist/components/exams/take/types/speaking.types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Speaking exam types — Cambridge Movers/Flyers
+ *
+ * Covers all 4 speaking question types rendered in the student exam-taking view.
+ * These match the `content` and `questionGroup.payload` shapes from the API.
+ */
+export interface CompareImagesContent {
+    audioUrl: string;
+    isBackup?: boolean;
+}
+export interface CompareImagesGroupPayload {
+    candidateImageUrl: string;
+    examinerImageUrl: string;
+}
+export interface StoryImagesContent {
+    audioUrl: string;
+    images: string[];
+    isBackup?: boolean;
+}
+export interface OddOneOutContent {
+    audioUrl: string;
+    activeImageId?: string;
+    images?: string[];
+    isBackup?: boolean;
+}
+export interface OddOneOutGroupPayload {
+    images: Array<{
+        id: string;
+        url: string;
+        label: string;
+    }>;
+}
+export interface QuestionListContent {
+    audioUrl: string;
+    activeQuestionId: string;
+    isBackup?: boolean;
+}
+export interface QuestionListGroupPayload {
+    content?: Array<{
+        id: string;
+        text: string;
+    }>;
+    questions?: Array<{
+        id: string;
+        text: string;
+    }>;
+}
+export interface InfoExchangeContent {
+    audioUrl: string;
+    isBackup?: boolean;
+}
+export interface InfoExchangeGroupPayload {
+    title: string;
+    imageUrl: string;
+    candidateFields: Array<{
+        key: string;
+        answer: string;
+    }>;
+    examinerFields: Array<{
+        key: string;
+        answer: string;
+    }>;
+}
+export interface ReadDisplayedContentContent {
+    /** The reference text passage the student must read aloud */
+    referenceText: string;
+    /** Optional: audio URL of a model/native pronunciation for reference */
+    modelAudioUrl?: string;
+    /** Optional: difficulty tag for the passage */
+    difficultyTag?: 'BASIC_PHONICS' | 'DAILY_ROUTINE' | 'DESCRIPTIVE_EMOTIONAL';
+    /** Backup flag - consistent with other speaking types */
+    isBackup?: boolean;
+}
+export interface SpontaneousQAContent {
+    /** How the admin created this question: uploaded audio or entered text */
+    inputType: 'AUDIO' | 'TEXT';
+    /** Audio URL — always present at client render time */
+    audioUrl?: string;
+    /** Question text — only visible in admin/review mode, not shown to student */
+    questionText?: string;
+    /** Backup flag — consistent with other speaking types */
+    isBackup?: boolean;
+}
+export interface GNSpeakingInterviewContent {
+    /** Examiner's question text */
+    questionText: string;
+    /** Audio URL for examiner's question (TTS or uploaded) */
+    audioUrl?: string;
+    /** How admin created the question */
+    inputType: 'AUDIO' | 'TEXT';
+    /** Which candidate this question is addressed to */
+    targetCandidate: 'VIRTUAL' | 'REAL';
+    /** Booklet image URL — collage for Part 2 Discussion with Pictures */
+    imageUrl?: string;
+    /** Virtual student's pre-recorded answer (filled by admin) */
+    virtualAnswer?: {
+        /** Text of the virtual student's answer */
+        answerText: string;
+        /** Audio URL — admin uploads or auto-generates via TTS */
+        audioUrl?: string;
+    };
+    /** Whether this is an Extended Response question */
+    isExtendedResponse?: boolean;
+    /** Backup flag */
+    isBackup?: boolean;
+}
+export interface GNSpeakingInterviewGroupPayload {
+    /** Which candidate role is virtual (pre-recorded) */
+    virtualCandidate: 'A' | 'B';
+    /** Virtual student display name */
+    virtualStudentName?: string;
+    /** Virtual student avatar image URL */
+    virtualStudentAvatar?: string;
+}
+/** Answer stored in examTakingStore for speaking questions */
+export interface SpeakingAnswer {
+    audioUrl: string;
+}
+/** Recording state managed by useSpeakingRecorder hook */
+export interface RecordingState {
+    status: 'idle' | 'recording' | 'recorded' | 'uploading' | 'uploaded' | 'error';
+    remainingSeconds: number;
+    isWarning: boolean;
+    durationSeconds: number;
+    audioBlob: Blob | null;
+    audioUrl: string | null;
+    uploadedKey: string | null;
+    error: string | null;
+    isAttemptExpired: boolean;
+}
+/** Response from POST /api/v1/student/attempts/:id/audio-answer */
+export interface UploadAudioAnswerResponse {
+    questionId: string;
+    audioKey: string;
+    answeredAt: string;
+}
+export type SpeakingConversationResponder = 'PARTNER' | 'STUDENT';
+export interface SpeakingConversationContent {
+    interlocutorAudioUrl?: string;
+    partnerAudioUrl?: string;
+    responder: SpeakingConversationResponder;
+    questionText?: string;
+    isBackup?: boolean;
+}
+export interface SpeakingConversationGroupPayload {
+    images?: Array<{
+        id: string;
+        url: string;
+        label: string;
+    }>;
+    partnerName?: string;
+    partnerAvatarUrl?: string;
+}

package/dist/components/exams/take/types/speaking.types.js

@@ -0,0 +1 @@
+export{};