@moveris/shared 2.0.0 → 2.1.1

package/README.md

@@ -80,11 +80,33 @@ const result = await client.fastCheck(frames, {
 
 ##### `fastCheckCrops(crops, options)`
 
-Perform fast liveness check with pre-cropped 224x224 face images. Use this when you handle face detection client-side.
+Perform fast liveness check with pre-cropped 224x224 face images. Use this when you handle face detection client-side. Expects `CropData[]` (no timestamps — only `index` and `pixels`).
 
 ```typescript
+import type { CropData } from '@moveris/shared';
+
+const crops: CropData[] = capturedFrames.map((f) => ({
+  index: f.index,
+  pixels: f.pixels, // base64 224x224 PNG
+}));
+
 const result = await client.fastCheckCrops(crops, {
-  model: '50',
+  model: '10',
+  source: 'live',
+});
+```
+
+##### `streamFrame(frame, options)`
+
+Send a single frame to the streaming endpoint. Returns the API response which may include a partial or final result. Used internally by `useLiveness` for sequential streaming.
+
+```typescript
+const response = await client.streamFrame(frame, {
+  sessionId: 'uuid',
+  model: '10',
+  source: 'live',
+  frameIndex: 0,
+  totalFrames: 10,
 });
 ```
 
@@ -160,14 +182,23 @@ const job = await client.waitForJobResult('job-uuid', 30);
 Model selection for liveness detection speed/accuracy trade-off.
 
 ```typescript
-type FastCheckModel = '10' | '50' | '250';
+type FastCheckModel =
+  | '10'
+  | '50'
+  | '250' // Standard models
+  | 'hybrid-v2-10'
+  | 'hybrid-v2-50' // Hybrid V2 (physiological features)
+  | 'mixed-10'; // Mixed (visual + physiological scoring)
 ```
 
-| Value   | Frames | Description                       |
-| ------- | ------ | --------------------------------- |
-| `'10'`  | 10     | Fast verification, lowest latency |
-| `'50'`  | 50     | Balanced speed and accuracy       |
-| `'250'` | 250    | Highest accuracy, slower          |
+| 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   |
 
 #### FrameSource
 
@@ -236,6 +267,17 @@ interface CapturedFrame {
 }
 ```
 
+#### CropData
+
+Pre-cropped face image for the `fast-check-crops` endpoint. Omits `timestampMs` since timing is not needed for cropped submissions.
+
+```typescript
+interface CropData {
+  index: number; // Frame sequence number (0-based)
+  pixels: string; // Base64-encoded 224x224 PNG image
+}
+```
+
 ---
 
 ### Utilities
@@ -424,10 +466,28 @@ const inOval = isFaceInOval(faceBbox, ovalRegion);
 console.log(inOval.isInOval); // true/false
 console.log(inOval.alignmentScore); // 0-1
 
-// Calculate crop region for face
+// Calculate crop region for face (224x224, aligned with cognito-check constants)
 const cropRegion = calculateFaceCropRegion(faceBbox, frameWidth, frameHeight);
+// { x, y, size } — square crop region in pixel coordinates
+
+// 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)
 ```
 
+#### Crop Constants (aligned with cognito-check)
+
+These constants control how face crops are generated for the `fast-check-crops` endpoint:
+
+| Constant                         | Value | Description                                      |
+| -------------------------------- | ----- | ------------------------------------------------ |
+| `IDEAL_CROP_MULTIPLIER`          | 2.0   | Default crop region = 2x face size               |
+| `MIN_CROP_MULTIPLIER`            | 1.8   | Minimum crop (face very close)                   |
+| `MAX_CROP_MULTIPLIER`            | 2.5   | Maximum crop (face very far)                     |
+| `FACE_CENTER_VERTICAL_OFFSET`    | 0.05  | Slight upward shift to include forehead for rPPG |
+| `TARGET_FACE_PERCENTAGE_IN_CROP` | 0.5   | Face should occupy ~50% of 224x224 crop          |
+
 ---
 
 ## Configuration Constants
@@ -456,7 +516,14 @@ import type {
   FrameSource,
   Verdict,
   CapturedFrame,
+  CropData,
   LivenessClientConfig,
+  DetectionResult,
+  DetectionSummary,
+  FaceBoundingBox,
+  HeadPose,
+  FaceLandmarkPoint,
+  LandmarkValidationResult,
 } from '@moveris/shared';
 ```
 

package/dist/index.d.mts

@@ -204,6 +204,204 @@ interface LivenessCallbacks {
     onStateChange?: OnStateChangeCallback;
 }
 
+interface FaceBoundingBox {
+    originX: number;
+    originY: number;
+    width: number;
+    height: number;
+}
+interface BlurAnalysis {
+    variance: number;
+    isBlurry: boolean;
+    threshold: number;
+}
+interface LightingAnalysis {
+    faceBrightness: number;
+    backgroundBrightness: number;
+    ratio: number;
+    status: 'good' | 'backlit' | 'low_light';
+    warning?: string;
+}
+interface FaceVisibilityResult {
+    visible: boolean;
+    reason?: string;
+}
+interface FaceAlignmentResult {
+    score: number;
+    tooClose: boolean;
+    tooFar: boolean;
+}
+interface OvalRegion {
+    centerX: number;
+    centerY: number;
+    width: number;
+    height: number;
+}
+interface FaceInOvalResult {
+    isInside: boolean;
+    centerInOval: boolean;
+    sizeMatch: boolean;
+    feedback?: string;
+}
+interface FrameQualityResult {
+    passed: boolean;
+    blur?: BlurAnalysis;
+    lighting?: LightingAnalysis;
+    visibility?: FaceVisibilityResult;
+    alignment?: FaceAlignmentResult;
+    rejectionReason?: 'blur' | 'backlit' | 'low_light' | 'partial_face' | 'no_face' | 'too_close' | 'too_far' | 'misaligned';
+}
+declare const DEFAULT_BLUR_THRESHOLD = 100;
+declare const BLUR_THRESHOLD_MOBILE = 150;
+declare const BACKLIT_RATIO_THRESHOLD = 0.6;
+declare const LOW_LIGHT_THRESHOLD = 50;
+declare const MIN_FACE_TOP_MARGIN = 0.1;
+declare const MIN_FACE_BOTTOM_MARGIN = 0.08;
+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 FACE_CENTER_VERTICAL_OFFSET = 0.05;
+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 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;
+declare function analyzeLighting(faceBrightness: number, backgroundBrightness: number): LightingAnalysis;
+declare function isFaceFullyVisible(boundingBox: FaceBoundingBox, frameWidth: number, frameHeight: number): FaceVisibilityResult;
+declare const DEFAULT_OVAL_REGION: OvalRegion;
+declare function isFaceInOval(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number, oval?: OvalRegion, tolerance?: number): FaceInOvalResult;
+declare function calculateFaceAlignment(boundingBox: FaceBoundingBox, frameWidth: number, frameHeight: number): FaceAlignmentResult;
+declare function calculateAdaptiveCropMultiplier(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): number;
+declare function isFaceCropFullyInFrame(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): boolean;
+declare function calculateFaceCropRegion(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): {
+    x: number;
+    y: number;
+    size: number;
+};
+declare function checkFrameQuality(options: {
+    faceBox?: FaceBoundingBox;
+    frameWidth: number;
+    frameHeight: number;
+    blurAnalysis?: BlurAnalysis;
+    lightingAnalysis?: LightingAnalysis;
+    minAlignment?: number;
+}): FrameQualityResult;
+declare class BaseFrameCollector {
+    protected frames: CapturedFrame[];
+    protected maxFrames: number;
+    protected startTime: number;
+    constructor(maxFrames?: number);
+    setMaxFrames(max: number): void;
+    addFrame(frame: CapturedFrame): void;
+    getFrames(): CapturedFrame[];
+    getCount(): number;
+    isComplete(): boolean;
+    reset(): void;
+    getStartTime(): number;
+    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 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;
+    confidence: number;
+    message?: string;
+    metadata?: Record<string, unknown>;
+}
+interface DetectorConfig {
+    enabled: boolean;
+    minConfidence?: number;
+}
+interface DetectionSummary {
+    allPassed: boolean;
+    results: Map<string, DetectionResult>;
+    faceBox?: FaceBoundingBox;
+    faceLandmarks?: FaceLandmarkPoint[];
+    warnings: string[];
+}
+interface HeadPose {
+    yawDeg: number;
+    pitchDeg: number;
+    rollDeg: number;
+}
+interface GazeThresholds {
+    maxYaw: number;
+    maxPitch: number;
+}
+declare const DEFAULT_GAZE_THRESHOLDS: GazeThresholds;
+interface HandOcclusionConfig {
+    faceExpansionFactor: number;
+    minLandmarksForOcclusion: number;
+    faceBoxExpiryMs: number;
+    centerRegion: number;
+}
+declare const DEFAULT_HAND_OCCLUSION_CONFIG: HandOcclusionConfig;
+interface FaceDetectionTiers {
+    primaryConfidence: number;
+    secondaryConfidence: number;
+}
+declare const DEFAULT_FACE_DETECTION_TIERS: FaceDetectionTiers;
+interface VideoFrameMetadata {
+    presentationTime: number;
+    expectedDisplayTime: number;
+    width: number;
+    height: number;
+    mediaTime: number;
+    presentedFrames: number;
+    processingDuration?: number;
+}
+interface StabilizationProgress {
+    elapsed: number;
+    stableFrameCount: number;
+    requiredFrames: number;
+    greenMean: number;
+    greenDelta: number | null;
+    threshold: number;
+    isStable: boolean;
+    progress: number;
+}
+interface StabilizationResult {
+    success: boolean;
+    elapsed: number;
+    finalGreenMean: number;
+    stableFrameCount: number;
+    message: string;
+}
+interface StabilizerConfig {
+    stabilityThreshold: number;
+    requiredStableFrames: number;
+    maxWaitMs: number;
+    checkIntervalMs: number;
+    sampleSize: number;
+}
+declare const DEFAULT_STABILIZER_CONFIG: StabilizerConfig;
+
 interface LivenessClientConfig {
     baseUrl?: string;
     apiKey: string;
@@ -244,7 +442,12 @@ declare class LivenessClient {
         model?: FastCheckModel;
         source?: FrameSource;
     }): Promise<LivenessResult>;
-    private sendStreamFrame;
+    streamFrame(frame: CapturedFrame, options: {
+        sessionId: string;
+        model?: FastCheckModel;
+        source?: FrameSource;
+    }): Promise<FastCheckStreamResponse>;
+    private sendStreamFrameInternal;
     fastCheckStream(frames: CapturedFrame[], options?: {
         sessionId?: string;
         model?: FastCheckModel;
@@ -480,108 +683,4 @@ interface RetryOptions {
 declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 declare function sleep(ms: number): Promise<void>;
 
-interface FaceBoundingBox {
-    originX: number;
-    originY: number;
-    width: number;
-    height: number;
-}
-interface BlurAnalysis {
-    variance: number;
-    isBlurry: boolean;
-    threshold: number;
-}
-interface LightingAnalysis {
-    faceBrightness: number;
-    backgroundBrightness: number;
-    ratio: number;
-    status: 'good' | 'backlit' | 'low_light';
-    warning?: string;
-}
-interface FaceVisibilityResult {
-    visible: boolean;
-    reason?: string;
-}
-interface FaceAlignmentResult {
-    score: number;
-    tooClose: boolean;
-    tooFar: boolean;
-}
-interface OvalRegion {
-    centerX: number;
-    centerY: number;
-    width: number;
-    height: number;
-}
-interface FaceInOvalResult {
-    isInside: boolean;
-    centerInOval: boolean;
-    sizeMatch: boolean;
-    feedback?: string;
-}
-interface FrameQualityResult {
-    passed: boolean;
-    blur?: BlurAnalysis;
-    lighting?: LightingAnalysis;
-    visibility?: FaceVisibilityResult;
-    alignment?: FaceAlignmentResult;
-    rejectionReason?: 'blur' | 'backlit' | 'low_light' | 'partial_face' | 'no_face' | 'too_close' | 'too_far' | 'misaligned';
-}
-declare const DEFAULT_BLUR_THRESHOLD = 100;
-declare const BLUR_THRESHOLD_MOBILE = 150;
-declare const BACKLIT_RATIO_THRESHOLD = 0.6;
-declare const LOW_LIGHT_THRESHOLD = 50;
-declare const MIN_FACE_TOP_MARGIN = 0.1;
-declare const MIN_FACE_BOTTOM_MARGIN = 0.08;
-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 = 3.33;
-declare const MIN_CROP_MULTIPLIER = 1.5;
-declare const MAX_CROP_MULTIPLIER = 4;
-declare const FACE_CENTER_VERTICAL_OFFSET = 0.15;
-declare const MIN_FACE_RATIO = 0.03;
-declare const MAX_FACE_RATIO = 0.7;
-declare const FACE_CROP_OUTPUT_SIZE = 224;
-declare const MAX_FACE_PERCENTAGE_IN_CROP = 0.5;
-declare const TARGET_FACE_PERCENTAGE_IN_CROP = 0.3;
-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;
-declare function analyzeLighting(faceBrightness: number, backgroundBrightness: number): LightingAnalysis;
-declare function isFaceFullyVisible(boundingBox: FaceBoundingBox, frameWidth: number, frameHeight: number): FaceVisibilityResult;
-declare const DEFAULT_OVAL_REGION: OvalRegion;
-declare function isFaceInOval(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number, oval?: OvalRegion, tolerance?: number): FaceInOvalResult;
-declare function calculateFaceAlignment(boundingBox: FaceBoundingBox, frameWidth: number, frameHeight: number): FaceAlignmentResult;
-declare function calculateAdaptiveCropMultiplier(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): number;
-declare function isFaceCropFullyInFrame(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): boolean;
-declare function calculateFaceCropRegion(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): {
-    x: number;
-    y: number;
-    size: number;
-};
-declare function checkFrameQuality(options: {
-    faceBox?: FaceBoundingBox;
-    frameWidth: number;
-    frameHeight: number;
-    blurAnalysis?: BlurAnalysis;
-    lightingAnalysis?: LightingAnalysis;
-    minAlignment?: number;
-}): FrameQualityResult;
-declare class BaseFrameCollector {
-    protected frames: CapturedFrame[];
-    protected maxFrames: number;
-    protected startTime: number;
-    constructor(maxFrames?: number);
-    setMaxFrames(max: number): void;
-    addFrame(frame: CapturedFrame): void;
-    getFrames(): CapturedFrame[];
-    getCount(): number;
-    isComplete(): boolean;
-    reset(): void;
-    getStartTime(): number;
-    getNextIndex(): number;
-}
-
-export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_PATHS, AUTH_CONFIG, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STATUS_MESSAGES, ES_LOCALE, type ErrorResponse, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceInOvalResult, 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, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LOW_LIGHT_THRESHOLD, 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, MODEL_CONFIGS, type ModelConfig, type ModelType, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, analyzeBlur, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkFrameQuality, decodeBase64, encodeBase64, generateSessionId, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_PATHS, AUTH_CONFIG, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ES_LOCALE, type ErrorResponse, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelType, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkFrameQuality, decodeBase64, encodeBase64, generateSessionId, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.d.ts

@@ -204,6 +204,204 @@ interface LivenessCallbacks {
     onStateChange?: OnStateChangeCallback;
 }
 
+interface FaceBoundingBox {
+    originX: number;
+    originY: number;
+    width: number;
+    height: number;
+}
+interface BlurAnalysis {
+    variance: number;
+    isBlurry: boolean;
+    threshold: number;
+}
+interface LightingAnalysis {
+    faceBrightness: number;
+    backgroundBrightness: number;
+    ratio: number;
+    status: 'good' | 'backlit' | 'low_light';
+    warning?: string;
+}
+interface FaceVisibilityResult {
+    visible: boolean;
+    reason?: string;
+}
+interface FaceAlignmentResult {
+    score: number;
+    tooClose: boolean;
+    tooFar: boolean;
+}
+interface OvalRegion {
+    centerX: number;
+    centerY: number;
+    width: number;
+    height: number;
+}
+interface FaceInOvalResult {
+    isInside: boolean;
+    centerInOval: boolean;
+    sizeMatch: boolean;
+    feedback?: string;
+}
+interface FrameQualityResult {
+    passed: boolean;
+    blur?: BlurAnalysis;
+    lighting?: LightingAnalysis;
+    visibility?: FaceVisibilityResult;
+    alignment?: FaceAlignmentResult;
+    rejectionReason?: 'blur' | 'backlit' | 'low_light' | 'partial_face' | 'no_face' | 'too_close' | 'too_far' | 'misaligned';
+}
+declare const DEFAULT_BLUR_THRESHOLD = 100;
+declare const BLUR_THRESHOLD_MOBILE = 150;
+declare const BACKLIT_RATIO_THRESHOLD = 0.6;
+declare const LOW_LIGHT_THRESHOLD = 50;
+declare const MIN_FACE_TOP_MARGIN = 0.1;
+declare const MIN_FACE_BOTTOM_MARGIN = 0.08;
+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 FACE_CENTER_VERTICAL_OFFSET = 0.05;
+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 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;
+declare function analyzeLighting(faceBrightness: number, backgroundBrightness: number): LightingAnalysis;
+declare function isFaceFullyVisible(boundingBox: FaceBoundingBox, frameWidth: number, frameHeight: number): FaceVisibilityResult;
+declare const DEFAULT_OVAL_REGION: OvalRegion;
+declare function isFaceInOval(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number, oval?: OvalRegion, tolerance?: number): FaceInOvalResult;
+declare function calculateFaceAlignment(boundingBox: FaceBoundingBox, frameWidth: number, frameHeight: number): FaceAlignmentResult;
+declare function calculateAdaptiveCropMultiplier(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): number;
+declare function isFaceCropFullyInFrame(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): boolean;
+declare function calculateFaceCropRegion(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): {
+    x: number;
+    y: number;
+    size: number;
+};
+declare function checkFrameQuality(options: {
+    faceBox?: FaceBoundingBox;
+    frameWidth: number;
+    frameHeight: number;
+    blurAnalysis?: BlurAnalysis;
+    lightingAnalysis?: LightingAnalysis;
+    minAlignment?: number;
+}): FrameQualityResult;
+declare class BaseFrameCollector {
+    protected frames: CapturedFrame[];
+    protected maxFrames: number;
+    protected startTime: number;
+    constructor(maxFrames?: number);
+    setMaxFrames(max: number): void;
+    addFrame(frame: CapturedFrame): void;
+    getFrames(): CapturedFrame[];
+    getCount(): number;
+    isComplete(): boolean;
+    reset(): void;
+    getStartTime(): number;
+    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 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;
+    confidence: number;
+    message?: string;
+    metadata?: Record<string, unknown>;
+}
+interface DetectorConfig {
+    enabled: boolean;
+    minConfidence?: number;
+}
+interface DetectionSummary {
+    allPassed: boolean;
+    results: Map<string, DetectionResult>;
+    faceBox?: FaceBoundingBox;
+    faceLandmarks?: FaceLandmarkPoint[];
+    warnings: string[];
+}
+interface HeadPose {
+    yawDeg: number;
+    pitchDeg: number;
+    rollDeg: number;
+}
+interface GazeThresholds {
+    maxYaw: number;
+    maxPitch: number;
+}
+declare const DEFAULT_GAZE_THRESHOLDS: GazeThresholds;
+interface HandOcclusionConfig {
+    faceExpansionFactor: number;
+    minLandmarksForOcclusion: number;
+    faceBoxExpiryMs: number;
+    centerRegion: number;
+}
+declare const DEFAULT_HAND_OCCLUSION_CONFIG: HandOcclusionConfig;
+interface FaceDetectionTiers {
+    primaryConfidence: number;
+    secondaryConfidence: number;
+}
+declare const DEFAULT_FACE_DETECTION_TIERS: FaceDetectionTiers;
+interface VideoFrameMetadata {
+    presentationTime: number;
+    expectedDisplayTime: number;
+    width: number;
+    height: number;
+    mediaTime: number;
+    presentedFrames: number;
+    processingDuration?: number;
+}
+interface StabilizationProgress {
+    elapsed: number;
+    stableFrameCount: number;
+    requiredFrames: number;
+    greenMean: number;
+    greenDelta: number | null;
+    threshold: number;
+    isStable: boolean;
+    progress: number;
+}
+interface StabilizationResult {
+    success: boolean;
+    elapsed: number;
+    finalGreenMean: number;
+    stableFrameCount: number;
+    message: string;
+}
+interface StabilizerConfig {
+    stabilityThreshold: number;
+    requiredStableFrames: number;
+    maxWaitMs: number;
+    checkIntervalMs: number;
+    sampleSize: number;
+}
+declare const DEFAULT_STABILIZER_CONFIG: StabilizerConfig;
+
 interface LivenessClientConfig {
     baseUrl?: string;
     apiKey: string;
@@ -244,7 +442,12 @@ declare class LivenessClient {
         model?: FastCheckModel;
         source?: FrameSource;
     }): Promise<LivenessResult>;
-    private sendStreamFrame;
+    streamFrame(frame: CapturedFrame, options: {
+        sessionId: string;
+        model?: FastCheckModel;
+        source?: FrameSource;
+    }): Promise<FastCheckStreamResponse>;
+    private sendStreamFrameInternal;
     fastCheckStream(frames: CapturedFrame[], options?: {
         sessionId?: string;
         model?: FastCheckModel;
@@ -480,108 +683,4 @@ interface RetryOptions {
 declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 declare function sleep(ms: number): Promise<void>;
 
-interface FaceBoundingBox {
-    originX: number;
-    originY: number;
-    width: number;
-    height: number;
-}
-interface BlurAnalysis {
-    variance: number;
-    isBlurry: boolean;
-    threshold: number;
-}
-interface LightingAnalysis {
-    faceBrightness: number;
-    backgroundBrightness: number;
-    ratio: number;
-    status: 'good' | 'backlit' | 'low_light';
-    warning?: string;
-}
-interface FaceVisibilityResult {
-    visible: boolean;
-    reason?: string;
-}
-interface FaceAlignmentResult {
-    score: number;
-    tooClose: boolean;
-    tooFar: boolean;
-}
-interface OvalRegion {
-    centerX: number;
-    centerY: number;
-    width: number;
-    height: number;
-}
-interface FaceInOvalResult {
-    isInside: boolean;
-    centerInOval: boolean;
-    sizeMatch: boolean;
-    feedback?: string;
-}
-interface FrameQualityResult {
-    passed: boolean;
-    blur?: BlurAnalysis;
-    lighting?: LightingAnalysis;
-    visibility?: FaceVisibilityResult;
-    alignment?: FaceAlignmentResult;
-    rejectionReason?: 'blur' | 'backlit' | 'low_light' | 'partial_face' | 'no_face' | 'too_close' | 'too_far' | 'misaligned';
-}
-declare const DEFAULT_BLUR_THRESHOLD = 100;
-declare const BLUR_THRESHOLD_MOBILE = 150;
-declare const BACKLIT_RATIO_THRESHOLD = 0.6;
-declare const LOW_LIGHT_THRESHOLD = 50;
-declare const MIN_FACE_TOP_MARGIN = 0.1;
-declare const MIN_FACE_BOTTOM_MARGIN = 0.08;
-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 = 3.33;
-declare const MIN_CROP_MULTIPLIER = 1.5;
-declare const MAX_CROP_MULTIPLIER = 4;
-declare const FACE_CENTER_VERTICAL_OFFSET = 0.15;
-declare const MIN_FACE_RATIO = 0.03;
-declare const MAX_FACE_RATIO = 0.7;
-declare const FACE_CROP_OUTPUT_SIZE = 224;
-declare const MAX_FACE_PERCENTAGE_IN_CROP = 0.5;
-declare const TARGET_FACE_PERCENTAGE_IN_CROP = 0.3;
-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;
-declare function analyzeLighting(faceBrightness: number, backgroundBrightness: number): LightingAnalysis;
-declare function isFaceFullyVisible(boundingBox: FaceBoundingBox, frameWidth: number, frameHeight: number): FaceVisibilityResult;
-declare const DEFAULT_OVAL_REGION: OvalRegion;
-declare function isFaceInOval(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number, oval?: OvalRegion, tolerance?: number): FaceInOvalResult;
-declare function calculateFaceAlignment(boundingBox: FaceBoundingBox, frameWidth: number, frameHeight: number): FaceAlignmentResult;
-declare function calculateAdaptiveCropMultiplier(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): number;
-declare function isFaceCropFullyInFrame(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): boolean;
-declare function calculateFaceCropRegion(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): {
-    x: number;
-    y: number;
-    size: number;
-};
-declare function checkFrameQuality(options: {
-    faceBox?: FaceBoundingBox;
-    frameWidth: number;
-    frameHeight: number;
-    blurAnalysis?: BlurAnalysis;
-    lightingAnalysis?: LightingAnalysis;
-    minAlignment?: number;
-}): FrameQualityResult;
-declare class BaseFrameCollector {
-    protected frames: CapturedFrame[];
-    protected maxFrames: number;
-    protected startTime: number;
-    constructor(maxFrames?: number);
-    setMaxFrames(max: number): void;
-    addFrame(frame: CapturedFrame): void;
-    getFrames(): CapturedFrame[];
-    getCount(): number;
-    isComplete(): boolean;
-    reset(): void;
-    getStartTime(): number;
-    getNextIndex(): number;
-}
-
-export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_PATHS, AUTH_CONFIG, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STATUS_MESSAGES, ES_LOCALE, type ErrorResponse, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceInOvalResult, 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, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LOW_LIGHT_THRESHOLD, 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, MODEL_CONFIGS, type ModelConfig, type ModelType, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, analyzeBlur, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkFrameQuality, decodeBase64, encodeBase64, generateSessionId, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_PATHS, AUTH_CONFIG, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ES_LOCALE, type ErrorResponse, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelType, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkFrameQuality, decodeBase64, encodeBase64, generateSessionId, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.js

@@ -32,9 +32,13 @@ __export(index_exports, {
   BaseFrameCollector: () => BaseFrameCollector,
   DEFAULT_BLUR_THRESHOLD: () => DEFAULT_BLUR_THRESHOLD,
   DEFAULT_ENDPOINT: () => DEFAULT_ENDPOINT,
+  DEFAULT_FACE_DETECTION_TIERS: () => DEFAULT_FACE_DETECTION_TIERS,
+  DEFAULT_GAZE_THRESHOLDS: () => DEFAULT_GAZE_THRESHOLDS,
+  DEFAULT_HAND_OCCLUSION_CONFIG: () => DEFAULT_HAND_OCCLUSION_CONFIG,
   DEFAULT_LIVENESS_CONFIG: () => DEFAULT_LIVENESS_CONFIG,
   DEFAULT_LOCALE: () => DEFAULT_LOCALE,
   DEFAULT_OVAL_REGION: () => DEFAULT_OVAL_REGION,
+  DEFAULT_STABILIZER_CONFIG: () => DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES: () => DEFAULT_STATUS_MESSAGES,
   ES_LOCALE: () => ES_LOCALE,
   FACE_CENTER_VERTICAL_OFFSET: () => FACE_CENTER_VERTICAL_OFFSET,
@@ -48,6 +52,9 @@ __export(index_exports, {
   HIGH_ALIGNMENT: () => HIGH_ALIGNMENT,
   HYBRID_MODEL_CONFIGS: () => HYBRID_MODEL_CONFIGS,
   IDEAL_CROP_MULTIPLIER: () => IDEAL_CROP_MULTIPLIER,
+  LANDMARK_INDEX: () => LANDMARK_INDEX,
+  LANDMARK_MAX_BOUND: () => LANDMARK_MAX_BOUND,
+  LANDMARK_MIN_BOUND: () => LANDMARK_MIN_BOUND,
   LOW_LIGHT_THRESHOLD: () => LOW_LIGHT_THRESHOLD,
   LivenessApiError: () => LivenessApiError,
   LivenessClient: () => LivenessClient,
@@ -60,6 +67,7 @@ __export(index_exports, {
   MIN_FACE_RATIO: () => MIN_FACE_RATIO,
   MIN_FACE_SIDE_MARGIN: () => MIN_FACE_SIDE_MARGIN,
   MIN_FACE_TOP_MARGIN: () => MIN_FACE_TOP_MARGIN,
+  MIN_LANDMARK_COUNT: () => MIN_LANDMARK_COUNT,
   MODEL_CONFIGS: () => MODEL_CONFIGS,
   OVAL_GUIDE_COLORS: () => OVAL_GUIDE_COLORS,
   OVAL_GUIDE_STYLES: () => OVAL_GUIDE_STYLES,
@@ -93,6 +101,7 @@ __export(index_exports, {
   toLivenessResult: () => toLivenessResult,
   toLivenessResultFromStream: () => toLivenessResultFromStream,
   validateApiKey: () => validateApiKey,
+  validateFaceLandmarks: () => validateFaceLandmarks,
   validateFrameCount: () => validateFrameCount,
   validateFrameData: () => validateFrameData,
   validateFrameIndex: () => validateFrameIndex,
@@ -385,18 +394,47 @@ var LivenessClient = class {
     return toLivenessResult(response);
   }
   /**
-   * Send a single frame to the streaming endpoint with retry
+   * Send a single captured frame to the streaming endpoint.
+   *
+   * Use this to implement **real-time** streaming: call once per captured
+   * frame instead of batching all frames first.
+   *
+   * - While the server is still collecting frames the response will have
+   *   `status: 'buffering'` with `frames_received` / `frames_required`.
+   * - When the last required frame arrives the response will have
+   *   `status: 'complete'` with the full liveness result.
+   *
+   * Each frame gets its own retry via {@link retryWithBackoff}.
+   *
+   * @param frame  - A single captured frame
+   * @param options - Session, model and source
+   * @returns Stream response (buffering or complete)
+   */
+  async streamFrame(frame, options) {
+    const frameData = {
+      index: frame.index,
+      timestamp_ms: frame.timestampMs,
+      pixels: frame.pixels
+    };
+    return this.sendStreamFrameInternal(frameData, {
+      sessionId: options.sessionId,
+      model: options.model ?? "10",
+      source: options.source ?? "live"
+    });
+  }
+  /**
+   * Send a single FrameData to the streaming endpoint with retry (internal)
    *
    * @param frame - Single frame to send
    * @param options - Session and model options
    * @returns Stream response with status
    */
-  async sendStreamFrame(frame, options) {
+  async sendStreamFrameInternal(frameData, options) {
     const request = {
       session_id: options.sessionId,
       model: options.model,
       source: options.source,
-      frame
+      frame: frameData
     };
     return this.requestWithRetry(API_PATHS.fastCheckStream, {
       method: "POST",
@@ -422,7 +460,7 @@ var LivenessClient = class {
     const total = frameDataList.length;
     let finalResponse = null;
     const sendPromises = frameDataList.map(async (frameData, index) => {
-      const response = await this.sendStreamFrame(frameData, {
+      const response = await this.sendStreamFrameInternal(frameData, {
         sessionId,
         model,
         source
@@ -471,7 +509,7 @@ var LivenessClient = class {
     const total = frameDataList.length;
     let finalResponse = null;
     for (const frameData of frameDataList) {
-      const response = await this.sendStreamFrame(frameData, {
+      const response = await this.sendStreamFrameInternal(frameData, {
         sessionId,
         model,
         source
@@ -891,6 +929,29 @@ function hasEnoughFrames(model, frameCount) {
   return frameCount >= MODEL_CONFIGS[model].minFrames;
 }
 
+// src/types/detectors.ts
+var DEFAULT_GAZE_THRESHOLDS = {
+  maxYaw: 25,
+  maxPitch: 20
+};
+var DEFAULT_HAND_OCCLUSION_CONFIG = {
+  faceExpansionFactor: 0.5,
+  minLandmarksForOcclusion: 3,
+  faceBoxExpiryMs: 1e3,
+  centerRegion: 0.6
+};
+var DEFAULT_FACE_DETECTION_TIERS = {
+  primaryConfidence: 0.7,
+  secondaryConfidence: 0.4
+};
+var DEFAULT_STABILIZER_CONFIG = {
+  stabilityThreshold: 1.5,
+  requiredStableFrames: 15,
+  maxWaitMs: 4e3,
+  checkIntervalMs: 100,
+  sampleSize: 64
+};
+
 // src/constants/feedback.ts
 var ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
 var ALIGNMENT_THRESHOLD_POOR = 0.5;
@@ -1142,15 +1203,15 @@ 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 = 3.33;
-var MIN_CROP_MULTIPLIER = 1.5;
-var MAX_CROP_MULTIPLIER = 4;
-var FACE_CENTER_VERTICAL_OFFSET = 0.15;
-var MIN_FACE_RATIO = 0.03;
+var IDEAL_CROP_MULTIPLIER = 2;
+var MIN_CROP_MULTIPLIER = 1.8;
+var MAX_CROP_MULTIPLIER = 2.5;
+var FACE_CENTER_VERTICAL_OFFSET = 0.05;
+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.5;
-var TARGET_FACE_PERCENTAGE_IN_CROP = 0.3;
+var MAX_FACE_PERCENTAGE_IN_CROP = 0.6;
+var TARGET_FACE_PERCENTAGE_IN_CROP = 0.5;
 function analyzeBlur(grayscalePixels, width, height, threshold = DEFAULT_BLUR_THRESHOLD) {
   const laplacian = [];
   for (let y = 1; y < height - 1; y++) {
@@ -1239,10 +1300,10 @@ function isFaceFullyVisible(boundingBox, frameWidth, frameHeight) {
 var DEFAULT_OVAL_REGION = {
   centerX: 0.5,
   centerY: 0.5,
-  width: 0.3,
-  // 30% of frame width
-  height: 0.4
-  // 30% * (4/3) = 40% of frame height (3:4 aspect ratio)
+  width: 0.36,
+  // 36% of frame width  (+20%)
+  height: 0.48
+  // 36% * (4/3) = 48% of frame height (+20%)
 };
 function isFaceInOval(faceBox, frameWidth, frameHeight, oval = DEFAULT_OVAL_REGION, tolerance = 0.3) {
   const faceCenterX = (faceBox.originX + faceBox.width / 2) / frameWidth;
@@ -1431,6 +1492,37 @@ var BaseFrameCollector = class {
     return this.frames.length;
   }
 };
+
+// src/utils/landmarkValidator.ts
+var LANDMARK_INDEX = {
+  /** Nose tip */
+  NOSE_TIP: 1,
+  /** Upper lip center */
+  UPPER_LIP: 13,
+  /** Lower lip center */
+  LOWER_LIP: 14
+};
+var LANDMARK_MIN_BOUND = 0.1;
+var LANDMARK_MAX_BOUND = 0.9;
+var MIN_LANDMARK_COUNT = 15;
+function isInBounds(x, y) {
+  return x >= LANDMARK_MIN_BOUND && x <= LANDMARK_MAX_BOUND && y >= LANDMARK_MIN_BOUND && y <= LANDMARK_MAX_BOUND;
+}
+function validateFaceLandmarks(landmarks) {
+  if (!landmarks || landmarks.length < MIN_LANDMARK_COUNT) {
+    return { valid: false, message: "Move closer to the camera" };
+  }
+  const noseTip = landmarks[LANDMARK_INDEX.NOSE_TIP];
+  const upperLip = landmarks[LANDMARK_INDEX.UPPER_LIP];
+  const lowerLip = landmarks[LANDMARK_INDEX.LOWER_LIP];
+  if (!noseTip || !isInBounds(noseTip.x, noseTip.y)) {
+    return { valid: false, message: "Make sure your full face is visible" };
+  }
+  if (!upperLip || !lowerLip || !isInBounds(upperLip.x, upperLip.y) || !isInBounds(lowerLip.x, lowerLip.y)) {
+    return { valid: false, message: "Don't cover your mouth" };
+  }
+  return { valid: true };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALIGNMENT_THRESHOLD_CAPTURE,
@@ -1445,9 +1537,13 @@ var BaseFrameCollector = class {
   BaseFrameCollector,
   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,
   ES_LOCALE,
   FACE_CENTER_VERTICAL_OFFSET,
@@ -1461,6 +1557,9 @@ var BaseFrameCollector = class {
   HIGH_ALIGNMENT,
   HYBRID_MODEL_CONFIGS,
   IDEAL_CROP_MULTIPLIER,
+  LANDMARK_INDEX,
+  LANDMARK_MAX_BOUND,
+  LANDMARK_MIN_BOUND,
   LOW_LIGHT_THRESHOLD,
   LivenessApiError,
   LivenessClient,
@@ -1473,6 +1572,7 @@ var BaseFrameCollector = class {
   MIN_FACE_RATIO,
   MIN_FACE_SIDE_MARGIN,
   MIN_FACE_TOP_MARGIN,
+  MIN_LANDMARK_COUNT,
   MODEL_CONFIGS,
   OVAL_GUIDE_COLORS,
   OVAL_GUIDE_STYLES,
@@ -1506,6 +1606,7 @@ var BaseFrameCollector = class {
   toLivenessResult,
   toLivenessResultFromStream,
   validateApiKey,
+  validateFaceLandmarks,
   validateFrameCount,
   validateFrameData,
   validateFrameIndex,

package/dist/index.mjs

@@ -281,18 +281,47 @@ var LivenessClient = class {
     return toLivenessResult(response);
   }
   /**
-   * Send a single frame to the streaming endpoint with retry
+   * Send a single captured frame to the streaming endpoint.
+   *
+   * Use this to implement **real-time** streaming: call once per captured
+   * frame instead of batching all frames first.
+   *
+   * - While the server is still collecting frames the response will have
+   *   `status: 'buffering'` with `frames_received` / `frames_required`.
+   * - When the last required frame arrives the response will have
+   *   `status: 'complete'` with the full liveness result.
+   *
+   * Each frame gets its own retry via {@link retryWithBackoff}.
+   *
+   * @param frame  - A single captured frame
+   * @param options - Session, model and source
+   * @returns Stream response (buffering or complete)
+   */
+  async streamFrame(frame, options) {
+    const frameData = {
+      index: frame.index,
+      timestamp_ms: frame.timestampMs,
+      pixels: frame.pixels
+    };
+    return this.sendStreamFrameInternal(frameData, {
+      sessionId: options.sessionId,
+      model: options.model ?? "10",
+      source: options.source ?? "live"
+    });
+  }
+  /**
+   * Send a single FrameData to the streaming endpoint with retry (internal)
    *
    * @param frame - Single frame to send
    * @param options - Session and model options
    * @returns Stream response with status
    */
-  async sendStreamFrame(frame, options) {
+  async sendStreamFrameInternal(frameData, options) {
     const request = {
       session_id: options.sessionId,
       model: options.model,
       source: options.source,
-      frame
+      frame: frameData
     };
     return this.requestWithRetry(API_PATHS.fastCheckStream, {
       method: "POST",
@@ -318,7 +347,7 @@ var LivenessClient = class {
     const total = frameDataList.length;
     let finalResponse = null;
     const sendPromises = frameDataList.map(async (frameData, index) => {
-      const response = await this.sendStreamFrame(frameData, {
+      const response = await this.sendStreamFrameInternal(frameData, {
         sessionId,
         model,
         source
@@ -367,7 +396,7 @@ var LivenessClient = class {
     const total = frameDataList.length;
     let finalResponse = null;
     for (const frameData of frameDataList) {
-      const response = await this.sendStreamFrame(frameData, {
+      const response = await this.sendStreamFrameInternal(frameData, {
         sessionId,
         model,
         source
@@ -787,6 +816,29 @@ function hasEnoughFrames(model, frameCount) {
   return frameCount >= MODEL_CONFIGS[model].minFrames;
 }
 
+// src/types/detectors.ts
+var DEFAULT_GAZE_THRESHOLDS = {
+  maxYaw: 25,
+  maxPitch: 20
+};
+var DEFAULT_HAND_OCCLUSION_CONFIG = {
+  faceExpansionFactor: 0.5,
+  minLandmarksForOcclusion: 3,
+  faceBoxExpiryMs: 1e3,
+  centerRegion: 0.6
+};
+var DEFAULT_FACE_DETECTION_TIERS = {
+  primaryConfidence: 0.7,
+  secondaryConfidence: 0.4
+};
+var DEFAULT_STABILIZER_CONFIG = {
+  stabilityThreshold: 1.5,
+  requiredStableFrames: 15,
+  maxWaitMs: 4e3,
+  checkIntervalMs: 100,
+  sampleSize: 64
+};
+
 // src/constants/feedback.ts
 var ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
 var ALIGNMENT_THRESHOLD_POOR = 0.5;
@@ -1038,15 +1090,15 @@ 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 = 3.33;
-var MIN_CROP_MULTIPLIER = 1.5;
-var MAX_CROP_MULTIPLIER = 4;
-var FACE_CENTER_VERTICAL_OFFSET = 0.15;
-var MIN_FACE_RATIO = 0.03;
+var IDEAL_CROP_MULTIPLIER = 2;
+var MIN_CROP_MULTIPLIER = 1.8;
+var MAX_CROP_MULTIPLIER = 2.5;
+var FACE_CENTER_VERTICAL_OFFSET = 0.05;
+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.5;
-var TARGET_FACE_PERCENTAGE_IN_CROP = 0.3;
+var MAX_FACE_PERCENTAGE_IN_CROP = 0.6;
+var TARGET_FACE_PERCENTAGE_IN_CROP = 0.5;
 function analyzeBlur(grayscalePixels, width, height, threshold = DEFAULT_BLUR_THRESHOLD) {
   const laplacian = [];
   for (let y = 1; y < height - 1; y++) {
@@ -1135,10 +1187,10 @@ function isFaceFullyVisible(boundingBox, frameWidth, frameHeight) {
 var DEFAULT_OVAL_REGION = {
   centerX: 0.5,
   centerY: 0.5,
-  width: 0.3,
-  // 30% of frame width
-  height: 0.4
-  // 30% * (4/3) = 40% of frame height (3:4 aspect ratio)
+  width: 0.36,
+  // 36% of frame width  (+20%)
+  height: 0.48
+  // 36% * (4/3) = 48% of frame height (+20%)
 };
 function isFaceInOval(faceBox, frameWidth, frameHeight, oval = DEFAULT_OVAL_REGION, tolerance = 0.3) {
   const faceCenterX = (faceBox.originX + faceBox.width / 2) / frameWidth;
@@ -1327,6 +1379,37 @@ var BaseFrameCollector = class {
     return this.frames.length;
   }
 };
+
+// src/utils/landmarkValidator.ts
+var LANDMARK_INDEX = {
+  /** Nose tip */
+  NOSE_TIP: 1,
+  /** Upper lip center */
+  UPPER_LIP: 13,
+  /** Lower lip center */
+  LOWER_LIP: 14
+};
+var LANDMARK_MIN_BOUND = 0.1;
+var LANDMARK_MAX_BOUND = 0.9;
+var MIN_LANDMARK_COUNT = 15;
+function isInBounds(x, y) {
+  return x >= LANDMARK_MIN_BOUND && x <= LANDMARK_MAX_BOUND && y >= LANDMARK_MIN_BOUND && y <= LANDMARK_MAX_BOUND;
+}
+function validateFaceLandmarks(landmarks) {
+  if (!landmarks || landmarks.length < MIN_LANDMARK_COUNT) {
+    return { valid: false, message: "Move closer to the camera" };
+  }
+  const noseTip = landmarks[LANDMARK_INDEX.NOSE_TIP];
+  const upperLip = landmarks[LANDMARK_INDEX.UPPER_LIP];
+  const lowerLip = landmarks[LANDMARK_INDEX.LOWER_LIP];
+  if (!noseTip || !isInBounds(noseTip.x, noseTip.y)) {
+    return { valid: false, message: "Make sure your full face is visible" };
+  }
+  if (!upperLip || !lowerLip || !isInBounds(upperLip.x, upperLip.y) || !isInBounds(lowerLip.x, lowerLip.y)) {
+    return { valid: false, message: "Don't cover your mouth" };
+  }
+  return { valid: true };
+}
 export {
   ALIGNMENT_THRESHOLD_CAPTURE,
   ALIGNMENT_THRESHOLD_GOOD,
@@ -1340,9 +1423,13 @@ export {
   BaseFrameCollector,
   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,
   ES_LOCALE,
   FACE_CENTER_VERTICAL_OFFSET,
@@ -1356,6 +1443,9 @@ export {
   HIGH_ALIGNMENT,
   HYBRID_MODEL_CONFIGS,
   IDEAL_CROP_MULTIPLIER,
+  LANDMARK_INDEX,
+  LANDMARK_MAX_BOUND,
+  LANDMARK_MIN_BOUND,
   LOW_LIGHT_THRESHOLD,
   LivenessApiError,
   LivenessClient,
@@ -1368,6 +1458,7 @@ export {
   MIN_FACE_RATIO,
   MIN_FACE_SIDE_MARGIN,
   MIN_FACE_TOP_MARGIN,
+  MIN_LANDMARK_COUNT,
   MODEL_CONFIGS,
   OVAL_GUIDE_COLORS,
   OVAL_GUIDE_STYLES,
@@ -1401,6 +1492,7 @@ export {
   toLivenessResult,
   toLivenessResultFromStream,
   validateApiKey,
+  validateFaceLandmarks,
   validateFrameCount,
   validateFrameData,
   validateFrameIndex,

package/package.json

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