clarityxo-sdk 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# ClarityXO SDK
+
+A TypeScript SDK and CLI for interacting with the ClarityXO decentralized Tic-Tac-Toe game on the Stacks blockchain.
+
+## Installation
+
+```bash
+npm install clarityxo-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from 'clarityxo-sdk';
+
+const client = createClient({
+  network: 'testnet',
+  contractAddress: 'ST1PQHQKVVA1MGKKKSQCXDTEYXSGHCV66VR89BS1',
+});
+
+const gameState = await client.getFullGameState();
+console.log(gameState.board);
+```
+
+## API Reference
+
+### ClarityXOClient
+
+The main client class for interacting with ClarityXO.
+
+#### Constructor
+
+```typescript
+new ClarityXOClient(config: ClarityXOConfig)
+```
+
+#### Game State Methods
+
+- `getBoardState(): Promise<Board>` - Get the current board state
+- `getGameStatus(): Promise<GameStatus>` - Get the game status ('active', 'finished', 'not-started')
+- `getWinner(): Promise<'player' | 'ai' | 'draw' | null>` - Get the winner
+- `getCurrentTurn(): Promise<Turn>` - Get whose turn it is ('player' or 'ai')
+- `isValidMove(row: 0|1|2, col: 0|1|2): Promise<boolean>` - Check if a move is valid
+- `getFullGameState(): Promise<GameState>` - Get all game state at once
+
+#### Transaction Methods
+
+These require `senderKey` and `senderAddress` in config.
+
+- `startNewGame(): Promise<{ txId: string }>` - Start a new game
+- `makeMove(row: 0|1|2, col: 0|1|2): Promise<{ txId: string }>` - Make a move
+- `resignGame(): Promise<{ txId: string }>` - Resign the current game
+
+#### Leaderboard Methods
+
+- `getLeaderboard(month: string): Promise<LeaderboardMonth>` - Get leaderboard for a month
+- `submitResult(result: GameResult): Promise<void>` - Submit a game result
+- `syncLeaderboard(): Promise<void>` - Sync leaderboard data
+- `healthCheck(): Promise<boolean>` - Check if leaderboard API is healthy
+
+### Types
+
+- `Network`: 'mainnet' | 'testnet'
+- `Board`: 3x3 array of CellValue
+- `CellValue`: 'X' | 'O' | null
+- `GameStatus`: 'active' | 'finished' | 'not-started'
+- `Turn`: 'player' | 'ai'
+- `GameState`: { board, status, winner, currentTurn }
+- `LeaderboardEntry`: { player, wins, losses, draws, points, rank }
+- `LeaderboardMonth`: { month, entries }
+- `GameResult`: { player, outcome, month }
+
+## CLI
+
+The package includes a CLI tool called `clarityxo`.
+
+### Global Options
+
+- `--contract <address>`: Contract address (required for most commands)
+- `--network <mainnet|testnet>`: Network (default: testnet)
+- `--api <url>`: Leaderboard API URL
+
+### Commands
+
+#### `board`
+
+Display the current game board.
+
+```bash
+clarityxo board --contract ST1PQHQKVVA1MGKKKSQCXDTEYXSGHCV66VR89BS1
+```
+
+Example output:
+
+```
+ClarityXO — Testnet
+Contract: ST1PQHQKVVA1MGKKKSQCXDTEYXSGHCV66VR89BS1
+
+X │ · │ O
+───┼───┼───
+· │ X │ ·
+───┼───┼───
+O │ · │ X
+
+Turn: AI    Status: active    Winner: —
+```
+
+#### `status`
+
+Display game status and current turn.
+
+```bash
+clarityxo status --contract ST1PQHQKVVA1MGKKKSQCXDTEYXSGHCV66VR89BS1
+```
+
+#### `winner`
+
+Display the winner.
+
+```bash
+clarityxo winner --contract ST1PQHQKVVA1MGKKKSQCXDTEYXSGHCV66VR89BS1
+```
+
+#### `leaderboard`
+
+Display the leaderboard for a month.
+
+```bash
+clarityxo leaderboard --month 2023-10 --contract ST1PQHQKVVA1MGKKKSQCXDTEYXSGHCV66VR89BS1
+```
+
+## Network Configuration
+
+- **Mainnet**: Use 'mainnet' network, mainnet contract addresses
+- **Testnet**: Use 'testnet' network, testnet contract addresses
+
+Default leaderboard API is `https://clarityxo.onrender.com`, but can be overridden.
+
+## Error Handling
+
+All methods throw descriptive errors. Handle them appropriately:
+
+```typescript
+try {
+  const tx = await client.startNewGame();
+  console.log('Transaction ID:', tx.txId);
+} catch (error) {
+  console.error('Failed to start game:', error.message);
+}
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `npm test`
+5. Lint: `npm run lint`
+6. Format: `npm run format`
+7. Submit a PR
+
+## License
+
+MIT

package/dist/chunk-2BSRQFEM.mjs

@@ -0,0 +1,318 @@
+// src/constants.ts
+var CONTRACT_NAME = "tictactoe";
+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 cv = await callReadOnlyFunction({
+    network,
+    contractAddress: config.contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.GET_BOARD_STATE,
+    functionArgs: [],
+    senderAddress: config.contractAddress
+    // arbitrary
+  });
+  return parseBoardCV(cv);
+}
+async function getGameStatus(config) {
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const cv = await callReadOnlyFunction({
+    network,
+    contractAddress: config.contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.GET_GAME_STATUS,
+    functionArgs: [],
+    senderAddress: config.contractAddress
+  });
+  return parseGameStatusCV(cv);
+}
+async function getWinner(config) {
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const cv = await callReadOnlyFunction({
+    network,
+    contractAddress: config.contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.GET_WINNER,
+    functionArgs: [],
+    senderAddress: config.contractAddress
+  });
+  return parseWinnerCV(cv);
+}
+async function getCurrentTurn(config) {
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const cv = await callReadOnlyFunction({
+    network,
+    contractAddress: config.contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.GET_CURRENT_TURN,
+    functionArgs: [],
+    senderAddress: config.contractAddress
+  });
+  return parseTurnCV(cv);
+}
+async function isValidMove(config, row, col) {
+  const network = getStacksNetwork(config.network);
+  const contractName = config.contractName || CONTRACT_NAME;
+  const cv = await callReadOnlyFunction({
+    network,
+    contractAddress: config.contractAddress,
+    contractName,
+    functionName: CONTRACT_FUNCTIONS.IS_VALID_MOVE,
+    functionArgs: [uintCV(row), uintCV(col)],
+    senderAddress: config.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 tx = await makeContractCall({
+    network,
+    contractAddress: config.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 tx = await makeContractCall({
+    network,
+    contractAddress: config.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 tx = await makeContractCall({
+    network,
+    contractAddress: config.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;
+  }
+}
+
+// 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);
+  }
+};
+function createClient(config) {
+  return new ClarityXOClient(config);
+}
+
+export {
+  CONTRACT_NAME,
+  MAINNET_API,
+  TESTNET_API,
+  DEFAULT_LEADERBOARD_API,
+  CONTRACT_FUNCTIONS,
+  getBoardState,
+  getGameStatus,
+  getWinner,
+  getCurrentTurn,
+  isValidMove,
+  getFullGameState,
+  startNewGame,
+  makeMove,
+  resignGame,
+  getLeaderboard,
+  submitResult,
+  syncLeaderboard,
+  healthCheck,
+  ClarityXOClient,
+  createClient
+};