@moveris/shared 2.6.0 → 2.9.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>`
 
@@ -94,6 +94,7 @@ const crops: CropData[] = capturedFrames.map((f) => ({
 const result = await client.fastCheckCrops(crops, {
   model: '10',
   source: 'live',
+  bgSegmentation: true, // optional — sent as bg_segmentation in payload
 });
 ```
 
@@ -184,22 +185,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
 
@@ -431,6 +444,9 @@ const status = getStatusMessage('capturing', DEFAULT_LOCALE);
 | `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  |
+| `camera_angle_low`  | "Raise camera to eye level"    | Camera below face (Y < 0.3)  |
+| `camera_angle_high` | "Lower camera to eye level"    | Camera above face (Y > 0.7)  |
+| `camera_tilted`     | "Hold camera level"            | Eye line deviates > 15°      |
 
 ---
 
@@ -492,6 +508,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
@@ -515,7 +533,13 @@ if (bounds) {
 Utilities for assessing frame quality before submission.
 
 ```typescript
-import { isFaceFullyVisible, isFaceInOval, calculateFaceCropRegion } from '@moveris/shared';
+import {
+  isFaceFullyVisible,
+  isFaceInOval,
+  calculateFaceCropRegion,
+  detectFaceRoll,
+  detectCameraAngle,
+} from '@moveris/shared';
 
 // Check if face is fully visible in frame
 const visibility = isFaceFullyVisible(faceBbox, frameWidth, frameHeight);
@@ -533,8 +557,17 @@ const cropRegion = calculateFaceCropRegion(faceBbox, frameWidth, frameHeight);
 
 // Calculate adaptive crop multiplier based on face size
 import { calculateAdaptiveCropMultiplier } from '@moveris/shared';
