@botoi/sdk

TypeScript SDK for the Botoi API. 150+ developer tool endpoints for IP lookup, email validation, DNS, hashing, JSON processing, image generation, and more.

Install

npm install @botoi/sdk

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.

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