Metadata-Version: 2.4
Name: openbot_api
Version: 1.2.1
Summary: Python client for the Openbot ID authorization API
Author: Kafnik
License-Expression: MIT
Keywords: telegram,authorization,fastapi,telebot
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Openbot API 1.2.1

Python library to check Telegram user roles and levels against your Openbot ID server.

## Install

```bash
pip install openbot_api
```

Until the new package is published to PyPI, install the local wheel included in the release archive.

## Usage

```python
import os
import telebot
import openbot_api

bot = telebot.TeleBot(os.environ["TELEGRAM_BOT_TOKEN"])
openbot = openbot_api.OpenbotAPI(api_key=os.environ["OPENBOT_API_KEY"], bot=bot)

@bot.message_handler(commands=["start"])
@openbot.check_level("tester", level=2)
@openbot.check_level("developer", level=2)
def start(message):
    bot.reply_to(message, "✅ Доступ разрешён!")

bot.infinity_polling()
```

Two stacked `check_level` decorators grant access if **either** status and its required level match.

Other methods: `get_user(id)`, `get_status(id)`, `get_level(id)`, `has_level(id, role, level)`, `check_access(id)`, and `require_access()`.

### Checking several statuses

```python
if not openbot.check_access(
    message.from_user.id,
    ("developer", "tester", "admin", "owner"),
    level=1,
):
    bot.reply_to(message, "⛔ Недостаточно прав!")
    return
```

This checks the user's **exact** status and minimum level, with OR across the requested statuses. It does not implicitly grant access to `owner` unless `owner` is included. The former `openbot.check_access(user_id)` is still supported and delegates to the server's general policy.

## Legacy bot compatibility (new in 1.2.0)

`get_id(user_id)` (returns tuple or `None`), `get_user_level(user_id)`, `check_dev_tester_level(user_id, required_level=1)`, `is_dev_or_owner(user_id)`, `is_globally_banned(user_id)`, `get_developers_count()`, `get_active_bots(user_id)` and the `ROLE`/`LEVEL` mappings.

`register_bot_activity(user_id, bot_name)` and `create_id(user_id, name, emoji=None)` now work with a **trusted bot API key** with the `bot_write` scope. Ordinary keys remain read-only. `update_bio`, `set_status` and `toggle_dev_mode` still **require server administrator credentials** (passed as `admin_key=` or `OPENBOT_ADMIN_API_KEY`). Do not distribute the administrator key to other developers or publicly distributed bots.

The associated server endpoints are **not available** until the administrator upgrades the server-side `api_keys.py`, `manage_keys.py`, `api_extensions.py` and registers the routers as documented in `server-extension/README.md`.

The API key is a secret. Do not commit it to Git, place it in bot source, or share it publicly. The client is intentionally **read-only**: new keys may only be issued by an authorized administrator on the server, not through an unauthenticated public endpoint.

## API keys on Linux server

See `server-key-tools/README.md` in the release archive. Back up your existing key database before replacing any existing files. `api_keys.py` and `manage_keys.py` are server-side tools and must **not** be published as part of the Python package.
