@infosel-sdk/core

SDK Core para la plataforma de servicios financieros Infosel. Proporciona infraestructura esencial para autenticación, comunicación HTTP/GraphQL, gestión de almacenamiento y manejo de errores.

🚀 Características

• ✨ Configuration Builder Pattern: Nueva API fluida para configuración sin duplicaciones
• 🔐 Gestión de Autenticación: Proveedores de autenticación KeyCloak y basados en tokens
• 🌐 Cliente HTTP: Cliente HTTP configurable con interceptores de autenticación
• 📡 Cliente GraphQL: Cliente GraphQL basado en Apollo con utilidades de consulta
• 💾 Gestión de Almacenamiento: Soporte para almacenamiento local, en memoria y encriptado
• 🚨 Manejo de Errores: Sistema completo de tipos de error y gestión centralizada
• ⚙️ Gestor del SDK: Configuración y gestión centralizada del SDK
• 🔧 Configuración de Realm: Configuración dinámica de realm para múltiples ambientes

📦 Instalación

npm install @infosel-sdk/core

Compatibilidad de Versiones

• React: >=18.0.0
• React Native: >=0.70.0 (opcional)
• Node.js: >=16.0.0
• TypeScript: >=4.5.0

Dependencias Opcionales

• react-native-encrypted-storage: Solo necesario para aplicaciones React Native que requieran almacenamiento encriptado

🔧 Configuración

✨ Nueva Configuración con Builder Pattern (Recomendado)

La nueva API elimina la duplicación de configuración y proporciona validaciones centralizadas:

Autenticación KeyCloak

import { InfoselSdkManager, AuthConfigurationBuilder } from '@infosel-sdk/core';

const authConfig = AuthConfigurationBuilder
  .keyCloak()
  .withRealm('my-realm')
  .withEnvironment('qa')
  .withCredentials({
    grant_type: 'client_credentials',
    client_id: 'my-app-client',
    client_secret: 'my-app-secret',
  })
  .build();

const sdk = InfoselSdkManager.initWithConfiguration({
  authConfiguration: authConfig,
});

console.log(sdk.getRealm()); // 'my-realm'

Autenticación con Token Existente

import { InfoselSdkManager, AuthConfigurationBuilder, Token } from '@infosel-sdk/core';

const token: Token = {
  accessToken: 'your-access-token',
  refreshToken: 'your-refresh-token',
};

const authConfig = AuthConfigurationBuilder
  .existingToken()
  .withRealm('production-realm')
  .withEnvironment('prod')
  .withClientId('production-client')
  .withToken(token)
  .build();

const sdk = InfoselSdkManager.initWithConfiguration({
  authConfiguration: authConfig,
});

Configuración con Valores por Defecto

import { InfoselSdkManager, AuthConfigurationBuilder } from '@infosel-sdk/core';

// Usa 'hub' como realm por defecto y 'prod' como environment
const authConfig = AuthConfigurationBuilder
  .keyCloak()
  .withCredentials({
    grant_type: 'client_credentials',
    client_id: 'my-client',
    client_secret: 'my-secret',
  })
  .build();

const sdk = InfoselSdkManager.initWithConfiguration({
  authConfiguration: authConfig,
});

Configuración Legacy (Compatibilidad)

import { InfoselSdkManager } from '@infosel-sdk/core';

const sdk = InfoselSdkManager.init({
  mode: 'qa',
  realm: 'my-realm',
  authProviderConfig: {
    type: 'key-cloak',
    credentials: {
      grant_type: 'client_credentials',
      client_id: 'my-client',
      client_secret: 'my-secret',
    },
  },
});

🔍 Validación de Configuración

El nuevo sistema incluye validaciones robustas:

import { AuthConfigurationBuilder } from '@infosel-sdk/core';

