Types & Constants

The @moveris/shared package exports all TypeScript types, constants, and utility functions used across the SDK. This page covers the most important exports.

In plain terms

These are the data shapes your code uses when talking to the API: frame format, response structure, verdict values, etc. Use them for type safety and autocomplete in TypeScript.

Optional parameters

Properties followed by ? (for example, model?) are optional. You can omit them when creating objects or when the API uses defaults. For instance, model and frame_count in FastCheckRequest can be left out.

Import

import type {
  FrameData,
  CropData,
  CapturedFrame,
  LivenessResult,
  FastCheckRequest,
  FastCheckResponse,
  // ... etc
} from '@moveris/shared';

Request & Response Types

FrameData

A single video frame for the API.

interface FrameData {
  index: number;          // Frame index (0-based)
  timestamp_ms: number;   // Timestamp in milliseconds
  pixels: string;         // Base64-encoded PNG image data
}

CropData

A pre-cropped 224x224 face image.

interface CropData {
  index: number;          // Frame index (0-based)
  pixels: string;         // Base64-encoded 224x224 PNG crop
}

CapturedFrame

Internal representation of a captured frame (used by hooks before converting to FrameData). The SDK uses timestampMs (camelCase); the API payload uses timestamp_ms (snake_case). The toFrameData() helper converts automatically.

interface CapturedFrame {
  index: number;
  timestampMs: number;   // API uses timestamp_ms
  pixels: string;
  landmarks?: { x: number; y: number; z: number }[] | null; // live-check only
}

FastCheckRequest

interface FastCheckRequest {
  session_id: string;
  source: FrameSource;
  model?: FastCheckModel;
  frame_count?: number;   // Optional. For v2 resolution with X-Model-Version header (30, 60, or 120).
  frames: FrameData[];
  warnings?: string[];    // Optional. Capture warnings from frontend (API echoes in response)
  fps?: number;           // Measured from frame timestamps; omitted when it cannot be measured
  fps_source?: 'measured' | 'unmeasured';
}

FastCheckResponse

confidence vs real_score

The confidence field is reserved for future use and is functionally identical to real_score. Use real_score for decision-making.

interface FastCheckResponse {
  session_id: string;
  verdict: 'live' | 'fake' | 'inconclusive' | null;
  confidence: number | null;     // Reserved for future use; use real_score for decision-making
  score: number | null;
  real_score: number | null;     // Use this for decision-making
  processing_ms: number;
  frames_processed: number;
  model: string | null;
  warning?: string | null;
  warnings?: string[] | null;
}

FastCheckStreamRequest

interface FastCheckStreamRequest {
  session_id: string;
  source: FrameSource;
  model?: FastCheckModel;
  frame_count?: number;   // Optional. For v2 resolution with X-Model-Version header. Must be 30, 60, or 120 and consistent across all requests.
  frame: FrameData;       // Single frame per request
  warnings?: string[];    // Optional. Per-frame capture warnings (API 1.11+)
}

FastCheckStreamResponse

interface FastCheckStreamResponse {
  status: 'buffering' | 'complete';
  session_id: string;
  frames_received: number;
  frames_required: number;
  ttl_seconds: number;
  warnings?: string[];    // Per-frame (buffering) or aggregated (complete)
  // Present when status is 'complete':
  verdict?: 'live' | 'fake' | 'inconclusive' | null;
  confidence?: number;     // Reserved for future use; use real_score for decision-making
  real_score?: number;     // Use this for decision-making
  score?: number;
  model?: string;
  processing_ms?: number;
  frames_processed?: number;
  available?: boolean;
  warning?: string;
  error?: string;
}

LivenessResult

Unified result type used by SDK hooks. Use realScore (or real_score from the API) for decision-making; confidence is reserved for future use.

interface LivenessResult {
  verdict: 'live' | 'fake' | 'inconclusive';
  confidence: number;     // Reserved for future use; use realScore for decision-making
  score: number;
  realScore: number | null; // Use this for decision-making
  sessionId: string;
  processingMs: number;
  framesProcessed: number;
  warnings?: string[];
  clientTime?: number;    // ms from start() to verdict
  deprecation?: DeprecationInfo;
}

HybridCheckRequest

interface HybridCheckRequest {
  session_id: string;
  source: FrameSource;
  frames: HybridFrameData[];
  fps?: number;
  model?: string;
}

