chore: Описание технических требований в README

assets/API.md

@@ -0,0 +1,283 @@
+# p1ctos4ve - контракты API
+
+## Better Auth
+API использует фреймворк [Better Auth](https://better-auth.com) для управления пользователями и сессиями.
+
+Для работы с авторизацией необходимо использовать [клиентскую библиотеку](https://www.better-auth.com/docs/concepts/client) Better Auth, прямой вызов методов авторизации из клиентов не предусматривается.
+
+### `POST /auth/api/sign-up/email`
+
+Регистрация нового пользователя с почтой и паролем.
+
+**Параметры запроса:**
+```json
+{
+  "name": "string",
+  "email": "string",
+  "password": "string",
+  "image": "string (опционально)",
+  "callbackURL": "string (опционально)",
+  "rememberMe": "boolean (опционально, по умолчанию true)"
+}
+```
+
+**Ответ (200):**
+```json
+{
+  "token": "string | null",
+  "user": {
+    "id": "string",
+    "email": "string",
+    "name": "string",
+    "image": "string | null",
+    "emailVerified": "boolean",
+    "createdAt": "string (date-time)",
+    "updatedAt": "string (date-time)"
+  }
+}
+```
+
+### `POST /auth/api/sign-in/email`
+
+Вход с использованием почты и пароля.
+
+**Параметры запроса:**
+```json
+{
+  "email": "string",
+  "password": "string",
+  "callbackURL": "string (опционально)",
+  "rememberMe": "string (опционально)"
+}
+```
+
+**Ответ (200):**
+```json
+{
+  "redirect": false,
+  "token": "string",
+  "url": null,
+  "user": {
+    "id": "string",
+    "email": "string",
+    "name": "string | null",
+    "image": "string | null",
+    "emailVerified": "boolean",
+    "createdAt": "string (date-time)",
+    "updatedAt": "string (date-time)"
+  }
+}
+```
+
+### `POST /auth/api/sign-out`
+
+Выход из системы и завершение текущей сессии.
+
+**Ответ (200):**
+```json
+{
+  "success": "boolean"
+}
+```
+
+## Сейвы
+API для работы с сохраненными медиафайлами (видео, фото). Каждый сейв имеет настройку видимости, определяющую режим доступа.
+
+### Режимы видимости сейва
+- `public` - сейв доступен всем пользователям, отображается в публичных списках и профиле владельца
+- `link` - сейв доступен только по прямой ссылке (shareUrl), не отображается в публичных списках. Владелец всегда видит его в своих списках
+
+### `GET /saves/my`
+
+Возвращает все сейвы текущего пользователя независимо от режима видимости.
+
+**Аутентификация:** Опциональна
+
+**Ответ (200):**
+```json
+[
+  {
+    "id": "number",
+    "name": "string",
+    "type": "string",
+    "description": "string",
+    "tags": ["string"],
+    "visibility": "public" | "link",
+    "shareUrl": "string (только для visibility: link)",
+    "createdAt": "string (date-time)",
+    "updatedAt": "string (date-time)"
+  }
+]
+```
+
+### `GET /saves/u/{slug}`
+Возвращает **только публичные сейвы** (visibility: public) конкретного пользователя по его никнейму (slug). Сейвы с видимостью "link" не включаются в этот список, даже если запрашивает владелец.
+
+**Параметры пути:**
+- `slug` (string, обязательный) - никнейм пользователя
+
+**Аутентификация:** Опциональна
+
+**Ответ (200):**
+```json
+[
+  {
+    "id": "number",
+    "name": "string",
+    "type": "string",
+    "description": "string",
+    "tags": ["string"],
+    "visibility": "public",
+    "createdAt": "string (date-time)",
+    "updatedAt": "string (date-time)"
+  }
+]
+```
+
+### `GET /saves/{id}`
+Возвращает информацию о конкретном сейве.
+
+**Параметры пути:**
+- `id` (number/string, обязательный) - ID сейва
+
+**Аутентификация:** Опциональна
+
+**Правила доступа:**
+- **Владелец:** полный доступ ко всем сейвам (public и link)
+- **Другие пользователи:**
+  - **public сейвы:** доступны всем
+  - **link сейвы:** доступны только при обращении по корректной shareUrl; запрос по голому ID вернет `404 Not Found`
+
+**Ответ (200):**
+```json
+{
+  "id": "number",
+  "name": "string",
+  "type": "string",
+  "description": "string",
+  "tags": ["string"],
+  "visibility": "public" | "link",
+  "shareUrl": "string (только для visibility: link)",
+  "userId": "string",
+  "createdAt": "string (date-time)",
+  "updatedAt": "string (date-time)"
+}
+```
+
+**Коды ошибок:**
+- `404 Not Found` - сейв не найден или недоступен (для link сейвов без shareUrl)
+- `403 Forbidden` - нет прав доступа
+
+### `DELETE /saves/{id}`
+Удаляет сейв по его ID. Доступно только владельцу.
+
+**Параметры пути:**
+- `id` (number/string, обязательный) - ID сейва
+
+**Аутентификация:** Обязательна
+
+**Ответ (200):**
+```json
+{
+  "success": true,
+  "message": "Сейв успешно удален"
+}
+```
+
+### `PATCH /saves/{id}`
+Обновляет метаданные сейва (название, описание, теги, видимость). Доступно только владельцу.
+
+**Параметры пути:**
+- `id` (number/string, обязательный) - ID сейва
+
+**Параметры запроса:**
+```json
+{
+  "name": "string (опционально)",
+  "description": "string (опционально)",
+  "tags": ["string"] (опционально),
+  "visibility": "public" | "link" (опционально)
+}
+```
+
+**Аутентификация:** Обязательна
+
+**Content-Type:** `application/json`, `application/x-www-form-urlencoded`, или `multipart/form-data`
+
+**Ответ (200):**
+```json
+{
+  "id": "number",
+  "name": "string",
+  "type": "string",
+  "description": "string",
+  "tags": ["string"],
+  "visibility": "public" | "link",
+  "shareUrl": "string (если visibility: link)",
+  "updatedAt": "string (date-time)"
+}
+```
+
+**Примечание:** При установке `visibility: "link"` сервер автоматически генерирует или возвращает существующую `shareUrl`. При смене на `visibility: "public"` поле `shareUrl` становится неактуальным.
+
+### `POST /saves/external`
+Скачивает и сохраняет медиафайл по URL из стороннего источника.
+
+**Параметры запроса:**
+```json
+{
+  "url": "string (URI, обязательный)",
+  "name": "string (опционально)",
+  "description": "string (опционально)",
+  "tags": ["string"] (опционально),
+  "visibility": "public" | "link" (опционально, по умолчанию: link)"
+}
+```
+
+**Аутентификация:** Обязательна
+
+**Content-Type:** `application/json`, `application/x-www-form-urlencoded`, или `multipart/form-data`
+
+**Ответ (200):**
+```json
+{
+  "id": "number",
+  "name": "string",
+  "type": "string",
+  "url": "string",
+  "visibility": "public" | "link",
+  "shareUrl": "string (если visibility: link)",
+  "createdAt": "string (date-time)"
+}
+```
+
+Если `visibility` не указана, по умолчанию устанавливается `link`.
+
+### `POST /saves/upload`
+Загружает медиафайл с устройства.
+
+**Параметры запроса (multipart/form-data):**
+- `file` (`binary`, обязательный) - файл для загрузки
+- `name` (`string`, опционально) - название сейва
+- `description` (`string`, опционально) - описание сейва
+- `tags` (`array[string]`, опционально) - теги
+- `visibility` (`"public" | "link"`, опционально, по умолчанию: "link") - режим видимости
+
+**Аутентификация:** Обязательна
+
+**Content-Type:** `multipart/form-data`
+
+**Ответ (200):**
+```json
+{
+  "id": "number",
+  "name": "string",
+  "type": "string",
+  "url": "string",
+  "visibility": "public" | "link",
+  "shareUrl": "string (если visibility: link)",
+  "createdAt": "string (date-time)"
+}
+```
+
+Если `visibility` не указана, по умолчанию устанавливается `link`.