Update dependency lucide-react to ^0.454.0

Reviewed-on: #87

package.json

@@ -13,6 +13,7 @@
   "author": "fascinated7",
   "license": "MIT",
   "dependencies": {
-    "concurrently": "^9.0.1"
+    "concurrently": "^9.0.1",
+    "cross-env": "^7.0.3"
   }
 }

projects/backend/Dockerfile

@@ -1,4 +1,4 @@
-FROM oven/bun:1.1.31-alpine AS base
+FROM oven/bun:1.1.33-alpine AS base
 
 # Install dependencies
 FROM base AS depends

projects/backend/package.json

@@ -14,6 +14,7 @@
     "@elysiajs/swagger": "^1.1.3",
     "@ssr/common": "workspace:common",
     "@tqman/nice-logger": "^1.0.1",
+    "@typegoose/auto-increment": "^4.7.0",
     "@typegoose/typegoose": "^12.8.0",
     "@typescript-eslint/eslint-plugin": "^8.9.0",
     "@typescript-eslint/parser": "^8.9.0",

projects/backend/src/bot/bot.ts

@@ -1,17 +1,19 @@
 import { Client, MetadataStorage } from "discordx";
-import { Config } from "@ssr/common/config";
 import { ActivityType, EmbedBuilder } from "discord.js";
+import { Config } from "@ssr/common/config";
 
+export const guildId = "1295984874942894100";
 export enum DiscordChannels {
   trackedPlayerLogs = "1295985197262569512",
   numberOneFeed = "1295988063817830430",
   backendLogs = "1296524935237468250",
 }
 
