tango-app-api-audio-analytics 1.0.0

package/src/dtos/audioAnalytics.dtos.js

@@ -0,0 +1,537 @@
+import joi from 'joi';
+
+/**
+ * Audio Analytics DTOs (Data Transfer Objects)
+ * Defines request and response structures for audio analytics API endpoints
+ */
+
+// ======================= REQUEST DTOs =======================
+
+/**
+ * Cohort Analysis Request DTO
+ * @typedef {Object} CohortAnalysisRequestDTO
+ * @property {string} startDate - Start date (YYYY-MM-DD)
+ * @property {string} endDate - End date (YYYY-MM-DD)
+ * @property {string[]} storeId - Array of store IDs
+ * @property {string} cohortType - Type of cohort (e.g., "Photochromatic")
+ * @property {string[]} clientId - Array of client IDs
+ */
+export class CohortAnalysisRequestDTO {
+  constructor( startDate, endDate, storeId, cohortType, clientId ) {
+    this.startDate = startDate;
+    this.endDate = endDate;
+    this.storeId = storeId;
+    this.cohortType = cohortType;
+    this.clientId = clientId;
+  }
+
+  validate() {
+    if ( !this.startDate || !this.endDate || !this.storeId ) {
+      throw new Error( 'Missing required parameters: startDate, endDate, storeId' );
+    }
+    return true;
+  }
+}
+
+/**
+ * Conversations List Request DTO
+ * @typedef {Object} ConversationsListRequestDTO
+ * @property {string} startDate - Start date (YYYY-MM-DD)
+ * @property {string} endDate - End date (YYYY-MM-DD)
+ * @property {string[]} storeId - Array of store IDs
+ * @property {string[]} [clientId] - Optional array of client IDs
+ * @property {boolean} [isAI] - Filter for AI-generated conversations
+ * @property {string} [type] - Type of conversation (e.g., "audio")
+ * @property {string} [searchValue] - Search term
+ * @property {boolean} [isExport] - Flag to export as CSV
+ * @property {number} [limit] - Pagination limit
+ * @property {number} [offset] - Pagination offset
+ */
+export class ConversationsListRequestDTO {
+  constructor( data ) {
+    this.startDate = data.startDate;
+    this.endDate = data.endDate;
+    this.storeId = data.storeId;
+    this.clientId = data.clientId || [];
+    this.isAI = data.isAI || false;
+    this.type = data.type || 'audio';
+    this.searchValue = data.searchValue || '';
+    this.isExport = data.isExport || false;
+    this.limit = data.limit || 10;
+    this.offset = data.offset || 0;
+  }
+
+  validate() {
+    if ( !this.startDate || !this.endDate || !this.storeId ) {
+      throw new Error( 'Missing required parameters: startDate, endDate, storeId' );
+    }
+    if ( this.limit < 1 || this.limit > 1000 ) {
+      throw new Error( 'Limit must be between 1 and 1000' );
+    }
+    return true;
+  }
+}
+
+/**
+ * Conversation Details Request DTO
+ * @typedef {Object} ConversationDetailsRequestDTO
+ * @property {string} conversationId - Conversation ID (from URL param)
+ * @property {string} storeId - Store ID
+ */
+export class ConversationDetailsRequestDTO {
+  constructor( conversationId, storeId ) {
+    this.conversationId = conversationId;
+    this.storeId = storeId;
+  }
+
+  validate() {
+    if ( !this.conversationId || !this.storeId ) {
+      throw new Error( 'Missing required parameters: conversationId, storeId' );
+    }
+    return true;
+  }
+}
+
+/**
+ * Conversation Metrics Request DTO
+ * @typedef {Object} ConversationMetricsRequestDTO
+ * @property {string} conversationId - Conversation ID (from URL param)
+ * @property {string} storeId - Store ID
+ * @property {boolean} [includeBreakdown] - Include detailed breakdowns
+ */
+export class ConversationMetricsRequestDTO {
+  constructor( conversationId, storeId, includeBreakdown = true ) {
+    this.conversationId = conversationId;
+    this.storeId = storeId;
+    this.includeBreakdown = includeBreakdown;
+  }
+
+  validate() {
+    if ( !this.conversationId || !this.storeId ) {
+      throw new Error( 'Missing required parameters: conversationId, storeId' );
+    }
+    return true;
+  }
+}
+
+/**
+ * AI Insights Request DTO
+ * @typedef {Object} AIInsightsRequestDTO
+ * @property {string} conversationId - Conversation ID (from URL param)
+ * @property {string} storeId - Store ID
+ * @property {string} [startDate] - Optional start date for trend analysis
+ * @property {string} [endDate] - Optional end date for trend analysis
+ * @property {string[]} [productModules] - Optional product modules filter
+ * @property {string} [country] - Optional country filter
+ * @property {string} [region] - Optional region filter
+ * @property {string[]} [clusters] - Optional cluster filter
+ * @property {boolean} [includeRecommendations] - Include AI recommendations
+ * @property {string} [analysisDepth] - Analysis depth ("brief" | "detailed")
+ */
+export class AIInsightsRequestDTO {
+  constructor( data ) {
+    this.conversationId = data.conversationId;
+    this.storeId = data.storeId;
+    this.startDate = data.startDate;
+    this.endDate = data.endDate;
+    this.productModules = data.productModules || [];
+    this.country = data.country || '';
+    this.region = data.region || '';
+    this.clusters = data.clusters || [];
+    this.includeRecommendations = data.includeRecommendations !== false;
+    this.analysisDepth = data.analysisDepth || 'detailed';
+  }
+
+  validate() {
+    if ( !this.conversationId || !this.storeId ) {
+      throw new Error( 'Missing required parameters: conversationId, storeId' );
+    }
+    if ( this.analysisDepth && ![ 'brief', 'detailed' ].includes( this.analysisDepth ) ) {
+      throw new Error( 'Invalid analysisDepth. Must be "brief" or "detailed"' );
+    }
+    return true;
+  }
+}
+
+/**
+ * Conversation Transcription Request DTO
+ * @typedef {Object} ConversationTranscriptionRequestDTO
+ * @property {string} conversationId - Conversation ID (from URL param)
+ * @property {string} storeId - Store ID
+ * @property {boolean} [includeTimestamps] - Include timestamps in transcription
+ * @property {boolean} [highlightKeyPhases] - Highlight key phrases
+ */
+export class ConversationTranscriptionRequestDTO {
+  constructor( conversationId, storeId, includeTimestamps = true, highlightKeyPhases = true ) {
+    this.conversationId = conversationId;
+    this.storeId = storeId;
+    this.includeTimestamps = includeTimestamps;
+    this.highlightKeyPhases = highlightKeyPhases;
+  }
+
+  validate() {
+    if ( !this.conversationId || !this.storeId ) {
+      throw new Error( 'Missing required parameters: conversationId, storeId' );
+    }
+    return true;
+  }
+}
+
+/**
+ * Dashboard Filter Request DTO
+ * @typedef {Object} DashboardFilterRequestDTO
+ * @property {Object} dateRange - Date range object
+ * @property {string} dateRange.startDate - Start date (YYYY-MM-DD)
+ * @property {string} dateRange.endDate - End date (YYYY-MM-DD)
+ * @property {string[]} [productModules] - Array of product module IDs
+ * @property {string} [country] - Selected country
+ * @property {string} [region] - Selected region
+ * @property {string[]} [clusters] - Array of cluster/store group IDs
+ * @property {boolean} [includeExport] - Include export option
+ * @property {string} [analyticsType] - Type of analytics ("overview" | "detailed")
+ */
+export class DashboardFilterRequestDTO {
+  constructor( data ) {
+    this.dateRange = {
+      startDate: data.dateRange.startDate,
+      endDate: data.dateRange.endDate,
+    };
+    this.productModules = data.productModules || [];
+    this.country = data.country || '';
+    this.region = data.region || '';
+    this.clusters = data.clusters || [];
+    this.includeExport = data.includeExport || false;
+    this.analyticsType = data.analyticsType || 'overview';
+  }
+
+  validate() {
+    if ( !this.dateRange.startDate || !this.dateRange.endDate ) {
+      throw new Error( 'Missing required fields: dateRange.startDate, dateRange.endDate' );
+    }
+    return true;
+  }
+}
+
+/**
+ * Export Data Request DTO
+ * @typedef {Object} ExportDataRequestDTO
+ * @property {Object} dateRange - Date range object
+ * @property {string} dateRange.startDate - Start date (YYYY-MM-DD)
+ * @property {string} dateRange.endDate - End date (YYYY-MM-DD)
+ * @property {string[]} [productModules] - Array of product module IDs
+ * @property {string} [country] - Selected country
+ * @property {string} [region] - Selected region
+ * @property {string[]} [clusters] - Array of cluster/store group IDs
+ * @property {string} exportFormat - Export format ("csv" | "json" | "xlsx")
+ * @property {string[]} [includeColumns] - Columns to include in export
+ */
+export class ExportDataRequestDTO {
+  constructor( data ) {
+    this.dateRange = {
+      startDate: data.dateRange.startDate,
+      endDate: data.dateRange.endDate,
+    };
+    this.productModules = data.productModules || [];
+    this.country = data.country || '';
+    this.region = data.region || '';
+    this.clusters = data.clusters || [];
+    this.exportFormat = data.exportFormat || 'csv';
+    this.includeColumns = data.includeColumns || [];
+  }
+
+  validate() {
+    if ( !this.dateRange.startDate || !this.dateRange.endDate ) {
+      throw new Error( 'Missing required fields: dateRange.startDate, dateRange.endDate' );
+    }
+    if ( ![ 'csv', 'json', 'xlsx' ].includes( this.exportFormat ) ) {
+      throw new Error( 'Invalid exportFormat. Must be "csv", "json", or "xlsx"' );
+    }
+    return true;
+  }
+}
+
+// ======================= RESPONSE DTOs =======================
+
+/**
+ * Standard API Response DTO
+ * @typedef {Object} ApiResponseDTO
+ * @property {string} status - Response status ("success" | "error")
+ * @property {*} data - Response data
+ * @property {string} [message] - Optional message
+ * @property {string} [code] - Optional error code
+ * @property {string} timestamp - ISO timestamp
+ */
+export class ApiResponseDTO {
+  constructor( status, data, timestamp = new Date().toISOString(), message = null, code = null ) {
+    this.status = status;
+    this.data = data;
+    this.timestamp = timestamp;
+    if ( message ) this.message = message;
+    if ( code ) this.code = code;
+  }
+
+  static success( data, timestamp = new Date().toISOString() ) {
+    return new ApiResponseDTO( 'success', data, timestamp );
+  }
+
+  static error( message, code = 'INTERNAL_ERROR', timestamp = new Date().toISOString() ) {
+    return new ApiResponseDTO( 'error', null, timestamp, message, code );
+  }
+}
+
+/**
+ * Conversation Data DTO
+ * @typedef {Object} ConversationDTO
+ * @property {string} audioId - Audio ID
+ * @property {string} storeId - Store ID
+ * @property {string} storeName - Store name
+ * @property {string} userName - User/staff name
+ * @property {string} location - Store location
+ * @property {string} date - Conversation date
+ * @property {string} time - Conversation time
+ * @property {string} duration - Conversation duration
+ * @property {string} audioDescription - Description of audio/conversation
+ * @property {Object} metrics - Metrics object
+ * @property {Object} aiInsights - AI-generated insights
+ * @property {Object} conversationDetails - Detailed conversation info
+ */
+export class ConversationDTO {
+  constructor( data ) {
+    this.audioId = data.audioId;
+    this.storeId = data.storeId;
+    this.storeName = data.storeName;
+    this.userName = data.userName || '';
+    this.location = data.location;
+    this.date = data.date;
+    this.time = data.time;
+    this.duration = data.duration;
+    this.audioDescription = data.audioDescription;
+    this.metrics = data.metrics || {};
+    this.aiInsights = data.aiInsights || {};
+    this.conversationDetails = data.conversationDetails || {};
+  }
+}
+
+/**
+ * Metrics DTO
+ * @typedef {Object} MetricsDTO
+ * @property {Object} greetings - Greeting metrics
+ * @property {Object} salesReport - Sales metrics
+ * @property {Object[]} pitchQuality - Pitch quality metrics
+ * @property {Object[]} uniquePitches - Unique pitches data
+ * @property {Object} [conversationQuality] - Quality metrics
+ */
+export class MetricsDTO {
+  constructor( data ) {
+    this.greetings = data.greetings || {};
+    this.salesReport = data.salesReport || {};
+    this.pitchQuality = data.pitchQuality || [];
+    this.uniquePitches = data.uniquePitches || [];
+    this.conversationQuality = data.conversationQuality || {};
+  }
+}
+
+/**
+ * AI Insights DTO
+ * @typedef {Object} AIInsightsDTO
+ * @property {string} title - Insights title
+ * @property {string} [summary] - Brief summary
+ * @property {Object[]} keyInsights - Array of key insights
+ * @property {Object} performanceMetrics - Performance metrics
+ * @property {Object} sentimentAnalysis - Sentiment analysis
+ * @property {Object} pitchEffectiveness - Pitch effectiveness data
+ * @property {Object[]} [recommendations] - AI recommendations
+ */
+export class AIInsightsDTO {
+  constructor( data ) {
+    this.title = data.title || 'Tango AI Generated Insights';
+    this.summary = data.summary || [];
+    this.keyInsights = data.keyInsights || [];
+    this.performanceMetrics = data.performanceMetrics || {};
+    this.sentimentAnalysis = data.sentimentAnalysis || {};
+    this.pitchEffectiveness = data.pitchEffectiveness || {};
+    this.recommendations = data.recommendations || [];
+  }
+}
+
+/**
+ * Transcription DTO
+ * @typedef {Object} TranscriptionDTO
+ * @property {string} audioId - Audio ID
+ * @property {string} duration - Total duration
+ * @property {string} date - Conversation date
+ * @property {string} time - Conversation time
+ * @property {string} store - Store name
+ * @property {string} location - Store location
+ * @property {Object[]} participants - Array of participants
+ * @property {string} summary - Audio summary
+ * @property {Object[]} fullTranscription - Full transcription with timestamps
+ * @property {Object} keyPhrases - Key phrases extracted
+ */
+export class TranscriptionDTO {
+  constructor( data ) {
+    this.audioId = data.audioId;
+    this.duration = data.duration;
+    this.date = data.date;
+    this.time = data.time;
+    this.store = data.store;
+    this.location = data.location;
+    this.participants = data.participants || [];
+    this.summary = data.summary;
+    this.fullTranscription = data.fullTranscription || [];
+    this.keyPhrases = data.keyPhrases || {};
+  }
+}
+
+/**
+ * Dashboard State DTO
+ * @typedef {Object} DashboardStateDTO
+ * @property {Object} currentFilters - Currently applied filters
+ * @property {string} lastUpdated - Last update timestamp
+ * @property {number} recordsMatching - Total records matching filters
+ * @property {string} viewMode - Current view mode
+ * @property {Object[]} [savedViews] - Array of saved views
+ */
+export class DashboardStateDTO {
+  constructor( data ) {
+    this.currentFilters = data.currentFilters || {};
+    this.lastUpdated = data.lastUpdated || new Date().toISOString();
+    this.recordsMatching = data.recordsMatching || 0;
+    this.viewMode = data.viewMode || 'overview';
+    this.savedViews = data.savedViews || [];
+  }
+}
+
+/**
+ * Export Response DTO
+ * @typedef {Object} ExportResponseDTO
+ * @property {string} exportId - Unique export ID
+ * @property {string} status - Export status ("processing" | "completed" | "failed")
+ * @property {string} format - Export format (csv | json | xlsx)
+ * @property {number} recordCount - Number of records exported
+ * @property {string} estimatedFileSize - Estimated file size
+ * @property {number} estimatedTimeSeconds - Estimated processing time
+ * @property {string} [downloadUrl] - Download URL when ready
+ * @property {number} expiresIn - URL expiration time in seconds
+ */
+export class ExportResponseDTO {
+  constructor( data ) {
+    this.exportId = data.exportId;
+    this.status = data.status || 'processing';
+    this.format = data.format;
+    this.recordCount = data.recordCount;
+    this.estimatedFileSize = data.estimatedFileSize;
+    this.estimatedTimeSeconds = data.estimatedTimeSeconds;
+    if ( data.downloadUrl ) this.downloadUrl = data.downloadUrl;
+    this.expiresIn = data.expiresIn || 3600;
+  }
+}
+
+/**
+ * Error Response DTO
+ * @typedef {Object} ErrorResponseDTO
+ * @property {string} status - Status ("error")
+ * @property {string} message - Error message
+ * @property {string} code - Error code
+ * @property {*} [details] - Additional error details
+ * @property {string} timestamp - ISO timestamp
+ */
+export class ErrorResponseDTO {
+  constructor( message, code = 'INTERNAL_ERROR', details = null ) {
+    this.status = 'error';
+    this.message = message;
+    this.code = code;
+    if ( details ) this.details = details;
+    this.timestamp = new Date().toISOString();
+  }
+}
+
+/**
+ * Pagination DTO
+ * @typedef {Object} PaginationDTO
+ * @property {number} total - Total records
+ * @property {number} limit - Records per page
+ * @property {number} offset - Current offset
+ * @property {boolean} hasMore - Has more records
+ * @property {number} [nextOffset] - Next offset value
+ */
+export class PaginationDTO {
+  constructor( total, limit, offset ) {
+    this.total = total;
+    this.limit = limit;
+    this.offset = offset;
+    this.hasMore = offset + limit < total;
+    if ( this.hasMore ) this.nextOffset = offset + limit;
+  }
+}
+
+/**
+ * External Stream API Request DTO
+ * @typedef {Object} ExternalStreamAPIRequestDTO
+ * @property {string} prompt - The prompt/query for AI analysis (required)
+ * @property {string} [storeId] - Store identifier for filtering
+ * @property {string} [productModule] - Product module name
+ * @property {string} [country] - Country code or name
+ * @property {string} [region] - Region identifier
+ * @property {string} [fromDate] - Start date for analytics (YYYY-MM-DD)
+ * @property {string} [toDate] - End date for analytics (YYYY-MM-DD)
+ * @property {string} [clusters] - Cluster identifiers for grouping
+ */
+export class ExternalStreamAPIRequestDTO {
+  constructor( data ) {
+    this.prompt = data.prompt;
+    this.storeId = data.storeId || null;
+    this.productModule = data.productModule || null;
+    this.country = data.country || null;
+    this.region = data.region || null;
+    this.fromDate = data.fromDate || null;
+    this.toDate = data.toDate || null;
+    this.clusters = data.clusters || null;
+  }
+
+  validate() {
+    if ( !this.prompt || this.prompt.trim() === '' ) {
+      throw new Error( 'Missing required parameter: prompt' );
+    }
+    return true;
+  }
+}
+
+
+const cohortContextNonNumericSchema = joi.object( {
+  contextName: joi.string().required(),
+  priority: joi.number().required(),
+  description: joi.string().required(),
+} );
+
+
+const cohortMetricSchema = joi.object( {
+  metricName: joi.string().required(),
+  metricDescription: joi.string().required(),
+  isNumeric: joi.boolean().optional().default( false ),
+
+  minValue: joi.when( 'isNumeric', {
+    is: true,
+    then: joi.number().optional().default( null ).allow( null ),
+    otherwise: joi.forbidden(),
+  } ),
+
+  maxValue: joi.when( 'isNumeric', {
+    is: true,
+    then: joi.number().optional().default( null ).allow( null ),
+    otherwise: joi.forbidden(),
+  } ),
+
+  contexts: joi.array().items( cohortContextNonNumericSchema ).optional(),
+} );
+
+export const createCohortSchema = joi.object( {
+  clientId: joi.string().required(),
+  cohortName: joi.string().required(),
+  cohortDescription: joi.string().required(),
+  metrics: joi.array().items( cohortMetricSchema ).optional(),
+} );
+
+export const createCohortValid = {
+  body: createCohortSchema,
+};