Metadata-Version: 2.5
Name: noluyo-bot
Version: 0.1.0
Summary: Official Python SDK for the N'oluyo bot platform
Author: N'oluyo
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Provides-Extra: http
Requires-Dist: cryptography>=42; extra == 'http'
Provides-Extra: voice
Requires-Dist: livekit>=0.17; extra == 'voice'
Description-Content-Type: text/markdown

# noluyo-bot (Python)

Official async Python SDK (`noluyo_bot`) for the [N'oluyo](https://noluyo.net/gelistirici) bot platform.

- **Python `>=3.11`** (`asyncio`, `IntFlag`, `TypedDict`, full `py.typed` hints)
- Single lightweight runtime dependency: `aiohttp>=3.9`
- Optional extras: `noluyo-bot[http]` (`cryptography>=42` for Ed25519 HTTP interaction signature verification) and `noluyo-bot[voice]` (`livekit>=0.17` for publish-only voice)
- Automatic per-bucket rate-limit queueing, `Retry-After` handling, shared-scope backoff, and `GET`-only 5xx retries
- Gateway sharding, jittered heartbeats, automatic `RESUME` (`op 6`), and fatal close-code protection
- Automatic bot token redaction in `__repr__`, `__str__`, and exceptions

Türkçe rehber için: [README.tr.md](./README.tr.md)

## Installation

```bash
pip install noluyo-bot
# Optional: HTTP interaction signature verification
pip install "noluyo-bot[http]"
# Optional: publish-only voice support
pip install "noluyo-bot[voice]"
```

## Quick Start

Never hardcode your bot token in source files. Read it from `os.environ["BOT_TOKEN"]`:

```python
import asyncio
import os
from noluyo_bot import Client, Intents

bot = Client(
    token=os.environ["BOT_TOKEN"],
    intents=Intents.GUILDS | Intents.GUILD_MESSAGES | Intents.MESSAGE_CONTENT,
)


@bot.on("READY")
async def on_ready(ready):
    print(f"Connected as {ready['user']['username']}")


@bot.on("MESSAGE_CREATE")
async def on_message(message):
    if message["author"].get("bot"):
        return
    if message["content"] == "!merhaba":
        await bot.rest.create_message(message["channel_id"], {"content": "Merhaba!"})


@bot.interactions.on("ping")
async def on_ping(ctx):
    await ctx.reply("Pong!", ephemeral=True)


async def main():
    async with bot:
        await bot.login()
        await bot.commands.sync([{"name": "ping", "description": "Checks whether the bot is alive"}])
        await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())
```

## HTTP Interaction Signature Verification

```python
import os
from noluyo_bot import verify_interaction

ok = verify_interaction(
    os.environ["NOLUYO_PUBLIC_KEY"],
    request_headers["X-Signature-Ed25519"],
    request_headers["X-Signature-Timestamp"],
    raw_body_bytes,
)
```

## Voice Publishing

Bots on N'oluyo are strictly publish-only in voice channels (`canSubscribe: false`) and can never hear or record users.

```python
conn = await bot.voice.join(guild_id, voice_channel_id)
await conn.play_file("./music.mp3")
await conn.leave()
```

## License

MIT — Copyright (c) 2026 N'oluyo
