Domain Plugin for OpenCode

Check domain name availability and retrieve WHOIS information with multiple reliable providers and automatic fallback.

Features

• ✅ Multiple WHOIS Providers - Choose from 5 different WHOIS providers
• ✅ Automatic Fallback - If one provider fails, automatically tries the next
• ✅ Free & Commercial Options - Start free, upgrade to commercial for better coverage
• ✅ Check Availability Across TLDs - Check 20+ popular TLDs at once
• ✅ Detailed WHOIS Information - Get registrar, dates, nameservers, and owner details
• ✅ Bulk Domain Checking - Check multiple domains in a single command
• ✅ DNS Resolution Verification - Fast DNS checks before WHOIS queries
• ✅ Provider Status Tracking - See which provider was used for each lookup

WHOIS Providers

Free Providers (No API Key Required)

1. Whoiser (Recommended Default)

• 📦 NPM package whoiser
• ✅ Most reliable free option
• ✅ Auto-discovery of WHOIS servers
• ✅ Supports 1000+ TLDs
• ✅ No rate limits for reasonable use
• 🎯 Best for: Most use cases, general domain checking

2. RDAP (Registration Data Access Protocol)

• 📦 Modern protocol via whois-rdap
• ✅ Standardized JSON responses
• ✅ More reliable than traditional WHOIS
• ✅ Better data structure
• ⚠️ Limited TLD support (growing)
• 🎯 Best for: Modern TLDs, structured data needs

3. System WHOIS (Fallback)

• 🖥️ Uses system whois command
• ✅ Available on most Unix systems
• ⚠️ Inconsistent output formats
• ⚠️ Depends on system configuration
• 🎯 Best for: Fallback when other providers fail

Commercial Providers (API Key Required)

4. WhoisXML API ⭐

• 🌐 Website: whoisxmlapi.com
• ✅ Most comprehensive coverage (7,596+ TLDs)
• ✅ Historical WHOIS data
• ✅ 99.9% uptime SLA
• ✅ Bulk lookup support
• 💰 Pricing: Free tier available, paid plans from $30/month
• 🎯 Best for: Production apps, maximum reliability

5. WhoisFreaks

• 🌐 Website: whoisfreaks.com
• ✅ 652M+ domain database
• ✅ 1,594 TLD support
• ✅ Bulk lookups (100 domains at once)
• ✅ Historical records
• 💰 Pricing: Free tier available, paid plans from $19/month
• 🎯 Best for: Bulk operations, cost-effective commercial option

Quick Start

1. Install Dependencies

cd pets/domain
npm install

The plugin automatically installs free provider packages (whoiser and whois-rdap).

2. Basic Usage (No Configuration)

Works out of the box with free providers:

opencode run "check if mycompany is available"

3. Optional: Add Commercial Providers

For enhanced reliability, add API keys to .env:

cp .env.example .env
# Edit .env with your API keys

Configuration

Environment Variables

# Optional Commercial Providers
WHOISXML_API_KEY=your_whoisxml_api_key_here
WHOISFREAKS_API_KEY=your_whoisfreaks_api_key_here

# Optional Provider Order
DOMAIN_PROVIDER_ORDER=whoiser,rdap,system

Default Provider Order

If no configuration is provided:

1. WhoisXML (if API key configured)
2. WhoisFreaks (if API key configured)
3. Whoiser (free, recommended)
4. RDAP (free, modern protocol)
5. System WHOIS (fallback)

Available Tools

1. check-domain-availability

Check if a domain name is available across multiple TLDs.

Parameters:

• domainName (required): Base domain without TLD (e.g., "mycompany")
• tlds (optional): Array of TLDs to check (defaults to 20 popular ones)
• provider (optional): Specific provider to use

Examples:

# Check with default TLDs
opencode run "check domain availability for techstartup"

# Check specific TLDs
opencode run "check if mycompany is available as .com, .io, .ai"

# Use specific provider
opencode run "check techstartup availability using whoiser"

Response:

