Prerequisites
Before using the SDK, a developer will need:
- Node.js (v18 or higher) installed on their machine.
- A Chapybara API Key, which they can get from their user dashboard.
Step 1: Installation
First, the developer adds the SDK to their project as a dependency.
npm install chapybara
Step 2: Initialization
Next, they import the client and create a new instance using their API key. It's best practice to store the API key in an environment variable rather than hardcoding it.
// main.js
import { ChapybaraClient } from "chapybara";
// Best practice: Load API key from environment variables
const apiKey = process.env.CHAPYBARA_API_KEY;
if (!apiKey) {
throw new Error("CHAPYBARA_API_KEY environment variable not set.");
}
const chapybara = new ChapybaraClient({
apiKey: apiKey,
});
Step 3: Making API Calls
Once initialized, they can use the simple, fluent API to access the different endpoints. All methods are asynchronous and return a Promise, making them perfect for async/await.
Example 1: Get Domain Intelligence
async function getDomainInfo(domain) {
try {
console.log(`Fetching intelligence for domain: ${domain}`);
const data = await chapybara.domain.getIntelligence(domain);
console.log("Domain:", data.domain_identity.domain);
console.log("Is Malicious:", data.security_analysis.is_malicious);
console.log("Active Subdomains Found:", data.subdomain_analysis.active_subdomains.length);
console.log("Active Subdomains:", data.subdomain_analysis.active_subdomains);
} catch (error) {
console.error(`Error: ${error.message}`);
}
}
getDomainInfo("google.com");
Example 2: Get IP Intelligence
async function getIpInfo(ip) {
try {
console.log(`Fetching intelligence for IP: ${ip}`);
const data = await chapybara.ip.getIntelligence(ip);
console.log("Country:", data.location.country.name);
console.log("City:", data.location.city.name);
console.log("Organization:", data.network.organization);
console.log("Is VPN/Proxy:", data.security.is_proxy);
} catch (error) {
console.error(`Error: ${error.message}`);
}
}
getIpInfo("8.8.8.8");
Example 3: Get Web Technology Scan
async function getWebTech(domain) {
try {
console.log(`Scanning web technologies for: ${domain}`);
const data = await chapybara.webtech.getScanner(domain);
console.log("Website Title:", data.title);
console.log("Detected Technologies:");
for (const tech of data.technologies) {
console.log(`- ${tech.name}${tech.version ? ` (v${tech.version})` : ''}`);
}
} catch (error) {
console.error(`Error: ${error.message}`);
}
}
getWebTech("github.com");
Example 4: Get a Website Screenshot
import { promises as fs } from "fs";
async function getScreenshot(domain, isMobile = false) {
try {
const filename = `${domain}_${isMobile ? 'mobile' : 'desktop'}.png`;
console.log(`Capturing ${isMobile ? 'mobile' : 'desktop'} screenshot for: ${domain}`);
// Pass options object as the second argument
const imageBuffer = await chapybara.screenshot.get(domain, { mobile: isMobile });
await fs.writeFile(filename, imageBuffer);
console.log(`Screenshot saved to ${filename}`);
} catch (error) {
console.error(`Error: ${error.message}`);
}
}
getScreenshot("alphasystem.dev", false); // Desktop
getScreenshot("alphasystem.dev", true); // Mobile
Step 4: Advanced Configuration (Caching & Retries)
For production applications, a developer can configure the client to enable caching (to improve performance and save on quotas) and adjust retry behavior.
import { ChapybaraClient } from "chapybara";
const chapybaraPro = new ChapybaraClient({
apiKey: process.env.CHAPYBARA_API_KEY,
retries: 3, // Retry up to 3 times on server errors
timeout: 15000, // Set a 15-second timeout for requests
cacheOptions: {
max: 500, // Store up to 500 unique API responses
ttl: 1000 * 60 * 10, // Cache items for 10 minutes
},
});
// The first time this is called, it will make an API request.
await chapybaraPro.domain.getIntelligence("alphasystem.dev");
// The second time (within 10 mins), it will return the cached result instantly.
await chapybaraPro.domain.getIntelligence("alphasystem.dev");
Step 5: Robust Error Handling
The SDK throws custom, specific errors, allowing developers to write clean and robust error-handling logic.
import {
ChapybaraClient,
AuthenticationError,
RateLimitError,
BadRequestError,
} from "chapybara";
const chapybara = new ChapybaraClient({ apiKey: "ck_invalid_key" });
async function checkDomain(domain) {
try {
const data = await chapybara.domain.getIntelligence(domain);
console.log("Domain is valid and not malicious.");
} catch (error) {
if (error instanceof AuthenticationError) {
console.error("Authentication failed! Check your API key.");
} else if (error instanceof RateLimitError) {
console.error("Rate limit exceeded. Please wait before making more requests.");
} else if (error instanceof BadRequestError) {
console.error(`Invalid input: ${error.message}. The domain '${domain}' is likely malformed.`);
} else {
// Generic API error
console.error(`An API error occurred: ${error.message}`);
console.error(`Request ID: ${error.requestId}`); // Useful for support
}
}
}
// This will trigger an AuthenticationError
checkDomain("google.com");
// If the API key were valid, this would trigger a BadRequestError
// checkDomain("not a valid domain");
TypeScript Usage
For developers using TypeScript, the SDK provides full type support for a great developer experience with autocompletion and type safety.
import { ChapybaraClient, IPIntelligenceResponse } from "chapybara";
const chapybara = new ChapybaraClient({
apiKey: process.env.CHAPYBARA_API_KEY!,
});
async function getIpCountry(ip: string): Promise<string | null> {
try {
const data: IPIntelligenceResponse = await chapybara.ip.getIntelligence(ip);
// Autocompletion works here! e.g., data.location.country.name
return data.location.country.name;
} catch (error) {
console.error(error);
return null;
}
}