app/assets/API.md

p1ctos4ve - контракты API

Better Auth

API использует фреймворк Better Auth для управления пользователями и сессиями.

Для работы с авторизацией необходимо использовать клиентскую библиотеку Better Auth, прямой вызов методов авторизации из клиентов не предусматривается.

POST /auth/api/sign-up/email

Регистрация нового пользователя с почтой и паролем.

Параметры запроса:

{
  "name": "string",
  "email": "string",
  "password": "string",
  "image": "string (опционально)",
  "callbackURL": "string (опционально)",
  "rememberMe": "boolean (опционально, по умолчанию true)"
}

Ответ (200):

{
  "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

Вход с использованием почты и пароля.

Параметры запроса:

{
  "email": "string",
  "password": "string",
  "callbackURL": "string (опционально)",
  "rememberMe": "string (опционально)"
}

Ответ (200):

{
  "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):

{
  "success": "boolean"
}

Сейвы

API для работы с сохраненными медиафайлами (видео, фото). Каждый сейв имеет настройку видимости, определяющую режим доступа.

Режимы видимости сейва

• public - сейв доступен всем пользователям, отображается в публичных списках и профиле владельца
• link - сейв доступен только по прямой ссылке (shareUrl), не отображается в публичных списках. Владелец всегда видит его в своих списках

GET /saves/my

Возвращает все сейвы текущего пользователя независимо от режима видимости.

Аутентификация: Опциональна

Ответ (200):

[
  {
    "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):

[
  {
    "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):

{
  "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):

{
  "success": true,
  "message": "Сейв успешно удален"
}

PATCH /saves/{id}

Обновляет метаданные сейва (название, описание, теги, видимость). Доступно только владельцу.

Параметры пути:

• id (number/string, обязательный) - ID сейва

Параметры запроса:

{
  "name": "string (опционально)",
  "description": "string (опционально)",
  "tags": ["string"] (опционально),
  "visibility": "public" | "link" (опционально)
}

Аутентификация: Обязательна

Content-Type: application/json, application/x-www-form-urlencoded, или multipart/form-data

Ответ (200):

{
  "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 из стороннего источника.

Параметры запроса:

{
  "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):

{
  "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):

{
  "id": "number",
  "name": "string",
  "type": "string",
  "url": "string",
  "visibility": "public" | "link",
  "shareUrl": "string (если visibility: link)",
  "createdAt": "string (date-time)"
}

Если visibility не указана, по умолчанию устанавливается link.