npm package: @neofaceid/web-sdk
Description: NeoFaceId Web SDK for facial authentication
Author: Octa Corporate
Latest version: 1.24.1

# NeoFace ID SDK Web

SDK para captura e reconhecimento facial em aplicações web.

## Instalação

```bash
npm install @neofaceid/web-sdk
```

## Uso Básico

```javascript
import { start } from '@neofaceid/web-sdk';

// Inicialize o SDK com seu token de aplicação
start('seu-token-de-aplicacao', {
  onSuccess: (user) => {
    console.log('Usuário autenticado:', user);
    // user contém: { name, email, documentId }
  },
  onError: (code, message) => {
    console.error('Erro:', code, message);
  }
});
```

## Versão

O SDK segue o padrão de versionamento semântico (SemVer):

```javascript
import { VERSION, RELEASE_DATE } from '@neofaceid/web-sdk';

console.log(`Usando NeoFace ID SDK versão ${VERSION} (lançada em ${RELEASE_DATE})`);
```

### Histórico de Versões

| Versão | Data | Mudanças |
|--------|------|----------|
| 1.0.0 | 2023-06-15 | Lançamento inicial do SDK |

## Parâmetros

### applicationToken (string)
Token de autenticação da sua aplicação. Obtenha este token no painel de administração do NeoFace ID.

### callbacks (object)

#### onSuccess (function)
Chamado quando o reconhecimento facial é bem-sucedido.
- Parâmetros: `user` (object) - Contém `name`, `email` e `documentId` do usuário reconhecido.

#### onError (function)
Chamado quando ocorre um erro durante o processo.
- Parâmetros:
  - `code` (string) - Código do erro
  - `message` (string) - Mensagem descritiva do erro

### Códigos de Erro

| Código | Descrição |
|--------|-----------|
| `TOKEN_VALIDATION_ERROR` | Token de aplicação inválido ou expirado |
| `NO_CAMERA` | Câmera não disponível ou permissão negada |
| `FACE_NOT_DETECTED` | Nenhum rosto detectado na imagem |
| `MULTIPLE_FACES` | Múltiplos rostos detectados na imagem |
| `FACE_NOT_CENTERED` | Rosto não está centralizado no frame |
| `LIVENESS_CHECK_FAILED` | Verificação de vivacidade falhou |
| `RECOGNITION_FAILED` | Falha no reconhecimento facial |
| `NETWORK_ERROR` | Erro de conexão com o servidor |
| `TIMEOUT` | Tempo limite excedido durante o processo |

## Customização

O modal de captura facial pode ser customizado através de CSS. Adicione as seguintes classes ao seu CSS:

```css
/* Container principal */
#neoface-modal-container {
  /* Estilos para o container */
}

/* Modal */
#neoface-modal-container .modal {
  /* Estilos para o modal */
}

/* Botões */
#neoface-modal-container .button {
  /* Estilos para os botões */
}

/* Mensagens */
#neoface-modal-container .message {
  /* Estilos para as mensagens */
}

/* Guia de posicionamento */
#neoface-modal-container .guide {
  /* Estilos para o guia de posicionamento */
}
```

## Requisitos de Segurança

### HTTPS
O SDK requer uma conexão HTTPS para funcionar. Em ambiente de desenvolvimento, você pode usar `localhost`.

### Permissões
O SDK solicita permissão para acessar a câmera do dispositivo. Esta permissão é essencial para o funcionamento do reconhecimento facial.

### HSTS
Recomendamos configurar HTTP Strict Transport Security (HSTS) no servidor para garantir que todas as conexões sejam feitas via HTTPS.

### Privacidade
O SDK não armazena dados biométricos localmente. Todas as imagens são processadas em tempo real e descartadas após o reconhecimento.

## Notas de Performance

- **Resolução Adaptativa**: O SDK ajusta automaticamente a resolução da câmera com base nas capacidades do dispositivo.
- **Compressão JPEG**: As imagens são comprimidas antes do envio para otimizar o uso de banda.
- **Timeout**: O processo de reconhecimento tem um timeout de 10 segundos para evitar que o usuário fique aguardando indefinidamente.

## Compatibilidade

### Navegadores Suportados
- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+

### Responsividade
O SDK é totalmente responsivo e funciona em dispositivos desktop e mobile. Em dispositivos móveis, o modal ocupa a tela inteira para uma melhor experiência do usuário.

## Integração com .NET Framework

O NeoFace ID SDK Web pode ser facilmente integrado em aplicações web desenvolvidas com .NET Framework 4.8 ou superior. Siga os passos abaixo para implementar a autenticação facial em seu projeto ASP.NET:

### 1. Instalação via NuGet

Adicione o pacote ao seu projeto .NET:

```powershell
Install-Package NeoFaceId.WebSdk
```

Ou adicione a referência ao seu arquivo `.csproj`:

```xml
<PackageReference Include="NeoFaceId.WebSdk" Version="1.0.2" />
```

