feat: add api docs for user's social score

swagger.yaml

@@ -295,6 +295,8 @@ paths:
     $ref: "./v1/analytics/community-metrics/index.yaml#/_communityId-most-active-day"
   /api/v1/analytics/community-metrics/{communityId}/most-active-time:
     $ref: "./v1/analytics/community-metrics/index.yaml#/_communityId-most-active-time"
+  /api/v1/analytics/users-social-score:
+    $ref: "./v1/analytics/index.yaml#/users-social-score"
   /api/v3/network-settings/chat:
     $ref: "./v3/network-setting/index.yaml#/chat"
   /api/v3/network-settings/feed-setting:
@@ -319,6 +321,8 @@ paths:
     $ref: "./v3/network-setting/index.yaml#/shareable-deep-links"
   /api/v3/network-settings/security-configs:
     $ref: "./v3/network-setting/index.yaml#/security-configs"
+  /api/v3/network-settings/analytic-configs:
+    $ref: "./v3/network-setting/index.yaml#/analytic-configs"
   /v1/notification:
     $ref: "./v1/notification/index.yaml#/root"
   /api/v1/notification-tray:

v1/analytics/index.yaml

@@ -74,3 +74,30 @@ views-stories_storyId-users:
         $ref: "../../global/error.yaml#/UnProcessableError"
       500:
         $ref: "../../global/error.yaml#/UnexpectedError"
+
+users-social-score:
+  get:
+    summary: query users social score
+    description:
+      "Query users' social scores including contributions (posts, comments, reactions) and content quality metrics. 
+      This endpoint provides comprehensive social engagement analytics for users within a network based on configurable time intervals."
+    tags:
+      - Analytic
+    security:
+      - BearerAuth: []
+    parameters:
+      - $ref: "./parameter.yaml#/socialScoreInterval"
+      - $ref: "./parameter.yaml#/userIds"
+      - $ref: "./parameter.yaml#/sortBy"
+      - $ref: "./parameter.yaml#/sortOrder"
+      - $ref: "./parameter.yaml#/contributionsLevel"
+      - $ref: "./parameter.yaml#/contentsQualityLevel"
+      - $ref: "./parameter.yaml#/options.token"
+      - $ref: "./parameter.yaml#/options.limit"
+    responses:
+      200:
+        $ref: "./response.yaml#/users-social-score-response-payload-200"
+      403:
+        $ref: "../../global/error.yaml#/ForbiddenError"
+      500:
+        $ref: "../../global/error.yaml#/UnexpectedError"

v1/analytics/parameter.yaml

@@ -32,3 +32,92 @@ limit:
     type: number
     default: 10
     description: number of user in a page
+
+socialScoreInterval:
+  name: interval
+  in: query
+  required: true
+  schema:
+    type: string
+    enum: ["7d", "30d", "90d"]
+    description: Time interval for social score analysis
+    example: "30d"
+
+userIds:
+  name: userIds
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+      pattern: '^[a-f\d]{24}$'
+    minItems: 1
+    maxItems: 20
+    description: Optional list of specific user IDs to query
+    example: ["60e4b1b4b3b2b5c4c4b3b2b5", "60e4b1b4b3b2b5c4c4b3b2b6"]
+
+sortBy:
+  name: sortBy
+  in: query
+  schema:
+    type: string
+    enum: ["contributions-score", "contents-quality-score"]
+    description: Field to sort results by
+    example: "contributions-score"
+
+sortOrder:
+  name: sortOrder
+  in: query
+  schema:
+    type: string
+    enum: ["desc", "asc"]
+    description: Sort order for results
+    example: "desc"
+
+contributionsLevel:
+  name: contributionsLevel
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+      enum: ["none", "low", "medium", "high", "very_high"]
+    minItems: 1
+    maxItems: 5
+    description: Filter by contribution levels
+    example: ["high", "very_high"]
+
+contentsQualityLevel:
+  name: contentsQualityLevel
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+      enum: ["broken", "weak", "fair", "good", "excellent"]
+    minItems: 1
+    maxItems: 5
+    description: Filter by content quality levels
+    example: ["good", "excellent"]
+
+options.limit:
+  name: options[limit]
+  in: query
+  description: Number of results per page (1-100)
+  schema:
+    type: number
+    minimum: 1
+    maximum: 20
+    default: 10
+    description: Number of users to return per page
+    example: 10
+
+options.token:
+  name: options[token]
+  in: query
+  description: Pagination token for getting next/previous pages
+  schema:
+    type: string
+    maxLength: 1000
+    description: Pagination token for retrieving next/previous page
+    example: "eyJhZnRlciI6eyJfaWQiOnsicG9zdElkIjoiNjUxNjZlZTNlOTVlZTQ4YjkzZWVkMjQ1IiwidXNlcklkIjoiNjUxNjZlZTRlOTVlZTQzZjgzZWVkMjViIn0sIm5ldHdvcmtJZCI6IjYwNmYzN2EzYWU2MDFlZjM3NGViYWEwMSIsInJlYWNoZWRBdCI6IjIwMjMtMDktMjlUMDY6Mjk6NTQuOTQ4WiJ9fQ=="

