@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: '[email protected]' });
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: '[email protected]' });
} 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)

License

Proprietary - Copyright (c) 2026 Savi Business Management LLC. See LICENSE for details.