alphavalid-sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,2 +1,135 @@
 # alphavalid-sdk
 
+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
+
+```bash
+npm i alphavalid-sdk
+```
+
+---
+
+## Modelos (obrigatório)
+
+O `face-api.js` carrega pesos via HTTP. Copie os models do pacote para a pasta pública do seu app.
+
+### CLI (recomendado)
+
+```bash
+npx alphavalid-sdk setup
+```
+
+Ele detecta o tipo de projeto e copia:
+- Angular: `src/assets/alphavalid-models` (runtime: `/assets/alphavalid-models`)
+- Vite: `public/alphavalid-models` (runtime: `/alphavalid-models`)
+
+### Manual
+
+```bash
+node ./node_modules/alphavalid-sdk/scripts/copy-models.cjs ./public/alphavalid-models
+```
+
+---
+
+## Uso minimo
+
+```ts
+import { AlphaValid } from 'alphavalid-sdk';
+
+const sdk = new AlphaValid();
+
+await sdk.start({
+  // se estiver no Angular/Ionic, use /assets/alphavalid-models
+  modelsPath: '/alphavalid-models',
+  onUserPreviewConfirm: (blob) => {
+    // enviar blob
+  }
+});
+```
+
+Para finalizar:
+
+```ts
+await sdk.stop();
+```
+
+---
+
+## Preview (OK/Recapturar)
+
+O preview gerenciado pelo SDK funciona em `uiMode: 'Mobile'` e `userPreview: true`.
+Por padrao o preview ja vem ligado.
+
+```ts
+await sdk.start({
+  uiMode: 'Mobile',
+  userPreview: true,
+  previewOkText: 'OK',
+  previewRetakeText: 'Tirar outra',
+  onUserPreviewConfirm: (blob) => {
+    // enviar blob
+  }
+});
+```
+
+Se voce quiser renderizar um preview customizado:
+
+```ts
+await sdk.start({
+  onPreview: (blob, actions) => {
+    // abra seu modal, use actions.retake() e actions.confirm()
+  }
+});
+```
+
+---
+
+## Personalizacao de botoes
+
+```ts
+await sdk.start({
+  captureButton: {
+    enabled: true,
+    text: 'Capturar foto',
+    color: '#ff6b35'
+  },
+  previewOkText: 'Usar foto',
+  previewRetakeText: 'Tirar outra'
+});
+```
+
+---
+
+## 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
+
+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
+
+
+### `stop(): Promise<void>`

package/bin/alphavalid.js

@@ -0,0 +1,92 @@
+#!/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}`);
+}
+
+function copyLoaderGif() {
+  const projectRoot = process.cwd();
+  const sdkRoot = path.join(__dirname, '..');
+
+  // Prefer the packaged location (guaranteed by package.json "files")
+  let loaderSrc = path.join(sdkRoot, 'public', 'images', 'alphaloader.gif');
+
+  // Fallback for local development (repo) only
+  if (!fs.existsSync(loaderSrc)) {
+    const demoLoader = path.join(sdkRoot, 'demo', 'public', 'images', 'alphaloader.gif');
+    if (fs.existsSync(demoLoader)) loaderSrc = demoLoader;
+  }
+
+  if (!fs.existsSync(loaderSrc)) return;
+
+  // Angular/Ionic Angular
+  if (fs.existsSync(path.join(projectRoot, 'angular.json'))) {
+    // Canonical destination used by the SDK: src/assets/images (plural)
+    const angularImages = path.join(projectRoot, 'src', 'assets', 'images');
+    fs.mkdirSync(angularImages, { recursive: true });
+    fs.copyFileSync(loaderSrc, path.join(angularImages, 'alphaloader.gif'));
+    console.log('[AlphaValid] Loader GIF copiado para', angularImages);
+
+    // Compatibility: if the project already uses src/assets/image (singular), also copy there
+    const angularImageSingular = path.join(projectRoot, 'src', 'assets', 'image');
+    if (fs.existsSync(angularImageSingular)) {
+      fs.mkdirSync(angularImageSingular, { recursive: true });
+      fs.copyFileSync(loaderSrc, path.join(angularImageSingular, 'alphaloader.gif'));
+      console.log('[AlphaValid] Loader GIF (compat) copiado para', angularImageSingular);
+    }
+
+    return;
+  }
+
+  // Vite / SPA genérica: public/images
+  if (
+    fs.existsSync(path.join(projectRoot, 'vite.config.js')) ||
+    fs.existsSync(path.join(projectRoot, 'vite.config.ts')) ||
+    fs.existsSync(path.join(projectRoot, 'index.html'))
+  ) {
+    const viteImages = path.join(projectRoot, 'public', 'images');
+    fs.mkdirSync(viteImages, { recursive: true });
+    fs.copyFileSync(loaderSrc, path.join(viteImages, 'alphaloader.gif'));
+    console.log('[AlphaValid] Loader GIF copiado para', viteImages);
+  }
+}
+
+try {
+  copyLoaderGif();
+} catch {
+  // silencioso: se falhar, o SDK tem fallback interno
+}
+
+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 };

