@giouwur/biometric-sdk 1.0.0

package/README.md

@@ -0,0 +1,215 @@
+# @giouwur/biometric-sdk 🚀
+
+A comprehensive React SDK for biometric enrollment, identification, and verification. Built with **React**, **Zustand**, and **Tailwind CSS**.
+
+---
+
+## ✨ Features
+
+- **Multi-modal Support**: Fingerprints (Flat & Rolled), Face, Palm, and Iris.
+- **WebSocket Protocol**: Built-in communication with biometric devices.
+- **State Management**: Zero-config stores for biometric data and device status.
+- **Fully Customizable**:
+  - All UI components accept `className`.
+  - Custom themes via CSS variables.
+  - Low-level primitives to build your own capture flows.
+- **Type Safe**: Exported TypeScript interfaces for all components and stores.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @giouwur/biometric-sdk
+```
+
+---
+
+## 🛠️ Step-by-Step Setup
+
+### 1. Wrap with BiometricProvider
+
+Wrap your app (usually in `layout.tsx` or `App.tsx`) with the provider to share configuration.
+
+```tsx
+import { BiometricProvider } from "@giouwur/biometric-sdk";
+
+export default function Layout({ children }) {
+  return (
+    <BiometricProvider
+      config={{
+        wsUrl: "ws://127.0.0.1:5000/biometric", // Local device bridge
+        apiBaseUrl: "https://your-api.com/v1", // Optional for services
+        deviceId: "scanner_front_01", // Optional identifier
+      }}
+    >
+      {children}
+    </BiometricProvider>
+  );
+}
+```
+
+### 2. Basic Usage (Modules)
+
+Use pre-built modules for a "drop-in" enrollment experience.
+
+```tsx
+import { FingerEnrollModule, FaceEnrollModule } from "@giouwur/biometric-sdk";
+
+function EnrollmentPage() {
+  return (
+    <div className="space-y-8">
+      <FingerEnrollModule className="custom-card-style" />
+      <FaceEnrollModule />
+    </div>
+  );
+}
+```
+
+### 3. Automatic Documentation & Test Page
+
+You can automatically generate a comprehensive documentation and test page in your project by running:
+
+```bash
+npx @giouwur/biometric-sdk init
+```
+
+This will create `app/sdk-test/page.tsx` (or `src/app/sdk-test/page.tsx`) with all possible SDK examples and documentation.
+
+---
+
+---
+
+## 🎨 Customization
+
+### Style Overrides (Tailwind)
+
+All modules and UI components accept the `className` prop.
+
+```tsx
+<FingerEnrollModule className="!bg-slate-900 border-2 border-primary/20 rounded-2xl p-8" />
+```
+
+### Custom Themes (CSS Variables)
+
+Override global colors for your brand:
+
+```css
+:root {
+  --primary: 219 255 0; /* HSL values */
+  --primary-foreground: 0 0 0;
+  --success: 34 197 94;
+}
+```
+
+---
+
+## 🧠 State & Data Access
+
+### Accessing Stores
+
+The SDK uses **Zustand** for state. You can read data or trigger actions from anywhere.
+
+```tsx
+import { useEnrollmentStore } from "@giouwur/biometric-sdk";
+
+function Status() {
+  const { fingerprints, faces } = useEnrollmentStore();
+  const count = Object.keys(fingerprints).length;
+
+  return (
+    <div>
+      Capturados: {count} huellas y {faces.length} rostros.
+    </div>
+  );
+}
+```
+
+### Protocol Primitives
+
+Build your own capture modal instead of using the pre-built ones:
+
+```tsx
+import { useBiometricStore } from "@giouwur/biometric-sdk";
+
+function MyCapture() {
+  const { sendMessage, registerHandler } = useBiometricStore();
+
+  const handleCapture = () => {
+    // 1. Listen for responses
+    registerHandler("fingerprint_captured", (msg) => {
+      console.log("Imagen recibida (base64):", msg.image);
+    });
+
+    // 2. Trigger capture
+    sendMessage({
+      messageType: "capture_fingerprint",
+      position: "RIGHT_INDEX",
+    });
+  };
+
+  return <button onClick={handleCapture}>Iniciar Escaneo</button>;
+}
+```
+
+---
+
+## 🔌 API Integration Flow
+
+The SDK doesn't make API calls directly to your backend. It provides the data you need to send.
+
+1. **Load data**: `loadApplicantData(data)`
+2. **Capture**: User interacts with modules.
+3. **Build Payload**: `buildEnrollmentRequest()` returns a standardized object.
+
+```tsx
+const store = useEnrollmentStore.getState();
+
+// Al finalizar el proceso
+const payload = store.buildEnrollmentRequest();
+
+await fetch("/api/enroll", {
+  method: "POST",
+  body: JSON.stringify(payload),
+});
+```
+
+---
+
+## 🖼️ Image Utilities
+
+Includes helpers for common biometric image tasks:
+
+```tsx
+import {
+  getImageSrcForDisplay, // Adds data:image/png;base64,... header
+  normalizeImageForStorage, // Removes headers for storage
+  base64toBlob, // Convert for FormData uploads
+} from "@giouwur/biometric-sdk";
+```
+
+---
+
+## 📐 Exported Components & Types
+
+### UI Primitives
+
+- `<Button />`, `<Card />`, `<Input />`, `<Select />`
+- `<Modal />`, `<BiometricSlot />`, `<StatusChip />`
+
+### Types (Full TS Support)
+
+```tsx
+import type {
+  BiometricItem,
+  EnrollmentState,
+  BiometricState,
+  BiometricSlotProps,
+} from "@intell/biometric-sdk";
+```
+
+---
+
+## 📜 License
+
+MIT © [Intelli Biometrics]

package/bin/init.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+async function init() {
+  console.log('🚀 Inicializando página de prueba de @giouwur/biometric-sdk...');
+
+  const cwd = process.cwd();
+  
+  // 1. Detectar directorio de destino (Next.js App Router)
+  let appDir = '';
+  if (fs.existsSync(path.join(cwd, 'src', 'app'))) {
+    appDir = path.join(cwd, 'src', 'app');
+  } else if (fs.existsSync(path.join(cwd, 'app'))) {
+    appDir = path.join(cwd, 'app');
+  } else {
+    console.error('❌ No se detectó un directorio "app" o "src/app" (Next.js App Router).');
+    console.log('Asegúrate de ejecutar este comando en la raíz de tu proyecto Next.js.');
+    process.exit(1);
+  }
+
+  const targetDir = path.join(appDir, 'sdk-test');
+  const targetFile = path.join(targetDir, 'page.tsx');
+
+  // 2. Crear carpeta si no existe
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  // 3. Copiar template
+  const templatePath = path.join(__dirname, '..', 'templates', 'test-page.tsx');
+  
+  if (!fs.existsSync(templatePath)) {
+    console.error('❌ Error interno: No se encontró el template en ' + templatePath);
+    process.exit(1);
+  }
+
+  try {
+    const content = fs.readFileSync(templatePath, 'utf8');
+    fs.writeFileSync(targetFile, content);
+    console.log(`✅ ¡Éxito! Página creada en: ${targetFile}`);
+    console.log('\nAhora puedes visitar: http://localhost:3000/sdk-test');
+  } catch (err) {
+    console.error('❌ Error al copiar el archivo:', err.message);
+    process.exit(1);
+  }
+}
+
+init();