369 lines
19 KiB
TypeScript
369 lines
19 KiB
TypeScript
export interface ApiEndpoint {
|
||
method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
|
||
path: string;
|
||
summary: string;
|
||
description?: string;
|
||
auth?: boolean;
|
||
}
|
||
|
||
export interface ApiTagGroup {
|
||
tag: string;
|
||
endpoints: ApiEndpoint[];
|
||
}
|
||
|
||
export const apiReference: ApiTagGroup[] = [
|
||
{
|
||
tag: 'Аутентификация',
|
||
endpoints: [
|
||
{ method: 'POST', path: '/auth/register', summary: 'Регистрация пользователя', description: 'Первый пользователь получает isSuperAdmin.' },
|
||
{ method: 'POST', path: '/auth/login', summary: 'Вход по почте, телефону или логину' },
|
||
{ method: 'POST', path: '/auth/identify', summary: 'Проверить способ входа (identifier-first)', description: 'Возвращает isTotpEnabled, otpChannels, methods.' },
|
||
{ method: 'POST', path: '/auth/totp/begin', summary: 'Начать вход по TOTP', description: 'Challenge для Google Authenticator вместо SMS/email OTP.' },
|
||
{ method: 'POST', path: '/auth/totp/verify', summary: 'Подтвердить TOTP при входе', description: 'Завершает вход после кода из приложения-аутентификатора.' },
|
||
{ method: 'POST', path: '/auth/otp/send', summary: 'Отправить OTP для passwordless-входа', description: 'Альтернатива TOTP; channel: email | phone | backupEmail | backupPhone.' },
|
||
{ method: 'POST', path: '/auth/otp/verify', summary: 'Проверить OTP', description: 'Завершает вход по SMS/email без повторного TOTP.' },
|
||
{ method: 'POST', path: '/auth/login/password', summary: 'Войти по паролю' },
|
||
{ method: 'POST', path: '/auth/ldap/login', summary: 'Войти через LDAP/LDAPS' },
|
||
{ method: 'POST', path: '/auth/pin/verify', summary: 'Подтвердить PIN-код' },
|
||
{ method: 'POST', path: '/auth/refresh', summary: 'Обновить access token' },
|
||
{ method: 'GET', path: '/auth/session', summary: 'Состояние текущей сессии', auth: true },
|
||
{ method: 'GET', path: '/auth/me', summary: 'Текущий пользователь', auth: true }
|
||
]
|
||
},
|
||
{
|
||
tag: 'OAuth 2.0 / OIDC',
|
||
endpoints: [
|
||
{
|
||
method: 'GET',
|
||
path: '/.well-known/openid-configuration',
|
||
summary: 'OpenID Connect Discovery',
|
||
description: 'Метаданные провайдера: issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, scopes_supported, code_challenge_methods_supported.'
|
||
},
|
||
{
|
||
method: 'GET',
|
||
path: '/oauth/authorize',
|
||
summary: 'Authorization endpoint (OIDC)',
|
||
description:
|
||
'Стандартные query: client_id, redirect_uri, response_type=code, scope, state, code_challenge, code_challenge_method. ' +
|
||
'HTTP 302 на redirect_uri?code=... или редирект на экран входа/подтверждения. Legacy: clientId, redirectUri, userId.'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/oauth/token',
|
||
summary: 'Token endpoint',
|
||
description:
|
||
'Content-Type: application/x-www-form-urlencoded или JSON. ' +
|
||
'Поля: grant_type, code, client_id, client_secret, redirect_uri, refresh_token. ' +
|
||
'Ответ (snake_case): access_token, token_type, expires_in, refresh_token, id_token. ' +
|
||
'Поддерживается Authorization: Basic (client_id:client_secret).'
|
||
},
|
||
{
|
||
method: 'GET',
|
||
path: '/oauth/userinfo',
|
||
summary: 'UserInfo endpoint',
|
||
description: 'Профиль по Bearer access_token. Поля: sub, email, phone, name, picture.',
|
||
auth: true
|
||
}
|
||
]
|
||
},
|
||
{
|
||
tag: 'Профиль и биометрия',
|
||
endpoints: [
|
||
{ method: 'GET', path: '/profile/users/{userId}', summary: 'Получить профиль', auth: true },
|
||
{ method: 'PATCH', path: '/profile/users/{userId}', summary: 'Обновить профиль', auth: true },
|
||
{ method: 'PATCH', path: '/profile/users/{userId}/avatar', summary: 'Обновить аватар', auth: true },
|
||
{ method: 'PATCH', path: '/profile/users/{userId}/contacts', summary: 'Обновить контакты', auth: true },
|
||
{ method: 'POST', path: '/profile/users/{userId}/password', summary: 'Установить пароль', auth: true },
|
||
{
|
||
method: 'GET',
|
||
path: '/profile/users/{userId}/e2e-public-key',
|
||
summary: 'Публичный E2E-ключ пользователя',
|
||
description: 'SPKI base64 для ECDH P-256. Нужен перед созданием секретного чата.',
|
||
auth: false
|
||
},
|
||
{
|
||
method: 'PATCH',
|
||
path: '/profile/users/{userId}/e2e-public-key',
|
||
summary: 'Сохранить свой E2E-ключ',
|
||
description: 'Тело: { "publicKey": "..." }. Только для своего userId.',
|
||
auth: true
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/profile/users/{userId}/self-delete',
|
||
summary: 'Запланировать удаление профиля',
|
||
description: 'Не удаляет аккаунт сразу. Запускает период ожидания ACCOUNT_DELETE_GRACE_DAYS (по умолчанию 30 дней).',
|
||
auth: true
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/profile/users/{userId}/self-delete/cancel',
|
||
summary: 'Отменить запланированное удаление профиля',
|
||
auth: true
|
||
},
|
||
{
|
||
method: 'GET',
|
||
path: '/profile/users/{userId}/self-delete/status',
|
||
summary: 'Статус запланированного удаления профиля',
|
||
description: 'Возвращает pending, deletionRequestedAt, effectiveAt и graceDays.',
|
||
auth: true
|
||
}
|
||
]
|
||
},
|
||
{
|
||
tag: 'Безопасность',
|
||
endpoints: [
|
||
{ method: 'GET', path: '/security/users/{userId}/devices', summary: 'Активные устройства', auth: true },
|
||
{ method: 'GET', path: '/security/users/{userId}/sessions', summary: 'Активные сессии', auth: true },
|
||
{ method: 'GET', path: '/security/users/{userId}/totp/status', summary: 'Статус TOTP', auth: true },
|
||
{ method: 'POST', path: '/security/users/{userId}/totp/setup', summary: 'Настроить TOTP (QR + секрет)', auth: true },
|
||
{ method: 'POST', path: '/security/users/{userId}/totp/enable', summary: 'Включить TOTP', auth: true },
|
||
{ method: 'POST', path: '/security/users/{userId}/totp/disable', summary: 'Отключить TOTP', auth: true },
|
||
{ method: 'POST', path: '/security/users/{userId}/pin/setup', summary: 'Настроить PIN', auth: true },
|
||
{ method: 'POST', path: '/security/users/{userId}/revoke-all-sessions', summary: 'Выйти везде', auth: true }
|
||
]
|
||
},
|
||
{
|
||
tag: 'Администрирование',
|
||
endpoints: [
|
||
{ method: 'GET', path: '/admin/users', summary: 'Список пользователей', auth: true },
|
||
{ method: 'PATCH', path: '/admin/users/{userId}', summary: 'Обновить пользователя', auth: true },
|
||
{ method: 'POST', path: '/admin/users/{userId}/reset-password', summary: 'Сбросить пароль', auth: true },
|
||
{ method: 'PATCH', path: '/admin/users/{userId}/super-admin', summary: 'Права супер-администратора', auth: true }
|
||
]
|
||
},
|
||
{
|
||
tag: 'RBAC и OAuth',
|
||
endpoints: [
|
||
{ method: 'GET', path: '/admin/rbac/roles', summary: 'Список ролей', auth: true },
|
||
{ method: 'POST', path: '/admin/rbac/oauth-clients', summary: 'Создать OAuth-приложение', auth: true },
|
||
{ method: 'GET', path: '/admin/rbac/oauth-scopes', summary: 'OAuth scopes', auth: true }
|
||
]
|
||
},
|
||
{
|
||
tag: 'Глобальные настройки',
|
||
endpoints: [
|
||
{ method: 'GET', path: '/admin/settings', summary: 'Список системных настроек', auth: true },
|
||
{ method: 'PUT', path: '/admin/settings', summary: 'Создать или обновить настройку', auth: true },
|
||
{ method: 'GET', path: '/settings/public', summary: 'Публичные настройки (без авторизации)' }
|
||
]
|
||
},
|
||
{
|
||
tag: 'Семья',
|
||
endpoints: [
|
||
{ method: 'POST', path: '/family/groups', summary: 'Создать семейную группу', auth: true },
|
||
{ method: 'GET', path: '/family/users/{userId}/groups', summary: 'Список семей пользователя', auth: true },
|
||
{ method: 'GET', path: '/family/groups/{groupId}', summary: 'Получить семейную группу', auth: true },
|
||
{ method: 'PATCH', path: '/family/groups/{groupId}', summary: 'Обновить семейную группу (название)', auth: true },
|
||
{
|
||
method: 'DELETE',
|
||
path: '/family/groups/{groupId}',
|
||
summary: 'Удалить семейную группу',
|
||
description: 'Только создатель семьи. Удаляет всех участников, приглашения, чаты, сообщения и медиа семьи.',
|
||
auth: true
|
||
},
|
||
{ method: 'POST', path: '/family/groups/{groupId}/members', summary: 'Добавить участника', auth: true },
|
||
{
|
||
method: 'DELETE',
|
||
path: '/family/members/{memberId}',
|
||
summary: 'Исключить участника или выйти из семьи',
|
||
description: 'Создатель может удалить участника; участник может удалить себя («Выйти»). Владельца семьи удалить нельзя.',
|
||
auth: true
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/family/groups/{groupId}/invites',
|
||
summary: 'Пригласить участника или бота',
|
||
description: 'Люди получают pending-приглашение. Системные боты и боты других пользователей добавляются автоматически через auto-accept приглашения.',
|
||
auth: true
|
||
},
|
||
{ method: 'GET', path: '/family/groups/{groupId}/invite-search', summary: 'Поиск пользователей и ботов для приглашения', auth: true },
|
||
{ method: 'GET', path: '/family/invites', summary: 'Входящие приглашения', auth: true },
|
||
{ method: 'POST', path: '/family/invites/{inviteId}/respond', summary: 'Принять или отклонить приглашение', auth: true },
|
||
{ method: 'GET', path: '/family/groups/{groupId}/presence', summary: 'Онлайн-статус участников семьи', auth: true }
|
||
]
|
||
},
|
||
{
|
||
tag: 'Чат',
|
||
endpoints: [
|
||
{
|
||
method: 'GET',
|
||
path: '/chat/groups/{groupId}/rooms',
|
||
summary: 'Список чатов семьи',
|
||
description: 'Автосинхронизация DIRECT/BOT через syncFamilyChats. Поля: type, peerUserId, botUsername, isE2E.',
|
||
auth: true
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/chat/groups/{groupId}/rooms',
|
||
summary: 'Создать групповой чат',
|
||
description: 'Минимум 3 участника. Личные DIRECT создаются автоматически.',
|
||
auth: true
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/chat/groups/{groupId}/e2e-rooms',
|
||
summary: 'Создать секретный E2E-чат',
|
||
description: 'Тело: { "peerUserId": "..." }. Только с участниками семьи (не ботами).',
|
||
auth: true
|
||
},
|
||
{ method: 'PATCH', path: '/chat/rooms/{roomId}', summary: 'Настройки чата (название, mute)', auth: true },
|
||
{ method: 'DELETE', path: '/chat/rooms/{roomId}', summary: 'Удалить чат', description: 'GENERAL удалить нельзя. E2E, DIRECT, BOT, GROUP — доступно участникам.', auth: true },
|
||
{ method: 'POST', path: '/chat/rooms/{roomId}/members', summary: 'Добавить участника в групповой чат', auth: true },
|
||
{ method: 'DELETE', path: '/chat/rooms/{roomId}/members/{memberUserId}', summary: 'Удалить участника из чата', auth: true },
|
||
{
|
||
method: 'GET',
|
||
path: '/chat/rooms/{roomId}/messages',
|
||
summary: 'Сообщения чата',
|
||
description: 'Query: limit (по умолчанию 50), beforeMessageId. Поле isEncrypted на сообщениях E2E.',
|
||
auth: true
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/chat/rooms/{roomId}/messages',
|
||
summary: 'Отправить сообщение',
|
||
description: 'type: TEXT|IMAGE|AUDIO|VOICE|FILE|EMOJI|POLL. isEncrypted обязателен для E2E. BOT — только через /bots/...',
|
||
auth: true
|
||
},
|
||
{ method: 'PATCH', path: '/chat/messages/{messageId}', summary: 'Редактировать сообщение', auth: true },
|
||
{ method: 'DELETE', path: '/chat/messages/{messageId}', summary: 'Удалить сообщение', auth: true },
|
||
{ method: 'POST', path: '/chat/messages/{messageId}/vote', summary: 'Голос в опросе', auth: true },
|
||
{ method: 'POST', path: '/chat/rooms/{roomId}/read', summary: 'Отметить чат прочитанным', auth: true },
|
||
{ method: 'POST', path: '/chat/rooms/{roomId}/mute', summary: 'Включить/выключить уведомления', auth: true }
|
||
]
|
||
},
|
||
{
|
||
tag: 'Медиа',
|
||
endpoints: [
|
||
{ method: 'POST', path: '/media/avatars/upload-url', summary: 'URL для загрузки аватара', auth: true },
|
||
{ method: 'GET', path: '/media/stream/{token}', summary: 'Потоковая выдача медиа' },
|
||
{ method: 'POST', path: '/media/chat/{roomId}/media/upload-url', summary: 'URL для медиа чата', auth: true }
|
||
]
|
||
},
|
||
{
|
||
tag: 'Telegram Bot API',
|
||
endpoints: [
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/sendMessage',
|
||
summary: 'Отправить текстовое сообщение',
|
||
description: 'Параметры: chat_id, text, reply_markup? (inline/reply/remove).'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/editMessageText',
|
||
summary: 'Редактировать текст сообщения',
|
||
description: 'Параметры: chat_id, message_id, text, reply_markup?'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/editMessageReplyMarkup',
|
||
summary: 'Редактировать клавиатуру сообщения',
|
||
description: 'Параметры: chat_id, message_id, reply_markup'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/answerCallbackQuery',
|
||
summary: 'Ответ на callback_query',
|
||
description: 'Параметры: callback_query_id, text?, show_alert?, url?'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/sendPhoto',
|
||
summary: 'Отправить фото',
|
||
description: 'Параметры: chat_id, photo (URL или file_id), caption?, reply_markup?'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/sendDocument',
|
||
summary: 'Отправить документ',
|
||
description: 'Параметры: chat_id, document (URL или file_id), caption?, reply_markup?'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/getMe',
|
||
summary: 'Информация о боте',
|
||
description: 'Telegram-совместимый формат ответа { ok, result }. Авторизация — токен в URL.'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/getUpdates',
|
||
summary: 'Long polling входящих Update',
|
||
description: 'Параметры: offset, limit (до 100), timeout (до 50 сек). Недоступен при активном webhook.'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/setWebhook',
|
||
summary: 'Установить webhook URL',
|
||
description: 'Тело: url, secret_token?, drop_pending_updates?'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/deleteWebhook',
|
||
summary: 'Удалить webhook'
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bot{token}/getWebhookInfo',
|
||
summary: 'Информация о webhook'
|
||
}
|
||
]
|
||
},
|
||
{
|
||
tag: 'BotFather',
|
||
endpoints: [
|
||
{ method: 'GET', path: '/bots', summary: 'Список моих ботов', auth: true },
|
||
{ method: 'POST', path: '/bots', summary: 'Создать бота', description: 'Возвращает token один раз.', auth: true },
|
||
{
|
||
method: 'GET',
|
||
path: '/bots/by-username/{botRef}/messages',
|
||
summary: 'История чата с ботом',
|
||
description: 'Сообщения пользователя с ботом в хронологическом порядке.',
|
||
auth: true
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bots/by-username/{botRef}/messages',
|
||
summary: 'Написать боту',
|
||
description: 'Inbound-сообщение пользователя → RabbitMQ → webhook/getUpdates',
|
||
auth: true
|
||
},
|
||
{
|
||
method: 'POST',
|
||
path: '/bots/by-username/{botRef}/callback',
|
||
summary: 'Нажатие inline-кнопки',
|
||
description: 'Тело: { messageId, callbackData } → callback_query Update → webhook/getUpdates',
|
||
auth: true
|
||
},
|
||
{ method: 'GET', path: '/bots/{botId}', summary: 'Получить бота', auth: true },
|
||
{ method: 'PATCH', path: '/bots/{botId}', summary: 'Обновить name / username', auth: true },
|
||
{ method: 'DELETE', path: '/bots/{botId}', summary: 'Удалить бота', auth: true },
|
||
{ method: 'POST', path: '/bots/{botId}/revoke-token', summary: 'Перевыпустить токен', auth: true },
|
||
{ method: 'PATCH', path: '/bots/{botId}/web-app', summary: 'Настроить Mini App URL', auth: true },
|
||
{
|
||
method: 'POST',
|
||
path: '/bots/web-app/validate',
|
||
summary: 'Проверить initData Mini App',
|
||
description: 'HMAC-SHA256 валидация как в Telegram Web Apps.'
|
||
}
|
||
]
|
||
},
|
||
{
|
||
tag: 'Администрирование ботов',
|
||
endpoints: [
|
||
{ method: 'GET', path: '/admin/bots', summary: 'Список всех ботов', description: 'Требует bots.manage.all', auth: true },
|
||
{ method: 'GET', path: '/admin/bots/metrics', summary: 'Метрики ботов', auth: true },
|
||
{ method: 'GET', path: '/admin/bots/{botId}', summary: 'Получить бота (админ)', auth: true },
|
||
{ method: 'PATCH', path: '/admin/bots/{botId}/active', summary: 'Заблокировать / разблокировать бота', auth: true }
|
||
]
|
||
},
|
||
{
|
||
tag: 'Уведомления',
|
||
endpoints: [
|
||
{ method: 'GET', path: '/notifications', summary: 'Список уведомлений', auth: true },
|
||
{ method: 'PATCH', path: '/notifications/{notificationId}/read', summary: 'Удалить просмотренное', auth: true },
|
||
{ method: 'DELETE', path: '/notifications', summary: 'Удалить все уведомления', auth: true }
|
||
]
|
||
}
|
||
];
|