Публичный API мессенджера Пачка существует с 2020 года, но до недавнего времени его документация жила в виде рукописных HTML-таблиц на самописном сайте. Машиночитаемого контракта — OpenAPI или аналога — не было, а значит, из этого источника нельзя было сгенерировать ни SDK, ни интеграции. Когда команда решила сделать ноду для n8n, она пошла привычным путём: написала всё руками.
n8n — open-source платформа визуальной автоматизации: пользователь соединяет блоки-ноды мышкой, не написав ни строчки кода. Платформа популярна среди команд, которые разворачивают её на собственных серверах. Для продукта с открытым API это прямой канал к пользователям: нода позволяет строить ботов, согласования и выгрузки данных без программирования. Готовый сценарий в n8n — это JSON, который можно передать коллеге или сгенерировать с помощью ИИ.
| Расширение | Охват | Что даёт в ноде |
|---|---|---|
| x-requirements | 68 операций | Предупреждение о нужном OAuth-скоупе и тарифном плане |
| x-scope-roles | Все операции | Подсказка о ролях (owner / admin / user / bot) |
| x-paginated | 15 эндпоинтов | Переключатель Return All / Limit с автодокачкой страниц |
| x-enum-descriptions | 25 enum'ов | Выпадающие списки с понятными подписями вместо строковых полей |
Осенью 2025 года команда выпустила рукописную ноду: около 5300 строк TypeScript, 33 коммита в отдельном репозитории, 12 ресурсов с частичным CRUD. В ноябре 2025-го её отправили на верификацию в n8n — процедуру, после которой нода появляется не только в self-hosted-установках, но и в облачном каталоге. Каждый раунд ревью занимает 3–4 недели: сначала автоматическая проверка, затем ручное ревью командой n8n. Нода возвращалась пять раз — каждый раз по мелким замечаниям. Пока шли итерации, API развивался: новые эндпоинты нужно было дописывать в ноду руками, замечания ревьюеров — исправлять и пересобирать всё заново. Первая версия верификацию так и не прошла.
Вывод оказался радикальным: проблема не в конкретных замечаниях, а в самом процессе. Рукописная нода неизбежно отстаёт от живого API. Команда остановила правки и занялась источником.
В качестве единого источника правды выбрали TypeSpec — типизированный язык описания API от Microsoft, который компилируется в openapi.yaml. Поверх стандартного OpenAPI команда добавила собственные расширения (x-*), кодирующие доменное знание об API Пачки: x-requirements описывает нужный OAuth-скоуп и тарифный план для каждой из 68 операций, x-scope-roles задаёт матрицу «скоуп → роли» (owner, admin, user, bot), x-paginated отмечает 15 эндпоинтов с курсорной пагинацией. Отдельно описаны 25 enum'ов с человекочитаемыми подписями через x-enum-descriptions.
Каждое расширение пишется один раз в.tsp-файле и читается всеми генераторами. В ноде x-requirements превращается в предупреждение «requires Corporation plan», x-paginated — в переключатель Return All / Limit с автодокачкой страниц, enum'ы — в выпадающие списки вместо строковых полей. В документации те же данные становятся бейджами требований и интерактивным справочником. В CLI x-paginated даёт флаг --all, в SDK — пагинаторы.
Пайплайн сборки выглядит так: tsp compile превращает TypeSpec в openapi.yaml, из которого параллельно собираются документация, CLI, нода и SDK на шести языках — TypeScript, Python, Java (JitPack), Swift (SPM), Go. Зависимости между шагами описаны в turbo.json, поэтому вся цепочка запускается одной командой turbo build. CI публикует результаты в соответствующие реестры: npm, PyPI, Go modules и другие. SDK на шести языках генерируется из той же спецификации, но в отдельной CI-джобе — каждому языку нужен свой тулчейн.
Агентские инструменты — Claude Code, Cursor, Codex — использовались не для генерации артефактов (это детерминированный процесс), а для написания самих генераторов, тестов и миграций. По словам автора, spec-driven проект с десятком артефактов раньше потребовал бы отдельной команды; сейчас основной объём ведёт один инженер, а генерацию и публикацию SDK на шесть языков добавил второй.
После перехода на новый процесс нода прошла верификацию n8n и получила статус verified by n8n в официальном каталоге. Параллельно обновился и сам портал для разработчиков Пачки: из справочника по методам он вырос в полноценный ресурс с гайдами, примерами на разных языках, CLI, SDK и готовыми сценариями для n8n.
