@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/leaderboards/LeaderboardPublicApi.js

@@ -0,0 +1,389 @@
+// The public leaderboard HTTP API (game-server-leaderboards D5, D6, D19, DR §6): one catch-all endpoint under
+// /game-server/leaderboards/ with its own route table. Every request is checked in a fixed order — route, origin,
+// address, auth, bans, read limit, body — before its handler runs. Player keys travel only in JSON bodies.
+import { createEndpoint } from "colyseus";
+import { isOriginAllowed } from "../AbuseLimits.js";
+import { getLogger } from "../GameServerLogger.js";
+import { needsVerification, verifyPlayerToken } from "../PlayerTokens.js";
+import { jsonResponse } from "../ServerEndpoints.js";
+import { requestOf } from "../admin/AdminApiRouter.js";
+import { AdminRequestGate } from "../admin/AdminRequestGate.js";
+import { LEADERBOARD_API_PREFIX, LEADERBOARD_DEFAULT_PAGE_SIZE, LEADERBOARD_MAX_BODY_BYTES, LEADERBOARD_MAXIMUM_AROUND_WINDOW, LEADERBOARD_MAXIMUM_PAGE_SIZE, LEADERBOARD_MAXIMUM_TARGETS } from "./LeaderboardConstants.js";
+import { LeaderboardError } from "./LeaderboardError.js";
+/** HTTP OK. */
+const HTTP_OK = 200;
+/** HTTP internal server error. */
+const HTTP_INTERNAL_ERROR = 500;
+/** The bearer scheme prefix of the Authorization header. */
+const BEARER_PREFIX = "Bearer ";
+/** Default window of an around-me read. */
+const DEFAULT_AROUND_WINDOW = 3;
+/** Most player ids in one players read. */
+const MAXIMUM_PLAYER_IDS = 50;
+/** Marker of a path parameter segment in a route pattern. */
+const PARAMETER_MARKER = ":";
+/**
+ * The public leaderboard endpoint for createRouter.
+ * @param service The leaderboard service.
+ * @param state The server state (config, verifier, bans, metrics).
+ * @returns The endpoint, keyed by name.
+ */
+export function createLeaderboardRoutes(service, state) {
+    const routes = buildRoutes(service);
+    return {
+        leaderboardApi: createEndpoint(LEADERBOARD_API_PREFIX + "**:apiPath", { method: ["GET", "POST"], disableBody: true }, async (context) => handleLeaderboardRequest(service, state, routes, requestOf(context)))
+    };
+}
+/**
+ * Answers one public request, turning a LeaderboardError into its JSON error body.
+ * @param service The leaderboard service.
+ * @param state The server state.
+ * @param routes The route table.
+ * @param request The Fetch request.
+ * @returns The response.
+ */
+async function handleLeaderboardRequest(service, state, routes, request) {
+    try {
+        return jsonResponse(HTTP_OK, await runRequest(service, state, routes, request));
+    }
+    catch (error) {
+        if (error instanceof LeaderboardError) {
+            state.metrics?.countLeaderboardRequestRefusal?.(error.reason);
+            return jsonResponse(error.status, { error: error.message, reason: error.reason });
+        }
+        getLogger().error("leaderboard request failed", { error: (error instanceof Error) ? error.message : String(error) });
+        return jsonResponse(HTTP_INTERNAL_ERROR, { error: "leaderboard request failed", reason: "invalidRequest" });
+    }
+}
+/**
+ * The request pipeline in its binding order: route, origin, address, auth, bans, read limit, body, handler.
+ * @param service The leaderboard service.
+ * @param state The server state.
+ * @param routes The route table.
+ * @param request The Fetch request.
+ * @returns The handler's answer.
+ * @throws LeaderboardError for every refusal.
+ */
+async function runRequest(service, state, routes, request) {
+    const url = new URL(request.url);
+    const match = matchRoute(routes, request.method.toUpperCase(), url.pathname);
+    if (match == null)
+        throw new LeaderboardError(404, "invalidRequest", "no such leaderboard route");
+    const origin = request.headers.get("origin");
+    if (origin != null && !isOriginAllowed(origin, state.config.limits))
+        throw new LeaderboardError(403, "invalidRequest", "origin not allowed");
+    const clientAddress = AdminRequestGate.clientAddressOf(request.headers);
+    const identity = await authenticate(state, request, clientAddress, origin);
+    const userId = (identity != null) ? identity.userId : null;
+    if (state.banList?.playerBan(userId, clientAddress) != null)
+        throw new LeaderboardError(403, "banned", "this player or address is banned");
+    if (match.route.isRead)
+        await service.consumeReadRate(clientAddress);
+    const body = (match.route.method === "POST") ? await readJsonBody(request) : {};
+    const caller = {
+        userId: userId,
+        userDisplayName: (identity != null) ? displayNameClaimOf(identity) : null,
+        userAvatar: (identity != null && typeof identity.claims.avatar === "string") ? identity.claims.avatar : null,
+        isNameManaged: identity != null && identity.claims.name_managed === true,
+        playerKey: (typeof body.playerKey === "string") ? body.playerKey : null,
+        clientAddress: clientAddress
+    };
+    return await match.route.handler({ params: match.params, query: url.searchParams, body: body, caller: caller });
+}
+/**
+ * Verifies the bearer token when the server's auth is on.
+ * @param state The server state.
+ * @param request The Fetch request.
+ * @param clientAddress The caller's address.
+ * @param origin The Origin header, or null.
+ * @returns The identity, or null when auth is off.
+ * @throws LeaderboardError 401 authRequired without a bearer token, 401 authRefused when the verifier refuses it.
+ */
+async function authenticate(state, request, clientAddress, origin) {
+    const authorization = request.headers.get("authorization") ?? "";
+    const token = authorization.startsWith(BEARER_PREFIX) ? authorization.slice(BEARER_PREFIX.length).trim() : "";
+    if (!needsVerification(state, token))
+        return null;
+    if (token === "")
+        throw new LeaderboardError(401, "authRequired", "this server needs an Authorization: Bearer token");
+    try {
+        return await verifyPlayerToken(state, { token: token, kind: "lobby", sessionName: null, gameMode: null, clientAddress: clientAddress, origin: origin });
+    }
+    catch {
+        state.metrics?.countAuthFailure(state.config.auth.mode);
+        throw new LeaderboardError(401, "authRefused", "the token was refused");
+    }
+}
+/**
+ * The display-name claim of an auth identity: name, else preferred_username.
+ * @param identity The identity.
+ * @returns The claim, or null.
+ */
+function displayNameClaimOf(identity) {
+    const name = identity.claims.name ?? identity.claims.preferred_username;
+    return (typeof name === "string") ? name : null;
+}
+/**
+ * Finds the route of a method and path, segment by segment.
+ * @param routes The route table.
+ * @param method The upper-case method.
+ * @param pathname The URL path.
+ * @returns The match, or null.
+ */
+function matchRoute(routes, method, pathname) {
+    if (!pathname.startsWith(LEADERBOARD_API_PREFIX))
+        return null;
+    const segments = pathname.slice(LEADERBOARD_API_PREFIX.length).split("/").filter((segment) => segment !== "");
+    for (const route of routes) {
+        if (route.method !== method)
+            continue;
+        const params = matchSegments(route.pattern.split("/"), segments);
+        if (params != null)
+            return { route: route, params: params };
+    }
+    return null;
+}
+/**
+ * Matches pattern segments against path segments.
+ * @param patternSegments The pattern's segments.
+ * @param pathSegments The path's segments.
+ * @returns The decoded parameters, or null when they do not match.
+ */
+function matchSegments(patternSegments, pathSegments) {
+    if (patternSegments.length !== pathSegments.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < patternSegments.length; i++) {
+        const patternSegment = patternSegments[i];
+        if (patternSegment.startsWith(PARAMETER_MARKER)) {
+            const decoded = decodeSegment(pathSegments[i]);
+            if (decoded == null)
+                return null;
+            params[patternSegment.slice(PARAMETER_MARKER.length)] = decoded;
+        }
+        else if (patternSegment !== pathSegments[i]) {
+            return null;
+        }
+    }
+    return params;
+}
+/**
+ * Decodes one URL path segment.
+ * @param segment The segment.
+ * @returns The decoded text, or null when it is not valid percent-encoding.
+ */
+function decodeSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads a POST body as a JSON object, at most LEADERBOARD_MAX_BODY_BYTES.
+ * @param request The Fetch request.
+ * @returns The object ({} for an empty body).
+ * @throws LeaderboardError 400 invalidRequest when too large, not JSON or not an object.
+ */
+export async function readJsonBody(request) {
+    const text = await readLimitedBodyText(request, LEADERBOARD_MAX_BODY_BYTES);
+    if (text == null)
+        throw new LeaderboardError(400, "invalidRequest", "request body too large");
+    if (text.trim() === "")
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new LeaderboardError(400, "invalidRequest", "the request body must be JSON");
+    }
+    if (typeof parsed !== "object" || parsed == null || Array.isArray(parsed))
+        throw new LeaderboardError(400, "invalidRequest", "the request body must be a JSON object");
+    return parsed;
+}
+/**
+ * Reads a request body, stopping as soon as it grows past the cap.
+ * @param request The Fetch request.
+ * @param maximumBytes The cap.
+ * @returns The body text, or null past the cap.
+ */
+async function readLimitedBodyText(request, maximumBytes) {
+    if (Number(request.headers.get("content-length") ?? 0) > maximumBytes)
+        return null;
+    if (request.body == null)
+        return "";
+    const reader = request.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        totalBytes += value.byteLength;
+        if (totalBytes > maximumBytes) {
+            await reader.cancel();
+            return null;
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * The public route table (DR §6).
+ * @param service The leaderboard service.
+ * @returns The routes.
+ */
+function buildRoutes(service) {
+    return [
+        { method: "POST", pattern: "players", isRead: false, handler: async (request) => service.openPlayerSession(request.caller) },
+        { method: "POST", pattern: "players/me", isRead: false, handler: async (request) => service.getOwnPlayer(request.caller) },
+        { method: "POST", pattern: "players/me/name", isRead: false, handler: async (request) => service.renameOwnPlayer(request.caller, request.body.displayName) },
+        { method: "POST", pattern: "players/me/delete", isRead: false, handler: async (request) => ({ erasedEntries: await service.eraseOwnPlayer(request.caller) }) },
+        { method: "GET", pattern: "boards", isRead: true, handler: async () => service.listPublicBoards() },
+        { method: "GET", pattern: "boards/:boardId/seasons", isRead: true, handler: async (request) => service.listSeasons(request.params.boardId, "public") },
+        { method: "GET", pattern: "boards/:boardId/entries", isRead: true, handler: async (request) => readEntriesPage(service, request) },
+        { method: "POST", pattern: "boards/:boardId/around", isRead: true, handler: async (request) => readAroundPage(service, request) },
+        { method: "POST", pattern: "boards/:boardId/players", isRead: true, handler: async (request) => readPlayersPage(service, request) },
+        { method: "POST", pattern: "entries/mine", isRead: true, handler: async (request) => readMyEntries(service, request) },
+        { method: "POST", pattern: "submissions", isRead: false, handler: async (request) => service.submit(request.caller, request.body, "public") }
+    ];
+}
+/**
+ * GET boards/:boardId/entries: `variant` (JSON object), `season`, `offset` and `limit` from the query.
+ * @param service The leaderboard service.
+ * @param request The parsed request.
+ * @returns The page.
+ */
+async function readEntriesPage(service, request) {
+    const variantText = request.query.get("variant");
+    const variant = (variantText != null) ? requireVariant(parseVariantText(variantText)) : null;
+    const seasonId = optionalInteger(request.query.get("season"), "season", 1, Number.MAX_SAFE_INTEGER);
+    const offset = optionalInteger(request.query.get("offset"), "offset", 0, Number.MAX_SAFE_INTEGER) ?? 0;
+    const limit = optionalInteger(request.query.get("limit"), "limit", 1, LEADERBOARD_MAXIMUM_PAGE_SIZE) ?? LEADERBOARD_DEFAULT_PAGE_SIZE;
+    const page = await service.readEntries(request.params.boardId, variant, seasonId, offset, limit, "public");
+    return { ...page, entries: await service.attachAvatars(page.entries) };
+}
+/**
+ * POST boards/:boardId/around: the caller's window of `window` (0–10, default 3) entries above and below.
+ * @param service The leaderboard service.
+ * @param request The parsed request.
+ * @returns The page.
+ */
+async function readAroundPage(service, request) {
+    const player = await service.resolvePlayer(request.caller);
+    const variant = requireVariant(request.body.variant);
+    const seasonId = optionalBodyInteger(request.body.seasonId, "seasonId", 1, Number.MAX_SAFE_INTEGER);
+    const window = optionalBodyInteger(request.body.window, "window", 0, LEADERBOARD_MAXIMUM_AROUND_WINDOW) ?? DEFAULT_AROUND_WINDOW;
+    const page = await service.readAround(request.params.boardId, variant, seasonId, player.playerId, window);
+    return { ...page, entries: await service.attachAvatars(page.entries) };
+}
+/**
+ * POST boards/:boardId/players: the entries of 1–50 named players.
+ * @param service The leaderboard service.
+ * @param request The parsed request.
+ * @returns The entries.
+ */
+async function readPlayersPage(service, request) {
+    const playerIds = request.body.playerIds;
+    const areIdsValid = Array.isArray(playerIds) && playerIds.length >= 1 && playerIds.length <= MAXIMUM_PLAYER_IDS && playerIds.every((playerId) => typeof playerId === "string");
+    if (!areIdsValid)
+        throw new LeaderboardError(400, "invalidRequest", "playerIds must be a list of 1–" + MAXIMUM_PLAYER_IDS + " player ids");
+    const variant = requireVariant(request.body.variant);
+    const seasonId = optionalBodyInteger(request.body.seasonId, "seasonId", 1, Number.MAX_SAFE_INTEGER);
+    const entries = await service.readPlayersEntries(request.params.boardId, variant, seasonId, playerIds);
+    return await service.attachAvatars(entries);
+}
+/**
+ * POST entries/mine: the caller's entry in each of 1–LEADERBOARD_MAXIMUM_TARGETS rankings.
+ * @param service The leaderboard service.
+ * @param request The parsed request.
+ * @returns One answer per target.
+ */
+async function readMyEntries(service, request) {
+    const player = await service.resolvePlayer(request.caller);
+    const targets = request.body.targets;
+    if (!Array.isArray(targets) || targets.length < 1 || targets.length > LEADERBOARD_MAXIMUM_TARGETS) {
+        throw new LeaderboardError(400, "invalidRequest", "targets must be a list of 1–" + LEADERBOARD_MAXIMUM_TARGETS + " rankings");
+    }
+    return await service.readTargets(player.playerId, targets.map(requireTarget));
+}
+/**
+ * Checks one my-entries target.
+ * @param value The target (any JSON).
+ * @returns The target.
+ * @throws LeaderboardError 400 invalidRequest.
+ */
+function requireTarget(value) {
+    if (typeof value !== "object" || value == null || Array.isArray(value))
+        throw new LeaderboardError(400, "invalidRequest", "each target must be an object");
+    const target = value;
+    if (typeof target.boardId !== "string")
+        throw new LeaderboardError(400, "invalidRequest", "each target needs a boardId");
+    const seasonId = optionalBodyInteger(target.seasonId, "seasonId", 1, Number.MAX_SAFE_INTEGER);
+    const parsed = { boardId: target.boardId, variant: requireVariant(target.variant) };
+    if (seasonId != null)
+        parsed.seasonId = seasonId;
+    return parsed;
+}
+/**
+ * Parses the `variant` query parameter.
+ * @param text The parameter.
+ * @returns The parsed JSON.
+ * @throws LeaderboardError 400 invalidRequest when it is not JSON.
+ */
+function parseVariantText(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new LeaderboardError(400, "invalidRequest", "variant must be a JSON object");
+    }
+}
+/**
+ * Checks a variant: null/absent or an object whose values are strings.
+ * @param value The variant (any JSON).
+ * @returns The variant, or null.
+ * @throws LeaderboardError 400 invalidRequest.
+ */
+function requireVariant(value) {
+    if (value == null)
+        return null;
+    const isObject = typeof value === "object" && !Array.isArray(value);
+    if (!isObject || !Object.values(value).every((entry) => typeof entry === "string")) {
+        throw new LeaderboardError(400, "invalidRequest", "variant must be an object whose values are texts");
+    }
+    return value;
+}
+/**
+ * Parses an optional integer query parameter.
+ * @param text The parameter, or null.
+ * @param name Its name (for the sentence).
+ * @param minimum The smallest value.
+ * @param maximum The largest value.
+ * @returns The value, or null when absent.
+ * @throws LeaderboardError 400 invalidRequest when it is not an integer in range.
+ */
+function optionalInteger(text, name, minimum, maximum) {
+    if (text == null || text === "")
+        return null;
+    return optionalBodyInteger(Number(text), name, minimum, maximum);
+}
+/**
+ * Checks an optional integer body field.
+ * @param value The field (any JSON).
+ * @param name Its name (for the sentence).
+ * @param minimum The smallest value.
+ * @param maximum The largest value.
+ * @returns The value, or null when absent.
+ * @throws LeaderboardError 400 invalidRequest when it is not an integer in range.
+ */
+function optionalBodyInteger(value, name, minimum, maximum) {
+    if (value == null)
+        return null;
+    const isValid = typeof value === "number" && Number.isSafeInteger(value) && value >= minimum && value <= maximum;
+    if (!isValid)
+        throw new LeaderboardError(400, "invalidRequest", name + " must be a whole number from " + minimum + " to " + maximum);
+    return value;
+}

package/lib/leaderboards/LeaderboardRankStore.d.ts

@@ -0,0 +1,296 @@
+import type { Redis } from "ioredis";
+import type { LeaderboardKeepPolicy, LeaderboardMetadata, LeaderboardSortOrder, LeaderboardTrustLevel } from "../admin/AdminApiTypes.js";
+/** One ranking: a board, a season and a variant. */
+export interface LeaderboardRankKey {
+    /** The board id. */
+    boardId: string;
+    /** The season (1, 2, 3 …). */
+    seasonId: number;
+    /** The canonical variant key (D16), "all" for a board without dimensions. */
+    variantKey: string;
+}
+/** An entry as stored (scores are integers, times are ISO strings plus the tie-break milliseconds). */
+export interface StoredLeaderboardEntry {
+    /** The player who owns the entry. */
+    playerId: string;
+    /** The player's name when the entry was written. */
+    displayName: string;
+    /** The stored score (an integer, D12). */
+    score: number;
+    /** Display-only details, or null. */
+    metadata: LeaderboardMetadata | null;
+    /** How far the write that set this entry was trusted. */
+    trustLevel: LeaderboardTrustLevel;
+    /** The network session the score came from, or null. */
+    sessionName: string | null;
+    /** The game's mode name, or null. */
+    gameMode: string | null;
+    /** The game's build version, or null. */
+    buildVersion: string | null;
+    /** ISO time of the last accepted submission. */
+    submittedAt: string;
+    /** ISO time the stored score was reached. */
+    achievedAt: string;
+    /** achievedAt in epoch milliseconds (the ranking tie-break, D13). */
+    achievedAtMs: number;
+    /** Accepted submissions that changed this entry (1 for a new entry). */
+    submissionCount: number;
+}
+/** A stored entry with its 1-based rank. */
+export interface RankedLeaderboardEntry extends StoredLeaderboardEntry {
+    /** 1-based rank in its ranking. */
+    rank: number;
+}
+/** A removed entry and why. */
+export interface RemovedLeaderboardEntry {
+    /** The entry as it was when removed. */
+    entry: StoredLeaderboardEntry;
+    /** Why it was removed ("playerHidden" for a hidden player). */
+    reason: string;
+    /** Who removed it. */
+    removedBy: string;
+    /** ISO time of the removal. */
+    removedAt: string;
+}
+/** One write. */
+export interface LeaderboardWriteRequest {
+    /** The ranking written. */
+    key: LeaderboardRankKey;
+    /** What the write does to an existing entry (D14). */
+    keepPolicy: LeaderboardKeepPolicy;
+    /** Which scores rank first. */
+    sortOrder: LeaderboardSortOrder;
+    /** The incoming entry; its score is the submitted score. */
+    entry: StoredLeaderboardEntry;
+    /** `<submissionId>|<boardId>|<variantKey>`, or null for admin writes (no dedupe). */
+    dedupeId: string | null;
+    /** The caller's clock (dedupe expiry in the file store). The store never sets entry times: callers do. */
+    nowMs: number;
+}
+/** What a write did. */
+export interface LeaderboardWriteResult {
+    /** "duplicate" when dedupeId was seen; "overflow" when a sum passed the score bound (nothing written). */
+    status: "written" | "kept" | "duplicate" | "overflow";
+    /** The keep-policy outcome, or null for an overflow. */
+    outcome: "created" | "improved" | "replaced" | "added" | "kept" | null;
+    /** The stored entry after the write, or null for an overflow. */
+    entry: StoredLeaderboardEntry | null;
+    /** The score stored before the write, or null for a new entry. */
+    previousScore: number | null;
+    /** The entry's 1-based rank after the write, or null for an overflow. */
+    rank: number | null;
+    /** Entries in the ranking after the write. */
+    total: number;
+}
+/** A leaderboard player as stored. */
+export interface LeaderboardPlayerRecord {
+    /** `anon-<uuid>`, `user:<userId>` or `manual-<uuid>` (D8). */
+    playerId: string;
+    /** How the player was created. */
+    kind: "anonymous" | "user" | "manual";
+    /** sha256 hex of the anonymous key's secret, else null. */
+    keyHash: string | null;
+    /** The current display name. */
+    displayName: string;
+    /** The avatar claim of an auth user's session (a Discord avatar hash for user:discord: players); absent or null otherwise. */
+    avatar?: string | null;
+    /** True while a moderator hides the player (D18). */
+    hidden: boolean;
+    /** ISO creation time. */
+    createdAt: string;
+    /** ISO time of the last submission or identity use. */
+    lastSeenAt: string;
+}
+/** Durability as D20 measures it. */
+export interface LeaderboardDurability {
+    /** Whether the data survives a restart or redeploy. */
+    durability: "durable" | "notDurable" | "unknown";
+    /** What to configure when not durable or unknown, else null. */
+    advice: string | null;
+}
+/** Rankings, players, rate counters and session presence (D1). */
+export interface LeaderboardRankStore {
+    /** "redis" or "file". */
+    readonly kind: "redis" | "file";
+    /**
+     * Writes one score with dedupe, the keep policy and the ranking, atomically.
+     * @param request The write.
+     * @returns What the write did.
+     */
+    write(request: LeaderboardWriteRequest): Promise<LeaderboardWriteResult>;
+    /**
+     * Reads a page of a ranking.
+     * @param key The ranking.
+     * @param offset Zero-based index of the first entry.
+     * @param limit Most entries returned.
+     * @returns The entries with their ranks, best first.
+     */
+    readRange(key: LeaderboardRankKey, offset: number, limit: number): Promise<RankedLeaderboardEntry[]>;
+    /**
+     * Counts the live entries of a ranking.
+     * @param key The ranking.
+     * @returns The count.
+     */
+    count(key: LeaderboardRankKey): Promise<number>;
+    /**
+     * Reads one player's live entry.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @returns The entry with its rank, or null.
+     */
+    readEntry(key: LeaderboardRankKey, playerId: string): Promise<RankedLeaderboardEntry | null>;
+    /**
+     * Reads the entries around a player's.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @param window Entries above and below.
+     * @returns The entries, or [] when the player has none.
+     */
+    readAround(key: LeaderboardRankKey, playerId: string, window: number): Promise<RankedLeaderboardEntry[]>;
+    /**
+     * Finds entries whose display name or player id contains the text, case-insensitively.
+     * @param key The ranking.
+     * @param text The text.
+     * @param limit Most entries returned.
+     * @returns The matches by rank.
+     */
+    searchEntries(key: LeaderboardRankKey, text: string, limit: number): Promise<RankedLeaderboardEntry[]>;
+    /**
+     * Reads the removed entries of a ranking.
+     * @param key The ranking.
+     * @returns The removed entries.
+     */
+    readRemoved(key: LeaderboardRankKey): Promise<RemovedLeaderboardEntry[]>;
+    /**
+     * Moves a live entry to the removed set.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @param reason Why.
+     * @param removedBy Who.
+     * @param removedAt ISO time.
+     * @returns True when there was a live entry.
+     */
+    removeEntry(key: LeaderboardRankKey, playerId: string, reason: string, removedBy: string, removedAt: string): Promise<boolean>;
+    /**
+     * Moves a removed entry back into the ranking.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @param sortOrder The board's sort order.
+     * @returns "restored", "missing" when nothing was removed, or "liveEntryExists".
+     */
+    restoreEntry(key: LeaderboardRankKey, playerId: string, sortOrder: LeaderboardSortOrder): Promise<"restored" | "missing" | "liveEntryExists">;
+    /**
+     * Lists the variant keys written in a season.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns The variant keys, sorted.
+     */
+    listVariantKeys(boardId: string, seasonId: number): Promise<string[]>;
+    /**
+     * Reads the time of a board's last accepted write.
+     * @param boardId The board.
+     * @returns ISO time, or null.
+     */
+    readLastSubmissionAt(boardId: string): Promise<string | null>;
+    /**
+     * Deletes every ranking of a season.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns How many entries (live and removed) were deleted.
+     */
+    deleteSeason(boardId: string, seasonId: number): Promise<number>;
+    /**
+     * Deletes every ranking of a board.
+     * @param boardId The board.
+     * @param seasonIds Its seasons.
+     */
+    deleteBoard(boardId: string, seasonIds: number[]): Promise<void>;
+    /**
+     * Lists every ranking a player has a live or removed entry in.
+     * @param playerId The player.
+     * @returns The rank keys.
+     */
+    listPlayerRankKeys(playerId: string): Promise<LeaderboardRankKey[]>;
+    /**
+     * Sets the display name on every entry of a player (live and removed).
+     * @param playerId The player.
+     * @param displayName The new name.
+     * @returns How many entries changed.
+     */
+    renamePlayerEntries(playerId: string, displayName: string): Promise<number>;
+    /**
+     * Deletes every entry of a player (live and removed).
+     * @param playerId The player.
+     * @returns How many entries were deleted.
+     */
+    deletePlayerEntries(playerId: string): Promise<number>;
+    /**
+     * Reads a player.
+     * @param playerId The player.
+     * @returns The record, or null.
+     */
+    getPlayer(playerId: string): Promise<LeaderboardPlayerRecord | null>;
+    /**
+     * Writes a player.
+     * @param record The record.
+     */
+    putPlayer(record: LeaderboardPlayerRecord): Promise<void>;
+    /**
+     * Deletes a player record.
+     * @param playerId The player.
+     * @returns True when it existed.
+     */
+    deletePlayer(playerId: string): Promise<boolean>;
+    /**
+     * Finds players whose display name or id contains the text, case-insensitively.
+     * @param text The text ("" lists any).
+     * @param limit Most players returned.
+     * @returns The players.
+     */
+    searchPlayers(text: string, limit: number): Promise<LeaderboardPlayerRecord[]>;
+    /**
+     * Counts every player.
+     * @returns The count.
+     */
+    countPlayers(): Promise<number>;
+    /**
+     * Counts one use in a fixed window (D19).
+     * @param bucket What is limited (e.g. "submit-player:<id>").
+     * @param limit Most uses per window.
+     * @param windowMs The window length, in milliseconds.
+     * @param nowMs The caller's clock.
+     * @returns True while the count is within the limit.
+     */
+    consumeRate(bucket: string, limit: number, windowMs: number, nowMs: number): Promise<boolean>;
+    /**
+     * Records a session join for each subject; the earliest join wins (D10).
+     * @param sessionName The session.
+     * @param subjects `address:<clientAddress>` and, when known, `user:<userId>`.
+     * @param joinedAtMs The join time.
+     * @param ttlMs How long the record lasts.
+     */
+    recordSessionPresence(sessionName: string, subjects: string[], joinedAtMs: number, ttlMs: number): Promise<void>;
+    /**
+     * Reads a subject's join time in a session.
+     * @param sessionName The session.
+     * @param subject The subject.
+     * @param nowMs The caller's clock (expiry).
+     * @returns The join time, or null.
+     */
+    readSessionPresence(sessionName: string, subject: string, nowMs: number): Promise<number | null>;
+    /**
+     * Measures whether the data survives a restart (D20).
+     * @returns The durability and advice.
+     */
+    measureDurability(): Promise<LeaderboardDurability>;
+    /** Flushes and releases what the store holds (never the shared Redis client). */
+    close(): Promise<void>;
+}
+/**
+ * Opens the rank store on the same Redis client the admin store uses, or on files under admin.dataDir.
+ * @param dataDir The resolved admin data folder (used without Redis).
+ * @param redisClient The shared ioredis client, or null.
+ * @param isFolderPersistent The admin store's isPersistent (the file store's durability).
+ * @returns The store.
+ */
+export declare function openLeaderboardRankStore(dataDir: string, redisClient: Redis | null, isFolderPersistent: boolean): Promise<LeaderboardRankStore>;