@donation-alerts/api
Version:
Interact with Donation Alerts API.
192 lines (191 loc) • 9.29 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
exports.DonationAlertsCentrifugoApi = void 0;
const tslib_1 = require("tslib");
const common_1 = require("@donation-alerts/common");
const donation_alerts_centrifugo_channel_1 = require("./donation-alerts-centrifugo-channel");
const base_api_1 = require("../base-api");
/**
* 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.
*/
let DonationAlertsCentrifugoApi = class DonationAlertsCentrifugoApi extends base_api_1.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}`)
* );
* ```
*/
async subscribeUserToPrivateChannels(user, clientId, channels, options, rateLimiterOptions) {
return await this._genericSubscribeToMultiplePrivateChannels(user, clientId, channels, options, rateLimiterOptions);
}
/**
* 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}`);
* ```
*/
async subscribeUserToDonationAlertEvents(user, clientId, options, rateLimiterOptions) {
return await this._genericSubscribeToPrivateChannel(user, clientId, '$alerts:donation', 'oauth-donation-subscribe', options, rateLimiterOptions);
}
/**
* 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}`);
* ```
*/
async subscribeUserToGoalUpdateEvents(user, clientId, options, rateLimiterOptions) {
return await this._genericSubscribeToPrivateChannel(user, clientId, '$goals:goal', 'oauth-goal-subscribe', options, rateLimiterOptions);
}
/**
* 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}`);
* ```
*/
async subscribeUserToPollUpdateEvents(user, clientId, options, rateLimiterOptions) {
return await this._genericSubscribeToPrivateChannel(user, clientId, '$polls:poll', 'oauth-poll-subscribe', options, rateLimiterOptions);
}
async _genericSubscribeToMultiplePrivateChannels(user, clientId, channels, options, rateLimiterOptions) {
const response = await this._apiClient.callApi(user, {
type: 'api',
url: 'centrifuge/subscribe',
method: 'POST',
jsonBody: {
client: clientId,
channels: (options?.transformChannel ?? true)
? channels.map(channel => `${channel}_${(0, common_1.extractUserId)(user)}`)
: channels,
},
}, rateLimiterOptions);
return response.channels.map(channel => new donation_alerts_centrifugo_channel_1.DonationAlertsCentrifugoChannel(channel));
}
async _genericSubscribeToPrivateChannel(user, clientId, channel, scope, options, rateLimiterOptions) {
const response = await this._apiClient.callApi(user, {
type: 'api',
url: 'centrifuge/subscribe',
method: 'POST',
scope: scope,
jsonBody: {
client: clientId,
channels: [
`${(options?.transformChannel ?? true) ? `${channel}_${(0, common_1.extractUserId)(user)}` : channel}`,
],
},
}, rateLimiterOptions);
if (response.channels.length === 0) {
throw new Error(`Could not subscribe to the private channel: ${channel}`);
}
return new donation_alerts_centrifugo_channel_1.DonationAlertsCentrifugoChannel(response.channels[0]);
}
};
exports.DonationAlertsCentrifugoApi = DonationAlertsCentrifugoApi;
exports.DonationAlertsCentrifugoApi = DonationAlertsCentrifugoApi = tslib_1.__decorate([
(0, common_1.ReadDocumentation)('api')
], DonationAlertsCentrifugoApi);