# API Usage Guide

## Authentication Endpoints

### Login
**POST** `/auth/login`

Start OAuth authentication with a Bluesky handle, DID, or PDS URL.

```bash
curl -X POST http://localhost:5173/auth/login \
  -H "Content-Type: application/json" \
  -d '{"handle":"alice.bsky.social"}'
```

**Response:** Redirects to OAuth authorization page

---

### Logout
**POST** `/auth/logout`

Revoke OAuth tokens and clear session.

```bash
curl -X POST http://localhost:5173/auth/logout \
  --cookie "go_session=..."
```

**Response:** Redirects to home page

---

## Game Endpoints

### Create Game
**POST** `/api/games`

Create a new Go game. Requires authentication.

```bash
curl -X POST http://localhost:5173/api/games \
  -H "Content-Type: application/json" \
  --cookie "go_session=..." \
  -d '{"boardSize": 19}'
```

**Request Body:**
```json
{
  "boardSize": 9 | 13 | 19  // Optional, defaults to 19
}
```

**Response:**
```json
{
  "gameId": "3l4k5j6h7g8f9",
  "uri": "at://did:plc:abc123/boo.sky.go.game/3l4k5j6h7g8f9"
}
```

---

### Join Game
**POST** `/api/games/[id]/join`

Join an existing game as the second player.

```bash
curl -X POST http://localhost:5173/api/games/3l4k5j6h7g8f9/join \
  --cookie "go_session=..."
```

**Response:**
```json
{
  "success": true
}
```

**Errors:**
- `401` - Not authenticated
- `404` - Game not found
- `400` - Game not in "waiting" status
- `400` - Cannot join own game
- `400` - Game already has two players

---

### Make Move
**POST** `/api/games/[id]/move`

Place a stone on the board.

```bash
curl -X POST http://localhost:5173/api/games/3l4k5j6h7g8f9/move \
  -H "Content-Type: application/json" \
  --cookie "go_session=..." \
  -d '{"x": 3, "y": 3, "captureCount": 0}'
```

**Request Body:**
```json
{
  "x": 0-18,          // Column position (0-based)
  "y": 0-18,          // Row position (0-based)
  "captureCount": 0   // Number of stones captured by this move
}
```

**Response:**
```json
{
  "success": true,
  "uri": "at://did:plc:abc123/boo.sky.go.move/3l4k5j6h7g8f9"
}
```

**Move Rules:**
- Black plays first (player one)
- Players alternate turns
- Game must be "active" (two players joined)
- Must be your turn

---

### Pass Turn
**POST** `/api/games/[id]/pass`

Pass your turn without placing a stone.

```bash
curl -X POST http://localhost:5173/api/games/3l4k5j6h7g8f9/pass \
  --cookie "go_session=..."
```

**Response:**
```json
{
  "success": true,
  "uri": "at://did:plc:abc123/boo.sky.go.pass/3l4k5j6h7g8f9"
}
```

**Special Behavior:**
- Two consecutive passes end the game
- Game status changes to "completed"

---

## OAuth Metadata Endpoints

### Client Metadata
**GET** `/oauth-client-metadata.json`

Returns OAuth client metadata for discovery.

```bash
curl http://localhost:5173/oauth-client-metadata.json
```

---

### JWKS (Public Keys)
**GET** `/jwks.json`

Returns JSON Web Key Set for token verification.

```bash
curl http://localhost:5173/jwks.json
```

---

## Using the UI

### Create a Game
1. Log in with your Bluesky handle
2. On the home page, select board size (9x9, 13x13, or 19x19)
3. Click "Create Game"
4. Your game appears in the "Waiting for Players" list

### Join a Game
1. Log in with your Bluesky handle
2. Browse the list of waiting games
3. Click "Join" on any game
4. You'll be redirected to the game board

### Play
1. Click on the board to place stones
2. Click "Pass" to skip your turn
3. Two consecutive passes end the game

---

## Game States

- **waiting** - Game created, waiting for second player
- **active** - Two players joined, game in progress
- **completed** - Game ended (two passes or manual completion)

---

## Testing Flow

```bash
# 1. Create a game
GAME_ID=$(curl -X POST http://localhost:5173/api/games \
  -H "Content-Type: application/json" \
  --cookie "go_session=YOUR_SESSION_1" \
  -d '{"boardSize": 9}' | jq -r '.gameId')

echo "Created game: $GAME_ID"

# 2. Join with second player
curl -X POST http://localhost:5173/api/games/$GAME_ID/join \
  --cookie "go_session=YOUR_SESSION_2"

# 3. Player 1 makes first move (black)
curl -X POST http://localhost:5173/api/games/$GAME_ID/move \
  -H "Content-Type: application/json" \
  --cookie "go_session=YOUR_SESSION_1" \
  -d '{"x": 3, "y": 3, "captureCount": 0}'

# 4. Player 2 makes move (white)
curl -X POST http://localhost:5173/api/games/$GAME_ID/move \
  -H "Content-Type: application/json" \
  --cookie "go_session=YOUR_SESSION_2" \
  -d '{"x": 3, "y": 4, "captureCount": 0}'

# 5. Pass to end game (both players)
curl -X POST http://localhost:5173/api/games/$GAME_ID/pass \
  --cookie "go_session=YOUR_SESSION_1"

curl -X POST http://localhost:5173/api/games/$GAME_ID/pass \
  --cookie "go_session=YOUR_SESSION_2"
```

---

## Error Codes

- `400` - Bad request (invalid parameters, validation failed)
- `401` - Not authenticated (missing or invalid session)
- `404` - Resource not found
- `500` - Server error

All error responses include a message describing the issue.