package/dist/alphavalid.es.d.ts

@@ -0,0 +1,126 @@
+declare global {
+    interface Window {
+        mouthWidthRatioDebug?: number;
+    }
+}
+import type { AlphaValidStartOptions, AlphaValidState } from './types/sdk';
+export declare function setupModels(): Promise<string>;
+export declare class AlphaValid {
+    private _camera;
+    private _overlay;
+    private _container;
+    private _faceDetector;
+    private _loopTimer;
+    private _lastStatusValid;
+    private _options;
+    private _status;
+    private _challengeIndex;
+    private _challengeStartedAt;
+    private _challengeEnterAt;
+    private _challengeCompletedAt;
+    private _challengeBaselineSeen;
+    private _blinkArmed;
+    private _state;
+    private _stableSince;
+    private _lastStableCx;
+    private _lastStableCy;
+    private _lastStableArea;
+    private _autoCaptureFired;
+    private _lastGoodStatus;
+    private _lastGoodAt;
+    /**
+     * Last detected frame status (most recent tick) used specifically for real-time
+     * capture button gating (look-forward).
+     */
+    private _lastStatusForCaptureGate;
+    private _lastLookForwardGateOk;
+    private _poseLatch;
+    private _lastPoseChallenge;
+    private _mouthJawBaseline;
+    private _faceLostAt;
+    private _lookForwardOkSince;
+    private _blinkCount;
+    private _blinkPrevClosed;
+    private _cheeseBaseline;
+    private _cheeseBaselineSamples;
+    private _cheeseBaselineSum;
+    private _cheeseBaselineStartedAt;
+    private _challengeHoldSince;
+    private _challengeLastStepOk;
+    private _challengeHoldProgress;
+    private _challengeUiProgress;
+    /** Keep the last start options so the loop/catch/finally always has access (avoids scope issues). */
+    private _startOptions;
+    /** Estado de preview: blob da última captura, se em preview. */
+    private _previewBlob;
+    /** Guardar actions do preview para retake/confirm. */
+    private _previewActions;
+    private _cheeseWindow;
+    private _cheeseWindowStart;
+    private _openMouthWindow;
+    private _openMouthWindowStart;
+    /** Internal SDK lifecycle state machine. */
+    private _lifecycle;
+    /** Prevent starting multiple detection loops concurrently. */
+    private _loopActive;
+    /** Internal flag for debug logs (derived from start options). */
+    private _debug;
+    /** Prevent concurrent capture() executions. */
+    private _isCapturing;
+    /** userPreview UI (Coxinha mode only). */
+    private _userPreviewUi;
+    private _userPreviewUrl;
+    /** Built-in camera/models loader overlay. */
+    private _loader;
+    private _captureBtn;
+    private _disposeCaptureButton;
+    private _syncCaptureButton;
+    private _setLifecycle;
+    /**
+     * Pauses the detection loop without stopping the camera stream or clearing options.
+     * Safe to call multiple times.
+     */
+    private _pause;
+    /**
+     * Resume the detection loop after a preview retake without tearing down/restoring options multiple times.
+     * Camera & overlay are recreated by calling start() with the original options.
+     */
+    private _retakeFromPreview;
+    /**
+     * Confirms the preview and finalizes the flow.
+     */
+    private _confirmFromPreview;
+    private _hideUserPreviewUi;
+    private _disposeUserPreviewUi;
+    /**
+     * Chama o preview após captura, pausa detecção e exibe opções de retake/confirm.
+     */
+    private _showPreview;
+    private _usesCustomPreview;
+    private _usesSdkManagedPreview;
+    /** Hide camera until everything is ready (prevents showing video before models/overlay are loaded). */
+    private _setVideoVisibility;
+    /** Esconde vídeo + overlay enquanto o host exibe preview customizado. */
+    private _setCaptureSurfaceVisibility;
+    start(options: AlphaValidStartOptions): Promise<void>;
+    stop(): Promise<void>;
+    /** Indica se está em preview (bloqueia detecção/captura). */
+    private get _isInPreview();
+    capture(): Promise<Blob>;
+    getState(): AlphaValidState | null;
+    /** Reset the challenge progression back to step 0 (does not restart camera/detector). */
+    resetChallenges(): void;
+    private getCurrentChallenge;
+    private markStepCompletedIfNeeded;
+    private mapChallengeToHint;
+    private isStableFrame;
+    /**
+     * Simple, independent lookForward gate for capture.
+     * Intentionally does NOT reuse computeFeedback/lookForward challenge state.
+     * Returns true when user is roughly facing the camera.
+     */
+    private _isLookForwardForCapture;
+    private startDetectionLoop;
+}
+export type { AlphaValidHint, AlphaValidStartOptions, AlphaValidState } from './types/sdk';
+//# sourceMappingURL=index.d.ts.map