Package Exports
- @eurovalidate/sdk
Readme
@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/sdkQuick 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