pagecraft-collections

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

PageCraft Collections

Управление коллекциями блоков через V1 REST API: коллекция — это именованный набор блоков (как папка «избранного»). Скрипты дёргают /api/v1/collections/*.

Что это и зачем

Коллекция группирует ссылки на блоки для удобного переиспользования. Два вида:

• private — личная коллекция владельца ключа (видна только ему).
• global — общий набор, видный всем. Создавать глобальные может только администратор (иначе 403).

Важно — что коллекция НЕ делает: она никак не связана со страницами, сайтами и макетами. Это просто сгруппированные ссылки на блоки. Удаление коллекции не трогает сами блоки — убираются только связи. Добавление/удаление блока из коллекции тоже не меняет блок.

Это не каталог: подача блока на модерацию в глобальный каталог — отдельный скилл pagecraft-block-catalog.

Окружение

• PAGECRAFT_API_KEY — обязательная: API-ключ pb_xxxx... (UI PageCraft → API keys).
• PAGECRAFT_API_URL — опциональная: базовый host, по умолчанию https://page-craft.4partners.io (префикс /api/v1 добавляется автоматически). Legacy-имя PAGE_CRAFT_API (host с /api/v1) ещё поддерживается как fallback.

Скрипты

Команда	Endpoint	Назначение
node scripts/collections-list.mjs [--scope p/g/all] [--search S] [--limit N] [--offset N]	GET /collections	Список (без блоков, только blocks_count).
node scripts/collections-get.mjs <id>	GET /collections/{id}	Полная коллекция с массивом блоков.
node scripts/collections-create.mjs <payload.json>	POST /collections	Создать коллекцию.
node scripts/collections-update.mjs <id> <payload.json>	PUT /collections/{id}	Переименовать / сменить описание.
node scripts/collections-delete.mjs <id>	DELETE /collections/{id}	Удалить коллекцию (блоки целы).
node scripts/collections-add-blocks.mjs <id> <block_id...>	POST /collections/{id}/blocks	Добавить блоки.
node scripts/collections-remove-block.mjs <id> <block_id>	DELETE /collections/{id}/blocks/{block_id}	Убрать один блок.
node scripts/collections-reorder.mjs <id> <block_id...>	PUT /collections/{id}/blocks/order	Задать порядок блоков.

Формы payload-ов

collections-create.mjs

{ "name": "Мои любимые блоки", "description": "Блоки для лендингов", "scope": "private" }

Поле	Тип	Обязательное	Заметка
name	string	✓	1–255 символов
description	string/null	—	Описание
scope	private/global	—	По умолчанию private. global — только админ

collections-update.mjs

Оба поля опциональны, поле со значением null (или отсутствующее) не меняется. scope через update не меняется.

{ "name": "Новое название" }

{ "description": "Новое описание" }

Workflow

Создать коллекцию и наполнить её

# 1. Создать
echo '{"name":"Hero-секции","description":"Первые экраны"}' > /tmp/col.json
ID=$(node scripts/collections-create.mjs /tmp/col.json | jq -r '.collection.id')

# 2. Добавить блоки (id блоков — из pagecraft-api get-blocks.js)
node scripts/collections-add-blocks.mjs $ID 12 34 56

# 3. Проверить состав
node scripts/collections-get.mjs $ID

Переупорядочить блоки

# Новый порядок = порядок аргументов
node scripts/collections-reorder.mjs 7 56 12 34

Убрать блок / удалить коллекцию

node scripts/collections-remove-block.mjs 7 12   # блок 12 остаётся в системе, уходит из коллекции
node scripts/collections-delete.mjs 7            # коллекция удалена, блоки целы

Формат ответа

• list → { data: [...], total, limit, offset }. Элементы без blocks (blocks: null), есть blocks_count.
• get / create / update / add / remove / reorder → { "collection": { ..., "blocks": [...] } } (для delete — { "success": true }).
• Поле is_owner показывает, владеет ли текущий ключ коллекцией (для глобальных у не-владельца будет false → редактировать нельзя).

Композиция с другими скиллами

• pagecraft-api (get-blocks.js) — узнать id блоков, которые кладёшь в коллекцию.
• pagecraft-block-catalog — это про модерацию блока в глобальный каталог, не путать с коллекциями.

Коды ошибок

Код	Причина
400	Невалидный payload (например, битый JSON тела)
401	Нет / неверный PAGECRAFT_API_KEY
403	Создание scope=global не администратором; правка чужой/глобальной коллекции
404	Коллекция не найдена / не принадлежит владельцу ключа
422	Пустой name, пустой block_ids, нецелые/отрицательные id блоков