datakeen-session-react 1.1.195-dev.8 → 1.1.195-dev.9

package/docs/POLLING_SYSTEM.md

@@ -1,699 +0,0 @@
-# Enhanced Polling System - Complete Documentation
-
-## Overview
-
-The enhanced polling system now supports multiple analyses per session by tracking analysis status through the `analysisId` field. This ensures accurate progress tracking even when multiple documents are analyzed in the same session, with user-friendly status messages and real-time updates.
-
-**Key Features:**
-- ✅ Multiple analyses per session support
-- ✅ Accurate 50% vs 100% progress tracking
-- ✅ User-friendly, non-technical status messages
-- ✅ Real-time polling every 2 seconds
-- ✅ Proper error handling and retry logic
-- ✅ Document code included in response
-- ✅ Backward compatible
-
----
-
-## How It Works
-
-### Backend Flow Diagram
-
-```
-┌──────────────┐
-│   Submit     │
-│  Document    │
-└──────┬───────┘
-       │
-       ▼
-┌──────────────────────────────────────┐
-│  analysisId = null                   │
-│  Progress: 50%                       │
-│  Message: "Analyzing your documents..."│
-└──────┬───────────────────────────────┘
-       │ (Backend processing...)
-       │
-       ▼
-┌──────────────────────────────────────┐
-│  analysisId = [analysis-id]          │
-│  Progress: 100%                      │
-│  Message: Based on analysis result   │
-│  Code: From document entry           │
-└──────────────────────────────────────┘
-```
-
-### Status Flow
-
-1. **Analysis Start** - When `POST /session/sdk/{sessionId}/analysis` is called:
-   - The `analysisId` field in the session is set to `null`
-   - This indicates that an analysis is in progress
-
-2. **Analysis Progress** - While analyzing (analysisId = null):
-   - `GET /session/sdk/{sessionId}/analysis-status` returns:
-     - `status: "processing"`
-     - `progress: 50`
-     - `currentStep: "analyzing"`
-     - `message: "Analyzing your documents..."`
-     - `code: null`
-
-3. **Analysis Complete** - When analysis finishes:
-   - The `analysisId` field is set to the completed analysis ID
-   - Document code is extracted from the database
-
-4. **Results Available** - After completion (analysisId = set):
-   - `GET /session/sdk/{sessionId}/analysis-status` returns:
-     - `status: "completed"`
-     - `progress: 100`
-     - `currentStep: "approved" | "rejected" | "to_verify" | "failed"`
-     - User-friendly message based on the result
-     - `code: "1.0" | "2.0" | "3.0" | "4.0"`
-
----
-
-## Status Mapping Reference
-
-### Complete Status Table
-
-| Backend Status | analysisId | Progress | Step | User Message | Code | Icon | Retry? |
-|---------------|-----------|----------|------|--------------|------|------|--------|
-| (processing) | `null` | 50% | `analyzing` | "Analyzing your documents..." | `null` | 🔄 | - |
-| `ai_approved` / `completed` | Set | 100% | `approved` | "Document verified successfully ✓" | `1.0` | ✅ | No |
-| `ai_rejected` | Set | 100% | `rejected` | "Document verification failed" | `2.0` | ❌ | Yes* |
-| `to_verify` | Set | 100% | `to_verify` | "Manual verification required" | `4.0` | ⏳ | No |
-| `failed` / `error` | Set | 100% | `failed` | "Analysis error occurred" | `3.0` | ❌ | Yes* |
-
-*Retry allowed depending on error type (network errors always allow retry)
-
-### Code Meanings
-
-| Code | Meaning | Status |
-|------|---------|--------|
-| `1.0` | Conform - Document approved | ✅ Success |
-| `2.0` | Rejected - Document rejected | ❌ Failure |
-| `3.0` | Error - Analysis error | ❌ Failure |
-| `4.0` | To Verify - Manual verification needed | ⏳ Pending |
-
----
-
-## API Response Examples
-
-### During Analysis (50% - Processing)
-
-```json
-{
-  "sessionId": "9a5e33c6b601d64d394f35db",
-  "status": "processing",
-  "progress": 50,
-  "currentStep": "analyzing",
-  "message": "Analyzing your documents...",
-  "analysisId": null,
-  "code": null,
-  "startedAt": "2025-11-05T10:00:00Z",
-  "completedAt": null
-}
-```
-
-### After Approval (100% - Approved)
-
-```json
-{
-  "sessionId": "9a5e33c6b601d64d394f35db",
-  "status": "completed",
-  "progress": 100,
-  "currentStep": "approved",
-  "message": "Document verified successfully ✓",
-  "analysisId": "690b26e7e1bc042feb0cf671",
-  "analysisStatus": "ai_approved",
-  "code": "1.0",
-  "codeName": "conform",
-  "codeDescription": "The document has been fully verified by the AI, it is valid and conform",
-  "startedAt": "2025-11-05T10:00:00Z",
-  "completedAt": "2025-11-05T10:01:30Z"
-}
-```
-
-### After Rejection (100% - Rejected)
-
-```json
-{
-  "sessionId": "9a5e33c6b601d64d394f35db",
-  "status": "completed",
-  "progress": 100,
-  "currentStep": "rejected",
-  "message": "Document verification failed",
-  "analysisId": "690b26e7e1bc042feb0cf671",
-  "analysisStatus": "ai_rejected",
-  "code": "2.0",
-  "codeName": "rejected",
-  "codeDescription": "The document does not meet verification requirements",
-  "startedAt": "2025-11-05T10:00:00Z",
-  "completedAt": "2025-11-05T10:01:30Z"
-}
-```
-
-### Manual Verification (100% - To Verify)
-
-```json
-{
-  "sessionId": "9a5e33c6b601d64d394f35db",
-  "status": "completed",
-  "progress": 100,
-  "currentStep": "to_verify",
-  "message": "Manual verification required",
-  "analysisId": "690b26e7e1bc042feb0cf671",
-  "analysisStatus": "to_verify",
-  "code": "4.0",
-  "codeName": "to_verify",
-  "codeDescription": "Manual verification is required for this document",
-  "startedAt": "2025-11-05T10:00:00Z",
-  "completedAt": "2025-11-05T10:01:30Z"
-}
-```
-
-### Analysis Error (100% - Failed)
-
-```json
-{
-  "sessionId": "9a5e33c6b601d64d394f35db",
-  "status": "completed",
-  "progress": 100,
-  "currentStep": "failed",
-  "message": "Analysis error occurred",
-  "analysisId": "690b26e7e1bc042feb0cf671",
-  "analysisStatus": "failed",
-  "code": "3.0",
-  "codeName": "error",
-  "codeDescription": "An error occurred during analysis",
-  "startedAt": "2025-11-05T10:00:00Z",
-  "completedAt": "2025-11-05T10:01:30Z"
-}
-```
-
-### Analysis Refused by the Service (quota / out of credits)
-
-When the backend refuses the analysis itself (engine quota reached, or the organisation's overdraft cap reached), it stores a fallback document (`code: "api_failure"`) whose `codeName` tells the cause: `quota_exceeded` or `insufficient_credits`. The SDK maps it to `QUOTA_EXCEEDED` / `INSUFFICIENT_CREDITS` (`getServiceErrorCodeFromCodeName`, `src/utils/analysisErrors.ts`), fails the step and shows `user_guidance.<code>` on the error screen (document, JDI, document video). The same codes returned synchronously by an HTTP error (`429 QUOTA_EXCEEDED`, `403 INSUFFICIENT_CREDITS`) are read by `getServiceErrorCode`.
-
----
-
-## Frontend Usage
-
-### Basic Example
-
-```typescript
-import { analyzeFiles } from '@datakeen/session-react-sdk';
-
-const result = await analyzeFiles(
-  sessionId,
-  files,
-  documentTypeId,
-  {
-    enablePolling: true,
-    pollingOptions: {
-      onProgress: (status) => {
-        console.log(`${status.progress}%: ${status.message}`);
-        updateProgressBar(status.progress);
-      },
-      onComplete: (status) => {
-        console.log('Analysis completed!', status);
-        console.log('Document code:', status.code);
-        
-        // Handle based on code
-        switch (status.code) {
-          case '1.0': // Approved
-            showSuccessMessage();
-            break;
-          case '2.0': // Rejected
-            showRejectionMessage();
-            break;
-          case '4.0': // To Verify
-            showPendingMessage();
-            break;
-          default:
-            showErrorMessage();
-        }
-      },
-      onFailed: (status, error) => {
-        console.error('Analysis failed:', error);
-        showErrorMessage();
-      },
-    },
-  }
-);
-```
-
-### React Component Example
-
-```tsx
-import React, { useState } from 'react';
-import { analyzeFiles } from '@datakeen/session-react-sdk';
-
-function DocumentAnalysis({ sessionId, files, documentTypeId }) {
-  const [progress, setProgress] = useState(0);
-  const [message, setMessage] = useState('');
-  const [isAnalyzing, setIsAnalyzing] = useState(false);
-  const [code, setCode] = useState<string | null>(null);
-
-  const handleAnalyze = async () => {
-    setIsAnalyzing(true);
-    setProgress(0);
-    
-    try {
-      await analyzeFiles(sessionId, files, documentTypeId, {
-        enablePolling: true,
-        pollingOptions: {
-          interval: 2000, // Poll every 2 seconds
-          
-          onProgress: (status) => {
-            setProgress(status.progress);
-            setMessage(status.message);
-          },
-          
-          onComplete: (status) => {
-            setProgress(100);
-            setMessage(status.message);
-            setCode(status.code);
-            
-            // Handle different outcomes
-            switch (status.code) {
-              case '1.0': // Approved
-                console.log('✅ Document approved');
-                break;
-              case '2.0': // Rejected
-                console.log('❌ Document rejected');
-                break;
-              case '4.0': // To Verify
-                console.log('⏳ Requires manual verification');
-                break;
-              case '3.0': // Error
-              default:
-                console.log('❌ Analysis error');
-            }
-          },
-          
-          onFailed: (status, error) => {
-            setMessage('Analysis failed: ' + error);
-          },
-        },
-      });
-    } finally {
-      setIsAnalyzing(false);
-    }
-  };
-
-  const getProgressColor = () => {
-    if (code === '1.0') return 'bg-green-500';
-    if (code === '2.0' || code === '3.0') return 'bg-red-500';
-    if (code === '4.0') return 'bg-yellow-500';
-    return 'bg-blue-500';
-  };
-
-  return (
-    <div className="max-w-2xl mx-auto p-6">
-      <button 
-        onClick={handleAnalyze} 
-        disabled={isAnalyzing}
-        className="w-full py-3 px-4 bg-blue-600 text-white rounded-lg font-semibold"
-      >
-        {isAnalyzing ? 'Analyzing...' : 'Analyze Document'}
-      </button>
-      
-      {/* Progress Bar */}
-      <div className="mt-6">
-        <div className="flex justify-between mb-2">
-          <span className="text-sm font-medium">Progress</span>
-          <span className="text-sm font-medium">{progress}%</span>
-        </div>
-        <div className="w-full bg-gray-200 rounded-full h-3">
-          <div 
-            className={`h-3 rounded-full transition-all duration-300 ${getProgressColor()}`}
-            style={{ width: `${progress}%` }}
-          />
-        </div>
-      </div>
-      
-      {/* Status Message */}
-      <p className="mt-4 text-center font-medium text-gray-700">
-        {message}
-      </p>
-      
-      {/* Code Display */}
-      {code && (
-        <div className="mt-4 p-3 bg-gray-50 rounded-lg text-center">
-          <p className="text-sm text-gray-600">Document Code</p>
-          <p className="text-xl font-bold">{code}</p>
-        </div>
-      )}
-    </div>
-  );
-}
-```
-
-### React Hook for Reusability
-
-```typescript
-import { useState } from 'react';
-import { analyzeFiles } from '@datakeen/session-react-sdk';
-import type { AnalysisStatusResponse } from '@datakeen/session-react-sdk/services/pollingService';
-
-export function useAnalysis(sessionId: string) {
-  const [progress, setProgress] = useState(0);
-  const [message, setMessage] = useState('');
-  const [code, setCode] = useState<string | null>(null);
-  const [status, setStatus] = useState<'idle' | 'processing' | 'completed' | 'failed'>('idle');
-
-  const analyze = async (files: any, documentTypeId: string) => {
-    setStatus('processing');
-    setProgress(0);
-    
-    try {
-      await analyzeFiles(sessionId, files, documentTypeId, {
-        enablePolling: true,
-        pollingOptions: {
-          onProgress: (pollStatus: AnalysisStatusResponse) => {
-            setProgress(pollStatus.progress);
-            setMessage(pollStatus.message);
-          },
-          onComplete: (pollStatus: AnalysisStatusResponse) => {
-            setProgress(100);
-            setMessage(pollStatus.message);
-            setCode(pollStatus.code);
-            setStatus('completed');
-          },
-          onFailed: (pollStatus, error) => {
-            setMessage('Analysis failed: ' + error);
-            setStatus('failed');
-          },
-        },
-      });
-    } catch (error) {
-      setStatus('failed');
-      setMessage('Error: ' + (error as Error).message);
-    }
-  };
-
-  return { progress, message, code, status, analyze };
-}
-
-// Usage
-function MyComponent() {
-  const { progress, message, code, status, analyze } = useAnalysis(sessionId);
-
-  return (
-    <div>
-      <button onClick={() => analyze(files, documentTypeId)}>
-        Analyze
-      </button>
-      <p>{progress}% - {message}</p>
-      {code && <p>Code: {code}</p>}
-    </div>
-  );
-}
-```
-
----
-
-## Multiple Analyses Per Session
-
-The system now correctly handles multiple analyses in the same session:
-
-```typescript
-// First analysis
-const result1 = await analyzeFiles(
-  sessionId, 
-  frontBackFiles, 
-  'driver-license', 
-  {
-    incrementAnalysis: true, // Create new analysis
-    enablePolling: true,
-  }
-);
-
-// Second analysis (same session)
-const result2 = await analyzeFiles(
-  sessionId, 
-  proofOfAddressFiles, 
-  'proof-of-address', 
-  {
-    incrementAnalysis: true, // Create another new analysis
-    enablePolling: true,
-  }
-);
-```
-
-Each analysis will:
-1. Clear the `analysisId` (progress = 50%)
-2. Process the documents
-3. Set the new `analysisId` when complete (progress = 100%)
-4. Return the appropriate result status with code
-
----
-
-## Configuration Options
-
-### Polling Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `interval` | number | 2000 | Milliseconds between polls |
-| `maxAttempts` | number | 300 | Maximum number of poll attempts (10 min) |
-| `timeout` | number | 600000 | Total timeout in milliseconds |
-| `onProgress` | function | - | Callback for progress updates |
-| `onComplete` | function | - | Callback when analysis completes |
-| `onFailed` | function | - | Callback when analysis fails |
-
-### Analysis Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enablePolling` | boolean | true | Enable automatic progress polling |
-| `incrementAnalysis` | boolean | true | Create new analysis |
-| `save` | boolean | true | Save analysis results |
-| `forceUpload` | boolean | false | Force re-upload of files |
-| `documentTypeKey` | string | - | Document type identifier |
-| `requiresTwoSides` | boolean | - | Whether document has two sides |
-
----
-
-## API Endpoints
-
-### Get Analysis Status
-
-```http
-GET /backend/session/sdk/{sessionId}/analysis-status
-
-Response: AnalysisStatusResponse (see examples above)
-```
-
-### Submit Analysis
-
-```http
-POST /backend/session/sdk/{sessionId}/analysis
-
-Side Effect: Clears analysisId to null (sets progress to 50%)
-Response: HTTP 202 Accepted
-```
-
----
-
-## UI Display Recommendations
-
-### Progress Indicator Colors
-
-| Progress | Status | Color | Hex |
-|----------|--------|-------|-----|
-| 50% | Processing | Blue | `#3B82F6` |
-| 100% | Approved | Green | `#10B981` |
-| 100% | Rejected | Red | `#EF4444` |
-| 100% | To Verify | Yellow | `#F59E0B` |
-| 100% | Failed | Red | `#EF4444` |
-
-### Icon Recommendations
-
-| Status | Icon | Emoji | HTML |
-|--------|------|-------|------|
-| Processing | Loading spinner | 🔄 | `<i class="fas fa-spinner fa-spin"></i>` |
-| Approved | Checkmark | ✓ | `<i class="fas fa-check-circle"></i>` |
-| Rejected | X mark | ✕ | `<i class="fas fa-times-circle"></i>` |
-| To Verify | Clock | ⏳ | `<i class="fas fa-clock"></i>` |
-| Failed | Alert | ⚠️ | `<i class="fas fa-exclamation-triangle"></i>` |
-
----
-
-## Translation Keys
-
-### English
-
-```json
-{
-  "analysis.status.processing": "Analyzing your documents...",
-  "analysis.status.approved": "Document verified successfully ✓",
-  "analysis.status.rejected": "Document verification failed",
-  "analysis.status.to_verify": "Manual verification required",
-  "analysis.status.failed": "Analysis error occurred"
-}
-```
-
-### French
-
-```json
-{
-  "analysis.status.processing": "Analyse de vos documents en cours...",
-  "analysis.status.approved": "Document vérifié avec succès ✓",
-  "analysis.status.rejected": "Vérification du document échouée",
-  "analysis.status.to_verify": "Vérification manuelle requise",
-  "analysis.status.failed": "Erreur d'analyse"
-}
-```
-
----
-
-## Troubleshooting
-
-### Issue: Polling never completes
-**Diagnosis:**
-```bash
-# Check backend logs for analysis errors
-tail -f /var/log/app-backend.log | grep "SESSION"
-
-# Check if analysisId is being set
-db.sessions.findOne({_id: ObjectId("your-session-id")})
-```
-
-**Solutions:**
-- Verify analysis is actually completing
-- Check for errors in analysis service
-- Ensure `analysisId` is being set after completion
-- Check network connectivity
-
-### Issue: Wrong status message or code
-**Diagnosis:**
-```typescript
-// Check raw response in browser console
-console.log('Full response:', status);
-console.log('Code:', status.code);
-console.log('Step:', status.currentStep);
-```
-
-**Solutions:**
-- Verify code is being extracted from document
-- Check document entry in database
-- Review logs for actual analysis outcome
-- Verify status mapping in backend
-
-### Issue: Code is undefined
-**Solution:** Ensure the backend response includes the `code` field from the document database entry. If documents exist but code is missing, check the document schema and update it with the code field.
-
----
-
-## Best Practices
-
-1. **Always enable polling** for better UX
-2. **Use onProgress callback** to update UI in real-time
-3. **Handle all outcomes** (approved, rejected, to_verify, failed)
-4. **Show user-friendly messages** from the status response
-5. **Check the code** for deterministic decision making
-6. **Implement retry logic** for failed analyses with code `2.0` or `3.0`
-7. **Test with multiple analyses** in the same session
-8. **Log status** for debugging and analytics
-
----
-
-## Database Schema
-
-```sql
--- sessions table
-CREATE TABLE sessions (
-  id VARCHAR(255) PRIMARY KEY,
-  analysisId VARCHAR(255) NULL,  -- NULL = processing, SET = completed
-  status VARCHAR(50),
-  createdAt TIMESTAMP,
-  updatedAt TIMESTAMP
-);
-
--- analysisruns table
-CREATE TABLE analysisruns (
-  id VARCHAR(255) PRIMARY KEY,
-  status VARCHAR(50),  -- 'completed', 'rejected', 'to_verify', 'failed', etc.
-  createdAt TIMESTAMP,
-  updatedAt TIMESTAMP
-);
-
--- documents table (MongoDB example)
-db.documents.find({
-  analysisId: ObjectId("..."),
-  code: "1.0",  // Conformity code
-  codeName: "conform",
-  codeDescription: "...",
-  status: "ai_approved"
-})
-```
-
----
-
-## Monitoring & Debugging
-
-### Check Current Status
-
-```sql
-SELECT 
-  s.id as session_id,
-  s.analysisId,
-  s.status as session_status,
-  ar.status as analysis_status,
-  s.createdAt,
-  ar.updatedAt as analysis_completed_at
-FROM sessions s
-LEFT JOIN analysisruns ar ON s.analysisId = ar.id
-WHERE s.id = 'your-session-id';
-```
-
-### Check Document Code
-
-```javascript
-db.documents.findOne({
-  sessionId: ObjectId("your-session-id"),
-  analysisId: ObjectId("your-analysis-id")
-}, {
-  code: 1,
-  codeName: 1,
-  status: 1,
-  extractedInformations: 1
-})
-```
-
-### Expected Results
-
-| analysisId | Progress | Code | Status | Meaning |
-|-----------|----------|------|--------|---------|
-| `null` | 50% | `null` | processing | Analysis in progress |
-| Set | 100% | `1.0` | completed | Approved ✅ |
-| Set | 100% | `2.0` | completed | Rejected ❌ |
-| Set | 100% | `3.0` | completed | Error ❌ |
-| Set | 100% | `4.0` | completed | To Verify ⏳ |
-
----
-
-## Performance Metrics
-
-- **Polling interval**: 2 seconds (optimized for UX and server load)
-- **Max polling duration**: 10 minutes (300 attempts × 2s)
-- **Typical analysis time**: 5-30 seconds
-- **Network overhead**: Minimal (status endpoint is lightweight)
-- **Request size**: ~300 bytes
-- **Response size**: ~400 bytes
-
----
-
-## Support & Resources
-
-- **Backend Implementation**: `src/session/session.service.ts`
-- **Frontend Polling**: `src/services/pollingService.ts`
-- **UI Component**: `src/components/jdi/JDIProcessing.tsx`
-- **Examples**: `examples/analysis-progress-example.tsx`
-- **Types**: `src/types/session.ts`, `src/services/pollingService.ts`
-
----
-
-**Version**: 2.0.0 (Enhanced Polling with Document Code)  
-**Last Updated**: November 5, 2025  
-**Status**: ✅ Production Ready