Node.js SDK

SDK BillionVerify pour Node.js. Installation, configuration et vérification d'e-mails en JavaScript avec exemples.

Le SDK officiel BillionVerify pour Node.js fournit un moyen simple et efficace d'intégrer la vérification d'emails dans vos applications Node.js.

Installation

npm install billionverify-sdk
# ou
yarn add billionverify-sdk
# ou
pnpm add billionverify-sdk

Démarrage Rapide

import { BillionVerify } from 'billionverify-sdk';

const client = new BillionVerify({
  apiKey: process.env.BV_API_KEY,
});

// Vérifier un seul email
const result = await client.verify('user@example.com');
console.log(result.status); // 'valid', 'invalid', 'unknown', ou 'catchall'

Configuration

Options du Client

const client = new BillionVerify({
  apiKey: 'your-api-key',

  // Configurations optionnelles
  timeout: 30000,           // Délai de requête en ms (par défaut : 30000)
  retries: 3,               // Nombre de tentatives (par défaut : 3)
  baseUrl: 'https://api.billionverify.com', // URL API personnalisée
});

Variables d'Environnement

Nous recommandons de stocker votre clé API dans des variables d'environnement :

# .env
BV_API_KEY=your_api_key_here

import { BillionVerify } from 'billionverify-sdk';

const client = new BillionVerify({
  apiKey: process.env.BV_API_KEY,
});

Vérification d'Email Unique

Vérification Basique

const result = await client.verify('user@example.com');

console.log({
  email: result.email,
  status: result.status,
  score: result.score,
  deliverable: result.result.deliverable,
  disposable: result.result.disposable,
  role: result.result.role,
});

Vérification avec Options

const result = await client.verify('user@example.com', {
  smtpCheck: true,      // Activer la vérification SMTP
  timeout: 5000,        // Délai personnalisé pour cette requête
});

Structure de Réponse

interface VerificationResult {
  email: string;
  status: 'valid' | 'invalid' | 'unknown' | 'catchall';
  result: {
    deliverable: boolean | null;
    valid_format: boolean;
    valid_domain: boolean;
    valid_mx: boolean;
    disposable: boolean;
    role: boolean;
    catchall: boolean;
    free: boolean;
    smtp_valid: boolean | null;
  };
  score: number;
  reason: string | null;
}

Vérification en Masse

Soumettre une Tâche en Masse

const emails = [
  'user1@example.com',
  'user2@example.com',
  'user3@example.com',
];

const job = await client.verifyBulk(emails);
console.log(`ID de tâche : ${job.id}`);
console.log(`Statut : ${job.status}`);

Vérifier le Statut de la Tâche

const status = await client.getBulkJobStatus(job.id);

console.log({
  id: status.id,
  status: status.status,      // 'pending', 'processing', 'completed', 'failed'
  total: status.total,
  processed: status.processed,
  valid: status.valid,
  invalid: status.invalid,
});

Obtenir les Résultats

// Attendre la fin de la tâche
const results = await client.getBulkJobResults(job.id);

for (const result of results) {
  console.log(`${result.email}: ${result.status}`);
}

Notifications par Webhook

Au lieu de l'interrogation, configurez un webhook pour recevoir des notifications lorsque la tâche est terminée :

const job = await client.verifyBulk(emails, {
  webhookUrl: 'https://your-domain.com/webhooks/billionverify',
});

Gestion des Crédits

Vérifier les Crédits Disponibles

const credits = await client.getCredits();

console.log({
  available: credits.available,
  used: credits.used,
  total: credits.total,
});

Gestion des Erreurs

Types d'Erreurs

import {
  BillionVerify,
  BillionVerifyError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
} from 'billionverify-sdk';

try {
  const result = await client.verify('invalid-email');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Clé API invalide');
  } else if (error instanceof RateLimitError) {
    console.error(`Limite de débit atteinte. Réessayer après ${error.retryAfter} secondes`);
  } else if (error instanceof ValidationError) {
    console.error(`Entrée invalide : ${error.message}`);
  } else if (error instanceof BillionVerifyError) {
    console.error(`Erreur API : ${error.message}`);
  }
}

Logique de Nouvelle Tentative

Le SDK réessaie automatiquement les requêtes échouées avec un délai exponentiel :

const client = new BillionVerify({
  apiKey: process.env.BV_API_KEY,
  retries: 5,                    // Tentatives max
  retryDelay: 1000,              // Délai initial en ms
  retryMaxDelay: 30000,          // Délai max entre tentatives
});

Intégration avec les Frameworks

Express.js

import express from 'express';
import { BillionVerify } from 'billionverify-sdk';

const app = express();
const client = new BillionVerify({
  apiKey: process.env.BV_API_KEY,
});

app.post('/api/verify-email', async (req, res) => {
  const { email } = req.body;

  try {
    const result = await client.verify(email);

    if (result.status === 'invalid') {
      return res.status(400).json({
        valid: false,
        message: 'Veuillez entrer une adresse email valide',
      });
    }

    if (result.result.disposable) {
      return res.status(400).json({
        valid: false,
        message: 'Les emails jetables ne sont pas autorisés',
      });
    }

    res.json({ valid: true, result });
  } catch (error) {
    res.status(500).json({ error: 'Échec de la vérification' });
  }
});

Fastify

import Fastify from 'fastify';
import { BillionVerify } from 'billionverify-sdk';

const fastify = Fastify();
const client = new BillionVerify({
  apiKey: process.env.BV_API_KEY,
});

fastify.post('/verify', async (request, reply) => {
  const { email } = request.body;
  const result = await client.verify(email);
  return result;
});

Route API Next.js

// pages/api/verify.js
import { BillionVerify } from 'billionverify-sdk';

const client = new BillionVerify({
  apiKey: process.env.BV_API_KEY,
});

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Méthode non autorisée' });
  }

  const { email } = req.body;

  try {
    const result = await client.verify(email);
    res.status(200).json(result);
  } catch (error) {
    res.status(500).json({ error: 'Échec de la vérification' });
  }
}

Exemple Complet

Inscription Utilisateur avec Vérification d'Email

import { BillionVerify } from 'billionverify-sdk';

const client = new BillionVerify({
  apiKey: process.env.BV_API_KEY,
});

async function validateRegistrationEmail(email) {
  const result = await client.verify(email);

  // Rejeter les emails invalides
  if (result.status === 'invalid') {
    return {
      valid: false,
      reason: 'invalid_email',
      message: 'Cette adresse email est invalide',
    };
  }

  // Rejeter les emails jetables
  if (result.result.disposable) {
    return {
      valid: false,
      reason: 'disposable',
      message: 'Veuillez utiliser une adresse email permanente',
    };
  }

  // Avertir sur les emails basés sur des rôles
  if (result.result.role) {
    return {
      valid: true,
      warning: 'role_based',
      message: 'Il est recommandé d\'utiliser un email personnel',
    };
  }

  // Accepter les emails valides
  return {
    valid: true,
    score: result.score,
  };
}

// Utilisation
const validation = await validateRegistrationEmail('user@example.com');
if (!validation.valid) {
  console.error(validation.message);
}

Support TypeScript

Le SDK inclut des définitions TypeScript prêtes à l'emploi :

import {
  BillionVerify,
  VerificationResult,
  BulkJob,
  ClientOptions
} from 'billionverify-sdk';

const options: ClientOptions = {
  apiKey: process.env.BV_API_KEY!,
  timeout: 30000,
};

const client = new BillionVerify(options);

const result: VerificationResult = await client.verify('user@example.com');