tango-app-api-audio-analytics 1.0.0

package/COHORT_API.md

@@ -0,0 +1,513 @@
+# Cohort API Documentation
+
+## Overview
+The Cohort API manages cohort creation, retrieval, and analytics for the Tango Audio Analytics system. Cohorts are templates that define specific evaluation criteria and metrics for analyzing audio conversations.
+
+## Base URL
+```
+https://testtangoretail-api.tangoeye.ai/v3/audio-analitics
+```
+
+## Database
+- **Search Engine**: OpenSearch
+- **Index Name**: `tango-audio-cohort`
+- **Document ID**: Auto-generated UUID
+
+## Validation
+All requests are validated using Joi schema validation from the `tango-app-api-middleware` package.
+
+---
+
+## Endpoints
+
+### 1. Create Cohort
+Create a new cohort with defined metrics and contexts.
+
+**Endpoint**
+```
+POST /cohorts
+```
+
+**Request Body**
+```json
+{
+  "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
+    }
+  ]
+}
+```
+
+**Response (201 Created)**
+```json
+{
+  "status": "success",
+  "message": "Cohort created successfully",
+  "data": {
+    "cohortId": "cohort_photochromatic_001",
+    "cohortName": "Photochromatic",
+    "clientId": "11",
+    "documentId": "550e8400-e29b-41d4-a716-446655440000",
+    "createdAt": "2026-03-03T10:30:00Z",
+    "metricsCount": 6
+  },
+  "timestamp": "2026-03-03T10:30:00Z"
+}
+```
+
+**Validation Rules**
+- `clientId`: Required, string
+- `cohortId`: Required, string (alphanumeric, hyphens, underscores only)
+- `cohortName`: Required, 3-100 characters
+- `cohortDescription`: Required, 10-500 characters
+- `metrics`: Required, array with 1-50 items
+- Each metric must have: `metricId`, `metricName`, `metricDescription`, `hasContext`, `isNumneric`
+
+---
+
+### 2. Get Cohort by ID
+Retrieve a specific cohort by its cohort ID.
+
+**Endpoint**
+```
+GET /cohorts/:cohortId
+```
+
+**Example**
+```
+GET /cohorts/cohort_photochromatic_001
+```
+
+**Response (200 OK)**
+```json
+{
+  "status": "success",
+  "data": {
+    "documentId": "550e8400-e29b-41d4-a716-446655440000",
+    "clientId": "11",
+    "cohortId": "cohort_photochromatic_001",
+    "cohortName": "Photochromatic",
+    "cohortDescription": "A strict evaluation...",
+    "metrics": [
+      {
+        "metricId": "pitch_quality_001",
+        "metricName": "Standard Pitch Quality",
+        "contexts": [...]
+      }
+    ],
+    "createdAt": "2026-03-03T10:30:00Z",
+    "updatedAt": "2026-03-03T10:30:00Z"
+  },
+  "timestamp": "2026-03-03T10:30:00Z"
+}
+```
+
+---
+
+### 3. Get Cohorts by Client
+Retrieve all cohorts for a specific client with pagination.
+
+**Endpoint**
+```
+GET /cohorts/client/:clientId?limit=10&offset=0
+```
+
+**Query Parameters**
+- `limit` (optional): Results per page (default: 10, max: 100)
+- `offset` (optional): Pagination offset (default: 0)
+
+**Example**
+```
+GET /cohorts/client/11?limit=5&offset=0
+```
+
+**Response (200 OK)**
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "documentId": "550e8400-e29b-41d4-a716-446655440000",
+      "clientId": "11",
+      "cohortId": "cohort_photochromatic_001",
+      "cohortName": "Photochromatic",
+      "createdAt": "2026-03-03T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 15,
+    "limit": 5,
+    "offset": 0,
+    "hasMore": true
+  },
+  "timestamp": "2026-03-03T10:30:00Z"
+}
+```
+
+---
+
+### 4. Search Cohorts
+Search for cohorts by multiple criteria (clientId, cohortId, or cohortName).
+
+**Endpoint**
+```
+POST /cohorts/search
+```
+
+**Request Body**
+```json
+{
+  "clientId": "11",
+  "cohortName": "Photochrom",
+  "limit": 10,
+  "offset": 0
+}
+```
+
+**Response (200 OK)**
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "documentId": "550e8400-e29b-41d4-a716-446655440000",
+      "cohortId": "cohort_photochromatic_001",
+      "cohortName": "Photochromatic",
+      "clientId": "11",
+      "createdAt": "2026-03-03T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 1,
+    "limit": 10,
+    "offset": 0,
+    "hasMore": false
+  },
+  "timestamp": "2026-03-03T10:30:00Z"
+}
+```
+
+---
+
+### 5. Update Cohort
+Update cohort name, description, or metrics.
+
+**Endpoint**
+```
+PUT /cohorts/:documentId
+```
+
+**Request Body** (Partial update)
+```json
+{
+  "cohortName": "Updated Photochromatic",
+  "cohortDescription": "Updated description",
+  "metrics": [...]
+}
+```
+
+**Response (200 OK)**
+```json
+{
+  "status": "success",
+  "message": "Cohort updated successfully",
+  "data": {
+    "documentId": "550e8400-e29b-41d4-a716-446655440000",
+    "cohortName": "Updated Photochromatic",
+    "updatedAt": "2026-03-03T11:00:00Z"
+  },
+  "timestamp": "2026-03-03T11:00:00Z"
+}
+```
+
+---
+
+### 6. Delete Cohort
+Delete a cohort from OpenSearch.
+
+**Endpoint**
+```
+DELETE /cohorts/:documentId
+```
+
+**Example**
+```
+DELETE /cohorts/550e8400-e29b-41d4-a716-446655440000
+```
+
+**Response (200 OK)**
+```json
+{
+  "status": "success",
+  "message": "Cohort deleted successfully",
+  "timestamp": "2026-03-03T11:00:00Z"
+}
+```
+
+---
+
+### 7. Get Cohort Analytics
+Retrieve cohort analytics and metrics summary.
+
+**Endpoint**
+```
+GET /cohorts/:cohortId/analytics
+```
+
+**Example**
+```
+GET /cohorts/cohort_photochromatic_001/analytics
+```
+
+**Response (200 OK)**
+```json
+{
+  "status": "success",
+  "data": {
+    "cohortId": "cohort_photochromatic_001",
+    "cohortName": "Photochromatic",
+    "clientId": "11",
+    "totalMetrics": 6,
+    "metrics": [
+      {
+        "metricId": "pitch_quality_001",
+        "metricName": "Standard Pitch Quality",
+        "isNumneric": false,
+        "contextCount": 4,
+        "contexts": [...]
+      }
+    ],
+    "createdAt": "2026-03-03T10:30:00Z",
+    "updatedAt": "2026-03-03T10:30:00Z"
+  },
+  "timestamp": "2026-03-03T11:00:00Z"
+}
+```
+
+---
+
+## Error Responses
+
+### 400 Bad Request - Validation Error
+```json
+{
+  "status": "error",
+  "message": "Validation failed",
+  "code": "VALIDATION_ERROR",
+  "details": [
+    {
+      "field": "cohortName",
+      "message": "\"cohortName\" length must be at least 3 characters long",
+      "type": "string.min"
+    }
+  ],
+  "timestamp": "2026-03-03T10:30:00Z"
+}
+```
+
+### 404 Not Found
+```json
+{
+  "status": "error",
+  "message": "Cohort not found",
+  "code": "COHORT_NOT_FOUND",
+  "timestamp": "2026-03-03T10:30:00Z"
+}
+```
+
+### 409 Conflict - Cohort Already Exists
+```json
+{
+  "status": "error",
+  "message": "Cohort with this ID already exists",
+  "code": "COHORT_EXISTS",
+  "timestamp": "2026-03-03T10:30:00Z"
+}
+```
+
+### 500 Internal Server Error
+```json
+{
+  "status": "error",
+  "message": "Internal server error",
+  "code": "INTERNAL_ERROR",
+  "timestamp": "2026-03-03T10:30:00Z"
+}
+```
+
+---
+
+## Data Structure
+
+### Cohort Document
+```json
+{
+  "documentId": "UUID",
+  "clientId": "string",
+  "cohortId": "string",
+  "cohortName": "string",
+  "cohortDescription": "string",
+  "metrics": [
+    {
+      "metricId": "string",
+      "metricName": "string",
+      "metricDescription": "string",
+      "hasContext": boolean,
+      "isNumneric": boolean,
+      "contexts": [...]
+    }
+  ],
+  "isActive": true,
+  "version": "1.0",
+  "createdAt": "ISO-8601 timestamp",
+  "updatedAt": "ISO-8601 timestamp"
+}
+```
+
+---
+
+## Implementation Notes
+
+### OpenSearch Integration
+- Uses `insert(index, documentId, document)` function from `tango-app-api-middleware`
+- Auto-generates UUID for each document
+- Stores metadata (createdAt, updatedAt, isActive, version)
+- Search operations use Elasticsearch Query DSL
+
+### Validation
+- All requests validated using Joi schemas
+- Custom validation schemas in `src/validations/cohort.validation.js`
+- Validation middleware in `src/middlewares/validation.middleware.js`
+
+### Service Layer
+- Cohort operations in `src/services/cohort.service.js`
+- Handles all OpenSearch CRUD operations
+- Error handling with specific error codes
+
+### Controller Layer
+- API handlers in `src/controllers/cohort.controller.js`
+- Request validation and response formatting
+- Comprehensive logging via `tango-app-api-middleware`