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

package/README.md

@@ -56,23 +56,49 @@ yarn add @jaak.ai/stamps
 
 ### Properties/Attributes
 
+#### License Properties (Required)
+
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `license` | `string` | `undefined` | License key for component authentication (required) |
-| `environment` | `'dev' \| 'qa' \| 'staging' \| 'prod'` | `'prod'` | API environment for license validation |
-| `trace-id` | `string` | `undefined` | Optional trace ID for request tracing (auto-generated if not provided) |
+| `license` | `string` | `undefined` | **[REQUIRED]** License key for component authentication |
+| `license-environment` | `'dev' \| 'qa' \| 'sandbox' \| 'prod'` | `'prod'` | API environment for license validation |
 | `app-id` | `string` | `'jaak-stamps-web'` | Application identifier for analytics and tracking |
+| `trace-id` | `string` | `undefined` | Optional trace ID for distributed tracing (auto-generated if not provided) |
+
+#### Base Configuration Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
 | `debug` | `boolean` | `false` | Enable debug mode with additional logging and overlays |
-| `mask-size` | `number` | `90` | Size percentage of the document detection mask |
-| `alignment-tolerance` | `number` | `15` | Tolerance level for document alignment detection |
-| `capture-delay` | `number` | `1500` | Delay in milliseconds before automatic capture |
-| `crop-margin` | `number` | `20` | Margin in pixels around detected document for cropping |
+| `mask-size` | `number` | `90` | Size percentage of the document detection mask (50-100) |
+| `alignment-tolerance` | `number` | `15` | Tolerance level in pixels for document alignment detection |
+| `capture-delay` | `number` | `1500` | Delay in milliseconds before automatic capture (0-10000) |
+| `crop-margin` | `number` | `20` | Margin in pixels around detected document for cropping (0-100) |
 | `preferred-camera` | `'auto' \| 'front' \| 'back'` | `'auto'` | Preferred camera selection |
-| `use-document-classification` | `boolean` | `false` | Enable AI document classification |
+| `use-document-classification` | `boolean` | `false` | Enable AI document type classification |
 | `use-document-detector` | `boolean` | `true` | Enable/disable AI document detection model |
 | `enable-back-document-timer` | `boolean` | `false` | Enable timer for back document capture |
 | `back-document-timer-duration` | `number` | `20` | Duration in seconds for back document capture timer |
 
+#### Telemetry and OpenTelemetry Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `telemetry-collector-url` | `string` | `'https://collector.jaak.ai/v1/traces'` | OTLP collector URL for distributed traces |
+| `metrics-collector-url` | `string` | `'https://collector.jaak.ai/v1/metrics'` | OTLP collector URL for metrics |
+| `enable-telemetry` | `boolean` | `true` | Enable distributed tracing with OpenTelemetry |
+| `enable-metrics` | `boolean` | `true` | Enable metrics export to OpenTelemetry |
+| `metrics-export-interval-millis` | `number` | `60000` | Metrics export interval in milliseconds |
+| `propagate-trace-header-cors-urls` | `string` | `undefined` | Comma-separated URLs for W3C Trace Context header propagation |
+
+#### Context Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `customer-id` | `string` | `undefined` | Customer ID for telemetry and analytics |
+| `tenant-id` | `string` | `undefined` | Tenant ID for multi-tenancy support |
+| `environment` | `string` | `'production'` | Execution environment (development/staging/production) |
+
 ### Methods
 
 #### Camera Control
