falconhub-apilibrary 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,357 @@
+declare class ErrorResponse extends Error {
+    statusCode?: number | undefined;
+    responseData?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, responseData?: any | undefined);
+}
+
+interface TokenData {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: Date;
+    rememberMe: boolean;
+}
+
+interface ServiceProperties {
+    url: string;
+    originRequest: string;
+    domain: string;
+    device: string;
+    source: string;
+    autoRefresh?: boolean | {
+        enabled: boolean;
+        thresholdMinutes: number;
+    };
+    onTokensUpdated?: (tokens: TokenData | null) => void;
+    onTokensRefreshed?: (tokens: {
+        accessToken: string | null;
+        refreshToken: string | null;
+    }) => void;
+    onSessionExpiring?: (remainingMinutes: number) => void;
+    onSessionExpired?: () => Promise<void>;
+    onAuthError?: (error: ErrorResponse) => void;
+}
+
+declare class CryptoService {
+    /**
+     * Encripta el texto plano utilizando AES con una clave derivada del secretWord y el timestamp
+     *
+     * @param plaintText -- Texto plano a encriptar
+     * @param secretWord - Palabra secreta utilizada para derivar la clave
+     * @param timestamp - Timestamp actual
+     * @returns Texto encriptado en formato Base64
+     */
+    encrypt(plaintText: string, secretWord: string, timestamp: string): string;
+    /**
+     * Genera la firma Signature para las operaciones de tipo POST
+     *
+     * @param body - Cuerpo de la solicitud
+     * @param timestamp - Timestamp actual
+     * @param refreshToken - Refresh token del usuario
+     * @returns Firma signature en formato Base64
+     */
+    genSignature(body: string, timestamp: string, refreshToken: string): string;
+    /**
+     * Desencripta texto usando AES-256-CBC
+     *
+     * @param encryptedBase64 - Texto encriptado en base64
+     * @param secret - Clave secreta
+     * @param timestamp - Timestamp usado en la encriptación
+     * @returns Texto desencriptado
+   */
+    decrypt(encryptedText: string, secretWord: string, timestamp: string): string;
+    /**
+   * Verifica una firma HMAC-SHA256 (útil para testing o validación)
+   *
+   * @param body - Cuerpo original
+   * @param timestamp - Timestamp original
+   * @param refreshToken - Token usado como clave
+   * @param signature - Firma a verificar
+   * @returns true si la firma es válida
+   */
+    verifySignature(body: string, timestamp: string, refreshToken: string, signature: string): boolean;
+    /**
+   * Genera un hash SHA256 de un texto (útil para fingerprints)
+   *
+   * @param text - Texto a hashear
+   * @returns Hash en formato hexadecimal
+   */
+    sha256(text: string): string;
+    /**
+     * Genera un identificador único basado en timestamp y random
+     * (útil para request IDs)
+     *
+     * @returns ID único
+     */
+    generateUniqueId(): string;
+}
+
+type MethodTypes = "GET" | "POST" | "PATCH" | "DELETE" | "PUT";
+interface RequestOptions {
+    endpoint: string;
+    method: MethodTypes;
+    body?: any;
+    requiresSignature: boolean;
+    requiresAuth: boolean;
+    timeStamp?: string;
+}
+
+interface AuthInterceptorConfig {
+    enabled?: boolean;
+    thresholdMinutes?: number;
+    isTokenExpiringSoon: () => boolean;
+    hasValidTokens: () => boolean;
+    shouldAutoRefresh: () => boolean;
+    refreshSession: () => Promise<void>;
+}
+
+interface InterceptorContext {
+    requestId: string;
+    startTime: number;
+    retryCount: number;
+    metadata?: Record<string, any>;
+}
+
+interface RequestConfig {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: any;
+    requiresAuth: boolean;
+    requiresSignature: boolean;
+}
+
+/**
+ * Interceptor de request
+ */
+interface RequestInterceptor {
+    name: string;
+    /**
+     * Procesa el request antes de enviarlo
+     *
+     * @param config - Configuración del request
+     * @param context - Contexto compartido
+     * @returns Configuración modificada o Promise que resuelve a la configuración
+     */
+    onRequest(config: RequestConfig, context: InterceptorContext): Promise<RequestConfig> | RequestConfig;
+}
+
+declare class AuthInterceptor implements RequestInterceptor {
+    readonly name = "AuthInterceptor";
+    private config;
+    private refreshPromise;
+    private isRefreshing;
+    constructor(config: AuthInterceptorConfig);
+    onRequest(config: RequestConfig, context: InterceptorContext): Promise<RequestConfig>;
+    updateConfig(config: Partial<AuthInterceptorConfig>): void;
+    reset(): void;
+}
+
+/**
+ * Clase base para la ejecución de request HTTP al API
+ */
+declare class API {
+    private properties;
+    private cryptoService;
+    private authInterceptor;
+    private getAccessToken;
+    private getRefreshToken;
+    constructor(properties: ServiceProperties, cryptoService: CryptoService, authInterceptor: AuthInterceptor | null, getAccessToken: () => string | null, getRefreshToken: () => string | null);
+    /**
+     * Ejecuta una request HTTP al API
+     *
+     * @param options - Opciones de la request
+     * @returns Respuesta parseada del tipo esperado
+     */
+    private apiExecute;
+    /**
+     * Maneja errores HTTP y lanza excepciones apropiadas
+     */
+    private handleErrorResponse;
+    executeGET<T>(endpoint: string, requiresAuth?: boolean): Promise<T | undefined>;
+    executePOST<T>(endpoint: string, body?: any, requiresAuth?: boolean, requiresSignature?: boolean): Promise<T | undefined>;
+    executePATCH<T>(endpoint: string, body?: any, requiresAuth?: boolean, requiresSignature?: boolean): Promise<T | undefined>;
+    executeDELETE<T>(endpoint: string, body?: any, requiresAuth?: boolean, requiresSignature?: boolean): Promise<T | undefined>;
+    executePUT<T>(endpoint: string, body?: any, requiresAuth?: boolean, requiresSignature?: boolean): Promise<T | undefined>;
+    executePublicRequest<T>(endpoint: string, method: MethodTypes, body?: any, timestamp?: string): Promise<T | undefined>;
+}
+
+/**
+ * Manages authentication tokens.
+ */
+declare class TokenManager {
+    private tokens;
+    private onTokensChanged?;
+    private sessionCheckInterval;
+    private onSessionExpiring?;
+    private onSessionExpired?;
+    private hasNotifiedExpiring;
+    constructor(onTokensChanged?: (tokens: TokenData | null) => void, onSessionExpiring?: (remainingMinutes: number) => void, onSessionExpired?: () => Promise<void>);
+    /**
+     * Guarda los tokens de autenticación y dispara el callback onTokensChanged.
+     */
+    setTokens(tokens: TokenData): void;
+    /**
+     * Obtiene los tokens de autenticación almacenados.
+     */
+    getTokens(): TokenData | null;
+    /**
+     * Limpia los tokens de autenticación almacenados y dispara el callback onTokensChanged.
+     */
+    clearTokens(): void;
+    /**
+     * Valida si existen tokens y si el access token no ha expirado.
+     */
+    hasValidTokens(): boolean;
+    /**
+     * Valida si el access token expirará dentro del umbral especificado (en minutos).
+     */
+    isTokenExpiringSoon(thresholdMinutes: number): boolean;
+    /**
+     * Obtiene el tiempo restante hasta la expiración del access token en milisegundos.
+     */
+    getTimeUntilExpiry(): number | null;
+    /**
+     * Obtiene el access token almacenado.
+     */
+    getAccessToken(): string | null;
+    /**
+     * Obtiene el refresh token almacenado.
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Verifica si el auto-refresh debe ejecutarse
+     * Solo si el usuario activó "rememberMe" durante el login
+     */
+    shouldAutoRefresh(): boolean;
+    /**
+     * Inicia el monitoreo de expiración para sesiones sin rememberMe
+     * - Notifica cuando quedan 5 minutos (onSessionExpiring)
+     * - Ejecuta logout cuando queda 1 minuto (onSessionExpired)
+     */
+    private startExpirationCheck;
+    /**
+     * Detiene el monitoreo de expiración
+     */
+    private stopExpirationCheck;
+}
+
+interface LoginRequest {
+    email: string;
+    password: string;
+    rememberMe: boolean;
+}
+
+interface LoginResponse {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: string;
+    message: string;
+    type: string;
+}
+
+interface RefreshTokenResponse {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: string;
+    message: string;
+    type: string;
+}
+
+interface ValidateSessionRenewedResponse {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: string;
+    remainingMinutes: number;
+    isRemembered: boolean;
+}
+interface ValidateSessionResponse {
+    expiresAt: Date;
+    remainingMinutes: number;
+    isRemembered: boolean;
+}
+
+interface ResponseModel<T = any> {
+    success: boolean;
+    message: string;
+    totalItems?: number;
+    data: T | null;
+    responseTime: string | null;
+}
+
+declare class AuthService {
+    private api;
+    private crytpoService;
+    private tokenManager;
+    private serviceProperties;
+    constructor(serviceProperties: ServiceProperties, tokenManager: TokenManager, cryptoService: CryptoService, api: API);
+    /**
+     * Login con las credenciales proporcionadas
+     * @param credentials - Objeto con email, password y rememberMe
+     * @returns Retorna el cuerpo de respuesta del login.
+     */
+    login(credentials: LoginRequest): Promise<ResponseModel<LoginResponse>>;
+    /**
+     * Valida la sesión actual y retorna información de expiración
+     *
+     * El servidor puede responder de 2 formas:
+     * 1. Sesión renovada (sliding window): retorna nuevos tokens
+     * 2. Sesión válida: retorna info de expiración sin renovar
+     */
+    validateSession(): Promise<ResponseModel<ValidateSessionRenewedResponse | ValidateSessionResponse>>;
+    /**
+     * Refresca los tokens usando el refresh token
+     */
+    refreshTokens(rememberMe?: boolean): Promise<ResponseModel<RefreshTokenResponse>>;
+    /**
+     * Cierra sesión: notifica al servidor y limpia tokens
+     */
+    logout(): Promise<void>;
+    /**
+     * Verifica si el usuario está autenticado
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Obtiene los tokens actuales
+     */
+    getTokens(): TokenData | null;
+}
+
+/**
+ * SDK principal de FalconHUB
+ */
+declare class FalconHUBSDK {
+    auth: AuthService;
+    private serviceProperties;
+    private cryptoService;
+    private tokenManager;
+    private authInterceptor;
+    private api;
+    constructor(serviceProperties: ServiceProperties);
+    private normalizeAutoRefreshConfig;
+    /**
+     * Inyecta tokens desde storage externo (cookies/localStorage/etc)
+     */
+    setTokensFromExternal(accessToken: string, refreshToken: string, expiresAt: Date, rememberMe?: boolean): void;
+    /**
+     * Obtiene los tokens actuales
+     */
+    getTokens(): TokenData | null;
+    /**
+     * Verifica si el usuario está autenticado
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Verifica si la sesión está por expirar
+     */
+    isSessionExpiringSoon(thresholdMinutes?: number): boolean;
+    /**
+     * Obtiene el tiempo restante hasta la expiración en milisegundos
+     */
+    getTimeUntilExpiry(): number | null;
+}
+
+interface RefreshTokenRequest {
+    rememberMe: boolean;
+}
+
+export { API, AuthInterceptor, type AuthInterceptorConfig, AuthService, CryptoService, ErrorResponse, FalconHUBSDK, type InterceptorContext, type LoginRequest, type LoginResponse, type MethodTypes, type RefreshTokenRequest, type RefreshTokenResponse, type RequestConfig, type RequestInterceptor, type RequestOptions, type ResponseModel, type ServiceProperties, type TokenData, TokenManager, type ValidateSessionRenewedResponse, type ValidateSessionResponse };