Файлы .sparku и импорт

Формат .sparku#

Экспорт интеграции — это её схема без секретов: название, адрес, поля, оформление островка и карточки, элементы управления. Файл — обычный JSON:

{
  "format": "sparku.integration",
  "version": 1,
  "integration": {
    "slug": "deploy",
    "name": "Деплой",
    "icon": "shippingbox.fill",
    "accent": "blue",
    "fields": [
      {"key": "progress", "type": "progress", "label": "Прогресс"},
      {"key": "stage", "type": "state", "label": "Этап", "states": [
        {"id": "running", "label": "Идёт", "icon": "arrow.triangle.2.circlepath", "color": "blue"},
        {"id": "done", "label": "Готово", "icon": "checkmark.circle.fill", "color": "success"},
        {"id": "failed", "label": "Ошибка", "icon": "xmark.octagon.fill", "color": "error"}
      ]},
      {"key": "title", "type": "text", "label": "Сервис", "maxLength": 60}
    ],
    "valueLifetime": null,
    "island": {"...": "настройки индикатора и строки"},
    "card": {"...": "шаблон, слоты, элементы управления"}
  }
}

Не входят в файл: id, createdAt, isEnabled и, конечно, токен — у импортированной интеграции он всегда новый. Схему создаёт только человек: файл переносит то, что он уже настроил, а не выдаёт скрипту право создавать интерфейс самому (см. Понятия).

Лимит размера файла — 512 КБ: интеграция — это десятки полей и шаблонов, не мегабайты. Файл, сохранённый более новой версией SparkU (version больше поддерживаемой), отклоняется с просьбой обновить приложение.

Экспорт#

Кнопка в шапке редактора интеграции (Настройки → Свои интеграции → «slug») сохраняет файл <адрес>.sparku (имя — по названию интеграции, транслитерация в адрес).

Импорт в настройках#

«+» → «Импортировать из файла…» открывает .sparku с диска. SparkU показывает экран согласия: кто предлагает интеграцию, что появится на островке и в карточке, и отдельно — какие элементы управления открывают адреса, выполняют команды или запускают «Команды» (Shortcuts). Занятый адрес (slug) заменяется на свободный — deploy → deploy-2.

Тот же экран открывается двойным кликом по файлу .sparku в Finder — SparkU зарегистрирован как его владелец. Если «Свои интеграции» выключены, SparkU откроет раздел «Интеграции» и попросит сначала включить их.

POST /v1/imports#

Тот же путь, но инициированный скриптом или установщиком: тело запроса — содержимое файла .sparku как есть (не JSON-обёртка, а сам файл). Токен не нужен — интеграции пока нет.

curl --unix-socket ~/.sparku/run/api.sock \
  --data-binary @deploy.sparku \
  http://sparku/v1/imports

Запрос блокируется, пока человек не откроет Настройки и не ответит на предложение — SparkU сам открывает нужный раздел. Согласие:

{"slug": "deploy", "name": "Деплой", "token": "spk_9f2c...a31b"}

Статус 201 Created. Отказ — 403 import_declined. Пока одно предложение уже ждёт ответа (из настроек или от другого запроса), новый POST /v1/imports получает 409 import_pending немедленно, не дожидаясь ничего.

Если SparkU закрывается или API выключают, пока запрос ждёт, — 503 withdrawn. Файл, который не проходит проверку схемы (как в редакторе) — 422 invalid_package.

sparku import#

sparku import deploy.sparku

Ждёт согласия так же, как прямой POST /v1/imports, и печатает в stdout строку экспорта токена:

export SPARKU_TOKEN_DEPLOY=spk_9f2c...a31b

Поэтому установщик скрипта делает:

eval "$(sparku import deploy.sparku)"
sparku push deploy progress=0

Отказ человека — код выхода 77 (нет прав, как и при неверном токене); во всех остальных случаях коды — обычные sparku, см. CLI sparku.

Риски#

Импорт .sparku — это доверие к чужой конфигурации, не к чужому коду: сам файл не исполняется, но элементы управления в нём могут быть настроены на выполнение команд на этом Mac при нажатии в карточке (действие «Выполнить команду» или «Запустить „Команду“»). Экран импорта показывает такие элементы явно — с текстом команды или именем Shortcuts-команды — до того, как человек согласится. Прочитайте их так же внимательно, как командную строку из письма.

Элементы с действием «Событие слушателю» безопасны сами по себе: они лишь сообщают о нажатии тому, кто запустил sparku listen, — исполнить что-либо без отдельного слушателя они не могут.

Коды ответов#

Код	HTTP	Когда
—	201	человек согласился, интеграция добавлена
import_declined	403	человек отклонил предложение
import_pending	409	SparkU уже ждёт ответа на другое предложение
invalid_package	422	файл не по формату .sparku или не проходит проверку схемы
withdrawn	503	SparkU закрылось или API выключили, пока запрос ждал