@springmusk/who-is/README.md

Professional WHOIS data scraping module with structured parsing and batch processing capabilities

# who-is

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)

A professional WHOIS data scraping module with structured parsing and batch processing capabilities.

## Features

- 🔍 **WHOIS Scraping** - Extract WHOIS data from domains
- 📊 **Structured Parsing** - Convert raw WHOIS data into structured JSON
- 🚀 **Batch Processing** - Process multiple domains concurrently
- 🔄 **Automatic Retry** - Built-in retry mechanism for failed requests
- ⚡ **TypeScript Support** - Full type definitions included
- 🛡️ **Error Handling** - Custom error classes for better error management

## Installation

```bash
npm i @springmusk/who-is
```

## Quick Start

```javascript
const { Whois } = require('@springmusk/who-is');

const scraper = new Whois();

async function main() {
  try {
    // Single domain lookup
    const result = await scraper.scrape('example.com');
    console.log('Domain info:', result);
    
    // Batch processing
    const batchResults = await scraper.scrapeMultiple([
      'example.com',
      'github.com',
      'stackoverflow.com'
    ]);
    console.log('Batch results:', batchResults);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();
```

### TypeScript Usage

```typescript
import { Whois, WhoisResult, WhoisConfig } from '@springmusk/who-is';

const scraper = new Whois({
  outputFormat: 'json',
  http: {
    timeout: 30000,
    maxRetries: 3
  }
});

const result: WhoisResult = await scraper.scrape('example.com');
```

## API Reference

### Whois

The main class for WHOIS data scraping operations.

#### Constructor

```typescript
constructor(config?: WhoisConfig)
```

Configuration options:
- `outputFormat`: 'json' | 'raw' (default: 'json')
- `http`: HTTP client configuration
  - `timeout`: Request timeout in ms (default: 30000)
  - `maxRetries`: Maximum retry attempts (default: 3)
  - `retryDelay`: Delay between retries in ms (default: 1000)
  - `userAgent`: Custom user agent string

#### Methods

##### scrape(domain: string): Promise<WhoisResult>

Scrapes WHOIS data for a single domain.

**Parameters:**
- `domain` (string): The domain name to lookup

**Returns:** Promise resolving to `WhoisResult`

**Throws:**
- `WhoisScrapingError`: When scraping fails
- `WhoisParsingError`: When data parsing fails

##### scrapeMultiple(domains: string[], options?: ScrapingOptions): Promise<BatchResult>

Scrapes WHOIS data for multiple domains.

**Parameters:**
- `domains` (string[]): Array of domain names
- `options`: Optional configuration
  - `concurrent`: Number of concurrent requests (default: 3)
  - `continueOnError`: Continue on error (default: true)

### Interfaces

```typescript
interface WhoisConfig {
  outputFormat?: 'json' | 'raw';
  baseUrl?: string;
  http?: HttpClientConfig;
}

interface WhoisResult {
  domain: string;
  scrapedAt: string;
  pageTitle: string;
  registry: ParsedWhoisData | string | null;
  registrar: ParsedWhoisData | string | null;
}

interface BatchResult {
  results: WhoisResult[];
  errors?: BatchError[];
  summary: {
    total: number;
    successful: number;
    failed: number;
  };
}
```

## Error Handling

```javascript
const { Whois, WhoisScrapingError, WhoisParsingError } = require('@springmusk/who-is');

try {
  const result = await scraper.scrape('example.com');
} catch (error) {
  if (error instanceof WhoisScrapingError) {
    console.error('Scraping failed:', error.message);
  } else if (error instanceof WhoisParsingError) {
    console.error('Parsing failed:', error.message);
  }
}
```

## Example: Batch Processing with Error Handling

```javascript
async function safeBatchProcess(domains) {
  const scraper = new Whois({
    http: { timeout: 30000, maxRetries: 2 }
  });

  const results = await scraper.scrapeMultiple(domains, {
    concurrent: 2,
    continueOnError: true
  });
  
  // Process successful results
  results.results.forEach(result => {
    console.log(`✅ ${result.domain}: ${result.registry?.registrar || 'N/A'}`);
  });
  
  // Handle errors
  results.errors?.forEach(error => {
    console.error(`❌ ${error.domain}: ${error.error}`);
  });
  
  return results;
}
```

## Requirements

- Node.js >= 14.0.0
- npm >= 6.0.0

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/springmusk026/who-is/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/springmusk026/who-is/discussions)