Skip to content

Commit 3b8211e

Browse files
PredaaAPredaaA
committed
Update readme and docs descriptions
1 parent 6dc7c20 commit 3b8211e

5 files changed

Lines changed: 31 additions & 186 deletions

File tree

‎README.md‎

Lines changed: 16 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,16 @@
33
[![PyPI](https://img.shields.io/pypi/v/kickcom.py)](https://pypi.org/project/kickcom.py)
44
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://predaaa.github.io/kickcom.py)
55

6-
Async library for Kick.com API and webhooks
6+
Modern async Python wrapper for the Kick.com API. OAuth 2.1 PKCE, typed models, webhook server with signature verification, and full coverage of chat, channels, livestreams, moderation, and rewards.
77

8-
[Documentation](https://predaaa.github.io/kickcom.py) | [Kick API Reference](https://docs.kick.com/)
8+
## Features
9+
10+
- Full coverage of the [Kick Public API](https://docs.kick.com/) (users, channels, livestreams, categories, chat, moderation, rewards, KICKs, events)
11+
- **OAuth 2.1 + PKCE** authentication with built-in browser flow and automatic token refresh
12+
- **Webhook server** with cryptographic signature verification for real-time events
13+
- Fully typed dataclass models for all API responses and webhook payloads
14+
- Optional speed extras (`orjson`, `aiodns`, `Brotli`) for faster serialization and networking
15+
- Async/await powered by [aiohttp](https://docs.aiohttp.org/)
916

1017
## Installation
1118

@@ -21,14 +28,12 @@ pip install kickcom.py[speed]
2128

2229
## Quick Start
2330

24-
### App Access Token (Bot / Server-side)
25-
2631
```python
2732
import asyncio
2833
from kickpy import KickClient
2934

3035
async def main():
31-
client = KickClient("KICK_CLIENT_ID", "KICK_CLIENT_SECRET")
36+
client = KickClient("CLIENT_ID", "CLIENT_SECRET")
3237

3338
user = await client.fetch_user(4377088)
3439
print(user.name)
@@ -41,171 +46,11 @@ async def main():
4146
asyncio.run(main())
4247
```
4348

44-
### User Access Token (OAuth 2.1 + PKCE)
45-
46-
Some endpoints require a user token. The library handles the full OAuth flow with a built-in local callback server:
47-
48-
```python
49-
import asyncio
50-
from kickpy import KickClient, Scope
51-
52-
async def main():
53-
client = KickClient("KICK_CLIENT_ID", "KICK_CLIENT_SECRET")
54-
55-
# Opens browser, captures callback on localhost, exchanges code for tokens
56-
await client.authenticate(
57-
scopes=[Scope.CHAT_WRITE, Scope.MODERATION_BAN],
58-
port=3000, # redirect URI must be http://127.0.0.1:3000/callback in your Kick app settings
59-
)
60-
61-
# User token endpoints are now available
62-
await client.send_chat_message("Hello from kickcom.py!", broadcaster_user_id=4377088)
63-
64-
await client.close()
65-
66-
asyncio.run(main())
67-
```
68-
69-
If you handle OAuth externally, you can inject tokens directly:
70-
71-
```python
72-
client.set_user_token(
73-
access_token="...",
74-
refresh_token="...",
75-
expires_in=3600,
76-
scope="chat:write moderation:ban",
77-
)
78-
```
79-
80-
## API Reference
81-
82-
### Users
83-
84-
| Method | Description | Token |
85-
|--------|-------------|-------|
86-
| `fetch_user(user_id)` | Get a user by ID | App |
87-
88-
### Channels
89-
90-
| Method | Description | Token |
91-
|--------|-------------|-------|
92-
| `fetch_channel(user_id?, slug?)` | Get a channel by broadcaster ID or slug | App |
93-
| `update_channel(category_id?, stream_title?, custom_tags?)` | Update channel metadata | User (`channel:write`) |
94-
95-
### Livestreams
96-
97-
| Method | Description | Token |
98-
|--------|-------------|-------|
99-
| `fetch_livestream(broadcaster_user_id)` | Get a single livestream | App |
100-
| `fetch_livestreams(broadcaster_user_id?, category_id?, language?, limit?, sort?)` | Get multiple livestreams | App |
101-
| `fetch_livestream_stats()` | Get global livestream stats | App |
102-
103-
### Categories
104-
105-
| Method | Description | Token |
106-
|--------|-------------|-------|
107-
| `fetch_categories(query?, name?, tag?, category_id?, cursor?, limit?)` | Search categories (v2) | App |
108-
109-
### Chat
110-
111-
| Method | Description | Token |
112-
|--------|-------------|-------|
113-
| `send_chat_message(content, message_type?, broadcaster_user_id?, reply_to_message_id?)` | Send a chat message | User (`chat:write`) |
114-
| `delete_chat_message(message_id)` | Delete a chat message | User (`moderation:chat_message:manage`) |
115-
116-
### Moderation
117-
118-
| Method | Description | Token |
119-
|--------|-------------|-------|
120-
| `ban_user(broadcaster_user_id, user_id, duration?, reason?)` | Ban or timeout a user | User (`moderation:ban`) |
121-
| `unban_user(broadcaster_user_id, user_id)` | Unban a user | User (`moderation:ban`) |
122-
123-
### Channel Rewards
124-
125-
| Method | Description | Token |
126-
|--------|-------------|-------|
127-
| `fetch_channel_rewards()` | List channel point rewards | User (`channel:rewards:read`) |
128-
| `create_channel_reward(cost, title, ...)` | Create a reward | User (`channel:rewards:write`) |
129-
| `update_channel_reward(reward_id, ...)` | Update a reward | User (`channel:rewards:write`) |
130-
| `delete_channel_reward(reward_id)` | Delete a reward | User (`channel:rewards:write`) |
131-
| `fetch_reward_redemptions(reward_id?, status?, ids?, cursor?)` | Get redemptions | User (`channel:rewards:read`) |
132-
| `accept_reward_redemptions(ids)` | Accept pending redemptions | User (`channel:rewards:write`) |
133-
| `reject_reward_redemptions(ids)` | Reject pending redemptions | User (`channel:rewards:write`) |
134-
135-
### KICKs
136-
137-
| Method | Description | Token |
138-
|--------|-------------|-------|
139-
| `fetch_kicks_leaderboard(top?)` | Get KICKs leaderboard | User (`kicks:read`) |
140-
141-
### Events / Subscriptions
142-
143-
| Method | Description | Token |
144-
|--------|-------------|-------|
145-
| `fetch_events_subscriptions()` | List event subscriptions | App |
146-
| `subscribe_to_event(event_type, user_id)` | Subscribe to a webhook event | App |
147-
| `unsubscribe_from_event(subscription_id)` | Unsubscribe from an event | App |
148-
149-
### Other
150-
151-
| Method | Description | Token |
152-
|--------|-------------|-------|
153-
| `fetch_public_key()` | Get the Kick public key for webhook verification | App |
154-
155-
## OAuth Scopes
156-
157-
```python
158-
from kickpy import Scope
159-
160-
Scope.USER_READ # user:read
161-
Scope.CHANNEL_READ # channel:read
162-
Scope.CHANNEL_WRITE # channel:write
163-
Scope.CHANNEL_REWARDS_READ # channel:rewards:read
164-
Scope.CHANNEL_REWARDS_WRITE # channel:rewards:write
165-
Scope.CHAT_WRITE # chat:write
166-
Scope.STREAMKEY_READ # streamkey:read
167-
Scope.EVENTS_SUBSCRIBE # events:subscribe
168-
Scope.MODERATION_BAN # moderation:ban
169-
Scope.MODERATION_CHAT_MESSAGE_MANAGE # moderation:chat_message:manage
170-
Scope.KICKS_READ # kicks:read
171-
```
172-
173-
## Webhook Server
49+
## Documentation
17450

175-
Receive and process webhook events from Kick:
176-
177-
```python
178-
import asyncio
179-
from kickpy import KickClient, WebhookEvent, WebhookServer
180-
from kickpy.models.webhooks.chat_message import ChatMessage
181-
182-
def on_chat_message(payload: ChatMessage):
183-
print(f"{payload.sender.username}: {payload.content}")
184-
185-
async def main():
186-
client = KickClient("KICK_CLIENT_ID", "KICK_CLIENT_SECRET")
187-
server = WebhookServer(client, callback_route="/webhooks/kick")
188-
server.dispatcher.listen(WebhookEvent.CHAT_MESSAGE_SENT, on_chat_message)
189-
190-
await server.listen(host="localhost", port=3000, access_log=None)
191-
192-
loop = asyncio.new_event_loop()
193-
asyncio.set_event_loop(loop)
194-
loop.run_until_complete(main())
195-
loop.run_forever()
196-
```
51+
For full guides and API reference, visit the **[documentation](https://predaaa.github.io/kickcom.py)**.
19752

198-
### Webhook Events
199-
200-
| Event | Enum |
201-
|-------|------|
202-
| `chat.message.sent` | `WebhookEvent.CHAT_MESSAGE_SENT` |
203-
| `channel.followed` | `WebhookEvent.CHANNEL_FOLLOWED` |
204-
| `channel.subscription.new` | `WebhookEvent.CHANNEL_SUB_NEW` |
205-
| `channel.subscription.gifts` | `WebhookEvent.CHANNEL_SUB_GIFTS` |
206-
| `channel.subscription.renewal` | `WebhookEvent.CHANNEL_SUB_RENEWAL` |
207-
| `livestream.status.updated` | `WebhookEvent.LIVESTREAM_STATUS_UPDATED` |
208-
| `livestream.metadata.updated` | `WebhookEvent.LIVESTREAM_METADATA_UPDATED` |
209-
| `channel.moderation.user_banned` | `WebhookEvent.MODERATION_USER_BANNED` |
210-
| `kicks.gifted` | `WebhookEvent.KICKS_GIFTED` |
211-
| `channel.reward.redemption.updated` | `WebhookEvent.CHANNEL_REWARD_REDEMPTION_UPDATED` |
53+
- [Getting Started](https://predaaa.github.io/kickcom.py/getting-started/) - Install and make your first API call
54+
- [Authentication](https://predaaa.github.io/kickcom.py/authentication/) - App tokens, user tokens, and OAuth flow
55+
- [API Reference](https://predaaa.github.io/kickcom.py/api/client/) - All client methods, models, enums, and errors
56+
- [Webhooks](https://predaaa.github.io/kickcom.py/webhooks/setup/) - Set up a webhook server and handle real-time events

‎docs/authentication.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Required for endpoints that act on behalf of a user (chat, moderation, rewards,
2626

2727
### Browser Flow (Built-in)
2828

29-
The simplest approach -- the library opens the user's browser and captures the callback:
29+
The simplest approach, the library opens the user's browser and captures the callback:
3030

3131
```python
3232
from kickpy import KickClient, Scope

‎docs/index.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
# kickcom.py
22

3-
Async library for the [Kick.com](https://kick.com) API and webhooks.
3+
Modern async Python wrapper for the [Kick.com](https://kick.com) API - OAuth 2.1 PKCE, typed models, webhook server with signature verification, and full coverage of chat, channels, livestreams, moderation, and rewards.
44

55
---
66

77
## Features
88

9-
- Full coverage of the [Kick Public API](https://docs.kick.com/)
10-
- **App Access Tokens** (client credentials) for server-side use
11-
- **User Access Tokens** (OAuth 2.1 + PKCE) with built-in browser flow
12-
- **Webhook server** with signature verification for real-time events
13-
- Auto-generated API reference from docstrings
14-
- Async/await with [aiohttp](https://docs.aiohttp.org/)
9+
- Full coverage of the [Kick Public API](https://docs.kick.com/) (users, channels, livestreams, categories, chat, moderation, rewards, KICKs, events)
10+
- **OAuth 2.1 + PKCE** authentication with built-in browser flow and automatic token refresh
11+
- **Webhook server** with cryptographic signature verification for real-time events
12+
- Fully typed dataclass models for all API responses and webhook payloads
13+
- Optional speed extras (`orjson`, `aiodns`, `Brotli`) for faster serialization and networking
14+
- Async/await powered by [aiohttp](https://docs.aiohttp.org/)
1515

1616
## Quick Example
1717

@@ -32,7 +32,7 @@ asyncio.run(main())
3232

3333
## Next Steps
3434

35-
- [Getting Started](getting-started.md) -- Install and make your first API call
36-
- [Authentication](authentication.md) -- App tokens vs user tokens
37-
- [API Reference](api/client.md) -- All client methods
38-
- [Webhooks](webhooks/setup.md) -- Receive real-time events
35+
- [Getting Started](getting-started.md) - Install and make your first API call
36+
- [Authentication](authentication.md) - App tokens, user tokens, and OAuth flow
37+
- [API Reference](api/client.md) - All client methods, models, enums, and errors
38+
- [Webhooks](webhooks/setup.md) - Set up a webhook server and handle real-time events

‎docs/webhooks/setup.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,8 @@ loop.run_forever()
3030

3131
1. **Create a `WebhookServer`** with a `KickClient` and a callback route path
3232
2. **Register listeners** on the dispatcher for specific event types
33-
3. **Start the server** -- it listens for incoming POST requests from Kick
34-
4. **Signature verification** is automatic -- the server fetches the Kick public key and validates every request using RSA PKCS1v15 + SHA-256
33+
3. **Start the server** it listens for incoming POST requests from Kick
34+
4. **Signature verification** is automatic, the server fetches the Kick public key and validates every request using RSA PKCS1v15 + SHA-256
3535

3636
## Subscribing to Events
3737

‎mkdocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
site_name: kickcom.py
22
site_url: https://predaaa.github.io/kickcom.py
3-
site_description: Async library for Kick.com API and webhooks
3+
site_description: Modern async Python wrapper for the Kick.com API with OAuth 2.1 PKCE, typed models, and webhook support
44
repo_url: https://github.com/PredaaA/kickcom.py
55
repo_name: PredaaA/kickcom.py
66

0 commit comments

Comments
 (0)