@donation-alerts/auth/cjs/providers/refreshing-auth-provider.d.ts

Authentication provider for Donation Alerts API with ability to automatically refresh user tokens.

import { EventEmitter } from '@d-fischer/typed-event-emitter';
import { type UserIdResolvable } from '@donation-alerts/common';
import { type AuthProvider } from './auth-provider';
import { type AccessToken, type AccessTokenWithUserId } from '../access-token';
/**
 * Configuration for {@link RefreshingAuthProvider}.
 */
export interface RefreshingAuthProviderConfig {
    /**
     * The Donation Alerts client ID.
     */
    clientId: string;
    /**
     * The Donation Alerts client secret.
     *
     * @remarks
     * This is required to refresh expired tokens for any user. If you do not need token refreshing,
     * you may opt for {@link StaticAuthProvider}.
     */
    clientSecret: string;
    /**
     * A redirect URI configured in your application settings.
     *
     * @remarks
     * This is required only if you intend to use the {@link RefreshingAuthProvider#addUserForCode} method.
     */
    redirectUri?: string;
    /**
     * The list of scopes that all registering tokens must include.
     *
     * If scopes are specified for the token being registered, it will be compared against the scopes from this option.
     * If the token misses any scope from this list then {@link MissingScopeError} exception will be thrown.
     */
    scopes?: string[];
}
/**
 * An authentication provider that automatically refreshes user access tokens when they expire.
 */
export declare class RefreshingAuthProvider extends EventEmitter implements AuthProvider {
    private readonly _config;
    private readonly _registry;
    private readonly _newTokenPromises;
    /**
     * Fires when a user's token is successfully refreshed.
     *
     * @param userId The ID of the user whose token was refreshed.
     * @param token The updated {@link AccessToken} object.
     */
    readonly onRefresh: import("@d-fischer/typed-event-emitter").EventBinder<[userId: number, token: AccessToken]>;
    /**
     * Creates a new instance of the `RefreshingAuthProvider`.
     *
     * @param config The configuration object that defines client credentials and settings.
     */
    constructor(config: RefreshingAuthProviderConfig);
    get clientId(): string;
    /**
     * Checks whether the specified user is registered in this provider.
     *
     * @param user The ID of the user to check.
     */
    hasUser(user: UserIdResolvable): boolean;
    /**
     * Adds a user to this provider, associating them with the provided token data.
     *
     * @param user The ID of the user to add.
     * @param token The token data, including refresh and access tokens.
     *
     * @throws {@link InvalidTokenError} if the access or refresh tokens are invalid.
     * @throws {@link MissingScopeError} if the token does not match the required scopes.
     */
    addUser(user: UserIdResolvable, token: AccessToken): AccessTokenWithUserId;
    /**
     * Determines the user ID from an access token and registers that user.
     *
     * If you already know the user's ID, using {@link addUser} might be preferable.
     *
     * @param token The token data, including refresh and access tokens.
     */
    addUserForToken(token: AccessToken): Promise<AccessTokenWithUserId>;
    /**
     * Exchanges a grant authorization code for an access token and registers the user in this auth provider.
     *
     * @remarks
     * The `redirectUri` option must be specified in {@link RefreshingAuthProviderConfig} to complete
     * this flow successfully.
     *
     * @param code The authorization code.
     * @param scopes Optional scopes that the user granted when retrieving the code. These scopes will be compared
     * against the scopes specified in the constructor.
     */
    addUserForCode(code: string, scopes?: string[]): Promise<AccessTokenWithUserId>;
    /**
     * Removes a user from this provider.
     *
     * @param user The ID of the user to remove.
     */
    removeUser(user: UserIdResolvable): void;
    getScopesForUser(user: UserIdResolvable): string[];
    getAccessTokenForUser(user: UserIdResolvable, scopes?: string[]): Promise<AccessTokenWithUserId>;
    /**
     * Forces a token refresh for the specified user and updates the provider's registry accordingly.
     *
     * @param user The ID of the user to add.
     *
     * @throws {@link UnregisteredUserError} if the user is not registered in this provider.
     * @throws {@link InvalidTokenError} if the refresh token is missing or invalid.
     */
    refreshAccessTokenForUser(user: UserIdResolvable): Promise<AccessTokenWithUserId>;
    private _validateToken;
}
//# sourceMappingURL=refreshing-auth-provider.d.ts.map