Релиз

README.md

@@ -0,0 +1,96 @@
+# 🧡 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?