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

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

Розміщуйте аддон у публічному GitHub-репозиторії. Поле id у маніфесті має збігатися з шляхом репозиторію на GitHub:

Формат: ORG/REPO — організація або користувач GitHub, слеш, назва репозиторію.

id не змінюється між релізами. Він використовується в:

• HTTP-маршрутах (/addon/{id}/…, /addon_static/{id}/…)
• посиланнях depends_on між аддонами
• перевірці оновлень (catalog API і GitHub releases)

Не змінюйте id після першого публічного релізу, якщо лише не публікуєте новий аддон.

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

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

Рекомендований вміст 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 (обов'язково для синхронізації з каталогом).

Чеклист перед публікацією

1. id у manifest.json дорівнює ORG/REPO вашого GitHub-репозиторію.
2. version збігається з тегом GitHub-релізу.
3. У релізі є main.zip, manifest.json і logo.png / logo.svg.
4. У main.zip є всі файли, необхідні для роботи аддона (включно з manifest.json і іконкою).
5. Дозволи в маніфесті відповідають реальній поведінці аддона.
6. Після публікації релізу запустіть синхронізацію з каталогом (на сайті або через API синхронізації), щоб користувачі отримали нові файли.

Кешування файлів у каталозі

Коли аддон додають до каталогу, сайт завантажує файли релізу (manifest.json, logo.png / logo.svg, main.zip) і кешує їх постійно.

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

Після модерації та схвалення аддона користувачі завантажують саме ті файли, що були перевірені. Зміна файлів у GitHub-релізі без синхронізації не змінює те, що отримують користувачі. Це зроблено навмисно й захищає від тихої підміни файлів після модерації.

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

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

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

1. У релізі є manifest.json, logo.png (або logo.svg) і main.zip.
2. Поле id у manifest.json відповідає репозиторію за тими ж правилами, що в manifest.json: ORG/REPO для сторонніх репозиторіїв або REPO (лише назва репозиторію) для аддонів організації RocketMan-StreamKit.
3. Файл manifest.json у assets релізу ідентичний manifest.json всередині main.zip.

Якщо перевірка не пройдена, додавання або синхронізацію відхиляють із поясненням.

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

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

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

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

1. Відкрийте сторінку Аддони на сайті.
2. Натисніть кнопку API key зверху.
3. Скопіюйте токен розробника з модального вікна.

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

Тримайте токен у секреті. Будь-хто, хто має його, може запускати оновлення версій ваших аддонів. Зберігайте його як секрет CI/CD (наприклад GitHub Actions secret ROCKETMAN_ADDON_TOKEN) і не комітьте в репозиторій.

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

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

Параметри можна передати також як 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):

Ліміти запитів

• 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 — опис полів
• Початок роботи — структура проєкту під час розробки