@ha_tecno/react-native-sdk/README.md

React Native SDK for biometric authentication, liveness detection, and fingerprint recognition

# React Native SDK

Esta SDK oferece componentes e serviços para captura de biometria (dedo, liveness), autenticação e integração com backend.

## Instalação

### NPM

```bash
npm install @hatecno/react-native-sdk
```

### Yarn

```bash
yarn add @hatecno/react-native-sdk
```

### Dependências Nativas

Esta SDK depende de algumas bibliotecas nativas. Instale-as seguindo suas respectivas documentações:

```bash
# Dependências obrigatórias
npm install react-native-vision-camera react-native-device-info react-native-fs
npm install react-native-gesture-handler react-native-reanimated react-native-svg
npm install react-native-worklets-core uuid

# iOS
cd ios && pod install

# Android - adicione as permissões necessárias ao AndroidManifest.xml
```

### Permissões

#### iOS (ios/Info.plist)

```xml
<key>NSCameraUsageDescription</key>
<string>Esta app precisa acessar a câmera para captura biométrica</string>
```

#### Android (android/app/src/main/AndroidManifest.xml)

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
```

---

## Configuração Inicial

Antes de usar qualquer funcionalidade, configure a SDK com um token de autenticação:

```ts
import { configureLibrary } from '@hatecno/react-native-sdk';

await configureLibrary('SEU_TOKEN_AQUI');
```

---

## Componentes

### `<Camera />`

Componente principal para captura de foto/vídeo biométrico.

**Props principais:**

- `serviceType`: `'finger' | 'liveness'` — Define o tipo de serviço.
- `onCapturePhoto(path, focusScore?, deviceConfig?)`: callback ao capturar foto.
- `onCaptureVideo(path)`: callback ao capturar vídeo.
- `captureButtonVisible`: exibe botão de captura.
- `disabled`: desabilita a câmera.
- `torch`: `'on' | 'off'` — flash.

**Exemplo:**

```tsx
<Camera
  serviceType="finger"
  onCapturePhoto={(path, focusScore, deviceConfig) => {
    /* ... */
  }}
  captureButtonVisible
