# @voiceidvault/sdk

VoiceIDVault JavaScript / TypeScript SDK — voice biometric authentication.

## Installation

```bash
npm install @voiceidvault/sdk
```

## Quick start

```typescript
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

```typescript
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