clarityxo-sdk 0.1.0 → 0.3.0

package/README.md

@@ -57,6 +57,7 @@ These require `senderKey` and `senderAddress` in config.
 - `submitResult(result: GameResult): Promise<void>` - Submit a game result
 - `syncLeaderboard(): Promise<void>` - Sync leaderboard data
 - `healthCheck(): Promise<boolean>` - Check if leaderboard API is healthy
+- `getPlayerStats(playerAddress: string, month?: string): Promise<PlayerStats | null>` - Get statistics for a specific player
 
 ### Types
 
@@ -69,6 +70,7 @@ These require `senderKey` and `senderAddress` in config.
 - `LeaderboardEntry`: { player, wins, losses, draws, points, rank }
 - `LeaderboardMonth`: { month, entries }
 - `GameResult`: { player, outcome, month }
+- `PlayerStats`: { player, wins, losses, draws, points, rank, totalGames, winRate }
 
 ## CLI
 
@@ -129,6 +131,30 @@ Display the leaderboard for a month.
 clarityxo leaderboard --month 2023-10 --contract ST1PQHQKVVA1MGKKKSQCXDTEYXSGHCV66VR89BS1
 ```
 
+#### `move <row> <col>`
+
+Make a move on the board. Requires sender key and address.
+
+```bash
+clarityxo move 1 2 --contract ST1PQHQKVVA1MGKKKSQCXDTEYXSGHCV66VR89BS1 --key <private-key> --address <address>
+```
+
+#### `start`
+
+Start a new game. Requires sender key and address.
+
+```bash
+clarityxo start --contract ST1PQHQKVVA1MGKKKSQCXDTEYXSGHCV66VR89BS1 --key <private-key> --address <address>
+```
+
+#### `resign`
+
+Resign the current game. Requires sender key and address.
+
+```bash
+clarityxo resign --contract ST1PQHQKVVA1MGKKKSQCXDTEYXSGHCV66VR89BS1 --key <private-key> --address <address>
+```
+
 ## Network Configuration
 
 - **Mainnet**: Use 'mainnet' network, mainnet contract addresses
@@ -149,6 +175,18 @@ try {
 }
 ```
 
+## Utility Functions
+
+The SDK includes utility functions for board analysis:
+
+- `checkWin(board, player)` - Check if a player has won
+- `isBoardFull(board)` - Check if the board is full
+- `isDraw(board)` - Check if the game is a draw
+- `getAvailableMoves(board)` - Get list of available moves
+- `getBoardString(board)` - Convert board to string representation
+- `cloneBoard(board)` - Create a deep copy of the board
+- `makeMoveOnBoard(board, row, col, player)` - Make a move and return new board
+
 ## Contributing
 
 1. Fork the repository
