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

Interact with Donation Alerts API.

import { type QueueEntryLimitReachedBehavior, type RateLimiterRequestOptions } from '@d-fischer/rate-limiter';
import { type DonationAlertsApiCallOptions, type DonationAlertsCallFetchOptions } from '@donation-alerts/api-call';
import { type AuthProvider } from '@donation-alerts/auth';
import { type UserIdResolvable } from '@donation-alerts/common';
import { type LoggerOptions } from '@stimulcross/logger';
import { DonationAlertsCentrifugoApi } from './api/centrifugo/donation-alerts-centrifugo-api';
import { DonationAlertsCustomAlertsApi } from './api/customAlerts/donation-alerts-custom-alerts-api';
import { DonationAlertsDonationsApi } from './api/donations/donation-alerts-donations-api';
import { DonationAlertsMerchandiseApi } from './api/merchandise/donation-alerts-merchandise-api';
import { DonationAlertsUsersApi } from './api/users/donation-alerts-users-api';
/**
 * Configuration options for the rate limiter.
 */
export interface RateLimiterOptions {
    /**
     * Whether to limit the number of requests to 1 per second.
     *
     * @remarks
     * According to the official documentation, the Donation Alerts API allows up to 60 requests per minute per
     * application, which translates to 1 request per second.
     *
     * By default, the library enforces this rate limit, ensuring that requests are executed sequentially at 1 request
     * per second. For example, if you initiate 60 simultaneous requests, they will be queued and executed one by one.
     *
     * If set to `false`, you can exceed the limit in a short period (e.g., 10 seconds), but subsequent requests
     * will fail for the remaining duration of the 60-second window due to the API's rate limit.
     *
     * Requests exceeding the limit are enqueued and executed later by default. You can customize this behavior
     * using the {@link RateLimiterOptions#limitReachedBehavior} property.
     *
     * @defaultValue `true`
     */
    limitToOneRequestPerSecond?: boolean;
    /**
     * Behavior to apply when the rate limit is reached.
     *
     * @remarks
     * Specifies what happens if the number of requests exceeds the rate limit. The available options are:
     * - `enqueue` - Adds the request to a queue to be executed when possible.
     * - `throw` - Throws a `RateLimitReachedError` when the limit is exceeded.
     * - `null` - Returns `null` instead of executing the request.
     *
     * @defaultValue `enqueue`
     */
    limitReachedBehavior?: QueueEntryLimitReachedBehavior;
}
/**
 * Configuration options for creating an {@link ApiClient}.
 */
export interface ApiConfig {
    /**
     * The authentication provider responsible for supplying access tokens to the client.
     *
     * @remarks
     * The client uses this provider to authorize requests to the Donation Alerts API.
     * For more details, refer to the {@link AuthProvider} documentation.
     */
    authProvider: AuthProvider;
    /**
     * Custom options to pass to the fetch method used for API requests.
     */
    fetchOptions?: DonationAlertsCallFetchOptions;
    /**
     * Configuration options for logging within the client.
     */
    logger?: Partial<LoggerOptions>;
    /**
     * Settings for the rate limiter that controls the request rate to the API.
     */
    rateLimiterOptions?: RateLimiterOptions;
}
/** @internal */
export interface DonationAlertsApiCallOptionsInternal {
    options: DonationAlertsApiCallOptions;
    accessToken?: string;
    fetchOptions?: DonationAlertsCallFetchOptions;
}
/**
 * The client for interacting with the Donation Alerts API.
 */
export declare class ApiClient {
    private readonly _config;
    private readonly _logger;
    private readonly _rateLimiter;
    private readonly _limitReachedBehavior;
    /**
     * Creates a new instance of the API client.
     *
     * @param config The configuration options for the API client.
     * @throws Error if the `authProvider` is not supplied in the configuration.
     */
    constructor(config: ApiConfig);
    /**
     * Users API namespace.
     *
     * This namespace allows you to fetch user details, such as information about the authenticated user.
     */
    get users(): DonationAlertsUsersApi;
    /**
     * Donations API namespace.
     *
     * This namespace provides methods for retrieving donation data.
     */
    get donations(): DonationAlertsDonationsApi;
    /**
     * Custom Alerts API namespace.
     *
     * This namespace provides methods for sending custom alerts.
     */
    get customAlerts(): DonationAlertsCustomAlertsApi;
    /**
     *
     * Centrifugo API namespace.
     *
     * This namespace provides methods for subscribing to Centrifugo channels.
     */
    get centrifugo(): DonationAlertsCentrifugoApi;
    /**
     * Merchandise API namespace.
     *
     * This namespace allows managing merchandise-related data.
     */
    get merchandise(): DonationAlertsMerchandiseApi;
    /**
     * Sends a request to the Donation Alerts API.
     *
     * @param user The ID of the user making the request.
     * @param options Options for the API call, including method, URL, and other details.
     * @param rateLimiterOptions Options for fine-tuning rate-limiting behavior.
     *
     * @throws {@link HttpError} If the response status code is outside the 200-299 range.
     * @throws {@link UnregisteredUserError} If the specified user is not registered in the authentication provider.
     * @throws {@link MissingScopeError} If the access token lacks the required scope to complete the request.
     */
    callApi<T = unknown>(user: UserIdResolvable, options: DonationAlertsApiCallOptions, rateLimiterOptions?: RateLimiterRequestOptions): Promise<T>;
    private _callApiInternal;
}
//# sourceMappingURL=api-client.d.ts.map