SDK v0.2.0

Создание и публикация плагина

Установите SDK, проверьте плагин локально, загрузите приватный кандидат и дайте его тестировщикам. Готовую версию можно отправить на модерацию маркетплейса.

Открыть кабинет разработчика Помощь: @sup_pulsebot

Разделы SDK

Шаг 1

Установка SDK

SDK работает отдельно от Pulse и устанавливается как обычный Python-пакет.

Python

Python 3.10+

Система

Windows, Linux или macOS

Среда

Отдельный venv рекомендуется

Создать виртуальное окружение

python -m venv .venv

Активировать · macOS / Linux

. .venv/bin/activate

Активировать · Windows PowerShell

.\\.venv\\Scripts\\Activate.ps1

Установить опубликованный SDK

python -m pip install "https://funpaypulse.com/releases/sdk/0.2.0/funpay_pulse_sdk-0.2.0-py3-none-any.whl"

Проверить установку

pulse-plugin --help

SHA-256 wheel: cec1e82352c252875a43faf6eb60e254dbea3bb8b48f3ebdfd76b54cbf828b84

Шаг 2

Создание первого плагина

Начните с шаблона и получите готовую структуру манифеста, fixtures и приложения.

Создать проект

pulse-plugin init seller_auto_reply

Перейти в каталог

cd seller_auto_reply

broker-pollerПо умолчанию

Получает события через Broker API. Подходит для первого запуска и отладки.

order-assistantЗаказы и лоты

Основа для чтения безопасных данных заказов и лотов.

basic-webhookBeta

Webhook-доставка с обязательной проверкой подписи и polling fallback.

trusted-actionsРучная проверка

Действия, меняющие данные FunPay. Требует отдельных прав и расширенной модерации.

Другой шаблон выбирается через --template order-assistant. Идентификатор плагина используйте в нижнем регистре: латинские буквы, цифры и подчёркивания.

SDK 0.2.0

Интерфейс плагина на Python

Опишите коллекции и команды на Python — Pulse покажет таблицу, карточку записи и форму действия.

Создать нативный каталог

pulse-plugin init my_catalog --template native-catalog

Проверить сценарии

pulse-plugin verify my_catalog

Открыть локальный интерфейс

pulse-plugin dev my_catalog

Preview входит в пакет SDK. Для работы нужны Python 3.10+ и браузер. Изменения Python загружаются автоматически. Доступны поиск, фильтры, сортировка, выбор аккаунта и лота, а также проверка неизвестного результата команды после обновления версии.

Локальный режим работает с тестовыми данными. На реальной установке нативный интерфейс доступен при поддержке сервером и клиентом Pulse; полный список аккаунтов и лотов требует совместимого Worker.

Руководство по нативным плагинам (.md)

Шаг 3

Локальные проверки

Сначала докажите работу на fixtures. Реальный аккаунт, токены и публикация для этого не нужны.

Создать тестовое событие

pulse-plugin emit fixtures/new_message.json --force

Проверить манифест, файлы и fixtures

pulse-plugin check . --require-fixtures

Запустить код на fixtures

pulse-plugin test .

Полная готовность перед упаковкой

pulse-plugin doctor . --require-fixtures

Важно: команда test импортирует и запускает локальный app.py. Используйте её только для кода, которому доверяете.

Шаг 4

Сборка .fppkg

Пакет фиксирует версию, которую увидят тестировщики и модератор.

Собрать пакет

pulse-plugin pack .

Результат появится в dist/<plugin_id>-<version>.fppkg. Архив содержит манифест, инвентарь файлов и SHA-256 каждого файла.

Сборка детерминирована: одинаковые исходники дают одинаковый пакет.
Секреты, приватные ключи, базы, бинарные файлы, кэши и symlink блокируются.
Успешный pack ещё не означает одобрение или публикацию в маркетплейсе.

Шаг 5

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

Токен создаётся в кабинете, показывается один раз и нужен только для загрузки кандидата.

Откройте кабинет разработчика и перейдите в «Аккаунт разработчика».
В разделе «SDK-токены» создайте токен и сразу сохраните его безопасно.
Передайте токен CLI через временный файл, а не аргумент командной строки.

Безопасно подготовить token file

