╭──────────────────────────────────────────────────────────╮
      │  ♜  CARDINAL · headless Starvell automation engine       │
      │                                                          │
      │   poll chats ──► plugins ──► orders ──► bump ──► logs   │
      ╰──────────────────────────────────────────────────────────╯

Starvell Cardinal — Telegram-панель управления для продавцов Starvell.com.
Читает ЛС покупателей, гоняет плагины, поднимает лоты — уведомления в логах, не в спаме TG.

🛒 Готовые плагины

Готовые модули под Starvell Cardinal — автоматика заказов, Telegram-панель, интеграции с поставщиками.

	Плагин	Цена	Что делает
⭐	Auto Stars	1 750 ₽	Автопродажа Telegram Stars через Fragment
💨	Auto Steam	1 500 ₽	Автопополнение Steam (ns.gifts и аналоги)
🎮	Auto DPGame	1 750 ₽	Перепродажа товаров с DPGame на Starvell
📉	Auto Dumper	1 500 ₽	Подрезание цен конкурентов с защитой по марже
🧱	Auto Robux	1 750 ₽	Автовыдача Robux по заказам

Заказ: @knowtake · Плагин под заказ — напишу любой модуль под вашу задачу (API, автовыдача, демпер, UI в боте).

📡 Inbox FunPay-style chat listener lastMessage API · plugin events

🧩 Plugins BIND_TO_NEW_MESSAGE BIND_TO_NEW_ORDER · hooks

🛡️ Anti-bot Next.js fallback · rate limit HTTP keep-alive

⚡ Установка

Важно: для автообновлений нужен git clone, не скачивание zip с GitHub.

wget https://raw.githubusercontent.com/etheriumflipper/StarvellCardinal/main/install.sh -O install.sh && bash install.sh

🐧 Linux / VPS (рекомендуется)

git clone https://github.com/etheriumflipper/StarvellCardinal.git
cd StarvellCardinal
sudo bash install.sh
sudo systemctl enable --now starvell-cardinal
sudo journalctl -u starvell-cardinal -f

install.sh сам настроит git в /opt/starvell-cardinal — /update заработает сразу.

🪟 Windows

git clone https://github.com/etheriumflipper/StarvellCardinal.git
cd StarvellCardinal
Setup.bat
Start.bat

🔄 Обновление

Через бота

/update          — установить последнюю версию
/check_update    — только проверить

⚠️ «Это не Git репозиторий!»

Так бывает, если бот поставили через zip или старый install.sh скопировал файлы без .git.

Автоматически (v0.3.8+): бот сам попробует починить репозиторий при /update.

Вручную на сервере:

cd /opt/starvell-cardinal    # или твоя папка с main.py
python fix_git_repo.py
sudo systemctl restart starvell-cardinal

Или через git напрямую:

cd /opt/starvell-cardinal
sudo -u starvell git fetch origin main
sudo -u starvell git reset --hard origin/main
sudo systemctl restart starvell-cardinal

Твои configs/, storage/, plugins/, logs/ при этом не трогаются.

🎛️ Модули

	Модуль	Что делает
⤴️	Auto-raise	Поднятие лотов по категориям (fallback через заказы, если профиль 403)
💬	Chat listener	Ловит ЛС покупателей — даже когда Starvell отдаёт только lastMessage
🎁	Auto-delivery	Выдача товаров по шаблонам
🤖	Auto-response	Ответы на новые заказы
🟢	Keep-alive	Вечный онлайн (HTTP heartbeat, Socket.IO fallback)
🧩	Plugins	Python-модули в plugins/ — документация
🔄	Auto-update	/update с GitHub — авто-починка git

🧩 Плагины за 60 секунд

# plugins/hello.py
NAME, VERSION, DESCRIPTION, AUTHOR = "Hello", "1.0.0", "Test", "@knowtake"
UUID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

async def on_new_message(data, starvell_service=None, **kwargs):
  if data.get("content", "").lower() == "привет":
    await starvell_service.send_message(data["chat_id"], "Привет! Cardinal на связи.")

BIND_TO_NEW_MESSAGE = [on_new_message]

Положи файл в plugins/ → systemctl restart starvell-cardinal → пиши в ЛС на Starvell → смотри journalctl -f.

📚 API Reference · Plugins API

📋 Логи вместо TG-спама

По умолчанию уведомления только в journal, Telegram не засоряется:

# configs/_main.cfg
[Notifications]
newMessages = 0
newOrders = 0

Включить TG обратно: /notifications в боте или newMessages = 1.

🗂️ Структура

StarvellCardinal/
├── main.py
├── fix_git_repo.py   # починка автообновления
├── api/              # Starvell client (Next.js + REST)
├── bot/
│   ├── core/         # chat_listener, notifications, services
│   ├── features/     # auto_raise, keep_alive, auto_update
│   └── plugins/      # plugin manager
├── configs/_main.cfg
├── docs/             # API_REFERENCE · PLUGINS_API
└── plugins/          # твои .py модули

📦 Changelog (recent)

Ver	Highlights
0.3.8	Авто-починка git при /update · install.sh настраивает .git
0.3.7	TG-уведомления off по умолчанию · redesign README
0.3.6	Fix lastMessage DM detection · unread on startup
0.3.5	FunPay-style chat events для плагинов
0.3.4	Auto-raise 403 fallback chain

🔧 Первый запуск

1. Bot Token — @BotFather
2. Пароль — для входа в панель бота
3. session_cookie — из браузера на starvell.com

Мастер first_setup.py создаст конфиг и systemd-сервис.

_{MIT © @knowtake · @starvellingbot}