@jaak.ai/stamps 2.1.0 → 2.2.0-dev.10

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' | 'sandbox' | '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?;
@@ -100,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;

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,26 +38,58 @@ export namespace Components {
           * @default false
          */
         "enableBackDocumentTimer": boolean;
+        /**
+          * @default true
+         */
+        "enableMetrics": boolean;
+        /**
+          * @default true
+         */
+        "enableTelemetry": boolean;
+        /**
+          * @default 'production'
+         */
+        "environment"?: string;
         "getCameraInfo": () => Promise<CameraInfoResponse>;
         "getCaptureDelay": () => Promise<number>;
         "getCapturedImages": () => Promise<CapturedImagesResponse>;
         "getStatus": () => Promise<StatusResponse>;
         "isProcessCompleted": () => Promise<boolean>;
+        "license"?: string;
+        /**
+          * @default 'prod'
+         */
+        "licenseEnvironment"?: 'dev' | 'qa' | 'sandbox' | '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; error?: undefined; } | { success: boolean; error: any; }>;
+        /**
+          * @default 'https://collector.jaak.ai/v1/traces'
+         */
+        "telemetryCollectorUrl"?: string;
+        "tenantId"?: string;
+        "traceId"?: string;
         /**
           * @default false
          */
@@ -71,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;
@@ -96,6 +134,10 @@ declare namespace LocalJSX {
           * @default 15
          */
         "alignmentTolerance"?: number;
+        /**
+          * @default 'jaak-stamps-web'
+         */
+        "appId"?: string;
         /**
           * @default 20
          */
@@ -108,6 +150,7 @@ declare namespace LocalJSX {
           * @default 20
          */
         "cropMargin"?: number;
+        "customerId"?: string;
         /**
           * @default false
          */
@@ -116,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' | 'sandbox' | '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/LicenseValidationService.d.ts

@@ -0,0 +1,59 @@
+/**
+ * License Validation Service
+ * Handles license validation for the jaak-stamps webcomponent
+ */
+export type Environment = 'dev' | 'qa' | 'sandbox' | '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,72 @@
+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 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>;
+    traceAsync<T>(name: string, fn: () => Promise<T>, attributes?: Record<string, any>): Promise<T>;
+    /**
+     * Flush all pending spans to the collector
+     * Call this when capture/process is complete to send all traces
+     */
+    flush(): Promise<void>;
+    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/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,64 @@
+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>;
+    /**
+     * Flushes all pending spans to the collector
+     * Call this when capture/process is complete
+     */
+    flush(): Promise<void>;
+    /**
+     * 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaak.ai/stamps",
-  "version": "2.1.0",
+  "version": "2.2.0-dev.10",
   "description": "Jaak Document Identifier",
   "main": "dist/index.cjs.js",
   "module": "dist/index.js",
@@ -43,6 +43,7 @@
     "@stencil/core": "^4.27.1",
     "@types/jest": "^29.5.14",
     "@types/node": "^22.13.5",
+    "@types/ua-parser-js": "^0.7.39",
     "http-server": "^14.1.1",
     "jest": "^29.7.0",
     "jest-cli": "^29.7.0",
@@ -50,12 +51,27 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-zone": "^2.2.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.208.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
+    "@opentelemetry/instrumentation-document-load": "^0.54.0",
+    "@opentelemetry/instrumentation-fetch": "^0.208.0",
+    "@opentelemetry/instrumentation-user-interaction": "^0.53.0",
+    "@opentelemetry/instrumentation-xml-http-request": "^0.208.0",
+    "@opentelemetry/propagator-b3": "^2.2.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@opentelemetry/sdk-metrics": "^2.2.0",
+    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@opentelemetry/sdk-trace-web": "^2.2.0",
+    "@opentelemetry/semantic-conventions": "^1.38.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^11.0.4",
     "@semantic-release/npm": "^12.0.2",
     "@semantic-release/release-notes-generator": "^14.0.3",
-    "semantic-release": "^24.2.7"
+    "semantic-release": "^24.2.7",
+    "ua-parser-js": "^1.0.40"
   }
 }