@kash-88/alerts 1.2.1 → 1.3.0

package/src/Function/updateMerchandise.ts

@@ -0,0 +1,98 @@
+import axios from "axios";
+import { Merchandise } from "@type";
+import generateSignature from "@function/generateSignature.js";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Update an existing merchandise by its DonationAlerts ID.
+ *
+ * @param {string} access_token - User access token
+ * @param {string} client_secret - API client secret key for signature
+ * @param {number} merchandise_id - Unique merchandise ID on DonationAlerts
+ * @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>} Updated merchandise data
+ * @see {@link https://www.donationalerts.com/apidoc#api_v1__merchandises__update_merchandise}
+ */
+
+export default async function updateMerchandise(
+    access_token: string,
+    client_secret: string,
+    merchandise_id: number,
+    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 (typeof merchandise_id !== "number" || merchandise_id <= 0) {
+        throw new Error("merchandise_id must be a positive number");
+    }
+    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> = {
+            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.put<{ data: Merchandise }>(
+            `https://www.donationalerts.com/api/v1/merchandise/${merchandise_id}`,
+            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/updateOauthToken.ts

@@ -0,0 +1,54 @@
+import axios from "axios";
+import { OAuthToken, OAuthScope } from "@type";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Refresh Access token using Refresh token.
+ * 
+ * @param {string} client_id - Your client (application) ID
+ * @param {string} client_secret - Your client (application) secret
+ * @param {string} refresh_token - User refresh token
+ * @param {OAuthScope[]} scopes - Array of access scopes
+ * 
+ * @returns {Promise<OAuthToken>} A promise that resolves to the new token data from the API.
+ * @see {@link https://www.donationalerts.com/apidoc#authorization__authorization_code__getting_access_token}
+ */
+
+export default async function updateOauthToken(
+    client_id: string,
+    client_secret: string,
+    refresh_token: string,
+    scopes: OAuthScope[]
+): 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 (!refresh_token || typeof refresh_token !== "string") {
+        throw new Error("refresh_token must be a non-empty string");
+    }
+    if (!Array.isArray(scopes) || scopes.length === 0) {
+        throw new Error("scopes must be a non-empty array");
+    }
+
+    try {
+        const formData = new URLSearchParams();
+        formData.append("grant_type", "refresh_token");
+        formData.append("refresh_token", refresh_token);
+        formData.append("client_id", client_id);
+        formData.append("client_secret", client_secret);
+        formData.append("scope", Array.from(new Set(scopes)).join(" "));
+
+        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/updateOrCreateMerchandise.ts

@@ -0,0 +1,103 @@
+import axios from "axios";
+import { Merchandise } from "@type";
+import generateSignature from "@function/generateSignature.js";
+import { formatAxiosError } from "@utils";
+
+/**
+ * Update or create a merchandise by merchant and merchandise identifiers.
+ *
+ * @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>} Updated or created merchandise data
+ * @see {@link https://www.donationalerts.com/apidoc#api_v1__merchandises__update_or_create_merchandise}
+ */
+
+export default async function updateOrCreateMerchandise(
+    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> = {
+            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.put<{ data: Merchandise }>(
+            `https://www.donationalerts.com/api/v1/merchandise/${merchant_identifier}/${merchandise_identifier}`,
+            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/Types/CustomAlerts.ts

@@ -0,0 +1,13 @@
+interface CustomAlerts {
+    id: number;
+    external_id: string | null;
+    header: string | null;
+    message: string | null;
+    image_url: string | null;
+    sound_url: string | null;
+    is_shown: 0 | 1;
+    created_at: string;
+    shown_at: string | null;
+}
+
+export default CustomAlerts;

package/src/Types/DonationsAlerts.ts

@@ -0,0 +1,32 @@
+interface DonationsAlerts {
+    data: {
+        id: number;
+        name: string;
+        username: string;
+        message: string;
+        message_type: string;
+        amount: number;
+        currency: string;
+        is_shown: number;
+        created_at: string;
+        shown_at: string | null;
+        amount_in_user_currency?: number;
+    }[];
+    links: {
+        first: string;
+        last: string;
+        prev: string | null;
+        next: string | null;
+    };
+    meta: {
+        current_page: number;
+        from: number;
+        last_page: number;
+        path: string;
+        per_page: number;
+        to: number;
+        total: number;
+    }
+}
+
+export default DonationsAlerts;

package/src/Types/Merchandise.ts

@@ -0,0 +1,19 @@
+interface Merchandise {
+    id: number;
+    merchant: {
+        identifier: string;
+        name: string;
+    };
+    identifier: string;
+    title: Record<string, string>;
+    is_active: 0 | 1;
+    is_percentage: 0 | 1;
+    currency: string;
+    price_user: number;
+    price_service: number;
+    url: string | null;
+    img_url: string | null;
+    end_at: string | null;
+}
+
+export default Merchandise;

package/src/Types/MerchandiseSale.ts

@@ -0,0 +1,15 @@
+interface MerchandiseSale {
+    id: number;
+    name: string;
+    external_id: string;
+    username: string | null;
+    message: string | null;
+    amount: number;
+    currency: string;
+    bought_amount: number;
+    is_shown: number;
+    created_at: string;
+    shown_at: string | null;
+}
+
+export default MerchandiseSale;

package/src/Types/OAuthScope.ts

@@ -0,0 +1,10 @@
+enum OAuthScope {
+    UserShow = "oauth-user-show",
+    DonationSubscribe = "oauth-donation-subscribe",
+    DonationIndex = "oauth-donation-index",
+    CustomAlertStore = "oauth-custom_alert-store",
+    GoalSubscribe = "oauth-goal-subscribe",
+    PollSubscribe = "oauth-poll-subscribe"
+}
+
+export default OAuthScope;

package/src/Types/OAuthToken.ts

@@ -0,0 +1,8 @@
+interface OAuthToken {
+    token_type: string;
+    expires_in: number;
+    access_token: string;
+    refresh_token?: string;
+}
+
+export default OAuthToken;

package/src/Types/User.ts

@@ -0,0 +1,10 @@
+interface User {
+    id: number;
+    code: string;
+    name: string;
+    avatar: string;
+    email: string;
+    socket_connection_token: string;
+}
+
+export default User;

package/src/Types/index.ts

@@ -0,0 +1,17 @@
+import CustomAlerts from "./CustomAlerts.js";
+import DonationsAlerts from "./DonationsAlerts.js";
+import Merchandise from "./Merchandise.js";
+import MerchandiseSale from "./MerchandiseSale.js";
+import OAuthScope from "./OAuthScope.js";
+import OAuthToken from "./OAuthToken.js";
+import User from "./User.js";
+
+export {
+    CustomAlerts,
+    DonationsAlerts,
+    Merchandise,
+    MerchandiseSale,
+    OAuthScope,
+    OAuthToken,
+    User
+};

package/src/WebSocket/CentrifugeClient.ts

@@ -0,0 +1,271 @@
+import getPrivateToken from "@function/getPrivateToken.js";
+import getUser from "@function/getUser.js";
+import getUserChannel from "@function/getUserChannel.js";
+import { User } from "@type";
+import { formatAxiosError } from "@utils";
+import { WebSocket, RawData } from "ws";
+import { EventEmitter } from "events";
+import TypedEmitter from "typed-emitter";
+
+interface WSClientOptions {
+    access_token: string;
+    channels?: string[];
+    autoReconnect?: boolean;
+}
+
+type MessageEvents = {
+    open: () => void;
+    message: (data: any) => void;
+    close: (code: number, reason: Buffer) => void;
+    error: (error: Error) => void;
+    reconnect: () => void;
+}
+
+/**
+ * Class for interacting with Centrifuge donationalerts
+ *
+ * @param {WSClientOptions} options - Connection options
+ * @param {string} options.access_token - User access token
+ * @param {string[]} [options.channels] - Custom channels to subscribe to (defaults to donation channel)
+ * @param {boolean} [options.autoReconnect=false] - Automatically reconnect on connection close
+ */
+
+export default class CentrifugeClient extends (EventEmitter as new () => TypedEmitter<MessageEvents>) {
+    private WebSocket: WebSocket | null;
+    private user: User | null;
+    private userPromise: Promise<User> | null;
+    private access_token: string;
+    private channels: string[];
+    private autoReconnect: boolean;
+    private isAuthorized: boolean;
+    private reconnectTimer: NodeJS.Timeout | null;
+    private isReconnecting: boolean;
+    private authMessageHandler: ((rawMessage: RawData) => void) | null;
+
+    constructor(options: WSClientOptions) {
+        super();
+        this.access_token = options.access_token;
+        this.channels = options.channels ?? [];
+        this.autoReconnect = options.autoReconnect ?? false;
+        this.isAuthorized = false;
+        this.reconnectTimer = null;
+        this.isReconnecting = false;
+        this.authMessageHandler = null;
+
+        this.WebSocket = null;
+        this.user = null;
+        this.userPromise = this.getUser(this.access_token).catch((error) => {
+            this.emit("error", error);
+            throw error;
+        });
+
+        this.createNewConnection();
+        this.setupEvent();
+    }
+
+    /**
+     * Obtain user data
+     *
+     * @param {string} access_token - User access token
+     * @returns {Promise<User>} User data
+     */
+
+    private async getUser(
+        access_token: string
+    ): Promise<User> {
+        try {
+            this.user = await getUser(access_token);
+            return this.user;
+        } catch (error: any) {
+            throw new Error(formatAxiosError(error));
+        }
+    }
+
+    /**
+     * Get channels to subscribe to
+     *
+     * @returns {Promise<string[]>} Array of channel identifiers
+     */
+
+    private async getChannels(): Promise<string[]> {
+        if (!this.user?.id) this.user = await (this.userPromise ?? this.getUser(this.access_token));
+        if (!this.user?.id) throw new Error("Failed to get channels due to missing user ID");
+
+        if (this.channels.length > 0) return this.channels;
+
+        return [getUserChannel(this.user.id)];
+    }
+
+    /**
+     * Create a new WebSocket connection
+     */
+
+    public createNewConnection() {
+        try {
+            if (this.WebSocket) return;
+            this.WebSocket = new WebSocket("wss://centrifugo.donationalerts.com/connection/websocket");
+        } catch (error: any) {
+            throw new Error(error?.message || error);
+        }
+    }
+
+    /**
+     * Forward events through a TypedEmitter
+     */
+
+    private setupEvent() {
+        if (!this.WebSocket) {
+            this.createNewConnection();
+            if (!this.WebSocket) throw new Error("WebSocket connection failed");
+        }
+
+        const ws = this.WebSocket;
+
+        ws.on('open', () => {
+            this.emit("open");
+        });
+
+        ws.on('close', (code: number, reason: Buffer) => {
+            this.isAuthorized = false;
+            this.emit("close", code, reason);
+
+            if (this.autoReconnect) {
+                this.WebSocket = null;
+                if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+                this.isReconnecting = true;
+                this.reconnectTimer = setTimeout(() => {
+                    this.isReconnecting = false;
+                    this.createNewConnection();
+                    this.setupEvent();
+                    this.emit("reconnect");
+                }, 5000);
+            }
+        });
+
+        ws.on('message', (rawMessage: RawData) => {
+            try {
+                const message = JSON.parse(rawMessage.toString());
+                this.emit("message", message);
+            } catch (error: any) {
+                this.emit("error", new Error(`Failed to parse WebSocket message: ${error?.message || error}`));
+            }
+        });
+
+        ws.on('error', (error: Error) => {
+            this.emit("error", error);
+        });
+    }
+
+    /**
+     * Authorize WebSocket and subscribe to selected channels
+     */
+
+    public async authorization() {
+        if (this.isReconnecting) {
+            throw new Error("Reconnection is in progress, please wait for the 'reconnect' event");
+        }
+
+        if (!this.WebSocket) this.createNewConnection();
+        if (!this.WebSocket) throw new Error("WebSocket connection failed");
+
+        if (this.WebSocket.readyState !== WebSocket.OPEN) {
+            throw new Error("WebSocket connection is not open. Call authorization() after the 'open' event");
+        }
+
+        if (!this.user) this.user = await (this.userPromise ?? this.getUser(this.access_token));
+        if (!this.user?.socket_connection_token) throw new Error("Failed to log in due to receiving socket connection token");
+
+        if (this.authMessageHandler) {
+            this.WebSocket?.removeListener('message', this.authMessageHandler);
+        }
+
+        const handleAuthResponse = async (rawMessage: RawData) => {
+            try {
+                const json = JSON.parse(rawMessage.toString());
+
+                if (json.id === 1) {
+                    this.authMessageHandler = null;
+                    this.WebSocket?.removeListener('message', handleAuthResponse);
+
+                    if (!json.result?.client) {
+                        this.emit("error", new Error("Authorization failed: missing client ID in response"));
+                        return;
+                    }
+
+                    const channels = await this.getChannels();
+
+                    for (let i = 0; i < channels.length; i++) {
+                        const channel = channels[i];
+                        const privateToken = await getPrivateToken(
+                            channel,
+                            json.result.client,
+                            this.access_token
+                        );
+
+                        this.sendMessage(JSON.stringify({
+                            id: 2 + i,
+                            method: 1,
+                            params: {
+                                channel,
+                                token: privateToken
+                            }
+                        }));
+                    }
+
+                    this.isAuthorized = true;
+                }
+            } catch (error: any) {
+                this.authMessageHandler = null;
+                this.WebSocket?.removeListener('message', handleAuthResponse);
+                this.emit("error", new Error(`Authorization failed: ${error?.message || error}`));
+            }
+        };
+
+        this.authMessageHandler = handleAuthResponse;
+        this.WebSocket.on('message', handleAuthResponse);
+
+        this.sendMessage(JSON.stringify({
+            params: {
+                token: this.user.socket_connection_token
+            },
+            id: 1
+        }));
+    }
+
+    /**
+     * Send a message through the WebSocket connection
+     *
+     * @param {string} message - JSON-encoded message to send
+     */
+
+    public sendMessage(message: string): void {
+        try {
+            if (!this.WebSocket) return;
+            if (this.WebSocket.readyState !== WebSocket.OPEN) return;
+            this.WebSocket.send(message);
+        } catch (error: any) {
+            throw new Error(error?.message || error);
+        }
+    }
+
+    /**
+     * Close the WebSocket connection and stop auto-reconnect
+     */
+
+    public close(): void {
+        this.autoReconnect = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.WebSocket) {
+            if (this.authMessageHandler) {
+                this.WebSocket.removeListener('message', this.authMessageHandler);
+                this.authMessageHandler = null;
+            }
+            this.WebSocket.close();
+            this.WebSocket = null;
+        }
+        this.isAuthorized = false;
+    }
+}