@voiceidvault/sdk

VoiceIDVault JavaScript / TypeScript SDK — voice biometric authentication.

Installation

npm install @voiceidvault/sdk

Quick start

import { VoiceIDVaultClient } from '@voiceidvault/sdk';

const client = new VoiceIDVaultClient({ apiKey: process.env.VOICEIDVAULT_API_KEY! });

// ── 1. Enroll a new user ──────────────────────────────────────────────────────
const session = await client.initEnrollment('user-123', '+12125551234');

// User enters the OTP they received via SMS
await client.verifySmsOtp(session.sessionId, 'user-123', '654321');

// Capture face (browser Blob from canvas/video)
const faceResult = await client.enrollFace(session.sessionId, 'user-123', faceImageBlob);
console.log('Face enrolled, next step:', faceResult.nextStep);

// Capture voice (browser Blob from MediaRecorder)
const voiceResult = await client.enrollVoice(session.sessionId, 'user-123', audioBlob, {
  phrase: 'my voice is my password',
  duration: 5,
});
console.log('Voice quality:', voiceResult.qualityScore);

// Complete enrollment — creates the biometric vault
const enrollment = await client.completeEnrollment(session.sessionId, 'user-123');
console.log('Vault ID:', enrollment.vaultId);
console.log('Trust score:', enrollment.trustScore);

// ── 2. Authenticate an existing user ─────────────────────────────────────────
const auth = await client.authenticateVoice(audioBlob, {
  userId: 'user-123',        // optional — omit for open-set search
  confidenceThreshold: 0.85,
});

if (auth.verified) {
  console.log('Authenticated! Confidence:', auth.confidence);
} else {
  console.log('Authentication failed:', auth.deepfakeAnalysis);
}

// ── 3. GDPR right-to-erasure ──────────────────────────────────────────────────
const deletion = await client.requestDeletion('erasure', {
  reason: 'User requested account deletion',
  priority: 'normal',
});
console.log('Deletion deadline:', deletion.request.responseDeadline);

Error handling

import {
  VoiceIDVaultClient,
  AuthenticationError,
  EnrollmentError,
  RateLimitError,
  NetworkError,
} from '@voiceidvault/sdk';

try {
  await client.authenticateVoice(audioBlob);
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Bad API key or forbidden:', err.message);
  } else if (err instanceof RateLimitError) {
    console.error('Rate limited, retry after:', err.retryAfter, 's');
  } else if (err instanceof EnrollmentError) {
    console.error('Enrollment error code:', err.code);
  } else if (err instanceof NetworkError) {
    console.error('Network failure:', err.message);
  }
}

Configuration

| Option | Type | Default | Description | |-----------|----------|----------------------------|------------------------------------| | apiKey | string | required | Your VoiceIDVault API key | | baseUrl | string | https://voiceidvault.com | Override the API base URL | | timeout | number | 30000 | Request timeout in milliseconds | | retries | number | 3 | Retry attempts for 5xx / timeouts |

License

MIT