tango-app-api-audio-analytics 1.0.0

package/COHORT_API_QUICKSTART.md

@@ -0,0 +1,387 @@
+# Cohort API - Quick Start Guide
+
+## Project Structure
+```
+src/
+├── controllers/
+│   ├── cohortAnalytics.controller.js       ✅ (7 endpoints)
+│   └── conversationAnalytics.controller.js
+├── services/
+│   └── cohort.service.js                   ✅ (7 CRUD operations)
+├── models/
+│   └── (ready for database models)
+├── routes/
+│   └── audioAnalytics.routes.js            ✅ (updated with 7 cohort routes)
+├── middlewares/
+│   └── validation.middleware.js            ✅ (3 cohort validators added)
+├── dtos/
+│   └── audioAnalytics.dtos.js              ✅ (17 DTO classes)
+├── validations/
+│   └── cohort.validation.js                ✅ (Joi schemas)
+└── utils/
+```
+
+## Installation
+
+```bash
+# Required dependency (if not already installed)
+npm install joi
+
+# The tango-app-api-middleware is already available
+const { insert, search, update, delete } = require('tango-app-api-middleware');
+```
+
+## Quick Integration
+
+### 1. Import Cohort Endpoints
+Already integrated in `src/routes/audioAnalytics.routes.js`:
+```javascript
+const {
+  createCohort,
+  getCohort,
+  getCohortsByClient,
+  searchCohortsEndpoint,
+  updateCohort,
+  deleteCohort,
+  getCohortAnalyticsEndpoint
+} = require('../controllers/cohort.controller');
+
+const {
+  validateCohortCreation,
+  validateCohortUpdate,
+  validateCohortQuery
+} = require('../middlewares/validation.middleware');
+```
+
+### 2. Available Routes
+```javascript
+// READ
+GET /cohorts/:cohortId                     // Get single cohort
+GET /cohorts/client/:clientId              // Get by client (paginated)
+GET /cohorts/:cohortId/analytics           // Get analytics
+
+// CREATE
+POST /cohorts                              // Create new cohort
+
+// SEARCH
+POST /cohorts/search                       // Search with filters
+
+// UPDATE
+PUT /cohorts/:documentId                   // Update cohort
+
+// DELETE
+DELETE /cohorts/:documentId                // Delete cohort
+```
+
+## Common Tasks
+
+### Create a Cohort
+```javascript
+// Request
+POST /cohorts
+{
+  "clientId": "11",
+  "cohortId": "cohort_example_001",
+  "cohortName": "Example Cohort",
+  "cohortDescription": "A test cohort with metrics",
+  "metrics": [
+    {
+      "metricId": "metric_1",
+      "metricName": "Engagement",
+      "metricDescription": "Customer engagement level",
+      "hasContext": true,
+      "isNumneric": true,
+      "contexts": [
+        {
+          "contextName": "HIGH",
+          "priority": 2,
+          "description": "High engagement",
+          "minValue": 80,
+          "maxValue": 100
+        }
+      ]
+    }
+  ]
+}
+
+// Response (201 Created)
+{
+  "status": "success",
+  "data": {
+    "documentId": "550e8400-e29b-41d4-a716-446655440000",
+    "clientId": "11",
+    "cohortId": "cohort_example_001",
+    ...
+  }
+}
+```
+
+### Get a Cohort
+```javascript
+GET /cohorts/cohort_example_001
+
+// Response (200 OK)
+{
+  "status": "success",
+  "data": { ...cohort document... }
+}
+```
+
+### Search Cohorts
+```javascript
+POST /cohorts/search
+{
+  "clientId": "11",
+  "cohortName": "Example",
+  "limit": 10,
+  "offset": 0
+}
+
+// Response (200 OK)
+{
+  "status": "success",
+  "data": {
+    "cohorts": [...],
+    "total": 5,
+    "limit": 10,
+    "offset": 0
+  }
+}
+```
+
+### Update a Cohort
+```javascript
+PUT /cohorts/550e8400-e29b-41d4-a716-446655440000
+{
+  "cohortName": "Updated Cohort Name",
+  "metrics": [...]
+}
+
+// Response (200 OK)
+{
+  "status": "success",
+  "data": { ...updated cohort... }
+}
+```
+
+### Delete a Cohort
+```javascript
+DELETE /cohorts/550e8400-e29b-41d4-a716-446655440000
+
+// Response (200 OK)
+{
+  "status": "success",
+  "message": "Cohort deleted successfully"
+}
+```
+
+### Get Analytics
+```javascript
+GET /cohorts/cohort_example_001/analytics
+
+// Response (200 OK)
+{
+  "status": "success",
+  "data": {
+    "cohortId": "cohort_example_001",
+    "metricsCount": 6,
+    "metrics": [
+      {
+        "metricId": "metric_1",
+        "metricName": "Engagement",
+        "contextsCount": 3
+      }
+    ]
+  }
+}
+```
+
+## Validation Reference
+
+### Cohort ID Format
+- Must be alphanumeric with hyphens and underscores
+- Examples: `cohort_001`, `cohort-test`, `test123`
+- Invalid: `cohort@001`, `cohort.test`, `Cohort_001` (uppercase)
+
+### Cohort Name
+- Minimum 3 characters, maximum 100 characters
+- Any UTF-8 characters allowed
+- Required field
+
+### Cohort Description
+- Minimum 10 characters, maximum 500 characters
+- Any UTF-8 characters allowed
+- Required field
+
+### Metrics Array
+- Minimum 1 metric, maximum 50 metrics
+- Each metric requires: metricId, metricName, metricDescription, hasContext, isNumneric
+- If hasContext is true, contexts array is required with at least 1 context
+
+### Contexts
+- contextName (required)
+- priority: 0, 1, or 2 (required)
+- description (required, any length)
+- minValue, maxValue (optional, for numeric metrics)
+
+## Error Handling
+
+### Common Error Responses
+
+**400 - Validation Error**
+```json
+{
+  "status": "error",
+  "message": "Validation failed",
+  "code": "VALIDATION_ERROR",
+  "details": [
+    "cohortName must be at least 3 characters",
+    "clientId is required"
+  ],
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+**409 - Cohort Exists**
+```json
+{
+  "status": "error",
+  "message": "Cohort with ID 'cohort_001' already exists",
+  "code": "COHORT_EXISTS",
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+**404 - Not Found**
+```json
+{
+  "status": "error",
+  "message": "Cohort not found",
+  "code": "COHORT_NOT_FOUND",
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+## Testing
+
+### Using curl
+```bash
+# Create
+curl -X POST http://localhost:3000/v3/audio-analitics/cohorts \
+  -H "Content-Type: application/json" \
+  -d @cohort_payload.json
+
+# Get
+curl http://localhost:3000/v3/audio-analitics/cohorts/cohort_001
+
+# Search
+curl -X POST http://localhost:3000/v3/audio-analitics/cohorts/search \
+  -H "Content-Type: application/json" \
+  -d '{"clientId":"11","limit":10}'
+
+# Update
+curl -X PUT http://localhost:3000/v3/audio-analitics/cohorts/DOC_ID \
+  -H "Content-Type: application/json" \
+  -d @update_payload.json
+
+# Delete
+curl -X DELETE http://localhost:3000/v3/audio-analitics/cohorts/DOC_ID
+
+# Analytics
+curl http://localhost:3000/v3/audio-analitics/cohorts/cohort_001/analytics
+```
+
+### Using Test Script
+```bash
+bash COHORT_API_EXAMPLES.sh
+```
+
+## File Dependencies
+
+| File | Depends On | Used By |
+|------|-----------|---------|
+| cohort.validation.js | joi | validation.middleware.js |
+| cohort.service.js | tango-app-api-middleware | cohort.controller.js |
+| cohort.controller.js | cohort.service.js, audioAnalytics.dtos.js | audioAnalytics.routes.js |
+| validation.middleware.js | cohort.validation.js | audioAnalytics.routes.js |
+| audioAnalytics.routes.js | cohort.controller.js, validation.middleware.js | app.js |
+
+## Environmental Setup
+
+### Required Environment Variables
+```env
+# Database (OpenSearch)
+OPENSEARCH_HOST=localhost
+OPENSEARCH_PORT=9200
+OPENSEARCH_INDEX=tango-audio-cohort
+
+# API
+API_PORT=3000
+NODE_ENV=development
+
+# Logger
+LOG_LEVEL=info
+```
+
+## Key Constants
+
+```javascript
+// Database
+OPENSEARCH_INDEX = 'tango-audio-cohort'
+
+// API Status Codes
+201 = Created
+200 = OK
+400 = Bad Request
+404 = Not Found
+409 = Conflict
+500 = Internal Server Error
+
+// Error Codes
+VALIDATION_ERROR       // 400
+COHORT_EXISTS          // 409
+COHORT_NOT_FOUND       // 404
+COHORT_CREATE_ERROR    // 500
+COHORT_SEARCH_ERROR    // 500
+INTERNAL_ERROR         // 500
+```
+
+## Performance Considerations
+
+### Pagination
+- Default limit: 10 items
+- Maximum items: 50
+- Offset-based pagination supported
+- Use for `/cohorts/client/:clientId` endpoint
+
+### Search Optimization
+- Fuzzy search enabled on cohortName (AUTO fuzziness)
+- Bool query for multiple criteria
+- Indexed by: clientId, cohortId, cohortName
+
+### Caching Recommendations
+- Cache GET /cohorts/:cohortId for 5 minutes
+- Invalidate cache on PUT/DELETE
+- Analytics endpoint can be cached for 1 hour
+
+## Security Notes
+
+- All inputs validated via Joi
+- SQL injection not applicable (OpenSearch)
+- Validate clientId against user permissions
+- Use UUID for document IDs (not sequential)
+- Hash sensitive data in metrics if needed
+
+## Support Files
+
+- **COHORT_API.md** - Full API documentation
+- **COHORT_API_EXAMPLES.sh** - Bash testing script
+- **COHORT_API_IMPLEMENTATION.md** - Implementation details
+
+## Next Steps
+
+1. ✅ Install dependencies (`npm install joi`)
+2. ✅ Review COHORT_API.md for complete documentation
+3. ✅ Run COHORT_API_EXAMPLES.sh to test endpoints
+4. ✅ Integrate with conversation analytics
+5. ✅ Deploy to production with proper environment configuration

package/index.js

@@ -0,0 +1,6 @@
+
+
+import { audioAnalyticsrouter } from './src/routes/audioAnalytics.routes.js';
+
+export { audioAnalyticsrouter };
+

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "tango-app-api-audio-analytics",
+    "version": "1.0.0",
+    "description": "audioAnalytics",
+    "main": "index.js",
+    "type": "module",
+    "scripts": {
+        "start": "nodemon --exec \"eslint --fix . && node app.js\""
+    },
+    "engines": {
+        "node": ">=18.10.0"
+    },
+    "author": "praveenraj",
+    "license": "ISC",
+    "dependencies": {
+        "aws-sdk": "^2.1693.0",
+        "body-parser": "^2.2.2",
+        "cors": "^2.8.6",
+        "dotenv": "^17.3.1",
+        "express": "^5.2.1",
+        "mongodb": "^6.21.0",
+        "nodemon": "^3.1.14",
+        "tango-api-schema": "^2.5.62",
+        "tango-app-api-middleware": "^3.6.18",
+        "winston": "^3.19.0",
+        "winston-daily-rotate-file": "^5.0.0"
+    },
+    "devDependencies": {
+        "eslint": "^8.57.1",
+        "eslint-config-google": "^0.14.0",
+        "eslint-config-semistandard": "^17.0.0",
+        "eslint-config-standard": "^17.1.0",
+        "eslint-plugin-import": "^2.32.0",
+        "eslint-plugin-promise": "^6.6.0"
+    }
+}

package/src/controllers/audioAnalytics.controller.js

@@ -0,0 +1,116 @@
+import { insertWithId, logger } from 'tango-app-api-middleware';
+import { randomUUID } from 'crypto';
+
+const EXTERNAL_STREAM_API = 'http://172.236.179.51:8000/stream';
+
+export async function createCohort( req, res ) {
+  try {
+    const inputData = req.body;
+
+    const cohortId = `cohort_${inputData.clientId}_${randomUUID()}`;
+
+    const metrics = ( inputData.metrics || [] ).map( ( metric ) => {
+      const hasContext = Array.isArray( metric.contexts ) && metric.contexts.length > 0;
+      return {
+        ...metric,
+        metricId: randomUUID(),
+        hasContext,
+        isNumeric: metric.isNumeric ?? false,
+      };
+    } );
+
+    const cohortData = {
+      clientId: inputData.clientId,
+      cohortId,
+      cohortName: inputData.cohortName,
+      cohortDescription: inputData.cohortDescription,
+      metrics,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    const result = await insertWithId( 'tango-audio-config', cohortId, cohortData );
+    logger.info( { result } );
+
+    if ( result && result.body && result.body.result === 'created' ) {
+      return res.sendSuccess( { result: 'Cohort created successfully', cohortId } );
+    } else {
+      return res.sendError( 'Failed to create cohort', 500 );
+    }
+  } catch ( error ) {
+    const err = error.message || 'Internal Server Error';
+    logger.error( { error: error, message: req.body, function: 'createCohort' } );
+    return res.sendError( err, 500 );
+  }
+}
+
+export const callExternalStreamAPI = async ( req, res ) => {
+  try {
+    const { prompt, storeId, productModule, country, region, fromDate, toDate, clusters } = req.body;
+    console.log( 'Received request for external stream API with parameters:', req.body );
+    // Validation for required parameters
+    if ( !prompt ) {
+      logger.warn( 'Stream API call attempted without prompt' );
+      return res.status( 400 ).json( {
+        status: 'error',
+        message: 'Missing required parameter: prompt',
+        code: 'MISSING_PROMPT',
+        timestamp: new Date().toISOString(),
+      } );
+    }
+
+    // Build query parameters
+    const queryParams = new URLSearchParams();
+    queryParams.append( 'prompt', prompt );
+
+    if ( storeId ) queryParams.append( 'storeId', storeId );
+    if ( productModule ) queryParams.append( 'productModule', productModule );
+    if ( country ) queryParams.append( 'country', country );
+    if ( region ) queryParams.append( 'region', region );
+    if ( fromDate ) queryParams.append( 'fromDate', fromDate );
+    if ( toDate ) queryParams.append( 'toDate', toDate );
+    if ( clusters ) queryParams.append( 'clusters', clusters );
+
+    const url = `${EXTERNAL_STREAM_API}?${queryParams.toString()}`;
+
+    logger.info( `Calling external stream API with URL: ${url}` );
+
+    // Make the external API call
+    const response = await fetch( url, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+    } );
+
+    if ( !response.ok ) {
+      logger.error( `External API error: ${response.status} ${response.statusText}` );
+      return res.status( response.status ).json( {
+        status: 'error',
+        message: `External API error: ${response.statusText}`,
+        code: 'EXTERNAL_API_ERROR',
+        timestamp: new Date().toISOString(),
+      } );
+    }
+
+    const data = await response.json();
+
+    logger.info( `Successfully called external stream API` );
+
+    return res.status( 200 ).json( {
+      status: 'success',
+      data: data,
+      timestamp: new Date().toISOString(),
+    } );
+  } catch ( error ) {
+    logger.error( `Error calling external stream API: ${error.message}` );
+    return res.status( 500 ).json( {
+      status: 'error',
+      message: 'Internal server error while calling external API',
+      code: 'INTERNAL_ERROR',
+      error: error.message,
+      timestamp: new Date().toISOString(),
+    } );
+  }
+};