falconhub-apilibrary 1.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 Blink Solutions SA de CV
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# FalconHUB SDK
+
+Librería cliente desarrollada en Typescript dedicada a faciliar el consumo del API de FalconHUB, manejo interno de procesos generales, tokens, sliding window session y firma de solicitudes mediante X-Signature.
+
+## Caracterísiticas
+
+**Gestión de tokens** - Al realizar el inicio de sesión mediate el módulo de auth, la librería se encargará de gestionar las sesiones mediante funciones callback.
+**Slinding window** - Cuando se desee mantener la sesión activa la librería gestionará las renovaciones de tokens mediante Sliding Window.
+**Firmas de seguridad autogestionadas** - Dentro del entorno existen rutas protegidas (de tipo POST) protegidas mediante firmas Signature, la librería se encarga de realizar estas firmas y procesarlas.
+**Callbacks** - Se introducen funciones que sincronizan información entre la librería y el proyecto que la consuma.
+
+## Instalación
+
+Ejecuta:
+
+```bash
+npm install
+```
+
+> **Nota:**
+> - **Producción (main)**: `falconhub-apilibrary-X.X.X.tgz` - Versión estable
+> - **Desarrollo (development)**: `falconhub-apilibrary-X.X.X-dev.tgz` - Última versión en desarrollo

package/dist/index.d.mts

@@ -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 };