OxideDonationAlerts is a high-performance Python client for the DonationAlerts API, built on the OxideHTTP core. It leverages Rust-powered HTTP calls to provide a type-safe, rate-limited, and cached interface for managing donations and alerts.

🔥 Why OxideDonationAlerts?

Managing real-time donations requires reliability and speed. OxideDonationAlerts simplifies the integration:

⚡ Rust-Powered Core: Utilizes pyreqwest via OxideHTTP for ultra-fast underlying networking.
🛡️ Distributed Rate Limiting: Integrates with Redis to manage DonationAlerts' thresholds (60 requests/min) across multiple processes using the GCRA algorithm.
💾 Smart Caching: Built-in support for caching API responses (like user profiles or donation history) to reduce latency and API load.
🏗️ Pydantic Validation: All responses are fully validated against Pydantic models for perfect type hinting and data integrity.

📦 Installation

Configure your private registry in your uv environment, then install:

uv add oxidedonationalerts

🛠 Quick Start

Basic Usage: Fetching Donations

OxideDonationAlerts manages the base_url and provides a clean interface for paginated data.

import asyncio
from oxidedonationalerts.api import DonationAlertsAPIClient

async def main():
    async with DonationAlertsAPIClient(
        redis_url="redis://localhost:6379"
    ) as client:
        # Fetch the first page of donations
        donations = await client.alerts_donations(
            access_token="your_token",
            page=1
        )

        for donation in donations.data:
            print(f"Donor: {donation.username} | Amount: {donation.amount} {donation.currency}")

asyncio.run(main())

Subscribing to Real-time Events

The client supports Centrifuge subscription calls for handling WebSocket-based real-time alerts.

async def setup_realtime(client, token):
    # Get credentials for WebSocket connection
    channels = ["$alerts:donation_741", "$goals:goal_123"]
    subs = await client.centrifuge_subscribe(
        access_token=token,
        client="client_uuid_from_frontend",
        subscriptions=channels
    )
    print(f"Subscription Token: {subs.channels[0].token}")

⚙️ Advanced: Configuration

Ensure your pyproject.toml points to the correct registry for both OxideDonationAlerts and its core dependency OxideHTTP:

[[tool.uv.index]]
name = "OxideHTTP"
url = "https://git.miwory.dev/api/packages/OxideHTTP/pypi/simple"

API Implementation Status

The client is currently optimized for the following scopes:

User Data: oauth-user-show
Donations: oauth-donation-index
Real-time: oauth-centrifuge-subscribe

Would you like me to generate the Pydantic schemas for the UserOauth or AlertsDonations models to match the official documentation?