npm package: @gs_manuel_gs/biometric-button
Description: Componente biométrico reusable para Expo/React Native.
Latest version: 0.0.1

# BiometricButton

Componente biométrico reusable para Expo/React Native.

## Instalación rápida

```bash
npm install @gs_manuel_gs/biometric-button
```

## Peer dependencies requeridas

La app que consuma la librería debe tener instaladas estas dependencias:

- `react`
- `react-native`
- `react-native-paper`
- `styled-components`
- `expo-local-authentication`

Ejemplo:

```bash
npm install react-native-paper styled-components expo-local-authentication
```

## Uso básico

```jsx
import { BiometricAuthScreen } from "@gs_manuel_gs/biometric-button";

<BiometricAuthScreen />;
```

Por defecto, el componente lanza automáticamente la autenticación biométrica cuando detecta hardware biométrico disponible y al menos una biometría registrada en el dispositivo.

## Uso configurable

```jsx
<BiometricAuthScreen
  config={{
    maxAttempts: 3,
    lockoutSeconds: 30,
    disableDeviceFallback: true,
    autoAuthenticate: true,
  }}
  promptOptions={{
    promptMessage: "Authenticate",
  }}
  attemptsRemainingLabel="Attempts remaining"
  attemptsLimitReachedMessage="You have reached the allowed attempts limit."
  buttonAuthenticatingText=""
  onSuccess={(result) => console.log("OK", result)}
  onError={(result) => console.log("FAIL", result)}
  onResult={(result) => console.log("DONE", result)}
  onStateChange={(state) => console.log("STATE", state)}
/>
```

## Texto del botón desde children

```jsx
<BiometricAuthScreen>Boton autenticación</BiometricAuthScreen>
```

El contenido entre etiquetas se usa como texto del botón principal cuando no está en estado de carga.

## Comportamiento de texto mínimo

Por defecto, la UI no muestra textos informativos de estado ni tipos biométricos. Solo se muestran mensajes de error.

## Configuración unificada (opcional)

La prop `config` agrupa la configuración principal:

- `maxAttempts`
- `lockoutSeconds`
- `disableDeviceFallback`
- `autoAuthenticate`

`autoAuthenticate` viene habilitado por defecto (`true`). Si quieres evitar el disparo automático y dejar solo el botón manual, configúralo en `false`.

```jsx
<BiometricAuthScreen config={{ autoAuthenticate: false }}>
  Authenticate manually
</BiometricAuthScreen>
```

Si configuras `maxAttempts`, se mostrará el número de intentos restantes y se bloqueará la acción al alcanzar el límite. Si también configuras `lockoutSeconds`, el botón queda bloqueado durante ese tiempo y luego se reinician los intentos.

```jsx
<BiometricAuthScreen config={{ maxAttempts: 3, lockoutSeconds: 20 }} />
```

### Significado de callbacks

- `onSuccess(result)`
  - Se ejecuta cuando la autenticación termina correctamente.
  - Úsalo para continuar el flujo protegido (por ejemplo, login o navegación).

- `onError(result)`
  - Se ejecuta cuando la autenticación falla o no puede completarse.
  - Úsalo para mostrar mensajes de error, métricas o lógica de reintento.

- `onResult(result)`
  - Se ejecuta siempre al finalizar un intento (éxito o error).
  - Útil para telemetría centralizada, logs o lógica común post-autenticación.

- `onStateChange(state)`
  - Se ejecuta cuando cambia el estado interno del componente.
  - Estados habituales: `checking_device`, `ready`, `authenticating`, `success`, `error`, `locked`.

### Estructura del `result`

Los callbacks `onSuccess`, `onError` y `onResult` reciben un objeto `result` con campos como:

- `success`: indica si la autenticación fue satisfactoria.
- `code`: código normalizado (ver `BIOMETRIC_ERROR_CODES`).
- `message`: descripción legible del resultado.
- `biometricTypes`: tipos biométricos detectados en el dispositivo.
- `canRetry`: indica si el usuario puede intentar de nuevo.
- `shouldCountAttempt`: indica si el fallo debe contar para `maxAttempts`.