@moveris/shared 2.2.0 → 2.3.0

package/README.md

@@ -426,6 +426,11 @@ const status = getStatusMessage('capturing', DEFAULT_LOCALE);
 | `processing`        | "Processing..."                | API verification in progress |
 | `success`           | "Verification complete"        | Successful completion        |
 | `failed`            | "Verification failed"          | Failed verification          |
+| `eyes_not_visible`  | "Eyes not clearly visible"     | Eye region featureless       |
+| `eyes_shadowed`     | "Eyes are in shadow…"          | Eye region too dark          |
+| `eyes_overexposed`  | "Eye region overexposed…"      | Eye region too bright        |
+| `glasses_glare`     | "Glare detected…"              | Specular highlights on eyes  |
+| `eye_quality_poor`  | "Eye region quality is poor"   | Generic eye quality failure  |
 
 ---
 
@@ -452,6 +457,59 @@ const color = OVAL_GUIDE_COLORS[state];
 
 ---
 
+### Eye Region Quality Analysis
+
+Pre-request eye-region quality gate. Platform-agnostic functions that analyze RGBA pixel data from eye regions to detect shadows, glare, occlusion, and poor visibility.
+
+```typescript
+import {
+  checkEyeRegionQuality,
+  analyzeEyeRegionBrightness,
+  analyzeEyeRegionContrast,
+  detectSpecularHighlights,
+  EYE_QUALITY_THRESHOLDS,
+} from '@moveris/shared';
+
+// Combined quality check (recommended)
+const quality = checkEyeRegionQuality(eyeRegionPixels);
+console.log(quality.passed); // boolean
+console.log(quality.brightness); // 0-255
+console.log(quality.contrast); // standard deviation of luminance
+console.log(quality.hasGlare); // boolean
+console.log(quality.glareRatio); // 0-1
+console.log(quality.message); // user-facing feedback or null
+
+// Individual checks
+const brightness = analyzeEyeRegionBrightness(pixels);
+const contrast = analyzeEyeRegionContrast(pixels);
+const glareRatio = detectSpecularHighlights(pixels);
+```
+
+| Check       | Threshold             | Condition                               |
+| ----------- | --------------------- | --------------------------------------- |
+| Shadowed    | `minBrightness: 40`   | Average luminance too low               |
+| Overexposed | `maxBrightness: 230`  | Average luminance too high              |
+| Glare       | `maxGlareRatio: 0.15` | >15% of pixels are specular highlights  |
+| Occluded    | `minContrast: 12`     | Standard deviation of luminance too low |
+
+Custom thresholds can be passed as a second argument to `checkEyeRegionQuality()`.
+
+### Eye Region Landmarks
+
+Extract bounding boxes for left and right eye regions from MediaPipe 468-point face mesh landmarks.
+
+```typescript
+import { getEyeRegionBounds, EYE_LANDMARK_INDICES, validateFaceLandmarks } from '@moveris/shared';
+
+const bounds = getEyeRegionBounds(landmarks);
+if (bounds) {
+  console.log(bounds.leftEye); // { x, y, width, height } (normalized 0-1)
+  console.log(bounds.rightEye); // { x, y, width, height } (normalized 0-1)
+}
+```
+
+---
+
 ### Frame Analysis Utilities
 
 Utilities for assessing frame quality before submission.
