goose.art
extremely claude-assisted go game based on atproto! working on cleaning up and giving a more unique design, still has a bit of a slop vibe to it.
1# API Usage Guide
2
3## Authentication Endpoints
4
5### Login
6**POST** `/auth/login`
7
8Start OAuth authentication with a Bluesky handle, DID, or PDS URL.
9
10```bash
11curl -X POST http://localhost:5173/auth/login \
12 -H "Content-Type: application/json" \
13 -d '{"handle":"alice.bsky.social"}'
14```
15
16**Response:** Redirects to OAuth authorization page
17
18---
19
20### Logout
21**POST** `/auth/logout`
22
23Revoke OAuth tokens and clear session.
24
25```bash
26curl -X POST http://localhost:5173/auth/logout \
27 --cookie "go_session=..."
28```
29
30**Response:** Redirects to home page
31
32---
33
34## Game Endpoints
35
36### Create Game
37**POST** `/api/games`
38
39Create a new Go game. Requires authentication.
40
41```bash
42curl -X POST http://localhost:5173/api/games \
43 -H "Content-Type: application/json" \
44 --cookie "go_session=..." \
45 -d '{"boardSize": 19}'
46```
47
48**Request Body:**
49```json
50{
51 "boardSize": 9 | 13 | 19 // Optional, defaults to 19
52}
53```
54
55**Response:**
56```json
57{
58 "gameId": "3l4k5j6h7g8f9",
59 "uri": "at://did:plc:abc123/boo.sky.go.game/3l4k5j6h7g8f9"
60}
61```
62
63---
64
65### Join Game
66**POST** `/api/games/[id]/join`
67
68Join an existing game as the second player.
69
70```bash
71curl -X POST http://localhost:5173/api/games/3l4k5j6h7g8f9/join \
72 --cookie "go_session=..."
73```
74
75**Response:**
76```json
77{
78 "success": true
79}
80```
81
82**Errors:**
83- `401` - Not authenticated
84- `404` - Game not found
85- `400` - Game not in "waiting" status
86- `400` - Cannot join own game
87- `400` - Game already has two players
88
89---
90
91### Make Move
92**POST** `/api/games/[id]/move`
93
94Place a stone on the board.
95
96```bash
97curl -X POST http://localhost:5173/api/games/3l4k5j6h7g8f9/move \
98 -H "Content-Type: application/json" \
99 --cookie "go_session=..." \
100 -d '{"x": 3, "y": 3, "captureCount": 0}'
101```
102
103**Request Body:**
104```json
105{
106 "x": 0-18, // Column position (0-based)
107 "y": 0-18, // Row position (0-based)
108 "captureCount": 0 // Number of stones captured by this move
109}
110```
111
112**Response:**
113```json
114{
115 "success": true,
116 "uri": "at://did:plc:abc123/boo.sky.go.move/3l4k5j6h7g8f9"
117}
118```
119
120**Move Rules:**
121- Black plays first (player one)
122- Players alternate turns
123- Game must be "active" (two players joined)
124- Must be your turn
125
126---
127
128### Pass Turn
129**POST** `/api/games/[id]/pass`
130
131Pass your turn without placing a stone.
132
133```bash
134curl -X POST http://localhost:5173/api/games/3l4k5j6h7g8f9/pass \
135 --cookie "go_session=..."
136```
137
138**Response:**
139```json
140{
141 "success": true,
142 "uri": "at://did:plc:abc123/boo.sky.go.pass/3l4k5j6h7g8f9"
143}
144```
145
146**Special Behavior:**
147- Two consecutive passes end the game
148- Game status changes to "completed"
149
150---
151
152## OAuth Metadata Endpoints
153
154### Client Metadata
155**GET** `/oauth-client-metadata.json`
156
157Returns OAuth client metadata for discovery.
158
159```bash
160curl http://localhost:5173/oauth-client-metadata.json
161```
162
163---
164
165### JWKS (Public Keys)
166**GET** `/jwks.json`
167
168Returns JSON Web Key Set for token verification.
169
170```bash
171curl http://localhost:5173/jwks.json
172```
173
174---
175
176## Using the UI
177
178### Create a Game
1791. Log in with your Bluesky handle
1802. On the home page, select board size (9x9, 13x13, or 19x19)
1813. Click "Create Game"
1824. Your game appears in the "Waiting for Players" list
183
184### Join a Game
1851. Log in with your Bluesky handle
1862. Browse the list of waiting games
1873. Click "Join" on any game
1884. You'll be redirected to the game board
189
190### Play
1911. Click on the board to place stones
1922. Click "Pass" to skip your turn
1933. Two consecutive passes end the game
194
195---
196
197## Game States
198
199- **waiting** - Game created, waiting for second player
200- **active** - Two players joined, game in progress
201- **completed** - Game ended (two passes or manual completion)
202
203---
204
205## Testing Flow
206
207```bash
208# 1. Create a game
209GAME_ID=$(curl -X POST http://localhost:5173/api/games \
210 -H "Content-Type: application/json" \
211 --cookie "go_session=YOUR_SESSION_1" \
212 -d '{"boardSize": 9}' | jq -r '.gameId')
213
214echo "Created game: $GAME_ID"
215
216# 2. Join with second player
217curl -X POST http://localhost:5173/api/games/$GAME_ID/join \
218 --cookie "go_session=YOUR_SESSION_2"
219
220# 3. Player 1 makes first move (black)
221curl -X POST http://localhost:5173/api/games/$GAME_ID/move \
222 -H "Content-Type: application/json" \
223 --cookie "go_session=YOUR_SESSION_1" \
224 -d '{"x": 3, "y": 3, "captureCount": 0}'
225
226# 4. Player 2 makes move (white)
227curl -X POST http://localhost:5173/api/games/$GAME_ID/move \
228 -H "Content-Type: application/json" \
229 --cookie "go_session=YOUR_SESSION_2" \
230 -d '{"x": 3, "y": 4, "captureCount": 0}'
231
232# 5. Pass to end game (both players)
233curl -X POST http://localhost:5173/api/games/$GAME_ID/pass \
234 --cookie "go_session=YOUR_SESSION_1"
235
236curl -X POST http://localhost:5173/api/games/$GAME_ID/pass \
237 --cookie "go_session=YOUR_SESSION_2"
238```
239
240---
241
242## Error Codes
243
244- `400` - Bad request (invalid parameters, validation failed)
245- `401` - Not authenticated (missing or invalid session)
246- `404` - Resource not found
247- `500` - Server error
248
249All error responses include a message describing the issue.