@wristband/express-auth/dist/types/wristband-service.d.ts

SDK for integrating your ExpressJS application with Wristband. Handles user authentication, session management, and token management.

import { SdkConfiguration, UserInfo, WristbandTokenResponse } from './types';
/**
 * Service class for making REST API calls to the Wristband platform.
 *
 * Handles OAuth token exchange, user information retrieval, token refresh,
 * and token revocation. Most methods use HTTP Basic Authentication with
 * the configured client credentials.
 *
 * @internal
 */
export declare class WristbandService {
    private wristbandApiClient;
    private basicAuthHeaders;
    private clientId;
    constructor(wristbandApplicationVanityDomain: string, clientId: string, clientSecret: string);
    /**
     * Fetches SDK configuration from Wristband's auto-configuration endpoint.
     *
     * Retrieves application-specific configuration values including login URLs,
     * redirect URIs, and custom domain settings.
     *
     * @returns Promise resolving to the SDK configuration object
     * @throws {Error} When the API request fails
     */
    getSdkConfiguration(): Promise<SdkConfiguration>;
    /**
     * Exchanges an authorization code for OAuth tokens.
     *
     * Makes a request to Wristband's token endpoint using the authorization code
     * received from the callback. Uses PKCE (code verifier) for enhanced security.
     *
     * @param code - The authorization code from the OAuth callback
     * @param redirectUri - The redirect URI used in the authorization request
     * @param codeVerifier - The PKCE code verifier for this authorization request
     * @returns Promise resolving to token response with access_token, id_token, and optional refresh_token
     * @throws {Error} When any parameter is missing or empty
     * @throws {InvalidGrantError} When the authorization code is invalid or expired
     */
    getTokens(code: string, redirectUri: string, codeVerifier: string): Promise<WristbandTokenResponse>;
    /**
     * Retrieves user information from Wristband's userinfo endpoint.
     *
     * Fetches OIDC-compliant user claims including profile, email, phone, and role data
     * based on the scopes associated with the access token. Transforms snake_case OIDC
     * claims to camelCase field names.
     *
     * @param accessToken - The OAuth access token
     * @returns Promise resolving to structured UserInfo object with user claims
     * @throws {Error} When access token is missing or empty
     * @throws {TypeError} When response is invalid or missing required claims
     */
    getUserInfo(accessToken: string): Promise<UserInfo>;
    /**
     * Refreshes an expired access token using a refresh token.
     *
     * Exchanges a valid refresh token for a new set of tokens. The refresh token
     * must have been obtained with the 'offline_access' scope.
     *
     * @param refreshToken - The refresh token
     * @returns Promise resolving to new token response with fresh access_token and id_token
     * @throws {Error} When refresh token is missing or empty
     * @throws {InvalidGrantError} When the refresh token is invalid or expired
     */
    refreshToken(refreshToken: string): Promise<WristbandTokenResponse>;
    /**
     * Revokes a refresh token to invalidate it.
     *
     * Makes a request to Wristband's revocation endpoint to permanently invalidate
     * the refresh token. After revocation, the token can no longer be used to obtain
     * new access tokens. This is typically called during logout.
     *
     * @param refreshToken - The refresh token to revoke
     * @returns Promise that resolves when revocation is complete
     * @throws {Error} When refresh token is missing or empty
     */
    revokeRefreshToken(refreshToken: string): Promise<void>;
    /**
     * Checks if an error is a FetchError containing an invalid_grant error code.
     *
     * @param error - The error to check
     * @returns True if the error is a FetchError with an invalid_grant body
     *
     * @internal
     */
    private static hasInvalidGrantError;
    /**
     * Extracts the error_description field from a FetchError response body.
     *
     * @param error - The error to inspect
     * @returns The error description string, or undefined if not present
     *
     * @internal
     */
    private static getErrorDescription;
    /**
     * Validates that the userinfo response from Wristband contains all required OIDC claims.
     *
     * Checks for the presence and correct types of mandatory claims that Wristband
     * always returns regardless of scopes: sub (userId), tnt_id (tenantId),
     * app_id (applicationId), and idp_name (identityProviderName).
     *
     * @param data - The raw response data from the userinfo endpoint
     * @throws {TypeError} When response is not an object or missing required claims
     *
     * @internal
     */
    private static validateUserinfoResponse;
    /**
     * Transforms the raw OIDC claims from Wristband's userinfo endpoint
     * to the structured UserInfo type with camelCase field names.
     *
     * @param userinfo - Raw userinfo claims from Wristband auth SDK
     * @returns Structured UserInfo object from Wristband session SDK
     */
    private static mapUserinfoClaims;
}