domain-age-checker

Check the registration age of a domain via a WHOIS-like API. Returns creation date, expiry date, and age in years/months/days.

Installation

npm install domain-age-checker

Usage

Class-based API

import { DomainAgeChecker } from "domain-age-checker";

const checker = new DomainAgeChecker({
  endpoint: "https://api.example.com/whois",
  token: "your-api-token",
});

const result = await checker.check("example.com");
console.log(result.age.years); // e.g., 10

Functional API

import { checkDomainAge } from "domain-age-checker";

const result = await checkDomainAge(
  "https://api.example.com/whois",
  "your-api-token",
  "example.com",
);

API

DomainAgeChecker

constructor(options: DomainAgeCheckerOptions)

| Option | Type | Default | Description | |-----------|----------|----------|------------------------------------------| | endpoint | string | — | WHOIS API endpoint URL (required) | | token | string | — | API authentication token (required) | | timeout | number | 10000 | Request timeout in milliseconds |

check(domain: string): Promise<DomainAgeResult>

checkDomainAge(endpoint, token, domain): Promise<DomainAgeResult>

Return Type: DomainAgeResult

| Field | Type | Description | |-------------|------------------------------------|--------------------------------------| | domain | string | The queried domain | | createdDate | string \| null | Domain creation date (DD-MM-YYYY) | | expiryDate | string \| null | Domain expiry date (DD-MM-YYYY) | | updatedDate | string \| null | Domain last updated date | | age | { years, months, days, totalDurationInDays } | Domain age breakdown | | ageInDays | number \| null (deprecated) | Use age.totalDurationInDays | | ageInYears | number \| null (deprecated) | Use age.years | | ageInMonths | number \| null (deprecated) | Use age.months | | raw | unknown | Raw API response data |

Error Handling

The package throws typed errors:

• DomainAgeValidationError — invalid arguments (missing token, malformed URL, invalid domain)
• DomainAgeApiError — API request failures (network error, non-2xx status, unsuccessful response)

import { DomainAgeError, DomainAgeValidationError, DomainAgeApiError } from "domain-age-checker";

try {
  const result = await checker.check("example.com");
} catch (error) {
  if (error instanceof DomainAgeValidationError) {
    console.error("Validation failed:", error.message);
  } else if (error instanceof DomainAgeApiError) {
    console.error("API error (status:", error.status, "):", error.message);
  }
}

License

MIT