@moveris/shared 2.9.0 → 3.0.0

package/dist/index.js

@@ -85,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,
@@ -171,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,
@@ -300,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);
@@ -325,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) {
@@ -410,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
    */
@@ -424,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
   // ===========================================================================
@@ -458,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
@@ -479,19 +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.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.
@@ -519,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)
     });
   }
   /**
@@ -565,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
       });
@@ -615,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
       });
@@ -891,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": {
@@ -898,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": {
@@ -920,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": {
@@ -984,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": {
@@ -1034,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 = {
@@ -2085,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,