TypeScript SDK

@neivi/iqx-lookup-typescript — TypeScript/JavaScript client for the IQX Lookup API using native fetch.

Installation

npm install @neivi/iqx-lookup-typescript

Quick Start

import { IqxLookup } from '@neivi/iqx-lookup-typescript';

const client = new IqxLookup({ apiKey: 'ALk-your-api-key' });

// Validate an email
const email = await client.validateEmail('user@example.com');
console.log('Valid format:', email.validFormat);
console.log('Disposable:', email.disposableEmail);

// Validate a phone number
const phone = await client.validatePhone('+34912345678', 'ES');
console.log('Valid:', phone.valid);
console.log('Carrier:', phone.carrier);

// Geolocate an IP
const ip = await client.geolocateIp('8.8.8.8');
console.log('Country:', ip.countryName);

// Validate a VAT number
const vat = await client.validateVat('ES', 'B87387775');
console.log('Valid:', vat.valid);

// Parse a user-agent string
const ua = await client.parseUserAgent('Mozilla/5.0...');
console.log('Browser:', ua.browserFamily);

Configuration

const client = new IqxLookup({
  apiKey: 'ALk-your-api-key',               // required
  baseUrl: 'https://api.iqxlookup.neivi.es',      // optional, default shown
  timeout: 15000,                             // optional, ms, default 10000
});

API Reference

All methods are async and return Promise<T>:

Method	Returns	Description
validateEmail(address)	EmailValidationResult	Email format, MX, disposable, free provider checks
validatePhone(number, countryCode?)	PhoneValidationResult	Phone validation
geolocateIp(ip?)	IpGeolocation	IP geolocation + ASN (omit ip = caller's IP)
validateVat(countryCode, number)	VatValidationResult	EU VIES VAT validation
parseUserAgent(ua?)	UserAgentResult	UA parsing — browser, OS, device brand & model
validateIban(iban)	IbanValidationResult	IBAN structure, checksum, bank info
validateBic(bic)	BicValidationResult	BIC/SWIFT format, institution info
lookupDns(domain, types?)	DnsLookupResult	DNS records, SPF/DKIM/DMARC security
checkSsl(domain)	SslCertificateResult	SSL certificate, chain, grade
analyzePassword(password)	PasswordStrengthResult	Strength score, crack time, breach check
validateCreditCard(number)	CreditCardValidationResult	Luhn check, card network, BIN lookup
rateLimitInfo (getter)	RateLimitInfo | null	Rate limit from last response

Error Handling

import { IqxLookup, RateLimitError, UnauthorizedError } from '@neivi/iqx-lookup-typescript';

try {
  const result = await client.validateEmail('user@example.com');
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Retry after: ${error.retryAfter}s`);
  } else if (error instanceof UnauthorizedError) {
    console.log('Check your API key');
  }
}

Requirements

• Node.js 18+ (uses native fetch)
• Works in modern browsers (no polyfills needed)
• Zero runtime dependencies