v27

core-routes.md

@@ -51,6 +51,7 @@ This file lists the current HTTP routes exposed by Core, grouped by access level
 | `GET` | `/me/node-protocols` | none | Available node protocols for the current user |
 | `GET` | `/me/balance` | none | `{ balance }` |
 | `GET` | `/me/balance/transactions` | none | User balance transaction history |
+| `GET` | `/me/donation-alerts` | none | Returns configured state, donation page URL, displayed commission, `RUB`, and the current user's UUID. Never returns the access token. |
 | `GET` | `/me/subscriptions` | none | User subscriptions |
 | `GET` | `/me/links` | none | All user subscription links |
 | `GET` | `/me/configs` | none | Available node/protocol configs for the current user |
@@ -204,11 +205,14 @@ This file lists the current HTTP routes exposed by Core, grouped by access level
 
 | Method | Route | Input | Output / Notes |
 | --- | --- | --- | --- |
-| `GET` | `/admin/settings/:category` | none | Returns settings for the given category (`panel`, `subscription`, `telegram`, `ipinfo`) |
+| `GET` | `/admin/settings/:category` | none | Returns settings for the given category (`panel`, `subscription`, `telegram`, `ipinfo`, `donation_alerts`) |
 | `PATCH` | `/admin/settings/panel` | `PanelSettingsDto` | Updates panel settings |
 | `PATCH` | `/admin/settings/subscription` | `SubscriptionSettingsDto` | Updates subscription delivery settings |
 | `PATCH` | `/admin/settings/telegram` | `TelegramSettingsDto` | Updates Telegram bot settings |
 | `PATCH` | `/admin/settings/ipinfo` | `{ provider?: "ipinfo" \| "ip-api", token?: string, language?: "ru" \| "en" }` | Updates the IP information provider settings. `token` is required by IPinfo.io; `language` is used by ip-api.com and defaults to `en`. The route name is retained for compatibility. |
+| `PATCH` | `/admin/settings/donation-alerts` | `{ clientId?: string, clientSecret?: string, redirectUri?: string, donationPageUrl?: string, commissionPercent?: number }` | Saves DonationAlerts OAuth application and payment settings. Changing OAuth credentials clears existing tokens. |
+| `POST` | `/admin/payments/donation-alerts/authorization-url` | none | Creates a short-lived OAuth state and returns the DonationAlerts authorization URL with `oauth-donation-index` scope. |
+| `POST` | `/admin/payments/donation-alerts/callback` | `{ code: string, state: string }` | Exchanges an OAuth callback code for access and refresh tokens. Access tokens are refreshed automatically. |
 
 ## Admin routes - broadcasts
 
@@ -365,6 +369,7 @@ This file lists the current HTTP routes exposed by Core, grouped by access level
 - `PanelSettingsDto` - `allowedHosts?`, `rootPath?`
 - `SubscriptionSettingsDto` - `allowedHosts?`, `rootPath?`, `updateInterval?`, `name?`, `supportUrl?`, `websiteUrl?`
 - `TelegramSettingsDto` - `botToken?`
+- `DonationAlertsSettingsDto` - `clientId?`, `clientSecret?`, `redirectUri?`, `donationPageUrl?`, `commissionPercent?`
 
 ### Broadcasts
 

core.md

@@ -18,6 +18,7 @@ This page is public operator documentation. It describes behavior, API, environm
 - Public subscription exports for VPN clients.
 - Platform settings management (panel, subscription delivery, Telegram, IP information provider).
 - User IP history with country, city, ISP, and ASN enrichment through IPinfo.io or ip-api.com.
+- OAuth-based DonationAlerts integration with automatic token refresh and RUB balance deposits linked by user UUID.
 - Telegram broadcast messages with user filtering and delivery tracking.
 - Referral system with code-based self-approval for pending users.
 - Audit logs, usage queries, metrics, and health checks.
@@ -158,6 +159,7 @@ Missing or unknown `format` falls back to `v2ray`.
 | `GET` | `/me/traffic/hourly-dist` | Hour-of-day traffic distribution. |
 | `GET` | `/me/balance` | Current balance. |
 | `GET` | `/me/balance/transactions` | User balance history. |
+| `GET` | `/me/donation-alerts` | Safe DonationAlerts payment settings and the current user's UUID. |
 | `GET` | `/me/subscriptions` | User subscriptions. |
 | `GET` | `/me/links` | User subscription links. |
 | `GET` | `/me/configs` | Available configs for the user. |

panel.md

@@ -71,6 +71,16 @@ This page is public operator documentation. It describes panel capabilities, rou
 - Configure subscription delivery settings (update interval, display name, support URL).
 - Configure Telegram bot token.
 - Configure the user IP information provider: IPinfo.io with an API token, or ip-api.com with Russian or English result language. English is the default for ip-api.com.
+- Configure a DonationAlerts OAuth application with its client ID, client secret, generated callback URL, public donation page URL, and commission percentage. After saving, authorize it through DonationAlerts; access and refresh tokens are stored and refreshed automatically.
+
+### DonationAlerts Payments
+
+- The Finance page shows an add-funds button only while DonationAlerts is configured.
+- The payment modal shows the configured commission and the current user's UUID.
+- The user must put exactly one UUID in the donation message; otherwise the donation remains unassigned.
+- Core checks donations every 5 minutes, scanning donations created during the previous hour.
+- Only positive whole-RUB donations are processed. The configured commission is deducted and the credited result is rounded down to whole RUB; other currencies and fractional gross amounts are skipped.
+- Donation IDs are stored as unique external transaction references, preventing duplicate credits.
 
 ### User IP History