tango-app-api-audio-analytics 1.0.0

package/COHORT_API_EXAMPLES.sh

@@ -0,0 +1,235 @@
+#!/bin/bash
+
+# Cohort API Test Examples
+# This file contains curl commands to test all cohort API endpoints
+
+BASE_URL="https://testtangoretail-api.tangoeye.ai/v3/audio-analitics"
+COHORT_ID="cohort_photochromatic_001"
+CLIENT_ID="11"
+
+# ==================== Helper Function ====================
+print_section() {
+  echo ""
+  echo "=================================="
+  echo "$1"
+  echo "=================================="
+}
+
+# ==================== 1. CREATE COHORT ====================
+print_section "1. CREATE COHORT"
+
+curl -X POST "$BASE_URL/cohorts" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "11",
+    "cohortId": "cohort_photochromatic_001",
+    "cohortName": "Photochromatic",
+    "cohortDescription": "A strict evaluation of the photochromatic sales journey, focusing on pitch quality, technical accuracy, and customer sentiment",
+    "metrics": [
+      {
+        "metricId": "pitch_quality_001",
+        "metricName": "Standard Pitch Quality",
+        "metricDescription": "Identify which specific value propositions were explicitly used by the staff",
+        "hasContext": true,
+        "isNumneric": false,
+        "contexts": [
+          {
+            "contextName": "ONE_GLASS_ALL_NEEDS",
+            "priority": 2,
+            "description": "Convenience of one pair for all lighting"
+          },
+          {
+            "contextName": "TRAVEL_CONVENIENCE",
+            "priority": 2,
+            "description": "Specific benefits for bikers/commuters"
+          },
+          {
+            "contextName": "LIGHT_ADAPTATION",
+            "priority": 2,
+            "description": "Technical explanation of UV reaction"
+          },
+          {
+            "contextName": "REDUCES_EYE_STRAIN",
+            "priority": 2,
+            "description": "Glare and fatigue protection"
+          }
+        ]
+      },
+      {
+        "metricId": "technical_depth_score_001",
+        "metricName": "Technical Depth Score",
+        "metricDescription": "A numeric evaluation of the staff'\''s product knowledge during the pitch",
+        "hasContext": true,
+        "isNumneric": true,
+        "contexts": [
+          {
+            "minValue": 0,
+            "maxValue": 100
+          }
+        ]
+      },
+      {
+        "metricId": "customer_sentiment_001",
+        "metricName": "Initial Customer Sentiment",
+        "metricDescription": "The immediate reaction of the customer when the lens was introduced",
+        "hasContext": true,
+        "isNumneric": false,
+        "contexts": [
+          {
+            "contextName": "POSITIVE",
+            "priority": 2,
+            "description": "High interest or curiosity"
+          },
+          {
+            "contextName": "NEUTRAL",
+            "priority": 1,
+            "description": "Acknowledgment or price-focused only"
+          },
+          {
+            "contextName": "NEGATIVE",
+            "priority": 0,
+            "description": "Dismissive or disinterested"
+          }
+        ]
+      },
+      {
+        "metricId": "staff_responsiveness_001",
+        "metricName": "Staff Responsiveness",
+        "metricDescription": "How effectively were customer doubts addressed?",
+        "hasContext": true,
+        "isNumneric": false,
+        "contexts": [
+          {
+            "contextName": "FULLY_RESPONSIVE",
+            "priority": 2,
+            "description": "All doubts cleared with evidence"
+          },
+          {
+            "contextName": "PARTIALLY_RESPONSIVE",
+            "priority": 1,
+            "description": "Some doubts addressed, others ignored"
+          },
+          {
+            "contextName": "UNRESPONSIVE",
+            "priority": 0,
+            "description": "Customer doubts were dismissed"
+          }
+        ]
+      },
+      {
+        "metricId": "sales_outcome_001",
+        "metricName": "Final Sales Outcome",
+        "metricDescription": "The final commitment level reached at the end of the conversation",
+        "hasContext": true,
+        "isNumneric": false,
+        "contexts": [
+          {
+            "contextName": "BOUGHT_PHOTOCHROMATIC",
+            "priority": 2,
+            "description": "Customer agreed to the upgrade"
+          },
+          {
+            "contextName": "BOUGHT_SOMETHING_ELSE",
+            "priority": 0,
+            "description": "Bought standard lenses/frames only"
+          },
+          {
+            "contextName": "NO_SALE",
+            "priority": 0,
+            "description": "No purchase commitment"
+          }
+        ]
+      },
+      {
+        "metricId": "pitch_timing_summary_001",
+        "metricName": "Pitch Timing & Context",
+        "metricDescription": "Narrative summary of when and how the pitch was introduced",
+        "hasContext": false,
+        "isNumneric": false
+      }
+    ]
+  }'
+
+# ==================== 2. GET COHORT BY ID ====================
+print_section "2. GET COHORT BY ID"
+
+curl -X GET "$BASE_URL/cohorts/$COHORT_ID" \
+  -H "Content-Type: application/json"
+
+# ==================== 3. GET COHORTS BY CLIENT ====================
+print_section "3. GET COHORTS BY CLIENT"
+
+curl -X GET "$BASE_URL/cohorts/client/$CLIENT_ID?limit=10&offset=0" \
+  -H "Content-Type: application/json"
+
+# ==================== 4. SEARCH COHORTS ====================
+print_section "4. SEARCH COHORTS"
+
+curl -X POST "$BASE_URL/cohorts/search" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "11",
+    "cohortName": "Photochrom",
+    "limit": 10,
+    "offset": 0
+  }'
+
+# ==================== 5. UPDATE COHORT ====================
+print_section "5. UPDATE COHORT"
+
+# Note: Replace DOCUMENT_ID with actual ID returned from create
+DOCUMENT_ID="550e8400-e29b-41d4-a716-446655440000"
+
+curl -X PUT "$BASE_URL/cohorts/$DOCUMENT_ID" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "cohortName": "Updated Photochromatic",
+    "cohortDescription": "Updated description for photochromatic cohort"
+  }'
+
+# ==================== 6. GET COHORT ANALYTICS ====================
+print_section "6. GET COHORT ANALYTICS"
+
+curl -X GET "$BASE_URL/cohorts/$COHORT_ID/analytics" \
+  -H "Content-Type: application/json"
+
+# ==================== 7. DELETE COHORT ====================
+print_section "7. DELETE COHORT"
+
+# Note: Replace DOCUMENT_ID with actual ID
+curl -X DELETE "$BASE_URL/cohorts/$DOCUMENT_ID" \
+  -H "Content-Type: application/json"
+
+# ==================== VALIDATION TESTS ====================
+print_section "VALIDATION TESTS"
+
+echo "Testing invalid cohort name (too short):"
+curl -X POST "$BASE_URL/cohorts" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "11",
+    "cohortId": "invalid_test",
+    "cohortName": "AB",
+    "cohortDescription": "This should fail because name is too short"
+  }'
+
+echo ""
+echo "Testing missing required field:"
+curl -X POST "$BASE_URL/cohorts" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "11",
+    "cohortId": "invalid_test",
+    "cohortName": "Valid Name"
+  }'
+
+echo ""
+echo "Testing invalid cohortId (special characters):"
+curl -X POST "$BASE_URL/cohorts" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "11",
+    "cohortId": "invalid@test",
+    "cohortName": "Valid Name",
+    "cohortDescription": "This should fail because cohortId has invalid characters"
+  }'

