From 16845a78ae0feba3a6517a6122a824b07c2115e9 Mon Sep 17 00:00:00 2001 From: GitPolyakoff Date: Tue, 14 Jul 2026 19:13:25 +0300 Subject: [PATCH 1/3] docs(ru): sync outdated pages and add missing translations --- astro.config.mjs | 6 + .../docs/ru/guides/account-deletion.mdx | 18 +- .../docs/ru/guides/appearance-preferences.mdx | 12 +- src/content/docs/ru/guides/bans-appeals.mdx | 8 +- src/content/docs/ru/guides/connections.mdx | 9 +- src/content/docs/ru/guides/contributing.mdx | 32 +- .../docs/ru/guides/developers/console.mdx | 4 +- .../ru/guides/developers/leaked-secrets.mdx | 73 ++++ .../docs/ru/guides/developers/oauth-apps.mdx | 9 + .../docs/ru/guides/developers/overview.mdx | 10 +- .../docs/ru/guides/developers/public-api.mdx | 26 +- .../ru/guides/developers/sdk-contributing.mdx | 193 ++++++++++ src/content/docs/ru/guides/developers/sdk.mdx | 343 ++++++++++++++++++ .../ru/guides/official-discord-server.mdx | 14 +- .../docs/ru/guides/profile-settings.mdx | 12 +- .../docs/ru/guides/support-tickets.mdx | 4 +- .../docs/ru/guides/translation-status.mdx | 32 ++ src/content/docs/ru/guides/user-directory.mdx | 8 +- .../docs/ru/guides/vtc-announcements.mdx | 4 +- src/content/docs/ru/guides/vtc-creating.mdx | 6 +- src/content/docs/ru/guides/vtc-directory.mdx | 15 +- src/content/docs/ru/guides/vtc-disbanding.mdx | 6 +- src/content/docs/ru/guides/vtc-events.mdx | 7 +- .../docs/ru/guides/vtc-recruitment.mdx | 8 +- .../docs/ru/guides/vtc-roles-permissions.mdx | 15 +- src/content/docs/ru/guides/vtc-visibility.mdx | 8 +- src/content/docs/ru/index.mdx | 4 + 27 files changed, 804 insertions(+), 82 deletions(-) create mode 100644 src/content/docs/ru/guides/developers/leaked-secrets.mdx create mode 100644 src/content/docs/ru/guides/developers/sdk-contributing.mdx create mode 100644 src/content/docs/ru/guides/developers/sdk.mdx create mode 100644 src/content/docs/ru/guides/translation-status.mdx diff --git a/astro.config.mjs b/astro.config.mjs index a7639aa..527663d 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -421,6 +421,9 @@ export default defineConfig({ { slug: "guides/developers/leaked-secrets", label: "Leaked API Keys & Secrets", + translations: { + ru: "Утечка API-ключей и секретов", + }, }, ], }, @@ -450,6 +453,9 @@ export default defineConfig({ { slug: "guides/translation-status", label: "Translation Status", + translations: { + ru: "Статус перевода", + }, }, ], }, diff --git a/src/content/docs/ru/guides/account-deletion.mdx b/src/content/docs/ru/guides/account-deletion.mdx index 86f7eec..3929534 100644 --- a/src/content/docs/ru/guides/account-deletion.mdx +++ b/src/content/docs/ru/guides/account-deletion.mdx @@ -2,7 +2,7 @@ title: Удаление аккаунта description: Как навсегда удалить свой аккаунт TrucklineMP и что происходит при выполнении этого действия. version: 1.2.0 -lastUpdated: 2026-07-08 +lastUpdated: 2026-07-14 --- # Удаление аккаунта @@ -22,7 +22,6 @@ lastUpdated: 2026-07-08 ### Рассмотрите альтернативы - **Сделайте перерыв** — Вы можете просто перестать пользоваться TrucklineMP без удаления учётной записи -- **Передайте права на VTC** — Если вы являетесь владельцем компании, сначала передайте управление ею - **Экспортируйте свои данные** — Запросите выгрузку ваших данных перед удалением - **Отключите сторонние аккаунты** — Отвяжите привязанные сервисы, если планируете регистрироваться заново @@ -31,6 +30,7 @@ lastUpdated: 2026-07-08 - Все ваши данные будут стёрты навсегда - Вы не сможете восстановить аккаунт после его удаления - Ваши имя пользователя и уникальный идентификатор смогут занять другие люди +- Если включена двухфакторная аутентификация, для подтверждения удаления вам потребуется ввести проверочный или резервный код --- @@ -48,7 +48,6 @@ lastUpdated: 2026-07-08 - Информация о привязанных аккаунтах ### Что может остаться -- Права собственности на VTC должны быть переданы до удаления аккаунта - Некоторые обезличенные данные могут храниться для ведения статистики и аналитики - Юридические записи могут сохраняться в соответствии с требованиями законодательства @@ -69,7 +68,8 @@ lastUpdated: 2026-07-08 ### Шаг 3: Подтверждение действия 1. Введите слово `DELETE` в поле подтверждения 2. Кнопка удаления станет активной по завершении обратного отсчёта -3. Нажмите **Delete My Account** +3. Если у вас включена двухфакторная аутентификация, вам будет предложено ввести код из приложения-аутентификатора или резервный код +4. Нажмите **Delete My Account** ### Шаг 4: Завершение - Ваш аккаунт будет немедленно удалён @@ -85,7 +85,7 @@ lastUpdated: 2026-07-08 - Выполняется выход из всех активных сессий - Страница вашего публичного профиля начинает выдавать ошибку 404 - Вы исключаетесь из всех VTC -- Ваши сообщения на форуме могут остаться, но будут полностью обезличены +- Ваши сообщения и темы на форуме удаляются вместе с остальными вашими данными ### Смогу ли я зарегистрироваться заново? - Да, вы сможете создать новый аккаунт на ту же электронную почту @@ -97,7 +97,6 @@ lastUpdated: 2026-07-08 ## Чек-лист перед удалением -- [ ] Передать права собственности на VTC (если вы владеете компанией) - [ ] Запросить экспорт персональных данных - [ ] Сохранить всю важную информацию - [ ] Записать резервные коды (если включена 2FA) @@ -132,12 +131,7 @@ lastUpdated: 2026-07-08 ### "Я не могу удалить свой аккаунт" - Убедитесь, что вы ввели слово `DELETE` в точности так, как требуется (заглавными буквами) - Дождитесь окончания 5-секундного таймера -- Проверьте, не являетесь ли вы владельцем VTC (сначала необходимо передать права) - -### "Я владею VTC и не могу удалить аккаунт" -- Сначала передайте права собственности другому участнику компании -- Перейдите в VTC Settings > Danger Zone > Transfer Ownership -- Как только права будут переданы, вы сможете удалить свой аккаунт +- Если у вас включена двухфакторная аутентификация, убедитесь, что вы ввели действительный код из приложения-аутентификатора или резервный код ### "Я удалил свой аккаунт и хочу его вернуть" - Удаление аккаунта необратимо, восстановить его невозможно diff --git a/src/content/docs/ru/guides/appearance-preferences.mdx b/src/content/docs/ru/guides/appearance-preferences.mdx index 86ea14a..b6199fa 100644 --- a/src/content/docs/ru/guides/appearance-preferences.mdx +++ b/src/content/docs/ru/guides/appearance-preferences.mdx @@ -2,7 +2,7 @@ title: Внешний вид и предпочтения description: Настройте внешний вид TrucklineMP с помощью тем оформления, управляйте авторизованными приложениями, экспортом данных и параметрами форума. version: 1.2.0 -lastUpdated: 2026-07-08 +lastUpdated: 2026-07-14 --- # Внешний вид и предпочтения @@ -51,6 +51,16 @@ lastUpdated: 2026-07-08 --- +## Региональные настройки + +Настройте параметры, специфичные для вашего региона. + +### Доступ к региональным настройкам +1. Перейдите в **Settings** > вкладка **Regional** +2. Или перейдите по адресу `trucklinemp.com/user/me/settings?tab=regional` + +--- + ## Авторизованные приложения Управляйте сторонними приложениями, которые имеют доступ к вашему аккаунту. diff --git a/src/content/docs/ru/guides/bans-appeals.mdx b/src/content/docs/ru/guides/bans-appeals.mdx index 9209506..1d03047 100644 --- a/src/content/docs/ru/guides/bans-appeals.mdx +++ b/src/content/docs/ru/guides/bans-appeals.mdx @@ -2,7 +2,7 @@ title: Баны и апелляции description: Узнайте о публичных записях банов, проверьте свой статус и подайте апелляцию на бан в TrucklineMP. version: 1.2.0 -lastUpdated: 2026-07-09 +lastUpdated: 2026-07-14 --- # Баны и апелляции @@ -80,9 +80,9 @@ TrucklineMP публикует определенные записи модер ## После вынесения решения -- **Одобрено**: Ограничения снимаются согласно инструкциям персонала. Возможно, вам потребуется выйти из системы и войти снова. -- **Отклонено**: В тикете отображается результат. Перед следующей апелляцией может действовать период ожидания. -- **Частично**: Некоторые ограничения сняты, другие остаются. Внимательно прочитайте ответ. +- **Принято**: Ограничения снимаются согласно инструкциям персонала. Возможно, вам потребуется выйти из аккаунта и войти снова. +- **Отклонено**: В тикете указан результат. Перед подачей новой апелляции может действовать период ожидания. +- **Отозвано**: Вы (или персонал от вашего имени) отозвали апелляцию до вынесения решения. --- diff --git a/src/content/docs/ru/guides/connections.mdx b/src/content/docs/ru/guides/connections.mdx index ffe53fa..ad8ab0c 100644 --- a/src/content/docs/ru/guides/connections.mdx +++ b/src/content/docs/ru/guides/connections.mdx @@ -2,7 +2,7 @@ title: Подключения description: Привязывайте и управляйте сторонними аккаунтами — Discord, Google, YouTube и Twitch — в вашем профиле TrucklineMP. version: 1.2.0 -lastUpdated: 2026-07-08 +lastUpdated: 2026-07-14 --- # Подключения @@ -27,6 +27,7 @@ lastUpdated: 2026-07-08 | **Google** | Подключено / Отключено | Нет | | **YouTube** | Подключено / Отключено | Да | | **Twitch** | Подключено / Отключено | Да | +| **Patreon** | Скоро | Да | --- @@ -131,6 +132,12 @@ lastUpdated: 2026-07-08 --- +## Patreon + +Подключение к Patreon планируется, но пока недоступно — на карточке подключения отображается надпись **Скоро**, и пока её нельзя использовать для подключения аккаунта. После включения этой функции появится возможность включать и выключать отображение, как на YouTube и Twitch. + +--- + ## Индикаторы статусов подключения ### Успех diff --git a/src/content/docs/ru/guides/contributing.mdx b/src/content/docs/ru/guides/contributing.mdx index eeb8e56..a8529a5 100644 --- a/src/content/docs/ru/guides/contributing.mdx +++ b/src/content/docs/ru/guides/contributing.mdx @@ -1,8 +1,8 @@ --- title: Помощь с переводом description: Полное руководство по участию в переводе документации TrucklineMP — структура файлов, стандарты качества и процесс отправки. -version: 1.2.0 -lastUpdated: 2026-07-08 +version: 1.3.0 +lastUpdated: 2026-07-14 --- # Помощь с переводом @@ -13,6 +13,32 @@ lastUpdated: 2026-07-08 TrucklineMP — это глобальное сообщество. Перевод нашей документации помогает игрокам и руководителям VTC по всему миру понять, как пользоваться платформой на их родном языке. Качественные переводы делают платформу более доступной и дружелюбной. +## Присоединяйтесь к сообществу участников + +Хотите помочь с переводом или у вас есть вопросы? Присоединяйтесь к нашему специальному Discord-серверу для контрибьюторов: + +[https://discord.gg/jsuGrx4Rbv](https://discord.gg/jsuGrx4Rbv) + +Это место, где можно пообщаться с другими переводчиками, задать вопросы и скоординировать работу над документацией. + +## Версионирование документов + +Каждая страница документации содержит два поля метаданных: + +```yaml +--- +title: Example Page +description: ... +version: 1.2.0 +lastUpdated: 2026-07-09 +--- +``` + +- **`version`** определяет версию контента на странице. Когда в английскую страницу вносятся значимые изменения, её версия повышается. +- **`lastUpdated`** это дата последнего редактирования файла. + +Когда вы переводите страницу или обновляете перевод, **копируйте `version` с текущей английской страницы** и устанавливайте `lastUpdated` сегодняшнюю дату. Перевод, версия которого совпадает с английской страницей, отображается как **Актуальный** на странице [Статуса перевода](/ru/guides/translation-status/); при несовпадении версий он помечается как **Устаревший**, а на переведенной странице появляется баннер с предупреждением. Оба поля обязательны — автоматическая проверка CI отклонит pull request, в котором они отсутствуют. + ## Поддерживаемые в данный момент языки | Локаль | Язык | Статус | @@ -371,4 +397,4 @@ locales: { ## Признание заслуг -Имена переводчиков будут указаны в документации. Спасибо, что помогаете сделать TrucklineMP доступным для каждого! +Имена переводчиков и участников проекта указываются на странице [Участники](/ru/guides/contributors/). Спасибо, что помогаете сделать TrucklineMP доступным для каждого! diff --git a/src/content/docs/ru/guides/developers/console.mdx b/src/content/docs/ru/guides/developers/console.mdx index 8238973..b5cb17d 100644 --- a/src/content/docs/ru/guides/developers/console.mdx +++ b/src/content/docs/ru/guides/developers/console.mdx @@ -28,7 +28,7 @@ lastUpdated: 2026-07-09 | Страница | Назначение | |------|---------| -| **Ключи API** | Создание и отзыв ключей `tl_` для каждого проекта | +| **Ключи API** | Создание и отзыв ключей `tlmp_api_` для каждого проекта | | **Приложения OAuth** | Регистрация и настройка приложений OAuth | | **Вебхуки** | Подписка на push-уведомления о событиях платформы | | **Библиотека API** | Встроенный ReDoc для `/api/v1/openapi.json` | @@ -64,7 +64,7 @@ lastUpdated: 2026-07-09 ## Ключи API -- Префикс: `tl_` +- Префикс: `tlmp_api_` (в старых ключах может по-прежнему использоваться устаревший префикс `tl_`) - Максимум **10 активных ключей** на проект - Секрет показывается **один раз** при создании - Доступ только для чтения к публичным данным REST плюс более высокие ограничения скорости diff --git a/src/content/docs/ru/guides/developers/leaked-secrets.mdx b/src/content/docs/ru/guides/developers/leaked-secrets.mdx new file mode 100644 index 0000000..dc76cd1 --- /dev/null +++ b/src/content/docs/ru/guides/developers/leaked-secrets.mdx @@ -0,0 +1,73 @@ +--- +title: Утечка API-ключей и секретов +description: Что делать, если API-ключ TrucklineMP, секрет клиента OAuth или секрет подписи вебхука оказались в открытом доступе. +version: 1.2.0 +lastUpdated: 2026-07-14 +--- + +# Утечка API-ключей и секретов + +Если секрет TrucklineMP — публичный API-ключ (`tlmp_api_...` или устаревший ключ `tl_...`), секрет клиента OAuth (`tlmp_secret_...`), токен OAuth (`tlmp_oat_...` / `tlmp_ort_...`) или секрет подписи вебхука — был закоммичен в публичный репозиторий, вставлен в публичный канал или иным образом скомпрометирован, немедленно считайте его утекшим и выполните следующие шаги. + +TrucklineMP участвует в программе [сканирования секретов GitHub](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning). Если GitHub обнаружит шаблон секрета TrucklineMP в публичном репозитории, эта страница является руководством по устранению проблемы, на которое ссылается данное предупреждение. + +## 1. Немедленно смените секрет + +Скомпрометированные секреты следует считать утекшими, а не просто "находящимися под угрозой". Ротация удаляет утекшее значение из службы, независимо от того, было ли оно уже использовано злоумышленниками. + +### API-ключи (`tlmp_api_...`, или устаревшие `tl_...`) + +1. Войдите в систему и откройте [Консоль разработчика](https://trucklinemp.com/developer). +2. Выберите проект, которому принадлежит ключ. +3. Удалите скомпрометированный ключ и сгенерируйте новый. +4. Обновите ключ везде, где он используется (серверы, секреты CI, боты). Старый ключ перестает работать в тот момент, когда он удален. + +### Секреты клиента OAuth + +1. Откройте [Консоль разработчика](https://trucklinemp.com/developer) → **OAuth Apps** → ваше приложение. +2. Перегенерируйте секрет клиента в настройках приложения. +3. Обновите секрет в конфигурации вашего приложения на стороне сервера. Существующие пользовательские сессии не будут затронуты, но любой код, всё ещё использующий старый секрет, не сможет получить новые токены. + +### Секреты подписи вебхуков + +1. Откройте [Консоль разработчика](https://trucklinemp.com/developer) → **Webhooks** → затронутая подписка. +2. Перегенерируйте секрет подписи. +3. Обновите обработчик вебхуков, чтобы он проверял подписи с помощью нового секрета. + +## 2. Удалите секрет из истории исходного кода + +Удаления файла или строки в новом коммите **недостаточно** — секрет остаётся доступным для чтения в истории git. Перезапишите историю, чтобы полностью его удалить: + +- [GitHub: удаление конфиденциальных данных из репозитория](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository) +- Инструменты: [git filter-repo](https://github.com/newren/git-filter-repo) или [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/) + +Если репозиторий публичный и был клонирован или форкнут, предполагайте, что старое значение навсегда скомпрометировано даже после переписывания истории — именно ротация (шаг 1) защищает ваш аккаунт, а не очистка истории. + +## 3. Проверьте на наличие злоупотреблений + +- API-ключи: просмотрите объем запросов и их источники для проекта в аналитике/журнале аудита в Консоли разработчика. +- OAuth-приложения: просмотрите недавние авторизации на наличие пользователей, которых вы не узнаёте. +- Вебхуки: просмотрите недавние доставки на предмет неожиданной активности на эндпоинте. + +Если вы заметили активность, которую не инициировали, обратитесь в службу поддержки (ниже), чтобы команда могла провести дальнейшее расследование. + +## 4. Предотвращение будущих утечек + +- Никогда не коммитьте секреты в систему контроля версий. Используйте переменные окружения или менеджер секретов. +- Добавьте хук pre-commit или проверку CI (например, [gitleaks](https://github.com/gitleaks/gitleaks), [trufflehog](https://github.com/trufflesecurity/trufflehog)), чтобы перехватывать секреты до того, как они будут отправлены на сервер. +- Ограничивайте область действия OAuth-приложений и API-ключей только тем, что действительно необходимо для интеграции. + +## Сообщение об утечке или подозрительной активности + +Если вы считаете, что секрет TrucklineMP был раскрыт или использован не по назначению, и вам нужна помощь помимо самостоятельной ротации, свяжитесь с нами: + +- **Discord:** [https://discord.gg/trucklinemp](https://discord.gg/trucklinemp) +- **Email:** support@trucklinemp.com + +## Связанные руководства + +- [Обзор платформы для разработчиков](/ru/guides/developers/overview/) +- [Публичный API](/ru/guides/developers/public-api/) +- [Приложения OAuth](/ru/guides/developers/oauth-apps/) +- [Вебхуки](/ru/guides/developers/webhooks/) +- [Безопасность аккаунта](/ru/guides/account-security/) diff --git a/src/content/docs/ru/guides/developers/oauth-apps.mdx b/src/content/docs/ru/guides/developers/oauth-apps.mdx index 75ed154..7349416 100644 --- a/src/content/docs/ru/guides/developers/oauth-apps.mdx +++ b/src/content/docs/ru/guides/developers/oauth-apps.mdx @@ -19,6 +19,14 @@ OAuth работает отдельно от публичных ключей API 4. На странице **OAuth** укажите **redirect URIs** (по одному в строке) и выберите **scopes**. 5. Сохраните изменения. Скопируйте **client secret**, когда он отобразится. Позже его нельзя будет восстановить. +### Правила для Redirect URI + +- **Точное совпадение** требуется во время авторизации и получения токена (включая путь, порт и завершающий слэш). +- **https://** публичные хосты разрешены. +- **http://** разрешен только для хостов локальной разработки: `localhost`, `*.localhost`, `127.x.x.x`, диапазонов частных локальных сетей (LAN) (`10/8`, `172.16/12`, `192.168/16`) и `host.docker.internal`. +- **Пользовательские схемы приложений** разрешены для нативных клиентов (например, `myapp://callback`). +- Фрагменты (`#...`) и встроенные учетные данные (`user:pass@`) отклоняются. + ### Типы приложений | Тип | Секретный ключ клиента | Типичное использование | @@ -132,6 +140,7 @@ curl -H "Authorization: Bearer tlmp_ACCESS_TOKEN" \ | `name` | string | Отображаемое имя | | `picture` | string | URL-адрес аватара | | `handle` | string | Публичный `@handle` (может быть null) | +| `steam_id` | string \| null | Привязанный SteamID64 | ### С областью доступа `vtc:read` diff --git a/src/content/docs/ru/guides/developers/overview.mdx b/src/content/docs/ru/guides/developers/overview.mdx index 3215a37..ad38821 100644 --- a/src/content/docs/ru/guides/developers/overview.mdx +++ b/src/content/docs/ru/guides/developers/overview.mdx @@ -1,8 +1,8 @@ --- title: Обзор платформы для разработчиков description: Начните работу с платформой для разработчиков TrucklineMP. Включите консоль, создавайте проекты и интегрируйтесь с публичным API или OAuth. -version: 1.2.0 -lastUpdated: 2026-07-08 +version: 1.3.0 +lastUpdated: 2026-07-14 --- # Обзор платформы для разработчиков @@ -30,11 +30,11 @@ TrucklineMP предлагает платформу для разработчи ## Быстрый старт: Публичный API 1. В Консоли разработчика создайте **проект** (project). -2. Сгенерируйте ключ API (префикс `tl_...`). Скопируйте его, когда он отобразится. Позже его нельзя будет просмотреть. +2. Сгенерируйте ключ API (префикс `tlmp_api_...`). Скопируйте его, когда он отобразится. Позже его нельзя будет просмотреть. 3. Отправьте запрос с вашим ключом: ```bash -curl -H "Authorization: Bearer tl_YOUR_API_KEY" \ +curl -H "Authorization: Bearer tlmp_api_YOUR_API_KEY" \ "https://api.trucklinemp.com/vtcs" ``` @@ -69,9 +69,11 @@ curl -H "Authorization: Bearer tl_YOUR_API_KEY" \ | Руководство | Темы | |-------|--------| | [Публичный API](/ru/guides/developers/public-api/) | Аутентификация, базовые URL-адреса, лимиты запросов, обзор эндпоинтов | +| [TypeScript SDK](/ru/guides/developers/sdk/) | Установка `@trucklinemp/sdk`, использование клиента, ошибки, проверка вебхуков | | [Приложения OAuth](/ru/guides/developers/oauth-apps/) | Поток авторизации, области доступа, информацию о пользователях, тестовые пользователи, PKCE, публикация | | [Вебхуки](/ru/guides/developers/webhooks/) | Подписки, подписи, повторные попытки, каталог событий | | [Консоль разработчика](/ru/guides/developers/console/) | Проекты, аналитика, журналы аудита, квоты, тестовая среда | +| [Утечка API-ключей и секретов](/ru/guides/developers/leaked-secrets/) | Что делать, если ключ или секрет был опубликован в открытом доступе | ## Конфиденциальность и соответствие требованиям diff --git a/src/content/docs/ru/guides/developers/public-api.mdx b/src/content/docs/ru/guides/developers/public-api.mdx index 4dcbf12..45a1a32 100644 --- a/src/content/docs/ru/guides/developers/public-api.mdx +++ b/src/content/docs/ru/guides/developers/public-api.mdx @@ -1,8 +1,8 @@ --- title: Публичный API description: Аутентификация, базовые URL-адреса, лимиты запросов и обзор эндпоинтов для публичного REST API TrucklineMP. -version: 1.2.0 -lastUpdated: 2026-07-08 +version: 1.3.0 +lastUpdated: 2026-07-14 --- # Публичный API @@ -16,12 +16,12 @@ lastUpdated: 2026-07-08 Отправьте ваш ключ API в заголовке `Authorization`: ``` -Authorization: Bearer tl_YOUR_API_KEY +Authorization: Bearer tlmp_api_YOUR_API_KEY ``` Ключи API: -- Используют префикс `tl_` (например, `tl_a1b2c3...`). +- Используют префикс `tlmp_api_` (например, `tlmp_api_a1b2c3...`). Старые ключи, выпущенные с устаревшим префиксом `tl_`, всё ещё работают. - Создаются для каждого проекта в [Консоли разработчика](https://trucklinemp.com/developer). - Отображаются **один раз** при создании. Храните их в безопасности. - Предоставляют доступ **только для чтения** к публичным данным. Они не открывают доступ к приватным действиям аккаунта или операциям записи. @@ -29,18 +29,17 @@ Authorization: Bearer tl_YOUR_API_KEY Недействительные или отозванные ключи игнорируются. Запрос рассматривается как анонимный и получает анонимные лимиты запросов. +Если ваш API-ключ оказался в открытом доступе (например, был закоммичен в репозиторий), немедленно смените его — см. [Утечка API-ключей и секретов](/ru/guides/developers/leaked-secrets/). + ### Сессионные cookie Некоторые эндпоинты возвращают дополнительные поля, когда вы авторизованы на trucklinemp.com и отправляете сессионные cookie с запросом (например, поля VTC, доступные только участникам). Это необязательно и предназначено для внутреннего использования. Сторонние интеграции должны полагаться на ключи API и OAuth, где это применимо. ## Базовые URL-адреса -Выберите базовый URL-адрес, который соответствует вашей среде: - | Среда | Базовый URL | Примечания | |-------------|----------|-------| -| Рабочая | `https://api.trucklinemp.com` | Рекомендуется для рабочих интеграций | - +| Рабочая | `https://api.trucklinemp.com` | Хост публичного API | | Локальная | `http://localhost:3000/api/v1` | Локальный сервер разработки веб-приложения | | Тот же источник | `https://trucklinemp.com/api/v1` | Используется в браузере | @@ -66,7 +65,7 @@ https://trucklinemp.com/api/v1/vtcs ```bash curl "https://api.trucklinemp.com/version" -curl -H "Authorization: Bearer tl_YOUR_API_KEY" \ +curl -H "Authorization: Bearer tlmp_api_YOUR_API_KEY" \ "https://api.trucklinemp.com/vtcs?limit=10" ``` @@ -108,13 +107,19 @@ curl -H "Authorization: Bearer tl_YOUR_API_KEY" \ | **VTC** | `GET /vtcs`, `GET /vtcs/{idOrHandle}`, `GET /vtcs/{id}/members`, `GET /vtcs/{id}/news`, `GET /vtcs/{id}/events`, `GET /vtcs/{id}/roles` | | **Мероприятия** | `GET /events`, `GET /events/{eventId}`, `GET /events/{eventId}/attendees`, `GET /events/{eventId}/slots` | | **Новости** | `GET /news`, `GET /news/{newsId}` | -| **Пользователи** | `GET /users/search`, `GET /users/{handleOrId}`, `GET /users/{id}/bans`, `GET /users/{id}/events` | +| **Пользователи** | `GET /users/search`, `GET /users/{handleOrId}`, `GET /users/steam/{steamId}`, `GET /users/batch`, `GET /users/{id}/bans`, `GET /users/{id}/events` | + +Публичные объекты пользователя включают поле `steamId` (строка SteamID64 или `null`, если аккаунт не привязан). Вы также можете получить профиль с помощью `GET /users/{steamId}` или через специальный маршрут `GET /users/steam/{steamId}`. | **Баны** | `GET /bans`, `GET /bans/{id}` | | **Программы** | `GET /programs/badges/{slug}`, `GET /programs/recognition` | | **Сессия** | `GET /session` (самоанализ сессии на основе cookie) | Параметры пути, такие как `{idOrHandle}`, принимают либо числовой ID, либо публичный никнейм там, где это отмечено в спецификации. +## TypeScript SDK + +Для интеграций на базе Node.js вы можете использовать официальный клиент вместо написания запросов `fetch` вручную. См. [TypeScript SDK](/ru/guides/developers/sdk/). + ## Ответы с ошибками Распространенные коды ошибок: @@ -137,3 +142,4 @@ curl -H "Authorization: Bearer tl_YOUR_API_KEY" \ - [Обзор платформы для разработчиков](/ru/guides/developers/overview/) - [Приложения OAuth](/ru/guides/developers/oauth-apps/) (вход пользователей, не требуется для публичных эндпоинтов чтения) - [Вебхуки](/ru/guides/developers/webhooks/) (push-уведомления о событиях) +- [Утечка API-ключей и секретов](/ru/guides/developers/leaked-secrets/) (устранение последствий компрометации ключа) diff --git a/src/content/docs/ru/guides/developers/sdk-contributing.mdx b/src/content/docs/ru/guides/developers/sdk-contributing.mdx new file mode 100644 index 0000000..0e3a2ac --- /dev/null +++ b/src/content/docs/ru/guides/developers/sdk-contributing.mdx @@ -0,0 +1,193 @@ +--- +title: Вклад в SDK +description: Как принять участие в разработке @trucklinemp/sdk — локальная настройка, структура пакета, добавление эндпоинтов, стандарты PR и релизы. +version: 1.1.0 +lastUpdated: 2026-07-14 +--- + +# Участие в разработке TypeScript SDK + +Спасибо, что помогаете улучшать `@trucklinemp/sdk`, официальный набор инструментов TypeScript и JavaScript для [Публичного API](/ru/guides/developers/public-api/) TrucklineMP, OAuth и вебхуков. + +Это руководство предназначено для тех, кто хочет изменить сам **пакет SDK** (новые методы, исправления ошибок, типы, документация в репозитории). Если вам нужно только **использовать** SDK в приложении, вместо этого ознакомьтесь с разделом [TypeScript SDK](/ru/guides/developers/sdk/). + +| | | +|---|---| +| Пакет | `@trucklinemp/sdk` | +| Исходный код | [github.com/trucklinemp/sdk](https://github.com/trucklinemp/sdk) | +| npm | [npmjs.com/package/@trucklinemp/sdk](https://www.npmjs.com/package/@trucklinemp/sdk) | +| Лицензия | MIT | + +## Перед началом работы + +1. Откройте [issue](https://github.com/trucklinemp/sdk/issues) для крупных изменений, чтобы мейнтейнеры могли согласовать архитектуру. +2. Проверьте [спецификацию OpenAPI](https://trucklinemp.com/api/v1/openapi.json) и [руководство по публичному API](/ru/guides/developers/public-api/), чтобы узнать реальный HTTP-контракт. SDK — это тонкий клиент, он должен отражать публичные маршруты, а не выдумывать приватные. +3. Отдавайте предпочтение небольшим, сфокусированным pull request-ам вместо масштабных переписываний кода. + +## Требования + +- **Node.js 18+** (клиент полагается на глобальный `fetch`) +- npm (поставляется вместе с Node) +- Аккаунт на GitHub и форк [trucklinemp/sdk](https://github.com/trucklinemp/sdk) + +Необязательно для ручных проверок интеграции: + +- API-ключ из [Консоли разработчика](https://trucklinemp.com/developer) TrucklineMP +- Локальный публичный API по адресу `http://localhost:3000/api/v1`, если вы запускаете веб-приложение локально + +## Клонирование и установка + +```bash +git clone https://github.com/YOUR_USER/sdk.git +cd sdk +npm install +``` + +Если вы работаете из структуры монорепозитория Truckline, пакет находится в папке `sdk/` с теми же скриптами. + +## Скрипты + +| Команда | Назначение | +|---------|---------| +| `npm run build` | Сборка с помощью tsup → `dist/` (точки входа main + oauth + webhooks) | +| `npm run typecheck` | `tsc --noEmit` | +| `npm test` | Юнит-тесты Vitest | +| `npm run prepublishOnly` | typecheck + test + build (для мейнтейнеров) | + +Всегда запускайте их перед открытием PR: + +```bash +npm run typecheck +npm test +npm run build +``` + +## Структура пакета + +``` +sdk/ +├── src/ +│ ├── index.ts # Основные экспорты +│ ├── oauth-entry.ts # @trucklinemp/sdk/oauth +│ ├── webhooks-entry.ts # @trucklinemp/sdk/webhooks +│ ├── client.ts # Класс Truckline +│ ├── http.ts # fetch, повторные попытки, хуки +│ ├── resources.ts # vtcs, users, events, … +│ ├── models.ts # Типы публичных ответов +│ ├── oauth.ts # TrucklineOAuth + PKCE +│ ├── webhooks.ts # HMAC + обработчики (Node crypto) +│ ├── pagination.ts +│ ├── batch.ts +│ ├── errors.ts +│ ├── types.ts +│ └── version.ts +├── tests/ +├── examples/ +├── dist/ +├── package.json +└── … +``` + +### Правила проектирования + +- **Тонкие обертки** над HTTP-путями. Отдавайте предпочтение `this.http.get("/users/…")` вместо тяжелого маппинга. +- **Кодируйте сегменты пути** с помощью `encodeURIComponent`. +- **Передавайте объекты запроса** через `withOpts`, чтобы `RequestOptions` оставались единообразными. +- **Типы находятся в `models.ts`** — поддерживайте их в соответствии с публичным API и OpenAPI. +- **Криптография вебхуков остается в `webhooks.ts`** (только для Node). Отдавайте предпочтение `@trucklinemp/sdk/webhooks` для серверных обработчиков. +- **OAuth находится в `oauth.ts`** и экспортируется по пути `/oauth`. +- Критические изменения в названиях методов и параметрах следуют семантическому версионированию; необязательные поля ответа могут добавляться без мажорного обновления. + +## Добавление метода публичного API + +Пример: в API добавляется `GET /users/steam/{steamId}`. + +1. Подтвердите путь и параметры в OpenAPI или публичном роутере веб-приложения. +2. Добавьте метод в соответствующий ресурс в `src/resources.ts`: + +```ts +// UsersResource +getBySteam(steamId: string, options?: RequestOptions) { + return this.http.get( + `/users/steam/${encodeURIComponent(steamId)}`, + options, + ); +} +``` + +3. Если вы вводите **новый класс ресурса**, создайте его в классе `Truckline` в файле `src/client.ts` и экспортируйте любые новые типы из `src/index.ts` только в том случае, если они нужны вызывающему коду. +4. Обновите страницу пользовательской документации ([TypeScript SDK](/ru/guides/developers/sdk/)), если изменение затрагивает пользователей. +5. Выполните `npm run build && npm run typecheck`. + +### Запасной выход + +Если маршрут используется редко или все еще меняется, вызывающий код может использовать: + +```ts +await tl.get("/path"); +await tl.request("GET", "/path", { query: { … } }); +``` + +Отдавайте предпочтение именованному методу, как только маршрут станет стабильным и часто используемым. + +## Локальное тестирование с API + +```ts +import { Truckline } from "trucklinemp-sdk"; // или импортируйте из src/index.ts вашего локального репозитория + +const tl = new Truckline({ + apiKey: process.env.TRUCKLINE_API_KEY, + // baseUrl: "http://localhost:3000/api/v1", +}); + +console.log(await tl.meta.version()); +``` + +**Не** коммитьте API-ключи. Используйте только переменные окружения. + +## Pull request-ы + +1. Сделайте форк и создайте ветку от `main` или `master` (в соответствии с веткой по умолчанию в репозитории). +2. Ограничьте изменения одной задачей. +3. Опишите, **что** изменилось и **почему**, и прикрепите ссылку на любую задачу по API или документации. +4. Убедитесь, что `npm run build` и `npm run typecheck` проходят успешно. +5. Обновите README или документацию, если поведение изменилось для пользователей. + +### Стиль коммитов (рекомендуемый) + +```text +feat(sdk): add users.getBySteam +fix(sdk): encode path ids on news.get +docs(sdk): document webhook raw-body requirement +chore(sdk): bump version to 0.1.2 +``` + +## Релизы (для мейнтейнеров) + +Публикация описана в файле `PUBLISH.md` репозитория. Краткое содержание: + +1. Обновите `version` в `package.json` (`npm version patch|minor|major`). +2. Отправьте изменения в ветку по умолчанию (или запустите рабочий процесс публикации). +3. CI собирает, проверяет типы и публикует в **публичный** реестр npm, когда версия новая. + +Контрибьюторам не нужны права на публикацию в npm. Мейнтейнеры выпускают релизы после проверки. + +## Чего мы не ждём + +- Обертки вокруг **приватных**, административных или доступных только по cookie веб-эндпоинтов +- Добавление несвязанных утилит, которые раздувают пакет +- Жесткие сгенерированные типы для каждого поля OpenAPI в каждом релизе (дополнительные инструменты допускаются, если они предварительно обсуждались) +- Секреты, ключи или персональные токены в репозитории + +## Связанные ссылки + +| Ресурс | Ссылка | +|----------|------| +| Использование SDK | [TypeScript SDK](/ru/guides/developers/sdk/) | +| Публичный API | [Публичный API](/ru/guides/developers/public-api/) | +| Вебхуки | [Вебхуки](/ru/guides/developers/webhooks/) | +| Консоль разработчика | [trucklinemp.com/developer](https://trucklinemp.com/developer) | +| OpenAPI | [openapi.json](https://trucklinemp.com/api/v1/openapi.json) | +| Перевод документации | [Перевод документации](/ru/guides/contributing/) | + +Вопросы об API платформы (а не только о пакете SDK) приветствуются через службу поддержки или каналы для разработчиков, указанные на trucklinemp.com. diff --git a/src/content/docs/ru/guides/developers/sdk.mdx b/src/content/docs/ru/guides/developers/sdk.mdx new file mode 100644 index 0000000..dde658a --- /dev/null +++ b/src/content/docs/ru/guides/developers/sdk.mdx @@ -0,0 +1,343 @@ +--- +title: TypeScript SDK +description: Официальное руководство по @trucklinemp/sdk — клиент публичного API, типизированные модели, пагинация, OAuth, вебхуки, ошибки и конфигурация. +version: 2.0.0 +lastUpdated: 2026-07-14 +--- + +# TypeScript SDK + +`@trucklinemp/sdk` это официальный набор инструментов TypeScript и JavaScript для интеграций с TrucklineMP. Он включает в себя: + +- Клиент **Публичного API** (`Truckline`) с типизированными моделями, повторными попытками и помощниками для пагинации +- Помощники **OAuth** (`TrucklineOAuth`, PKCE) для авторизации пользователей +- Проверка подписей **вебхуков** и обработчики доставки (Node.js) + +[Спецификация OpenAPI](https://trucklinemp.com/api/v1/openapi.json) остаётся главным источником истины для каждого поля. SDK отслеживает общие ресурсы и намеренно остаётся легковесным. + +| | | +|---|---| +| Пакет | `@trucklinemp/sdk` | +| Версия | 0.2.x | +| Реестр | [npmjs.com](https://www.npmjs.com/package/@trucklinemp/sdk) | +| Репозиторий | [github.com/trucklinemp/sdk](https://github.com/trucklinemp/sdk) | +| Лицензия | MIT | +| Среда выполнения | Node.js 18+ (глобальный `fetch`); поддерживается работа HTTP-клиента в браузере | + +## Установка + +```bash +npm install @trucklinemp/sdk +``` + +### Точки входа + +| Импорт | Содержимое | +|--------|----------| +| `@trucklinemp/sdk` | Полный клиент, модели, ошибки; OAuth и вебхуки реэкспортируются | +| `@trucklinemp/sdk/oauth` | Только OAuth / PKCE | +| `@trucklinemp/sdk/webhooks` | Только проверка / обработчик вебхуков (использует встроенный модуль Node `crypto`) | + +Отдавайте предпочтение импорту по конкретным путям, если вам нужна меньшая площадь пакета (например, для OAuth в отдельном микросервисе). + +## Быстрый старт (Публичный API) + +1. Включите режим разработчика и создайте проект в [Консоли разработчика](https://trucklinemp.com/developer). +2. Создайте API-ключ (`tlmp_api_...`) и сохраните его в безопасном месте. +3. Вызовите API: + +```ts +import { Truckline, TrucklineError } from "@trucklinemp/sdk"; + +const tl = new Truckline({ + apiKey: process.env.TRUCKLINE_API_KEY, +}); + +console.log(tl.version); // строка версии SDK + +const { user } = await tl.users.get("some-handle"); +console.log(user.webId, user.steamId, user.name); + +const bySteam = await tl.users.getBySteam("76561198000000000"); + +try { + await tl.vtcs.get("missing-vtc"); +} catch (err) { + if (err instanceof TrucklineError) { + console.error(err.status, err.code, err.requestId, err.message); + if (err.isRateLimited) console.error("retry after", err.retryAfter); + } +} +``` + +Анонимные запросы работают для многих публичных маршрутов, но имеют более строгие лимиты. В продакшене всегда отправляйте ключ. + +## Конфигурация + +```ts +new Truckline({ + apiKey: "tlmp_api_...", + baseUrl: undefined, // по умолчанию https://api.trucklinemp.com + timeoutMs: 30_000, + maxRetries: 1, // повторные попытки при 429 и 5xx + retryOnServerError: true, + headers: { "X-App": "my-bot" }, + userAgent: "my-bot/1.0", // только для Node; по умолчанию включает версию SDK + debug: false, + onRequest: ({ method, url, attempt }) => {}, + onResponse: ({ status, requestId, durationMs }) => {}, + fetch: customFetch, // необязательно +}); +``` + +### Базовый URL + +| Опция | Базовый URL | +|--------|----------| +| По умолчанию | `https://api.trucklinemp.com` | +| Локальный сервер | `http://localhost:3000/api/v1` | + +**Не** добавляйте дополнительный `/v1` к `api.trucklinemp.com`. См. [Базовые URL публичного API](/ru/guides/developers/public-api/#base-urls). + +### Информация о лимитах запросов + +После выполнения запроса вы можете проверить последние разобранные заголовки лимитов: + +```ts +await tl.meta.version(); +console.log(tl.lastRateLimit); +// { retryAfter, limit, remaining, reset } +``` + +## Типизированные модели + +Пакет экспортирует типы TypeScript для публичных данных (структуры могут расширяться по мере развития API; необязательные поля остаются необязательными): + +- Пользователи: `PublicUser`, `PublicUserSearchResult`, `PublicUserBans`, … +- VTC / участники: `VtcListItem`, `VtcMember`, `VtcNewsItem`, `VtcRole` +- Мероприятия: `PublicEvent`, `PublicEventAttendee`, `PublicEventSlot` +- Новости, баны, партнёры, значки, игровые серверы, OAuth userinfo, доставка вебхуков + +Даты, получаемые от API, типизированы как ISO-строки (`IsoDateString`). + +Пример: + +```ts +import type { PublicUser } from "@trucklinemp/sdk"; + +const { user } = await tl.users.get("driver"); +const profile: PublicUser = user; +``` + +## Ресурсы + +### Мета / платформа + +```ts +await tl.meta.version(); +await tl.meta.status(); +await tl.meta.stats(); +await tl.meta.partners(); +await tl.meta.rules(); +await tl.meta.session(); +await tl.meta.recruitmentOpen(); +``` + +### Пользователи + +```ts +await tl.users.search({ q: "alex", page: 1, limit: 20 }); +await tl.users.get("handle-or-id-or-steamId64"); +await tl.users.getBySteam("7656119…"); +await tl.users.resolve("handle"); // возвращает PublicUser +await tl.users.batch(["id1", "id2"]); // автоматически разбивает на чанки по 50 +await tl.users.bans(userId); +await tl.users.events(userId, { tab: "upcoming" }); + +for await (const page of tl.users.iterateSearch({ q: "a", limit: 20 })) { + console.log(page.length); +} + +const allMatches = await tl.users.searchAll({ q: "a", maxItems: 100 }); +``` + +Публичные объекты пользователя включают **`steamId`**, если аккаунт привязан. + +### VTC + +```ts +await tl.vtcs.list({ limit: 20, q: "logistics" }); +await tl.vtcs.get("handle-or-id"); +await tl.vtcs.batch([1, 2, 3]); +await tl.vtcs.members("handle"); +await tl.vtcs.news(vtcId); +await tl.vtcs.events(vtcId); +await tl.vtcs.roles(vtcId); +await tl.vtcs.gallery(vtcId); +await tl.vtcs.tier(vtcId); +await tl.vtcs.liveEvents(vtcId); +await tl.vtcs.upcomingEvents(vtcId); + +for await (const members of tl.vtcs.iterateMembers("my-vtc", { limit: 50 })) { + for (const m of members) console.log(m.name, m.steamId); +} + +const everyVtc = await tl.vtcs.listAll({ maxPages: 10 }); +``` + +### Мероприятия, новости, баны, программы, игра + +```ts +await tl.events.list(); +await tl.events.get(eventId); +await tl.events.attendees(eventId); +await tl.events.slots(eventId); + +await tl.news.list(); +await tl.news.get(newsId); + +await tl.bans.list({ page: 1, pageSize: 25, q: "cheat" }); +await tl.bans.get(banId); +for await (const page of tl.bans.iterate({ pageSize: 50 })) { /* … */ } + +await tl.programs.badge("bug-hunter"); +await tl.programs.recognition(); +await tl.game.servers(); +``` + +### Запасной выход + +```ts +await tl.get("/version"); +await tl.request("GET", "/vtcs", { query: { limit: 5 } }); +await tl.post("/path", { body: { … } }); // если в будущем будет задокументирован маршрут для записи +``` + +## Ошибки и повторные попытки + +При неудачных HTTP-ответах выбрасывается ошибка `TrucklineError`: + +| Поле / флаг | Значение | +|--------------|---------| +| `status` | HTTP-статус (`0` при сетевой ошибке / таймауте / прерывании) | +| `code` | Код API или клиента (`NOT_FOUND`, `TIMEOUT`, `ABORTED`, …) | +| `requestId` | Идентификатор корреляции для службы поддержки | +| `retryAfter` | Секунды из заголовка `Retry-After`, если он присутствует | +| `details` | Дополнительные данные от API | +| `isRateLimited` / `isNotFound` / `isUnauthorized` / `isForbidden` | Хелперы | +| `isTimeout` / `isNetworkError` / `isServerError` / `isValidationError` | Хелперы | + +Повторные попытки по умолчанию: до `maxRetries` (по умолчанию `1`) при ошибках **429** и **5xx**, с использованием джиттера. Установите `maxRetries: 0`, чтобы отключить. При сбоях сети запросы также повторяются, если `maxRetries > 0`. + +Таблицы лимитов платформы: [Лимиты запросов](/ru/guides/developers/public-api/#rate-limits). + +## OAuth + +Используйте OAuth, когда вам нужны данные **от лица авторизованного пользователя** (а не только с помощью API-ключа). Полное описание процесса: [Приложения OAuth](/ru/guides/developers/oauth-apps/). + +```ts +import { TrucklineOAuth, generatePkce } from "@trucklinemp/sdk/oauth"; + +const oauth = new TrucklineOAuth({ + clientId: process.env.CLIENT_ID!, + clientSecret: process.env.CLIENT_SECRET, // опустите для публичных клиентов + PKCE + redirectUri: "https://myapp.com/callback", + // siteUrl: "https://trucklinemp.com", +}); + +const pkce = generatePkce(); +const url = oauth.getAuthorizeUrl({ + scope: ["profile", "vtc:read", "presence:read"], + state: "csrf-token", + codeChallenge: pkce.codeChallenge, +}); + +// После редиректа: +const tokens = await oauth.exchangeCode(code, { + codeVerifier: pkce.codeVerifier, +}); +const me = await oauth.userinfo(tokens.access_token); +console.log(me.sub, me.steam_id, me.handle); + +const refreshed = await oauth.refresh(tokens.refresh_token!); +await oauth.revoke(tokens.access_token, "access_token"); +``` + +Правила Redirect URI (localhost / приватная LAN / https): [Приложения OAuth — redirect URIs](/ru/guides/developers/oauth-apps/#redirect-uri-rules). + +`userinfo` с областью видимости `profile` включает `steam_id`, если аккаунт привязан. + +## Вебхуки (Node.js) + +Доставка вебхуков подписывается с помощью HMAC-SHA256 на основе **сырого тела запроса**: + +``` +X-TrucklineMP-Signature: sha256= +X-TrucklineMP-Event: user.banned +X-TrucklineMP-Delivery: +``` + +```ts +import { + createWebhookHandler, + verifyWebhookSignature, + WEBHOOK_SIGNATURE_HEADER, +} from "@trucklinemp/sdk/webhooks"; + +const handle = createWebhookHandler({ + secret: process.env.WEBHOOK_SECRET!, + onEvent: async (event, meta) => { + console.log(meta.type, meta.deliveryId, event); + }, +}); + +// Express: используйте express.raw(), чтобы тело не парсилось заново перед этим +app.post("/hooks/truckline", express.raw({ type: "*/*" }), async (req, res) => { + const result = await handle({ rawBody: req.body, headers: req.headers }); + res.status(result.ok ? 200 : 401).json(result); +}); +``` + +Низкоуровневый вариант: + +```ts +verifyWebhookSignature(rawBody, req.headers[WEBHOOK_SIGNATURE_HEADER], secret); +``` + +Каталог событий и повторные попытки: [Вебхуки](/ru/guides/developers/webhooks/). + +## Примеры + +В репозитории SDK (после `npm run build`): + +| Файл | Назначение | +|------|---------| +| `examples/basic.mjs` | Версия + поиск пользователя | +| `examples/oauth-pkce.mjs` | Вывод URL авторизации + верификатор | +| `examples/webhook-express.mjs` | Минимальный обработчик на Express | + +## Версионирование + +- Методы **SDK**, параметры и класс ошибок следуют семантическому версионированию (`Truckline.VERSION` / версия пакета). +- Поля JSON на **Сервере** могут развиваться; относитесь к новым необязательным полям как к необязательным. +- Критические изменения в клиенте выпускаются как мажорные версии. Смотрите [CHANGELOG](https://github.com/trucklinemp/sdk/blob/main/CHANGELOG.md) пакета. + +## Конфиденциальность + +API-трафик с использованием вашего ключа подлежит такому же логированию и ограничению скорости, как и обычные HTTP-запросы. Ознакомьтесь с [Политикой конфиденциальности](https://id.trucklinemp.com/legal/privacy) и примечаниями к телеметрии [Публичный API](/ru/guides/developers/public-api/). + +## Участие в разработке + +Структура пакета, пулл-реквесты PR и добавление новых методов: [Участие в разработке TypeScript SDK](/ru/guides/developers/sdk-contributing/). + +## Связанные руководства + +| Руководство | Темы | +|-------|--------| +| [Обзор платформы](/ru/guides/developers/overview/) | Режим разработчика, типы интеграций | +| [Публичный API](/ru/guides/developers/public-api/) | Авторизация, базовые URL, лимиты, карта эндпоинтов | +| [Приложения OAuth](/ru/guides/developers/oauth-apps/) | Авторизация, токены, права доступа, redirect URIs | +| [Вебхуки](/ru/guides/developers/webhooks/) | События, подписи, повторные попытки | +| [Консоль разработчика](/ru/guides/developers/console/) | Проекты, ключи, рабочая среда | +| [Участие в разработке SDK](/ru/guides/developers/sdk-contributing/) | Локальная настройка и PR | +| [Утечка API-ключей и секретов](/ru/guides/developers/leaked-secrets/) | Смена ключей после компрометации | diff --git a/src/content/docs/ru/guides/official-discord-server.mdx b/src/content/docs/ru/guides/official-discord-server.mdx index 96e78cc..58b8488 100644 --- a/src/content/docs/ru/guides/official-discord-server.mdx +++ b/src/content/docs/ru/guides/official-discord-server.mdx @@ -1,8 +1,8 @@ --- title: Официальный сервер Discord description: Как главный сервер Discord TrucklineMP связан с веб-сайтом, поддержкой и модерацией. -version: 1.2.0 -lastUpdated: 2026-07-09 +version: 1.3.0 +lastUpdated: 2026-07-14 --- # Официальный сервер Discord @@ -63,6 +63,16 @@ Modbot может направить вас на сайт для подачи а --- +## Discord-сервер контрибьюторов + +Если вы заинтересованы в том, чтобы внести свой вклад в развитие документации TrucklineMP, или хотите пообщаться с другими переводчиками, присоединяйтесь к нашему специальному Discord-серверу для контрибьюторов: + +[https://discord.gg/jsuGrx4Rbv](https://discord.gg/jsuGrx4Rbv) + +Этот сервер существует отдельно от основного сообщества TrucklineMP и предназначен специально для авторов документации и переводчиков. + +--- + ## Связанные руководства - [Варианты подключения Discord](/ru/guides/discord-connection-flows/) diff --git a/src/content/docs/ru/guides/profile-settings.mdx b/src/content/docs/ru/guides/profile-settings.mdx index d5dca78..bb6833c 100644 --- a/src/content/docs/ru/guides/profile-settings.mdx +++ b/src/content/docs/ru/guides/profile-settings.mdx @@ -2,7 +2,7 @@ title: Настройки профиля description: Настройте отображаемое имя, уникальный идентификатор, аватар и социальные ссылки в вашем публичном профиле TrucklineMP. version: 1.2.0 -lastUpdated: 2026-07-08 +lastUpdated: 2026-07-14 --- # Настройки профиля @@ -22,8 +22,8 @@ lastUpdated: 2026-07-08 Ваше публичное имя, видимое всем пользователям платформы. -- **Длина:** 3–24 символа -- **Кулдаун:** Можно изменять один раз в 30 дней +- **Длина:** 2–32 символа +- **Время восстановления:** можно изменять один раз в день - **Видимость:** Отображается в вашем профиле, в VTC, мероприятиях, на форумах и в новостных лентах ### Советы @@ -40,7 +40,7 @@ lastUpdated: 2026-07-08 - **URL-адрес:** `trucklinemp.com/@yourhandle` - **Длина:** 2–15 символов - **Допустимые символы:** Только строчные буквы, цифры и знаки подчёркивания -- **Кулдаун:** Можно изменять один раз в 30 дней +- **Время восстановления:** Можно изменять один раз в 30 дней ### Советы - Делайте его коротким и запоминающимся @@ -116,8 +116,8 @@ lastUpdated: 2026-07-08 ## Устранение неполадок ### "Я не могу изменить своё имя" -- Имя можно изменять только один раз в 30 дней -- Убедитесь, что длина имени составляет от 3 до 24 символов +- Имя можно менять только один раз в день +- Убедитесь, что длина имени составляет от 2 до 32 символов - Проверьте текст на наличие недопустимых символов ### "Мой идентификатор не сохраняется" diff --git a/src/content/docs/ru/guides/support-tickets.mdx b/src/content/docs/ru/guides/support-tickets.mdx index b37d216..1930480 100644 --- a/src/content/docs/ru/guides/support-tickets.mdx +++ b/src/content/docs/ru/guides/support-tickets.mdx @@ -2,7 +2,7 @@ title: Тикеты поддержки description: Открывайте тикеты поддержки для получения помощи, жалоб на игроков и другой помощи в TrucklineMP. version: 1.2.0 -lastUpdated: 2026-07-09 +lastUpdated: 2026-07-14 --- # Тикеты поддержки @@ -60,7 +60,7 @@ lastUpdated: 2026-07-09 - Читать ответы персонала - Добавлять последующие сообщения, пока тикет открыт -- Видеть статус (открыт, ожидает ответа, закрыт) +- Просмотреть статус (новое, открытое, на рассмотрении, приостановлено, решено или закрыто) - Просматривать связанный контекст модерации для апелляций Придерживайтесь одной темы в тикете. Открывайте новый тикет для несвязанных проблем. diff --git a/src/content/docs/ru/guides/translation-status.mdx b/src/content/docs/ru/guides/translation-status.mdx new file mode 100644 index 0000000..eed8b94 --- /dev/null +++ b/src/content/docs/ru/guides/translation-status.mdx @@ -0,0 +1,32 @@ +--- +title: Статус перевода +description: Текущий статус перевода документации на все языки. +version: 1.2.0 +lastUpdated: 2026-07-14 +--- + +import TranslationStatusTable from '../../../components/TranslationStatusTable.astro'; + +# Статус перевода + +На этой странице показано, какие страницы документации переведены и насколько актуален каждый перевод. В каждой ячейке указана версия документа и дата его последнего обновления. Зеленый статус означает, что перевод полностью соответствует английской версии. Оранжевый означает, что перевод отстает. Красный означает, что страница еще не переведена. + + + +## Условные обозначения + +- **Актуальный** - Перевод имеет ту же версию, что и английская страница. +- **Устаревший** - Перевод имеет более старую версию, чем английская страница (или, если версия не задана, отстает более чем на 1 день по дате). +- **Отсутствует** - Перевод для этого языка еще не добавлен. + +Когда в английскую страницу вносятся значимые изменения, ее значение `version` повышается. Переводчики обновляют перевод и устанавливают соответствующую `version` — именно это снова делает его актуальным. + +## Как помочь + +Если вы заметили устаревший перевод или хотите добавить новый, пожалуйста: + +1. Ознакомьтесь с руководством [Помощь с переводом](/ru/guides/contributing/). +2. Создайте pull request на GitHub с вашим переводом. +3. Следуйте структуре файлов и стандартам качества, описанным в руководстве. + +Спасибо за вашу помощь в поддержании нашей документации доступной на разных языках! diff --git a/src/content/docs/ru/guides/user-directory.mdx b/src/content/docs/ru/guides/user-directory.mdx index 259dfcd..a3c4ae5 100644 --- a/src/content/docs/ru/guides/user-directory.mdx +++ b/src/content/docs/ru/guides/user-directory.mdx @@ -2,7 +2,7 @@ title: Каталог пользователей description: Ищите и просматривайте профили пользователей TrucklineMP в публичном каталоге. version: 1.2.0 -lastUpdated: 2026-07-09 +lastUpdated: 2026-07-14 --- # Каталог пользователей @@ -19,12 +19,14 @@ lastUpdated: 2026-07-09 ## Поиск и фильтры -Используйте панель поиска и фильтры для сужения результатов: +Воспользуйтесь строкой поиска, чтобы сузить круг результатов: - **Имя или имя пользователя** по частичному совпадению -- **Принадлежность к VTC**, если доступно +- В каждом результате отображается текущий показатель VTC пользователя (если таковой имеется), когда эта информация доступна - Пагинация для больших наборов результатов +Отдельных элементов управления фильтрацией (таких как фильтрация по VTC) нет — поиск осуществляется только по имени или идентификатору. + Нажмите на пользователя, чтобы открыть его [публичный профиль](/ru/guides/public-profile/). --- diff --git a/src/content/docs/ru/guides/vtc-announcements.mdx b/src/content/docs/ru/guides/vtc-announcements.mdx index bb11b97..09dc308 100644 --- a/src/content/docs/ru/guides/vtc-announcements.mdx +++ b/src/content/docs/ru/guides/vtc-announcements.mdx @@ -2,7 +2,7 @@ title: Объявления VTC description: Настройте отправку вебхук-уведомлений в Discord при совершении важных действий в вашей VTC на платформе TrucklineMP. version: 1.2.0 -lastUpdated: 2026-07-08 +lastUpdated: 2026-07-14 --- # Объявления VTC @@ -160,6 +160,8 @@ URL-адреса вебхуков хранятся в зашифрованном - Отметка о присутствии - Участник одобрен (если требуется ручное одобрение) - Мероприятие отменено автоматически (нет регистраций до начала) +- Заявка на слот +- Решение по слоту (утверждено или отклонено) ### Роли diff --git a/src/content/docs/ru/guides/vtc-creating.mdx b/src/content/docs/ru/guides/vtc-creating.mdx index d6848df..ccb3ea9 100644 --- a/src/content/docs/ru/guides/vtc-creating.mdx +++ b/src/content/docs/ru/guides/vtc-creating.mdx @@ -2,7 +2,7 @@ title: Создание VTC description: Узнайте о требованиях к кандидатам и о том, как создать свою виртуальную транспортную компанию в TrucklineMP. version: 1.2.0 -lastUpdated: 2026-07-09 +lastUpdated: 2026-07-14 --- # Создание VTC @@ -51,11 +51,11 @@ lastUpdated: 2026-07-09 ### Шаг 2: Описание -Напишите историю вашей VTC с использованием Markdown. Минимум 20 символов. Это отображается в вашем публичном профиле. +Напишите свою историю о VTC в формате Markdown. Обязательное поле, до 5 000 символов. Этот текст будет отображаться в вашем общедоступном профиле. ### Шаг 3: Правила -Напишите правила для участников с использованием Markdown. Минимум 20 символов. Кандидаты и участники смогут прочитать их в вашем профиле. +Напишите правила для участников в формате Markdown. Обязательное поле, максимум 5 000 символов. Кандидаты и участники смогут ознакомиться с ними в вашем профиле. ### Шаг 4: Детали diff --git a/src/content/docs/ru/guides/vtc-directory.mdx b/src/content/docs/ru/guides/vtc-directory.mdx index d784ec5..07087ab 100644 --- a/src/content/docs/ru/guides/vtc-directory.mdx +++ b/src/content/docs/ru/guides/vtc-directory.mdx @@ -2,7 +2,7 @@ title: Каталог VTC description: Просматривайте, ищите и фильтруйте Виртуальные Транспортные Компании в TrucklineMP. version: 1.2.0 -lastUpdated: 2026-07-09 +lastUpdated: 2026-07-14 --- # Каталог VTC @@ -13,7 +13,7 @@ lastUpdated: 2026-07-09 Откройте [trucklinemp.com/vtc](https://trucklinemp.com/vtc). -Здесь отображаются только **публичные** и **скрытые** из списков VTC. Приватные VTC скрыты, если у вас нет ссылки-приглашения. +Здесь отображаются только **публичные** VTC. Непубличные и частные VTC скрыты при просмотре каталога, если у вас нет прямой ссылки или приглашения. --- @@ -23,17 +23,20 @@ lastUpdated: 2026-07-09 | Фильтр | Назначение | |--------|---------| -| **Поиск** | Совпадение по названию или имени пользователя VTC | +| **Поиск** | По названию, описанию или игровому тегу VTC | +| **Проверенные** | Показать только проверенные VTC | | **Верифицированные** | Показать только верифицированные VTC | | **Официальные** | Показать официальные VTC платформы | +| **Партнерские** | Показать только партнерские VTC | | **Набор открыт** | VTC, которые в данный момент принимают заявки | | **Язык** | Фильтр основного языка | ### Параметры сортировки -- Сначала новые -- По названию (А-Я) -- По количеству участников +- Сначала самые новые +- Наибольшее количество участников +- Наиболее активные +- По имени (A–Z) Результаты обновляются при изменении фильтров. Пагинация загружает больше VTC, если они доступны. diff --git a/src/content/docs/ru/guides/vtc-disbanding.mdx b/src/content/docs/ru/guides/vtc-disbanding.mdx index c197c32..4ef7e32 100644 --- a/src/content/docs/ru/guides/vtc-disbanding.mdx +++ b/src/content/docs/ru/guides/vtc-disbanding.mdx @@ -2,7 +2,7 @@ title: Расформирование VTC description: Безвозвратно расформируйте свою виртуальную транспортную компанию и узнайте, что происходит с участниками и данными. version: 1.2.0 -lastUpdated: 2026-07-09 +lastUpdated: 2026-07-14 --- # Расформирование VTC @@ -26,8 +26,8 @@ lastUpdated: 2026-07-09 1. Откройте панель **Управление** вашей VTC 2. Перейдите в **Общие настройки** (`/vtc/@handle/manage/settings`) 3. Прокрутите вниз до опасной зоны -4. Выберите **Расформировать VTC** -5. Подтвердите при появлении запроса (вам может потребоваться ввести название VTC) +4. Выберите **Delete VTC** +5. Подтвердите действие при появлении запроса (вам нужно будет ввести название VTC) Только основатель видит эту опцию. diff --git a/src/content/docs/ru/guides/vtc-events.mdx b/src/content/docs/ru/guides/vtc-events.mdx index c4a66e3..67e5be7 100644 --- a/src/content/docs/ru/guides/vtc-events.mdx +++ b/src/content/docs/ru/guides/vtc-events.mdx @@ -2,7 +2,7 @@ title: Мероприятия VTC description: Создавайте конвои и мероприятия, управляйте заявками на участие, слотами, посещаемостью и глобальным календарем мероприятий в TrucklineMP. version: 1.2.0 -lastUpdated: 2026-07-09 +lastUpdated: 2026-07-14 --- # Мероприятия VTC @@ -50,11 +50,10 @@ lastUpdated: 2026-07-09 | Статус | Значение | |--------|---------| | **Иду** | Подтвержденное присутствие | -| **Возможно** | Заинтересован, но не обещает | +| **Не уверен** | Заинтересован, но не готов принять решение | | **Не иду** | Отказался | -| **Лист ожидания** | Места заполнены; в очереди на место | -Когда установлено **максимальное количество участников** и список присутствующих заполнен, новые заявки со статусом "Иду" автоматически переносятся в лист ожидания. +Если установлено **максимальное количество участников** и список участников, которые подтвердили участие, заполнен, новые подтверждения участия автоматически помечаются как "в списке ожидания" до тех пор, пока не освободится место. ### Отметка о присутствии diff --git a/src/content/docs/ru/guides/vtc-recruitment.mdx b/src/content/docs/ru/guides/vtc-recruitment.mdx index 369b289..f8302f1 100644 --- a/src/content/docs/ru/guides/vtc-recruitment.mdx +++ b/src/content/docs/ru/guides/vtc-recruitment.mdx @@ -2,7 +2,7 @@ title: Рекрутинг в VTC description: Настройте анкеты для кандидатов, вопросы формы подачи заявок и управляйте тем, как пользователи вступают в вашу VTC на TrucklineMP. version: 1.2.0 -lastUpdated: 2026-07-08 +lastUpdated: 2026-07-14 --- # Рекрутинг в VTC @@ -146,7 +146,7 @@ lastUpdated: 2026-07-08 ### Просмотр заявок - Поступившие заявки отображаются в панели управления вашей VTC - Изучайте информацию о кандидате и его ответы -- Фильтруйте список по статусам (pending — ожидает, approved — одобрено, rejected — отклонено) +- Для каждой заявки отображается её статус (на рассмотрении, одобрена, отклонена или в ожидании ответа от заявителя) ### Рассмотрение заявок - Внимательно читайте все ответы @@ -156,8 +156,8 @@ lastUpdated: 2026-07-08 ### Одобрение заявок - Нажмите кнопку **Accept** на карточке заявки - Кандидат получит соответствующее уведомление -- Он будет автоматически зачислен в состав участников вашей VTC -- Вы сразу же сможете назначить ему роли +- Они добавляются в вашу VTC в качестве участников с ролью по умолчанию +- Позже вы можете изменить их роль в разделе "Управление участниками" ### Отклонение заявок - Нажмите кнопку **Reject** на карточке заявки diff --git a/src/content/docs/ru/guides/vtc-roles-permissions.mdx b/src/content/docs/ru/guides/vtc-roles-permissions.mdx index 848b92f..43c8c07 100644 --- a/src/content/docs/ru/guides/vtc-roles-permissions.mdx +++ b/src/content/docs/ru/guides/vtc-roles-permissions.mdx @@ -2,7 +2,7 @@ title: Роли и разрешения VTC description: Узнайте, как создавать, настраивать и управлять ролями и разрешениями вашей VTC на платформе TrucklineMP. version: 1.2.0 -lastUpdated: 2026-07-08 +lastUpdated: 2026-07-14 --- # Роли и разрешения VTC @@ -57,14 +57,15 @@ lastUpdated: 2026-07-08 **Управленческие разрешения:** - `management.vtc.edit` — Редактирование настроек VTC -- `management.vtc.members` — Управление участниками -- `management.vtc.roles` — Управление ролями -- `management.vtc.recruitment` — Управление рекрутингом -- `management.vtc.news` — Публикация новостей -- `management.vtc.events` — Создание мероприятий +- `management.vtc.visibility` — Изменение видимости VTC и управление приглашениями +- `management.vtc.appearance` — Настройка цветов темы и макета VTC +- `management.members.manage` — Изменение ролей участников +- `management.members.kick` — Удаление участников из VTC +- `management.members.view_activity` — Просмотр журналов активности участников +- `management.roles.manage` — Создание, редактирование и удаление ролей **Другие разрешения:** -- Дополнительные разрешения могут быть доступны в зависимости от конфигурации вашей VTC +- Дополнительные категории охватывают новости, набор участников, мероприятия, приглашения, уведомления, черный список, галерею, партнерства и поддержку — доступность зависит от настроек вашей VTC Используйте кнопку **Select All** для выдачи всех разрешений в категории или **Deselect All** для их отмены. diff --git a/src/content/docs/ru/guides/vtc-visibility.mdx b/src/content/docs/ru/guides/vtc-visibility.mdx index 9472a51..ac59960 100644 --- a/src/content/docs/ru/guides/vtc-visibility.mdx +++ b/src/content/docs/ru/guides/vtc-visibility.mdx @@ -2,7 +2,7 @@ title: Видимость VTC description: Управление тем, кто может находить и просматривать вашу VTC на платформе TrucklineMP — объяснение публичного, доступного по ссылке и приватного режимов видимости. version: 1.2.0 -lastUpdated: 2026-07-08 +lastUpdated: 2026-07-14 --- # Видимость VTC @@ -87,7 +87,7 @@ TrucklineMP позволяет вам контролировать, кто им 4. Настройте параметры приглашения: - **Макс. использований** — Сколько раз можно использовать ссылку (оставьте пустым для неограниченного числа) - **Истекает через (часы)** — Срок действия ссылки в часах (оставьте пустым, чтобы сделать бессрочной) - - **ID целевого пользователя (необязательно)** — Ограничить действие приглашения конкретным пользователем + - **Целевые пользователи (необязательно)** — Ограничить действие приглашения конкретным пользователем 5. Нажмите **Create Invite** 6. Скопируйте ссылку-приглашение и поделитесь ей @@ -115,8 +115,8 @@ https://trucklinemp.com/vtc/invite/ВАШ_КОД ### Целевые приглашения -Целевые приглашения предназначаются строго конкретному пользователю TrucklineMP: -- Принять такое приглашение может исключительно этот пользователь +Целевые приглашения направляются только одному или нескольким конкретным пользователям TrucklineMP: +- Принять приглашение может только тот пользователь, которому оно адресовано - Он должен быть авторизован в системе именно под этой учётной записью - Удобно для точечного найма конкретных водителей diff --git a/src/content/docs/ru/index.mdx b/src/content/docs/ru/index.mdx index 7d77f56..b34e03c 100644 --- a/src/content/docs/ru/index.mdx +++ b/src/content/docs/ru/index.mdx @@ -170,6 +170,10 @@ import QuickLinks from '../../../components/QuickLinks.astro'; Аутентификация, базовые URL-адреса, лимиты запросов и обзор эндпоинтов для REST-доступа только для чтения. [Читать руководство →](/ru/guides/developers/public-api/) + + Официальный клиент `@trucklinemp/sdk` для Node: установка, ресурсы, ошибки и проверка вебхуков. + [Читать руководство →](/ru/guides/developers/sdk/) + Авторизация пользователей через TrucklineMP, настройка PKCE, тестовые пользователи и публикация вашего приложения. [Читать руководство →](/ru/guides/developers/oauth-apps/) From 272658934a97872e89d7026df03c595bc0a6f40b Mon Sep 17 00:00:00 2001 From: GitPolyakoff Date: Tue, 14 Jul 2026 19:25:21 +0300 Subject: [PATCH 2/3] fix(ru): correct import path for translation status table --- src/content/docs/guides/translation-status.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/guides/translation-status.mdx b/src/content/docs/guides/translation-status.mdx index 48b47d5..5c929e9 100644 --- a/src/content/docs/guides/translation-status.mdx +++ b/src/content/docs/guides/translation-status.mdx @@ -5,7 +5,7 @@ version: 1.2.0 lastUpdated: 2026-07-09 --- -import TranslationStatusTable from '../../../components/TranslationStatusTable.astro'; +import TranslationStatusTable from '../../../../components/TranslationStatusTable.astro'; # Translation Status From d3b8e1bc9958beb6ad896fe0dee8431af687209c Mon Sep 17 00:00:00 2001 From: GitPolyakoff Date: Tue, 14 Jul 2026 19:35:25 +0300 Subject: [PATCH 3/3] fix(ru): correct import paths in both locales --- src/content/docs/guides/translation-status.mdx | 2 +- src/content/docs/ru/guides/translation-status.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/guides/translation-status.mdx b/src/content/docs/guides/translation-status.mdx index 5c929e9..48b47d5 100644 --- a/src/content/docs/guides/translation-status.mdx +++ b/src/content/docs/guides/translation-status.mdx @@ -5,7 +5,7 @@ version: 1.2.0 lastUpdated: 2026-07-09 --- -import TranslationStatusTable from '../../../../components/TranslationStatusTable.astro'; +import TranslationStatusTable from '../../../components/TranslationStatusTable.astro'; # Translation Status diff --git a/src/content/docs/ru/guides/translation-status.mdx b/src/content/docs/ru/guides/translation-status.mdx index eed8b94..4c20ea7 100644 --- a/src/content/docs/ru/guides/translation-status.mdx +++ b/src/content/docs/ru/guides/translation-status.mdx @@ -5,7 +5,7 @@ version: 1.2.0 lastUpdated: 2026-07-14 --- -import TranslationStatusTable from '../../../components/TranslationStatusTable.astro'; +import TranslationStatusTable from '../../../../components/TranslationStatusTable.astro'; # Статус перевода