API Документация

# API Документация

## Общи бележки

- Всички endpoint-и се достъпват през `?api=ACTION`
- Content-Type: `application/json; charset=utf-8`
- Автентикация: PHP сесия (`$_SESSION`) + `remember_token` cookie
- Rate limit: 180 заявки за 60 секунди на IP (сесия-базиран)
- Грешки връщат подходящ HTTP статус код + JSON с поле `error`

---

## 1. Автентикация

### `login`

Създава нов потребител или логва съществуващ. При успешен логин връща `theme` и сетва сесия.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=login" \
  -H "Content-Type: application/json" \
  -d '{"username":"ivan","password":"secret123","avatar":"https://..."}'
```

**Response:**
```json
{
  "success": true,
  "theme": "light",
  "php_execution_time": "12.34 ms"
}
```

**Errors:**
- `missing_fields` (400) — липсва username или password
- `invalid_password` (401) — грешна парола за съществуващ потребител
- `server_misconfiguration` (500) — липсва `VRLIN_LOGIN_SESSIONS_SECRET_KEY`

---

### `logout`

Унищожава сесията и изтрива `remember_token` от БД и cookie.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=logout" \
  -H "Cookie: PHPSESSID=xxx; remember_token=yyy"
```

**Response:**
```json
{
  "success": true,
  "php_execution_time": "5.67 ms"
}
```

---

### `me`

Връща информация за логнатия потребител.

**Request:**
```bash
curl -X GET "https://example.com/api.php?api=me" \
  -H "Cookie: PHPSESSID=xxx"
```

**Response (логнат):**
```json
{
  "id": 1,
  "username": "ivan",
  "avatar": "uploads/123456_avatar.jpg",
  "theme": "dark",
  "php_execution_time": "8.90 ms"
}
```

**Response (не-логнат):**
```json
{
  "logged_in": false,
  "php_execution_time": "3.21 ms"
}
```

---

## 2. Потребителски настройки

### `set_theme`

Променя темата на логнатия потребител.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=set_theme" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=xxx" \
  -d '{"theme":"dark"}'
```

**Response:**
```json
{
  "success": true,
  "php_execution_time": "7.12 ms"
}
```

**Errors:** `not_logged_in` (401)

---

### `get_user`

Връща публична информация за произволен потребител по ID.

**Request:**
```bash
curl -X GET "https://example.com/api.php?api=get_user&user_id=5"
```

**Response:**
```json
{
  "id": 5,
  "username": "maria",
  "avatar": "uploads/..."
}
```

**Errors:** `user_not_found` (404)

---

### `update_avatar`

Качва файл като аватар на логнатия потребител.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=update_avatar" \
  -H "Cookie: PHPSESSID=xxx" \
  -F "avatar=@/path/to/photo.jpg"
```

**Response:**
```json
{
  "success": true,
  "avatar": "uploads/1699123456_photo.jpg"
}
```

**Errors:**
- `not_logged_in` (401)
- `no_file` (400)
- `forbidden_file_type` (403) — ако файлът е в blocked списъка

---

### `update_avatar_url`

Задава аватар чрез URL (вместо файл).

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=update_avatar_url" \
  -H "Cookie: PHPSESSID=xxx" \
  -d "avatar=https://example.com/pic.jpg"
```

**Response:**
```json
{
  "success": true,
  "avatar": "https://example.com/pic.jpg"
}
```

**Errors:**
- `not_logged_in` (401)
- `no_url` (400)

---

## 3. Постове

### `add_post`

Създава нов пост. Поддържа текст, снимка (файл или URL) и scheduled публикуване.

**Request (само текст):**
```bash
curl -X POST "https://example.com/api.php?api=add_post" \
  -H "Cookie: PHPSESSID=xxx" \
  -d "content=Здравей свят!"
```

**Request (със снимка файл):**
```bash
curl -X POST "https://example.com/api.php?api=add_post" \
  -H "Cookie: PHPSESSID=xxx" \
  -F "content=Моята снимка" \
  -F "image=@/path/to/photo.jpg"
```

**Request (със scheduled):**
```bash
curl -X POST "https://example.com/api.php?api=add_post" \
  -H "Cookie: PHPSESSID=xxx" \
  -d "content=Утре ще публикувам" \
  -d "scheduled_at=2026-07-05 10:00:00"
