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

package/docs/condition-node.md

@@ -1,651 +0,0 @@
-# Condition Node Documentation
-
-## Overview
-
-The Condition Node is a powerful workflow component that enables conditional branching based on dynamic data evaluation. It allows you to create decision points in your session flow by evaluating expressions against session data, analysis results, user input, and document controls.
-
-## Table of Contents
-
-- [Basic Concepts](#basic-concepts)
-- [Node Configuration](#node-configuration)
-- [Token Types](#token-types)
-- [Supported Operators](#supported-operators)
-- [Data Resolution](#data-resolution)
-- [Examples](#examples)
-- [Best Practices](#best-practices)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## Basic Concepts
-
-### What is a Condition Node?
-
-A Condition Node evaluates one or more expressions and routes the workflow to different paths based on the result:
-- **True path**: Taken when the condition evaluates to `true`
-- **False path**: Taken when the condition evaluates to `false`
-
-### Key Features
-
-- **Dynamic Data Access**: Access data from analysis results, user input, session state, and document controls
-- **Multiple Operators**: Support for comparison (`==`, `!=`, `>`, `<`, etc.) and logical (`&&`, `||`) operators
-- **Type Coercion**: Automatic conversion between strings, numbers, and booleans
-- **Nested Properties**: Access deeply nested data using dot notation
-- **Hash-based References**: Reference analysis data using document template IDs
-
----
-
-## Node Configuration
-
-### Template Structure
-
-```typescript
-{
-  "id": "node-condition-123",
-  "type": "condition",
-  "title": "Verify Document Quality",
-  "description": "Check if document meets quality requirements",
-  "conditionExpression": "chipIsPresent && photoQuality >= 0.8",
-  "conditionTokens": [
-    {
-      "type": "control",
-      "value": "c979478e6459d7441b161ca8.chipIsPresent",
-      "label": "Chip Present",
-      "sourceNodeId": "node-document-check-456"
-    },
-    {
-      "type": "operator",
-      "value": "&&",
-      "label": "AND"
-    },
-    {
-      "type": "control",
-      "value": "c979478e6459d7441b161ca8.photoQuality",
-      "label": "Photo Quality",
-      "sourceNodeId": "node-document-check-456"
-    },
-    {
-      "type": "operator",
-      "value": ">=",
-      "label": ">="
-    },
-    {
-      "type": "input",
-      "value": "0.8",
-      "label": "0.8"
-    }
-  ]
-}
-```
-
-### Edge Configuration
-
-```typescript
-{
-  "edges": [
-    {
-      "source": "node-condition-123",
-      "target": "node-success-path",
-      "sourceHandle": "true"  // or conditionValue: "true"
-    },
-    {
-      "source": "node-condition-123",
-      "target": "node-failure-path",
-      "sourceHandle": "false"
-    }
-  ]
-}
-```
-
----
-
-## Token Types
-
-### 1. Input (Literal Values)
-
-Fixed values provided in the condition expression.
-
-**Supported Types:**
-- **String**: `"DUPONT"`, `"approved"`
-- **Number**: `18`, `0.95`, `-5`
-- **Boolean**: `true`, `false`
-- **Date**: `"2024-01-01"` (converted to timestamp)
-
-**Example:**
-```typescript
-{
-  "type": "input",
-  "value": "\"DUPONT\"",
-  "label": "\"DUPONT\""
-}
-```
-
-### 2. Variable (Dynamic Session Data)
-
-Access data from session state, user input, or contact information.
-
-**Common Paths:**
-- `session.result.{property}`
-- `session.userInput.{property}`
-- `session.contactInfo.{property}`
-- `userInput.{property}`
-- `contactInfo.{property}`
-
-**Example:**
-```typescript
-{
-  "type": "variable",
-  "value": "userInput.age",
-  "label": "User Age"
-}
-```
-
-### 3. Control (Document Analysis Results)
-
-Access control values and extracted information from document analysis.
-
-**Path Format:** `{documentTemplateId}.{property}`
-
-**Sources:**
-- **Control Categories**: Quality checks and validation results
-  - `controlCategories.visual.controls.{property}.value`
-  - `controlCategories.metadata.controls.{property}.value`
-  - `controlCategories.dataCoherency.controls.{property}.value`
-- **Extracted Information**: OCR and document data
-  - `extractedInformations.{property}` (returns `{confidence, value}`, automatically extracts `.value`)
-
-**Example:**
-```typescript
-{
-  "type": "control",
-  "value": "7dc8ad327dacbd5dcc78ef1c.chipIsPresent",
-  "label": "Chip Present",
-  "sourceNodeId": "node-document-check-456"
-}
-```
-
-**Important:** The `sourceNodeId` is required to correctly identify which analysis entry to query.
-
-### 4. Operator
-
-Comparison and logical operators.
-
-**Example:**
-```typescript
-{
-  "type": "operator",
-  "value": "==",
-  "label": "="
-}
-```
-
----
-
-## Supported Operators
-
-### Comparison Operators
-
-| Operator | Description | Example |
-|----------|-------------|---------|
-| `==` | Loose equality | `age == 18` |
-| `===` | Strict equality | `status === "approved"` |
-| `!=` | Loose inequality | `result != "pending"` |
-| `!==` | Strict inequality | `type !== "temporary"` |
-| `>` | Greater than | `score > 80` |
-| `>=` | Greater or equal | `confidence >= 0.9` |
-| `<` | Less than | `attempts < 3` |
-| `<=` | Less or equal | `age <= 65` |
-
-### Logical Operators
-
-| Operator | Description | Example |
-|----------|-------------|---------|
-| `&&` | AND | `chipIsPresent && photoIsPresent` |
-| `||` | OR | `documentExpired || qualityLow` |
-
-### Operator Precedence
-
-Evaluation is **left-to-right** with logical operators applied sequentially:
-```javascript
-a && b || c && d
-// Evaluates as: ((a && b) || c) && d
-```
-
-**Recommendation:** Use parentheses in complex expressions for clarity (handled by the builder UI).
-
----
-
-## Data Resolution
-
-### Resolution Order
-
-For a path like `{hash}.{property}`, the evaluator searches in this order:
-
-1. **Session Direct Properties**
-   - `session.result.{property}`
-   - `session.userInput.{property}`
-   - `session.contactInfo.{property}`
-
-2. **Analysis Entry (if `sourceNodeId` provided)**
-   - Finds analysis entry where `nodeId === sourceNodeId`
-   - Skips 24-character hex hash (document template ID)
-   - Searches in associated document:
-     - **Control Categories**: `controlCategories.{category}.controls.{property}.value`
-     - **Extracted Information**: `extractedInformations.{property}.value`
-     - Direct properties on the document
-
-3. **Legacy Identifier Matching** (fallback)
-   - Matches first segment with: `documentTemplateId`, `documentTypeId`, `documentId`, `id`, `name`
-
-### Hash-based References
-
-The builder generates 24-character hex IDs (e.g., `c979478e6459d7441b161ca8`) to reference document templates. These are automatically detected and skipped during resolution.
-
-**Builder Path:**
-```
-c979478e6459d7441b161ca8.lastName
-```
-
-**Actual Resolution:**
-1. Detect hash: `c979478e6459d7441b161ca8` (matches `/^[a-f0-9]{24}$/i`)
-2. Skip hash, resolve: `lastName`
-3. Find in `documents[].extractedInformations.lastName`
-
-### Value Extraction
-
-API responses often return values with confidence scores:
-
-```json
-{
-  "lastName": {
-    "confidence": 0.95,
-    "value": "DUPONT"
-  }
-}
-```
-
-The evaluator **automatically extracts** the `.value` property for comparison:
-```javascript
-// API returns: {confidence: 0.95, value: "DUPONT"}
-// Comparison uses: "DUPONT"
-lastName == "DUPONT"  // ✅ true
-```
-
----
-
-## Examples
-
-### Example 1: Document Quality Check
-
-**Condition:** Check if both chip and photo are present
-
-```typescript
-{
-  "conditionExpression": "chipIsPresent && photoIsPresent",
-  "conditionTokens": [
-    {
-      "type": "control",
-      "value": "d71eb9480bfd97be5d193183.chipIsPresent",
-      "sourceNodeId": "node-id-check-123"
-    },
-    {"type": "operator", "value": "&&"},
-    {
-      "type": "control",
-      "value": "d71eb9480bfd97be5d193183.photoIsPresent",
-      "sourceNodeId": "node-id-check-123"
-    }
-  ]
-}
-```
-
-**Data Resolution:**
-```javascript
-// Finds document with analysisId matching node-id-check-123
-// Looks in: controlCategories.visual.controls.chipIsPresent.value
-// Returns: true
-
-// Looks in: controlCategories.visual.controls.photoIsPresent.value
-// Returns: true
-
-// Result: true && true = true → Takes "true" path
-```
-
-### Example 2: Age Verification
-
-**Condition:** User must be 18 or older
-
-```typescript
-{
-  "conditionExpression": "age >= 18",
-  "conditionTokens": [
-    {
-      "type": "variable",
-      "value": "userInput.age"
-    },
-    {"type": "operator", "value": ">="},
-    {
-      "type": "input",
-      "value": "18"
-    }
-  ]
-}
-```
-
-### Example 3: Name Matching
-
-**Condition:** Verify extracted name matches user input
-
-```typescript
-{
-  "conditionExpression": "extractedLastName == inputLastName",
-  "conditionTokens": [
-    {
-      "type": "control",
-      "value": "7dc8ad327dacbd5dcc78ef1c.lastName",
-      "sourceNodeId": "node-doc-collection-456"
-    },
-    {"type": "operator", "value": "=="},
-    {
-      "type": "variable",
-      "value": "userInput.lastName"
-    }
-  ]
-}
-```
-
-**Data:**
-```javascript
-// Document extractedInformations:
-{
-  "lastName": {
-    "confidence": 1,
-    "value": "DUPONT"
-  }
-}
-
-// User input:
-{
-  "lastName": "DUPONT"
-}
-
-// Comparison: "DUPONT" == "DUPONT" → true
-```
-
-### Example 4: Complex Multi-Condition
-
-**Condition:** Document valid AND (score high OR manual review approved)
-
-```typescript
-{
-  "conditionExpression": "!documentExpired && (qualityScore >= 0.8 || manualApproved)",
-  "conditionTokens": [
-    {
-      "type": "control",
-      "value": "hash.documentExpired",
-      "sourceNodeId": "node-doc-123"
-    },
-    {"type": "operator", "value": "&&"},
-    {
-      "type": "control",
-      "value": "hash.qualityScore",
-      "sourceNodeId": "node-doc-123"
-    },
-    {"type": "operator", "value": ">="},
-    {"type": "input", "value": "0.8"},
-    {"type": "operator", "value": "||"},
-    {
-      "type": "variable",
-      "value": "result.manualApproved"
-    }
-  ]
-}
-```
-
-### Example 5: Boolean (Truthy) Check
-
-**Condition:** Check if a value is truthy (no comparison operator)
-
-```typescript
-{
-  "conditionExpression": "documentVerified",
-  "conditionTokens": [
-    {
-      "type": "control",
-      "value": "hash.isVerified",
-      "sourceNodeId": "node-doc-123"
-    }
-  ]
-}
-```
-
-**Truthy Evaluation:**
-- `true`, non-zero numbers, non-empty strings → `true`
-- `false`, `0`, `""`, `null`, `undefined` → `false`
-
----
-
-## Best Practices
-
-### 1. Always Provide sourceNodeId
-
-**✅ Good:**
-```typescript
-{
-  "type": "control",
-  "value": "hash.lastName",
-  "sourceNodeId": "node-doc-check-123"
-}
-```
-
-**❌ Bad:**
-```typescript
-{
-  "type": "control",
-  "value": "hash.lastName"
-  // Missing sourceNodeId - may find wrong analysis entry
-}
-```
-
-### 2. Use Specific Property Paths
-
-**✅ Good:**
-```typescript
-"userInput.firstName"  // Clear and specific
-```
-
-**❌ Bad:**
-```typescript
-"firstName"  // Ambiguous - which source?
-```
-
-### 3. Handle Missing Data
-
-Consider fallback paths or default values:
-
-```typescript
-// Check if property exists before comparison
-documentStatus && documentStatus == "approved"
-```
-
-### 4. Type-Aware Comparisons
-
-Use strict equality when type matters:
-
-```typescript
-age === 18    // Number comparison
-status === "approved"  // String comparison
-```
-
-Use loose equality for flexible matching:
-
-```typescript
-score == "80"  // Matches number 80 or string "80"
-```
-
-### 5. Document Template ID Tracking
-
-Keep track of which hash corresponds to which document type in your builder:
-
-```typescript
-// Document mapping in builder:
-{
-  "passport": "c979478e6459d7441b161ca8",
-  "idCard": "7dc8ad327dacbd5dcc78ef1c",
-  "driverLicense": "a1b2c3d4e5f6789012345678"
-}
-```
-
----
-
-## Troubleshooting
-
-### Condition Always Returns False
-
-**Check:**
-1. Verify `sourceNodeId` matches the analysis node ID
-2. Inspect browser console for resolution logs
-3. Confirm property path exists in session/analysis data
-4. Check for type mismatches (string vs number)
-
-**Debug Logs:**
-```javascript
-// Look for these in browser console:
-[ConditionEvaluator] Tokens received: [...]
-[ResolvePathValue] Found in extractedInformations: {...}
-[EvaluateComparison] left == right → result
-```
-
-### Value Not Found
-
-**Common Causes:**
-1. **Wrong sourceNodeId**: Points to different analysis entry
-2. **Hash not recognized**: Should be 24-character hex
-3. **Property name mismatch**: Check exact spelling and case
-4. **Data not yet available**: Ensure analysis completed before condition
-
-**Solution:**
-```javascript
-// Fetch fresh session data
-await fetchSessionById(sessionId)
-// Check analysis.length > 0
-// Verify documents array populated
-```
-
-### Type Comparison Fails
-
-**Issue:** Comparing string with number
-
-```javascript
-// API returns: age = "25" (string)
-// Condition: age > 18
-
-// Fix: Use loose comparison or ensure types match
-age >= 18  // Coerces string "25" to number 25
-```
-
-### Object Comparison
-
-**Issue:** Comparing object instead of value
-
-```javascript
-// Extracted data: {confidence: 1, value: "DUPONT"}
-// Comparison: lastName == "DUPONT"
-
-// ✅ Automatic extraction: "DUPONT" == "DUPONT"
-// The evaluator handles this automatically
-```
-
-### Missing Documents Array
-
-**Issue:** `documents` array not populated in session
-
-**Solution:**
-Ensure the backend returns documents with analysis:
-
-```json
-{
-  "analysis": [{
-    "id": "analysis-123",
-    "nodeId": "node-doc-check"
-  }],
-  "documents": [{
-    "analysisId": "analysis-123",
-    "extractedInformations": {...},
-    "controlCategories": {...}
-  }]
-}
-```
-
----
-
-## API Reference
-
-### ConditionToken Interface
-
-```typescript
-interface ConditionToken {
-  type: "input" | "variable" | "control" | "operator";
-  value: string;
-  label?: string;
-  sourceNodeId?: string;
-}
-```
-
-### ConditionEvaluationContext Interface
-
-```typescript
-interface ConditionEvaluationContext {
-  session: SessionData;
-  userInput?: UserInput | Record<string, unknown>;
-  contactInfo?: ContactInfo | Record<string, unknown>;
-}
-```
-
-### Key Functions
-
-```typescript
-// Evaluate condition tokens
-evaluateConditionTokens(
-  tokens: ConditionToken[],
-  context: ConditionEvaluationContext
-): boolean
-
-// Parse expression string to tokens
-parseConditionExpression(
-  expression?: string
-): ConditionToken[]
-```
-
----
-
-## Migration Notes
-
-### From Previous Versions
-
-If upgrading from an older version:
-
-1. **Add sourceNodeId**: Update existing condition tokens to include `sourceNodeId`
-2. **Update Hash Matching**: 24-char hex hashes are now automatically detected
-3. **Value Extraction**: Objects with `{confidence, value}` are auto-extracted
-4. **Control Categories**: Support for nested control category lookups
-
-### Breaking Changes
-
-- Requires `sourceNodeId` for accurate analysis resolution
-- Hash-based paths must be 24 hex characters to be recognized
-- Session must include `documents` array for control/variable resolution
-
----
-
-## Support
-
-For additional help:
-- Check browser console for detailed logs
-- Review session data structure in API responses
-- Verify template configuration in builder
-- Contact support with session ID and condition configuration
-
----
-
-**Version:** 1.0.0  
-**Last Updated:** December 2025