Пачка API

Unified Developer Experience Platform для Pachca API — API корпоративного мессенджера Пачка. Один источник (TypeSpec + workflows.ts) генерирует артефакты для всех каналов: web docs, CLI, SDK, agent skills, LLM context.

Документация: https://dev.pachca.com · OpenAPI: https://dev.pachca.com/openapi.yaml · Авторизация: https://dev.pachca.com/guides/authorization · Changelog: https://dev.pachca.com/guides/updates · Postman/Bruno: https://dev.pachca.com/pachca.postman_collection.json

CLI

# Zero-install (npx)
npx @pachca/cli messages create --entity-id=123 --content="Привет!" --token $PACHCA_TOKEN

# For regular use
npm install -g @pachca/cli
pachca auth login
pachca messages create --entity-id=123 --content="Привет!"
pachca guide "отправить сообщение"  # CLI guide

Все методы API доступны как команды. Типизированные флаги, валидация, 4 формата вывода (table, JSON, YAML, CSV), курсорная пагинация, несколько профилей авторизации, неинтерактивный режим для CI и AI-агентов.

Документация: https://dev.pachca.com/guides/cli

Agent Skills

AI-агенты используют CLI-first скиллы с пошаговыми сценариями, zero-friction авторизацией и автоматической проверкой прав.

Установка (40+ агентов)

npx skills add pachca/openapi

Совместимость

Агент	Путь
Claude Code	`CLAUDE.md` → `AGENTS.md`
Codex CLI	`AGENTS.md`
OpenCode	`skills/`
Cursor, Windsurf, Continue, 40+ других	Автоопределение
Ручная установка	`cp -r skills/pachca-* <path>`

Доступные скиллы

Скилл	Описание
`pachca-profile`	Профиль, статус, кастомные поля
`pachca-users`	Сотрудники и теги (группы)
`pachca-chats`	Каналы, беседы, участники, экспорт
`pachca-messages`	Сообщения, файлы, реакции, кнопки
`pachca-threads`	Треды (комментарии к сообщениям)
`pachca-read-members`	Прочтение сообщений
`pachca-bots`	Боты, вебхуки, unfurling
`pachca-forms`	Интерактивные формы
`pachca-tasks`	Напоминания (задачи)
`pachca-search`	Полнотекстовый поиск
`pachca-security`	Аудит событий, DLP
`pachca`	Router skill — маршрутизация к нужному скиллу

Как скиллы помогают агенту

Без скилла — агент не знает порядок вызовов:

> Отправь файл report.pdf в тред сообщения 123
Агент: POST /messages с file=@report.pdf  ← неверно, файлы не передаются inline

Со скиллом — агент выполняет CLI-команды по сценарию:

> Отправь файл report.pdf в тред сообщения 123
1. pachca uploads create --file-name=report.pdf --file-size=...
2. curl <direct_url> -F ... (загрузка на S3)
3. pachca threads create --message-id=123
4. pachca messages create --entity-type=thread --entity-id=<thread_id> --files='[{"key":"..."}]'

Скиллы генерируются автоматически из OpenAPI-спеки при bun turbo build. Устанавливайте только из официального репозитория — скиллы содержат исключительно инструкции (нет исполняемого кода).

SDK

Язык	Пакет	Реестр
TypeScript	`@pachca/sdk`	npm
Python	`pachca`	PyPI
Go	`github.com/pachca/go-sdk`	Go modules
Kotlin	`com.pachca:sdk`	JitPack
Swift	`PachcaSDK`	SPM

Пример (TypeScript):

import { createClient } from '@pachca/sdk';

const client = createClient({
  baseUrl: 'https://api.pachca.com/api/v1',
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
});

const { data, error } = await client.GET('/users');

SDK генерируются из openapi.yaml и публикуются автоматически при пуше в main: генерация → коммит chore: regenerate SDK v{VERSION} → теги → npm, PyPI, JitPack. Swift и Go — через Git-теги.

Тестирование

Инструмент	Как использовать
Scalar	Онлайн-клиент прямо в браузере — без установки
Postman Collection	Скачайте и импортируйте в Postman
Bruno	Скачайте тот же файл и импортируйте: File → Import → Postman Collection

AI-интеграции

Файл	Содержимое
`/llms.txt`	Краткий индекс: все endpoint'ы со ссылками
`/llms-full.txt`	Полная документация: гайды + endpoint'ы с параметрами
`/skill.md`	AI-agent skill: workflows, capabilities, ссылки
`/scenarios.json`	Машиночитаемые сценарии для no-code платформ (n8n, Albato)
`/{section}/{action}.md`	Отдельный .md для каждого endpoint'а и гайда

Context7 — AI-native document discovery.

