import type { GameModelAPI } from '../domains/gameModel.js';
import type { EngineDetector } from './engine.js';
import type { Scalars } from '../generated/graphql.js';
import { type KitInvokeResult } from './shared.js';
/** Options for {@link LeaderboardsKit}. Must match the deployed blueprint. */
export interface LeaderboardsKitOptions {
    /** The board engine module for server-computed rankings. Defaults to `'board-engine'`. */
    engineModuleName?: string;
    /** The `typePrefix` the leaderboards blueprint was deployed with. */
    typePrefix?: string;
}
/** A parsed view of one leaderboard entry. */
export interface KitLeaderboardEntry {
    containerId: string;
    displayName: string;
    ownerUserId: string | null;
    boardId: string;
    score: number;
    season: number;
    /** 1-based position AFTER client-side sorting (not the stamped `rank` property). */
    position: number;
}
/**
 * Runtime helpers for the {@link leaderboardsBlueprint} conventions: ensure
 * per-player entries, submit scores (trusted — host by default), and rank.
 * There is no server-side ORDER BY on container lists, so reads fetch a
 * board's entries and sort client-side — fine for the few hundred entries a
 * per-app board holds.
 *
 * Obtained via `client.kit(appId).leaderboards`.
 */
export declare class LeaderboardsKit {
    private readonly appId;
    private readonly gameModel;
    private readonly engines?;
    private readonly names;
    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: LeaderboardsKitOptions, engines?: EngineDetector | undefined);
    private readonly engineModuleName;
    /**
     * Is a board compute engine deployed + enabled (cached per session)? When
     * true, rankings are computed SERVER-side (tie-aware ranks, percentiles,
     * pages) instead of the blueprint's client-sorted reads.
     */
    engineAvailable(): Promise<boolean>;
    /** A server-ranked page (rank/percentile computed module-side). */
    engineTop(boardId: string, page?: number, perPage?: number): Promise<Record<string, unknown>>;
    /** Your (or a subject's) server-computed ranked row. */
    engineRankOf(boardId: string, subjectId?: string): Promise<Record<string, unknown>>;
    /** Submit YOUR OWN score (personal-best semantics) to an engine board. */
    engineSubmitSelf(boardId: string, score: number): Promise<Record<string, unknown>>;
    /** Frozen season snapshots (top rows per rolled season). */
    engineSeasons(boardId: string): Promise<Record<string, unknown>>;
    private engineInvoke;
    /** Find-or-create a player's entry on a board. */
    ensureEntry(ownerUserId: Scalars['BigInt']['input'], boardId: string, options?: {
        displayName?: string;
    }): Promise<{
        __typename?: "GmContainer";
        containerId: string;
        appId: string;
        sessionId: string | null;
        typeName: string;
        displayName: string;
        description: string | null;
        ownerUserId: string | null;
        metadataJson: string;
    }>;
    /**
     * Submit a score — a **trusted** call (host by default per the blueprint's
     * `submitAuthority`). Resolves with the entry's (possibly kept-best)
     * score.
     */
    submit(entryId: string, points: number): Promise<KitInvokeResult<number>>;
    /** All entries of one board, sorted best-first with 1-based positions. */
    board(boardId: string): Promise<KitLeaderboardEntry[]>;
    /** The top `n` of a board (client-side ranking). */
    top(boardId: string, n?: number): Promise<KitLeaderboardEntry[]>;
    /**
     * The entries around one player on a board (`radius` above and below),
     * for "your neighborhood" widgets.
     */
    around(boardId: string, userId: Scalars['BigInt']['input'], radius?: number): Promise<KitLeaderboardEntry[]>;
    /** The board's current season (max season across its entries; 1 when empty). */
    season(boardId: string): Promise<number>;
}
//# sourceMappingURL=leaderboards.d.ts.map