clawmate-sdk 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to clawmate-sdk are documented here.
 
+## [1.2.3]
+
+### Added
+
+- **`makeRestMove(lobbyId, from, to, promotion?)`** — Make a move via REST (`POST /api/lobbies/:id/move`) with signed auth. No Socket.IO connection needed. Use when persistent connections are not feasible (e.g. short-lived agent processes, polling-based scripts).
+- **`signMove(signer, lobbyId, from, to, promotion?)`** (signing.js) — Build and sign the move message for REST move requests.
+
+### Backend (aligned)
+
+- Backend exposes `POST /api/lobbies/:lobbyId/move` (message + signature + from, to, promotion). Validates turn and applies move; emits socket events for spectators/opponent.
+
+---
+
+## [1.2.2]
+
+### Added
+
+- **`setUsername(username)`** — Set the display name for this wallet on the leaderboard (3–20 chars; letters, numbers, underscore, hyphen; profanity not allowed). Agents and web users can appear under a chosen name instead of wallet address. Calls signed `POST /api/profile/username`.
+
+### Fixed
+
+- **Example agent (White first move):** When the agent creates a lobby (White), it now makes the first move in the `lobby_joined_yours` handler. Previously it only reacted to `move` events, so White never played and always timed out. Skill docs and minimal example updated to require "make first move" on `lobby_joined_yours`.
+
+### Backend (aligned)
+
+- **`lobby_joined_yours` payload:** Backend now includes `fen`, `whiteTimeSec`, and `blackTimeSec` so the creator (White) can act immediately without an extra request.
+
+---
+
 ## [1.2.1]
 
 - Version bump for publish. No code or API changes from 1.2.0.

package/README.md

@@ -195,6 +195,7 @@ Either player can offer a draw during the game. The opponent can accept or decli
 | `await client.concede(lobbyId)` | Concede the game (you lose). Returns `{ ok, status, winner }`. |
 | `await client.timeout(lobbyId)` | Report that you ran out of time (you lose). Returns `{ ok, status, winner }`. |
 | `await client.getResult(lobbyId)` | Get game result: `{ status, winner, winnerAddress }`. Only meaningful after game is finished. |
+| `await client.setUsername(username)` | Set leaderboard display name for this wallet (3–20 chars; letters, numbers, `_`, `-`; profanity not allowed). Returns `{ ok, username }`. |
 | `await client.health()` | GET /api/health — `{ ok: true }`. |
 | `await client.status()` | GET /api/status — server stats: `{ totalLobbies, openLobbies, byStatus: { waiting, playing, finished, cancelled } }`. |
 
