How to use the Botoi TypeScript SDK with 5 real examples

You're building a Node.js app and need to validate emails, capture screenshots, detect PII in support tickets, or generate QR codes for receipts. You could write fetch wrappers, handle retries, parse errors, and hope the types stay in sync with the API. Or you could install one package.

The @botoi/sdk package gives you typed access to 150+ endpoints with auto-retry, error classes, and zero dependencies. This post walks through five copy-paste examples you can ship today.

Install and initialize

npm install @botoi/sdk

import Botoi from "@botoi/sdk";

const botoi = new Botoi({
  apiKey: process.env.BOTOI_API_KEY,
});

The SDK reads BOTOI_API_KEY from your environment by default. No API key? Anonymous access works at 5 requests per minute and 100 per day. The package has zero dependencies and requires Node.js 20+.

Five things you can build today

Scan user input for PII before logging

Support tickets contain emails, phone numbers, and SSNs that customers paste in without thinking. If you log those payloads, you're storing PII you never asked for. The pii.detect method finds sensitive data so you can redact it before it hits your database.

import Botoi from "@botoi/sdk";

const botoi = new Botoi();

const result = await botoi.pii.detect({
  text: "Hi, my name is Sarah Connor. Reach me at sarah@skynet.io or 415-555-0198. My SSN is 123-45-6789.",
});

console.log(result.findings);

Response:

[
  { "type": "PERSON",       "value": "Sarah Connor",   "start": 15, "end": 27 },
  { "type": "EMAIL",        "value": "sarah@skynet.io", "start": 41, "end": 57 },
  { "type": "PHONE_NUMBER", "value": "415-555-0198",   "start": 61, "end": 73 },
  { "type": "SSN",          "value": "123-45-6789",    "start": 84, "end": 95 }
]

Each finding includes the entity type, the matched value, and the start/end character positions. Use those offsets to replace sensitive text with [REDACTED] before writing to logs.

Generate Zod schemas from API responses

You get JSON from a third-party API and need runtime validation. Hand-writing Zod schemas for a 30-field Stripe payment intent takes time you don't have. The schema.jsonToZod method generates the schema from any JSON object.

const schema = await botoi.schema.jsonToZod({
  json: {
    id: "pi_3PqRsT4eZvKYlo2C0",
    amount: 24900,
    currency: "usd",
    status: "succeeded",
    customer: "cus_QrStUvWxYz",
    metadata: {
      order_id: "ord_98765",
      product_sku: "PRO-ANNUAL",
    },
  },
  name: "PaymentIntent",
});

console.log(schema.zod);

Output:

const PaymentIntentSchema = z.object({
  id: z.string(),
  amount: z.number(),
  currency: z.string(),
  status: z.string(),
  customer: z.string(),
  metadata: z.object({
    order_id: z.string(),
    product_sku: z.string(),
  }),
})

Paste the output into your codebase, add import { z } from "zod", and you have runtime-validated types in under 30 seconds. Nested objects and arrays are handled recursively.

Detect what tech stack a competitor uses

Competitor research usually means opening DevTools and guessing from script tags. The techDetect.detect method scans a URL and returns categorized results; frameworks, analytics, CDNs, hosting providers, and more.

const result = await botoi.techDetect.detect({
  url: "https://linear.app",
});

console.log(result.categories);

Response:

{
  "JavaScript frameworks": ["React", "Next.js"],
  "CSS frameworks":        ["Tailwind CSS"],
  "Analytics":             ["Segment", "Amplitude"],
  "CDN":                   ["Cloudflare"],
  "Hosting":               ["Vercel"]
}

Each technology includes a confidence score and category. Useful for sales intelligence, market research, or auditing your own stack.

Capture full-page screenshots programmatically

Social preview images, PDF reports, visual regression tests. They all need screenshots. The screenshot.capture method returns a binary Response object you can write straight to disk.

import fs from "node:fs";

const response = await botoi.screenshot.capture({
  url: "https://github.com/trending",
  fullPage: true,
  format: "png",
  width: 1280,
});

const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync("trending.png", buffer);

console.log("Saved trending.png (" + buffer.length + " bytes)");

Binary endpoints (screenshots, PDFs, images) return a raw Response. Call .arrayBuffer() to get the bytes. The endpoint supports custom viewports, full-page capture, and PNG/JPEG/WebP formats.

Generate QR codes as SVG

Receipts, event tickets, marketing materials. QR codes show up everywhere. The qr.generate method returns SVG by default, which means infinite scaling and tiny file sizes.

const response = await botoi.qr.generate({
  text: "https://botoi.com/api",
  format: "svg",
  size: 400,
  darkColor: "#1e293b",
  lightColor: "#ffffff",
});

const svg = await response.text();
fs.writeFileSync("ticket-qr.svg", svg);

The SVG output is a self-contained string you can embed in HTML, save to a file, or include in a PDF. Custom colors, error correction levels, and size are all configurable.

Error handling that helps you recover

The SDK exports typed error classes for each failure mode. You can catch specific errors and respond differently to rate limits, auth failures, and timeouts.

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

const botoi = new Botoi();

try {
  const result = await botoi.pii.detect({ text: ticketBody });
  // process result
} catch (err) {
  if (err instanceof BotoiRateLimitError) {
    console.log("Rate limited. Retry after " + err.retryAfter + "s");
  } else if (err instanceof BotoiError) {
    console.log(err.code + ": " + err.message);
  }
}

The SDK auto-retries 429 and 5xx errors with exponential backoff (up to 3 attempts by default). Most transient failures resolve without your code touching them. The BotoiRateLimitError includes a retryAfter property in seconds, so you can build queue-based fallbacks for high-volume workloads.

Configuration options

<table> <thead> <tr> <th>Option</th> <th>Type</th> <th>Default</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>apiKey</code></td> <td><code>string</code></td> <td><code>BOTOI_API_KEY</code> env var</td> <td>Your API key. Falls back to the environment variable if omitted.</td> </tr> <tr> <td><code>baseUrl</code></td> <td><code>string</code></td> <td><code>https://api.botoi.com</code></td> <td>Override the API base URL for testing or self-hosted instances.</td> </tr> <tr> <td><code>maxRetries</code></td> <td><code>number</code></td> <td><code>3</code></td> <td>Number of retry attempts for 429 and 5xx errors. Set to 0 to disable.</td> </tr> <tr> <td><code>timeout</code></td> <td><code>number</code></td> <td><code>30000</code></td> <td>Request timeout in milliseconds.</td> </tr> </tbody> </table>

The simplest configuration reads everything from the environment:

// Reads BOTOI_API_KEY from process.env automatically
const botoi = new Botoi();

Set BOTOI_API_KEY in your .env file and the SDK picks it up automatically. No constructor arguments needed.

What's included

The SDK exposes 87 resource namespaces covering lookup, text processing, developer utilities, security and validation, image generation, and storage services. Every method is fully typed; hover over any call in your editor to see the request parameters and response shape.

A few namespaces to get started with:

• botoi.ip, botoi.email, botoi.dns for lookups
• botoi.hash, botoi.jwt, botoi.uuid for developer utilities
• botoi.pii, botoi.encrypt, botoi.validate for security
• botoi.qr, botoi.screenshot, botoi.og for image generation
• botoi.schema, botoi.json, botoi.csv for data transformation

See the full SDK reference at /sdk/, or browse the package on npm.