Verifence JavaScript SDK

Official Node.js / TypeScript client for Verifence — the pre-send firewall for SMS verification. Zero dependencies (uses built-in fetch, Node ≥ 18).

npm install verifence

Your API key is a secret. Every call is server-to-server. Read it from an environment variable; never ship it in browser or mobile code.

Usage

import { Verifence, QuotaExceededError } from 'verifence';

const vf = new Verifence(process.env.VERIFENCE_KEY);

// Before you hand a message to Twilio/Vonage/etc:
const verdict = await vf.check('+14155552671', req.ip, { userId: 'u_123' });
//                                              ^ the END USER's IP, from your inbound request

if (!verdict.allow) {
  return res.status(429).json({ error: 'too_many_verification_requests' });
}

// ... send the SMS with your provider ...

// After the user enters the correct code:
await vf.confirm(req.ip);

Handle a spent quota:

try {
  await vf.check('+14155552671', req.ip);
} catch (err) {
  if (err instanceof QuotaExceededError) {
    console.log('quota resets at', err.resetsAt);
  }
}

API

• check(phone, clientIp, { userId?, requireMobile? }) → Decision ({ allow, reason, detail, degraded, ... })
• confirm(clientIp) → { recorded }
• stats() → account totals

A block is a resolved promise with allow: false — not a throw. Only bad input, auth, and quota (429) reject. Self-hosting? new Verifence(key, { baseUrl: 'https://verifence.internal' }).