# 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`.