97 lines
3.0 KiB
Markdown
97 lines
3.0 KiB
Markdown
# 🧡 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?
|