```

**Response:**
```json
{
  "success": true,
  "debug": {
    "scheduled": 1751709600,
    "php_time": 1699123456
  },
  "php_execution_time": "15.23 ms"
}
```

**Errors:** `not_logged_in` (401), `forbidden_file_type` (403)

---

### `add_canvas_post`

Създава пост с HTML/JS canvas код. **Внимание:** `canvas_code` се записва чист в БД — по дизайн!

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=add_canvas_post" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=xxx" \
  -d '{
    "content": "Моят canvas пост",
    "canvas_code": "<script>alert(1)</script>"
  }'
```

**Response:**
```json
{
  "success": true,
  "php_execution_time": "9.87 ms"
}
```

**Errors:** `not_logged_in` (401)

---

### `get_all_posts`

Връща всички постове (макс. 100) с коментари и like-ове.

**Request:**
```bash
curl -X GET "https://example.com/api.php?api=get_all_posts&viewer=1&user=5"
```

- `viewer` — ID на текущия потребител (за `liked_by_user`)
- `user` — филтрирай само постове на този потребител (0 = всички)

**Response:**
```json
{
  "posts": [
    {
      "id": 10,
      "user_id": 5,
      "content": "Здравей",
      "image": "uploads/...",
      "username": "maria",
      "avatar": "uploads/...",
      "post_count": 12,
      "like_count": 7,
      "liked_by_user": 1,
      "comments": [
        {
          "id": 3,
          "post_id": 10,
          "user_id": 2,
          "text": "Супер!",
          "username": "pesho",
          "avatar": "..."
        }
      ]
    }
  ],
  "php_execution_time": "45.12 ms"
}
```

---

### `get_posts`

Връща постове с пагинация (10 на страница).

**Request:**
```bash
curl -X GET "https://example.com/api.php?api=get_posts&viewer=1&user=0&page=2"
```

**Response:**
```json
{
  "posts": [...],
  "total": 156,
  "pages": 16,
  "page": 2,
  "php_execution_time": "23.45 ms"
}
```

---

### `get_post`

Връща единичен пост по ID с всички коментари.

**Request:**
```bash
curl -X GET "https://example.com/api.php?api=get_post&viewer=1&post_id=10"
```

**Response:**
```json
{
  "id": 10,
  "content": "Здравей",
  "username": "maria",
  "like_count": 7,
  "liked_by_user": 1,
  "comments": [...]
}
```

**Errors:** `not_found` (404)

---

### `get_scheduled_posts`

Връща всички бъдещи (scheduled) постове на логнатия потребител.

**Request:**
```bash
curl -X GET "https://example.com/api.php?api=get_scheduled_posts" \
  -H "Cookie: PHPSESSID=xxx"
```

**Response:**
```json
[
  {
    "id": 15,
    "content": "Утре ще публикувам",
    "scheduled_at": "2026-07-05 10:00:00",
    "like_count": 0
  }
]
```

**Errors:** `not_logged_in` (401)

---

### `edit_post`

Редактира текст на пост (само ако е на логнатия потребител).

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=edit_post" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=xxx" \
  -d '{"post_id":10,"content":"Нов текст"}'
```

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

**Errors:** `not_logged_in` (401), `no_permission` (403)

---

### `delete_post`

Трие пост + свързаните коментари, like-ове и качената снимка от файловата система.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=delete_post" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=xxx" \
  -d '{"post_id":10}'
```

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

**Errors:** `not_logged_in` (401), `no_permission` (403)

---

## 4. Коментари

### `add_comment`

Добавя коментар към пост.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=add_comment" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=xxx" \
  -d '{"post_id":10,"text":"Супер пост!"}'
```

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

**Errors:** `not_logged_in` (401)

---

### `delete_comment`

Трие коментар (само ако е на логнатия потребител).

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=delete_comment" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=xxx" \
  -d '{"comment_id":5}'
```

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

**Errors:** `not_logged_in` (401), `no_permission` (403)

---

## 5. Like-ове

### `toggle_like`

Like/unlike на пост. Връща текущото състояние.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=toggle_like" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=xxx" \
  -d '{"post_id":10}'
