@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/AdminApiTypes.d.ts

@@ -0,0 +1,1782 @@
+/** One permission the console and API check (D17); AdminPermissions.ts lists them in this order. */
+export type AdminPermission = "fleet.view" | "fleet.manage" | "sessions.view" | "sessions.manage" | "sessions.inspect" | "players.view" | "players.viewAddresses" | "players.manage" | "bans.view" | "bans.manage" | "dedicated.view" | "dedicated.manage" | "metrics.view" | "logs.view" | "logs.manage" | "config.view" | "config.manage" | "auth.view" | "auth.manage" | "alerts.view" | "alerts.manage" | "audit.view" | "audit.retention" | "users.view" | "users.manage" | "apiKeys.manage" | "players.notes" | "extensions.run" | "extensions.runDeveloper" | "cloud.view" | "cloud.billing" | "leaderboards.view" | "leaderboards.manage" | "leaderboards.submit";
+/** One fixed admin role (D17), highest first in AdminPermissions.ADMIN_ROLES. */
+export type AdminRole = "owner" | "admin" | "operator" | "moderator" | "developer" | "viewer";
+/** Log levels, most severe first (structurally equal to the server's GameServerLogLevel). */
+export type AdminLogLevel = "error" | "warn" | "info" | "debug";
+/** How player tokens are verified (the server's AuthMode). */
+export type AdminAuthMode = "shared-secret" | "jwt" | "webhook" | "custom";
+/** Who made an admin call. */
+export type AdminCallerKind = "user" | "apiKey" | "legacyToken" | "cli" | "system";
+/** How prominent a notice to players is (the runtime's NetworkNoticeSeverity). */
+export type AdminNoticeSeverity = "info" | "warning" | "critical";
+/** Severity of an alert (spec 11). */
+export type AdminAlertSeverity = "info" | "warning" | "critical";
+/** What a ban matches. */
+export type BanKind = "user" | "address" | "network";
+/** Who started a dedicated session. */
+export type DedicatedStartedBy = "boot" | "admin" | "onDemand" | "code";
+/** A player's connection. */
+export type PlayerTransport = "websocket" | "webtransport";
+/** The chart ranges of the metrics page. */
+export type MetricsRange = "15m" | "1h" | "6h" | "24h";
+/** A page of a server-side list (ADMIN_PAGE_SIZE rows). */
+export interface PageView<Item> {
+    /** The rows of this page. */
+    items: Item[];
+    /** Rows matching the filters, on every page. */
+    total: number;
+}
+/** The answer of an action with nothing else to say. */
+export interface OkView {
+    /** Always true. */
+    ok: true;
+}
+/** The error body of every refused or failed call. */
+export interface AdminErrorView {
+    /** One sentence for the admin. */
+    error: string;
+    /** Extra detail, e.g. the missing permission or "stepUp". */
+    detail?: string;
+    /** The current document of a 409 conflict. */
+    current?: unknown;
+}
+/** Per-admin console preferences. */
+export interface AdminPreferences {
+    /** Colour theme. */
+    theme: "system" | "light" | "dark";
+    /** How times are shown. */
+    timeZone: "local" | "utc";
+}
+/** Maintenance in force on one instance (D14). */
+export interface MaintenanceState {
+    /** Shown to refused players. */
+    message: string;
+    /** User ids still admitted. */
+    allowUserIds: string[];
+    /** Addresses still admitted. */
+    allowAddresses: string[];
+    /** True when readiness reports "maintenance". */
+    leaveReadiness: boolean;
+    /** "fleet" when it comes from the stored fleet setting, "instance" when set for this instance only. */
+    scope: "fleet" | "instance";
+    /** ISO time it ends by itself (scheduled windows), or null. */
+    endsAt: string | null;
+}
+/** The stored fleet maintenance setting (settings/maintenance). */
+export interface MaintenanceSettings extends Omit<MaintenanceState, "scope" | "endsAt"> {
+    /** False when fleet maintenance is off. */
+    enabled: boolean;
+}
+/** What each instance publishes every FLEET_HEARTBEAT_INTERVAL_MS (D16). */
+export interface InstanceHeartbeat {
+    processId: string;
+    publicAddress: string | null;
+    hostName: string;
+    instanceLabel: string | null;
+    serverVersion: string;
+    protocolVersion: number;
+    startedAt: string;
+    sentAt: string;
+    ready: boolean;
+    readinessReasons: string[];
+    draining: boolean;
+    drainDeadline: string | null;
+    maintenance: MaintenanceState | null;
+    players: number;
+    sessions: number;
+    dedicatedSessions: number;
+    cpuPercent: number;
+    residentMemoryBytes: number;
+    heapUsedBytes: number;
+    eventLoopLagMilliseconds: number;
+    certificateDaysLeft: number | null;
+    logLevel: AdminLogLevel;
+    /** Counter totals since start (0 when metrics are off). */
+    joinsAccepted: number;
+    joinsRefused: number;
+    refusalsByReason: Record<string, number>;
+    authFailures: number;
+    framesWebsocket: number;
+    framesWebtransport: number;
+}
+/** One captured log entry (redacted at capture, D21). */
+export interface LogEntry {
+    /** Grows by one per entry on its instance. */
+    sequence: number;
+    time: string;
+    level: AdminLogLevel;
+    message: string;
+    fields: Record<string, unknown>;
+}
+/** A notice to players (the runtime's NetworkNoticePayload, DR §6.9). */
+export interface AdminNoticePayload {
+    /** Unique per notice. */
+    noticeId: string;
+    /** At most NOTICE_TEXT_MAX_LENGTH characters. */
+    text: string;
+    severity: AdminNoticeSeverity;
+    /** Seconds until the announced event, or null. */
+    countdownSeconds: number | null;
+    /** Server time it was sent, in milliseconds since the epoch. */
+    sentAtMilliseconds: number;
+}
+/** A typed input of a custom admin action (D25). */
+export interface AdminActionField {
+    name: string;
+    label: string;
+    type: "text" | "number" | "boolean" | "select" | "secret";
+    required: boolean;
+    /** The choices of a "select". */
+    options?: string[];
+    defaultValue?: string | number | boolean;
+}
+/** What a custom action targets; the console shows it on that page. */
+export type AdminActionTarget = "server" | "instance" | "session" | "player";
+/** The target ids of a custom action or panel: instance processId, session roomId, or a player. */
+export interface AdminActionTargetIds {
+    processId?: string;
+    roomId?: string;
+    playerId?: number;
+    userId?: string | null;
+}
+/** What a custom action returns. */
+export interface AdminActionResult {
+    ok: boolean;
+    message: string;
+    data?: Record<string, string | number | boolean | null>;
+}
+/** Where a custom panel is shown. */
+export type AdminPanelPlacement = "overview" | "session" | "player";
+/** Content of a custom panel. */
+export type AdminPanelContent = {
+    kind: "table";
+    columns: string[];
+    rows: (string | number | boolean | null)[][];
+} | {
+    kind: "values";
+    values: {
+        label: string;
+        value: string | number | boolean | null;
+    }[];
+};
+/** GET auth/methods: what the sign-in page offers. */
+export interface SignInMethodsView {
+    local: boolean;
+    oidc: {
+        label: string;
+    } | null;
+    passkeys: boolean;
+    /** True while a first-owner setup link is pending. */
+    needsSetup: boolean;
+}
+/** POST setup/owner. */
+export interface SetupOwnerRequest {
+    setupToken: string;
+    username: string;
+    displayName: string;
+    password: string;
+}
+/** POST auth/sign-in. */
+export interface SignInRequest {
+    username: string;
+    password: string;
+}
+/** The next step of a sign-in. */
+export interface SignInStepView {
+    stage: "secondFactor" | "enrolSecondFactor";
+    /** Names the half-finished sign-in in the next call. */
+    pendingToken: string;
+}
+/** POST auth/enrol. */
+export interface AuthEnrolRequest {
+    pendingToken: string;
+}
+/** The authenticator secret to enrol (the only answer that shows it). */
+export interface TotpEnrolmentView {
+    /** Base32 secret. */
+    secret: string;
+    /** otpauth:// URI for the QR code. */
+    otpauthUri: string;
+}
+/** POST auth/enrol/confirm. */
+export interface AuthEnrolConfirmRequest {
+    pendingToken: string;
+    code: string;
+}
+/** POST auth/second-factor: a code or a recovery code. */
+export interface AuthSecondFactorRequest {
+    pendingToken: string;
+    code?: string;
+    recoveryCode?: string;
+}
+/** A finished sign-in (the cookie comes with it). */
+export interface SignedInView {
+    session: ConsoleSessionView;
+    /** New recovery codes after enrolment; empty otherwise. */
+    recoveryCodes: string[];
+}
+/** Whether the console's Colyseus Cloud page applies to this server (colyseus-cloud-console D8). */
+export type ColyseusCloudFeature = "configured" | "setupNeeded" | "off";
+/** Server features the console adapts its navigation to. */
+export interface ConsoleFeaturesView {
+    /** "configured": a Cloud API token is set; "setupNeeded": on Colyseus Cloud without one; "off": the page is hidden. */
+    colyseusCloud: ColyseusCloudFeature;
+}
+/** GET auth/session: the signed-in admin. */
+export interface ConsoleSessionView {
+    user: AdminUserView;
+    permissions: AdminPermission[];
+    /** Sent back as x-admin-csrf on POST, PUT and DELETE. */
+    csrfToken: string;
+    secondFactorAt: string;
+    /** When the session ends at the latest (absolute timeout). */
+    expiresAt: string;
+    /** Server features the console adapts its navigation to (colyseus-cloud-console D8). */
+    features: ConsoleFeaturesView;
+}
+/** POST auth/step-up: a code or a recovery code. */
+export interface AuthStepUpRequest {
+    code?: string;
+    recoveryCode?: string;
+}
+/** GET account/sessions: one of the caller's console sessions. */
+export interface AccountSessionView {
+    sessionId: string;
+    createdAt: string;
+    lastSeenAt: string;
+    clientAddress: string;
+    userAgent: string;
+    /** True for the session making the call. */
+    current: boolean;
+}
+/** PUT account/password. */
+export interface AccountPasswordRequest {
+    currentPassword: string;
+    newPassword: string;
+}
+/** POST account/recovery-codes. */
+export interface AccountRecoveryCodesView {
+    recoveryCodes: string[];
+}
+/** An admin account as the console shows it (never its secrets). */
+export interface AdminUserView {
+    userId: string;
+    username: string;
+    displayName: string;
+    email: string | null;
+    role: AdminRole;
+    disabled: boolean;
+    locked: boolean;
+    hasSecondFactor: boolean;
+    createdAt: string;
+    lastSignInAt: string | null;
+    preferences: AdminPreferences;
+    /** The stored revision, for UpdateUserRequest.expectedRevision. */
+    revision: number;
+}
+/** POST users. */
+export interface CreateUserRequest {
+    username: string;
+    displayName: string;
+    email: string | null;
+    role: AdminRole;
+    temporaryPassword: string;
+}
+/** PUT users/:userId. */
+export interface UpdateUserRequest {
+    displayName?: string;
+    email?: string | null;
+    role?: AdminRole;
+    disabled?: boolean;
+    expectedRevision: number;
+}
+/** POST users/:userId/end-sessions. */
+export interface UsersEndSessionsView {
+    ended: number;
+}
+/** An API key as the console shows it (never its secret). */
+export interface ApiKeyView {
+    keyId: string;
+    name: string;
+    permissions: AdminPermission[];
+    expiresAt: string | null;
+    allowedNetworks: string[];
+    createdBy: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    revoked: boolean;
+}
+/** POST api-keys. */
+export interface CreateApiKeyRequest {
+    name: string;
+    permissions: AdminPermission[];
+    expiresAt: string | null;
+    allowedNetworks: string[];
+}
+/** A new API key: its secret is shown this once. */
+export interface CreatedApiKeyView {
+    key: ApiKeyView;
+    /** The full bearer value, bgsk_<keyId>_<secret>. */
+    secret: string;
+}
+/** The fleet at a glance (spec 2). */
+export interface OverviewView {
+    instancesUp: number;
+    instancesLost: number;
+    players: number;
+    sessions: number;
+    playersByGameMode: Record<string, number>;
+    sessionsByGameMode: Record<string, number>;
+    dedicatedSessions: number;
+    joinsPerMinute: number;
+    refusalsPerMinute: number;
+    topRefusalReasons: {
+        reason: string;
+        perMinute: number;
+    }[];
+    authFailuresPerMinute: number;
+    transportShare: {
+        websocket: number;
+        webtransport: number;
+    };
+    versions: {
+        serverVersion: string;
+        protocolVersion: number;
+        instances: number;
+    }[];
+    certificateDaysLeft: number | null;
+    redis: "reachable" | "unreachable" | "not configured";
+    maintenance: "off" | "fleet" | "some instances";
+    draining: number;
+    scaledOut: boolean;
+    warnings: HealthWarningView[];
+    customPanels: AdminPanelView[];
+    activity: ActivityItemView[];
+}
+/** One health warning with the page that fixes it (spec 2). */
+export interface HealthWarningView {
+    code: "authOffInProduction" | "originsOpen" | "metricsUnprotected" | "consoleOverHttp" | "certificateExpiring" | "mixedVersions" | "instanceLost" | "storeNotPersistent" | "fleetWithoutRedis";
+    severity: "info" | "warning" | "critical";
+    message: string;
+    /** Console hash route of the fix, e.g. "#/config?path=auth.enabled". */
+    fixRoute: string;
+}
+/** An instance row (spec 3). */
+export interface InstanceView extends InstanceHeartbeat {
+    status: "up" | "lost";
+    isThisInstance: boolean;
+}
+/** An instance page. */
+export interface InstanceDetailView {
+    instance: InstanceView;
+    sessions: SessionSummaryView[];
+    dedicated: DedicatedSessionView[];
+}
+/** POST instances/:processId/drain. */
+export interface InstancesDrainRequest {
+    noticeText: string | null;
+    noticeLeadSeconds: number;
+}
+/** The answer of a drain. */
+export interface DrainStartedView {
+    drainDeadline: string;
+}
+/** GET maintenance. */
+export interface MaintenanceView {
+    fleet: MaintenanceSettings | null;
+    instances: {
+        processId: string;
+        maintenance: MaintenanceState | null;
+    }[];
+    windows: MaintenanceWindowView[];
+}
+/** PUT maintenance. */
+export interface SetMaintenanceRequest {
+    /** "fleet" or a process id. */
+    scope: "fleet" | string;
+    enabled: boolean;
+    message: string;
+    allowUserIds: string[];
+    allowAddresses: string[];
+    leaveReadiness: boolean;
+    /** Seconds of warning notice sent first, or null. */
+    noticeSeconds: number | null;
+}
+/** A session row (spec 4). */
+export interface SessionSummaryView {
+    roomId: string;
+    sessionName: string;
+    gameMode: string;
+    players: number;
+    maxPlayers: number;
+    processId: string;
+    publicAddress: string | null;
+    createdAt: string | null;
+    dedicatedScene: string | null;
+    hostPlayerId: number | null;
+    isOpen: boolean;
+    isVisible: boolean;
+    locked: boolean;
+    bytesPerSecond: number;
+}
+/** A session page (spec 4). */
+export interface SessionDetailView extends SessionSummaryView {
+    properties: Record<string, string | number | boolean>;
+    tickRate: number | null;
+    players: number;
+    playerList: SessionPlayerView[];
+    traffic: {
+        framesIn: number;
+        framesOut: number;
+        bytesIn: number;
+        bytesOut: number;
+    };
+    /** The dedicated runner's scene, who started it and its frame history; null for a session without one. */
+    dedicated: {
+        sceneName: string;
+        startedBy: DedicatedStartedBy;
+        frameStatistics: DedicatedFrameBucketView[];
+    } | null;
+    hostMigrations: {
+        at: string;
+        fromPlayerId: number;
+        toPlayerId: number;
+    }[];
+    logLines: LogEntryView[];
+}
+/** One player of a session. */
+export interface SessionPlayerView {
+    playerId: number;
+    userId: string | null;
+    /** claims.name ?? claims.preferred_username ?? null. */
+    displayName: string | null;
+    /** Null without players.viewAddresses. */
+    clientAddress: string | null;
+    transport: PlayerTransport;
+    joinedAt: string;
+    connected: boolean;
+    isHost: boolean;
+    isMasterClient: boolean;
+}
+/** The session inspector (spec 4, Should). */
+export interface SessionInspectorView {
+    available: boolean;
+    reason: string | null;
+    objects: {
+        networkId: string;
+        kind: "prefab" | "scene";
+        name: string;
+        stateAuthorityPlayerId: number | null;
+        lastChangedTick: number | null;
+        stateWordCount: number;
+    }[];
+}
+/** POST sessions/:roomId/close. */
+export interface SessionsCloseRequest {
+    message: string;
+}
+/** POST sessions/close-all. */
+export interface SessionsCloseAllRequest {
+    message: string;
+    /** Must be exactly "close all sessions". */
+    confirmText: "close all sessions";
+}
+/** The answer of close-all. */
+export interface SessionsCloseAllView {
+    closed: number;
+}
+/** POST sessions/:roomId/lock. */
+export interface SessionsLockRequest {
+    locked: boolean;
+}
+/** POST notices. */
+export interface SendNoticeRequest {
+    scope: "fleet" | "instance" | "session" | "player";
+    processId?: string;
+    roomId?: string;
+    playerId?: number;
+    text: string;
+    severity: AdminNoticeSeverity;
+    countdownSeconds: number | null;
+}
+/** The answer of a notice. */
+export interface NoticeSentView {
+    targetedPlayers: number;
+}
+/** A player search row. */
+export interface PlayerSummaryView {
+    roomId: string;
+    sessionName: string;
+    processId: string;
+    playerId: number;
+    userId: string | null;
+    displayName: string | null;
+    clientAddress: string | null;
+    transport: PlayerTransport;
+    joinedAt: string;
+}
+/** A player page. */
+export interface PlayerDetailView {
+    userId: string | null;
+    address: string | null;
+    /** Values of claims named like secrets show "[hidden]". */
+    claims: Record<string, unknown> | null;
+    online: PlayerSummaryView[];
+    recentSessions: PlayerSessionHistoryView[];
+    bans: BanView[];
+    /** Empty without players.notes. */
+    notes: PlayerNoteView[];
+    /** Empty without players.notes. */
+    kicks: AuditRecordView[];
+}
+/** A past session of a player (stream playerHistory). */
+export interface PlayerSessionHistoryView {
+    roomId: string;
+    sessionName: string;
+    processId: string;
+    playerId: number;
+    joinedAt: string;
+    leftAt: string | null;
+}
+/** A note on a player. */
+export interface PlayerNoteView {
+    noteId: string;
+    subject: string;
+    text: string;
+    by: string;
+    at: string;
+}
+/** POST players/kick. */
+export interface KickPlayerRequest {
+    roomId: string;
+    playerId: number;
+    message: string;
+    allowRejoin: boolean;
+}
+/** POST players/notes. */
+export interface PlayersNotesRequest {
+    /** A user id or an address. */
+    subject: string;
+    text: string;
+}
+/** POST lobby/kick. */
+export interface LobbyKickRequest {
+    userId: string | null;
+    address: string | null;
+}
+/** The answer of a lobby kick. */
+export interface LobbyKickView {
+    disconnected: number;
+}
+/** One change in a ban's history. */
+export interface BanHistoryEntry {
+    at: string;
+    by: string;
+    change: string;
+}
+/** A ban as the console shows it. */
+export interface BanView {
+    banId: string;
+    kind: BanKind;
+    /** User id, address, or CIDR range. */
+    value: string;
+    reason: string;
+    note: string;
+    /** Null for a permanent ban. */
+    expiresAt: string | null;
+    createdBy: string;
+    createdAt: string;
+    active: boolean;
+    revision: number;
+    history: BanHistoryEntry[];
+}
+/** POST bans. */
+export interface CreateBanRequest {
+    kind: BanKind;
+    value: string;
+    /** Null for a permanent ban. */
+    durationSeconds: number | null;
+    reason: string;
+    note: string;
+    /** Confirms a ban of an address many players may share. */
+    confirmSharedAddress: boolean;
+}
+/** PUT bans/:banId. */
+export interface BansUpdateRequest {
+    expiresAt: string | null;
+    reason: string;
+    note: string;
+    expectedRevision: number;
+}
+/** The bans.json download and the bans/import body (R30). */
+export interface BanExportFile {
+    version: 1;
+    exportedAt: string;
+    bans: {
+        kind: BanKind;
+        value: string;
+        reason: string;
+        note: string;
+        expiresAt: string | null;
+    }[];
+}
+/** POST bans/import. */
+export type BansImportRequest = BanExportFile;
+/** The answer of a ban import. */
+export interface BansImportView {
+    imported: number;
+    skipped: number;
+}
+/** GET dedicated (spec 6). */
+export interface DedicatedView {
+    scenes: DedicatedSceneView[];
+    sessions: DedicatedSessionView[];
+}
+/** A configured dedicated scene. */
+export interface DedicatedSceneView {
+    name: string;
+    sceneRoot: string;
+    sceneFile: string;
+    projectScripts: string[];
+    maxPlayers: number;
+    onDemand: boolean;
+    idleSeconds: number;
+    source: "config";
+}
+/** A running dedicated session. */
+export interface DedicatedSessionView {
+    roomId: string;
+    sessionName: string;
+    sceneName: string;
+    processId: string;
+    players: number;
+    maxPlayers: number;
+    startedBy: DedicatedStartedBy;
+    frameStatistics: DedicatedFrameBucketView[];
+}
+/** One DEDICATED_FRAME_BUCKET_SECONDS bucket of a dedicated runner's frames. */
+export interface DedicatedFrameBucketView {
+    at: string;
+    averageFrameMilliseconds: number;
+    maximumFrameMilliseconds: number;
+    tickOverruns: number;
+}
+/** POST dedicated/start. */
+export interface DedicatedStartRequest {
+    sceneName: string;
+    sessionName: string;
+    /** The instance to run it on, or null for this one. */
+    processId: string | null;
+}
+/** The answer of a dedicated start or restart. */
+export interface DedicatedStartedView {
+    roomId: string;
+}
+/** POST dedicated/:roomId/stop. */
+export interface DedicatedStopRequest {
+    message: string;
+}
+/** POST dedicated/:roomId/restart. */
+export interface DedicatedRestartRequest {
+    message: string;
+}
+/** What a stopped dedicated session needs to start again under the same name (R17), returned before it disconnects. */
+export interface DedicatedRestartOptions {
+    sceneName: string;
+    sessionName: string;
+    /** The instance that ran it. */
+    processId: string;
+}
+/** POST dedicated/scenes/:sceneName/check. */
+export interface DedicatedScenesCheckRequest {
+    processId: string | null;
+}
+/** Whether a scene's files load. */
+export interface SceneCheckView {
+    sceneName: string;
+    ok: boolean;
+    files: {
+        url: string;
+        ok: boolean;
+        status: number | null;
+        error: string | null;
+    }[];
+}
+/** One chart point: rates per second are computed from counter differences. */
+export interface MetricsPointView {
+    at: string;
+    players: number;
+    sessions: number;
+    dedicatedSessions: number;
+    joinsPerSecond: number;
+    refusalsPerSecond: number;
+    authFailuresPerSecond: number;
+    bytesInPerSecond: number;
+    bytesOutPerSecond: number;
+    messagesInPerSecond: number;
+    cpuPercent: number;
+    residentMemoryBytes: number;
+    heapUsedBytes: number;
+    eventLoopLagMilliseconds: number;
+    gcMillisecondsPerSecond: number;
+    dedicatedFrameMillisecondsAverage: number;
+    dedicatedTickOverrunsPerSecond: number;
+    /** Accepted leaderboard scores per second (game-server-leaderboards D21). */
+    leaderboardAcceptedPerSecond: number;
+    /** Refused leaderboard scores per second (game-server-leaderboards D21). */
+    leaderboardRefusedPerSecond: number;
+}
+/** GET metrics (spec 7). */
+export interface MetricsSeriesView {
+    /** "fleet" or a process id. */
+    processId: string;
+    range: MetricsRange;
+    points: MetricsPointView[];
+    grafanaUrl: string | null;
+}
+/** A log line (spec 8). */
+export interface LogEntryView extends LogEntry {
+    processId: string;
+}
+/** GET logs. */
+export interface LogPageView {
+    entries: LogEntryView[];
+    /** JSON cursor for the next ?after=. */
+    cursor: string;
+}
+/** PUT logs/level. */
+export interface LogsLevelRequest {
+    /** "fleet" or a process id. */
+    scope: "fleet" | string;
+    level: AdminLogLevel;
+    revertAfterMinutes: number;
+}
+/** GET config (spec 9). */
+export interface ConfigView {
+    processId: string;
+    /** The configOverrides document revision, or null when none is stored. */
+    revision: number | null;
+    options: ConfigOptionView[];
+    dedicatedScenes: DedicatedSceneView[];
+}
+/** One option of the config page. */
+export interface ConfigOptionView {
+    path: string;
+    environmentVariable: string;
+    flag: string | null;
+    description: string;
+    isSecret: boolean;
+    /** The value, or "set" / "not set" for secrets. */
+    value: unknown;
+    source: "default" | "platform" | "file" | "environment" | "flag" | "code" | "override";
+    liveEditable: boolean;
+    locked: boolean;
+    needsRestart: boolean;
+}
+/** PUT config/overrides. */
+export interface ConfigOverridesRequest {
+    /** "fleet" or a process id. */
+    scope: "fleet" | string;
+    path: string;
+    value: unknown;
+    expectedRevision: number | null;
+}
+/** One config change of the history. */
+export interface ConfigChangeView {
+    at: string;
+    by: string;
+    scope: "fleet" | string;
+    path: string;
+    before: unknown;
+    after: unknown;
+    reverted: boolean;
+}
+/** GET auth-tools/status (spec 10). */
+export interface AuthStatusView {
+    enabled: boolean;
+    mode: AdminAuthMode;
+    issuer: string | null;
+    audience: string | null;
+    jwksUrl: string | null;
+    jwksCacheAgeSeconds: number | null;
+    /** Shown as scheme://host/… only. */
+    webhookUrl: string | null;
+    webhookTimeoutMs: number;
+    sharedSecretTokens: "set" | "not set";
+    jwtSecret: "set" | "not set";
+    failuresLastHour: {
+        reason: string;
+        count: number;
+    }[];
+    topFailingAddresses: {
+        address: string;
+        count: number;
+    }[];
+}
+/** POST auth-tools/test-token. */
+export interface AuthToolsTestTokenRequest {
+    token: string;
+    kind: "session" | "lobby";
+    sessionName: string | null;
+}
+/** The answer of a token test. */
+export interface TokenTestView {
+    accepted: boolean;
+    /** The verified identity; userId is null for a token that names no user (shared-secret mode). */
+    identity: {
+        userId: string | null;
+        claims: Record<string, unknown>;
+    } | null;
+    refusal: string | null;
+}
+/** POST auth-tools/reload-keys. */
+export interface AuthToolsReloadKeysView {
+    reloadedInstances: number;
+    failures: string[];
+}
+/** The alert rules (spec 11). */
+export type AlertRuleId = "instanceLost" | "instanceNotReady" | "redisUnreachable" | "refusalSpike" | "authFailureSpike" | "eventLoopLag" | "memoryHigh" | "dedicatedOverruns" | "certificateExpiring" | "versionMismatch" | "nearLimits" | "newAdminAddress" | "accountLockout";
+/** An alert rule with its settings. */
+export interface AlertRuleView {
+    ruleId: AlertRuleId;
+    label: string;
+    enabled: boolean;
+    threshold: number | null;
+    thresholdUnit: string | null;
+    forMinutes: number;
+    severity: AdminAlertSeverity;
+    channelIds: string[];
+    silencedUntil: string | null;
+    revision: number;
+}
+/** PUT alerts/rules/:ruleId. */
+export interface AlertsRulesRequest {
+    enabled: boolean;
+    threshold: number | null;
+    forMinutes: number;
+    severity: AdminAlertSeverity;
+    channelIds: string[];
+}
+/** POST alerts/rules/:ruleId/silence. */
+export interface AlertsRulesSilenceRequest {
+    minutes: number;
+}
+/** The kinds of alert channel. */
+export type AlertChannelKind = "webhook" | "slack" | "discord" | "teams" | "pagerduty";
+/** An alert channel (secrets shown as set / not set). */
+export interface AlertChannelView {
+    channelId: string;
+    kind: AlertChannelKind;
+    name: string;
+    /** Shown as scheme://host/… (path hidden). */
+    url: string | null;
+    routingKey: "set" | "not set";
+}
+/** POST alerts/channels. */
+export interface CreateAlertChannelRequest {
+    kind: AlertChannelKind;
+    name: string;
+    url: string | null;
+    routingKey: string | null;
+}
+/** POST alerts/channels/:channelId/test. */
+export interface AlertChannelTestView {
+    delivered: boolean;
+    error: string | null;
+}
+/** A fired alert. */
+export interface AlertView {
+    alertId: string;
+    ruleId: AlertRuleId;
+    severity: AdminAlertSeverity;
+    summary: string;
+    processId: string | null;
+    state: "firing" | "resolved";
+    firedAt: string;
+    resolvedAt: string | null;
+    acknowledgedBy: string | null;
+    acknowledgedAt: string | null;
+    deliveries: {
+        channelId: string;
+        ok: boolean;
+        error: string | null;
+        at: string;
+    }[];
+}
+/** A scheduled maintenance window (spec 3, Should). */
+export interface MaintenanceWindowView {
+    windowId: string;
+    startsAt: string;
+    endsAt: string;
+    message: string;
+    warningMinutes: number | null;
+    state: "scheduled" | "warning" | "active" | "done" | "cancelled";
+    createdBy: string;
+}
+/** POST maintenance/windows. */
+export interface MaintenanceWindowsRequest {
+    startsAt: string;
+    endsAt: string;
+    message: string;
+    warningMinutes: number | null;
+    allowUserIds: string[];
+    allowAddresses: string[];
+    leaveReadiness: boolean;
+}
+/** One instance's step of a rolling update. */
+export interface RolloutStepView {
+    processId: string;
+    state: "waiting" | "noticeSent" | "draining" | "replaced" | "failed";
+    replacementProcessId: string | null;
+    message: string | null;
+}
+/** A rolling update. */
+export interface RolloutView {
+    rolloutId: string;
+    state: "running" | "paused" | "done" | "cancelled" | "failed";
+    startedAt: string;
+    startedBy: string;
+    steps: RolloutStepView[];
+    message: string | null;
+}
+/** POST rollouts. */
+export interface RolloutsRequest {
+    noticeText: string | null;
+    noticeLeadSeconds: number;
+    perInstanceTimeoutMinutes: number;
+}
+/** One audit record (spec 12). */
+export interface AuditRecordView {
+    sequence: number;
+    at: string;
+    actor: {
+        kind: AdminCallerKind;
+        id: string;
+        name: string;
+    };
+    clientAddress: string | null;
+    processId: string;
+    action: string;
+    target: string | null;
+    parameters: Record<string, unknown>;
+    result: {
+        ok: boolean;
+        detail: string | null;
+    };
+    previousHash: string;
+    hash: string;
+}
+/** GET audit/verify. */
+export interface AuditVerifyView {
+    ok: boolean;
+    checked: number;
+    brokenAtSequence: number | null;
+}
+/** PUT audit/retention and its answer. */
+export interface AuditRetentionRequest {
+    days: number;
+}
+/** An activity feed item (spec 2, Should). */
+export interface ActivityItemView {
+    at: string;
+    kind: "admin" | "server";
+    text: string;
+    processId: string | null;
+}
+/** A custom action as the console sees it (spec 13). */
+export interface AdminActionView {
+    name: string;
+    label: string;
+    description: string;
+    target: AdminActionTarget;
+    fields: AdminActionField[];
+    confirm: boolean;
+}
+/** A custom panel as the console sees it. */
+export interface AdminPanelView {
+    name: string;
+    title: string;
+    placement: AdminPanelPlacement;
+}
+/** GET extensions: the actions and panels the caller may use. */
+export interface ExtensionsView {
+    actions: AdminActionView[];
+    panels: AdminPanelView[];
+}
+/** POST extensions/actions/:actionName. */
+export interface ExtensionsActionsRequest {
+    target: AdminActionTargetIds;
+    inputs: Record<string, unknown>;
+}
+/** GET docs/:documentName. */
+export interface DocsView {
+    markdown: string;
+}
+/** A COSE algorithm a passkey may use: ES256, RS256 or EdDSA. */
+export type PasskeyAlgorithm = -7 | -257 | -8;
+/** Options of navigator.credentials.create. */
+export interface PasskeyCreationOptionsView {
+    challenge: string;
+    rp: {
+        id: string;
+        name: string;
+    };
+    user: {
+        id: string;
+        name: string;
+        displayName: string;
+    };
+    pubKeyCredParams: {
+        type: "public-key";
+        alg: PasskeyAlgorithm;
+    }[];
+    timeout: number;
+    attestation: "none";
+    authenticatorSelection: {
+        residentKey: "preferred";
+        userVerification: "preferred";
+    };
+    excludeCredentials: {
+        type: "public-key";
+        id: string;
+    }[];
+}
+/** Options of navigator.credentials.get. */
+export interface PasskeyRequestOptionsView {
+    challenge: string;
+    rpId: string;
+    timeout: number;
+    userVerification: "preferred";
+    allowCredentials: {
+        type: "public-key";
+        id: string;
+    }[];
+}
+/** The result of navigator.credentials.create. */
+export interface PasskeyAttestationView {
+    id: string;
+    rawId: string;
+    type: "public-key";
+    response: {
+        clientDataJSON: string;
+        attestationObject: string;
+    };
+}
+/** The result of navigator.credentials.get. */
+export interface PasskeyAssertionView {
+    id: string;
+    rawId: string;
+    type: "public-key";
+    response: {
+        clientDataJSON: string;
+        authenticatorData: string;
+        signature: string;
+        userHandle: string | null;
+    };
+}
+/** A registered passkey. */
+export interface PasskeyView {
+    passkeyId: string;
+    name: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+/** POST auth/passkey/options. */
+export interface AuthPasskeyOptionsRequest {
+    username: string | null;
+}
+/** POST auth/passkey/verify. */
+export interface AuthPasskeyVerifyRequest {
+    pendingToken: string | null;
+    credential: PasskeyAssertionView;
+}
+/** POST account/passkeys. */
+export interface AccountPasskeysRequest {
+    name: string;
+    credential: PasskeyAttestationView;
+}
+/** A cached Colyseus Cloud resource, refreshed by the fleet leader at Colyseus's own cadence (D3, D4). */
+export type CloudResourceName = "applications" | "metricsCurrent" | "metricsDay" | "egress" | "deploys" | "billing";
+/** Resolution of the Cloud load history. */
+export type CloudHistoryResolution = "minute" | "day";
+/** Which output stream of an instance's logs to read. */
+export type CloudLogStream = "all" | "out" | "err";
+/** How many log lines to read (Colyseus rounds to these). */
+export type CloudLogLines = 100 | 500;
+/** Why a Cloud part could not be refreshed or no application could be chosen. */
+export interface CloudProblemView {
+    /** HTTP status Colyseus answered, or 0 when it did not answer or the problem is not an answer of Colyseus. */
+    status: number;
+    /** Colyseus's error code (e.g. "unauthenticated", "rate_limited") or one of ours ("unreachable", "unknown_application", "several_applications", "no_applications"). */
+    code: string;
+    /** Human-readable explanation. */
+    message: string;
+}
+/** How current a Cloud part is. */
+export interface CloudFreshnessView {
+    /** When the shown data was fetched (ISO), or null before the first success. */
+    fetchedAt: string | null;
+    /** When the last attempt ran (ISO), or null before the first. */
+    attemptedAt: string | null;
+    /** How often Colyseus refreshes this data, in seconds. */
+    refreshSeconds: number;
+    /** True when the last attempt failed or the data is older than twice its refresh interval plus a grace. */
+    isStale: boolean;
+    /** The last attempt's problem, or null when it succeeded. */
+    problem: CloudProblemView | null;
+}
+/** One part of the Cloud page: its last good data and how current it is. */
+export interface CloudPart<Data> {
+    /** The last good data, or null before the first success. */
+    data: Data | null;
+    /** How current the data is. */
+    freshness: CloudFreshnessView;
+}
+/** A Cloud instance in the application overview. */
+export interface CloudInstanceView {
+    /** Colyseus's instance id (used for logs). */
+    id: number;
+    /** Instance address, or null until it has one. */
+    endpoint: string | null;
+    /** pending, provisioning, installing, ready, error, destroying, resizing, unpaid or parked. */
+    status: string;
+    /** The deploy status values, or null. */
+    deployStatus: string | null;
+    /** When it was last deployed (ISO), or null. */
+    deployedAt: string | null;
+    /** True for the instance this console is served from (D11). */
+    isThisInstance: boolean;
+}
+/** A location's plan. */
+export interface CloudPlanView {
+    /** Virtual CPUs. */
+    vcpus: number;
+    /** Memory in megabytes. */
+    ramMegabytes: number;
+    /** Monthly transfer included per instance, in gigabytes. */
+    transferGigabytes: number;
+}
+/** A Cloud location (region) of the application. */
+export interface CloudLocationView {
+    /** Colyseus's location id. */
+    id: number;
+    /** Colyseus's region code, e.g. "fra". */
+    regionCode: string;
+    /** City of the region. */
+    city: string;
+    /** ISO country code, e.g. "DE". */
+    country: string;
+    /** Same values as an instance's status. */
+    status: string;
+    /** "vertical" (one instance) or "horizontal" (several behind a load balancer). */
+    scaleStrategy: string;
+    /** Location address, or null until it has one. */
+    endpoint: string | null;
+    /** The location's plan. */
+    plan: CloudPlanView;
+    /** The location's instances. */
+    instances: CloudInstanceView[];
+}
+/** The application this console watches. */
+export interface CloudApplicationView {
+    /** Colyseus's application id. */
+    id: number;
+    /** The slug that addresses it in the API, e.g. "1234-my-game". */
+    slug: string;
+    /** Display name. */
+    name: string;
+    /** True while maintenance mode is on in Colyseus's dashboard. */
+    maintenanceMode: boolean;
+    /** Creation time (ISO). */
+    createdAt: string;
+    /** The application's locations. */
+    locations: CloudLocationView[];
+}
+/** Load totals: players and rooms summed, CPU and memory of the busiest instance (Colyseus's rule). */
+export interface CloudLoadTotalsView {
+    /** Connected players (CCU). */
+    players: number;
+    /** Open rooms. */
+    rooms: number;
+    /** CPU use, 0–100. */
+    cpuPercent: number;
+    /** Memory use of the plan's RAM, 0–100. */
+    memoryPercent: number;
+}
+/** A server process on a Cloud instance. */
+export interface CloudProcessView {
+    /** The process manager's process number. */
+    id: number;
+    /** online, launching, stopping, stopped, waiting restart or errored. */
+    status: string;
+    /** Start time (ISO), or null. */
+    startedAt: string | null;
+    /** The process manager's restart counter. */
+    restarts: number;
+    /** CPU use, 0–100. */
+    cpuPercent: number;
+    /** Resident memory in megabytes. */
+    memoryMegabytes: number;
+    /** Connected players. */
+    players: number;
+    /** Open rooms. */
+    rooms: number;
+    /** Node.js version, e.g. "24.1.0". */
+    nodeVersion: string;
+}
+/** A Cloud instance's latest sample. */
+export interface CloudInstanceLoadView {
+    /** Colyseus's instance id. */
+    id: number;
+    /** When it reported (ISO), or null. */
+    sampledAt: string | null;
+    /** True when the instance has not reported within Colyseus's window (its values are null). */
+    isSilent: boolean;
+    /** Connected players, or null when silent. */
+    players: number | null;
+    /** Open rooms, or null when silent. */
+    rooms: number | null;
+    /** CPU use 0–100, or null when silent. */
+    cpuPercent: number | null;
+    /** Memory use 0–100, or null when silent. */
+    memoryPercent: number | null;
+    /** The instance's processes (empty when silent). */
+    processes: CloudProcessView[];
+}
+/** One location's current load. */
+export interface CloudLocationLoadView {
+    /** Colyseus's location id. */
+    id: number;
+    /** Colyseus's region code. */
+    regionCode: string;
+    /** Null when every instance of the location is silent. */
+    totals: CloudLoadTotalsView | null;
+    /** The location's instances. */
+    instances: CloudInstanceLoadView[];
+}
+/** The application's current load. */
+export interface CloudLoadView {
+    /** Minutes after which a silent instance's values become null. */
+    windowMinutes: number;
+    /** Per location. */
+    locations: CloudLocationLoadView[];
+    /** Every location together (same rule), or null when all are silent. */
+    totals: CloudLoadTotalsView | null;
+}
+/** One history point of a location. */
+export interface CloudHistoryPointView {
+    /** Point time (ISO). */
+    time: string;
+    /** Players (CCU). */
+    players: number;
+    /** Rooms. */
+    rooms: number;
+    /** CPU use, 0–100. */
+    cpuPercent: number;
+    /** Memory use, 0–100. */
+    memoryPercent: number;
+}
+/** One location's history. */
+export interface CloudLocationHistoryView {
+    /** Colyseus's location id. */
+    id: number;
+    /** Colyseus's region code. */
+    regionCode: string;
+    /** Points, oldest first. */
+    points: CloudHistoryPointView[];
+}
+/** The application's load history at one resolution. */
+export interface CloudHistoryView {
+    /** "minute" (last 24 h) or "day" (last 30 days). */
+    resolution: CloudHistoryResolution;
+    /** Window start (ISO). */
+    from: string;
+    /** Window end (ISO, inclusive). */
+    to: string;
+    /** Per location. */
+    locations: CloudLocationHistoryView[];
+}
+/** One day of a location's traffic. */
+export interface CloudEgressDayView {
+    /** YYYY-MM-DD. */
+    date: string;
+    /** Bytes sent. */
+    outgoingBytes: number;
+    /** Bytes received. */
+    incomingBytes: number;
+}
+/** One location's traffic. */
+export interface CloudLocationEgressView {
+    /** Colyseus's location id. */
+    id: number;
+    /** Colyseus's region code. */
+    regionCode: string;
+    /** Bytes sent in the window. */
+    outgoingBytes: number;
+    /** Bytes received in the window. */
+    incomingBytes: number;
+    /** Per day. */
+    days: CloudEgressDayView[];
+}
+/** The application's traffic over the last 30 days. */
+export interface CloudEgressView {
+    /** YYYY-MM-DD. */
+    from: string;
+    /** YYYY-MM-DD. */
+    to: string;
+    /** When Colyseus last copied the figures (ISO), or null before the first copy. */
+    collectedAt: string | null;
+    /** Per location. */
+    locations: CloudLocationEgressView[];
+}
+/** A deploy of the application. */
+export interface CloudDeployView {
+    /** Colyseus's deploy id. */
+    id: number;
+    /** none, enqueued, deploying, deployed or failed. */
+    status: string;
+    /** Deployed branch. */
+    branch: string;
+    /** Short commit hash, or null until the code is fetched. */
+    commit: string | null;
+    /** Commit message, or null until the code is fetched. */
+    message: string | null;
+    /** When it was triggered (ISO). */
+    startedAt: string;
+    /** When it ended (ISO), or null while running. */
+    finishedAt: string | null;
+}
+/** GET cloud/deploys/:deployId: a deploy with its build output (D10). */
+export interface CloudDeployDetailView extends CloudDeployView {
+    /** Build and deploy output as plain text, or null once Colyseus no longer keeps it. */
+    output: string | null;
+}
+/** The application's subscription. */
+export interface CloudSubscriptionView {
+    /** active, past_due, unpaid, incomplete, incomplete_expired, trialing or canceled. */
+    status: string;
+    /** List price per month, in the account currency's units (not cents). */
+    monthlyPrice: number;
+    /** End of the current period (ISO). */
+    currentPeriodEnd: string;
+    /** True when the subscription ends at the period end. */
+    cancelAtPeriodEnd: boolean;
+}
+/** The team owner's billing account (shared with any other team they own). */
+export interface CloudAccountView {
+    /** Lower-case ISO currency code, e.g. "usd". */
+    currency: string;
+    /** Prepaid credit that pays future invoices. */
+    creditBalance: number;
+    /** Owed, added to the next invoice. */
+    balanceDue: number;
+    /** Credit from downgrades and cancellations. */
+    unusedTimeCredit: number;
+}
+/** GET cloud/billing data. */
+export interface CloudBillingView {
+    /** Null when the team owner has no billing account yet. */
+    account: CloudAccountView | null;
+    /** Null when the application has no subscription. */
+    subscription: CloudSubscriptionView | null;
+    /** When Colyseus read the billing figures (ISO). */
+    fetchedAt: string;
+}
+/** GET cloud: everything the page shows except history, billing, deploy output and logs. */
+export interface ColyseusCloudView {
+    /** Whether the page applies (D8). */
+    feature: ColyseusCloudFeature;
+    /** The team's application slugs when several exist and none is configured (D9); otherwise empty. */
+    applicationChoices: string[];
+    /** Why no application is shown (token refused, unknown slug, several or no applications), or null. */
+    setupProblem: CloudProblemView | null;
+    /** The application and its locations. */
+    overview: CloudPart<CloudApplicationView>;
+    /** Current load. */
+    load: CloudPart<CloudLoadView>;
+    /** Recent deploys, newest first. */
+    deploys: CloudPart<CloudDeployView[]>;
+    /** Traffic of the last 30 days. */
+    egress: CloudPart<CloudEgressView>;
+}
+/** GET cloud/instances/:instanceId/logs answer (D5, D10). */
+export interface CloudLogsView {
+    /** Colyseus's instance id. */
+    instanceId: number;
+    /** The stream read. */
+    stream: CloudLogStream;
+    /** The number of lines asked for. */
+    lines: CloudLogLines;
+    /** The newest log lines, colour codes stripped by Colyseus. */
+    text: string;
+    /** When they were read (ISO). */
+    fetchedAt: string;
+    /** True when this answer is another request's from the last minute (the limit allowed no new one). */
+    isShared: boolean;
+    /** When the next log request is allowed (ISO). */
+    nextAllowedAt: string;
+}
+/** Which scores rank first: "lowerIsBetter" for times, "higherIsBetter" for points and counters. */
+export type LeaderboardSortOrder = "higherIsBetter" | "lowerIsBetter";
+/** How a score is shown: a plain integer, milliseconds shown as a time, or points. Scores are integers (D12). */
+export type LeaderboardScoreFormat = "integer" | "timeMilliseconds" | "points";
+/** What a new score does to a player's entry: keep the best, keep the latest, or add to a running total (D14). */
+export type LeaderboardKeepPolicy = "best" | "latest" | "sum";
+/** How far a submission can be trusted (D9): signed by the game client, confirmed by session presence, or sent by a server API key. */
+export type LeaderboardTrustLevel = "client" | "session" | "server";
+/** Whether game clients can read and submit to a board. */
+export type LeaderboardVisibility = "public" | "hidden";
+/** When a board's season resets by itself (UTC, D17); "manual" resets only from the console, "never" not at all. */
+export type LeaderboardResetSchedule = "never" | "manual" | "daily" | "weekly" | "monthly";
+/** Why a request or one score was refused. */
+export type LeaderboardRefusalReason = "invalidRequest" | "authRequired" | "authRefused" | "banned" | "invalidPlayer" | "rateLimited" | "tooManyScores" | "unknownBoard" | "variantNotAllowed" | "scoreNotInteger" | "scoreOutOfRange" | "trustLevelNotAccepted" | "implausibleDuration" | "metadataTooLarge" | "nameInvalid" | "nameBlocked" | "nameManaged" | "signInRequired";
+/** What a write did to the player's stored entry (D14). */
+export type LeaderboardWriteOutcome = "created" | "improved" | "replaced" | "added" | "kept";
+/** A JSON value allowed in entry metadata (display-only details next to a score). */
+export type LeaderboardMetadataValue = string | number | boolean | null | LeaderboardMetadataValue[] | {
+    [key: string]: LeaderboardMetadataValue;
+};
+/** Free-form, size-capped details stored with an entry; never ranked or queried. */
+export type LeaderboardMetadata = {
+    [key: string]: LeaderboardMetadataValue;
+};
+/** One way a board's rankings are split (a "map", a "difficulty"), with the values a submission may use (D16). */
+export interface LeaderboardVariantDimension {
+    /** Key in a submission's variant object. */
+    name: string;
+    /** Label shown in the console and in games. */
+    label: string;
+    /** Allowed values, in display order. */
+    values: string[];
+}
+/** Everything an admin defines about a board. */
+export interface LeaderboardBoardDefinition {
+    /** Stable id, `/^[a-z0-9][a-z0-9-]{0,63}$/`. */
+    boardId: string;
+    /** Name shown to players and admins (1–80 characters). */
+    displayName: string;
+    /** What the board ranks (0–500 characters). */
+    description: string;
+    sortOrder: LeaderboardSortOrder;
+    scoreFormat: LeaderboardScoreFormat;
+    keepPolicy: LeaderboardKeepPolicy;
+    /** Smallest score one submission may carry, or null for no limit. */
+    minimumScore: number | null;
+    /** Largest score one submission may carry, or null for no limit. */
+    maximumScore: number | null;
+    /** Trust levels the board accepts (at least one). */
+    acceptedTrustLevels: LeaderboardTrustLevel[];
+    visibility: LeaderboardVisibility;
+    resetSchedule: LeaderboardResetSchedule;
+    /** Ranking splits; empty for a single ranking. */
+    dimensions: LeaderboardVariantDimension[];
+}
+/** One season of a board. */
+export interface LeaderboardSeasonView {
+    /** 1, 2, 3 … */
+    seasonId: number;
+    /** ISO start. */
+    startedAt: string;
+    /** ISO end, or null for the current season. */
+    endedAt: string | null;
+    isCurrent: boolean;
+}
+/** A board as game clients see it. */
+export interface LeaderboardPublicBoardView {
+    boardId: string;
+    displayName: string;
+    description: string;
+    sortOrder: LeaderboardSortOrder;
+    scoreFormat: LeaderboardScoreFormat;
+    keepPolicy: LeaderboardKeepPolicy;
+    dimensions: LeaderboardVariantDimension[];
+    currentSeasonId: number;
+    currentSeasonStartedAt: string;
+    /** ISO time of the next scheduled reset, or null. */
+    nextResetAt: string | null;
+}
+/** One ranked entry. */
+export interface LeaderboardEntryView {
+    /** 1-based rank in its ranking. */
+    rank: number;
+    playerId: string;
+    /** The name the player had when the entry was written (console renames update it). */
+    displayName: string;
+    /** The player's avatar claim (a Discord avatar hash for user:discord: players), filled on public reads; absent or null otherwise. */
+    avatar?: string | null;
+    score: number;
+    metadata: LeaderboardMetadata | null;
+    trustLevel: LeaderboardTrustLevel;
+    /** ISO time of the last accepted submission. */
+    submittedAt: string;
+    /** ISO time the stored score was reached (tie-break, D13). */
+    achievedAt: string;
+}
+/** A page of one ranking. */
+export interface LeaderboardEntriesPage {
+    boardId: string;
+    seasonId: number;
+    variantKey: string;
+    /** Entries in the ranking. */
+    total: number;
+    /** Zero-based index of the first entry. */
+    offset: number;
+    entries: LeaderboardEntryView[];
+}
+/** A window around one player; `playerRank` is null when the player has no entry. */
+export interface LeaderboardAroundPage extends LeaderboardEntriesPage {
+    playerRank: number | null;
+}
+/** A player as games see them. */
+export interface LeaderboardPlayerView {
+    playerId: string;
+    displayName: string;
+    kind: "anonymous" | "user" | "manual";
+    createdAt: string;
+}
+/** The answer to POST players: the player and, only when it was just created anonymously, its one-time key. */
+export interface LeaderboardPlayerSession {
+    player: LeaderboardPlayerView;
+    playerKey: string | null;
+}
+/** One score in a submission. */
+export interface LeaderboardScoreSubmission {
+    boardId: string;
+    /** Dimension values; null or {} for a board without dimensions. */
+    variant: Record<string, string> | null;
+    score: number;
+    metadata: LeaderboardMetadata | null;
+}
+/** POST submissions: the envelope every game sends at a key stage (spec D13). */
+export interface LeaderboardSubmissionRequest {
+    /** The anonymous player's key, or omitted for an auth user. */
+    playerKey?: string;
+    /** Client-made unique id, 8–64 of `[A-Za-z0-9-]` (exactly-once, D15). */
+    submissionId: string;
+    /** The game's mode name, at most 64 characters, or null. */
+    gameMode: string | null;
+    /** The game's build version, at most 64 characters, or null. */
+    buildVersion: string | null;
+    /** The network session name when the scores come from a network game, or null. */
+    sessionName: string | null;
+    /** How long the run lasted, in milliseconds, or null. */
+    durationMs: number | null;
+    /** The client's ISO clock (informational only; the server stamps its own time). */
+    clientTime: string | null;
+    /** 1–maximumScoresPerSubmission scores. */
+    scores: LeaderboardScoreSubmission[];
+}
+/** What happened to one score. */
+export interface LeaderboardScoreResult {
+    boardId: string;
+    variantKey: string | null;
+    status: "accepted" | "duplicate" | "refused";
+    outcome: LeaderboardWriteOutcome | null;
+    /** The stored score after the keep policy, or null when refused. */
+    score: number | null;
+    previousScore: number | null;
+    /** True when this submission created or improved the player's entry (or changed a latest/sum entry). */
+    isPersonalBest: boolean;
+    rank: number | null;
+    total: number | null;
+    seasonId: number | null;
+    trustLevel: LeaderboardTrustLevel | null;
+    refusal: LeaderboardRefusalReason | null;
+}
+/** The answer to POST submissions. */
+export interface LeaderboardSubmissionResponse {
+    submissionId: string;
+    playerId: string;
+    results: LeaderboardScoreResult[];
+}
+/** One ranking a player asks about. */
+export interface LeaderboardTarget {
+    boardId: string;
+    variant: Record<string, string> | null;
+    /** A season, or omitted for the current one. */
+    seasonId?: number;
+}
+/** A player's entry in one ranking (null when they have none). */
+export interface LeaderboardTargetEntry {
+    boardId: string;
+    variantKey: string;
+    seasonId: number;
+    total: number;
+    entry: LeaderboardEntryView | null;
+}
+/** The error body of a refused public request. */
+export interface LeaderboardErrorBody {
+    error: string;
+    reason: LeaderboardRefusalReason;
+}
+/** Console-editable abuse limits and name rules (D19). */
+export interface LeaderboardRules {
+    submissionsPerMinutePerPlayer: number;
+    submissionsPerMinutePerAddress: number;
+    readsPerMinutePerAddress: number;
+    identitiesPerHourPerAddress: number;
+    maximumScoresPerSubmission: number;
+    metadataMaximumBytes: number;
+    /** Lower-case words a display name may not contain. */
+    blockedWords: string[];
+}
+/** GET leaderboards/rules. */
+export interface LeaderboardRulesView {
+    rules: LeaderboardRules;
+    defaults: LeaderboardRules;
+    revision: number;
+}
+/** A board in the console's list. */
+export interface LeaderboardBoardSummaryView {
+    definition: LeaderboardBoardDefinition;
+    revision: number;
+    currentSeasonId: number;
+    seasons: LeaderboardSeasonView[];
+    nextResetAt: string | null;
+    /** Live entries of the current season, all variants. */
+    entryCount: number;
+    /** ISO time of the last accepted score, or null. */
+    lastSubmissionAt: string | null;
+}
+/** One variant of a board in its detail view. */
+export interface LeaderboardVariantSummaryView {
+    variantKey: string;
+    values: Record<string, string>;
+    entryCount: number;
+    topEntry: LeaderboardEntryView | null;
+}
+/** GET leaderboards/boards/:boardId. */
+export interface LeaderboardBoardDetailView {
+    summary: LeaderboardBoardSummaryView;
+    seasonId: number;
+    variants: LeaderboardVariantSummaryView[];
+}
+/** An entry a moderator removed or a hidden player's entry. */
+export interface LeaderboardRemovedEntryView {
+    entry: LeaderboardEntryView;
+    reason: string;
+    removedBy: string;
+    removedAt: string;
+}
+/** A player in the console. */
+export interface LeaderboardPlayerAdminView {
+    playerId: string;
+    displayName: string;
+    kind: "anonymous" | "user" | "manual";
+    hidden: boolean;
+    createdAt: string;
+    lastSeenAt: string;
+}
+/** One of a player's entries across boards. */
+export interface LeaderboardPlayerEntryView {
+    boardId: string;
+    boardName: string;
+    scoreFormat: LeaderboardScoreFormat;
+    seasonId: number;
+    isCurrentSeason: boolean;
+    variantKey: string;
+    rank: number | null;
+    total: number;
+    score: number;
+    removedReason: string | null;
+}
+/** GET leaderboards/players/:playerId. */
+export interface LeaderboardPlayerDetailView {
+    player: LeaderboardPlayerAdminView;
+    entries: LeaderboardPlayerEntryView[];
+}
+/** One activity record (D21). */
+export interface LeaderboardActivityView {
+    sequence: number;
+    at: string;
+    kind: "accepted" | "duplicate" | "refused";
+    boardId: string | null;
+    variantKey: string | null;
+    playerId: string | null;
+    displayName: string | null;
+    score: number | null;
+    outcome: LeaderboardWriteOutcome | null;
+    reason: LeaderboardRefusalReason | null;
+    trustLevel: LeaderboardTrustLevel | null;
+    gameMode: string | null;
+    /** Empty unless the caller holds players.viewAddresses. */
+    clientAddress: string;
+}
+/** GET leaderboards/status. */
+export interface LeaderboardStatusView {
+    storage: "redis" | "files";
+    durability: "durable" | "notDurable" | "unknown";
+    /** What to configure when not durable or unknown, else null. */
+    durabilityAdvice: string | null;
+    /** The definitions-file problem found at start, or null. */
+    definitionsProblem: string | null;
+    boardCount: number;
+    acceptedPerMinute: number;
+    refusedPerMinute: number;
+}
+/** The startup definitions file (D11) and a console definitions import. */
+export interface LeaderboardDefinitionsFile {
+    format: "babylon-game-server-leaderboard-definitions";
+    version: 1;
+    boards: LeaderboardBoardDefinition[];
+}
+/** One exported entry. */
+export interface LeaderboardExportEntry {
+    seasonId: number;
+    variantKey: string;
+    playerId: string;
+    displayName: string;
+    score: number;
+    metadata: LeaderboardMetadata | null;
+    trustLevel: LeaderboardTrustLevel;
+    sessionName: string | null;
+    submittedAt: string;
+    achievedAt: string;
+    submissionCount: number;
+    /** The removal reason, or null for a live entry. */
+    removedReason: string | null;
+    /** Who removed it, or null for a live entry. */
+    removedBy: string | null;
+    /** ISO time it was removed, or null for a live entry. */
+    removedAt: string | null;
+}
+/** One exported player (keyHash keeps anonymous players' keys working after a restore). */
+export interface LeaderboardExportPlayer {
+    playerId: string;
+    displayName: string;
+    kind: "anonymous" | "user" | "manual";
+    keyHash: string | null;
+    hidden: boolean;
+    createdAt: string;
+}
+/** One exported board. */
+export interface LeaderboardExportBoard {
+    definition: LeaderboardBoardDefinition;
+    currentSeasonId: number;
+    seasons: LeaderboardSeasonView[];
+    entries: LeaderboardExportEntry[];
+}
+/** GET leaderboards/export?format=json: a full or partial backup. */
+export interface LeaderboardExportFile {
+    format: "babylon-game-server-leaderboards";
+    version: 1;
+    exportedAt: string;
+    boards: LeaderboardExportBoard[];
+    players: LeaderboardExportPlayer[];
+}
+/** POST leaderboards/import body. */
+export interface LeaderboardImportRequest {
+    file: LeaderboardExportFile | LeaderboardDefinitionsFile;
+    conflictPolicy: "skip" | "replace";
+    dryRun: boolean;
+}
+/** POST leaderboards/import answer (the preview when dryRun). */
+export interface LeaderboardImportResult {
+    dryRun: boolean;
+    boardsCreated: string[];
+    boardsReplaced: string[];
+    boardsSkipped: string[];
+    entriesWritten: number;
+    playersWritten: number;
+}