@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/leaderboards/LeaderboardTransfer.d.ts

@@ -0,0 +1,35 @@
+import type { LeaderboardExportFile, LeaderboardImportRequest, LeaderboardImportResult } from "../admin/AdminApiTypes.js";
+import { type AdminClock } from "../admin/AdminClock.js";
+import type { LeaderboardService } from "./LeaderboardService.js";
+/**
+ * Builds a JSON backup: every board or one, entries live and removed, every season or one, and every player those entries
+ * name (key hashes included, so anonymous players keep their keys after a restore).
+ * @param service The leaderboard service.
+ * @param boardId One board, or null for all.
+ * @param seasonId One season's entries, or null for every season's.
+ * @param clock The clock of the export time (the service's clock; default the system clock).
+ * @returns The export file.
+ * @throws LeaderboardError 404 for an unknown board, or a season that one named board does not keep.
+ */
+export declare function exportLeaderboards(service: LeaderboardService, boardId: string | null, seasonId: number | null, clock?: AdminClock): Promise<LeaderboardExportFile>;
+/**
+ * Builds the CSV of one ranking: the header and one RFC 4180 line per live entry in rank order.
+ * @param service The leaderboard service.
+ * @param boardId The board.
+ * @param seasonId The season.
+ * @param variantKey The variant key.
+ * @returns The CSV text.
+ * @throws LeaderboardError 404 for an unknown board or a season the board does not keep.
+ */
+export declare function exportRankingCsv(service: LeaderboardService, boardId: string, seasonId: number, variantKey: string): Promise<string>;
+/**
+ * Imports a backup or a definitions file. Every board is validated before anything is written; a dry run computes the
+ * same result without writing. "skip" leaves existing boards (and existing players) alone; "replace" deletes an existing
+ * board first and overwrites the file's players.
+ * @param service The leaderboard service.
+ * @param request The file, the conflict policy and the dry-run flag.
+ * @param clock The clock of the writes (the service's clock; default the system clock).
+ * @returns What was (or would be) created, replaced, skipped and written.
+ * @throws LeaderboardError 400 invalidRequest naming every problem of the file.
+ */
+export declare function importLeaderboards(service: LeaderboardService, request: LeaderboardImportRequest, clock?: AdminClock): Promise<LeaderboardImportResult>;

package/lib/leaderboards/LeaderboardTransfer.js

