npm package: @jamx-framework/adapter-reactnative
Description: JAMX Framework â€” bare React Native adapter
Author: Stiven-21
Latest version: 2.0.0

# @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
```typescript
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
```typescript
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
```typescript
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
```typescript
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
```typescript
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
```typescript
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`:

```bash
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:
```bash
npx expo install expo-local-authentication expo-device expo-network expo-notifications expo-permissions
```

2. Configurar permisos en `app.json` o `app.config.ts`:
```json
{
  "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.