open-index/open-npm huggingface dataset:
npm package: @surtai/faceguard
Description: Official SDK for FaceGuard — face verification for secure login
Latest version: 0.1.0

# @surtai/faceguard

Official SDK for [FaceGuard](https://faceguard.surt.com) — face verification for secure login.

## Install

```bash
npm install @surtai/faceguard
```

## Quick Start

### Callback style

```typescript
import { FaceGuard } from '@surtai/faceguard';

const fg = FaceGuard.init({
  token: 'PORTAL_TOKEN', // from your backend
  onSuccess: (result) => console.log('Approved', result.confidence),
  onFailed: (result) => console.log('Rejected', result.confidence),
  onCancel: () => console.log('Canceled'),
  onError: (error) => console.log('Error', error.message),
});

// cleanup
fg.destroy();
```

### Async/await

```typescript
const result = await FaceGuard.verify({ token: 'PORTAL_TOKEN' });

if (result.status === 'approved') {
  // grant access
} else if (result.status === 'rejected') {
  // deny access
}
```

## Options

| Option      | Type                    | Required | Default                      | Description                                |
| ----------- | ----------------------- | -------- | ---------------------------- | ------------------------------------------ |
| `token`     | `string`                | Yes      | —                            | Portal JWT from your backend               |
| `baseUrl`   | `string`                | No       | `https://faceguard.surt.com` | Override for non-prod environments         |
| `mode`      | `'mobile' \| 'desktop'` | No       | Auto-detect                  | Force mobile (camera) or desktop (QR) flow |
| `container` | `HTMLElement`           | No       | `document.body`              | DOM element to mount the overlay into      |
| `lang`      | `string`                | No       | Browser default              | `'en'`, `'es'`, `'pt'`, or `'de'`          |

### Callbacks (FaceGuard.init)

| Callback    | Payload                  | Description                 |
| ----------- | ------------------------ | --------------------------- |
| `onReady`   | —                        | FaceGuard iframe loaded     |
| `onSuccess` | `{ confidence: number }` | Verification passed (0-100) |
| `onFailed`  | `{ confidence: number }` | Verification failed (0-100) |
| `onCancel`  | —                        | User closed FaceGuard       |
| `onError`   | `{ message: string }`    | Something went wrong        |

### Result (FaceGuard.verify)

```typescript
interface FaceGuardVerifyResult {
  status: 'approved' | 'rejected' | 'canceled' | 'error';
  confidence?: number;
  error?: string;
}
```

## How It Works

The SDK creates an iframe overlay pointing to the FaceGuard app. On mobile, it goes fullscreen with the camera flow. On desktop, it shows a phone-shaped modal with a QR code for phone handoff (or "Verify Here" for webcam).

All communication happens via `postMessage`. The SDK handles the event mapping and cleanup automatically.

## Requirements

- HTTPS (camera requires secure context)
- A valid portal token from your backend

## License

Apache 2.0