facegate-client

@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