Kawaa Node.js SDK

Node.js SDK source for the Kawaa Email Verification API.

Features

• Single email verification with detailed results
• Batch verification with deduplication
• Webhook support for async notifications
• TypeScript support with full type definitions
• Automatic retries with exponential backoff
• Express/Connect middleware for webhooks

Local Development

Package registry availability is not guaranteed until the SDK publish process is verified.

npm install

Requirements

• Node.js 18.0.0 or higher

Quick Start

import { Kawaa } from 'kawaa';

const kawaa = new Kawaa('your-api-key');

// Verify a single email
const result = await kawaa.verify('[email protected]');

if (result.isValid) {
  console.log('Email is valid!');
  console.log(`Score: ${result.score}/100`);
}

API Reference

Constructor

const kawaa = new Kawaa(apiKey: string, options?: KawaaOptions);

Options:

• baseUrl - API base URL (default: https://api.kawaa.com)
• timeout - Request timeout in ms (default: 30000)
• maxRetries - Max retry attempts (default: 3)
• fetch - Custom fetch implementation

Single Email Verification

const result = await kawaa.verify('[email protected]');

console.log(result.email);        // '[email protected]'
console.log(result.status);       // 'valid' | 'invalid' | 'risky' | 'unknown' | 'spam_trap' | 'disposable' | 'role' | 'catch_all' ('pending' on sync timeout)
console.log(result.score);        // 0-100
console.log(result.isValid);      // true if status === 'valid'
console.log(result.isDeliverable); // true only when status is "valid"

// Flags
console.log(result.flags.disposable);   // Is disposable email
console.log(result.flags.role);         // Is role account (info@, support@)
console.log(result.flags.freeProvider); // Is free provider (gmail, yahoo)
console.log(result.flags.catchAll);     // Is catch-all domain

// Typo suggestion
if (result.suggestion) {
  console.log(`Did you mean: ${result.suggestion}`);
}

Batch Verification

const emails = [
  '[email protected]',
  '[email protected]',
  '[email protected]',
];

// Start batch job
const job = await kawaa.verifyBatch(emails);
console.log(`Job ID: ${job.jobId}`);
console.log(`Duplicates removed: ${job.duplicatesRemoved}`);
console.log(`Credits used: ${job.creditsUsed}`);

// Wait for completion with progress updates
const result = await kawaa.waitForJob(job.jobId, {
  timeout: 300000,    // 5 minutes
  pollInterval: 2000, // 2 seconds
  onProgress: (status) => {
    console.log(`Progress: ${status.progressPercent}%`);
  },
});

console.log(`Valid: ${result.validCount}`);
console.log(`Invalid: ${result.invalidCount}`);
console.log(`Risky: ${result.riskyCount}`);

// Or use the convenience method
const result = await kawaa.verifyBatchAndWait(emails);

Batch with Webhook

const job = await kawaa.verifyBatch(emails, {
  webhookUrl: 'https://your-server.com/webhook',
  webhookSecret: 'your-secret-key',
});

// Job will notify your webhook when complete
console.log(`Job ${job.jobId} started, webhook will be called on completion`);

Download Results

// Download as JSON
const results = await kawaa.downloadResults(jobId, 'json');
for (const r of results.results) {
  console.log(`${r.email}: ${r.status} (score: ${r.score})`);
}

// Download as CSV
const csv = await kawaa.downloadResults(jobId, 'csv');
fs.writeFileSync('results.csv', csv);

Account Information

const account = await kawaa.getAccount();

console.log(`Plan: ${account.plan}`);
console.log(`Credits remaining: ${account.creditsRemaining}`);
console.log(`Credits used: ${account.creditsUsed}`);

Webhook Handling

Express Middleware

import express from 'express';
import { webhookMiddleware } from 'kawaa/webhooks';

const app = express();

app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  webhookMiddleware(process.env.WEBHOOK_SECRET!),
  (req, res) => {
    const event = req.kawaaEvent;

    if (event.event === 'job.completed') {
      console.log(`Job ${event.jobId} completed!`);
      console.log(`Valid: ${event.results?.valid}`);
      console.log(`Download: ${event.downloadUrl}`);
    }

    res.sendStatus(200);
  }
);

Manual Verification

import { verifySignature, parseWebhook } from 'kawaa/webhooks';

// Verify signature
const isValid = verifySignature(
  requestBody,
  headers['x-kawaa-signature'],
  process.env.WEBHOOK_SECRET!
);

if (!isValid) {
  throw new Error('Invalid signature');
}

// Parse payload
const event = parseWebhook(requestBody);
console.log(event.event);  // 'job.completed'
console.log(event.jobId);  // 'job-123'

Next.js API Route (App Router)

// app/api/webhook/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { parseWebhook, verifySignature } from 'kawaa/webhooks';

export async function POST(request: NextRequest) {
  const body = await request.text();
  const signature = request.headers.get('x-kawaa-signature') ?? '';

  if (!verifySignature(body, signature, process.env.WEBHOOK_SECRET!)) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const event = parseWebhook(body);

  // Process the event
  if (event.event === 'job.completed') {
    // Handle completed job
  }

  return NextResponse.json({ received: true });
}

Error Handling

import {
  Kawaa,
  KawaaError,
  AuthenticationError,
  RateLimitError,
  InsufficientCreditsError,
  ValidationError,
} from 'kawaa';

try {
  const result = await kawaa.verify('[email protected]');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof InsufficientCreditsError) {
    console.error('Not enough credits');
  } else if (error instanceof ValidationError) {
    console.error('Invalid request:', error.message);
  } else if (error instanceof KawaaError) {
    console.error('API error:', error.message);
  }
}

TypeScript Support

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

import type {
  VerificationResult,
  VerificationFlags,
  BatchJobResult,
  JobStatusResult,
  DownloadResult,
  AccountInfo,
  WebhookEvent,
  KawaaOptions,
} from 'kawaa';

License

MIT