alphavalid-sdk 0.0.25 → 0.1.0

package/README.md

@@ -1,10 +1,15 @@
 # alphavalid-sdk
 
-SDK frontend (framework-agnostic) para:
-- abrir câmera frontal
-- guiar posicionamento (overlay)
-- detectar rosto (MVP) com `face-api.js` (TinyFaceDetector)
-- capturar selfie em JPEG (Blob)
+SDK frontend (framework-agnostic) para validação facial e liveness com captura de selfie em JPEG.
+
+Principais recursos:
+- câmera frontal com teardown correto
+- overlay visual com guias e hints
+- desafios de liveness configuráveis
+- captura manual e auto-capture com gate de estabilidade
+- preview com botões OK/Recapturar (SDK ou customizado)
+
+---
 
 ## Instalação
 
@@ -12,40 +17,31 @@ SDK frontend (framework-agnostic) para:
 npm i alphavalid-sdk
 ```
 
-## Passo obrigatório: disponibilizar os models
-
-O `face-api.js` carrega os pesos do modelo via HTTP. Este pacote leva os arquivos em `models/`, e você deve copiá-los para os assets do seu app.
+---
 
-> Nota (Ionic/Angular + Vite dev-server): o shard do TinyFaceDetector é distribuído com extensão `.bin`
-> para evitar erros de `vite:import-analysis` em alguns pipelines.
+## Modelos (obrigatório)
 
-### Ionic/Angular (recomendado) — cópia automática no `postinstall`
+O `face-api.js` carrega pesos via HTTP. Copie os models do pacote para a pasta pública do seu app.
 
-No `package.json` do **APP consumidor**, adicione:
+### CLI (recomendado)
 
-```json
-{
-  "scripts": {
-    "postinstall": "node ./node_modules/alphavalid-sdk/scripts/copy-models.cjs ./src/assets/alphavalid-models"
-  }
-}
+```bash
+npx alphavalid-sdk setup
 ```
 
-Isso garante que, ao rodar `npm i`, os models sejam copiados para:
+Ele detecta o tipo de projeto e copia:
+- Angular: `src/assets/alphavalid-models` (runtime: `/assets/alphavalid-models`)
+- Vite: `public/alphavalid-models` (runtime: `/alphavalid-models`)
 
-- `src/assets/alphavalid-models/`  -> servidos em runtime como `/assets/alphavalid-models`
-
-> Se você estiver no Windows, pode precisar rodar esse script via `node` do mesmo jeito (sem `./`).
-
-### Execução manual (alternativa)
+### Manual
 
 ```bash
-node ./node_modules/alphavalid-sdk/scripts/copy-models.cjs ./src/assets/alphavalid-models
+node ./node_modules/alphavalid-sdk/scripts/copy-models.cjs ./public/alphavalid-models
 ```
 
-## Uso
+---
 
-Crie um container (div) com tamanho definido (ex.: 320x320, ou 100% do seu layout) e passe no `start()`.
+## Uso minimo
 
 ```ts
 import { AlphaValid } from 'alphavalid-sdk';
@@ -53,117 +49,87 @@ import { AlphaValid } from 'alphavalid-sdk';
 const sdk = new AlphaValid();
 
 await sdk.start({
-  container: document.getElementById('cameraContainer')!,
-  // Angular/Ionic assets:
-  modelsPath: '/assets/alphavalid-models',
-  onReady: () => console.log('ready'),
-  onFeedback: (msg) => console.log('feedback:', msg),
-  onError: (err) => console.error('error:', err)
+  // se estiver no Angular/Ionic, use /assets/alphavalid-models
+  modelsPath: '/alphavalid-models',
+  onUserPreviewConfirm: (blob) => {
+    // enviar blob
+  }
 });
-
-// quando feedback retornar "Pronto para capturar"
-const blob = await sdk.capture();
 ```
 
-Para encerrar:
+Para finalizar:
 
 ```ts
 await sdk.stop();
 ```
 
-### Liveness / desafios (opcional)
-
-Você pode exigir que só seja considerado **válido olhando para frente**, e/ou definir uma sequência de desafios.
+---
 
-#### Importante (fluxo com challenges)
+## Preview (OK/Recapturar)
 
-- Quando `liveness.challenges` é informado, o SDK **não** força `lookForward` globalmente a cada frame.
-- Se você quiser `lookForward`, coloque como **um step explícito** (recomendado como último step).
-
-#### Ajuste de sensibilidade do lookForward
-
-Use `liveness.lookForwardTolerance` (0..1):
-- **maior = mais tolerante** (mais fácil passar)
-- se omitido, é derivado de `strictness`
+O preview gerenciado pelo SDK funciona em `uiMode: 'Mobile'` e `userPreview: true`.
+Por padrao o preview ja vem ligado.
 
 ```ts
 await sdk.start({
-  // ...
-  liveness: {
-    strictness: 0.5,
-    lookForwardTolerance: 0.75
+  uiMode: 'Mobile',
+  userPreview: true,
+  previewOkText: 'OK',
+  previewRetakeText: 'Tirar outra',
+  onUserPreviewConfirm: (blob) => {
+    // enviar blob
   }
 });
 ```
 
-Exemplo com sequência (cliente orquestra a ordem, SDK valida e controla o progresso):
+Se voce quiser renderizar um preview customizado:
 
 ```ts
 await sdk.start({
-  container: document.getElementById('cameraContainer')!,
-  modelsPath: '/assets/alphavalid-models',
-  liveness: {
-    strictness: 0.5,
-    lookForwardTolerance: 0.75,
-    challenges: [
-      { type: 'lookLeft' },
-      { type: 'lookRight' },
-      { type: 'lookUp' },
-      { type: 'lookDown' },
-      { type: 'blink' },
-      { type: 'lookForward' } // recomendado como último
-    ]
-  },
-  onStateChange: (state) => {
-    console.log('step:', state.challenge?.current, state.challenge?.index, '/', state.challenge?.total);
+  onPreview: (blob, actions) => {
+    // abra seu modal, use actions.retake() e actions.confirm()
   }
 });
 ```
 
