npm package: @giouwur/biometric-sdk
Description: SDK for Intelli Biometric components and logic
Latest version: 1.0.0

# @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]