@eurovalidate/sdk

Official Node.js/TypeScript SDK for the EuroValidate API -- validate EU VAT numbers, IBANs, EORI numbers, and look up company data.

• Zero dependencies (native fetch, Node 18+)
• TypeScript-first with full type definitions
• ESM + CommonJS dual package
• Auto-retry on 429 with Retry-After
• Typed error classes for every failure mode

Installation

npm install @eurovalidate/sdk

Quick Start

import { EuroValidate } from '@eurovalidate/sdk';

const client = new EuroValidate('ev_live_your_key');

// VAT validation
const vat = await client.validateVat('NL820646660B01');
console.log(vat.valid, vat.companyName);
// true "COOLBLUE B.V."

// IBAN validation
const iban = await client.validateIban('DE89370400440532013000');
console.log(iban.valid, iban.bankName, iban.bic);
// true "Commerzbank" "COBADEFFXXX"

// EORI validation
const eori = await client.validateEori('DE328169180000040');
console.log(eori.valid, eori.companyName);

// Company lookup by LEI
const company = await client.lookupCompanyByLei('724500Y6DUVHQD6OXN27');
console.log(company.companyName, company.countryCode);

// VAT rates
const rates = await client.getVatRates('DE');
console.log(rates.standardRate); // 19

const allRates = await client.getAllVatRates();
console.log(allRates.countries.length); // 27

// Unified validation (multiple checks in one call)
const result = await client.validate({
  vatNumber: 'NL820646660B01',
  iban: 'DE89370400440532013000',
});
console.log(result.vat?.valid, result.iban?.valid);

// Account info
const account = await client.getAccount();
console.log(account.plan, account.callsUsed, account.callsLimit);

Error Handling

import {
  EuroValidate,
  AuthError,
  RateLimitError,
  ValidationError,
  NotFoundError,
  ServerError,
} from '@eurovalidate/sdk';

const client = new EuroValidate('ev_live_your_key');

try {
  const vat = await client.validateVat('INVALID');
} catch (err) {
  if (err instanceof AuthError) {
    // 401 -- invalid API key
  } else if (err instanceof RateLimitError) {
    // 429 -- rate limited (auto-retried 3 times before throwing)
    console.log('Retry after:', err.retryAfter, 'seconds');
  } else if (err instanceof ValidationError) {
    // 400/422 -- bad input
  } else if (err instanceof NotFoundError) {
    // 404
  } else if (err instanceof ServerError) {
    // 5xx -- server error
  }
}

Configuration

const client = new EuroValidate('ev_live_your_key', {
  baseUrl: 'https://api.eurovalidate.com', // default
  timeout: 30000,                           // ms, default 30s
  maxRetries: 3,                            // retries on 429, default 3
});

Requirements

• Node.js 18+ (uses native fetch)
• TypeScript 5.0+ (optional, for type checking)

License

MIT