# Wishlist API Documentation

## Base URL
```
http://127.0.0.1:8000/api/v1/auth/wishlists
```

## Authentication
All wishlist endpoints require authentication via JWT token in the `Authorization` header:
```
Authorization: Bearer {access_token}
```

---

## Endpoints Overview

### 1. Get User Wishlist
Retrieve all products in the authenticated user's wishlist.

**Endpoint:**
```
GET /api/v1/auth/wishlists
```

**Method:** `GET`

**Authentication:** Required ✅

**Parameters:** None

**Response (200 OK):**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "product_id": 101,
      "created_at": "2025-12-20T10:30:00Z",
      "updated_at": "2025-12-20T10:30:00Z",
      "product": {
        "id": 101,
        "name": "Product Name",
        "description": "Product description",
        "price": 99.99,
        "discount_price": 79.99,
        "stock": 50,
        "rating": 4.5,
        "image": "https://example.com/product.jpg",
        "gallery": [...],
        "is_wishlist": true,
        "category": {...}
      }
    }
  ]
}
```

---

### 2. Add Product to Wishlist
Add a single product to the authenticated user's wishlist.

**Endpoint:**
```
POST /api/v1/auth/wishlists
```

**Method:** `POST`

**Authentication:** Required ✅

**Request Body:**
```json
{
  "product_id": 101
}
```

**Validation:**
- `product_id` - Required, must exist in products table

**Response (201 Created) - Product Added:**
```json
{
  "success": true,
  "message": "Product added to wishlist.",
  "data": {
    "id": 101,
    "name": "Product Name",
    "description": "Product description",
    "price": 99.99,
    "discount_price": 79.99,
    "stock": 50,
    "rating": 4.5,
    "image": "https://example.com/product.jpg",
    "gallery": [...],
    "is_wishlist": true,
    "category": {...}
  }
}
```

**Response (200 OK) - Already in Wishlist:**
```json
{
  "success": true,
  "message": "Product is already in your wishlist."
}
```

**Response (422 Unprocessable Entity) - Validation Error:**
```json
{
  "success": false,
  "errors": {
    "product_id": ["The product_id field is required."]
  }
}
```

---

### 3. Toggle Product in Wishlist ⭐
Toggle a product in the wishlist. If the product is already in the wishlist, it will be removed. If it's not, it will be added.

**Endpoint:**
```
POST /api/v1/auth/wishlists/toggle
```

**Method:** `POST`

**Authentication:** Required ✅

**Request Body:**
```json
{
  "product_id": 101
}
```

**Validation:**
- `product_id` - Required, must exist in products table

**Response (200 OK) - Product Added to Wishlist:**
```json
{
  "success": true,
  "is_wishlist": true,
  "message": "Product added to wishlist."
}
```

**Response (200 OK) - Product Removed from Wishlist:**
```json
{
  "success": true,
  "is_wishlist": false,
  "message": "Product removed from wishlist."
}
```

**Response (422 Unprocessable Entity) - Validation Error:**
```json
{
  "success": false,
  "errors": {
    "product_id": ["The product_id field is required."]
  }
}
```

---

### 4. Remove Product from Wishlist ❌ **[DELETE METHOD]**
Remove a specific product from the authenticated user's wishlist.

**Endpoint:**
```
DELETE /api/v1/auth/wishlists/{productId}
```

**Method:** `DELETE`

**Authentication:** Required ✅

**URL Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `productId` | Integer | Yes | The ID of the product to remove from wishlist |

**Example Request:**
```
DELETE /api/v1/auth/wishlists/101
Authorization: Bearer {access_token}
```

**Request Body:** None (Not required)

**Response (200 OK) - Successfully Removed:**
```json
{
  "success": true,
  "message": "Product removed from wishlist."
}
```

**Response (404 Not Found) - Product Not in Wishlist:**
```json
{
  "success": false,
  "message": "Product not found in your wishlist."
}
```

---

## cURL Examples

### Get Wishlist
```bash
curl -X GET "http://127.0.0.1:8000/api/v1/auth/wishlists" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

### Add to Wishlist
```bash
curl -X POST "http://127.0.0.1:8000/api/v1/auth/wishlists" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 101
  }'
```

### Toggle Wishlist
```bash
curl -X POST "http://127.0.0.1:8000/api/v1/auth/wishlists/toggle" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 101
  }'
```

### Remove from Wishlist (DELETE)
```bash
curl -X DELETE "http://127.0.0.1:8000/api/v1/auth/wishlists/101" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

---

## HTTP Status Codes

| Status Code | Name | Description |
|-------------|------|-------------|
| 200 | OK | Request successful |
| 201 | Created | Product successfully added to wishlist |
| 404 | Not Found | Product not found in wishlist |
| 422 | Unprocessable Entity | Validation error in request data |

---

## Error Handling

All error responses follow this format:

**Validation Error (422):**
```json
{
  "success": false,
  "errors": {
    "field_name": ["Error message"]
  }
}
```

**Not Found Error (404):**
```json
{
  "success": false,
  "message": "Product not found in your wishlist."
}
```

---

## Notes

1. **Authentication**: All endpoints require a valid JWT token obtained from the `/api/v1/auth/login` endpoint
2. **User Context**: All operations are scoped to the authenticated user automatically
3. **Product Validation**: The product must exist in the database
4. **Duplicate Prevention**: Adding an already existing product returns 200 with message
5. **Toggle vs Delete**: 
   - **Toggle** (`POST /toggle`) - Returns whether product is now in wishlist
   - **Delete** (`DELETE /{productId}`) - Direct removal of product from wishlist

---

## Examples with Real-world Scenarios

### Scenario 1: User adds product to wishlist
```bash
# Request
POST /api/v1/auth/wishlists
Content-Type: application/json
Authorization: Bearer eyJhbGc...

{
  "product_id": 5
}

# Response (201)
{
  "success": true,
  "message": "Product added to wishlist.",
  "data": {
    "id": 5,
    "name": "Wireless Headphones",
    "price": 199.99,
    "discount_price": 149.99,
    "is_wishlist": true,
    ...
  }
}
```

### Scenario 2: User removes product using DELETE
```bash
# Request
DELETE /api/v1/auth/wishlists/5
Authorization: Bearer eyJhbGc...

# Response (200)
{
  "success": true,
  "message": "Product removed from wishlist."
}
```

### Scenario 3: User toggles wishlist status
```bash
# Request (First time - adds to wishlist)
POST /api/v1/auth/wishlists/toggle
Content-Type: application/json
Authorization: Bearer eyJhbGc...

{
  "product_id": 5
}

# Response (200)
{
  "success": true,
  "is_wishlist": true,
  "message": "Product added to wishlist."
}

# Second request (Removes from wishlist)
POST /api/v1/auth/wishlists/toggle
{
  "product_id": 5
}

# Response (200)
{
  "success": true,
  "is_wishlist": false,
  "message": "Product removed from wishlist."
}
```

