KickPy

KickPy is a powerful and flexible Python library designed to interact with the Kick API. It provides an event-driven interface to fetch user, channel, and stream data, post messages, manage moderation (ban/timeout), and subscribe to real-time events. The library includes a built-in caching mechanism to optimize performance and reduce redundant API calls.

🚀 Features

• ✅ OAuth2 authentication flow with token caching
• 🔁 Real-time event subscription system
• 💬 Post and receive chat messages
• 👤 Fetch user and channel information
• 📺 Monitor livestreams and metadata
• 🛠️ Moderate users (ban, timeout)
• 🗂️ Access categories and streams
• 🧠 Caching layer for efficient API usage

📦 Installation

pip install kickpy

🔧 Usage Example

from kickpy import (
    KickClient,
    Scopes,
    Events,
    Message,
    Broadcaster,
    Subscription,
    Gift,
    Stream,
    Ban,
    Timeout,
    __version__ as version
)

client = KickClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    scopes=[
        Scopes.USER_READ,
        Scopes.EVENTS_SUBSCRIBE,
        Scopes.CHANNEL_READ
    ],
)

@client.on(Events.ON_READY)
async def on_ready():
    print(f"Logged in as {client.me.name} (ID: {client.me.user_id})")

@client.on(Events.ON_MESSAGE)
async def on_message(message: Message):
    sender = await message.sender.get_or_resolve()
    print(f"{sender.name}: {message.content}")

@client.on(Events.ON_FOLLOW)
async def on_follow(broadcaster: Broadcaster, follower: Broadcaster):
    print(f"{follower.name} followed {broadcaster.name}")

@client.on(Events.ON_SUBSCRIPTION)
async def on_subscription(subscription: Subscription):
    print(f"{subscription.subscriber.name} subscribed to {subscription.broadcaster.name}")

@client.on(Events.ON_SUBSCRIPTION_GIFT)
async def on_subscription_gift(gift: Gift):
    gifter = gift.gifter.name if not gift.gifter.is_anonymous else "Anonymous"
    print(f"{gifter} gifted {len(gift.subscriptions)} subscriptions to {gift.broadcaster.name}")

@client.on(Events.ON_LIVESTREAM_STARTED)
async def on_livestream_started(stream: Stream):
    broadcaster = await stream.broadcaster.get_or_resolve()
    print(f"{broadcaster.name} started streaming: {stream.stream_title}")

@client.on(Events.ON_MODERATION_BAN)
async def on_moderation_ban(moderation: Ban):
    print(f"{moderation.user.name} was banned by {moderation.moderator.name} for: {moderation.reason}")

@client.on(Events.ON_MODERATION_TIMEOUT)
async def on_moderation_timeout(moderation: Timeout):
    print(f"{moderation.user.name} was timed out by {moderation.moderator.name} until {moderation.expires_at}")


if __name__ == "__main__":
    print(f"Starting Kick {version} client...")
    client.run()

⚙️ Client Configuration Options

Parameter	Description	Default
client_id	Your Kick application client ID	Required
client_secret	Your Kick application client secret	Required
scopes	OAuth2 scopes for API access	None
development	Enable development mode	False
web_app_url	Web application URL for redirect/webhook	"http://0.0.0.0:8000"
oauth_redirect_host	Hostname for the redirect server	"localhost"
webhook_callback_endpoint	Webhook callback endpoint	"webhook"
oauth_redirect_endpoint	OAuth redirect endpoint	"oauth/callback"
cache_oauth	Cache the OAuth token locally	True
oauth_file	File to cache OAuth tokens	".oauth"
prefetch_me	Automatically fetch authenticated user info	True
loop	Custom asyncio event loop	None
http_client_cls	Custom HTTP client implementation	lib._http.KickHttpClient

📡 Available Events

Event Name	Description
ON_READY	Raised when the client successfully connects and authentication completes.
ON_MESSAGE	Raised when a chat message is received in the connected channel.
ON_FOLLOW	Raised when a user follows the connected channel.
ON_SUBSCRIPTION	Raised when a user subscribes to the channel.
ON_SUBSCRIPTION_GIFT	Raised when a user gifts one or more subscriptions.
ON_LIVESTREAM_STARTED	Raised when the channel starts a livestream.
ON_LIVESTREAM_ENDED	Raised when a livestream ends.
ON_LIVESTREAM_UPDATED	Raised when livestream metadata (title, category, etc.) is updated.
ON_MODERATION_BAN	Raised when a user is banned from the channel.
ON_MODERATION_TIMEOUT	Raised when a user is timed out from the channel.
ON_OAUTH_URL	Raised when an OAuth URL is generated for user authentication.
ON_ERROR	Raised when an unhandled internal error occurs during event processing.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! If you encounter bugs, need a feature, or want to help, feel free to open an issue or submit a pull request.

📫 Contact

For questions, issues, or ideas, open a GitHub issue or contact the maintainer.