npm - @jaak.ai/stamps - Versions diffs - 2.1.0-dev.9 → 2.2.0-beta.1 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (79) hide show

package/README.md CHANGED Viewed

@@ -56,19 +56,49 @@ yarn add @jaak.ai/stamps
 ### Properties/Attributes
+#### License Properties (Required)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `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
@@ -152,6 +182,7 @@ preloadModel(): Promise<{
 |-------|-------------|-------------|
 | `isReady` | `boolean` | Fired when component is fully initialized and ready |
 | `captureCompleted` | `object` | Fired when document capture process is completed |
+| `traceIdGenerated` | `{ traceId: string }` | Fired after license validation with the generated or provided trace ID for request tracing |
 ### Type Definitions
@@ -206,6 +237,9 @@ interface StatusResponse {
 <body>
   <jaak-stamps
     id="documentScanner"
+    license="your-license-key-here"
+    environment="prod"
+    app-id="my-custom-app"
     preferred-camera="auto"
     capture-delay="1500"
     use-document-detector="true"
@@ -214,23 +248,29 @@ interface StatusResponse {
   <script>
     const scanner = document.getElementById('documentScanner');
+    // Handle trace ID generation
+    scanner.addEventListener('traceIdGenerated', (event) => {
+      console.log('Trace ID for this session:', event.detail.traceId);
+      // Use this trace ID for correlating requests across your system
+    });
     // Wait for component to be ready
     scanner.addEventListener('isReady', () => {
       console.log('Document scanner is ready');
       // Start the capture process
       scanner.startCapture();
     });
     // Handle capture completion
     scanner.addEventListener('captureCompleted', async (event) => {
       console.log('Capture completed:', event.detail);
       // Get captured images
       const images = await scanner.getCapturedImages();
       console.log('Captured images:', images);
       // Process the images as needed
       if (images.front.cropped) {
         // Display or upload the cropped front image
@@ -285,22 +325,29 @@ const DocumentScanner: React.FC = () => {
     const scanner = scannerRef.current;
     if (!scanner) return;
+    // Trace ID generation handler
+    const handleTraceIdGenerated = (event: CustomEvent) => {
+      console.log('Trace ID:', event.detail.traceId);
+    };
     // Component ready handler
     const handleReady = () => {
       setIsReady(true);
     };
     // Capture completion handler
     const handleCaptureCompleted = async () => {
       const images = await (scanner as any).getCapturedImages();
       setCapturedImages(images);
     };
     // Add event listeners
+    scanner.addEventListener('traceIdGenerated', handleTraceIdGenerated);
     scanner.addEventListener('isReady', handleReady);
     scanner.addEventListener('captureCompleted', handleCaptureCompleted);
     return () => {
+      scanner.removeEventListener('traceIdGenerated', handleTraceIdGenerated);
       scanner.removeEventListener('isReady', handleReady);
       scanner.removeEventListener('captureCompleted', handleCaptureCompleted);
     };
@@ -318,6 +365,10 @@ const DocumentScanner: React.FC = () => {
       <jaak-stamps
         ref={scannerRef}
+        license="your-license-key-here"
+        environment="prod"
+        app-id="my-react-app"
+        trace-id=""  // Leave empty to auto-generate
         preferred-camera="auto"
         capture-delay={1500}
         use-document-classification={true}
@@ -390,6 +441,9 @@ interface CapturedImages {
       <jaak-stamps
         #scanner
+        license="your-license-key-here"
+        environment="prod"
+        app-id="my-angular-app"
         preferred-camera="auto"
         [capture-delay]="1500"
         [use-document-classification]="true"
@@ -506,12 +560,17 @@ export class DocumentScannerComponent implements AfterViewInit {
   ngAfterViewInit() {
     const scanner = this.scannerRef.nativeElement;
+    // Trace ID generation handler
+    scanner.addEventListener('traceIdGenerated', (event: CustomEvent) => {
+      console.log('Trace ID:', event.detail.traceId);
+    });
     // Component ready handler
     scanner.addEventListener('isReady', () => {
       this.isReady = true;
     });
     // Capture completion handler
     scanner.addEventListener('captureCompleted', async () => {
       this.capturedImages = await scanner.getCapturedImages();
@@ -548,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/dist/cjs/app-globals-V2Kpy_OQ.js ADDED Viewed

@@ -0,0 +1,8 @@
+'use strict';
+const globalScripts = () => {};
+exports.globalScripts = globalScripts;
+//# sourceMappingURL=app-globals-V2Kpy_OQ.js.map
+//# sourceMappingURL=app-globals-V2Kpy_OQ.js.map

package/dist/cjs/app-globals-V2Kpy_OQ.js.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"app-globals-V2Kpy_OQ.js","sources":["@stencil/core/internal/app-globals"],"sourcesContent":["export const globalScripts = () => {};\nexport const globalStyles = \"\";\n"],"names":[],"mappings":";;AAAY,MAAC,aAAa,GAAG,MAAM;;;;"}