4cms-catalog

⚡ Этот скилл — для вызова через тул Skill(4cms-catalog), не через Read .../SKILL.md.

4cms Catalog

Обход и перечисление каталога витрины через аутентифицированный API api.4partners.io/v1: дерево рубрик и список брендов. Отдаёт реальные id/slug/link — для привязок блоков и ссылок.

Когда что брать. Нужно зарезолвить одно имя или URL в id — бери 4cms-resolve (публичные ручки, без ключа, мгновенно). Нужно перечислить/обойти (все подрубрики, дерево, список брендов) — это сюда.

Граница доменов. Это 4cms — реальные сущности витрины. Создание/публикация страниц — PageCraft.

Предусловие

FOURCMS_API_KEY с доступом к каталогу (Skill(4cms-env)). Установка зависимостей (один раз): npm install --prefix .claude/skills/4cms-catalog

Рейт-лимит ~600 req/min. HTTP всегда 200 — реальный статус в теле. При 100002 «Доступ запрещён» чаще всего это лимит: разнеси запросы, повтори (api.js делает 1 авто-ретрай). Поэтому обходы — по чанкам, лениво, а не «выкачать весь каталог разом».

Рубрики — rubrics.js

Дерево может быть на десятки тысяч узлов, поэтому целиком не тянем — ходим по уровням.

Команда	Что делает
(без флагов)	Корневые рубрики
--info <id>	Одна рубрика детально
--children <id>	Прямые дети
--subtree <id> [--depth N]	Всё поддерево (одним вызовом; для огромных категорий лучше --children по уровням)
--find "<имя>" [--max-nodes 300]	Поиск по дереву обходом вширь с лимитом узлов; ставит truncated, если не обошёл всё

Бренды — brands.js

Серверного поиска по брендам нет, а дефолтный размер страницы огромный (~10k) — поэтому пагинируем чанками 1000 через курсор next_page_key.

Команда	Что делает
--list [--limit 1000] [--next <key>]	Один чанк брендов + next_page_key для следующего
--find "<имя>" [--max-pages 5]	Поиск по name/slug/синонимам (у брендов богатые синонимы, в т.ч. кириллица) постранично; ставит truncated
--info <id>	Бренд детально (+ synonyms)

Рубрика-бренд — rubric-brands.js

Связка «бренд внутри рубрики» (своя ссылка/SEO) — сущность за страницами вида «Nike в рубрике Кроссовки» и за кейсом «сравни бренды в категории X». Та же пагинация-капкан, что у брендов (дефолт 10k) → чанки 1000 + курсор.

Команда	Что делает
--list <rubricId> [--max-pages 5]	Бренды рубрики (чанками); ставит truncated
--list <rubricId> --find "<имя>"	То же, но отфильтровать по имени/slug бренда
--info <rubricId> <brandId>	Детали связки: link, product_count

Выдача: { rubric_id, brand_id, brand_name, brand_slug, link, product_count }. link — ссылка на страницу бренда-в-рубрике на витрине.

Резолв готового URL связки (/brand-{slug}/r-{slug}) — через 4cms-resolve (url/info вернёт page_type: rubric_brand).

Формат

• Рубрика: { id, parent_id, name, slug, level, is_leaf, link, breadcrumbs_text, partner_tag }.
• Бренд: { id, name, slug, link, is_active, product_count } (+ synonyms у --info/--find).
• --find помечает точное совпадение exact_match и ставит его первым (несколько exact_match: true → неоднозначность, уточни у пользователя).
• id идёт в привязки (rubric_id, brand_id — если источник их принимает), link — в ссылки.

⚠️ truncated: true означает «обошёл не весь каталог» → «не нашёл» ≠ «нет такого». Сузь запрос, подними лимит или используй 4cms-resolve.

Если скрипт не отдаёт ожидаемое — проверь живой API

Открой Swagger UI 4cms: https://api.4partners.io/ → Authorize (заголовок X-Auth-Token = твой ключ) → нужный метод → Try it out. Это запрос к реальному API — сравни его ответ с тем, что вернул скрипт.

• HTTP всегда 200 — смотри тело (status, status_code, message).
• 100002 «Доступ запрещён» чаще всего = рейт-лимит (~600 req/min): подожди ~минуту и повтори, а не считай, что прав нет.
• Док (Notion): https://help.4partners.io/partner-site-api-v1

Что не делает

• Не резолвит одиночное имя/URL в id мгновенно — это 4cms-resolve.
• Не работает с товарами — это 4cms-products.
• Не настраивает .env — это 4cms-env.