-const multiplier = calculateAdaptiveCropMultiplier(faceSize, videoSize);
-// Returns 1.8–2.5x (matched to cognito-check for ~50% face coverage)
+const multiplier = calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight);
+// Returns 2.5–4.0x (matched to cognito-check for ~33% face coverage in 224×224 crop)
+
+// Detect face roll (device tilt) from eye-corner landmarks
+const rollResult = detectFaceRoll(landmarks); // requires ≥364 landmarks
+// { roll: number (degrees), tooTilted: boolean }
+
+// Detect camera vertical angle from forehead/nose/chin landmark ratio
+const angleResult = detectCameraAngle(landmarks); // requires ≥153 landmarks
+// { ratio: number, cameraAbove: boolean, cameraBelow: boolean }
+// ratio ~1.0 at eye level; >1.35 = camera above user; <0.75 = camera below user
 ```
 
 #### Crop Constants (aligned with cognito-check)

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 {
@@ -296,7 +301,7 @@ interface FrameQualityResult {
     alignment?: FaceAlignmentResult;
     rejectionReason?: 'blur' | 'backlit' | 'low_light' | 'partial_face' | 'no_face' | 'too_close' | 'too_far' | 'misaligned';
 }
-declare const DEFAULT_BLUR_THRESHOLD = 100;
+declare const DEFAULT_BLUR_THRESHOLD = 110;
 declare const BLUR_THRESHOLD_MOBILE = 60;
 declare const BACKLIT_RATIO_THRESHOLD = 0.6;
 declare const LOW_LIGHT_THRESHOLD = 50;
@@ -348,6 +353,14 @@ interface FaceRollResult {
 }
 declare const MAX_FACE_ROLL_DEGREES = 15;
 declare function detectFaceRoll(landmarks: FaceLandmarkPoint[]): FaceRollResult;
+interface CameraAngleResult {
+    ratio: number;
+    cameraAbove: boolean;
+    cameraBelow: boolean;
+}
+declare const CAMERA_ANGLE_HIGH_RATIO = 1.35;
+declare const CAMERA_ANGLE_LOW_RATIO = 0.75;
+declare function detectCameraAngle(landmarks: FaceLandmarkPoint[]): CameraAngleResult;
 declare class BaseFrameCollector {
     protected frames: CapturedFrame[];
     protected maxFrames: number;
@@ -477,22 +490,27 @@ 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[];
+        bgSegmentation?: boolean;
     }): 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;
@@ -501,6 +519,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;
@@ -694,8 +713,9 @@ 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 camera_angle_low: "Raise camera to eye level";
+    readonly camera_angle_high: "Lower camera to eye level";
+    readonly camera_tilted: "Hold camera 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";
@@ -728,8 +748,9 @@ interface CaptureQualityState {
     targetFrames: number;
     tooFarFromIdeal?: boolean;
     tooCloseToIdeal?: boolean;
-    phoneAngled?: boolean;
-    phoneTilted?: boolean;
+    cameraAngleLow?: boolean;
+    cameraAngleHigh?: boolean;
+    cameraTilted?: boolean;
 }
 declare function getCaptureQualityFeedback(state: CaptureQualityState): string;
 declare function canCaptureFrame(state: Omit<CaptureQualityState, 'framesCaptured' | 'targetFrames' | 'isCapturing'>): boolean;
@@ -771,13 +792,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 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 };
+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, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, 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, detectCameraAngle, 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 {
@@ -296,7 +301,7 @@ interface FrameQualityResult {
     alignment?: FaceAlignmentResult;
     rejectionReason?: 'blur' | 'backlit' | 'low_light' | 'partial_face' | 'no_face' | 'too_close' | 'too_far' | 'misaligned';
 }
-declare const DEFAULT_BLUR_THRESHOLD = 100;
+declare const DEFAULT_BLUR_THRESHOLD = 110;
 declare const BLUR_THRESHOLD_MOBILE = 60;
 declare const BACKLIT_RATIO_THRESHOLD = 0.6;
 declare const LOW_LIGHT_THRESHOLD = 50;
@@ -348,6 +353,14 @@ interface FaceRollResult {
 }
 declare const MAX_FACE_ROLL_DEGREES = 15;
 declare function detectFaceRoll(landmarks: FaceLandmarkPoint[]): FaceRollResult;
+interface CameraAngleResult {
+    ratio: number;
+    cameraAbove: boolean;
+    cameraBelow: boolean;
+}
+declare const CAMERA_ANGLE_HIGH_RATIO = 1.35;
+declare const CAMERA_ANGLE_LOW_RATIO = 0.75;
+declare function detectCameraAngle(landmarks: FaceLandmarkPoint[]): CameraAngleResult;
 declare class BaseFrameCollector {
     protected frames: CapturedFrame[];
     protected maxFrames: number;
@@ -477,22 +490,27 @@ 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[];
+        bgSegmentation?: boolean;
     }): 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;
@@ -501,6 +519,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;
@@ -694,8 +713,9 @@ 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 camera_angle_low: "Raise camera to eye level";
+    readonly camera_angle_high: "Lower camera to eye level";
+    readonly camera_tilted: "Hold camera 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";
@@ -728,8 +748,9 @@ interface CaptureQualityState {
     targetFrames: number;
     tooFarFromIdeal?: boolean;
     tooCloseToIdeal?: boolean;
-    phoneAngled?: boolean;
-    phoneTilted?: boolean;
+    cameraAngleLow?: boolean;
+    cameraAngleHigh?: boolean;
+    cameraTilted?: boolean;
 }
 declare function getCaptureQualityFeedback(state: CaptureQualityState): string;
 declare function canCaptureFrame(state: Omit<CaptureQualityState, 'framesCaptured' | 'targetFrames' | 'isCapturing'>): boolean;
@@ -771,13 +792,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 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 };
+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, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, 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, detectCameraAngle, 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

@@ -31,6 +31,8 @@ __export(index_exports, {
   BACKLIT_RATIO_THRESHOLD: () => BACKLIT_RATIO_THRESHOLD,
   BLUR_THRESHOLD_MOBILE: () => BLUR_THRESHOLD_MOBILE,
   BaseFrameCollector: () => BaseFrameCollector,
+  CAMERA_ANGLE_HIGH_RATIO: () => CAMERA_ANGLE_HIGH_RATIO,
+  CAMERA_ANGLE_LOW_RATIO: () => CAMERA_ANGLE_LOW_RATIO,
   DEFAULT_BLUR_THRESHOLD: () => DEFAULT_BLUR_THRESHOLD,
   DEFAULT_ENDPOINT: () => DEFAULT_ENDPOINT,
   DEFAULT_FACE_DETECTION_TIERS: () => DEFAULT_FACE_DETECTION_TIERS,
@@ -95,6 +97,7 @@ __export(index_exports, {
   checkEyeRegionQuality: () => checkEyeRegionQuality,
   checkFrameQuality: () => checkFrameQuality,
   decodeBase64: () => decodeBase64,
+  detectCameraAngle: () => detectCameraAngle,
   detectFaceRoll: () => detectFaceRoll,
   detectSpecularHighlights: () => detectSpecularHighlights,
   encodeBase64: () => encodeBase64,
@@ -261,7 +264,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) {
@@ -278,7 +282,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() {
@@ -457,7 +462,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",
@@ -477,7 +483,9 @@ 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 } : {},
+      ...options.bgSegmentation !== void 0 ? { bg_segmentation: options.bgSegmentation } : {}
     };
     const response = await this.requestWithRetry(API_PATHS.fastCheckCrops, {
       method: "POST",
@@ -511,7 +519,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
     });
   }
   /**
@@ -526,7 +535,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",
@@ -555,7 +565,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") {
@@ -604,7 +615,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);
@@ -1246,9 +1258,10 @@ 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",
+  // Camera angle (platform-agnostic)
+  camera_angle_low: "Raise camera to eye level",
+  camera_angle_high: "Lower camera to eye level",
+  camera_tilted: "Hold camera level",
   // Hand occlusion
   hand_detected: "Remove hand from face",
   // Eye region quality
@@ -1308,9 +1321,10 @@ 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",
+    // Camera angle (platform-agnostic)
+    camera_angle_low: "Levanta la c\xE1mara a la altura de los ojos",
+    camera_angle_high: "Baja la c\xE1mara a la altura de los ojos",
+    camera_tilted: "Mant\xE9n la c\xE1mara nivelada",
     // Hand occlusion
     hand_detected: "Retira la mano del rostro",
     // Eye region quality
@@ -1346,17 +1360,21 @@ function getCaptureQualityFeedback(state) {
     targetFrames,
     tooFarFromIdeal,
     tooCloseToIdeal,
-    phoneAngled,
-    phoneTilted
+    cameraAngleLow,
+    cameraAngleHigh,
+    cameraTilted
   } = state;
   if (!hasFace) {
     return FEEDBACK_MESSAGES.no_face;
   }
-  if (phoneTilted) {
-    return FEEDBACK_MESSAGES.phone_tilted;
+  if (cameraTilted) {
+    return FEEDBACK_MESSAGES.camera_tilted;
   }
-  if (phoneAngled) {
-    return FEEDBACK_MESSAGES.phone_angle_low;
+  if (cameraAngleLow) {
+    return FEEDBACK_MESSAGES.camera_angle_low;
+  }
+  if (cameraAngleHigh) {
+    return FEEDBACK_MESSAGES.camera_angle_high;
   }
   if (tooClose) {
     return FEEDBACK_MESSAGES.too_close;
@@ -1400,10 +1418,11 @@ function canCaptureFrame(state) {
     isPartialFace,
     tooFarFromIdeal,
     tooCloseToIdeal,
-    phoneAngled,
-    phoneTilted
+    cameraAngleLow,
+    cameraAngleHigh,
+    cameraTilted
   } = state;
-  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace && !tooFarFromIdeal && !tooCloseToIdeal && !phoneAngled && !phoneTilted;
+  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace && !tooFarFromIdeal && !tooCloseToIdeal && !cameraAngleLow && !cameraAngleHigh && !cameraTilted;
 }
 
 // src/utils/validators.ts
@@ -1470,7 +1489,7 @@ function decodeBase64(base64) {
 }
 
 // src/utils/frameAnalysis.ts
-var DEFAULT_BLUR_THRESHOLD = 100;
+var DEFAULT_BLUR_THRESHOLD = 110;
 var BLUR_THRESHOLD_MOBILE = 60;
 var BACKLIT_RATIO_THRESHOLD = 0.6;
 var LOW_LIGHT_THRESHOLD = 50;
@@ -1771,6 +1790,30 @@ function detectFaceRoll(landmarks) {
     tooTilted: roll > MAX_FACE_ROLL_DEGREES
   };
 }
+var CAMERA_ANGLE_HIGH_RATIO = 1.35;
+var CAMERA_ANGLE_LOW_RATIO = 0.75;
+function detectCameraAngle(landmarks) {
+  if (landmarks.length < 153) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const forehead = landmarks[10];
+  const noseTip = landmarks[1];
+  const chin = landmarks[152];
+  if (!forehead || !noseTip || !chin) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const foreheadToNose = Math.abs(forehead.y - noseTip.y);
+  const noseToChin = Math.abs(noseTip.y - chin.y);
+  if (noseToChin < 1e-3) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const ratio = foreheadToNose / noseToChin;
+  return {
+    ratio,
+    cameraAbove: ratio > CAMERA_ANGLE_HIGH_RATIO,
+    cameraBelow: ratio < CAMERA_ANGLE_LOW_RATIO
+  };
+}
 var BaseFrameCollector = class {
   constructor(maxFrames = 10) {
     this.frames = [];
@@ -1880,7 +1923,7 @@ var EYE_QUALITY_THRESHOLDS = {
   minBrightness: 40,
   maxBrightness: 230,
   minContrast: 12,
-  glarePixelThreshold: 240,
+  glareRelativeFactor: 2.5,
   maxGlareRatio: 0.15
 };
 function rgbaToLuminance(r, g, b) {
@@ -1907,9 +1950,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]);
@@ -1932,7 +1977,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 {
@@ -1954,16 +1999,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,
@@ -1996,6 +2031,8 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   BACKLIT_RATIO_THRESHOLD,
   BLUR_THRESHOLD_MOBILE,
   BaseFrameCollector,
+  CAMERA_ANGLE_HIGH_RATIO,
+  CAMERA_ANGLE_LOW_RATIO,
   DEFAULT_BLUR_THRESHOLD,
   DEFAULT_ENDPOINT,
   DEFAULT_FACE_DETECTION_TIERS,
@@ -2060,6 +2097,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectCameraAngle,
   detectFaceRoll,
   detectSpecularHighlights,
   encodeBase64,

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,9 @@ 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 } : {},
+      ...options.bgSegmentation !== void 0 ? { bg_segmentation: options.bgSegmentation } : {}
     };
     const response = await this.requestWithRetry(API_PATHS.fastCheckCrops, {
       method: "POST",
@@ -378,7 +383,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 +399,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 +429,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 +479,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);
@@ -1113,9 +1122,10 @@ 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",
+  // Camera angle (platform-agnostic)
+  camera_angle_low: "Raise camera to eye level",
+  camera_angle_high: "Lower camera to eye level",
+  camera_tilted: "Hold camera level",
   // Hand occlusion
   hand_detected: "Remove hand from face",
   // Eye region quality
@@ -1175,9 +1185,10 @@ 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",
+    // Camera angle (platform-agnostic)
+    camera_angle_low: "Levanta la c\xE1mara a la altura de los ojos",
+    camera_angle_high: "Baja la c\xE1mara a la altura de los ojos",
+    camera_tilted: "Mant\xE9n la c\xE1mara nivelada",
     // Hand occlusion
     hand_detected: "Retira la mano del rostro",
     // Eye region quality
@@ -1213,17 +1224,21 @@ function getCaptureQualityFeedback(state) {
     targetFrames,
     tooFarFromIdeal,
     tooCloseToIdeal,
-    phoneAngled,
-    phoneTilted
+    cameraAngleLow,
+    cameraAngleHigh,
+    cameraTilted
   } = state;
   if (!hasFace) {
     return FEEDBACK_MESSAGES.no_face;
   }
-  if (phoneTilted) {
-    return FEEDBACK_MESSAGES.phone_tilted;
+  if (cameraTilted) {
+    return FEEDBACK_MESSAGES.camera_tilted;
   }
-  if (phoneAngled) {
-    return FEEDBACK_MESSAGES.phone_angle_low;
+  if (cameraAngleLow) {
+    return FEEDBACK_MESSAGES.camera_angle_low;
+  }
+  if (cameraAngleHigh) {
+    return FEEDBACK_MESSAGES.camera_angle_high;
   }
   if (tooClose) {
     return FEEDBACK_MESSAGES.too_close;
@@ -1267,10 +1282,11 @@ function canCaptureFrame(state) {
     isPartialFace,
     tooFarFromIdeal,
     tooCloseToIdeal,
-    phoneAngled,
-    phoneTilted
+    cameraAngleLow,
+    cameraAngleHigh,
+    cameraTilted
   } = state;
-  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace && !tooFarFromIdeal && !tooCloseToIdeal && !phoneAngled && !phoneTilted;
+  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace && !tooFarFromIdeal && !tooCloseToIdeal && !cameraAngleLow && !cameraAngleHigh && !cameraTilted;
 }
 
 // src/utils/validators.ts
@@ -1337,7 +1353,7 @@ function decodeBase64(base64) {
 }
 
 // src/utils/frameAnalysis.ts
-var DEFAULT_BLUR_THRESHOLD = 100;
+var DEFAULT_BLUR_THRESHOLD = 110;
 var BLUR_THRESHOLD_MOBILE = 60;
 var BACKLIT_RATIO_THRESHOLD = 0.6;
 var LOW_LIGHT_THRESHOLD = 50;
@@ -1638,6 +1654,30 @@ function detectFaceRoll(landmarks) {
     tooTilted: roll > MAX_FACE_ROLL_DEGREES
   };
 }
+var CAMERA_ANGLE_HIGH_RATIO = 1.35;
+var CAMERA_ANGLE_LOW_RATIO = 0.75;
+function detectCameraAngle(landmarks) {
+  if (landmarks.length < 153) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const forehead = landmarks[10];
+  const noseTip = landmarks[1];
+  const chin = landmarks[152];
+  if (!forehead || !noseTip || !chin) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const foreheadToNose = Math.abs(forehead.y - noseTip.y);
+  const noseToChin = Math.abs(noseTip.y - chin.y);
+  if (noseToChin < 1e-3) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const ratio = foreheadToNose / noseToChin;
+  return {
+    ratio,
+    cameraAbove: ratio > CAMERA_ANGLE_HIGH_RATIO,
+    cameraBelow: ratio < CAMERA_ANGLE_LOW_RATIO
+  };
+}
 var BaseFrameCollector = class {
   constructor(maxFrames = 10) {
     this.frames = [];
@@ -1747,7 +1787,7 @@ var EYE_QUALITY_THRESHOLDS = {
   minBrightness: 40,
   maxBrightness: 230,
   minContrast: 12,
-  glarePixelThreshold: 240,
+  glareRelativeFactor: 2.5,
   maxGlareRatio: 0.15
 };
 function rgbaToLuminance(r, g, b) {
@@ -1774,9 +1814,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]);
@@ -1799,7 +1841,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 {
@@ -1821,16 +1863,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,
@@ -1862,6 +1894,8 @@ export {
   BACKLIT_RATIO_THRESHOLD,
   BLUR_THRESHOLD_MOBILE,
   BaseFrameCollector,
+  CAMERA_ANGLE_HIGH_RATIO,
+  CAMERA_ANGLE_LOW_RATIO,
   DEFAULT_BLUR_THRESHOLD,
   DEFAULT_ENDPOINT,
   DEFAULT_FACE_DETECTION_TIERS,
@@ -1926,6 +1960,7 @@ export {
   checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectCameraAngle,
   detectFaceRoll,
   detectSpecularHighlights,
   encodeBase64,

package/package.json

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