@botoi/sdk

Zero-dependency TypeScript SDK for the Botoi API: 150+ 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.

| Namespace | Methods | Description | |-----------|---------|-------------| | base64 | encode, decode | Base64 encoding/decoding | | hash | create, batch, hmac | Cryptographic hashing | | uuid | v4, v7, ulid, batch, validate | UUID/ULID generation | | url | encode, decode, parse | URL encoding and parsing | | password | generate, strength | Password generation and analysis | | cron | parse, next | Cron expression parsing | | json | format, minify, validate, diff | JSON processing | | ip | lookup, inRange, reverse, bulk | IP geolocation | | email | validate | Email validation | | dns | lookup, batch, propagation | DNS record lookup | | text | case, extractEmails, extractUrls, slugify, stats, truncate, language | Text processing | | jwt | generate, decode | JWT creation and decoding | | og | generate | Open Graph image generation | | qr | generate | QR code generation | | schema | validate, openapiValidate, jsonToTypescript, jsonToZod, jsonToJsonSchema | Schema tools | | code | format, detect, highlight | Code formatting and detection | | encrypt | encrypt, decrypt | AES encryption | | validate | creditCard, iban, vat | Financial validation | | currency | convert, rates | Currency conversion | | geo | distance, geocode, reverse | Geolocation utilities |

...and 50+ more namespaces. See the full API docs for all endpoints.

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

MIT