# WoW Character Manager - Addon API Documentation

This document describes the API endpoints available for WoW addon integration. The addon API allows external applications (such as a WoW addon) to read and update character data.

## Authentication

All addon API endpoints require **Bearer Token** authentication. 

### Getting a Token

1. Log into the WoW Character Manager web application
2. Go to **Settings** (gear icon)
3. Find the **WoW Addon API** section
4. Click **Generate API Token**
5. Copy the token immediately - it will only be shown once!

### Using the Token

Include the token in the `Authorization` header for all API requests:

```http
Authorization: Bearer YOUR_TOKEN_HERE
```

### Token Management

- **Enable/Disable**: You can temporarily disable your token without deleting it
- **Regenerate**: Generate a new token (invalidates the old one)
- **Revoke**: Permanently delete your token

---

## Rate Limiting

All addon API endpoints are rate-limited to **300 requests per minute** per client IP.

---

## API Endpoints

### Base URL

```
https://your-server.com/api/addon
```

---

## Characters

### Game Versions

The `version` field accepts exactly these values (case-insensitive). Any other value is rejected with HTTP 400 and an error message listing the supported versions.

| Value | Game | Realm |
|-------|------|-------|
| `retail` | Retail | required |
| `classic_era` | Classic Era | required |
| `classic` | Classic (Progression, currently Mists of Pandaria) | required |
| `anniversary` | TBC Anniversary | required |
| `forever` | WoW Forever (experimental) | not used, requires `surname` |

WoW Forever characters have no realm. They are identified by `name` (first name) and `surname`. Realm-based endpoints such as `/api/realms` return HTTP 400 for `forever`. The addon sync does not accept `forever` yet.

### List All Characters

```http
GET /api/addon/characters
```

Returns all characters belonging to the authenticated user.

**Response:**
```json
{
  "success": true,
  "characters": [
    {
      "id": 1,
      "name": "Thrall",
      "realm": "stormrage",
      "region": "us",
      "faction": "Horde",
      "race": "Orc",
      "class": "Shaman",
      "level": 70,
      "item_level": 489,
      "version": "retail",
      "main_task1": "Farm gold",
      "main_task2": "Do M+",
      "main_task3": null,
      "last_updated": "2024-01-15T10:30:00Z"
    }
  ]
}
```

---

### Get Character Details

```http
GET /api/addon/characters/:id
```

Returns detailed information for a specific character, including professions, notes, and reputations.

**Parameters:**
- `id` (path) - Character ID

**Response:**
```json
{
  "success": true,
  "character": {
    "id": 1,
    "name": "Thrall",
    "realm": "stormrage",
    "region": "us",
    "faction": "Horde",
    "race": "Orc",
    "class": "Shaman",
    "level": 70,
    "item_level": 489,
    "version": "retail",
    "main_task1": "Farm gold",
    "main_task2": "Do M+",
    "main_task3": null,
    "last_updated": "2024-01-15T10:30:00Z"
  },
  "professions": [
    {
      "profession_name": "Mining",
      "profession_type": "primary",
      "tier_name": "Dragon Isles Mining",
      "skill_level": 100,
      "max_skill_level": 100
    }
  ],
  "notes": [
    {
      "id": 1,
      "note_text": "Remember to do weekly raid",
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-10T08:00:00Z"
    }
  ],
  "reputations": [
    {
      "faction_name": "Valdrakken Accord",
      "standing_name": "Exalted",
      "standing_value": 21000,
      "standing_max": 21000
    }
  ]
}
```

---

### Update Character Main Tasks

```http
PUT /api/addon/characters/:id/tasks
```

Update the main tasks (roles/purposes) for a character.

**Parameters:**
- `id` (path) - Character ID

**Request Body:**
```json
{
  "main_task1": "Farm gold",
  "main_task2": "Run mythic+",
  "main_task3": "PvP arenas"
}
```

**Constraints:**
- Each task must be 50 characters or less
- All fields are optional (pass `null` to clear)

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

---

## Notes

### Get Character Notes

```http
GET /api/addon/characters/:id/notes
```

Returns all notes for a specific character.

**Parameters:**
- `id` (path) - Character ID

**Response:**
```json
{
  "success": true,
  "notes": [
    {
      "id": 1,
      "note_text": "Remember to do weekly raid",
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-10T08:00:00Z"
    }
  ]
}
```

---

### Add Note

```http
POST /api/addon/characters/:id/notes
```

Add a new note to a character.

**Parameters:**
- `id` (path) - Character ID

**Request Body:**
```json
{
  "noteText": "This is a new note from the addon"
}
```

**Constraints:**
- Maximum 5000 characters

**Response:**
```json
{
  "success": true,
  "noteId": 5
}
```

---

### Update Note

```http
PUT /api/addon/notes/:id
```

Update an existing note.

**Parameters:**
- `id` (path) - Note ID

**Request Body:**
```json
{
  "noteText": "Updated note content"
}
```

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

---

### Delete Note

```http
DELETE /api/addon/notes/:id
```

Delete a note.

**Parameters:**
- `id` (path) - Note ID

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

---

## Tasks (Dailies & Weeklies)

### Get All Tasks

```http
GET /api/addon/tasks
```

Returns all daily and weekly tasks for the user.

**Response:**
```json
{
  "success": true,
  "tasks": [
    {
      "id": 1,
      "character_id": 1,
      "character_name": "Thrall",
      "task_type": "custom",
      "title": "Complete Daily Quests",
      "description": "Do the daily hub quests",
      "reset_type": "daily",
      "is_completed": false,
      "last_reset": null,
      "created_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": 2,
      "character_id": 1,
      "character_name": "Thrall",
      "task_type": "custom",
      "title": "Weekly Vault",
      "description": "Complete M+ for vault",
      "reset_type": "weekly",
      "is_completed": true,
      "last_reset": "2024-01-14T00:00:00Z",
      "created_at": "2024-01-10T10:00:00Z"
    }
  ]
}
```

---

### Get Character Tasks

```http
GET /api/addon/characters/:id/tasks
```

Returns tasks for a specific character (including global tasks).

**Parameters:**
- `id` (path) - Character ID

**Response:** Same format as "Get All Tasks"

---

### Toggle Task Completion

```http
POST /api/addon/tasks/:id/toggle
```

Toggle a task between completed and incomplete.

**Parameters:**
- `id` (path) - Task ID

**Response:**
```json
{
  "success": true,
  "is_completed": 1
}
```

---

## Error Responses

All endpoints may return error responses in this format:

```json
{
  "error": "Error message here"
}
```

### Common Error Codes

| Status | Description |
|--------|-------------|
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Missing or invalid token |
| 404 | Not Found - Resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error |

---

## Example: WoW Addon Integration (Lua)

Here's a conceptual example of how you might integrate this API with a WoW addon:

```lua
-- WoWCharManagerAddon.lua
local API_URL = "https://your-server.com/api/addon"
local API_TOKEN = "your-token-here"

-- Note: WoW addons cannot make HTTP requests directly.
-- You would need to use an external companion app or 
-- WeakAuras web integration to bridge the gap.

-- The addon could:
-- 1. Display data from a local cache file
-- 2. Export current character info to a file
-- 3. Use a companion app to sync with the API
```

---

## Changelog

### v1.0.0 (Initial Release)
- Character listing and details
- Main tasks management  
- Notes CRUD operations
- Daily/Weekly tasks with toggle

---

## Support

For issues or feature requests, please visit the project repository or contact the administrator.