@@ -581,6 +607,160 @@ import { DocumentScannerComponent } from './document-scanner.component';
 export class DocumentScannerModule { }
 ```
 
+## Telemetry and Observability (OpenTelemetry)
+
+Jaak Stamps includes full **OpenTelemetry** integration for distributed tracing, metrics, and performance monitoring in production environments.
+
+### Distributed Tracing
+
+The component implements distributed tracing following the **W3C Trace Context** standard, providing:
+
+- Complete flow tracking of document capture processes
+- Request correlation between frontend and backend
+- Performance bottleneck identification
+- Context propagation via `traceparent` headers
+
+**Automatically Recorded Spans:**
+- `component.initialize` - Component initialization
+- `capture.start` - Capture process start
+- `model.preload` - AI model preloading
+- `model.detection.load` - Detection model loading
+- `model.classification.load` - Classification model loading
+
+### Performance Metrics
+
+The component exports detailed metrics to OpenTelemetry:
+
+**Counters:**
+- `capture.counter` - Number of completed captures
+- `error.counter` - Error count by type
+- `model.load.counter` - Model load count
+- `user.interaction.counter` - User interactions
+
+**Histograms (Latencies):**
+- `capture.latency` - Total capture time
+- `model.load.latency` - Model loading time
+- `detection.latency` - Per-frame detection time
+- `image.size` - Captured image sizes
+
+**Gauges (Current State):**
+- `active.sessions` - Active sessions
+- `memory.usage` - Memory usage
+
+### Telemetry Configuration
+
+```html
+<jaak-stamps
+  license="your-license-key"
+  enable-telemetry="true"
+  enable-metrics="true"
+  telemetry-collector-url="https://collector.jaak.ai/v1/traces"
+  metrics-collector-url="https://collector.jaak.ai/v1/metrics"
+  metrics-export-interval-millis="60000"
+  propagate-trace-header-cors-urls="https://api.example.com,https://backend.example.com"
+  customer-id="customer123"
+  tenant-id="tenant456"
+  environment="production"
+  trace-id="optional-custom-trace-id">
+</jaak-stamps>
+```
+
+### Using Trace ID
+
+The component automatically generates a unique trace ID for each session, or accepts a custom one:
+
+```javascript
+const scanner = document.getElementById('documentScanner');
+
+// Listen for trace ID generation
+scanner.addEventListener('traceIdGenerated', (event) => {
+  const traceId = event.detail.traceId;
+  console.log('Trace ID for this session:', traceId);
+
+  // Use this traceId to correlate requests in your backend
+  fetch('/api/process-document', {
+    method: 'POST',
+    headers: {
+      'X-Trace-Id': traceId,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ /* data */ })
+  });
+});
+```
+
+### Enriched Attributes
+
+Traces and metrics automatically include:
+
+- **User Agent:** Browser, version, operating system
+- **Geolocation:** Country, region, city (when available)
+- **Device Memory:** Device memory capacity
+- **Customer Context:** `customerId`, `tenantId`, `environment`
+- **Service Info:** Service name, component version
+
+### Context Propagation (CORS)
+
+To propagate traces to your backend services:
+
+```html
+<jaak-stamps
+  propagate-trace-header-cors-urls="https://api.example.com,https://services.example.com">
+</jaak-stamps>
+```
+
+This automatically configures `fetch` and `XMLHttpRequest` interceptors to include the `traceparent` header in requests to those URLs.
+
+### Visualization with Jaeger/Zipkin
+
+Exported traces are compatible with:
+- **Jaeger** - Distributed tracing system
+- **Zipkin** - Alternative tracing system
+- **Grafana Tempo** - Grafana trace backend
+- Any OTLP-compatible backend (OpenTelemetry Protocol)
+
+## License Validation
+
+The component **requires a valid license** to function. Validation occurs automatically when the component loads.
+
+### License Configuration
+
+```html
+<jaak-stamps
+  license="your-license-key-here"
+  license-environment="prod"
+  app-id="my-application">
+</jaak-stamps>
+```
+
+### Available Environments
+
+| Environment | Validation URL | Use Case |
+|-------------|---------------|----------|
+| `dev` | `https://api.dev.jaak.ai` | Local development |
+| `qa` | `https://api.qa.jaak.ai` | Quality assurance testing |
+| `sandbox` | `https://api.sandbox.jaak.ai` | Integration testing |
+| `prod` | `https://services.api.jaak.ai` | Production |
+
+### License Error Handling
+
+If the license is invalid, the component will display an error and not function:
+
+```javascript
+const scanner = document.getElementById('documentScanner');
+
+scanner.addEventListener('isReady', (event) => {
+  if (!event.detail) {
+    console.error('Error: Invalid license or component not initialized');
+  }
+});
+```
+
+**Common error messages:**
+- `"License key is required"` - No license provided
+- `"Invalid license key"` - Invalid or expired license
+- `"License validation failed"` - Validation error
+
 ## Style Guide
 
 ### CSS Custom Properties

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaak.ai/stamps",
-  "version": "2.2.0-dev.10",
+  "version": "2.2.0-dev.12",
   "description": "Jaak Document Identifier",
   "main": "dist/index.cjs.js",
   "module": "dist/index.js",