@donation-alerts/api/cjs/api/customAlerts/donation-alerts-custom-alerts-api.d.ts

Interact with Donation Alerts API.

import { type RateLimiterRequestOptions } from '@d-fischer/rate-limiter';
import { type UserIdResolvable } from '@donation-alerts/common';
import { DonationAlertsCustomAlert } from './donation-alerts-custom-alert';
import { BaseApi } from '../base-api';
/**
 * Data structure for sending a custom alert to Donation Alerts.
 */
export interface DonationAlertsSendCustomAlertData {
    /**
     * A unique alert ID generated by the application developer (maximum length: 32 characters).
     */
    externalId?: string;
    /**
     * A header text to display in the custom alert (maximum length: 255 characters).
     */
    header?: string;
    /**
     * A message text to display in the custom alert (maximum length: 300 characters).
     */
    message?: string;
    /**
     * Determines whether the alert should be displayed immediately.
     *
     * @defaultValue `true`
     *
     * @remarks
     * If set to `false`, the alert will not be shown.
     */
    shouldShow?: boolean;
    /**
     * A URL to an image that will be included in the alert (maximum length: 255 characters).
     */
    imageUrl?: string;
    /**
     * A URL to a sound file that will play when the custom alert is displayed (maximum length: 255 characters).
     */
    soundUrl?: string;
}
/**
 * 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.
 */
export declare class DonationAlertsCustomAlertsApi extends 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}`);
     * ```
     */
    sendCustomAlert(user: UserIdResolvable, data: DonationAlertsSendCustomAlertData, rateLimiterOptions?: RateLimiterRequestOptions): Promise<DonationAlertsCustomAlert>;
}
//# sourceMappingURL=donation-alerts-custom-alerts-api.d.ts.map