@simprints/simface-sdk 0.1.0

package/README.md

@@ -0,0 +1,256 @@
+# SimFace SDK
+
+SimFace SDK provides facial recognition for web-based KYC workflows. It is a drop-in Web Component and JavaScript API that handles camera capture, face quality validation, and communication with the SimFace backend.
+
+Works in: all modern browsers, WhatsApp in-app browser, and mobile WebViews.
+
+This repository is the public frontend SDK and demo repo for SimFace. For frontend architecture and contributor setup, see [docs/architecture.md](docs/architecture.md) and [docs/development.md](docs/development.md).
+
+The backend API, infrastructure, and TensorFlow Lite runtime live in the separate private backend repository.
+
+In standard browsers, the SDK uses an in-page camera flow powered by `getUserMedia()`. In WhatsApp, it falls back to the native capture handoff because that path is more reliable in the in-app browser.
+
+## Quick Start
+
+### 1. Include the SDK
+
+Via npm or a private registry after publishing the package:
+```bash
+npm install @simprints/simface-sdk
+```
+```javascript
+import { enroll, verify } from '@simprints/simface-sdk';
+```
+
+Directly in a webpage from the latest GitHub release:
+
+1. Open the latest GitHub release for this repository.
+2. Download the `simface-sdk-<version>-dist.tgz` asset.
+3. Extract the archive and copy `dist/simface-sdk.js` into your app's static assets, for example `public/vendor/simface-sdk.js`.
+4. Reference the copied file from your page:
+
+```html
+<script type="module" src="/vendor/simface-sdk.js"></script>
+```
+
+From this repository:
+```bash
+npm install
+npm run build
+```
+
+Then publish or serve the generated files from `dist/`.
+The generated library files are:
+
+- `dist/simface-sdk.js` (ES module)
+- `dist/simface-sdk.umd.cjs` (UMD/CommonJS build)
+
+### 2. Configure
+
+```javascript
+const config = {
+  apiUrl: 'https://your-simface-api.run.app',
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key',
+};
+```
+
+### 3. Enroll a User
+
+```javascript
+import { enroll } from '@simprints/simface-sdk';
+
+const result = await enroll(config, 'unique-user-id');
+
+if (result.success) {
+  console.log('User enrolled successfully!');
+} else if (result.alreadyEnrolled) {
+  console.log('User is already enrolled - use verify() instead.');
+} else {
+  console.log('Enrollment failed:', result.message);
+}
+```
+
+### 4. Verify a User
+
+```javascript
+import { verify } from '@simprints/simface-sdk';
+
+const result = await verify(config, 'unique-user-id');
+
+if (result.match) {
+  console.log(`Identity verified! (score: ${result.score})`);
+} else if (result.notEnrolled) {
+  console.log('User not enrolled - use enroll() first.');
+} else {
+  console.log(`Verification failed (score: ${result.score}, threshold: ${result.threshold})`);
+}
+```
+
+## Try the local demo
+
+Build the SDK at the repository root, then run the demo:
+
+```bash
+npm install
+npm run build
+
+cd demo
+npm install
+npm run dev
+```
+
+The demo runs at `http://localhost:4173` and consumes the built SDK artifact from `dist/`.
+
+## Web Component
+
+For more control over the UI, use the `<simface-capture>` Web Component directly:
+
+```html
+<simface-capture label="Take a selfie for verification"></simface-capture>
+
+<script type="module">
+  import '@simprints/simface-sdk';
+  import { SimFaceAPIClient } from '@simprints/simface-sdk';
+
+  const captureEl = document.querySelector('simface-capture');
+  const client = new SimFaceAPIClient({
+    apiUrl: 'https://your-simface-api.run.app',
+    projectId: 'your-project-id',
+    apiKey: 'your-api-key',
+  });
+
+  captureEl.addEventListener('simface-captured', async (e) => {
+    const { imageBlob } = e.detail;
+    const result = await client.verify('user-123', imageBlob);
+    console.log('Verify result:', result);
+  });
+
+  captureEl.addEventListener('simface-cancelled', () => {
+    console.log('User cancelled capture');
+  });
+
+  captureEl.addEventListener('simface-error', (e) => {
+    console.error('Capture error:', e.detail.error);
+  });
+</script>
+```
+
+### Component Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `label` | String | `"Take a selfie"` | Instructional text shown on the capture button |
+
+### Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `simface-captured` | `{ imageBlob: Blob }` | Fires when a quality-checked face image is confirmed |
+| `simface-cancelled` | - | Fires when the user cancels the capture flow |
+| `simface-error` | `{ error: string }` | Fires on capture/detection errors |
+
+## API Reference
+
+### `enroll(config, clientId): Promise<EnrollResult>`
+
+Opens the camera, captures a face image with quality validation, and enrolls the user.
+
+Parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config` | `SimFaceConfig` | SDK configuration (`apiUrl`, `projectId`, `apiKey`) |
+| `clientId` | `string` | Unique identifier for the user |
+
+Returns `EnrollResult`:
+```typescript
+{
+  success: boolean;
+  clientId: string;
+  message?: string;
+  alreadyEnrolled?: boolean;
+}
+```
+
+### `verify(config, clientId): Promise<VerifyResult>`
+
+Opens the camera, captures a face image, and verifies against the enrolled face.
+
+Parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config` | `SimFaceConfig` | SDK configuration (`apiUrl`, `projectId`, `apiKey`) |
+| `clientId` | `string` | Unique identifier for the user |
+
+Returns `VerifyResult`:
+```typescript
+{
+  match: boolean;
+  score: number;
+  threshold: number;
+  message?: string;
+  notEnrolled?: boolean;
+}
+```
+
+### `SimFaceConfig`
+
+```typescript
+{
+  apiUrl: string;
+  projectId: string;
+  apiKey: string;
+}
+```
+
+## Backend API Endpoints
+
+For clients integrating directly with the REST API:
+
+### `POST /api/v1/auth/validate`
+Validate API credentials.
+
+Body: `{ "projectId": "...", "apiKey": "..." }`
+Response: `{ "valid": true, "projectId": "...", "name": "..." }`
+
+### `POST /api/v1/enroll`
+Enroll a new user.
+
+Body: multipart form data with fields `projectId`, `apiKey`, `clientId`, `image`.
+Response: `{ "success": true, "clientId": "..." }`
+
+### `POST /api/v1/verify`
+Verify a user against their enrollment.
+
+Body: multipart form data with fields `projectId`, `apiKey`, `clientId`, `image`.
+Response: `{ "match": true, "score": 0.85, "threshold": 0.6 }`
+
+### `GET /api/v1/health`
+Health check endpoint.
+
+Response: `{ "status": "ok" }`
+
+## Face Quality Checks
+
+The SDK automatically performs these checks on captured images before submission:
+
+1. Face presence - at least one face must be detected.
+2. Single face - only one face should be in the frame.
+3. Face size - face must not be too close or too far.
+4. Centering - face must be approximately centered in the frame.
+
+If a check fails, the user is prompted with specific guidance and asked to retake the photo.
+
+## Browser Compatibility
+
+| Browser | Camera Capture | Face Detection |
+|---------|---------------|----------------|
+| Chrome (Android/Desktop) | Yes | Yes |
+| Safari (iOS/Desktop) | Yes | Yes |
+| WhatsApp in-app browser | Yes (via native camera) | Yes |
+| Firefox | Yes | Yes |
+| Samsung Internet | Yes | Yes |
+
+> Note: In WhatsApp's in-app browser, the camera opens via the device's native camera app rather than an in-browser preview. Face quality checks run after the photo is taken.