@moveris/shared 2.1.1 → 2.2.0

package/README.md

@@ -25,6 +25,7 @@ const client = new LivenessClient({
 
 // Perform a fast liveness check
 const result = await client.fastCheck(frames, {
+  sessionId: 'my-session-id', // optional — auto-generated if omitted
   model: '10',
   source: 'live',
 });
@@ -293,6 +294,8 @@ const sessionId = generateSessionId();
 // e.g., 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
 ```
 
+> **Session ID injection**: Every `LivenessClient` method (`fastCheck`, `fastCheckCrops`, `streamFrame`, `verify`, `hybrid50`, `hybrid150`) accepts an optional `sessionId` in its options object. If provided, that ID is used for the request; if omitted, a new UUID is generated automatically. This is useful for debugging, testing, or correlating client requests with server logs. In `@moveris/react`, the `sessionId` can be injected via the `useLiveness` hook config or the `LivenessView` / `LivenessModal` props.
+
 #### `toFrameData(frames)`
 
 Convert CapturedFrame array to API format.

package/dist/index.d.mts

@@ -429,6 +429,10 @@ declare class LivenessClient {
     private readonly fetchFn;
     constructor(config: LivenessClientConfig);
     private request;
+    private parseErrorResponse;
+    private static unwrapErrorCode;
+    private static unwrapErrorMessage;
+    private static extractCodeFromText;
     private requestWithRetry;
     health(): Promise<HealthResponse>;
     queueStats(): Promise<QueueStatsResponse>;
@@ -565,6 +569,27 @@ declare const DEFAULT_LIVENESS_CONFIG: {
     readonly timeout: 30000;
 };
 
+declare const API_ERROR_CODES: {
+    readonly SESSION_EXPIRED: "session_expired";
+    readonly INVALID_KEY: "invalid_key";
+    readonly INVALID_MODEL: "invalid_model";
+    readonly INSUFFICIENT_FRAMES: "insufficient_frames";
+    readonly MISSING_FIELD: "missing_field";
+    readonly INVALID_FRAME: "invalid_frame";
+    readonly INVALID_SESSION: "invalid_session";
+    readonly RATE_LIMITED: "rate_limited";
+    readonly STREAM_INCOMPLETE: "stream_incomplete";
+    readonly NO_VERDICT: "no_verdict";
+    readonly TIMEOUT: "timeout";
+    readonly NETWORK_ERROR: "network_error";
+    readonly SERVER_ERROR: "server_error";
+};
+type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
+declare const ERROR_MESSAGES: Record<string, string>;
+declare const ERROR_MESSAGES_ES: Record<string, string>;
+declare function getApiErrorMessage(code: string | undefined, message?: string, customMessages?: Record<string, string>): string;
+declare function isRetryableError(code: string | undefined): boolean;
+
 declare const ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
 declare const ALIGNMENT_THRESHOLD_POOR = 0.5;
 declare const ALIGNMENT_THRESHOLD_GOOD = 0.5;
@@ -683,4 +708,4 @@ interface RetryOptions {
 declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 declare function sleep(ms: number): Promise<void>;
 
-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 };
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, 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, getApiErrorMessage, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.d.ts

@@ -429,6 +429,10 @@ declare class LivenessClient {
     private readonly fetchFn;
     constructor(config: LivenessClientConfig);
     private request;
+    private parseErrorResponse;
+    private static unwrapErrorCode;
+    private static unwrapErrorMessage;
+    private static extractCodeFromText;
     private requestWithRetry;
     health(): Promise<HealthResponse>;
     queueStats(): Promise<QueueStatsResponse>;
@@ -565,6 +569,27 @@ declare const DEFAULT_LIVENESS_CONFIG: {
     readonly timeout: 30000;
 };
 
+declare const API_ERROR_CODES: {
+    readonly SESSION_EXPIRED: "session_expired";
+    readonly INVALID_KEY: "invalid_key";
+    readonly INVALID_MODEL: "invalid_model";
+    readonly INSUFFICIENT_FRAMES: "insufficient_frames";
+    readonly MISSING_FIELD: "missing_field";
+    readonly INVALID_FRAME: "invalid_frame";
+    readonly INVALID_SESSION: "invalid_session";
+    readonly RATE_LIMITED: "rate_limited";
+    readonly STREAM_INCOMPLETE: "stream_incomplete";
+    readonly NO_VERDICT: "no_verdict";
+    readonly TIMEOUT: "timeout";
+    readonly NETWORK_ERROR: "network_error";
+    readonly SERVER_ERROR: "server_error";
+};
+type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
+declare const ERROR_MESSAGES: Record<string, string>;
+declare const ERROR_MESSAGES_ES: Record<string, string>;
+declare function getApiErrorMessage(code: string | undefined, message?: string, customMessages?: Record<string, string>): string;
+declare function isRetryableError(code: string | undefined): boolean;
+
 declare const ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
 declare const ALIGNMENT_THRESHOLD_POOR = 0.5;
 declare const ALIGNMENT_THRESHOLD_GOOD = 0.5;
@@ -683,4 +708,4 @@ interface RetryOptions {
 declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 declare function sleep(ms: number): Promise<void>;
 
-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 };
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, 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, getApiErrorMessage, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   ALIGNMENT_THRESHOLD_PERFECT: () => ALIGNMENT_THRESHOLD_PERFECT,
   ALIGNMENT_THRESHOLD_POOR: () => ALIGNMENT_THRESHOLD_POOR,
   API_ENDPOINTS: () => API_ENDPOINTS,
+  API_ERROR_CODES: () => API_ERROR_CODES,
   API_PATHS: () => API_PATHS,
   AUTH_CONFIG: () => AUTH_CONFIG,
   BACKLIT_RATIO_THRESHOLD: () => BACKLIT_RATIO_THRESHOLD,
@@ -40,6 +41,8 @@ __export(index_exports, {
   DEFAULT_OVAL_REGION: () => DEFAULT_OVAL_REGION,
   DEFAULT_STABILIZER_CONFIG: () => DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES: () => DEFAULT_STATUS_MESSAGES,
+  ERROR_MESSAGES: () => ERROR_MESSAGES,
+  ERROR_MESSAGES_ES: () => ERROR_MESSAGES_ES,
   ES_LOCALE: () => ES_LOCALE,
   FACE_CENTER_VERTICAL_OFFSET: () => FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE: () => FACE_CROP_OUTPUT_SIZE,
@@ -84,6 +87,7 @@ __export(index_exports, {
   decodeBase64: () => decodeBase64,
   encodeBase64: () => encodeBase64,
   generateSessionId: () => generateSessionId,
+  getApiErrorMessage: () => getApiErrorMessage,
   getCaptureQualityFeedback: () => getCaptureQualityFeedback,
   getFeedbackMessage: () => getFeedbackMessage,
   getMinFramesForModel: () => getMinFramesForModel,
@@ -93,6 +97,7 @@ __export(index_exports, {
   isFaceCropFullyInFrame: () => isFaceCropFullyInFrame,
   isFaceFullyVisible: () => isFaceFullyVisible,
   isFaceInOval: () => isFaceInOval,
+  isRetryableError: () => isRetryableError,
   retryWithBackoff: () => retryWithBackoff,
   rgbaToGrayscale: () => rgbaToGrayscale,
   sleep: () => sleep,
@@ -248,7 +253,8 @@ function toLivenessResultFromStream(response) {
     throw new LivenessApiError("Stream not complete", "stream_incomplete", 400);
   }
   if (!response.verdict) {
-    throw new LivenessApiError(response.error ?? "No verdict received", "no_verdict", 500);
+    const errorCode = response.error ?? "no_verdict";
+    throw new LivenessApiError(response.error ?? "No verdict received", errorCode, 500);
   }
   return {
     verdict: response.verdict,
@@ -269,7 +275,7 @@ function generateSessionId() {
     return v.toString(16);
   });
 }
-var LivenessClient = class {
+var LivenessClient = class _LivenessClient {
   constructor(config) {
     this.baseUrl = (config.baseUrl ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
     this.apiKey = config.apiKey;
@@ -296,14 +302,7 @@ var LivenessClient = class {
       });
       clearTimeout(timeoutId);
       if (!response.ok) {
-        const errorData = await response.json();
-        throw new LivenessApiError(
-          errorData.message,
-          errorData.error,
-          response.status,
-          errorData.required,
-          errorData.received
-        );
+        throw await this.parseErrorResponse(response);
       }
       return await response.json();
     } catch (error) {
@@ -321,6 +320,75 @@ var LivenessClient = class {
       );
     }
   }
+  /**
+   * Parse an error response body, handling both JSON and non-JSON bodies.
+   *
+   * The backend sometimes wraps the real error in a generic envelope:
+   * ```json
+   * { "error": "http_error", "message": "{'error': 'session_expired', ...}" }
+   * ```
+   * This method unwraps such envelopes to extract the real error code.
+   */
+  async parseErrorResponse(response) {
+    const status = response.status;
+    let body;
+    try {
+      body = await response.text();
+    } catch {
+      return new LivenessApiError(`Request failed with status ${status}`, "server_error", status);
+    }
+    try {
+      const data = JSON.parse(body);
+      if (data.error) {
+        const realCode = _LivenessClient.unwrapErrorCode(data.error, data.message);
+        const realMessage = _LivenessClient.unwrapErrorMessage(data.message);
+        return new LivenessApiError(
+          realMessage ?? `Request failed (${realCode})`,
+          realCode,
+          status,
+          data.required,
+          data.received
+        );
+      }
+    } catch {
+    }
+    const code = _LivenessClient.extractCodeFromText(body) ?? "server_error";
+    return new LivenessApiError(`Request failed with status ${status}`, code, status);
+  }
+  /**
+   * When the outer error code is a generic wrapper (e.g. "http_error"),
+   * try to extract the real error code from the message text.
+   */
+  static unwrapErrorCode(outerCode, message) {
+    const WRAPPER_CODES = /* @__PURE__ */ new Set([
+      "http_error",
+      "upstream_error",
+      "proxy_error",
+      "internal_error"
+    ]);
+    if (!WRAPPER_CODES.has(outerCode) || !message) {
+      return outerCode;
+    }
+    return _LivenessClient.extractCodeFromText(message) ?? outerCode;
+  }
+  /**
+   * Try to extract a human-readable message from a nested Python dict string.
+   * E.g.: "{'error': 'session_expired', 'message': \"Create a new session...\"}"
+   *       → "Create a new session..."
+   */
+  static unwrapErrorMessage(message) {
+    if (!message) return void 0;
+    const msgMatch = /'message'\s*:\s*"([^"]+)"/.exec(message) ?? /'message'\s*:\s*'([^']+)'/.exec(message) ?? /"message"\s*:\s*"([^"]+)"/.exec(message);
+    return msgMatch?.[1] ?? void 0;
+  }
+  /**
+   * Extract an error code from raw text using regex.
+   * Handles both Python dict (`'error': 'code'`) and JSON (`"error": "code"`).
+   */
+  static extractCodeFromText(text) {
+    const match = /'error'\s*:\s*'([^']+)'/.exec(text) ?? /"error"\s*:\s*"([^"]+)"/.exec(text);
+    return match?.[1] ?? null;
+  }
   /**
    * Make a request with optional retry
    */
@@ -952,6 +1020,81 @@ var DEFAULT_STABILIZER_CONFIG = {
   sampleSize: 64
 };
 
+// src/constants/errors.ts
+var API_ERROR_CODES = {
+  SESSION_EXPIRED: "session_expired",
+  INVALID_KEY: "invalid_key",
+  INVALID_MODEL: "invalid_model",
+  INSUFFICIENT_FRAMES: "insufficient_frames",
+  MISSING_FIELD: "missing_field",
+  INVALID_FRAME: "invalid_frame",
+  INVALID_SESSION: "invalid_session",
+  RATE_LIMITED: "rate_limited",
+  STREAM_INCOMPLETE: "stream_incomplete",
+  NO_VERDICT: "no_verdict",
+  TIMEOUT: "timeout",
+  NETWORK_ERROR: "network_error",
+  SERVER_ERROR: "server_error"
+};
+var ERROR_MESSAGES = {
+  [API_ERROR_CODES.SESSION_EXPIRED]: "Session expired \u2014 please restart the verification",
+  [API_ERROR_CODES.INVALID_KEY]: "Invalid API key \u2014 contact your administrator",
+  [API_ERROR_CODES.INVALID_MODEL]: "Invalid model configuration",
+  [API_ERROR_CODES.INSUFFICIENT_FRAMES]: "Not enough frames captured \u2014 try again",
+  [API_ERROR_CODES.MISSING_FIELD]: "Missing required data \u2014 please try again",
+  [API_ERROR_CODES.INVALID_FRAME]: "Invalid frame data \u2014 please try again",
+  [API_ERROR_CODES.INVALID_SESSION]: "Invalid session \u2014 please restart",
+  [API_ERROR_CODES.RATE_LIMITED]: "Too many requests \u2014 wait a moment and try again",
+  [API_ERROR_CODES.STREAM_INCOMPLETE]: "Streaming incomplete \u2014 please try again",
+  [API_ERROR_CODES.NO_VERDICT]: "No result received \u2014 please try again",
+  [API_ERROR_CODES.TIMEOUT]: "Request timed out \u2014 check your connection",
+  [API_ERROR_CODES.NETWORK_ERROR]: "Network error \u2014 check your connection",
+  [API_ERROR_CODES.SERVER_ERROR]: "Server error \u2014 please try again later"
+};
+var ERROR_MESSAGES_ES = {
+  [API_ERROR_CODES.SESSION_EXPIRED]: "Sesi\xF3n expirada \u2014 reinicie la verificaci\xF3n",
+  [API_ERROR_CODES.INVALID_KEY]: "Clave API inv\xE1lida \u2014 contacte al administrador",
+  [API_ERROR_CODES.INVALID_MODEL]: "Configuraci\xF3n de modelo inv\xE1lida",
+  [API_ERROR_CODES.INSUFFICIENT_FRAMES]: "Frames insuficientes \u2014 intente de nuevo",
+  [API_ERROR_CODES.MISSING_FIELD]: "Datos requeridos faltantes \u2014 intente de nuevo",
+  [API_ERROR_CODES.INVALID_FRAME]: "Frame inv\xE1lido \u2014 intente de nuevo",
+  [API_ERROR_CODES.INVALID_SESSION]: "Sesi\xF3n inv\xE1lida \u2014 reinicie",
+  [API_ERROR_CODES.RATE_LIMITED]: "Demasiadas solicitudes \u2014 espere un momento",
+  [API_ERROR_CODES.STREAM_INCOMPLETE]: "Streaming incompleto \u2014 intente de nuevo",
+  [API_ERROR_CODES.NO_VERDICT]: "Sin resultado \u2014 intente de nuevo",
+  [API_ERROR_CODES.TIMEOUT]: "Tiempo de espera agotado \u2014 verifique su conexi\xF3n",
+  [API_ERROR_CODES.NETWORK_ERROR]: "Error de red \u2014 verifique su conexi\xF3n",
+  [API_ERROR_CODES.SERVER_ERROR]: "Error del servidor \u2014 intente m\xE1s tarde"
+};
+function looksLikeRawData(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) return true;
+  if (/'error'\s*:/.test(trimmed)) return true;
+  if (/"error"\s*:/.test(trimmed)) return true;
+  return false;
+}
+var GENERIC_FALLBACK = "An unexpected error occurred \u2014 please try again";
+function getApiErrorMessage(code, message, customMessages) {
+  if (code) {
+    const custom = customMessages?.[code];
+    if (custom) return custom;
+    const known = ERROR_MESSAGES[code];
+    if (known) return known;
+  }
+  if (message && !looksLikeRawData(message)) {
+    return message;
+  }
+  return GENERIC_FALLBACK;
+}
+function isRetryableError(code) {
+  if (!code) return true;
+  const nonRetryable = /* @__PURE__ */ new Set([
+    API_ERROR_CODES.INVALID_KEY,
+    API_ERROR_CODES.INVALID_MODEL
+  ]);
+  return !nonRetryable.has(code);
+}
+
 // src/constants/feedback.ts
 var ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
 var ALIGNMENT_THRESHOLD_POOR = 0.5;
@@ -1530,6 +1673,7 @@ function validateFaceLandmarks(landmarks) {
   ALIGNMENT_THRESHOLD_PERFECT,
   ALIGNMENT_THRESHOLD_POOR,
   API_ENDPOINTS,
+  API_ERROR_CODES,
   API_PATHS,
   AUTH_CONFIG,
   BACKLIT_RATIO_THRESHOLD,
@@ -1545,6 +1689,8 @@ function validateFaceLandmarks(landmarks) {
   DEFAULT_OVAL_REGION,
   DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES,
+  ERROR_MESSAGES,
+  ERROR_MESSAGES_ES,
   ES_LOCALE,
   FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE,
@@ -1589,6 +1735,7 @@ function validateFaceLandmarks(landmarks) {
   decodeBase64,
   encodeBase64,
   generateSessionId,
+  getApiErrorMessage,
   getCaptureQualityFeedback,
   getFeedbackMessage,
   getMinFramesForModel,
@@ -1598,6 +1745,7 @@ function validateFaceLandmarks(landmarks) {
   isFaceCropFullyInFrame,
   isFaceFullyVisible,
   isFaceInOval,
+  isRetryableError,
   retryWithBackoff,
   rgbaToGrayscale,
   sleep,

package/dist/index.mjs

@@ -135,7 +135,8 @@ function toLivenessResultFromStream(response) {
     throw new LivenessApiError("Stream not complete", "stream_incomplete", 400);
   }
   if (!response.verdict) {
-    throw new LivenessApiError(response.error ?? "No verdict received", "no_verdict", 500);
+    const errorCode = response.error ?? "no_verdict";
+    throw new LivenessApiError(response.error ?? "No verdict received", errorCode, 500);
   }
   return {
     verdict: response.verdict,
@@ -156,7 +157,7 @@ function generateSessionId() {
     return v.toString(16);
   });
 }
-var LivenessClient = class {
+var LivenessClient = class _LivenessClient {
   constructor(config) {
     this.baseUrl = (config.baseUrl ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
     this.apiKey = config.apiKey;
@@ -183,14 +184,7 @@ var LivenessClient = class {
       });
       clearTimeout(timeoutId);
       if (!response.ok) {
-        const errorData = await response.json();
-        throw new LivenessApiError(
-          errorData.message,
-          errorData.error,
-          response.status,
-          errorData.required,
-          errorData.received
-        );
+        throw await this.parseErrorResponse(response);
       }
       return await response.json();
     } catch (error) {
@@ -208,6 +202,75 @@ var LivenessClient = class {
       );
     }
   }
+  /**
+   * Parse an error response body, handling both JSON and non-JSON bodies.
+   *
+   * The backend sometimes wraps the real error in a generic envelope:
+   * ```json
+   * { "error": "http_error", "message": "{'error': 'session_expired', ...}" }
+   * ```
+   * This method unwraps such envelopes to extract the real error code.
+   */
+  async parseErrorResponse(response) {
+    const status = response.status;
+    let body;
+    try {
+      body = await response.text();
+    } catch {
+      return new LivenessApiError(`Request failed with status ${status}`, "server_error", status);
+    }
+    try {
+      const data = JSON.parse(body);
+      if (data.error) {
+        const realCode = _LivenessClient.unwrapErrorCode(data.error, data.message);
+        const realMessage = _LivenessClient.unwrapErrorMessage(data.message);
+        return new LivenessApiError(
+          realMessage ?? `Request failed (${realCode})`,
+          realCode,
+          status,
+          data.required,
+          data.received
+        );
+      }
+    } catch {
+    }
+    const code = _LivenessClient.extractCodeFromText(body) ?? "server_error";
+    return new LivenessApiError(`Request failed with status ${status}`, code, status);
+  }
+  /**
+   * When the outer error code is a generic wrapper (e.g. "http_error"),
+   * try to extract the real error code from the message text.
+   */
+  static unwrapErrorCode(outerCode, message) {
+    const WRAPPER_CODES = /* @__PURE__ */ new Set([
+      "http_error",
+      "upstream_error",
+      "proxy_error",
+      "internal_error"
+    ]);
+    if (!WRAPPER_CODES.has(outerCode) || !message) {
+      return outerCode;
+    }
+    return _LivenessClient.extractCodeFromText(message) ?? outerCode;
+  }
+  /**
+   * Try to extract a human-readable message from a nested Python dict string.
+   * E.g.: "{'error': 'session_expired', 'message': \"Create a new session...\"}"
+   *       → "Create a new session..."
+   */
+  static unwrapErrorMessage(message) {
+    if (!message) return void 0;
+    const msgMatch = /'message'\s*:\s*"([^"]+)"/.exec(message) ?? /'message'\s*:\s*'([^']+)'/.exec(message) ?? /"message"\s*:\s*"([^"]+)"/.exec(message);
+    return msgMatch?.[1] ?? void 0;
+  }
+  /**
+   * Extract an error code from raw text using regex.
+   * Handles both Python dict (`'error': 'code'`) and JSON (`"error": "code"`).
+   */
+  static extractCodeFromText(text) {
+    const match = /'error'\s*:\s*'([^']+)'/.exec(text) ?? /"error"\s*:\s*"([^"]+)"/.exec(text);
+    return match?.[1] ?? null;
+  }
   /**
    * Make a request with optional retry
    */
@@ -839,6 +902,81 @@ var DEFAULT_STABILIZER_CONFIG = {
   sampleSize: 64
 };
 
+// src/constants/errors.ts
+var API_ERROR_CODES = {
+  SESSION_EXPIRED: "session_expired",
+  INVALID_KEY: "invalid_key",
+  INVALID_MODEL: "invalid_model",
+  INSUFFICIENT_FRAMES: "insufficient_frames",
+  MISSING_FIELD: "missing_field",
+  INVALID_FRAME: "invalid_frame",
+  INVALID_SESSION: "invalid_session",
+  RATE_LIMITED: "rate_limited",
+  STREAM_INCOMPLETE: "stream_incomplete",
+  NO_VERDICT: "no_verdict",
+  TIMEOUT: "timeout",
+  NETWORK_ERROR: "network_error",
+  SERVER_ERROR: "server_error"
+};
+var ERROR_MESSAGES = {
+  [API_ERROR_CODES.SESSION_EXPIRED]: "Session expired \u2014 please restart the verification",
+  [API_ERROR_CODES.INVALID_KEY]: "Invalid API key \u2014 contact your administrator",
+  [API_ERROR_CODES.INVALID_MODEL]: "Invalid model configuration",
+  [API_ERROR_CODES.INSUFFICIENT_FRAMES]: "Not enough frames captured \u2014 try again",
+  [API_ERROR_CODES.MISSING_FIELD]: "Missing required data \u2014 please try again",
+  [API_ERROR_CODES.INVALID_FRAME]: "Invalid frame data \u2014 please try again",
+  [API_ERROR_CODES.INVALID_SESSION]: "Invalid session \u2014 please restart",
+  [API_ERROR_CODES.RATE_LIMITED]: "Too many requests \u2014 wait a moment and try again",
+  [API_ERROR_CODES.STREAM_INCOMPLETE]: "Streaming incomplete \u2014 please try again",
+  [API_ERROR_CODES.NO_VERDICT]: "No result received \u2014 please try again",
+  [API_ERROR_CODES.TIMEOUT]: "Request timed out \u2014 check your connection",
+  [API_ERROR_CODES.NETWORK_ERROR]: "Network error \u2014 check your connection",
+  [API_ERROR_CODES.SERVER_ERROR]: "Server error \u2014 please try again later"
+};
+var ERROR_MESSAGES_ES = {
+  [API_ERROR_CODES.SESSION_EXPIRED]: "Sesi\xF3n expirada \u2014 reinicie la verificaci\xF3n",
+  [API_ERROR_CODES.INVALID_KEY]: "Clave API inv\xE1lida \u2014 contacte al administrador",
+  [API_ERROR_CODES.INVALID_MODEL]: "Configuraci\xF3n de modelo inv\xE1lida",
+  [API_ERROR_CODES.INSUFFICIENT_FRAMES]: "Frames insuficientes \u2014 intente de nuevo",
+  [API_ERROR_CODES.MISSING_FIELD]: "Datos requeridos faltantes \u2014 intente de nuevo",
+  [API_ERROR_CODES.INVALID_FRAME]: "Frame inv\xE1lido \u2014 intente de nuevo",
+  [API_ERROR_CODES.INVALID_SESSION]: "Sesi\xF3n inv\xE1lida \u2014 reinicie",
+  [API_ERROR_CODES.RATE_LIMITED]: "Demasiadas solicitudes \u2014 espere un momento",
+  [API_ERROR_CODES.STREAM_INCOMPLETE]: "Streaming incompleto \u2014 intente de nuevo",
+  [API_ERROR_CODES.NO_VERDICT]: "Sin resultado \u2014 intente de nuevo",
+  [API_ERROR_CODES.TIMEOUT]: "Tiempo de espera agotado \u2014 verifique su conexi\xF3n",
+  [API_ERROR_CODES.NETWORK_ERROR]: "Error de red \u2014 verifique su conexi\xF3n",
+  [API_ERROR_CODES.SERVER_ERROR]: "Error del servidor \u2014 intente m\xE1s tarde"
+};
+function looksLikeRawData(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) return true;
+  if (/'error'\s*:/.test(trimmed)) return true;
+  if (/"error"\s*:/.test(trimmed)) return true;
+  return false;
+}
+var GENERIC_FALLBACK = "An unexpected error occurred \u2014 please try again";
+function getApiErrorMessage(code, message, customMessages) {
+  if (code) {
+    const custom = customMessages?.[code];
+    if (custom) return custom;
+    const known = ERROR_MESSAGES[code];
+    if (known) return known;
+  }
+  if (message && !looksLikeRawData(message)) {
+    return message;
+  }
+  return GENERIC_FALLBACK;
+}
+function isRetryableError(code) {
+  if (!code) return true;
+  const nonRetryable = /* @__PURE__ */ new Set([
+    API_ERROR_CODES.INVALID_KEY,
+    API_ERROR_CODES.INVALID_MODEL
+  ]);
+  return !nonRetryable.has(code);
+}
+
 // src/constants/feedback.ts
 var ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
 var ALIGNMENT_THRESHOLD_POOR = 0.5;
@@ -1416,6 +1554,7 @@ export {
   ALIGNMENT_THRESHOLD_PERFECT,
   ALIGNMENT_THRESHOLD_POOR,
   API_ENDPOINTS,
+  API_ERROR_CODES,
   API_PATHS,
   AUTH_CONFIG,
   BACKLIT_RATIO_THRESHOLD,
@@ -1431,6 +1570,8 @@ export {
   DEFAULT_OVAL_REGION,
   DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES,
+  ERROR_MESSAGES,
+  ERROR_MESSAGES_ES,
   ES_LOCALE,
   FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE,
@@ -1475,6 +1616,7 @@ export {
   decodeBase64,
   encodeBase64,
   generateSessionId,
+  getApiErrorMessage,
   getCaptureQualityFeedback,
   getFeedbackMessage,
   getMinFramesForModel,
@@ -1484,6 +1626,7 @@ export {
   isFaceCropFullyInFrame,
   isFaceFullyVisible,
   isFaceInOval,
+  isRetryableError,
   retryWithBackoff,
   rgbaToGrayscale,
   sleep,

package/package.json

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