@@ -527,6 +585,10 @@ import type {
   HeadPose,
   FaceLandmarkPoint,
   LandmarkValidationResult,
+  EyeRegionQuality,
+  EyeQualityThresholds,
+  EyeRegionBounds,
+  EyeRegionsBounds,
 } from '@moveris/shared';
 ```
 

package/dist/index.d.mts

@@ -322,6 +322,21 @@ declare const LANDMARK_INDEX: {
     readonly UPPER_LIP: 13;
     readonly LOWER_LIP: 14;
 };
+declare const EYE_LANDMARK_INDICES: {
+    readonly RIGHT_EYE: readonly [33, 7, 163, 144, 145, 153, 154, 155, 133, 173, 157, 158, 159, 160, 161, 246];
+    readonly LEFT_EYE: readonly [362, 382, 381, 380, 374, 373, 390, 249, 263, 466, 388, 387, 386, 385, 384, 398];
+};
+interface EyeRegionBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface EyeRegionsBounds {
+    leftEye: EyeRegionBounds;
+    rightEye: EyeRegionBounds;
+}
+declare function getEyeRegionBounds(landmarks: FaceLandmarkPoint[]): EyeRegionsBounds | null;
 declare const LANDMARK_MIN_BOUND = 0.1;
 declare const LANDMARK_MAX_BOUND = 0.9;
 declare const MIN_LANDMARK_COUNT = 15;
@@ -655,6 +670,11 @@ declare const FEEDBACK_MESSAGES: {
     readonly too_dark: "Low lighting - move to a brighter area";
     readonly backlit: "Backlit - try facing the light source";
     readonly hand_detected: "Remove hand from face";
+    readonly eyes_not_visible: "Eyes not clearly visible";
+    readonly eyes_shadowed: "Eyes are in shadow - improve lighting";
+    readonly eyes_overexposed: "Eye region overexposed - reduce lighting";
+    readonly glasses_glare: "Glare detected - adjust angle or remove glasses";
+    readonly eye_quality_poor: "Eye region quality is poor";
     readonly capturing: "Capturing...";
     readonly almost_done: "Almost done...";
     readonly verification_complete: "Verification complete";
@@ -708,4 +728,25 @@ interface RetryOptions {
 declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 declare function sleep(ms: number): Promise<void>;
 
-export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, type ErrorResponse, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelType, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkFrameQuality, decodeBase64, encodeBase64, generateSessionId, getApiErrorMessage, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+interface EyeRegionQuality {
+    passed: boolean;
+    brightness: number;
+    contrast: number;
+    hasGlare: boolean;
+    glareRatio: number;
+    message: string | null;
+}
+interface EyeQualityThresholds {
+    minBrightness: number;
+    maxBrightness: number;
+    minContrast: number;
+    glarePixelThreshold: number;
+    maxGlareRatio: number;
+}
+declare const EYE_QUALITY_THRESHOLDS: EyeQualityThresholds;
+declare function analyzeEyeRegionBrightness(pixels: Uint8Array | Uint8ClampedArray): number;
+declare function analyzeEyeRegionContrast(pixels: Uint8Array | Uint8ClampedArray, meanBrightness?: number): number;
+declare function detectSpecularHighlights(pixels: Uint8Array | Uint8ClampedArray, threshold?: number): number;
+declare function checkEyeRegionQuality(pixels: Uint8Array | Uint8ClampedArray, thresholds?: EyeQualityThresholds): EyeRegionQuality;
+
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelType, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectSpecularHighlights, encodeBase64, generateSessionId, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.d.ts

@@ -322,6 +322,21 @@ declare const LANDMARK_INDEX: {
     readonly UPPER_LIP: 13;
     readonly LOWER_LIP: 14;
 };
+declare const EYE_LANDMARK_INDICES: {
+    readonly RIGHT_EYE: readonly [33, 7, 163, 144, 145, 153, 154, 155, 133, 173, 157, 158, 159, 160, 161, 246];
+    readonly LEFT_EYE: readonly [362, 382, 381, 380, 374, 373, 390, 249, 263, 466, 388, 387, 386, 385, 384, 398];
+};
+interface EyeRegionBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface EyeRegionsBounds {
+    leftEye: EyeRegionBounds;
+    rightEye: EyeRegionBounds;
+}
+declare function getEyeRegionBounds(landmarks: FaceLandmarkPoint[]): EyeRegionsBounds | null;
 declare const LANDMARK_MIN_BOUND = 0.1;
 declare const LANDMARK_MAX_BOUND = 0.9;
 declare const MIN_LANDMARK_COUNT = 15;
@@ -655,6 +670,11 @@ declare const FEEDBACK_MESSAGES: {
     readonly too_dark: "Low lighting - move to a brighter area";
     readonly backlit: "Backlit - try facing the light source";
     readonly hand_detected: "Remove hand from face";
+    readonly eyes_not_visible: "Eyes not clearly visible";
+    readonly eyes_shadowed: "Eyes are in shadow - improve lighting";
+    readonly eyes_overexposed: "Eye region overexposed - reduce lighting";
+    readonly glasses_glare: "Glare detected - adjust angle or remove glasses";
+    readonly eye_quality_poor: "Eye region quality is poor";
     readonly capturing: "Capturing...";
     readonly almost_done: "Almost done...";
     readonly verification_complete: "Verification complete";
@@ -708,4 +728,25 @@ interface RetryOptions {
 declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 declare function sleep(ms: number): Promise<void>;
 
-export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, type ErrorResponse, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelType, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkFrameQuality, decodeBase64, encodeBase64, generateSessionId, getApiErrorMessage, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+interface EyeRegionQuality {
+    passed: boolean;
+    brightness: number;
+    contrast: number;
+    hasGlare: boolean;
+    glareRatio: number;
+    message: string | null;
+}
+interface EyeQualityThresholds {
+    minBrightness: number;
+    maxBrightness: number;
+    minContrast: number;
+    glarePixelThreshold: number;
+    maxGlareRatio: number;
+}
+declare const EYE_QUALITY_THRESHOLDS: EyeQualityThresholds;
+declare function analyzeEyeRegionBrightness(pixels: Uint8Array | Uint8ClampedArray): number;
+declare function analyzeEyeRegionContrast(pixels: Uint8Array | Uint8ClampedArray, meanBrightness?: number): number;
+declare function detectSpecularHighlights(pixels: Uint8Array | Uint8ClampedArray, threshold?: number): number;
+declare function checkEyeRegionQuality(pixels: Uint8Array | Uint8ClampedArray, thresholds?: EyeQualityThresholds): EyeRegionQuality;
+
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelType, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectSpecularHighlights, encodeBase64, generateSessionId, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.js

@@ -44,6 +44,8 @@ __export(index_exports, {
   ERROR_MESSAGES: () => ERROR_MESSAGES,
   ERROR_MESSAGES_ES: () => ERROR_MESSAGES_ES,
   ES_LOCALE: () => ES_LOCALE,
+  EYE_LANDMARK_INDICES: () => EYE_LANDMARK_INDICES,
+  EYE_QUALITY_THRESHOLDS: () => EYE_QUALITY_THRESHOLDS,
   FACE_CENTER_VERTICAL_OFFSET: () => FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE: () => FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES: () => FEEDBACK_MESSAGES,
@@ -77,18 +79,23 @@ __export(index_exports, {
   RETRY_CONFIG: () => RETRY_CONFIG,
   TARGET_FACE_PERCENTAGE_IN_CROP: () => TARGET_FACE_PERCENTAGE_IN_CROP,
   analyzeBlur: () => analyzeBlur,
+  analyzeEyeRegionBrightness: () => analyzeEyeRegionBrightness,
+  analyzeEyeRegionContrast: () => analyzeEyeRegionContrast,
   analyzeLighting: () => analyzeLighting,
   calculateAdaptiveCropMultiplier: () => calculateAdaptiveCropMultiplier,
   calculateBrightness: () => calculateBrightness,
   calculateFaceAlignment: () => calculateFaceAlignment,
   calculateFaceCropRegion: () => calculateFaceCropRegion,
   canCaptureFrame: () => canCaptureFrame,
+  checkEyeRegionQuality: () => checkEyeRegionQuality,
   checkFrameQuality: () => checkFrameQuality,
   decodeBase64: () => decodeBase64,
+  detectSpecularHighlights: () => detectSpecularHighlights,
   encodeBase64: () => encodeBase64,
   generateSessionId: () => generateSessionId,
   getApiErrorMessage: () => getApiErrorMessage,
   getCaptureQualityFeedback: () => getCaptureQualityFeedback,
+  getEyeRegionBounds: () => getEyeRegionBounds,
   getFeedbackMessage: () => getFeedbackMessage,
   getMinFramesForModel: () => getMinFramesForModel,
   getOvalGuideState: () => getOvalGuideState,
@@ -1161,6 +1168,12 @@ var FEEDBACK_MESSAGES = {
   backlit: "Backlit - try facing the light source",
   // Hand occlusion
   hand_detected: "Remove hand from face",
+  // Eye region quality
+  eyes_not_visible: "Eyes not clearly visible",
+  eyes_shadowed: "Eyes are in shadow - improve lighting",
+  eyes_overexposed: "Eye region overexposed - reduce lighting",
+  glasses_glare: "Glare detected - adjust angle or remove glasses",
+  eye_quality_poor: "Eye region quality is poor",
   // Progress messages
   capturing: "Capturing...",
   almost_done: "Almost done...",
@@ -1212,6 +1225,12 @@ var ES_LOCALE = {
     backlit: "Contraluz - intenta mirar hacia la fuente de luz",
     // Hand occlusion
     hand_detected: "Retira la mano del rostro",
+    // Eye region quality
+    eyes_not_visible: "Ojos no visibles claramente",
+    eyes_shadowed: "Ojos en sombra - mejora la iluminaci\xF3n",
+    eyes_overexposed: "Regi\xF3n de ojos sobreexpuesta - reduce la iluminaci\xF3n",
+    glasses_glare: "Reflejo detectado - ajusta el \xE1ngulo o retira los lentes",
+    eye_quality_poor: "Calidad de la regi\xF3n de ojos insuficiente",
     // Progress messages
     capturing: "Capturando...",
     almost_done: "Casi listo...",
@@ -1645,6 +1664,44 @@ var LANDMARK_INDEX = {
   /** Lower lip center */
   LOWER_LIP: 14
 };
+var EYE_LANDMARK_INDICES = {
+  /** Right eye contour (viewer's left) */
+  RIGHT_EYE: [33, 7, 163, 144, 145, 153, 154, 155, 133, 173, 157, 158, 159, 160, 161, 246],
+  /** Left eye contour (viewer's right) */
+  LEFT_EYE: [362, 382, 381, 380, 374, 373, 390, 249, 263, 466, 388, 387, 386, 385, 384, 398]
+};
+function getEyeRegionBounds(landmarks) {
+  if (landmarks.length < 468) return null;
+  const PADDING = 0.2;
+  function computeBounds(indices) {
+    let minX = 1;
+    let minY = 1;
+    let maxX = 0;
+    let maxY = 0;
+    for (const idx of indices) {
+      const lm = landmarks[idx];
+      if (!lm) continue;
+      if (lm.x < minX) minX = lm.x;
+      if (lm.y < minY) minY = lm.y;
+      if (lm.x > maxX) maxX = lm.x;
+      if (lm.y > maxY) maxY = lm.y;
+    }
+    const width = maxX - minX;
+    const height = maxY - minY;
+    const padX = width * PADDING;
+    const padY = height * PADDING;
+    return {
+      x: Math.max(0, minX - padX),
+      y: Math.max(0, minY - padY),
+      width: Math.min(1 - Math.max(0, minX - padX), width + padX * 2),
+      height: Math.min(1 - Math.max(0, minY - padY), height + padY * 2)
+    };
+  }
+  return {
+    rightEye: computeBounds(EYE_LANDMARK_INDICES.RIGHT_EYE),
+    leftEye: computeBounds(EYE_LANDMARK_INDICES.LEFT_EYE)
+  };
+}
 var LANDMARK_MIN_BOUND = 0.1;
 var LANDMARK_MAX_BOUND = 0.9;
 var MIN_LANDMARK_COUNT = 15;
@@ -1666,6 +1723,115 @@ function validateFaceLandmarks(landmarks) {
   }
   return { valid: true };
 }
+
+// src/utils/eyeRegionAnalysis.ts
+var EYE_QUALITY_THRESHOLDS = {
+  minBrightness: 40,
+  maxBrightness: 230,
+  minContrast: 12,
+  glarePixelThreshold: 240,
+  maxGlareRatio: 0.15
+};
+function rgbaToLuminance(r, g, b) {
+  return 0.299 * r + 0.587 * g + 0.114 * b;
+}
+function analyzeEyeRegionBrightness(pixels) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  let totalLuminance = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    totalLuminance += rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+  }
+  return totalLuminance / pixelCount;
+}
+function analyzeEyeRegionContrast(pixels, meanBrightness) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  const mean = meanBrightness ?? analyzeEyeRegionBrightness(pixels);
+  let sumSqDiff = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const lum = rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+    const diff = lum - mean;
+    sumSqDiff += diff * diff;
+  }
+  return Math.sqrt(sumSqDiff / pixelCount);
+}
+function detectSpecularHighlights(pixels, threshold = EYE_QUALITY_THRESHOLDS.glarePixelThreshold) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  let glareCount = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const lum = rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+    if (lum >= threshold) {
+      glareCount++;
+    }
+  }
+  return glareCount / pixelCount;
+}
+function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
+  if (pixels.length < 4) {
+    return {
+      passed: false,
+      brightness: 0,
+      contrast: 0,
+      hasGlare: false,
+      glareRatio: 0,
+      message: "Eyes not clearly visible"
+    };
+  }
+  const brightness = analyzeEyeRegionBrightness(pixels);
+  const contrast = analyzeEyeRegionContrast(pixels, brightness);
+  const glareRatio = detectSpecularHighlights(pixels, thresholds.glarePixelThreshold);
+  const hasGlare = glareRatio > thresholds.maxGlareRatio;
+  if (brightness < thresholds.minBrightness) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eyes are in shadow - improve lighting"
+    };
+  }
+  if (brightness > thresholds.maxBrightness) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eye region overexposed - reduce lighting"
+    };
+  }
+  if (hasGlare) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Glare detected - adjust angle or remove glasses"
+    };
+  }
+  if (contrast < thresholds.minContrast) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eyes not clearly visible"
+    };
+  }
+  return {
+    passed: true,
+    brightness,
+    contrast,
+    hasGlare,
+    glareRatio,
+    message: null
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALIGNMENT_THRESHOLD_CAPTURE,
@@ -1692,6 +1858,8 @@ function validateFaceLandmarks(landmarks) {
   ERROR_MESSAGES,
   ERROR_MESSAGES_ES,
   ES_LOCALE,
+  EYE_LANDMARK_INDICES,
+  EYE_QUALITY_THRESHOLDS,
   FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES,
@@ -1725,18 +1893,23 @@ function validateFaceLandmarks(landmarks) {
   RETRY_CONFIG,
   TARGET_FACE_PERCENTAGE_IN_CROP,
   analyzeBlur,
+  analyzeEyeRegionBrightness,
+  analyzeEyeRegionContrast,
   analyzeLighting,
   calculateAdaptiveCropMultiplier,
   calculateBrightness,
   calculateFaceAlignment,
   calculateFaceCropRegion,
   canCaptureFrame,
+  checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectSpecularHighlights,
   encodeBase64,
   generateSessionId,
   getApiErrorMessage,
   getCaptureQualityFeedback,
+  getEyeRegionBounds,
   getFeedbackMessage,
   getMinFramesForModel,
   getOvalGuideState,

package/dist/index.mjs

@@ -1043,6 +1043,12 @@ var FEEDBACK_MESSAGES = {
   backlit: "Backlit - try facing the light source",
   // Hand occlusion
   hand_detected: "Remove hand from face",
+  // Eye region quality
+  eyes_not_visible: "Eyes not clearly visible",
+  eyes_shadowed: "Eyes are in shadow - improve lighting",
+  eyes_overexposed: "Eye region overexposed - reduce lighting",
+  glasses_glare: "Glare detected - adjust angle or remove glasses",
+  eye_quality_poor: "Eye region quality is poor",
   // Progress messages
   capturing: "Capturing...",
   almost_done: "Almost done...",
@@ -1094,6 +1100,12 @@ var ES_LOCALE = {
     backlit: "Contraluz - intenta mirar hacia la fuente de luz",
     // Hand occlusion
     hand_detected: "Retira la mano del rostro",
+    // Eye region quality
+    eyes_not_visible: "Ojos no visibles claramente",
+    eyes_shadowed: "Ojos en sombra - mejora la iluminaci\xF3n",
+    eyes_overexposed: "Regi\xF3n de ojos sobreexpuesta - reduce la iluminaci\xF3n",
+    glasses_glare: "Reflejo detectado - ajusta el \xE1ngulo o retira los lentes",
+    eye_quality_poor: "Calidad de la regi\xF3n de ojos insuficiente",
     // Progress messages
     capturing: "Capturando...",
     almost_done: "Casi listo...",
@@ -1527,6 +1539,44 @@ var LANDMARK_INDEX = {
   /** Lower lip center */
   LOWER_LIP: 14
 };
+var EYE_LANDMARK_INDICES = {
+  /** Right eye contour (viewer's left) */
+  RIGHT_EYE: [33, 7, 163, 144, 145, 153, 154, 155, 133, 173, 157, 158, 159, 160, 161, 246],
+  /** Left eye contour (viewer's right) */
+  LEFT_EYE: [362, 382, 381, 380, 374, 373, 390, 249, 263, 466, 388, 387, 386, 385, 384, 398]
+};
+function getEyeRegionBounds(landmarks) {
+  if (landmarks.length < 468) return null;
+  const PADDING = 0.2;
+  function computeBounds(indices) {
+    let minX = 1;
+    let minY = 1;
+    let maxX = 0;
+    let maxY = 0;
+    for (const idx of indices) {
+      const lm = landmarks[idx];
+      if (!lm) continue;
+      if (lm.x < minX) minX = lm.x;
+      if (lm.y < minY) minY = lm.y;
+      if (lm.x > maxX) maxX = lm.x;
+      if (lm.y > maxY) maxY = lm.y;
+    }
+    const width = maxX - minX;
+    const height = maxY - minY;
+    const padX = width * PADDING;
+    const padY = height * PADDING;
+    return {
+      x: Math.max(0, minX - padX),
+      y: Math.max(0, minY - padY),
+      width: Math.min(1 - Math.max(0, minX - padX), width + padX * 2),
+      height: Math.min(1 - Math.max(0, minY - padY), height + padY * 2)
+    };
+  }
+  return {
+    rightEye: computeBounds(EYE_LANDMARK_INDICES.RIGHT_EYE),
+    leftEye: computeBounds(EYE_LANDMARK_INDICES.LEFT_EYE)
+  };
+}
 var LANDMARK_MIN_BOUND = 0.1;
 var LANDMARK_MAX_BOUND = 0.9;
 var MIN_LANDMARK_COUNT = 15;
@@ -1548,6 +1598,115 @@ function validateFaceLandmarks(landmarks) {
   }
   return { valid: true };
 }
+
+// src/utils/eyeRegionAnalysis.ts
+var EYE_QUALITY_THRESHOLDS = {
+  minBrightness: 40,
+  maxBrightness: 230,
+  minContrast: 12,
+  glarePixelThreshold: 240,
+  maxGlareRatio: 0.15
+};
+function rgbaToLuminance(r, g, b) {
+  return 0.299 * r + 0.587 * g + 0.114 * b;
+}
+function analyzeEyeRegionBrightness(pixels) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  let totalLuminance = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    totalLuminance += rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+  }
+  return totalLuminance / pixelCount;
+}
+function analyzeEyeRegionContrast(pixels, meanBrightness) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  const mean = meanBrightness ?? analyzeEyeRegionBrightness(pixels);
+  let sumSqDiff = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const lum = rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+    const diff = lum - mean;
+    sumSqDiff += diff * diff;
+  }
+  return Math.sqrt(sumSqDiff / pixelCount);
+}
+function detectSpecularHighlights(pixels, threshold = EYE_QUALITY_THRESHOLDS.glarePixelThreshold) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  let glareCount = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const lum = rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+    if (lum >= threshold) {
+      glareCount++;
+    }
+  }
+  return glareCount / pixelCount;
+}
+function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
+  if (pixels.length < 4) {
+    return {
+      passed: false,
+      brightness: 0,
+      contrast: 0,
+      hasGlare: false,
+      glareRatio: 0,
+      message: "Eyes not clearly visible"
+    };
+  }
+  const brightness = analyzeEyeRegionBrightness(pixels);
+  const contrast = analyzeEyeRegionContrast(pixels, brightness);
+  const glareRatio = detectSpecularHighlights(pixels, thresholds.glarePixelThreshold);
+  const hasGlare = glareRatio > thresholds.maxGlareRatio;
+  if (brightness < thresholds.minBrightness) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eyes are in shadow - improve lighting"
+    };
+  }
+  if (brightness > thresholds.maxBrightness) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eye region overexposed - reduce lighting"
+    };
+  }
+  if (hasGlare) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Glare detected - adjust angle or remove glasses"
+    };
+  }
+  if (contrast < thresholds.minContrast) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eyes not clearly visible"
+    };
+  }
+  return {
+    passed: true,
+    brightness,
+    contrast,
+    hasGlare,
+    glareRatio,
+    message: null
+  };
+}
 export {
   ALIGNMENT_THRESHOLD_CAPTURE,
   ALIGNMENT_THRESHOLD_GOOD,
@@ -1573,6 +1732,8 @@ export {
   ERROR_MESSAGES,
   ERROR_MESSAGES_ES,
   ES_LOCALE,
+  EYE_LANDMARK_INDICES,
+  EYE_QUALITY_THRESHOLDS,
   FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES,
@@ -1606,18 +1767,23 @@ export {
   RETRY_CONFIG,
   TARGET_FACE_PERCENTAGE_IN_CROP,
   analyzeBlur,
+  analyzeEyeRegionBrightness,
+  analyzeEyeRegionContrast,
   analyzeLighting,
   calculateAdaptiveCropMultiplier,
   calculateBrightness,
   calculateFaceAlignment,
   calculateFaceCropRegion,
   canCaptureFrame,
+  checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectSpecularHighlights,
   encodeBase64,
   generateSessionId,
   getApiErrorMessage,
   getCaptureQualityFeedback,
+  getEyeRegionBounds,
   getFeedbackMessage,
   getMinFramesForModel,
   getOvalGuideState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moveris/shared",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Core business logic for Moveris Live SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",