theref-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+type NetworkId = "bradbury" | "studionet";
+interface NetworkConfig {
+    id: NetworkId;
+    rpc: string;
+    chainId: number;
+    addresses: ContractAddresses;
+}
+interface ContractAddresses {
+    CORE: string;
+    LB: string;
+    ORG: string;
+    FEE: string;
+    TRN: string;
+}
+interface TheRefConfig {
+    network: NetworkId | NetworkConfig;
+    privateKey?: `0x${string}`;
+    walletAddress?: `0x${string}`;
+    wsUrl?: string;
+    retries?: number;
+    pollInterval?: number;
+}
+type GameStatus = "waiting" | "active" | "completed" | "draw";
+type PlayerType = "human" | "agent";
+interface CreateGameOptions {
+    name: string;
+    rules?: string;
+    player1: string;
+    player2?: string;
+    maxRounds?: number;
+    visibility?: "public" | "private";
+    agent1?: `0x${string}`;
+    agent2?: `0x${string}`;
+}
+interface GameState {
+    gameId: string;
+    gameName: string;
+    status: GameStatus;
+    player1: string;
+    player2: string;
+    agent1: string;
+    agent2: string;
+    maxRounds: number;
+    roundCount: number;
+    judgedThrough: number;
+    rules: string;
+    winner: string;
+    score: Record<string, number>;
+    playerTypes: Record<string, PlayerType>;
+    rounds: RoundResult[];
+    caller: string;
+}
+interface RoundResult {
+    roundNumber: number;
+    movePlayer1: string;
+    movePlayer2: string;
+    result: "player1" | "player2" | "draw" | "pending";
+    reasonType: "normal" | "invalid_move";
+    invalidPlayer: "none" | "player1" | "player2";
+    reasoning: string;
+    confidence: number;
+    status: string;
+}
+interface JudgmentResult {
+    winner: string;
+    isDraw: boolean;
+    score: Record<string, number>;
+    rounds: RoundResult[];
+    txHash: string;
+    payload: string;
+}
+type AnyMove = string | number | boolean | AnyMove[] | {
+    [key: string]: AnyMove;
+};
+interface NormalizedMove {
+    raw: AnyMove;
+    text: string;
+    adapter: string;
+}
+interface CreateTournamentOptions {
+    name: string;
+    gameName: string;
+    format: "single_elimination" | "round_robin" | "swiss";
+    maxPlayers: number;
+    rules?: string;
+    roundsPerMatch?: number;
+    prizeSplit?: number[];
+}
+interface Tournament {
+    tid: string;
+    name: string;
+    gameName: string;
+    format: string;
+    maxPlayers: number;
+    status: string;
+    players: string[];
+    bracket: BracketMatch[];
+    winner: string;
+}
+interface BracketMatch {
+    matchId: number;
+    round: number;
+    player1: string;
+    player2: string;
+    gameId: string;
+    winner: string;
+    status: string;
+}
+interface LeaderboardEntry {
+    player: string;
+    wins: number;
+    losses: number;
+    draws: number;
+    score: number;
+    playerType: PlayerType;
+}
+interface PlayerStats extends LeaderboardEntry {
+    games: number;
+}
+
+declare class TheRefClient {
+    private network;
+    private glClient;
+    private retries;
+    private pollInterval;
+    private wsUrl;
+    constructor(config: TheRefConfig);
+    private write;
+    private read;
+    private get CORE();
+    private get LB();
+    private get TRN();
+    private mapGameState;
+    /**
+     * Create a new game. Returns the game ID.
+     */
+    createGame(options: CreateGameOptions): Promise<string>;
+    /**
+     * Submit a move for a player. Accepts ANY move format — string, object, array, etc.
+     * The SDK automatically normalizes it to a string the AI judge can understand.
+     */
+    submitMove(gameId: string, playerName: string, move: AnyMove, gameHint?: string): Promise<{
+        txHash: string;
+        normalizedMove: string;
+    }>;
+    /**
+     * Judge the game — triggers AI consensus on all pending rounds.
+     */
+    judgeGame(gameId: string): Promise<JudgmentResult>;
+    /**
+     * End an open-ended game (max_rounds = 0). Only callable by the game creator.
+     */
+    endGame(gameId: string): Promise<JudgmentResult>;
+    /**
+     * Get the full game state.
+     */
+    getGameState(gameId: string): Promise<GameState>;
+    /**
+     * Get all active games.
+     */
+    getActiveGames(): Promise<GameState[]>;
+    /**
+     * Get total number of games.
+     */
+    getTotalGames(): Promise<number>;
+    /**
+     * Wait until both players have submitted their move for a given round.
+     * Polls every `pollInterval` ms.
+     */
+    waitForBothMoves(gameId: string, roundNumber: number): Promise<RoundResult>;
+    /**
+     * Wait until the opponent has submitted their move for a round.
+     * isPlayer1: true if you are player1, false if player2.
+     */
+    waitForOpponentMove(gameId: string, roundNumber: number, isPlayer1: boolean): Promise<string>;
+    /**
+     * Wait until the game reaches a specific status.
+     */
+    waitForStatus(gameId: string, status: GameStatus): Promise<GameState>;
+    /**
+     * Play a full game automatically.
+     * moveFn is called for each round — return your move in any format.
+     */
+    playGame(gameId: string, playerName: string, isPlayer1: boolean, moveFn: (state: GameState, round: number) => Promise<AnyMove>, gameHint?: string): Promise<JudgmentResult>;
+    getLeaderboard(gameName: string, playerType?: PlayerType | "all"): Promise<LeaderboardEntry[]>;
+    getTopPlayers(gameName: string, n?: number): Promise<LeaderboardEntry[]>;
+    getPlayerStats(gameName: string, playerName: string, playerType?: PlayerType | "all"): Promise<PlayerStats | null>;
+    createTournament(options: CreateTournamentOptions): Promise<string>;
+    joinTournament(tid: string, playerName: string, playerType?: PlayerType): Promise<void>;
+    startTournament(tid: string): Promise<void>;
+    getTournament(tid: string): Promise<Tournament | null>;
+    listTournaments(): Promise<Tournament[]>;
+    recordMatchResult(tid: string, matchId: number, winner: string): Promise<void>;
+    /** Normalize any move to a string without submitting */
+    normalizeMove(move: AnyMove, gameHint?: string): NormalizedMove;
+    /** Sleep helper */
+    private sleep;
+}
+
+declare function normalizeMove(move: AnyMove, gameHint?: string): NormalizedMove;
+
+declare const NETWORKS: Record<NetworkId, NetworkConfig>;
+declare function resolveNetwork(network: NetworkId | NetworkConfig): NetworkConfig;
+declare function gidToNum(gid: string): number;
+
+/**
+ * Create a TheRef client.
+ *
+ * @example
+ * // Agent (server-side)
+ * const ref = createTheRef({
+ *   network: "bradbury",
+ *   privateKey: process.env.AGENT_KEY as `0x${string}`,
+ * });
+ *
+ * @example
+ * // Browser wallet
+ * const ref = createTheRef({
+ *   network: "bradbury",
+ *   walletAddress: "0xYourWallet",
+ * });
+ *
+ * @example
+ * // Development (Studionet, no key needed)
+ * const ref = createTheRef({ network: "studionet" });
+ */
+declare function createTheRef(config: TheRefConfig): TheRefClient;
+
+export { type AnyMove, type BracketMatch, type ContractAddresses, type CreateGameOptions, type CreateTournamentOptions, type GameState, type GameStatus, type JudgmentResult, type LeaderboardEntry, NETWORKS, type NetworkConfig, type NetworkId, type NormalizedMove, type PlayerStats, type PlayerType, type RoundResult, TheRefClient, type TheRefConfig, type Tournament, createTheRef, gidToNum, normalizeMove, resolveNetwork };