@donation-alerts/api/cjs/api/customAlerts/donation-alerts-custom-alerts-api.js

Interact with Donation Alerts API.

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.DonationAlertsCustomAlertsApi = void 0;
const tslib_1 = require("tslib");
const common_1 = require("@donation-alerts/common");
const donation_alerts_custom_alert_1 = require("./donation-alerts-custom-alert");
const base_api_1 = require("../base-api");
/**
 * API for managing Donation Alerts custom alerts.
 *
 * Custom alerts allow developers to create fully customizable notifications that broadcast to a streamer's audience.
 * These alerts can include custom headers, messages, images, and sounds for a tailored viewer experience.
 *
 * @remarks
 * **Important:** For the custom alert to display, the streamer must configure a variation in the Alerts widget
 * with the "Custom alerts" type.
 */
let DonationAlertsCustomAlertsApi = class DonationAlertsCustomAlertsApi extends base_api_1.BaseApi {
    /**
     * Sends a custom alert to the authorized streamer.
     *
     * This method sends a custom-designed alert to the specified user (streamer). The customizable fields
     * include the header, message, image, and sound. To display in the streamer's widget, the alert type
     * must be configured as "Custom alerts" in their settings.
     *
     * @remarks
     * Requires the `oauth-custom_alert-store` scope.
     *
     * @param user The ID of the user to send the custom alert to.
     * @param data The data object containing properties for the custom alert, such as header, message, or sound URL.
     * @param rateLimiterOptions Optional rate limiting configuration.
     *
     * @returns An instance of the newly created {@link DonationAlertsCustomAlert}.
     *
     * @throws {@link HttpError} if the HTTP status code is outside the range of 200–299.
     * @throws {@link UnregisteredUserError} if the specified user is not registered in the authentication provider.
     * @throws {@link MissingScopeError} if the access token lacks the necessary `oauth-custom_alert-store` scope.
     *
     * @example
     * ```ts
     * const customAlert = await customAlertsApi.sendCustomAlert(userId, {
     *   externalId: 'unique-alert-id',
     *   header: 'Custom Title!',
     *   message: 'Custom message.',
     *   shouldShow: true, // Will be displayed
     *   imageUrl: 'https://example.com/image.jpg',
     *   soundUrl: 'https://example.com/sound.mp3'
     * });
     *
     * console.log(`Custom alert sent! Header: ${customAlert.header}; Message: ${customAlert.message}`);
     * ```
     */
    async sendCustomAlert(user, data, rateLimiterOptions) {
        const response = await this._apiClient.callApi(user, {
            type: 'api',
            url: 'custom_alert',
            method: 'POST',
            scope: 'oauth-custom_alert-store',
            formBody: {
                external_id: data.externalId,
                header: data.header,
                message: data.message,
                is_shown: (data.shouldShow ?? true) ? '0' : '1',
                image_url: data.imageUrl,
                sound_url: data.soundUrl,
            },
            auth: true,
        }, rateLimiterOptions);
        return new donation_alerts_custom_alert_1.DonationAlertsCustomAlert(response.data);
    }
};
exports.DonationAlertsCustomAlertsApi = DonationAlertsCustomAlertsApi;
exports.DonationAlertsCustomAlertsApi = DonationAlertsCustomAlertsApi = tslib_1.__decorate([
    (0, common_1.ReadDocumentation)('api')
], DonationAlertsCustomAlertsApi);