proctor-sdk/dist/index.d.ts

A light-weight proctoring library for some of the commonly used proctoring events

// Type definitions for your-proctor-sdk
// Project: [Link to your project repository if you have one]
// Definitions by: Your Name <your.email@example.com>

// --- Constants ---

/**
 * Defines the types of warnings or violations that the SDK can report.
 */
export declare const WARNING_TYPES: {
  readonly NO_FACE: 'NO_FACE';
  readonly MULTIPLE_FACES: 'MULTIPLE_FACES';
  readonly FULLSCREEN_EXIT: 'FULLSCREEN_EXIT';
  readonly TAB_SWITCH: 'TAB_SWITCH';
  readonly COPY_PASTE_ATTEMPT: 'COPY_PASTE_ATTEMPT';
  readonly MULTIPLE_SCREENS: 'MULTIPLE_SCREENS';
};

/**
* Defines the types of operational statuses the SDK can report.
*/
export declare const STATUS_TYPES: {
  readonly INITIALIZING: 'INITIALIZING';
  readonly MODEL_LOADING: 'MODEL_LOADING';
  readonly MODEL_LOADED: 'MODEL_LOADED';
  readonly WEBCAM_REQUESTING: 'WEBCAM_REQUESTING';
  readonly WEBCAM_READY: 'WEBCAM_READY';
  readonly STARTING: 'STARTING';
  readonly STARTED: 'STARTED';
  readonly STOPPING: 'STOPPING';
  readonly STOPPED: 'STOPPED';
  readonly ERROR: 'ERROR';
  readonly DESTROYED: 'DESTROYED';
};

// --- Data Structures ---

/**
* Data object passed to the onStatusChange callback.
*/
export interface StatusData {
  status: (typeof STATUS_TYPES)[keyof typeof STATUS_TYPES]; // Value from STATUS_TYPES
  message: string;
  error?: Error;
}

/**
* Data object passed to the onViolation callback.
*/
export interface ViolationData {
  type: (typeof WARNING_TYPES)[keyof typeof WARNING_TYPES]; // Value from WARNING_TYPES
  active: boolean;
  message: string;
  timestamp: Date;
  details?: {
      count?: number; // For MULTIPLE_FACES
      eventType?: 'copy' | 'paste' | 'cut'; // For COPY_PASTE_ATTEMPT
      // Add other potential details here
  };
}

// --- Configuration ---

/**
* Configuration options for initializing the ProctorSDK.
*/
export interface ProctorSDKConfig {
  /** The DOM element (or its ID string) where the video feed will be injected. */
  containerElement: HTMLElement | string;

  /** Callbacks for SDK events. */
  callbacks: {
      onStatusChange: (statusData: StatusData) => void;
      onViolation: (violationData: ViolationData) => void;
      onWebcamStreamReady?: (stream: MediaStream) => void;
      onFacePredictions?: (predictions: any[]) => void; // TODO: Define a more specific type for BlazeFace predictions if possible
  };

  /** Flags to enable or disable specific proctoring checks. Defaults to all true. */
  enabledChecks?: {
      faceDetection?: boolean;
      fullscreen?: boolean;
      tabSwitch?: boolean;
      copyPaste?: boolean;
      multipleScreens?: boolean;
  };

  /** Custom paths for TensorFlow.js and BlazeFace models. */
  tfjsModelPaths?: {
      tfjs?: string;
      blazeface?: string;
  };

  /** Custom throttle durations (in ms) for violation event reporting. */
  violationThrottleDurations?: {
      [key in (typeof WARNING_TYPES)[keyof typeof WARNING_TYPES]]?: number;
  };
}

// --- Main SDK Class ---

/**
* ProctorSDK class for web-based proctoring and user monitoring.
*/
declare class ProctorSDK {
  /**
   * Creates an instance of ProctorSDK.
   * @param config Configuration object for the SDK.
   */
  constructor(config: ProctorSDKConfig);

  /**
   * Initiates the proctoring session.
   * Loads models, requests webcam access, and starts monitoring checks.
   * @returns A Promise that resolves when proctoring starts or rejects on critical failure.
   */
  start(): Promise<void>;

  /**
   * Stops the currently active proctoring session.
   * Releases webcam, stops detection loops, and removes event listeners.
   */
  stop(): void;

  /**
   * Checks if proctoring is currently active.
   * @returns True if proctoring is active, false otherwise.
   */
  isProctoringActive(): boolean;

  /**
   * Requests the browser to enter fullscreen mode for the SDK's container or the document.
   * @returns A Promise that resolves if fullscreen is entered, or rejects.
   */
  requestFullscreen(): Promise<void>;

  /**
   * Cleans up all SDK resources and prepares the instance for garbage collection.
   * Should be called when the SDK is no longer needed.
   */
  destroy(): void;

  /**
   * Static property providing access to WARNING_TYPES constants.
   */
  static readonly WARNING_TYPES: typeof WARNING_TYPES;

  /**
   * Static property providing access to STATUS_TYPES constants.
   */
  static readonly STATUS_TYPES: typeof STATUS_TYPES;
}

// Default export of the ProctorSDK class
export default ProctorSDK;