HybridCheckResponse

interface HybridCheckResponse {
  session_id: string;
  verdict: 'live' | 'fake';
  confidence: number;     // Reserved for future use; use real_score for decision-making
  score: number;
  real_score: number;     // Use this for decision-making
  visual_score?: number;
  physio_extracted?: boolean;
  processing_ms: number;
  frames_processed: number;
  model: string;
}

Other Response Types

interface HealthResponse {
  status: string;
  version: string;
  models_available: string[];
}

interface JobStatusResponse {
  job_id: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  result?: FastCheckResponse;
}

interface QueueStatsResponse {
  pending: number;
  processing: number;
  completed: number;
}

interface ErrorResponse {
  error: string;
  message: string;
  required?: number;
  received?: number;
  required_scope?: string;   // Present when error is insufficient_scope (API 1.10+)
}

Common error codes

invalid_key (401), insufficient_credits or account_suspended (402), insufficient_scope (403), insufficient_frames (400).

Enums & Literals

FrameSource

type FrameSource = 'live' | 'media';

• "live" -- Captured from a live camera feed
• "media" -- From a recorded video or uploaded file

FastCheckModel

type FastCheckModel = 'mixed-30-v3_1_1' | 'mixed-60-v3_1_1' | 'mixed-120-v3_1_1' | (string & object);

Frame count must match the model's min_frames (30, 60, or 120). Send exactly that many. Default is DEFAULT_MODEL (mixed-30-v3_1_1). Use getModels() or useModels to fetch the live registry.

ModelVersion

type ModelVersion = 'latest' | 'v3_1_1' | (string & object);

Sent as X-Model-Version. latest and v3_1_1 both resolve to Mixed V3.1.1.

Constants

API Endpoints

import { API_ENDPOINTS } from '@moveris/shared';

API_ENDPOINTS.production  // 'https://api.moveris.com'
API_ENDPOINTS.staging     // 'https://moveris-api-v2-staging.fly.dev'
API_ENDPOINTS.development // 'http://localhost:8000'

API Paths

import { API_PATHS } from '@moveris/shared';

API_PATHS.health          // '/health'
API_PATHS.fastCheck       // '/api/v1/fast-check'
API_PATHS.fastCheckCrops  // '/api/v1/fast-check-crops'
API_PATHS.fastCheckStream // '/api/v1/fast-check-stream'
API_PATHS.liveCheck       // '/api/v1/live-check'
API_PATHS.v2Upload        // '/api/v2/upload'
API_PATHS.v2FastCheck     // '/api/v2/fast-check'
API_PATHS.v2LiveCheck     // '/api/v2/live-check'
API_PATHS.verify          // '/api/v1/verify'
API_PATHS.hybridCheck     // '/api/v1/hybrid-check'
API_PATHS.hybrid50        // '/api/v1/hybrid-50'
API_PATHS.hybrid150       // '/api/v1/hybrid-150'

Frame Configuration

import { FRAME_CONFIG, DEFAULT_MODEL, VALID_FRAME_COUNTS } from '@moveris/shared';

DEFAULT_MODEL               // 'mixed-30-v3_1_1'
VALID_FRAME_COUNTS          // [30, 60, 120]
FRAME_CONFIG.defaultModel   // 'mixed-30-v3_1_1'
FRAME_CONFIG.targetFPS      // 30

Retry Configuration

import { RETRY_CONFIG } from '@moveris/shared';

RETRY_CONFIG.maxAttempts    // 3
RETRY_CONFIG.initialDelay   // 1000 (ms)
RETRY_CONFIG.maxDelay       // 10000 (ms)
RETRY_CONFIG.backoffMultiplier // 2

Frame Buffer Configuration

import { FRAME_BUFFER_CONFIG } from '@moveris/shared';

FRAME_BUFFER_CONFIG.maxSize    // 10
FRAME_BUFFER_CONFIG.maxMemory  // 4 * 1024 * 1024

Feedback System

The SDK includes a built-in feedback message system for guiding users during face capture.

Feedback Messages

import {
  FEEDBACK_MESSAGES,
  DEFAULT_STATUS_MESSAGES,
  getFeedbackMessage,
  getStatusMessage,
} from '@moveris/shared';

