whizoai

WhizoAI SDK for Node.js & TypeScript

Official Node.js and TypeScript SDK for the WhizoAI web scraping and data extraction API.

Features

• Full TypeScript Support - Complete type definitions and IntelliSense
• Modern ESM - ES Module support with tree-shaking
• Comprehensive API Coverage - All WhizoAI endpoints supported
• Automatic Retries - Built-in exponential backoff for failed requests
• Error Handling - Structured error types for better debugging
• Zero Dependencies - Only relies on Node.js built-in modules and axios
• Async/Await - Promise-based API for clean async code

Installation

npm install whizoai

Or with yarn:

yarn add whizoai

Or with pnpm:

pnpm add whizoai

Quick Start

import { WhizoAI } from 'whizoai';

// Initialize the client
const whizoai = new WhizoAI({
  apiKey: process.env.WHIZOAI_API_KEY, // Get your API key from https://whizo.ai/app/api-keys
});

// Scrape a webpage
const result = await whizoai.scrape('https://example.com', {
  format: 'markdown',
  onlyMainContent: true,
});

console.log(result.data.content);
console.log(`Credits used: ${result.creditsUsed}`);

Authentication

Get your API key from the WhizoAI Dashboard.

Environment Variable (Recommended)

export WHIZOAI_API_KEY="whizo_your_api_key_here"

import { WhizoAI } from 'whizoai';

const whizoai = new WhizoAI({
  apiKey: process.env.WHIZOAI_API_KEY,
});

Direct Initialization

const whizoai = new WhizoAI({
  apiKey: 'whizo_your_api_key_here',
});

API Reference

Scraping

Single Page Scraping

const result = await whizoai.scrape('https://example.com', {
  format: 'markdown', // 'markdown' | 'html' | 'text' | 'json'
  onlyMainContent: true,
  includeScreenshot: false,
  includePDF: false,
  waitFor: 0, // milliseconds to wait before scraping
  headers: {
    'User-Agent': 'Custom User Agent',
  },
});

console.log(result.data.content);
console.log(result.data.metadata.title);
console.log(`Credits used: ${result.creditsUsed}`);

Multi-Page Crawling

const result = await whizoai.crawl('https://example.com', {
  maxPages: 10,
  maxDepth: 2,
  allowedDomains: ['example.com'],
  excludePaths: ['/admin', '/private'],
  format: 'markdown',
  onlyMainContent: true,
});

console.log(`Crawled ${result.data.pages.length} pages`);
result.data.pages.forEach(page => {
  console.log(`${page.url}: ${page.content.substring(0, 100)}...`);
});

AI-Powered Extraction

Extract structured data from webpages using AI:

const result = await whizoai.extract('https://github.com/anthropics', {
  schema: {
    companyName: 'string',
    description: 'string',
    mainProducts: ['string'],
    teamSize: 'number',
  },
  model: 'gpt-3.5-turbo', // or 'gpt-4'
  prompt: 'Extract information about this company',
});

console.log(result.data.extractedData);
// {
//   companyName: "Anthropic",
//   description: "AI safety company...",
//   mainProducts: ["Claude", "Constitutional AI"],
//   teamSize: 150
// }

Web Search

Search the web with optional content scraping:

const result = await whizoai.search('best web scraping tools 2025', {
  maxResults: 10,
  scrapeResults: true, // Scrape each search result
  searchEngine: 'google', // 'google' | 'bing' | 'duckduckgo'
  country: 'us',
  language: 'en',
});

console.log(`Found ${result.data.results.length} results`);
result.data.results.forEach(item => {
  console.log(`${item.title}: ${item.url}`);
  if (item.content) {
    console.log(`Content: ${item.content.substring(0, 200)}...`);
  }
});

URL Mapping

Discover all URLs on a website:

const result = await whizoai.map('https://example.com', {
  maxDepth: 3,
  maxPages: 100,
  includeSubdomains: false,
});

console.log(`Found ${result.totalUrls} URLs`);
result.data.urls.forEach(urlInfo => {
  console.log(`${urlInfo.url} (depth: ${urlInfo.depth})`);
});

Batch Operations

Process multiple URLs in parallel:

const result = await whizoai.batch({
  urls: [
    'https://example.com',
    'https://example.com/about',
    'https://example.com/contact',
  ],
  scrapeType: 'scrape',
  options: {
    format: 'markdown',
    onlyMainContent: true,
  },
});

console.log(`Total credits used: ${result.totalCreditsUsed}`);
result.data.results.forEach((item, i) => {
  console.log(`Result ${i + 1}: ${item.status}`);
  if (item.data) {
    console.log(item.data.content.substring(0, 100));
  }
});

Job Management

List Jobs

const jobs = await whizoai.listJobs({
  limit: 20,
  offset: 0,
  status: 'completed', // 'pending' | 'running' | 'completed' | 'failed'
  scrapeType: 'scrape', // Filter by type
});

console.log(`Found ${jobs.data.total} jobs`);
jobs.data.jobs.forEach(job => {
  console.log(`${job.id}: ${job.url} - ${job.status}`);
});

Get Job Details

const job = await whizoai.getJob('job-id-here');

console.log(`Status: ${job.data.status}`);
console.log(`Progress: ${job.data.progress}%`);
console.log(`Credits used: ${job.data.creditsUsed}`);

Cancel Job

await whizoai.cancelJob('job-id-here');
console.log('Job cancelled successfully');

Delete Job

await whizoai.deleteJob('job-id-here');
console.log('Job deleted successfully');

User & Credits

Check Credit Balance

const credits = await whizoai.getCreditBalance();

