Package Exports

@botoi/sdk
@botoi/sdk/package.json

Readme

@botoi/sdk

Zero-dependency TypeScript SDK for the Botoi API: 196+ endpoints for IP geolocation, DNS lookups, email validation, currency conversion, QR code generation, and more. Ships with full IntelliSense, auto-retry with exponential backoff, and typed error classes.

npm install @botoi/sdk

import Botoi from '@botoi/sdk';
const botoi = new Botoi({ apiKey: 'your-api-key' });
const ip = await botoi.ip.lookup();
console.log(ip.country, ip.city); // "US" "San Francisco"

Full API docs | Interactive playground | Get a free API key

Quick start

import Botoi from '@botoi/sdk';

const botoi = new Botoi({ apiKey: 'your-api-key' });

// Validate an email
const email = await botoi.email.validate({ email: 'user@gmail.com' });
console.log(email.is_valid); // true

// Look up an IP
const ip = await botoi.ip.lookup();
console.log(ip.country, ip.city); // "US" "San Francisco"

// Generate a hash
const hash = await botoi.hash.create({ text: 'hello', algorithm: 'sha256' });
console.log(hash.hash);

Authentication

Pass your API key directly or set the BOTOI_API_KEY environment variable:

// Option 1: Pass directly
const botoi = new Botoi({ apiKey: 'bot_xxx' });

// Option 2: Environment variable
// Set BOTOI_API_KEY=bot_xxx in your environment
const botoi = new Botoi();

Anonymous usage (5 req/min, no API key) also works:

const botoi = new Botoi();
const ip = await botoi.ip.lookup();

Get a free API key at botoi.com/api.

Configuration

const botoi = new Botoi({
  apiKey: 'bot_xxx',           // API key (or set BOTOI_API_KEY env var)
  baseUrl: 'https://api.botoi.com', // Custom base URL
  maxRetries: 3,               // Retry attempts for 429/5xx (default: 3, set 0 to disable)
  timeout: 30_000,             // Request timeout in ms (default: 30s)
});

Error handling

import Botoi, { BotoiError, BotoiRateLimitError, BotoiAuthError } from '@botoi/sdk';

try {
  const result = await botoi.email.validate({ email: 'test@example.com' });
} catch (error) {
  if (error instanceof BotoiRateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof BotoiAuthError) {
    console.log('Invalid API key');
  } else if (error instanceof BotoiError) {
    console.log(`API error: ${error.code} - ${error.message}`);
    console.log(`Request ID: ${error.requestId}`);
  }
}

Auto-retry

The SDK retries on rate limits (429) and server errors (5xx) with exponential backoff:

429 responses: respects the Retry-After header
5xx responses: exponential backoff with jitter (500ms, 1s, 2s)
4xx responses (except 429): fail immediately (bad input is bad input)
Max 3 retries by default

Disable retries:

const botoi = new Botoi({ maxRetries: 0 });

Available namespaces

Every method maps 1:1 to an API endpoint. Type botoi. and autocomplete shows all namespaces.

Lookup

Namespace	Methods	Description
`ip`	`lookup`, `inRange`, `reverse`, `bulk`	IP geolocation and range checks
`ipWhois`	`lookup`	IP WHOIS ownership details
`ipBlocklist`	`check`	Check IP against threat blocklists
`vpnDetect`	`detect`	Detect VPN, proxy, and Tor exits
`email`	`validate`	Email syntax and deliverability
`emailMx`	`verify`	SMTP MX record verification
`emailSecurity`	`report`	Combined SPF, DKIM, DMARC report
`disposableEmail`	`check`, `list`	Flag disposable email domains
`abuseEmail`	`check`	Abuse contact lookup for a domain
`breach`	`check`	Check an email against known breaches
`phone`	`validate`	Phone number validation and formatting
`useragent`	`parse`	Parse user-agent strings
`timezone`	`get`, `convert`	Timezone lookup and conversion
`dns`	`lookup`, `batch`, `propagation`, `compare`	DNS record lookup and propagation
`dnsSecurity`	`spfCheck`, `dmarcCheck`, `dkimCheck`	SPF, DMARC, DKIM validation
`dnsMonitor`	`check`	Snapshot DNS for change tracking
`whois`	`lookup`	Domain WHOIS lookup
`domain`	`availability`	Domain availability check
`domainSearch`	`search`	Find domains by keyword or TLD
`ssl`	`check`	SSL/TLS certificate health check
`sslCert`	`certificate`	Full certificate chain details
`tlsFingerprint`	`fingerprint`	JA3/JA4 TLS client fingerprint
`headers`	`inspect`	Inspect outgoing request headers
`company`	`lookup`	Company info from domain
`urlMetadata`	`extract`	Page title, description, OG tags
`link`	`expand`, `check`	Expand short links, check safety
`redirectTrace`	`trace`	Trace full HTTP redirect chain
`mx`	`check`	MX record check for a domain
`techDetect`	`detect`	Detect tech stack on a site
`robots`	`parse`	Parse robots.txt rules
`sitemap`	`parse`	Parse XML sitemaps
`rss`	`parse`	Parse RSS and Atom feeds
`socialPreview`	`extract`	Open Graph and Twitter card preview
`site`	`check`	Uptime, TTFB, and response stats
`uptime`	`check`	Single-shot uptime probe
`accessibility`	`check`	WCAG accessibility audit
`pageRank`	`check`	Open PageRank score for a domain
`currency`	`convert`, `rates`	Currency conversion and FX rates
`currencyList`	`list`	Supported currency list
`crypto`	`price`, `search`	Crypto prices and coin search
`country`	`lookup`	Country metadata by ISO code
`address`	`validate`, `autocomplete`	Address validation and autocomplete
`geo`	`distance`, `geocode`, `reverse`	Distance, geocoding, reverse geocoding
`elevation`	`lookup`	Elevation for a coordinate
`onWater`	`check`	Check if a coordinate is on water
`weather`	`current`	Current weather for a location
`airQuality`	`check`	Air quality index by location
`carbon`	`estimate`	CO2 emissions for a web page
`holidays`	`list`	Public holidays by country and year
`asn`	`lookup`	ASN lookup and prefix info
`bin`	`lookup`	BIN lookup for card issuer details
`age`	`estimate`	Estimate age from a first name
`gender`	`estimate`	Estimate gender from a first name
`nationality`	`estimate`	Estimate nationality from a first name