### 2. Configuração no Web.config

Adicione a configuração do token no seu arquivo `Web.config`:

```xml
<configuration>
  <appSettings>
    <add key="NeoFaceId:ApplicationToken" value="seu-token-de-aplicacao" />
  </appSettings>
</configuration>
```

### 3. Implementação no Código

#### No Controller (C#)

```csharp
using System.Web.Mvc;
using NeoFaceId.WebSdk;

public class AuthenticationController : Controller
{
    private readonly string _applicationToken;

    public AuthenticationController()
    {
        _applicationToken = System.Configuration.ConfigurationManager.AppSettings["NeoFaceId:ApplicationToken"];
    }

    public ActionResult Index()
    {
        return View();
    }

    [HttpPost]
    public JsonResult AuthenticateUser(string name, string email, string documentId)
    {
        // Processar a autenticação do usuário
        // Este método é chamado após o reconhecimento facial bem-sucedido
        
        // Exemplo: Criar sessão do usuário
        Session["UserName"] = name;
        Session["UserEmail"] = email;
        Session["UserDocumentId"] = documentId;
        
        return Json(new { success = true });
    }
}
```

#### Na View (Razor)

```html
@{
    ViewBag.Title = "Autenticação Facial";
}

<div class="container">
    <h2>Autenticação Facial</h2>
    
    <button id="startFaceAuth" class="btn btn-primary">Iniciar Autenticação Facial</button>
    
    <div id="authResult"></div>
</div>

@section Scripts {
    <script src="~/Scripts/neoface-id-sdk.js"></script>
    <script>
        document.getElementById('startFaceAuth').addEventListener('click', function() {
            // Inicializar o SDK com o token da aplicação
            NeoFaceId.start('@System.Configuration.ConfigurationManager.AppSettings["NeoFaceId:ApplicationToken"]', {
                onSuccess: function(user) {
                    // Enviar dados do usuário para o servidor
                    $.ajax({
                        url: '@Url.Action("AuthenticateUser", "Authentication")',
                        type: 'POST',
                        data: {
                            name: user.name,
                            email: user.email,
                            documentId: user.documentId
                        },
                        success: function(response) {
                            if (response.success) {
                                document.getElementById('authResult').innerHTML = 
                                    '<div class="alert alert-success">Autenticação bem-sucedida!</div>';
                                // Redirecionar para a página principal após autenticação
                                setTimeout(function() {
                                    window.location.href = '@Url.Action("Index", "Home")';
                                }, 1500);
                            }
                        },
                        error: function() {
                            document.getElementById('authResult').innerHTML = 
                                '<div class="alert alert-danger">Erro ao processar autenticação no servidor.</div>';
                        }
                    });
                },
                onError: function(code, message) {
                    document.getElementById('authResult').innerHTML = 
                        '<div class="alert alert-danger">Erro: ' + message + '</div>';
                }
            });
        });
    </script>
}
```

### 4. Personalização do Modal

Para personalizar a aparência do modal de captura facial, adicione os estilos CSS ao seu arquivo `Site.css` ou ao layout principal:

```css
/* Estilos para o modal de captura facial */
#neoface-modal-container .modal {
    border-radius: 8px;
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

#neoface-modal-container .button {
    background-color: #007bff;
    color: white;
    border: none;
    padding: 8px 16px;
    border-radius: 4px;
    cursor: pointer;
}

#neoface-modal-container .button:hover {
    background-color: #0069d9;
}
```

### 5. Considerações de Segurança

- Sempre valide os dados recebidos do cliente no servidor
- Utilize HTTPS para todas as comunicações
- Armazene o token de aplicação de forma segura (nunca no código-fonte)
- Considere implementar rate limiting para evitar abusos
- Implemente logs de auditoria para rastrear tentativas de autenticação

## Deploy Automático

O SDK é publicado automaticamente no NPM quando há push na branch `master`. O workflow:

1. **Valida** que está rodando na branch master
2. **Verifica** se a versão atual já existe no NPM (idempotente)
3. **Determina** o tipo de bump (patch/minor) baseado no commit message
4. **Incrementa** a versão em todos os arquivos (package.json, package-lock.json, src/version.ts)
5. **Commita** e faz push das mudanças com retry logic
6. **Builda** o pacote
7. **Publica** no NPM com retry automático em caso de falhas temporárias

### Convenções de Commit

- `feat:` ou `feature:` → bump **minor** (1.0.0 → 1.1.0)
- `fix:` ou `patch:` → bump **patch** (1.0.0 → 1.0.1)
- Outros commits → bump **patch** por padrão

### Idempotência

O workflow é idempotente: se a versão já existe no NPM, o deploy é pulado automaticamente sem erro.

### Retry Logic

- **Git sync**: 3 tentativas com backoff exponencial
- **NPM publish**: 3 tentativas com backoff exponencial
- **Erro 409**: Verifica se versão existe antes de falhar

## Licença

MIT