@moveris/shared 2.5.0 → 2.7.0

package/README.md

@@ -26,7 +26,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',
+  model: 'mixed-10-v2',
   source: 'live',
 });
 
@@ -64,18 +64,18 @@ Perform fast liveness check with server-side face detection. Ideal for quick ver
 ```typescript
 const result = await client.fastCheck(frames, {
   sessionId: 'optional-uuid',
-  model: '10', // '10' | '50' | '250'
+  model: 'mixed-10-v2',
   source: 'live', // 'live' | 'media'
 });
 ```
 
 **Parameters:**
 
-| Option      | Type             | Default        | Description                                                             |
-| ----------- | ---------------- | -------------- | ----------------------------------------------------------------------- |
-| `sessionId` | `string`         | auto-generated | Unique session identifier (UUID)                                        |
-| `model`     | `FastCheckModel` | `'10'`         | Model to use: `'10'` (fast), `'50'` (balanced), `'250'` (high-accuracy) |
-| `source`    | `FrameSource`    | `'live'`       | Frame source: `'live'` (camera) or `'media'` (recorded video)           |
+| Option      | Type             | Default         | Description                                                   |
+| ----------- | ---------------- | --------------- | ------------------------------------------------------------- |
+| `sessionId` | `string`         | auto-generated  | Unique session identifier (UUID)                              |
+| `model`     | `FastCheckModel` | `'mixed-10-v2'` | Model to use (see Models section)                             |
+| `source`    | `FrameSource`    | `'live'`        | Frame source: `'live'` (camera) or `'media'` (recorded video) |
 
 **Returns:** `Promise<LivenessResult>`
 
@@ -184,22 +184,34 @@ Model selection for liveness detection speed/accuracy trade-off.
 
 ```typescript
 type FastCheckModel =
+  | 'mixed-10-v2'
+  | 'mixed-30-v2'
+  | 'mixed-60-v2'
+  | 'mixed-90-v2'
+  | 'mixed-120-v2' // Active mixed-v2 models (recommended)
   | '10'
   | '50'
-  | '250' // Standard models
-  | 'hybrid-v2-10'
-  | 'hybrid-v2-50' // Hybrid V2 (physiological features)
-  | 'mixed-10'; // Mixed (visual + physiological scoring)
+  | '250' // Legacy standard models
+  | (string & object); // Forward-compatible with future model IDs
 ```
 
-| Value            | Frames | Category  | Description                               |
-| ---------------- | ------ | --------- | ----------------------------------------- |
-| `'10'`           | 10     | Standard  | Fast verification, lowest latency         |
-| `'50'`           | 50     | Standard  | Balanced speed and accuracy               |
-| `'250'`          | 250    | Standard  | Highest accuracy, slower                  |
-| `'hybrid-v2-10'` | 10     | Hybrid V2 | Visual + physiological feature extraction |
-| `'hybrid-v2-50'` | 50     | Hybrid V2 | Higher accuracy physiological features    |
-| `'mixed-10'`     | 10     | Mixed     | Combined visual + physiological scoring   |
+Active models (recommended):
+
+| Value            | Frames | Description                    |
+| ---------------- | ------ | ------------------------------ |
+| `'mixed-10-v2'`  | 10     | Fast verification, low latency |
+| `'mixed-30-v2'`  | 30     | Balanced speed and accuracy    |
+| `'mixed-60-v2'`  | 60     | Higher accuracy                |
+| `'mixed-90-v2'`  | 90     | High accuracy                  |
+| `'mixed-120-v2'` | 120    | Highest accuracy, slower       |
+
+Legacy models (still supported):
+
+| Value   | Frames | Description                 |
+| ------- | ------ | --------------------------- |
+| `'10'`  | 10     | Standard — fast             |
+| `'50'`  | 50     | Standard — balanced         |
+| `'250'` | 250    | Standard — highest accuracy |
 
 #### FrameSource
 
@@ -492,6 +504,8 @@ const glareRatio = detectSpecularHighlights(pixels);
 | Glare       | `maxGlareRatio: 0.15` | >15% of pixels are specular highlights  |
 | Occluded    | `minContrast: 12`     | Standard deviation of luminance too low |
 
+Glare detection uses a **relative threshold** (`mean brightness × 2.5`) so sensitivity adapts to ambient lighting, avoiding false positives in bright environments.
+
 Custom thresholds can be passed as a second argument to `checkEyeRegionQuality()`.
 
 ### Eye Region Landmarks

package/dist/index.d.mts

