pagecraft-s3

PageCraft S3 Storage

Этот skill учит агента работать с S3-хранилищем сайта в PageCraft через V1 REST API: проверять подключение и заливать файлы.

Когда применять

• В брифе пользователя есть локальные пути к ассетам (картинки, видео, PDF), которые надо разместить в блоках.
• Нужно положить файл в S3 и получить публичный URL для подстановки в placeholder_values блока.
• Перед стартом работы с лендингом — узнать, подключён ли S3 у сайта.

Жёсткие правила

1. Перед первой заливкой ВСЕГДА вызывай node scripts/s3-status.mjs <site_id>.

   • Если configured: false — S3 не подключён. Сообщи пользователю: «В UI PageCraft → Настройки сайта → S3 нужно подключить хранилище. Я не могу залить файлы без этого». Останови работу с S3.
   • Если configured: true, writable: false — выведи error пользователю и не пытайся грузить (заливка точно упадёт). Возможные причины: невалидные credentials, нет write-permission, недоступный endpoint.
   • Если configured: true, writable: true — можно грузить.

2. Лимит размера — 100 MB. Большие файлы nginx отрежет с кодом 413. Если у тебя файл крупнее — попроси пользователя сжать или захостить отдельно.

3. Не пытайся угадать MIME-тип или валидировать «опасные» типы. Сервер определит MIME через finfo (читает magic bytes), любые расширения принимаются. Это политика владельца bucket'а, а не наша.

4. URL из ответа сохраняй. Полученный url подставляй в поля типа image/url в placeholder_values блока (см. skill pagecraft-pages, Шаг 4). Не хардкодь локальные пути.

Окружение

• 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/s3-status.mjs <site_id>	GET /sites/{id}/s3/status	Шаг 1 — обязательно перед заливкой
node scripts/s3-upload.mjs <site_id> <file>	POST /sites/{id}/s3/upload	Шаг 2 — для каждого файла

Workflow

Шаг 1. Проверить подключение S3

node scripts/s3-status.mjs 1

Ответ:

{ "configured": true, "writable": true, "error": null }

Возможные кейсы:

• { "configured": false, ... } — S3 не настроен. Stop. Сообщи пользователю.
• { "configured": true, "writable": false, "error": "Access Denied" } — проблема с правами или credentials. Stop. Покажи error.
• { "configured": true, "writable": true, ... } — go.

Шаг 2. Залить файл

node scripts/s3-upload.mjs 1 /path/to/image.jpg

Ответ:

{ "url": "https://bucket.s3.amazonaws.com/uploads/20260605_a1b2c3d4e5f6g7h8.jpg" }

Сохрани url.

Шаг 3. Использовать в блоках

В pagecraft-pages (см. соседний skill) этот URL идёт в placeholder_values блока:

{
  "block_id": 5,
  "placeholder_values": {
    "image_url": "https://bucket.s3.amazonaws.com/uploads/20260605_a1b2c3d4e5f6g7h8.jpg"
  }
}

Композиция с pagecraft-pages

Типичный полный сценарий:

1. pagecraft-s3 (этот skill) — для каждого локального файла из брифа: s3-status → s3-upload.
2. pagecraft-pages — собрать страницу из блоков, подставляя полученные URLs в placeholder_values.

Не пытайся залить файлы через pagecraft-pages — там нет такой команды. Не пытайся хардкодить локальные пути в placeholder_values — на проде их не будет.