dwroller/docs/api.md

# API Documentation

## Base URL

```
http://localhost:5000/api
```

## Authentication

Most endpoints require authentication via session cookies.

### Session Management

```bash
# Login (example)
POST /api/auth/login
Content-Type: application/json

{
  "email": "player@example.com",
  "password": "secret"
}
```

## Players Endpoints

### Get All Players

```bash
GET /api/players
```

**Response:**

```json
[
  {
    "id": 1,
    "name": "Player One",
    "xp": 1500,
    "rp": 500,
    "renown": 10,
    "createdAt": "2025-08-16T10:00:00Z"
  }
]
```

### Create Player (GM Only)

```bash
POST /api/players
Authorization: Bearer {gm-token}
```

**Request:**

```json
{
  "name": "New Player",
  "xp": 0,
  "rp": 100,
  "renown": 0
}
```

### Update Player

```bash
PUT /api/players/:id
Authorization: Bearer {gm-token}
```

**Request:**

```json
{
  "xp": 1600,
  "rp": 600
}
```

### Delete Player (GM Only)

```bash
DELETE /api/players/:id
Authorization: Bearer {gm-token}
```

### Reset Password

```bash
POST /api/players/:id/reset-password
Authorization: Bearer {gm-token}
```

## Shop Endpoints

### Get Shop Inventory

```bash
GET /api/shop
```

**Response:**

```json
[
  {
    "id": 1,
    "name": "Blade",
    "type": "weapon",
    "cost": 100,
    "stats": {
      "damage": "1d10",
      "weight": 3
    }
  }
]
```

### Purchase Item

```bash
POST /api/shop/purchase
```

**Request:**

```json
{
  "itemId": 1,
  "quantity": 1
}
```

### Get Player Inventory

```bash
GET /api/inventory
```

**Response:**

```json
[
  {
    "itemId": 1,
    "item": {
      "name": "Blade",
      "stats": {...}
    },
    "quantity": 1
  }
]
```

## Bestiary Endpoints

### Get All Creatures

```bash
GET /api/bestiary
```

**Response:**

```json
[
  {
    "id": 1,
    "name": "Ghoul",
    "type": "abomination",
    "hp": 45,
    "armor": 10,
    "weaknesses": ["acid", "piercing"],
    "description": "Corrupted abomination..."
  }
]
```

### Get Creature by ID

```bash
GET /api/bestiary/:id
```

### Search Creatures

```bash
GET /api/bestiary/search?query=ghoul&type=abomination
```

## Rules Endpoints

### Search Rules

```bash
GET /api/rules/search?query=damage
```

**Response:**

```json
[
  {
    "title": "Damage Mechanics",
    "content": "...",
    "page": "combat_damage"
  }
]
```

### Get Rules Page

```bash
GET /api/rules/page/:pageId
```

### Print Rulesheet

```bash
GET /api/rules/print/quick-reference
```

Returns printable HTML for the quick reference.

## Sessions Endpoints

### Create Session

```bash
POST /api/sessions
```

**Request:**

```json
{
  "title": "Session 1",
  "date": "2026-04-19",
  "notes": "First session",
  "location": "The Ruins"
}
```

### Get Sessions

```bash
GET /api/sessions?date=2026-04-19
```

### Get Session by ID

```bash
GET /api/sessions/:id
```

### Update Session

```bash
PUT /api/sessions/:id
```

**Request:**

```json
{
  "notes": "Updated notes",
  "location": "The Ruins"
}
```

### Delete Session

```bash
DELETE /api/sessions/:id
```

## Files Endpoints

### Upload File

```bash
POST /api/files/upload
Content-Type: multipart/form-data
```

**Form Data:**

- `file`: The file to upload

### Get File

```bash
GET /api/files/:filename
```

### Delete File

```bash
DELETE /api/files/:filename
```

### List Files

```bash
GET /api/files
```

## Error Handling

### Standard Responses

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error",
    "details": "Additional details"
  }
}
```

### Common Errors

| Code | Description |
|------|-------------|
| `UNAUTHORIZED` | Invalid or missing session |
| `FORBIDDEN` | Insufficient permissions |
| `NOT_FOUND` | Resource doesn't exist |
| `VALIDATION_ERROR` | Invalid input data |
| `INTERNAL_ERROR` | Server error |

### Error Examples

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}
```

## Rate Limiting

API calls are rate limited:
- **100 requests per minute** per IP
- Headers include:
  - `X-RateLimit-Limit: 100`
  - `X-RateLimit-Remaining: 99`

## Webhooks

Webhooks can be configured for events:
- Player created
- Item purchased
- Session created

```bash
POST /api/webhooks
```

**Request:**

```json
{
  "url": "https://example.com/webhook",
  "events": ["player.created", "item.purchased"],
  "secret": "your-webhook-secret"
}
```

## Testing with curl

### Get Players

```bash
curl http://localhost:5000/api/players
```

### Get Shop

```bash
curl http://localhost:5000/api/shop
```

### Get Bestiary

```bash
curl http://localhost:5000/api/bestiary
```

### Search Rules

```bash
curl "http://localhost:5000/api/rules/search?query=damage"
```