umask 077
token_file="$(mktemp "${TMPDIR:-/tmp}/pulse-developer-token.XXXXXX")"
trap 'rm -f "$token_file"' EXIT
read -r -s developer_token
printf '%s\n' "$developer_token" > "$token_file"
unset developer_token

Загрузить приватный кандидат

pulse-plugin publish . --upload --token-file "$token_file" --api https://funpaypulse.com

Без --product-id CLI создаёт приватный продукт и загружает первую версию.
Загрузка не публикует карточку, не выдаёт доступ покупателям и не запускает код.
После завершения удалите временный token file или дождитесь выполнения trap.

Шаг 6

Личный и приватный тест

Сначала проверьте кандидат сами, затем откройте его выбранным тестировщикам.

Личный тест

В разделе «Тест» установите текущий кандидат на свой активный VPS, проверьте запуск, события, настройки и логи.

Приватный доступ

В разделе «Тестировщики» создайте одноразовое приглашение. Оно даёт доступ только указанному пользователю и не публикует продукт.

Проверьте обязательные настройки и пустые состояния.
Смоделируйте повторное событие: обработчик не должен выполнять действие дважды.
Не отправляйте тестировщику свои токены. Он устанавливает плагин через Pulse.

Шаг 7

Проверка и публикация в маркетплейсе

Публичная карточка появляется только после решения модератора.

Шаблон уже создаёт два файла карточки. До упаковки замените в них тестовые значения своими. Модератор проверяет именно содержимое зафиксированного пакета.

`funpay-pulse.plugin.json`

Название, полное описание, версия, runtime, события, права и схема настроек плагина.

`funpay-pulse.marketplace.json`

Категория, краткое описание, публичный автор, HTTPS-ссылки поддержки и конфиденциальности, а также условия возврата.

После приватного теста откройте раздел «Маркетплейс» в кабинете, выберите модель продажи, цену и срок доступа, затем нажмите «Отправить на модерацию».

На модерации

Кандидат зафиксирован. Цену, пакет и права нельзя тихо подменить в открытой заявке.

Нужны изменения

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

Опубликован

Одобренная версия доступна пользователям. Следующее обновление проходит отдельную проверку.

Модератор проверяет пакет, права, настройки, секреты и изменения файлов.
Для платного продукта обязательны понятные условия поддержки и возврата.
Trusted-права проверяются отдельно и могут оставаться недоступными даже после обычного approval.

Шаг 8

Исправления и новые версии

Не редактируйте уже отправленный артефакт: создавайте новую версию и сохраняйте историю.

Прочитайте причину в блоке модерации.
Исправьте код или карточку и увеличьте version в манифесте.
Повторите check, test, doctor и pack.
Загрузите кандидат в существующий продукт и отправьте повторно.

Загрузить новую версию существующего продукта

pulse-plugin publish . --upload --product-id plp_... --token-file "$token_file" --api https://funpaypulse.com

Пока обновление находится на модерации, ранее опубликованная версия продолжает работать у пользователей.

Шаг 9

Установка и запуск

Pulse управляет доступом и Broker-связью, но сторонний код остаётся отдельным процессом.

Покупатель получает доступ через покупку, бесплатный claim, trial или приватное приглашение.
При установке он выбирает свой VPS и подтверждает права текущей версии.
Для broker-poller Desktop может запустить managed runner; ручной запуск остаётся fallback.
Обновление устанавливается только после публикации новой одобренной версии.

Ручной внешний запуск

export FPP_BASE_URL=https://funpaypulse.com
export FPP_BROKER_TOKEN_FILE=/secure/path/broker-token
python app.py

Pulse не импортирует сторонний app.py внутрь Backend или Worker. Плагин общается с платформой только через разрешённый Broker API.

Шаг 10

Безопасность и помощь

Два типа токенов решают разные задачи и никогда не должны попадать в пакет или поддержку.

fppd_… · загрузка

Токен разработчика загружает кандидаты. Он не устанавливает плагин, не публикует его и не выдаёт доступ покупателям.

fppb_… · runtime

Broker-токен привязан к установке, лицензии, VPS и версии. Он показывается один раз и хранится как production secret.

Не добавляйте токены, golden_key, private key или реальные cookies в код, fixtures и .fppkg.
Не передавайте токены через --token: используйте --token-file и файл с правами 0600.
Для обращения укажите plugin id, product id, version, время ошибки и очищенный фрагмент лога.

Написать в Telegram