-const DiscordBot = new Client({
-  intents: [],
+const client = new Client({
+  intents: ["Guilds", "GuildMessages"],
   presence: {
     status: "online",
+
     activities: [
       {
         name: "scores...",
@@ -22,15 +24,26 @@ const DiscordBot = new Client({
   },
 });
 
-DiscordBot.once("ready", () => {
+client.once("ready", () => {
   console.log("Discord bot ready!");
 });
 
-export function initDiscordBot() {
+export async function initDiscordBot() {
   console.log("Initializing discord bot...");
 
+  // We will now build our application to load all the commands/events for both bots.
   MetadataStorage.instance.build().then(async () => {
-    await DiscordBot.login(Config.discordBotToken!).then();
+    // Setup slash commands
+    client.once("ready", async () => {
+      await client.initApplicationCommands();
+      console.log(client.applicationCommands);
+    });
+    client.on("interactionCreate", interaction => {
+      client.executeInteraction(interaction);
+    });
+
+    // Login
+    await client.login(Config.discordBotToken!);
   });
 }
 
@@ -41,7 +54,8 @@ export function initDiscordBot() {
  * @param message the message to log
  */
 export async function logToChannel(channelId: DiscordChannels, message: EmbedBuilder) {
-  const channel = await DiscordBot.channels.fetch(channelId);
+  try {
+    const channel = await client.channels.fetch(channelId);
     if (channel == undefined) {
       throw new Error(`Channel "${channelId}" not found`);
     }
@@ -50,4 +64,7 @@ export async function logToChannel(channelId: DiscordChannels, message: EmbedBui
     }
 
     channel.send({ embeds: [message] });
+  } catch (error) {
+    console.error(error);
+  }
 }

projects/backend/src/bot/command/refresh-player-scores-command.ts

@@ -0,0 +1,20 @@
+import { Discord, Guild, Slash } from "discordx";
+import { CommandInteraction } from "discord.js";
+import { PlayerService } from "../../service/player.service";
+import { guildId } from "../bot";
+
+@Discord()
+export class RefreshPlayerScoresCommand {
+  @Guild(guildId)
+  @Slash({
+    description: "Refreshes scores for all tracked players",
+    name: "refresh-player-scores",
+    defaultMemberPermissions: ["Administrator"],
+  })
+  hello(interaction: CommandInteraction) {
+    interaction.reply("Updating player scores...").then(async response => {
+      await PlayerService.refreshPlayerScores();
+      await response.edit("Done!");
+    });
+  }
+}

projects/backend/src/common/cache.util.ts

@@ -1,5 +1,6 @@
 import { SSRCache } from "@ssr/common/cache";
-import { InternalServerError } from "../error/internal-server-error";
+import { InternalServerError } from "@ssr/common/error/internal-server-error";
+import { isProduction } from "@ssr/common/utils/utils";
 
 /**
  * Fetches data with caching.
@@ -13,6 +14,10 @@ export async function fetchWithCache<T>(
   cacheKey: string,
   fetchFn: () => Promise<T | undefined>
 ): Promise<T | undefined> {
+  if (!isProduction()) {
+    return await fetchFn();
+  }
+
   if (cache == undefined) {
     throw new InternalServerError(`Cache is not defined`);
   }

projects/backend/src/common/embds.ts

@@ -0,0 +1,37 @@
+import ScoreSaberPlayerToken from "@ssr/common/types/token/scoresaber/score-saber-player-token";
+import { DiscordChannels, logToChannel } from "../bot/bot";
+import { EmbedBuilder } from "discord.js";
+import { formatPp } from "@ssr/common/utils/number-utils";
+
+/**
+ * Logs that a new player is being tracked
+ *
+ * @param player the player being tracked
+ */
+export async function logNewTrackedPlayer(player: ScoreSaberPlayerToken) {
+  await logToChannel(
+    DiscordChannels.trackedPlayerLogs,
+    new EmbedBuilder()
+      .setTitle("New Player Tracked")
+      .setDescription(`https://ssr.fascinated.cc/player/${player.id}`)
+      .addFields([
+        {
+          name: "Username",
+          value: player.name,
+          inline: true,
+        },
+        {
+          name: "ID",
+          value: player.id,
+          inline: true,
+        },
+        {
+          name: "PP",
+          value: formatPp(player.pp) + "pp",
+          inline: true,
+        },
+      ])
+      .setThumbnail(player.profilePicture)
+      .setColor("#00ff00")
+  );
+}

projects/backend/src/controller/player.controller.ts

@@ -7,24 +7,32 @@ import { AroundPlayerResponse } from "@ssr/common/response/around-player-respons
 
 @Controller("/player")
 export default class PlayerController {
-  @Get("/history/:id", {
+  @Get("/history/:id/:days", {
     config: {},
     params: t.Object({
       id: t.String({ required: true }),
+      days: t.Number({ default: 50, required: false }),
     }),
     query: t.Object({
       createIfMissing: t.Boolean({ default: false, required: false }),
     }),
   })
   public async getPlayer({
-    params: { id },
+    params: { id, days },
     query: { createIfMissing },
   }: {
-    params: { id: string };
+    params: { id: string; days: number };
     query: { createIfMissing: boolean };
   }): Promise<{ statistics: Record<string, PlayerHistory> }> {
+    if (days < 1) {
+      days = 1;
+    }
+    // Limit to 10 years
+    if (days > 365 * 10) {
+      days = 365 * 10;
+    }
     const player = await PlayerService.getPlayer(id, createIfMissing);
-    return { statistics: player.getHistoryPreviousDays(50) };
+    return { statistics: player.getHistoryPreviousDays(days) };
   }
 
   @Get("/tracked/:id", {

projects/backend/src/controller/scores.controller.ts

@@ -1,6 +1,7 @@
 import { Controller, Get } from "elysia-decorators";
 import { t } from "elysia";
 import { Leaderboards } from "@ssr/common/leaderboard";
+import { TopScoresResponse } from "@ssr/common/response/top-scores-response";
 import { ScoreService } from "../service/score.service";
 
 @Controller("/scores")
@@ -52,4 +53,35 @@ export default class ScoresController {
   }): Promise<unknown> {
     return await ScoreService.getLeaderboardScores(leaderboard, id, page);
   }
+
+  @Get("/history/:playerId/:leaderboardId/:page", {
+    config: {},
+    params: t.Object({
+      playerId: t.String({ required: true }),
+      leaderboardId: t.String({ required: true }),
+      page: t.Number({ required: true }),
+    }),
+  })
+  public async getScoreHistory({
+    params: { playerId, leaderboardId, page },
+  }: {
+    params: {
+      playerId: string;
+      leaderboardId: string;
+      page: number;
+    };
+    query: { search?: string };
+  }): Promise<unknown> {
+    return (await ScoreService.getScoreHistory(playerId, leaderboardId, page)).toJSON();
+  }
+
+  @Get("/top", {
+    config: {},
+  })
+  public async getTopScores(): Promise<TopScoresResponse> {
+    const scores = await ScoreService.getTopScores();
+    return {
+      scores,
+    };
+  }
 }

projects/backend/src/index.ts

@@ -8,22 +8,20 @@ import { etag } from "@bogeychan/elysia-etag";
 import AppController from "./controller/app.controller";
 import * as dotenv from "@dotenvx/dotenvx";
 import mongoose from "mongoose";
-import { setLogLevel } from "@typegoose/typegoose";
 import PlayerController from "./controller/player.controller";
 import { PlayerService } from "./service/player.service";
 import { cron } from "@elysiajs/cron";
-import { scoresaberService } from "@ssr/common/service/impl/scoresaber";
-import { delay, isProduction } from "@ssr/common/utils/utils";
-import { connectScoreSaberWebSocket } from "@ssr/common/websocket/scoresaber-websocket";
+import { isProduction } from "@ssr/common/utils/utils";
 import ImageController from "./controller/image.controller";
 import { ScoreService } from "./service/score.service";
 import { Config } from "@ssr/common/config";
-import { PlayerDocument, PlayerModel } from "@ssr/common/model/player";
 import ScoresController from "./controller/scores.controller";
 import LeaderboardController from "./controller/leaderboard.controller";
+import { getAppVersion } from "./common/app.util";
+import { connectScoresaberWebsocket } from "@ssr/common/websocket/scoresaber-websocket";
+import { connectBeatLeaderWebsocket } from "@ssr/common/websocket/beatleader-websocket";
 import { DiscordChannels, initDiscordBot, logToChannel } from "./bot/bot";
 import { EmbedBuilder } from "discord.js";
-import { getAppVersion } from "./common/app.util";
 
 // Load .env file
 dotenv.config({
@@ -32,18 +30,32 @@ dotenv.config({
   override: true,
 });
 
+// Connect to Mongo
 await mongoose.connect(Config.mongoUri!); // Connect to MongoDB
-setLogLevel("DEBUG");
 
-connectScoreSaberWebSocket({
-  onScore: async playerScore => {
-    await PlayerService.trackScore(playerScore);
-    await ScoreService.notifyNumberOne(playerScore);
+// Connect to websockets
+connectScoresaberWebsocket({
+  onScore: async score => {
+    await ScoreService.trackScoreSaberScore(score.score, score.leaderboard);
+    await ScoreService.updatePlayerScoresSet(score);
+
+    await ScoreService.notifyNumberOne(score);
   },
   onDisconnect: async error => {
     await logToChannel(
       DiscordChannels.backendLogs,
-      new EmbedBuilder().setDescription(`ScoreSaber websocket disconnected: ${error}`)
+      new EmbedBuilder().setDescription(`ScoreSaber websocket disconnected: ${JSON.stringify(error)}`)
+    );
+  },
+});
+connectBeatLeaderWebsocket({
+  onScore: async score => {
+    await ScoreService.trackBeatLeaderScore(score);
+  },
+  onDisconnect: async error => {
+    await logToChannel(
+      DiscordChannels.backendLogs,
+      new EmbedBuilder().setDescription(`BeatLeader websocket disconnected: ${JSON.stringify(error)}`)
     );
   },
 });
@@ -52,44 +64,22 @@ export const app = new Elysia();
 app.use(
   cron({
     name: "player-statistics-tracker-cron",
-    pattern: "1 0 * * *", // Every day at 00:01
+    pattern: "0 1 * * * *", // Every day at 00:01
     timezone: "Europe/London", // UTC time
+    protect: true,
     run: async () => {
-      const pages = 20; // top 1000 players
-      const cooldown = 60_000 / 250; // 250 requests per minute
-
-      let toTrack: PlayerDocument[] = await PlayerModel.find({});
-      const toRemoveIds: string[] = [];
-
-      // loop through pages to fetch the top players
-      console.log(`Fetching ${pages} pages of players from ScoreSaber...`);
-      for (let i = 0; i < pages; i++) {
-        const pageNumber = i + 1;
-        console.log(`Fetching page ${pageNumber}...`);
-        const page = await scoresaberService.lookupPlayers(pageNumber);
-        if (page === undefined) {
-          console.log(`Failed to fetch players on page ${pageNumber}, skipping page...`);
-          await delay(cooldown);
-          continue;
-        }
-        for (const player of page.players) {
-          const foundPlayer = await PlayerService.getPlayer(player.id, true, player);
-          await PlayerService.trackScoreSaberPlayer(foundPlayer, player);
-          toRemoveIds.push(foundPlayer.id);
-        }
-        await delay(cooldown);
-      }
-      console.log(`Finished tracking player statistics for ${pages} pages, found ${toRemoveIds.length} players.`);
-
-      // remove all players that have been tracked
-      toTrack = toTrack.filter(player => !toRemoveIds.includes(player.id));
-
-      console.log(`Tracking ${toTrack.length} player statistics...`);
-      for (const player of toTrack) {
-        await PlayerService.trackScoreSaberPlayer(player);
-        await delay(cooldown);
-      }
-      console.log("Finished tracking player statistics.");
+      await PlayerService.updatePlayerStatistics();
+    },
+  })
+);
+app.use(
+  cron({
+    name: "player-scores-tracker-cron",
+    pattern: "0 4 * * *", // Every day at 04:00
+    timezone: "Europe/London", // UTC time
+    protect: true,
+    run: async () => {
+      await PlayerService.refreshPlayerScores();
     },
   })
 );
@@ -162,14 +152,25 @@ app.use(
         version: await getAppVersion(),
       },
     },
+    scalarConfig: {
+      servers: [
+        {
+          url: "https://ssr.fascinated.cc/api",
+          description: "Production server",
+        },
+      ],
+    },
   })
 );
 
-app.onStart(() => {
+app.onStart(async () => {
   console.log("Listening on port http://localhost:8080");
   if (isProduction()) {
-    initDiscordBot();
+    await initDiscordBot();
   }
 });
 
-app.listen(8080);
+app.listen({
+  port: 8080,
+  idleTimeout: 120, // 2 minutes
+});

projects/backend/src/service/app.service.ts

@@ -1,15 +1,38 @@
 import { PlayerModel } from "@ssr/common/model/player";
 import { AppStatistics } from "@ssr/common/types/backend/app-statistics";
+import { ScoreSaberScoreModel } from "@ssr/common/model/score/impl/scoresaber-score";
+import { AdditionalScoreDataModel } from "@ssr/common/model/additional-score-data/additional-score-data";
+import { BeatSaverMapModel } from "@ssr/common/model/beatsaver/map";
+import { ScoreSaberLeaderboardModel } from "@ssr/common/model/leaderboard/impl/scoresaber-leaderboard";
+import { SSRCache } from "@ssr/common/cache";
+
+const statisticsCache = new SSRCache({
+  ttl: 120 * 1000, // 2 minutes
+});
 
 export class AppService {
   /**
    * Gets the app statistics.
    */
   public static async getAppStatistics(): Promise<AppStatistics> {
-    const trackedPlayers = await PlayerModel.countDocuments();
+    if (statisticsCache.has("app-statistics")) {
+      return statisticsCache.get<AppStatistics>("app-statistics")!;
+    }
 
-    return {
+    const trackedPlayers = await PlayerModel.countDocuments();
+    const trackedScores = await ScoreSaberScoreModel.countDocuments();
+    const additionalScoresData = await AdditionalScoreDataModel.countDocuments();
+    const cachedBeatSaverMaps = await BeatSaverMapModel.countDocuments();
+    const cachedScoreSaberLeaderboards = await ScoreSaberLeaderboardModel.countDocuments();
+
+    const response = {
       trackedPlayers,
+      trackedScores,
+      additionalScoresData,
+      cachedBeatSaverMaps,
+      cachedScoreSaberLeaderboards,
     };
+    statisticsCache.set("app-statistics", response);
+    return response;
   }
 }

projects/backend/src/service/beatsaver.service.ts

@@ -1,39 +1,96 @@
 import { beatsaverService } from "@ssr/common/service/impl/beatsaver";
-import { BeatSaverMap, BeatSaverMapModel } from "@ssr/common/model/beatsaver/beatsaver-map";
+import { BeatSaverMap, BeatSaverMapModel } from "@ssr/common/model/beatsaver/map";
 
 export default class BeatSaverService {
   /**
-   * Gets a map by its hash.
+   * Gets a map by its hash, updates if necessary, or inserts if not found.
    *
    * @param hash the hash of the map
-   * @returns the beatsaver map
+   * @returns the beatsaver map, or undefined if not found
    */
   public static async getMap(hash: string): Promise<BeatSaverMap | undefined> {
-    let map = await BeatSaverMapModel.findById(hash);
-    if (map != undefined) {
+    let map = await BeatSaverMapModel.findOne({
+      "versions.hash": hash.toUpperCase(),
+    });
+
+    if (map) {
       const toObject = map.toObject() as BeatSaverMap;
-      if (toObject.unknownMap) {
+
+      // If the map is not found, return undefined
+      if (toObject.notFound) {
         return undefined;
       }
+
+      // If the map does not need to be refreshed, return it
+      if (!(map as unknown as BeatSaverMap).shouldRefresh()) {
         return toObject;
       }
+    }
 
+    // Map needs to be fetched or refreshed
     const token = await beatsaverService.lookupMap(hash);
-    map = await BeatSaverMapModel.create(
-      token
+    const uploader = token?.uploader;
+    const metadata = token?.metadata;
+
+    // Create the new map object based on fetched data
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error
+    const newMapData: BeatSaverMap =
+      token && uploader && metadata
         ? {
-            _id: hash,
+            _id: hash, // todo: change this to an incrementing id
             bsr: token.id,
+            name: token.name,
+            description: token.description,
             author: {
-              id: token.uploader.id,
+              id: uploader.id,
+              name: uploader.name,
+              avatar: uploader.avatar,
             },
+            metadata: {
+              bpm: metadata.bpm,
+              duration: metadata.duration,
+              levelAuthorName: metadata.levelAuthorName,
+              songAuthorName: metadata.songAuthorName,
+              songName: metadata.songName,
+              songSubName: metadata.songSubName,
+            },
+            versions: token.versions.map(version => ({
+              hash: version.hash.toUpperCase(),
+              difficulties: version.diffs.map(diff => ({
+                njs: diff.njs,
+                offset: diff.offset,
+                notes: diff.notes,
+                bombs: diff.bombs,
+                obstacles: diff.obstacles,
+                nps: diff.nps,
+                characteristic: diff.characteristic,
+                difficulty: diff.difficulty,
+                events: diff.events,
+                chroma: diff.chroma,
+                mappingExtensions: diff.me,
+                noodleExtensions: diff.ne,
+                cinema: diff.cinema,
+                maxScore: diff.maxScore,
+                label: diff.label,
+              })),
+              createdAt: new Date(version.createdAt),
+            })),
+            lastRefreshed: new Date(),
           }
         : {
             _id: hash,
-            unknownMap: true,
-          }
-    );
-    if (map.unknownMap) {
+            notFound: true,
+          };
+
+    // Upsert the map: if it exists, update it; if not, create a new one
+    map = await BeatSaverMapModel.findOneAndUpdate({ _id: hash }, newMapData, {
+      upsert: true,
+      new: true,
+      setDefaultsOnInsert: true,
+    });
+
+    if (map == null || map.notFound) {
       return undefined;
     }
     return map.toObject() as BeatSaverMap;

projects/backend/src/service/image.service.tsx

@@ -2,16 +2,17 @@ import { ImageResponse } from "@vercel/og";
 import { scoresaberService } from "@ssr/common/service/impl/scoresaber";
 import React from "react";
 import { formatNumberWithCommas, formatPp } from "@ssr/common/utils/number-utils";
-import { getDifficultyFromScoreSaberDifficulty } from "@ssr/common/utils/scoresaber-utils";
 import { StarIcon } from "../../components/star-icon";
 import { GlobeIcon } from "../../components/globe-icon";
-import ScoreSaberLeaderboardToken from "@ssr/common/types/token/scoresaber/score-saber-leaderboard-token";
-import ScoreSaberPlayer, { getScoreSaberPlayerFromToken } from "@ssr/common/player/impl/scoresaber-player";
+import ScoreSaberPlayer from "@ssr/common/player/impl/scoresaber-player";
 import { Jimp } from "jimp";
 import { extractColors } from "extract-colors";
 import { Config } from "@ssr/common/config";
 import { fetchWithCache } from "../common/cache.util";
 import { SSRCache } from "@ssr/common/cache";
+import { getScoreSaberPlayerFromToken } from "@ssr/common/token-creators";
+import LeaderboardService from "./leaderboard.service";
+import ScoreSaberLeaderboard from "@ssr/common/model/leaderboard/impl/scoresaber-leaderboard";
 
 const cache = new SSRCache({
   ttl: 1000 * 60 * 60, // 1 hour
@@ -175,12 +176,11 @@ export class ImageService {
    * @param id the leaderboard's id
    */
   public static async generateLeaderboardImage(id: string) {
-    const leaderboard = await fetchWithCache<ScoreSaberLeaderboardToken>(cache, `leaderboard-${id}`, () =>
-      scoresaberService.lookupLeaderboard(id)
-    );
-    if (!leaderboard) {
+    const response = await LeaderboardService.getLeaderboard<ScoreSaberLeaderboard>("scoresaber", id);
+    if (!response) {
       return undefined;
     }
+    const { leaderboard } = response;
 
     const ranked = leaderboard.stars > 0;
 
@@ -188,7 +188,7 @@ export class ImageService {
       (
         <ImageService.BaseImage>
           {/* Leaderboard Cover Image */}
-          <img src={leaderboard.coverImage} width={256} height={256} alt="Leaderboard Cover" tw="rounded-full mb-3" />
+          <img src={leaderboard.songArt} width={256} height={256} alt="Leaderboard Cover" tw="rounded-full mb-3" />
 
           {/* Leaderboard Name */}
           <p tw="font-bold text-6xl m-0">
@@ -205,9 +205,7 @@ export class ImageService {
             )}
 
             {/* Leaderboard Difficulty */}
-            <p tw={"font-bold m-0 text-4xl" + (ranked ? " pl-3" : "")}>
-              {getDifficultyFromScoreSaberDifficulty(leaderboard.difficulty.difficulty)}
-            </p>
+            <p tw={"font-bold m-0 text-4xl" + (ranked ? " pl-3" : "")}>{leaderboard.difficulty.difficulty}</p>
           </div>
 
           {/* Leaderboard Author */}

projects/backend/src/service/leaderboard.service.ts

@@ -1,17 +1,16 @@
 import { Leaderboards } from "@ssr/common/leaderboard";
 import { scoresaberService } from "@ssr/common/service/impl/scoresaber";
-import { SSRCache } from "@ssr/common/cache";
 import { LeaderboardResponse } from "@ssr/common/response/leaderboard-response";
-import Leaderboard from "@ssr/common/leaderboard/leaderboard";
 import ScoreSaberLeaderboardToken from "@ssr/common/types/token/scoresaber/score-saber-leaderboard-token";
 import { NotFoundError } from "elysia";
-import { getScoreSaberLeaderboardFromToken } from "@ssr/common/leaderboard/impl/scoresaber-leaderboard";
 import BeatSaverService from "./beatsaver.service";
-import { BeatSaverMap } from "@ssr/common/model/beatsaver/beatsaver-map";
-
-const leaderboardCache = new SSRCache({
-  ttl: 1000 * 60 * 60 * 24,
-});
+import { BeatSaverMap } from "@ssr/common/model/beatsaver/map";
+import { getScoreSaberLeaderboardFromToken } from "@ssr/common/token-creators";
+import {
+  ScoreSaberLeaderboard,
+  ScoreSaberLeaderboardModel,
+} from "@ssr/common/model/leaderboard/impl/scoresaber-leaderboard";
+import Leaderboard from "@ssr/common/model/leaderboard/leaderboard";
 
 export default class LeaderboardService {
   /**
@@ -21,16 +20,9 @@ export default class LeaderboardService {
    * @param id the id
    */
   private static async getLeaderboardToken<T>(leaderboard: Leaderboards, id: string): Promise<T | undefined> {
-    const cacheKey = `${leaderboard}-${id}`;
-    if (leaderboardCache.has(cacheKey)) {
-      return leaderboardCache.get(cacheKey) as T;
-    }
-
     switch (leaderboard) {
       case "scoresaber": {
-        const leaderboard = (await scoresaberService.lookupLeaderboard(id)) as T;
-        leaderboardCache.set(cacheKey, leaderboard);
-        return leaderboard;
+        return (await scoresaberService.lookupLeaderboard(id)) as T;
       }
       default: {
         return undefined;
@@ -49,8 +41,24 @@ export default class LeaderboardService {
     let leaderboard: Leaderboard | undefined;
     let beatSaverMap: BeatSaverMap | undefined;
 
+    const now = new Date();
     switch (leaderboardName) {
       case "scoresaber": {
+        let foundLeaderboard = false;
+        const cachedLeaderboard = await ScoreSaberLeaderboardModel.findById(id);
+        if (cachedLeaderboard != null) {
+          leaderboard = cachedLeaderboard.toObject() as unknown as ScoreSaberLeaderboard;
+          if (
+            leaderboard &&
+            (leaderboard.ranked || // Never refresh ranked leaderboards (it will get refreshed every night)
+              leaderboard.lastRefreshed == undefined || // Refresh if it has never been refreshed
+              now.getTime() - leaderboard.lastRefreshed.getTime() > 1000 * 60 * 60 * 24) // Refresh every day
+          ) {
+            foundLeaderboard = true;
+          }
+        }
+
+        if (!foundLeaderboard) {
           const leaderboardToken = await LeaderboardService.getLeaderboardToken<ScoreSaberLeaderboardToken>(
             leaderboardName,
             id
@@ -58,7 +66,20 @@ export default class LeaderboardService {
           if (leaderboardToken == undefined) {
             throw new NotFoundError(`Leaderboard not found for "${id}"`);
           }
+
           leaderboard = getScoreSaberLeaderboardFromToken(leaderboardToken);
+          leaderboard.lastRefreshed = new Date();
+
+          await ScoreSaberLeaderboardModel.findOneAndUpdate({ _id: id }, leaderboard, {
+            upsert: true,
+            new: true,
+            setDefaultsOnInsert: true,
+          });
+        }
+        if (leaderboard == undefined) {
+          throw new NotFoundError(`Leaderboard not found for "${id}"`);
+        }
+
         beatSaverMap = await BeatSaverService.getMap(leaderboard.songHash);
         break;
       }

projects/backend/src/service/player.service.ts

@@ -1,80 +1,82 @@
 import { PlayerDocument, PlayerModel } from "@ssr/common/model/player";
-import { NotFoundError } from "../error/not-found-error";
+import { NotFoundError } from "@ssr/common/error/not-found-error";
 import { getDaysAgoDate, getMidnightAlignedDate } from "@ssr/common/utils/time-utils";
 import { scoresaberService } from "@ssr/common/service/impl/scoresaber";
 import ScoreSaberPlayerToken from "@ssr/common/types/token/scoresaber/score-saber-player-token";
-import { InternalServerError } from "../error/internal-server-error";
-import ScoreSaberPlayerScoreToken from "@ssr/common/types/token/scoresaber/score-saber-player-score-token";
-import { formatPp } from "@ssr/common/utils/number-utils";
-import { getPageFromRank, isProduction } from "@ssr/common/utils/utils";
-import { DiscordChannels, logToChannel } from "../bot/bot";
-import { EmbedBuilder } from "discord.js";
+import { InternalServerError } from "@ssr/common/error/internal-server-error";
+import { delay, getPageFromRank, isProduction } from "@ssr/common/utils/utils";
 import { AroundPlayer } from "@ssr/common/types/around-player";
+import { ScoreSort } from "@ssr/common/score/score-sort";
+import { getScoreSaberLeaderboardFromToken } from "@ssr/common/token-creators";
+import { ScoreService } from "./score.service";
+import { logNewTrackedPlayer } from "../common/embds";
+
+const SCORESABER_REQUEST_COOLDOWN = 60_000 / 250; // 250 requests per minute
+const accountCreationLock: { [id: string]: Promise<PlayerDocument> } = {};
 
 export class PlayerService {
-  /**
-   * Get a player from the database.
-   *
-   * @param id the player to fetch
-   * @param create if true, create the player if it doesn't exist
-   * @param playerToken an optional player token for the player
-   * @returns the player
-   * @throws NotFoundError if the player is not found
-   */
   public static async getPlayer(
     id: string,
     create: boolean = false,
     playerToken?: ScoreSaberPlayerToken
   ): Promise<PlayerDocument> {
+    // Wait for the existing lock if it's in progress
+    if (accountCreationLock[id] !== undefined) {
+      await accountCreationLock[id];
+    }
+
     let player: PlayerDocument | null = await PlayerModel.findById(id);
+
     if (player === null) {
-      // If create is on, create the player, otherwise return unknown player
-      playerToken = create ? (playerToken ? playerToken : await scoresaberService.lookupPlayer(id)) : undefined;
-      if (playerToken === undefined) {
+      if (!create) {
         throw new NotFoundError(`Player "${id}" not found`);
       }
 
-      console.log(`Creating player "${id}"...`);
-      try {
-        player = (await PlayerModel.create({ _id: id })) as PlayerDocument;
-        player.trackedSince = new Date();
-        await this.seedPlayerHistory(player, playerToken);
+      playerToken = playerToken || (await scoresaberService.lookupPlayer(id));
 
-        // Only notify in production
+      if (!playerToken) {
+        throw new NotFoundError(`Player "${id}" not found`);
+      }
+
+      // Create a new lock promise and assign it
+      accountCreationLock[id] = (async () => {
+        let newPlayer: PlayerDocument;
+        try {
+          console.log(`Creating player "${id}"...`);
+          newPlayer = (await PlayerModel.create({ _id: id })) as PlayerDocument;
+          newPlayer.trackedSince = new Date();
+          await newPlayer.save();
+
+          await this.seedPlayerHistory(newPlayer, playerToken);
+          await this.refreshAllPlayerScores(newPlayer);
+
+          // Notify in production
           if (isProduction()) {
-          await logToChannel(
-            DiscordChannels.trackedPlayerLogs,
-            new EmbedBuilder()
-              .setTitle("New Player Tracked")
-              .setDescription(`https://ssr.fascinated.cc/player/${playerToken.id}`)
-              .addFields([
-                {
-                  name: "Username",
-                  value: playerToken.name,
-                  inline: true,
-                },
-                {
-                  name: "ID",
-                  value: playerToken.id,
-                  inline: true,
-                },
-                {
-                  name: "PP",
-                  value: formatPp(playerToken.pp) + "pp",
-                  inline: true,
-                },
-              ])
-              .setThumbnail(playerToken.profilePicture)
-              .setColor("#00ff00")
-          );
+            await logNewTrackedPlayer(playerToken);
           }
         } catch (err) {
-        const message = `Failed to create player document for "${id}"`;
-        console.log(message, err);
-        throw new InternalServerError(message);
+          console.log(`Failed to create player document for "${id}"`, err);
+          throw new InternalServerError(`Failed to create player document for "${id}"`);
+        } finally {
+          // Ensure the lock is always removed
+          delete accountCreationLock[id];
+        }
+
+        return newPlayer;
+      })();
+
+      // Wait for the player creation to complete
+      player = await accountCreationLock[id];
+
+      // Update player name
+      if (player.name !== playerToken.name) {
+        player.name = playerToken.name;
+        await player.save();
       }
     }
-    return player;
+
+    // Ensure that the player is now of type PlayerDocument
+    return player as PlayerDocument;
   }
 
   /**
@@ -91,7 +93,7 @@ export class PlayerService {
     });
     playerRankHistory.push(playerToken.rank);
 
-    let daysAgo = 1; // Start from yesterday
+    let daysAgo = 0; // Start from today
     for (let i = playerRankHistory.length - daysAgo - 1; i >= 0; i--) {
       const rank = playerRankHistory[i];
       // Skip inactive days
@@ -132,7 +134,7 @@ export class PlayerService {
 
     // Seed the history with ScoreSaber data if no history exists
     if (foundPlayer.getDaysTracked() === 0) {
-      await this.seedPlayerHistory(foundPlayer, player);
+      await this.seedPlayerHistory(foundPlayer.id, player);
     }
 
     // Update current day's statistics
@@ -148,12 +150,21 @@ export class PlayerService {
     history.countryRank = player.countryRank;
     history.rank = player.rank;
     history.accuracy = {
+      ...history.accuracy,
       averageRankedAccuracy: scoreStats.averageRankedAccuracy,
     };
     history.scores = {
+      rankedScores: 0,
+      unrankedScores: 0,
+      ...history.scores,
       totalScores: scoreStats.totalPlayCount,
       totalRankedScores: scoreStats.rankedPlayCount,
     };
+    history.score = {
+      ...history.score,
+      totalScore: scoreStats.totalScore,
+      totalRankedScore: scoreStats.totalRankedScore,
+    };
 
     foundPlayer.setStatisticHistory(dateToday, history);
     foundPlayer.sortStatisticHistory();
@@ -164,47 +175,6 @@ export class PlayerService {
     console.log(`Tracked player "${foundPlayer.id}"!`);
   }
 
-  /**
-   * Track player score.
-   *
-   * @param score the score to track
-   * @param leaderboard the leaderboard to track
-   */
-  public static async trackScore({ score, leaderboard }: ScoreSaberPlayerScoreToken) {
-    const playerId = score.leaderboardPlayerInfo.id;
-    const playerName = score.leaderboardPlayerInfo.name;
-    const player: PlayerDocument | null = await PlayerModel.findById(playerId);
-    // Player is not tracked, so ignore the score.
-    if (player == undefined) {
-      return;
-    }
-
-    const today = new Date();
-    let history = player.getHistoryByDate(today);
-    if (history == undefined || Object.keys(history).length === 0) {
-      history = { scores: { rankedScores: 0, unrankedScores: 0 } }; // Ensure initialization
-    }
-
-    const scores = history.scores || {};
-    if (leaderboard.stars > 0) {
-      scores.rankedScores!++;
-    } else {
-      scores.unrankedScores!++;
-    }
-
-    history.scores = scores;
-    player.setStatisticHistory(today, history);
-    player.sortStatisticHistory();
-
-    // Save the changes
-    player.markModified("statisticHistory");
-    await player.save();
-
-    console.log(
-      `Updated scores set statistic for "${playerName}"(${playerId}), scores today: ${scores.rankedScores} ranked, ${scores.unrankedScores} unranked`
-    );
-  }
-
   /**
    * Gets the players around a player.
    *
@@ -276,4 +246,126 @@ export class PlayerService {
 
     return players.slice(start, end);
   }
+
+  /**
+   * Refreshes all the players scores.
+   *
+   * @param player the player to refresh
+   */
+  public static async refreshAllPlayerScores(player: PlayerDocument) {
+    await this.refreshPlayerScoreSaberScores(player);
+  }
+
+  /**
+   * Ensures that all the players scores from the
+   * ScoreSaber API are up-to-date.
+   *
+   * @param player the player to refresh
+   * @private
+   */
+  private static async refreshPlayerScoreSaberScores(player: PlayerDocument) {
+    console.log(`Refreshing scores for ${player.id}...`);
+    let page = 1;
+    let hasMorePages = true;
+
+    while (hasMorePages) {
+      const scoresPage = await scoresaberService.lookupPlayerScores({
+        playerId: player.id,
+        page: page,
+        limit: 100,
+        sort: ScoreSort.recent,
+      });
+
+      if (!scoresPage) {
+        console.warn(`Failed to fetch scores for ${player.id} on page ${page}.`);
+        break;
+      }
+
+      let missingScores = 0;
+      for (const score of scoresPage.playerScores) {
+        const leaderboard = getScoreSaberLeaderboardFromToken(score.leaderboard);
+        const scoreSaberScore = await ScoreService.getScoreSaberScore(
+          player.id,
+          leaderboard.id + "",
+          leaderboard.difficulty.difficulty,
+          leaderboard.difficulty.characteristic,
+          score.score.baseScore
+        );
+
+        if (scoreSaberScore == null) {
+          missingScores++;
+        }
+        await ScoreService.trackScoreSaberScore(score.score, score.leaderboard, player.id);
+      }
+
+      // Stop paginating if no scores are missing OR if player has seededScores marked true
+      if ((missingScores === 0 && player.seededScores) || page >= Math.ceil(scoresPage.metadata.total / 100)) {
+        hasMorePages = false;
+      }
+
+      page++;
+      await delay(SCORESABER_REQUEST_COOLDOWN); // Cooldown between page requests
+    }
+
+    // Mark player as seeded
+    player.seededScores = true;
+    await player.save();
+
+    console.log(`Finished refreshing scores for ${player.id}, total pages refreshed: ${page - 1}.`);
+  }
+
+  /**
+   * Ensures all player scores are up-to-date.
+   */
+  public static async refreshPlayerScores() {
+    console.log(`Refreshing player score data...`);
+
+    const players = await PlayerModel.find({});
+    console.log(`Found ${players.length} players to refresh.`);
+
+    for (const player of players) {
+      await this.refreshAllPlayerScores(player.id);
+      await delay(SCORESABER_REQUEST_COOLDOWN); // Cooldown between players
+    }
+  }
+
+  /**
+   * Updates the player statistics for all players.
+   */
+  public static async updatePlayerStatistics() {
+    const pages = 20; // top 1000 players
+
+    let toTrack: PlayerDocument[] = await PlayerModel.find({});
+    const toRemoveIds: string[] = [];
+
+    // loop through pages to fetch the top players
+    console.log(`Fetching ${pages} pages of players from ScoreSaber...`);
+    for (let i = 0; i < pages; i++) {
+      const pageNumber = i + 1;
+      console.log(`Fetching page ${pageNumber}...`);
+      const page = await scoresaberService.lookupPlayers(pageNumber);
+      if (page === undefined) {
+        console.log(`Failed to fetch players on page ${pageNumber}, skipping page...`);
+        await delay(SCORESABER_REQUEST_COOLDOWN);
+        continue;
+      }
+      for (const player of page.players) {
+        const foundPlayer = await PlayerService.getPlayer(player.id, true, player);
+        await PlayerService.trackScoreSaberPlayer(foundPlayer, player);
+        toRemoveIds.push(foundPlayer.id);
+      }
+      await delay(SCORESABER_REQUEST_COOLDOWN);
+    }
+    console.log(`Finished tracking player statistics for ${pages} pages, found ${toRemoveIds.length} players.`);
+
+    // remove all players that have been tracked
+    toTrack = toTrack.filter(player => !toRemoveIds.includes(player.id));
+
+    console.log(`Tracking ${toTrack.length} player statistics...`);
+    for (const player of toTrack) {
+      await PlayerService.trackScoreSaberPlayer(player);
+      await delay(SCORESABER_REQUEST_COOLDOWN);
+    }
+    console.log("Finished tracking player statistics.");
+  }
 }

projects/backend/src/service/score.service.ts

@@ -4,25 +4,40 @@ import { isProduction } from "@ssr/common/utils/utils";
 import { Metadata } from "@ssr/common/types/metadata";
 import { NotFoundError } from "elysia";
 import BeatSaverService from "./beatsaver.service";
-import ScoreSaberLeaderboard, {
-  getScoreSaberLeaderboardFromToken,
-} from "@ssr/common/leaderboard/impl/scoresaber-leaderboard";
-import { getScoreSaberScoreFromToken } from "@ssr/common/score/impl/scoresaber-score";
 import { scoresaberService } from "@ssr/common/service/impl/scoresaber";
 import { ScoreSort } from "@ssr/common/score/score-sort";
 import { Leaderboards } from "@ssr/common/leaderboard";
-import Leaderboard from "@ssr/common/leaderboard/leaderboard";
 import LeaderboardService from "./leaderboard.service";
-import { BeatSaverMap } from "@ssr/common/model/beatsaver/beatsaver-map";
+import { BeatSaverMap } from "@ssr/common/model/beatsaver/map";
 import { PlayerScore } from "@ssr/common/score/player-score";
 import LeaderboardScoresResponse from "@ssr/common/response/leaderboard-scores-response";
-import Score from "@ssr/common/score/score";
 import PlayerScoresResponse from "@ssr/common/response/player-scores-response";
 import { DiscordChannels, logToChannel } from "../bot/bot";
 import { EmbedBuilder } from "discord.js";
 import { Config } from "@ssr/common/config";
 import { SSRCache } from "@ssr/common/cache";
 import { fetchWithCache } from "../common/cache.util";
+import { PlayerDocument, PlayerModel } from "@ssr/common/model/player";
+import { BeatLeaderScoreToken } from "@ssr/common/types/token/beatleader/score/score";
+import {
+  AdditionalScoreData,
+  AdditionalScoreDataModel,
+} from "@ssr/common/model/additional-score-data/additional-score-data";
+import { BeatLeaderScoreImprovementToken } from "@ssr/common/types/token/beatleader/score/score-improvement";
+import { ScoreType } from "@ssr/common/model/score/score";
+import { getScoreSaberLeaderboardFromToken, getScoreSaberScoreFromToken } from "@ssr/common/token-creators";
+import {
+  ScoreSaberPreviousScore,
+  ScoreSaberScore,
+  ScoreSaberScoreModel,
+} from "@ssr/common/model/score/impl/scoresaber-score";
+import ScoreSaberScoreToken from "@ssr/common/types/token/scoresaber/score-saber-score-token";
+import ScoreSaberLeaderboardToken from "@ssr/common/types/token/scoresaber/score-saber-leaderboard-token";
+import { MapDifficulty } from "@ssr/common/score/map-difficulty";
+import { MapCharacteristic } from "@ssr/common/types/map-characteristic";
+import { Page, Pagination } from "@ssr/common/pagination";
+import ScoreSaberLeaderboard from "@ssr/common/model/leaderboard/impl/scoresaber-leaderboard";
+import Leaderboard from "@ssr/common/model/leaderboard/leaderboard";
 
 const playerScoresCache = new SSRCache({
   ttl: 1000 * 60, // 1 minute
@@ -45,8 +60,8 @@ export class ScoreService {
     }
 
     const { score: scoreToken, leaderboard: leaderboardToken } = playerScore;
-    const score = getScoreSaberScoreFromToken(scoreToken, leaderboardToken);
     const leaderboard = getScoreSaberLeaderboardFromToken(leaderboardToken);
+    const score = getScoreSaberScoreFromToken(scoreToken, leaderboard, scoreToken.leaderboardPlayerInfo.id);
     const playerInfo = score.playerInfo;
 
     // Not ranked
@@ -112,37 +127,348 @@ export class ScoreService {
   }
 
   /**
-   * Gets scores for a player.
+   * Updates the players set scores count for today.
    *
-   * @param leaderboardName the leaderboard to get the scores from
-   * @param id the players id
-   * @param page the page to get
-   * @param sort the sort to use
-   * @param search the search to use
-   * @returns the scores
+   * @param score the score
    */
+  public static async updatePlayerScoresSet({
+    score: scoreToken,
+    leaderboard: leaderboardToken,
+  }: ScoreSaberPlayerScoreToken) {
+    const playerId = scoreToken.leaderboardPlayerInfo.id;
+
+    const leaderboard = getScoreSaberLeaderboardFromToken(leaderboardToken);
+    const player: PlayerDocument | null = await PlayerModel.findById(playerId);
+    // Player is not tracked, so ignore the score.
+    if (player == undefined) {
+      return;
+    }
+
+    const today = new Date();
+    const history = player.getHistoryByDate(today);
+    const scores = history.scores || {
+      rankedScores: 0,
+      unrankedScores: 0,
+    };
+    if (leaderboard.stars > 0) {
+      scores.rankedScores!++;
+    } else {
+      scores.unrankedScores!++;
+    }
+
+    history.scores = scores;
+    player.setStatisticHistory(today, history);
+    player.markModified("statisticHistory");
+    await player.save();
+  }
+
+  /**
+   * Tracks ScoreSaber score.
+   *
+   * @param scoreToken the score to track
+   * @param leaderboardToken the leaderboard for the score
+   * @param playerId the id of the player
+   */
+  public static async trackScoreSaberScore(
+    scoreToken: ScoreSaberScoreToken,
+    leaderboardToken: ScoreSaberLeaderboardToken,
+    playerId?: string
+  ) {
+    playerId = (scoreToken.leaderboardPlayerInfo && scoreToken.leaderboardPlayerInfo.id) || playerId;
+    if (!playerId) {
+      console.error(`Player ID is undefined, unable to track score: ${scoreToken.id}`);
+      return;
+    }
+
+    const playerName = (scoreToken.leaderboardPlayerInfo && scoreToken.leaderboardPlayerInfo.name) || "Unknown";
+
+    const leaderboard = getScoreSaberLeaderboardFromToken(leaderboardToken);
+    const score = getScoreSaberScoreFromToken(scoreToken, leaderboard, playerId);
+    const player: PlayerDocument | null = await PlayerModel.findById(playerId);
+    // Player is not tracked, so ignore the score.
+    if (player == undefined) {
+      return;
+    }
+    // Update player name
+    player.name = playerName;
+    await player.save();
+
+    // The score has already been tracked, so ignore it.
+    if (
+      (await this.getScoreSaberScore(
+        playerId,
+        leaderboard.id + "",
+        leaderboard.difficulty.difficulty,
+        leaderboard.difficulty.characteristic,
+        score.score
+      )) !== null
+    ) {
+      await logToChannel(
+        DiscordChannels.backendLogs,
+        new EmbedBuilder().setDescription(`Score ${score.scoreId} already tracked`)
+      );
+      return;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error
+    delete score.playerInfo;
+
+    await ScoreSaberScoreModel.create(score);
+    console.log(
+      `Tracked ScoreSaber score for "${playerName}"(${playerId}), difficulty: ${score.difficulty}, score: ${score.score}, pp: ${score.pp.toFixed(2)}pp, leaderboard: ${leaderboard.id}`
+    );
+  }
+
+  /**
+   * Tracks BeatLeader score.
+   *
+   * @param score the score to track
+   */
+  public static async trackBeatLeaderScore(score: BeatLeaderScoreToken) {
+    const { playerId, player: scorePlayer, leaderboard } = score;
+    const player: PlayerDocument | null = await PlayerModel.findById(playerId);
+    // Player is not tracked, so ignore the score.
+    if (player == undefined) {
+      return;
+    }
+
+    // The score has already been tracked, so ignore it.
+    if (
+      (await this.getAdditionalScoreData(
+        playerId,
+        leaderboard.song.hash,
+        leaderboard.difficulty.difficultyName,
+        score.baseScore
+      )) !== undefined
+    ) {
+      return;
+    }
+
+    const getMisses = (score: BeatLeaderScoreToken | BeatLeaderScoreImprovementToken) => {
+      return score.missedNotes + score.badCuts + score.bombCuts;
+    };
+
+    const difficulty = leaderboard.difficulty;
+    const difficultyKey = `${difficulty.difficultyName}-${difficulty.modeName}`;
+    const rawScoreImprovement = score.scoreImprovement;
+    const data = {
+      playerId: playerId,
+      songHash: leaderboard.song.hash.toUpperCase(),
+      songDifficulty: difficultyKey,
+      songScore: score.baseScore,
+      scoreId: score.id,
+      leaderboardId: leaderboard.id,
+      misses: {
+        misses: getMisses(score),
+        missedNotes: score.missedNotes,
+        bombCuts: score.bombCuts,
+        badCuts: score.badCuts,
+        wallsHit: score.wallsHit,
+      },
+      pauses: score.pauses,
+      fcAccuracy: score.fcAccuracy * 100,
+      fullCombo: score.fullCombo,
+      handAccuracy: {
+        left: score.accLeft,
+        right: score.accRight,
+      },
+      timestamp: new Date(Number(score.timeset) * 1000),
+    } as AdditionalScoreData;
+    if (rawScoreImprovement && rawScoreImprovement.score > 0) {
+      data.scoreImprovement = {
+        score: rawScoreImprovement.score,
+        misses: {
+          misses: getMisses(rawScoreImprovement),
+          missedNotes: rawScoreImprovement.missedNotes,
+          bombCuts: rawScoreImprovement.bombCuts,
+          badCuts: rawScoreImprovement.badCuts,
+          wallsHit: rawScoreImprovement.wallsHit,
+        },
+        accuracy: rawScoreImprovement.accuracy * 100,
+        handAccuracy: {
+          left: rawScoreImprovement.accLeft,
+          right: rawScoreImprovement.accRight,
+        },
+      };
+    }
+
+    await AdditionalScoreDataModel.create(data);
+    console.log(
+      `Tracked additional score data for "${scorePlayer.name}"(${playerId}), difficulty: ${difficultyKey}, score: ${score.baseScore}`
+    );
+  }
+
+  /**
+   * Gets the top tracked scores.
+   *
+   * @param amount the amount of scores to get
+   * @returns the top scores
+   */
+  public static async getTopScores(amount: number = 100) {
+    const foundScores = await ScoreSaberScoreModel.aggregate([
+      // Start sorting by timestamp descending using the new compound index
+      { $sort: { leaderboardId: 1, playerId: 1, timestamp: -1 } },
+      {
+        $group: {
+          _id: { leaderboardId: "$leaderboardId", playerId: "$playerId" },
+          latestScore: { $first: "$$ROOT" }, // Retrieve the latest score per group
+        },
+      },
+      // Sort by pp of the latest scores in descending order
+      { $sort: { "latestScore.pp": -1 } },
+      { $limit: amount },
+    ]);
+
+    // Collect unique leaderboard IDs
+    const leaderboardIds = [...new Set(foundScores.map(s => s.latestScore.leaderboardId))];
+    const leaderboardMap = await this.fetchLeaderboardsInBatch(leaderboardIds);
+
+    // Collect player IDs for batch retrieval
+    const playerIds = foundScores.map(result => result.latestScore.playerId);
+    const players = await PlayerModel.find({ _id: { $in: playerIds } }).exec();
+    const playerMap = new Map(players.map(player => [player._id.toString(), player]));
+
+    // Prepare to fetch additional data concurrently
+    const scoreDataPromises = foundScores.map(async result => {
+      const score: ScoreSaberScore = result.latestScore;
+      const leaderboardResponse = leaderboardMap[score.leaderboardId];
+      if (!leaderboardResponse) {
+        return null; // Skip if leaderboard data is not available
+      }
+
+      const { leaderboard, beatsaver } = leaderboardResponse;
+
+      // Fetch additional data concurrently
+      const [additionalData, previousScore] = await Promise.all([
+        this.getAdditionalScoreData(
+          score.playerId,
+          leaderboard.songHash,
+          `${leaderboard.difficulty.difficulty}-${leaderboard.difficulty.characteristic}`,
+          score.score
+        ),
+        this.getPreviousScore(score.playerId, leaderboard.id + "", score.timestamp),
+      ]);
+
+      // Attach additional and previous score data if available
+      if (additionalData) score.additionalData = additionalData;
+      if (previousScore) score.previousScore = previousScore;
+
+      // Attach player info if available
+      const player = playerMap.get(score.playerId.toString());
+      if (player) {
+        score.playerInfo = {
+          id: player._id,
+          name: player.name,
+        };
+      }
+
+      return {
+        score: score as ScoreSaberScore,
+        leaderboard: leaderboard,
+        beatSaver: beatsaver,
+      };
+    });
+    return (await Promise.all(scoreDataPromises)).filter(score => score !== null);
+  }
+
+  /**
+   * Fetches leaderboards in a batch.
+   *
+   * @param leaderboardIds the ids of the leaderboards
+   * @returns the fetched leaderboards
+   * @private
+   */
+  private static async fetchLeaderboardsInBatch(leaderboardIds: string[]) {
+    // Remove duplicates from leaderboardIds
+    const uniqueLeaderboardIds = Array.from(new Set(leaderboardIds));
+
+    const leaderboardResponses = await Promise.all(
+      uniqueLeaderboardIds.map(id => LeaderboardService.getLeaderboard<ScoreSaberLeaderboard>("scoresaber", id))
+    );
+
+    return leaderboardResponses.reduce(
+      (map, response) => {
+        if (response) map[response.leaderboard.id] = response;
+        return map;
+      },
+      {} as Record<string, { leaderboard: ScoreSaberLeaderboard; beatsaver?: BeatSaverMap }>
+    );
+  }
+
+  /**
+   * Gets the additional score data for a player's score.
+   *
+   * @param playerId the id of the player
+   * @param songHash the hash of the map
+   * @param songDifficulty the difficulty of the map
+   * @param songScore the score of the play
+   * @private
+   */
+  private static async getAdditionalScoreData(
+    playerId: string,
+    songHash: string,
+    songDifficulty: string,
+    songScore: number
+  ): Promise<AdditionalScoreData | undefined> {
+    const additionalData = await AdditionalScoreDataModel.findOne({
+      playerId: playerId,
+      songHash: songHash.toUpperCase(),
+      songDifficulty: songDifficulty,
+      songScore: songScore,
+    });
+    if (!additionalData) {
+      return undefined;
+    }
+    return additionalData.toObject();
+  }
+
+  /**
+   * Gets a ScoreSaber score.
+   *
+   * @param playerId the player who set the score
+   * @param leaderboardId the leaderboard id the score was set on
+   * @param difficulty the difficulty played
+   * @param characteristic the characteristic played
+   * @param score the score of the score set
+   */
+  public static async getScoreSaberScore(
+    playerId: string,
+    leaderboardId: string,
+    difficulty: MapDifficulty,
+    characteristic: MapCharacteristic,
+    score: number
+  ) {
+    return ScoreSaberScoreModel.findOne({
+      playerId: playerId,
+      leaderboardId: leaderboardId,
+      difficulty: difficulty,
+      characteristic: characteristic,
+      score: score,
+    });
+  }
+
   public static async getPlayerScores(
     leaderboardName: Leaderboards,
-    id: string,
+    playerId: string,
     page: number,
     sort: string,
     search?: string
   ): Promise<PlayerScoresResponse<unknown, unknown> | undefined> {
     return fetchWithCache(
       playerScoresCache,
-      `player-scores-${leaderboardName}-${id}-${page}-${sort}-${search}`,
+      `player-scores-${leaderboardName}-${playerId}-${page}-${sort}-${search}`,
       async () => {
-        const scores: PlayerScore<unknown, unknown>[] | undefined = [];
-        let beatSaverMap: BeatSaverMap | undefined;
+        const scores: PlayerScore<unknown, unknown>[] = [];
         let metadata: Metadata = new Metadata(0, 0, 0, 0); // Default values
 
         switch (leaderboardName) {
           case "scoresaber": {
             const leaderboardScores = await scoresaberService.lookupPlayerScores({
-              playerId: id,
-              page: page,
+              playerId,
+              page,
               sort: sort as ScoreSort,
-              search: search,
+              search,
             });
             if (leaderboardScores == undefined) {
               break;
@@ -155,23 +481,43 @@ export class ScoreService {
               leaderboardScores.metadata.itemsPerPage
             );
 
-            for (const token of leaderboardScores.playerScores) {
-              const score = getScoreSaberScoreFromToken(token.score, token.leaderboard);
-              if (score == undefined) {
-                continue;
-              }
-              const tokenLeaderboard = getScoreSaberLeaderboardFromToken(token.leaderboard);
-              if (tokenLeaderboard == undefined) {
-                continue;
-              }
-              beatSaverMap = await BeatSaverService.getMap(tokenLeaderboard.songHash);
+            const scorePromises = leaderboardScores.playerScores.map(async token => {
+              const leaderboard = getScoreSaberLeaderboardFromToken(token.leaderboard);
+              if (!leaderboard) return undefined;
 
-              scores.push({
-                score: score,
-                leaderboard: tokenLeaderboard,
-                beatSaver: beatSaverMap,
-              });
+              const score = getScoreSaberScoreFromToken(token.score, leaderboard, playerId);
+              if (!score) return undefined;
+
+              // Fetch additional data, previous score, and BeatSaver map concurrently
+              const [additionalData, previousScore, beatSaverMap] = await Promise.all([
+                this.getAdditionalScoreData(
+                  playerId,
+                  leaderboard.songHash,
+                  `${leaderboard.difficulty.difficulty}-${leaderboard.difficulty.characteristic}`,
+                  score.score
+                ),
+                this.getPreviousScore(playerId, leaderboard.id + "", score.timestamp),
+                BeatSaverService.getMap(leaderboard.songHash),
+              ]);
+
+              if (additionalData) {
+                score.additionalData = additionalData;
               }
+              if (previousScore) {
+                score.previousScore = previousScore;
+              }
+
+              return {
+                score: score,
+                leaderboard: leaderboard,
+                beatSaver: beatSaverMap,
+              } as PlayerScore<ScoreSaberScore, ScoreSaberLeaderboard>;
+            });
+
+            const resolvedScores = (await Promise.all(scorePromises)).filter(
+              (s): s is PlayerScore<ScoreSaberScore, ScoreSaberLeaderboard> => s !== undefined
+            );
+            scores.push(...resolvedScores);
             break;
           }
           default: {
@@ -191,17 +537,20 @@ export class ScoreService {
    * Gets scores for a leaderboard.
    *
    * @param leaderboardName the leaderboard to get the scores from
-   * @param id the leaderboard id
+   * @param leaderboardId the leaderboard id
    * @param page the page to get
    * @returns the scores
    */
   public static async getLeaderboardScores(
     leaderboardName: Leaderboards,
-    id: string,
+    leaderboardId: string,
     page: number
   ): Promise<LeaderboardScoresResponse<unknown, unknown> | undefined> {
-    return fetchWithCache(leaderboardScoresCache, `leaderboard-scores-${leaderboardName}-${id}-${page}`, async () => {
-      const scores: Score[] = [];
+    return fetchWithCache(
+      leaderboardScoresCache,
+      `leaderboard-scores-${leaderboardName}-${leaderboardId}-${page}`,
+      async () => {
+        const scores: ScoreType[] = [];
         let leaderboard: Leaderboard | undefined;
         let beatSaverMap: BeatSaverMap | undefined;
         let metadata: Metadata = new Metadata(0, 0, 0, 0); // Default values
@@ -210,7 +559,7 @@ export class ScoreService {
           case "scoresaber": {
             const leaderboardResponse = await LeaderboardService.getLeaderboard<ScoreSaberLeaderboard>(
               leaderboardName,
-            id
+              leaderboardId
             );
             if (leaderboardResponse == undefined) {
               throw new NotFoundError(`Leaderboard "${leaderboardName}" not found`);
@@ -218,13 +567,17 @@ export class ScoreService {
             leaderboard = leaderboardResponse.leaderboard;
             beatSaverMap = leaderboardResponse.beatsaver;
 
-          const leaderboardScores = await scoresaberService.lookupLeaderboardScores(id, page);
+            const leaderboardScores = await scoresaberService.lookupLeaderboardScores(leaderboardId, page);
             if (leaderboardScores == undefined) {
               break;
             }
 
             for (const token of leaderboardScores.scores) {
-            const score = getScoreSaberScoreFromToken(token, leaderboardResponse.leaderboard);
+              const score = getScoreSaberScoreFromToken(
+                token,
+                leaderboardResponse.leaderboard,
+                token.leaderboardPlayerInfo.id
+              );
               if (score == undefined) {
                 continue;
               }
@@ -250,6 +603,117 @@ export class ScoreService {
           beatSaver: beatSaverMap,
           metadata: metadata,
         };
+      }
+    );
+  }
+
+  /**
+   * Gets the player's score history for a map.
+   *
+   * @param playerId the player's id to get the previous scores for
+   * @param leaderboardId the leaderboard to get the previous scores on
+   * @param page the page to get
+   */
+  public static async getScoreHistory(
+    playerId: string,
+    leaderboardId: string,
+    page: number
+  ): Promise<Page<PlayerScore<ScoreSaberScore, ScoreSaberLeaderboard>>> {
+    const scores = await ScoreSaberScoreModel.find({ playerId: playerId, leaderboardId: leaderboardId })
+      .sort({ timestamp: -1 })
+      .skip(1);
+    if (scores == null || scores.length == 0) {
+      throw new NotFoundError(`No previous scores found for ${playerId} in ${leaderboardId}`);
+    }
+
+    return new Pagination<PlayerScore<ScoreSaberScore, ScoreSaberLeaderboard>>()
+      .setItemsPerPage(8)
+      .setTotalItems(scores.length)
+      .getPage(page, async () => {
+        const toReturn: PlayerScore<ScoreSaberScore, ScoreSaberLeaderboard>[] = [];
+        for (const score of scores) {
+          const leaderboardResponse = await LeaderboardService.getLeaderboard<ScoreSaberLeaderboard>(
+            "scoresaber",
+            leaderboardId
+          );
+          if (leaderboardResponse == undefined) {
+            throw new NotFoundError(`Leaderboard "${leaderboardId}" not found`);
+          }
+          const { leaderboard, beatsaver } = leaderboardResponse;
+
+          const additionalData = await this.getAdditionalScoreData(
+            playerId,
+            leaderboard.songHash,
+            `${leaderboard.difficulty.difficulty}-${leaderboard.difficulty.characteristic}`,
+            score.score
+          );
+          if (additionalData !== undefined) {
+            score.additionalData = additionalData;
+          }
+          const previousScore = await this.getPreviousScore(playerId, leaderboardId, score.timestamp);
+          if (previousScore !== undefined) {
+            score.previousScore = previousScore;
+          }
+
+          toReturn.push({
+            score: score as unknown as ScoreSaberScore,
+            leaderboard: leaderboard,
+            beatSaver: beatsaver,
           });
         }
+
+        return toReturn;
+      });
+  }
+
+  /**
+   * Gets the player's previous score for a map.
+   *
+   * @param playerId the player's id to get the previous score for
+   * @param leaderboardId the leaderboard to get the previous score on
+   * @param timestamp the score's timestamp to get the previous score for
+   * @returns the score, or undefined if none
+   */
+  public static async getPreviousScore(
+    playerId: string,
+    leaderboardId: string,
+    timestamp: Date
+  ): Promise<ScoreSaberPreviousScore | undefined> {
+    const scores = await ScoreSaberScoreModel.find({ playerId: playerId, leaderboardId: leaderboardId });
+    if (scores == null || scores.length == 0) {
+      return undefined;
+    }
+
+    const scoreIndex = scores.findIndex(score => score.timestamp.getTime() == timestamp.getTime());
+    const score = scores.find(score => score.timestamp.getTime() == timestamp.getTime());
+    if (scoreIndex == -1 || score == undefined) {
+      return undefined;
+    }
+    const previousScore = scores[scoreIndex - 1];
+    if (previousScore == undefined) {
+      return undefined;
+    }
+    return {
+      score: previousScore.score,
+      accuracy: previousScore.accuracy,
+      modifiers: previousScore.modifiers,
+      misses: previousScore.misses,
+      missedNotes: previousScore.missedNotes,
+      badCuts: previousScore.badCuts,
+      fullCombo: previousScore.fullCombo,
+      pp: previousScore.pp,
+      weight: previousScore.weight,
+      maxCombo: previousScore.maxCombo,
+      change: {
+        score: score.score - previousScore.score,
+        accuracy: score.accuracy - previousScore.accuracy,
+        misses: score.misses - previousScore.misses,
+        missedNotes: score.missedNotes - previousScore.missedNotes,
+        badCuts: score.badCuts - previousScore.badCuts,
+        pp: score.pp - previousScore.pp,
+        weight: score.weight && previousScore.weight && score.weight - previousScore.weight,
+        maxCombo: score.maxCombo - previousScore.maxCombo,
+      },
+    } as ScoreSaberPreviousScore;
+  }
 }

projects/common/package.json

@@ -19,6 +19,7 @@
     "typescript": "^5"
   },
   "dependencies": {
+    "@typegoose/auto-increment": "^4.7.0",
     "@typegoose/typegoose": "^12.8.0",
     "ky": "^1.7.2",
     "ws": "^8.18.0"

projects/common/src/cache.ts

@@ -1,6 +1,6 @@
 type CacheOptions = {
   /**
-   * The time the cached object will be valid for
+   * The time (in ms) the cached object will be valid for
    */
   ttl?: number;
 

projects/common/src/error/internal-server-error.ts

@@ -1,4 +1,4 @@
-import { HttpCode } from "../common/http-codes";
+import { HttpCode } from "../http-codes";
 
 export class InternalServerError extends Error {
   constructor(

projects/common/src/error/not-found-error.ts

@@ -1,4 +1,4 @@
-import { HttpCode } from "../common/http-codes";
+import { HttpCode } from "../http-codes";
 
 export class NotFoundError extends Error {
   constructor(

projects/common/src/error/rate-limit-error.ts

@@ -1,4 +1,4 @@
-import { HttpCode } from "../common/http-codes";
+import { HttpCode } from "../http-codes";
 
 export class RateLimitError extends Error {
   constructor(

projects/common/src/leaderboard/impl/scoresaber-leaderboard.ts

@@ -1,63 +0,0 @@
-import Leaderboard from "../leaderboard";
-import LeaderboardDifficulty from "../leaderboard-difficulty";
-import ScoreSaberLeaderboardToken from "../../types/token/scoresaber/score-saber-leaderboard-token";
-import { getDifficultyFromScoreSaberDifficulty } from "../../utils/scoresaber-utils";
-import { parseDate } from "../../utils/time-utils";
-
-export default interface ScoreSaberLeaderboard extends Leaderboard {
-  /**
-   * The star count for the leaderboard.
-   */
-  readonly stars: number;
-
-  /**
-   * The total amount of plays.
-   */
-  readonly plays: number;
-
-  /**
-   * The amount of plays today.
-   */
-  readonly dailyPlays: number;
-}
-
-/**
- * Parses a {@link ScoreSaberLeaderboardToken} into a {@link ScoreSaberLeaderboard}.
- *
- * @param token the token to parse
- */
-export function getScoreSaberLeaderboardFromToken(token: ScoreSaberLeaderboardToken): ScoreSaberLeaderboard {
-  const difficulty: LeaderboardDifficulty = {
-    leaderboardId: token.difficulty.leaderboardId,
-    difficulty: getDifficultyFromScoreSaberDifficulty(token.difficulty.difficulty),
-    gameMode: token.difficulty.gameMode,
-    difficultyRaw: token.difficulty.difficultyRaw,
-  };
-  return {
-    id: token.id,
-    songHash: token.songHash,
-    songName: token.songName,
-    songSubName: token.songSubName,
-    songAuthorName: token.songAuthorName,
-    levelAuthorName: token.levelAuthorName,
-    difficulty: difficulty,
-    difficulties:
-      token.difficulties != undefined && token.difficulties.length > 0
-        ? token.difficulties.map(difficulty => {
-            return {
-              leaderboardId: difficulty.leaderboardId,
-              difficulty: getDifficultyFromScoreSaberDifficulty(difficulty.difficulty),
-              gameMode: difficulty.gameMode,
-              difficultyRaw: difficulty.difficultyRaw,
-            };
-          })
-        : [difficulty],
-    maxScore: token.maxScore,
-    ranked: token.ranked,
-    songArt: token.coverImage,
-    timestamp: parseDate(token.createdDate),
-    stars: token.stars,
-    plays: token.plays,
-    dailyPlays: token.dailyPlays,
-  };
-}

projects/common/src/leaderboard/leaderboard-difficulty.ts

@@ -1,23 +0,0 @@
-import { Difficulty } from "../score/difficulty";
-
-export default interface LeaderboardDifficulty {
-  /**
-   * The id of the leaderboard.
-   */
-  leaderboardId: number;
-
-  /**
-   * The difficulty of the leaderboard.
-   */
-  difficulty: Difficulty;
-
-  /**
-   * The game mode of the leaderboard.
-   */
-  gameMode: string;
-
-  /**
-   * The raw difficulty of the leaderboard.
-   */
-  difficultyRaw: string;
-}

projects/common/src/leaderboard/leaderboard.ts

@@ -1,75 +0,0 @@
-import LeaderboardDifficulty from "./leaderboard-difficulty";
-
-export default interface Leaderboard {
-  /**
-   * The id of the leaderboard.
-   * @private
-   */
-  readonly id: number;
-
-  /**
-   * The hash of the song this leaderboard is for.
-   * @private
-   */
-  readonly songHash: string;
-
-  /**
-   * The name of the song this leaderboard is for.
-   * @private
-   */
-  readonly songName: string;
-
-  /**
-   * The sub name of the leaderboard.
-   * @private
-   */
-  readonly songSubName: string;
-
-  /**
-   * The author of the song this leaderboard is for.
-   * @private
-   */
-  readonly songAuthorName: string;
-
-  /**
-   * The author of the level this leaderboard is for.
-   * @private
-   */
-  readonly levelAuthorName: string;
-
-  /**
-   * The difficulty of the leaderboard.
-   * @private
-   */
-  readonly difficulty: LeaderboardDifficulty;
-
-  /**
-   * The difficulties of the leaderboard.
-   * @private
-   */
-  readonly difficulties: LeaderboardDifficulty[];
-
-  /**
-   * The maximum score of the leaderboard.
-   * @private
-   */
-  readonly maxScore: number;
-
-  /**
-   * Whether the leaderboard is ranked.
-   * @private
-   */
-  readonly ranked: boolean;
-
-  /**
-   * The link to the song art.
-   * @private
-   */
-  readonly songArt: string;
-
-  /**
-   * The date the leaderboard was created.
-   * @private
-   */
-  readonly timestamp: Date;
-}

projects/common/src/model/additional-score-data/additional-score-data.ts

@@ -0,0 +1,133 @@
+import { getModelForClass, modelOptions, prop, ReturnModelType, Severity } from "@typegoose/typegoose";
+import { Document } from "mongoose";
+import { HandAccuracy } from "./hand-accuracy";
+import { Misses } from "./misses";
+
+/**
+ * The model for additional score data.
+ */
+@modelOptions({
+  options: { allowMixed: Severity.ALLOW },
+  schemaOptions: {
+    collection: "additional-score-data",
+    toObject: {
+      virtuals: true,
+      transform: function (_, ret) {
+        delete ret._id;
+        delete ret.playerId;
+        delete ret.songHash;
+        delete ret.songDifficulty;
+        delete ret.songScore;
+        delete ret.__v;
+        return ret;
+      },
+    },
+  },
+})
+export class AdditionalScoreData {
+  /**
+   * The of the player who set the score.
+   */
+  @prop({ required: true, index: true })
+  public playerId!: string;
+
+  /**
+   * The hash of the song.
+   */
+  @prop({ required: true, index: true })
+  public songHash!: string;
+
+  /**
+   * The difficulty the score was set on.
+   */
+  @prop({ required: true, index: true })
+  public songDifficulty!: string;
+
+  /**
+   * The score of the play.
+   */
+  @prop({ required: true, index: true })
+  public songScore!: number;
+
+  // Above data is only so we can fetch it
+  // --------------------------------
+
+  /**
+   * The BeatLeader score id for this score.
+   */
+  @prop({ required: false })
+  public scoreId!: number;
+
+  /**
+   * The BeatLeader leaderboard id for this score.
+   */
+  @prop({ required: false })
+  public leaderboardId!: string;
+
+  /**
+   * The amount of pauses in the play.
+   */
+  @prop({ required: false })
+  public pauses!: number;
+
+  /**
+   * The miss data for the play.
+   */
+  @prop({ required: false, _id: false })
+  public misses!: Misses;
+
+  /**
+   * The hand accuracy for each hand.
+   * @private
+   */
+  @prop({ required: false, _id: false })
+  public handAccuracy!: HandAccuracy;
+
+  /**
+   * The full combo accuracy of the play.
+   */
+  @prop({ required: true })
+  public fcAccuracy!: number;
+
+  /**
+   * Whether the play was a full combo.
+   */
+  @prop({ required: true })
+  public fullCombo!: boolean;
+
+  /**
+   * The score improvement.
+   */
+  @prop({ required: false, _id: false })
+  public scoreImprovement?: {
+    /**
+     * The change in the score.
+     */
+    score: number;
+
+    /**
+     * The change in the accuracy.
+     */
+    accuracy: number;
+
+    /**
+     * The change in the misses.
+     */
+    misses: Misses;
+
+    /**
+     * The change in the hand accuracy.
+     */
+    handAccuracy: HandAccuracy;
+  };
+
+  /**
+   * The date the score was set on.
+   */
+  @prop({ required: true, index: true })
+  public timestamp!: Date;
+}
+
+export type AdditionalScoreDataDocument = AdditionalScoreData & Document;
+export const AdditionalScoreDataModel: ReturnModelType<typeof AdditionalScoreData> =
+  getModelForClass(AdditionalScoreData);

projects/common/src/model/additional-score-data/hand-accuracy.ts

@@ -0,0 +1,15 @@
+import { prop } from "@typegoose/typegoose";
+
+export class HandAccuracy {
+  /**
+   * The left hand accuracy.
+   */
+  @prop({ required: true })
+  left!: number;
+
+  /**
+   * The right hand accuracy.
+   */
+  @prop({ required: true })
+  right!: number;
+}

projects/common/src/model/additional-score-data/misses.ts

@@ -0,0 +1,33 @@
+import { prop } from "@typegoose/typegoose";
+
+export class Misses {
+  /**
+   * The amount of misses notes + bad cuts.
+   */
+  @prop({ required: true })
+  misses!: number;
+
+  /**
+   * The total amount of notes that were missed.
+   */
+  @prop({ required: true })
+  missedNotes!: number;
+
+  /**
+   * The amount of times a bomb was hit.
+   */
+  @prop({ required: true })
+  bombCuts!: number;
+
+  /**
+   * The amount of walls hit in the play.
+   */
+  @prop({ required: true })
+  wallsHit!: number;
+
+  /**
+   * The number of bad cuts.
+   */
+  @prop({ required: true })
+  badCuts!: number;
+}

projects/common/src/model/beatsaver/author.ts

@@ -0,0 +1,27 @@
+import { prop } from "@typegoose/typegoose";
+
+export default class BeatSaverAuthor {
+  /**
+   * The id of the author.
+   */
+  @prop({ required: true })
+  id: number;
+
+  /**
+   * The name of the mapper.
+   */
+  @prop({ required: true })
+  name: string;
+
+  /**
+   * The avatar URL for the mapper.
+   */
+  @prop({ required: true })
+  avatar: string;
+
+  constructor(id: number, name: string, avatar: string) {
+    this.id = id;
+    this.name = name;
+    this.avatar = avatar;
+  }
+}

projects/common/src/model/beatsaver/beatsaver-author.ts

@@ -1,13 +0,0 @@
-import { prop } from "@typegoose/typegoose";
-
-export default class BeatsaverAuthor {
-  /**
-   * The id of the author.
-   */
-  @prop({ required: true })
-  id: number;
-
-  constructor(id: number) {
-    this.id = id;
-  }
-}

projects/common/src/model/beatsaver/beatsaver-map.ts

@@ -1,57 +0,0 @@
-import { getModelForClass, modelOptions, prop, ReturnModelType, Severity } from "@typegoose/typegoose";
-import { Document } from "mongoose";
-import BeatsaverAuthor from "./beatsaver-author";
-
-/**
- * The model for a BeatSaver map.
- */
-@modelOptions({
-  options: { allowMixed: Severity.ALLOW },
-  schemaOptions: {
-    toObject: {
-      virtuals: true,
-      transform: function (_, ret) {
-        ret.id = ret._id;
-        delete ret._id;
-        delete ret.__v;
-        return ret;
-      },
-    },
-  },
-})
-export class BeatSaverMap {
-  /**
-   * The internal MongoDB ID (_id).
-   */
-  @prop({ required: true })
-  private _id!: string;
-
-  /**
-   * The bsr code for the map.
-   * @private
-   */
-  @prop({ required: false })
-  public bsr!: string;
-
-  /**
-   * The author of the map.
-   */
-  @prop({ required: false, _id: false, type: () => BeatsaverAuthor })
-  public author!: BeatsaverAuthor;
-
-  /**
-   * True if the map is unknown on beatsaver.
-   */
-  @prop({ required: false })
-  public unknownMap?: boolean;
-
-  /**
-   * Exposes `id` as a virtual field mapped from `_id`.
-   */
-  public get id(): string {
-    return this._id;
-  }
-}
-
-export type BeatSaverMapDocument = BeatSaverMap & Document;
-export const BeatSaverMapModel: ReturnModelType<typeof BeatSaverMap> = getModelForClass(BeatSaverMap);

projects/common/src/model/beatsaver/map-difficulty.ts

@@ -0,0 +1,128 @@
+import { prop } from "@typegoose/typegoose";
+import { type MapDifficulty } from "../../score/map-difficulty";
+
+export default class BeatSaverMapDifficulty {
+  /**
+   * The NJS of this difficulty.
+   */
+  @prop({ required: true })
+  njs: number;
+
+  /**
+   * The NJS offset of this difficulty.
+   */
+  @prop({ required: true })
+  offset: number;
+
+  /**
+   * The amount of notes in this difficulty.
+   */
+  @prop({ required: true })
+  notes: number;
+
+  /**
+   * The amount of bombs in this difficulty.
+   */
+  @prop({ required: true })
+  bombs: number;
+
+  /**
+   * The amount of obstacles in this difficulty.
+   */
+  @prop({ required: true })
+  obstacles: number;
+
+  /**
+   * The notes per second in this difficulty.
+   */
+  @prop({ required: true })
+  nps: number;
+
+  /**
+   * The characteristic of this difficulty.
+   */
+  @prop({ required: true, enum: ["Standard", "Lawless"] })
+  characteristic: "Standard" | "Lawless";
+
+  /**
+   * The difficulty level.
+   */
+  @prop({ required: true })
+  difficulty: MapDifficulty;
+
+  /**
+   * The amount of lighting events in this difficulty.
+   */
+  @prop({ required: true })
+  events: number;
+
+  /**
+   * Whether this difficulty uses Chroma.
+   */
+  @prop({ required: true, default: false })
+  chroma: boolean;
+
+  /**
+   * Does this difficulty use Mapping Extensions.
+   */
+  @prop({ required: true, default: false })
+  mappingExtensions: boolean;
+
+  /**
+   * Does this difficulty use Noodle Extensions.
+   */
+  @prop({ required: true, default: false })
+  noodleExtensions: boolean;
+
+  /**
+   * Whether this difficulty uses cinema mode.
+   */
+  @prop({ required: true, default: false })
+  cinema: boolean;
+
+  /**
+   * The maximum score achievable in this difficulty.
+   */
+  @prop({ required: true })
+  maxScore: number;
+
+  /**
+   * The custom label for this difficulty.
+   */
+  @prop()
+  label: string;
+
+  constructor(
+    njs: number,
+    offset: number,
+    notes: number,
+    bombs: number,
+    obstacles: number,
+    nps: number,
+    characteristic: "Standard" | "Lawless",
+    difficulty: MapDifficulty,
+    events: number,
+    chroma: boolean,
+    mappingExtensions: boolean,
+    noodleExtensions: boolean,
+    cinema: boolean,
+    maxScore: number,
+    label: string
+  ) {
+    this.njs = njs;
+    this.offset = offset;
+    this.notes = notes;
+    this.bombs = bombs;
+    this.obstacles = obstacles;
+    this.nps = nps;
+    this.characteristic = characteristic;
+    this.difficulty = difficulty;
+    this.events = events;
+    this.chroma = chroma;
+    this.mappingExtensions = mappingExtensions;
+    this.noodleExtensions = noodleExtensions;
+    this.cinema = cinema;
+    this.maxScore = maxScore;
+    this.label = label;
+  }
+}

projects/common/src/model/beatsaver/map-metadata.ts

@@ -0,0 +1,55 @@
+import { prop } from "@typegoose/typegoose";
+
+export default class BeatSaverMapMetadata {
+  /**
+   * The bpm of the song.
+   */
+  @prop({ required: true })
+  bpm: number;
+
+  /**
+   * The song's length in seconds.
+   */
+  @prop({ required: true })
+  duration: number;
+
+  /**
+   * The song's name.
+   */
+  @prop({ required: true })
+  songName: string;
+
+  /**
+   * The song's sub name.
+   */
+  @prop({ required: false })
+  songSubName: string;
+
+  /**
+   * The artist(s) name.
+   */
+  @prop({ required: true })
+  songAuthorName: string;
+
+  /**
+   * The level mapper(s) name.
+   */
+  @prop({ required: true })
+  levelAuthorName: string;
+
+  constructor(
+    bpm: number,
+    duration: number,
+    songName: string,
+    songSubName: string,
+    songAuthorName: string,
+    levelAuthorName: string
+  ) {
+    this.bpm = bpm;
+    this.duration = duration;
+    this.songName = songName;
+    this.songSubName = songSubName;
+    this.songAuthorName = songAuthorName;
+    this.levelAuthorName = levelAuthorName;
+  }
+}

projects/common/src/model/beatsaver/map-version.ts

@@ -0,0 +1,31 @@
+import { modelOptions, prop, Severity } from "@typegoose/typegoose";
+import BeatSaverMapDifficulty from "./map-difficulty";
+
+@modelOptions({
+  options: { allowMixed: Severity.ALLOW },
+})
+export default class BeatSaverMapVersion {
+  /**
+   * The hash of this map.
+   */
+  @prop({ required: true })
+  hash: string;
+
+  /**
+   * The date the map was created.
+   */
+  @prop({ required: true })
+  createdAt: Date;
+
+  /**
+   * The difficulties of this map.
+   */
+  @prop({ required: true })
+  difficulties: BeatSaverMapDifficulty[];
+
+  constructor(hash: string, createdAt: Date, difficulties: BeatSaverMapDifficulty[]) {
+    this.hash = hash;
+    this.createdAt = createdAt;
+    this.difficulties = difficulties;
+  }
+}

projects/common/src/model/beatsaver/map.ts

@@ -0,0 +1,99 @@
+import { getModelForClass, modelOptions, prop, ReturnModelType, Severity } from "@typegoose/typegoose";
+import { Document } from "mongoose";
+import BeatSaverAuthor from "./author";
+import BeatSaverMapVersion from "./map-version";
+import BeatSaverMapMetadata from "./map-metadata";
+
+/**
+ * The model for a BeatSaver map.
+ */
+@modelOptions({
+  options: { allowMixed: Severity.ALLOW },
+  schemaOptions: {
+    collection: "beatsaver-maps",
+    toObject: {
+      virtuals: true,
+      transform: function (_, ret) {
+        ret.id = ret._id;
+        delete ret._id;
+        delete ret.__v;
+        return ret;
+      },
+    },
+  },
+})
+export class BeatSaverMap {
+  /**
+   * The internal MongoDB ID (_id).
+   */
+  @prop({ required: true })
+  private _id!: string;
+
+  /**
+   * The name of the map.
+   */
+  @prop({ required: false })
+  public name!: string;
+
+  /**
+   * The description of the map.
+   */
+  @prop({ required: false })
+  public description!: string;
+
+  /**
+   * The bsr code for the map.
+   */
+  @prop({ required: false })
+  public bsr!: string;
+
+  /**
+   * The author of the map.
+   */
+  @prop({ required: false, _id: false, type: () => BeatSaverAuthor })
+  public author!: BeatSaverAuthor;
+
+  /**
+   * The versions of the map.
+   */
+  @prop({ required: false, _id: false, type: () => [BeatSaverMapVersion] })
+  public versions!: BeatSaverMapVersion[];
+
+  /**
+   * The metadata of the map.
+   */
+  @prop({ required: false, _id: false, type: () => BeatSaverMapMetadata })
+  public metadata!: BeatSaverMapMetadata;
+
+  /**
+   * True if the map is not found on beatsaver.
+   */
+  @prop({ required: false })
+  public notFound?: boolean;
+
+  /**
+   * The last time the map data was refreshed.
+   */
+  @prop({ required: true })
+  public lastRefreshed!: Date;
+
+  /**
+   * Exposes `id` as a virtual field mapped from `_id`.
+   */
+  public get id(): string {
+    return this._id;
+  }
+
+  /**
+   * Should the map data be refreshed?
+   *
+   * @returns true if the map data should be refreshed
+   */
+  public shouldRefresh(): boolean {
+    const now = new Date();
+    return now.getTime() - this.lastRefreshed.getTime() > 1000 * 60 * 60 * 24 * 3; // 3 days
+  }
+}
+
+export type BeatSaverMapDocument = BeatSaverMap & Document;
+export const BeatSaverMapModel: ReturnModelType<typeof BeatSaverMap> = getModelForClass(BeatSaverMap);

projects/common/src/model/leaderboard/impl/scoresaber-leaderboard.ts

@@ -0,0 +1,56 @@
+import Leaderboard from "../leaderboard";
+import { type LeaderboardStatus } from "../leaderboard-status";
+import { getModelForClass, modelOptions, Prop, ReturnModelType, Severity } from "@typegoose/typegoose";
+import { Document } from "mongoose";
+
+@modelOptions({
+  options: { allowMixed: Severity.ALLOW },
+  schemaOptions: {
+    collection: "scoresaber-leaderboards",
+    toObject: {
+      virtuals: true,
+      transform: function (_, ret) {
+        ret.id = ret._id;
+        delete ret._id;
+        delete ret.__v;
+        return ret;
+      },
+    },
+  },
+})
+export default class ScoreSaberLeaderboardInternal extends Leaderboard {
+  /**
+   * The star count for the leaderboard.
+   */
+  @Prop({ required: true })
+  readonly stars!: number;
+
+  /**
+   * The total amount of plays.
+   */
+  @Prop({ required: true })
+  readonly plays!: number;
+
+  /**
+   * The amount of plays today.
+   */
+  @Prop({ required: true })
+  readonly dailyPlays!: number;
+
+  /**
+   * Whether this leaderboard is qualified to be ranked.
+   */
+  @Prop({ required: true })
+  readonly qualified!: boolean;
+
+  /**
+   * The status of the map.
+   */
+  @Prop({ required: true })
+  readonly status!: LeaderboardStatus;
+}
+
+export type ScoreSaberLeaderboard = InstanceType<typeof ScoreSaberLeaderboardInternal>;
+export type ScoreSaberLeaderboardDocument = ScoreSaberLeaderboard & Document;
+export const ScoreSaberLeaderboardModel: ReturnModelType<typeof ScoreSaberLeaderboardInternal> =
+  getModelForClass(ScoreSaberLeaderboardInternal);

projects/common/src/model/leaderboard/leaderboard-difficulty.ts

@@ -0,0 +1,29 @@
+import { type MapDifficulty } from "../../score/map-difficulty";
+import { type MapCharacteristic } from "../../types/map-characteristic";
+import { Prop } from "@typegoose/typegoose";
+
+export default class LeaderboardDifficulty {
+  /**
+   * The id of the leaderboard.
+   */
+  @Prop({ required: true })
+  leaderboardId!: number;
+
+  /**
+   * The difficulty of the leaderboard.
+   */
+  @Prop({ required: true })
+  difficulty!: MapDifficulty;
+
+  /**
+   * The characteristic of the leaderboard.
+   */
+  @Prop({ required: true })
+  characteristic!: MapCharacteristic;
+
+  /**
+   * The raw difficulty of the leaderboard.
+   */
+  @Prop({ required: true })
+  difficultyRaw!: string;
+}

projects/common/src/model/leaderboard/leaderboard-status.ts

@@ -0,0 +1,4 @@
+/**
+ * The status of the leaderboard.
+ */
+export type LeaderboardStatus = "Unranked" | "Ranked" | "Qualified";

projects/common/src/model/leaderboard/leaderboard.ts

@@ -0,0 +1,99 @@
+import LeaderboardDifficulty from "./leaderboard-difficulty";
+import { Prop } from "@typegoose/typegoose";
+
+export default class Leaderboard {
+  /**
+   * The id of the leaderboard.
+   * @private
+   */
+  @Prop({ required: true })
+  private readonly _id?: number;
+
+  /**
+   * The hash of the song this leaderboard is for.
+   * @private
+   */
+  @Prop({ required: true })
+  readonly songHash!: string;
+
+  /**
+   * The name of the song this leaderboard is for.
+   * @private
+   */
+  @Prop({ required: true })
+  readonly songName!: string;
+
+  /**
+   * The sub name of the leaderboard.
+   * @private
+   */
+  @Prop({ required: true })
+  readonly songSubName!: string;
+
+  /**
+   * The author of the song this leaderboard is for.
+   * @private
+   */
+  @Prop({ required: true })
+  readonly songAuthorName!: string;
+
+  /**
+   * The author of the level this leaderboard is for.
+   * @private
+   */
+  @Prop({ required: true })
+  readonly levelAuthorName!: string;
+
+  /**
+   * The difficulty of the leaderboard.
+   * @private
+   */
+  @Prop({ required: true, _id: false, type: () => LeaderboardDifficulty })
+  readonly difficulty!: LeaderboardDifficulty;
+
+  /**
+   * The difficulties of the leaderboard.
+   * @private
+   */
+  @Prop({ required: true, _id: false, type: () => [LeaderboardDifficulty] })
+  readonly difficulties!: LeaderboardDifficulty[];
+
+  /**
+   * The maximum score of the leaderboard.
+   * @private
+   */
+  @Prop({ required: true })
+  readonly maxScore!: number;
+
+  /**
+   * Whether the leaderboard is ranked.
+   * @private
+   */
+  @Prop({ required: true })
+  readonly ranked!: boolean;
+
+  /**
+   * The link to the song art.
+   * @private
+   */
+  @Prop({ required: true })
+  readonly songArt!: string;
+
+  /**
+   * The date the leaderboard was created.
+   * @private
+   */
+  @Prop({ required: true })
+  readonly timestamp!: Date;
+
+  /**
+   * The date the leaderboard was last refreshed.
+   * @private
+   */
+  @Prop({ required: true })
+  lastRefreshed?: Date;
+
+  get id(): number {
+    return this._id ?? 0;
+  }
+}

projects/common/src/model/player.ts

@@ -14,12 +14,24 @@ export class Player {
   @prop()
   public _id!: string;
 
+  /**
+   * The player's name.
+   */
+  @prop()
+  public name?: string;
+
   /**
    * The player's statistic history.
    */
   @prop()
   private statisticHistory?: Record<string, PlayerHistory>;
 
+  /**
+   * Whether the player has their scores seeded.
+   */
+  @prop()
+  public seededScores?: boolean;
+
   /**
    * The date the player was last tracked.
    */
@@ -63,7 +75,7 @@ export class Player {
     const statisticHistory = this.getStatisticHistory();
     const history: Record<string, PlayerHistory> = {};
 
-    for (let i = 0; i < days; i++) {
+    for (let i = 0; i <= days; i++) {
       const date = formatDateMinimal(getMidnightAlignedDate(getDaysAgoDate(i)));
       const playerHistory = statisticHistory[date];
       if (playerHistory !== undefined && Object.keys(playerHistory).length > 0) {

projects/common/src/model/score/impl/scoresaber-score.ts

@@ -0,0 +1,102 @@
+import { getModelForClass, index, modelOptions, plugin, Prop, ReturnModelType, Severity } from "@typegoose/typegoose";
+import Score from "../score";
+import { type ScoreSaberLeaderboardPlayerInfoToken } from "../../../types/token/scoresaber/score-saber-leaderboard-player-info-token";
+import { Document } from "mongoose";
+import { AutoIncrementID } from "@typegoose/auto-increment";
+import { PreviousScore } from "../previous-score";
+
+@modelOptions({
+  options: { allowMixed: Severity.ALLOW },
+  schemaOptions: {
+    collection: "scoresaber-scores",
+    toObject: {
+      virtuals: true,
+      transform: function (_, ret) {
+        ret.id = ret._id;
+        delete ret._id;
+        delete ret.__v;
+        return ret;
+      },
+    },
+  },
+})
+@index({ leaderboardId: 1, playerId: 1, timestamp: -1 }) // Compound index for optimized queries
+@plugin(AutoIncrementID, {
+  field: "_id",
+  startAt: 1,
+  trackerModelName: "scores",
+  trackerCollection: "increments",
+  overwriteModelName: "scoresaber-scores",
+})
+export class ScoreSaberScoreInternal extends Score {
+  /**
+   * The score's id.
+   */
+  @Prop({ required: true, index: true })
+  public readonly scoreId!: string;
+
+  /**
+   * The leaderboard the score was set on.
+   */
+  @Prop({ required: true, index: true })
+  public readonly leaderboardId!: number;
+
+  /**
+   * The amount of pp for the score.
+   * @private
+   */
+  @Prop({ required: true, index: true })
+  public pp!: number;
+
+  /**
+   * The weight of the score, or undefined if not ranked.
+   * @private
+   */
+  @Prop()
+  public readonly weight?: number;
+
+  /**
+   * The max combo of the score.
+   */
+  @Prop({ required: true })
+  public readonly maxCombo!: number;
+
+  /**
+   * The previous score, if any.
+   */
+  public previousScore?: ScoreSaberPreviousScore;
+}
+
+class ScoreSaberScorePublic extends ScoreSaberScoreInternal {
+  /**
+   * The player who set the score.
+   */
+  public playerInfo!: ScoreSaberLeaderboardPlayerInfoToken;
+}
+
+export type ScoreSaberPreviousScore = PreviousScore & {
+  /**
+   * The pp of the previous score.
+   */
+  pp: number;
+
+  /**
+   * The weight of the previous score.
+   */
+  weight: number;
+
+  /**
+   * The max combo of the previous score.
+   */
+  maxCombo: number;
+
+  /**
+   * The change between the previous score and the current score.
+   */
+  change?: ScoreSaberPreviousScore;
+};
+
+export type ScoreSaberScore = InstanceType<typeof ScoreSaberScorePublic>;
+export type ScoreSaberScoreDocument = ScoreSaberScore & Document;
+export const ScoreSaberScoreModel: ReturnModelType<typeof ScoreSaberScoreInternal> =
+  getModelForClass(ScoreSaberScoreInternal);

projects/common/src/model/score/previous-score.ts

@@ -0,0 +1,38 @@
+import { Modifier } from "../../score/modifier";
+
+export type PreviousScore = {
+  /**
+   * The score of the previous score.
+   */
+  score: number;
+
+  /**
+   * The accuracy of the previous score.
+   */
+  accuracy: number;
+
+  /**
+   * The modifiers of the previous score.
+   */
+  modifiers?: Modifier[];
+
+  /**
+   * The misses of the previous score.
+   */
+  misses: number;
+
+  /**
+   * The missed notes of the previous score.
+   */
+  missedNotes: number;
+
+  /**
+   * The bad cuts of the previous score.
+   */
+  badCuts: number;
+
+  /**
+   * The full combo of the previous score.
+   */
+  fullCombo?: boolean;
+};

projects/common/src/model/score/score.ts

@@ -0,0 +1,102 @@
+import { Modifier } from "../../score/modifier";
+import { AdditionalScoreData } from "../additional-score-data/additional-score-data";
+import { prop } from "@typegoose/typegoose";
+import { type MapDifficulty } from "../../score/map-difficulty";
+import { type MapCharacteristic } from "../../types/map-characteristic";
+
+/**
+ * The model for a score.
+ */
+export default class Score {
+  /**
+   * The internal score id.
+   */
+  @prop()
+  public _id?: number;
+
+  /**
+   * The id of the player who set the score.
+   */
+  @prop({ required: true, index: true })
+  public readonly playerId!: string;
+
+  /**
+   * The map difficulty played in the score.
+   */
+  @prop({ required: true })
+  public readonly difficulty!: MapDifficulty;
+
+  /**
+   * The characteristic of the map.
+   */
+  @prop({ required: true })
+  public readonly characteristic!: MapCharacteristic;
+
+  /**
+   * The base score for the score.
+   * @private
+   */
+  @prop({ required: true })
+  public readonly score!: number;
+
+  /**
+   * The accuracy of the score.
+   */
+  @prop({ required: true })
+  public readonly accuracy!: number;
+
+  /**
+   * The rank for the score.
+   * @private
+   */
+  @prop({ required: true })
+  public readonly rank!: number;
+
+  /**
+   * The modifiers used on the score.
+   * @private
+   */
+  @prop({ enum: () => Modifier, type: String, required: true })
+  public readonly modifiers!: Modifier[];
+
+  /**
+   * The total amount of misses.
+   * @private
+   */
+  @prop({ required: true })
+  public readonly misses!: number;
+
+  /**
+   * The amount of missed notes.
+   */
+  @prop({ required: true })
+  public readonly missedNotes!: number;
+
+  /**
+   * The amount of bad cuts.
+   * @private
+   */
+  @prop({ required: true })
+  public readonly badCuts!: number;
+
+  /**
+   * Whether every note was hit.
+   * @private
+   */
+  @prop({ required: true })
+  public readonly fullCombo!: boolean;
+
+  /**
+   * The additional data for the score.
+   */
+  public additionalData?: AdditionalScoreData;
+
+  /**
+   * The time the score was set.
+   * @private
+   */
+  @prop({ required: true, index: true })
+  public readonly timestamp!: Date;
+}
+
+export type ScoreType = InstanceType<typeof Score>;

projects/common/src/pagination.ts

@@ -0,0 +1,103 @@
+import { Metadata } from "./types/metadata";
+import { NotFoundError } from "./error/not-found-error";
+
+type FetchItemsFunction<T> = (fetchItems: FetchItems) => Promise<T[]>;
+
+export class Pagination<T> {
+  private itemsPerPage: number = 0;
+  private totalItems: number = 0;
+  private items: T[] | null = null; // Optional array to hold set items
+
+  /**
+   * Sets the number of items per page.
+   * @param itemsPerPage - The number of items per page.
+   * @returns the pagination
+   */
+  setItemsPerPage(itemsPerPage: number): Pagination<T> {
+    this.itemsPerPage = itemsPerPage;
+    return this;
+  }
+
+  /**
+   * Sets the items to paginate.
+   * @param items - The items to paginate.
+   * @returns the pagination
+   */
+  setItems(items: T[]): Pagination<T> {
+    this.items = items;
+    this.totalItems = items.length;
+    return this;
+  }
+
+  /**
+   * Sets the total number of items.
+   * @param totalItems - Total number of items.
+   * @returns the pagination
+   */
+  setTotalItems(totalItems: number): Pagination<T> {
+    this.totalItems = totalItems;
+    return this;
+  }
+
+  /**
+   * Gets a page of items, using either static items or a dynamic fetchItems callback.
+   * @param page - The page number to retrieve.
+   * @param fetchItems - The async function to fetch items if setItems was not used.
+   * @returns A promise resolving to the page of items.
+   * @throws throws an error if the page number is invalid.
+   */
+  async getPage(page: number, fetchItems?: FetchItemsFunction<T>): Promise<Page<T>> {
+    const totalPages = Math.ceil(this.totalItems / this.itemsPerPage);
+
+    if (page < 1 || page > totalPages) {
+      throw new NotFoundError("Invalid page number");
+    }
+
+    // Calculate the range of items to fetch for the current page
+    const start = (page - 1) * this.itemsPerPage;
+    const end = start + this.itemsPerPage;
+
+    let pageItems: T[];
+
+    // Use set items if they are present, otherwise use fetchItems callback
+    if (this.items) {
+      pageItems = this.items.slice(start, end);
+    } else if (fetchItems) {
+      pageItems = await fetchItems(new FetchItems(start, end));
+    } else {
+      throw new Error("Items function is not set and no fetchItems callback provided");
+    }
+
+    return new Page<T>(pageItems, new Metadata(totalPages, this.totalItems, page, this.itemsPerPage));
+  }
+}
+
+class FetchItems {
+  readonly start: number;
+  readonly end: number;
+
+  constructor(start: number, end: number) {
+    this.start = start;
+    this.end = end;
+  }
+}
+
+export class Page<T> {
+  readonly items: T[];
+  readonly metadata: Metadata;
+
+  constructor(items: T[], metadata: Metadata) {
+    this.items = items;
+    this.metadata = metadata;
+  }
+
+  /**
+   * Converts the page to a JSON object.
+   */
+  toJSON() {
+    return {
+      items: this.items,
+      metadata: this.metadata,
+    };
+  }
+}

projects/common/src/player/impl/scoresaber-player.ts

@@ -1,11 +1,5 @@
 import Player, { StatisticChange } from "../player";
-import ky from "ky";
 import { PlayerHistory } from "../player-history";
-import ScoreSaberPlayerToken from "../../types/token/scoresaber/score-saber-player-token";
-import { formatDateMinimal, getDaysAgoDate, getMidnightAlignedDate } from "../../utils/time-utils";
-import { getPageFromRank } from "../../utils/utils";
-import { Config } from "../../config";
-import { getValueFromHistory } from "../../utils/player-utils";
 
 /**
  * A ScoreSaber player.
@@ -29,7 +23,7 @@ export default interface ScoreSaberPlayer extends Player {
   /**
    * The role the player has.
    */
-  role: ScoreSaberRole | undefined;
+  role: string | undefined;
 
   /**
    * The badges the player has.
@@ -73,217 +67,6 @@ export default interface ScoreSaberPlayer extends Player {
   isBeingTracked?: boolean;
 }
 
-/**
- * Gets the ScoreSaber Player from an {@link ScoreSaberPlayerToken}.
- *
- * @param token the player token
- * @param playerIdCookie the id of the claimed player
- */
-export async function getScoreSaberPlayerFromToken(
-  token: ScoreSaberPlayerToken,
-  playerIdCookie?: string
-): Promise<ScoreSaberPlayer> {
-  const bio: ScoreSaberBio = {
-    lines: token.bio?.split("\n") || [],
-    linesStripped: token.bio?.replace(/<[^>]+>/g, "")?.split("\n") || [],
-  };
-  const role = token.role == null ? undefined : (token.role as ScoreSaberRole);
-  const badges: ScoreSaberBadge[] =
-    token.badges?.map(badge => {
-      return {
-        url: badge.image,
-        description: badge.description,
-      };
-    }) || [];
-
-  let isBeingTracked = false;
-  const todayDate = formatDateMinimal(getMidnightAlignedDate(new Date()));
-  let statisticHistory: { [key: string]: PlayerHistory } = {};
-
-  try {
-    const { statistics: history } = await ky
-      .get<{
-        statistics: { [key: string]: PlayerHistory };
-      }>(
-        `${Config.apiUrl}/player/history/${token.id}${playerIdCookie && playerIdCookie == token.id ? "?createIfMissing=true" : ""}`
-      )
-      .json();
-    if (history) {
-      // Use the latest data for today
-      history[todayDate] = {
-        ...{
-          scores: {
-            rankedScores: 0,
-            unrankedScores: 0,
-            totalScores: 0,
-            totalRankedScores: 0,
-          },
-        },
-        ...history[todayDate],
-        rank: token.rank,
-        countryRank: token.countryRank,
-        pp: token.pp,
-        accuracy: {
-          averageRankedAccuracy: token.scoreStats.averageRankedAccuracy,
-        },
-      };
-
-      isBeingTracked = true;
-    }
-    statisticHistory = history;
-  } catch (e) {}
-
-  const playerRankHistory = token.histories.split(",").map(value => {
-    return parseInt(value);
-  });
-  playerRankHistory.push(token.rank);
-
-  let missingDays = 0;
-  let daysAgo = 0; // Start from current day
-  for (let i = playerRankHistory.length - 1; i >= 0; i--) {
-    const rank = playerRankHistory[i];
-    if (rank == 999_999) {
-      continue;
-    }
-
-    const date = getMidnightAlignedDate(getDaysAgoDate(daysAgo));
-    daysAgo += 1;
-
-    const dateKey = formatDateMinimal(date);
-    if (!statisticHistory[dateKey] || statisticHistory[dateKey].rank == undefined) {
-      missingDays += 1;
-      statisticHistory[dateKey] = {
-        ...statisticHistory[dateKey],
-        rank: rank,
-        scores: {
-          totalScores: token.scoreStats.totalPlayCount,
-          totalRankedScores: token.scoreStats.rankedPlayCount,
-        },
-      };
-    }
-  }
-
-  if (missingDays > 0 && missingDays != playerRankHistory.length) {
-    console.log(
-      `Player has ${missingDays} missing day${missingDays > 1 ? "s" : ""}, filling in with fallback history...`
-    );
-  }
-
-  // Sort the fallback history
-  statisticHistory = Object.entries(statisticHistory)
-    .sort((a, b) => Date.parse(b[0]) - Date.parse(a[0]))
-    .reduce((obj, [key, value]) => ({ ...obj, [key]: value }), {});
-
-  /**
-   * Gets the change in the given stat
-   *
-   * @param statType the stat to check
-   * @param daysAgo the amount of days ago to get the stat for
-   * @return the change
-   */
-  const getStatisticChange = (statType: string, daysAgo: number = 1): number | undefined => {
-    const todayStats = statisticHistory[todayDate];
-    let otherDate: Date | undefined;
-
-    // Use the same logic as the first version to get the date exactly 'daysAgo' days earlier
-    if (daysAgo === 1) {
-      otherDate = getMidnightAlignedDate(getDaysAgoDate(1)); // Yesterday
-    } else {
-      const targetDate = getDaysAgoDate(daysAgo);
-
-      // Filter available dates to find the closest one to the target
-      const availableDates = Object.keys(statisticHistory)
-        .map(dateKey => new Date(dateKey))
-        .filter(date => {
-          // Convert date back to the correct format for statisticHistory lookup
-          const formattedDate = formatDateMinimal(date);
-          const statsForDate = statisticHistory[formattedDate];
-          const hasStat = statsForDate && statType in statsForDate;
-
-          // Only consider past dates with the required statType
-          const isPast = date.getTime() < new Date().getTime();
-          return hasStat && isPast;
-        });
-
-      // If no valid dates are found, return undefined
-      if (availableDates.length === 0) {
-        return undefined;
-      }
-
-      // Find the closest date from the filtered available dates
-      otherDate = availableDates.reduce((closestDate, currentDate) => {
-        const currentDiff = Math.abs(currentDate.getTime() - targetDate.getTime());
-        const closestDiff = Math.abs(closestDate.getTime() - targetDate.getTime());
-        return currentDiff < closestDiff ? currentDate : closestDate;
-      }, availableDates[0]); // Start with the first available date
-    }
-
-    // Ensure todayStats exists and contains the statType
-    if (!todayStats || !(statType in todayStats)) {
-      return undefined;
-    }
-
-    const otherStats = statisticHistory[formatDateMinimal(otherDate)]; // This is now validated
-
-    // Ensure otherStats exists and contains the statType
-    if (!otherStats || !(statType in otherStats)) {
-      return undefined;
-    }
-
-    const statToday = getValueFromHistory(todayStats, statType);
-    const statOther = getValueFromHistory(otherStats, statType);
-
-    if (statToday === undefined || statOther === undefined) {
-      return undefined;
-    }
-
-    // Return the difference, accounting for negative changes in ranks
-    return (statToday - statOther) * (statType === "pp" ? 1 : -1);
-  };
-
-  const getStatisticChanges = (daysAgo: number): PlayerHistory => {
-    return {
-      rank: getStatisticChange("rank", daysAgo),
-      countryRank: getStatisticChange("countryRank", daysAgo),
-      pp: getStatisticChange("pp", daysAgo),
-      scores: {
-        totalScores: getStatisticChange("scores.totalScores", daysAgo),
-        totalRankedScores: getStatisticChange("scores.totalRankedScores", daysAgo),
-      },
-    };
-  };
-
-  return {
-    id: token.id,
-    name: token.name,
-    avatar: token.profilePicture,
-    country: token.country,
-    rank: token.rank,
-    countryRank: token.countryRank,
-    joinedDate: new Date(token.firstSeen),
-    bio: bio,
-    pp: token.pp,
-    statisticChange: {
-      daily: getStatisticChanges(1),
-      weekly: getStatisticChanges(7),
-      monthly: getStatisticChanges(30),
-      yearly: getStatisticChanges(365),
-    },
-    role: role,
-    badges: badges,
-    statisticHistory: statisticHistory,
-    statistics: token.scoreStats,
-    rankPages: {
-      global: getPageFromRank(token.rank, 50),
-      country: getPageFromRank(token.countryRank, 50),
-    },
-    permissions: token.permissions,
-    banned: token.banned,
-    inactive: token.inactive,
-    isBeingTracked: isBeingTracked,
-  };
-}
-
 /**
  * A bio of a player.
  */
@@ -299,11 +82,6 @@ export type ScoreSaberBio = {
   linesStripped: string[];
 };
 
-/**
- * The ScoreSaber account roles.
- */
-export type ScoreSaberRole = "Admin";
-
 /**
  * A badge for a player.
  */

projects/common/src/player/player-history.ts

@@ -15,7 +15,27 @@ export interface PlayerHistory {
   pp?: number;
 
   /**
-   * The amount of scores set for this day.
+   * How many times replays of the player scores have been watched
+   */
+  replaysWatched?: number;
+
+  /**
+   * The player's score stats.
+   */
+  score?: {
+    /**
+     * The total amount of unranked and ranked score.
+     */
+    totalScore?: number;
+
+    /**
+     * The total amount of ranked score.
+     */
+    totalRankedScore?: number;
+  };
+
+  /**
+   * The player's scores stats.
    */
   scores?: {
     /**
@@ -40,7 +60,7 @@ export interface PlayerHistory {
   };
 
   /**
-   * The player's accuracy.
+   * The player's accuracy stats.
    */
   accuracy?: {
     /**

projects/common/src/player/player-stat-change.ts

@@ -0,0 +1,64 @@
+import ScoreSaberPlayer from "./impl/scoresaber-player";
+import { ChangeRange } from "./player";
+
+export type PlayerStatValue = {
+  /**
+   * The type of the stat.
+   */
+  type: string;
+
+  /**
+   * The value of the stat.
+   */
+  value: (player: ScoreSaberPlayer, range: ChangeRange) => number | undefined;
+};
+
+export type PlayerStatChangeType =
+  | "Rank"
+  | "CountryRank"
+  | "PerformancePoints"
+  | "TotalPlayCount"
+  | "RankedPlayCount"
+  | "TotalScore"
+  | "TotalRankedScore"
+  | "AverageRankedAccuracy"
+  | "TotalReplaysWatched";
+
+export const PlayerStatChange: Record<PlayerStatChangeType, PlayerStatValue> = {
+  Rank: {
+    type: "Rank",
+    value: (player, range) => player.statisticChange?.[range].rank,
+  },
+  CountryRank: {
+    type: "Country Rank",
+    value: (player, range) => player.statisticChange?.[range].countryRank,
+  },
+  PerformancePoints: {
+    type: "Performance Points",
+    value: (player, range) => player.statisticChange?.[range].pp,
+  },
+  TotalPlayCount: {
+    type: "Total Play Count",
+    value: (player, range) => player.statisticChange?.[range].scores?.totalScores,
+  },
+  RankedPlayCount: {
+    type: "Ranked Play Count",
+    value: (player, range) => player.statisticChange?.[range].scores?.totalRankedScores,
+  },
+  TotalScore: {
+    type: "Total Score",
+    value: (player, range) => player.statisticChange?.[range].score?.totalScore,
+  },
+  TotalRankedScore: {
+    type: "Total Ranked Score",
+    value: (player, range) => player.statisticChange?.[range].score?.totalRankedScore,
+  },
+  AverageRankedAccuracy: {
+    type: "Average Ranked Accuracy",
+    value: (player, range) => player.statisticChange?.[range].accuracy?.averageRankedAccuracy,
+  },
+  TotalReplaysWatched: {
+    type: "Total Replays Watched",
+    value: (player, range) => player.statisticChange?.[range].replaysWatched,
+  },
+};

projects/common/src/player/player-stat.ts

@@ -1,32 +0,0 @@
-export type PlayerStatValue = {
-  /**
-   * The display name of the stat.
-   */
-  displayName: string;
-
-  /**
-   * The value of the stat.
-   */
-  value?: "rank" | "countryRank" | "pp";
-};
-
-export const PlayerStat: Record<string, PlayerStatValue> = {
-  Rank: {
-    displayName: "Rank",
-    value: "rank",
-  },
-  CountryRank: {
-    displayName: "Country Rank",
-    value: "countryRank",
-  },
-  PerformancePoints: {
-    displayName: "Performance Points",
-    value: "pp",
-  },
-  TotalPlayCount: {
-    displayName: "Total Play Count",
-  },
-  RankedPlayCount: {
-    displayName: "Ranked Play Count",
-  },
-};

projects/common/src/player/player.ts

@@ -55,9 +55,7 @@ export default class Player {
   }
 }
 
+export type ChangeRange = "daily" | "weekly" | "monthly";
 export type StatisticChange = {
-  daily: PlayerHistory;
-  weekly: PlayerHistory;
-  monthly: PlayerHistory;
-  yearly: PlayerHistory;
+  [key in ChangeRange]: PlayerHistory;
 };

projects/common/src/player/stat-timeframe.ts

@@ -1 +0,0 @@
-export type StatTimeframe = "daily" | "weekly" | "monthly";

projects/common/src/response/leaderboard-response.ts

@@ -1,4 +1,4 @@
-import { BeatSaverMap } from "../model/beatsaver/beatsaver-map";
+import { BeatSaverMap } from "../model/beatsaver/map";
 
 export type LeaderboardResponse<L> = {
   /**

projects/common/src/response/leaderboard-scores-response.ts

@@ -1,5 +1,5 @@
 import { Metadata } from "../types/metadata";
-import { BeatSaverMap } from "../model/beatsaver/beatsaver-map";
+import { BeatSaverMap } from "../model/beatsaver/map";
 
 export default interface LeaderboardScoresResponse<S, L> {
   /**

projects/common/src/response/top-scores-response.ts

@@ -0,0 +1,10 @@
+import { ScoreSaberLeaderboard } from "src/model/leaderboard/impl/scoresaber-leaderboard";
+import { ScoreSaberScore } from "../model/score/impl/scoresaber-score";
+import { PlayerScore } from "../score/player-score";
+
+export type TopScoresResponse = {
+  /**
+   * The top scores.
+   */
+  scores: PlayerScore<ScoreSaberScore, ScoreSaberLeaderboard>[];
+};

projects/common/src/score/difficulty.ts

@@ -1 +0,0 @@
-export type Difficulty = "Easy" | "Normal" | "Hard" | "Expert" | "Expert+" | "Unknown";

projects/common/src/score/impl/scoresaber-score.ts

@@ -1,76 +0,0 @@
-import Score from "../score";
-import { Modifier } from "../modifier";
-import ScoreSaberScoreToken from "../../types/token/scoresaber/score-saber-score-token";
-import ScoreSaberLeaderboardPlayerInfoToken from "../../types/token/scoresaber/score-saber-leaderboard-player-info-token";
-import ScoreSaberLeaderboardToken from "../../types/token/scoresaber/score-saber-leaderboard-token";
-import ScoreSaberLeaderboard from "../../leaderboard/impl/scoresaber-leaderboard";
-
-export default interface ScoreSaberScore extends Score {
-  /**
-   * The score's id.
-   */
-  readonly id: string;
-
-  /**
-   * The amount of pp for the score.
-   * @private
-   */
-  readonly pp: number;
-
-  /**
-   * The weight of the score, or undefined if not ranked.s
-   * @private
-   */
-  readonly weight?: number;
-
-  /**
-   * The max combo of the score.
-   */
-  readonly maxCombo: number;
-
-  /**
-   * The player who set the score
-   */
-  readonly playerInfo: ScoreSaberLeaderboardPlayerInfoToken;
-}
-
-/**
- * Gets a {@link ScoreSaberScore} from a {@link ScoreSaberScoreToken}.
- *
- * @param token the token to convert
- * @param leaderboard the leaderboard the score was set on
- */
-export function getScoreSaberScoreFromToken(
-  token: ScoreSaberScoreToken,
-  leaderboard?: ScoreSaberLeaderboardToken | ScoreSaberLeaderboard
-): ScoreSaberScore {
-  const modifiers: Modifier[] =
-    token.modifiers == undefined || token.modifiers === ""
-      ? []
-      : token.modifiers.split(",").map(mod => {
-          mod = mod.toUpperCase();
-          const modifier = Modifier[mod as keyof typeof Modifier];
-          if (modifier === undefined) {
-            throw new Error(`Unknown modifier: ${mod}`);
-          }
-          return modifier;
-        });
-
-  return {
-    leaderboard: "scoresaber",
-    score: token.baseScore,
-    accuracy: leaderboard ? (token.baseScore / leaderboard.maxScore) * 100 : Infinity,
-    rank: token.rank,
-    modifiers: modifiers,
-    misses: token.missedNotes + token.badCuts,
-    missedNotes: token.missedNotes,
-    badCuts: token.badCuts,
-    fullCombo: token.fullCombo,
-    timestamp: new Date(token.timeSet),
-    id: token.id,
-    pp: token.pp,
-    weight: token.weight,
-    maxCombo: token.maxCombo,
-    playerInfo: token.leaderboardPlayerInfo,
-  };
-}

projects/common/src/score/map-difficulty.ts

@@ -0,0 +1 @@
+export type MapDifficulty = "Easy" | "Normal" | "Hard" | "Expert" | "ExpertPlus" | "Unknown";

projects/common/src/score/player-score.ts

@@ -1,4 +1,4 @@
-import { BeatSaverMap } from "../model/beatsaver/beatsaver-map";
+import { BeatSaverMap } from "../model/beatsaver/map";
 
 export interface PlayerScore<S, L> {
   /**

projects/common/src/score/score.ts

@@ -1,61 +0,0 @@
-import { Modifier } from "./modifier";
-import { Leaderboards } from "../leaderboard";
-
-export default interface Score {
-  /**
-   * The leaderboard the score is from.
-   */
-  readonly leaderboard: Leaderboards;
-
-  /**
-   * The base score for the score.
-   * @private
-   */
-  readonly score: number;
-
-  /**
-   * The accuracy of the score.
-   */
-  readonly accuracy: number;
-
-  /**
-   * The rank for the score.
-   * @private
-   */
-  readonly rank: number;
-
-  /**
-   * The modifiers used on the score.
-   * @private
-   */
-  readonly modifiers: Modifier[];
-
-  /**
-   * The amount total amount of misses.
-   * @private
-   */
-  readonly misses: number;
-
-  /**
-   * The amount of missed notes.
-   */
-  readonly missedNotes: number;
-
-  /**
-   * The amount of bad cuts.
-   * @private
-   */
-  readonly badCuts: number;
-
-  /**
-   * Whether every note was hit.
-   * @private
-   */
-  readonly fullCombo: boolean;
-
-  /**
-   * The time the score was set.
-   * @private
-   */
-  readonly timestamp: Date;
-}

projects/common/src/service/impl/beatleader.ts

@@ -0,0 +1,34 @@
+import Service from "../service";
+import { ScoreStatsToken } from "../../types/token/beatleader/score-stats/score-stats";
+
+const LOOKUP_MAP_STATS_BY_SCORE_ID_ENDPOINT = `https://cdn.scorestats.beatleader.xyz/:scoreId.json`;
+
+class BeatLeaderService extends Service {
+  constructor() {
+    super("BeatLeader");
+  }
+
+  /**
+   * Looks up the score stats for a score
+   *
+   * @param scoreId the score id to get
+   * @returns the score stats, or undefined if nothing was found
+   */
+  async lookupScoreStats(scoreId: number): Promise<ScoreStatsToken | undefined> {
+    const before = performance.now();
+    this.log(`Looking score stats for "${scoreId}"...`);
+
+    const response = await this.fetch<ScoreStatsToken>(
+      LOOKUP_MAP_STATS_BY_SCORE_ID_ENDPOINT.replace(":scoreId", scoreId + "")
+    );
+    // Score stats not found
+    if (response == undefined) {
+      return undefined;
+    }
+
+    this.log(`Found score stats for score "${scoreId}" in ${(performance.now() - before).toFixed(0)}ms`);
+    return response;
+  }
+}
+
+export const beatLeaderService = new BeatLeaderService();

projects/common/src/service/impl/beatsaver.ts

@@ -1,5 +1,5 @@
 import Service from "../service";
-import { BeatSaverMapToken } from "../../types/token/beatsaver/beat-saver-map-token";
+import { BeatSaverMapToken } from "../../types/token/beatsaver/map";
 
 const API_BASE = "https://api.beatsaver.com";
 const LOOKUP_MAP_BY_HASH_ENDPOINT = `${API_BASE}/maps/hash/:query`;

projects/common/src/service/impl/scoresaber.ts

@@ -7,7 +7,7 @@ import ScoreSaberPlayerScoresPageToken from "../../types/token/scoresaber/score-
 import ScoreSaberLeaderboardToken from "../../types/token/scoresaber/score-saber-leaderboard-token";
 import ScoreSaberLeaderboardScoresPageToken from "../../types/token/scoresaber/score-saber-leaderboard-scores-page-token";
 import { clamp, lerp } from "../../utils/math-utils";
-import { CurvePoint } from "../../utils/curve-point";
+import { CurvePoint } from "../../curve-point";
 import { SSRCache } from "../../cache";
 
 const API_BASE = "https://scoresaber.com/api";
@@ -30,7 +30,7 @@ const LOOKUP_LEADERBOARD_SCORES_ENDPOINT = `${API_BASE}/leaderboard/by-id/:id/sc
 const STAR_MULTIPLIER = 42.117208413;
 
 const playerCache = new SSRCache({
-  ttl: 60 * 30, // 30 minutes
+  ttl: 60, // 1 minute
 });
 
 class ScoreSaberService extends Service {
@@ -167,18 +167,21 @@ class ScoreSaberService extends Service {
    *
    * @param playerId the ID of the player to look up
    * @param sort the sort to use
+   * @param limit the amount of sores to fetch
    * @param page the page to get scores for
-   * @param search
+   * @param search the query to search for
    * @returns the scores of the player, or undefined
    */
   public async lookupPlayerScores({
     playerId,
     sort,
+    limit = 8,
     page,
     search,
   }: {
     playerId: string;
     sort: ScoreSort;
+    limit?: number;
     page: number;
     search?: string;
     useProxy?: boolean;
@@ -189,7 +192,7 @@ class ScoreSaberService extends Service {
     );
     const response = await this.fetch<ScoreSaberPlayerScoresPageToken>(
       LOOKUP_PLAYER_SCORES_ENDPOINT.replace(":id", playerId)
-        .replace(":limit", 8 + "")
+        .replace(":limit", limit + "")
         .replace(":sort", sort)
         .replace(":page", page + "") + (search ? `&search=${search}` : "")
     );

projects/common/src/token-creators.ts

@@ -0,0 +1,331 @@
+import ScoreSaberLeaderboard from "./model/leaderboard/impl/scoresaber-leaderboard";
+import ScoreSaberLeaderboardToken from "./types/token/scoresaber/score-saber-leaderboard-token";
+import LeaderboardDifficulty from "./model/leaderboard/leaderboard-difficulty";
+import { getDifficultyFromScoreSaberDifficulty } from "./utils/scoresaber-utils";
+import { MapCharacteristic } from "./types/map-characteristic";
+import { LeaderboardStatus } from "./model/leaderboard/leaderboard-status";
+import { formatDateMinimal, getDaysAgoDate, getMidnightAlignedDate, parseDate } from "./utils/time-utils";
+import ScoreSaberPlayerToken from "./types/token/scoresaber/score-saber-player-token";
+import ScoreSaberPlayer, { ScoreSaberBadge, ScoreSaberBio } from "./player/impl/scoresaber-player";
+import { PlayerHistory } from "./player/player-history";
+import ky from "ky";
+import { Config } from "./config";
+import { getValueFromHistory } from "./utils/player-utils";
+import { getPageFromRank } from "./utils/utils";
+import ScoreSaberScoreToken from "./types/token/scoresaber/score-saber-score-token";
+import { ScoreSaberScore } from "./model/score/impl/scoresaber-score";
+import { Modifier } from "./score/modifier";
+
+/**
+ * Parses a {@link ScoreSaberLeaderboardToken} into a {@link ScoreSaberLeaderboard}.
+ *
+ * @param token the token to parse
+ */
+export function getScoreSaberLeaderboardFromToken(token: ScoreSaberLeaderboardToken): ScoreSaberLeaderboard {
+  const difficulty: LeaderboardDifficulty = {
+    leaderboardId: token.difficulty.leaderboardId,
+    difficulty: getDifficultyFromScoreSaberDifficulty(token.difficulty.difficulty),
+    characteristic: token.difficulty.gameMode.replace("Solo", "") as MapCharacteristic,
+    difficultyRaw: token.difficulty.difficultyRaw,
+  };
+
+  let status: LeaderboardStatus = "Unranked";
+  if (token.qualified) {
+    status = "Qualified";
+  } else if (token.ranked) {
+    status = "Ranked";
+  }
+
+  return {
+    id: token.id,
+    songHash: token.songHash.toUpperCase(),
+    songName: token.songName,
+    songSubName: token.songSubName,
+    songAuthorName: token.songAuthorName,
+    levelAuthorName: token.levelAuthorName,
+    difficulty: difficulty,
+    difficulties:
+      token.difficulties != undefined && token.difficulties.length > 0
+        ? token.difficulties.map(difficulty => {
+            return {
+              leaderboardId: difficulty.leaderboardId,
+              difficulty: getDifficultyFromScoreSaberDifficulty(difficulty.difficulty),
+              characteristic: difficulty.gameMode.replace("Solo", "") as MapCharacteristic,
+              difficultyRaw: difficulty.difficultyRaw,
+            };
+          })
+        : [difficulty],
+    maxScore: token.maxScore,
+    ranked: token.ranked,
+    songArt: token.coverImage,
+    timestamp: parseDate(token.createdDate),
+    stars: token.stars,
+    plays: token.plays,
+    dailyPlays: token.dailyPlays,
+    qualified: token.qualified,
+    status: status,
+  };
+}
+
+/**
+ * Gets a {@link ScoreSaberScore} from a {@link ScoreSaberScoreToken}.
+ *
+ * @param token the token to convert
+ * @param playerId the id of the player who set the score
+ * @param leaderboard the leaderboard the score was set on
+ */
+export function getScoreSaberScoreFromToken(
+  token: ScoreSaberScoreToken,
+  leaderboard: ScoreSaberLeaderboard,
+  playerId?: string
+): ScoreSaberScore {
+  const modifiers: Modifier[] =
+    token.modifiers == undefined || token.modifiers === ""
+      ? []
+      : token.modifiers.split(",").map(mod => {
+          mod = mod.toUpperCase();
+          const modifier = Modifier[mod as keyof typeof Modifier];
+          if (modifier === undefined) {
+            throw new Error(`Unknown modifier: ${mod}`);
+          }
+          return modifier;
+        });
+
+  return {
+    playerId: playerId || token.leaderboardPlayerInfo.id,
+    leaderboardId: leaderboard.id,
+    difficulty: leaderboard.difficulty.difficulty,
+    characteristic: leaderboard.difficulty.characteristic,
+    score: token.baseScore,
+    accuracy: leaderboard.maxScore ? (token.baseScore / leaderboard.maxScore) * 100 : Infinity,
+    rank: token.rank,
+    modifiers: modifiers,
+    misses: token.missedNotes + token.badCuts,
+    missedNotes: token.missedNotes,
+    badCuts: token.badCuts,
+    fullCombo: token.fullCombo,
+    timestamp: new Date(token.timeSet),
+    scoreId: token.id,
+    pp: token.pp,
+    weight: token.weight,
+    maxCombo: token.maxCombo,
+    playerInfo: token.leaderboardPlayerInfo,
+  };
+}
+
+/**
+ * Gets the ScoreSaber Player from an {@link ScoreSaberPlayerToken}.
+ *
+ * @param token the player token
+ * @param playerIdCookie the id of the claimed player
+ */
+export async function getScoreSaberPlayerFromToken(
+  token: ScoreSaberPlayerToken,
+  playerIdCookie?: string
+): Promise<ScoreSaberPlayer> {
+  const bio: ScoreSaberBio = {
+    lines: token.bio?.split("\n") || [],
+    linesStripped: token.bio?.replace(/<[^>]+>/g, "")?.split("\n") || [], // strips html tags
+  };
+  const badges: ScoreSaberBadge[] =
+    token.badges?.map(badge => {
+      return {
+        url: badge.image,
+        description: badge.description,
+      };
+    }) || [];
+
+  let isBeingTracked = false;
+  const todayDate = formatDateMinimal(getMidnightAlignedDate(new Date()));
+  let statisticHistory: { [key: string]: PlayerHistory } = {};
+
+  try {
+    const { statistics: history } = await ky
+      .get<{
+        statistics: { [key: string]: PlayerHistory };
+      }>(
+        `${Config.apiUrl}/player/history/${token.id}/50/${playerIdCookie && playerIdCookie == token.id ? "?createIfMissing=true" : ""}`
+      )
+      .json();
+    if (history) {
+      // Use the latest data for today
+      history[todayDate] = {
+        ...history[todayDate],
+        rank: token.rank,
+        countryRank: token.countryRank,
+        pp: token.pp,
+        replaysWatched: token.scoreStats.replaysWatched,
+        accuracy: {
+          ...history[todayDate]?.accuracy,
+          averageRankedAccuracy: token.scoreStats.averageRankedAccuracy,
+        },
+        scores: {
+          ...history[todayDate]?.scores,
+          totalScores: token.scoreStats.totalPlayCount,
+          totalRankedScores: token.scoreStats.rankedPlayCount,
+        },
+        score: {
+          ...history[todayDate]?.score,
+          totalScore: token.scoreStats.totalScore,
+          totalRankedScore: token.scoreStats.totalRankedScore,
+        },
+      };
+
+      isBeingTracked = true;
+    }
+    statisticHistory = history;
+  } catch (e) {}
+
+  const playerRankHistory = token.histories.split(",").map(value => {
+    return parseInt(value);
+  });
+  playerRankHistory.push(token.rank);
+
+  let missingDays = 0;
+  let daysAgo = 0; // Start from current day
+  for (let i = playerRankHistory.length - 1; i >= 0; i--) {
+    const rank = playerRankHistory[i];
+    if (rank == 999_999) {
+      continue;
+    }
+
+    const date = getMidnightAlignedDate(getDaysAgoDate(daysAgo));
+    daysAgo += 1;
+
+    const dateKey = formatDateMinimal(date);
+    if (!statisticHistory[dateKey] || statisticHistory[dateKey].rank == undefined) {
+      missingDays += 1;
+      statisticHistory[dateKey] = {
+        ...statisticHistory[dateKey],
+        rank: rank,
+      };
+    }
+  }
+
+  if (missingDays > 0 && missingDays != playerRankHistory.length) {
+    console.log(
+      `Player has ${missingDays} missing day${missingDays > 1 ? "s" : ""}, filling in with fallback history...`
+    );
+  }
+
+  // Sort the fallback history
+  statisticHistory = Object.entries(statisticHistory)
+    .sort((a, b) => Date.parse(b[0]) - Date.parse(a[0]))
+    .reduce((obj, [key, value]) => ({ ...obj, [key]: value }), {});
+
+  /**
+   * Gets the change in the given stat
+   *
+   * @param statType the stat to check
+   * @param isNegativeChange whether to multiply the change by 1 or -1
+   * @param daysAgo the amount of days ago to get the stat for
+   * @return the change
+   */
+  const getStatisticChange = (statType: string, isNegativeChange: boolean, daysAgo: number = 1): number | undefined => {
+    const todayStats = statisticHistory[todayDate];
+    let otherDate: Date | undefined;
+
+    if (daysAgo === 1) {
+      otherDate = getMidnightAlignedDate(getDaysAgoDate(1)); // Yesterday
+    } else {
+      const targetDate = getDaysAgoDate(daysAgo);
+
+      // Filter available dates to find the closest one to the target
+      const availableDates = Object.keys(statisticHistory)
+        .map(dateKey => new Date(dateKey))
+        .filter(date => {
+          // Convert date back to the correct format for statisticHistory lookup
+          const formattedDate = formatDateMinimal(date);
+          const statsForDate = statisticHistory[formattedDate];
+          const hasStat = statsForDate && statType in statsForDate;
+
+          // Only consider past dates with the required statType
+          const isPast = date.getTime() < new Date().getTime();
+          return hasStat && isPast;
+        });
+
+      // If no valid dates are found, return undefined
+      if (availableDates.length === 0) {
+        return undefined;
+      }
+
+      // Find the closest date from the filtered available dates
+      otherDate = availableDates.reduce((closestDate, currentDate) => {
+        const currentDiff = Math.abs(currentDate.getTime() - targetDate.getTime());
+        const closestDiff = Math.abs(closestDate.getTime() - targetDate.getTime());
+        return currentDiff < closestDiff ? currentDate : closestDate;
+      }, availableDates[0]); // Start with the first available date
+    }
+
+    // Ensure todayStats exists and contains the statType
+    if (!todayStats || !getValueFromHistory(todayStats, statType)) {
+      return undefined;
+    }
+
+    const otherStats = statisticHistory[formatDateMinimal(otherDate)]; // This is now validated
+
+    // Ensure otherStats exists and contains the statType
+    if (!otherStats || !getValueFromHistory(otherStats, statType)) {
+      return undefined;
+    }
+
+    const statToday = getValueFromHistory(todayStats, statType);
+    const statOther = getValueFromHistory(otherStats, statType);
+
+    if (statToday === undefined || statOther === undefined) {
+      return undefined;
+    }
+    return (statToday - statOther) * (!isNegativeChange ? 1 : -1);
+  };
+
+  const getStatisticChanges = (daysAgo: number): PlayerHistory => {
+    return {
+      rank: getStatisticChange("rank", true, daysAgo),
+      countryRank: getStatisticChange("countryRank", true, daysAgo),
+      pp: getStatisticChange("pp", false, daysAgo),
+      replaysWatched: getStatisticChange("replaysWatched", false, daysAgo),
+      accuracy: {
+        averageRankedAccuracy: getStatisticChange("accuracy.averageRankedAccuracy", false, daysAgo),
+      },
+      score: {
+        totalScore: getStatisticChange("score.totalScore", false, daysAgo),
+        totalRankedScore: getStatisticChange("score.totalRankedScore", false, daysAgo),
+      },
+      scores: {
+        totalScores: getStatisticChange("scores.totalScores", false, daysAgo),
+        totalRankedScores: getStatisticChange("scores.totalRankedScores", false, daysAgo),
+        rankedScores: getStatisticChange("scores.rankedScores", false, daysAgo),
+        unrankedScores: getStatisticChange("scores.unrankedScores", false, daysAgo),
+      },
+    };
+  };
+
+  return {
+    id: token.id,
+    name: token.name,
+    avatar: token.profilePicture,
+    country: token.country,
+    rank: token.rank,
+    countryRank: token.countryRank,
+    joinedDate: new Date(token.firstSeen),
+    bio: bio,
+    pp: token.pp,
+    statisticChange: {
+      daily: getStatisticChanges(1),
+      weekly: getStatisticChanges(7),
+      monthly: getStatisticChanges(30),
+    },
+    role: token.role == null ? undefined : token.role,
+    badges: badges,
+    statisticHistory: statisticHistory,
+    statistics: token.scoreStats,
+    rankPages: {
+      global: getPageFromRank(token.rank, 50),
+      country: getPageFromRank(token.countryRank, 50),
+    },
+    permissions: token.permissions,
+    banned: token.banned,
+    inactive: token.inactive,
+    isBeingTracked: isBeingTracked,
+  };
+}

projects/common/src/types/backend/app-statistics.ts

@@ -3,4 +3,24 @@ export type AppStatistics = {
    * The total amount of players being tracked.
    */
   trackedPlayers: number;
+
+  /**
+   * The total amount of ScoreSaber scores tracked.
+   */
+  trackedScores: number;
+
+  /**
+   * The total amount of additional data for scores being tracked.
+   */
+  additionalScoresData: number;
+
+  /**
+   * The amount of cached BeatSaver maps.
+   */
+  cachedBeatSaverMaps: number;
+
+  /**
+   * The amount of cached ScoreSaber leaderboards.
+   */
+  cachedScoreSaberLeaderboards: number;
 };

projects/common/src/types/map-characteristic.ts

@@ -0,0 +1 @@
+export type MapCharacteristic = "Standard" | "Lawless";

projects/common/src/types/page.ts

@@ -1,13 +0,0 @@
-import { Metadata } from "./metadata";
-
-export type Page<T> = {
-  /**
-   * The data to return.
-   */
-  data: T[];
-
-  /**
-   * The metadata of the page.
-   */
-  metadata: Metadata;
-};

projects/common/src/types/token/beatleader/difficulty.ts

@@ -0,0 +1,30 @@
+import { BeatLeaderModifierToken } from "./modifier/modifiers";
+import { BeatLeaderModifierRatingToken } from "./modifier/modifier-rating";
+
+export type BeatLeaderDifficultyToken = {
+  id: number;
+  value: number;
+  mode: number;
+  difficultyName: string;
+  modeName: string;
+  status: number;
+  modifierValues: BeatLeaderModifierToken;
+  modifiersRating: BeatLeaderModifierRatingToken;
+  nominatedTime: number;
+  qualifiedTime: number;
+  rankedTime: number;
+  stars: number;
+  predictedAcc: number;
+  passRating: number;
+  accRating: number;
+  techRating: number;
+  type: number;
+  njs: number;
+  nps: number;
+  notes: number;
+  bombs: number;
+  walls: number;
+  maxScore: number;
+  duration: number;
+  requirements: number;
+};

projects/common/src/types/token/beatleader/leaderboard.ts

@@ -0,0 +1,16 @@
+import { BeatLeaderSongToken } from "./score/song";
+import { BeatLeaderDifficultyToken } from "./difficulty";
+
+export type BeatLeaderLeaderboardToken = {
+  id: string;
+  song: BeatLeaderSongToken;
+  difficulty: BeatLeaderDifficultyToken;
+  scores: null; // ??
+  changes: null; // ??
+  qualification: null; // ??
+  reweight: null; // ??
+  leaderboardGroup: null; // ??
+  plays: number;
+  clan: null; // ??
+  clanRankingContested: boolean;
+};

projects/common/src/types/token/beatleader/modifier/modifier-rating.ts

@@ -0,0 +1,18 @@
+export type BeatLeaderModifierRatingToken = {
+  id: number;
+  fsPredictedAcc: number;
+  fsPassRating: number;
+  fsAccRating: number;
+  fsTechRating: number;
+  fsStars: number;
+  ssPredictedAcc: number;
+  ssPassRating: number;
+  ssAccRating: number;
+  ssTechRating: number;
+  ssStars: number;
+  sfPredictedAcc: number;
+  sfPassRating: number;
+  sfAccRating: number;
+  sfTechRating: number;
+  sfStars: number;
+};

projects/common/src/types/token/beatleader/modifier/modifiers.ts

@@ -0,0 +1,16 @@
+export type BeatLeaderModifierToken = {
+  modifierId: number;
+  da: number;
+  fs: number;
+  sf: number;
+  ss: number;
+  gn: number;
+  na: number;
+  nb: number;
+  nf: number;
+  no: number;
+  pm: number;
+  sc: number;
+  sa: number;
+  op: number;
+};

projects/common/src/types/token/beatleader/player.ts

@@ -0,0 +1,10 @@
+export type BeatLeaderPlayerToken = {
+  id: string;
+  country: string;
+  avatar: string;
+  pp: number;
+  rank: number;
+  countryRank: number;
+  name: string;
+  // todo: finish this
+};

projects/common/src/types/token/beatleader/score-stats/accuracy-tracker.ts

@@ -0,0 +1,66 @@
+export type ScoreStatsAccuracyTrackerToken = {
+  /**
+   * The accuracy of the right hand.
+   */
+  accRight: number;
+
+  /**
+   * The accuracy of the left hand.
+   */
+  accLeft: number;
+
+  /**
+   * The left hand pre-swing.
+   */
+  leftPreswing: number;
+
+  /**
+   * The right hand pre-swing.
+   */
+  rightPreswing: number;
+
+  /**
+   * The average pre-swing.
+   */
+  averagePreswing: number;
+
+  /**
+   * The left hand post-swing.
+   */
+  leftPostswing: number;
+
+  /**
+   * The right hand post-swing.
+   */
+  rightPostswing: number;
+
+  /**
+   * The left hand time dependence.
+   */
+  leftTimeDependence: number;
+
+  /**
+   * The right hand time dependence.
+   */
+  rightTimeDependence: number;
+
+  /**
+   * The left hand average cut.
+   */
+  leftAverageCut: number[];
+
+  /**
+   * The right hand average cut.
+   */
+  rightAverageCut: number[];
+
+  /**
+   * The grid accuracy.
+   */
+  gridAcc: number[];
+
+  /**
+   * The full combo accuracy.
+   */
+  fcAcc: number;
+};

projects/common/src/types/token/beatleader/score-stats/head-position.ts

@@ -0,0 +1,16 @@
+export type ScoreStatsHeadPositionToken = {
+  /**
+   * The X position of the head
+   */
+  x: number;
+
+  /**
+   * The Y position of the head
+   */
+  y: number;
+
+  /**
+   * The Z position of the head
+   */
+  z: number;
+};

projects/common/src/types/token/beatleader/score-stats/hit-tracker.ts

@@ -0,0 +1,51 @@
+export type ScoreStatsHitTrackerToken = {
+  /**
+   * The maximum combo achieved.
+   */
+  maxCombo: number;
+
+  /**
+   * The highest amount of 115 notes hit in a row.
+   */
+  maxStreak: number;
+
+  /**
+   * The left hand timing.
+   */
+  leftTiming: number;
+
+  /**
+   * The right hand timing.
+   */
+  rightTiming: number;
+
+  /**
+   * The left hand misses.
+   */
+  leftMiss: number;
+
+  /**
+   * The right hand misses.
+   */
+  rightMiss: number;
+
+  /**
+   * The left hand bad cuts.
+   */
+  leftBadCuts: number;
+
+  /**
+   * The right hand bad cuts.
+   */
+  rightBadCuts: number;
+
+  /**
+   * The left hand bombs.
+   */
+  leftBombs: number;
+
+  /**
+   * The right hand bombs.
+   */
+  rightBombs: number;
+};

projects/common/src/types/token/beatleader/score-stats/score-graph-tracker.ts

@@ -0,0 +1,6 @@
+export type ScoreStatsGraphTrackerToken = {
+  /**
+   * The accuracy graph data.
+   */
+  graph: number[];
+};

projects/common/src/types/token/beatleader/score-stats/score-stats.ts

@@ -0,0 +1,26 @@
+import { ScoreStatsHitTrackerToken } from "./hit-tracker";
+import { ScoreStatsAccuracyTrackerToken } from "./accuracy-tracker";
+import { ScoreStatsWinTrackerToken } from "./win-tracker";
+import { ScoreStatsGraphTrackerToken } from "./score-graph-tracker";
+
+export type ScoreStatsToken = {
+  /**
+   * The hit tracker stats.
+   */
+  hitTracker: ScoreStatsHitTrackerToken;
+
+  /**
+   * The accuracy tracker stats.
+   */
+  accuracyTracker: ScoreStatsAccuracyTrackerToken;
+
+  /**
+   * The win tracker stats.
+   */
+  winTracker: ScoreStatsWinTrackerToken;
+
+  /**
+   * The score graph tracker stats.
+   */
+  scoreGraphTracker: ScoreStatsGraphTrackerToken;
+};

projects/common/src/types/token/beatleader/score-stats/win-tracker.ts

@@ -0,0 +1,48 @@
+import { ScoreStatsHeadPositionToken } from "./head-position";
+
+export type ScoreStatsWinTrackerToken = {
+  /**
+   * Whether the score was won. (not failed)
+   */
+  won: boolean;
+
+  /**
+   * The time the score ended.
+   */
+  endTime: number;
+
+  /**
+   * The total amount of pauses.
+   */
+  nbOfPause: number;
+
+  /**
+   * The total amount of pause time.
+   */
+  totalPauseDuration: number;
+
+  /**
+   * The jump distance the score was played on.
+   */
+  jumpDistance: number;
+
+  /**
+   * The average height of the player.
+   */
+  averageHeight: number;
+
+  /**
+   * The average head position of the player.
+   */
+  averageHeadPosition: ScoreStatsHeadPositionToken;
+
+  /**
+   * The total score.
+   */
+  totalScore: number;
+
+  /**
+   * The maximum score for this song.
+   */
+  maxScore: number;
+};

projects/common/src/types/token/beatleader/score/score-improvement.ts

@@ -0,0 +1,19 @@
+export type BeatLeaderScoreImprovementToken = {
+  id: number;
+  timeset: number;
+  score: number;
+  accuracy: number;
+  pp: number;
+  bonusPp: number;
+  rank: number;
+  accRight: number;
+  accLeft: number;
+  averageRankedAccuracy: number;
+  totalPp: number;
+  totalRank: number;
+  badCuts: number;
+  missedNotes: number;
+  bombCuts: number;
+  wallsHit: number;
+  pauses: number;
+};

projects/common/src/types/token/beatleader/score/score-offsets.ts

@@ -0,0 +1,8 @@
+export type BeatLeaderScoreOffsetsToken = {
+  id: number;
+  frames: number;
+  notes: number;
+  walls: number;
+  heights: number;
+  pauses: number;
+};

projects/common/src/types/token/beatleader/score/score.ts

@@ -0,0 +1,52 @@
+import { BeatLeaderLeaderboardToken } from "../leaderboard";
+import { BeatLeaderScoreImprovementToken } from "./score-improvement";
+import { BeatLeaderScoreOffsetsToken } from "./score-offsets";
+import { BeatLeaderPlayerToken } from "../player";
+
+export type BeatLeaderScoreToken = {
+  myScore: null; // ??
+  validContexts: number;
+  leaderboard: BeatLeaderLeaderboardToken;
+  contextExtensions: null; // ??
+  accLeft: number;
+  accRight: number;
+  id: number;
+  baseScore: number;
+  modifiedScore: number;
+  accuracy: number;
+  playerId: string;
+  pp: number;
+  bonusPp: number;
+  passPP: number;
+  accPP: number;
+  techPP: number;
+  rank: number;
+  country: string;
+  fcAccuracy: number;
+  fcPp: number;
+  weight: number;
+  replay: string;
+  modifiers: string;
+  badCuts: number;
+  missedNotes: number;
+  bombCuts: number;
+  wallsHit: number;
+  pauses: number;
+  fullCombo: boolean;
+  platform: string;
+  maxCombo: number;
+  maxStreak: number;
+  hmd: number;
+  controller: number;
+  leaderboardId: string;
+  timeset: string;
+  timepost: number;
+  replaysWatched: number;
+  playCount: number;
+  priority: number;
+  player: BeatLeaderPlayerToken; // ??
+  scoreImprovement: BeatLeaderScoreImprovementToken;
+  rankVoting: null; // ??
+  metadata: null; // ??
+  offsets: BeatLeaderScoreOffsetsToken;
+};

projects/common/src/types/token/beatleader/score/song.ts

@@ -0,0 +1,16 @@
+export type BeatLeaderSongToken = {
+  id: string;
+  hash: string;
+  name: string;
+  subName: string;
+  author: string;
+  mapperId: string;
+  coverImage: string;
+  fullCoverImage: string;
+  downloadUrl: string;
+  bpm: number;
+  duration: number;
+  tags: string;
+  uploadTime: number;
+  difficulties: null; // ??
+};

projects/common/src/types/token/beatsaver/beat-saver-map-token.ts

@@ -1,24 +0,0 @@
-import BeatSaverAccountToken from "./beat-saver-account-token";
-import BeatSaverMapMetadataToken from "./beat-saver-map-metadata-token";
-import BeatSaverMapStatsToken from "./beat-saver-map-stats-token";
-
-export interface BeatSaverMapToken {
-  id: string;
-  name: string;
-  description: string;
-  uploader: BeatSaverAccountToken;
-  metadata: BeatSaverMapMetadataToken;
-  stats: BeatSaverMapStatsToken;
-  uploaded: string;
-  automapper: boolean;
-  ranked: boolean;
-  qualified: boolean;
-  // todo: versions
-  createdAt: string;
-  updatedAt: string;
-  lastPublishedAt: string;
-  tags: string[];
-  declaredAi: string;
-  blRanked: boolean;
-  blQualified: boolean;
-}

projects/common/src/types/token/beatsaver/difficulty-parity-summary.ts

@@ -0,0 +1,16 @@
+export type MapDifficultyParitySummaryToken = {
+  /**
+   * The amount of parity errors.
+   */
+  errors: number;
+
+  /**
+   * The amount of parity warnings.
+   */
+  warns: number;
+
+  /**
+   * The amount of resets in the difficulty.
+   */
+  resets: number;
+};

projects/common/src/types/token/beatsaver/map-difficulty.ts

@@ -0,0 +1,90 @@
+import { MapDifficulty } from "../../../score/map-difficulty";
+import { MapDifficultyParitySummaryToken } from "./difficulty-parity-summary";
+
+export type BeatSaverMapDifficultyToken = {
+  /**
+   * The NJS of this difficulty.
+   */
+  njs: number;
+
+  /**
+   * The NJS offset of this difficulty.
+   */
+  offset: number;
+
+  /**
+   * The amount of notes in this difficulty.
+   */
+  notes: number;
+
+  /**
+   * The amount of bombs in this difficulty.
+   */
+  bombs: number;
+
+  /**
+   * The amount of obstacles in this difficulty.
+   */
+  obstacles: number;
+
+  /**
+   * The notes per second in this difficulty.
+   */
+  nps: number;
+
+  /**
+   * The length of this difficulty in seconds.
+   */
+  length: number;
+
+  /**
+   * The characteristic of this difficulty.
+   */
+  characteristic: "Standard" | "Lawless";
+
+  /**
+   * The difficulty of this difficulty.
+   */
+  difficulty: MapDifficulty;
+
+  /**
+   * The amount of lighting events in this difficulty.
+   */
+  events: number;
+
+  /**
+   * Whether this difficulty uses Chroma.
+   */
+  chroma: boolean;
+
+  /**
+   * Quite frankly I have no fucking idea what these are.
+   */
+  me: boolean;
+  ne: boolean;
+
+  /**
+   * Does this difficulty use cinema?
+   */
+  cinema: boolean;
+
+  /**
+   * The length of this difficulty in seconds.
+   */
+  seconds: number;
+
+  /**
+   * The parity summary of this difficulty.
+   */
+  paritySummary: MapDifficultyParitySummaryToken;
+
+  /**
+   * The maximum score of this difficulty.
+   */
+  maxScore: number;
+
+  /**
+   * The custom difficulty label.
+   */
+  label: string;
+};

projects/common/src/types/token/beatsaver/map-version.ts

@@ -0,0 +1,43 @@
+import { BeatSaverMapDifficultyToken } from "./map-difficulty";
+
+export type BeatSaverMapVersionToken = {
+  /**
+   * The hash of the map.
+   */
+  hash: string;
+
+  /**
+   * The stage of the map.
+   */
+  stage: "Published"; // todo: find the rest of these
+
+  /**
+   * The date the map was created.
+   */
+  createdAt: string;
+
+  /**
+   * The sage score of the map. (no idea what this is x.x)
+   */
+  sageScore: number;
+
+  /**
+   * The difficulties in the map.
+   */
+  diffs: BeatSaverMapDifficultyToken[];
+
+  /**
+   * The URL to the download of the map.
+   */
+  downloadURL: string;
+
+  /**
+   * The URL to the cover image.
+   */
+  coverURL: string;
+
+  /**
+   * The URL to the preview of the map.
+   */
+  previewURL: string;
+};

projects/common/src/types/token/beatsaver/map.ts

@@ -0,0 +1,96 @@
+import BeatSaverAccountToken from "./account";
+import BeatSaverMapMetadataToken from "./map-metadata";
+import BeatSaverMapStatsToken from "./map-stats";
+import { BeatSaverMapVersionToken } from "./map-version";
+
+export interface BeatSaverMapToken {
+  /**
+   * The id of the map.
+   */
+  id: string;
+
+  /**
+   * The name of the map.
+   */
+  name: string;
+
+  /**
+   * The description of the map.
+   */
+  description: string;
+
+  /**
+   * The uploader of the map.
+   */
+  uploader: BeatSaverAccountToken;
+
+  /**
+   * The metadata of the map.
+   */
+  metadata: BeatSaverMapMetadataToken;
+
+  /**
+   * The stats of the map.
+   */
+  stats: BeatSaverMapStatsToken;
+
+  /**
+   * The date the map was uploaded.
+   */
+  uploaded: string;
+
+  /**
+   * Whether the map was mapped by an automapper.
+   */
+  automapper: boolean;
+
+  /**
+   * Whether the map is ranked on ScoreSaber.
+   */
+  ranked: boolean;
+
+  /**
+   * Whether the map is qualified on ScoreSaber.
+   */
+  qualified: boolean;
+
+  /**
+   * The versions of the map.
+   */
+  versions: BeatSaverMapVersionToken[];
+
+  /**
+   * The date the map was created.
+   */
+  createdAt: string;
+
+  /**
+   * The date the map was last updated.
+   */
+  updatedAt: string;
+
+  /**
+   * The date the map was last published.
+   */
+  lastPublishedAt: string;
+
+  /**
+   * The tags of the map.
+   */
+  tags: string[];
+
+  /**
+   * Whether the map is declared to be mapped by an AI.
+   */
+  declaredAi: string;
+
+  /**
+   * Whether the map is ranked on BeatLeader.
+   */
+  blRanked: boolean;
+
+  /**
+   * Whether the map is qualified on BeatLeader.
+   */
+  blQualified: boolean;
+}

projects/common/src/types/token/scoresaber/score-saber-leaderboard-player-info-token.ts

@@ -1,8 +1,8 @@
-export default interface ScoreSaberLeaderboardPlayerInfoToken {
+export type ScoreSaberLeaderboardPlayerInfoToken = {
   id: string;
-  name: string;
-  profilePicture: string;
-  country: string;
-  permissions: number;
-  role: string;
-}
+  name?: string;
+  profilePicture?: string;
+  country?: string;
+  permissions?: number;
+  role?: string;
+};

projects/common/src/types/token/scoresaber/score-saber-score-token.ts

@@ -1,5 +1,5 @@
 import ScoreSaberLeaderboardToken from "./score-saber-leaderboard-token";
-import ScoreSaberLeaderboardPlayerInfoToken from "./score-saber-leaderboard-player-info-token";
+import { ScoreSaberLeaderboardPlayerInfoToken } from "./score-saber-leaderboard-player-info-token";
 
 export default interface ScoreSaberScoreToken {
   id: string;

projects/common/src/utils/beatsaver.util.ts

@@ -1,7 +1,8 @@
-import { BeatSaverMap } from "../model/beatsaver/beatsaver-map";
+import { BeatSaverMap } from "../model/beatsaver/map";
+import { MapDifficulty } from "../score/map-difficulty";
 
 /**
- * Gets the beatSaver mapper profile url.
+ * Gets the BeatSaver mapper profile url.
  *
  * @param map the beatsaver map
  * @returns the beatsaver mapper profile url
@@ -9,3 +10,18 @@ import { BeatSaverMap } from "../model/beatsaver/beatsaver-map";
 export function getBeatSaverMapperProfileUrl(map?: BeatSaverMap) {
   return map != undefined ? `https://beatsaver.com/profile/${map?.author.id}` : undefined;
 }
+
+/**
+ * Gets a BeatSaver difficulty from a map.
+ *
+ * @param map the map to get the difficulty from
+ * @param hash the hash of the map
+ * @param difficulty the difficulty to get
+ */
+export function getBeatSaverDifficulty(map: BeatSaverMap, hash: string, difficulty: MapDifficulty) {
+  const version = map.versions.find(v => v.hash === hash);
+  if (version == undefined) {
+    return undefined;
+  }
+  return version.difficulties.find(d => d.difficulty === difficulty);
+}

projects/common/src/utils/number-utils.ts

@@ -41,3 +41,16 @@ export function formatNumber(num: number, type: "number" | "pp" = "number") {
   }
   return formatNumberWithCommas(num);
 }
+
+/**
+ * Ensures a number is always positive
+ *
+ * @param num the number to ensure
+ * @returns the positive number
+ */
+export function ensurePositiveNumber(num: number) {
+  if (num == -0) {
+    return 0;
+  }
+  return num < 0 ? num * -1 : num;
+}

projects/common/src/utils/player-utils.ts

@@ -60,7 +60,7 @@ export function sortPlayerHistory(history: Map<string, PlayerHistory>) {
  * @param id the player id
  */
 export async function trackPlayer(id: string) {
-  await kyFetch(`${Config.apiUrl}/player/history/${id}?createIfMissing=true`);
+  await kyFetch(`${Config.apiUrl}/player/history/${id}/1?createIfMissing=true`);
 }
 
 /**

projects/common/src/utils/score-utils.ts

@@ -4,6 +4,23 @@ import PlayerScoresResponse from "../response/player-scores-response";
 import { Config } from "../config";
 import { ScoreSort } from "../score/score-sort";
 import LeaderboardScoresResponse from "../response/leaderboard-scores-response";
+import { Page } from "../pagination";
+import { ScoreSaberScore } from "src/model/score/impl/scoresaber-score";
+import { PlayerScore } from "../score/player-score";
+import ScoreSaberLeaderboard from "../model/leaderboard/impl/scoresaber-leaderboard";
+
+/**
+ * Fetches the player's scores
+ *
+ * @param playerId the id of the player
+ * @param leaderboardId the id of the leaderboard
+ * @param page the page
+ */
+export async function fetchPlayerScoresHistory(playerId: string, leaderboardId: string, page: number) {
+  return kyFetch<Page<PlayerScore<ScoreSaberScore, ScoreSaberLeaderboard>>>(
+    `${Config.apiUrl}/scores/history/${playerId}/${leaderboardId}/${page}`
+  );
+}
 
 /**
  * Fetches the player's scores

projects/common/src/utils/scoresaber-utils.ts

@@ -1,11 +1,11 @@
-import { Difficulty } from "../score/difficulty";
+import { MapDifficulty } from "../score/map-difficulty";
 
 /**
  * Formats the ScoreSaber difficulty number
  *
  * @param diff the diffuiclity number
  */
-export function getDifficultyFromScoreSaberDifficulty(diff: number): Difficulty {
+export function getDifficultyFromScoreSaberDifficulty(diff: number): MapDifficulty {
   switch (diff) {
     case 1: {
       return "Easy";
@@ -20,7 +20,7 @@ export function getDifficultyFromScoreSaberDifficulty(diff: number): Difficulty
       return "Expert";
     }
     case 9: {
-      return "Expert+";
+      return "ExpertPlus";
     }
     default: {
       return "Unknown";

projects/common/src/utils/scoresaber.util.ts

@@ -1,8 +1,8 @@
 import ScoreSaberPlayerToken from "../types/token/scoresaber/score-saber-player-token";
-import ScoreSaberLeaderboardPlayerInfoToken from "../types/token/scoresaber/score-saber-leaderboard-player-info-token";
 import ScoreSaberPlayer from "../player/impl/scoresaber-player";
+import { ScoreSaberLeaderboardPlayerInfoToken } from "../types/token/scoresaber/score-saber-leaderboard-player-info-token";
 
-type ScoreSaberRole = {
+export type ScoreSaberRole = {
   /**
    * The name of the role.
    */

projects/common/src/utils/string.util.ts

@@ -0,0 +1,14 @@
+/**
+ * Generates a random string
+ *
+ * @param length the length of the string
+ * @returns the random string
+ */
+export function randomString(length: number) {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}

projects/common/src/utils/time-utils.ts

@@ -134,3 +134,20 @@ export function getDaysAgo(date: Date): number {
 export function parseDate(date: string): Date {
   return new Date(date);
 }
+
+/**
+ * Formats the time in the format "MM:SS"
+ *
+ * @param seconds the time to format in seconds
+ * @returns the formatted time in "MM:SS" format
+ */
+export function formatTime(seconds: number): string {
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+
+  // Zero pad minutes and seconds to ensure two digits
+  const formattedMinutes = minutes < 10 ? `0${minutes}` : `${minutes}`;
+  const formattedSeconds = remainingSeconds < 10 ? `0${remainingSeconds}` : `${remainingSeconds}`;
+
+  return `${formattedMinutes}:${formattedSeconds}`;
+}