# Chat API Documentation

This document provides detailed information about the Chat API endpoints for managing conversations and messages.

## Base URL

/chat

## Authentication
All endpoints require JWT authentication. Include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

---

## 1. Create Conversation

Creates a new conversation in a specific channel.

### Endpoint

POST /chat/conversations

### Request Body

{
  "channelId": 1
}

### Request Schema
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| channelId | number | Yes | ID of the channel where the conversation will be created |

### Response

{
    "success": true,
    "statusCode": 201,
    "message": "Conversation created successfully",
    "data": {
        "id": "13",
        "channelId": "18",
        "isRead": 0,
        "createdAt": "2025-10-23T13:51:10.000Z",
        "updatedAt": "2025-10-23T13:51:10.000Z",
        "channel": {
            "id": "18",
            "name": "Beauty & Cosmetics",
            "description": "Skincare, makeup, and beauty products for all occasions",
            "channelCode": null
        }
    }
}

### Response Schema
| Field | Type | Description |
|-------|------|-------------|
| id | number | Unique conversation ID |
| channelId | number | ID of the associated channel |
| isRead | boolean | Whether the conversation has been read |
| createdAt | string | ISO timestamp of creation |
| updatedAt | string | ISO timestamp of last update |
| channel | object | Channel information |

### Error Responses
- **404 Not Found**: Channel not found
- **403 Forbidden**: User doesn't have access to the channel
- **401 Unauthorized**: Invalid or missing JWT token

---

## 2. List Conversations

Retrieves a paginated list of conversations for the authenticated user.

### Endpoint

GET /chat/conversations

### Query Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| page | number | No | 1 | Page number for pagination |
| limit | number | No | 10 | Number of conversations per page |
| channelId | number | No | - | Filter by specific channel ID |
| unreadOnly | boolean | No | false | Show only unread conversations |

### Example Request

GET /chat/conversations?page=1&limit=10&unreadOnly=true

### Response