console.log(`Plan: ${credits.data.plan}`);
console.log(`Monthly credits: ${credits.data.monthlyCredits}`);
console.log(`Used this month: ${credits.data.creditsUsedThisMonth}`);
console.log(`Remaining: ${credits.data.creditsRemaining}`);
console.log(`Lifetime credits: ${credits.data.lifetimeCredits}`);

Get User Profile

const profile = await whizoai.getUserProfile();

console.log(`Email: ${profile.data.email}`);
console.log(`Name: ${profile.data.fullName}`);
console.log(`Plan: ${profile.data.plan}`);

Update User Profile

await whizoai.updateUserProfile({
  fullName: 'John Doe',
  email: '[e-mail]',
});

Get Usage Analytics

const usage = await whizoai.getUsageAnalytics({
  startDate: '2025-01-01',
  endDate: '2025-01-31',
  groupBy: 'day', // 'hour' | 'day' | 'week' | 'month'
});

console.log(`Total requests: ${usage.data.totalRequests}`);
console.log(`Total credits: ${usage.data.totalCredits}`);
usage.data.breakdown.forEach(item => {
  console.log(`${item.date}: ${item.requests} requests, ${item.credits} credits`);
});

API Key Management

List API Keys

const keys = await whizoai.listApiKeys();

keys.data.forEach(key => {
  console.log(`${key.name}: ${key.maskedKey} (${key.isActive ? 'Active' : 'Inactive'})`);
  console.log(`  Last used: ${key.lastUsedAt}`);
  console.log(`  Usage: ${key.usageCount} requests`);
});

Create API Key

const newKey = await whizoai.createApiKey({
  name: 'Production API Key',
  scopes: ['scrape', 'crawl', 'extract'],
  rateLimitPerHour: 100,
  expiresAt: '2025-12-31T23:59:59Z', // Optional
});

console.log(`New API key: ${newKey.data.apiKey}`);
console.log('⚠️ Save this key - you won\'t see it again!');

Update API Key

await whizoai.updateApiKey('key-id-here', {
  name: 'Updated Key Name',
  isActive: false, // Disable the key
});

Delete API Key

await whizoai.deleteApiKey('key-id-here');
console.log('API key deleted successfully');

Webhooks

List Webhooks

const webhooks = await whizoai.listWebhooks();

webhooks.data.forEach(webhook => {
  console.log(`${webhook.url} - ${webhook.events.join(', ')}`);
});

Create Webhook

const webhook = await whizoai.createWebhook({
  url: 'https://your-app.com/webhooks/whizoai',
  events: ['job.completed', 'job.failed'],
  secret: 'your-webhook-secret', // For signature verification
});

console.log(`Webhook created: ${webhook.data.id}`);

Delete Webhook

await whizoai.deleteWebhook('webhook-id-here');

Error Handling

The SDK provides structured error types for better error handling:

import {
  WhizoAI,
  WhizoAIError,
  AuthenticationError,
  ValidationError,
  InsufficientCreditsError,
  RateLimitError,
  NetworkError
} from 'whizoai';

try {
  const result = await whizoai.scrape('https://example.com');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Invalid input:', error.details);
  } else if (error instanceof InsufficientCreditsError) {
    console.error('Out of credits:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof WhizoAIError) {
    console.error('WhizoAI error:', error.message, error.code);
  } else {
    console.error('Unexpected error:', error);
  }
}

Advanced Configuration

Custom API URL

For self-hosted or testing environments:

const whizoai = new WhizoAI({
  apiKey: process.env.WHIZOAI_API_KEY,
  apiUrl: 'http://localhost:8080', // Default: https://api.whizo.ai
});

Custom Timeout

const whizoai = new WhizoAI({
  apiKey: process.env.WHIZOAI_API_KEY,
  timeout: 60000, // 60 seconds (default: 30000)
});

Retry Configuration

const whizoai = new WhizoAI({
  apiKey: process.env.WHIZOAI_API_KEY,
  maxRetries: 5, // Default: 3
  retryDelay: 2000, // Initial delay in ms (default: 1000)
});

TypeScript Support

The SDK is written in TypeScript and provides complete type definitions:

import type {
  ScrapeOptions,
  ScrapeResponse,
  CrawlOptions,
  CrawlResponse,
  ExtractOptions,
  ExtractResponse,
  JobStatus,
  UserPlan,
} from 'whizoai';

const options: ScrapeOptions = {
  format: 'markdown',
  onlyMainContent: true,
  includeScreenshot: false,
};

const result: ScrapeResponse = await whizoai.scrape('https://example.com', options);

Examples

Check out the examples directory for more usage examples:

• Basic Usage - Common operations
• Advanced Scraping - Complex scraping scenarios
• AI Extraction - Structured data extraction
• Batch Processing - Processing multiple URLs
• Error Handling - Comprehensive error handling

Credit Costs

Operation	Base Cost	Additional
Basic scraping	1 credit	-
Screenshot	+1 credit	Per page
PDF generation	+1 credit	Per page
AI extraction (GPT-3.5)	3 credits	Per page
AI extraction (GPT-4)	6 credits	Per page
Web search	1 credit	Per search
Stealth mode	+4 credits	Per page

Rate Limits

Rate limits vary by subscription plan:

Plan	Requests/Hour	Requests/Day
Free	10	100
Starter	50	500
Pro	200	2,000
Enterprise	1,000	10,000

Support

• Documentation: https://docs.whizo.ai
• Dashboard: https://whizo.ai/app
• Email: [e-mail]
• GitHub Issues: https://github.com/whizoai/whizoai-sdks/issues

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

Changelog

See CHANGELOG.md for a list of changes in each version.

Made with ❤️ by the WhizoAI Team