Все файлы доступны с Access-Control-Allow-Origin: * и кешируются через CDN.

Разработка

bun install

bun turbo dev            # Разработка с hot reload (localhost:3000)
bun turbo build          # Production сборка
bun turbo check          # Все проверки (lint + typecheck + knip + format)
bun turbo generate       # TypeSpec → openapi.yaml + SDK

CI/CD

Workflow	Триггер	Что делает
`check.yml`	PR в `main`	`bun turbo check`
`sdk.yml`	Push в `main`	Генерация SDK → коммит → теги → публикация
`deploy.yml`	Push в `main`	Docker build → GitLab registry → SSH deploy
`gitlab.yml`	Push в `main`	Зеркало в GitLab

Контакты

Для мейнтейнеров: архитектура и внутреннее устройство

Структура монорепозитория

├── apps/
│   └── docs/              # Next.js 16 сайт документации (@pachca/docs)
├── packages/
│   ├── spec/              # TypeSpec спецификация + workflows.ts (@pachca/spec)
│   └── cli/               # CLI для работы с API (@pachca/cli)
├── sdk/                   # SDK для 5 языков
│   ├── typescript/        # openapi-typescript → npm
│   ├── python/            # openapi-python-client → PyPI
│   ├── go/                # oapi-codegen → Go modules
│   ├── kotlin/            # openapi-generator → JitPack
│   └── swift/             # swift-openapi-generator → SPM
├── skills/                # Agent Skills (генерируются → apps/docs/public/.well-known/skills/)
├── .github/workflows/     # CI/CD (check, sdk, deploy, gitlab)
├── Package.swift          # Корневой Swift Package (копируется из sdk/swift при CI)
├── jitpack.yml            # JitPack конфиг для Kotlin (JDK 17)
├── Dockerfile             # Multi-stage Docker-сборка docs
├── context7.json          # Context7 AI document discovery
├── turbo.json             # Turborepo пайплайн
└── package.json           # Корневой (workspaces: apps/*, packages/*, sdk/*)

Пайплайн данных

typespec.tsp (packages/spec)
    │
    │ tsp compile
    ▼
openapi.yaml ──────────────────────────┐
    │                                  │
    ▼                                  ▼
