govbr-auth/dist/index.d.ts

Biblioteca de autenticação GOV.BR não oficial para aplicações Node.js | Unofficial GOV.BR authentication library for Node.js applications

/**
 * Environment type for GOV.BR API
 * Tipo de ambiente para a API do GOV.BR
 */
type Environment = 'production' | 'staging';
/**
 * Configuration interface for GovBRAuth
 * Interface de configuração para GovBRAuth
 */
interface GovBRConfig {
    /** Client ID provided by GOV.BR / ID do cliente fornecido pelo GOV.BR */
    clientId: string;
    /** Client secret provided by GOV.BR / Chave secreta fornecida pelo GOV.BR */
    clientSecret: string;
    /** Redirect URI for OAuth flow / URI de redirecionamento para o fluxo OAuth */
    redirectUri: string;
    /** Environment selection / Seleção de ambiente */
    environment?: Environment;
    /** OAuth scopes / Escopos OAuth */
    scopes?: string[];
}
/**
 * Parameters for authorization URL generation
 * Parâmetros para geração da URL de autorização
 */
interface AuthorizeParams {
    /** Response type for OAuth flow / Tipo de resposta para o fluxo OAuth */
    responseType?: string;
    /** Nonce for OpenID Connect / Nonce para OpenID Connect */
    nonce?: string;
    /** State for CSRF protection / State para proteção CSRF */
    state?: string;
    /** PKCE code challenge / Desafio de código PKCE */
    codeChallenge?: string;
    /** PKCE code challenge method / Método de desafio de código PKCE */
    codeChallengeMethod?: string;
}
/**
 * Token response from GOV.BR
 * Resposta de tokens do GOV.BR
 */
interface TokenResponse {
    /** Access token / Token de acesso */
    access_token: string;
    /** ID token for OpenID Connect / Token de ID para OpenID Connect */
    id_token: string;
    /** Token type (usually "Bearer") / Tipo do token (geralmente "Bearer") */
    token_type: string;
    /** Token expiration time in seconds / Tempo de expiração do token em segundos */
    expires_in: number;
}
/**
 * User information from GOV.BR
 * Informações do usuário do GOV.BR
 */
interface UserInfo {
    /** User identifier / Identificador do usuário */
    sub: string;
    /** User's full name / Nome completo do usuário */
    name: string;
    /** User's email / Email do usuário */
    email?: string;
    /** User's phone number / Número de telefone do usuário */
    phone_number?: string;
    /** Email verification status / Status de verificação do email */
    email_verified?: boolean;
    /** Phone number verification status / Status de verificação do telefone */
    phone_number_verified?: boolean;
    /** User's profile picture URL / URL da foto de perfil do usuário */
    picture?: string;
    /** Authentication methods used / Métodos de autenticação utilizados */
    amr: string[];
    /** User's social name / Nome social do usuário */
    social_name?: string;
    /** User's CNPJ if available / CNPJ do usuário se disponível */
    cnpj?: string;
}
/**
 * Trust level information
 * Informação de nível de confiabilidade
 */
interface ConfiabilidadeNivel {
    /** Trust level ID / ID do nível de confiabilidade */
    id: string;
    /** Last update date / Data da última atualização */
    dataAtualizacao: string;
}
/**
 * Trust seal information
 * Informação de selo de confiabilidade
 */
interface ConfiabilidadeSelo {
    /** Trust seal ID / ID do selo de confiabilidade */
    id: string;
    /** Last update date / Data da última atualização */
    dataAtualizacao: string;
}

/**
 * Core service for handling GOV.BR authentication and authorization.
 * Serviço principal para gerenciamento de autenticação e autorização do GOV.BR.
 */
declare class AuthService {
    private readonly config;
    private readonly endpoints;
    private readonly client;
    /**
     * Creates a new instance of AuthService.
     * Cria uma nova instância do AuthService.
     *
     * @param config - Configuration object / Objeto de configuração
     * @throws {Error} If required configuration parameters are missing
     *                 Se parâmetros obrigatórios de configuração estiverem faltando
     */
    constructor(config: GovBRConfig);
    /**
     * Sets up Axios interceptors for error handling.
     * Configura interceptadores do Axios para tratamento de erros.
     *
     * @private
     */
    private setupAxiosInterceptors;
    /**
     * Generates the authorization URL for the OAuth flow.
     * Gera a URL de autorização para o fluxo OAuth.
     *
     * @param params - Optional authorization parameters / Parâmetros opcionais de autorização
     * @returns Authorization URL string / String da URL de autorização
     */
    generateAuthorizationUrl(params?: AuthorizeParams): string;
    /**
     * Exchanges authorization code for access tokens.
     * Troca o código de autorização por tokens de acesso.
     *
     * @param code - Authorization code from callback / Código de autorização do callback
     * @param codeVerifier - PKCE code verifier / Verificador de código PKCE
     * @returns Promise with token response / Promise com resposta dos tokens
     */
    getTokens(code: string, codeVerifier: string): Promise<TokenResponse>;
    /**
     * Retrieves user information using the access token.
     * Obtém informações do usuário usando o token de acesso.
     *
     * @param accessToken - Valid access token / Token de acesso válido
     * @returns Promise with user information / Promise com informações do usuário
     */
    getUserInfo(accessToken: string): Promise<UserInfo>;
    /**
     * Gets user's trust levels.
     * Obtém os níveis de confiabilidade do usuário.
     *
     * @param accessToken - Valid access token / Token de acesso válido
     * @param cpf - User's CPF / CPF do usuário
     * @returns Promise with trust levels / Promise com níveis de confiabilidade
     */
    getConfiabilidadeNiveis(accessToken: string, cpf: string): Promise<ConfiabilidadeNivel[]>;
    /**
     * Gets user's trust seals.
     * Obtém os selos de confiabilidade do usuário.
     *
     * @param accessToken - Valid access token / Token de acesso válido
     * @param cpf - User's CPF / CPF do usuário
     * @returns Promise with trust seals / Promise com selos de confiabilidade
     */
    getConfiabilidadeSelos(accessToken: string, cpf: string): Promise<ConfiabilidadeSelo[]>;
    /**
     * Generates the logout URL.
     * Gera a URL de logout.
     *
     * @param postLogoutRedirectUri - URL to redirect after logout / URL para redirecionamento após logout
     * @returns Logout URL string / String da URL de logout
     */
    generateLogoutUrl(postLogoutRedirectUri: string): string;
}

declare class GovBRAuth extends AuthService {
    constructor(config: GovBRConfig);
}

declare class GovBRAuthError extends Error {
    readonly code: string;
    readonly statusCode?: number | undefined;
    readonly originalError?: Error | undefined;
    constructor(message: string, code: string, statusCode?: number | undefined, originalError?: Error | undefined);
}

declare function generateNonce(): string;
declare function generateState(): string;
declare function generateCodeVerifier(): string;
declare function generateCodeChallenge(verifier: string): string;
declare function base64URLEncode(str: string): string;

export { type AuthorizeParams, type ConfiabilidadeNivel, type ConfiabilidadeSelo, type Environment, GovBRAuth, GovBRAuthError, type GovBRConfig, type TokenResponse, type UserInfo, base64URLEncode, generateCodeChallenge, generateCodeVerifier, generateNonce, generateState };