getFeedbackMessage(key, locale?)

Returns a localized feedback message for the user:

getFeedbackMessage('no_face');
// "No face detected - move into frame"

getFeedbackMessage('too_far', 'es');
// Spanish translation

Common feedback keys:

Key	Description
no_face	No face found in frame
too_far	Face is too far from camera
too_close	Face is too close to camera
center_face	Face is not within the circle guide
poor_lighting	Lighting conditions are insufficient
blurry	Frame is too blurry
hold_still	User needs to hold still
perfect	Alignment is good; capture is running

Locales

import { DEFAULT_LOCALE, ES_LOCALE } from '@moveris/shared';

• DEFAULT_LOCALE -- English messages
• ES_LOCALE -- Spanish messages

Oval Guide Helpers

For rendering face guide overlays:

import {
  OVAL_GUIDE_COLORS,
  getOvalGuideState,
  getCaptureQualityFeedback,
  canCaptureFrame,
} from '@moveris/shared';

• getOvalGuideState(hasFace, alignment) -- Returns 'no_face' | 'poor' | 'good' | 'perfect'. Pass this to LivenessOverlay as ovalState.
• getCaptureQualityFeedback(state) -- Returns quality feedback for the current frame
• canCaptureFrame(state) -- Returns true if the current frame meets quality thresholds

Detection Types

Types used by the face detection system:

interface DetectionResult {
  faceDetected: boolean;
  boundingBox?: BoundingBox;
  landmarks?: FaceLandmarks;
  headPose?: HeadPose;
  quality?: FrameQuality;
}

interface DetectionSummary {
  totalFrames: number;
  facesDetected: number;
  averageQuality: number;
}

interface HeadPose {
  pitch: number;    // Up/down rotation
  yaw: number;      // Left/right rotation
  roll: number;     // Tilt
}

interface GazeThresholds {
  maxPitch: number;
  maxYaw: number;
  maxRoll: number;
}

Utility Functions

Validators

import { validateFrameData, validateCropData } from '@moveris/shared';

Encoders

import {
  toFrameData,
  toHybridFrameData,
  toV2UploadFrameData,
  detectImageFormat,
  getPngDimensions,
} from '@moveris/shared';

Retry

import { retryWithBackoff } from '@moveris/shared';

// Retry any async function with exponential backoff
const result = await retryWithBackoff(
  () => someAsyncOperation(),
  { maxAttempts: 3, initialDelay: 1000, maxDelay: 10000 }
);

Frame Analysis

import {
  isFaceFullyVisible,
  isFaceInOval,
  calculateFaceCropRegion,
  validateFaceLandmarks,
  computeAdaptiveBlurThreshold,
  computeAdaptiveBrightnessThreshold,
  detectPlatform,
  PLATFORM_BLUR_PARAMS,
} from '@moveris/shared';

These functions are used internally by the SDK hooks but can be used directly for custom implementations.

computeAdaptiveBlurThreshold and computeAdaptiveBrightnessThreshold (3.19+) derive quality cutoffs from a rolling window of recent samples. Related constants: MIN_BLUR_FLOOR, MIN_BRIGHTNESS_FLOOR, ADAPTIVE_BLUR_WINDOW_SIZE, ADAPTIVE_BRIGHTNESS_WINDOW_SIZE, BLUR_PERSISTENT_REJECTION_COUNT, BRIGHTNESS_PERSISTENT_REJECTION_COUNT.

From 3.22.0, pass optional platform params (or rely on useSmartFrameCapture, which resolves them automatically):

const platform = detectPlatform(); // 'ios' | 'android' | 'harmonyos' | 'desktop' | 'other'
const params = PLATFORM_BLUR_PARAMS[platform];
const threshold = computeAdaptiveBlurThreshold(samples, undefined, params);

Breaking change in 3.8.6

calculateFaceCropRegion() now returns { x, y, width, height } (not { x, y, size }). If you draw crops manually, update drawImage calls to use width and height. calculateAdaptiveCropMultiplier was removed in this version.

Capture format in 3.10.x

captureVideoFrame and useSmartFrameCapture now emit PNG base64 only. The previous 'raw' RGBA option and the jpeg-js encoding path were removed. If you need JPEG, encode it yourself from the returned PNG (or from the source canvas). See the Changelog entry for 2.7.0.