@moveris/shared 3.13.0 → 3.16.0

package/dist/index.d.mts

@@ -97,7 +97,46 @@ interface LiveCheckRequest {
     metadata?: {
         consumer?: ConsumerContext;
     } | null;
+    trace_id?: string;
+    forensic_client?: unknown;
 }
+interface V2UploadFrameData extends FrameData {
+    landmarks?: {
+        x: number;
+        y: number;
+        z: number;
+    }[] | null;
+}
+interface V2UploadRequest {
+    session_id: string;
+    model?: FastCheckModel;
+    source?: FrameSource;
+    fps?: number;
+    frames: V2UploadFrameData[];
+    frame_count?: number;
+    warnings?: string[];
+}
+interface V2UploadResponse {
+    session_id: string;
+    frames_received: number;
+    frames_required: number;
+    is_complete: boolean;
+    ttl_seconds: number;
+    stored_durable: boolean;
+}
+interface V2FastCheckRequest {
+    session_id: string;
+    model?: FastCheckModel;
+    source?: FrameSource;
+    fps?: number;
+    frame_count?: number;
+    warnings?: string[];
+    device_intelligence?: DeviceIntelligence;
+    metadata?: {
+        consumer?: ConsumerContext;
+    } | null;
+}
+type V2LiveCheckRequest = V2FastCheckRequest;
 interface FastCheckCropsRequest {
     session_id: string;
     model?: FastCheckModel;
@@ -602,6 +641,59 @@ interface CameraValidationResult {
 }
 declare const DEFAULT_CAMERA_REQUIREMENTS: CameraRequirements;
 
+declare const FORENSIC_SCHEMA_VERSION = "1.0";
+type ForensicSource = 'webcam' | 'media';
+interface ClientStage {
+    stage_id: 'capture' | 'landmarks' | 'encode' | 'transport';
+    layer: 'sdk' | 'wire';
+    ok: boolean;
+    metrics: Record<string, unknown>;
+}
+interface ClientFragment {
+    trace_id: string;
+    schema_version: string;
+    source: ForensicSource;
+    origin: {
+        sdk_version?: string;
+        demo_commit?: string;
+        video_path?: string;
+    };
+    target: {
+        environment?: string;
+        model?: string;
+        endpoint?: string;
+    };
+    stages: ClientStage[];
+}
+interface CaptureSummary {
+    framesCaptured: number;
+    alignmentMean?: number;
+    blurVarMean?: number;
+    brightnessMean?: number;
+    landmarksPresentPct?: number;
+    validationPassPct?: number;
+    rollMean?: number;
+    yawMean?: number;
+    pitchMean?: number;
+    encoding?: string;
+    width?: number;
+    height?: number;
+    bytesPerFrame?: number;
+    framesSent?: number;
+    requestBytes?: number;
+    sessionId?: string;
+}
+interface FragmentContext {
+    sdkVersion?: string;
+    demoCommit?: string;
+    videoPath?: string;
+    environment?: string;
+    model?: string;
+    endpoint?: string;
+}
+declare function generateTraceId(): string;
+declare function buildClientFragment(traceId: string, source: ForensicSource, summary: CaptureSummary, ctx?: FragmentContext): ClientFragment;
+
 interface LivenessClientConfig {
     baseUrl?: string;
     apiKey: string;
@@ -613,6 +705,7 @@ interface LivenessClientConfig {
     consumer?: ConsumerContext;
     trackClientTime?: boolean;
     extraMetadata?: ExtraMetadata;
+    traceId?: string;
 }
 declare class LivenessApiError extends Error {
     readonly code: string;
@@ -622,6 +715,9 @@ declare class LivenessApiError extends Error {
     constructor(message: string, code: string, statusCode: number, required?: number, received?: number);
 }
 declare function toFrameData(frames: CapturedFrame[]): FrameData[];
+declare function toV2UploadFrameData(frames: CapturedFrame[], options?: {
+    withLandmarks?: boolean;
+}): V2UploadFrameData[];
 declare function toHybridFrameData(frames: CapturedFrame[]): HybridFrameData[];
 declare function toLivenessResult(response: FastCheckResponse | VerifyResponse | HybridCheckResponse): LivenessResult;
 declare function toLivenessResultFromStream(response: FastCheckStreamResponse): LivenessResult;
@@ -636,6 +732,7 @@ declare class LivenessClient {
     private readonly consumer;
     private readonly trackClientTime;
     private readonly extraMetadata;
+    private readonly traceId;
     private diCollected;
     private diCollecting;
     private diOverrides;
@@ -673,6 +770,8 @@ declare class LivenessClient {
         frameCount?: number;
         source?: FrameSource;
         warnings?: string[];
+        traceId?: string;
+        forensic?: ClientFragment;
     }): Promise<LivenessResult>;
     fastCheckCrops(crops: CropData[], options?: {
         sessionId?: string;
@@ -735,6 +834,35 @@ declare class LivenessClient {
     }): Promise<LivenessResult>;
     getJobResult(jobId: string): Promise<JobStatusResponse>;
     waitForJobResult(jobId: string, timeout?: number): Promise<JobStatusResponse>;
+    v2Upload(frames: CapturedFrame[], options: {
+        sessionId: string;
+        model?: FastCheckModel;
+        modelVersion?: ModelVersion;
+        source?: FrameSource;
+        fps?: number;
+        frameCount?: number;
+        warnings?: string[];
+        withLandmarks?: boolean;
+    }): Promise<V2UploadResponse>;
+    v2FastCheck(options: {
+        sessionId: string;
+        model?: FastCheckModel;
+        modelVersion?: ModelVersion;
+        source?: FrameSource;
+        fps?: number;
+        frameCount?: number;
+        warnings?: string[];
+    }): Promise<LivenessResult>;
+    v2LiveCheck(options: {
+        sessionId: string;
+        model?: FastCheckModel;
+        modelVersion?: ModelVersion;
+        source?: FrameSource;
+        fps?: number;
+        frameCount?: number;
+        warnings?: string[];
+    }): Promise<LivenessResult>;
+    private runV2Check;
 }
 
 declare class FrameBuffer {
@@ -789,6 +917,9 @@ declare const API_PATHS: {
     readonly jobResult: "/api/v1/result";
     readonly queueStats: "/api/v1/queue/stats";
     readonly sessions: "/api/v1/sessions";
+    readonly v2Upload: "/api/v2/upload";
+    readonly v2FastCheck: "/api/v2/fast-check";
+    readonly v2LiveCheck: "/api/v2/live-check";
 };
 declare const RETRY_CONFIG: {
     readonly maxAttempts: 3;
@@ -1003,4 +1134,51 @@ declare function collectDeviceIntelligence(opts?: {
     platformVersion?: string;
 }): Promise<DeviceIntelligence | null>;
 
-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, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, type CameraCapabilities, type CameraRequirements, type CameraValidationResult, type CaptureQualityState, type CapturedFrame, type ConsumerContext, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_CAMERA_REQUIREMENTS, 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, DYNAMIC_RANGE_WARNING_THRESHOLD, type DeprecationInfo, type DetectionResult, type DetectionSummary, type DetectorConfig, type DeviceIntelligence, type DeviceIntelligenceCamera, type DeviceIntelligenceGeo, type DeviceIntelligenceOverrides, type DynamicRangeAnalysis, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type ExtraMetadata, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CROP_FRAME_MARGIN, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, 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, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, type LiveCheckFrameData, type LiveCheckRequest, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, SHARED_SDK_PLATFORM, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeDynamicRange, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, collectDeviceIntelligence, decodeBase64, detectCameraAngle, detectFaceRoll, detectFaceRollFromMatrix, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, linearRgbToLabL, retryWithBackoff, rgbaToGrayscale, sleep, srgbToLinear, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+interface RecorderFrame {
+    pixels?: string;
+    landmarks?: unknown[] | null;
+}
+interface RecorderQuality {
+    alignment?: number;
+    blurVariance?: number;
+    brightness?: number;
+    landmarksValid?: boolean;
+    width?: number;
+    height?: number;
+    encoding?: string;
+}
+declare class ForensicRecorder {
+    readonly traceId: string;
+    private readonly source;
+    private readonly ctx;
+    private framesCaptured;
+    private landmarksPresent;
+    private landmarksValid;
+    private qualityTicks;
+    private bytesTotal;
+    private encoding;
+    private width;
+    private height;
+    private readonly alignment;
+    private readonly blur;
+    private readonly brightness;
+    private framesSent;
+    private requestBytes;
+    private sessionId;
+    constructor(opts?: {
+        source?: ForensicSource;
+        traceId?: string;
+        ctx?: FragmentContext;
+    });
+    onFrame(frame: RecorderFrame): void;
+    onQuality(q: RecorderQuality): void;
+    setTransport(t: {
+        framesSent?: number;
+        requestBytes?: number;
+        sessionId?: string;
+    }): void;
+    summary(): CaptureSummary;
+    build(): ClientFragment;
+}
+
+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, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, type CameraCapabilities, type CameraRequirements, type CameraValidationResult, type CaptureQualityState, type CaptureSummary, type CapturedFrame, type ClientFragment, type ClientStage, type ConsumerContext, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_CAMERA_REQUIREMENTS, 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, DYNAMIC_RANGE_WARNING_THRESHOLD, type DeprecationInfo, type DetectionResult, type DetectionSummary, type DetectorConfig, type DeviceIntelligence, type DeviceIntelligenceCamera, type DeviceIntelligenceGeo, type DeviceIntelligenceOverrides, type DynamicRangeAnalysis, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type ExtraMetadata, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CROP_FRAME_MARGIN, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FORENSIC_SCHEMA_VERSION, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, ForensicRecorder, type ForensicSource, type FragmentContext, 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, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, type LiveCheckFrameData, type LiveCheckRequest, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RecorderFrame, type RecorderQuality, type RetryOptions, SHARED_SDK_PLATFORM, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type V2FastCheckRequest, type V2LiveCheckRequest, type V2UploadFrameData, type V2UploadRequest, type V2UploadResponse, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeDynamicRange, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, buildClientFragment, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, collectDeviceIntelligence, decodeBase64, detectCameraAngle, detectFaceRoll, detectFaceRollFromMatrix, detectSpecularHighlights, encodeBase64, generateSessionId, generateTraceId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, linearRgbToLabL, retryWithBackoff, rgbaToGrayscale, sleep, srgbToLinear, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, toV2UploadFrameData, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.d.ts

@@ -97,7 +97,46 @@ interface LiveCheckRequest {
     metadata?: {
         consumer?: ConsumerContext;
     } | null;
+    trace_id?: string;
+    forensic_client?: unknown;
 }
+interface V2UploadFrameData extends FrameData {
+    landmarks?: {
+        x: number;
+        y: number;
+        z: number;
+    }[] | null;
+}
+interface V2UploadRequest {
+    session_id: string;
+    model?: FastCheckModel;
+    source?: FrameSource;
+    fps?: number;
+    frames: V2UploadFrameData[];
+    frame_count?: number;
+    warnings?: string[];
+}
+interface V2UploadResponse {
+    session_id: string;
+    frames_received: number;
+    frames_required: number;
+    is_complete: boolean;
+    ttl_seconds: number;
+    stored_durable: boolean;
+}
+interface V2FastCheckRequest {
+    session_id: string;
+    model?: FastCheckModel;
+    source?: FrameSource;
+    fps?: number;
+    frame_count?: number;
+    warnings?: string[];
+    device_intelligence?: DeviceIntelligence;
+    metadata?: {
+        consumer?: ConsumerContext;
+    } | null;
+}
+type V2LiveCheckRequest = V2FastCheckRequest;
 interface FastCheckCropsRequest {
     session_id: string;
     model?: FastCheckModel;
@@ -602,6 +641,59 @@ interface CameraValidationResult {
 }
 declare const DEFAULT_CAMERA_REQUIREMENTS: CameraRequirements;
 
+declare const FORENSIC_SCHEMA_VERSION = "1.0";
+type ForensicSource = 'webcam' | 'media';
+interface ClientStage {
+    stage_id: 'capture' | 'landmarks' | 'encode' | 'transport';
+    layer: 'sdk' | 'wire';
+    ok: boolean;
+    metrics: Record<string, unknown>;
+}
+interface ClientFragment {
+    trace_id: string;
+    schema_version: string;
+    source: ForensicSource;
+    origin: {
+        sdk_version?: string;
+        demo_commit?: string;
+        video_path?: string;
+    };
+    target: {
+        environment?: string;
+        model?: string;
+        endpoint?: string;
+    };
+    stages: ClientStage[];
+}
+interface CaptureSummary {
+    framesCaptured: number;
+    alignmentMean?: number;
+    blurVarMean?: number;
+    brightnessMean?: number;
+    landmarksPresentPct?: number;
+    validationPassPct?: number;
+    rollMean?: number;
+    yawMean?: number;
+    pitchMean?: number;
+    encoding?: string;
+    width?: number;
+    height?: number;
+    bytesPerFrame?: number;
+    framesSent?: number;
+    requestBytes?: number;
+    sessionId?: string;
+}
+interface FragmentContext {
+    sdkVersion?: string;
+    demoCommit?: string;
+    videoPath?: string;
+    environment?: string;
+    model?: string;
+    endpoint?: string;
+}
+declare function generateTraceId(): string;
+declare function buildClientFragment(traceId: string, source: ForensicSource, summary: CaptureSummary, ctx?: FragmentContext): ClientFragment;
+
 interface LivenessClientConfig {
     baseUrl?: string;
     apiKey: string;
@@ -613,6 +705,7 @@ interface LivenessClientConfig {
     consumer?: ConsumerContext;
     trackClientTime?: boolean;
     extraMetadata?: ExtraMetadata;
+    traceId?: string;
 }
 declare class LivenessApiError extends Error {
     readonly code: string;
@@ -622,6 +715,9 @@ declare class LivenessApiError extends Error {
     constructor(message: string, code: string, statusCode: number, required?: number, received?: number);
 }
 declare function toFrameData(frames: CapturedFrame[]): FrameData[];
+declare function toV2UploadFrameData(frames: CapturedFrame[], options?: {
+    withLandmarks?: boolean;
+}): V2UploadFrameData[];
 declare function toHybridFrameData(frames: CapturedFrame[]): HybridFrameData[];
 declare function toLivenessResult(response: FastCheckResponse | VerifyResponse | HybridCheckResponse): LivenessResult;
 declare function toLivenessResultFromStream(response: FastCheckStreamResponse): LivenessResult;
@@ -636,6 +732,7 @@ declare class LivenessClient {
     private readonly consumer;
     private readonly trackClientTime;
     private readonly extraMetadata;
+    private readonly traceId;
     private diCollected;
     private diCollecting;
     private diOverrides;
@@ -673,6 +770,8 @@ declare class LivenessClient {
         frameCount?: number;
         source?: FrameSource;
         warnings?: string[];
+        traceId?: string;
+        forensic?: ClientFragment;
     }): Promise<LivenessResult>;
     fastCheckCrops(crops: CropData[], options?: {
         sessionId?: string;
@@ -735,6 +834,35 @@ declare class LivenessClient {
     }): Promise<LivenessResult>;
     getJobResult(jobId: string): Promise<JobStatusResponse>;
     waitForJobResult(jobId: string, timeout?: number): Promise<JobStatusResponse>;
+    v2Upload(frames: CapturedFrame[], options: {
+        sessionId: string;
+        model?: FastCheckModel;
+        modelVersion?: ModelVersion;
+        source?: FrameSource;
+        fps?: number;
+        frameCount?: number;
+        warnings?: string[];
+        withLandmarks?: boolean;
+    }): Promise<V2UploadResponse>;
+    v2FastCheck(options: {
+        sessionId: string;
+        model?: FastCheckModel;
+        modelVersion?: ModelVersion;
+        source?: FrameSource;
+        fps?: number;
+        frameCount?: number;
+        warnings?: string[];
+    }): Promise<LivenessResult>;
+    v2LiveCheck(options: {
+        sessionId: string;
+        model?: FastCheckModel;
+        modelVersion?: ModelVersion;
+        source?: FrameSource;
+        fps?: number;
+        frameCount?: number;
+        warnings?: string[];
+    }): Promise<LivenessResult>;
+    private runV2Check;
 }
 
 declare class FrameBuffer {
@@ -789,6 +917,9 @@ declare const API_PATHS: {
     readonly jobResult: "/api/v1/result";
     readonly queueStats: "/api/v1/queue/stats";
     readonly sessions: "/api/v1/sessions";
+    readonly v2Upload: "/api/v2/upload";
+    readonly v2FastCheck: "/api/v2/fast-check";
+    readonly v2LiveCheck: "/api/v2/live-check";
 };
 declare const RETRY_CONFIG: {
     readonly maxAttempts: 3;
@@ -1003,4 +1134,51 @@ declare function collectDeviceIntelligence(opts?: {
     platformVersion?: string;
 }): Promise<DeviceIntelligence | null>;
 
-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, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, type CameraCapabilities, type CameraRequirements, type CameraValidationResult, type CaptureQualityState, type CapturedFrame, type ConsumerContext, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_CAMERA_REQUIREMENTS, 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, DYNAMIC_RANGE_WARNING_THRESHOLD, type DeprecationInfo, type DetectionResult, type DetectionSummary, type DetectorConfig, type DeviceIntelligence, type DeviceIntelligenceCamera, type DeviceIntelligenceGeo, type DeviceIntelligenceOverrides, type DynamicRangeAnalysis, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type ExtraMetadata, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CROP_FRAME_MARGIN, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, 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, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, type LiveCheckFrameData, type LiveCheckRequest, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, SHARED_SDK_PLATFORM, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeDynamicRange, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, collectDeviceIntelligence, decodeBase64, detectCameraAngle, detectFaceRoll, detectFaceRollFromMatrix, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, linearRgbToLabL, retryWithBackoff, rgbaToGrayscale, sleep, srgbToLinear, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+interface RecorderFrame {
+    pixels?: string;
+    landmarks?: unknown[] | null;
+}
+interface RecorderQuality {
+    alignment?: number;
+    blurVariance?: number;
+    brightness?: number;
+    landmarksValid?: boolean;
+    width?: number;
+    height?: number;
+    encoding?: string;
+}
+declare class ForensicRecorder {
+    readonly traceId: string;
+    private readonly source;
+    private readonly ctx;
+    private framesCaptured;
+    private landmarksPresent;
+    private landmarksValid;
+    private qualityTicks;
+    private bytesTotal;
+    private encoding;
+    private width;
+    private height;
+    private readonly alignment;
+    private readonly blur;
+    private readonly brightness;
+    private framesSent;
+    private requestBytes;
+    private sessionId;
+    constructor(opts?: {
+        source?: ForensicSource;
+        traceId?: string;
+        ctx?: FragmentContext;
+    });
+    onFrame(frame: RecorderFrame): void;
+    onQuality(q: RecorderQuality): void;
+    setTransport(t: {
+        framesSent?: number;
+        requestBytes?: number;
+        sessionId?: string;
+    }): void;
+    summary(): CaptureSummary;
+    build(): ClientFragment;
+}
+
+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, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, type CameraCapabilities, type CameraRequirements, type CameraValidationResult, type CaptureQualityState, type CaptureSummary, type CapturedFrame, type ClientFragment, type ClientStage, type ConsumerContext, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_CAMERA_REQUIREMENTS, 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, DYNAMIC_RANGE_WARNING_THRESHOLD, type DeprecationInfo, type DetectionResult, type DetectionSummary, type DetectorConfig, type DeviceIntelligence, type DeviceIntelligenceCamera, type DeviceIntelligenceGeo, type DeviceIntelligenceOverrides, type DynamicRangeAnalysis, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type ExtraMetadata, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CROP_FRAME_MARGIN, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FORENSIC_SCHEMA_VERSION, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, ForensicRecorder, type ForensicSource, type FragmentContext, 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, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, type LiveCheckFrameData, type LiveCheckRequest, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RecorderFrame, type RecorderQuality, type RetryOptions, SHARED_SDK_PLATFORM, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type V2FastCheckRequest, type V2LiveCheckRequest, type V2UploadFrameData, type V2UploadRequest, type V2UploadResponse, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeDynamicRange, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, buildClientFragment, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, collectDeviceIntelligence, decodeBase64, detectCameraAngle, detectFaceRoll, detectFaceRollFromMatrix, detectSpecularHighlights, encodeBase64, generateSessionId, generateTraceId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, linearRgbToLabL, retryWithBackoff, rgbaToGrayscale, sleep, srgbToLinear, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, toV2UploadFrameData, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.js

@@ -53,8 +53,10 @@ __export(index_exports, {
   FACE_CROP_FRAME_MARGIN: () => FACE_CROP_FRAME_MARGIN,
   FACE_CROP_OUTPUT_SIZE: () => FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES: () => FEEDBACK_MESSAGES,
+  FORENSIC_SCHEMA_VERSION: () => FORENSIC_SCHEMA_VERSION,
   FRAME_BUFFER_CONFIG: () => FRAME_BUFFER_CONFIG,
   FRAME_CONFIG: () => FRAME_CONFIG,
+  ForensicRecorder: () => ForensicRecorder,
   FrameBuffer: () => FrameBuffer,
   FrameQueue: () => FrameQueue,
   GOOD_ALIGNMENT: () => GOOD_ALIGNMENT,
@@ -92,6 +94,7 @@ __export(index_exports, {
   analyzeEyeRegionBrightness: () => analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast: () => analyzeEyeRegionContrast,
   analyzeLighting: () => analyzeLighting,
+  buildClientFragment: () => buildClientFragment,
   calculateBrightness: () => calculateBrightness,
   calculateFaceAlignment: () => calculateFaceAlignment,
   calculateFaceCropRegion: () => calculateFaceCropRegion,
@@ -106,6 +109,7 @@ __export(index_exports, {
   detectSpecularHighlights: () => detectSpecularHighlights,
   encodeBase64: () => encodeBase64,
   generateSessionId: () => generateSessionId,
+  generateTraceId: () => generateTraceId,
   getActiveModels: () => getActiveModels,
   getApiErrorMessage: () => getApiErrorMessage,
   getCaptureQualityFeedback: () => getCaptureQualityFeedback,
@@ -129,6 +133,7 @@ __export(index_exports, {
   toHybridFrameData: () => toHybridFrameData,
   toLivenessResult: () => toLivenessResult,
   toLivenessResultFromStream: () => toLivenessResultFromStream,
+  toV2UploadFrameData: () => toV2UploadFrameData,
   validateApiKey: () => validateApiKey,
   validateFaceLandmarks: () => validateFaceLandmarks,
   validateFrameCount: () => validateFrameCount,
@@ -161,7 +166,12 @@ var API_PATHS = {
   hybrid150: "/api/v1/hybrid-150",
   jobResult: "/api/v1/result",
   queueStats: "/api/v1/queue/stats",
-  sessions: "/api/v1/sessions"
+  sessions: "/api/v1/sessions",
+  // v2 upload-first pipeline (MOV-1936). Separate from v1; frames are uploaded
+  // first and resolved server-side by session_id at check time.
+  v2Upload: "/api/v2/upload",
+  v2FastCheck: "/api/v2/fast-check",
+  v2LiveCheck: "/api/v2/live-check"
 };
 var RETRY_CONFIG = {
   maxAttempts: 3,
@@ -241,7 +251,7 @@ async function sleep(ms) {
 }
 
 // package.json
-var version = "3.13.0";
+var version = "3.16.0";
 
 // src/utils/deviceIntelligence.ts
 var IPINFO_URL = "https://ipinfo.io/json";
@@ -289,6 +299,85 @@ async function collectDeviceIntelligence(opts) {
   }
 }
 
+// src/forensic/clientFragment.ts
+var FORENSIC_SCHEMA_VERSION = "1.0";
+function defined(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== void 0 && v !== null) out[k] = v;
+  }
+  return out;
+}
+function generateTraceId() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return "trace-" + Math.abs(hashString(String(Date.now()) + ":" + performanceNow())).toString(36);
+}
+function performanceNow() {
+  const p = globalThis.performance;
+  return p?.now ? p.now() : 0;
+}
+function hashString(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = Math.imul(31, h) + s.charCodeAt(i) | 0;
+  return h;
+}
+function buildClientFragment(traceId, source, summary, ctx = {}) {
+  const stages = [];
+  const capture = defined({
+    frames_captured: summary.framesCaptured,
+    alignment_mean: summary.alignmentMean,
+    blur_var_mean: summary.blurVarMean,
+    brightness_mean: summary.brightnessMean
+  });
+  if (Object.keys(capture).length) {
+    stages.push({ stage_id: "capture", layer: "sdk", ok: true, metrics: capture });
+  }
+  const landmarks = defined({
+    landmarks_present_pct: summary.landmarksPresentPct,
+    validation_pass_pct: summary.validationPassPct,
+    roll_mean: summary.rollMean,
+    yaw_mean: summary.yawMean,
+    pitch_mean: summary.pitchMean
+  });
+  if (Object.keys(landmarks).length) {
+    stages.push({ stage_id: "landmarks", layer: "sdk", ok: true, metrics: landmarks });
+  }
+  const encode = defined({
+    encoding: summary.encoding,
+    w: summary.width,
+    h: summary.height,
+    bytes_per_frame: summary.bytesPerFrame
+  });
+  if (Object.keys(encode).length) {
+    stages.push({ stage_id: "encode", layer: "sdk", ok: true, metrics: encode });
+  }
+  const transport = defined({
+    frames_sent: summary.framesSent,
+    request_bytes: summary.requestBytes,
+    session_id: summary.sessionId
+  });
+  if (Object.keys(transport).length) {
+    stages.push({ stage_id: "transport", layer: "wire", ok: true, metrics: transport });
+  }
+  return {
+    trace_id: traceId,
+    schema_version: FORENSIC_SCHEMA_VERSION,
+    source,
+    origin: defined({
+      sdk_version: ctx.sdkVersion,
+      demo_commit: ctx.demoCommit,
+      video_path: ctx.videoPath
+    }),
+    target: defined({
+      environment: ctx.environment,
+      model: ctx.model,
+      endpoint: ctx.endpoint
+    }),
+    stages
+  };
+}
+
 // src/client/LivenessClient.ts
 var LivenessApiError = class extends Error {
   constructor(message, code, statusCode, required, received) {
@@ -315,6 +404,16 @@ function toFrameData(frames) {
     pixels: frame.pixels
   }));
 }
+function toV2UploadFrameData(frames, options = {}) {
+  return frames.map((frame) => ({
+    index: frame.index,
+    timestamp_ms: frame.timestampMs,
+    pixels: frame.pixels,
+    ...options.withLandmarks ? {
+      landmarks: frame.landmarks ? frame.landmarks.map((lm) => ({ x: lm.x, y: lm.y, z: lm.z })) : null
+    } : {}
+  }));
+}
 function toHybridFrameData(frames) {
   return frames.map((frame) => ({
     timestamp_ms: frame.timestampMs,
@@ -403,6 +502,7 @@ var LivenessClient = class _LivenessClient {
     this.consumer = config.consumer;
     this.trackClientTime = config.trackClientTime ?? false;
     this.extraMetadata = config.extraMetadata;
+    this.traceId = config.traceId;
   }
   /**
    * Merge additional device intelligence overrides into the existing set.
@@ -732,11 +832,14 @@ var LivenessClient = class _LivenessClient {
   async liveCheck(frames, options = {}) {
     const effectiveVersion = options.modelVersion ?? this.modelVersion;
     const di = await this.getDeviceIntelligence();
+    const traceId = options.forensic?.trace_id ?? options.traceId ?? this.traceId ?? generateTraceId();
     const request = {
       session_id: options.sessionId ?? generateSessionId(),
       model: options.model ?? "10",
       source: options.source ?? "live",
       frames: toLiveCheckFrameData(frames),
+      trace_id: traceId,
+      ...options.forensic ? { forensic_client: options.forensic } : {},
       ...options.frameCount != null ? { frame_count: options.frameCount } : {},
       ...options.warnings?.length ? { warnings: options.warnings } : {},
       ...di ? { device_intelligence: di } : {},
@@ -747,7 +850,7 @@ var LivenessClient = class _LivenessClient {
       {
         method: "POST",
         body: JSON.stringify(request),
-        headers: this.buildModelVersionHeaders(effectiveVersion)
+        headers: { ...this.buildModelVersionHeaders(effectiveVersion), "X-Trace-Id": traceId }
       }
     );
     const result = toLivenessResult(response);
@@ -1057,6 +1160,103 @@ var LivenessClient = class _LivenessClient {
       `${API_PATHS.jobResult}/${jobId}/wait?timeout=${timeout}`
     );
   }
+  // ===========================================================================
+  // v2 Pipeline (MOV-1936): upload-first
+  //
+  // Two-phase flow, fully separate from the v1 endpoints above:
+  //   1. v2Upload()    — buffer frames server-side (call once or repeatedly).
+  //   2. v2FastCheck() / v2LiveCheck() — run inference; NO frames in the body,
+  //      the server resolves them by session_id from the prior upload(s).
+  // The check responses reuse the v1 FastCheckResponse shape, so the existing
+  // `toLivenessResult` + deprecation-header handling applies unchanged.
+  // ===========================================================================
+  /**
+   * Buffer a batch of frames for a session (POST /api/v2/upload).
+   *
+   * Inference is NOT run here — this only stores frames keyed by `session_id`.
+   * May be called multiple times for the same session (e.g. chunked during
+   * capture); the server accumulates and reports cumulative progress.
+   *
+   * Set `withLandmarks` for the live-check path so MediaPipe landmarks travel
+   * with each frame; leave it off for the fast-check path.
+   *
+   * @param frames  - Captured frames to buffer
+   * @param options - Session, model, source and upload flags
+   * @returns Upload progress (frames_received / frames_required / is_complete)
+   */
+  async v2Upload(frames, options) {
+    const effectiveVersion = options.modelVersion ?? this.modelVersion;
+    const request = {
+      session_id: options.sessionId,
+      model: options.model ?? "10",
+      source: options.source ?? "live",
+      frames: toV2UploadFrameData(frames, { withLandmarks: options.withLandmarks }),
+      ...options.fps != null ? { fps: options.fps } : {},
+      ...options.frameCount != null ? { frame_count: options.frameCount } : {},
+      ...options.warnings?.length ? { warnings: options.warnings } : {}
+    };
+    return this.requestWithRetry(API_PATHS.v2Upload, {
+      method: "POST",
+      body: JSON.stringify(request),
+      headers: this.buildModelVersionHeaders(effectiveVersion)
+    });
+  }
+  /**
+   * Run a fast-check against frames previously uploaded via {@link v2Upload}
+   * (POST /api/v2/fast-check). The request carries NO frames — the server
+   * resolves them by `session_id`.
+   *
+   * @param options - Session and request context
+   * @returns Liveness result
+   */
+  async v2FastCheck(options) {
+    return this.runV2Check(API_PATHS.v2FastCheck, options);
+  }
+  /**
+   * Run a live-check against frames previously uploaded via {@link v2Upload}
+   * with `withLandmarks: true` (POST /api/v2/live-check). The request carries
+   * NO frames. The server requires a V3 model and surfaces the V3 `diagnostics`
+   * block on the result.
+   *
+   * @param options - Session and request context
+   * @returns Liveness result (includes `diagnostics`)
+   */
+  async v2LiveCheck(options) {
+    return this.runV2Check(API_PATHS.v2LiveCheck, options);
+  }
+  /**
+   * Shared body for the v2 fast-check / live-check requests (internal).
+   * Both endpoints take the identical no-frames payload and response shape;
+   * only the path differs.
+   */
+  async runV2Check(path, options) {
+    const effectiveVersion = options.modelVersion ?? this.modelVersion;
+    const di = await this.getDeviceIntelligence();
+    const metadata = this.buildMetadata();
+    const request = {
+      session_id: options.sessionId,
+      model: options.model ?? "10",
+      source: options.source ?? "live",
+      ...options.fps != null ? { fps: options.fps } : {},
+      ...options.frameCount != null ? { frame_count: options.frameCount } : {},
+      ...options.warnings?.length ? { warnings: options.warnings } : {},
+      ...di ? { device_intelligence: di } : {},
+      ...metadata ? { metadata } : {}
+    };
+    const { data: response, headers } = await this.requestWithRetryRaw(path, {
+      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;
+  }
 };
 
 // src/buffer/FrameBuffer.ts
@@ -2461,6 +2661,85 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
     message: null
   };
 }
+
+// src/forensic/recorder.ts
+var RunningMean = class {
+  constructor() {
+    this.sum = 0;
+    this.n = 0;
+  }
+  add(v) {
+    if (typeof v === "number" && !Number.isNaN(v)) {
+      this.sum += v;
+      this.n += 1;
+    }
+  }
+  get value() {
+    return this.n ? this.sum / this.n : void 0;
+  }
+};
+var ForensicRecorder = class {
+  constructor(opts = {}) {
+    this.framesCaptured = 0;
+    this.landmarksPresent = 0;
+    this.landmarksValid = 0;
+    this.qualityTicks = 0;
+    this.bytesTotal = 0;
+    this.alignment = new RunningMean();
+    this.blur = new RunningMean();
+    this.brightness = new RunningMean();
+    this.source = opts.source ?? "webcam";
+    this.traceId = opts.traceId ?? generateTraceId();
+    this.ctx = opts.ctx ?? {};
+  }
+  /** Record one captured frame (counts, landmark presence, encoded size). */
+  onFrame(frame) {
+    this.framesCaptured += 1;
+    if (frame.landmarks && frame.landmarks.length) this.landmarksPresent += 1;
+    if (typeof frame.pixels === "string") this.bytesTotal += frame.pixels.length;
+  }
+  /** Record one quality update (alignment/blur/brightness/landmark validity). */
+  onQuality(q) {
+    this.qualityTicks += 1;
+    this.alignment.add(q.alignment);
+    this.blur.add(q.blurVariance);
+    this.brightness.add(q.brightness);
+    if (q.landmarksValid) this.landmarksValid += 1;
+    if (q.encoding) this.encoding = q.encoding;
+    if (q.width) this.width = q.width;
+    if (q.height) this.height = q.height;
+  }
+  /** Record the transport leg once the request is built/sent. */
+  setTransport(t) {
+    this.framesSent = t.framesSent;
+    this.requestBytes = t.requestBytes;
+    this.sessionId = t.sessionId;
+  }
+  /** Summarise the session into the CaptureSummary the fragment builder expects. */
+  summary() {
+    return {
+      framesCaptured: this.framesCaptured,
+      alignmentMean: this.alignment.value,
+      blurVarMean: this.blur.value,
+      brightnessMean: this.brightness.value,
+      landmarksPresentPct: this.framesCaptured ? this.landmarksPresent / this.framesCaptured : void 0,
+      // validity is a fraction of QUALITY ticks, not frames — quality updates fire
+      // more often than frames, so dividing by frames could exceed 1.0.
+      validationPassPct: this.qualityTicks ? this.landmarksValid / this.qualityTicks : void 0,
+      encoding: this.encoding,
+      width: this.width,
+      height: this.height,
+      bytesPerFrame: this.framesCaptured && this.bytesTotal ? Math.round(this.bytesTotal / this.framesCaptured) : void 0,
+      framesSent: this.framesSent ?? (this.framesCaptured || void 0),
+      requestBytes: this.requestBytes,
+      sessionId: this.sessionId
+    };
+  }
+  /** Build the client fragment for this session. */
+  build() {
+    return buildClientFragment(this.traceId, this.source, this.summary(), this.ctx);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALIGNMENT_THRESHOLD_CAPTURE,
@@ -2496,8 +2775,10 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   FACE_CROP_FRAME_MARGIN,
   FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES,
+  FORENSIC_SCHEMA_VERSION,
   FRAME_BUFFER_CONFIG,
   FRAME_CONFIG,
+  ForensicRecorder,
   FrameBuffer,
   FrameQueue,
   GOOD_ALIGNMENT,
@@ -2535,6 +2816,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
   analyzeLighting,
+  buildClientFragment,
   calculateBrightness,
   calculateFaceAlignment,
   calculateFaceCropRegion,
@@ -2549,6 +2831,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   detectSpecularHighlights,
   encodeBase64,
   generateSessionId,
+  generateTraceId,
   getActiveModels,
   getApiErrorMessage,
   getCaptureQualityFeedback,
@@ -2572,6 +2855,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   toHybridFrameData,
   toLivenessResult,
   toLivenessResultFromStream,
+  toV2UploadFrameData,
   validateApiKey,
   validateFaceLandmarks,
   validateFrameCount,

package/dist/index.mjs

@@ -19,7 +19,12 @@ var API_PATHS = {
   hybrid150: "/api/v1/hybrid-150",
   jobResult: "/api/v1/result",
   queueStats: "/api/v1/queue/stats",
-  sessions: "/api/v1/sessions"
+  sessions: "/api/v1/sessions",
+  // v2 upload-first pipeline (MOV-1936). Separate from v1; frames are uploaded
+  // first and resolved server-side by session_id at check time.
+  v2Upload: "/api/v2/upload",
+  v2FastCheck: "/api/v2/fast-check",
+  v2LiveCheck: "/api/v2/live-check"
 };
 var RETRY_CONFIG = {
   maxAttempts: 3,
@@ -99,7 +104,7 @@ async function sleep(ms) {
 }
 
 // package.json
-var version = "3.13.0";
+var version = "3.16.0";
 
 // src/utils/deviceIntelligence.ts
 var IPINFO_URL = "https://ipinfo.io/json";
@@ -147,6 +152,85 @@ async function collectDeviceIntelligence(opts) {
   }
 }
 
+// src/forensic/clientFragment.ts
+var FORENSIC_SCHEMA_VERSION = "1.0";
+function defined(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== void 0 && v !== null) out[k] = v;
+  }
+  return out;
+}
+function generateTraceId() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return "trace-" + Math.abs(hashString(String(Date.now()) + ":" + performanceNow())).toString(36);
+}
+function performanceNow() {
+  const p = globalThis.performance;
+  return p?.now ? p.now() : 0;
+}
+function hashString(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = Math.imul(31, h) + s.charCodeAt(i) | 0;
+  return h;
+}
+function buildClientFragment(traceId, source, summary, ctx = {}) {
+  const stages = [];
+  const capture = defined({
+    frames_captured: summary.framesCaptured,
+    alignment_mean: summary.alignmentMean,
+    blur_var_mean: summary.blurVarMean,
+    brightness_mean: summary.brightnessMean
+  });
+  if (Object.keys(capture).length) {
+    stages.push({ stage_id: "capture", layer: "sdk", ok: true, metrics: capture });
+  }
+  const landmarks = defined({
+    landmarks_present_pct: summary.landmarksPresentPct,
+    validation_pass_pct: summary.validationPassPct,
+    roll_mean: summary.rollMean,
+    yaw_mean: summary.yawMean,
+    pitch_mean: summary.pitchMean
+  });
+  if (Object.keys(landmarks).length) {
+    stages.push({ stage_id: "landmarks", layer: "sdk", ok: true, metrics: landmarks });
+  }
+  const encode = defined({
+    encoding: summary.encoding,
+    w: summary.width,
+    h: summary.height,
+    bytes_per_frame: summary.bytesPerFrame
+  });
+  if (Object.keys(encode).length) {
+    stages.push({ stage_id: "encode", layer: "sdk", ok: true, metrics: encode });
+  }
+  const transport = defined({
+    frames_sent: summary.framesSent,
+    request_bytes: summary.requestBytes,
+    session_id: summary.sessionId
+  });
+  if (Object.keys(transport).length) {
+    stages.push({ stage_id: "transport", layer: "wire", ok: true, metrics: transport });
+  }
+  return {
+    trace_id: traceId,
+    schema_version: FORENSIC_SCHEMA_VERSION,
+    source,
+    origin: defined({
+      sdk_version: ctx.sdkVersion,
+      demo_commit: ctx.demoCommit,
+      video_path: ctx.videoPath
+    }),
+    target: defined({
+      environment: ctx.environment,
+      model: ctx.model,
+      endpoint: ctx.endpoint
+    }),
+    stages
+  };
+}
+
 // src/client/LivenessClient.ts
 var LivenessApiError = class extends Error {
   constructor(message, code, statusCode, required, received) {
@@ -173,6 +257,16 @@ function toFrameData(frames) {
     pixels: frame.pixels
   }));
 }
+function toV2UploadFrameData(frames, options = {}) {
+  return frames.map((frame) => ({
+    index: frame.index,
+    timestamp_ms: frame.timestampMs,
+    pixels: frame.pixels,
+    ...options.withLandmarks ? {
+      landmarks: frame.landmarks ? frame.landmarks.map((lm) => ({ x: lm.x, y: lm.y, z: lm.z })) : null
+    } : {}
+  }));
+}
 function toHybridFrameData(frames) {
   return frames.map((frame) => ({
     timestamp_ms: frame.timestampMs,
@@ -261,6 +355,7 @@ var LivenessClient = class _LivenessClient {
     this.consumer = config.consumer;
     this.trackClientTime = config.trackClientTime ?? false;
     this.extraMetadata = config.extraMetadata;
+    this.traceId = config.traceId;
   }
   /**
    * Merge additional device intelligence overrides into the existing set.
@@ -590,11 +685,14 @@ var LivenessClient = class _LivenessClient {
   async liveCheck(frames, options = {}) {
     const effectiveVersion = options.modelVersion ?? this.modelVersion;
     const di = await this.getDeviceIntelligence();
+    const traceId = options.forensic?.trace_id ?? options.traceId ?? this.traceId ?? generateTraceId();
     const request = {
       session_id: options.sessionId ?? generateSessionId(),
       model: options.model ?? "10",
       source: options.source ?? "live",
       frames: toLiveCheckFrameData(frames),
+      trace_id: traceId,
+      ...options.forensic ? { forensic_client: options.forensic } : {},
       ...options.frameCount != null ? { frame_count: options.frameCount } : {},
       ...options.warnings?.length ? { warnings: options.warnings } : {},
       ...di ? { device_intelligence: di } : {},
@@ -605,7 +703,7 @@ var LivenessClient = class _LivenessClient {
       {
         method: "POST",
         body: JSON.stringify(request),
-        headers: this.buildModelVersionHeaders(effectiveVersion)
+        headers: { ...this.buildModelVersionHeaders(effectiveVersion), "X-Trace-Id": traceId }
       }
     );
     const result = toLivenessResult(response);
@@ -915,6 +1013,103 @@ var LivenessClient = class _LivenessClient {
       `${API_PATHS.jobResult}/${jobId}/wait?timeout=${timeout}`
     );
   }
+  // ===========================================================================
+  // v2 Pipeline (MOV-1936): upload-first
+  //
+  // Two-phase flow, fully separate from the v1 endpoints above:
+  //   1. v2Upload()    — buffer frames server-side (call once or repeatedly).
+  //   2. v2FastCheck() / v2LiveCheck() — run inference; NO frames in the body,
+  //      the server resolves them by session_id from the prior upload(s).
+  // The check responses reuse the v1 FastCheckResponse shape, so the existing
+  // `toLivenessResult` + deprecation-header handling applies unchanged.
+  // ===========================================================================
+  /**
+   * Buffer a batch of frames for a session (POST /api/v2/upload).
+   *
+   * Inference is NOT run here — this only stores frames keyed by `session_id`.
+   * May be called multiple times for the same session (e.g. chunked during
+   * capture); the server accumulates and reports cumulative progress.
+   *
+   * Set `withLandmarks` for the live-check path so MediaPipe landmarks travel
+   * with each frame; leave it off for the fast-check path.
+   *
+   * @param frames  - Captured frames to buffer
+   * @param options - Session, model, source and upload flags
+   * @returns Upload progress (frames_received / frames_required / is_complete)
+   */
+  async v2Upload(frames, options) {
+    const effectiveVersion = options.modelVersion ?? this.modelVersion;
+    const request = {
+      session_id: options.sessionId,
+      model: options.model ?? "10",
+      source: options.source ?? "live",
+      frames: toV2UploadFrameData(frames, { withLandmarks: options.withLandmarks }),
+      ...options.fps != null ? { fps: options.fps } : {},
+      ...options.frameCount != null ? { frame_count: options.frameCount } : {},
+      ...options.warnings?.length ? { warnings: options.warnings } : {}
+    };
+    return this.requestWithRetry(API_PATHS.v2Upload, {
+      method: "POST",
+      body: JSON.stringify(request),
+      headers: this.buildModelVersionHeaders(effectiveVersion)
+    });
+  }
+  /**
+   * Run a fast-check against frames previously uploaded via {@link v2Upload}
+   * (POST /api/v2/fast-check). The request carries NO frames — the server
+   * resolves them by `session_id`.
+   *
+   * @param options - Session and request context
+   * @returns Liveness result
+   */
+  async v2FastCheck(options) {
+    return this.runV2Check(API_PATHS.v2FastCheck, options);
+  }
+  /**
+   * Run a live-check against frames previously uploaded via {@link v2Upload}
+   * with `withLandmarks: true` (POST /api/v2/live-check). The request carries
+   * NO frames. The server requires a V3 model and surfaces the V3 `diagnostics`
+   * block on the result.
+   *
+   * @param options - Session and request context
+   * @returns Liveness result (includes `diagnostics`)
+   */
+  async v2LiveCheck(options) {
+    return this.runV2Check(API_PATHS.v2LiveCheck, options);
+  }
+  /**
+   * Shared body for the v2 fast-check / live-check requests (internal).
+   * Both endpoints take the identical no-frames payload and response shape;
+   * only the path differs.
+   */
+  async runV2Check(path, options) {
+    const effectiveVersion = options.modelVersion ?? this.modelVersion;
+    const di = await this.getDeviceIntelligence();
+    const metadata = this.buildMetadata();
+    const request = {
+      session_id: options.sessionId,
+      model: options.model ?? "10",
+      source: options.source ?? "live",
+      ...options.fps != null ? { fps: options.fps } : {},
+      ...options.frameCount != null ? { frame_count: options.frameCount } : {},
+      ...options.warnings?.length ? { warnings: options.warnings } : {},
+      ...di ? { device_intelligence: di } : {},
+      ...metadata ? { metadata } : {}
+    };
+    const { data: response, headers } = await this.requestWithRetryRaw(path, {
+      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;
+  }
 };
 
 // src/buffer/FrameBuffer.ts
@@ -2319,6 +2514,85 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
     message: null
   };
 }
+
+// src/forensic/recorder.ts
+var RunningMean = class {
+  constructor() {
+    this.sum = 0;
+    this.n = 0;
+  }
+  add(v) {
+    if (typeof v === "number" && !Number.isNaN(v)) {
+      this.sum += v;
+      this.n += 1;
+    }
+  }
+  get value() {
+    return this.n ? this.sum / this.n : void 0;
+  }
+};
+var ForensicRecorder = class {
+  constructor(opts = {}) {
+    this.framesCaptured = 0;
+    this.landmarksPresent = 0;
+    this.landmarksValid = 0;
+    this.qualityTicks = 0;
+    this.bytesTotal = 0;
+    this.alignment = new RunningMean();
+    this.blur = new RunningMean();
+    this.brightness = new RunningMean();
+    this.source = opts.source ?? "webcam";
+    this.traceId = opts.traceId ?? generateTraceId();
+    this.ctx = opts.ctx ?? {};
+  }
+  /** Record one captured frame (counts, landmark presence, encoded size). */
+  onFrame(frame) {
+    this.framesCaptured += 1;
+    if (frame.landmarks && frame.landmarks.length) this.landmarksPresent += 1;
+    if (typeof frame.pixels === "string") this.bytesTotal += frame.pixels.length;
+  }
+  /** Record one quality update (alignment/blur/brightness/landmark validity). */
+  onQuality(q) {
+    this.qualityTicks += 1;
+    this.alignment.add(q.alignment);
+    this.blur.add(q.blurVariance);
+    this.brightness.add(q.brightness);
+    if (q.landmarksValid) this.landmarksValid += 1;
+    if (q.encoding) this.encoding = q.encoding;
+    if (q.width) this.width = q.width;
+    if (q.height) this.height = q.height;
+  }
+  /** Record the transport leg once the request is built/sent. */
+  setTransport(t) {
+    this.framesSent = t.framesSent;
+    this.requestBytes = t.requestBytes;
+    this.sessionId = t.sessionId;
+  }
+  /** Summarise the session into the CaptureSummary the fragment builder expects. */
+  summary() {
+    return {
+      framesCaptured: this.framesCaptured,
+      alignmentMean: this.alignment.value,
+      blurVarMean: this.blur.value,
+      brightnessMean: this.brightness.value,
+      landmarksPresentPct: this.framesCaptured ? this.landmarksPresent / this.framesCaptured : void 0,
+      // validity is a fraction of QUALITY ticks, not frames — quality updates fire
+      // more often than frames, so dividing by frames could exceed 1.0.
+      validationPassPct: this.qualityTicks ? this.landmarksValid / this.qualityTicks : void 0,
+      encoding: this.encoding,
+      width: this.width,
+      height: this.height,
+      bytesPerFrame: this.framesCaptured && this.bytesTotal ? Math.round(this.bytesTotal / this.framesCaptured) : void 0,
+      framesSent: this.framesSent ?? (this.framesCaptured || void 0),
+      requestBytes: this.requestBytes,
+      sessionId: this.sessionId
+    };
+  }
+  /** Build the client fragment for this session. */
+  build() {
+    return buildClientFragment(this.traceId, this.source, this.summary(), this.ctx);
+  }
+};
 export {
   ALIGNMENT_THRESHOLD_CAPTURE,
   ALIGNMENT_THRESHOLD_GOOD,
@@ -2353,8 +2627,10 @@ export {
   FACE_CROP_FRAME_MARGIN,
   FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES,
+  FORENSIC_SCHEMA_VERSION,
   FRAME_BUFFER_CONFIG,
   FRAME_CONFIG,
+  ForensicRecorder,
   FrameBuffer,
   FrameQueue,
   GOOD_ALIGNMENT,
@@ -2392,6 +2668,7 @@ export {
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
   analyzeLighting,
+  buildClientFragment,
   calculateBrightness,
   calculateFaceAlignment,
   calculateFaceCropRegion,
@@ -2406,6 +2683,7 @@ export {
   detectSpecularHighlights,
   encodeBase64,
   generateSessionId,
+  generateTraceId,
   getActiveModels,
   getApiErrorMessage,
   getCaptureQualityFeedback,
@@ -2429,6 +2707,7 @@ export {
   toHybridFrameData,
   toLivenessResult,
   toLivenessResultFromStream,
+  toV2UploadFrameData,
   validateApiKey,
   validateFaceLandmarks,
   validateFrameCount,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moveris/shared",
-  "version": "3.13.0",
+  "version": "3.16.0",
   "description": "Core business logic for Moveris Live SDK",
   "author": "Moveris - Jeyson Palacio, Arthur ITurres, Eric D. Brown",
   "main": "./dist/index.js",