rdapper 0.9.1 → 0.10.0

package/README.md

@@ -2,12 +2,17 @@
 
 RDAP‑first domain registration lookups with WHOIS fallback. Produces a single, normalized record shape regardless of source.
 
-- RDAP discovery via IANA bootstrap (`https://data.iana.org/rdap/dns.json`)
-- WHOIS TCP 43 client with TLD discovery, registrar referral follow, and curated exceptions
-- Normalized output: registrar, contacts, nameservers, statuses, dates, DNSSEC, privacy flag, source metadata
-- TypeScript types included; ESM‑only; no external HTTP client (uses global `fetch`)
+- RDAP‑first lookup via [IANA bootstrap](https://data.iana.org/rdap/dns.json) 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`)
 
-### [🦉 See it in action on hoot.sh!](https://hoot.sh)
+> [!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**](https://domainstack.io)!
 
 ## Install
 
@@ -18,23 +23,14 @@ npm install rdapper
 ## Quick Start
 
 ```ts
-import { lookupDomain } from "rdapper";
+import { lookup } from "rdapper";
 
-const { ok, record, error } = await lookupDomain("example.com");
+const { ok, record, error } = await lookup("example.com");
 
 if (!ok) throw new Error(error);
 console.log(record); // normalized DomainRecord
 ```
 
-Also available:
-
-```ts
-import { isRegistered, isAvailable } from "rdapper";
-
-await isRegistered("example.com"); // => true
-await isAvailable("likely-unregistered-thing-320485230458.com"); // => false
-```
-
 Normalize arbitrary input (domain or URL) to its registrable domain (eTLD+1):
 
 ```ts
@@ -45,11 +41,25 @@ toRegistrableDomain("spark-public.s3.amazonaws.com");   // => "amazonaws.com" (I
 toRegistrableDomain("192.168.0.1");                      // => null
 ```
 
+Convenience helpers to quickly check availability:
+
+```ts
+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
 
-- `lookupDomain(domain, options?) => Promise<LookupResult>`
+- `lookup(domain, options?) => Promise<LookupResult>`
   - 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 }`.
+- `toRegistrableDomain(input, options?) => string | null`
+  - Normalizes a domain or URL to its registrable domain (eTLD+1).
+  - Returns the registrable domain string, or `null` for IPs/invalid input; [options](https://github.com/remusao/tldts/blob/master/packages/tldts-core/src/options.ts) are forwarded to `tldts` (e.g., `allowPrivateDomains`).
 - `isRegistered(domain, options?) => Promise<boolean>`
 - `isAvailable(domain, options?) => Promise<boolean>`
 
@@ -64,17 +74,17 @@ echo "example.com" | npx rdapper
 
 ### 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. This package lazily loads `node:net` only when the WHOIS code path runs. To use rdapper safely on 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:
+- Prefer RDAP only on edge:
 
 ```ts
-import { lookupDomain } from "rdapper";
+import { lookup } from "rdapper";
 
-const res = await lookupDomain("example.com", { rdapOnly: true });
+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 indicating WHOIS is unsupported on edge and to run in Node or set `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 }`.
 
 ### Options
 
@@ -98,7 +108,7 @@ The exact presence of fields depends on registry/registrar data and whether RDAP
 ```ts
 interface DomainRecord {
   domain: string;             // normalized name (unicode when available)
-  tld: string;                // terminal TLD label (e.g., "com")
+  tld: string;                // public suffix (can be multi-label, e.g., "com", "co.uk")
   isRegistered: boolean;      // availability heuristic (WHOIS) or true (RDAP)
   isIDN?: boolean;            // uses punycode labels (xn--)
   unicodeName?: string;       // RDAP unicodeName when provided
@@ -152,7 +162,7 @@ interface DomainRecord {
   }>;
   privacyEnabled?: boolean;   // registrant appears privacy-redacted based on keyword heuristics
   whoisServer?: string;       // authoritative WHOIS queried (if any)
-  rdapServers?: string[];     // RDAP base URLs tried
+  rdapServers?: string[];     // RDAP URLs tried (bootstrap bases and related/entity links)
   rawRdap?: unknown;          // raw RDAP JSON (only when options.includeRaw)
   rawWhois?: string;          // raw WHOIS text (only when options.includeRaw)
   source: "rdap" | "whois";   // which path produced data
@@ -191,13 +201,13 @@ Timeouts are enforced per request using a simple race against `timeoutMs` (defau
 
 ## Development
 
-- Build: `npm run build`
-- Test: `npm test` (Vitest)
+- Build: `npm run build` ([tsdown](https://tsdown.dev/))
+- Test: `npm test` ([Vitest](https://vitest.dev/))
   - By default, tests are offline/deterministic.
-  - Watch mode: `npm run test:watch`
-  - Coverage: `npm run test:coverage`
-  - Smoke tests that hit the network are gated by `SMOKE=1`, e.g. `SMOKE=1 npm run test:smoke`.
-- Lint/format: `npm run lint` (Biome)
+  - Watch mode: `npm run dev`
+  - Coverage: `npm run test:run -- --coverage`
+  - Smoke tests that hit the network are gated by `SMOKE=1`, e.g. `SMOKE=1 npm test`.
+- Lint/format: `npm run lint` ([Biome](https://biomejs.dev/))
 
 Project layout:
 
@@ -214,7 +224,7 @@ Project layout:
 - Some TLDs provide no RDAP service; `rdapOnly: true` will fail for them.
 - Registries may throttle or block WHOIS; respect rate limits and usage policies.
 - Field presence depends on source and privacy policies (e.g., redaction/withholding).
-- Public suffix detection uses `tldts` with ICANN‑only defaults (Private section is ignored). If you need behavior closer to `psl` that considers private suffixes, see the `allowPrivateDomains` option in the `tldts` docs (rdapper currently sticks to ICANN‑only by default). See: [tldts migration notes](https://github.com/remusao/tldts#migrating-from-other-libraries).
+- Public suffix detection uses `tldts` with ICANN‑only defaults (Private section is ignored). You can pass options through to `tldts` via `toRegistrableDomain`/`getDomainParts`/`getDomainTld` (e.g., `allowPrivateDomains`) to customize behavior. See: [tldts migration notes](https://github.com/remusao/tldts#migrating-from-other-libraries).
 
 ## License
 

package/bin/cli.js

@@ -6,14 +6,14 @@
 //   echo "example.com" | npx rdapper
 
 import { createInterface } from "node:readline";
-import { lookupDomain } from "../dist/index.js";
+import { lookup } from "../dist/index.js";
 
 async function main() {
   if (process.argv.length > 2) {
     // URL(s) specified in the command arguments
     console.log(
       JSON.stringify(
-        await lookupDomain(process.argv[process.argv.length - 1]),
+        await lookup(process.argv[process.argv.length - 1]),
         null,
         2,
       ),
@@ -24,7 +24,7 @@ async function main() {
       input: process.stdin,
     });
     rlInterface.on("line", async (line) => {
-      console.log(JSON.stringify(await lookupDomain(line), null, 2));
+      console.log(JSON.stringify(await lookup(line), null, 2));
     });
   }
 }

package/dist/index.d.ts

@@ -129,11 +129,14 @@ type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Respo
 //#region src/lib/domain.d.ts
 type ParseOptions = Parameters<typeof parse>[1];
 /**
- * Parse a domain into its parts. Accepts options which are passed to tldts.parse().
+ * Parse a domain into its parts. Passes options to `tldts.parse()`.
  * @see https://github.com/remusao/tldts/blob/master/packages/tldts-core/src/options.ts
  */
 declare function getDomainParts(domain: string, opts?: ParseOptions): ReturnType<typeof parse>;
-/** Get the TLD (ICANN-only public suffix) of a domain. */
+/**
+ * Get the TLD (ICANN-only public suffix) of a domain. Passes options to `tldts.parse()`.
+ * @see https://github.com/remusao/tldts/blob/master/packages/tldts-core/src/options.ts
+ */
 declare function getDomainTld(domain: string, opts?: ParseOptions): string | null;
 /**
  * Basic domain validity check (hostname-like), not performing DNS or RDAP.
@@ -141,7 +144,9 @@ declare function getDomainTld(domain: string, opts?: ParseOptions): string | nul
 declare function isLikelyDomain(value: string): boolean;
 /**
  * Normalize arbitrary input (domain or URL) to its registrable domain (eTLD+1).
- * Returns null when the input is not a valid ICANN domain (e.g., invalid TLD, IPs).
+ * Passes options to `tldts.parse()`.
+ * Returns null when the input is not a valid ICANN domain (e.g., invalid TLD, IPs)
+ * @see https://github.com/remusao/tldts/blob/master/packages/tldts-core/src/options.ts
  */
 declare function toRegistrableDomain(input: string, opts?: ParseOptions): string | null;
 //#endregion
@@ -150,12 +155,20 @@ declare function toRegistrableDomain(input: string, opts?: ParseOptions): string
  * High-level lookup that prefers RDAP and falls back to WHOIS.
  * Ensures a standardized DomainRecord, independent of the source.
  */
-declare function lookupDomain(domain: string, opts?: LookupOptions): Promise<LookupResult>;
-/** Determine if a domain appears available (not registered).
- * Performs a lookup and resolves to a boolean. Rejects on lookup error. */
+declare function lookup(domain: string, opts?: LookupOptions): Promise<LookupResult>;
+/**
+ * Determine if a domain appears available (not registered).
+ * Performs a lookup and resolves to a boolean. Rejects on lookup error.
+ */
 declare function isAvailable(domain: string, opts?: LookupOptions): Promise<boolean>;
-/** Determine if a domain appears registered.
- * Performs a lookup and resolves to a boolean. Rejects on lookup error. */
+/**
+ * Determine if a domain appears registered.
+ * Performs a lookup and resolves to a boolean. Rejects on lookup error.
+ */
 declare function isRegistered(domain: string, opts?: LookupOptions): Promise<boolean>;
+/**
+ * @deprecated Use `lookup` instead.
+ */
+declare const lookupDomain: typeof lookup;
 //#endregion
-export { Contact, DomainRecord, FetchLike, LookupOptions, LookupResult, LookupSource, Nameserver, RegistrarInfo, StatusEvent, getDomainParts, getDomainTld, isAvailable, isLikelyDomain, isRegistered, lookupDomain, toRegistrableDomain };
+export { Contact, DomainRecord, FetchLike, LookupOptions, LookupResult, LookupSource, Nameserver, RegistrarInfo, StatusEvent, getDomainParts, getDomainTld, isAvailable, isLikelyDomain, isRegistered, lookup, lookupDomain, toRegistrableDomain };

package/dist/index.js

@@ -2,13 +2,16 @@ import { parse } from "tldts";
 
 //#region src/lib/domain.ts
 /**
-* Parse a domain into its parts. Accepts options which are passed to tldts.parse().
+* Parse a domain into its parts. Passes options to `tldts.parse()`.
 * @see https://github.com/remusao/tldts/blob/master/packages/tldts-core/src/options.ts
 */
 function getDomainParts(domain, opts) {
 	return parse(domain, { ...opts });
 }
-/** Get the TLD (ICANN-only public suffix) of a domain. */
+/**
+* Get the TLD (ICANN-only public suffix) of a domain. Passes options to `tldts.parse()`.
+* @see https://github.com/remusao/tldts/blob/master/packages/tldts-core/src/options.ts
+*/
 function getDomainTld(domain, opts) {
 	return getDomainParts(domain, {
 		allowPrivateDomains: false,
@@ -24,7 +27,9 @@ function isLikelyDomain(value) {
 }
 /**
 * Normalize arbitrary input (domain or URL) to its registrable domain (eTLD+1).
-* Returns null when the input is not a valid ICANN domain (e.g., invalid TLD, IPs).
+* Passes options to `tldts.parse()`.
+* Returns null when the input is not a valid ICANN domain (e.g., invalid TLD, IPs)
+* @see https://github.com/remusao/tldts/blob/master/packages/tldts-core/src/options.ts
 */
 function toRegistrableDomain(input, opts) {
 	const raw = (input ?? "").trim();
@@ -39,26 +44,6 @@ function toRegistrableDomain(input, opts) {
 	if (domain === "") return null;
 	return domain.toLowerCase();
 }
-const WHOIS_AVAILABLE_PATTERNS = [
-	/\bno match\b/i,
-	/\bnot found\b/i,
-	/\bno entries found\b/i,
-	/\bno data found\b/i,
-	/\bavailable for registration\b/i,
-	/\bdomain\s+available\b/i,
-	/\bdomain status[:\s]+available\b/i,
-	/\bobject does not exist\b/i,
-	/\bthe queried object does not exist\b/i,
-	/\bstatus:\s*free\b/i,
-	/\bstatus:\s*available\b/i,
-	/\bno object found\b/i,
-	/\bnicht gefunden\b/i,
-	/\bpending release\b/i
-];
-function isWhoisAvailable(text) {
-	if (!text) return false;
-	return WHOIS_AVAILABLE_PATTERNS.some((re) => re.test(text));
-}
 
 //#endregion
 //#region src/lib/async.ts
@@ -839,6 +824,29 @@ function preferLatestIso(a, b) {
 
 //#endregion
 //#region src/whois/normalize.ts
+const WHOIS_AVAILABLE_PATTERNS = [
+	/\bno match\b/i,
+	/\bnot found\b/i,
+	/\bno entries found\b/i,
+	/\bno data found\b/i,
+	/\bavailable for registration\b/i,
+	/\bdomain\s+available\b/i,
+	/\bdomain status[:\s]+available\b/i,
+	/\bobject does not exist\b/i,
+	/\bthe queried object does not exist\b/i,
+	/\bstatus:\s*free\b/i,
+	/\bstatus:\s*available\b/i,
+	/\bno object found\b/i,
+	/\bnicht gefunden\b/i,
+	/\bpending release\b/i
+];
+/**
+* Best-effort heuristic to determine if a WHOIS response indicates the domain is available.
+*/
+function isAvailableByWhois(text) {
+	if (!text) return false;
+	return WHOIS_AVAILABLE_PATTERNS.some((re) => re.test(text));
+}
 /**
 * Convert raw WHOIS text into our normalized DomainRecord.
 * Heuristics cover many gTLD and ccTLD formats; exact fields vary per registry.
@@ -937,7 +945,7 @@ function normalizeWhois(domain, tld, whoisText, whoisServer, includeRaw = false)
 	return {
 		domain,
 		tld,
-		isRegistered: !isWhoisAvailable(whoisText),
+		isRegistered: !isAvailableByWhois(whoisText),
 		isIDN: /(^|\.)xn--/i.test(domain),
 		unicodeName: void 0,
 		punycodeName: void 0,
@@ -1066,8 +1074,8 @@ async function followWhoisReferrals(initialServer, domain, opts) {
 		visited.add(normalized);
 		try {
 			const res = await whoisQuery(next, domain, opts);
-			const registeredBefore = !isWhoisAvailable(current.text);
-			const registeredAfter = !isWhoisAvailable(res.text);
+			const registeredBefore = !isAvailableByWhois(current.text);
+			const registeredAfter = !isAvailableByWhois(res.text);
 			if (registeredBefore && !registeredAfter) break;
 			current = res;
 		} catch {
@@ -1099,8 +1107,8 @@ async function collectWhoisReferralChain(initialServer, domain, opts) {
 		visited.add(normalized);
 		try {
 			const res = await whoisQuery(next, domain, opts);
-			const registeredBefore = !isWhoisAvailable(current.text);
-			const registeredAfter = !isWhoisAvailable(res.text);
+			const registeredBefore = !isAvailableByWhois(current.text);
+			const registeredAfter = !isAvailableByWhois(res.text);
 			if (registeredBefore && !registeredAfter) break;
 			results.push(res);
 			current = res;
@@ -1121,7 +1129,7 @@ function normalize(server) {
 * High-level lookup that prefers RDAP and falls back to WHOIS.
 * Ensures a standardized DomainRecord, independent of the source.
 */
-async function lookupDomain(domain, opts) {
+async function lookup(domain, opts) {
 	try {
 		if (!isLikelyDomain(domain)) return {
 			ok: false,
@@ -1181,20 +1189,28 @@ async function lookupDomain(domain, opts) {
 		};
 	}
 }
-/** Determine if a domain appears available (not registered).
-* Performs a lookup and resolves to a boolean. Rejects on lookup error. */
+/**
+* Determine if a domain appears available (not registered).
+* Performs a lookup and resolves to a boolean. Rejects on lookup error.
+*/
 async function isAvailable(domain, opts) {
-	const res = await lookupDomain(domain, opts);
+	const res = await lookup(domain, opts);
 	if (!res.ok || !res.record) throw new Error(res.error || "Lookup failed");
 	return res.record.isRegistered === false;
 }
-/** Determine if a domain appears registered.
-* Performs a lookup and resolves to a boolean. Rejects on lookup error. */
+/**
+* Determine if a domain appears registered.
+* Performs a lookup and resolves to a boolean. Rejects on lookup error.
+*/
 async function isRegistered(domain, opts) {
-	const res = await lookupDomain(domain, opts);
+	const res = await lookup(domain, opts);
 	if (!res.ok || !res.record) throw new Error(res.error || "Lookup failed");
 	return res.record.isRegistered === true;
 }
+/**
+* @deprecated Use `lookup` instead.
+*/
+const lookupDomain = lookup;
 
 //#endregion
-export { getDomainParts, getDomainTld, isAvailable, isLikelyDomain, isRegistered, lookupDomain, toRegistrableDomain };
+export { getDomainParts, getDomainTld, isAvailable, isLikelyDomain, isRegistered, lookup, lookupDomain, toRegistrableDomain };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rdapper",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "license": "MIT",
   "description": "🎩 RDAP/WHOIS fetcher, parser, and normalizer for Node",
   "repository": {