# Gamification API Endpoints

This document outlines the API endpoints available for the gamification features of the application. All endpoints require authentication.

## Avatar Endpoints

### Get Avatar Types

Retrieves all available avatar types in the system.

**Endpoint:** `GET /api/v1/gamification/avatars/types`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "success": true,
  "message": "Avatar types retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Wizard",
      "description": "A powerful magic user",
      "image_url": "/storage/avatars/wizard.png"
    },
    {
      "id": 2,
      "name": "Warrior",
      "description": "A mighty fighter",
      "image_url": "/storage/avatars/warrior.png"
    }
  ]
}
```

### Get Active Avatar

Retrieves the customer's currently active avatar.

**Endpoint:** `GET /api/v1/gamification/avatars/active`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "success": true,
  "message": "Active avatar retrieved successfully",
  "data": {
    "id": 5,
    "type": {
      "id": 1,
      "name": "Wizard"
    },
    "is_active": true,
    "current_level": 3,
    "experience_points": 340,
    "next_level_points": 500,
    "progress_percentage": 68
  }
}
```

### Get Customer Avatars

Retrieves all avatars owned by the authenticated customer.

**Endpoint:** `GET /api/v1/gamification/avatars`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "success": true,
  "message": "Customer avatars retrieved successfully",
  "data": [
    {
      "id": 5,
      "type": {
        "id": 1,
        "name": "Wizard"
      },
      "is_active": true,
      "current_level": 3,
      "experience_points": 340
    },
    {
      "id": 8,
      "type": {
        "id": 2,
        "name": "Warrior"
      },
      "is_active": false,
      "current_level": 2,
      "experience_points": 220
    }
  ]
}
```

### Select Avatar

Sets the specified avatar as the customer's active avatar.

**Endpoint:** `POST /api/v1/gamification/avatars/select`

**Authentication:** Required (Customer)

**Request Body:**
```json
{
  "avatar_id": 8
}
```

**Response:**
```json
{
  "success": true,
  "message": "Avatar selected successfully",
  "data": {
    "id": 8,
    "type": {
      "id": 2,
      "name": "Warrior"
    },
    "is_active": true,
    "current_level": 2,
    "experience_points": 220
  }
}
```

## Quest Endpoints

### Get Available Quests

Retrieves all available quests for the customer.

**Endpoint:** `GET /api/v1/gamification/quests`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "success": true,
  "message": "Quests retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Quiz Master",
      "description": "Complete 5 quizzes",
      "reward_experience": 100,
      "progress": {
        "current": 3,
        "required": 5,
        "percentage": 60
      }
    },
    {
      "id": 2,
      "name": "Perfect Score",
      "description": "Get 100% on any quiz",
      "reward_experience": 150,
      "progress": {
        "current": 0,
        "required": 1,
        "percentage": 0
      }
    }
  ]
}
```

### Get Completed Quests

Retrieves all quests completed by the customer.

**Endpoint:** `GET /api/v1/gamification/quests/completed`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "success": true,
  "message": "Completed quests retrieved successfully",
  "data": [
    {
      "id": 3,
      "name": "Quick Learner",
      "description": "Complete a quiz in under 5 minutes",
      "reward_experience": 75,
      "completed_at": "2023-06-15T14:32:18Z"
    }
  ]
}
```

## Gamification Settings

### Toggle Gamification

Toggles gamification features on or off for the authenticated customer.

**Endpoint:** `POST /api/v1/gamification/toggle`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "success": true,
  "message": "Gamification enabled successfully",
  "data": {
    "gamification_enabled": true
  }
}
```

## Stats Endpoint

### Get Gamification Stats

Retrieves comprehensive gamification statistics for the authenticated customer.

**Endpoint:** `GET /api/v1/gamification/stats`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "success": true,
  "message": "Gamification stats retrieved successfully",
  "data": {
    "gamification_enabled": true,
    "active_avatar": {
      "id": 5,
      "type": "Wizard",
      "level": 3,
      "experience": 340
    },
    "quiz_stats": {
      "total_taken": 12,
      "passed": 10,
      "pass_rate": 83.3,
      "average_score": 78.5
    },
    "quest_stats": {
      "completed": 5,
      "total": 15,
      "completion_rate": 33.3
    },
    "achievements": 7
  }
}
```

## Experience Logs

### Get Experience Logs

Retrieves paginated experience logs for the authenticated customer, with options for filtering.

**Endpoint:** `GET /api/v1/gamification/experience-logs`

**Authentication:** Required (Customer)

**Query Parameters:**
- `source_type` (optional): Filter by source type (e.g., 'quiz_completion', 'quest_completion', 'login_streak')
- `from_date` (optional): Filter logs after this date (format: YYYY-MM-DD)
- `to_date` (optional): Filter logs before this date (format: YYYY-MM-DD)
- `only_gains` (optional): Show only positive experience transactions (true/false)
- `only_losses` (optional): Show only negative experience transactions (true/false)
- `per_page` (optional): Number of logs per page (min: 5, max: 100, default: 15)

**Response:**
```json
{
  "success": true,
  "message": "Experience logs retrieved successfully",
  "data": {
    "logs": [
      {
        "id": 42,
        "amount": 350,
        "source_type": "quiz_completion",
        "description": "Completed quiz: Advanced JavaScript with score 92%",
        "created_at": "2023-06-12T14:33:21Z",
        "avatar": {
          "id": 5,
          "type": "Wizard",
          "level_change": {
            "new_level": 3,
            "previous_level": 2
          }
        },
        "metadata": {
          "quiz_stats": {
            "total": 25,
            "correct": 23,
            "incorrect": 2,
            "unanswered": 0,
            "percentage": 92.00
          },
          "quiz_name": "Advanced JavaScript",
          "quiz_type": "test",
          "time_taken": 1230000,
          "time_limit": 1800000,
          "is_passed": true,
          "score_percentage": 92.00
        }
      },
      {
        "id": 41,
        "amount": 5,
        "source_type": "correct_answer",
        "description": "Correct answer to question #156",
        "created_at": "2023-06-12T14:30:45Z",
        "avatar": {
          "id": 5,
          "type": "Wizard",
          "level_change": null
        },
        "metadata": {
          "question_id": 156,
          "question_text": "What is the output of console.log(typeof NaN)?",
          "selected_answer_id": 623,
          "is_correct": true
        }
      }
    ],
    "summary": {
      "total_gained": 1250,
      "total_lost": -50,
      "net_change": 1200
    },
    "pagination": {
      "current_page": 1,
      "last_page": 5,
      "per_page": 15,
      "total": 68
    }
  }
}
```

**Key Features:**
- Comprehensive filtering options to find specific experience sources
- Detailed metadata for each experience transaction
- Information about level ups and experience changes
- Summary statistics for the filtered period
- Pagination for navigating through large numbers of logs