@jamx-framework/adapter-reactnative

Descripción

Adaptador de JAMX Framework para React Native. Proporciona acceso a APIs nativas de React Native (biometría, dispositivo, red, notificaciones, permisos) a través de una interfaz tipada y consistente, permitiendo construir aplicaciones móviles con funcionalidades avanzadas del sistema.

Cómo funciona

El adaptador encapsula las APIs nativas de React Native en servicios especializados que pueden ser inyectados mediante el contenedor de JAMX. Cada servicio maneja una área funcional específica y proporciona métodos asíncronos para interactuar con el hardware y sistema operativo.

Componentes principales

• src/biometrics.ts: Autenticación biométrica (huella, Face ID)
• src/device.ts: Información del dispositivo (modelo, OS, UUID)
• src/network.ts: Estado de conectividad de red
• src/notifications.ts: Notificaciones push locales
• src/permissions.ts: Gestión de permisos de la app
• src/index.ts: Punto de exportación que reúne todos los servicios
• src/types.ts: Definiciones de tipos compartidos

Uso básico

import {
  BiometricService,
  DeviceService,
  NetworkService,
  NotificationService,
  PermissionsService,
} from '@jamx-framework/adapter-reactnative';

// Inicializar servicios
const biometrics = new BiometricService();
const device = new DeviceService();
const network = new NetworkService();
const notifications = new NotificationService();
const permissions = new PermissionsService();

// Información del dispositivo
console.log('Modelo:', device.getModel());
console.log('Sistema operativo:', device.getOS());
console.log('UUID:', device.getUUID());

// Estado de red
const isConnected = await network.isConnected();
console.log('Conectado:', isConnected);

// Biometría
const available = await biometrics.isAvailable();
if (available) {
  const result = await biometrics.authenticate('Desbloquear app');
  console.log('Autenticado:', result.success);
}

// Permisos
const cameraGranted = await permissions.request('camera');
console.log('Permiso de cámara:', cameraGranted);

// Notificaciones
await notifications.requestPermission();
await notifications.schedule({
  title: 'Hola',
  body: 'Esta es una notificación local',
});

Ejemplos

Autenticación biométrica completa

import { BiometricService } from '@jamx-framework/adapter-reactnative';

const biometrics = new BiometricService();

async function loginWithBiometrics() {
  try {
    // Verificar disponibilidad
    const available = await biometrics.isAvailable();
    if (!available) {
      throw new Error('Biometría no disponible en este dispositivo');
    }

    // Autenticar
    const result = await biometrics.authenticate('Inicia sesión en tu cuenta', {
      reason: 'Para acceder a tu cuenta',
      confirmationRequired: true,
    });

    if (result.success) {
      // El usuario se autenticó exitosamente
      console.log('Usuario autenticado con biometría');
      return true;
    } else {
      console.log('Autenticación cancelada o fallida');
      return false;
    }
  } catch (error) {
    console.error('Error en biometría:', error);
    return false;
  }
}

Monitoreo de conectividad

import { NetworkService } from '@jamx-framework/adapter-reactnative';

const network = new NetworkService();

// Escuchar cambios de conectividad
network.onChange((isConnected) => {
  console.log('Estado de red cambiado:', isConnected ? 'Conectado' : 'Desconectado');
});

// Verificar tipo de conexión
const connectionType = await network.getConnectionType();
console.log('Tipo de conexión:', connectionType); // 'wifi' | 'cellular' | 'none'

Gestión de permisos reactiva

import { PermissionsService } from '@jamx-framework/adapter-reactnative';

const permissions = new PermissionsService();

async function requestCameraAndPhotos() {
  // Solicitar múltiples permisos
  const results = await permissions.requestMultiple(['camera', 'photos']);
  
  if (results.camera === 'granted' && results.photos === 'granted') {
    console.log('Todos los permisos concedidos');
    // Iniciar cámara, galería, etc.
  } else {
    console.log('Algunos permisos denegados:', results);
  }
}

// Verificar estado actual
const cameraStatus = await permissions.check('camera');
console.log('Estado cámara:', cameraStatus); // 'granted' | 'denied' | 'blocked'

Notificaciones push locales

import { NotificationService } from '@jamx-framework/adapter-reactnative';

const notifications = new NotificationService();

