Metadata-Version: 2.4
Name: bbsocials_bot
Version: 1.0.1
Summary: A Python SDK for creating bots on BBSocials.
Author: BlackBullNetwork
License-Expression: MIT
Project-URL: Homepage, https://social.blackbullnetwork.eu
Project-URL: Documentation, https://social.blackbullnetwork.eu/app/developers?tab=docs
Keywords: BBSocials,Bot,BBSocials.py
Classifier: Development Status :: 3 - Alpha
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-socketio[asyncio_client]<6,>=5.11
Dynamic: license-file

# bbsocials_bot

A Python SDK for creating bots on BBSocials.

## Install

```bash
pip install bbsocials_bot
```

## Minimal bot

```python
import os

import bbsocials_bot
from bbsocials_bot.ext import commands

bot = commands.Bot()

@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}")

@bot.command(description="Say hello")
async def hello(ctx: bbsocials_bot.Context):
    await ctx.send(f"Hello, {ctx.author.display_name}!")

bot.run(os.environ["BBSOCIALS_BOT_TOKEN"])
```

`commands.Bot()` automatically connects to the service


## Authentication

`bot.run(token)` performs these steps:

1. Rejects values that clearly are not BBSocials bot tokens.
2. Requires a valid, enabled, non-banned bot application and bot identity.
3. Opens the Socket.IO gateway only after successful REST authentication.

A user ID, application ID, normal account session, revoked token, disabled bot, or
banned bot will not authenticate.

## Commands

```python
@bot.command(description="Add two numbers")
@commands.describe(first="First number", second="Second number")
async def add(ctx, first: int, second: int):
    await ctx.send(str(first + second))
```

Type annotations become command option types:

- `str` -> `string`
- `int` -> `integer`
- `float` -> `number`
- `bool` -> `boolean`
- parameters with defaults are optional
- `str | None` is optional

## UI components

```python
from bbsocials_bot import ui

class Menu(ui.View):
    @ui.button(label="Click", custom_id="menu:click", style=ui.ButtonStyle.primary)
    async def click(self, interaction, button):
        await interaction.respond("Clicked!")

@bot.command(description="Show UI")
async def menu(ctx):
    await ctx.send("Choose:", view=Menu())
```

## Voice

```python
await bot.voice.join(channel_id)
await bot.voice.play(channel_id, audio_url, title="Music")
await bot.voice.leave(channel_id)
```

## Roles

```python
await ctx.add_role(member_id, role_id)
```

The bot must have Manage Roles in the community.

## Events

```python
@bot.event
async def on_connect():
    print("Gateway connected")

@bot.event
async def on_ready():
    print("Bot ready")

@bot.event
async def on_command_error(ctx, error):
    await ctx.send(f"Error: {error}")

@bot.event
async def on_interaction(interaction):
    print(interaction.custom_id)
```
