@jaak.ai/stamps 2.1.0-dev.9 → 2.2.0-dev.1

package/dist/types/components/my-component/my-component.d.ts

@@ -12,8 +12,24 @@ export declare class JaakStamps {
     captureDelay: number;
     enableBackDocumentTimer: boolean;
     backDocumentTimerDuration: number;
+    telemetryCollectorUrl?: string;
+    metricsCollectorUrl?: string;
+    enableTelemetry: boolean;
+    enableMetrics: boolean;
+    customerId?: string;
+    tenantId?: string;
+    environment?: string;
+    propagateTraceHeaderCorsUrls?: string;
+    metricsExportIntervalMillis?: number;
+    license?: string;
+    licenseEnvironment?: 'dev' | 'qa' | 'staging' | 'prod';
+    traceId?: string;
+    appId?: string;
     captureCompleted: EventEmitter<any>;
     isReady: EventEmitter<boolean>;
+    traceIdGenerated: EventEmitter<{
+        traceId: string;
+    }>;
     detectionBoxes: Array<{
         x: number;
         y: number;
@@ -66,11 +82,16 @@ export declare class JaakStamps {
     showPerformanceMessage: boolean;
     captureStateVersion: number;
     processingButton: 'capture-front' | 'capture-back' | 'skip-back' | null;
+    licenseValid: boolean;
+    licenseError: string | null;
+    private licenseValidationService;
     private serviceContainer;
     private eventBus;
     private stateManager;
     private cameraService;
     private detectionService;
+    private tracingService;
+    private metricsService;
     private videoRef?;
     private detectionContainer?;
     private videoStream?;
@@ -81,6 +102,7 @@ export declare class JaakStamps {
     private alignmentStartTime?;
     private alignmentTimer?;
     private backDocumentTimer?;
+    private orientationTimer?;
     private performanceMetrics;
     private performanceUpdateInterval?;
     private frameSkipCounter;
@@ -99,8 +121,10 @@ export declare class JaakStamps {
     private hasAutoSwitchedToManual;
     private canvasPool;
     private readonly MAX_CANVAS_POOL_SIZE;
+    componentWillLoad(): Promise<void>;
     componentDidLoad(): Promise<void>;
     private initializeServices;
+    private validateLicense;
     private setupEventListeners;
     private initializeComponent;
     private validateProps;
@@ -127,14 +151,10 @@ export declare class JaakStamps {
     }>;
     stopCapture(): Promise<{
         success: boolean;
-        resourcesFreed: string[];
-        cleanupErrors: string[];
         error?: undefined;
     } | {
         success: boolean;
         error: any;
-        resourcesFreed?: undefined;
-        cleanupErrors?: undefined;
     }>;
     resetCapture(): Promise<{
         success: boolean;
@@ -182,35 +202,12 @@ export declare class JaakStamps {
         error?: undefined;
     }>;
     getCaptureDelay(): Promise<number>;
-    getResourceReport(): Promise<any>;
-    forceResourceCleanup(): Promise<{
-        success: boolean;
-        resourcesFreed: string[];
-        errors: string[];
-        timestamp: string;
-        error?: undefined;
-    } | {
-        success: boolean;
-        error: any;
-        resourcesFreed?: undefined;
-        errors?: undefined;
-        timestamp?: undefined;
-    }>;
     private checkDeviceCapabilities;
     private startDetection;
     private initializeVideoStream;
     private detectFrame;
     disconnectedCallback(): void;
     private cleanup;
-    private cleanupDOMReferences;
-    private clearBrowserCache;
-    private clearLocalStorage;
-    aggressiveResourceCleanup(): Promise<{
-        freed: string[];
-        errors: string[];
-    }>;
-    onFrontCaptureComplete(): Promise<void>;
-    getResourceReportInternal(): any;
     render(): any;
     private updateDetectionBoxes;
     private updateMaskColor;

package/dist/types/components.d.ts

@@ -13,6 +13,10 @@ export namespace Components {
           * @default 15
          */
         "alignmentTolerance": number;
+        /**
+          * @default 'jaak-stamps-web'
+         */
+        "appId"?: string;
         /**
           * @default 20
          */
@@ -25,6 +29,7 @@ export namespace Components {
           * @default 20
          */
         "cropMargin": number;
+        "customerId"?: string;
         /**
           * @default false
          */
@@ -33,28 +38,58 @@ export namespace Components {
           * @default false
          */
         "enableBackDocumentTimer": boolean;
-        "forceResourceCleanup": () => Promise<{ success: boolean; resourcesFreed: string[]; errors: string[]; timestamp: string; error?: undefined; } | { success: boolean; error: any; resourcesFreed?: undefined; errors?: undefined; timestamp?: undefined; }>;
+        /**
+          * @default true
+         */
+        "enableMetrics": boolean;
+        /**
+          * @default true
+         */
+        "enableTelemetry": boolean;
+        /**
+          * @default 'production'
+         */
+        "environment"?: string;
         "getCameraInfo": () => Promise<CameraInfoResponse>;
         "getCaptureDelay": () => Promise<number>;
         "getCapturedImages": () => Promise<CapturedImagesResponse>;
-        "getResourceReport": () => Promise<any>;
         "getStatus": () => Promise<StatusResponse>;
         "isProcessCompleted": () => Promise<boolean>;
+        "license"?: string;
+        /**
+          * @default 'prod'
+         */
+        "licenseEnvironment"?: 'dev' | 'qa' | 'staging' | 'prod';
         /**
           * @default 90
          */
         "maskSize": number;
+        /**
+          * @default 'https://collector.jaak.ai/v1/metrics'
+         */
+        "metricsCollectorUrl"?: string;
+        /**
+          * @default 60000
+         */
+        "metricsExportIntervalMillis"?: number;
         /**
           * @default 'auto'
          */
         "preferredCamera": 'auto' | 'front' | 'back';
         "preloadModel": () => Promise<{ success: boolean; message: string; error?: undefined; } | { success: boolean; error: any; message?: undefined; }>;
+        "propagateTraceHeaderCorsUrls"?: string;
         "resetCapture": () => Promise<{ success: boolean; error?: undefined; } | { success: boolean; error: any; }>;
         "setCaptureDelay": (delay: number) => Promise<{ success: boolean; error: string; captureDelay: number; } | { success: boolean; captureDelay: number; error?: undefined; }>;
         "setPreferredCamera": (camera: "auto" | "front" | "back") => Promise<{ success: boolean; selectedCamera: string; availableCameras: number; error?: undefined; } | { success: boolean; error: any; selectedCamera: any; availableCameras: number; }>;
         "skipBackCapture": () => Promise<{ success: boolean; error?: undefined; } | { success: boolean; error: any; }>;
         "startCapture": () => Promise<{ success: boolean; error?: undefined; } | { success: boolean; error: any; }>;
-        "stopCapture": () => Promise<{ success: boolean; resourcesFreed: string[]; cleanupErrors: string[]; error?: undefined; } | { success: boolean; error: any; resourcesFreed?: undefined; cleanupErrors?: undefined; }>;
+        "stopCapture": () => Promise<{ success: boolean; error?: undefined; } | { success: boolean; error: any; }>;
+        /**
+          * @default 'https://collector.jaak.ai/v1/traces'
+         */
+        "telemetryCollectorUrl"?: string;
+        "tenantId"?: string;
+        "traceId"?: string;
         /**
           * @default false
          */
@@ -73,6 +108,7 @@ declare global {
     interface HTMLJaakStampsElementEventMap {
         "captureCompleted": any;
         "isReady": boolean;
+        "traceIdGenerated": {traceId: string};
     }
     interface HTMLJaakStampsElement extends Components.JaakStamps, HTMLStencilElement {
         addEventListener<K extends keyof HTMLJaakStampsElementEventMap>(type: K, listener: (this: HTMLJaakStampsElement, ev: JaakStampsCustomEvent<HTMLJaakStampsElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -98,6 +134,10 @@ declare namespace LocalJSX {
           * @default 15
          */
         "alignmentTolerance"?: number;
+        /**
+          * @default 'jaak-stamps-web'
+         */
+        "appId"?: string;
         /**
           * @default 20
          */
@@ -110,6 +150,7 @@ declare namespace LocalJSX {
           * @default 20
          */
         "cropMargin"?: number;
+        "customerId"?: string;
         /**
           * @default false
          */
@@ -118,16 +159,49 @@ declare namespace LocalJSX {
           * @default false
          */
         "enableBackDocumentTimer"?: boolean;
+        /**
+          * @default true
+         */
+        "enableMetrics"?: boolean;
+        /**
+          * @default true
+         */
+        "enableTelemetry"?: boolean;
+        /**
+          * @default 'production'
+         */
+        "environment"?: string;
+        "license"?: string;
+        /**
+          * @default 'prod'
+         */
+        "licenseEnvironment"?: 'dev' | 'qa' | 'staging' | 'prod';
         /**
           * @default 90
          */
         "maskSize"?: number;
+        /**
+          * @default 'https://collector.jaak.ai/v1/metrics'
+         */
+        "metricsCollectorUrl"?: string;
+        /**
+          * @default 60000
+         */
+        "metricsExportIntervalMillis"?: number;
         "onCaptureCompleted"?: (event: JaakStampsCustomEvent<any>) => void;
         "onIsReady"?: (event: JaakStampsCustomEvent<boolean>) => void;
+        "onTraceIdGenerated"?: (event: JaakStampsCustomEvent<{traceId: string}>) => void;
         /**
           * @default 'auto'
          */
         "preferredCamera"?: 'auto' | 'front' | 'back';
+        "propagateTraceHeaderCorsUrls"?: string;
+        /**
+          * @default 'https://collector.jaak.ai/v1/traces'
+         */
+        "telemetryCollectorUrl"?: string;
+        "tenantId"?: string;
+        "traceId"?: string;
         /**
           * @default false
          */

package/dist/types/services/CameraService.d.ts

@@ -42,4 +42,5 @@ export declare class CameraService implements ICameraService {
     private constraintsEqual;
     static clearCaches(): void;
     invalidateDeviceCache(): void;
+    private isVirtualCamera;
 }

package/dist/types/services/DetectionService.d.ts

@@ -18,9 +18,6 @@ export declare class DetectionService implements IDetectionService {
     private captureCanvas?;
     private static canvasPool;
     private static readonly MAX_POOL_SIZE;
-    private modelLoadController?;
-    private classificationLoadController?;
-    private modelBlobUrls;
     constructor(debug?: boolean, useDocumentClassification?: boolean, useDocumentDetector?: boolean);
     loadModel(): Promise<void>;
     loadClassificationModel(): Promise<void>;
@@ -38,12 +35,7 @@ export declare class DetectionService implements IDetectionService {
     private preprocessMobileNet;
     private getCanvas;
     private returnCanvas;
-    clearModelCache(): Promise<void>;
-    private abortPendingRequests;
-    private revokeModelBlobUrls;
-    releaseMobileNetResources(): Promise<void>;
-    optimizeCanvasPool(maxSize: number): void;
-    static clearAllCanvasPools(): void;
+    static clearCanvasPools(): void;
     getPoolStats(): {
         [key: string]: number;
     };

package/dist/types/services/LicenseValidationService.d.ts

@@ -0,0 +1,59 @@
+/**
+ * License Validation Service
+ * Handles license validation for the jaak-stamps webcomponent
+ */
+export type Environment = 'dev' | 'qa' | 'staging' | 'prod';
+export interface LicenseValidationRequest {
+    license: string;
+    origin: string;
+    app_id?: string;
+    product?: string;
+    product_version?: string;
+    metadata?: {
+        [key: string]: any;
+    };
+}
+export interface LicenseValidationResponse {
+    access_token: string;
+    token_type: string;
+    expires_at: string;
+    session_id: string;
+    jti: string;
+    step: number;
+    license: string;
+    traceId?: string;
+}
+export interface LicenseValidationError {
+    error: string;
+    error_description?: string;
+    status_code?: number;
+}
+export declare class LicenseValidationService {
+    private apiEndpoint;
+    private baseUrl;
+    private static readonly ENVIRONMENT_URLS;
+    constructor(environment?: Environment);
+    /**
+     * Validate license with the API
+     * @param license License key to validate
+     * @param traceId Optional trace ID from W3C Trace Context
+     * @param appId Optional application ID
+     * @param metadata Optional additional metadata
+     * @returns Promise<LicenseValidationResponse>
+     */
+    validateLicense(license: string, traceId?: string, appId?: string): Promise<LicenseValidationResponse>;
+    /**
+     * Generate a random trace ID for W3C Trace Context (32 hex characters)
+     */
+    private generateTraceId;
+    /**
+     * Generate a random span ID for W3C Trace Context (16 hex characters)
+     */
+    private generateSpanId;
+    /**
+     * Extract trace ID from license field
+     * License format: "L<32-hex-chars>"
+     * Example: "Ld79223833a2fd91971e4c14a33298904" -> "d79223833a2fd91971e4c14a33298904"
+     */
+    static extractTraceIdFromLicense(license: string): string | null;
+}

package/dist/types/services/MetricsService.d.ts

@@ -0,0 +1,74 @@
+import { IMetricsService } from './interfaces/IMetricsService';
+export interface MetricsConfig {
+    collectorUrl?: string;
+    serviceName?: string;
+    serviceVersion?: string;
+    debug?: boolean;
+    customerId?: string;
+    tenantId?: string;
+    environment?: string;
+    exportIntervalMillis?: number;
+}
+export declare class MetricsService implements IMetricsService {
+    private meterProvider;
+    private meter;
+    private readonly collectorUrl;
+    private readonly serviceName;
+    private readonly serviceVersion;
+    private readonly debug;
+    private readonly customerId?;
+    private readonly tenantId?;
+    private readonly environment?;
+    private readonly exportIntervalMillis;
+    private metricReader;
+    private captureCounter;
+    private errorCounter;
+    private modelLoadCounter;
+    private userInteractionCounter;
+    private captureLatencyHistogram;
+    private modelLoadLatencyHistogram;
+    private detectionLatencyHistogram;
+    private imageSizeHistogram;
+    private activeSessionsGauge;
+    private memoryUsageGauge;
+    private activeSessions;
+    private gaugeValues;
+    constructor(config?: MetricsConfig);
+    initialize(): void;
+    private initializeMetrics;
+    private getBaseAttributes;
+    incrementCounter(name: string, value?: number, attributes?: Record<string, any>): void;
+    recordHistogram(name: string, value: number, attributes?: Record<string, any>): void;
+    setGauge(name: string, value: number, attributes?: Record<string, any>): void;
+    measureDuration<T>(name: string, fn: () => T | Promise<T>, attributes?: Record<string, any>): Promise<T>;
+    flush(): Promise<void>;
+    cleanup(): Promise<void>;
+    /**
+     * Record a successful capture
+     */
+    recordCapture(side: 'front' | 'back', mode: 'auto' | 'manual', durationMs: number): void;
+    /**
+     * Record an error
+     */
+    recordError(errorType: string, operation: string): void;
+    /**
+     * Record model load performance
+     */
+    recordModelLoad(modelType: 'detection' | 'classification', durationMs: number, cached: boolean): void;
+    /**
+     * Record detection performance
+     */
+    recordDetection(durationMs: number, detectionsFound: number): void;
+    /**
+     * Record image size
+     */
+    recordImageSize(side: 'front' | 'back', sizeBytes: number): void;
+    /**
+     * Update active sessions count
+     */
+    updateActiveSessions(count: number): void;
+    /**
+     * Record user interaction
+     */
+    recordUserInteraction(interactionType: string): void;
+}

package/dist/types/services/ServiceContainer.d.ts

@@ -2,6 +2,8 @@ import { ICameraService } from './interfaces/ICameraService';
 import { IDetectionService } from './interfaces/IDetectionService';
 import { IStateManager } from './interfaces/IStateManager';
 import { IEventBus } from './interfaces/IEventBus';
+import { ITracingService } from './interfaces/ITracingService';
+import { IMetricsService } from './interfaces/IMetricsService';
 export interface ComponentConfig {
     debug: boolean;
     alignmentTolerance: number;
@@ -11,6 +13,15 @@ export interface ComponentConfig {
     useDocumentDetector: boolean;
     preferredCamera: 'auto' | 'front' | 'back';
     captureDelay: number;
+    telemetryCollectorUrl?: string;
+    metricsCollectorUrl?: string;
+    enableTelemetry?: boolean;
+    enableMetrics?: boolean;
+    customerId?: string;
+    tenantId?: string;
+    environment?: string;
+    propagateTraceHeaderCorsUrls?: (string | RegExp)[];
+    metricsExportIntervalMillis?: number;
 }
 export declare class ServiceContainer {
     private services;
@@ -21,6 +32,8 @@ export declare class ServiceContainer {
     getStateManager(): IStateManager;
     getCameraService(): ICameraService;
     getDetectionService(): IDetectionService;
+    getTracingService(): ITracingService | null;
+    getMetricsService(): IMetricsService | null;
     updateConfig(config: Partial<ComponentConfig>): void;
-    cleanup(): void;
+    cleanup(): Promise<void>;
 }

package/dist/types/services/TracingService.d.ts

@@ -0,0 +1,67 @@
+import { ITracingService } from './interfaces/ITracingService';
+import { Span } from '@opentelemetry/api';
+export interface TracingConfig {
+    collectorUrl?: string;
+    serviceName?: string;
+    serviceVersion?: string;
+    debug?: boolean;
+    customerId?: string;
+    tenantId?: string;
+    environment?: string;
+    propagateTraceHeaderCorsUrls?: (string | RegExp)[];
+    enableAutoInstrumentation?: boolean;
+}
+export declare class TracingService implements ITracingService {
+    private provider;
+    private tracer;
+    private sessionTraceId;
+    private readonly collectorUrl;
+    private readonly serviceName;
+    private readonly serviceVersion;
+    private readonly debug;
+    private readonly customerId?;
+    private readonly tenantId?;
+    private readonly environment?;
+    private readonly propagateTraceHeaderCorsUrls;
+    private readonly enableAutoInstrumentation;
+    private spanProcessor;
+    private parser;
+    private geoCache;
+    private geoCacheTimestamp;
+    private readonly GEO_CACHE_DURATION_MS;
+    constructor(config?: TracingConfig);
+    initialize(): void;
+    private initializeAutoInstrumentation;
+    private getDeviceInfo;
+    private getBrowserInfo;
+    private getOSInfo;
+    /**
+     * Set the session trace ID from external source (license or component prop)
+     * @param traceId - The trace ID to use for all spans (32 hex characters)
+     */
+    setSessionTraceId(traceId: string | null): void;
+    /**
+     * Get the current session trace ID
+     */
+    getSessionTraceId(): string | null;
+    /**
+     * Generate a random span ID (16 hex characters)
+     */
+    private generateSpanId;
+    private getGeoLocation;
+    startSpan(name: string, attributes?: Record<string, any>): Span;
+    endSpan(span: Span): void;
+    addSpanEvent(span: Span, name: string, attributes?: Record<string, any>): void;
+    recordException(span: Span, error: Error): void;
+    setSpanAttribute(span: Span, key: string, value: any): void;
+    trace<T>(name: string, fn: () => T | Promise<T>, attributes?: Record<string, any>): Promise<T>;
+    cleanup(): Promise<void>;
+    /**
+     * Get the current trace ID (useful for logging correlation)
+     */
+    getCurrentTraceId(): string | undefined;
+    /**
+     * Get the current span ID
+     */
+    getCurrentSpanId(): string | undefined;
+}

package/dist/types/services/interfaces/IDetectionService.d.ts

@@ -28,10 +28,4 @@ export interface IDetectionService {
     isCardInFrame(box: DetectionBox): boolean;
     areAllSidesAligned(alignment: SideAlignment): boolean;
     cleanup(): void;
-    clearModelCache(): Promise<void>;
-    releaseMobileNetResources(): Promise<void>;
-    optimizeCanvasPool(maxSize: number): void;
-    getPoolStats(): {
-        [key: string]: number;
-    };
 }

package/dist/types/services/interfaces/ILicenseValidationService.d.ts

@@ -0,0 +1,4 @@
+import { LicenseValidationResponse } from '../LicenseValidationService';
+export interface ILicenseValidationService {
+    validateLicense(license: string, traceId?: string, appId?: string, metadata?: any): Promise<LicenseValidationResponse>;
+}

package/dist/types/services/interfaces/IMetricsService.d.ts

@@ -0,0 +1,70 @@
+export interface IMetricsService {
+    /**
+     * Initializes the metrics service with the collector endpoint
+     */
+    initialize(): void;
+    /**
+     * Increments a counter metric
+     * @param name - Name of the counter
+     * @param value - Value to add (default: 1)
+     * @param attributes - Optional attributes
+     */
+    incrementCounter(name: string, value?: number, attributes?: Record<string, any>): void;
+    /**
+     * Records a histogram value (for latencies, sizes, etc.)
+     * @param name - Name of the histogram
+     * @param value - Value to record
+     * @param attributes - Optional attributes
+     */
+    recordHistogram(name: string, value: number, attributes?: Record<string, any>): void;
+    /**
+     * Sets a gauge value (for current state values)
+     * @param name - Name of the gauge
+     * @param value - Current value
+     * @param attributes - Optional attributes
+     */
+    setGauge(name: string, value: number, attributes?: Record<string, any>): void;
+    /**
+     * Records operation duration automatically
+     * @param name - Name of the operation
+     * @param fn - Function to measure
+     * @param attributes - Optional attributes
+     */
+    measureDuration<T>(name: string, fn: () => T | Promise<T>, attributes?: Record<string, any>): Promise<T>;
+    /**
+     * Forces flush of metrics
+     */
+    flush(): Promise<void>;
+    /**
+     * Cleans up resources
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Record a successful capture
+     */
+    recordCapture(side: 'front' | 'back', mode: 'auto' | 'manual', durationMs: number): void;
+    /**
+     * Record an error
+     */
+    recordError(errorType: string, operation: string): void;
+    /**
+     * Record model load performance
+     */
+    recordModelLoad(modelType: 'detection' | 'classification', durationMs: number, cached: boolean): void;
+    /**
+     * Record detection performance
+     */
+    recordDetection(durationMs: number, detectionsFound: number): void;
+    /**
+     * Record image size
+     */
+    recordImageSize(side: 'front' | 'back', sizeBytes: number): void;
+    /**
+     * Update active sessions count
+     */
+    updateActiveSessions(count: number): void;
+    /**
+     * Record user interaction
+     */
+    recordUserInteraction(interactionType: string): void;
+}

package/dist/types/services/interfaces/ITracingService.d.ts

@@ -0,0 +1,59 @@
+import { Span } from '@opentelemetry/api';
+export interface ITracingService {
+    /**
+     * Initializes the tracing service with the collector endpoint
+     */
+    initialize(): void;
+    /**
+     * Starts a new span with the given name
+     * @param name - Name of the span
+     * @param attributes - Optional attributes to add to the span
+     * @returns The created span
+     */
+    startSpan(name: string, attributes?: Record<string, any>): Span;
+    /**
+     * Ends a span
+     * @param span - The span to end
+     */
+    endSpan(span: Span): void;
+    /**
+     * Adds an event to a span
+     * @param span - The span to add the event to
+     * @param name - Name of the event
+     * @param attributes - Optional attributes for the event
+     */
+    addSpanEvent(span: Span, name: string, attributes?: Record<string, any>): void;
+    /**
+     * Records an exception in a span
+     * @param span - The span to record the exception in
+     * @param error - The error to record
+     */
+    recordException(span: Span, error: Error): void;
+    /**
+     * Sets an attribute on a span
+     * @param span - The span to set the attribute on
+     * @param key - Attribute key
+     * @param value - Attribute value
+     */
+    setSpanAttribute(span: Span, key: string, value: any): void;
+    /**
+     * Wraps a function with automatic span creation
+     * @param name - Name of the span
+     * @param fn - Function to wrap
+     * @param attributes - Optional attributes
+     */
+    trace<T>(name: string, fn: () => T | Promise<T>, attributes?: Record<string, any>): Promise<T>;
+    /**
+     * Cleans up resources
+     */
+    cleanup(): void;
+    /**
+     * Set the session trace ID from external source (license or component prop)
+     * @param traceId - The trace ID to use for all spans (32 hex characters)
+     */
+    setSessionTraceId(traceId: string | null): void;
+    /**
+     * Get the current session trace ID
+     */
+    getSessionTraceId(): string | null;
+}