https://github.com/etheriumflipper/starvellcardinal
Starvell Cardinal - работающий кардинал под сервис Starvell.
https://github.com/etheriumflipper/starvellcardinal
aiogram automation bot bots cardinal marketplace marketplace-bot python starvell starvell-cardinal starvell-marketplace starvellapi starvellcardinal telegram telegram-bot
Last synced: about 11 hours ago
JSON representation
Starvell Cardinal - работающий кардинал под сервис Starvell.
- Host: GitHub
- URL: https://github.com/etheriumflipper/starvellcardinal
- Owner: etheriumflipper
- License: mit
- Created: 2026-04-23T20:29:34.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-30T00:44:13.000Z (3 days ago)
- Last Synced: 2026-06-30T02:19:47.282Z (3 days ago)
- Topics: aiogram, automation, bot, bots, cardinal, marketplace, marketplace-bot, python, starvell, starvell-cardinal, starvell-marketplace, starvellapi, starvellcardinal, telegram, telegram-bot
- Language: Python
- Homepage:
- Size: 274 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
```text
╭──────────────────────────────────────────────────────────╮
│ ♜ CARDINAL · headless Starvell automation engine │
│ │
│ poll chats ──► plugins ──► orders ──► bump ──► logs │
╰──────────────────────────────────────────────────────────╯
```
> **Starvell Cardinal** — Telegram-панель управления для продавцов [Starvell.com](https://starvell.com).
> Читает ЛС покупателей, гоняет плагины, поднимает лоты — уведомления в **логах**, не в спаме TG.
### 📡 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.
```bash
wget https://raw.githubusercontent.com/etheriumflipper/StarvellCardinal/main/install.sh -O install.sh && bash install.sh
```
🐧 Linux / VPS (рекомендуется)
```bash
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
```bat
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`.
**Вручную на сервере:**
```bash
cd /opt/starvell-cardinal # или твоя папка с main.py
python fix_git_repo.py
sudo systemctl restart starvell-cardinal
```
**Или через git напрямую:**
```bash
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/` — [документация](docs/PLUGINS_API.md) |
| 🔄 | **Auto-update** | `/update` с GitHub — авто-починка git |
## 🧩 Плагины за 60 секунд
```python
# 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](docs/API_REFERENCE.md) · [Plugins API](docs/PLUGINS_API.md)
## 📋 Логи вместо TG-спама
По умолчанию **уведомления только в journal**, Telegram не засоряется:
```ini
# configs/_main.cfg
[Notifications]
newMessages = 0
newOrders = 0
```
Включить TG обратно: `/notifications` в боте или `newMessages = 1`.
## 🗂️ Структура
```text
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