Metadata-Version: 2.4
Name: cb-events
Version: 1.12.0
Summary: An asynchronous client for the Chaturbate Events API.
Project-URL: Homepage, https://github.com/MountainGod2/chaturbate-events
Project-URL: Documentation, https://github.com/MountainGod2/chaturbate-events#readme
Project-URL: Repository, https://github.com/MountainGod2/chaturbate-events.git
Project-URL: Changelog, https://github.com/MountainGod2/chaturbate-events/blob/main/CHANGELOG.md
Project-URL: Issue Tracker, https://github.com/MountainGod2/chaturbate-events/issues
Author-email: MountainGod2 <admin@reid.ca>
Maintainer-email: MountainGod2 <admin@reid.ca>
License: MIT
License-File: LICENSE
Keywords: api,async,chaturbate,client,events,real-time,streaming,webcam
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pydantic
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiohttp-retry==2.9.1
Requires-Dist: aiohttp==3.12.15
Requires-Dist: aiolimiter==1.2.1
Requires-Dist: pydantic==2.11.9
Description-Content-Type: text/markdown

# CB Events

Async Python wrapper for Chaturbate Events API with real-time event notifications.

[![PyPI](https://img.shields.io/pypi/v/cb-events)](https://pypi.org/project/cb-events/)
[![Python](https://img.shields.io/pypi/pyversions/cb-events)](https://pypi.org/project/cb-events/)
[![License](https://img.shields.io/github/license/MountainGod2/cb-events)](https://github.com/MountainGod2/chaturbate-events/tree/main/LICENSE)

## Installation

```bash
pip install cb-events
```

## Quick Start

```python
import asyncio
import os
from cb_events import EventClient, EventRouter, EventType

async def main():
    # Get credentials from environment
    username = os.getenv("CB_USERNAME")
    token = os.getenv("CB_TOKEN")

    router = EventRouter()

    @router.on(EventType.TIP)
    async def handle_tip(event):
        tip = event.tip
        user = event.user
        if tip and user:
            print(f"{user.username} tipped {tip.tokens} tokens")

    @router.on(EventType.CHAT_MESSAGE)
    async def handle_message(event):
        message = event.message
        user = event.user
        if message and user:
            print(f"{user.username}: {message.message}")

    async with EventClient(username, token) as client:
        async for event in client:
            await router.dispatch(event)

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

## Event Types

Handle various broadcaster events:

- **Tips**: `TIP`
- **Chat**: `CHAT_MESSAGE`, `PRIVATE_MESSAGE`
- **Users**: `USER_ENTER`, `USER_LEAVE`, `FOLLOW`, `UNFOLLOW`
- **Broadcast**: `BROADCAST_START`, `BROADCAST_STOP`, `ROOM_SUBJECT_CHANGE`
- **Fanclub**: `FANCLUB_JOIN`
- **Media**: `MEDIA_PURCHASE`

## Configuration

Set credentials via environment variables:

```bash
export CB_USERNAME="your_username"
export CB_TOKEN="your_api_token"
```

Or pass directly to client:

```python
from cb_events import EventClient

client = EventClient(username="your_username"token="your_api_token")
```

### Retry Configuration

Configure retry behavior for handling network errors:

```python
from cb_events import EventClient

client = EventClient(
    username="your_username",
    token="your_api_token",
    config=EventClientConfig(
        timeout=10
        use_testbed=True,
        retry_attempts=5,            # Maximum retry attempts
        retry_backoff=2.0,           # Initial backoff delay in seconds
        retry_max_delay=60.0,        # Maximum delay between retries
        retry_exponential_base=2.0   # Exponential backoff factor
        )
    )
```

**Default retry behavior:**
- Retries on: 500, 502-504, 521-524 (Cloudflare), and 429 status codes
- No retry on: authentication errors (401, 403)
- 8 attempts with exponential backoff (1s, 2s, 4s...)
- Maximum delay: 30 seconds

## Error Handling

```python
from cb_events.exceptions import EventsError, AuthError

try:
    async with EventClient(username, token) as client:
        async for event in client:
            await router.dispatch(event)
except AuthError:
    logger.error("Authentication failed")
except EventsError as e:
    logger.error("API error: %s", e.message)
```

## Requirements

- Python 3.11+
- aiohttp
- pydantic
- aiolimiter

## License

MIT licensed. See [LICENSE](https://github.com/MountainGod2/chaturbate-events/tree/main/LICENSE).

## Disclaimer

Not affiliated with Chaturbate.
