@moveris/shared 2.1.1 → 2.3.0

package/README.md

@@ -25,6 +25,7 @@ const client = new LivenessClient({
 
 // Perform a fast liveness check
 const result = await client.fastCheck(frames, {
+  sessionId: 'my-session-id', // optional — auto-generated if omitted
   model: '10',
   source: 'live',
 });
@@ -293,6 +294,8 @@ const sessionId = generateSessionId();
 // e.g., 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
 ```
 
+> **Session ID injection**: Every `LivenessClient` method (`fastCheck`, `fastCheckCrops`, `streamFrame`, `verify`, `hybrid50`, `hybrid150`) accepts an optional `sessionId` in its options object. If provided, that ID is used for the request; if omitted, a new UUID is generated automatically. This is useful for debugging, testing, or correlating client requests with server logs. In `@moveris/react`, the `sessionId` can be injected via the `useLiveness` hook config or the `LivenessView` / `LivenessModal` props.
+
 #### `toFrameData(frames)`
 
 Convert CapturedFrame array to API format.
@@ -423,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  |
 
 ---
 
@@ -449,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.
@@ -524,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;
@@ -429,6 +444,10 @@ declare class LivenessClient {
     private readonly fetchFn;
     constructor(config: LivenessClientConfig);
     private request;
+    private parseErrorResponse;
+    private static unwrapErrorCode;
+    private static unwrapErrorMessage;
+    private static extractCodeFromText;
     private requestWithRetry;
     health(): Promise<HealthResponse>;
     queueStats(): Promise<QueueStatsResponse>;
@@ -565,6 +584,27 @@ declare const DEFAULT_LIVENESS_CONFIG: {
     readonly timeout: 30000;
 };
 
+declare const API_ERROR_CODES: {
+    readonly SESSION_EXPIRED: "session_expired";
+    readonly INVALID_KEY: "invalid_key";
+    readonly INVALID_MODEL: "invalid_model";
+    readonly INSUFFICIENT_FRAMES: "insufficient_frames";
+    readonly MISSING_FIELD: "missing_field";
+    readonly INVALID_FRAME: "invalid_frame";
+    readonly INVALID_SESSION: "invalid_session";
+    readonly RATE_LIMITED: "rate_limited";
+    readonly STREAM_INCOMPLETE: "stream_incomplete";
+    readonly NO_VERDICT: "no_verdict";
+    readonly TIMEOUT: "timeout";
+    readonly NETWORK_ERROR: "network_error";
+    readonly SERVER_ERROR: "server_error";
+};
+type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
+declare const ERROR_MESSAGES: Record<string, string>;
+declare const ERROR_MESSAGES_ES: Record<string, string>;
+declare function getApiErrorMessage(code: string | undefined, message?: string, customMessages?: Record<string, string>): string;
+declare function isRetryableError(code: string | undefined): boolean;
+
 declare const ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
 declare const ALIGNMENT_THRESHOLD_POOR = 0.5;
 declare const ALIGNMENT_THRESHOLD_GOOD = 0.5;
@@ -630,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";
@@ -683,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_PATHS, AUTH_CONFIG, 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, 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, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, 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;
@@ -429,6 +444,10 @@ declare class LivenessClient {
     private readonly fetchFn;
     constructor(config: LivenessClientConfig);
     private request;
+    private parseErrorResponse;
+    private static unwrapErrorCode;
+    private static unwrapErrorMessage;
+    private static extractCodeFromText;
     private requestWithRetry;
     health(): Promise<HealthResponse>;
     queueStats(): Promise<QueueStatsResponse>;
@@ -565,6 +584,27 @@ declare const DEFAULT_LIVENESS_CONFIG: {
     readonly timeout: 30000;
 };
 
+declare const API_ERROR_CODES: {
+    readonly SESSION_EXPIRED: "session_expired";
+    readonly INVALID_KEY: "invalid_key";
+    readonly INVALID_MODEL: "invalid_model";
+    readonly INSUFFICIENT_FRAMES: "insufficient_frames";
+    readonly MISSING_FIELD: "missing_field";
+    readonly INVALID_FRAME: "invalid_frame";
+    readonly INVALID_SESSION: "invalid_session";
+    readonly RATE_LIMITED: "rate_limited";
+    readonly STREAM_INCOMPLETE: "stream_incomplete";
+    readonly NO_VERDICT: "no_verdict";
+    readonly TIMEOUT: "timeout";
+    readonly NETWORK_ERROR: "network_error";
+    readonly SERVER_ERROR: "server_error";
+};
+type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
+declare const ERROR_MESSAGES: Record<string, string>;
+declare const ERROR_MESSAGES_ES: Record<string, string>;
+declare function getApiErrorMessage(code: string | undefined, message?: string, customMessages?: Record<string, string>): string;
+declare function isRetryableError(code: string | undefined): boolean;
+
 declare const ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
 declare const ALIGNMENT_THRESHOLD_POOR = 0.5;
 declare const ALIGNMENT_THRESHOLD_GOOD = 0.5;
@@ -630,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";
@@ -683,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_PATHS, AUTH_CONFIG, 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, 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, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, 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

@@ -25,6 +25,7 @@ __export(index_exports, {
   ALIGNMENT_THRESHOLD_PERFECT: () => ALIGNMENT_THRESHOLD_PERFECT,
   ALIGNMENT_THRESHOLD_POOR: () => ALIGNMENT_THRESHOLD_POOR,
   API_ENDPOINTS: () => API_ENDPOINTS,
+  API_ERROR_CODES: () => API_ERROR_CODES,
   API_PATHS: () => API_PATHS,
   AUTH_CONFIG: () => AUTH_CONFIG,
   BACKLIT_RATIO_THRESHOLD: () => BACKLIT_RATIO_THRESHOLD,
@@ -40,7 +41,11 @@ __export(index_exports, {
   DEFAULT_OVAL_REGION: () => DEFAULT_OVAL_REGION,
   DEFAULT_STABILIZER_CONFIG: () => DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES: () => DEFAULT_STATUS_MESSAGES,
+  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,
@@ -74,17 +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,
@@ -93,6 +104,7 @@ __export(index_exports, {
   isFaceCropFullyInFrame: () => isFaceCropFullyInFrame,
   isFaceFullyVisible: () => isFaceFullyVisible,
   isFaceInOval: () => isFaceInOval,
+  isRetryableError: () => isRetryableError,
   retryWithBackoff: () => retryWithBackoff,
   rgbaToGrayscale: () => rgbaToGrayscale,
   sleep: () => sleep,
@@ -248,7 +260,8 @@ function toLivenessResultFromStream(response) {
     throw new LivenessApiError("Stream not complete", "stream_incomplete", 400);
   }
   if (!response.verdict) {
-    throw new LivenessApiError(response.error ?? "No verdict received", "no_verdict", 500);
+    const errorCode = response.error ?? "no_verdict";
+    throw new LivenessApiError(response.error ?? "No verdict received", errorCode, 500);
   }
   return {
     verdict: response.verdict,
@@ -269,7 +282,7 @@ function generateSessionId() {
     return v.toString(16);
   });
 }
-var LivenessClient = class {
+var LivenessClient = class _LivenessClient {
   constructor(config) {
     this.baseUrl = (config.baseUrl ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
     this.apiKey = config.apiKey;
@@ -296,14 +309,7 @@ var LivenessClient = class {
       });
       clearTimeout(timeoutId);
       if (!response.ok) {
-        const errorData = await response.json();
-        throw new LivenessApiError(
-          errorData.message,
-          errorData.error,
-          response.status,
-          errorData.required,
-          errorData.received
-        );
+        throw await this.parseErrorResponse(response);
       }
       return await response.json();
     } catch (error) {
@@ -321,6 +327,75 @@ var LivenessClient = class {
       );
     }
   }
+  /**
+   * Parse an error response body, handling both JSON and non-JSON bodies.
+   *
+   * The backend sometimes wraps the real error in a generic envelope:
+   * ```json
+   * { "error": "http_error", "message": "{'error': 'session_expired', ...}" }
+   * ```
+   * This method unwraps such envelopes to extract the real error code.
+   */
+  async parseErrorResponse(response) {
+    const status = response.status;
+    let body;
+    try {
+      body = await response.text();
+    } catch {
+      return new LivenessApiError(`Request failed with status ${status}`, "server_error", status);
+    }
+    try {
+      const data = JSON.parse(body);
+      if (data.error) {
+        const realCode = _LivenessClient.unwrapErrorCode(data.error, data.message);
+        const realMessage = _LivenessClient.unwrapErrorMessage(data.message);
+        return new LivenessApiError(
+          realMessage ?? `Request failed (${realCode})`,
+          realCode,
+          status,
+          data.required,
+          data.received
+        );
+      }
+    } catch {
+    }
+    const code = _LivenessClient.extractCodeFromText(body) ?? "server_error";
+    return new LivenessApiError(`Request failed with status ${status}`, code, status);
+  }
+  /**
+   * When the outer error code is a generic wrapper (e.g. "http_error"),
+   * try to extract the real error code from the message text.
+   */
+  static unwrapErrorCode(outerCode, message) {
+    const WRAPPER_CODES = /* @__PURE__ */ new Set([
+      "http_error",
+      "upstream_error",
+      "proxy_error",
+      "internal_error"
+    ]);
+    if (!WRAPPER_CODES.has(outerCode) || !message) {
+      return outerCode;
+    }
+    return _LivenessClient.extractCodeFromText(message) ?? outerCode;
+  }
+  /**
+   * Try to extract a human-readable message from a nested Python dict string.
+   * E.g.: "{'error': 'session_expired', 'message': \"Create a new session...\"}"
+   *       → "Create a new session..."
+   */
+  static unwrapErrorMessage(message) {
+    if (!message) return void 0;
+    const msgMatch = /'message'\s*:\s*"([^"]+)"/.exec(message) ?? /'message'\s*:\s*'([^']+)'/.exec(message) ?? /"message"\s*:\s*"([^"]+)"/.exec(message);
+    return msgMatch?.[1] ?? void 0;
+  }
+  /**
+   * Extract an error code from raw text using regex.
+   * Handles both Python dict (`'error': 'code'`) and JSON (`"error": "code"`).
+   */
+  static extractCodeFromText(text) {
+    const match = /'error'\s*:\s*'([^']+)'/.exec(text) ?? /"error"\s*:\s*"([^"]+)"/.exec(text);
+    return match?.[1] ?? null;
+  }
   /**
    * Make a request with optional retry
    */
@@ -952,6 +1027,81 @@ var DEFAULT_STABILIZER_CONFIG = {
   sampleSize: 64
 };
 
+// src/constants/errors.ts
+var API_ERROR_CODES = {
+  SESSION_EXPIRED: "session_expired",
+  INVALID_KEY: "invalid_key",
+  INVALID_MODEL: "invalid_model",
+  INSUFFICIENT_FRAMES: "insufficient_frames",
+  MISSING_FIELD: "missing_field",
+  INVALID_FRAME: "invalid_frame",
+  INVALID_SESSION: "invalid_session",
+  RATE_LIMITED: "rate_limited",
+  STREAM_INCOMPLETE: "stream_incomplete",
+  NO_VERDICT: "no_verdict",
+  TIMEOUT: "timeout",
+  NETWORK_ERROR: "network_error",
+  SERVER_ERROR: "server_error"
+};
+var ERROR_MESSAGES = {
+  [API_ERROR_CODES.SESSION_EXPIRED]: "Session expired \u2014 please restart the verification",
+  [API_ERROR_CODES.INVALID_KEY]: "Invalid API key \u2014 contact your administrator",
+  [API_ERROR_CODES.INVALID_MODEL]: "Invalid model configuration",
+  [API_ERROR_CODES.INSUFFICIENT_FRAMES]: "Not enough frames captured \u2014 try again",
+  [API_ERROR_CODES.MISSING_FIELD]: "Missing required data \u2014 please try again",
+  [API_ERROR_CODES.INVALID_FRAME]: "Invalid frame data \u2014 please try again",
+  [API_ERROR_CODES.INVALID_SESSION]: "Invalid session \u2014 please restart",
+  [API_ERROR_CODES.RATE_LIMITED]: "Too many requests \u2014 wait a moment and try again",
+  [API_ERROR_CODES.STREAM_INCOMPLETE]: "Streaming incomplete \u2014 please try again",
+  [API_ERROR_CODES.NO_VERDICT]: "No result received \u2014 please try again",
+  [API_ERROR_CODES.TIMEOUT]: "Request timed out \u2014 check your connection",
+  [API_ERROR_CODES.NETWORK_ERROR]: "Network error \u2014 check your connection",
+  [API_ERROR_CODES.SERVER_ERROR]: "Server error \u2014 please try again later"
+};
+var ERROR_MESSAGES_ES = {
+  [API_ERROR_CODES.SESSION_EXPIRED]: "Sesi\xF3n expirada \u2014 reinicie la verificaci\xF3n",
+  [API_ERROR_CODES.INVALID_KEY]: "Clave API inv\xE1lida \u2014 contacte al administrador",
+  [API_ERROR_CODES.INVALID_MODEL]: "Configuraci\xF3n de modelo inv\xE1lida",
+  [API_ERROR_CODES.INSUFFICIENT_FRAMES]: "Frames insuficientes \u2014 intente de nuevo",
+  [API_ERROR_CODES.MISSING_FIELD]: "Datos requeridos faltantes \u2014 intente de nuevo",
+  [API_ERROR_CODES.INVALID_FRAME]: "Frame inv\xE1lido \u2014 intente de nuevo",
+  [API_ERROR_CODES.INVALID_SESSION]: "Sesi\xF3n inv\xE1lida \u2014 reinicie",
+  [API_ERROR_CODES.RATE_LIMITED]: "Demasiadas solicitudes \u2014 espere un momento",
+  [API_ERROR_CODES.STREAM_INCOMPLETE]: "Streaming incompleto \u2014 intente de nuevo",
+  [API_ERROR_CODES.NO_VERDICT]: "Sin resultado \u2014 intente de nuevo",
+  [API_ERROR_CODES.TIMEOUT]: "Tiempo de espera agotado \u2014 verifique su conexi\xF3n",
+  [API_ERROR_CODES.NETWORK_ERROR]: "Error de red \u2014 verifique su conexi\xF3n",
+  [API_ERROR_CODES.SERVER_ERROR]: "Error del servidor \u2014 intente m\xE1s tarde"
+};
+function looksLikeRawData(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) return true;
+  if (/'error'\s*:/.test(trimmed)) return true;
+  if (/"error"\s*:/.test(trimmed)) return true;
+  return false;
+}
+var GENERIC_FALLBACK = "An unexpected error occurred \u2014 please try again";
+function getApiErrorMessage(code, message, customMessages) {
+  if (code) {
+    const custom = customMessages?.[code];
+    if (custom) return custom;
+    const known = ERROR_MESSAGES[code];
+    if (known) return known;
+  }
+  if (message && !looksLikeRawData(message)) {
+    return message;
+  }
+  return GENERIC_FALLBACK;
+}
+function isRetryableError(code) {
+  if (!code) return true;
+  const nonRetryable = /* @__PURE__ */ new Set([
+    API_ERROR_CODES.INVALID_KEY,
+    API_ERROR_CODES.INVALID_MODEL
+  ]);
+  return !nonRetryable.has(code);
+}
+
 // src/constants/feedback.ts
 var ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
 var ALIGNMENT_THRESHOLD_POOR = 0.5;
@@ -1018,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...",
@@ -1069,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...",
@@ -1502,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;
@@ -1523,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,
@@ -1530,6 +1839,7 @@ function validateFaceLandmarks(landmarks) {
   ALIGNMENT_THRESHOLD_PERFECT,
   ALIGNMENT_THRESHOLD_POOR,
   API_ENDPOINTS,
+  API_ERROR_CODES,
   API_PATHS,
   AUTH_CONFIG,
   BACKLIT_RATIO_THRESHOLD,
@@ -1545,7 +1855,11 @@ function validateFaceLandmarks(landmarks) {
   DEFAULT_OVAL_REGION,
   DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES,
+  ERROR_MESSAGES,
+  ERROR_MESSAGES_ES,
   ES_LOCALE,
+  EYE_LANDMARK_INDICES,
+  EYE_QUALITY_THRESHOLDS,
   FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES,
@@ -1579,17 +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,
@@ -1598,6 +1918,7 @@ function validateFaceLandmarks(landmarks) {
   isFaceCropFullyInFrame,
   isFaceFullyVisible,
   isFaceInOval,
+  isRetryableError,
   retryWithBackoff,
   rgbaToGrayscale,
   sleep,

package/dist/index.mjs

@@ -135,7 +135,8 @@ function toLivenessResultFromStream(response) {
     throw new LivenessApiError("Stream not complete", "stream_incomplete", 400);
   }
   if (!response.verdict) {
-    throw new LivenessApiError(response.error ?? "No verdict received", "no_verdict", 500);
+    const errorCode = response.error ?? "no_verdict";
+    throw new LivenessApiError(response.error ?? "No verdict received", errorCode, 500);
   }
   return {
     verdict: response.verdict,
@@ -156,7 +157,7 @@ function generateSessionId() {
     return v.toString(16);
   });
 }
-var LivenessClient = class {
+var LivenessClient = class _LivenessClient {
   constructor(config) {
     this.baseUrl = (config.baseUrl ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
     this.apiKey = config.apiKey;
@@ -183,14 +184,7 @@ var LivenessClient = class {
       });
       clearTimeout(timeoutId);
       if (!response.ok) {
-        const errorData = await response.json();
-        throw new LivenessApiError(
-          errorData.message,
-          errorData.error,
-          response.status,
-          errorData.required,
-          errorData.received
-        );
+        throw await this.parseErrorResponse(response);
       }
       return await response.json();
     } catch (error) {
@@ -208,6 +202,75 @@ var LivenessClient = class {
       );
     }
   }
+  /**
+   * Parse an error response body, handling both JSON and non-JSON bodies.
+   *
+   * The backend sometimes wraps the real error in a generic envelope:
+   * ```json
+   * { "error": "http_error", "message": "{'error': 'session_expired', ...}" }
+   * ```
+   * This method unwraps such envelopes to extract the real error code.
+   */
+  async parseErrorResponse(response) {
+    const status = response.status;
+    let body;
+    try {
+      body = await response.text();
+    } catch {
+      return new LivenessApiError(`Request failed with status ${status}`, "server_error", status);
+    }
+    try {
+      const data = JSON.parse(body);
+      if (data.error) {
+        const realCode = _LivenessClient.unwrapErrorCode(data.error, data.message);
+        const realMessage = _LivenessClient.unwrapErrorMessage(data.message);
+        return new LivenessApiError(
+          realMessage ?? `Request failed (${realCode})`,
+          realCode,
+          status,
+          data.required,
+          data.received
+        );
+      }
+    } catch {
+    }
+    const code = _LivenessClient.extractCodeFromText(body) ?? "server_error";
+    return new LivenessApiError(`Request failed with status ${status}`, code, status);
+  }
+  /**
+   * When the outer error code is a generic wrapper (e.g. "http_error"),
+   * try to extract the real error code from the message text.
+   */
+  static unwrapErrorCode(outerCode, message) {
+    const WRAPPER_CODES = /* @__PURE__ */ new Set([
+      "http_error",
+      "upstream_error",
+      "proxy_error",
+      "internal_error"
+    ]);
+    if (!WRAPPER_CODES.has(outerCode) || !message) {
+      return outerCode;
+    }
+    return _LivenessClient.extractCodeFromText(message) ?? outerCode;
+  }
+  /**
+   * Try to extract a human-readable message from a nested Python dict string.
+   * E.g.: "{'error': 'session_expired', 'message': \"Create a new session...\"}"
+   *       → "Create a new session..."
+   */
+  static unwrapErrorMessage(message) {
+    if (!message) return void 0;
+    const msgMatch = /'message'\s*:\s*"([^"]+)"/.exec(message) ?? /'message'\s*:\s*'([^']+)'/.exec(message) ?? /"message"\s*:\s*"([^"]+)"/.exec(message);
+    return msgMatch?.[1] ?? void 0;
+  }
+  /**
+   * Extract an error code from raw text using regex.
+   * Handles both Python dict (`'error': 'code'`) and JSON (`"error": "code"`).
+   */
+  static extractCodeFromText(text) {
+    const match = /'error'\s*:\s*'([^']+)'/.exec(text) ?? /"error"\s*:\s*"([^"]+)"/.exec(text);
+    return match?.[1] ?? null;
+  }
   /**
    * Make a request with optional retry
    */
@@ -839,6 +902,81 @@ var DEFAULT_STABILIZER_CONFIG = {
   sampleSize: 64
 };
 
+// src/constants/errors.ts
+var API_ERROR_CODES = {
+  SESSION_EXPIRED: "session_expired",
+  INVALID_KEY: "invalid_key",
+  INVALID_MODEL: "invalid_model",
+  INSUFFICIENT_FRAMES: "insufficient_frames",
+  MISSING_FIELD: "missing_field",
+  INVALID_FRAME: "invalid_frame",
+  INVALID_SESSION: "invalid_session",
+  RATE_LIMITED: "rate_limited",
+  STREAM_INCOMPLETE: "stream_incomplete",
+  NO_VERDICT: "no_verdict",
+  TIMEOUT: "timeout",
+  NETWORK_ERROR: "network_error",
+  SERVER_ERROR: "server_error"
+};
+var ERROR_MESSAGES = {
+  [API_ERROR_CODES.SESSION_EXPIRED]: "Session expired \u2014 please restart the verification",
+  [API_ERROR_CODES.INVALID_KEY]: "Invalid API key \u2014 contact your administrator",
+  [API_ERROR_CODES.INVALID_MODEL]: "Invalid model configuration",
+  [API_ERROR_CODES.INSUFFICIENT_FRAMES]: "Not enough frames captured \u2014 try again",
+  [API_ERROR_CODES.MISSING_FIELD]: "Missing required data \u2014 please try again",
+  [API_ERROR_CODES.INVALID_FRAME]: "Invalid frame data \u2014 please try again",
+  [API_ERROR_CODES.INVALID_SESSION]: "Invalid session \u2014 please restart",
+  [API_ERROR_CODES.RATE_LIMITED]: "Too many requests \u2014 wait a moment and try again",
+  [API_ERROR_CODES.STREAM_INCOMPLETE]: "Streaming incomplete \u2014 please try again",
+  [API_ERROR_CODES.NO_VERDICT]: "No result received \u2014 please try again",
+  [API_ERROR_CODES.TIMEOUT]: "Request timed out \u2014 check your connection",
+  [API_ERROR_CODES.NETWORK_ERROR]: "Network error \u2014 check your connection",
+  [API_ERROR_CODES.SERVER_ERROR]: "Server error \u2014 please try again later"
+};
+var ERROR_MESSAGES_ES = {
+  [API_ERROR_CODES.SESSION_EXPIRED]: "Sesi\xF3n expirada \u2014 reinicie la verificaci\xF3n",
+  [API_ERROR_CODES.INVALID_KEY]: "Clave API inv\xE1lida \u2014 contacte al administrador",
+  [API_ERROR_CODES.INVALID_MODEL]: "Configuraci\xF3n de modelo inv\xE1lida",
+  [API_ERROR_CODES.INSUFFICIENT_FRAMES]: "Frames insuficientes \u2014 intente de nuevo",
+  [API_ERROR_CODES.MISSING_FIELD]: "Datos requeridos faltantes \u2014 intente de nuevo",
+  [API_ERROR_CODES.INVALID_FRAME]: "Frame inv\xE1lido \u2014 intente de nuevo",
+  [API_ERROR_CODES.INVALID_SESSION]: "Sesi\xF3n inv\xE1lida \u2014 reinicie",
+  [API_ERROR_CODES.RATE_LIMITED]: "Demasiadas solicitudes \u2014 espere un momento",
+  [API_ERROR_CODES.STREAM_INCOMPLETE]: "Streaming incompleto \u2014 intente de nuevo",
+  [API_ERROR_CODES.NO_VERDICT]: "Sin resultado \u2014 intente de nuevo",
+  [API_ERROR_CODES.TIMEOUT]: "Tiempo de espera agotado \u2014 verifique su conexi\xF3n",
+  [API_ERROR_CODES.NETWORK_ERROR]: "Error de red \u2014 verifique su conexi\xF3n",
+  [API_ERROR_CODES.SERVER_ERROR]: "Error del servidor \u2014 intente m\xE1s tarde"
+};
+function looksLikeRawData(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) return true;
+  if (/'error'\s*:/.test(trimmed)) return true;
+  if (/"error"\s*:/.test(trimmed)) return true;
+  return false;
+}
+var GENERIC_FALLBACK = "An unexpected error occurred \u2014 please try again";
+function getApiErrorMessage(code, message, customMessages) {
+  if (code) {
+    const custom = customMessages?.[code];
+    if (custom) return custom;
+    const known = ERROR_MESSAGES[code];
+    if (known) return known;
+  }
+  if (message && !looksLikeRawData(message)) {
+    return message;
+  }
+  return GENERIC_FALLBACK;
+}
+function isRetryableError(code) {
+  if (!code) return true;
+  const nonRetryable = /* @__PURE__ */ new Set([
+    API_ERROR_CODES.INVALID_KEY,
+    API_ERROR_CODES.INVALID_MODEL
+  ]);
+  return !nonRetryable.has(code);
+}
+
 // src/constants/feedback.ts
 var ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
 var ALIGNMENT_THRESHOLD_POOR = 0.5;
@@ -905,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...",
@@ -956,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...",
@@ -1389,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;
@@ -1410,12 +1598,122 @@ 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,
   ALIGNMENT_THRESHOLD_PERFECT,
   ALIGNMENT_THRESHOLD_POOR,
   API_ENDPOINTS,
+  API_ERROR_CODES,
   API_PATHS,
   AUTH_CONFIG,
   BACKLIT_RATIO_THRESHOLD,
@@ -1431,7 +1729,11 @@ export {
   DEFAULT_OVAL_REGION,
   DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES,
+  ERROR_MESSAGES,
+  ERROR_MESSAGES_ES,
   ES_LOCALE,
+  EYE_LANDMARK_INDICES,
+  EYE_QUALITY_THRESHOLDS,
   FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES,
@@ -1465,17 +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,
@@ -1484,6 +1792,7 @@ export {
   isFaceCropFullyInFrame,
   isFaceFullyVisible,
   isFaceInOval,
+  isRetryableError,
   retryWithBackoff,
   rgbaToGrayscale,
   sleep,

package/package.json

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