async function scheduleReminder() {
  // Solicitar permiso primero
  const granted = await notifications.requestPermission();
  if (!granted) {
    console.warn('Permiso de notificaciones no concedido');
    return;
  }

  // Programar notificación
  await notifications.schedule({
    title: 'Recordatorio',
    body: 'No olvides completar tu perfil',
    trigger: { seconds: 3600 }, // En 1 hora
    sound: true,
    badge: 1,
  });

  console.log('Notificación programada');
}

Información del dispositivo

import { DeviceService } from '@jamx-framework/adapter-reactnative';

const device = new DeviceService();

console.log('Información del dispositivo:');
console.log('  Modelo:', device.getModel());
console.log('  Marca:', device.getBrand());
console.log('  Fabricante:', device.getManufacturer());
console.log('  OS:', device.getOS());
console.log('  Versión OS:', device.getOSVersion());
console.log('  UUID:', device.getUUID());
console.log('  ID de build:', device.getBuildId());
console.log('  Es tablet?', device.isTablet());
console.log('  Es emulador?', device.isEmulator());

Flujo interno

1. Inicialización: Cada servicio se instancia y se registra en el contenedor de JAMX.
2. Comprobación de disponibilidad: Los servicios verifican si la API nativa está disponible en el dispositivo.
3. Ejecución asíncrona: Todos los métodos son asíncronos y devuelven Promises.
4. Manejo de errores: Los errores nativos de React Native se convierten a errores tipados.
5. Eventos: Algunos servicios (Network, Permissions) emiten eventos de cambio.
6. Testing: En tests, los servicios usan implementaciones mock que simulan respuestas.

API Reference (Resumen)

BiometricService

• isAvailable(): Promise<boolean>
• authenticate(reason: string, options?: BiometricOptions): Promise<BiometricResult>
• enumerate(): Promise<BiometricType[]>

DeviceService

• getModel(): string
• getBrand(): string
• getManufacturer(): string
• getOS(): 'ios' | 'android'
• getOSVersion(): string
• getUUID(): string
• getBuildId(): string
• isTablet(): boolean
• isEmulator(): boolean

NetworkService

• isConnected(): Promise<boolean>
• getConnectionType(): Promise<'wifi' | 'cellular' | 'none'>
• onChange(callback: (connected: boolean) => void): () => void

NotificationService

• requestPermission(): Promise<boolean>
• schedule(options: NotificationOptions): Promise<string>
• cancel(id: string): Promise<void>
• cancelAll(): Promise<void>

PermissionsService

• check(permission: string): Promise<PermissionStatus>
• request(permission: string): Promise<PermissionStatus>
• requestMultiple(permissions: string[]): Promise<Record<string, PermissionStatus>>
• onChange(callback: (permission: string, status: PermissionStatus) => void): () => void

Performance Considerations

• Lazy loading: Los servicios solo cargan las APIs nativas cuando se usan.
• Caching: Información del dispositivo se cachea después de la primera lectura.
• Event delegation: Los listeners de eventos se gestionan centralizadamente.
• Memory cleanup: Los servicios exponen métodos dispose() para limpiar listeners.

Compatibility

• Compatible con React Native >= 0.73.0
• Funciona en iOS y Android
• Requiere permisos nativos configurados en AndroidManifest.xml y Info.plist
• Algunas APIs (biometría) requieren dispositivos físicos

Testing

Tests en packages/adapter-reactnative/tests/unit/reactnative.test.ts:

pnpm test

Cubre:

• Detección de disponibilidad de biometría
• Obtención de información del dispositivo
• Monitoreo de conectividad de red
• Solicitud de permisos
• Programación de notificaciones

Configuration

Para usar este adaptador en una app React Native:

1. Instalar dependencias nativas:

npx expo install expo-local-authentication expo-device expo-network expo-notifications expo-permissions

2. Configurar permisos en app.json o app.config.ts:

{
  "expo": {
    "plugins": [
      ["expo-local-authentication", { "faceIDPermission": "Permite autenticación facial" }],
      ["expo-notifications", { "icon": "./assets/icon.png" }]
    ]
  }
}

CLI Integration

• jamx build: Compila el adaptador
• jamx run:android / jamx run:ios: Ejecuta en dispositivo/emulador

This adapter provides seamless integration between JAMX Framework and React Native, enabling developers to access native device capabilities with type safety and a consistent API across iOS and Android platforms.