-#### Auto-capture (recomendado no cliente)
+---
 
-O SDK expõe `state.isReadyToCapture`. Para auto-capture sem duplicar disparos, use lock + debounce:
+## Personalizacao de botoes
 
 ```ts
-let lock = false;
-let timer: any = null;
-
 await sdk.start({
-  // ...
-  onStateChange: async (state) => {
-    if (lock) return;
-
-    if (state.isReadyToCapture) {
-      if (timer) return;
-      timer = setTimeout(async () => {
-        timer = null;
-        if (lock) return;
-        if (!sdk.getState()?.isReadyToCapture) return;
-
-        lock = true;
-        try {
-          const blob = await sdk.capture();
-          // envie o blob pro backend...
-        } finally {
-          await sdk.stop();
-        }
-      }, 500); // 300-600ms costuma funcionar bem
-    } else {
-      if (timer) {
-        clearTimeout(timer);
-        timer = null;
-      }
-    }
-  }
+  captureButton: {
+    enabled: true,
+    text: 'Capturar foto',
+    color: '#ff6b35'
+  },
+  previewOkText: 'Usar foto',
+  previewRetakeText: 'Tirar outra'
 });
 ```
 
-## Observações
+---
+
+## API publica
+
+- `new AlphaValid()`
+- `start(options: AlphaValidStartOptions): Promise<void>`
+- `stop(): Promise<void>`
+- `capture(): Promise<Blob>`
+- `getState(): AlphaValidState | null`
+- `resetChallenges(): void`
+- `setupModels(): Promise<string>` (importando `setupModels` do pacote)
+
+---
+
+## Documentacao completa
 
-- Este MVP faz **detecção** (tem 1 rosto? está centralizado? perto/longe?).
-- Não é reconhecimento facial (comparar com base de rostos).
+Veja [alphavalid-sdk-docs.md](alphavalid-sdk-docs.md) para:
+- todas as opcoes do SDK
+- defaults oficiais
+- exemplos completos
+- ajustes de liveness e debug
+- detalhes do estado e callbacks
 
-Observações sobre liveness:
-- Tudo aqui é **heurístico (MVP)**. Para liveness robusto, o ideal é um pipeline dedicado.
-- O desafio `blink` usa landmarks (modelo `faceLandmark68TinyNet`).
 
+### `stop(): Promise<void>`

package/bin/alphavalid.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+function detectProjectType() {
+  if (fs.existsSync('angular.json')) return 'angular';
+  if (fs.existsSync('vite.config.js') || fs.existsSync('vite.config.ts') || fs.existsSync('index.html') || fs.existsSync('public')) return 'vite';
+  return 'unknown';
+}
+
+function getTargetDir() {
+  const type = detectProjectType();
+  if (type === 'angular') return path.join('src', 'assets', 'alphavalid-models');
+  if (type === 'vite') return path.join('public', 'alphavalid-models');
+  return path.join('alphavalid-models');
+}
+
+function copyModels() {
+  const src = path.join(__dirname, '..', 'models');
+  const dest = path.resolve(process.cwd(), getTargetDir());
+  if (!fs.existsSync(src)) {
+    console.error('[AlphaValid] Pasta de models não encontrada:', src);
+    process.exit(1);
+  }
+  fs.mkdirSync(dest, { recursive: true });
+  for (const file of fs.readdirSync(src)) {
+    fs.copyFileSync(path.join(src, file), path.join(dest, file));
+  }
+  console.log(`[AlphaValid] Models copiados para ${dest}`);
+}
+
+try {
+  copyModels();
+} catch (e) {
+  console.error('[AlphaValid] Não foi possível copiar automaticamente os models.');
+  console.error('Execute: npx alphavalid-sdk setup');
+  process.exit(1);
+}

package/dist/__vite-browser-external-C7ivxuo1.mjs

@@ -0,0 +1,18 @@
+//#region \0rolldown/runtime.js
+var e = Object.create, t = Object.defineProperty, n = Object.getOwnPropertyDescriptor, r = Object.getOwnPropertyNames, i = Object.getPrototypeOf, a = Object.prototype.hasOwnProperty, o = (e, t) => () => (t || e((t = { exports: {} }).exports, t), t.exports), s = (e, i, o, s) => {
+	if (i && typeof i == "object" || typeof i == "function") for (var c = r(i), l = 0, u = c.length, d; l < u; l++) d = c[l], !a.call(e, d) && d !== o && t(e, d, {
+		get: ((e) => i[e]).bind(null, d),
+		enumerable: !(s = n(i, d)) || s.enumerable
+	});
+	return e;
+}, c = (n, r, a) => (a = n == null ? {} : e(i(n)), s(r || !n || !n.__esModule ? t(a, "default", {
+	value: n,
+	enumerable: !0
+}) : a, n)), l = /* @__PURE__ */ ((e) => typeof require < "u" ? require : typeof Proxy < "u" ? new Proxy(e, { get: (e, t) => (typeof require < "u" ? require : e)[t] }) : e)(function(e) {
+	if (typeof require < "u") return require.apply(this, arguments);
+	throw Error("Calling `require` for \"" + e + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
+}), u = /* @__PURE__ */ o(((e, t) => {
+	t.exports = {};
+}));
+//#endregion
+export { l as n, c as r, u as t };