Text & data

Namespace	Methods	Description
`base64`	`encode`, `decode`	Base64 encoding and decoding
`json`	`format`, `minify`, `validate`, `diff`	Format, minify, validate, diff JSON
`jsonExtra`	`flatten`, `unflatten`	Flatten and unflatten nested JSON
`markdown`	`toHtml`, `toText`	Markdown to HTML and plain text
`htmlToText`	`convert`	Strip HTML to readable text
`htmlToMarkdown`	`convert`	Convert HTML to Markdown
`htmlSanitize`	`sanitize`	Sanitize untrusted HTML
`lorem`	`generate`	Lorem ipsum filler text
`regex`	`test`, `replace`	Test and replace with regex
`text`	`case`, `extractEmails`, `extractUrls`, `language`, `slugify`, `stats`, `truncate`	Case, slugify, stats, extraction
`csv`	`toCsv`, `toJson`	Convert between CSV and JSON
`xml`	`toJson`	Convert XML to JSON
`emoji`	`search`	Search emojis by keyword
`ical`	`parse`, `generate`	Parse and build iCalendar events
`metatag`	`generate`	Generate HTML meta tags
`number`	`format`, `spell`	Format and spell out numbers
`date`	`parse`	Parse flexible date strings

Developer utilities

Namespace	Methods	Description
`hash`	`create`, `batch`, `hmac`	Cryptographic hashing (MD5, SHA, HMAC)
`uuid`	`v4`, `v7`, `ulid`, `batch`, `validate`	UUID/ULID generation and validation
`url`	`encode`, `decode`, `parse`	URL encoding and parsing
`password`	`generate`, `strength`	Password generation and strength
`cron`	`parse`, `next`	Parse cron and compute next runs
`color`	`convert`, `palette`	Color conversion and palettes
`jwt`	`generate`, `decode`	JWT generation and decoding
`diff`	`text`, `json`	Text and JSON diffs
`totp`	`generate`, `validate`	TOTP secrets and code validation
`timestamp`	`convert`	Unix to ISO and back
`semver`	`compare`, `validate`	Semver comparison and validation
`yaml`	`toJson`, `toYaml`	YAML to JSON and back
`math`	`evaluate`	Evaluate math expressions
`units`	`convert`	Unit conversion
`token`	`count`, `truncate`	LLM token counting and truncation
`code`	`format`, `detect`, `highlight`	Format, detect, highlight source code
`sql`	`format`, `parse`	SQL formatting and parsing
`minify`	`js`, `css`, `html`	Minify JS, CSS, HTML
`schema`	`validate`, `openapiValidate`, `jsonToTypescript`, `jsonToZod`, `jsonToJsonSchema`	Schema validation and conversion
`mock`	`generate`	Generate mock data from a schema
`random`	`data`	Random strings, numbers, and bytes
`license`	`lookup`	SPDX open-source license lookup
`npm`	`info`	npm package info and metadata
`otp`	`generate`	Generate one-time passwords

Image & media

Namespace	Methods	Description
`og`	`generate`	Open Graph social images
`qr`	`generate`	QR code generation
`placeholder`	`generate`	Placeholder images
`avatar`	`generate`	Generate initials avatars
`favicon`	`get`	Fetch a site's favicon
`barcode`	`generate`	Linear and 2D barcodes
`pdf`	`fromHtml`, `fromMarkdown`	PDF from HTML or Markdown
`screenshot`	`capture`	Website screenshot capture
`image`	`metadata`, `resize`, `convert`	Image metadata, resize, format convert
`svg`	`optimize`	SVG optimization

Security & validation

Namespace	Methods	Description
`validate`	`creditCard`, `iban`, `vat`	Credit card, IBAN, VAT validation
`encrypt`	`encrypt`, `decrypt`	AES encryption and decryption
`phishing`	`check`	Phishing URL detection
`pii`	`detect`	Detect PII in text
`security`	`grade`	Overall site security grade

Storage & services

Namespace	Methods	Description
`webhook`	`create`, `get`, `payloads`, `receive`	Webhook inbox for request capture
`shortUrl`	`create`, `stats`	Short URL creation and analytics
`paste`	`create`, `get`	Ephemeral code and text pastes

See the interactive playground for live request builders, and the full endpoint catalog for setup guides and examples.

Binary responses

Some endpoints return binary data (images, PDFs). These return a raw Response object:

// Generate a QR code
const response = await botoi.qr.generate({ text: 'https://botoi.com' });
const svg = await response.text();

// Generate a PDF
const pdf = await botoi.pdf.fromHtml({ html: '<h1>Hello</h1>' });
const buffer = await pdf.arrayBuffer();

Requirements

Node.js 20+
TypeScript 5.0+ (for type inference)

JSPM

@botoi/sdk

Package Exports

Readme

@botoi/sdk

Quick start

Authentication

Configuration

Error handling

Auto-retry

Available namespaces

Lookup

Text & data

Developer utilities

Image & media

Security & validation

Storage & services

Binary responses

Requirements

License