Публикация и релизы

Репозиторий и ID аддона

Размещайте аддон в публичном GitHub-репозитории. Поле id в манифесте должно совпадать с путём репозитория на GitHub:

GitHub-репозиторий	`id` в manifest
`https://github.com/MyOrg/my-stream-addon`	`"MyOrg/my-stream-addon"`
`https://github.com/jane/widget-panel`	`"jane/widget-panel"`

Формат: ORG/REPO — организация или пользователь GitHub, слэш, имя репозитория.

id не меняется между релизами. Он используется в:

HTTP-маршрутах (/addon/{id}/…, /addon_static/{id}/…)
ссылках depends_on между аддонами
проверке обновлений (catalog API и GitHub releases)

Не меняйте id после первого публичного релиза, если только не публикуете новый аддон.

Структура GitHub-релиза

Каждую версию публикуйте как GitHub Release. К релизу должны быть приложены файлы:

Файл релиза	Обязателен	Описание
`main.zip`	Да	Архив со всеми файлами аддона
`manifest.json`	Да	Отдельная копия манифеста (также внутри `main.zip`)
`logo.png` или `logo.svg`	Да	Иконка из поля `icon` манифеста (также внутри `main.zip`)

Рекомендуемое содержимое main.zip:

main.zip
├── manifest.json
├── index.js              # если есть worker
├── logo.png              # или logo.svg
├── index.html            # если используется web UI
└── ...                   # остальные ресурсы

Бэкенд каталога StreamKit+ и проверка обновлений в приложении читают manifest.json из assets релиза, чтобы определить опубликованную версию. Поле version должно совпадать с тегом релиза (например тег v1.2.0 → "version": "1.2.0"). Файл в assets должен быть идентичен manifest.json внутри main.zip (обязательно для синхронизации с каталогом).

Чеклист перед публикацией

id в manifest.json равен ORG/REPO вашего GitHub-репозитория.
version совпадает с тегом GitHub-релиза.
В релизе есть main.zip, manifest.json и logo.png / logo.svg.
В main.zip есть все файлы, необходимые для работы аддона (включая manifest.json и иконку).
Разрешения в манифесте соответствуют реальному поведению аддона.
После публикации релиза запустите синхронизацию с каталогом (на сайте или через API синхронизации), чтобы пользователи получили новые файлы.

Кэширование файлов в каталоге

Когда аддон добавляют в каталог, сайт скачивает файлы релиза (manifest.json, logo.png / logo.svg, main.zip) и кэширует их постоянно.

Кэшированные файлы раздаются всем пользователям и не подтягиваются заново автоматически.
Они обновляются только при синхронизации версии — вручную на сайте (Обновить версию) или через API синхронизации.

После модерации и одобрения аддона пользователи скачивают ровно те файлы, что были проверены. Изменение файлов в GitHub-релизе без синхронизации не влияет на то, что получают пользователи. Это сделано намеренно и защищает от тихой подмены файлов после модерации.

Чтобы выпустить новую версию, опубликуйте новый GitHub-релиз и запустите синхронизацию.

Проверки при синхронизации с каталогом

При добавлении или синхронизации аддона каталог проверяет:

В релизе есть manifest.json, logo.png (или logo.svg) и main.zip.
Поле id в manifest.json соответствует репозиторию по тем же правилам, что в manifest.json: ORG/REPO для сторонних репозиториев или REPO (только имя репозитория) для аддонов организации RocketMan-StreamKit.
Файл manifest.json в assets релиза идентичен manifest.json внутри main.zip.

При ошибке добавление или синхронизация отклоняются с пояснением.

Автоматическая синхронизация версии в каталоге

Используйте API синхронизации для разработчиков, чтобы обновлять каталог после каждого GitHub-релиза без ручного нажатия Обновить версию на сайте.

Базовый URL в примерах: https://rocketman-streams.com. Используйте домен сайта, на котором опубликован ваш аддон.

Токен разработчика

Откройте страницу Аддоны на сайте.
Нажмите кнопку API key вверху.
Скопируйте токен разработчика из модального окна.

Токен можно перегенерировать в том же окне (с подтверждением). Перегенерация сразу аннулирует старый токен — обновите его везде, где он используется.

Храните токен в секрете. Любой, у кого он есть, может запускать обновление версий ваших аддонов. Сохраняйте его как секрет CI/CD (например GitHub Actions secret ROCKETMAN_ADDON_TOKEN) и не коммитьте в репозиторий.

API синхронизации

POST https://rocketman-streams.com/api/extensions/dev/sync
Content-Type: application/json

Параметр	Обязателен	Описание
`repo`	да	Репозиторий аддона в формате `OWNER/NAME` (как `github.repository` в GitHub Actions). Должен совпадать с аддоном вашей собственности в каталоге.
`token`	да	Токен разработчика из модального окна API key.

Параметры можно передать также как application/x-www-form-urlencoded или query-параметры URL; рекомендуется JSON.

При успехе эндпоинт заново читает последний GitHub-релиз, перекачивает и обновляет кэшированные файлы и сохраняет новую версию и метаданные, если релиз изменился.

Пример:

curl -X POST "https://rocketman-streams.com/api/extensions/dev/sync" \
  -H "Content-Type: application/json" \
  -d '{"repo":"OWNER/REPO","token":"YOUR_TOKEN"}'

Успешный ответ:

{
  "status": true,
  "repo": "OWNER/REPO",
  "updated": true,
  "version": "1.2.3"
}

updated — true, если версия или метаданные изменились относительно сохранённых; false, если релиз перечитан, но ничего не изменилось.
version — версия после синхронизации.

Ошибки (HTTP-статус и поле error):

HTTP	`error`	Значение
400	`token_required`	Параметр `token` не передан.
400	`invalid_repo`	Параметр `repo` не передан или некорректен.
401	`invalid_token`	Токен не принадлежит ни одному разработчику аддонов.
403	`not_owner`	Аддон есть в каталоге, но не принадлежит владельцу токена.
404	`addon_not_found`	В каталоге нет аддона с таким `repo`.
429	`rate_limited_token`	Слишком много запросов для этого токена. См. `retryAfter` (секунды).
429	`rate_limited_repo`	Слишком много запросов для этого репозитория. См. `retryAfter` (секунды).
502	`sync_failed`	Не удалось получить или разобрать GitHub-релиз (см. `message`).
500	`internal_error`	Непредвиденная ошибка сервера.

Лимиты запросов

1 запрос за 30 секунд на токен разработчика.
1 запрос за 60 секунд на репозиторий.

При превышении лимита в ответе есть поле retryAfter (в секундах).

Пример GitHub Actions

Workflow запускается при каждой публикации релиза и уведомляет каталог. Сохраните как .github/workflows/rocketman-sync.yml в репозитории аддона и добавьте secret ROCKETMAN_ADDON_TOKEN с токеном разработчика.

name: Sync addon to RocketMan catalog

on:
  release:
    types: [published]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Notify catalog about the new release
        run: |
          curl -sS -X POST "https://rocketman-streams.com/api/extensions/dev/sync" \
            -H "Content-Type: application/json" \
            -d "{\"repo\":\"${{ github.repository }}\",\"token\":\"${{ secrets.ROCKETMAN_ADDON_TOKEN }}\"}"

Связанные материалы

manifest.json — описание полей
Начало работы — структура проекта при разработке