{
  "success": true,
  "statusCode": 200,
  "message": "Conversations retrieved successfully",
  "data": [
    {
      "id": 1,
      "channelId": 1,
      "isRead": false,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T11:45:00.000Z",
      "channel": {
        "id": 1,
        "name": "Electronics & Gadgets",
        "description": "Latest smartphones, laptops, and electronic accessories",
        "channelCode": "CH000018"
      },
      "lastMessage": {
        "id": 5,
        "content": "Check out this new iPhone!",
        "messageType": "text",
        "senderId": 2,
        "senderName": "John Doe",
        "createdAt": "2024-01-15T11:45:00.000Z"
      },
      "unreadCount": 3
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

### Error Responses
- **401 Unauthorized**: Invalid or missing JWT token

---

## 3. Send Message

Sends a new message to a conversation.

### Endpoint

POST /chat/messages

### Request Body

#### Text Message

{
  "conversationId": 1,
  "message": "Hello, how are you?",
  "messageType": "text"
}

#### Catalog Item Message

{
  "conversationId": 1,
  "message": "Check out this product!",
  "messageType": "catalog_item",
  "catalogItemId": 5
}

#### Media Message

{
  "conversationId": 1,
  "message": "Check this image",
  "messageType": "img",
  "mediaUrl": "https://example.com/image.jpg"
}

### Request Schema
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| conversationId | number | Yes | ID of the conversation |
| message | string | Yes | Message content |
| messageType | string | No | Type of message (default: "text") |
| catalogItemId | number | Conditional | Required when messageType is "catalog_item" |
| mediaUrl | string | No | URL for media messages (img, video, audio, etc.) |

### Message Types
- `text` - Plain text message
- `catalog_item` - Product/catalog item share
- `img` - Image message
- `video` - Video message
- `audio` - Audio message
- `file` - File attachment
- `sticker` - Sticker message
- `gif` - GIF message

### Response

{
  "success": true,
  "statusCode": 201,
  "message": "Message sent successfully",
  "data": {
    "id": 10,
    "conversationId": 1,
    "senderId": 2,
    "message": "Hello, how are you?",
    "messageType": "text",
    "isRead": false,
    "catalogItem": null,
    "mediaUrl": null,
    "createdAt": "2024-01-15T12:00:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z",
    "sender": {
      "id": 2,
      "firstName": "John",
      "lastName": "Doe",
      "email": "[e-mail]"
    }
  }
}

### Catalog Item Message Response

{
  "success": true,
  "statusCode": 201,
  "message": "Message sent successfully",
  "data": {
    "id": 11,
    "conversationId": 1,
    "senderId": 2,
    "message": "Check out this product!",
    "messageType": "catalog_item",
    "isRead": false,
    "catalogItem": {
      "id": 5,
      "name": "iPhone 15 Pro Max",
      "description": "Latest Apple iPhone with A17 Pro chip",
      "price": 1199.99,
      "photoUrls": ["https://example.com/iphone.jpg"],
      "discountPercentage": null
    },
    "mediaUrl": null,
    "createdAt": "2024-01-15T12:05:00.000Z",
    "updatedAt": "2024-01-15T12:05:00.000Z",
    "sender": {
      "id": 2,
      "firstName": "John",
      "lastName": "Doe",
      "email": "[e-mail]"
    }
  }
}

### Error Responses
- **404 Not Found**: Conversation or catalog item not found
- **403 Forbidden**: User doesn't have access to the conversation
- **400 Bad Request**: Invalid message data or missing required fields
- **401 Unauthorized**: Invalid or missing JWT token

---

## 4. List Messages

Retrieves a paginated list of messages from a conversation.

### Endpoint

GET /chat/messages

### Query Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| page | number | No | 1 | Page number for pagination |
| limit | number | No | 50 | Number of messages per page |
| conversationId | number | No | - | Filter by specific conversation ID |
| unreadOnly | boolean | No | false | Show only unread messages |

### Example Request

GET /chat/messages?conversationId=1&page=1&limit=20

### Response

{
  "success": true,
  "statusCode": 200,
  "message": "Messages retrieved successfully",
  "data": [
    {
      "id": 10,
      "conversationId": 1,
      "senderId": 2,
      "message": "Hello, how are you?",
      "messageType": "text",
      "isRead": true,
      "catalogItem": null,
      "mediaUrl": null,
      "createdAt": "2024-01-15T12:00:00.000Z",
      "updatedAt": "2024-01-15T12:00:00.000Z",
      "sender": {
        "id": 2,
        "firstName": "John",
        "lastName": "Doe",
        "email": "[e-mail]"
      }
    },
    {
      "id": 11,
      "conversationId": 1,
      "senderId": 3,
      "message": "Check out this amazing product!",
      "messageType": "catalog_item",
      "isRead": false,
      "catalogItem": {
        "id": 5,
        "name": "iPhone 15 Pro Max",
        "description": "Latest Apple iPhone with A17 Pro chip, 256GB storage",
        "price": 1199.99,
        "photoUrls": [
          "https://example.com/iphone-front.jpg",
          "https://example.com/iphone-back.jpg"
        ],
        "discountPercentage": 10
      },
      "mediaUrl": null,
      "createdAt": "2024-01-15T12:05:00.000Z",
      "updatedAt": "2024-01-15T12:05:00.000Z",
      "sender": {
        "id": 3,
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "[e-mail]"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

### Response Schema
| Field | Type | Description |
|-------|------|-------------|
| id | number | Unique message ID |
| conversationId | number | ID of the conversation |
| senderId | number | ID of the message sender |
| message | string | Message content |
| messageType | string | Type of message |
| isRead | boolean | Whether the message has been read |
| catalogItem | object\|null | Catalog item data (if messageType is "catalog_item") |
| mediaUrl | string\|null | Media URL (for media messages) |
| createdAt | string | ISO timestamp of creation |
| updatedAt | string | ISO timestamp of last update |
| sender | object | Sender information |

### Error Responses
- **404 Not Found**: Conversation not found
- **403 Forbidden**: User doesn't have access to the conversation
- **401 Unauthorized**: Invalid or missing JWT token

---

## Error Response Format

All error responses follow this format:

{
  "success": false,
  "statusCode": 400,
  "message": "Error description",
  "error": "Detailed error information"
}

## Status Codes

- **200 OK**: Request successful
- **201 Created**: Resource created successfully
- **400 Bad Request**: Invalid request data
- **401 Unauthorized**: Authentication required
- **403 Forbidden**: Access denied
- **404 Not Found**: Resource not found
- **500 Internal Server Error**: Server error