# 🧡 OxideDonationAlerts

**OxideDonationAlerts** is a high-performance Python client for the [DonationAlerts API](https://www.donationalerts.com/apidoc), built on the [OxideHTTP](https://git.miwory.dev/OxideHTTP/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:

```bash
uv add oxidedonationalerts

```

---

## 🛠 Quick Start

### Basic Usage: Fetching Donations

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

```python
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.

```python
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**:

```toml
[[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?