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

> Формат .sparku, что в него не входит, POST /v1/imports и sparku import, согласие человека, риски.

## Формат `.sparku`

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

```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` и, конечно, токен — у
импортированной интеграции он всегда новый. Схему создаёт только человек: файл
переносит то, что он уже настроил, а не выдаёт скрипту право создавать интерфейс
самому (см. [Понятия](/docs/api/ru/concepts.md)).

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

## Экспорт

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

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

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

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

## `POST /v1/imports`

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

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

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

```json
{"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`

```bash
sparku import deploy.sparku
```

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

```
export SPARKU_TOKEN_DEPLOY=spk_9f2c...a31b
```

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

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

Отказ человека — код выхода `77` (нет прав, как и при неверном токене); во всех
остальных случаях коды — обычные `sparku`, см. [CLI sparku](/docs/api/ru/cli.md#коды-выхода).

## Риски

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

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

> [!WARNING]
> Не запускайте `sparku import` и не открывайте `.sparku`-файлы из источников,
> которым вы не доверяете, даже если экран импорта не показал ни одного риска:
> ссылки в элементах «Открыть» тоже стоит проверить прежде, чем нажимать кнопку на
> островке.

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

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