@facegate/client

Core FaceGate client SDK. Zero framework dependencies. Handles camera access, liveness challenges, face verification, and QR code fallback.

Install

npm install @facegate/client

Quick Start — Supabase App

Most developers should use @facegate/react + @facegate/supabase instead. This package is for non-React apps or custom UI implementations.

import { FaceGateClient, Camera, LivenessOrchestrator } from '@facegate/client'

// 1. Create client
const fg = new FaceGateClient({
  apiKey: 'fg_live_your_api_key_here',
  provider: 'supabase',
})

// 2. Open camera
const camera = new Camera()
await camera.open()

// 3. Run liveness challenge + verification
const orchestrator = new LivenessOrchestrator({
  getChallenge: () => fg.getChallenge(),
  verify: (params) => fg.verify(params),
  captureFrame: () => camera.captureFrame(),
  captureFrames: (count, interval) => camera.captureFrames(count, interval),
  onStateChange: (state) => {
    // Update your UI based on state.phase:
    // 'requesting_challenge' | 'performing' | 'capturing_frames' | 'submitting' | 'passed' | 'failed'
    console.log('Liveness state:', state.phase)
  },
  challengeTimeout: 30_000,
})

const result = await orchestrator.run()

if (result.matched && result.verification_token) {
  // 4. Create Supabase session
  const session = await fg.createSession(result.verification_token)
  console.log('Authenticated:', session.user.name)
  // session.provider_session contains the Supabase access_token + refresh_token
}

// 5. Cleanup
camera.close()

QR Code Fallback (No Camera)

When Camera.isAvailable() returns false, show a QR code instead:

import { FaceGateClient, QRGenerator, HandoffConnection } from '@facegate/client'

const fg = new FaceGateClient({ apiKey: 'fg_live_...', provider: 'supabase' })

// 1. Create handoff session (call your server or FaceGate API)
const handoff = await fg.createHandoffSession()

// 2. Display QR code
const qrDataUrl = await QRGenerator.generateDataUrl(handoff.verify_url)
document.getElementById('qr').src = qrDataUrl

// 3. Listen for phone to complete auth
const conn = new HandoffConnection(handoff.ws_url)
conn.onMessage((msg) => {
  if (msg.type === 'authenticated') {
    console.log('Phone auth complete:', msg.session.user.name)
  }
})
conn.connect()

API Reference

FaceGateClient

| Method | Description | |--------|-------------| | getChallenge() | Get a liveness challenge (blink, turn, nod) | | verify({ image, challengeFrames, nonce }) | Verify face + liveness | | createSession(verificationToken) | Create auth provider session | | enroll({ name, images, role? }) | Enroll a face (admin) | | health() | Check server health |

Camera

| Method | Description | |--------|-------------| | Camera.isAvailable() | Check if camera API exists | | Camera.listDevices() | List video input devices | | camera.open(deviceId?) | Request camera permission + start stream | | camera.captureFrame() | Capture a single JPEG frame | | camera.captureFrames(count, interval) | Capture multiple frames | | camera.close() | Release the camera |

Error Types

| Error | Code | Retryable | |-------|------|-----------| | CameraPermissionDenied | CAMERA_PERMISSION_DENIED | No | | CameraUnavailable | CAMERA_UNAVAILABLE | No | | LivenessTimeout | LIVENESS_TIMEOUT | Yes | | LivenessFailed | LIVENESS_FAILED | Yes | | VerificationFailed | VERIFICATION_FAILED | Yes | | ApiError | API_ERROR | 5xx/429 only | | NetworkError | NETWORK_ERROR | Yes | | InvalidApiKey | INVALID_API_KEY | No |