@moveris/shared 2.7.0 → 3.0.0

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,
@@ -83,6 +85,7 @@ __export(index_exports, {
   OVAL_REGION_MOBILE: () => OVAL_REGION_MOBILE,
   RETRY_CONFIG: () => RETRY_CONFIG,
   TARGET_FACE_PERCENTAGE_IN_CROP: () => TARGET_FACE_PERCENTAGE_IN_CROP,
+  VALID_FRAME_COUNTS: () => VALID_FRAME_COUNTS,
   analyzeBlur: () => analyzeBlur,
   analyzeEyeRegionBrightness: () => analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast: () => analyzeEyeRegionContrast,
@@ -95,6 +98,7 @@ __export(index_exports, {
   checkEyeRegionQuality: () => checkEyeRegionQuality,
   checkFrameQuality: () => checkFrameQuality,
   decodeBase64: () => decodeBase64,
+  detectCameraAngle: () => detectCameraAngle,
   detectFaceRoll: () => detectFaceRoll,
   detectSpecularHighlights: () => detectSpecularHighlights,
   encodeBase64: () => encodeBase64,
@@ -168,7 +172,8 @@ var FRAME_BUFFER_CONFIG = {
 var AUTH_CONFIG = {
   timeout: 3e4,
   // 30 seconds for API requests
-  apiKeyHeader: "X-API-Key"
+  apiKeyHeader: "X-API-Key",
+  modelVersionHeader: "X-Model-Version"
 };
 var FRAME_CONFIG = {
   targetFPS: 30,
@@ -297,14 +302,22 @@ var LivenessClient = class _LivenessClient {
   constructor(config) {
     this.baseUrl = (config.baseUrl ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
     this.apiKey = config.apiKey;
+    this.modelVersion = config.modelVersion;
     this.timeout = config.timeout ?? AUTH_CONFIG.timeout;
     this.enableRetry = config.enableRetry ?? true;
     this.fetchFn = config.customFetch ?? (typeof window !== "undefined" ? fetch.bind(window) : fetch);
   }
   /**
-   * Make an authenticated API request
+   * Make an authenticated API request, returning the parsed body.
    */
   async request(path, options = {}) {
+    const { data } = await this.requestRaw(path, options);
+    return data;
+  }
+  /**
+   * Make an authenticated API request, returning both parsed body and headers.
+   */
+  async requestRaw(path, options = {}) {
     const url = `${this.baseUrl}${path}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
@@ -322,7 +335,8 @@ var LivenessClient = class _LivenessClient {
       if (!response.ok) {
         throw await this.parseErrorResponse(response);
       }
-      return await response.json();
+      const data = await response.json();
+      return { data, headers: response.headers };
     } catch (error) {
       clearTimeout(timeoutId);
       if (error instanceof LivenessApiError) {
@@ -407,6 +421,30 @@ var LivenessClient = class _LivenessClient {
     const match = /'error'\s*:\s*'([^']+)'/.exec(text) ?? /"error"\s*:\s*"([^"]+)"/.exec(text);
     return match?.[1] ?? null;
   }
+  /**
+   * Parse deprecation-related headers from an API response.
+   * Returns undefined when no deprecation info is present.
+   */
+  static parseDeprecationHeaders(headers) {
+    const resolved = headers.get("x-moveris-model-resolved");
+    if (!resolved) return void 0;
+    const deprecated = headers.get("deprecation") === "true";
+    return {
+      deprecated,
+      resolvedModel: resolved,
+      deprecatedModel: headers.get("x-moveris-deprecated-model") ?? void 0,
+      sunsetDate: headers.get("sunset") ?? void 0,
+      suggestedModel: headers.get("x-moveris-suggested-model") ?? void 0
+    };
+  }
+  /**
+   * Build extra request headers for model versioning.
+   */
+  buildModelVersionHeaders(modelVersion) {
+    const version = modelVersion ?? this.modelVersion;
+    if (!version) return {};
+    return { [AUTH_CONFIG.modelVersionHeader]: version };
+  }
   /**
    * Make a request with optional retry
    */
@@ -421,6 +459,20 @@ var LivenessClient = class _LivenessClient {
     }
     return this.request(path, options);
   }
+  /**
+   * Make a request with optional retry, returning both data and headers.
+   */
+  async requestWithRetryRaw(path, options = {}) {
+    if (this.enableRetry) {
+      return retryWithBackoff(() => this.requestRaw(path, options), {
+        maxAttempts: RETRY_CONFIG.maxAttempts,
+        initialDelay: RETRY_CONFIG.initialDelay,
+        maxDelay: RETRY_CONFIG.maxDelay,
+        backoffMultiplier: RETRY_CONFIG.backoffMultiplier
+      });
+    }
+    return this.requestRaw(path, options);
+  }
   // ===========================================================================
   // Health & Status
   // ===========================================================================
@@ -455,18 +507,31 @@ var LivenessClient = class _LivenessClient {
    * @returns Liveness result
    */
   async fastCheck(frames, options = {}) {
+    const effectiveVersion = options.modelVersion ?? this.modelVersion;
     const request = {
       session_id: options.sessionId ?? generateSessionId(),
       model: options.model ?? "10",
       source: options.source ?? "live",
       frames: toFrameData(frames),
+      ...options.frameCount != null ? { frame_count: options.frameCount } : {},
       ...options.warnings?.length ? { warnings: options.warnings } : {}
     };
-    const response = await this.requestWithRetry(API_PATHS.fastCheck, {
-      method: "POST",
-      body: JSON.stringify(request)
-    });
-    return toLivenessResult(response);
+    const { data: response, headers } = await this.requestWithRetryRaw(
+      API_PATHS.fastCheck,
+      {
+        method: "POST",
+        body: JSON.stringify(request),
+        headers: this.buildModelVersionHeaders(effectiveVersion)
+      }
+    );
+    const result = toLivenessResult(response);
+    result.deprecation = _LivenessClient.parseDeprecationHeaders(headers);
+    if (result.deprecation?.deprecated) {
+      console.warn(
+        `[Moveris] Model "${result.deprecation.resolvedModel}" is deprecated.` + (result.deprecation.suggestedModel ? ` Migrate to "${result.deprecation.suggestedModel}".` : "") + (result.deprecation.sunsetDate ? ` Sunset date: ${result.deprecation.sunsetDate}.` : "")
+      );
+    }
+    return result;
   }
   /**
    * Perform fast liveness check with pre-cropped face images
@@ -476,18 +541,32 @@ var LivenessClient = class _LivenessClient {
    * @returns Liveness result
    */
   async fastCheckCrops(crops, options = {}) {
+    const effectiveVersion = options.modelVersion ?? this.modelVersion;
     const request = {
       session_id: options.sessionId ?? generateSessionId(),
       model: options.model ?? "10",
       source: options.source ?? "live",
       crops,
-      ...options.warnings?.length ? { warnings: options.warnings } : {}
+      ...options.frameCount != null ? { frame_count: options.frameCount } : {},
+      ...options.warnings?.length ? { warnings: options.warnings } : {},
+      ...options.bgSegmentation !== void 0 ? { bg_segmentation: options.bgSegmentation } : {}
     };
-    const response = await this.requestWithRetry(API_PATHS.fastCheckCrops, {
-      method: "POST",
-      body: JSON.stringify(request)
-    });
-    return toLivenessResult(response);
+    const { data: response, headers } = await this.requestWithRetryRaw(
+      API_PATHS.fastCheckCrops,
+      {
+        method: "POST",
+        body: JSON.stringify(request),
+        headers: this.buildModelVersionHeaders(effectiveVersion)
+      }
+    );
+    const result = toLivenessResult(response);
+    result.deprecation = _LivenessClient.parseDeprecationHeaders(headers);
+    if (result.deprecation?.deprecated) {
+      console.warn(
+        `[Moveris] Model "${result.deprecation.resolvedModel}" is deprecated.` + (result.deprecation.suggestedModel ? ` Migrate to "${result.deprecation.suggestedModel}".` : "") + (result.deprecation.sunsetDate ? ` Sunset date: ${result.deprecation.sunsetDate}.` : "")
+      );
+    }
+    return result;
   }
   /**
    * Send a single captured frame to the streaming endpoint.
@@ -515,28 +594,29 @@ var LivenessClient = class _LivenessClient {
     return this.sendStreamFrameInternal(frameData, {
       sessionId: options.sessionId,
       model: options.model ?? "10",
+      modelVersion: options.modelVersion,
+      frameCount: options.frameCount,
       source: options.source ?? "live",
       warnings: options.warnings
     });
   }
   /**
    * 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 effectiveVersion = options.modelVersion ?? this.modelVersion;
     const request = {
       session_id: options.sessionId,
       model: options.model,
       source: options.source,
       frame: frameData,
+      ...options.frameCount != null ? { frame_count: options.frameCount } : {},
       ...options.warnings?.length ? { warnings: options.warnings } : {}
     };
     return this.requestWithRetry(API_PATHS.fastCheckStream, {
       method: "POST",
-      body: JSON.stringify(request)
+      body: JSON.stringify(request),
+      headers: this.buildModelVersionHeaders(effectiveVersion)
     });
   }
   /**
@@ -561,6 +641,8 @@ var LivenessClient = class _LivenessClient {
       const response = await this.sendStreamFrameInternal(frameData, {
         sessionId,
         model,
+        modelVersion: options.modelVersion,
+        frameCount: options.frameCount,
         source,
         warnings: options.warnings
       });
@@ -611,6 +693,8 @@ var LivenessClient = class _LivenessClient {
       const response = await this.sendStreamFrameInternal(frameData, {
         sessionId,
         model,
+        modelVersion: options.modelVersion,
+        frameCount: options.frameCount,
         source,
         warnings: options.warnings
       });
@@ -887,6 +971,7 @@ var FrameQueue = class {
 };
 
 // src/types/models.ts
+var VALID_FRAME_COUNTS = [10, 30, 60, 90, 120];
 var MODEL_CONFIGS = {
   // Standard fast-check models
   "10": {
@@ -894,21 +979,24 @@ var MODEL_CONFIGS = {
     minFrames: 10,
     recommendedFrames: 10,
     description: "Fast model - 10 frames, quick verification",
-    deprecated: false
+    deprecated: false,
+    aliases: ["fast"]
   },
   "50": {
     type: "50",
     minFrames: 50,
     recommendedFrames: 50,
     description: "Balanced model - 50 frames, good accuracy",
-    deprecated: false
+    deprecated: false,
+    aliases: ["spatial"]
   },
   "250": {
     type: "250",
     minFrames: 250,
     recommendedFrames: 250,
     description: "High-accuracy model - 250 frames, best accuracy",
-    deprecated: false
+    deprecated: false,
+    aliases: ["spatial"]
   },
   // Hybrid V2 models with physiological features
   "hybrid-v2-10": {
@@ -916,63 +1004,72 @@ var MODEL_CONFIGS = {
     minFrames: 10,
     recommendedFrames: 10,
     description: "Hybrid V2 10-frame model with physio features",
-    deprecated: false
+    deprecated: false,
+    aliases: ["hybrid"]
   },
   "hybrid-v2-30": {
     type: "hybrid-v2-30",
     minFrames: 30,
     recommendedFrames: 30,
     description: "Hybrid V2 30-frame model with physio features",
-    deprecated: false
+    deprecated: false,
+    aliases: ["hybrid"]
   },
   "hybrid-v2-50": {
     type: "hybrid-v2-50",
     minFrames: 50,
     recommendedFrames: 50,
     description: "Hybrid V2 50-frame model with physio features",
-    deprecated: false
+    deprecated: false,
+    aliases: ["hybrid"]
   },
   "hybrid-v2-60": {
     type: "hybrid-v2-60",
     minFrames: 60,
     recommendedFrames: 60,
     description: "Hybrid V2 60-frame model with physio features",
-    deprecated: false
+    deprecated: false,
+    aliases: ["hybrid"]
   },
   "hybrid-v2-90": {
     type: "hybrid-v2-90",
     minFrames: 90,
     recommendedFrames: 90,
     description: "Hybrid V2 90-frame model with physio features",
-    deprecated: false
+    deprecated: false,
+    aliases: ["hybrid"]
   },
   "hybrid-v2-100": {
     type: "hybrid-v2-100",
     minFrames: 100,
     recommendedFrames: 100,
     description: "Hybrid V2 100-frame model with physio features",
-    deprecated: false
+    deprecated: false,
+    aliases: ["hybrid"]
   },
   "hybrid-v2-125": {
     type: "hybrid-v2-125",
     minFrames: 125,
     recommendedFrames: 125,
     description: "Hybrid V2 125-frame model with physio features",
-    deprecated: false
+    deprecated: false,
+    aliases: ["hybrid"]
   },
   "hybrid-v2-150": {
     type: "hybrid-v2-150",
     minFrames: 150,
     recommendedFrames: 150,
     description: "Hybrid V2 150-frame model with physio features",
-    deprecated: false
+    deprecated: false,
+    aliases: ["hybrid"]
   },
   "hybrid-v2-250": {
     type: "hybrid-v2-250",
     minFrames: 250,
     recommendedFrames: 250,
     description: "Hybrid V2 250-frame model with physio features",
-    deprecated: false
+    deprecated: false,
+    aliases: ["hybrid"]
   },
   // Mixed V1 models — deprecated, use mixed-*-v2 equivalents instead
   "mixed-10": {
@@ -980,49 +1077,68 @@ var MODEL_CONFIGS = {
     minFrames: 10,
     recommendedFrames: 10,
     description: "Mixed 10-frame model",
-    deprecated: true
+    deprecated: true,
+    aliases: ["v1"],
+    sunsetDate: "2026-09-01",
+    replacement: "mixed-10-v2"
   },
   "mixed-30": {
     type: "mixed-30",
     minFrames: 30,
     recommendedFrames: 30,
     description: "Mixed 30-frame model",
-    deprecated: true
+    deprecated: true,
+    aliases: ["v1"],
+    sunsetDate: "2026-09-01",
+    replacement: "mixed-30-v2"
   },
   "mixed-60": {
     type: "mixed-60",
     minFrames: 60,
     recommendedFrames: 60,
     description: "Mixed 60-frame model",
-    deprecated: true
+    deprecated: true,
+    aliases: ["v1"],
+    sunsetDate: "2026-09-01",
+    replacement: "mixed-60-v2"
   },
   "mixed-90": {
     type: "mixed-90",
     minFrames: 90,
     recommendedFrames: 90,
     description: "Mixed 90-frame model",
-    deprecated: true
+    deprecated: true,
+    aliases: ["v1"],
+    sunsetDate: "2026-09-01",
+    replacement: "mixed-90-v2"
   },
   "mixed-120": {
     type: "mixed-120",
     minFrames: 120,
     recommendedFrames: 120,
     description: "Mixed 120-frame model",
-    deprecated: true
+    deprecated: true,
+    aliases: ["v1"],
+    sunsetDate: "2026-09-01",
+    replacement: "mixed-120-v2"
   },
   "mixed-150": {
     type: "mixed-150",
     minFrames: 150,
     recommendedFrames: 150,
     description: "Mixed 150-frame model",
-    deprecated: true
+    deprecated: true,
+    aliases: ["v1"],
+    sunsetDate: "2026-09-01"
   },
   "mixed-250": {
     type: "mixed-250",
     minFrames: 250,
     recommendedFrames: 250,
     description: "Mixed 250-frame model",
-    deprecated: true
+    deprecated: true,
+    aliases: ["v1"],
+    sunsetDate: "2026-09-01"
   },
   // Mixed V2 models (exp_042 checkpoints — EER: 4.0% / AUC: 0.991 at 30f)
   "mixed-10-v2": {
@@ -1030,35 +1146,40 @@ var MODEL_CONFIGS = {
     minFrames: 10,
     recommendedFrames: 10,
     description: "Mixed V2 10-frame model",
-    deprecated: false
+    deprecated: false,
+    aliases: ["latest", "v2"]
   },
   "mixed-30-v2": {
     type: "mixed-30-v2",
     minFrames: 30,
     recommendedFrames: 30,
     description: "Mixed V2 30-frame model (recommended \u2014 95.7% balanced accuracy)",
-    deprecated: false
+    deprecated: false,
+    aliases: ["latest", "v2"]
   },
   "mixed-60-v2": {
     type: "mixed-60-v2",
     minFrames: 60,
     recommendedFrames: 60,
     description: "Mixed V2 60-frame model",
-    deprecated: false
+    deprecated: false,
+    aliases: ["latest", "v2"]
   },
   "mixed-90-v2": {
     type: "mixed-90-v2",
     minFrames: 90,
     recommendedFrames: 90,
     description: "Mixed V2 90-frame model",
-    deprecated: false
+    deprecated: false,
+    aliases: ["latest", "v2"]
   },
   "mixed-120-v2": {
     type: "mixed-120-v2",
     minFrames: 120,
     recommendedFrames: 120,
     description: "Mixed V2 120-frame model",
-    deprecated: false
+    deprecated: false,
+    aliases: ["latest", "v2"]
   }
 };
 var HYBRID_MODEL_CONFIGS = {
@@ -1254,9 +1375,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
@@ -1316,9 +1438,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
@@ -1354,17 +1477,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;
@@ -1408,10 +1535,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
@@ -1478,7 +1606,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;
@@ -1779,6 +1907,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 = [];
@@ -1996,6 +2148,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,
@@ -2048,6 +2202,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   OVAL_REGION_MOBILE,
   RETRY_CONFIG,
   TARGET_FACE_PERCENTAGE_IN_CROP,
+  VALID_FRAME_COUNTS,
   analyzeBlur,
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
@@ -2060,6 +2215,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectCameraAngle,
   detectFaceRoll,
   detectSpecularHighlights,
   encodeBase64,