pagecraft-api

⚡ Этот скилл — для вызова через тул Skill(pagecraft-api), не через Read .../SKILL.md. Если ты сюда попал через Read — остановись, вызови Skill(pagecraft-api). Содержимое то же, но система правильно учтёт делегирование.

PageCraft API

Тонкий слой над PageCraft REST API. Содержит общий HTTP-клиент и набор скриптов для типовых операций. Другие скиллы (pagecraft-block, pagecraft-block-ssr, pagecraft-block-publish) вызывают эти скрипты по их полному пути — никаких Node-импортов между папками скиллов.

Требования

В .env корня проекта должны быть PAGECRAFT_API_KEY (для всех скриптов кроме sync-schema-эндпоинта) и опционально PAGECRAFT_API_URL. Дефолтный URL — https://page-craft.4partners.io. Настройка переменных — pagecraft-env.

Установка:

npm install --prefix .claude/skills/pagecraft-api

Скрипты

Скрипт	Что делает
scripts/api.js	HTTP-клиент. Экспортирует apiRequest(method, path, body). Не вызывается напрямую
scripts/get-blocks.js	Список блоков. [--search "query"] [--tags "1,2"]
scripts/get-block.js	Один блок по id. <id> [--save blocks/{slug}]
scripts/get-tags.js	Список тегов, либо подбор тегов по блоку. [--suggest <block-dir>] [--verbose]
scripts/publish-block.js	Создать или обновить блок. <block-dir> [--changelog "..."]
scripts/submit-block.js	Подать блок в глобальный каталог на модерацию. <id>
scripts/list-submissions.js	Список своих заявок в каталог. [--status pending|approved|rejected|withdrawn]
scripts/withdraw-submission.js	Отозвать заявку из каталога. <submission-id>
scripts/sync-meta.js	Стянуть SSR-реестр (data-result-types, data-sources) в blocks/_meta/. Diff с прошлым снапшотом. [--quiet]

Когда дёргать что

• «покажи блоки» / «найди блок про X» → get-blocks.js. Поиск частичный, чувствителен к языку.
• «покажи блок {id}» → get-block.js. Без --save — печать в stdout, с — сохранить в blocks/{slug}/.
• «подскажи теги» для нового блока → get-tags.js --suggest <block-dir>. Внутри использует description+keywords из block.json. Без --suggest — полный список.
• «опубликуй» / «залей» → publish-block.js. Использует get-block.js под капотом для preflight (см. ниже).
• Перед SSR-работой / правкой существующего SSR-блока → sync-meta.js. Это обязательный шаг: pagecraft-block-ssr читает только локальный blocks/_meta/ и не ходит в API сам.

Эндпоинты

Блоки и страницы:

• GET /api/v1/blocks — список (фильтры: search через FTS, tags, scope)
• GET /api/v1/blocks/{id} — один
• POST /api/v1/blocks — создать
• PUT /api/v1/blocks/{id} — обновить
• POST /api/v1/blocks/{id}/adopt — сделать копию чужого блока себе: доступно владельцу сайта для блока соредактора, стоящего на его страницах. Копия уходит в свою библиотеку, все экземпляры на сайтах владельца переезжают на неё, вид опубликованных страниц не меняется
• GET /api/v1/pages — список страниц (новое: фильтры external_id, bindingSource, bindingValue, bindingParamName)

Полнотекстовый поиск (PostgreSQL FTS + pg_trgm, морфология RU, опечатки):

• GET /api/v1/search/pages?q=... — поиск по содержимому страниц (name, meta_*, текстовые поля и markdown блоков). Возвращает { items: [{id, name, slug, external_id, score, snippet}], total }. Snippet содержит HTML <mark>…</mark>. Лаг индексации до 5 секунд.
• GET /api/v1/search/blocks?q=...&tags=...&scope=... — поиск по name/description/tags блоков. tags — csv ID с AND-семантикой; scope — private|global.

Реестры:

• GET /api/v1/tags — теги
• GET /api/v1/data-result-types — реестр типов результатов (для SSR)
• GET /api/v1/data-sources — реестр источников данных (для SSR)

Auth: Authorization: Bearer ${PAGECRAFT_API_KEY}. 401 → ключ невалиден, отправить пользователя в pagecraft-env.

Publish — preflight

publish-block.js перед обновлением (когда у блока уже есть id в block.json) сверяет remote-version с локальной. Если remote ушёл вперёд — публикация прерывается и предлагается:

node .claude/skills/pagecraft-api/scripts/get-block.js {id} --save blocks/{slug}

Это защищает от затирания чужих изменений. Полный воркфлоу публикации (changelog, версии, что обновляется) — в pagecraft-block-publish.

Что не делает этот скилл

• Не валидирует структуру schema.json блока — это pagecraft-schema-block (validate-schema.js).
• Не работает с локальным snapshot _meta/ (читать, искать, сравнивать) — это pagecraft-block-ssr (meta-local.js + утилиты).
• Не собирает data-stubs.json для preview — это pagecraft-block-ssr (build-stubs.js).
• Не отвечает за .env — это pagecraft-env.

Типичные ошибки

• PAGECRAFT_API_KEY not set — нет ключа в .env. Скрипт сам выходит с ошибкой; отправь пользователя в pagecraft-env.
• 401 Unauthorized — ключ неверный или истёк. То же — pagecraft-env.
• Version conflict при publish — remote ушёл вперёд. Пользователю показать команду get-block.js {id} --save ....
• sync-meta не запущен перед SSR-работой — pagecraft-block-ssr-скрипты упадут с ошибкой «нет локального snapshot». Прогнать sync-meta.js.