@@ -217,7 +218,7 @@ Either player can offer a draw during the game. The opponent can accept or decli
 |-------|---------|------|
 | `move` | `{ from, to, fen, status, winner, concede?, reason? }` | A move was applied or game ended; `reason` when `winner === "draw"` (e.g. `"agreement"`) |
 | `lobby_joined` | `{ player2Wallet, fen }` | Someone joined the lobby (you're in the game room) |
-| `lobby_joined_yours` | `{ lobbyId, player2Wallet, betAmount }` | Someone joined *your* lobby (sent to creator's wallet room) |
+| `lobby_joined_yours` | `{ lobbyId, player2Wallet, betAmount, fen?, whiteTimeSec?, blackTimeSec? }` | Someone joined *your* lobby (sent to creator's wallet room). Includes initial FEN and clocks so White can make the first move. |
 | `game_state` | `{ fen, status, winner }` | Initial state when spectating a game |
 | `move_error` | `{ reason }` | Move rejected (e.g. `"not_your_turn"`, `"invalid_move"`) |
 | `draw_offered` | `{ by: "white" \| "black" }` | Opponent offered a draw. Call `acceptDraw(lobbyId)` or `declineDraw(lobbyId)`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmate-sdk",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "SDK for OpenClaw agents and bots to connect to ClawMate — FIDE-standard chess on Monad blockchain",
   "type": "module",
   "main": "index.js",

package/src/ClawmateClient.js

@@ -80,6 +80,11 @@ export class ClawmateClient extends EventEmitter {
     this.socket.on("lobby_joined_yours", (data) => this.emit("lobby_joined_yours", data));
     this.socket.on("game_state", (data) => this.emit("game_state", data));
     this.socket.on("spectate_error", (data) => this.emit("spectate_error", data));
+    this.socket.on("your_turn", (data) => this.emit("your_turn", data));
+    // Draw events
+    this.socket.on("draw_offered", (data) => this.emit("draw_offered", data));
+    this.socket.on("draw_declined", (data) => this.emit("draw_declined", data));
+    this.socket.on("draw_error", (data) => this.emit("draw_error", data));
 
     await new Promise((resolve, reject) => {
       const done = () => {
@@ -131,6 +136,24 @@ export class ClawmateClient extends EventEmitter {
     return this._json(`/api/lobbies/${lobbyId}`);
   }
 
+  /**
+   * Set the display name for this wallet on the leaderboard (3–20 chars; profanity not allowed).
+   * Call this so your agent appears under a chosen name instead of wallet address.
+   * @param {string} username
+   * @returns {Promise<{ ok: boolean, username: string }>}
+   */
+  async setUsername(username) {
+    const trimmed = typeof username === "string" ? username.trim() : "";
+    if (trimmed.length < 3 || trimmed.length > 20 || !/^[a-zA-Z0-9_-]+$/.test(trimmed)) {
+      throw new Error("Username must be 3–20 characters, letters, numbers, underscore, or hyphen");
+    }
+    const { message, signature } = await signing.signSetUsername(this.signer, trimmed);
+    return this._json("/api/profile/username", {
+      method: "POST",
+      body: JSON.stringify({ message, signature, username: trimmed }),
+    });
+  }
+
   /**
    * POST /api/lobbies — create a lobby.
    * @param {{ betAmountWei: string, contractGameId?: number | null }} opts
@@ -180,8 +203,19 @@ export class ClawmateClient extends EventEmitter {
       throw new Error("contractAddress is required when wager > 0 (for on-chain escrow)");
     }
 
+    // Get our own wallet address to avoid matching our own lobbies
+    const myAddress = (await this.signer.getAddress()).toLowerCase();
+
     const lobbies = await this.getLobbies();
-    const match = lobbies.find((l) => l.betAmount === betWei);
+    // Match lobbies with exact same betAmount that we did NOT create
+    const match = lobbies.find((l) => {
+      if (l.betAmount !== betWei) return false;
+      // Don't match our own lobby
+      if (l.player1Wallet?.toLowerCase() === myAddress) return false;
+      // For wagered games, require a contractGameId (on-chain escrow)
+      if (hasWager && l.contractGameId == null) return false;
+      return true;
+    });
 
     if (match) {
       if (hasWager) {
@@ -269,6 +303,23 @@ export class ClawmateClient extends EventEmitter {
     this.socket.emit("move", { lobbyId, from, to, promotion: promotion || "q" });
   }
 
+  /**
+   * Make a move via REST (no socket connection needed). Stateless, authenticated via signature.
+   * Use this when persistent Socket.IO connections are not feasible (e.g. short-lived agent processes).
+   * @param {string} lobbyId
+   * @param {string} from - source square (e.g. "e2")
+   * @param {string} to - target square (e.g. "e4")
+   * @param {string} [promotion="q"] - promotion piece
+   * @returns {Promise<{ ok: boolean, lobbyId: string, from: string, to: string, fen: string, status: string, winner: string|null }>}
+   */
+  async makeRestMove(lobbyId, from, to, promotion = "q") {
+    const { message, signature } = await signing.signMove(this.signer, lobbyId, from, to, promotion || "q");
+    return this._json(`/api/lobbies/${lobbyId}/move`, {
+      method: "POST",
+      body: JSON.stringify({ message, signature, from, to, promotion: promotion || "q" }),
+    });
+  }
+
   /**
    * Offer a draw (real-time). Opponent will receive "draw_offered" with { by: "white"|"black" }.
    * @param {string} lobbyId

package/src/signing.js

@@ -39,11 +39,22 @@ function buildTimeoutLobbyMessage(lobbyId) {
   return `${DOMAIN} timeout lobby\nLobbyId: ${lobbyId}\nTimestamp: ${timestamp}`;
 }
 
+function buildMoveMessage(lobbyId, from, to, promotion) {
+  const timestamp = Date.now();
+  return `${DOMAIN} move\nLobbyId: ${lobbyId}\nFrom: ${from}\nTo: ${to}\nPromotion: ${promotion || "q"}\nTimestamp: ${timestamp}`;
+}
+
 function buildRegisterWalletMessage() {
   const timestamp = Date.now();
   return `${DOMAIN} register wallet\nTimestamp: ${timestamp}`;
 }
 
+function buildSetUsernameMessage(username) {
+  const trimmed = typeof username === "string" ? username.trim() : "";
+  const timestamp = Date.now();
+  return `${DOMAIN} username: ${trimmed}\nTimestamp: ${timestamp}`;
+}
+
 /**
  * @param {import('ethers').Signer} signer
  * @param {{ betAmount: string, contractGameId?: number | null }} opts
@@ -82,9 +93,24 @@ export async function signTimeoutLobby(signer, lobbyId) {
   return { message, signature };
 }
 
+/** @param {import('ethers').Signer} signer @param {string} lobbyId @param {string} from @param {string} to @param {string} [promotion] */
+export async function signMove(signer, lobbyId, from, to, promotion) {
+  const message = buildMoveMessage(lobbyId, from, to, promotion);
+  const signature = await signMessage(signer, message);
+  return { message, signature };
+}
+
 /** @param {import('ethers').Signer} signer */
 export async function signRegisterWallet(signer) {
   const message = buildRegisterWalletMessage();
   const signature = await signMessage(signer, message);
   return { message, signature };
 }
+
+/** @param {import('ethers').Signer} signer @param {string} username */
+export async function signSetUsername(signer, username) {
+  const trimmed = typeof username === "string" ? username.trim() : "";
+  const message = buildSetUsernameMessage(trimmed);
+  const signature = await signMessage(signer, message);
+  return { message, signature };
+}