Типы полей

Как работает приведение#

POST /v1/integrations/{slug}/fields принимает JSON-объект {"ключ": значение}. Каждое значение приводится к типу поля, которое объявили в редакторе. Если хоть одно не проходит проверку — отклоняется весь запрос (422 invalid_fields), с текстом ошибки для каждого поля.

sparku push умеет два синтаксиса присваивания:

• поле=значение — отправляет строку, сервер сам приводит её к типу поля;
• поле:=json — отправляет значение как есть, распарсив как JSON (items:='[{"title":"a"}]', done:=true, state:=null).

null (через поле:=null) очищает поле, не удаляя его из схемы.

Таблица типов#

Тип	Значение в push	Приведение из строки CLI	Примечание
text	"prod"	берётся как есть	обрезается по лимиту длины (по умолчанию 120 символов), не отклоняется
number	72	Double(строка)	единица, min/max для шкал и кольца; копит историю для графика
progress	0.7	число 0…1, либо "70%"	строго 0…1 после приведения
bool	true	true/false/yes/no/on/off/1/0 (без учёта регистра)	для тумблеров и эквалайзера
state	"failed"	строка, должна входить в список состояний поля	у каждого состояния — иконка, цвет, анимация, вспышка при переходе
time	ISO 8601 или +5m	+5m, -1h30m, ISO 8601	таймеры тикают внутри SparkU — слать push каждую секунду не нужно
image	путь или base64 (≤ 256 КБ)	путь /… или ~/…, либо base64 (можно с data:...,)	только PNG/JPEG
url	"https://…"	строка со схемой	для действий кнопок; javascript: и data: отклоняются
list	[{"title": "…"}]	только поле:=json	до 50 строк

Примеры push для каждого типа#

sparku push deploy title="Деплой прода"
sparku push server cpu=37.5
sparku push build progress=70%          # эквивалент progress=0.7
sparku push server ready=true
sparku push build stage=failed          # значение должно быть объявлено в поле
sparku push timer ends=+5m              # через 5 минут от текущего момента
sparku push timer ends=2026-10-01T12:00:00Z   # ISO 8601
sparku push now cover=~/cover.png
sparku push deploy link=https://ci.example.com/builds/482
sparku push queue items:='[{"title": "Сборка"}, {"title": "Тесты", "state": "running"}]'

Формат time#

Принимается одно из:

• Относительное смещение от текущего момента: +5m, -1h30m, +90s, +2d. Единицы — d, h, m, s, можно комбинировать, но только в порядке убывания (1h30m, не 30m1h). Одно поле time работает и таймером (+5m — обратный отсчёт), и секундомером (-10m — время, прошедшее с момента).
• ISO 8601 с временем и часовым поясом (2026-10-01T12:00:00Z, с долями секунды тоже подходит).
• UNIX-время — только числом в поле:=1699999999, не строкой в поле=….

list — объекты строк#

Каждый элемент — объект {"title", "subtitle"?, "value"?, "state"?, "icon"?} или просто строка (тогда она становится title). Обязателен только title. Не больше 50 элементов на запись.

sparku push queue items:='[
  "Простая строка",
  {"title": "Сборка", "subtitle": "main", "state": "running"},
  {"title": "Тесты", "value": "42/50", "icon": "checkmark"}
]'

image#

• Абсолютный путь (/Users/…) или путь с ~ — файл должен существовать и быть PNG или JPEG.
• Или содержимое в base64 (можно с префиксом data:image/png;base64, — он отбрасывается). Ограничение — 256 КБ после декодирования; больше — отклоняется.

Тексты ошибок 422 (из кода)#

Ответ 422 invalid_fields содержит fields: [{field, message}], а объединённое сообщение — field: message; field2: message2. Примеры реальных текстов:

progress: ожидалось 0…1, пришло 70
progress: ожидалось число 0…1, пришло «много»
cpu: ожидалось число, пришло «abc»
ready: ожидалось true или false, пришло «maybe»
stage: ожидалось одно из: queued, running, passed, failed; пришло «cancelled»
ends: ожидалось время (ISO 8601, +5m, -1h30m или UNIX-время), пришло «завтра»
cover: файла нет: /Users/me/cover.png
cover: поддерживаются только PNG и JPEG
cover: base64 не разобран или картинка больше 256 КБ
link: ожидалась ссылка со схемой (https://…), пришло «example.com»
link: схема «javascript» не поддерживается
items: ожидался массив, пришло объект
items: не больше 50 строк, пришло 63
items[0]: нет title
title: ожидалась строка, пришло массив

Ошибка не объявленного поля:

поле не объявлено в интеграции «deploy»; есть: title, progress, stage
поле не объявлено: у интеграции «deploy» пока нет полей

Оба текста одновременно попадают в ответ API и в журнал интеграции в Настройках.