const builder = AuthConfigurationBuilder
  .keyCloak()
  .withRealm('invalid@realm') // Caracteres inválidos
  .withCredentials({
    grant_type: 'client_credentials',
    client_id: '', // Client ID vacío
    client_secret: 'secret',
  });

// Validar antes de construir
const validation = builder.validate();
if (!validation.isValid) {
  console.log('Errores:', validation.errors);
  // ['Realm contains invalid characters...', 'Client ID is required...']
}

// O validar automáticamente al construir
try {
  const config = builder.build();
} catch (error) {
  console.error(error.message); // Lista todos los errores de validación
}

🌍 Configuración por Ambiente

import { AuthConfigurationBuilder, Environment } from '@infosel-sdk/core';

function createSdkForEnvironment(env: Environment) {
  const baseBuilder = AuthConfigurationBuilder
    .keyCloak()
    .withEnvironment(env);
    
  if (env === 'qa') {
    return baseBuilder
      .withRealm('qa-realm')
      .withCredentials({
        grant_type: 'client_credentials',
        client_id: 'qa-client',
        client_secret: 'qa-secret',
      })
      .build();
  } else {
    return baseBuilder
      .withRealm('prod-realm')
      .withCredentials({
        grant_type: 'client_credentials',
        client_id: 'prod-client',
        client_secret: 'prod-secret',
      })
      .build();
  }
}

const qaSdk = InfoselSdkManager.initWithConfiguration({
  authConfiguration: createSdkForEnvironment('qa'),
});

💾 Almacenamiento

El SDK proporciona un sistema de almacenamiento que se adapta automáticamente según la plataforma:

Convención de Archivos

• app_local_storage.ts: Implementación para Web (localStorage)
• app_local_storage.native.ts: Implementación para React Native (EncryptedStorage)

Uso del Almacenamiento

import { AppLocalStorage } from '@infosel-sdk/core';

const storage = new AppLocalStorage();

// Guardar datos
await storage.saveObject('user-data', { name: 'John', id: 123 });

// Obtener datos
const userData = await storage.getObject('user-data');

// Eliminar datos
await storage.removeObject('user-data');

🔐 Proveedores de Autenticación

Token Auth Provider

import { TokenAuthProvider } from '@infosel-sdk/core';

// Uso directo (para casos avanzados)
const authProvider = new TokenAuthProvider(
  'qa', // environment
  token, // Token object
  'custom-realm', // realm
  'custom-client' // clientId
);

KeyCloak Auth Provider

import { KeyCloakAuthProvider } from '@infosel-sdk/core';

// Uso directo (para casos avanzados)
const authProvider = new KeyCloakAuthProvider('qa', {
  type: 'key-cloak',
  credentials: {
    grant_type: 'client_credentials',
    client_id: 'client',
    client_secret: 'secret',
  },
  realm: 'custom-realm',
});

🌐 Cliente HTTP

import { InfoselHttpClient } from '@infosel-sdk/core';

const httpClient = new InfoselHttpClient({
  baseURL: 'https://api.infosel.com',
  timeout: 30000,
});

// GET request
const data = await httpClient.get('/users');

// POST request
const response = await httpClient.post('/users', { name: 'John' });

🔍 Cliente GraphQL

import { InfoselGraphQlClient, queryfy } from '@infosel-sdk/core';

const graphqlClient = new InfoselGraphQlClient({
  url: 'https://api.infosel.com/graphql',
});

// Query simple
const query = queryfy`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      email
    }
  }
`;

const result = await graphqlClient.query(query, { id: '123' });

🚨 Manejo de Errores

import { SdkError, SdkErrorType } from '@infosel-sdk/core';

