clarityxo-sdk 0.1.0 → 0.2.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

package/dist/chunk-ETEDBK3G.mjs

@@ -0,0 +1,348 @@
+// 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 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,
+  CONTRACT_FUNCTIONS,
+  getBoardState,
+  getGameStatus,
+  getWinner,
+  getCurrentTurn,
+  isValidMove,
+  getFullGameState,
+  startNewGame,
+  makeMove,
+  resignGame,
+  getLeaderboard,
+  submitResult,
+  syncLeaderboard,
+  healthCheck,
+  getPlayerStats,
+  ClarityXOClient,
+  createClient
+};

package/dist/cli/index.js

@@ -24,7 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli/index.ts
-var import_commander5 = require("commander");
+var import_commander8 = require("commander");
 
 // src/cli/commands/board.ts
 var import_commander = require("commander");
@@ -280,6 +280,22 @@ async function healthCheck(config) {
     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 {
@@ -329,14 +345,53 @@ var ClarityXOClient = class {
   healthCheck() {
     return healthCheck(this.config);
   }
+  getPlayerStats(playerAddress, month) {
+    return getPlayerStats(this.config, playerAddress, month);
+  }
 };
 function createClient(config) {
   return new ClarityXOClient(config);
 }
 
+// src/utils/validation.ts
+function isValidStacksAddress(address) {
+  return /^S[TP][0-9A-Z]{38}$/.test(address);
+}
+function validateContractAddress(address) {
+  if (!address) {
+    throw new Error("Contract address is required");
+  }
+  if (!isValidStacksAddress(address)) {
+    throw new Error("Invalid Stacks address format");
+  }
+}
+function validateNetwork(network) {
+  if (network !== "mainnet" && network !== "testnet") {
+    throw new Error('Network must be either "mainnet" or "testnet"');
+  }
+}
+function validateWriteConfig(key, address) {
+  if (!key) {
+    throw new Error("--key (sender private key) is required for write operations");
+  }
+  if (!address) {
+    throw new Error("--address (sender address) is required for write operations");
+  }
+  if (!isValidStacksAddress(address)) {
+    throw new Error("Invalid sender address format");
+  }
+}
+
 // src/cli/commands/board.ts
 var command = new import_commander.Command("board");
 command.description("Display the current game board").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+    validateContractAddress(options.contract);
+  } catch (error) {
+    console.error(import_chalk.default.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
   const config = {
     network: options.network,
     contractAddress: options.contract,
@@ -384,6 +439,13 @@ var import_chalk2 = __toESM(require("chalk"));
 var import_ora2 = __toESM(require("ora"));
 var command2 = new import_commander2.Command("status");
 command2.description("Display the current game status and turn").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+    validateContractAddress(options.contract);
+  } catch (error) {
+    console.error(import_chalk2.default.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
   const config = {
     network: options.network,
     contractAddress: options.contract,
@@ -413,6 +475,13 @@ var import_chalk3 = __toESM(require("chalk"));
 var import_ora3 = __toESM(require("ora"));
 var command3 = new import_commander3.Command("winner");
 command3.description("Display the game winner").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+    validateContractAddress(options.contract);
+  } catch (error) {
+    console.error(import_chalk3.default.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
   const config = {
     network: options.network,
     contractAddress: options.contract,
@@ -443,6 +512,12 @@ var import_chalk4 = __toESM(require("chalk"));
 var import_ora4 = __toESM(require("ora"));
 var command4 = new import_commander4.Command("leaderboard");
 command4.description("Display the leaderboard for a given month").option("--month <yyyy-mm>", "Month (YYYY-MM)", (/* @__PURE__ */ new Date()).toISOString().slice(0, 7)).option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+  } catch (error) {
+    console.error(import_chalk4.default.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
   const config = {
     network: options.network,
     contractAddress: options.contract,
@@ -470,13 +545,123 @@ command4.description("Display the leaderboard for a given month").option("--mont
 });
 var leaderboard_default = command4;
 
+// src/cli/commands/move.ts
+var import_commander5 = require("commander");
+var import_chalk5 = __toESM(require("chalk"));
+var import_ora5 = __toESM(require("ora"));
+var command5 = new import_commander5.Command("move");
+command5.description("Make a move on the board").argument("<row>", "Row (0-2)").argument("<col>", "Column (0-2)").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").option("--key <key>", "Sender private key (required)").option("--address <address>", "Sender address (required)").action(async (row, col, options) => {
+  try {
+    validateNetwork(options.network);
+    const rowNum2 = parseInt(row, 10);
+    const colNum2 = parseInt(col, 10);
+    if (isNaN(rowNum2) || isNaN(colNum2) || rowNum2 < 0 || rowNum2 > 2 || colNum2 < 0 || colNum2 > 2) {
+      throw new Error("Row and column must be integers between 0 and 2");
+    }
+    validateWriteConfig(options.key, options.address);
+  } catch (error) {
+    console.error(import_chalk5.default.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+  const config = {
+    network: options.network,
+    contractAddress: options.contract,
+    leaderboardApiUrl: options.api,
+    senderKey: options.key,
+    senderAddress: options.address
+  };
+  const spinner = (0, import_ora5.default)("Making move...").start();
+  try {
+    const client = createClient(config);
+    const tx = await client.makeMove(rowNum, colNum);
+    spinner.stop();
+    console.log(import_chalk5.default.green(`Move successful! Transaction ID: ${tx.txId}`));
+  } catch (error) {
+    spinner.stop();
+    console.error(import_chalk5.default.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+});
+var move_default = command5;
+
+// src/cli/commands/start.ts
+var import_commander6 = require("commander");
+var import_chalk6 = __toESM(require("chalk"));
+var import_ora6 = __toESM(require("ora"));
+var command6 = new import_commander6.Command("start");
+command6.description("Start a new game").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").option("--key <key>", "Sender private key (required)").option("--address <address>", "Sender address (required)").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+    validateWriteConfig(options.key, options.address);
+  } catch (error) {
+    console.error(import_chalk6.default.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+  const config = {
+    network: options.network,
+    contractAddress: options.contract,
+    leaderboardApiUrl: options.api,
+    senderKey: options.key,
+    senderAddress: options.address
+  };
+  const spinner = (0, import_ora6.default)("Starting new game...").start();
+  try {
+    const client = createClient(config);
+    const tx = await client.startNewGame();
+    spinner.stop();
+    console.log(import_chalk6.default.green(`New game started! Transaction ID: ${tx.txId}`));
+  } catch (error) {
+    spinner.stop();
+    console.error(import_chalk6.default.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+});
+var start_default = command6;
+
+// src/cli/commands/resign.ts
+var import_commander7 = require("commander");
+var import_chalk7 = __toESM(require("chalk"));
+var import_ora7 = __toESM(require("ora"));
+var command7 = new import_commander7.Command("resign");
+command7.description("Resign the current game").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").option("--key <key>", "Sender private key (required)").option("--address <address>", "Sender address (required)").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+    validateWriteConfig(options.key, options.address);
+  } catch (error) {
+    console.error(import_chalk7.default.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+  const config = {
+    network: options.network,
+    contractAddress: options.contract,
+    leaderboardApiUrl: options.api,
+    senderKey: options.key,
+    senderAddress: options.address
+  };
+  const spinner = (0, import_ora7.default)("Resigning game...").start();
+  try {
+    const client = createClient(config);
+    const tx = await client.resignGame();
+    spinner.stop();
+    console.log(import_chalk7.default.green(`Game resigned! Transaction ID: ${tx.txId}`));
+  } catch (error) {
+    spinner.stop();
+    console.error(import_chalk7.default.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+});
+var resign_default = command7;
+
 // src/cli/index.ts
-var packageJson = { version: "0.1.0" };
-var program = new import_commander5.Command();
+var packageJson = { version: "0.2.0" };
+var program = new import_commander8.Command();
 program.name("clarityxo").description("CLI for ClarityXO Tic-Tac-Toe on Stacks blockchain").version(packageJson.version);
 program.option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL");
 program.addCommand(board_default);
 program.addCommand(status_default);
 program.addCommand(winner_default);
 program.addCommand(leaderboard_default);
+program.addCommand(move_default);
+program.addCommand(start_default);
+program.addCommand(resign_default);
 program.parse();

package/dist/cli/index.mjs

@@ -1,17 +1,55 @@
 #!/usr/bin/env node
 import {
   createClient
-} from "../chunk-Z5L3H7VV.mjs";
+} from "../chunk-ETEDBK3G.mjs";
 
 // src/cli/index.ts
-import { Command as Command5 } from "commander";
+import { Command as Command8 } from "commander";
 
 // src/cli/commands/board.ts
 import { Command } from "commander";
 import chalk from "chalk";
 import ora from "ora";
+
+// src/utils/validation.ts
+function isValidStacksAddress(address) {
+  return /^S[TP][0-9A-Z]{38}$/.test(address);
+}
+function validateContractAddress(address) {
+  if (!address) {
+    throw new Error("Contract address is required");
+  }
+  if (!isValidStacksAddress(address)) {
+    throw new Error("Invalid Stacks address format");
+  }
+}
+function validateNetwork(network) {
+  if (network !== "mainnet" && network !== "testnet") {
+    throw new Error('Network must be either "mainnet" or "testnet"');
+  }
+}
+function validateWriteConfig(key, address) {
+  if (!key) {
+    throw new Error("--key (sender private key) is required for write operations");
+  }
+  if (!address) {
+    throw new Error("--address (sender address) is required for write operations");
+  }
+  if (!isValidStacksAddress(address)) {
+    throw new Error("Invalid sender address format");
+  }
+}
+
+// src/cli/commands/board.ts
 var command = new Command("board");
 command.description("Display the current game board").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+    validateContractAddress(options.contract);
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
   const config = {
     network: options.network,
     contractAddress: options.contract,
@@ -59,6 +97,13 @@ import chalk2 from "chalk";
 import ora2 from "ora";
 var command2 = new Command2("status");
 command2.description("Display the current game status and turn").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+    validateContractAddress(options.contract);
+  } catch (error) {
+    console.error(chalk2.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
   const config = {
     network: options.network,
     contractAddress: options.contract,
@@ -88,6 +133,13 @@ import chalk3 from "chalk";
 import ora3 from "ora";
 var command3 = new Command3("winner");
 command3.description("Display the game winner").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+    validateContractAddress(options.contract);
+  } catch (error) {
+    console.error(chalk3.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
   const config = {
     network: options.network,
     contractAddress: options.contract,
@@ -118,6 +170,12 @@ import chalk4 from "chalk";
 import ora4 from "ora";
 var command4 = new Command4("leaderboard");
 command4.description("Display the leaderboard for a given month").option("--month <yyyy-mm>", "Month (YYYY-MM)", (/* @__PURE__ */ new Date()).toISOString().slice(0, 7)).option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+  } catch (error) {
+    console.error(chalk4.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
   const config = {
     network: options.network,
     contractAddress: options.contract,
@@ -145,13 +203,123 @@ command4.description("Display the leaderboard for a given month").option("--mont
 });
 var leaderboard_default = command4;
 
+// src/cli/commands/move.ts
+import { Command as Command5 } from "commander";
+import chalk5 from "chalk";
+import ora5 from "ora";
+var command5 = new Command5("move");
+command5.description("Make a move on the board").argument("<row>", "Row (0-2)").argument("<col>", "Column (0-2)").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").option("--key <key>", "Sender private key (required)").option("--address <address>", "Sender address (required)").action(async (row, col, options) => {
+  try {
+    validateNetwork(options.network);
+    const rowNum2 = parseInt(row, 10);
+    const colNum2 = parseInt(col, 10);
+    if (isNaN(rowNum2) || isNaN(colNum2) || rowNum2 < 0 || rowNum2 > 2 || colNum2 < 0 || colNum2 > 2) {
+      throw new Error("Row and column must be integers between 0 and 2");
+    }
+    validateWriteConfig(options.key, options.address);
+  } catch (error) {
+    console.error(chalk5.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+  const config = {
+    network: options.network,
+    contractAddress: options.contract,
+    leaderboardApiUrl: options.api,
+    senderKey: options.key,
+    senderAddress: options.address
+  };
+  const spinner = ora5("Making move...").start();
+  try {
+    const client = createClient(config);
+    const tx = await client.makeMove(rowNum, colNum);
+    spinner.stop();
+    console.log(chalk5.green(`Move successful! Transaction ID: ${tx.txId}`));
+  } catch (error) {
+    spinner.stop();
+    console.error(chalk5.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+});
+var move_default = command5;
+
+// src/cli/commands/start.ts
+import { Command as Command6 } from "commander";
+import chalk6 from "chalk";
+import ora6 from "ora";
+var command6 = new Command6("start");
+command6.description("Start a new game").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").option("--key <key>", "Sender private key (required)").option("--address <address>", "Sender address (required)").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+    validateWriteConfig(options.key, options.address);
+  } catch (error) {
+    console.error(chalk6.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+  const config = {
+    network: options.network,
+    contractAddress: options.contract,
+    leaderboardApiUrl: options.api,
+    senderKey: options.key,
+    senderAddress: options.address
+  };
+  const spinner = ora6("Starting new game...").start();
+  try {
+    const client = createClient(config);
+    const tx = await client.startNewGame();
+    spinner.stop();
+    console.log(chalk6.green(`New game started! Transaction ID: ${tx.txId}`));
+  } catch (error) {
+    spinner.stop();
+    console.error(chalk6.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+});
+var start_default = command6;
+
+// src/cli/commands/resign.ts
+import { Command as Command7 } from "commander";
+import chalk7 from "chalk";
+import ora7 from "ora";
+var command7 = new Command7("resign");
+command7.description("Resign the current game").option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL").option("--key <key>", "Sender private key (required)").option("--address <address>", "Sender address (required)").action(async (options) => {
+  try {
+    validateNetwork(options.network);
+    validateWriteConfig(options.key, options.address);
+  } catch (error) {
+    console.error(chalk7.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+  const config = {
+    network: options.network,
+    contractAddress: options.contract,
+    leaderboardApiUrl: options.api,
+    senderKey: options.key,
+    senderAddress: options.address
+  };
+  const spinner = ora7("Resigning game...").start();
+  try {
+    const client = createClient(config);
+    const tx = await client.resignGame();
+    spinner.stop();
+    console.log(chalk7.green(`Game resigned! Transaction ID: ${tx.txId}`));
+  } catch (error) {
+    spinner.stop();
+    console.error(chalk7.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+});
+var resign_default = command7;
+
 // src/cli/index.ts
-var packageJson = { version: "0.1.0" };
-var program = new Command5();
+var packageJson = { version: "0.2.0" };
+var program = new Command8();
 program.name("clarityxo").description("CLI for ClarityXO Tic-Tac-Toe on Stacks blockchain").version(packageJson.version);
 program.option("--contract [address]", "Contract address").option("--network <network>", "Network (mainnet or testnet)", "testnet").option("--api <url>", "Leaderboard API URL");
 program.addCommand(board_default);
 program.addCommand(status_default);
 program.addCommand(winner_default);
 program.addCommand(leaderboard_default);
+program.addCommand(move_default);
+program.addCommand(start_default);
+program.addCommand(resign_default);
 program.parse();

package/dist/index.d.mts

@@ -33,6 +33,16 @@ interface LeaderboardEntry {
     points: number;
     rank: number;
 }
+interface PlayerStats {
+    player: string;
+    wins: number;
+    losses: number;
+    draws: number;
+    points: number;
+    rank: number;
+    totalGames: number;
+    winRate: number;
+}
 interface LeaderboardMonth {
     month: string;
     entries: LeaderboardEntry[];
@@ -73,6 +83,7 @@ declare class ClarityXOClient {
     submitResult(result: GameResult): Promise<void>;
     syncLeaderboard(): Promise<void>;
     healthCheck(): Promise<boolean>;
+    getPlayerStats(playerAddress: string, month?: string): Promise<PlayerStats | null>;
 }
 declare function createClient(config: ClarityXOConfig): ClarityXOClient;
 
@@ -113,5 +124,14 @@ declare function getLeaderboard(config: ClarityXOConfig, month: string): Promise
 declare function submitResult(config: ClarityXOConfig, result: GameResult): Promise<void>;
 declare function syncLeaderboard(config: ClarityXOConfig): Promise<void>;
 declare function healthCheck(config: ClarityXOConfig): Promise<boolean>;
+declare function getPlayerStats(config: ClarityXOConfig, playerAddress: string, month?: string): Promise<PlayerStats | null>;
+
+declare function checkWin(board: Board, player: CellValue): boolean;
+declare function isBoardFull(board: Board): boolean;
+declare function isDraw(board: Board): boolean;
+declare function getAvailableMoves(board: Board): Array<[number, number]>;
+declare function getBoardString(board: Board): string;
+declare function cloneBoard(board: Board): Board;
+declare function makeMoveOnBoard(board: Board, row: number, col: number, player: CellValue): Board;
 
-export { type Board, CONTRACT_ADDRESS, CONTRACT_FUNCTIONS, CONTRACT_NAME, type CellValue, ClarityXOClient, type ClarityXOConfig, DEFAULT_LEADERBOARD_API, type GameResult, type GameState, type GameStatus, type LeaderboardEntry, type LeaderboardMonth, MAINNET_API, type Network, TESTNET_API, type Turn, createClient, getBoardState, getCurrentTurn, getFullGameState, getGameStatus, getLeaderboard, getWinner, healthCheck, isValidMove, makeMove, resignGame, startNewGame, submitResult, syncLeaderboard };
+export { type Board, CONTRACT_ADDRESS, CONTRACT_FUNCTIONS, CONTRACT_NAME, type CellValue, ClarityXOClient, type ClarityXOConfig, DEFAULT_LEADERBOARD_API, type GameResult, type GameState, type GameStatus, type LeaderboardEntry, type LeaderboardMonth, MAINNET_API, type Network, type PlayerStats, TESTNET_API, type Turn, checkWin, cloneBoard, createClient, getAvailableMoves, getBoardState, getBoardString, getCurrentTurn, getFullGameState, getGameStatus, getLeaderboard, getPlayerStats, getWinner, healthCheck, isBoardFull, isDraw, isValidMove, makeMove, makeMoveOnBoard, resignGame, startNewGame, submitResult, syncLeaderboard };

package/dist/index.d.ts

@@ -33,6 +33,16 @@ interface LeaderboardEntry {
     points: number;
     rank: number;
 }
+interface PlayerStats {
+    player: string;
+    wins: number;
+    losses: number;
+    draws: number;
+    points: number;
+    rank: number;
+    totalGames: number;
+    winRate: number;
+}
 interface LeaderboardMonth {
     month: string;
     entries: LeaderboardEntry[];
@@ -73,6 +83,7 @@ declare class ClarityXOClient {
     submitResult(result: GameResult): Promise<void>;
     syncLeaderboard(): Promise<void>;
     healthCheck(): Promise<boolean>;
+    getPlayerStats(playerAddress: string, month?: string): Promise<PlayerStats | null>;
 }
 declare function createClient(config: ClarityXOConfig): ClarityXOClient;
 
@@ -113,5 +124,14 @@ declare function getLeaderboard(config: ClarityXOConfig, month: string): Promise
 declare function submitResult(config: ClarityXOConfig, result: GameResult): Promise<void>;
 declare function syncLeaderboard(config: ClarityXOConfig): Promise<void>;
 declare function healthCheck(config: ClarityXOConfig): Promise<boolean>;
+declare function getPlayerStats(config: ClarityXOConfig, playerAddress: string, month?: string): Promise<PlayerStats | null>;
+
+declare function checkWin(board: Board, player: CellValue): boolean;
+declare function isBoardFull(board: Board): boolean;
+declare function isDraw(board: Board): boolean;
+declare function getAvailableMoves(board: Board): Array<[number, number]>;
+declare function getBoardString(board: Board): string;
+declare function cloneBoard(board: Board): Board;
+declare function makeMoveOnBoard(board: Board, row: number, col: number, player: CellValue): Board;
 
-export { type Board, CONTRACT_ADDRESS, CONTRACT_FUNCTIONS, CONTRACT_NAME, type CellValue, ClarityXOClient, type ClarityXOConfig, DEFAULT_LEADERBOARD_API, type GameResult, type GameState, type GameStatus, type LeaderboardEntry, type LeaderboardMonth, MAINNET_API, type Network, TESTNET_API, type Turn, createClient, getBoardState, getCurrentTurn, getFullGameState, getGameStatus, getLeaderboard, getWinner, healthCheck, isValidMove, makeMove, resignGame, startNewGame, submitResult, syncLeaderboard };
+export { type Board, CONTRACT_ADDRESS, CONTRACT_FUNCTIONS, CONTRACT_NAME, type CellValue, ClarityXOClient, type ClarityXOConfig, DEFAULT_LEADERBOARD_API, type GameResult, type GameState, type GameStatus, type LeaderboardEntry, type LeaderboardMonth, MAINNET_API, type Network, type PlayerStats, TESTNET_API, type Turn, checkWin, cloneBoard, createClient, getAvailableMoves, getBoardState, getBoardString, getCurrentTurn, getFullGameState, getGameStatus, getLeaderboard, getPlayerStats, getWinner, healthCheck, isBoardFull, isDraw, isValidMove, makeMove, makeMoveOnBoard, resignGame, startNewGame, submitResult, syncLeaderboard };

package/dist/index.js

@@ -27,16 +27,24 @@ __export(index_exports, {
   DEFAULT_LEADERBOARD_API: () => DEFAULT_LEADERBOARD_API,
   MAINNET_API: () => MAINNET_API,
   TESTNET_API: () => TESTNET_API,
+  checkWin: () => checkWin,
+  cloneBoard: () => cloneBoard,
   createClient: () => createClient,
+  getAvailableMoves: () => getAvailableMoves,
   getBoardState: () => getBoardState,
+  getBoardString: () => getBoardString,
   getCurrentTurn: () => getCurrentTurn,
   getFullGameState: () => getFullGameState,
   getGameStatus: () => getGameStatus,
   getLeaderboard: () => getLeaderboard,
+  getPlayerStats: () => getPlayerStats,
   getWinner: () => getWinner,
   healthCheck: () => healthCheck,
+  isBoardFull: () => isBoardFull,
+  isDraw: () => isDraw,
   isValidMove: () => isValidMove,
   makeMove: () => makeMove,
+  makeMoveOnBoard: () => makeMoveOnBoard,
   resignGame: () => resignGame,
   startNewGame: () => startNewGame,
   submitResult: () => submitResult,
@@ -295,6 +303,22 @@ async function healthCheck(config) {
     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 {
@@ -344,10 +368,66 @@ var ClarityXOClient = class {
   healthCheck() {
     return healthCheck(this.config);
   }
+  getPlayerStats(playerAddress, month) {
+    return getPlayerStats(this.config, playerAddress, month);
+  }
 };
 function createClient(config) {
   return new ClarityXOClient(config);
 }
+
+// src/utils/board.ts
+function checkWin(board, player) {
+  if (player === null) return false;
+  for (let row = 0; row < 3; row++) {
+    if (board[row][0] === player && board[row][1] === player && board[row][2] === player) {
+      return true;
+    }
+  }
+  for (let col = 0; col < 3; col++) {
+    if (board[0][col] === player && board[1][col] === player && board[2][col] === player) {
+      return true;
+    }
+  }
+  if (board[0][0] === player && board[1][1] === player && board[2][2] === player) {
+    return true;
+  }
+  if (board[0][2] === player && board[1][1] === player && board[2][0] === player) {
+    return true;
+  }
+  return false;
+}
+function isBoardFull(board) {
+  return board.every((row) => row.every((cell) => cell !== null));
+}
+function isDraw(board) {
+  return isBoardFull(board) && !checkWin(board, "X") && !checkWin(board, "O");
+}
+function getAvailableMoves(board) {
+  const moves = [];
+  for (let row = 0; row < 3; row++) {
+    for (let col = 0; col < 3; col++) {
+      if (board[row][col] === null) {
+        moves.push([row, col]);
+      }
+    }
+  }
+  return moves;
+}
+function getBoardString(board) {
+  return board.map((row) => row.map((cell) => cell || " ").join("")).join("\n");
+}
+function cloneBoard(board) {
+  return board.map((row) => [...row]);
+}
+function makeMoveOnBoard(board, row, col, player) {
+  if (board[row][col] !== null) {
+    throw new Error("Cell is already occupied");
+  }
+  const newBoard = cloneBoard(board);
+  newBoard[row][col] = player;
+  return newBoard;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CONTRACT_ADDRESS,
@@ -357,16 +437,24 @@ function createClient(config) {
   DEFAULT_LEADERBOARD_API,
   MAINNET_API,
   TESTNET_API,
+  checkWin,
+  cloneBoard,
   createClient,
+  getAvailableMoves,
   getBoardState,
+  getBoardString,
   getCurrentTurn,
   getFullGameState,
   getGameStatus,
   getLeaderboard,
+  getPlayerStats,
   getWinner,
   healthCheck,
+  isBoardFull,
+  isDraw,
   isValidMove,
   makeMove,
+  makeMoveOnBoard,
   resignGame,
   startNewGame,
   submitResult,

package/dist/index.mjs

@@ -12,6 +12,7 @@ import {
   getFullGameState,
   getGameStatus,
   getLeaderboard,
+  getPlayerStats,
   getWinner,
   healthCheck,
   isValidMove,
@@ -20,7 +21,60 @@ import {
   startNewGame,
   submitResult,
   syncLeaderboard
-} from "./chunk-Z5L3H7VV.mjs";
+} from "./chunk-ETEDBK3G.mjs";
+
+// src/utils/board.ts
+function checkWin(board, player) {
+  if (player === null) return false;
+  for (let row = 0; row < 3; row++) {
+    if (board[row][0] === player && board[row][1] === player && board[row][2] === player) {
+      return true;
+    }
+  }
+  for (let col = 0; col < 3; col++) {
+    if (board[0][col] === player && board[1][col] === player && board[2][col] === player) {
+      return true;
+    }
+  }
+  if (board[0][0] === player && board[1][1] === player && board[2][2] === player) {
+    return true;
+  }
+  if (board[0][2] === player && board[1][1] === player && board[2][0] === player) {
+    return true;
+  }
+  return false;
+}
+function isBoardFull(board) {
+  return board.every((row) => row.every((cell) => cell !== null));
+}
+function isDraw(board) {
+  return isBoardFull(board) && !checkWin(board, "X") && !checkWin(board, "O");
+}
+function getAvailableMoves(board) {
+  const moves = [];
+  for (let row = 0; row < 3; row++) {
+    for (let col = 0; col < 3; col++) {
+      if (board[row][col] === null) {
+        moves.push([row, col]);
+      }
+    }
+  }
+  return moves;
+}
+function getBoardString(board) {
+  return board.map((row) => row.map((cell) => cell || " ").join("")).join("\n");
+}
+function cloneBoard(board) {
+  return board.map((row) => [...row]);
+}
+function makeMoveOnBoard(board, row, col, player) {
+  if (board[row][col] !== null) {
+    throw new Error("Cell is already occupied");
+  }
+  const newBoard = cloneBoard(board);
+  newBoard[row][col] = player;
+  return newBoard;
+}
 export {
   CONTRACT_ADDRESS,
   CONTRACT_FUNCTIONS,
@@ -29,16 +83,24 @@ export {
   DEFAULT_LEADERBOARD_API,
   MAINNET_API,
   TESTNET_API,
+  checkWin,
+  cloneBoard,
   createClient,
+  getAvailableMoves,
   getBoardState,
+  getBoardString,
   getCurrentTurn,
   getFullGameState,
   getGameStatus,
   getLeaderboard,
+  getPlayerStats,
   getWinner,
   healthCheck,
+  isBoardFull,
+  isDraw,
   isValidMove,
   makeMove,
+  makeMoveOnBoard,
   resignGame,
   startNewGame,
   submitResult,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clarityxo-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript SDK and CLI for the ClarityXO on-chain Tic-Tac-Toe game on Stacks",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -31,7 +31,6 @@
     "web3"
   ],
   "author": "Dominion <limbotech116@gmail.com>",
-  "author": "Dominion <limbotech116@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",