DonationAlerts API

A lightweight library for easy integration with the DonationAlerts API: authorization, token management, and user info in a few lines.

Available in: RU, EN

Installation

Using npm:

$ npm install @kash-88/alerts

Using yarn:

$ yarn add @kash-88/alerts

Using pnpm:

$ pnpm add @kash-88/alerts

Using bun:

$ bun add @kash-88/alerts

Available Methods (Quick Overview)

| Function | Purpose | |---------------------|--------------------------------------------------------------| | getAuthorizeLink | Generate OAuth authorization link | | getOauthToken | Exchange code for access_token and refresh_token | | getUser | Fetch user profile by access_token | | getUserChannel | Get user channel by user_id | | updateAccessToken | Refresh access_token using refresh_token | | getPrivateToken | Get private token for channel subscription |

getAuthorizeLink (Sync)

Purpose: Generate OAuth authorization link for DonationAlerts.

• Params:
  • client_id: string — Your app"s client ID
  • scope: string[] — Array of access scopes
• Endpoint: https://www.donationalerts.com/oauth/authorize
• API Docs: Authorization Request

Example:

import { getAuthorizeLink } from "@kash-88/alerts";

const client_id = "YOUR_CLIENT_ID"; // Get on https://www.donationalerts.com/application/clients
const scope = ["oauth-user-show"];

try {
    const link = getAuthorizeLink({ client_id, scope });
    console.log("Authorize link:", link);
} catch (error) {
    console.error("Error:", error.message);
} 

getOauthToken (Async)

Purpose: Exchange authorization code for access_token and refresh_token.

• Params:
  • client_id: string — Your app's client ID
  • client_secret: string — Your app's client secret
  • code: string — Authorization code
• Endpoint: https://www.donationalerts.com/oauth/token
• API Docs: Getting Access Token

Example:

import { getOauthToken } from "@kash-88/alerts";

// Get on https://www.donationalerts.com/application/clients
const client_id = "YOUR_CLIENT_ID";
const client_secret = process.env.CLIENT_SECRET!;
const code = "USER_CODE";

(async () => {
    try {
        const token = await getOauthToken({ client_id, client_secret, code });
        console.log("Oauth token:", token);
    } catch (error) {
        console.error("Error:", error.message);
    }
})(); 

getUser (Async)

Purpose: Fetch user profile information by access_token.

• Params:
  • access_token: string — User's access token
• Endpoint: https://www.donationalerts.com/api/v1/user/oauth
• API Docs: User Info

Example:

import { getUser } from "@kash-88/alerts";

const user_access_token = "USER_ACCESS_TOKEN";

(async () => {
    try {
        const user = await getUser(user_access_token);
        console.log("User data:", user);
    } catch (error) {
        console.error("Error:", error.message);
    }
})(); 

getUserChannel (Sync)

Purpose: Get user channel by user_id.

• Params:
  • user_id: string — User ID
• Endpoint: —
• API Docs: —

Example:

import { getUserChannel } from "@kash-88/alerts";

const user_id = "USER_ID";

const channel = getUserChannel(user_id);
console.log("User channel:", channel);

updateAccessToken (Async)

Purpose: Refresh access_token using refresh_token.

• Params:
  • client_id: string — Your app's client ID
  • client_secret: string — Your app's client secret
  • refresh_token: string — Refresh token
• Endpoint: https://www.donationalerts.com/oauth/token
• API Docs: Refreshing Access Tokens

Example:

import "dotenv/config";
import { getOauthToken } from "@kash-88/alerts";

// Get on https://www.donationalerts.com/application/clients
const client_id = "YOUR_CLIENT_ID";
const client_secret = process.env.CLIENT_SECRET!;

const refresh_token = "USER_REFRESH_TOKEN";

(async () => {
    try {
        const token = await getOauthToken({ client_id, client_secret, refresh_token });
        console.log("Oauth token:", token);
    } catch (error) {
        console.error("Error:", error.message);
    }
})();

getPrivateToken (Async)

Purpose: Get a private token for subscribing to a DonationAlerts channel via Centrifuge.

• Params:
  • channel: string — Channel name to subscribe
  • uuidv4_client_id: string — UUID v4 client ID (used in WebSocket connection)
  • access_token: string — User's OAuth access token
• Endpoint: https://www.donationalerts.com/api/v1/centrifuge/subscribe
• API Docs: —

Example:

import { getPrivateToken } from "@kash-88/alerts";

const channel = "USER_CHANNEL"; // Get via getUserChannel
const uuidv4_client_id = "UUIDv4_CLIENT_ID"; // WebSocket client UUID
const access_token = "USER_ACCESS_TOKEN";

(async () => {
    try {
        const token = await getPrivateToken({ channel, uuidv4_client_id, access_token });
        console.log("Private token:", token);
    } catch (error) {
        console.error("Error getting private token:", error.message);
    }
})();