The Node.js SDK Is Here.
Zero Dependencies, Full TypeScript.

Why a Node.js SDK

The Python SDK was built for ourselves — our Telegram bot needed a clean way to talk to the FaceVault API. But not everyone writes Python. Express servers, Next.js backends, Cloudflare Workers, Telegram bots on grammY — the Node.js ecosystem is where a lot of verification integrations will live.

We wanted the Node SDK to feel native to TypeScript developers. Not a port. Not a wrapper around axios with a few type annotations bolted on. A proper, idiomatic package that uses the language's strengths: interfaces instead of classes for data, native fetch instead of HTTP libraries, async/await everywhere because that's what JavaScript already is.

Zero Dependencies

The Python SDK depends on httpx. We needed it for sync+async support, and it's a reasonable single dependency. But Node 18+ has globalThis.fetch built in, and node:crypto has everything we need for HMAC-SHA256. So the Node SDK has zero runtime dependencies.

Zero dependencies means:

Design Decisions

What It Looks Like

Install it:

npm install facevault

Create a verification session:

import { FaceVaultClient } from "facevault";

const client = new FaceVaultClient({ apiKey: "fv_live_your_api_key" });

// Create a verification session
const session = await client.createSession("user-123");
console.log(session.webappUrl);   // send this to your user

// Or require proof of address for this session
const session2 = await client.createSession("user-456", {
  requirePoa: true,
});

// Check results — trust engine gives you a single score
const status = await client.getSession(session.sessionId);
console.log(status.trustScore);      // 0-100
console.log(status.trustDecision);   // "accept", "review", "reject"
console.log(status.faceMatchPassed);

Handle errors:

import { FaceVaultClient, AuthError, NotFoundError, RateLimitError } from "facevault";

const client = new FaceVaultClient({ apiKey: "fv_live_your_api_key" });

try {
  const status = await client.getSession("nonexistent");
} catch (err) {
  if (err instanceof AuthError) console.log("Invalid API key");
  if (err instanceof NotFoundError) console.log("Session not found");
  if (err instanceof RateLimitError) console.log("Too many requests");
}

That's it. Same surface area as the Python SDK: one client, three models, four exceptions, two webhook helpers.

Webhook Verification

Webhook payloads are signed with HMAC-SHA256. The SDK re-canonicalises the JSON (sorted keys, compact format) before computing the HMAC, matching what the server does. Signature comparison uses crypto.timingSafeEqual() to prevent timing attacks.

import express from "express";
import { verifySignature, parseEvent } from "facevault";

const app = express();

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-signature"] as string;

  if (!verifySignature(req.body, sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send("Invalid signature");
  }

  const event = parseEvent(req.body);

  // Trust engine decision — one field, no guesswork
  if (event.trustDecision === "accept") {
    console.log(`User ${event.externalUserId} verified! Score: ${event.trustScore}`);
  } else if (event.trustDecision === "review") {
    console.log(`Manual review needed — score: ${event.trustScore}`);
  } else {
    console.log(`Rejected — sanctions hit: ${event.sanctionsHit}`);
  }

  res.sendStatus(200);
});

Parity with Python

Both SDKs share the same API surface. If you've used one, you know the other.

The naming difference is just convention — snake_case for Python, camelCase for JavaScript. The behaviour is identical. Same endpoints, same error mapping, same HMAC canonicalisation, same security guarantees.

What's New in 1.0.0

v0.1 shipped the essentials. v1.0.0 ships everything. The SDK now exposes every signal the FaceVault engine produces — and we security-audited the whole thing before flipping the repos to public.

The upgrade is non-breaking. Every new field is optional with a sensible default. Your existing code keeps working — you just get richer data when you're ready for it.