kol overview

backend/src/swagger/index.ts

@@ -2088,6 +2088,157 @@ export const openAPISpec = {
         }
       }
     },
+    '/api/analytics/kol-overview': {
+      get: {
+        summary: 'Get KOL performance overview',
+        description: 'Returns card-style layout showing key performance metrics for each KOL including followers growth, new likes, and new follows',
+        tags: ['Analytics'],
+        parameters: [
+          {
+            name: 'timeRange',
+            in: 'query',
+            description: 'Number of days to look back',
+            schema: {
+              type: 'string',
+              enum: ['7', '30', '90'],
+              default: '30'
+            }
+          },
+          {
+            name: 'projectId',
+            in: 'query',
+            description: 'Filter by project ID',
+            schema: {
+              type: 'string'
+            }
+          },
+          {
+            name: 'sortBy',
+            in: 'query',
+            description: 'Field to sort by',
+            schema: {
+              type: 'string',
+              enum: ['followers_change', 'likes_change', 'follows_change'],
+              default: 'followers_change'
+            }
+          },
+          {
+            name: 'sortOrder',
+            in: 'query',
+            description: 'Sort order',
+            schema: {
+              type: 'string',
+              enum: ['asc', 'desc'],
+              default: 'desc'
+            }
+          },
+          {
+            name: 'limit',
+            in: 'query',
+            description: 'Number of KOLs to return',
+            schema: {
+              type: 'integer',
+              default: 20
+            }
+          },
+          {
+            name: 'offset',
+            in: 'query',
+            description: 'Offset for pagination',
+            schema: {
+              type: 'integer',
+              default: 0
+            }
+          }
+        ],
+        responses: {
+          '200': {
+            description: 'Successful response with KOL performance data',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: {
+                      type: 'boolean',
+                      example: true
+                    },
+                    data: {
+                      type: 'array',
+                      items: {
+                        type: 'object',
+                        properties: {
+                          influencer_id: { type: 'string', example: 'inf-123-456' },
+                          name: { type: 'string', example: 'John Influencer' },
+                          platform: { type: 'string', example: 'instagram' },
+                          profile_url: { type: 'string', example: 'https://instagram.com/johninfluencer' },
+                          followers_count: { type: 'integer', example: 50000 },
+                          followers_change: { type: 'integer', example: 1500 },
+                          followers_change_percentage: { 
+                            type: 'number', 
+                            nullable: true,
+                            example: 12.5 
+                          },
+                          likes_change: { type: 'integer', example: 2800 },
+                          likes_change_percentage: { 
+                            type: 'number', 
+                            nullable: true,
+                            example: 15.3 
+                          },
+                          follows_change: { type: 'integer', example: 1200 },
+                          follows_change_percentage: { 
+                            type: 'number', 
+                            nullable: true,
+                            example: 8.7 
+                          }
+                        }
+                      }
+                    },
+                    pagination: {
+                      type: 'object',
+                      properties: {
+                        limit: { type: 'integer', example: 20 },
+                        offset: { type: 'integer', example: 0 },
+                        total: { type: 'integer', example: 42 }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          '400': {
+            description: 'Bad request - invalid parameters',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean', example: false },
+                    error: { type: 'string', example: 'Invalid sortBy. Must be one of: followers_change, likes_change, follows_change' }
+                  }
+                }
+              }
+            }
+          },
+          '500': {
+            description: 'Server error',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean', example: false },
+                    error: { type: 'string', example: 'Failed to fetch KOL overview data' },
+                    message: { type: 'string', example: 'ClickHouse query error: Connection refused' }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
   },
   components: {
     schemas: {