Metadata-Version: 2.4
Name: prismacore
Version: 0.1.0
Summary: Python SDK for orchestrating sing-box VPN nodes
Author: PrismaCore Authors
License-Expression: MIT
Project-URL: Documentation, https://github.com/DevGMoree/PrismaCore#readme
Project-URL: Repository, https://github.com/DevGMoree/PrismaCore
Project-URL: Issues, https://github.com/DevGMoree/PrismaCore/issues
Keywords: sing-box,vpn,sdk,proxy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Requires-Dist: redis>=5.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# PrismaCore

Monorepo: REST API для одной sing-box-ноды (`server/`) и Python SDK для управления несколькими нодами (`client/`).

**License:** MIT · **English:** [README.en.md](README.en.md)

---

## Состав

| Часть | Что делает |
|-------|------------|
| `server/` | FastAPI: CRUD пользователей, инбаундов, аутбаундов, роутов; генерация share-ссылок; запись конфига sing-box |
| `client/` | SDK: несколько нод, выбор по региону/latency, сборка подписок |
| `deploy/` | Установка server на Linux (systemd) |

SDK не отдаёт HTTP-подписку клиентам — вы сами оборачиваете `core.subscriptions.build()` во FastAPI/Flask/nginx.

---

## Требования

- Python 3.10+
- sing-box (для server)
- Redis — опционально (кэш на server и в SDK)

---

## Установка

**SDK (PyPI):**

```bash
pip install prismacore
```

**SDK (из исходников / dev):**

```bash
git clone https://github.com/YOUR_USER/PrismaCore.git
cd PrismaCore
pip install -e .
```

**Server:**

```bash
pip install -r server/requirements.txt
# или production: sudo bash deploy/install_server.sh
```

Импорт SDK: `from client import PrismaCore`. Публикация новых версий на PyPI — [docs/publishing.md](docs/publishing.md).

---

## Быстрый старт

```python
import asyncio
from client import PrismaCore

async def main():
    async with PrismaCore.single_node(
        url="http://127.0.0.1:8000",
        token="<api-token>",
        public_host="203.0.113.10",  # публичный IP/домен для share-ссылок на server
    ) as core:
        await core.node().users.create_simple("alice", inbound_tags=["vless-in"])
        sub = await core.subscriptions.build("alice")
        print(sub[:80])

asyncio.run(main())
```

Токен API создаётся один раз: `POST /api/v1/auth/token` (см. [docs/server.md](docs/server.md)).

---

## Документация

| Документ | Содержание |
|----------|------------|
| [docs/sdk.md](docs/sdk.md) | SDK: конфиг, CRUD, регионы, подписки, кэш, ошибки, модели |
| [docs/server.md](docs/server.md) | Server API: эндпoинты, auth, env, sing-box, share-ссылки |
| [docs/deploy.md](docs/deploy.md) | Production-установка: `install_server.sh`, systemd, `.env` |
| [docs/publishing.md](docs/publishing.md) | PyPI: сборка, первая загрузка, новые версии |

---

## Архитектура

```
PrismaCore (SDK)
├── vpn_servers: VpnServerManager     # реестр нод
├── regions: RegionService            # fastest_node / best_nodes
├── subscriptions: SubscriptionAggregator
└── cache: CacheManager               # Redis, опционально

Node (на каждую ноду)
├── users / inbounds / outbounds / routes / system
└── HttpClient → server /api/v1/*
```

Типичный поток подписки:

1. SDK выбирает ноды по регионам (`fastest_only=True` — одна на регион)
2. На каждой ноде: `GET /api/v1/sublink/{user_name}/all`
3. Server собирает `vless://` / `hysteria2://` из БД + `HOST`
4. SDK добавляет meta-строки Happ, кодирует в base64

---

## Структура репозитория

```
client/
├── prismacore.py
├── config.py, models.py, api_funcs.py, cache.py, exceptions.py
├── nodes/          node.py, vpn.py
├── resources/      users, inbounds, outbounds, routes, system
├── regions/        prober.py, registry.py
└── subscriptions/  aggregator.py

server/
├── app.py, routes.py, config.py
├── database.py, models.py, schemas.py
└── core/           singbox.py, cache.py

deploy/
├── install_server.sh
├── prismacore.service
└── .env.example
```

---

## Частые ошибки

- **`HOST=localhost` на server** — share-ссылки будут с localhost, клиенты не подключатся. Задайте публичный IP/домен.
- **Забыли `invalidate` после CRUD** — подписчики получат закэшированную подписку без новых ссылок.
- **Несколько нод, `core.node()` без имени** — `ConfigError`. Указывайте `core.node("de-1")`.
- **Токен в заголовке** — server ждёт `?token=...` в query, не Bearer.

---

## English

See [README.en.md](README.en.md) and [docs/en/](docs/en/).