apps/docs                           sdk/* (5 языков)
    │                                  │
    │ generate-llms                    │ CI: generate + publish
    │ next build                       ▼
    ▼                                npm, PyPI, JitPack, SPM, Go modules
  Сайт + llms.txt + llms-full.txt
  + skill.md + per-endpoint .md
  + Agent Skills (skills/, AGENTS.md, .well-known/)
  + scenarios.json (n8n, no-code)
  + CLI examples (10-й код-генератор)
  + pachca.postman_collection.json
  + OG-изображения + sitemap + RSS

workflows.ts (packages/spec — единый источник сценариев)
    │
    ├──→ Web (страница сценариев с поиском)
    ├──→ CLI (pachca guide)
    ├──→ Skills (CLI-сценарии в SKILL.md)
    └──→ scenarios.json (no-code: n8n, Albato)

Turborepo пайплайн

Задача	Зависит от	Кешируется
`generate`	`setup`	да (inputs: tsp + yaml config → outputs: openapi.yaml, generated/)
`generate-llms`	`@pachca/spec#generate`	да (→ llms.txt, llms-full.txt, skill.md, *.md, Agent Skills)
`build`	`@pachca/spec#generate`, `generate-llms`	да (→ .next/)
`dev`	`@pachca/spec#generate`, `generate-llms`	нет (persistent)
`check`	`lint`, `typecheck`, `knip`, `format:check`	нет

Архитектура docs (apps/docs)

Next.js 16 (App Router, Turbopack) + MDX + FlexSearch (+ русские синонимы/стемминг) + Shiki + Mermaid + GSAP.

Всё динамическое — навигация, маршруты, поиск, примеры кода генерируются из OpenAPI.

Что генерируется автоматически

Действие	Результат
Добавляете endpoint в TypeSpec	Страница + навигация + поиск + llms.txt + .md-файл
Удаляете endpoint	Всё исчезает
Добавляете тег	Новая секция в навигации
Меняете порядок тегов	Меняется порядок секций
Меняете `servers[0].url`	Обновляются все примеры кода
Добавляете гайд (.mdx)	Навигация + поиск + llms.txt + RSS
Добавляете обновление	Badge «Новое» (< 7 дней) + RSS feed

Маршрутизация

URL	Источник
`/`	`content/home.mdx`
`/guides/{slug}`	`content/guides/{slug}.mdx`
`/{section}/{action}`	OpenAPI endpoint (динамически из тегов и путей)
`/{section}/{action}.md`	Статический markdown для endpoint'а
`/guides/{slug}.md`	Статический markdown для гайда
`/.md`	Rewrite → `/index.md`
`/api/og`	Генерация OG-изображений
`/api/search`	API поиска
`/feed.xml`	RSS-лента обновлений
`/sitemap.xml`	Карта сайта
`/openapi.yaml`	OpenAPI спецификация
`/pachca.postman_collection.json`	Postman/Bruno коллекция

URL маппинг

Паттерн	URL	Пример
`GET /items`	`/{section}/list`	`/messages/list`
`POST /items`	`/{section}/create`	`/messages/create`
`GET /items/{id}`	`/{section}/get`	`/users/get`
`PUT /items/{id}`	`/{section}/update`	`/chats/update`
`DELETE /items/{id}`	`/{section}/delete`	`/chats/delete`
Sub-resources	`/{section}/list-{sub}`	`/messages/list-reactions`
Специальные	По действию	`/messages/pin`, `/messages/unpin`

Секция определяется из OpenAPI-тега через tagToUrlSegment(). Скрипт check-url-conflicts.mjs проверяет конфликты.

Поиск

FlexSearch с tokenize: 'forward'. Русский язык: синонимы (участники → members, users), стемминг (участников → участник), стоп-слова, action patterns (отправить → create/post).

Ссылки на API методы в тексте

[Список сотрудников](GET /users)
[Новое сообщение](POST /messages)

Ссылки резолвятся в реальные URL и рендерятся с method-badge.

Требования к методам (x-requirements)

Ограничения эндпоинтов описываются через @extension("x-requirements", ...) в TypeSpec. Попадают в OpenAPI YAML как x-requirements и рендерятся в трёх местах: в UI как бейджи, в Agent Skills рядом с каждой операцией, в per-endpoint .md-файлах.

Поля:

scope — требуемый скоуп токена (например "messages:read")
plan — требуемый тариф (например "corporation")
auth — false если авторизация не нужна

MDX компоненты

Регистрируются в components/mdx/mdx-components.tsx и components/api/markdown-content.tsx.

<SchemaBlock name="MessageWebhookPayload" />
<ApiCodeExample operationId="SecurityOperations_getAuditEvents" />
<Info>Информация</Info>
<Warning>Предупреждение</Warning>
<Danger>Опасно</Danger>
<Steps><Step title="Шаг 1">Описание</Step></Steps>
<Limit title="Название" limit="~4" period="1 сек" entity="chat_id" />
<Updates />
<GuideCards />
<ApiCards />
<Mermaid chart={`graph TD; A-->B;`} />

Как добавить новый гайд

Создайте content/guides/{slug}.mdx с frontmatter:

---
title: Название гайда
description: Краткое описание для SEO
---

Добавьте путь в lib/guides-config.ts → гайд появится в навигации, поиске, llms.txt, RSS и получит .md-файл.

Обновление API (changelog)

В content/guides/updates.mdx:

<!-- update:2025-12-01 -->
## Название обновления

- [Новый метод](POST /messages)

Badge «Новое» показывается < 7 дней. Попадает в RSS feed.

Кастомная схема для гайда

Создайте lib/schemas/guides/{Name}.json → используйте <SchemaBlock name="Name" />. Индексируется для поиска и попадает в llms-full.txt.

Настройки

lib/display-config.ts — showSchemaExamples (по умолчанию false)
redirects.ts — permanent (308) редиректы

Безопасность (next.config.ts)

HSTS (2 года, preload), X-Frame-Options: DENY, nosniff, Permissions-Policy. CORS разрешён для llms.txt, llms-full.txt, skill.md, *.md, /.well-known/skills/*, openapi.yaml, pachca.postman_collection.json, scenarios.json.

Name		Name	Last commit message	Last commit date
Latest commit History 230 Commits
.github		.github
apps/docs		apps/docs
packages		packages
sdk		sdk
skills		skills
.dockerignore		.dockerignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
bun.lock		bun.lock
context7.json		context7.json
jitpack.yml		jitpack.yml
package.json		package.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

Пачка API

CLI

Agent Skills

Установка (40+ агентов)

Совместимость

Доступные скиллы

Как скиллы помогают агенту

SDK

Тестирование

AI-интеграции

Разработка

CI/CD

Контакты

Структура монорепозитория

Пайплайн данных

Turborepo пайплайн

Архитектура docs (apps/docs)

Что генерируется автоматически

Маршрутизация

URL маппинг

Поиск

Ссылки на API методы в тексте

Требования к методам (x-requirements)

MDX компоненты

Как добавить новый гайд

Обновление API (changelog)

Кастомная схема для гайда

Настройки

Безопасность (next.config.ts)

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages