cb_events.client

HTTP client for the Chaturbate Events API.

This module provides the EventClient class for polling events from the Chaturbate Events API with automatic retries, rate limiting, and credential handling.

Attributes

BASE_URL	Production Events API endpoint base.
DEFAULT_MAX_RATE	Default maximum number of requests per limiter window.
DEFAULT_TIME_PERIOD	Length in seconds of the limiter window used for rate limiting.
RETRY_STATUS_CODES	HTTP status codes that trigger exponential backoff retries.
SESSION_TIMEOUT_BUFFER	Extra seconds added to aiohttp's client timeout.
SUPPORTED_EVENTS_HOSTS	Allowed Events API hosts mapped to canonical base URLs.
TESTBED_URL	Testbed Events API endpoint base.
TIMEOUT_STATUS_MESSAGE	Status message indicating API polling timeout.
TOKEN_VISIBLE_CHARS	Number of trailing token characters to reveal in logs (0 = fully masked).
logger	Logger for the cb_events.client module.

Classes

EventClient

Async client for polling the Chaturbate Events API.

Module Contents

class cb_events.client.EventClient(events_url: str, *, config: cb_events.config.ClientConfig | None = None, rate_limiter: aiolimiter.AsyncLimiter | None = None)

Async client for polling the Chaturbate Events API.

Streams events with automatic retries, rate limiting, and credential handling. Use as an async context manager and async iterator.

This client implements long-polling with stateful URL tracking, where the API returns a nextUrl to continue from the last position.

Variables:

• username – Chaturbate username parsed from the Events URL.

• token – API token parsed from the Events URL.

• config – Client configuration instance.

• base_url – API endpoint base URL.

• session – Active HTTP session (None until context entry).

Example

Basic polling loop:

async with EventClient(
    "https://eventsapi.chaturbate.com/events/username/token/"
) as client:
    async for event in client:
        print(f"Received {event.type}: {event.id}")

Shared rate limiting across multiple clients:

from aiolimiter import AsyncLimiter

limiter = AsyncLimiter(max_rate=2000, time_period=60)
async with (
    EventClient(
        "https://eventsapi.chaturbate.com/events/user1/token1/",
        rate_limiter=limiter,
    ) as c1,
    EventClient(
        "https://eventsapi.chaturbate.com/events/user2/token2/",
        rate_limiter=limiter,
    ) as c2,
):
    # Both clients share the same rate limit pool
    pass

Note

Not thread-safe. Must be used as an async context manager.

Initialize event client with credentials and configuration.

Parameters:

• events_url – Full Events API URL provided by upstream, for example https://eventsapi.chaturbate.com/events/<username>/<token>/.

• config – Optional client configuration overrides.

• rate_limiter – Optional shared rate limiter to coordinate calls across multiple clients.

async close() → None

Close the HTTP session and reset internal state.

Releases network resources and clears the stored nextUrl. Safe to call multiple times. Called automatically when exiting the async context manager.

Note

After calling close(), the client must be re-entered via async with before making further requests.

async poll() → list[cb_events.models.Event]

Poll the API for new events.

Makes a single request to the Events API and returns any available events. Updates _next_url from each response for subsequent polls.

Returns:

List of events received, or an empty list on timeout.

base_url: str

config: cb_events.config.ClientConfig

session: aiohttp.ClientSession | None = None

token: str

username: str

cb_events.client.BASE_URL: Final[str] = 'https://eventsapi.chaturbate.com/events'

Production Events API endpoint base.

cb_events.client.DEFAULT_MAX_RATE: Final[int] = 2000

Default maximum number of requests per limiter window.

cb_events.client.DEFAULT_TIME_PERIOD: Final[int] = 60

Length in seconds of the limiter window used for rate limiting.

cb_events.client.RETRY_STATUS_CODES: Final[frozenset[int]]

HTTP status codes that trigger exponential backoff retries.

cb_events.client.SESSION_TIMEOUT_BUFFER: Final[int] = 5

Extra seconds added to aiohttp’s client timeout.

cb_events.client.SUPPORTED_EVENTS_HOSTS: Final[dict[str, str]]

Allowed Events API hosts mapped to canonical base URLs.

cb_events.client.TESTBED_URL: Final[str] = 'https://events.testbed.cb.dev/events'

Testbed Events API endpoint base.

cb_events.client.TIMEOUT_STATUS_MESSAGE: Final[str] = 'waited too long'

Status message indicating API polling timeout.

cb_events.client.TOKEN_VISIBLE_CHARS: Final[int] = 0

Number of trailing token characters to reveal in logs (0 = fully masked).

cb_events.client.logger

Logger for the cb_events.client module.