{
  "success": true,
  "summary": {
    "total": 20,
    "available": 5,
    "taken": 14,
    "unknown": 1
  },
  "availableDomains": [
    { "domain": "techstartup.info", "provider": "whoiser" },
    { "domain": "techstartup.biz", "provider": "whoiser" }
  ]
}

2. check-single-domain

Quick check for a specific complete domain.

Parameters:

• domain (required): Full domain with TLD
• provider (optional): Specific provider

Examples:

opencode run "check if example.com is available"
opencode run "is mysite.io taken?"

Response:

{
  "success": true,
  "available": false,
  "status": "taken",
  "providerUsed": "whoiser"
}

3. get-whois-info

Get detailed WHOIS information for a registered domain.

Parameters:

• domain (required): Full domain name
• provider (optional): Specific provider

Examples:

opencode run "get whois info for google.com"
opencode run "who owns github.com?"
opencode run "when does mycompany.com expire?"

Response:

{
  "success": true,
  "domain": "google.com",
  "providerUsed": "whoiser",
  "data": {
    "registrar": "MarkMonitor Inc.",
    "createdDate": "1997-09-15",
    "expiryDate": "2028-09-14",
    "updatedDate": "2024-01-10",
    "nameServers": ["ns1.google.com", "ns2.google.com"],
    "status": ["clientDeleteProhibited"],
    "registrant": {
      "organization": "Google LLC"
    }
  }
}

4. bulk-domain-check

Check multiple complete domains at once.

Parameters:

• domains (required): Array of complete domains
• provider (optional): Specific provider for all checks

Examples:

opencode run "check these domains: test.com, test.io, test.net"

Response:

{
  "success": true,
  "total": 3,
  "summary": {
    "available": 1,
    "taken": 2
  },
  "results": {
    "available": [
      { "domain": "test.io", "provider": "whoiser" }
    ],
    "taken": [
      { "domain": "test.com", "provider": "whoiser" },
      { "domain": "test.net", "provider": "whoiser" }
    ]
  }
}

5. list-whois-providers

See available providers and their configuration status.

Examples:

opencode run "list available whois providers"
opencode run "show domain providers"

Response:

{
  "success": true,
  "currentOrder": ["whoiser", "rdap", "system"],
  "providers": [
    {
      "name": "whoiser",
      "configured": true,
      "requiresApiKey": false,
      "status": "ready"
    },
    {
      "name": "whoisxml",
      "configured": false,
      "requiresApiKey": true,
      "status": "needs API key"
    }
  ],
  "recommendations": {
    "free": ["whoiser", "rdap"],
    "commercial": ["whoisxml", "whoisfreaks"]
  }
}

Provider Selection Guide

When to Use Each Provider

| Provider | Use Case | Cost | Reliability | |----------|----------|------|-------------| | whoiser | General use, most domains | Free | ⭐⭐⭐⭐ | | rdap | Modern TLDs, structured data | Free | ⭐⭐⭐⭐ | | whoisxml | Production apps, max reliability | Paid | ⭐⭐⭐⭐⭐ | | whoisfreaks | Bulk operations, cost-effective | Paid | ⭐⭐⭐⭐ | | system | Fallback only | Free | ⭐⭐ |

Recommended Configurations

For Personal Use (Free)

DOMAIN_PROVIDER_ORDER=whoiser,rdap,system

For Professional Use

WHOISXML_API_KEY=your_key_here
DOMAIN_PROVIDER_ORDER=whoisxml,whoiser,rdap

For Bulk Operations

WHOISFREAKS_API_KEY=your_key_here
DOMAIN_PROVIDER_ORDER=whoisfreaks,whoiser

How It Works

1. DNS Resolution Check

First, the plugin attempts to resolve the domain using DNS:

• ✅ If domain resolves → marked as "taken"
• ❌ If domain doesn't resolve → proceed to WHOIS check

2. WHOIS Lookup with Fallback

Query WHOIS providers in configured order:

1. Try first provider in list
2. If error, try next provider
3. Continue until success or all providers exhausted

3. Availability Determination

