@donation-alerts/api/cjs/api/centrifugo/donation-alerts-centrifugo-api.d.ts

Interact with Donation Alerts API.

import { type RateLimiterRequestOptions } from '@d-fischer/rate-limiter';
import { type CentrifugoChannel, type UserIdResolvable } from '@donation-alerts/common';
import { DonationAlertsCentrifugoChannel } from './donation-alerts-centrifugo-channel';
import { BaseApi } from '../base-api';
/**
 * Additional subscribe options.
 */
export interface DonationAlertsCentrifugoSubscribeOptions {
    /**
     * Merges channel name and user ID to form valid channel name.
     *
     * @defaultValue `true`
     */
    transformChannel?: boolean;
}
/**
 * Donation Alerts Centrifugo API.
 *
 * Provides methods to manage user subscriptions to Centrifugo private channels.
 * These channels allow receiving real-time updates about specific events such as donations, goals, and polls.
 */
export declare class DonationAlertsCentrifugoApi extends BaseApi {
    /**
     * Subscribes a user to the specified Centrifugo private channels.
     *
     * @remarks
     * To subscribe a user, you must first obtain the Client ID (UUIDv4) via WebSockets.
     *
     * The full subscription flow is described in the official documentation:
     * {@link https://www.donationalerts.com/apidoc#introduction__centrifugo}
     *
     * Alternatively, the `@donation-alerts/events` library can simplify the process of subscribing
     * and listening to events.
     *
     * @param user The Donation Alerts user ID.
     * @param clientId The Client ID obtained beforehand.
     * @param channels List of private channel names to subscribe the user to. Channel names should not include the
     * user ID – the library will format them automatically if needed.
     * @param options Additional options for subscription, such as formatting channel names.
     * @param rateLimiterOptions Options for controlling the request rate using a rate limiter.
     *
     * @returns A promise resolving with a list of {@link DonationAlertsCentrifugoChannel}.
     *
     * @throws {@link HttpError} If the HTTP status code is outside the range of 200–299.
     * @throws {@link UnregisteredUserError} If the user provided is not registered in the auth provider.
     *
     * @example
     * ```ts
     * const subscribedChannels = await apiClient.centrifugo.subscribeUserToPrivateChannels(userId, clientId, [
     *   '$alerts:donation',
     *   '$goals:goal'
     * ]);
     * subscribedChannels.forEach(channel =>
     *   console.log(`Subscribed to ${channel.channel}; token: ${channel.token}`)
     * );
     * ```
     */
    subscribeUserToPrivateChannels(user: UserIdResolvable, clientId: string, channels: Array<CentrifugoChannel | string>, options?: DonationAlertsCentrifugoSubscribeOptions, rateLimiterOptions?: RateLimiterRequestOptions): Promise<DonationAlertsCentrifugoChannel[]>;
    /**
     * Subscribes a user to donation alert events.
     *
     * Donation alert events notify when a new donation is made. This requires the user to be subscribed
     * to the `$alerts:donation` private channel.
     *
     * @remarks
     * Requires `oauth-donation-subscribe` scope.
     *
     * See the official documentation for more details:
     * {@link https://www.donationalerts.com/apidoc#introduction__centrifugo}
     *
     * Alternatively, the `@donation-alerts/events` library can simplify the process of subscribing
     * and listening to events.
     *
     * @param user The Donation Alerts user ID.
     * @param clientId The Client ID obtained beforehand.
     * @param options Additional options for subscription, such as formatting channel names.
     * @param rateLimiterOptions Options for rate limiting during the subscription.
     *
     * @returns A promise resolving with the {@link DonationAlertsCentrifugoChannel} object.
     *
     * @throws {@link HttpError} If the HTTP status code is outside the range of 200–299.
     * @throws {@link UnregisteredUserError} If the user provided is not registered in the auth provider.
     *
     * @example
     * ```ts
     * const channel = await apiClient.centrifugo.subscribeUserToDonationAlertEvents(userId, clientId);
     * console.log(`Subscribed to channel: ${channel.channel}; token: ${channel.token}`);
     * ```
     */
    subscribeUserToDonationAlertEvents(user: UserIdResolvable, clientId: string, options?: DonationAlertsCentrifugoSubscribeOptions, rateLimiterOptions?: RateLimiterRequestOptions): Promise<DonationAlertsCentrifugoChannel>;
    /**
     * Subscribes a user to goal update events.
     *
     * Goal update events provide information about the progress and completion of goals.
     * This requires the user to be subscribed to the `$goals:goal` private channel.
     *
     * @remarks
     * Requires `oauth-goal-subscribe` scope.
     *
     * See the official documentation for more details:
     * {@link https://www.donationalerts.com/apidoc#introduction__centrifugo}
     *
     * Alternatively, the `@donation-alerts/events` library can simplify the process of subscribing
     * and listening to events.
     *
     * @param user The Donation Alerts user ID.
     * @param clientId The Client ID obtained beforehand.
     * @param options Additional options for subscription, such as formatting channel names.
     * @param rateLimiterOptions Options for rate limiting during the subscription.
     *
     * @returns A promise resolving with the successfully subscribed channel object.
     *
     * @throws {@link HttpError} If the HTTP status code is outside the range of 200–299.
     * @throws {@link UnregisteredUserError} If the user provided is not registered in the auth.
     *
     * @example
     * ```ts
     * const channel = await apiClient.centrifugo.subscribeUserToGoalUpdateEvents(userId, clientId);
     * console.log(`Subscribed to channel: ${channel.channel}; token: ${channel.token}`);
     * ```
     */
    subscribeUserToGoalUpdateEvents(user: UserIdResolvable, clientId: string, options?: DonationAlertsCentrifugoSubscribeOptions, rateLimiterOptions?: RateLimiterRequestOptions): Promise<DonationAlertsCentrifugoChannel>;
    /**
     * Subscribes a user to poll update events.
     *
     * Poll update events notify about ongoing poll progress or results.
     * This requires the user to be subscribed to the `$polls:poll` private channel.
     *
     * @remarks
     * Requires `oauth-poll-subscribe` scope.
     *
     * See the official documentation for more details:
     * {@link https://www.donationalerts.com/apidoc#introduction__centrifugo}
     *
     * Alternatively, the `@donation-alerts/events` library can simplify the process of subscribing
     * and listening to events.
     *
     * @param user The Donation Alerts user ID.
     * @param clientId The Client ID obtained beforehand.
     * @param options Additional options for subscription, such as formatting channel names.
     * @param rateLimiterOptions Options for rate limiting during the subscription.
     *
     * @returns A promise resolving with the successfully subscribed channel object.
     *
     * @throws {@link HttpError} If the HTTP status code is outside the range of 200–299.
     * @throws {@link UnregisteredUserError} If the user provided is not registered in the auth provider.
     *
     * @example
     * ```ts
     * const channel = await apiClient.centrifugo.subscribeUserToPollUpdateEvents(userId, clientId);
     * console.log(`Subscribed to channel: ${channel.channel}; token: ${channel.token}`);
     * ```
     */
    subscribeUserToPollUpdateEvents(user: UserIdResolvable, clientId: string, options?: DonationAlertsCentrifugoSubscribeOptions, rateLimiterOptions?: RateLimiterRequestOptions): Promise<DonationAlertsCentrifugoChannel>;
    private _genericSubscribeToMultiplePrivateChannels;
    private _genericSubscribeToPrivateChannel;
}
//# sourceMappingURL=donation-alerts-centrifugo-api.d.ts.map