v1/analytics/response.yaml

@@ -47,3 +47,78 @@ views-stories_storyId-users-response-payload-200:
               previous:
                 type: string
                 example: "eyJhZnRlciI6eyJfaWQiOnsicG9zdElkIjoiNjUxNjZlZTNlOTVlZTQ4YjkzZWVkMjQ1IiwidXNlcklkIjoiNjUxNjZlZTRlOTVlZTQzZjgzZWVkMjViIn0sIm5ldHdvcmtJZCI6IjYwNmYzN2EzYWU2MDFlZjM3NGViYWEwMSIsInJlYWNoZWRBdCI6IjIwMjMtMDktMjlUMDY6Mjk6NTQuOTQ4WiJ9fQ=="
+
+users-social-score-response-payload-200:
+  description: List of users with their social scores including contributions and content quality metrics
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          data:
+            type: array
+            items:
+              type: object
+              properties:
+                userId:
+                  type: string
+                  pattern: '^[a-f\d]{24}$'
+                  description: Unique identifier of the user
+                  example: "60e4b1b4b3b2b5c4c4b3b2b5"
+                contributions:
+                  type: object
+                  properties:
+                    posts:
+                      type: number
+                      description: Number of posts created by the user
+                      example: 15
+                    comments:
+                      type: number
+                      description: Number of comments made by the user
+                      example: 42
+                    reactions:
+                      type: number
+                      description: Number of reactions given by the user
+                      example: 87
+                    score:
+                      type: number
+                      description: Calculated contribution score based on weighted activities
+                      example: 156.5
+                    level:
+                      type: string
+                      enum: ["none", "low", "medium", "high", "very_high"]
+                      description: Contribution level based on score thresholds
+                      example: "high"
+                contentsQuality:
+                  type: object
+                  properties:
+                    score:
+                      type: number
+                      description: Average content quality score
+                      example: 4.2
+                    count:
+                      type: number
+                      description: Number of content pieces analyzed for quality
+                      example: 12
+                    level:
+                      type: string
+                      enum: ["broken", "weak", "fair", "good", "excellent"]
+                      description: Content quality level based on average score
+                      example: "good"
+          paging:
+            type: object
+            properties:
+              next:
+                type: string
+                nullable: true
+                description: Token for retrieving the next page of results
+                example: "eyJmcm9tIjoyMCwibGltaXQiOjEwfQ=="
+              previous:
+                type: string
+                nullable: true
+                description: Token for retrieving the previous page of results
+                example: "eyJmcm9tIjowLCJsaW1pdCI6MTB9"
+              limit:
+                type: number
+                description: Number of items per page
+                example: 10

v3/network-setting/index.yaml

@@ -415,3 +415,35 @@ security-configs:
         $ref: "../../global/error.yaml#/BadRequestError"
       500:
         $ref: "../../global/error.yaml#/UnexpectedError"
+
+analytic-configs:
+  put:
+    summary: "Update network analytic configuration"
+    tags:
+      - "Network Setting"
+    security:
+      - BearerAuth: []
+    description: "Update analytic configuration including contributions scoring and content quality settings for social score analytics.\n"
+    requestBody:
+      $ref: "./request.yaml#/analytic-configs-put-request-payload"
+    responses:
+      200:
+        $ref: "./response.yaml#/analytic-configs-response-200"
+      400:
+        $ref: "../../global/error.yaml#/BadRequestError"
+      500:
+        $ref: "../../global/error.yaml#/UnexpectedError"
+  get:
+    summary: "Get network analytic configuration"
+    tags:
+      - "Network Setting"
+    security:
+      - BearerAuth: []
+    description: "Get analytic configuration including contributions scoring and content quality settings for social score analytics.\n"
+    responses:
+      200:
+        $ref: "./response.yaml#/analytic-configs-response-200"
+      400:
+        $ref: "../../global/error.yaml#/BadRequestError"
+      500:
+        $ref: "../../global/error.yaml#/UnexpectedError"

