@avetrust/node

SDK Node.js officiel d'AveTrust — vérification d'identité de niveau forensique (eKYC). Sessions de vérification, résultats, webhooks signés, et sandbox intégré.

Installation

npm i @avetrust/node

Node ≥ 18 (utilise fetch et crypto natifs, zéro dépendance runtime).

Démarrage rapide

import { AveTrust } from "@avetrust/node";

const av = new AveTrust("sk_test_…"); // clé test → sandbox (gratuit, déterministe)

// 1. Créer une vérification et envoyer le lien hébergé au client
const v = await av.verifications.create({
  checks: ["DOCUMENT", "LIVENESS", "FACE_MATCH"],
  callbackUrl: "https://mon-app/kyc/webhook",
  simulate: "approved", // ignoré hors sandbox
});

await av.verifications.sendLink(v.id, {
  channel: "EMAIL",
  to: "[email protected]",
  link: `https://verify-test.avetrust.net/s/${v.token}`,
});

Recevoir le résultat (webhook)

Vérifiez toujours la signature avant de faire confiance à un événement :

import express from "express";
const app = express();

// Corps BRUT indispensable pour la signature
app.post("/kyc/webhook", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = av.webhooks.constructEvent(
      req.body, // Buffer brut
      req.header("X-AveTrust-Signature"),
      process.env.AVETRUST_WEBHOOK_SECRET!
    );
  } catch {
    return res.status(400).send("signature invalide");
  }

  if (!event.livemode) return res.sendStatus(200); // événement sandbox → ignoré en prod

  if (event.data.decision?.outcome === "APPROVED") {
    activateAccount(event.data.externalUserId);
  }
  res.sendStatus(200);
});

Suivi en temps réel (SSE, sans polling)

const { token } = await av.verifications.create({ checks: ["DOCUMENT", "LIVENESS"] });

const result = await av.verifications.stream(token, {
  onProgress: (e) => console.log("étape :", e.step),
  onStatus:   (e) => console.log("statut :", e.status),
});
console.log("verdict :", result.status); // APPROVED | REVIEW | REJECTED

Le serveur pousse les mises à jour ; la promesse se résout au verdict final. Passez un signal (AbortSignal) pour interrompre.

Sandbox

Une clé sk_test_… place tout en mode bac à sable : aucun appel réel, gratuit, non facturé, et le verdict est déterministe via simulate (approved | review | rejected). Les webhooks partent avec livemode: false.

const av = new AveTrust("sk_test_…");
console.log(av.isTestMode); // true
const v = await av.verifications.create({ checks: ["DOCUMENT"], simulate: "rejected" });

Erreurs typées

import { AuthenticationError, RateLimitError, AveTrustError } from "@avetrust/node";

try {
  await av.verifications.create();
} catch (err) {
  if (err instanceof AuthenticationError) { /* clé invalide */ }
  else if (err instanceof RateLimitError) { /* quota */ }
  else if (err instanceof AveTrustError) { console.error(err.code, err.status, err.requestId); }
}

API

| Méthode | Description | |---|---| | verifications.create(params) | Crée une session (renvoie id + token) | | verifications.retrieve(id) | Résumé d'une session | | verifications.result(id) | Résultat complet (checks + décision) | | verifications.list(params) | Liste paginée (filtre status, test) | | verifications.stream(token, handlers) | Suivi temps réel (SSE), résout au verdict final | | verifications.sendLink(id, {channel, to, link}) | Envoie le lien hébergé | | verifications.decide(id, outcome, note?) | Décision manuelle (revue) | | apiKeys.list() / create(name, env) / revoke(id) | Gestion des clés | | webhooks.constructEvent(payload, sig, secret) | Vérifie + parse un webhook |

Options

new AveTrust("sk_live_…", {
  baseUrl: "https://api-test.avetrust.net/api/v1", // défaut
  timeout: 30_000,
  maxRetries: 2, // reprises sur 429 / 5xx
});

Licence

© AveTrust — usage réservé.