Whisper NodeJS SDK

Introduction

‍

The Whisper TypeScript/JavaScript SDK provides a fully-typed, Promise-based client for the Whisper API v1. It's designed for both Node.js and browser environments, offering comprehensive intelligence gathering and monitoring capabilities for domains, IPs, and web infrastructure with excellent TypeScript support.

‍

Key Features

• Fully Typed: Complete TypeScript definitions for IDE autocomplete
• Promise-Based: Modern async/await support
• Universal: Works in Node.js and browsers
• Performance: <500ms typical response time
• Tree-Shakeable: Import only what you need

Getting Started

‍

Prerequisites

• Node.js 18+ or modern browser
• npm or yarn package manager
• Whisper API key from dash.whisper.security

Installation

‍

‍

# npm
npm install @whisper-security/whisper-api-sdk

# yarn
yarn add @whisper-security/whisper-api-sdk

# pnpm
pnpm add @whisper-security/whisper-api-sdk

‍


Quick Start Example

‍

‍

import { Configuration, IndicatorsApi } from '@whisper-security/whisper-api-sdk';

// Configure API client
const configuration = new Configuration({
    basePath: 'https://api.whisper.security',
    accessToken: 'YOUR_API_KEY'
});

const api = new IndicatorsApi(configuration);

// Enrich an IP address
async function enrichIP() {
    try {
        const response = await api.getIndicator('ip', '8.8.8.8');
        console.log(`Organization: ${response.data.summary?.organization}`);
        console.log(`Risk Score: ${response.data.reputation?.risk_score}`);
    } catch (error) {
        console.error('API Error:', error);
    }
}

enrichIP();

‍

Core Concepts

‍

1. API Structure

‍

The SDK is organized into three main API classes:

• IndicatorsApi: Intelligence and enrichment operations
• LocationApi: Geolocation and ASN intelligence
• OperationsApi: Async job management and tools

2. Response Structure

‍

All API methods return an AxiosResponse wrapper:

‍

interface AxiosResponse<T> {
    data: T;           // The actual response data
    status: number;    // HTTP status code
    statusText: string;
    headers: any;
    config: any;
}

‍

3. Include Parameter Patterns

‍

The SDK uses different patterns for include parameters:

• Single enrichment: String value for include parameter
• Bulk enrichment: Set with enum values

// Single enrichment - use string
await api.getIndicator('ip', '8.8.8.8', 'routing');

// Bulk enrichment - use Set with enums
import { BulkRequestIncludeEnum } from '@whisper-security/whisper-api-sdk';

const bulkRequest = {
    indicators: ['8.8.8.8'],
    include: new Set([
        BulkRequestIncludeEnum.Routing,
        BulkRequestIncludeEnum.Whois
    ])
};

‍

4. TypeScript Types

‍

The SDK includes comprehensive TypeScript interfaces:

‍

import type { 
    IndicatorResponse,
    LocationResponse,
    JobResponse,
    Job 
} from '@whisper-security/whisper-api-sdk';

‍

Authentication

‍

‍

import { Configuration } from '@whisper-security/whisper-api-sdk';

const configuration = new Configuration({
    basePath: 'https://api.whisper.security',
    accessToken: 'wsk_live_your_api_key_here'
});

‍

API Overview

‍

IndicatorsApi - Intelligence & Enrichment

‍

Core API for gathering intelligence on IPs and domains.

‍

Methods:

‍

‍

// Single indicator enrichment
getIndicator(
    type: 'ip' | 'domain',
    value: string,
    include?: string
): Promise<AxiosResponse<IndicatorResponse>>

// Historical data
getIndicatorHistory(
    type: string,
    value: string,
    limit?: number
): Promise<AxiosResponse<HistoryResponse>>

// Infrastructure relationships
getIndicatorGraph(
    type: string,
    value: string
): Promise<AxiosResponse<GraphResponse>>

// Domain subdomains
getSubdomains(
    domain: string,
    limit?: number
): Promise<AxiosResponse<SubdomainsResponse>>

// Similar domains
generateSimilarDomainsGet(
    domain: string,
    type?: string,
    limit?: number
): Promise<AxiosResponse<SimilarDomainsResponse>>

// Bulk enrichment (async)
bulkEnrichment(
    bulkRequest: BulkRequest
): Promise<AxiosResponse<JobResponse>>

// Search indicators (async)
searchIndicators(
    searchRequest: SearchRequest
): Promise<AxiosResponse<JobResponse>>

‍

Include Parameter Values:

‍

// Available string values for single enrichment
type IncludeModule = 
    | 'routing'      // BGP routing information
    | 'rpki'        // RPKI validation status
    | 'whois'       // WHOIS registration data
    | 'dns_details' // Detailed DNS records
    | 'ip_intelligence'; // IP intelligence and reputation

// Example usage
const ipData = await api.getIndicator('ip', '8.8.8.8', 'routing');
const domainData = await api.getIndicator('domain', 'example.com', 'whois');

‍

LocationApi - Geolocation Intelligence

‍

Geographic and network location services.

‍

Methods:

‍

// IP geolocation
getIpLocation(ip: string): Promise<AxiosResponse<void>>

// Search by location attributes
searchLocation(
    field: string,
    value: string,
    limit?: number
): Promise<AxiosResponse<void>>

‍

Note: LocationApi currently has incomplete TypeScript types. The API returns data, but TypeScript shows void.

‍

OperationsApi - Async Jobs & Tools

‍

Long-running operations and monitoring tools.

‍

Methods:

‍

// Job management
getJob(jobId: string): Promise<AxiosResponse<Job>>
listJobs(status?: string, limit?: number): Promise<AxiosResponse<Job[]>>

// Screenshots
createScreenshot(
    screenshotRequest: ScreenshotRequest
): Promise<AxiosResponse<JobResponse>>

// Infrastructure scanning
createScan(
    infraScanRequest: InfraScanRequest
): Promise<AxiosResponse<JobResponse>>

‍

Error Handling

‍

Error Types

‍

import { AxiosError } from 'axios';

// API errors are AxiosErrors with additional properties
interface ApiError extends AxiosError {
    response?: {
        status: number;
        data: {
            error?: string;
            message?: string;
            details?: any;
        };
    };
}

‍

‍

Support and Resources

• API Documentation: developer.whisper.security
• API Playground: dash.whisper.security/playground
• Support Email: support@whisper.security
• GitHub Issues: github.com/whisper-sec/sdk-typescript/issues
• NPM Package: npmjs.com/package/@whisper-security/whisper-api-sdk

‍

‍

‍

‍

‍

‍

‍