veris-node-sdk

Node.js SDK for Veris Compare - server-side face similarity API.

Send two images from your backend and get a 0-100 match score. No images are stored - deleted immediately after every request.

Requires a Regular or Pro plan. Get a free sandbox key at https://verisinfra.com.

---

Installation

npm install @verisinfra/node-sdk

---

Quick start

const { VerisCompare } = require('@verisinfra/node-sdk');

const client = new VerisCompare({
  apiKey: process.env.VERIS_API_KEY,
});

const result = await client.compareFiles({
  captured: './selfie.jpg',
  reference: './id_photo.jpg',
});

console.log(result.match);       // true or false
console.log(result.confidence);  // 0-100

---

Authentication

const client = new VerisCompare({
  apiKey: process.env.VERIS_API_KEY,
});

Use your production license key. Sandbox keys work for testing (limited to 10 lifetime Compare calls).

---

Comparing images

From file paths

const result = await client.compareFiles({
  captured: '/path/to/selfie.jpg',
  reference: '/path/to/id_photo.jpg',
});

From base64 strings

const result = await client.compareBase64({
  capturedB64: fs.readFileSync('./selfie.jpg').toString('base64'),
  referenceB64: fs.readFileSync('./id.jpg').toString('base64'),
});

From buffers

const result = await client.compareBuffers({
  captured: fs.readFileSync('./selfie.jpg'),
  reference: fs.readFileSync('./id.jpg'),
});

---

Response

{
  match: true,
  confidence: 73.53,    // 0-100, above ~70 is a strong match
  distance: 0.18,
  threshold: 0.68,
  engine: 'veris-compare-v1',
  environment: 'production',
  quotaRemaining: 742
}

confidence = (1 - distance / threshold) * 100, clamped to 0-100.

---

Checking quota

const quota = await client.getQuota();
console.log(quota.remaining);  // calls remaining this cycle
console.log(quota.resetsAt);   // ISO date of next billing cycle reset

---

Error handling

const { VerisCompare, VerisError } = require('@verisinfra/node-sdk');

try {
  const result = await client.compareFiles({ captured, reference });
} catch (err) {
  if (err instanceof VerisError) {
    switch (err.code) {
      case 'FACE_NOT_DETECTED':
        // No face in one or both images
        break;
      case 'QUOTA_EXCEEDED':
        // Monthly cap and overage cap both reached
        break;
      case 'SUBSCRIPTION_INACTIVE':
        // Plan has lapsed
        break;
      case 'COMPARE_NOT_IN_PLAN':
        // Starter plan does not include Compare
        break;
      case 'RATE_LIMITED':
        // Too many requests per minute
        break;
      case 'SANDBOX_COMPARE_LIMIT_REACHED':
        // 10 sandbox calls used - upgrade at verisinfra.com
        break;
    }
  }
}

---

Rate limits

Plan	Requests/min	Burst
Regular	10	20
Pro	30	60

The SDK retries on RATE_LIMITED with exponential backoff (2 retries by default).

---

Compare quotas

Plan	Monthly quota	Overage rate	Overage cap
Regular	10,000	$0.02/call	$50/month
Pro	30,000	$0.01/call	$80/month

---

Express.js integration

const express = require('express');
const multer = require('multer');
const { VerisCompare, VerisError } = require('@verisinfra/node-sdk');

const app = express();
const upload = multer({ storage: multer.memoryStorage() });
const veris = new VerisCompare({ apiKey: process.env.VERIS_API_KEY });

app.post('/verify-face', upload.fields([
  { name: 'selfie', maxCount: 1 },
  { name: 'id_photo', maxCount: 1 },
]), async (req, res) => {
  try {
    const result = await veris.compareBuffers({
      captured: req.files['selfie'][0].buffer,
      reference: req.files['id_photo'][0].buffer,
    });
    res.json({ verified: result.match, confidence: result.confidence });
  } catch (err) {
    if (err instanceof VerisError && err.code === 'FACE_NOT_DETECTED') {
      return res.status(422).json({ error: 'No face detected' });
    }
    res.status(500).json({ error: 'Verification failed' });
  }
});

---

Image requirements

• Format: JPEG or PNG
• Max size: 5MB per image
• Face clearly visible, well lit, unobscured
• Minimum face size: 150x150px within the frame

---

TypeScript

Full types included:

import { VerisCompare, CompareResult, VerisError } from '@verisinfra/node-sdk';

const client = new VerisCompare({ apiKey: process.env.VERIS_API_KEY! });
const result: CompareResult = await client.compareFiles({ captured, reference });

---

Examples

See examples/standalone-compare.js for standalone usage patterns.

Changelog

See CHANGELOG.md.

License

MIT - see LICENSE.