Analyze WHOIS response:

• Look for "available" indicators (no match, not found, etc.)
• Look for "taken" indicators (creation date, registrar, etc.)
• Return structured result with provider information

Common Use Cases

Finding a Startup Name

opencode run "I need a domain for my AI startup, check availability for aiassistant with TLDs: com, io, ai, co"

Domain Portfolio Management

opencode run "check these domains I own: site1.com, site2.io, site3.net and tell me expiry dates"

Competitor Research

opencode run "get whois info for competitor.com to see when it was registered and expires"

Bulk Domain Research

opencode run "check availability for these 10 domain names: [list]"

Advantages Over Original

✅ Multiple Providers

• Original: Single system whois command
• Now: 5 providers with automatic fallback

✅ Better Reliability

• Original: Single point of failure
• Now: Automatic fallback if provider fails

✅ Structured Data

• Original: Inconsistent text parsing
• Now: Normalized, structured JSON responses

✅ Provider Choice

• Original: System-dependent
• Now: Choose free or commercial providers

✅ Better Coverage

• Original: Limited by system whois
• Now: Access to 7,596+ TLDs (with commercial)

Troubleshooting

Provider Errors

"All providers failed"

• Check internet connection
• Verify API keys if using commercial providers
• Try with different provider explicitly

"Provider not configured"

• Add API key to .env for commercial providers
• Check .env file is in correct location

Slow Responses

• WHOIS queries can be slow (5-15 seconds per domain)
• Use commercial providers for faster response times
• Consider caching results for repeated queries

Inconsistent Results

• Different providers may return different data formats
• Domain availability can change rapidly
• Always verify through official registrar

Rate Limiting

• Free providers: Reasonable use (1-2 queries/second)
• Commercial providers: Higher limits (check provider docs)
• Plugin: Built-in 500ms delay between checks

Getting API Keys

WhoisXML API

1. Visit whoisxmlapi.com
2. Sign up for free tier (500 requests/month)
3. Get API key from dashboard
4. Add to .env: WHOISXML_API_KEY=your_key

WhoisFreaks

1. Visit whoisfreaks.com
2. Sign up for free tier (100 requests/day)
3. Get API key from dashboard
4. Add to .env: WHOISFREAKS_API_KEY=your_key

Architecture

Self-Contained Plugin Design

This plugin follows the OpenPets factory-based architecture pattern where all provider logic is contained within the plugin itself:

pets/domain/
├── index.ts              # Main plugin with factory pattern
├── domain-checker.ts     # Domain availability checker
├── providers/            # All WHOIS provider implementations
│   ├── base.ts          # Base provider interface
│   ├── whoiser.ts       # Whoiser provider
│   ├── rdap.ts          # RDAP provider
│   ├── whoisxml.ts      # WhoisXML API provider
│   ├── whoisfreaks.ts   # WhoisFreaks API provider
│   ├── system.ts        # System whois provider
│   ├── manager.ts       # Provider manager with fallbacks
│   └── index.ts         # Provider exports
├── package.json         # Plugin dependencies
├── .env.example         # Configuration template
└── README.md           # This file

Key Design Principles

1. Factory Pattern: Uses createPlugin() from @/core/plugin-factory for consistent tool creation
2. Provider-Agnostic: All provider logic is self-contained and swappable
3. Self-Sufficient: No dependencies on src/utils/ - everything needed is in the plugin
4. Type-Safe: Zod schemas for all tool parameters
5. Graceful Fallbacks: Automatic provider failover when errors occur

Migration from Utils

This plugin previously relied on shared utilities in src/utils/domain/. It has been migrated to be fully self-contained following the pet-creator pattern:

• ✅ All provider implementations moved from src/utils/domain/providers/ to pets/domain/providers/
• ✅ Domain checker logic moved from src/utils/domain/index.ts to pets/domain/domain-checker.ts
• ✅ Dependencies (whoiser, whois-rdap) added to plugin's package.json
• ✅ Plugin is now independent and can be used without external utilities

License

MIT