try {
  const data = await httpClient.get('/users');
} catch (error) {
  if (error instanceof SdkError) {
    switch (error.type) {
      case SdkErrorType.AXIOS_RESPONSE_ERROR:
        console.error('Error de respuesta HTTP:', error.message);
        break;
      case SdkErrorType.LOCAL_STORAGE_KEY_NOT_FOUND:
        console.error('Clave de almacenamiento no encontrada:', error.message);
        break;
      case SdkErrorType.INVALID_AUTH_PROVIDER_CONFIG:
        console.error('Configuración de autenticación inválida:', error.message);
        break;
      default:
        console.error('Error del SDK:', error.message);
    }
  }
}

📚 API Reference

Clases Principales

• InfoselSdkManager: Gestor principal del SDK
• AuthConfigurationBuilder: Builder para configuraciones de autenticación
• ConfigurationValidator: Validador centralizado de configuraciones
• AppLocalStorage: Almacenamiento local adaptativo
• InfoselHttpClient: Cliente HTTP con interceptores
• InfoselGraphQlClient: Cliente GraphQL
• TokenAuthProvider: Proveedor de autenticación por token
• KeyCloakAuthProvider: Proveedor de autenticación KeyCloak

Interfaces y Tipos

• AuthConfiguration: Configuración de autenticación centralizada
• ValidationResult: Resultado de validación con errores detallados
• SdkConfig: Configuración legacy del SDK (compatibilidad)
• ModernSdkConfig: Nueva configuración del SDK
• Environment: Tipo para ambientes ('qa' | 'prod')
• AuthType: Tipo de autenticación ('key-cloak' | 'existing-token')

Tipos de Error

• SdkErrorType.SDK_MANAGER_NOT_INITIALIZED: SDK no inicializado
• SdkErrorType.AXIOS_RESPONSE_ERROR: Error de respuesta HTTP
• SdkErrorType.LOCAL_STORAGE_KEY_NOT_FOUND: Clave de almacenamiento no encontrada
• SdkErrorType.LOCAL_STORAGE_NOT_AVAILABLE: Almacenamiento no disponible
• SdkErrorType.GRAPH_QL_ERROR: Error de GraphQL
• SdkErrorType.INVALID_AUTH_PROVIDER_CONFIG: Configuración de autenticación inválida

🆕 Novedades en v0.0.4

✨ Configuration Builder Pattern

• Nueva API fluida para configuración sin duplicaciones
• Validaciones centralizadas con mensajes de error descriptivos
• Single source of truth para configuración de realm
• Compatibilidad hacia atrás mantenida

🔧 Mejoras en Configuración

• Configuración dinámica de realm para múltiples ambientes
• Validación de formatos de realm, client_id y credenciales
• Valores por defecto inteligentes basados en el tipo de autenticación
• Type safety mejorado con TypeScript

📖 Documentación

• Ejemplos completos de uso del Configuration Builder
• Guías de migración desde configuración legacy
• Casos de uso avanzados para diferentes ambientes

🔄 Migración desde v0.0.3

Antes

// ❌ Configuración duplicada
const sdk = InfoselSdkManager.init({
  mode: 'qa',
  realm: 'my-realm', // Primera definición
  authProviderConfig: {
    type: 'key-cloak',
    realm: 'my-realm', // Segunda definición (duplicada)
    credentials: { /* ... */ },
  },
});

Después

// ✅ Single source of truth
const authConfig = AuthConfigurationBuilder
  .keyCloak()
  .withRealm('my-realm') // Una sola definición
  .withEnvironment('qa')
  .withCredentials({ /* ... */ })
  .build();

const sdk = InfoselSdkManager.initWithConfiguration({
  authConfiguration: authConfig,
});

🧪 Testing

# Ejecutar tests
npm test

# Ejecutar tests con cobertura
npm run test:coverage

# Ejecutar tests específicos
npm test -- --testPathPattern="auth_configuration_builder"

🔨 Development

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

# Crear distribución
npm run build:dist

🤝 Contribución

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

📞 Soporte

• Documentación: Ejemplos de Configuration Builder
• Issues: GitHub Issues
• Equipo: Infosel Team

Hecho con ❤️ por el equipo de Infosel