@moveris/shared 1.0.2 → 2.1.0

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,
@@ -91,7 +99,9 @@ __export(index_exports, {
   toFrameData: () => toFrameData,
   toHybridFrameData: () => toHybridFrameData,
   toLivenessResult: () => toLivenessResult,
+  toLivenessResultFromStream: () => toLivenessResultFromStream,
   validateApiKey: () => validateApiKey,
+  validateFaceLandmarks: () => validateFaceLandmarks,
   validateFrameCount: () => validateFrameCount,
   validateFrameData: () => validateFrameData,
   validateFrameIndex: () => validateFrameIndex,
@@ -112,6 +122,7 @@ var API_PATHS = {
   health: "/health",
   fastCheck: "/api/v1/fast-check",
   fastCheckCrops: "/api/v1/fast-check-crops",
+  fastCheckStream: "/api/v1/fast-check-stream",
   verify: "/api/v1/verify",
   hybridCheck: "/api/v1/hybrid-check",
   hybrid50: "/api/v1/hybrid-50",
@@ -232,6 +243,22 @@ function toLivenessResult(response) {
     framesProcessed: "frames_processed" in response ? response.frames_processed ?? 0 : 0
   };
 }
+function toLivenessResultFromStream(response) {
+  if (response.status !== "complete") {
+    throw new LivenessApiError("Stream not complete", "stream_incomplete", 400);
+  }
+  if (!response.verdict) {
+    throw new LivenessApiError(response.error ?? "No verdict received", "no_verdict", 500);
+  }
+  return {
+    verdict: response.verdict,
+    confidence: response.confidence ?? 0,
+    score: response.score ?? 0,
+    sessionId: response.session_id,
+    processingMs: response.processing_ms ?? 0,
+    framesProcessed: response.frames_processed ?? 0
+  };
+}
 function generateSessionId() {
   if (typeof crypto !== "undefined" && crypto.randomUUID) {
     return crypto.randomUUID();
@@ -366,6 +393,145 @@ var LivenessClient = class {
     });
     return toLivenessResult(response);
   }
+  /**
+   * 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 sendStreamFrameInternal(frameData, options) {
+    const request = {
+      session_id: options.sessionId,
+      model: options.model,
+      source: options.source,
+      frame: frameData
+    };
+    return this.requestWithRetry(API_PATHS.fastCheckStream, {
+      method: "POST",
+      body: JSON.stringify(request)
+    });
+  }
+  /**
+   * Perform streaming liveness check by sending frames one at a time
+   *
+   * Each frame is sent separately to the streaming endpoint with individual retry.
+   * The last frame that completes the set will return the full liveness result.
+   *
+   * @param frames - Captured frames to analyze
+   * @param options - Additional options
+   * @param callbacks - Optional callbacks for progress tracking
+   * @returns Liveness result
+   */
+  async fastCheckStream(frames, options = {}, callbacks) {
+    const sessionId = options.sessionId ?? generateSessionId();
+    const model = options.model ?? "10";
+    const source = options.source ?? "live";
+    const frameDataList = toFrameData(frames);
+    const total = frameDataList.length;
+    let finalResponse = null;
+    const sendPromises = frameDataList.map(async (frameData, index) => {
+      const response = await this.sendStreamFrameInternal(frameData, {
+        sessionId,
+        model,
+        source
+      });
+      callbacks?.onFrameSent?.(index + 1, total);
+      if (response.status === "buffering") {
+        callbacks?.onFrameBuffered?.(response.frames_received, response.frames_required);
+      }
+      return response;
+    });
+    const responses = await Promise.all(sendPromises);
+    finalResponse = responses.find((r) => r.status === "complete") ?? null;
+    if (!finalResponse) {
+      const lastResponse = responses[responses.length - 1];
+      if (lastResponse) {
+        throw new LivenessApiError(
+          `Streaming incomplete: received ${lastResponse.frames_received}/${lastResponse.frames_required} frames`,
+          "stream_incomplete",
+          400
+        );
+      }
+      throw new LivenessApiError(
+        "Streaming failed: no responses received",
+        "stream_incomplete",
+        400
+      );
+    }
+    return toLivenessResultFromStream(finalResponse);
+  }
+  /**
+   * Perform streaming liveness check by sending frames sequentially
+   *
+   * Alternative to fastCheckStream that sends frames one by one in order.
+   * Useful when parallel uploads are not desired or network is constrained.
+   *
+   * @param frames - Captured frames to analyze
+   * @param options - Additional options
+   * @param callbacks - Optional callbacks for progress tracking
+   * @returns Liveness result
+   */
+  async fastCheckStreamSequential(frames, options = {}, callbacks) {
+    const sessionId = options.sessionId ?? generateSessionId();
+    const model = options.model ?? "10";
+    const source = options.source ?? "live";
+    const frameDataList = toFrameData(frames);
+    const total = frameDataList.length;
+    let finalResponse = null;
+    for (const frameData of frameDataList) {
+      const response = await this.sendStreamFrameInternal(frameData, {
+        sessionId,
+        model,
+        source
+      });
+      const currentIndex = frameData.index;
+      callbacks?.onFrameSent?.(currentIndex + 1, total);
+      if (response.status === "buffering") {
+        callbacks?.onFrameBuffered?.(response.frames_received, response.frames_required);
+      } else if (response.status === "complete") {
+        finalResponse = response;
+        break;
+      }
+    }
+    if (!finalResponse) {
+      throw new LivenessApiError(
+        "Streaming did not complete after all frames sent",
+        "stream_incomplete",
+        400
+      );
+    }
+    return toLivenessResultFromStream(finalResponse);
+  }
   // ===========================================================================
   // Verify Endpoint (Spatial Features)
   // ===========================================================================
@@ -622,6 +788,7 @@ var FrameQueue = class {
 
 // src/types/models.ts
 var MODEL_CONFIGS = {
+  // Standard fast-check models
   "10": {
     type: "10",
     minFrames: 10,
@@ -639,6 +806,104 @@ var MODEL_CONFIGS = {
     minFrames: 250,
     recommendedFrames: 250,
     description: "High-accuracy model - 250 frames, best accuracy"
+  },
+  // Hybrid V2 models with physiological features
+  "hybrid-v2-10": {
+    type: "hybrid-v2-10",
+    minFrames: 10,
+    recommendedFrames: 10,
+    description: "Hybrid V2 10-frame model with physio features"
+  },
+  "hybrid-v2-30": {
+    type: "hybrid-v2-30",
+    minFrames: 30,
+    recommendedFrames: 30,
+    description: "Hybrid V2 30-frame model with physio features"
+  },
+  "hybrid-v2-50": {
+    type: "hybrid-v2-50",
+    minFrames: 50,
+    recommendedFrames: 50,
+    description: "Hybrid V2 50-frame model with physio features"
+  },
+  "hybrid-v2-60": {
+    type: "hybrid-v2-60",
+    minFrames: 60,
+    recommendedFrames: 60,
+    description: "Hybrid V2 60-frame model with physio features"
+  },
+  "hybrid-v2-90": {
+    type: "hybrid-v2-90",
+    minFrames: 90,
+    recommendedFrames: 90,
+    description: "Hybrid V2 90-frame model with physio features"
+  },
+  "hybrid-v2-100": {
+    type: "hybrid-v2-100",
+    minFrames: 100,
+    recommendedFrames: 100,
+    description: "Hybrid V2 100-frame model with physio features"
+  },
+  "hybrid-v2-125": {
+    type: "hybrid-v2-125",
+    minFrames: 125,
+    recommendedFrames: 125,
+    description: "Hybrid V2 125-frame model with physio features"
+  },
+  "hybrid-v2-150": {
+    type: "hybrid-v2-150",
+    minFrames: 150,
+    recommendedFrames: 150,
+    description: "Hybrid V2 150-frame model with physio features"
+  },
+  "hybrid-v2-250": {
+    type: "hybrid-v2-250",
+    minFrames: 250,
+    recommendedFrames: 250,
+    description: "Hybrid V2 250-frame model with physio features"
+  },
+  // Mixed models (FastLivenessDetector with mixed-trained weights)
+  "mixed-10": {
+    type: "mixed-10",
+    minFrames: 10,
+    recommendedFrames: 10,
+    description: "Mixed 10-frame model"
+  },
+  "mixed-30": {
+    type: "mixed-30",
+    minFrames: 30,
+    recommendedFrames: 30,
+    description: "Mixed 30-frame model"
+  },
+  "mixed-60": {
+    type: "mixed-60",
+    minFrames: 60,
+    recommendedFrames: 60,
+    description: "Mixed 60-frame model"
+  },
+  "mixed-90": {
+    type: "mixed-90",
+    minFrames: 90,
+    recommendedFrames: 90,
+    description: "Mixed 90-frame model"
+  },
+  "mixed-120": {
+    type: "mixed-120",
+    minFrames: 120,
+    recommendedFrames: 120,
+    description: "Mixed 120-frame model"
+  },
+  "mixed-150": {
+    type: "mixed-150",
+    minFrames: 150,
+    recommendedFrames: 150,
+    description: "Mixed 150-frame model"
+  },
+  "mixed-250": {
+    type: "mixed-250",
+    minFrames: 250,
+    recommendedFrames: 250,
+    description: "Mixed 250-frame model"
   }
 };
 var HYBRID_MODEL_CONFIGS = {
@@ -664,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;
@@ -915,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++) {
@@ -1012,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;
@@ -1204,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,
@@ -1218,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,
@@ -1234,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,
@@ -1246,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,
@@ -1277,7 +1604,9 @@ var BaseFrameCollector = class {
   toFrameData,
   toHybridFrameData,
   toLivenessResult,
+  toLivenessResultFromStream,
   validateApiKey,
+  validateFaceLandmarks,
   validateFrameCount,
   validateFrameData,
   validateFrameIndex,