# Twitch Client (Async)

An internal **async Twitch API client** built on top of **AioHTTPX**, providing typed access to the Twitch **Helix API** and **OAuth2** endpoints with built-in rate limiting and optional caching.

---

## What it provides

* `TwitchAPIClient` — async client for Twitch **Helix API**
* `TwitchAuthClient` — async client for Twitch **OAuth2**
* Built on **AioHTTPX** (aiohttp transport, Redis rate limiting & caching)
* Strongly typed responses using **Pydantic models**
* Automatic request parameter cleanup (`None` values removed)

---

## Installation (internal)

Configure your private package index, then:

```bash
pip install twitchclient
```

---

## Authentication

### OAuth helper client

```python
from twitchclient.auth import TwitchAuthClient
from twitchclient import scopes

auth = TwitchAuthClient(
    client_id="CLIENT_ID",
    client_secret="CLIENT_SECRET",
    redirect_uri="https://your.app/callback",
)

url = await auth.create_authorization_code_grant_flow_url(
    scope=[scopes.USER_READ_EMAIL, scopes.CHAT_READ],
)
```

### App access token

```python
token = await auth.app_access_token()
print(token.access_token)
```

### User access token

```python
token = await auth.user_access_token(code="AUTH_CODE")
```

---

## API Client

```python
from twitchclient.api import TwitchAPIClient

client = TwitchAPIClient(
    client_id="CLIENT_ID",
    client_secret="CLIENT_SECRET",
    redirect_uri="https://your.app/callback",
    redis_url="redis://localhost:6379",  # optional
)
```

* Base URL: `https://api.twitch.tv/helix`
* `Client-Id` header is set automatically
* Rate limit defaults to **700 req/min** when Redis is enabled

---

## Example usage

### Get channel information

```python
channels = await client.get_channel_information(
    access_token=token.access_token,
    broadcaster_id=123456,
)
```

### Start a commercial

```python
await client.start_commercial(
    access_token=token.access_token,
    broadcaster_id=123456,
)
```

### Cached request

Caching is controlled via the `X-Cache-TTL` header:

```python
streams = await client.get_streams(
    access_token=token.access_token,
    game_id=509658,
    cache_time=30,
)
```

---

## Rate limiting & caching

* **Redis-backed**
* Shared key: `twitch`
* Enabled automatically when `redis_url` is provided
* Cache TTL is per-request (`X-Cache-TTL` header)

Implementation is inherited from **AioHTTPX transports** .

---

## Errors

All API methods raise typed exceptions:

* `ClientError(status_code, message)`
* `InternalError(status_code, message)`

Defined in schema module .

---

## Scopes

OAuth scopes are defined as constants and typed literals:

```python
from twitchclient import scopes

scopes.CHANNEL_READ_SUBSCRIPTIONS
scopes.CHAT_READ
```

See `scopes.py` for the full list .

---

## Typed responses

All successful responses return **Pydantic models**, e.g.:

* `ChannelsInformation`
* `Streams`
* `Users`
* `EventsubSubscriptions`

Models live in `schema.py` .

---

## Notes & limitations

* Async-only (no sync client)
* Internal API, no stability guarantees
* Some endpoints still marked TODO (e.g. Guest Star)

---