@@ -29,6 +29,7 @@ interface FastCheckRequest {
     model?: FastCheckModel;
     source?: FrameSource;
     frames: FrameData[];
+    warnings?: string[];
 }
 interface FastCheckCropsRequest {
     session_id: string;
@@ -64,6 +65,7 @@ interface FastCheckStreamRequest {
     model?: FastCheckModel;
     source?: FrameSource;
     frame: FrameData;
+    warnings?: string[];
 }
 interface FastCheckResponse {
     verdict: Verdict | null;
@@ -76,6 +78,7 @@ interface FastCheckResponse {
     frames_processed: number;
     available: boolean;
     warning: string | null;
+    warnings?: string[] | null;
     error: string | null;
 }
 interface FastCheckStreamResponse {
@@ -93,6 +96,7 @@ interface FastCheckStreamResponse {
     frames_processed: number | null;
     available: boolean;
     warning: string | null;
+    warnings?: string[] | null;
     error: string | null;
 }
 interface VerifyResponse {
@@ -157,6 +161,7 @@ interface LivenessResult {
     sessionId: string;
     processingMs: number;
     framesProcessed: number;
+    warnings?: string[];
 }
 type LivenessState = 'idle' | 'capturing' | 'uploading' | 'processing' | 'complete' | 'error';
 interface LivenessConfig {
@@ -215,6 +220,40 @@ interface LivenessCallbacks {
     onStateChange?: OnStateChangeCallback;
 }
 
+interface FaceLandmarkPoint {
+    x: number;
+    y: number;
+    z: number;
+}
+interface LandmarkValidationResult {
+    valid: boolean;
+    message?: string;
+}
+declare const LANDMARK_INDEX: {
+    readonly NOSE_TIP: 1;
+    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;
+declare function validateFaceLandmarks(landmarks: FaceLandmarkPoint[] | undefined): LandmarkValidationResult;
+
 interface FaceBoundingBox {
     originX: number;
     originY: number;
@@ -272,15 +311,17 @@ declare const MIN_FACE_SIDE_MARGIN = 0.05;
 declare const MIN_CAPTURE_ALIGNMENT = 0.6;
 declare const HIGH_ALIGNMENT = 0.85;
 declare const GOOD_ALIGNMENT = 0.5;
-declare const IDEAL_CROP_MULTIPLIER = 2;
-declare const MIN_CROP_MULTIPLIER = 1.8;
-declare const MAX_CROP_MULTIPLIER = 2.5;
+declare const IDEAL_CROP_MULTIPLIER = 3;
+declare const MIN_CROP_MULTIPLIER = 2.5;
+declare const MAX_CROP_MULTIPLIER = 4;
 declare const FACE_CENTER_VERTICAL_OFFSET = 0.05;
+declare const MIN_IDEAL_FACE_RATIO = 0.05;
+declare const MAX_IDEAL_FACE_RATIO = 0.2;
 declare const MIN_FACE_RATIO = 0.036;
 declare const MAX_FACE_RATIO = 0.7;
 declare const FACE_CROP_OUTPUT_SIZE = 224;
-declare const MAX_FACE_PERCENTAGE_IN_CROP = 0.6;
-declare const TARGET_FACE_PERCENTAGE_IN_CROP = 0.5;
+declare const MAX_FACE_PERCENTAGE_IN_CROP = 0.45;
+declare const TARGET_FACE_PERCENTAGE_IN_CROP = 0.33;
 declare function analyzeBlur(grayscalePixels: number[], width: number, height: number, threshold?: number): BlurAnalysis;
 declare function rgbaToGrayscale(rgbaPixels: Uint8ClampedArray | number[]): number[];
 declare function calculateBrightness(rgbaPixels: Uint8ClampedArray | number[]): number;
@@ -306,6 +347,12 @@ declare function checkFrameQuality(options: {
     lightingAnalysis?: LightingAnalysis;
     minAlignment?: number;
 }): FrameQualityResult;
+interface FaceRollResult {
+    roll: number;
+    tooTilted: boolean;
+}
+declare const MAX_FACE_ROLL_DEGREES = 15;
+declare function detectFaceRoll(landmarks: FaceLandmarkPoint[]): FaceRollResult;
 declare class BaseFrameCollector {
     protected frames: CapturedFrame[];
     protected maxFrames: number;
@@ -321,40 +368,6 @@ declare class BaseFrameCollector {
     getNextIndex(): number;
 }
 
-interface FaceLandmarkPoint {
-    x: number;
-    y: number;
-    z: number;
-}
-interface LandmarkValidationResult {
-    valid: boolean;
-    message?: string;
-}
-declare const LANDMARK_INDEX: {
-    readonly NOSE_TIP: 1;
-    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;
-declare function validateFaceLandmarks(landmarks: FaceLandmarkPoint[] | undefined): LandmarkValidationResult;
-
 interface DetectionResult {
     type: string;
     passed: boolean;
@@ -469,22 +482,26 @@ declare class LivenessClient {
         sessionId?: string;
         model?: FastCheckModel;
         source?: FrameSource;
+        warnings?: string[];
     }): Promise<LivenessResult>;
     fastCheckCrops(crops: CropData[], options?: {
         sessionId?: string;
         model?: FastCheckModel;
         source?: FrameSource;
+        warnings?: string[];
     }): Promise<LivenessResult>;
     streamFrame(frame: CapturedFrame, options: {
         sessionId: string;
         model?: FastCheckModel;
         source?: FrameSource;
+        warnings?: string[];
     }): Promise<FastCheckStreamResponse>;
     private sendStreamFrameInternal;
     fastCheckStream(frames: CapturedFrame[], options?: {
         sessionId?: string;
         model?: FastCheckModel;
         source?: FrameSource;
+        warnings?: string[];
     }, callbacks?: {
         onFrameSent?: (index: number, total: number) => void;
         onFrameBuffered?: (framesReceived: number, framesRequired: number) => void;
@@ -493,6 +510,7 @@ declare class LivenessClient {
         sessionId?: string;
         model?: FastCheckModel;
         source?: FrameSource;
+        warnings?: string[];
     }, callbacks?: {
         onFrameSent?: (index: number, total: number) => void;
         onFrameBuffered?: (framesReceived: number, framesRequired: number) => void;
@@ -620,7 +638,7 @@ 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_CAPTURE = 0.85;
 declare const ALIGNMENT_THRESHOLD_POOR = 0.6;
 declare const ALIGNMENT_THRESHOLD_GOOD = 0.6;
 declare const ALIGNMENT_THRESHOLD_PERFECT = 0.85;
@@ -677,6 +695,8 @@ declare const FEEDBACK_MESSAGES: {
     readonly move_back: "Move back - face too close";
     readonly too_close: "Move back - face too close";
     readonly too_far: "Move closer - face too far";
+    readonly move_closer_ideal: "Move a little closer";
+    readonly move_back_ideal: "Move back slightly";
     readonly face_not_visible: "Center your face - edges cut off";
     readonly partial_face: "Center your face - edges cut off";
     readonly hold_still: "Hold still - image blurry";
@@ -684,6 +704,8 @@ declare const FEEDBACK_MESSAGES: {
     readonly poor_lighting: "Improve lighting";
     readonly too_dark: "Low lighting - move to a brighter area";
     readonly backlit: "Backlit - try facing the light source";
+    readonly phone_angle_low: "Raise your phone to eye level";
+    readonly phone_tilted: "Hold your phone level";
     readonly hand_detected: "Remove hand from face";
     readonly eyes_not_visible: "Eyes not clearly visible";
     readonly eyes_shadowed: "Eyes are in shadow - improve lighting";
@@ -714,6 +736,10 @@ interface CaptureQualityState {
     isPartialFace: boolean;
     framesCaptured: number;
     targetFrames: number;
+    tooFarFromIdeal?: boolean;
+    tooCloseToIdeal?: boolean;
+    phoneAngled?: boolean;
+    phoneTilted?: boolean;
 }
 declare function getCaptureQualityFeedback(state: CaptureQualityState): string;
 declare function canCaptureFrame(state: Omit<CaptureQualityState, 'framesCaptured' | 'targetFrames' | 'isCapturing'>): boolean;
@@ -755,13 +781,13 @@ interface EyeQualityThresholds {
     minBrightness: number;
     maxBrightness: number;
     minContrast: number;
-    glarePixelThreshold: number;
+    glareRelativeFactor: 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 detectSpecularHighlights(pixels: Uint8Array | Uint8ClampedArray, relativeFactor?: number, meanBrightness?: 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 ModelEntry, type ModelType, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, 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, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+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 FaceRollResult, 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, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, 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, detectFaceRoll, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.d.ts

@@ -29,6 +29,7 @@ interface FastCheckRequest {
     model?: FastCheckModel;
     source?: FrameSource;
     frames: FrameData[];
+    warnings?: string[];
 }
 interface FastCheckCropsRequest {
     session_id: string;
@@ -64,6 +65,7 @@ interface FastCheckStreamRequest {
     model?: FastCheckModel;
     source?: FrameSource;
     frame: FrameData;
+    warnings?: string[];
 }
 interface FastCheckResponse {
     verdict: Verdict | null;
@@ -76,6 +78,7 @@ interface FastCheckResponse {
     frames_processed: number;
     available: boolean;
     warning: string | null;
+    warnings?: string[] | null;
     error: string | null;
 }
 interface FastCheckStreamResponse {
@@ -93,6 +96,7 @@ interface FastCheckStreamResponse {
     frames_processed: number | null;
     available: boolean;
     warning: string | null;
+    warnings?: string[] | null;
     error: string | null;
 }
 interface VerifyResponse {
@@ -157,6 +161,7 @@ interface LivenessResult {
     sessionId: string;
     processingMs: number;
     framesProcessed: number;
+    warnings?: string[];
 }
 type LivenessState = 'idle' | 'capturing' | 'uploading' | 'processing' | 'complete' | 'error';
 interface LivenessConfig {
@@ -215,6 +220,40 @@ interface LivenessCallbacks {
     onStateChange?: OnStateChangeCallback;
 }
 
+interface FaceLandmarkPoint {
+    x: number;
+    y: number;
+    z: number;
+}
+interface LandmarkValidationResult {
+    valid: boolean;
+    message?: string;
+}
+declare const LANDMARK_INDEX: {
+    readonly NOSE_TIP: 1;
+    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;
+declare function validateFaceLandmarks(landmarks: FaceLandmarkPoint[] | undefined): LandmarkValidationResult;
+
 interface FaceBoundingBox {
     originX: number;
     originY: number;
@@ -272,15 +311,17 @@ declare const MIN_FACE_SIDE_MARGIN = 0.05;
 declare const MIN_CAPTURE_ALIGNMENT = 0.6;
 declare const HIGH_ALIGNMENT = 0.85;
 declare const GOOD_ALIGNMENT = 0.5;
-declare const IDEAL_CROP_MULTIPLIER = 2;
-declare const MIN_CROP_MULTIPLIER = 1.8;
-declare const MAX_CROP_MULTIPLIER = 2.5;
+declare const IDEAL_CROP_MULTIPLIER = 3;
+declare const MIN_CROP_MULTIPLIER = 2.5;
+declare const MAX_CROP_MULTIPLIER = 4;
 declare const FACE_CENTER_VERTICAL_OFFSET = 0.05;
+declare const MIN_IDEAL_FACE_RATIO = 0.05;
+declare const MAX_IDEAL_FACE_RATIO = 0.2;
 declare const MIN_FACE_RATIO = 0.036;
 declare const MAX_FACE_RATIO = 0.7;
 declare const FACE_CROP_OUTPUT_SIZE = 224;
-declare const MAX_FACE_PERCENTAGE_IN_CROP = 0.6;
-declare const TARGET_FACE_PERCENTAGE_IN_CROP = 0.5;
+declare const MAX_FACE_PERCENTAGE_IN_CROP = 0.45;
+declare const TARGET_FACE_PERCENTAGE_IN_CROP = 0.33;
 declare function analyzeBlur(grayscalePixels: number[], width: number, height: number, threshold?: number): BlurAnalysis;
 declare function rgbaToGrayscale(rgbaPixels: Uint8ClampedArray | number[]): number[];
 declare function calculateBrightness(rgbaPixels: Uint8ClampedArray | number[]): number;
@@ -306,6 +347,12 @@ declare function checkFrameQuality(options: {
     lightingAnalysis?: LightingAnalysis;
     minAlignment?: number;
 }): FrameQualityResult;
+interface FaceRollResult {
+    roll: number;
+    tooTilted: boolean;
+}
+declare const MAX_FACE_ROLL_DEGREES = 15;
+declare function detectFaceRoll(landmarks: FaceLandmarkPoint[]): FaceRollResult;
 declare class BaseFrameCollector {
     protected frames: CapturedFrame[];
     protected maxFrames: number;
@@ -321,40 +368,6 @@ declare class BaseFrameCollector {
     getNextIndex(): number;
 }
 
-interface FaceLandmarkPoint {
-    x: number;
-    y: number;
-    z: number;
-}
-interface LandmarkValidationResult {
-    valid: boolean;
-    message?: string;
-}
-declare const LANDMARK_INDEX: {
-    readonly NOSE_TIP: 1;
-    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;
-declare function validateFaceLandmarks(landmarks: FaceLandmarkPoint[] | undefined): LandmarkValidationResult;
-
 interface DetectionResult {
     type: string;
     passed: boolean;
@@ -469,22 +482,26 @@ declare class LivenessClient {
         sessionId?: string;
         model?: FastCheckModel;
         source?: FrameSource;
+        warnings?: string[];
     }): Promise<LivenessResult>;
     fastCheckCrops(crops: CropData[], options?: {
         sessionId?: string;
         model?: FastCheckModel;
         source?: FrameSource;
+        warnings?: string[];
     }): Promise<LivenessResult>;
     streamFrame(frame: CapturedFrame, options: {
         sessionId: string;
         model?: FastCheckModel;
         source?: FrameSource;
+        warnings?: string[];
     }): Promise<FastCheckStreamResponse>;
     private sendStreamFrameInternal;
     fastCheckStream(frames: CapturedFrame[], options?: {
         sessionId?: string;
         model?: FastCheckModel;
         source?: FrameSource;
+        warnings?: string[];
     }, callbacks?: {
         onFrameSent?: (index: number, total: number) => void;
         onFrameBuffered?: (framesReceived: number, framesRequired: number) => void;
@@ -493,6 +510,7 @@ declare class LivenessClient {
         sessionId?: string;
         model?: FastCheckModel;
         source?: FrameSource;
+        warnings?: string[];
     }, callbacks?: {
         onFrameSent?: (index: number, total: number) => void;
         onFrameBuffered?: (framesReceived: number, framesRequired: number) => void;
@@ -620,7 +638,7 @@ 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_CAPTURE = 0.85;
 declare const ALIGNMENT_THRESHOLD_POOR = 0.6;
 declare const ALIGNMENT_THRESHOLD_GOOD = 0.6;
 declare const ALIGNMENT_THRESHOLD_PERFECT = 0.85;
@@ -677,6 +695,8 @@ declare const FEEDBACK_MESSAGES: {
     readonly move_back: "Move back - face too close";
     readonly too_close: "Move back - face too close";
     readonly too_far: "Move closer - face too far";
+    readonly move_closer_ideal: "Move a little closer";
+    readonly move_back_ideal: "Move back slightly";
     readonly face_not_visible: "Center your face - edges cut off";
     readonly partial_face: "Center your face - edges cut off";
     readonly hold_still: "Hold still - image blurry";
@@ -684,6 +704,8 @@ declare const FEEDBACK_MESSAGES: {
     readonly poor_lighting: "Improve lighting";
     readonly too_dark: "Low lighting - move to a brighter area";
     readonly backlit: "Backlit - try facing the light source";
+    readonly phone_angle_low: "Raise your phone to eye level";
+    readonly phone_tilted: "Hold your phone level";
     readonly hand_detected: "Remove hand from face";
     readonly eyes_not_visible: "Eyes not clearly visible";
     readonly eyes_shadowed: "Eyes are in shadow - improve lighting";
@@ -714,6 +736,10 @@ interface CaptureQualityState {
     isPartialFace: boolean;
     framesCaptured: number;
     targetFrames: number;
+    tooFarFromIdeal?: boolean;
+    tooCloseToIdeal?: boolean;
+    phoneAngled?: boolean;
+    phoneTilted?: boolean;
 }
 declare function getCaptureQualityFeedback(state: CaptureQualityState): string;
 declare function canCaptureFrame(state: Omit<CaptureQualityState, 'framesCaptured' | 'targetFrames' | 'isCapturing'>): boolean;
@@ -755,13 +781,13 @@ interface EyeQualityThresholds {
     minBrightness: number;
     maxBrightness: number;
     minContrast: number;
-    glarePixelThreshold: number;
+    glareRelativeFactor: 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 detectSpecularHighlights(pixels: Uint8Array | Uint8ClampedArray, relativeFactor?: number, meanBrightness?: 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 ModelEntry, type ModelType, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, 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, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+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 FaceRollResult, 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, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, 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, detectFaceRoll, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.js

@@ -66,12 +66,15 @@ __export(index_exports, {
   MAX_CROP_MULTIPLIER: () => MAX_CROP_MULTIPLIER,
   MAX_FACE_PERCENTAGE_IN_CROP: () => MAX_FACE_PERCENTAGE_IN_CROP,
   MAX_FACE_RATIO: () => MAX_FACE_RATIO,
+  MAX_FACE_ROLL_DEGREES: () => MAX_FACE_ROLL_DEGREES,
+  MAX_IDEAL_FACE_RATIO: () => MAX_IDEAL_FACE_RATIO,
   MIN_CAPTURE_ALIGNMENT: () => MIN_CAPTURE_ALIGNMENT,
   MIN_CROP_MULTIPLIER: () => MIN_CROP_MULTIPLIER,
   MIN_FACE_BOTTOM_MARGIN: () => MIN_FACE_BOTTOM_MARGIN,
   MIN_FACE_RATIO: () => MIN_FACE_RATIO,
   MIN_FACE_SIDE_MARGIN: () => MIN_FACE_SIDE_MARGIN,
   MIN_FACE_TOP_MARGIN: () => MIN_FACE_TOP_MARGIN,
+  MIN_IDEAL_FACE_RATIO: () => MIN_IDEAL_FACE_RATIO,
   MIN_LANDMARK_COUNT: () => MIN_LANDMARK_COUNT,
   MODEL_CONFIGS: () => MODEL_CONFIGS,
   OVAL_GUIDE_COLORS: () => OVAL_GUIDE_COLORS,
@@ -92,6 +95,7 @@ __export(index_exports, {
   checkEyeRegionQuality: () => checkEyeRegionQuality,
   checkFrameQuality: () => checkFrameQuality,
   decodeBase64: () => decodeBase64,
+  detectFaceRoll: () => detectFaceRoll,
   detectSpecularHighlights: () => detectSpecularHighlights,
   encodeBase64: () => encodeBase64,
   generateSessionId: () => generateSessionId,
@@ -257,7 +261,8 @@ function toLivenessResult(response) {
     score: response.score ?? 0,
     sessionId: response.session_id,
     processingMs: response.processing_ms,
-    framesProcessed: "frames_processed" in response ? response.frames_processed ?? 0 : 0
+    framesProcessed: "frames_processed" in response ? response.frames_processed ?? 0 : 0,
+    warnings: "warnings" in response && Array.isArray(response.warnings) ? response.warnings : void 0
   };
 }
 function toLivenessResultFromStream(response) {
@@ -274,7 +279,8 @@ function toLivenessResultFromStream(response) {
     score: response.score ?? 0,
     sessionId: response.session_id,
     processingMs: response.processing_ms ?? 0,
-    framesProcessed: response.frames_processed ?? 0
+    framesProcessed: response.frames_processed ?? 0,
+    warnings: Array.isArray(response.warnings) ? response.warnings : void 0
   };
 }
 function generateSessionId() {
@@ -453,7 +459,8 @@ var LivenessClient = class _LivenessClient {
       session_id: options.sessionId ?? generateSessionId(),
       model: options.model ?? "10",
       source: options.source ?? "live",
-      frames: toFrameData(frames)
+      frames: toFrameData(frames),
+      ...options.warnings?.length ? { warnings: options.warnings } : {}
     };
     const response = await this.requestWithRetry(API_PATHS.fastCheck, {
       method: "POST",
@@ -473,7 +480,8 @@ var LivenessClient = class _LivenessClient {
       session_id: options.sessionId ?? generateSessionId(),
       model: options.model ?? "10",
       source: options.source ?? "live",
-      crops
+      crops,
+      ...options.warnings?.length ? { warnings: options.warnings } : {}
     };
     const response = await this.requestWithRetry(API_PATHS.fastCheckCrops, {
       method: "POST",
@@ -507,7 +515,8 @@ var LivenessClient = class _LivenessClient {
     return this.sendStreamFrameInternal(frameData, {
       sessionId: options.sessionId,
       model: options.model ?? "10",
-      source: options.source ?? "live"
+      source: options.source ?? "live",
+      warnings: options.warnings
     });
   }
   /**
@@ -522,7 +531,8 @@ var LivenessClient = class _LivenessClient {
       session_id: options.sessionId,
       model: options.model,
       source: options.source,
-      frame: frameData
+      frame: frameData,
+      ...options.warnings?.length ? { warnings: options.warnings } : {}
     };
     return this.requestWithRetry(API_PATHS.fastCheckStream, {
       method: "POST",
@@ -551,7 +561,8 @@ var LivenessClient = class _LivenessClient {
       const response = await this.sendStreamFrameInternal(frameData, {
         sessionId,
         model,
-        source
+        source,
+        warnings: options.warnings
       });
       callbacks?.onFrameSent?.(index + 1, total);
       if (response.status === "buffering") {
@@ -600,7 +611,8 @@ var LivenessClient = class _LivenessClient {
       const response = await this.sendStreamFrameInternal(frameData, {
         sessionId,
         model,
-        source
+        source,
+        warnings: options.warnings
       });
       const currentIndex = frameData.index;
       callbacks?.onFrameSent?.(currentIndex + 1, total);
@@ -1177,7 +1189,7 @@ function isRetryableError(code) {
 }
 
 // src/constants/feedback.ts
-var ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
+var ALIGNMENT_THRESHOLD_CAPTURE = 0.85;
 var ALIGNMENT_THRESHOLD_POOR = 0.6;
 var ALIGNMENT_THRESHOLD_GOOD = 0.6;
 var ALIGNMENT_THRESHOLD_PERFECT = 0.85;
@@ -1230,6 +1242,8 @@ var FEEDBACK_MESSAGES = {
   move_back: "Move back - face too close",
   too_close: "Move back - face too close",
   too_far: "Move closer - face too far",
+  move_closer_ideal: "Move a little closer",
+  move_back_ideal: "Move back slightly",
   // Visibility issues
   face_not_visible: "Center your face - edges cut off",
   partial_face: "Center your face - edges cut off",
@@ -1240,6 +1254,9 @@ var FEEDBACK_MESSAGES = {
   poor_lighting: "Improve lighting",
   too_dark: "Low lighting - move to a brighter area",
   backlit: "Backlit - try facing the light source",
+  // Phone orientation
+  phone_angle_low: "Raise your phone to eye level",
+  phone_tilted: "Hold your phone level",
   // Hand occlusion
   hand_detected: "Remove hand from face",
   // Eye region quality
@@ -1287,6 +1304,8 @@ var ES_LOCALE = {
     move_back: "Al\xE9jate - rostro muy cerca",
     too_close: "Al\xE9jate - rostro muy cerca",
     too_far: "Ac\xE9rcate - rostro muy lejos",
+    move_closer_ideal: "Ac\xE9rcate un poco",
+    move_back_ideal: "Al\xE9jate un poco",
     // Visibility issues
     face_not_visible: "Centra tu rostro - bordes cortados",
     partial_face: "Centra tu rostro - bordes cortados",
@@ -1297,6 +1316,9 @@ var ES_LOCALE = {
     poor_lighting: "Mejora la iluminaci\xF3n",
     too_dark: "Poca luz - mu\xE9vete a un \xE1rea m\xE1s iluminada",
     backlit: "Contraluz - intenta mirar hacia la fuente de luz",
+    // Phone orientation
+    phone_angle_low: "Levanta el tel\xE9fono a la altura de los ojos",
+    phone_tilted: "Mant\xE9n el tel\xE9fono nivelado",
     // Hand occlusion
     hand_detected: "Retira la mano del rostro",
     // Eye region quality
@@ -1329,11 +1351,21 @@ function getCaptureQualityFeedback(state) {
     isBlurry,
     isPartialFace,
     framesCaptured,
-    targetFrames
+    targetFrames,
+    tooFarFromIdeal,
+    tooCloseToIdeal,
+    phoneAngled,
+    phoneTilted
   } = state;
   if (!hasFace) {
     return FEEDBACK_MESSAGES.no_face;
   }
+  if (phoneTilted) {
+    return FEEDBACK_MESSAGES.phone_tilted;
+  }
+  if (phoneAngled) {
+    return FEEDBACK_MESSAGES.phone_angle_low;
+  }
   if (tooClose) {
     return FEEDBACK_MESSAGES.too_close;
   }
@@ -1346,6 +1378,12 @@ function getCaptureQualityFeedback(state) {
   if (isBlurry) {
     return FEEDBACK_MESSAGES.blurry;
   }
+  if (tooFarFromIdeal) {
+    return FEEDBACK_MESSAGES.move_closer_ideal;
+  }
+  if (tooCloseToIdeal) {
+    return FEEDBACK_MESSAGES.move_back_ideal;
+  }
   if (alignment < ALIGNMENT_THRESHOLD_POOR) {
     return FEEDBACK_MESSAGES.move_closer_to_center;
   }
@@ -1361,8 +1399,19 @@ function getCaptureQualityFeedback(state) {
   return FEEDBACK_MESSAGES.perfect;
 }
 function canCaptureFrame(state) {
-  const { hasFace, alignment, tooClose, tooFar, isBlurry, isPartialFace } = state;
-  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace;
+  const {
+    hasFace,
+    alignment,
+    tooClose,
+    tooFar,
+    isBlurry,
+    isPartialFace,
+    tooFarFromIdeal,
+    tooCloseToIdeal,
+    phoneAngled,
+    phoneTilted
+  } = state;
+  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace && !tooFarFromIdeal && !tooCloseToIdeal && !phoneAngled && !phoneTilted;
 }
 
 // src/utils/validators.ts
@@ -1439,15 +1488,17 @@ var MIN_FACE_SIDE_MARGIN = 0.05;
 var MIN_CAPTURE_ALIGNMENT = 0.6;
 var HIGH_ALIGNMENT = 0.85;
 var GOOD_ALIGNMENT = 0.5;
-var IDEAL_CROP_MULTIPLIER = 2;
-var MIN_CROP_MULTIPLIER = 1.8;
-var MAX_CROP_MULTIPLIER = 2.5;
+var IDEAL_CROP_MULTIPLIER = 3;
+var MIN_CROP_MULTIPLIER = 2.5;
+var MAX_CROP_MULTIPLIER = 4;
 var FACE_CENTER_VERTICAL_OFFSET = 0.05;
+var MIN_IDEAL_FACE_RATIO = 0.05;
+var MAX_IDEAL_FACE_RATIO = 0.2;
 var MIN_FACE_RATIO = 0.036;
 var MAX_FACE_RATIO = 0.7;
 var FACE_CROP_OUTPUT_SIZE = 224;
-var MAX_FACE_PERCENTAGE_IN_CROP = 0.6;
-var TARGET_FACE_PERCENTAGE_IN_CROP = 0.5;
+var MAX_FACE_PERCENTAGE_IN_CROP = 0.45;
+var TARGET_FACE_PERCENTAGE_IN_CROP = 0.33;
 function analyzeBlur(grayscalePixels, width, height, threshold = DEFAULT_BLUR_THRESHOLD) {
   const laplacian = [];
   for (let y = 1; y < height - 1; y++) {
@@ -1543,9 +1594,9 @@ var OVAL_REGION_DESKTOP = {
 var OVAL_REGION_MOBILE = {
   centerX: 0.5,
   centerY: 0.5,
-  width: 0.55,
-  height: 0.73
-  // 0.55 * (4/3)
+  width: 0.48,
+  height: 0.64
+  // 0.48 * (4/3)
 };
 var DEFAULT_OVAL_REGION = OVAL_REGION_DESKTOP;
 function isFaceInOval(faceBox, frameWidth, frameHeight, oval = DEFAULT_OVAL_REGION, tolerance = 0.3) {
@@ -1701,6 +1752,33 @@ function checkFrameQuality(options) {
   }
   return result;
 }
+var MAX_FACE_ROLL_DEGREES = 15;
+function detectFaceRoll(landmarks) {
+  if (landmarks.length < 364) {
+    return { roll: 0, tooTilted: false };
+  }
+  const l33 = landmarks[33];
+  const l133 = landmarks[133];
+  const l362 = landmarks[362];
+  const l263 = landmarks[263];
+  if (!l33 || !l133 || !l362 || !l263) {
+    return { roll: 0, tooTilted: false };
+  }
+  const leftEyeX = (l33.x + l133.x) / 2;
+  const leftEyeY = (l33.y + l133.y) / 2;
+  const rightEyeX = (l362.x + l263.x) / 2;
+  const rightEyeY = (l362.y + l263.y) / 2;
+  const eyeXDist = Math.abs(leftEyeX - rightEyeX);
+  const eyeYDiff = Math.abs(leftEyeY - rightEyeY);
+  if (eyeXDist < 0.01) {
+    return { roll: 0, tooTilted: false };
+  }
+  const roll = Math.atan2(eyeYDiff, eyeXDist) * (180 / Math.PI);
+  return {
+    roll,
+    tooTilted: roll > MAX_FACE_ROLL_DEGREES
+  };
+}
 var BaseFrameCollector = class {
   constructor(maxFrames = 10) {
     this.frames = [];
@@ -1810,7 +1888,7 @@ var EYE_QUALITY_THRESHOLDS = {
   minBrightness: 40,
   maxBrightness: 230,
   minContrast: 12,
-  glarePixelThreshold: 240,
+  glareRelativeFactor: 2.5,
   maxGlareRatio: 0.15
 };
 function rgbaToLuminance(r, g, b) {
@@ -1837,9 +1915,11 @@ function analyzeEyeRegionContrast(pixels, meanBrightness) {
   }
   return Math.sqrt(sumSqDiff / pixelCount);
 }
-function detectSpecularHighlights(pixels, threshold = EYE_QUALITY_THRESHOLDS.glarePixelThreshold) {
+function detectSpecularHighlights(pixels, relativeFactor = EYE_QUALITY_THRESHOLDS.glareRelativeFactor, meanBrightness) {
   const pixelCount = pixels.length / 4;
   if (pixelCount === 0) return 0;
+  const mean = meanBrightness ?? analyzeEyeRegionBrightness(pixels);
+  const threshold = mean * relativeFactor;
   let glareCount = 0;
   for (let i = 0; i < pixels.length; i += 4) {
     const lum = rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
@@ -1862,7 +1942,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   }
   const brightness = analyzeEyeRegionBrightness(pixels);
   const contrast = analyzeEyeRegionContrast(pixels, brightness);
-  const glareRatio = detectSpecularHighlights(pixels, thresholds.glarePixelThreshold);
+  const glareRatio = detectSpecularHighlights(pixels, thresholds.glareRelativeFactor, brightness);
   const hasGlare = glareRatio > thresholds.maxGlareRatio;
   if (brightness < thresholds.minBrightness) {
     return {
@@ -1884,16 +1964,6 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
       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,
@@ -1961,12 +2031,15 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   MAX_CROP_MULTIPLIER,
   MAX_FACE_PERCENTAGE_IN_CROP,
   MAX_FACE_RATIO,
+  MAX_FACE_ROLL_DEGREES,
+  MAX_IDEAL_FACE_RATIO,
   MIN_CAPTURE_ALIGNMENT,
   MIN_CROP_MULTIPLIER,
   MIN_FACE_BOTTOM_MARGIN,
   MIN_FACE_RATIO,
   MIN_FACE_SIDE_MARGIN,
   MIN_FACE_TOP_MARGIN,
+  MIN_IDEAL_FACE_RATIO,
   MIN_LANDMARK_COUNT,
   MODEL_CONFIGS,
   OVAL_GUIDE_COLORS,
@@ -1987,6 +2060,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectFaceRoll,
   detectSpecularHighlights,
   encodeBase64,
   generateSessionId,

package/dist/index.mjs

@@ -128,7 +128,8 @@ function toLivenessResult(response) {
     score: response.score ?? 0,
     sessionId: response.session_id,
     processingMs: response.processing_ms,
-    framesProcessed: "frames_processed" in response ? response.frames_processed ?? 0 : 0
+    framesProcessed: "frames_processed" in response ? response.frames_processed ?? 0 : 0,
+    warnings: "warnings" in response && Array.isArray(response.warnings) ? response.warnings : void 0
   };
 }
 function toLivenessResultFromStream(response) {
@@ -145,7 +146,8 @@ function toLivenessResultFromStream(response) {
     score: response.score ?? 0,
     sessionId: response.session_id,
     processingMs: response.processing_ms ?? 0,
-    framesProcessed: response.frames_processed ?? 0
+    framesProcessed: response.frames_processed ?? 0,
+    warnings: Array.isArray(response.warnings) ? response.warnings : void 0
   };
 }
 function generateSessionId() {
@@ -324,7 +326,8 @@ var LivenessClient = class _LivenessClient {
       session_id: options.sessionId ?? generateSessionId(),
       model: options.model ?? "10",
       source: options.source ?? "live",
-      frames: toFrameData(frames)
+      frames: toFrameData(frames),
+      ...options.warnings?.length ? { warnings: options.warnings } : {}
     };
     const response = await this.requestWithRetry(API_PATHS.fastCheck, {
       method: "POST",
@@ -344,7 +347,8 @@ var LivenessClient = class _LivenessClient {
       session_id: options.sessionId ?? generateSessionId(),
       model: options.model ?? "10",
       source: options.source ?? "live",
-      crops
+      crops,
+      ...options.warnings?.length ? { warnings: options.warnings } : {}
     };
     const response = await this.requestWithRetry(API_PATHS.fastCheckCrops, {
       method: "POST",
@@ -378,7 +382,8 @@ var LivenessClient = class _LivenessClient {
     return this.sendStreamFrameInternal(frameData, {
       sessionId: options.sessionId,
       model: options.model ?? "10",
-      source: options.source ?? "live"
+      source: options.source ?? "live",
+      warnings: options.warnings
     });
   }
   /**
@@ -393,7 +398,8 @@ var LivenessClient = class _LivenessClient {
       session_id: options.sessionId,
       model: options.model,
       source: options.source,
-      frame: frameData
+      frame: frameData,
+      ...options.warnings?.length ? { warnings: options.warnings } : {}
     };
     return this.requestWithRetry(API_PATHS.fastCheckStream, {
       method: "POST",
@@ -422,7 +428,8 @@ var LivenessClient = class _LivenessClient {
       const response = await this.sendStreamFrameInternal(frameData, {
         sessionId,
         model,
-        source
+        source,
+        warnings: options.warnings
       });
       callbacks?.onFrameSent?.(index + 1, total);
       if (response.status === "buffering") {
@@ -471,7 +478,8 @@ var LivenessClient = class _LivenessClient {
       const response = await this.sendStreamFrameInternal(frameData, {
         sessionId,
         model,
-        source
+        source,
+        warnings: options.warnings
       });
       const currentIndex = frameData.index;
       callbacks?.onFrameSent?.(currentIndex + 1, total);
@@ -1048,7 +1056,7 @@ function isRetryableError(code) {
 }
 
 // src/constants/feedback.ts
-var ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
+var ALIGNMENT_THRESHOLD_CAPTURE = 0.85;
 var ALIGNMENT_THRESHOLD_POOR = 0.6;
 var ALIGNMENT_THRESHOLD_GOOD = 0.6;
 var ALIGNMENT_THRESHOLD_PERFECT = 0.85;
@@ -1101,6 +1109,8 @@ var FEEDBACK_MESSAGES = {
   move_back: "Move back - face too close",
   too_close: "Move back - face too close",
   too_far: "Move closer - face too far",
+  move_closer_ideal: "Move a little closer",
+  move_back_ideal: "Move back slightly",
   // Visibility issues
   face_not_visible: "Center your face - edges cut off",
   partial_face: "Center your face - edges cut off",
@@ -1111,6 +1121,9 @@ var FEEDBACK_MESSAGES = {
   poor_lighting: "Improve lighting",
   too_dark: "Low lighting - move to a brighter area",
   backlit: "Backlit - try facing the light source",
+  // Phone orientation
+  phone_angle_low: "Raise your phone to eye level",
+  phone_tilted: "Hold your phone level",
   // Hand occlusion
   hand_detected: "Remove hand from face",
   // Eye region quality
@@ -1158,6 +1171,8 @@ var ES_LOCALE = {
     move_back: "Al\xE9jate - rostro muy cerca",
     too_close: "Al\xE9jate - rostro muy cerca",
     too_far: "Ac\xE9rcate - rostro muy lejos",
+    move_closer_ideal: "Ac\xE9rcate un poco",
+    move_back_ideal: "Al\xE9jate un poco",
     // Visibility issues
     face_not_visible: "Centra tu rostro - bordes cortados",
     partial_face: "Centra tu rostro - bordes cortados",
@@ -1168,6 +1183,9 @@ var ES_LOCALE = {
     poor_lighting: "Mejora la iluminaci\xF3n",
     too_dark: "Poca luz - mu\xE9vete a un \xE1rea m\xE1s iluminada",
     backlit: "Contraluz - intenta mirar hacia la fuente de luz",
+    // Phone orientation
+    phone_angle_low: "Levanta el tel\xE9fono a la altura de los ojos",
+    phone_tilted: "Mant\xE9n el tel\xE9fono nivelado",
     // Hand occlusion
     hand_detected: "Retira la mano del rostro",
     // Eye region quality
@@ -1200,11 +1218,21 @@ function getCaptureQualityFeedback(state) {
     isBlurry,
     isPartialFace,
     framesCaptured,
-    targetFrames
+    targetFrames,
+    tooFarFromIdeal,
+    tooCloseToIdeal,
+    phoneAngled,
+    phoneTilted
   } = state;
   if (!hasFace) {
     return FEEDBACK_MESSAGES.no_face;
   }
+  if (phoneTilted) {
+    return FEEDBACK_MESSAGES.phone_tilted;
+  }
+  if (phoneAngled) {
+    return FEEDBACK_MESSAGES.phone_angle_low;
+  }
   if (tooClose) {
     return FEEDBACK_MESSAGES.too_close;
   }
@@ -1217,6 +1245,12 @@ function getCaptureQualityFeedback(state) {
   if (isBlurry) {
     return FEEDBACK_MESSAGES.blurry;
   }
+  if (tooFarFromIdeal) {
+    return FEEDBACK_MESSAGES.move_closer_ideal;
+  }
+  if (tooCloseToIdeal) {
+    return FEEDBACK_MESSAGES.move_back_ideal;
+  }
   if (alignment < ALIGNMENT_THRESHOLD_POOR) {
     return FEEDBACK_MESSAGES.move_closer_to_center;
   }
@@ -1232,8 +1266,19 @@ function getCaptureQualityFeedback(state) {
   return FEEDBACK_MESSAGES.perfect;
 }
 function canCaptureFrame(state) {
-  const { hasFace, alignment, tooClose, tooFar, isBlurry, isPartialFace } = state;
-  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace;
+  const {
+    hasFace,
+    alignment,
+    tooClose,
+    tooFar,
+    isBlurry,
+    isPartialFace,
+    tooFarFromIdeal,
+    tooCloseToIdeal,
+    phoneAngled,
+    phoneTilted
+  } = state;
+  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace && !tooFarFromIdeal && !tooCloseToIdeal && !phoneAngled && !phoneTilted;
 }
 
 // src/utils/validators.ts
@@ -1310,15 +1355,17 @@ var MIN_FACE_SIDE_MARGIN = 0.05;
 var MIN_CAPTURE_ALIGNMENT = 0.6;
 var HIGH_ALIGNMENT = 0.85;
 var GOOD_ALIGNMENT = 0.5;
-var IDEAL_CROP_MULTIPLIER = 2;
-var MIN_CROP_MULTIPLIER = 1.8;
-var MAX_CROP_MULTIPLIER = 2.5;
+var IDEAL_CROP_MULTIPLIER = 3;
+var MIN_CROP_MULTIPLIER = 2.5;
+var MAX_CROP_MULTIPLIER = 4;
 var FACE_CENTER_VERTICAL_OFFSET = 0.05;
+var MIN_IDEAL_FACE_RATIO = 0.05;
+var MAX_IDEAL_FACE_RATIO = 0.2;
 var MIN_FACE_RATIO = 0.036;
 var MAX_FACE_RATIO = 0.7;
 var FACE_CROP_OUTPUT_SIZE = 224;
-var MAX_FACE_PERCENTAGE_IN_CROP = 0.6;
-var TARGET_FACE_PERCENTAGE_IN_CROP = 0.5;
+var MAX_FACE_PERCENTAGE_IN_CROP = 0.45;
+var TARGET_FACE_PERCENTAGE_IN_CROP = 0.33;
 function analyzeBlur(grayscalePixels, width, height, threshold = DEFAULT_BLUR_THRESHOLD) {
   const laplacian = [];
   for (let y = 1; y < height - 1; y++) {
@@ -1414,9 +1461,9 @@ var OVAL_REGION_DESKTOP = {
 var OVAL_REGION_MOBILE = {
   centerX: 0.5,
   centerY: 0.5,
-  width: 0.55,
-  height: 0.73
-  // 0.55 * (4/3)
+  width: 0.48,
+  height: 0.64
+  // 0.48 * (4/3)
 };
 var DEFAULT_OVAL_REGION = OVAL_REGION_DESKTOP;
 function isFaceInOval(faceBox, frameWidth, frameHeight, oval = DEFAULT_OVAL_REGION, tolerance = 0.3) {
@@ -1572,6 +1619,33 @@ function checkFrameQuality(options) {
   }
   return result;
 }
+var MAX_FACE_ROLL_DEGREES = 15;
+function detectFaceRoll(landmarks) {
+  if (landmarks.length < 364) {
+    return { roll: 0, tooTilted: false };
+  }
+  const l33 = landmarks[33];
+  const l133 = landmarks[133];
+  const l362 = landmarks[362];
+  const l263 = landmarks[263];
+  if (!l33 || !l133 || !l362 || !l263) {
+    return { roll: 0, tooTilted: false };
+  }
+  const leftEyeX = (l33.x + l133.x) / 2;
+  const leftEyeY = (l33.y + l133.y) / 2;
+  const rightEyeX = (l362.x + l263.x) / 2;
+  const rightEyeY = (l362.y + l263.y) / 2;
+  const eyeXDist = Math.abs(leftEyeX - rightEyeX);
+  const eyeYDiff = Math.abs(leftEyeY - rightEyeY);
+  if (eyeXDist < 0.01) {
+    return { roll: 0, tooTilted: false };
+  }
+  const roll = Math.atan2(eyeYDiff, eyeXDist) * (180 / Math.PI);
+  return {
+    roll,
+    tooTilted: roll > MAX_FACE_ROLL_DEGREES
+  };
+}
 var BaseFrameCollector = class {
   constructor(maxFrames = 10) {
     this.frames = [];
@@ -1681,7 +1755,7 @@ var EYE_QUALITY_THRESHOLDS = {
   minBrightness: 40,
   maxBrightness: 230,
   minContrast: 12,
-  glarePixelThreshold: 240,
+  glareRelativeFactor: 2.5,
   maxGlareRatio: 0.15
 };
 function rgbaToLuminance(r, g, b) {
@@ -1708,9 +1782,11 @@ function analyzeEyeRegionContrast(pixels, meanBrightness) {
   }
   return Math.sqrt(sumSqDiff / pixelCount);
 }
-function detectSpecularHighlights(pixels, threshold = EYE_QUALITY_THRESHOLDS.glarePixelThreshold) {
+function detectSpecularHighlights(pixels, relativeFactor = EYE_QUALITY_THRESHOLDS.glareRelativeFactor, meanBrightness) {
   const pixelCount = pixels.length / 4;
   if (pixelCount === 0) return 0;
+  const mean = meanBrightness ?? analyzeEyeRegionBrightness(pixels);
+  const threshold = mean * relativeFactor;
   let glareCount = 0;
   for (let i = 0; i < pixels.length; i += 4) {
     const lum = rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
@@ -1733,7 +1809,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   }
   const brightness = analyzeEyeRegionBrightness(pixels);
   const contrast = analyzeEyeRegionContrast(pixels, brightness);
-  const glareRatio = detectSpecularHighlights(pixels, thresholds.glarePixelThreshold);
+  const glareRatio = detectSpecularHighlights(pixels, thresholds.glareRelativeFactor, brightness);
   const hasGlare = glareRatio > thresholds.maxGlareRatio;
   if (brightness < thresholds.minBrightness) {
     return {
@@ -1755,16 +1831,6 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
       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,
@@ -1831,12 +1897,15 @@ export {
   MAX_CROP_MULTIPLIER,
   MAX_FACE_PERCENTAGE_IN_CROP,
   MAX_FACE_RATIO,
+  MAX_FACE_ROLL_DEGREES,
+  MAX_IDEAL_FACE_RATIO,
   MIN_CAPTURE_ALIGNMENT,
   MIN_CROP_MULTIPLIER,
   MIN_FACE_BOTTOM_MARGIN,
   MIN_FACE_RATIO,
   MIN_FACE_SIDE_MARGIN,
   MIN_FACE_TOP_MARGIN,
+  MIN_IDEAL_FACE_RATIO,
   MIN_LANDMARK_COUNT,
   MODEL_CONFIGS,
   OVAL_GUIDE_COLORS,
@@ -1857,6 +1926,7 @@ export {
   checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectFaceRoll,
   detectSpecularHighlights,
   encodeBase64,
   generateSessionId,

package/package.json

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