Merge pull request #69 from Dans-Plugins/copilot/add-average-daily-activity

Add average daily activity calculation with command and REST API

Author: dmccoystephenson

REST_API.md

@@ -111,6 +111,41 @@ Get detailed activity information for a specific player.
 }
 ```
 
+### Average Daily Activity
+```
+GET /api/average-daily-activity/{uuid}?days=7
+```
+Get average daily activity for a specific player over a specified period.
+
+**Parameters:**
+- `uuid` (path): Player's UUID
+- `days` (query, optional): Number of days to calculate average over (default: 7)
+
+**Response:**
+```json
+{
+  "playerUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "playerName": "Steve",
+  "days": 7,
+  "averageHoursPerDay": 3.25,
+  "totalHours": 22.75
+}
+```
+
+**Error Response (404):**
+```json
+{
+  "error": "Player not found"
+}
+```
+
+**Error Response (400):**
+```json
+{
+  "error": "Days must be a positive number"
+}
+```
+
 ## OpenAPI Specification
 
 A complete OpenAPI 3.0 specification is available in the `openapi.yaml` file in the plugin repository. You can use this specification with tools like:
@@ -143,6 +178,12 @@ curl http://localhost:8080/api/leaderboard
 
 # Get specific player info
 curl http://localhost:8080/api/players/a1b2c3d4-e5f6-7890-abcd-ef1234567890
+
+# Get average daily activity for a player (default 7 days)
+curl http://localhost:8080/api/average-daily-activity/a1b2c3d4-e5f6-7890-abcd-ef1234567890
+
+# Get average daily activity for a player over 30 days
+curl "http://localhost:8080/api/average-daily-activity/a1b2c3d4-e5f6-7890-abcd-ef1234567890?days=30"
 ```
 
 ### Using JavaScript (fetch)
@@ -156,6 +197,11 @@ fetch('http://localhost:8080/api/stats')
 fetch('http://localhost:8080/api/leaderboard')
   .then(response => response.json())
   .then(data => console.log(data));
+
+// Get average daily activity
+fetch('http://localhost:8080/api/average-daily-activity/a1b2c3d4-e5f6-7890-abcd-ef1234567890?days=7')
+  .then(response => response.json())
+  .then(data => console.log(data));
 ```
 
 ### Using Python
@@ -173,6 +219,13 @@ response = requests.get('http://localhost:8080/api/leaderboard')
 leaderboard = response.json()
 for i, player in enumerate(leaderboard, 1):
     print(f"{i}. {player['playerName']} - {player['hoursPlayed']:.2f} hours")
+
+# Get average daily activity
+response = requests.get('http://localhost:8080/api/average-daily-activity/a1b2c3d4-e5f6-7890-abcd-ef1234567890', 
+                       params={'days': 7})
+avg_activity = response.json()
+print(f"Player: {avg_activity['playerName']}")
+print(f"Average hours per day ({avg_activity['days']} days): {avg_activity['averageHoursPerDay']:.2f}")
 ```
 
 ## Troubleshooting

openapi.yaml

@@ -129,6 +129,51 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
 
+  /api/average-daily-activity/{uuid}:
+    get:
+      summary: Get average daily activity for a player
+      description: Calculate and retrieve the average daily activity for a specific player over a specified period
+      operationId: getAverageDailyActivity
+      tags:
+        - Players
+      parameters:
+        - name: uuid
+          in: path
+          required: true
+          description: The UUID of the player
+          schema:
+            type: string
+            format: uuid
+            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+        - name: days
+          in: query
+          required: false
+          description: Number of days to calculate average over (default 7)
+          schema:
+            type: integer
+            minimum: 1
+            default: 7
+            example: 7
+      responses:
+        '200':
+          description: Average daily activity retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AverageDailyActivityResponse'
+        '400':
+          description: Invalid UUID format or days parameter
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Player not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
 components:
   schemas:
     HealthResponse:
@@ -250,6 +295,39 @@ components:
         - totalHoursPlayed
         - currentlyOnline
 
+    AverageDailyActivityResponse:
+      type: object
+      properties:
+        playerUuid:
+          type: string
+          format: uuid
+          description: UUID of the player
+          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+        playerName:
+          type: string
+          description: Name of the player
+          example: "Steve"
+        days:
+          type: integer
+          description: Number of days the average was calculated over
+          example: 7
+        averageHoursPerDay:
+          type: number
+          format: double
+          description: Average hours played per day
+          example: 3.25
+        totalHours:
+          type: number
+          format: double
+          description: Total hours played in the specified period
+          example: 22.75
+      required:
+        - playerUuid
+        - playerName
+        - days
+        - averageHoursPerDay
+        - totalHours
+
     ErrorResponse:
       type: object
       properties:

