@beltec/face-gate 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,259 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+
+/** Caixa do rosto dominante, em frações da imagem (0 a 1). */
+type FaceBox = {
+    xmin: number;
+    ymin: number;
+    xmax: number;
+    ymax: number;
+};
+/** Tokens de uma análise (unidade de processamento do Face Gate: megapixels × peso de cada etapa). */
+type TokenUsage = {
+    tokens: number;
+    /** `validate` conta em dobro com melhoria (valida antes e depois); `enhance` = custo da melhoria. */
+    breakdown: {
+        decode: number;
+        validate: number;
+        clean: number;
+        enhance?: number;
+        avatar?: number;
+    };
+    /** Saldo da janela do plano (ex.: 5 h a partir do 1º uso). */
+    window?: {
+        used: number;
+        limit: number;
+        hours: number;
+        started_on: string | null;
+        resets_at: string | null;
+    };
+    /** Saldo do teto mensal (renova no aniversário do contrato). */
+    month?: {
+        used: number;
+        limit: number;
+        cycle_start: string;
+        cycle_end: string;
+    };
+};
+/**
+ * Melhoria de imagem (serviço "validate_enhance"):
+ *  - "classic": luz, cor, contraste, ruído e nitidez leve; determinística, não altera o rosto;
+ *  - "gfpgan": a clássica + restauração do rosto com IA (recria detalhes; avisa `face_restored_ai`).
+ */
+type EnhanceMethod = "classic" | "gfpgan";
+/** Resumo de uma validação dentro de `enhancement` (antes = foto original, depois = melhorada). */
+type ValidationSummary = {
+    accepted: boolean;
+    score: number | null;
+    hard_fails: string[];
+};
+type Enhancement = {
+    method: EnhanceMethod;
+    /** Etapas aplicadas: white_balance, exposure, local_contrast, denoise, sharpen, face_restoration. */
+    steps: string[];
+    /** Dispositivo do GFPGAN (null na clássica). */
+    device: "cpu" | "gpu" | null;
+    before: ValidationSummary;
+    after: ValidationSummary;
+    /** Falhas da original que a melhoria não corrige (desfoque, olhos fechados…): continuam reprovando. */
+    carried_over: string[];
+    /** Foto melhorada (JPEG em data URL). */
+    enhanced_image: string;
+};
+/** Formato do avatar (serviço "avatar"): redondo (fora do círculo transparente) ou quadrado. */
+type AvatarShape = "square" | "round";
+/**
+ * Onde a pessoa fica no avatar (só com fundo de cor ou imagem): centro; apoiada na base (o fundo aparece em
+ * cima); na base à esquerda ou à direita.
+ */
+type AvatarLayout = "center" | "bottom" | "left" | "right";
+/** Dados do avatar gerado (POST /v1/photos/avatar). */
+type AvatarInfo = {
+    shape: AvatarShape;
+    /** Lado em pixels (64 a 1024). */
+    size: number;
+    /** Modelo de remoção de fundo que separou a pessoa. */
+    model: string;
+    /** "transparent", "image" (fundo enviado) ou a cor "#rrggbb". */
+    background: string;
+    /** % do quadro deixado para o fundo (0 com fundo transparente). */
+    margin?: number;
+    layout?: AvatarLayout;
+};
+/** Avisos da validação. `face_restored_ai`: o GFPGAN recriou detalhes do rosto. */
+type ValidationWarning = "face_restored_ai" | "gpu_fallback_cpu" | (string & {});
+/** Resultado da validação de uma foto (mesmo formato de POST /v1/photos/*). */
+type ValidationResult = {
+    accepted: boolean;
+    score: number;
+    checks: Record<string, boolean | null>;
+    /** Critérios que reprovaram (ex.: "eyes_closed", "sunglasses", "low_light"). */
+    hard_fails?: string[];
+    reasons?: string[];
+    warnings?: ValidationWarning[];
+    error?: string;
+    dominant_face_bbox?: FaceBox | null;
+    /** Foto com o fundo removido, recortada no rosto (PNG em data URL), quando pedido `clean`. */
+    cleaned_image?: string;
+    rembg_model?: string;
+    device?: "cpu" | "gpu";
+    timings?: {
+        validation_ms?: number;
+    };
+    usage?: TokenUsage;
+    /** Presente quando a foto passou pela melhoria (`enhance`). */
+    enhancement?: Enhancement;
+    /** Avatar (só com a foto aprovada): PNG em data URL só com a pessoa do rosto em foco. */
+    avatar_image?: string;
+    avatar?: AvatarInfo;
+};
+type StreamOptions = {
+    /** Remover o fundo da foto capturada (serviço "validate_clean" contratado). */
+    clean?: boolean;
+    model?: "u2net" | "u2netp" | "birefnet-portrait";
+    device?: "cpu" | "gpu";
+    /** Limiares de validação (mesmos nomes de GET /v1/thresholds). */
+    thresholds?: Record<string, number>;
+    /**
+     * Melhorar a foto capturada antes de validar (serviço "validate_enhance" contratado). Os quadros ao
+     * vivo não passam pela melhoria. null/undefined = sem melhoria.
+     */
+    enhance?: EnhanceMethod | null;
+};
+/** Ticket de uso único (60 s) para o navegador abrir a webcam, emitido pelo SEU servidor. */
+type StreamTicket = {
+    ticket: string;
+    url: string;
+    expiresIn?: number;
+};
+/** Há quanto tempo os quadros seguidos estão aprovados e parados, e o alvo para capturar. */
+type Stable = {
+    ms: number;
+    needed: number;
+};
+type FaceGateErrorCode = "unauthorized" | "forbidden" | "token_month_limit" | "token_window_limit" | "bad_request" | "camera_denied" | "camera_unavailable" | "network" | "server";
+declare class FaceGateError extends Error {
+    code: FaceGateErrorCode;
+    status?: number | undefined;
+    /** Quando o limite renova (ISO), se a API informou. */
+    resetsAt?: string | undefined;
+    constructor(code: FaceGateErrorCode, message: string, status?: number | undefined, 
+    /** Quando o limite renova (ISO), se a API informou. */
+    resetsAt?: string | undefined);
+}
+
+/** Textos do componente (pt-BR). Passe `labels` no <FaceGate> para trocar qualquer um. */
+declare const DEFAULT_LABELS: {
+    start: string;
+    stop: string;
+    retry: string;
+    connecting: string;
+    searching: string;
+    hold: string;
+    allGood: string;
+    fix: string;
+    analyzing: string;
+    analyzingClean: string;
+    analyzingEnhance: string;
+    enhanced: string;
+    enhancedAi: string;
+    approved: string;
+    rejected: string;
+    cameraOff: string;
+    cameraHint: string;
+    insecure: string;
+    noCamera: string;
+    denied: string;
+    notFound: string;
+    busy: string;
+};
+type FaceGateLabels = typeof DEFAULT_LABELS;
+/** Critério reprovado (hard_fails da API) → orientação curta para quem está na câmera. */
+declare const FAIL_LABELS: Record<string, string>;
+declare function describeFails(codes?: string[]): string;
+
+type FaceGateCapture = {
+    /**
+     * Foto final: sem fundo (PNG) quando `clean`; senão a melhorada (JPEG) quando `enhance`; senão o quadro
+     * capturado (JPEG). Data URL ou blob URL.
+     */
+    image: string;
+    /** O quadro capturado, como enviado à API. */
+    frame: Blob;
+    result: ValidationResult;
+};
+type FaceGateProps = StreamOptions & {
+    /** Pede ao SEU servidor um ticket de uso único (ex.: fetch("/api/face-gate/ticket", { method: "POST" })). */
+    getTicket: () => Promise<StreamTicket>;
+    /** Foto capturada e validada (aprovada ou reprovada na validação final). */
+    onCapture?: (capture: FaceGateCapture) => void;
+    /** Cada quadro analisado ao vivo. */
+    onLive?: (result: ValidationResult) => void;
+    onError?: (error: FaceGateError) => void;
+    /** Liga a câmera ao montar (padrão: espera o clique em "Ligar câmera"). */
+    autoStart?: boolean;
+    /** Abertura animada do escudo ao ligar a câmera (padrão: true; desligada com prefers-reduced-motion). */
+    intro?: boolean;
+    /** Marca d'água do escudo no canto do vídeo (padrão: true). */
+    watermark?: boolean;
+    /**
+     * Enquadramento automático (padrão: true): a imagem aproxima e acompanha o rosto, mantendo-o no centro; a foto
+     * capturada é esse recorte e só sai com o rosto centralizado (tolerância de 8%). Ignora as tarjas pretas que
+     * algumas câmeras acrescentam.
+     */
+    autoFrame?: boolean;
+    /** Prévia espelhada, como um espelho (padrão: true). A foto enviada e a final não são espelhadas. */
+    mirror?: boolean;
+    labels?: Partial<FaceGateLabels>;
+    className?: string;
+    style?: CSSProperties;
+};
+/**
+ * Webcam com validação em tempo real do Face Gate: uma conexão WebSocket por sessão, mira que segue o
+ * rosto, captura automática só depois de ~0,8 s aprovado e parado, scanner sobre a foto até a resposta.
+ * Importe também "@beltec/face-gate/styles.css".
+ */
+declare function FaceGate({ getTicket, onCapture, onLive, onError, autoStart, intro, watermark, labels, className, style, clean, model, device, thresholds, enhance, autoFrame, mirror, }: FaceGateProps): react.JSX.Element;
+
+/**
+ * Escudo BelTec (Face Gate, uma solução BelTec): a faixa do escudo Belfort liga três pontos — a lente
+ * (a caixa que vê), a Central que entende e as pessoas que agem. Com `animated`, se desenha como na
+ * abertura da câmera do app (CSS em styles.css, classes .fg-emblem-*).
+ */
+declare function Emblem({ animated, className }: {
+    animated?: boolean;
+    className?: string;
+}): react.JSX.Element;
+
+/**
+ * Cliente do WebSocket /v1/stream do Face Gate (uma conexão por sessão de câmera).
+ *
+ * O navegador manda quadros JPEG (mensagens binárias) num ritmo fixo, o `max_fps` que a API informa no "ready":
+ * ela analisa sempre o mais novo e descarta os que ficaram para trás. Recebe o resultado de cada quadro
+ * analisado. A API só captura depois de ~0,8 s de quadros aprovados e parados (`stable`), avisa `captured`
+ * com o seq do melhor quadro e devolve a validação final.
+ */
+type StreamHandlers = {
+    /** `maxFps`: quantos quadros por segundo a API analisa (o ritmo para mandar os quadros). */
+    onReady?: (maxFps: number) => void;
+    onFrame?: (seq: number, result: ValidationResult, stable: Stable) => void;
+    onCaptured?: (seq: number) => void;
+    onFinal?: (seq: number, result: ValidationResult) => void;
+    /** Conexão encerrada sem ter sido pedida (`close()`). */
+    onError?: (error: FaceGateError) => void;
+};
+type FaceGateStream = {
+    /**
+     * Envia o quadro e devolve o seq dele (1, 2, 3… igual ao servidor); null se a conexão não está aberta ou o
+     * quadro anterior ainda está subindo.
+     */
+    sendFrame: (frame: Blob) => number | null;
+    configure: (options: StreamOptions) => void;
+    /** Recomeça depois de uma captura, na mesma conexão. */
+    reset: () => void;
+    close: () => void;
+};
+type WebSocketLike = new (url: string) => WebSocket;
+declare function openFaceGateStream(url: string, ticket: string, options: StreamOptions, handlers: StreamHandlers, WS?: WebSocketLike): FaceGateStream;
+
+export { type AvatarInfo, type AvatarLayout, type AvatarShape, DEFAULT_LABELS, Emblem, type EnhanceMethod, type Enhancement, FAIL_LABELS, type FaceBox, FaceGate, type FaceGateCapture, FaceGateError, type FaceGateErrorCode, type FaceGateLabels, type FaceGateProps, type FaceGateStream, type Stable, type StreamHandlers, type StreamOptions, type StreamTicket, type TokenUsage, type ValidationResult, type ValidationSummary, type ValidationWarning, describeFails, openFaceGateStream };