package/COHORT_API_IMPLEMENTATION.md

@@ -0,0 +1,296 @@
+# Cohort API Implementation Summary
+
+## Overview
+A complete Cohort API has been implemented with full OpenSearch integration using the `tango-app-api-middleware` package. The API supports creating, retrieving, searching, updating, and deleting cohorts with Joi validation.
+
+## Files Created/Modified
+
+### 1. Validation Schema (`src/validations/cohort.validation.js`)
+- **Purpose**: Define Joi validation schemas for cohort operations
+- **Schemas**:
+  - `cohortCreationSchema` - Validates new cohort data
+  - `cohortUpdateSchema` - Validates cohort updates (partial)
+  - `cohortQuerySchema` - Validates search/query parameters
+- **Features**:
+  - Recursive validation of nested metrics and contexts
+  - Alphanumeric validation for cohort IDs
+  - String length validation
+  - Numeric range validation
+  - `validateCohortData()` helper function
+
+### 2. Cohort Service (`src/services/cohort.service.js`)
+- **Purpose**: Handle all OpenSearch CRUD operations
+- **OpenSearch Index**: `tango-audio-cohort`
+- **Functions**:
+  - `createCohort()` - Insert cohort with auto-generated UUID
+  - `getCohortById()` - Retrieve by cohort ID
+  - `getCohortsByClientId()` - Paginated retrieval by client
+  - `searchCohorts()` - Fuzzy search by multiple criteria
+  - `updateCohort()` - Update cohort metadata
+  - `deleteCohort()` - Remove cohort
+  - `getCohortAnalytics()` - Get metrics summary
+  - `cohortExists()` - Check existence
+- **Features**:
+  - Uses `insert()` with document ID from `tango-app-api-middleware`
+  - Automatic timestamp management
+  - Comprehensive error handling
+  - Logging via `tango-app-api-middleware`
+
+### 3. Cohort Controller (`src/controllers/cohort.controller.js`)
+- **Purpose**: API endpoint handlers
+- **Endpoints**:
+  - `createCohort()` - POST /cohorts
+  - `getCohort()` - GET /cohorts/:cohortId
+  - `getCohortsByClient()` - GET /cohorts/client/:clientId
+  - `searchCohortsEndpoint()` - POST /cohorts/search
+  - `updateCohort()` - PUT /cohorts/:documentId
+  - `deleteCohort()` - DELETE /cohorts/:documentId
+  - `getCohortAnalyticsEndpoint()` - GET /cohorts/:cohortId/analytics
+- **Features**:
+  - Joi validation integration
+  - Duplicate cohort detection
+  - Comprehensive error responses
+  - Detailed request/response logging
+
+### 4. Validation Middleware (`src/middlewares/validation.middleware.js`)
+**Added Functions**:
+- `validateCohortCreation()` - Validates POST /cohorts requests
+- `validateCohortUpdate()` - Validates PUT requests
+- `validateCohortQuery()` - Validates search/query requests
+- **Features**:
+  - Uses Joi schemas
+  - Provides detailed error feedback
+  - Sets `req.validatedData` for controller use
+
+### 5. Router Updates (`src/routes/audioAnalytics.routes.js`)
+**New Routes Added**:
+```
+POST   /cohorts                      - Create cohort
+GET    /cohorts/:cohortId            - Get by ID
+GET    /cohorts/client/:clientId     - Get by client
+POST   /cohorts/search               - Search cohorts
+PUT    /cohorts/:documentId          - Update cohort
+DELETE /cohorts/:documentId          - Delete cohort
+GET    /cohorts/:cohortId/analytics  - Get analytics
+```
+
+## Data Schema
+
+### Cohort Document Structure
+```json
+{
+  "documentId": "UUID (auto-generated)",
+  "clientId": "string (required)",
+  "cohortId": "string (required, alphanumeric with - and _)",
+  "cohortName": "string (3-100 chars)",
+  "cohortDescription": "string (10-500 chars)",
+  "metrics": [
+    {
+      "metricId": "string",
+      "metricName": "string",
+      "metricDescription": "string",
+      "hasContext": "boolean",
+      "isNumneric": "boolean",
+      "contexts": [
+        {
+          "contextName": "string",
+          "priority": "number (0-2)",
+          "description": "string",
+          "minValue": "number (optional)",
+          "maxValue": "number (optional)"
+        }
+      ]
+    }
+  ],
+  "isActive": "boolean (default: true)",
+  "version": "string (default: 1.0)",
+  "createdAt": "ISO-8601 timestamp",
+  "updatedAt": "ISO-8601 timestamp"
+}
+```
+
+## OpenSearch Integration
+
+### Index Configuration
+- **Index Name**: `tango-audio-cohort`
+- **Document ID**: UUID v4 (auto-generated)
+- **Operations**: insert, search, update, delete
+
+### Functions Used
+- `insert(index, documentId, document)` - From `tango-app-api-middleware`
+- `search(index, query)` - From `tango-app-api-middleware`
+- `update(index, documentId, document)` - From `tango-app-api-middleware`
+- `delete(index, documentId)` - From `tango-app-api-middleware`
+
+### Search Queries
+```javascript
+// Search by exact match
+{
+  query: {
+    match: {
+      cohortId: "cohort_photochromatic_001"
+    }
+  }
+}
+
+// Fuzzy search
+{
+  query: {
+    match: {
+      cohortName: {
+        query: "Photochrom",
+        fuzziness: "AUTO"
+      }
+    }
+  }
+}
+
+// Multiple criteria (bool query)
+{
+  query: {
+    bool: {
+      must: [
+        { match: { clientId: "11" } },
+        { match: { cohortId: "cohort_photochromatic_001" } }
+      ]
+    }
+  }
+}
+```
+
+## API Endpoints
+
+### 1. Create Cohort (POST /cohorts)
+- **Status**: 201 Created / 400 Bad Request / 409 Conflict / 500 Error
+- **Validation**: Full cohort schema validation
+- **Returns**: Created cohort with documentId
+
+### 2. Get Cohort (GET /cohorts/:cohortId)
+- **Status**: 200 OK / 404 Not Found / 500 Error
+- **Returns**: Full cohort document with all metrics
+
+### 3. Get by Client (GET /cohorts/client/:clientId)
+- **Status**: 200 OK / 500 Error
+- **Pagination**: limit (default 10), offset (default 0)
+- **Returns**: Array of cohorts with pagination metadata
+
+### 4. Search Cohorts (POST /cohorts/search)
+- **Status**: 200 OK / 400 Bad Request / 500 Error
+- **Criteria**: clientId, cohortId, cohortName, limit, offset
+- **Returns**: Matching cohorts with pagination
+
+### 5. Update Cohort (PUT /cohorts/:documentId)
+- **Status**: 200 OK / 400 Bad Request / 500 Error
+- **Fields**: Partial update (cohortName, cohortDescription, metrics)
+- **Returns**: Updated cohort with new updatedAt timestamp
+
+### 6. Delete Cohort (DELETE /cohorts/:documentId)
+- **Status**: 200 OK / 500 Error
+- **Returns**: Deletion confirmation
+
+### 7. Get Analytics (GET /cohorts/:cohortId/analytics)
+- **Status**: 200 OK / 404 Not Found / 500 Error
+- **Returns**: Analytics summary with metrics breakdown
+
+## Validation Rules
+
+### Cohort Creation
+| Field | Type | Rules | Example |
+|-------|------|-------|---------|
+| clientId | string | Required | "11" |
+| cohortId | string | Required, alphanumeric with - _ | "cohort_photo_001" |
+| cohortName | string | Required, 3-100 chars | "Photochromatic" |
+| cohortDescription | string | Required, 10-500 chars | "A strict evaluation..." |
+| metrics | array | Required, 1-50 items | [...] |
+
+### Metric Fields
+| Field | Type | Rules |
+|-------|------|-------|
+| metricId | string | Required |
+| metricName | string | Required |
+| metricDescription | string | Required |
+| hasContext | boolean | Required |
+| isNumneric | boolean | Required |
+| contexts | array | Required if hasContext=true |
+
+### Context Fields (if hasContext=true)
+| Field | Type | Rules | Example |
+|-------|------|-------|---------|
+| contextName | string | Required | "POSITIVE" |
+| priority | number | Required, 0-2 | 2 |
+| description | string | Required | "High interest..." |
+| minValue | number | Optional (for numeric) | 0 |
+| maxValue | number | Optional (for numeric) | 100 |
+
+## Error Handling
+
+### Error Response Format
+```json
+{
+  "status": "error",
+  "message": "Human-readable error message",
+  "code": "ERROR_CODE",
+  "details": [...],
+  "timestamp": "ISO-8601"
+}
+```
+
+### Common Error Codes
+- `VALIDATION_ERROR` - 400 - Failed schema validation
+- `COHORT_EXISTS` - 409 - Duplicate cohort ID
+- `COHORT_NOT_FOUND` - 404 - Cohort doesn't exist
+- `COHORT_CREATE_ERROR` - 500 - Creation failed
+- `COHORT_SEARCH_ERROR` - 500 - Search/retrieval failed
+- `INTERNAL_ERROR` - 500 - Server error
+
+## Logging
+
+All operations are logged via `tango-app-api-middleware` logger:
+- `logger.info()` - Successful operations
+- `logger.warn()` - Validation warnings
+- `logger.error()` - Errors with stack traces
+
+## Usage Examples
+
+### Create a Cohort
+```bash
+curl -X POST https://api.example.com/v3/audio-analitics/cohorts \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "11",
+    "cohortId": "cohort_photochromatic_001",
+    ...
+  }'
+```
+
+### Search Cohorts
+```bash
+curl -X POST https://api.example.com/v3/audio-analitics/cohorts/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "11",
+    "cohortName": "Photochrom",
+    "limit": 10
+  }'
+```
+
+## Testing
+
+Use `COHORT_API_EXAMPLES.sh` for curl-based testing:
+```bash
+bash COHORT_API_EXAMPLES.sh
+```
+
+## Next Steps
+
+1. Install required dependencies: `npm install joi`
+2. Configure OpenSearch connection in `tango-app-api-middleware`
+3. Test endpoints using provided curl examples
+4. Integrate with conversation analyzers to apply cohort metrics
+5. Build dashboard to visualize cohort analytics
+
+## Documentation Files
+
+- `COHORT_API.md` - Complete API documentation
+- `COHORT_API_EXAMPLES.sh` - Curl command examples
+- `COHORT_API_IMPLEMENTATION.md` - This implementation summary