@kash-88/alerts 1.2.1 → 1.3.0

package/src/Function/createCustomAlerts.ts

@@ -0,0 +1,65 @@
+import { CustomAlerts } from "@type";
+import axios from "axios";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Send a custom alert to the authorized user.
+ *
+ * @param {string} access_token - User access token
+ * @param {string} external_id - Up to 32 characters long unique alert ID
+ * @param {string} header - Up to 255 characters long header text
+ * @param {string} message - Up to 300 characters long message text
+ * @param {number} is_shown - 0 or 1, determines whether the alert should be displayed
+ * @param {string | null} [image_url] - URL to the image file displayed with the alert
+ * @param {string | null} [sound_url] - URL to the sound file played when displaying the alert
+ *
+ * @returns {Promise<CustomAlerts>} Created custom alert data
+ * @see {@link https://www.donationalerts.com/apidoc#api_v1__custom_alerts__send_custom_alerts}
+ */
+
+export default async function createCustomAlerts(
+	access_token: string,
+	external_id: string,
+	header: string,
+	message: string,
+	is_shown: 0 | 1,
+	image_url?: string | null,
+	sound_url?: string | null
+): Promise<CustomAlerts> {
+	if (!access_token || typeof access_token !== "string") {
+		throw new Error("access_token must be a non-empty string");
+	}
+	if (!external_id || typeof external_id !== "string") {
+		throw new Error("external_id must be a non-empty string");
+	}
+	if (typeof header !== "string" || typeof message !== "string") {
+		throw new Error("header and message must be strings");
+	}
+	if (is_shown !== 0 && is_shown !== 1) {
+		throw new Error("is_shown must be 0 or 1");
+	}
+
+	try {
+		const formData = new URLSearchParams();
+		formData.append("external_id", external_id);
+		formData.append("header", header);
+		formData.append("message", message);
+		formData.append("is_shown", String(is_shown));
+		if (image_url) formData.append("image_url", image_url);
+		if (sound_url) formData.append("sound_url", sound_url);
+
+		const response = await axios.post<{ data: CustomAlerts }>("https://www.donationalerts.com/api/v1/custom_alert",
+			formData,
+			{
+				headers: {
+					Authorization: `Bearer ${access_token}`,
+					"Content-Type": "application/x-www-form-urlencoded"
+				}
+			}
+		);
+
+		return response.data.data;
+	} catch (error: any) {
+		throw new Error(formatAxiosError(error));
+	}
+} 

package/src/Function/createMerchandise.ts

@@ -0,0 +1,105 @@
+import axios from "axios";
+import { Merchandise } from "@type";
+import generateSignature from "@function/generateSignature.js";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Create a new merchandise.
+ *
+ * @param {string} access_token - User access token
+ * @param {string} client_secret - API client secret key for signature
+ * @param {string} merchant_identifier - Merchant's ID on DonationAlerts
+ * @param {string} merchandise_identifier - Up to 16 characters long unique merchandise ID
+ * @param {Record<string, string>} title - Object with merchandise titles in different locales (en_US required)
+ * @param {string} currency - Currency code (EUR, USD, RUB, BRL, TRY)
+ * @param {number} price_user - Revenue added to streamer for each sale
+ * @param {number} price_service - Revenue added to DonationAlerts for each sale
+ * @param {number} [is_active=0] - 0 or 1, whether merchandise is available for purchase
+ * @param {number} [is_percentage=0] - 0 or 1, whether prices are percentages or absolute amounts
+ * @param {string} [url] - URL to merchandise's web page
+ * @param {string} [img_url] - URL to merchandise's image
+ * @param {number} [end_at_ts] - Unix timestamp when merchandise becomes inactive
+ *
+ * @returns {Promise<Merchandise>} Created merchandise data
+ * @see {@link https://www.donationalerts.com/apidoc#api_v1__merchandises__create_merchandise}
+ */
+
+export default async function createMerchandise(
+    access_token: string,
+    client_secret: string,
+    merchant_identifier: string,
+    merchandise_identifier: string,
+    title: Record<string, string>,
+    currency: string,
+    price_user: number,
+    price_service: number,
+    is_active: number = 0,
+    is_percentage: number = 0,
+    url?: string,
+    img_url?: string,
+    end_at_ts?: number
+): Promise<Merchandise> {
+    if (!access_token || typeof access_token !== "string") {
+        throw new Error("access_token must be a non-empty string");
+    }
+    if (!client_secret || typeof client_secret !== "string") {
+        throw new Error("client_secret must be a non-empty string");
+    }
+    if (!merchant_identifier || typeof merchant_identifier !== "string") {
+        throw new Error("merchant_identifier must be a non-empty string");
+    }
+    if (!merchandise_identifier || typeof merchandise_identifier !== "string") {
+        throw new Error("merchandise_identifier must be a non-empty string");
+    }
+    if (!title || Object.keys(title).length === 0) {
+        throw new Error("title must be a non-empty object");
+    }
+    if (!currency || typeof currency !== "string") {
+        throw new Error("currency must be a non-empty string");
+    }
+    if (typeof price_user !== "number" || typeof price_service !== "number") {
+        throw new Error("price_user and price_service must be numbers");
+    }
+
+    try {
+        const params: Record<string, string | number> = {
+            merchant_identifier,
+            merchandise_identifier,
+            currency,
+            price_user,
+            price_service,
+            is_active,
+            is_percentage
+        };
+
+        for (const [locale, value] of Object.entries(title)) {
+            params[`title[${locale}]`] = value;
+        }
+        if (url) params.url = url;
+        if (img_url) params.img_url = img_url;
+        if (end_at_ts !== undefined) params.end_at_ts = end_at_ts;
+
+        const signature = generateSignature(params, client_secret);
+        params.signature = signature;
+
+        const formData = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            formData.append(key, String(value));
+        }
+
+        const response = await axios.post<{ data: Merchandise }>(
+            "https://www.donationalerts.com/api/v1/merchandise",
+            formData,
+            {
+                headers: {
+                    Authorization: `Bearer ${access_token}`,
+                    "Content-Type": "application/x-www-form-urlencoded"
+                }
+            }
+        );
+
+        return response.data.data;
+    } catch (error: any) {
+        throw new Error(formatAxiosError(error));
+    }
+}

package/src/Function/generateSignature.ts

@@ -0,0 +1,23 @@
+import { createHash } from "crypto";
+
+/**
+ * Generate a SHA256 request signature for Merchandise API.
+ *
+ * The signature is formed from alphabetically sorted parameter values
+ * (interpreted as strings) with the API client secret appended to the end.
+ *
+ * @param {Record<string, string | number>} params - Request parameters
+ * @param {string} client_secret - API client secret key
+ *
+ * @returns {string} SHA256 hex digest signature
+ * @see {@link https://www.donationalerts.com/apidoc#introduction__http_api_requests__request_signatures}
+ */
+
+export default function generateSignature(
+    params: Record<string, string | number>,
+    client_secret: string
+): string {
+    const sortedValues = Object.values(params).map(String).sort();
+    const valuesString = sortedValues.join("");
+    return createHash("sha256").update(valuesString + client_secret).digest("hex");
+}

package/src/Function/getAuthorizeLink.ts

@@ -0,0 +1,37 @@
+import { OAuthScope } from "@type";
+
+/**
+ * Generate OAuth authorization link for DonationAlerts.
+ * 
+ * @param {string} client_id - Your client (application) ID
+ * @param {string} redirect_uri - The URL where users will be sent after authorization
+ * @param {OAuthScope[]} scopes - Array of access scopes
+ * @param {'code' | 'token'} type - Type response oauth token
+ * 
+ * @returns {string} The authorization URL.
+ * @see {@link https://www.donationalerts.com/apidoc#authorization__authorization_code__authorization_steps}
+ */
+
+export default function getAuthorizeLink(
+    client_id: string,
+    redirect_uri: string,
+    scopes: OAuthScope[],
+    type: 'code' | 'token'
+): string {
+    if (!client_id || typeof client_id !== "string") {
+        throw new Error("client_id must be a non-empty string");
+    }
+    if (!redirect_uri || typeof redirect_uri !== "string") {
+        throw new Error("redirect_uri must be a non-empty string");
+    }
+    if (!Array.isArray(scopes) || scopes.length === 0) {
+        throw new Error("scopes must be a non-empty array");
+    }
+    if (type !== "code" && type !== "token") {
+        throw new Error("type must be 'code' or 'token'");
+    }
+
+    const uniqueScopes = Array.from(new Set(scopes));
+
+    return `https://www.donationalerts.com/oauth/authorize?client_id=${encodeURIComponent(client_id)}&redirect_uri=${encodeURIComponent(redirect_uri)}&response_type=${type}&scope=${uniqueScopes.join("%20")}`;
+}

package/src/Function/getDonationsAlerts.ts

@@ -0,0 +1,37 @@
+import axios from "axios";
+import { DonationsAlerts } from "@type";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Fetch user donation alerts list.
+ *
+ * @param {string} access_token - User access token
+ * @param {number | string} [page=1] - Page number for pagination
+ *
+ * @returns {Promise<DonationsAlerts>} Donation alerts data
+ * @see {@link https://www.donationalerts.com/apidoc#api_v1__donations__donation_alerts_list}
+ */
+
+export default async function getDonationsAlerts(
+    access_token: string,
+    page: number | string = 1
+): Promise<DonationsAlerts> {
+    if (!access_token || typeof access_token !== "string") {
+        throw new Error("access_token must be a non-empty string");
+    }
+
+    try {
+        const response = await axios.get<DonationsAlerts>("https://www.donationalerts.com/api/v1/alerts/donations", {
+            params: {
+                page
+            },
+            headers: {
+                Authorization: `Bearer ${access_token}`
+            }
+        });
+
+        return response.data;
+    } catch (error: any) {
+        throw new Error(formatAxiosError(error));
+    }
+}

package/src/Function/getExternal.ts

@@ -0,0 +1,31 @@
+import { randomBytes } from "crypto";
+
+/**
+ * Generate a random 32-character external ID.
+ *
+ * @returns {string} 32 random alphanumeric characters
+ */
+
+export default function getExternal(): string {
+    const charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    const randomValues = randomBytes(32);
+
+    // Use rejection sampling to avoid bias
+    const charsetLength = charset.length;
+    const maxValidValue = 256 - (256 % charsetLength);
+    let result = "";
+    let index = 0;
+
+    while (index < 32) {
+        const randomValue = randomValues[index];
+        if (randomValue < maxValidValue) {
+            result += charset[randomValue % charsetLength];
+            index++;
+        } else {
+            // Rejection: generate a new random value for this position
+            randomValues[index] = randomBytes(1)[0];
+        }
+    }
+
+    return result;
+} 

package/src/Function/getOauthToken.ts

@@ -0,0 +1,54 @@
+import axios from "axios";
+import { OAuthToken } from "@type";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Exchange Authorization code for OAuth token and Refresh token.
+ * 
+ * @param {string} client_id - Your client (application) ID
+ * @param {string} client_secret - Your client (application) secret
+ * @param {string} redirect_uri - The URL where users will be sent after authorization
+ * @param {string} code - User authorization code
+ * 
+ * @returns {Promise<OAuthToken>} OAuth user token
+ * @see {@link https://github.com/kash-ts/alerts-SDK?tab=readme-ov-file#getOauthToken}
+ */
+
+export default async function getOauthToken(
+    client_id: string,
+    client_secret: string,
+    redirect_uri: string,
+    code: string
+): Promise<OAuthToken> {
+    if (!client_id || typeof client_id !== "string") {
+        throw new Error("client_id must be a non-empty string");
+    }
+    if (!client_secret || typeof client_secret !== "string") {
+        throw new Error("client_secret must be a non-empty string");
+    }
+    if (!redirect_uri || typeof redirect_uri !== "string") {
+        throw new Error("redirect_uri must be a non-empty string");
+    }
+    if (!code || typeof code !== "string") {
+        throw new Error("code must be a non-empty string");
+    }
+
+    try {
+        const formData = new URLSearchParams();
+        formData.append("grant_type", "authorization_code");
+        formData.append("client_id", client_id);
+        formData.append("client_secret", client_secret);
+        formData.append("redirect_uri", redirect_uri);
+        formData.append("code", code);
+
+        const response = await axios.post<OAuthToken>("https://www.donationalerts.com/oauth/token", formData, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded"
+            }
+        });
+
+        return response.data;
+    } catch (error: any) {
+        throw new Error(formatAxiosError(error));
+    }
+} 

package/src/Function/getPrivateToken.ts

@@ -0,0 +1,50 @@
+import axios from "axios";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Get a Private token for subscribing to a DonationAlerts channel via Centrifuge.
+ *
+ * @param {string} channel - User channel
+ * @param {string} client - Centrifugo UUIDv4 client ID
+ * @param {string} access_token - User OAuth token
+ * 
+ * @returns {Promise<string>} - Token for channel subscription.
+ */
+
+export default async function getPrivateToken(
+  channel: string,
+  client: string,
+  access_token: string
+): Promise<string> {
+  if (!channel || typeof channel !== "string") {
+    throw new Error("channel must be a non-empty string");
+  }
+  if (!client || typeof client !== "string") {
+    throw new Error("client must be a non-empty string");
+  }
+  if (!access_token || typeof access_token !== "string") {
+    throw new Error("access_token must be a non-empty string");
+  }
+
+  try {
+    const response = await axios.post("https://www.donationalerts.com/api/v1/centrifuge/subscribe",
+      {
+        channels: [channel],
+        client: client
+      },
+      {
+        headers: {
+          Authorization: `Bearer ${access_token}`,
+          "Content-Type": "application/json"
+        }
+      }
+    );
+
+    if (!response.data?.channels?.[0]?.token) {
+      throw new Error("Failed to get private token: no channels in response");
+    }
+    return response.data.channels[0].token;
+  } catch (error: any) {
+    throw new Error(formatAxiosError(error));
+  }
+} 

package/src/Function/getUser.ts

@@ -0,0 +1,32 @@
+import axios from "axios";
+import { User } from "@type";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Fetch user profile information by OAuth token.
+ * 
+ * @param {string} access_token - User access token
+ * 
+ * @returns {Promise<User>} User data
+ * @see {@link https://www.donationalerts.com/apidoc#api_v1__users__user_profile_information}
+ */
+
+export default async function getUser(
+    access_token: string
+): Promise<User> {
+    if (!access_token || typeof access_token !== "string") {
+        throw new Error("access_token must be a non-empty string");
+    }
+
+    try {
+        const response = await axios.get<{ data: User }>("https://www.donationalerts.com/api/v1/user/oauth", {
+            headers: {
+                Authorization: `Bearer ${access_token}`
+            }
+        });
+
+        return response.data.data;
+    } catch (error: any) {
+        throw new Error(formatAxiosError(error));
+    }
+} 

package/src/Function/getUserChannel.ts

@@ -0,0 +1,17 @@
+/**
+ * Get user channel by user id for WebSocket.
+ * 
+ * @param {string | number} id - User ID
+ * 
+ * @returns {string} The donation alert channel identifier in the format "$alerts:donation_{id}".
+ */
+
+export default function getUserChannel(
+    id: string | number
+): string {
+    if (id === null || id === undefined || id === "") {
+        throw new Error("id must be a non-empty string or number");
+    }
+
+    return `$alerts:donation_${id}`;
+} 

package/src/Function/getUserDataFromPromocode.ts

@@ -0,0 +1,51 @@
+import axios from "axios";
+import generateSignature from "@function/generateSignature.js";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Get user ID from an advertising promocode.
+ *
+ * @param {string} access_token - User access token
+ * @param {string} client_secret - API client secret key for signature
+ * @param {string} promocode - User promocode
+ *
+ * @returns {Promise<number>} DonationAlerts user ID
+ * @see {@link https://www.donationalerts.com/apidoc#api_v1__merchandises__update_or_create_merchandise__get_user_data_from_promocode}
+ */
+
+export default async function getUserDataFromPromocode(
+    access_token: string,
+    client_secret: string,
+    promocode: string
+): Promise<number> {
+    if (!access_token || typeof access_token !== "string") {
+        throw new Error("access_token must be a non-empty string");
+    }
+    if (!client_secret || typeof client_secret !== "string") {
+        throw new Error("client_secret must be a non-empty string");
+    }
+    if (!promocode || typeof promocode !== "string") {
+        throw new Error("promocode must be a non-empty string");
+    }
+
+    try {
+        const params: Record<string, string | number> = { promocode };
+
+        const signature = generateSignature(params, client_secret);
+        params.signature = signature;
+
+        const response = await axios.get<{ data: { user_id: number } }>(
+            "https://www.donationalerts.com/api/v1/merchandise/user",
+            {
+                params,
+                headers: {
+                    Authorization: `Bearer ${access_token}`
+                }
+            }
+        );
+
+        return response.data.data.user_id;
+    } catch (error: any) {
+        throw new Error(formatAxiosError(error));
+    }
+}

package/src/Function/sendSaleAlert.ts

@@ -0,0 +1,103 @@
+import axios from "axios";
+import { MerchandiseSale } from "@type";
+import generateSignature from "@function/generateSignature.js";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Send a merchandise sale alert.
+ *
+ * @param {string} access_token - User access token
+ * @param {string} client_secret - API client secret key for signature
+ * @param {number} user_id - DonationAlerts user ID to which the sale is referenced
+ * @param {string} external_id - Up to 32 characters long unique sale ID
+ * @param {string} merchant_identifier - Merchant's ID on DonationAlerts
+ * @param {string} merchandise_identifier - Merchant's merchandise ID that was bought
+ * @param {number} amount - Grand total of the sale
+ * @param {string} currency - Currency code (EUR, USD, RUB, BRL, TRY)
+ * @param {number} [bought_amount=1] - Total number of bought items
+ * @param {string} [username] - Name of the customer
+ * @param {string} [message] - Message sent by the customer
+ *
+ * @returns {Promise<MerchandiseSale>} Created merchandise sale alert data
+ * @see {@link https://www.donationalerts.com/apidoc#api_v1__merchandise_sale_notifications__send_sale_alerts}
+ */
+
+export default async function sendSaleAlert(
+    access_token: string,
+    client_secret: string,
+    user_id: number,
+    external_id: string,
+    merchant_identifier: string,
+    merchandise_identifier: string,
+    amount: number,
+    currency: string,
+    bought_amount: number = 1,
+    username?: string,
+    message?: string
+): Promise<MerchandiseSale> {
+    if (!access_token || typeof access_token !== "string") {
+        throw new Error("access_token must be a non-empty string");
+    }
+    if (!client_secret || typeof client_secret !== "string") {
+        throw new Error("client_secret must be a non-empty string");
+    }
+    if (typeof user_id !== "number" || user_id <= 0) {
+        throw new Error("user_id must be a positive number");
+    }
+    if (!external_id || typeof external_id !== "string") {
+        throw new Error("external_id must be a non-empty string");
+    }
+    if (!merchant_identifier || typeof merchant_identifier !== "string") {
+        throw new Error("merchant_identifier must be a non-empty string");
+    }
+    if (!merchandise_identifier || typeof merchandise_identifier !== "string") {
+        throw new Error("merchandise_identifier must be a non-empty string");
+    }
+    if (typeof amount !== "number" || amount <= 0) {
+        throw new Error("amount must be a positive number");
+    }
+    if (!currency || typeof currency !== "string") {
+        throw new Error("currency must be a non-empty string");
+    }
+    if (typeof bought_amount !== "number" || bought_amount <= 0) {
+        throw new Error("bought_amount must be a positive number");
+    }
+
+    try {
+        const params: Record<string, string | number> = {
+            user_id,
+            external_id,
+            merchant_identifier,
+            merchandise_identifier,
+            amount,
+            currency,
+            bought_amount
+        };
+
+        if (username) params.username = username;
+        if (message) params.message = message;
+
+        const signature = generateSignature(params, client_secret);
+        params.signature = signature;
+
+        const formData = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            formData.append(key, String(value));
+        }
+
+        const response = await axios.post<{ data: MerchandiseSale }>(
+            "https://www.donationalerts.com/api/v1/merchandise_sale",
+            formData,
+            {
+                headers: {
+                    Authorization: `Bearer ${access_token}`,
+                    "Content-Type": "application/x-www-form-urlencoded"
+                }
+            }
+        );
+
+        return response.data.data;
+    } catch (error: any) {
+        throw new Error(formatAxiosError(error));
+    }
+}