@moveris/shared 0.0.1 → 1.0.1

package/dist/index.mjs

@@ -1,44 +1,74 @@
 // src/constants/config.ts
 var API_ENDPOINTS = {
-  production: "wss://api.moveris.com/v1/liveness",
-  staging: "wss://staging-api.moveris.com/v1/liveness",
-  development: "ws://localhost:8080/v1/liveness"
+  production: "https://api.moveris.com",
+  staging: "https://moveris-api-v2-staging.fly.dev",
+  development: "http://localhost:8000"
 };
 var DEFAULT_ENDPOINT = API_ENDPOINTS.production;
-var RECONNECTION_CONFIG = {
-  maxAttempts: 10,
+var API_PATHS = {
+  health: "/health",
+  fastCheck: "/api/v1/fast-check",
+  fastCheckCrops: "/api/v1/fast-check-crops",
+  verify: "/api/v1/verify",
+  hybridCheck: "/api/v1/hybrid-check",
+  hybrid50: "/api/v1/hybrid-50",
+  hybrid150: "/api/v1/hybrid-150",
+  jobResult: "/api/v1/result",
+  queueStats: "/api/v1/queue/stats"
+};
+var RETRY_CONFIG = {
+  maxAttempts: 3,
   initialDelay: 1e3,
   // 1 second
-  maxDelay: 3e4,
-  // 30 seconds
+  maxDelay: 1e4,
+  // 10 seconds
   backoffMultiplier: 2
 };
 var FRAME_BUFFER_CONFIG = {
   maxSize: 10,
-  // Maximum un-acked frames
+  // Maximum frames to keep in buffer
   maxMemory: 4 * 1024 * 1024
   // 4 MB
 };
 var AUTH_CONFIG = {
-  timeout: 1e4,
-  // 10 seconds
-  apiKeyPattern: /^mv_[a-zA-Z0-9]{32}$/
+  timeout: 3e4,
+  // 30 seconds for API requests
+  apiKeyHeader: "X-API-Key"
 };
 var FRAME_CONFIG = {
   targetFPS: 30,
   frameInterval: 33,
   // milliseconds (1000 / 30)
-  jpegQuality: 0.8
+  jpegQuality: 0.8,
   // 80%
+  defaultModel: "10",
+  defaultSource: "live"
+};
+var DEFAULT_LIVENESS_CONFIG = {
+  model: FRAME_CONFIG.defaultModel,
+  source: FRAME_CONFIG.defaultSource,
+  fps: FRAME_CONFIG.targetFPS,
+  timeout: AUTH_CONFIG.timeout
 };
 
 // src/utils/retry.ts
+function defaultIsRetryable(error) {
+  if (error instanceof Error) {
+    if ("statusCode" in error) {
+      const statusCode = error.statusCode;
+      return statusCode === 0 || statusCode === 408 || statusCode === 429 || statusCode >= 500;
+    }
+    return error.name === "AbortError" || error.message.includes("network") || error.message.includes("fetch");
+  }
+  return false;
+}
 async function retryWithBackoff(fn, options = {}) {
   const {
-    maxAttempts = RECONNECTION_CONFIG.maxAttempts,
-    initialDelay = RECONNECTION_CONFIG.initialDelay,
-    maxDelay = RECONNECTION_CONFIG.maxDelay,
-    backoffMultiplier = RECONNECTION_CONFIG.backoffMultiplier
+    maxAttempts = RETRY_CONFIG.maxAttempts,
+    initialDelay = RETRY_CONFIG.initialDelay,
+    maxDelay = RETRY_CONFIG.maxDelay,
+    backoffMultiplier = RETRY_CONFIG.backoffMultiplier,
+    isRetryable = defaultIsRetryable
   } = options;
   let lastError;
   let delay = initialDelay;
@@ -47,6 +77,9 @@ async function retryWithBackoff(fn, options = {}) {
       return await fn();
     } catch (error) {
       lastError = error;
+      if (!isRetryable(error)) {
+        throw error;
+      }
       if (attempt < maxAttempts - 1) {
         await new Promise((resolve) => setTimeout(resolve, delay));
         delay = Math.min(delay * backoffMultiplier, maxDelay);
@@ -55,189 +88,294 @@ async function retryWithBackoff(fn, options = {}) {
   }
   throw lastError;
 }
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
 
-// src/client/ConnectionManager.ts
-var ConnectionManager = class {
-  constructor(config) {
-    this.reconnectAttempts = 0;
-    this.config = config;
-  }
-  async handleDisconnect() {
-    if (this.reconnectAttempts >= (this.config.maxAttempts ?? 10)) {
-      throw new Error("Max reconnection attempts reached");
-    }
-    try {
-      await retryWithBackoff(
-        async () => {
-          await this.config.onReconnect();
-          this.reconnectAttempts = 0;
-        },
-        {
-          maxAttempts: this.config.maxAttempts ?? 10
-        }
-      );
-    } catch (error) {
-      this.reconnectAttempts++;
-      throw error;
-    }
-  }
-  reset() {
-    this.reconnectAttempts = 0;
+// src/client/LivenessClient.ts
+var LivenessApiError = class extends Error {
+  constructor(message, code, statusCode, required, received) {
+    super(message);
+    this.name = "LivenessApiError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.required = required;
+    this.received = received;
   }
 };
-
-// src/utils/validators.ts
-function validateApiKey(apiKey) {
-  if (!apiKey || typeof apiKey !== "string") {
-    return false;
-  }
-  return AUTH_CONFIG.apiKeyPattern.test(apiKey);
+function toFrameData(frames) {
+  return frames.map((frame) => ({
+    index: frame.index,
+    timestamp_ms: frame.timestampMs,
+    pixels: frame.pixels
+  }));
 }
-function validateFrameData(data) {
-  if (!data || typeof data !== "string") {
-    return false;
-  }
-  const base64Pattern = /^[A-Za-z0-9+/=]+$/;
-  return base64Pattern.test(data) && data.length > 0;
+function toHybridFrameData(frames) {
+  return frames.map((frame) => ({
+    timestamp_ms: frame.timestampMs,
+    pixels: frame.pixels
+  }));
 }
-function validateFrameNumber(frameNumber) {
-  return Number.isInteger(frameNumber) && frameNumber > 0;
-}
-
-// src/types/models.ts
-var MODEL_CONFIGS = {
-  "50-frame": {
-    type: "50-frame",
-    fileName: "model_50.h5",
-    frameCount: 50
-  },
-  "250-frame": {
-    type: "250-frame",
-    fileName: "model_250.h5",
-    frameCount: 250
+function toLivenessResult(response) {
+  if (!response.verdict) {
+    throw new LivenessApiError(response.error ?? "No verdict received", "no_verdict", 500);
   }
-};
-
-// src/client/AuthManager.ts
-var AuthManager = class {
-  async authenticate(ws, apiKey, model) {
-    if (!validateApiKey(apiKey)) {
-      throw new Error("Invalid API key format");
-    }
-    const modelType = model;
-    if (!MODEL_CONFIGS[modelType]) {
-      throw new Error(`Invalid model type: ${model}`);
-    }
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        reject(new Error("Authentication timeout"));
-      }, AUTH_CONFIG.timeout);
-      const messageHandler = (event) => {
-        try {
-          const message = JSON.parse(event.data);
-          if (message.type === "auth_success") {
-            clearTimeout(timeout);
-            ws.removeEventListener("message", messageHandler);
-            resolve(message.request_id);
-          } else if (message.type === "auth_error") {
-            clearTimeout(timeout);
-            ws.removeEventListener("message", messageHandler);
-            reject(new Error(message.error));
-          }
-        } catch (error) {
-        }
-      };
-      ws.addEventListener("message", messageHandler);
-      ws.send(
-        JSON.stringify({
-          type: "auth",
-          token: apiKey,
-          model_file_name: MODEL_CONFIGS[modelType].fileName
-        })
-      );
-    });
+  return {
+    verdict: response.verdict,
+    confidence: response.confidence ?? 0,
+    score: response.score ?? 0,
+    sessionId: response.session_id,
+    processingMs: response.processing_ms,
+    framesProcessed: "frames_processed" in response ? response.frames_processed ?? 0 : 0
+  };
+}
+function generateSessionId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
   }
-};
-
-// src/client/WebSocketClient.ts
-var WebSocketClient = class {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+var LivenessClient = class {
   constructor(config) {
-    this.ws = null;
-    this.state = "disconnected";
-    this.config = config;
-    this.connectionManager = new ConnectionManager({
-      onReconnect: () => this.connect()
-    });
-    this.authManager = new AuthManager();
+    this.baseUrl = (config.baseUrl ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout ?? AUTH_CONFIG.timeout;
+    this.enableRetry = config.enableRetry ?? true;
+    this.fetchFn = config.customFetch ?? (typeof window !== "undefined" ? fetch.bind(window) : fetch);
   }
-  async connect() {
-    if (this.state === "connected" || this.state === "connecting") {
-      return;
-    }
-    this.setState("connecting");
+  /**
+   * Make an authenticated API request
+   */
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      this.ws = new WebSocket(this.config.url);
-      this.ws.onopen = async () => {
-        try {
-          await this.authManager.authenticate(this.ws, this.config.apiKey, this.config.model);
-          this.setState("connected");
-        } catch (error) {
-          this.handleError(error instanceof Error ? error : new Error("Authentication failed"));
-        }
-      };
-      this.ws.onmessage = (event) => {
-        try {
-          const message = JSON.parse(event.data);
-          this.handleMessage(message);
-        } catch (error) {
-          this.handleError(error instanceof Error ? error : new Error("Failed to parse message"));
+      const response = await this.fetchFn(url, {
+        ...options,
+        signal: controller.signal,
+        headers: {
+          "Content-Type": "application/json",
+          [AUTH_CONFIG.apiKeyHeader]: this.apiKey,
+          ...options.headers
         }
-      };
-      this.ws.onerror = () => {
-        this.handleError(new Error("WebSocket error"));
-      };
-      this.ws.onclose = () => {
-        this.setState("disconnected");
-        this.connectionManager.handleDisconnect();
-      };
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorData = await response.json();
+        throw new LivenessApiError(
+          errorData.message,
+          errorData.error,
+          response.status,
+          errorData.required,
+          errorData.received
+        );
+      }
+      return await response.json();
     } catch (error) {
-      this.handleError(error instanceof Error ? error : new Error("Connection failed"));
+      clearTimeout(timeoutId);
+      if (error instanceof LivenessApiError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new LivenessApiError("Request timeout", "timeout", 408);
+      }
+      throw new LivenessApiError(
+        error instanceof Error ? error.message : "Network error",
+        "network_error",
+        0
+      );
     }
   }
-  disconnect() {
-    if (this.ws) {
-      this.ws.close();
-      this.ws = null;
+  /**
+   * Make a request with optional retry
+   */
+  async requestWithRetry(path, options = {}) {
+    if (this.enableRetry) {
+      return retryWithBackoff(() => this.request(path, options), {
+        maxAttempts: RETRY_CONFIG.maxAttempts,
+        initialDelay: RETRY_CONFIG.initialDelay,
+        maxDelay: RETRY_CONFIG.maxDelay,
+        backoffMultiplier: RETRY_CONFIG.backoffMultiplier
+      });
     }
-    this.setState("disconnected");
+    return this.request(path, options);
   }
-  sendFrame(frameData, frameNumber) {
-    if (this.state !== "connected" || !this.ws) {
-      throw new Error("WebSocket not connected");
-    }
-    const message = {
-      type: "frame",
-      frame_data: frameData,
-      frame_number: frameNumber,
-      timestamp: Date.now()
+  // ===========================================================================
+  // Health & Status
+  // ===========================================================================
+  /**
+   * Check API health status
+   */
+  async health() {
+    return this.request(API_PATHS.health);
+  }
+  /**
+   * Get queue statistics
+   */
+  async queueStats() {
+    return this.request(API_PATHS.queueStats);
+  }
+  // ===========================================================================
+  // Fast Check Endpoints
+  // ===========================================================================
+  /**
+   * Perform fast liveness check with server-side face detection
+   *
+   * @param frames - Captured frames to analyze
+   * @param options - Additional options
+   * @returns Liveness result
+   */
+  async fastCheck(frames, options = {}) {
+    const request = {
+      session_id: options.sessionId ?? generateSessionId(),
+      model: options.model ?? "10",
+      source: options.source ?? "live",
+      frames: toFrameData(frames)
+    };
+    const response = await this.requestWithRetry(API_PATHS.fastCheck, {
+      method: "POST",
+      body: JSON.stringify(request)
+    });
+    return toLivenessResult(response);
+  }
+  /**
+   * Perform fast liveness check with pre-cropped face images
+   *
+   * @param crops - Pre-cropped 224x224 face images
+   * @param options - Additional options
+   * @returns Liveness result
+   */
+  async fastCheckCrops(crops, options = {}) {
+    const request = {
+      session_id: options.sessionId ?? generateSessionId(),
+      model: options.model ?? "10",
+      source: options.source ?? "live",
+      crops
     };
-    this.ws.send(JSON.stringify(message));
+    const response = await this.requestWithRetry(API_PATHS.fastCheckCrops, {
+      method: "POST",
+      body: JSON.stringify(request)
+    });
+    return toLivenessResult(response);
   }
-  getState() {
-    return this.state;
+  // ===========================================================================
+  // Verify Endpoint (Spatial Features)
+  // ===========================================================================
+  /**
+   * Verify liveness using spatial feature-based detection
+   * Requires minimum 50 frames
+   *
+   * @param frames - Captured frames to analyze
+   * @param options - Additional options
+   * @returns Liveness result
+   */
+  async verify(frames, options = {}) {
+    const request = {
+      session_id: options.sessionId ?? generateSessionId(),
+      capture_start_ms: options.captureStartMs ?? 0,
+      frame_width: options.frameWidth ?? 640,
+      frame_height: options.frameHeight ?? 480,
+      fps: options.fps ?? 10,
+      frames: toFrameData(frames)
+    };
+    const response = await this.requestWithRetry(API_PATHS.verify, {
+      method: "POST",
+      body: JSON.stringify(request)
+    });
+    return toLivenessResult(response);
   }
-  setState(newState) {
-    if (this.state !== newState) {
-      this.state = newState;
-      this.config.onConnectionStateChange?.(newState);
-    }
+  // ===========================================================================
+  // Hybrid Check Endpoints
+  // ===========================================================================
+  /**
+   * Perform hybrid liveness check with CNN + physiological features
+   * Requires minimum 50 frames
+   *
+   * @param frames - Captured frames to analyze
+   * @param options - Additional options
+   * @returns Liveness result
+   */
+  async hybridCheck(frames, options = {}) {
+    const request = {
+      session_id: options.sessionId ?? generateSessionId(),
+      fps: options.fps ?? 30,
+      frames: toHybridFrameData(frames)
+    };
+    const response = await this.requestWithRetry(API_PATHS.hybridCheck, {
+      method: "POST",
+      body: JSON.stringify(request)
+    });
+    return toLivenessResult(response);
+  }
+  /**
+   * Perform 50-frame hybrid liveness check
+   * Achieves 93.8% balanced accuracy
+   *
+   * @param frames - Captured frames to analyze (minimum 50)
+   * @param options - Additional options
+   * @returns Liveness result
+   */
+  async hybrid50(frames, options = {}) {
+    const request = {
+      session_id: options.sessionId ?? generateSessionId(),
+      fps: options.fps ?? 30,
+      frames: toHybridFrameData(frames)
+    };
+    const response = await this.requestWithRetry(API_PATHS.hybrid50, {
+      method: "POST",
+      body: JSON.stringify(request)
+    });
+    return toLivenessResult(response);
   }
-  handleMessage(message) {
-    this.config.onMessage?.(message);
+  /**
+   * Perform 150-frame hybrid liveness check
+   * Achieves 96.2% balanced accuracy
+   *
+   * @param frames - Captured frames to analyze (minimum 150)
+   * @param options - Additional options
+   * @returns Liveness result
+   */
+  async hybrid150(frames, options = {}) {
+    const request = {
+      session_id: options.sessionId ?? generateSessionId(),
+      fps: options.fps ?? 30,
+      frames: toHybridFrameData(frames)
+    };
+    const response = await this.requestWithRetry(API_PATHS.hybrid150, {
+      method: "POST",
+      body: JSON.stringify(request)
+    });
+    return toLivenessResult(response);
   }
-  handleError(error) {
-    this.setState("error");
-    this.config.onError?.(error);
+  // ===========================================================================
+  // Job Polling Endpoints
+  // ===========================================================================
+  /**
+   * Get job status and result
+   *
+   * @param jobId - Job identifier
+   * @returns Job status response
+   */
+  async getJobResult(jobId) {
+    return this.request(`${API_PATHS.jobResult}/${jobId}`);
+  }
+  /**
+   * Long-poll for job result
+   * Waits up to timeout seconds for the job to complete
+   *
+   * @param jobId - Job identifier
+   * @param timeout - Max seconds to wait (default 30, max 120)
+   * @returns Job status response
+   */
+  async waitForJobResult(jobId, timeout = 30) {
+    return this.request(
+      `${API_PATHS.jobResult}/${jobId}/wait?timeout=${timeout}`
+    );
   }
 };
 
@@ -245,54 +383,103 @@ var WebSocketClient = class {
 var FrameBuffer = class {
   constructor(maxSize = FRAME_BUFFER_CONFIG.maxSize, maxMemory = FRAME_BUFFER_CONFIG.maxMemory) {
     this.buffer = /* @__PURE__ */ new Map();
-    this.lastAcknowledged = 0;
     this.currentMemoryUsage = 0;
     this.maxSize = maxSize;
     this.maxMemory = maxMemory;
   }
+  /**
+   * Add a frame to the buffer
+   */
   add(frame) {
     if (this.currentMemoryUsage + frame.size > this.maxMemory) {
       this.flushOldest();
     }
-    this.buffer.set(frame.number, frame);
+    this.buffer.set(frame.index, frame);
     this.currentMemoryUsage += frame.size;
     if (this.buffer.size > this.maxSize) {
       const oldest = Math.min(...this.buffer.keys());
       this.remove(oldest);
     }
   }
-  acknowledge(frameNumber) {
-    this.lastAcknowledged = Math.max(this.lastAcknowledged, frameNumber);
-    for (const [num] of this.buffer) {
-      if (num <= frameNumber) {
-        this.remove(num);
-      }
-    }
+  /**
+   * Get a frame by index
+   */
+  get(index) {
+    return this.buffer.get(index);
   }
-  getUnacknowledged() {
-    return Array.from(this.buffer.values()).filter((f) => f.number > this.lastAcknowledged).sort((a, b) => a.number - b.number);
+  /**
+   * Get all frames sorted by index
+   */
+  getAll() {
+    return Array.from(this.buffer.values()).sort((a, b) => a.index - b.index);
   }
-  getLastAcknowledged() {
-    return this.lastAcknowledged;
+  /**
+   * Get frames within a range
+   */
+  getRange(startIndex, endIndex) {
+    return this.getAll().filter((f) => f.index >= startIndex && f.index <= endIndex);
+  }
+  /**
+   * Get the latest N frames
+   */
+  getLatest(count) {
+    const all = this.getAll();
+    return all.slice(-count);
+  }
+  /**
+   * Remove frames up to and including the given index
+   */
+  removeUpTo(index) {
+    for (const [frameIndex] of this.buffer) {
+      if (frameIndex <= index) {
+        this.remove(frameIndex);
+      }
+    }
   }
+  /**
+   * Get current buffer size (number of frames)
+   */
   size() {
     return this.buffer.size;
   }
+  /**
+   * Get current memory usage in bytes
+   */
   getMemoryUsage() {
     return this.currentMemoryUsage;
   }
+  /**
+   * Check if buffer is empty
+   */
+  isEmpty() {
+    return this.buffer.size === 0;
+  }
+  /**
+   * Check if buffer is at capacity
+   */
+  isFull() {
+    return this.buffer.size >= this.maxSize;
+  }
+  /**
+   * Clear all frames from the buffer
+   */
   clear() {
     this.buffer.clear();
     this.currentMemoryUsage = 0;
-    this.lastAcknowledged = 0;
   }
-  remove(frameNumber) {
-    const frame = this.buffer.get(frameNumber);
+  /**
+   * Remove a specific frame by index
+   */
+  remove(index) {
+    const frame = this.buffer.get(index);
     if (frame) {
       this.currentMemoryUsage -= frame.size;
-      this.buffer.delete(frameNumber);
+      this.buffer.delete(index);
     }
   }
+  /**
+   * Remove the oldest frame
+   */
   flushOldest() {
     if (this.buffer.size === 0) {
       return;
@@ -330,6 +517,273 @@ var FrameQueue = class {
   }
 };
 
+// src/types/models.ts
+var MODEL_CONFIGS = {
+  "10": {
+    type: "10",
+    minFrames: 10,
+    recommendedFrames: 10,
+    description: "Fast model - 10 frames, quick verification"
+  },
+  "50": {
+    type: "50",
+    minFrames: 50,
+    recommendedFrames: 50,
+    description: "Balanced model - 50 frames, good accuracy"
+  },
+  "250": {
+    type: "250",
+    minFrames: 250,
+    recommendedFrames: 250,
+    description: "High-accuracy model - 250 frames, best accuracy"
+  }
+};
+var HYBRID_MODEL_CONFIGS = {
+  "hybrid-50": {
+    type: "hybrid-50",
+    minFrames: 50,
+    recommendedFps: 30,
+    captureDurationSeconds: 1.7,
+    description: "Hybrid 50-frame model - 93.8% balanced accuracy"
+  },
+  "hybrid-150": {
+    type: "hybrid-150",
+    minFrames: 150,
+    recommendedFps: 30,
+    captureDurationSeconds: 5,
+    description: "Hybrid 150-frame model - 96.2% balanced accuracy"
+  }
+};
+function getMinFramesForModel(model) {
+  return MODEL_CONFIGS[model].minFrames;
+}
+function hasEnoughFrames(model, frameCount) {
+  return frameCount >= MODEL_CONFIGS[model].minFrames;
+}
+
+// src/constants/feedback.ts
+var ALIGNMENT_THRESHOLD_CAPTURE = 0.6;
+var ALIGNMENT_THRESHOLD_POOR = 0.5;
+var ALIGNMENT_THRESHOLD_GOOD = 0.5;
+var ALIGNMENT_THRESHOLD_PERFECT = 0.85;
+var OVAL_GUIDE_COLORS = {
+  no_face: "#ef4444",
+  // Red - no face detected
+  poor: "#f97316",
+  // Orange - face detected but alignment < 50%
+  good: "#eab308",
+  // Yellow - alignment 50-85%
+  perfect: "#22c55e"
+  // Green - alignment >= 85%, ready to capture
+};
+var OVAL_GUIDE_STYLES = {
+  no_face: { color: "#ef4444", dashed: true, pulse: false },
+  poor: { color: "#f97316", dashed: false, pulse: false },
+  good: { color: "#eab308", dashed: false, pulse: false },
+  perfect: { color: "#22c55e", dashed: false, pulse: true }
+};
+function getOvalGuideState(hasFace, alignment) {
+  if (!hasFace) return "no_face";
+  if (alignment < ALIGNMENT_THRESHOLD_POOR) return "poor";
+  if (alignment < ALIGNMENT_THRESHOLD_PERFECT) return "good";
+  return "perfect";
+}
+var DEFAULT_STATUS_MESSAGES = {
+  idle: "Ready to start",
+  capturing: "Hold still...",
+  uploading: "Processing...",
+  processing: "Analyzing...",
+  complete: "Complete!",
+  error: "Error occurred"
+};
+var FEEDBACK_MESSAGES = {
+  // Initial / No face (Red state)
+  position_face: "Position your face in the oval",
+  no_face: "No face detected - move into frame",
+  multiple_faces: "Multiple people detected - please verify alone",
+  // Poor alignment (Orange state) - alignment < 50%
+  move_closer_to_center: "Move closer to center",
+  center_face: "Center your face",
+  // Good alignment (Yellow state) - alignment 50-85%
+  almost_there: "Almost there...",
+  keep_steady: "Keep steady...",
+  // Perfect alignment (Green state) - alignment >= 85%
+  perfect: "Perfect! Hold still",
+  scanning: "Scanning...",
+  // Distance issues
+  move_closer: "Move closer - face too far",
+  move_back: "Move back - face too close",
+  too_close: "Move back - face too close",
+  too_far: "Move closer - face too far",
+  // Visibility issues
+  face_not_visible: "Center your face - edges cut off",
+  partial_face: "Center your face - edges cut off",
+  // Quality issues
+  hold_still: "Hold still - image blurry",
+  blurry: "Hold still - image blurry",
+  // Lighting issues
+  poor_lighting: "Improve lighting",
+  too_dark: "Low lighting - move to a brighter area",
+  backlit: "Backlit - try facing the light source",
+  // Hand occlusion
+  hand_detected: "Remove hand from face",
+  // Progress messages
+  capturing: "Capturing...",
+  almost_done: "Almost done...",
+  verification_complete: "Verification complete",
+  // Alignment-based messages (used by getAlignmentFeedback)
+  align_face: "Align your face"
+};
+var DEFAULT_LOCALE = {
+  status: DEFAULT_STATUS_MESSAGES,
+  feedback: FEEDBACK_MESSAGES
+};
+var ES_LOCALE = {
+  status: {
+    idle: "Listo para comenzar",
+    capturing: "Mantente quieto...",
+    uploading: "Procesando...",
+    processing: "Analizando...",
+    complete: "\xA1Completado!",
+    error: "Ocurri\xF3 un error"
+  },
+  feedback: {
+    // Initial / No face (Red state)
+    position_face: "Posiciona tu rostro en el \xF3valo",
+    no_face: "No se detecta rostro - mu\xE9vete al marco",
+    multiple_faces: "Varias personas detectadas - verifica solo",
+    // Poor alignment (Orange state)
+    move_closer_to_center: "Mu\xE9vete al centro",
+    center_face: "Centra tu rostro",
+    // Good alignment (Yellow state)
+    almost_there: "Casi listo...",
+    keep_steady: "Mantente quieto...",
+    // Perfect alignment (Green state)
+    perfect: "\xA1Perfecto! No te muevas",
+    scanning: "Escaneando...",
+    // Distance issues
+    move_closer: "Ac\xE9rcate - rostro muy lejos",
+    move_back: "Al\xE9jate - rostro muy cerca",
+    too_close: "Al\xE9jate - rostro muy cerca",
+    too_far: "Ac\xE9rcate - rostro muy lejos",
+    // Visibility issues
+    face_not_visible: "Centra tu rostro - bordes cortados",
+    partial_face: "Centra tu rostro - bordes cortados",
+    // Quality issues
+    hold_still: "Mantente quieto - imagen borrosa",
+    blurry: "Mantente quieto - imagen borrosa",
+    // Lighting issues
+    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",
+    // Hand occlusion
+    hand_detected: "Retira la mano del rostro",
+    // Progress messages
+    capturing: "Capturando...",
+    almost_done: "Casi listo...",
+    verification_complete: "Verificaci\xF3n completada",
+    // Alignment-based
+    align_face: "Alinea tu rostro"
+  }
+};
+function getFeedbackMessage(key, locale = DEFAULT_LOCALE) {
+  return locale.feedback[key] ?? FEEDBACK_MESSAGES[key];
+}
+function getStatusMessage(key, locale = DEFAULT_LOCALE) {
+  return locale.status[key] ?? DEFAULT_STATUS_MESSAGES[key];
+}
+function getCaptureQualityFeedback(state) {
+  const {
+    hasFace,
+    alignment,
+    isCapturing,
+    tooClose,
+    tooFar,
+    isBlurry,
+    isPartialFace,
+    framesCaptured,
+    targetFrames
+  } = state;
+  if (!hasFace) {
+    return FEEDBACK_MESSAGES.no_face;
+  }
+  if (tooClose) {
+    return FEEDBACK_MESSAGES.too_close;
+  }
+  if (tooFar) {
+    return FEEDBACK_MESSAGES.too_far;
+  }
+  if (isPartialFace) {
+    return FEEDBACK_MESSAGES.partial_face;
+  }
+  if (isBlurry) {
+    return FEEDBACK_MESSAGES.blurry;
+  }
+  if (alignment < ALIGNMENT_THRESHOLD_POOR) {
+    return FEEDBACK_MESSAGES.move_closer_to_center;
+  }
+  if (alignment < ALIGNMENT_THRESHOLD_PERFECT) {
+    return FEEDBACK_MESSAGES.almost_there;
+  }
+  if (isCapturing && framesCaptured > 0) {
+    if (framesCaptured >= targetFrames - 2) {
+      return FEEDBACK_MESSAGES.almost_done;
+    }
+    return FEEDBACK_MESSAGES.scanning;
+  }
+  return FEEDBACK_MESSAGES.perfect;
+}
+function canCaptureFrame(state) {
+  const { hasFace, alignment, tooClose, tooFar, isBlurry, isPartialFace } = state;
+  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace;
+}
+
+// src/utils/validators.ts
+function validateApiKey(apiKey) {
+  return typeof apiKey === "string" && apiKey.length > 0;
+}
+function validateFrameData(data) {
+  if (!data || typeof data !== "string") {
+    return false;
+  }
+  if (data.startsWith("data:")) {
+    const base64Part = data.split(",")[1];
+    return base64Part !== void 0 && base64Part.length > 0;
+  }
+  const base64Pattern = /^[A-Za-z0-9+/=]+$/;
+  return base64Pattern.test(data) && data.length > 0;
+}
+function validateFrameIndex(index) {
+  return Number.isInteger(index) && index >= 0;
+}
+function validateTimestamp(timestamp) {
+  return typeof timestamp === "number" && timestamp >= 0 && isFinite(timestamp);
+}
+function validateFrameCount(model, frameCount) {
+  const config = MODEL_CONFIGS[model];
+  const required = config.minFrames;
+  return {
+    valid: frameCount >= required,
+    required,
+    received: frameCount
+  };
+}
+function validateUUID(uuid) {
+  if (!uuid || typeof uuid !== "string") {
+    return false;
+  }
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidPattern.test(uuid);
+}
+function validateUrl(url) {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/utils/encoders.ts
 function encodeBase64(buffer) {
   if (buffer instanceof ArrayBuffer) {
@@ -346,22 +800,384 @@ function decodeBase64(base64) {
   }
   return bytes;
 }
+
+// src/utils/frameAnalysis.ts
+var DEFAULT_BLUR_THRESHOLD = 100;
+var BLUR_THRESHOLD_MOBILE = 150;
+var BACKLIT_RATIO_THRESHOLD = 0.6;
+var LOW_LIGHT_THRESHOLD = 50;
+var MIN_FACE_TOP_MARGIN = 0.1;
+var MIN_FACE_BOTTOM_MARGIN = 0.08;
+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 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;
+function analyzeBlur(grayscalePixels, width, height, threshold = DEFAULT_BLUR_THRESHOLD) {
+  const laplacian = [];
+  for (let y = 1; y < height - 1; y++) {
+    for (let x = 1; x < width - 1; x++) {
+      const idx = y * width + x;
+      const top = grayscalePixels[idx - width] ?? 0;
+      const left = grayscalePixels[idx - 1] ?? 0;
+      const center = grayscalePixels[idx] ?? 0;
+      const right = grayscalePixels[idx + 1] ?? 0;
+      const bottom = grayscalePixels[idx + width] ?? 0;
+      const value = top + left + center * -4 + right + bottom;
+      laplacian.push(value);
+    }
+  }
+  const n = laplacian.length;
+  if (n === 0) {
+    return { variance: 0, isBlurry: true, threshold };
+  }
+  const mean = laplacian.reduce((a, b) => a + b, 0) / n;
+  const variance = laplacian.reduce((sum, val) => sum + Math.pow(val - mean, 2), 0) / n;
+  return {
+    variance,
+    isBlurry: variance < threshold,
+    threshold
+  };
+}
+function rgbaToGrayscale(rgbaPixels) {
+  const grayscale = [];
+  for (let i = 0; i < rgbaPixels.length; i += 4) {
+    const r = rgbaPixels[i] ?? 0;
+    const g = rgbaPixels[i + 1] ?? 0;
+    const b = rgbaPixels[i + 2] ?? 0;
+    grayscale.push(0.299 * r + 0.587 * g + 0.114 * b);
+  }
+  return grayscale;
+}
+function calculateBrightness(rgbaPixels) {
+  let totalLuminance = 0;
+  const pixelCount = rgbaPixels.length / 4;
+  for (let i = 0; i < rgbaPixels.length; i += 4) {
+    const r = rgbaPixels[i] ?? 0;
+    const g = rgbaPixels[i + 1] ?? 0;
+    const b = rgbaPixels[i + 2] ?? 0;
+    totalLuminance += 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  }
+  return pixelCount > 0 ? totalLuminance / pixelCount : 0;
+}
+function analyzeLighting(faceBrightness, backgroundBrightness) {
+  const ratio = backgroundBrightness > 0 ? faceBrightness / backgroundBrightness : 1;
+  let status = "good";
+  let warning;
+  if (faceBrightness < LOW_LIGHT_THRESHOLD && backgroundBrightness < LOW_LIGHT_THRESHOLD) {
+    status = "low_light";
+    warning = "Low lighting - move to a brighter area";
+  } else if (ratio < BACKLIT_RATIO_THRESHOLD) {
+    status = "backlit";
+    warning = "Backlit - try facing the light source";
+  }
+  return {
+    faceBrightness,
+    backgroundBrightness,
+    ratio,
+    status,
+    warning
+  };
+}
+function isFaceFullyVisible(boundingBox, frameWidth, frameHeight) {
+  const faceTop = boundingBox.originY / frameHeight;
+  const faceBottom = (boundingBox.originY + boundingBox.height) / frameHeight;
+  const faceLeft = boundingBox.originX / frameWidth;
+  const faceRight = (boundingBox.originX + boundingBox.width) / frameWidth;
+  if (faceTop < MIN_FACE_TOP_MARGIN) {
+    return { visible: false, reason: "Face too close to top edge" };
+  }
+  if (faceBottom > 1 - MIN_FACE_BOTTOM_MARGIN) {
+    return { visible: false, reason: "Face too close to bottom edge" };
+  }
+  if (faceLeft < MIN_FACE_SIDE_MARGIN) {
+    return { visible: false, reason: "Face too close to left edge" };
+  }
+  if (faceRight > 1 - MIN_FACE_SIDE_MARGIN) {
+    return { visible: false, reason: "Face too close to right edge" };
+  }
+  return { visible: true };
+}
+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)
+};
+function isFaceInOval(faceBox, frameWidth, frameHeight, oval = DEFAULT_OVAL_REGION, tolerance = 0.3) {
+  const faceCenterX = (faceBox.originX + faceBox.width / 2) / frameWidth;
+  const faceCenterY = (faceBox.originY + faceBox.height / 2) / frameHeight;
+  const faceWidth = faceBox.width / frameWidth;
+  const faceHeight = faceBox.height / frameHeight;
+  const ovalRadiusX = oval.width / 2;
+  const ovalRadiusY = oval.height / 2;
+  const dx = faceCenterX - oval.centerX;
+  const dy = faceCenterY - oval.centerY;
+  const normalizedDist = dx * dx / (ovalRadiusX * ovalRadiusX) + dy * dy / (ovalRadiusY * ovalRadiusY);
+  const centerInOval = normalizedDist <= 1;
+  const expectedFaceWidth = oval.width * 0.7;
+  const expectedFaceHeight = oval.height * 0.7;
+  const widthRatio = faceWidth / expectedFaceWidth;
+  const heightRatio = faceHeight / expectedFaceHeight;
+  const tooSmall = widthRatio < 1 - tolerance || heightRatio < 1 - tolerance;
+  const tooBig = widthRatio > 1 + tolerance || heightRatio > 1 + tolerance;
+  const sizeMatch = !tooSmall && !tooBig;
+  let feedback;
+  if (!centerInOval) {
+    if (dy < -0.1) {
+      feedback = "Move face down";
+    } else if (dy > 0.1) {
+      feedback = "Move face up";
+    } else if (dx < -0.1) {
+      feedback = "Move face right";
+    } else if (dx > 0.1) {
+      feedback = "Move face left";
+    } else {
+      feedback = "Center your face in the oval";
+    }
+  } else if (tooSmall) {
+    feedback = "Move closer";
+  } else if (tooBig) {
+    feedback = "Move back";
+  }
+  return {
+    isInside: centerInOval && sizeMatch,
+    centerInOval,
+    sizeMatch,
+    feedback
+  };
+}
+function calculateFaceAlignment(boundingBox, frameWidth, frameHeight) {
+  const faceCenterX = boundingBox.originX + boundingBox.width / 2;
+  const faceCenterY = boundingBox.originY + boundingBox.height / 2;
+  const targetX = frameWidth / 2;
+  const targetY = frameHeight / 2;
+  const distX = Math.abs(faceCenterX - targetX) / (frameWidth / 2);
+  const distY = Math.abs(faceCenterY - targetY) / (frameHeight / 2);
+  const faceRatio = Math.max(boundingBox.width, boundingBox.height) / Math.min(frameWidth, frameHeight);
+  const score = Math.max(0, 1 - Math.max(distX, distY));
+  return {
+    score,
+    tooClose: faceRatio > MAX_FACE_RATIO,
+    tooFar: faceRatio < MIN_FACE_RATIO
+  };
+}
+function calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight) {
+  const faceSize = Math.max(faceBox.width, faceBox.height);
+  const idealCropSize = faceSize * IDEAL_CROP_MULTIPLIER;
+  const maxCropSize = Math.min(frameWidth, frameHeight);
+  if (idealCropSize <= maxCropSize) {
+    return IDEAL_CROP_MULTIPLIER;
+  }
+  const adaptiveMultiplier = maxCropSize / faceSize;
+  return Math.max(MIN_CROP_MULTIPLIER, Math.min(MAX_CROP_MULTIPLIER, adaptiveMultiplier));
+}
+function isFaceCropFullyInFrame(faceBox, frameWidth, frameHeight) {
+  const marginMultiplier = calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight);
+  const marginX = faceBox.width * (marginMultiplier - 1) / 2;
+  const marginY = faceBox.height * (marginMultiplier - 1) / 2;
+  const faceLeft = faceBox.originX - marginX;
+  const faceTop = faceBox.originY - marginY;
+  const faceRight = faceBox.originX + faceBox.width + marginX;
+  const faceBottom = faceBox.originY + faceBox.height + marginY;
+  return faceLeft >= 0 && faceTop >= 0 && faceRight <= frameWidth && faceBottom <= frameHeight;
+}
+function calculateFaceCropRegion(faceBox, frameWidth, frameHeight) {
+  const cropMultiplier = calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight);
+  const expandedWidth = faceBox.width * cropMultiplier;
+  const expandedHeight = faceBox.height * cropMultiplier;
+  const cropSize = Math.max(expandedWidth, expandedHeight);
+  const centerX = faceBox.originX + faceBox.width / 2;
+  const verticalShift = faceBox.height * FACE_CENTER_VERTICAL_OFFSET;
+  const centerY = faceBox.originY + faceBox.height / 2 + verticalShift;
+  let cropX = centerX - cropSize / 2;
+  let cropY = centerY - cropSize / 2;
+  cropX = Math.max(0, Math.min(frameWidth - cropSize, cropX));
+  cropY = Math.max(0, Math.min(frameHeight - cropSize, cropY));
+  const finalSize = Math.min(cropSize, frameWidth - cropX, frameHeight - cropY);
+  return { x: cropX, y: cropY, size: finalSize };
+}
+function checkFrameQuality(options) {
+  const {
+    faceBox,
+    frameWidth,
+    frameHeight,
+    blurAnalysis,
+    lightingAnalysis,
+    minAlignment = MIN_CAPTURE_ALIGNMENT
+  } = options;
+  const result = { passed: true };
+  if (!faceBox) {
+    result.passed = false;
+    result.rejectionReason = "no_face";
+    return result;
+  }
+  result.visibility = isFaceFullyVisible(faceBox, frameWidth, frameHeight);
+  if (!result.visibility.visible) {
+    result.passed = false;
+    result.rejectionReason = "partial_face";
+    return result;
+  }
+  result.alignment = calculateFaceAlignment(faceBox, frameWidth, frameHeight);
+  if (result.alignment.tooClose) {
+    result.passed = false;
+    result.rejectionReason = "too_close";
+    return result;
+  }
+  if (result.alignment.tooFar) {
+    result.passed = false;
+    result.rejectionReason = "too_far";
+    return result;
+  }
+  if (result.alignment.score < minAlignment) {
+    result.passed = false;
+    result.rejectionReason = "misaligned";
+    return result;
+  }
+  if (blurAnalysis) {
+    result.blur = blurAnalysis;
+    if (blurAnalysis.isBlurry) {
+      result.passed = false;
+      result.rejectionReason = "blur";
+      return result;
+    }
+  }
+  if (lightingAnalysis) {
+    result.lighting = lightingAnalysis;
+    if (lightingAnalysis.status === "backlit") {
+      result.passed = false;
+      result.rejectionReason = "backlit";
+      return result;
+    }
+    if (lightingAnalysis.status === "low_light") {
+      result.passed = false;
+      result.rejectionReason = "low_light";
+      return result;
+    }
+  }
+  return result;
+}
+var BaseFrameCollector = class {
+  constructor(maxFrames = 10) {
+    this.frames = [];
+    this.maxFrames = maxFrames;
+    this.startTime = Date.now();
+  }
+  setMaxFrames(max) {
+    this.maxFrames = max;
+  }
+  addFrame(frame) {
+    if (!this.isComplete()) {
+      this.frames.push(frame);
+    }
+  }
+  getFrames() {
+    return [...this.frames];
+  }
+  getCount() {
+    return this.frames.length;
+  }
+  isComplete() {
+    return this.frames.length >= this.maxFrames;
+  }
+  reset() {
+    this.frames = [];
+    this.startTime = Date.now();
+  }
+  getStartTime() {
+    return this.startTime;
+  }
+  getNextIndex() {
+    return this.frames.length;
+  }
+};
 export {
+  ALIGNMENT_THRESHOLD_CAPTURE,
+  ALIGNMENT_THRESHOLD_GOOD,
+  ALIGNMENT_THRESHOLD_PERFECT,
+  ALIGNMENT_THRESHOLD_POOR,
   API_ENDPOINTS,
+  API_PATHS,
   AUTH_CONFIG,
-  AuthManager,
-  ConnectionManager,
+  BACKLIT_RATIO_THRESHOLD,
+  BLUR_THRESHOLD_MOBILE,
+  BaseFrameCollector,
+  DEFAULT_BLUR_THRESHOLD,
   DEFAULT_ENDPOINT,
+  DEFAULT_LIVENESS_CONFIG,
+  DEFAULT_LOCALE,
+  DEFAULT_OVAL_REGION,
+  DEFAULT_STATUS_MESSAGES,
+  ES_LOCALE,
+  FACE_CENTER_VERTICAL_OFFSET,
+  FACE_CROP_OUTPUT_SIZE,
+  FEEDBACK_MESSAGES,
   FRAME_BUFFER_CONFIG,
   FRAME_CONFIG,
   FrameBuffer,
   FrameQueue,
-  RECONNECTION_CONFIG,
-  WebSocketClient,
+  GOOD_ALIGNMENT,
+  HIGH_ALIGNMENT,
+  HYBRID_MODEL_CONFIGS,
+  IDEAL_CROP_MULTIPLIER,
+  LOW_LIGHT_THRESHOLD,
+  LivenessApiError,
+  LivenessClient,
+  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,
+  OVAL_GUIDE_COLORS,
+  OVAL_GUIDE_STYLES,
+  RETRY_CONFIG,
+  TARGET_FACE_PERCENTAGE_IN_CROP,
+  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,
   validateApiKey,
+  validateFrameCount,
   validateFrameData,
-  validateFrameNumber
+  validateFrameIndex,
+  validateTimestamp,
+  validateUUID,
+  validateUrl
 };