@@ -0,0 +1,580 @@
+// Leaderboard backups (game-server-leaderboards T6, DR §6 export/import rows, §15 imports): the JSON export with every
+// live and removed entry and the players they name, the CSV ranking export, and the import that restores a backup or
+// creates the boards of a definitions file. General purpose: nothing here knows any game (D2).
+import { SYSTEM_CLOCK } from "../admin/AdminClock.js";
+import { LeaderboardError } from "./LeaderboardError.js";
+import { validateBoardDefinition } from "./LeaderboardRules.js";
+/** The format marker of an export file. */
+const EXPORT_FORMAT = "babylon-game-server-leaderboards";
+/** The format marker of a definitions file (D11). */
+const DEFINITIONS_FORMAT = "babylon-game-server-leaderboard-definitions";
+/** The only file version this server reads and writes. */
+const FILE_VERSION = 1;
+/** Admin store collection of the boards (the service's own collection). */
+const LEADERBOARD_BOARDS_COLLECTION = "leaderboards";
+/** Entries read per page while exporting a ranking. */
+const EXPORT_PAGE_SIZE = 1000;
+/** The CSV ranking header (DR §6). */
+const CSV_HEADER = "rank,playerId,displayName,score,variantKey,seasonId,trustLevel,submittedAt";
+/** The CSV line ending (RFC 4180). */
+const CSV_LINE_END = "\r\n";
+/** Characters that make a CSV field need quotes (RFC 4180). */
+const CSV_QUOTED_CHARACTERS = /[",\r\n]/;
+/** Every trust level an exported entry may carry. */
+const TRUST_LEVELS = new Set(["client", "session", "server"]);
+/** Every kind an exported player may have. */
+const PLAYER_KINDS = new Set(["anonymous", "user", "manual"]);
+/** The conflict policies of an import. */
+const CONFLICT_POLICIES = new Set(["skip", "replace"]);
+/** Keep policy of every imported write: the entry as exported, never merged with a better score. */
+const IMPORT_KEEP_POLICY = "latest";
+// ---- Export ---------------------------------------------------------------------------------------------------------
+/**
+ * Builds a JSON backup: every board or one, entries live and removed, every season or one, and every player those entries
+ * name (key hashes included, so anonymous players keep their keys after a restore).
+ * @param service The leaderboard service.
+ * @param boardId One board, or null for all.
+ * @param seasonId One season's entries, or null for every season's.
+ * @param clock The clock of the export time (the service's clock; default the system clock).
+ * @returns The export file.
+ * @throws LeaderboardError 404 for an unknown board, or a season that one named board does not keep.
+ */
+export async function exportLeaderboards(service, boardId, seasonId, clock = SYSTEM_CLOCK) {
+    const records = (boardId != null) ? [await service.getBoardRecord(boardId)] : await service.listBoardRecords();
+    if (boardId != null && seasonId != null)
+        requireKeptSeason(records[0].value, seasonId);
+    const rankStore = service.stores.rankStore;
+    const boards = [];
+    const playerIds = new Set();
+    for (const stored of records) {
+        const board = await exportBoard(rankStore, stored.value, seasonId);
+        for (const entry of board.entries)
+            playerIds.add(entry.playerId);
+        boards.push(board);
+    }
+    return { format: EXPORT_FORMAT, version: FILE_VERSION, exportedAt: new Date(clock.now()).toISOString(), boards: boards, players: await exportPlayers(rankStore, playerIds) };
+}
+/**
+ * Builds the CSV of one ranking: the header and one RFC 4180 line per live entry in rank order.
+ * @param service The leaderboard service.
+ * @param boardId The board.
+ * @param seasonId The season.
+ * @param variantKey The variant key.
+ * @returns The CSV text.
+ * @throws LeaderboardError 404 for an unknown board or a season the board does not keep.
+ */
+export async function exportRankingCsv(service, boardId, seasonId, variantKey) {
+    const record = (await service.getBoardRecord(boardId)).value;
+    requireKeptSeason(record, seasonId);
+    const entries = await readWholeRanking(service.stores.rankStore, { boardId: boardId, seasonId: seasonId, variantKey: variantKey });
+    const lines = [CSV_HEADER];
+    for (const entry of entries) {
+        const fields = [entry.rank, entry.playerId, entry.displayName, entry.score, variantKey, seasonId, entry.trustLevel, entry.submittedAt];
+        lines.push(fields.map(csvField).join(","));
+    }
+    return lines.join(CSV_LINE_END) + CSV_LINE_END;
+}
+// ---- Import ---------------------------------------------------------------------------------------------------------
+/**
+ * Imports a backup or a definitions file. Every board is validated before anything is written; a dry run computes the
+ * same result without writing. "skip" leaves existing boards (and existing players) alone; "replace" deletes an existing
+ * board first and overwrites the file's players.
+ * @param service The leaderboard service.
+ * @param request The file, the conflict policy and the dry-run flag.
+ * @param clock The clock of the writes (the service's clock; default the system clock).
+ * @returns What was (or would be) created, replaced, skipped and written.
+ * @throws LeaderboardError 400 invalidRequest naming every problem of the file.
+ */
+export async function importLeaderboards(service, request, clock = SYSTEM_CLOCK) {
+    if (!CONFLICT_POLICIES.has(request.conflictPolicy))
+        throw new LeaderboardError(400, "invalidRequest", "conflictPolicy must be skip or replace");
+    const plan = parseImportFile(request.file);
+    const isReplacing = request.conflictPolicy === "replace";
+    const actions = [];
+    for (const board of plan.boards)
+        actions.push(await boardActionOf(service, board.definition.boardId, isReplacing));
+    const players = isReplacing ? plan.players : await missingPlayers(service.stores.rankStore, plan.players);
+    const writtenBoards = plan.boards.filter((board, index) => actions[index] !== "skip");
+    const result = {
+        dryRun: request.dryRun,
+        boardsCreated: boardIdsWith(plan.boards, actions, "create"),
+        boardsReplaced: boardIdsWith(plan.boards, actions, "replace"),
+        boardsSkipped: boardIdsWith(plan.boards, actions, "skip"),
+        entriesWritten: writtenBoards.reduce((total, board) => total + board.entries.length, 0),
+        playersWritten: players.length
+    };
+    if (request.dryRun)
+        return result;
+    for (const player of players)
+        await service.stores.rankStore.putPlayer(toPlayerRecord(player));
+    for (let i = 0; i < plan.boards.length; i++) {
+        if (actions[i] === "skip")
+            continue;
+        if (actions[i] === "replace")
+            await service.deleteBoard(plan.boards[i].definition.boardId);
+        await writeBoard(service, plan.boards[i], clock);
+    }
+    return result;
+}
+// ---- Export helpers -------------------------------------------------------------------------------------------------
+/**
+ * One board of an export.
+ * @param rankStore The rank store.
+ * @param record The board.
+ * @param seasonId One season (no entries when the board does not keep it), or null for every season the board keeps.
+ * @returns The exported board.
+ */
+async function exportBoard(rankStore, record, seasonId) {
+    const keptSeasonIds = record.seasons.map((season) => season.seasonId);
+    const seasonIds = (seasonId != null) ? keptSeasonIds.filter((keptSeasonId) => keptSeasonId === seasonId) : keptSeasonIds;
+    const entries = [];
+    for (const exportedSeasonId of seasonIds) {
+        for (const variantKey of await rankStore.listVariantKeys(record.definition.boardId, exportedSeasonId)) {
+            const key = { boardId: record.definition.boardId, seasonId: exportedSeasonId, variantKey: variantKey };
+            for (const entry of await readWholeRanking(rankStore, key))
+                entries.push(toExportEntry(key, entry, null));
+            for (const removed of await rankStore.readRemoved(key))
+                entries.push(toExportEntry(key, removed.entry, removed));
+        }
+    }
+    return { definition: record.definition, currentSeasonId: record.currentSeasonId, seasons: record.seasons, entries: entries };
+}
+/**
+ * Every live entry of a ranking, best first, read in pages.
+ * @param rankStore The rank store.
+ * @param key The ranking.
+ * @returns The entries with their ranks.
+ */
+async function readWholeRanking(rankStore, key) {
+    const total = await rankStore.count(key);
+    const entries = [];
+    for (let offset = 0; offset < total; offset += EXPORT_PAGE_SIZE)
+        entries.push(...await rankStore.readRange(key, offset, EXPORT_PAGE_SIZE));
+    return entries;
+}
+/**
+ * An entry as exported.
+ * @param key Its ranking.
+ * @param entry The stored entry.
+ * @param removed The removal record of a removed entry, or null for a live one.
+ * @returns The exported entry.
+ */
+function toExportEntry(key, entry, removed) {
+    return {
+        seasonId: key.seasonId,
+        variantKey: key.variantKey,
+        playerId: entry.playerId,
+        displayName: entry.displayName,
+        score: entry.score,
+        metadata: entry.metadata,
+        trustLevel: entry.trustLevel,
+        sessionName: entry.sessionName,
+        submittedAt: entry.submittedAt,
+        achievedAt: entry.achievedAt,
+        submissionCount: entry.submissionCount,
+        removedReason: (removed != null) ? removed.reason : null,
+        removedBy: (removed != null) ? removed.removedBy : null,
+        removedAt: (removed != null) ? removed.removedAt : null
+    };
+}
+/**
+ * The player records an export names (players without a record are left out).
+ * @param rankStore The rank store.
+ * @param playerIds The players.
+ * @returns The exported players, sorted by id.
+ */
+async function exportPlayers(rankStore, playerIds) {
+    const players = [];
+    for (const playerId of Array.from(playerIds).sort()) {
+        const record = await rankStore.getPlayer(playerId);
+        if (record == null)
+            continue;
+        players.push({ playerId: record.playerId, displayName: record.displayName, kind: record.kind, keyHash: record.keyHash, hidden: record.hidden, createdAt: record.createdAt });
+    }
+    return players;
+}
+/**
+ * One CSV field, quoted when it holds a quote, a comma or a line break (RFC 4180).
+ * @param value The value.
+ * @returns The field.
+ */
+function csvField(value) {
+    const text = String(value);
+    if (!CSV_QUOTED_CHARACTERS.test(text))
+        return text;
+    return "\"" + text.replace(/"/g, "\"\"") + "\"";
+}
+/**
+ * Checks that a board keeps a season.
+ * @param record The board.
+ * @param seasonId The season.
+ * @throws LeaderboardError 404 invalidRequest when it does not.
+ */
+function requireKeptSeason(record, seasonId) {
+    const isKept = record.seasons.some((season) => season.seasonId === seasonId);
+    if (!isKept)
+        throw new LeaderboardError(404, "invalidRequest", "board " + record.definition.boardId + " has no season " + seasonId);
+}
+// ---- Import helpers -------------------------------------------------------------------------------------------------
+/**
+ * Validates an import file completely.
+ * @param file The file (any JSON).
+ * @returns The plan.
+ * @throws LeaderboardError 400 invalidRequest with every problem joined.
+ */
+function parseImportFile(file) {
+    if (!isPlainObject(file))
+        throw new LeaderboardError(400, "invalidRequest", "file must be an export or definitions file object");
+    if (file.version !== FILE_VERSION)
+        throw new LeaderboardError(400, "invalidRequest", "file.version must be 1");
+    if (!Array.isArray(file.boards))
+        throw new LeaderboardError(400, "invalidRequest", "file.boards must be a list");
+    const problems = [];
+    let plan;
+    if (file.format === DEFINITIONS_FORMAT)
+        plan = { boards: parseDefinitionBoards(file.boards, problems), players: [] };
+    else if (file.format === EXPORT_FORMAT)
+        plan = { boards: parseExportBoards(file.boards, problems), players: parsePlayers(file.players, problems) };
+    else
+        throw new LeaderboardError(400, "invalidRequest", "file.format must be " + EXPORT_FORMAT + " or " + DEFINITIONS_FORMAT);
+    problems.push(...duplicateBoardProblems(plan.boards));
+    if (problems.length > 0)
+        throw new LeaderboardError(400, "invalidRequest", problems.join("; "));
+    return plan;
+}
+/**
+ * The boards of a definitions file.
+ * @param values The file's boards.
+ * @param problems Collects one sentence per problem.
+ * @returns The valid boards.
+ */
+function parseDefinitionBoards(values, problems) {
+    const boards = [];
+    values.forEach((value, index) => {
+        const definition = checkedDefinition(value, "boards[" + index + "]", problems);
+        if (definition != null)
+            boards.push({ definition: definition, currentSeasonId: null, seasons: null, entries: [] });
+    });
+    return boards;
+}
+/**
+ * The boards of an export file: definition, seasons and entries.
+ * @param values The file's boards.
+ * @param problems Collects one sentence per problem.
+ * @returns The valid boards.
+ */
+function parseExportBoards(values, problems) {
+    const boards = [];
+    values.forEach((value, index) => {
+        const label = "boards[" + index + "]";
+        if (!isPlainObject(value)) {
+            problems.push(label + " must be an object");
+            return;
+        }
+        const definition = checkedDefinition(value.definition, label, problems);
+        const seasons = checkedSeasons(value, label, problems);
+        const entries = checkedEntries(value.entries, label, seasons, problems);
+        if (definition == null || seasons == null)
+            return;
+        boards.push({ definition: definition, currentSeasonId: value.currentSeasonId, seasons: seasons, entries: entries });
+    });
+    return boards;
+}
+/**
+ * A board definition, or null with its problems recorded.
+ * @param value The definition (any JSON).
+ * @param label Where it is in the file.
+ * @param problems Collects one sentence per problem.
+ * @returns The valid definition, or null.
+ */
+function checkedDefinition(value, label, problems) {
+    const checked = validateBoardDefinition(value);
+    if (checked.definition == null)
+        problems.push(label + ": " + checked.problems.join(", "));
+    return checked.definition;
+}
+/**
+ * An exported board's seasons and current season, or null with its problems recorded.
+ * @param board The exported board.
+ * @param label Where it is in the file.
+ * @param problems Collects one sentence per problem.
+ * @returns The seasons, or null.
+ */
+function checkedSeasons(board, label, problems) {
+    const currentSeasonId = board.currentSeasonId;
+    if (!isPositiveInteger(currentSeasonId)) {
+        problems.push(label + ".currentSeasonId must be a whole number from 1");
+        return null;
+    }
+    const seasons = board.seasons;
+    const isSeasonList = Array.isArray(seasons) && seasons.every(isSeasonView);
+    if (!isSeasonList) {
+        problems.push(label + ".seasons must be a list of seasons");
+        return null;
+    }
+    const seasonList = seasons;
+    if (!seasonList.some((season) => season.seasonId === currentSeasonId)) {
+        problems.push(label + ".seasons must include the current season " + currentSeasonId);
+        return null;
+    }
+    return seasonList;
+}
+/**
+ * An exported board's entries, with each bad entry's problem recorded.
+ * @param value The entries (any JSON).
+ * @param label Where the board is in the file.
+ * @param seasons The board's seasons, or null when they were invalid.
+ * @param problems Collects one sentence per problem.
+ * @returns The entries (meaningful only when no problem was recorded).
+ */
+function checkedEntries(value, label, seasons, problems) {
+    if (!Array.isArray(value)) {
+        problems.push(label + ".entries must be a list");
+        return [];
+    }
+    const seasonIds = new Set((seasons ?? []).map((season) => season.seasonId));
+    value.forEach((entry, index) => {
+        const problem = entryProblem(entry, seasonIds);
+        if (problem != null)
+            problems.push(label + ".entries[" + index + "] " + problem);
+    });
+    return value;
+}
+/**
+ * What is wrong with one exported entry.
+ * @param value The entry (any JSON).
+ * @param seasonIds The board's seasons.
+ * @returns A problem sentence, or null.
+ */
+function entryProblem(value, seasonIds) {
+    if (!isPlainObject(value))
+        return "must be an object";
+    if (!isPositiveInteger(value.seasonId) || !seasonIds.has(value.seasonId))
+        return "names a season the board does not keep";
+    if (!isNonEmptyText(value.variantKey) || !isNonEmptyText(value.playerId))
+        return "needs a variantKey and a playerId";
+    if (typeof value.displayName !== "string")
+        return "displayName must be text";
+    if (!Number.isSafeInteger(value.score))
+        return "score must be a whole number";
+    if (!TRUST_LEVELS.has(value.trustLevel))
+        return "trustLevel must be client, session or server";
+    if (!isIsoTime(value.submittedAt) || !isIsoTime(value.achievedAt))
+        return "submittedAt and achievedAt must be ISO times";
+    if (!isPositiveInteger(value.submissionCount))
+        return "submissionCount must be a whole number from 1";
+    if (value.metadata != null && !isPlainObject(value.metadata))
+        return "metadata must be an object or null";
+    if (value.sessionName != null && typeof value.sessionName !== "string")
+        return "sessionName must be text or null";
+    return removalProblem(value);
+}
+/**
+ * What is wrong with an exported entry's removal fields: all null (live) or reason, removedBy and an ISO removedAt.
+ * @param entry The entry.
+ * @returns A problem sentence, or null.
+ */
+function removalProblem(entry) {
+    if (entry.removedReason == null)
+        return (entry.removedBy == null && entry.removedAt == null) ? null : "has removedBy or removedAt without a removedReason";
+    const isRemoval = typeof entry.removedReason === "string" && typeof entry.removedBy === "string" && isIsoTime(entry.removedAt);
+    return isRemoval ? null : "a removed entry needs text removedReason and removedBy and an ISO removedAt";
+}
+/**
+ * The players of an export file.
+ * @param value The players (any JSON).
+ * @param problems Collects one sentence per problem.
+ * @returns The players (meaningful only when no problem was recorded).
+ */
+function parsePlayers(value, problems) {
+    if (!Array.isArray(value)) {
+        problems.push("file.players must be a list");
+        return [];
+    }
+    value.forEach((player, index) => {
+        if (!isExportPlayer(player))
+            problems.push("players[" + index + "] needs playerId, displayName, kind, keyHash, hidden and an ISO createdAt");
+    });
+    return value;
+}
+/**
+ * One sentence per board id that appears more than once.
+ * @param boards The boards.
+ * @returns The problems.
+ */
+function duplicateBoardProblems(boards) {
+    const seen = new Set();
+    const problems = [];
+    for (const board of boards) {
+        const boardId = board.definition.boardId;
+        if (seen.has(boardId))
+            problems.push("board " + boardId + " appears more than once");
+        seen.add(boardId);
+    }
+    return problems;
+}
+/**
+ * What an import does to one board.
+ * @param service The leaderboard service.
+ * @param boardId The board.
+ * @param isReplacing True for the "replace" policy.
+ * @returns "create" for a new board, else "replace" or "skip" by the policy.
+ */
+async function boardActionOf(service, boardId, isReplacing) {
+    if (!await boardExists(service, boardId))
+        return "create";
+    return isReplacing ? "replace" : "skip";
+}
+/**
+ * Whether a board exists (read fresh from the admin store).
+ * @param service The leaderboard service.
+ * @param boardId The board.
+ * @returns True when it exists.
+ */
+async function boardExists(service, boardId) {
+    try {
+        await service.getBoardRecord(boardId);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof LeaderboardError && error.reason === "unknownBoard")
+            return false;
+        throw error;
+    }
+}
+/**
+ * The players of a file that have no record yet ("skip" never overwrites a player).
+ * @param rankStore The rank store.
+ * @param players The file's players.
+ * @returns The missing ones.
+ */
+async function missingPlayers(rankStore, players) {
+    const missing = [];
+    for (const player of players) {
+        if (await rankStore.getPlayer(player.playerId) == null)
+            missing.push(player);
+    }
+    return missing;
+}
+/**
+ * The ids of the boards an import treats one way.
+ * @param boards The boards.
+ * @param actions Each board's action, by index.
+ * @param action The action.
+ * @returns The board ids.
+ */
+function boardIdsWith(boards, actions, action) {
+    return boards.filter((board, index) => actions[index] === action).map((board) => board.definition.boardId);
+}
+/**
+ * Creates one board and writes its seasons and entries: removed entries first (written, then removed again with their
+ * reason, removedBy and removedAt), then live entries, so a player with both keeps both.
+ * @param service The leaderboard service.
+ * @param board The board.
+ * @param clock The clock of the writes.
+ */
+async function writeBoard(service, board, clock) {
+    await service.createBoard(board.definition);
+    if (board.currentSeasonId == null || board.seasons == null)
+        return;
+    const { adminStore, rankStore } = service.stores;
+    const created = await service.getBoardRecord(board.definition.boardId);
+    await adminStore.putDocument(LEADERBOARD_BOARDS_COLLECTION, board.definition.boardId, { ...created.value, currentSeasonId: board.currentSeasonId, seasons: board.seasons }, created.revision);
+    const removedEntries = board.entries.filter((entry) => entry.removedReason != null);
+    const liveEntries = board.entries.filter((entry) => entry.removedReason == null);
+    for (const entry of removedEntries) {
+        const key = await writeEntry(rankStore, board.definition, entry, clock);
+        await rankStore.removeEntry(key, entry.playerId, entry.removedReason, entry.removedBy, entry.removedAt);
+    }
+    for (const entry of liveEntries)
+        await writeEntry(rankStore, board.definition, entry, clock);
+}
+/**
+ * Writes one exported entry as it was (keep policy latest, its own achieved time, no dedupe).
+ * @param rankStore The rank store.
+ * @param definition The board.
+ * @param entry The exported entry.
+ * @param clock The clock of the write.
+ * @returns The entry's ranking.
+ */
+async function writeEntry(rankStore, definition, entry, clock) {
+    const key = { boardId: definition.boardId, seasonId: entry.seasonId, variantKey: entry.variantKey };
+    const stored = {
+        playerId: entry.playerId,
+        displayName: entry.displayName,
+        score: entry.score,
+        metadata: entry.metadata ?? null,
+        trustLevel: entry.trustLevel,
+        sessionName: entry.sessionName ?? null,
+        gameMode: null,
+        buildVersion: null,
+        submittedAt: entry.submittedAt,
+        achievedAt: entry.achievedAt,
+        achievedAtMs: Date.parse(entry.achievedAt),
+        submissionCount: entry.submissionCount
+    };
+    await rankStore.write({ key: key, keepPolicy: IMPORT_KEEP_POLICY, sortOrder: definition.sortOrder, entry: stored, dedupeId: null, nowMs: clock.now() });
+    return key;
+}
+/**
+ * The stored record of an exported player (its last-seen time is its creation time).
+ * @param player The exported player.
+ * @returns The record.
+ */
+function toPlayerRecord(player) {
+    return { playerId: player.playerId, kind: player.kind, keyHash: player.keyHash, displayName: player.displayName, hidden: player.hidden, createdAt: player.createdAt, lastSeenAt: player.createdAt };
+}
+// ---- Shape checks ---------------------------------------------------------------------------------------------------
+/**
+ * Whether a value is a plain JSON object.
+ * @param value The value.
+ * @returns True for a non-null, non-array object.
+ */
+function isPlainObject(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Whether a value is a whole number from 1.
+ * @param value The value.
+ * @returns True for 1, 2, 3 …
+ */
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && value >= 1;
+}
+/**
+ * Whether a value is non-empty text.
+ * @param value The value.
+ * @returns True for a string with at least one character.
+ */
+function isNonEmptyText(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/**
+ * Whether a value is a time text Date can read.
+ * @param value The value.
+ * @returns True for a parseable time string.
+ */
+function isIsoTime(value) {
+    return typeof value === "string" && !Number.isNaN(Date.parse(value));
+}
+/**
+ * Whether a value is a season view.
+ * @param value The value.
+ * @returns True for { seasonId, startedAt, endedAt, isCurrent } with the right types.
+ */
+function isSeasonView(value) {
+    if (!isPlainObject(value))
+        return false;
+    return isPositiveInteger(value.seasonId) && isIsoTime(value.startedAt) && (value.endedAt == null || isIsoTime(value.endedAt)) && typeof value.isCurrent === "boolean";
+}
+/**
+ * Whether a value is an exported player.
+ * @param value The value.
+ * @returns True for a player with every field of the right type.
+ */
+function isExportPlayer(value) {
+    if (!isPlainObject(value))
+        return false;
+    const hasKeyHash = value.keyHash === null || typeof value.keyHash === "string";
+    return isNonEmptyText(value.playerId) && typeof value.displayName === "string" && PLAYER_KINDS.has(value.kind) && hasKeyHash && typeof value.hidden === "boolean" && isIsoTime(value.createdAt);
+}