/>
```

---

## Serviços

### `cameraService`

Configurações e parâmetros da câmera:

- `getCameraDeviceConfig()`: Busca configurações do dispositivo.
- `getFocusScoreParams()`: Busca parâmetros de foco.

### `userService`

Autenticação tradicional com CPF/senha:

- `validCpf(cpf: string)`: Valida CPF.
- `login(cpf: string, password: string)`: Login com CPF e senha.
- `register(cpf: string, name: string, password: string)`: Cadastro de usuário.

### `biometricService`

Autenticação e cadastro biométrico:

- `loginWithFingerprint(params)`: Autenticação por biometria.
- `registerWithFingerprint(params)`: Cadastro de biometria.

**Parâmetros comuns:**

- `deviceModel`: Modelo do dispositivo
- `uid`: ID do usuário
- `finger`: Dedo (ex: 'RI' para indicador direito)
- `exposure`: Exposição da câmera
- `zoom`: Zoom da câmera
- `meanScore`, `stdScore`, `varScore`: Parâmetros de qualidade de foco

**Login específico:**

- `image`: Imagem em base64

**Cadastro específico:**

- `imagens`: Array de imagens em base64

### `livenessService`

Prova de vida:

- `lifeCertificate(params)`: Processa prova de vida com vídeo.

**Parâmetros:**

- `videoPath`: Caminho do vídeo capturado
- `uid`: ID do usuário
- `exposure`: Valor de exposição da câmera
- `exposureMax?`: Exposição máxima (opcional)
- `exposureMin?`: Exposição mínima (opcional)
- `exposureScaleZeroToOne?`: Escala de exposição 0-1 (opcional)

**Retorno:**

- `code`: Código de status (0 = sucesso)
- `bpm?`: Batimentos cardíacos detectados
- `message?`: Mensagem de erro/sucesso

### `calibrationService`

Calibração de pontos de operação para otimizar captura em diferentes dispositivos:

- `registerOperationPointsBiometrics(params)`: Calibra pontos de operação para biometria.
- `registerOperationPointsLiveness(params)`: Calibra pontos de operação para prova de vida.

**Parâmetros Biometria:**

- `images`: Array de imagens em base64 para calibração
- `exposure`, `exposureMin`, `exposureMax`: Configurações de exposição
- `exposureScaleZeroToOne`: Escala de exposição 0-1
- `zoom`, `zoomMin`, `zoomMax`: Configurações de zoom
- `zoomScaleZeroToOne`: Escala de zoom 0-1
- `deviceModel?`: Modelo do dispositivo (opcional, detectado automaticamente)

**Parâmetros Prova de Vida:**

- `videoPath`: Caminho do vídeo para calibração
- `exposure`, `exposureMin`, `exposureMax`: Configurações de exposição
- `exposureScaleZeroToOne`: Escala de exposição 0-1
- `deviceModel?`: Modelo do dispositivo (opcional, detectado automaticamente)

**Retorno:**

- `status`: Código de status
- `message`: Mensagem de resultado
- `hasConfig?`: Indica se a configuração foi criada (apenas para liveness)

---

## Utilitários

### Enum `Finger`

Enum para identificar dedos:

```ts
Finger.LEFT_THUMB; // 'LT'
Finger.RIGHT_INDEX; // 'RI'
// etc.
```

---

## Tipos

- `CameraProps`: Tipagem das props do componente Camera.
- `DeviceParams`: Configuração do dispositivo para captura.
- `BiometricLoginParams`: Parâmetros para login biométrico.
- `BiometricRegisterParams`: Parâmetros para cadastro biométrico.
- `BiometricResponse`: Resposta das operações biométricas.
- `LifeCertificateParams`: Parâmetros para prova de vida.
- `LifeCertificateResponse`: Resposta da prova de vida.
- `BiometricCalibrationParams`: Parâmetros para calibração de biometria.
- `LivenessCalibrationParams`: Parâmetros para calibração de prova de vida.
- `CalibrationResponse`: Resposta das operações de calibração.

---

## Exemplo de Uso Completo

### Prova de Vida

```tsx
import { Camera, livenessService } from '@hatecno/react-native-sdk';

const ProvaDeVida = () => {
  const onCaptureVideo = async (videoPath: string | undefined) => {
    if (!videoPath) return;

    try {
      const result = await livenessService.lifeCertificate({
        videoPath,
        uid: 'USER_ID_123',
        exposure: 0.5,
        exposureMax: 1.0,
        exposureMin: 0.0,
        exposureScaleZeroToOne: 0.5,
      });

      if (result.code === 0) {
        console.log(`✅ Prova de vida concluída! BPM: ${result.bpm}`);
      } else {
        console.log(`❌ Erro: ${result.message}`);
      }
    } catch (error) {
      console.error('Erro na prova de vida:', error);
    }
  };

  return (
    <Camera
      serviceType="liveness"
      onCaptureVideo={onCaptureVideo}
      totalRemainingSeconds={10}
    />
  );
};
```

### Login Biométrico

```tsx
import { Camera, biometricService, Finger } from '@hatecno/react-native-sdk';
import { readFile } from 'react-native-fs';
import { getModel } from 'react-native-device-info';

const LoginBiometrico = () => {
  const onCapturePhoto = async (
    path: string | undefined,
    focusScore?: any,
    deviceConfig?: any
  ) => {
    if (!path) return;

    try {
      const image = await readFile(path, 'base64');

      const result = await biometricService.loginWithFingerprint({
        deviceModel: getModel(),
        uid: 'USER_ID_123',
        image,
        finger: Finger.RIGHT_INDEX,
        exposure: deviceConfig?.exposure ?? 0,
        zoom: deviceConfig?.zoom ?? 0,
        meanScore: focusScore?.meanScore ?? 0,
        stdScore: focusScore?.stdScore ?? 0,
        varScore: focusScore?.varScore ?? 0,
      });

      if (result.status === 200) {
        console.log('✅ Login biométrico realizado com sucesso!');
      } else {
        console.log(`❌ Erro: ${result.message}`);
      }
    } catch (error) {
      console.error('Erro no login biométrico:', error);
    }
  };

  return (
    <Camera
      serviceType="finger"
      onCapturePhoto={onCapturePhoto}
      captureButtonVisible
    />
  );
};
```

### Cadastro Biométrico

```tsx
import { Camera, biometricService, Finger } from '@hatecno/react-native-sdk';