v3/network-setting/request.yaml

@@ -297,3 +297,64 @@ security-configs-put-request-payload:
           - required: ["serverKey"]
           - required: ["adminToken"]
 
+analytic-configs-put-request-payload:
+  description: "Analytic configuration for social score and content quality settings\n"
+  required: true
+  content:
+    application/json:
+      schema:
+        type: "object"
+        properties:
+          contributionsSetting:
+            type: "object"
+            description: "Configuration for user contributions scoring"
+            properties:
+              scoreWeight:
+                type: "object"
+                description: "Weight values for different contribution types"
+                properties:
+                  post:
+                    type: "number"
+                    description: "Weight for posts in contribution score calculation"
+                    example: 10
+                  comment:
+                    type: "number"
+                    description: "Weight for comments in contribution score calculation"
+                    example: 3
+                  reaction:
+                    type: "number"
+                    description: "Weight for reactions in contribution score calculation"
+                    example: 1
+              threshold:
+                type: "object"
+                description: "Threshold values for contribution levels"
+                properties:
+                  none:
+                    type: "number"
+                    description: "Minimum score for 'none' level"
+                    example: 0
+                  low:
+                    type: "number"
+                    description: "Minimum score for 'low' level"
+                    example: 10
+                  medium:
+                    type: "number"
+                    description: "Minimum score for 'medium' level"
+                    example: 50
+                  high:
+                    type: "number"
+                    description: "Minimum score for 'high' level"
+                    example: 100
+                  veryHigh:
+                    type: "number"
+                    description: "Minimum score for 'very_high' level"
+                    example: 200
+          contentsQualitySetting:
+            type: "object"
+            description: "Configuration for content quality assessment"
+            properties:
+              qualityDefinition:
+                type: "string"
+                description: "Definition or criteria for content quality assessment"
+                example: "Content quality is assessed based on engagement metrics, community guidelines compliance, and user feedback"
+

v3/network-setting/response.yaml

@@ -251,3 +251,73 @@ security-configs-response-200:
             adminToken:
               expiresInHours: 24
 
+analytic-configs-response-200:
+  description: Analytic configuration for social score and content quality
+  content:
+    application/json:
+      schema:
+        type: "object"
+        properties:
+          analyticConfigs:
+            type: "object"
+            description: "Analytic configuration settings"
+            properties:
+              contributionsSetting:
+                type: "object"
+                description: "Configuration for user contributions scoring"
+                properties:
+                  scoreWeight:
+                    type: "object"
+                    description: "Weight values for different contribution types"
+                    properties:
+                      post:
+                        type: "number"
+                        description: "Weight for posts in contribution score calculation"
+                      comment:
+                        type: "number"
+                        description: "Weight for comments in contribution score calculation"
+                      reaction:
+                        type: "number"
+                        description: "Weight for reactions in contribution score calculation"
+                  threshold:
+                    type: "object"
+                    description: "Threshold values for contribution levels"
+                    properties:
+                      none:
+                        type: "number"
+                        description: "Minimum score for 'none' level"
+                      low:
+                        type: "number"
+                        description: "Minimum score for 'low' level"
+                      medium:
+                        type: "number"
+                        description: "Minimum score for 'medium' level"
+                      high:
+                        type: "number"
+                        description: "Minimum score for 'high' level"
+                      veryHigh:
+                        type: "number"
+                        description: "Minimum score for 'very_high' level"
+              contentsQualitySetting:
+                type: "object"
+                description: "Configuration for content quality assessment"
+                properties:
+                  qualityDefinition:
+                    type: "string"
+                    description: "Definition or criteria for content quality assessment"
+        example:
+          analyticConfigs:
+            contributionsSetting:
+              scoreWeight:
+                post: 10
+                comment: 3
+                reaction: 1
+              threshold:
+                none: 0
+                low: 10
+                medium: 50
+                high: 100
+                veryHigh: 200
+            contentsQualitySetting:
+              qualityDefinition: "Content quality is assessed based on engagement metrics, community guidelines compliance, and user feedback"
+