@moveris/shared 3.15.0 → 3.16.0

package/dist/index.d.mts

@@ -97,6 +97,8 @@ interface LiveCheckRequest {
     metadata?: {
         consumer?: ConsumerContext;
     } | null;
+    trace_id?: string;
+    forensic_client?: unknown;
 }
 interface V2UploadFrameData extends FrameData {
     landmarks?: {
@@ -639,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;
@@ -650,6 +705,7 @@ interface LivenessClientConfig {
     consumer?: ConsumerContext;
     trackClientTime?: boolean;
     extraMetadata?: ExtraMetadata;
+    traceId?: string;
 }
 declare class LivenessApiError extends Error {
     readonly code: string;
@@ -676,6 +732,7 @@ declare class LivenessClient {
     private readonly consumer;
     private readonly trackClientTime;
     private readonly extraMetadata;
+    private readonly traceId;
     private diCollected;
     private diCollecting;
     private diOverrides;
@@ -713,6 +770,8 @@ declare class LivenessClient {
         frameCount?: number;
         source?: FrameSource;
         warnings?: string[];
+        traceId?: string;
+        forensic?: ClientFragment;
     }): Promise<LivenessResult>;
     fastCheckCrops(crops: CropData[], options?: {
         sessionId?: string;
@@ -1075,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, 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, 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, toV2UploadFrameData, 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,6 +97,8 @@ interface LiveCheckRequest {
     metadata?: {
         consumer?: ConsumerContext;
     } | null;
+    trace_id?: string;
+    forensic_client?: unknown;
 }
 interface V2UploadFrameData extends FrameData {
     landmarks?: {
@@ -639,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;
@@ -650,6 +705,7 @@ interface LivenessClientConfig {
     consumer?: ConsumerContext;
     trackClientTime?: boolean;
     extraMetadata?: ExtraMetadata;
+    traceId?: string;
 }
 declare class LivenessApiError extends Error {
     readonly code: string;
@@ -676,6 +732,7 @@ declare class LivenessClient {
     private readonly consumer;
     private readonly trackClientTime;
     private readonly extraMetadata;
+    private readonly traceId;
     private diCollected;
     private diCollecting;
     private diOverrides;
@@ -713,6 +770,8 @@ declare class LivenessClient {
         frameCount?: number;
         source?: FrameSource;
         warnings?: string[];
+        traceId?: string;
+        forensic?: ClientFragment;
     }): Promise<LivenessResult>;
     fastCheckCrops(crops: CropData[], options?: {
         sessionId?: string;
@@ -1075,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, 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, 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, toV2UploadFrameData, 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,
@@ -247,7 +251,7 @@ async function sleep(ms) {
 }
 
 // package.json
-var version = "3.15.0";
+var version = "3.16.0";
 
 // src/utils/deviceIntelligence.ts
 var IPINFO_URL = "https://ipinfo.io/json";
@@ -295,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) {
@@ -419,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.
@@ -748,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 } : {},
@@ -763,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);
@@ -2574,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,
@@ -2609,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,
@@ -2648,6 +2816,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
   analyzeLighting,
+  buildClientFragment,
   calculateBrightness,
   calculateFaceAlignment,
   calculateFaceCropRegion,
@@ -2662,6 +2831,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   detectSpecularHighlights,
   encodeBase64,
   generateSessionId,
+  generateTraceId,
   getActiveModels,
   getApiErrorMessage,
   getCaptureQualityFeedback,

package/dist/index.mjs

@@ -104,7 +104,7 @@ async function sleep(ms) {
 }
 
 // package.json
-var version = "3.15.0";
+var version = "3.16.0";
 
 // src/utils/deviceIntelligence.ts
 var IPINFO_URL = "https://ipinfo.io/json";
@@ -152,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) {
@@ -276,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.
@@ -605,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 } : {},
@@ -620,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);
@@ -2431,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,
@@ -2465,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,
@@ -2504,6 +2668,7 @@ export {
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
   analyzeLighting,
+  buildClientFragment,
   calculateBrightness,
   calculateFaceAlignment,
   calculateFaceCropRegion,
@@ -2518,6 +2683,7 @@ export {
   detectSpecularHighlights,
   encodeBase64,
   generateSessionId,
+  generateTraceId,
   getActiveModels,
   getApiErrorMessage,
   getCaptureQualityFeedback,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moveris/shared",
-  "version": "3.15.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",