# ChatBud API Documentation

## Overview

The ChatBud API provides RESTful endpoints for user management, posts, comments, notifications, and direct messaging.

## Base URL

```
http://localhost/ChatBud-PHP/public/api.php/v1
```

## Authentication

Most endpoints require authentication via JWT token or session cookie.

Include the token in request headers:
```
Authorization: Bearer YOUR_TOKEN
```

Or use the `chatbud_token` cookie (automatically set on login).

## Response Format

All responses are JSON:

### Success Response
```json
{
  "success": true,
  "data": { /* response data */ }
}
```

### Error Response
```json
{
  "success": false,
  "error": "Error message"
}
```

## Endpoints

### Authentication

#### Register
- **Endpoint:** `POST /api/v1/auth/register`
- **Public:** Yes
- **Body:**
  ```json
  {
    "email": "user@example.com",
    "username": "username",
    "password": "securepassword",
    "display_name": "User Name"
  }
  ```
- **Response:** User object with ID

#### Login
- **Endpoint:** `POST /api/v1/auth/login`
- **Public:** Yes
- **Body:**
  ```json
  {
    "email": "user@example.com",
    "password": "securepassword"
  }
  ```
- **Response:** 
  ```json
  {
    "success": true,
    "data": {
      "user": { /* user object */ },
      "token": "session_token"
    }
  }
  ```

#### Logout
- **Endpoint:** `POST /api/v1/auth/logout`
- **Protected:** Yes
- **Response:** Success message

### Users

#### Get User
- **Endpoint:** `GET /api/v1/users/:id`
- **Public:** Yes
- **Response:** User object with follower/following counts

#### Update User
- **Endpoint:** `PUT /api/v1/users/:id`
- **Protected:** Yes
- **Body:**
  ```json
  {
    "display_name": "New Name",
    "bio": "User bio",
    "avatar_url": "https://...",
    "country": "US"
  }
  ```
- **Response:** Updated user object

#### Get User Posts
- **Endpoint:** `GET /api/v1/users/:id/posts?limit=20&offset=0`
- **Public:** Yes
- **Query Parameters:**
  - `limit`: Number of posts (default: 20)
  - `offset`: Pagination offset (default: 0)
- **Response:** Array of post objects

#### Get Followers
- **Endpoint:** `GET /api/v1/users/:id/followers?limit=50&offset=0`
- **Public:** Yes
- **Response:** Array of user objects

#### Get Following
- **Endpoint:** `GET /api/v1/users/:id/following?limit=50&offset=0`
- **Public:** Yes
- **Response:** Array of user objects

#### Follow User
- **Endpoint:** `POST /api/v1/users/:id/follow`
- **Protected:** Yes
- **Response:** Success message

#### Unfollow User
- **Endpoint:** `DELETE /api/v1/users/:id/follow`
- **Protected:** Yes
- **Response:** Success message

### Posts

#### Get Feed
- **Endpoint:** `GET /api/v1/feed?limit=20&offset=0`
- **Protected:** Yes
- **Query Parameters:**
  - `limit`: Number of posts (default: 20)
  - `offset`: Pagination offset (default: 0)
- **Response:** Array of feed posts

#### Get Posts
- **Endpoint:** `GET /api/v1/posts?limit=20&offset=0`
- **Public:** Yes
- **Response:** Array of trending posts

#### Get Post
- **Endpoint:** `GET /api/v1/posts/:id`
- **Public:** Yes
- **Response:** Single post object with media and counts

#### Create Post
- **Endpoint:** `POST /api/v1/posts`
- **Protected:** Yes
- **Body:**
  ```json
  {
    "content": "Post content up to 2000 characters"
  }
  ```
- **Response:** Created post object

#### Update Post
- **Endpoint:** `PUT /api/v1/posts/:id`
- **Protected:** Yes
- **Body:**
  ```json
  {
    "content": "Updated content"
  }
  ```
- **Response:** Updated post object

#### Delete Post
- **Endpoint:** `DELETE /api/v1/posts/:id`
- **Protected:** Yes
- **Response:** Success message

#### Like Post
- **Endpoint:** `POST /api/v1/posts/:id/like`
- **Protected:** Yes
- **Response:** Success message

#### Unlike Post
- **Endpoint:** `DELETE /api/v1/posts/:id/like`
- **Protected:** Yes
- **Response:** Success message

### Comments

#### Get Comments
- **Endpoint:** `GET /api/v1/posts/:id/comments?limit=50&offset=0`
- **Public:** Yes
- **Response:** Array of comment objects

#### Create Comment
- **Endpoint:** `POST /api/v1/posts/:id/comments`
- **Protected:** Yes
- **Body:**
  ```json
  {
    "content": "Comment content up to 2000 characters"
  }
  ```
- **Response:** Created comment object

### Media

#### Upload File
- **Endpoint:** `POST /api/v1/upload`
- **Protected:** Yes
- **Content-Type:** multipart/form-data
- **Body:** File upload
- **Response:** 
  ```json
  {
    "success": true,
    "data": [
      {
        "filename": "timestamp_random.ext",
        "url": "/uploads/posts/...",
        "mime_type": "image/jpeg",
        "file_size": 1024,
        "type": "image",
        "width": 1920,
        "height": 1080,
        "thumbnail_url": "/uploads/posts/thumb_..."
      }
    ]
  }
  ```

## Status Codes

- `200 OK` - Successful request
- `201 Created` - Resource created
- `400 Bad Request` - Invalid input
- `401 Unauthorized` - Authentication required or failed
- `403 Forbidden` - User doesn't have permission
- `404 Not Found` - Resource not found
- `405 Method Not Allowed` - Wrong HTTP method
- `500 Internal Server Error` - Server error

## Error Handling

All errors follow this format:
```json
{
  "success": false,
  "error": "Error description"
}
```

Common errors:
- "Unauthorized" - No valid authentication token
- "Forbidden" - User lacks permissions
- "User not found" - User doesn't exist
- "Post not found" - Post doesn't exist
- "Invalid email or password" - Login failed

## Rate Limiting

(To be implemented)

## Webhooks

(To be implemented)

## Examples

### Register a new user
```bash
curl -X POST http://localhost/ChatBud-PHP/public/api.php/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "newuser",
    "password": "SecurePassword123",
    "display_name": "New User"
  }'
```

### Login
```bash
curl -X POST http://localhost/ChatBud-PHP/public/api.php/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123"
  }'
```

### Create a post
```bash
curl -X POST http://localhost/ChatBud-PHP/public/api.php/v1/posts \
  -H "Content-Type: application/json" \
  -H "Cookie: chatbud_token=YOUR_TOKEN" \
  -d '{
    "content": "Hello, ChatBud!"
  }'
```

### Upload an image
```bash
curl -X POST http://localhost/ChatBud-PHP/public/api.php/v1/upload \
  -H "Cookie: chatbud_token=YOUR_TOKEN" \
  -F "file=@/path/to/image.jpg"
```

### Get user posts
```bash
curl "http://localhost/ChatBud-PHP/public/api.php/v1/users/USER_ID/posts?limit=10"
```

## Pagination

Use `limit` and `offset` parameters for pagination:
```
GET /api/v1/posts?limit=20&offset=0
GET /api/v1/posts?limit=20&offset=20
```

## Versioning

Current API version: v1

Future versions will be available at `/api/v2`, etc.

## Support

For API support, contact: api@chatbud.com