const CadastroBiometrico = () => {
  const [images, setImages] = useState<string[]>([]);

  const onCapturePhoto = async (path: string | undefined) => {
    if (!path) return;

    const image = await readFile(path, 'base64');
    const newImages = [...images, image];
    setImages(newImages);

    // Cadastrar após 3 capturas
    if (newImages.length === 3) {
      const result = await biometricService.registerWithFingerprint({
        deviceModel: getModel(),
        uid: 'USER_ID_123',
        imagens: newImages,
        finger: Finger.RIGHT_INDEX,
        exposure: 0.5,
        zoom: 1.0,
        meanScore: 0,
        stdScore: 0,
        varScore: 0,
      });

      console.log('Resultado cadastro:', result);
      setImages([]); // Reset
    }
  };

  return (
    <Camera
      serviceType="finger"
      onCapturePhoto={onCapturePhoto}
      captureButtonVisible
    />
  );
};
```

### Calibração de Dispositivo

```tsx
import { calibrationService, Camera } from '@hatecno/react-native-sdk';
import { readFile } from 'react-native-fs';

const CalibracaoDispositivo = () => {
  const [calibrationImages, setCalibrationImages] = useState<string[]>([]);

  // Calibração para Biometria
  const calibrateBiometrics = async () => {
    const result = await calibrationService.registerOperationPointsBiometrics({
      images: calibrationImages,
      exposure: 0.5,
      exposureMin: 0.0,
      exposureMax: 1.0,
      exposureScaleZeroToOne: 0.5,
      zoom: 1.0,
      zoomMin: 1.0,
      zoomMax: 3.0,
      zoomScaleZeroToOne: 0.33,
    });

    if (result.status === 200) {
      console.log('✅ Calibração de biometria concluída!');
    } else {
      console.log(`❌ Erro na calibração: ${result.message}`);
    }
  };

  // Calibração para Prova de Vida
  const onCaptureVideoCalibration = async (videoPath: string | undefined) => {
    if (!videoPath) return;

    const result = await calibrationService.registerOperationPointsLiveness({
      videoPath,
      exposure: 0.5,
      exposureMin: 0.0,
      exposureMax: 1.0,
      exposureScaleZeroToOne: 0.5,
    });

    if (result.status === 200) {
      console.log('✅ Calibração de prova de vida concluída!');
      if (result.hasConfig) {
        console.log('🎯 Configuração criada com sucesso!');
      } else {
        console.log('🔄 Repita o processo mais uma vez');
      }
    } else {
      console.log(`❌ Erro na calibração: ${result.message}`);
    }
  };

  const onCapturePhotoCalibration = async (path: string | undefined) => {
    if (!path) return;

    const image = await readFile(path, 'base64');
    const newImages = [...calibrationImages, image];
    setCalibrationImages(newImages);

    // Calibrar após 5 capturas
    if (newImages.length >= 5) {
      await calibrateBiometrics();
      setCalibrationImages([]); // Reset
    }
  };

  return (
    <div>
      <h3>Calibração de Biometria</h3>
      <Camera
        serviceType="finger"
        onCapturePhoto={onCapturePhotoCalibration}
        captureButtonVisible
      />

      <h3>Calibração de Prova de Vida</h3>
      <Camera
        serviceType="liveness"
        onCaptureVideo={onCaptureVideoCalibration}
        totalRemainingSeconds={10}
      />
    </div>
  );
};
```

---

## Observações

- Certifique-se de conceder permissões de câmera.
- Para biometria, utilize o enum `Finger` para identificar o dedo.
- Os serviços retornam promessas e podem lançar erros.

---

Se precisar de exemplos mais avançados ou integração específica, abra uma issue!