@@ -159,6 +197,8 @@ try {
 6. Format: `npm run format`
 7. Submit a PR
 
+If you'd like to contribute a bugfix or small improvement, open an issue first with a short description of the change. For larger features, open a discussion or draft PR so we can coordinate before significant design work.
+
 ## License
 
 MIT

package/dist/chunk-2P6NUM7A.mjs

@@ -0,0 +1,350 @@
+// src/constants.ts
+var CONTRACT_NAME = "tictactoe";
+var CONTRACT_ADDRESS = "SP30VGN68PSGVWGNMD0HH2WQMM5T486EK3YGP7Z3Y.clarity-xo-game";
+var MAINNET_API = "https://api.mainnet.hiro.so";
+var TESTNET_API = "https://api.testnet.hiro.so";
+var DEFAULT_LEADERBOARD_API = "https://clarityxo.onrender.com";
+var DEFAULT_NETWORK = "testnet";
+var CONTRACT_FUNCTIONS = {
+  START_NEW_GAME: "start-new-game",
+  MAKE_MOVE: "make-move",
+  RESIGN_GAME: "resign-game",
+  GET_BOARD_STATE: "get-board-state",
+  GET_GAME_STATUS: "get-game-status",
+  GET_WINNER: "get-winner",
+  GET_CURRENT_TURN: "get-current-turn",
+  IS_VALID_MOVE: "is-valid-move"
+};
+
+// src/contract/read.ts
+import { callReadOnlyFunction, uintCV } from "@stacks/transactions";
+
+// src/utils/network.ts
+import { StacksMainnet, StacksTestnet } from "@stacks/network";
+function getStacksNetwork(network) {
+  return network === "mainnet" ? new StacksMainnet() : new StacksTestnet();
+}
+
+// src/utils/cv.ts
+function parseBoardCV(cv) {
+  const rows = cv;
+  const board = [
+    [null, null, null],
+    [null, null, null],
+    [null, null, null]
+  ];
+  for (let i = 0; i < 3; i++) {
+    const row = rows.list[i].list;
+    for (let j = 0; j < 3; j++) {
+      const cell = row[j];
+      if (cell.type === "some") {
+        board[i][j] = cell.value.value;
+      } else {
+        board[i][j] = null;
+      }
+    }
+  }
+  return board;
+}
+function parseGameStatusCV(cv) {
+  const value = cv.value;
+  if (value === "active") return "active";
+  if (value === "finished") return "finished";
+  if (value === "not-started") return "not-started";
+  throw new Error(`Invalid game status: ${value}`);
+}
+function parseWinnerCV(cv) {
+  const value = cv.value;
+  if (value === "player") return "player";
+  if (value === "ai") return "ai";
+  if (value === "draw") return "draw";
+  return null;
+}
+function parseTurnCV(cv) {
+  const value = cv.value;
+  if (value === "player") return "player";
+  if (value === "ai") return "ai";
+  throw new Error(`Invalid turn: ${value}`);
+}
+
+// src/contract/read.ts
+async function getBoardState(config) {
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const contractAddress = config.contractAddress || CONTRACT_ADDRESS;
+  const cv = await callReadOnlyFunction({
+    network,
+    contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.GET_BOARD_STATE,
+    functionArgs: [],
+    senderAddress: contractAddress
+    // arbitrary
+  });
+  return parseBoardCV(cv);
+}
+async function getGameStatus(config) {
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const contractAddress = config.contractAddress || CONTRACT_ADDRESS;
+  const cv = await callReadOnlyFunction({
+    network,
+    contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.GET_GAME_STATUS,
+    functionArgs: [],
+    senderAddress: contractAddress
+  });
+  return parseGameStatusCV(cv);
+}
+async function getWinner(config) {
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const contractAddress = config.contractAddress || CONTRACT_ADDRESS;
+  const cv = await callReadOnlyFunction({
+    network,
+    contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.GET_WINNER,
+    functionArgs: [],
+    senderAddress: contractAddress
+  });
+  return parseWinnerCV(cv);
+}
+async function getCurrentTurn(config) {
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const contractAddress = config.contractAddress || CONTRACT_ADDRESS;
+  const cv = await callReadOnlyFunction({
+    network,
+    contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.GET_CURRENT_TURN,
+    functionArgs: [],
+    senderAddress: contractAddress
+  });
+  return parseTurnCV(cv);
+}
+async function isValidMove(config, row, col) {
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const contractAddress = config.contractAddress || CONTRACT_ADDRESS;
+  const cv = await callReadOnlyFunction({
+    network,
+    contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.IS_VALID_MOVE,
+    functionArgs: [uintCV(row), uintCV(col)],
+    senderAddress: contractAddress
+  });
+  return cv.value;
+}
+async function getFullGameState(config) {
+  const [board, status, winner, currentTurn] = await Promise.all([
+    getBoardState(config),
+    getGameStatus(config),
+    getWinner(config),
+    getCurrentTurn(config)
+  ]);
+  return { board, status, winner, currentTurn };
+}
+
+// src/contract/write.ts
+import { makeContractCall, broadcastTransaction, uintCV as uintCV2 } from "@stacks/transactions";
+async function startNewGame(config) {
+  if (!config.senderKey || !config.senderAddress) {
+    throw new Error("senderKey and senderAddress are required for write operations");
+  }
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const contractAddress = config.contractAddress || CONTRACT_ADDRESS;
+  const tx = await makeContractCall({
+    network,
+    contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.START_NEW_GAME,
+    functionArgs: [],
+    senderKey: config.senderKey,
+    anchorMode: "any"
+  });
+  const broadcastResponse = await broadcastTransaction(tx, network);
+  return { txId: broadcastResponse.txid };
+}
+async function makeMove(config, row, col) {
+  if (!config.senderKey || !config.senderAddress) {
+    throw new Error("senderKey and senderAddress are required for write operations");
+  }
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const contractAddress = config.contractAddress || CONTRACT_ADDRESS;
+  const tx = await makeContractCall({
+    network,
+    contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.MAKE_MOVE,
+    functionArgs: [uintCV2(row), uintCV2(col)],
+    senderKey: config.senderKey,
+    anchorMode: "any"
+  });
+  const broadcastResponse = await broadcastTransaction(tx, network);
+  return { txId: broadcastResponse.txid };
+}
+async function resignGame(config) {
+  if (!config.senderKey || !config.senderAddress) {
+    throw new Error("senderKey and senderAddress are required for write operations");
+  }
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const contractAddress = config.contractAddress || CONTRACT_ADDRESS;
+  const tx = await makeContractCall({
+    network,
+    contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.RESIGN_GAME,
+    functionArgs: [],
+    senderKey: config.senderKey,
+    anchorMode: "any"
+  });
+  const broadcastResponse = await broadcastTransaction(tx, network);
+  return { txId: broadcastResponse.txid };
+}
+
+// src/leaderboard/api.ts
+function getBaseUrl(config) {
+  return config.leaderboardApiUrl || DEFAULT_LEADERBOARD_API;
+}
+async function getLeaderboard(config, month) {
+  const baseUrl = getBaseUrl(config);
+  const response = await fetch(`${baseUrl}/api/leaderboard?month=${month}`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch leaderboard: ${response.statusText}`);
+  }
+  return response.json();
+}
+async function submitResult(config, result) {
+  const baseUrl = getBaseUrl(config);
+  const response = await fetch(`${baseUrl}/api/leaderboard/result`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(result)
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to submit result: ${response.statusText}`);
+  }
+}
+async function syncLeaderboard(config) {
+  const baseUrl = getBaseUrl(config);
+  const response = await fetch(`${baseUrl}/api/sync`, {
+    method: "POST"
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to sync leaderboard: ${response.statusText}`);
+  }
+}
+async function healthCheck(config) {
+  const baseUrl = getBaseUrl(config);
+  try {
+    const response = await fetch(`${baseUrl}/health`);
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+async function getPlayerStats(config, playerAddress, month) {
+  const currentMonth = month || (/* @__PURE__ */ new Date()).toISOString().slice(0, 7);
+  const leaderboard = await getLeaderboard(config, currentMonth);
+  const entry = leaderboard.entries.find((e) => e.player === playerAddress);
+  if (!entry) {
+    return null;
+  }
+  const totalGames = entry.wins + entry.losses + entry.draws;
+  const winRate = totalGames > 0 ? entry.wins / totalGames * 100 : 0;
+  return {
+    ...entry,
+    totalGames,
+    winRate: Math.round(winRate * 100) / 100
+    // Round to 2 decimal places
+  };
+}
+
+// src/client.ts
+var ClarityXOClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  // Game state
+  getBoardState() {
+    return getBoardState(this.config);
+  }
+  getGameStatus() {
+    return getGameStatus(this.config);
+  }
+  getWinner() {
+    return getWinner(this.config);
+  }
+  getCurrentTurn() {
+    return getCurrentTurn(this.config);
+  }
+  isValidMove(row, col) {
+    return isValidMove(this.config, row, col);
+  }
+  getFullGameState() {
+    return getFullGameState(this.config);
+  }
+  // Transactions
+  startNewGame() {
+    return startNewGame(this.config);
+  }
+  makeMove(row, col) {
+    return makeMove(this.config, row, col);
+  }
+  resignGame() {
+    return resignGame(this.config);
+  }
+  // Leaderboard
+  getLeaderboard(month) {
+    return getLeaderboard(this.config, month);
+  }
+  submitResult(result) {
+    return submitResult(this.config, result);
+  }
+  syncLeaderboard() {
+    return syncLeaderboard(this.config);
+  }
+  healthCheck() {
+    return healthCheck(this.config);
+  }
+  getPlayerStats(playerAddress, month) {
+    return getPlayerStats(this.config, playerAddress, month);
+  }
+};
+function createClient(config) {
+  return new ClarityXOClient(config);
+}
+
+export {
+  CONTRACT_NAME,
+  CONTRACT_ADDRESS,
+  MAINNET_API,
+  TESTNET_API,
+  DEFAULT_LEADERBOARD_API,
+  DEFAULT_NETWORK,
+  CONTRACT_FUNCTIONS,
+  getBoardState,
+  getGameStatus,
+  getWinner,
+  getCurrentTurn,
+  isValidMove,
+  getFullGameState,
+  startNewGame,
+  makeMove,
+  resignGame,
+  getLeaderboard,
+  submitResult,
+  syncLeaderboard,
+  healthCheck,
+  getPlayerStats,
+  ClarityXOClient,
+  createClient
+};