Metadata-Version: 2.4
Name: bbsocials_bot
Version: 1.1.0
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 official BBSocials API and realtime gateway.

## Authentication

`bot.run(token)` validates the token through `GET /api/v1/bot/me` before opening the Socket.IO gateway. User IDs, application IDs, account sessions, revoked tokens, disabled bots, and banned bots are rejected.

## Supported bot REST API

The SDK is intentionally limited to routes protected by the `botToken` security scheme in BBSocials OpenAPI 0.4.0:

| Method | Route | SDK behavior |
|---|---|---|
| `GET` | `/api/v1/bot/me` | Token validation and bot identity |
| `PUT` | `/api/v1/bot/commands` | Automatic slash-command synchronization |
| `POST` | `/api/v1/bot/channels/{channelId}/messages` | `ctx.send()` and `bot.send_message()` |

Public diagnostics are also available:

```python
live = await bot.is_service_live()
ready = await bot.is_service_ready()
```

The SDK does not use user-session, CSRF-protected, developer-portal, or admin routes.

## 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 gateway

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

Voice operations use the realtime gateway rather than a REST route.

## 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)
```

## Important route limitation

The supplied OpenAPI contract does not expose bot-token endpoints for communities, member lookup, roles, message history, direct messages, tickets, or application management. Those features cannot be called by the SDK until matching `/api/v1/bot/...` routes are added to the backend and documented.

Documentation: https://social.blackbullnetwork.eu/app/developers?tab=docs
