theref-sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,56 @@
+export { TheRefClient } from "./client/TheRefClient";
+export { normalizeMove } from "./adapters/normalizer";
+export { NETWORKS, resolveNetwork, gidToNum } from "./utils/networks";
+export type {
+  // Config
+  TheRefConfig,
+  NetworkId,
+  NetworkConfig,
+  ContractAddresses,
+  // Game
+  CreateGameOptions,
+  GameState,
+  GameStatus,
+  RoundResult,
+  JudgmentResult,
+  PlayerType,
+  // Move
+  AnyMove,
+  NormalizedMove,
+  // Tournament
+  CreateTournamentOptions,
+  Tournament,
+  BracketMatch,
+  // Leaderboard
+  LeaderboardEntry,
+  PlayerStats,
+} from "./types";
+
+// Convenience factory function
+import { TheRefClient } from "./client/TheRefClient";
+import { TheRefConfig } from "./types";
+
+/**
+ * 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" });
+ */
+export function createTheRef(config: TheRefConfig): TheRefClient {
+  return new TheRefClient(config);
+}

package/src/types/index.ts

@@ -0,0 +1,149 @@
+// ── Network ───────────────────────────────────────────────────────────────────
+
+export type NetworkId = "bradbury" | "studionet";
+
+export interface NetworkConfig {
+  id:        NetworkId;
+  rpc:       string;
+  chainId:   number;
+  addresses: ContractAddresses;
+}
+
+export interface ContractAddresses {
+  CORE: string;
+  LB:   string;
+  ORG:  string;
+  FEE:  string;
+  TRN:  string;
+}
+
+// ── TheRef Client Config ──────────────────────────────────────────────────────
+
+export interface TheRefConfig {
+  network:       NetworkId | NetworkConfig;
+  privateKey?:   `0x${string}`;    // for agents / server-side
+  walletAddress?: `0x${string}`;   // for browser wallets
+  wsUrl?:        string;            // WebSocket URL (default: wss://ws.theref.fun)
+  retries?:      number;            // tx retries (default: 300)
+  pollInterval?: number;            // ms between polls (default: 5000)
+}
+
+// ── Game ─────────────────────────────────────────────────────────────────────
+
+export type GameStatus = "waiting" | "active" | "completed" | "draw";
+export type PlayerType = "human" | "agent";
+
+export interface CreateGameOptions {
+  name:        string;
+  rules?:      string;
+  player1:     string;
+  player2?:    string;
+  maxRounds?:  number;
+  visibility?: "public" | "private";
+  agent1?:     `0x${string}`;
+  agent2?:     `0x${string}`;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export interface JudgmentResult {
+  winner:  string;
+  isDraw:  boolean;
+  score:   Record<string, number>;
+  rounds:  RoundResult[];
+  txHash:  string;
+  payload: string;
+}
+
+// ── Move ─────────────────────────────────────────────────────────────────────
+
+export type AnyMove =
+  | string
+  | number
+  | boolean
+  | AnyMove[]
+  | { [key: string]: AnyMove };
+
+export interface NormalizedMove {
+  raw:     AnyMove;
+  text:    string;
+  adapter: string;
+}
+
+// ── Tournament ────────────────────────────────────────────────────────────────
+
+export interface CreateTournamentOptions {
+  name:            string;
+  gameName:        string;
+  format:          "single_elimination" | "round_robin" | "swiss";
+  maxPlayers:      number;
+  rules?:          string;
+  roundsPerMatch?: number;
+  prizeSplit?:     number[];
+}
+
+export interface Tournament {
+  tid:        string;
+  name:       string;
+  gameName:   string;
+  format:     string;
+  maxPlayers: number;
+  status:     string;
+  players:    string[];
+  bracket:    BracketMatch[];
+  winner:     string;
+}
+
+export interface BracketMatch {
+  matchId: number;
+  round:   number;
+  player1: string;
+  player2: string;
+  gameId:  string;
+  winner:  string;
+  status:  string;
+}
+
+// ── Leaderboard ───────────────────────────────────────────────────────────────
+
+export interface LeaderboardEntry {
+  player:     string;
+  wins:       number;
+  losses:     number;
+  draws:      number;
+  score:      number;
+  playerType: PlayerType;
+}
+
+export interface PlayerStats extends LeaderboardEntry {
+  games: number;
+}

package/src/utils/networks.ts

@@ -0,0 +1,39 @@
+import { NetworkConfig, NetworkId } from "../types";
+
+export const NETWORKS: Record<NetworkId, NetworkConfig> = {
+  bradbury: {
+    id:      "bradbury",
+    rpc:     "https://rpc-bradbury.genlayer.com",
+    chainId: 4221,
+    addresses: {
+      CORE: "0xA29CfFC83d32fe924cFf1F1bDCf21555CCC96206",
+      LB:   "0x5D417F296b17656c9b950236feE66F63E22d8A54",
+      ORG:  "0x440b28afc1804fc1E4AA8f5b559C18F7bCf43B3A",
+      FEE:  "0x88A0A4d573fD9C63433E457e94d266D7904278C2",
+      TRN:  "0xbcc0E82a17491297E0c4938606624Fa04e6abA1B",
+    },
+  },
+  studionet: {
+    id:      "studionet",
+    rpc:     "https://studio.genlayer.com/api",
+    chainId: 61999,
+    addresses: {
+      CORE: "0x88CAA18419714aA38CdF53c0E603141c48fa3238",
+      LB:   "0x8A2d05Df048A64cc6B83682a431ade05030e4BBB",
+      ORG:  "0x265ef96A5230F13836c553D7DD2B9D7c3fE14aE1",
+      FEE:  "0x0000000000000000000000000000000000000000",
+      TRN:  "0x44f7c1bDa293B9cdBD79a6dfb66bD45696dEa4A6",
+    },
+  },
+};
+
+export const DEFAULT_WS_URL = "wss://ws.theref.fun";
+
+export function resolveNetwork(network: NetworkId | NetworkConfig): NetworkConfig {
+  if (typeof network === "string") return NETWORKS[network];
+  return network;
+}
+
+export function gidToNum(gid: string): number {
+  return parseInt(gid.replace(/^0+/, "") || "0", 36) || 1;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "lib": ["ES2020", "DOM"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}