feat(api): add GET /player/stale route for worker sweeper

Exposes stale players (expiresAt older than N days) as a worker-only
endpoint so the external worker can refresh them via its own Hypixel
keys without a direct MongoDB connection.

- Add PlayerStaleDto with limit (default 10k, max 50k) and staleAfterDays (default 7)
- Add PlayerService.getStale: queries MongoDB sorted by expiresAt asc
- Add GET /player/stale controller route (WORKER role, weight 10)
- Add mongo index on Player.expiresAt to keep the query fast

Author: ugcodrr

apps/api/src/dtos/index.ts

@@ -17,6 +17,7 @@ export * from "./verify-code.dto.js";
 export * from "./command.dto.js";
 export * from "./update-player.dto.js";
 export * from "./player-group.dto.js";
+export * from "./player-stale.dto.js";
 export * from "./player-search.dto.js";
 export * from "./player.dto.js";
 export * from "./key.dto.js";

apps/api/src/dtos/player-stale.dto.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) Statsify
+ *
+ * This source code is licensed under the GNU GPL v3 license found in the
+ * LICENSE file in the root directory of this source tree.
+ * https://github.com/Statsify/statsify/blob/main/LICENSE
+ */
+
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { IsNumber, IsOptional, Max, Min } from "class-validator";
+import { Transform } from "class-transformer";
+
+export class PlayerStaleDto {
+  @Transform((params) => +params.value)
+  @IsNumber()
+  @IsOptional()
+  @Min(1)
+  @Max(50_000)
+  @ApiPropertyOptional({ default: 10_000 })
+  public limit: number = 10_000;
+
+  @Transform((params) => +params.value)
+  @IsNumber()
+  @IsOptional()
+  @Min(1)
+  @ApiPropertyOptional({ default: 7 })
+  public staleAfterDays: number = 7;
+}

apps/api/src/player/player.controller.ts

@@ -15,7 +15,7 @@ import {
 } from "@nestjs/swagger";
 import { Auth, AuthRole } from "#auth";
 import { Body, Controller, Delete, Get, Post, Query } from "@nestjs/common";
-import { CachedPlayerDto, PlayerDto, PlayerGroupDto, UpdatePlayerDto } from "#dtos";
+import { CachedPlayerDto, PlayerDto, PlayerGroupDto, PlayerStaleDto, UpdatePlayerDto } from "#dtos";
 import {
   DeletePlayerResponse,
   ErrorResponse,
@@ -63,6 +63,13 @@ export class PlayerController {
     return this.playerService.getPlayers(start, end);
   }
 
+  @ApiOperation({ summary: "Get Stale Players" })
+  @Auth({ role: AuthRole.WORKER, weight: 10 })
+  @Get("/stale")
+  public getStale(@Query() { limit, staleAfterDays }: PlayerStaleDto) {
+    return this.playerService.getStale(limit, staleAfterDays);
+  }
+
   @ApiOperation({ summary: "Deletes a Player" })
   @ApiOkResponse({ type: DeletePlayerResponse })
   @ApiBadRequestResponse({ type: ErrorResponse })

apps/api/src/player/player.service.ts

@@ -103,6 +103,19 @@ export class PlayerService {
     );
   }
 
+  public async getStale(limit: number, staleAfterDays: number): Promise<string[]> {
+    const threshold = Date.now() - staleAfterDays * 24 * 60 * 60 * 1000;
+
+    const players = await this.playerModel
+      .find({ expiresAt: { $lt: threshold } } as any, { uuid: 1, _id: 0 })
+      .sort({ expiresAt: 1 })
+      .limit(limit)
+      .lean()
+      .exec();
+
+    return (players as any[]).map((p) => p.uuid);
+  }
+
   public async getStatus(tag: string) {
     const player = await this.get(tag, CacheLevel.CACHE, {
       uuid: true,