Ротация токена бота, настройки вебхука и IA-нейминг методов#265
Merged
Conversation
lookinway
force-pushed
the
api-2026-06-24-token-rotation-ia-renames
branch
from
June 24, 2026 18:23
038c9d4 to
0787a9c
Compare
Новые методы и поля API:
- Ротация токена бота: POST /bots/{id}/recreate_token (bots:write) и
POST /bot/recreate_token (bot_self:write); audit-событие bot_token_recreated
- Поля настроек вебхука бота: ignore_self_messages, events_history_enabled
(в POST/PUT /bots и в ответе)
- Новые коды ошибок: cannot_kick_owner, pin_failed, message_deleted,
thread_message, export_file_not_found
- Новые типы аудит-событий: bot_scopes_updated, bot_webhook_settings_updated,
bot_token_recreated (+ модели деталей)
IA-нейминг методов (лучшая дискаверабилити для агентов), с обратной совместимостью:
- token-info -> раздел OAuth; unfurl -> Messages; экспорт чата -> Chats;
загрузка/доп. поля -> Files/CustomProperties. Чистые URL и slug.
- CLI: новые команды, старые имена работают скрытыми hiddenAliases
- n8n: новые ресурсы (экспорт в Chat, unfurl в Message, OAuth), роутер
принимает старые resource/operation из сохранённых workflow
- SDK (6 языков): новые сервисы документируются, старые (client.common,
client.linkPreviews, client.profile.getTokenInfo) работают как
deprecated alias-сервисы, скрытые из примеров
Сборка/генераторы:
- generate-cli полностью очищает dist/commands перед пересборкой, чтобы
.js от переименованных команд не протекали в oclif.manifest.json
как команды-призраки (детерминированный манифест на любой ОС)
- generate-llms сам удаляет осиротевшие скилл-папки (как sweep для .md)
Версии: CLI 2026.6.3, SDK 1.0.25, n8n 2.0.13, generator 1.1.8.
Тесты обратной совместимости (SDK/CLI/n8n); обновлены гайды, скиллы
(+pachca-oauth/files/customproperties), e2e.
lookinway
force-pushed
the
api-2026-06-24-token-rotation-ia-renames
branch
from
June 24, 2026 18:47
0787a9c to
8b3b18b
Compare
Уникальный случай IA-переноса: сменился и сервис, и сам глагол метода.
Раньше unfurl в SDK звался client.linkPreviews.createLinkPreviews() —
расходился с CLI/n8n/URL, где он уже unfurl. Теперь единообразно:
- operationId переименован createLinkPreviews -> unfurl (в typespec.tsp),
поэтому SDK-метод выводится как client.messages.unfurl()
- deprecated-алиас сохраняет СТАРОЕ имя: client.linkPreviews.createLinkPreviews()
по-прежнему работает (aliasClone получил override старого имени метода)
CLI/n8n/docs-URL не тронуты: они деривят имя из пути (/messages/{id}/link_previews),
а не из operationId, и уже отдают unfurl через свои overrides. SDK — единственный,
кто читает operationId, поэтому правка только в tsp + генераторе SDK.
Тест: канонический Messages.unfurl (primary), Link Previews.createLinkPreviews (alias).
В группе метод-сортировался только по HTTP-методу, а внутри метода порядок
шёл из алфавита пути openapi.yaml. Из-за этого новый эндпоинт самостоятельной
ротации (/bot/recreate_token, ед. число) обгонял создание (/bots, мн. число) —
«Новый бот» оказывался не первым, в отличие от остальных групп.
Добавлен вторичный ключ сортировки по глубине пути: внутри одного метода
корневые операции (POST /bots — create) идут раньше вложенных/self-путей
(POST /bot/recreate_token, POST /bots/{id}/...). Стабильная сортировка
сохраняет порядок спеки внутри одной (метод, глубина).
Общий компаратор compareEndpointsForNav применён в трёх местах единообразно:
сайдбар, групповые редиректы, генерация .md-шпаргалок — чтобы порядок совпадал.
Также долетела пере-генерация updates (формулировка client.messages.unfurl()
из releases.json предыдущего коммита).
…ений) generate-llms генерит public/updates/*.md из releases.json, но releases.json не был объявлен во inputs задачи. turbo отдавал кэш при правке только releases.json → страница обновлений уезжала со стейлом (локально check мог не поймать, т.к. сравнивал кэш со стейлом; ловилось лишь на холодной сборке CI). Добавлен data/releases.json во inputs обоих generate-llms — теперь правка releases.json инвалидирует кэш и страница обновлений перегенерируется.
…чный регистр) Тег CustomProperties не имел пробела, а tagToProperty разбивает имя сервиса по пробелам — поэтому аксессор лоуэркейсился целиком: client.customproperties (неидиоматично в TS и Python). Переименован тег -> "Custom Properties" (как "Link Previews"), и генератор сам выдаёт правильный регистр по конвенции языка: - TS: client.customProperties - Python: client.custom_properties - Go: client.CustomProperties (без изменений) Риска нет: это новый сервис (раньше — client.common.listProperties()), им ещё никто не пользовался; старый код через deprecated client.common цел. Скилл авто-переименовался pachca-customproperties -> pachca-custom-properties (старый подчищен orphan-sweep'ом). URL /api/custom-properties не тронут.
…Files) Рукописный MDX генераторы не трогают — две ссылки уехали: - link-previews.mdx: <ApiCodeExample operationId="...createLinkPreviews"> -> "...unfurl" (operationId переименован, пример не находился = пустой) - sdk/csharp.mdx: пример загрузки файла использовал deprecated client.Common -> client.Files (канонический сервис после IA-переноса) Остальные гайды чисты: file-uploads.mdx уже на client.files, client.profile.getProfile валиден (переезжал только getTokenInfo), все ApiCodeExample operationId валидны.
Новые коды (export_file_not_found, cannot_kick_owner, pin_failed, message_deleted, thread_message) были добавлены в enum ValidationErrorCode с @doc, но НЕ в x-enum-descriptions — а страница берёт описания именно оттуда, поэтому рендерились голыми чипами без пояснений. Добавлены 5 RU-записей (EN в overlay.en.yaml уже были — отсюда асимметрия RU/EN на странице). Системно проверены все 29 enum с x-enum-descriptions: остальные покрыты (аудит-события — ок, OAuthScope 53/53). Пробел был только здесь. docs/api-audit.md: пункт про ValidationErrorCode приведён к стандарту секции AuditEventKey — явно требовать строку в x-enum-descriptions (RU + EN overlay), иначе чип без описания.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Новые методы и поля API
POST /bots/{id}/recreate_token(scopebots:write, админ/владелец/создатель) иPOST /bot/recreate_token(scopebot_self:write, бот сам себе). Прежний токен инвалидируется, новый возвращается один раз. Audit-событиеbot_token_recreated.ignore_self_messages(анти-луп) иevents_history_enabled(история для polling) — вPOST/PUT /botsи в ответе.cannot_kick_owner,pin_failed,message_deleted,thread_message,export_file_not_found.bot_scopes_updated,bot_webhook_settings_updated,bot_token_recreated(+ модели деталей).IA-нейминг методов (дискаверабилити для агентов)
Методы переразложены по смыслу, URL и slug стали чище:
Обратная совместимость — ничего не ломается:
hiddenAliases.Chat, unfurl внутриMessage,OAuth); роутер принимает старые{resource, operation}из сохранённых workflow.client.common,client.linkPreviews,client.profile.getTokenInfo) работают как deprecated alias-сервисы, исключённые из примеров.Пакеты
CLI
2026.6.3, SDK1.0.25, n8n2.0.13, generator1.1.8. Добавлены тесты обратной совместимости (SDK/CLI/n8n); обновлены гайды, скиллы (+pachca-oauth/files/customproperties), редиректы старых URL, e2e.npx turbo build+npx turbo check— зелёные.