```

**Response (like):**
```json
{"liked": true}
```

**Response (unlike):**
```json
{"liked": false}
```

**Errors:** `not_logged_in` (401)

---

## 6. Социални функции (Follow)

### `follow`

Започва следване на потребител.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=follow" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=xxx" \
  -d '{"follow_id":5}'
```

**Response:**
```json
{
  "success": true,
  "username": "maria"
}
```

**Errors:**
- `not_logged_in` (401)
- `invalid_user` (400)
- `cannot_follow_self` (400)
- `user_not_found` (404)
- `already_following` (200)

---

### `unfollow`

Спира следване на потребител.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=unfollow" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=xxx" \
  -d '{"unfollow_id":5}'
```

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

**Errors:** `not_logged_in` (401), `invalid_request` (400)

---

### `remove_follower`

Премахва последовател от своя списък.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=remove_follower" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=xxx" \
  -d '{"unfollow_id":5}'
```

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

**Errors:** `not_logged_in` (401)

---

### `is_following`

Проверява дали логнатия потребител следва друг.

**Request:**
```bash
curl -X GET "https://example.com/api.php?api=is_following&check_id=5" \
  -H "Cookie: PHPSESSID=xxx"
```

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

**Errors:** `not_logged_in` (401)

---

### `get_followers`

Връща списък с последователи на потребител.

**Request:**
```bash
curl -X GET "https://example.com/api.php?api=get_followers&user_id=5"
```

**Response:**
```json
[
  {"id": 1, "username": "ivan", "avatar": "..."},
  {"id": 2, "username": "pesho", "avatar": "..."}
]
```

---

### `get_following`

Връща списък с хора, които потребителят следва.

**Request:**
```bash
curl -X GET "https://example.com/api.php?api=get_following&user_id=5"
```

**Response:**
```json
[
  {"id": 3, "username": "gosho", "avatar": "..."}
]
```

---

### `get_vector_count`

Връща броя "вектори" (followers + following) на потребител.

**Request:**
```bash
curl -X GET "https://example.com/api.php?api=get_vector_count&user_id=5"
```

**Response:**
```json
{"vectors": 42}
```

---

## 7. Импресии

### `add_impression`

Увеличава брояча за показвания на пост.

**Request:**
```bash
curl -X POST "https://example.com/api.php?api=add_impression" \
  -d "post_id=10"
```

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

---

## HTTP Статус Кодове

| Код | Значение |
|-----|----------|
| 200 | OK |
| 400 | Bad Request — липсващи/невалидни полета |
| 401 | Unauthorized — не сте логнати |
| 403 | Forbidden — нямате права или забранен файл |
| 404 | Not Found — потребител/пост не съществува |
| 429 | Too Many Requests — rate limit |
| 500 | Internal Server Error — MySQL или конфигурация |

---

## Забранени файлови типове (Upload)

При качване на снимка/аватар се блокират:
- **Разширения:** `php`, `php3-8`, `phtml`, `phar`, `cgi`, `exe`, `sh`, `pl`, `py`, `rb`, `jar`, `jsp`, `asp`, `aspx`, `dll`, `so`, `bin`, `msi`, `com`, `bat`, `cmd`
- **MIME типове:** `application/x-httpd-php`, `text/x-php`, `application/x-sh`, `application/x-executable`, `application/x-msdownload`, `application/x-python`, `application/x-perl`, `application/x-cgi`

---

## Примерен workflow

```bash
# 1. Регистрация / Логин
curl -c cookies.txt -X POST "https://example.com/api.php?api=login" \
  -H "Content-Type: application/json" \
  -d '{"username":"ivan","password":"secret123"}'

# 2. Публикуване на пост
curl -b cookies.txt -X POST "https://example.com/api.php?api=add_post" \
  -F "content=Здравей от curl!" \
  -F "image=@photo.jpg"

# 3. Вземане на постове (страница 1)
curl -b cookies.txt "https://example.com/api.php?api=get_posts&viewer=1&page=1"

# 4. Like на пост
curl -b cookies.txt -X POST "https://example.com/api.php?api=toggle_like" \
  -d "post_id=10"

# 5. Коментар
curl -b cookies.txt -X POST "https://example.com/api.php?api=add_comment" \
  -d "post_id=10" -d "text=Браво!"

# 6. Логаут
curl -b cookies.txt -X POST "https://example.com/api.php?api=logout"
```