110 online 3 members  + Join RP Base  +
FreeScript

rdapper

by jakejarvis  ·  version 2026.11.15  ·  updated yesterday

No reviews yet

Downloads
0
Reviews
0
Size
152 KB
Code check
Clean
Licence
MIT
Released
Nov 2026

🎩 RDAP/WHOIS fetcher, parser, and normalizer for Node

rdapper
🎩 rdapper
RDAP‑first domain registration lookups with WHOIS fallback. Produces a single, normalized record shape regardless of source.

  • RDAP‑first lookup via IANA bootstrap with automatic WHOIS fallback when needed
  • Smart WHOIS client (TCP 43): authoritative TLD discovery, registrar referral follow, and curated exceptions
  • Rich, normalized results: registrar, contacts, nameservers, EPP statuses, key dates, DNSSEC, privacy flag, source metadata
  • RDAP enrichment: follows related/entity/registrar links (bounded) to fill in missing details
  • TypeScript‑first: shipped types, ESM‑only, zero external HTTP client (uses global fetch)

IMPORTANT
Edge runtimes (e.g., Vercel Edge, Cloudflare Workers) do not support WHOIS (TCP 43 via node:net). Use RDAP‑only mode by setting { rdapOnly: true }.

TIP
See rdapper in action on Domainstack!
Install
npm install rdapper

Quick Start
import { lookup } from "rdapper";

const { ok, record, error } = await lookup("example.com");

if (!ok) throw new Error(error);
console.log(record); // normalized DomainRecord

Normalize arbitrary input (domain or URL) to its registrable domain (eTLD+1):

import { toRegistrableDomain } from "rdapper";

toRegistrableDomain("https://sub.example.co.uk/page"); // => "example.co.uk"
toRegistrableDomain("spark-public.s3.amazonaws.com"); // => "amazonaws.com" (ICANN-only default)
toRegistrableDomain("www.google.uk.com"); // => "google.uk.com" (CentralNic sub-registry)
toRegistrableDomain("192.168.0.1"); // => null

Convenience helpers to quickly check availability:

import { isRegistered, isAvailable } from "rdapper";

await isRegistered("example.com"); // => true
await isRegistered("likely-unregistered-thing-320485230458.com"); // => false
await isAvailable("example.com"); // => false
await isAvailable("likely-unregistered-thing-320485230458.com"); // => true

API
  • lookup(domain, options?) => Promise
  • Tries RDAP first if supported by the domain’s TLD; if unavailable or fails, falls back to WHOIS (unless toggled off).
  • Result is { ok: boolean, record?: DomainRecord, error?: string }.
  • domain may be Unicode (münchen.de) and may carry surrounding whitespace or a trailing dot; the lowercase punycode form is what gets queried.
  • domain must be a registrable name (example.com, example.co.uk), not a subdomain or a bare public suffix: www.example.com fails with invalid_input naming example.com, since the registry would otherwise answer "not registered". Use toRegistrableDomain to normalize hostnames and URLs first.
  • toRegistrableDomain(input, options?) => string | null
  • Normalizes a domain or URL to its registrable domain (eTLD+1), the name lookup() accepts. A name under a sub-registry keeps its own label (google.uk.com, not uk.com).
  • Returns the registrable domain string, or null for IPs/invalid input; options are forwarded to tldts (e.g., allowPrivateDomains).
  • getDomainTld(domain, options?) => string | null
  • The suffix a name is registered under, matching the tld a lookup reports: the ICANN public suffix (co.uk), or a sub-registry's (uk.com for google.uk.com).
  • isRegistered(domain, options?) => Promise
  • isAvailable(domain, options?) => Promise
  • Reject when the lookup fails, with an RdapperError (exported) whose code, phase, server, and retryAfterMs mirror the result's errorCode, errorPhase, errorServer, and retryAfterMs. An abort keeps the name "AbortError".
  • finalizeContact(contact, redactedHint?) => Contact
  • Cleans a contact: drops placeholder values (recording them in redactedFields), drops a registry handle (JJ1234-IS) given as the name or organization, sets privacyService, resolves country/countryCode, and sets redacted. Safe to re-run on an already-cleaned contact, e.g. to upgrade contacts stored by an older version.
  • isPrivacyContact(contact) => boolean
  • True when the contact hides who it is: a privacy service is named, or something was withheld and no name or organization is left.
  • normalizeEppStatus(status) => string
  • Maps a status in either spelling to its EPP code ("client transfer prohibited" → "clientTransferProhibited", RDAP "active" → "ok"), leaving other values as they are. Useful for upgrading statuses stored by an older version.
CLI
For quick checks, a minimal CLI is included:

npx rdapper example.com example.org
echo "example.com" | npx rdapper

Domains are looked up one at a time, in order, printing each result as JSON; the exit code is 1 when any lookup fails.
Edge runtimes (e.g., Vercel Edge)
WHOIS requires a raw TCP connection over port 43 via node:net, which is not available on edge runtimes. rdapper lazily loads node:net only when the WHOIS path is taken.

  • Prefer RDAP only on edge:

import { lookup } from "rdapper";

const res = await lookup("example.com", { rdapOnly: true });

  • If rdapOnly is omitted and the code path reaches WHOIS on edge, rdapper throws a clear runtime error advising to run in Node or set { rdapOnly: true }.
Bootstrap Data Caching
By default, rdapper fetches IANA's RDAP bootstrap registry from [https://data.iana.org/rdap/dns.json](https://data.iana.org/rdap/dns.json) on every RDAP lookup to discover the authoritative RDAP servers for a given TLD. While this ensures you always have up-to-date server mappings, it also adds latency and a network dependency to each lookup.

For production applications that perform many domain lookups, you can take control of bootstrap data caching by fetching and caching the data yourself, then passing it to rdapper using the customBootstrapData option. This eliminates redundant network requests and gives you full control over cache invalidation.
**W

…