AuraGyt AI JavaScript/TypeScript SDK

A browser-based SDK for AuraGyt AI biometric authentication platform. This SDK provides easy-to-use APIs for face recognition, liveness detection, and authentication in web applications.

Installation

npm install auragyt-ai-sdk

Quick Start

import { AuraGytSDK } from 'auragyt-ai-sdk';

// Initialize SDK
const sdk = new AuraGytSDK({
  baseURL: 'https://api.auragyt.com',
  apiKey: 'your-api-key', // Optional, can use JWT tokens instead
});

// Login
const tokens = await sdk.auth.login('[email protected]', 'password');

// Enroll face
const video = document.getElementById('video') as HTMLVideoElement;
await sdk.faceCapture.setupVideo(video);
const enrollment = await sdk.auth.enrollFace(video);

// Verify face
const verification = await sdk.auth.verifyFace(video);

Features

• Face Capture: Camera access, face detection, and image quality validation
• Liveness Detection: Challenge-response liveness checks (blink, head movement)
• Authentication: User registration, login, face verification, and session management
• WebAuthn/FIDO2: Passwordless authentication using passkeys (hardware-backed credentials)
• TypeScript Support: Full TypeScript definitions included
• Error Handling: Comprehensive error handling with retry logic
• Token Management: Automatic token refresh and localStorage persistence

API Reference

SDK Configuration

interface SDKConfig {
  apiKey?: string;        // API key for authentication (optional)
  baseURL?: string;       // API base URL (default: 'http://localhost:8000')
  timeout?: number;        // Request timeout in ms (default: 30000)
  retries?: number;        // Number of retries (default: 3)
  retryDelay?: number;     // Retry delay in ms (default: 1000)
}

Authentication

Login

const tokens = await sdk.auth.login(email, password);
// Returns: { accessToken, refreshToken, tokenType, expiresIn }

Register

const user = await sdk.auth.register(email, password);

Logout

await sdk.auth.logout();

Get Current User

const user = await sdk.auth.getCurrentUser();

Face Capture

Setup Camera

const video = document.getElementById('video') as HTMLVideoElement;
await sdk.faceCapture.setupVideo(video, {
  width: 1280,
  height: 720,
  facingMode: 'user',
});

Capture Face

const result = await sdk.faceCapture.captureFace(video, {
  qualityThreshold: 0.7,
  maxAttempts: 3,
});
// Returns: { image, faces, qualityScore }

Detect Faces

const faces = await sdk.faceCapture.detectFaces(imageBase64);

Stop Camera

sdk.faceCapture.stopCamera();

Liveness Detection

Perform Liveness Check

const stream = await sdk.faceCapture.requestCamera();
const result = await sdk.liveness.performLivenessCheck(stream, {
  challengeType: 'blink', // or 'head_movement' or 'auto'
  duration: 3000,
});
// Returns: { isLive, livenessScore, challengeType, spoofingDetected, spoofingScore }

Get Challenge Instructions

const instructions = sdk.liveness.getChallengeInstructions('blink');

Face Enrollment

const enrollment = await sdk.auth.enrollFace(video, 0.7);
// Returns: { templateId, qualityScore, success }

Face Verification

const verification = await sdk.auth.verifyFace(video, 0.6);
// Returns: { isMatch, similarityScore, threshold }

WebAuthn/FIDO2

Check Availability

if (AuraGytSDK.WebAuthn.isAvailable()) {
  // WebAuthn is supported
}

Register Credential

// Complete registration flow
const result = await sdk.webauthn.register({
  deviceName: 'My Device',
  platform: 'web', // or 'ios', 'android'
  useSecureEnclave: false
});
// Returns: { credential_id, device_name, message }

Authenticate with WebAuthn

// Complete authentication flow
const tokens = await sdk.webauthn.authenticate('[email protected]');
// Returns: { access_token, refresh_token, token_type }

List Credentials

const response = await sdk.webauthn.listCredentials();
// Returns: { credentials: [...] }

Revoke Credential

await sdk.webauthn.revokeCredential(credentialId);

List Hardware-Backed Credentials

const response = await sdk.webauthn.listHardwareBackedCredentials();
// Returns credentials stored in Secure Enclave/Keystore

Error Handling

The SDK provides custom error classes:

import {
  AuraGytError,
  NetworkError,
  AuthenticationError,
  ValidationError,
  ServiceUnavailableError,
} from 'auragyt-ai-sdk';

try {
  await sdk.auth.login(email, password);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.message);
  }
}

Examples

Complete Enrollment Flow

import { AuraGytSDK } from 'auragyt-ai-sdk';

const sdk = new AuraGytSDK({
  baseURL: 'https://api.auragyt.com',
});

async function enrollUser() {
  try {
    // 1. Login
    await sdk.auth.login('[email protected]', 'password');

    // 2. Setup camera
    const video = document.getElementById('video') as HTMLVideoElement;
    await sdk.faceCapture.setupVideo(video);

    // 3. Capture and enroll face
    const enrollment = await sdk.auth.enrollFace(video, 0.7);
    console.log('Face enrolled:', enrollment.templateId);

    // 4. Cleanup
    sdk.faceCapture.stopCamera();
  } catch (error) {
    console.error('Enrollment failed:', error);
  }
}

Face Verification Flow

async function verifyUser() {
  try {
    // 1. Setup camera
    const video = document.getElementById('video') as HTMLVideoElement;
    await sdk.faceCapture.setupVideo(video);

    // 2. Perform liveness check
    const stream = await sdk.faceCapture.requestCamera();
    const liveness = await sdk.liveness.performLivenessCheck(stream, {
      challengeType: 'blink',
      duration: 3000,
    });

    if (!liveness.isLive) {
      throw new Error('Liveness check failed');
    }

    // 3. Verify face
    const verification = await sdk.auth.verifyFace(video, 0.6);

    if (verification.isMatch) {
      console.log('Face verified! Similarity:', verification.similarityScore);
    } else {
      console.log('Face verification failed');
    }

    // 4. Cleanup
    sdk.faceCapture.stopCamera();
  } catch (error) {
    console.error('Verification failed:', error);
  }
}

Browser Compatibility

• Chrome/Edge: Full support
• Firefox: Full support
• Safari: Full support (iOS 11+)
• Opera: Full support

Requirements

• Modern browser with WebRTC support
• HTTPS (required for camera access in production)
• Camera permissions

License

MIT

Support

For issues and questions, please visit: https://github.com/auragyt/auragyt-app