src/main/java/dansplugins/activitytracker/ActivityTracker.java

@@ -18,6 +18,7 @@
 import org.bukkit.event.Listener;
 
 import dansplugins.activitytracker.bstats.Metrics;
+import dansplugins.activitytracker.commands.AverageCommand;
 import dansplugins.activitytracker.commands.ConfigCommand;
 import dansplugins.activitytracker.commands.DefaultCommand;
 import dansplugins.activitytracker.commands.HelpCommand;
@@ -156,6 +157,7 @@ private void registerEventHandlers() {
      */
     private void initializeCommandService() {
         ArrayList<AbstractPluginCommand> commands = new ArrayList<>(Arrays.asList(
+                new AverageCommand(persistentData, activityRecordService),
                 new ConfigCommand(configService),
                 new HelpCommand(),
                 new InfoCommand(persistentData),

src/main/java/dansplugins/activitytracker/api/AverageDailyActivityResponse.java

@@ -0,0 +1,41 @@
+package dansplugins.activitytracker.api;
+
+/**
+ * Response object for average daily activity data
+ * @author Daniel McCoy Stephenson
+ */
+public class AverageDailyActivityResponse {
+    private final String playerUuid;
+    private final String playerName;
+    private final int days;
+    private final double averageHoursPerDay;
+    private final double totalHours;
+
+    public AverageDailyActivityResponse(String playerUuid, String playerName, int days, double averageHoursPerDay, double totalHours) {
+        this.playerUuid = playerUuid;
+        this.playerName = playerName;
+        this.days = days;
+        this.averageHoursPerDay = averageHoursPerDay;
+        this.totalHours = totalHours;
+    }
+
+    public String getPlayerUuid() {
+        return playerUuid;
+    }
+
+    public String getPlayerName() {
+        return playerName;
+    }
+
+    public int getDays() {
+        return days;
+    }
+
+    public double getAverageHoursPerDay() {
+        return averageHoursPerDay;
+    }
+
+    public double getTotalHours() {
+        return totalHours;
+    }
+}

src/main/java/dansplugins/activitytracker/api/RestApiService.java

@@ -209,6 +209,60 @@ private void setupRoutes() {
             return gson.toJson(playerResponse);
         });
 
+        // GET /api/average-daily-activity/:uuid - Get average daily activity for a player
+        Spark.get("/api/average-daily-activity/:uuid", (request, response) -> {
+            String uuidParam = request.params(":uuid");
+            UUID playerUuid;
+
+            try {
+                playerUuid = UUID.fromString(uuidParam);
+            } catch (IllegalArgumentException e) {
+                response.status(400);
+                return gson.toJson(new ErrorResponse("Invalid UUID format"));
+            }
+
+            ActivityRecord record = persistentData.getActivityRecord(playerUuid);
+            if (record == null) {
+                response.status(404);
+                return gson.toJson(new ErrorResponse("Player not found"));
+            }
+
+            // Get days parameter from query string (default: 7)
+            String daysParam = request.queryParams("days");
+            int days = 7;
+            if (daysParam != null) {
+                try {
+                    days = Integer.parseInt(daysParam);
+                    if (days <= 0) {
+                        response.status(400);
+                        return gson.toJson(new ErrorResponse("Days must be a positive number"));
+                    }
+                } catch (NumberFormatException e) {
+                    response.status(400);
+                    return gson.toJson(new ErrorResponse("Invalid days parameter"));
+                }
+            }
+
+            UUIDChecker uuidChecker = new UUIDChecker();
+            String playerName = uuidChecker.findPlayerNameBasedOnUUID(playerUuid);
+            if (playerName == null) {
+                playerName = "Unknown";
+            }
+
+            double averageHoursPerDay = activityRecordService.calculateAverageDailyActivity(record, days);
+            double totalHours = activityRecordService.calculateTotalHoursInPeriod(record, days);
+
+            AverageDailyActivityResponse avgResponse = new AverageDailyActivityResponse(
+                    playerUuid.toString(),
+                    playerName,
+                    days,
+                    averageHoursPerDay,
+                    totalHours
+            );
+
+            return gson.toJson(avgResponse);
+        });
+
         // GET /api/health - Health check endpoint
         Spark.get("/api/health", (request, response) -> {
             return gson.toJson(new HealthResponse("OK", "Activity Tracker REST API"));