# HTTP reference clients

All clients use the same server-owned game:

```text
newGame() -> Game
Game.board: number[][]
Game.move(x, y, n) -> Game
```

`x` is the zero-based **column**, `y` the zero-based **row**, and `n` is 1–9.
Read a cell with `board[y][x]`; 0 means empty. `move(2, 1, 5)` places 5 in row 1,
column 2. The wire format is `{ "row": 1, "col": 2, "value": 5 }`.

A move returns the updated Game. Use that return value in all languages:
Python/TypeScript also update the object; Lean/Haskell return a new snapshot.
The board changes only after a successful response. HTTP or transport failures
raise an error and leave the client's previous board intact. Reads are local
snapshots, not live subscriptions. Games are in memory and disappear when the
HTTP server restarts.

| File | Run | Requirements |
| --- | --- | --- |
| sudoku.ts | `bun sudoku.ts http://localhost:3000` | Bun, native fetch |
| sudoku.py | `python3 sudoku.py http://localhost:3000` | Python 3 standard library |
| Sudoku.hs | `runghc Sudoku.hs http://localhost:3000` | GHC bundled libraries, curl |
| Sudoku.lean | `lean --run Sudoku.lean http://localhost:3000` | Lean 4, curl |
| sudoku.sh | `sh sudoku.sh http://localhost:3000` | POSIX shell, curl, Python 3 |

Lean's base URL should have no trailing slash. Curl examples require a version
supporting `--fail-with-body` (7.76+). The Haskell parser intentionally targets
this API's single-field responses; it is not a general-purpose JSON parser.
Each executable creates a blank board, makes the same example move, and prints
it. Import the Python or TypeScript files to use their clients without running
that example. Haskell exports `newGame`, `newGameAt`, `board`, and `move`;
Lean supports `newGame`, `game.board`, and `game.move`.

## HTTP API

- `POST /board` → 201, `{ "id": "…" }`
- `GET /board/:id` → 200, `{ "board": [[…]] }`
- `PATCH /board/:id/turn` with `{ "row": y, "col": x, "value": n }`
  → 200, `{ "board": [[…]] }`
- Rejected moves → 400, `{ "error": "…", "examinedCells": […], "conflictingCell": { "row": …, "col": … } }`
  (`conflictingCell` is optional).
- Unknown game → 404, `{ "error": "game not found" }`.

## SSH

Use `ssh -t -p 2222 HOST` to play in your terminal. Authenticate with an SSH key.
SSH games are associated with your key for that server run; HTTP games use IDs.

Lean uses the official [process API](https://lean-lang.org/doc/reference/latest/IO/Processes/) and [JSON API](https://lean-lang.org/doc/api/Lean/Data/Json/FromToJson/Basic.html).