jsonified-whois 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pinghome
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# jsonified-whois
+
+A simple, open-source WHOIS client for Node.js that returns unified data as json.
+
+## Features
+
+- Query WHOIS information for domains
+- Parses and normalizes WHOIS responses
+- Supports falling back to query that has the most information
+- Retrieves IPv4 and IPv6 addresses for domains
+- TypeScript support
+
+## Installation
+
+```sh
+npm install jsonified-whois
+```
+
+or
+
+```sh
+yarn add jsonified-whois
+```
+
+## Usage
+
+```ts
+import WhoisClient from "../index.ts";
+import type { WhoisClientConfig } from "../types/index.js";
+
+const config: WhoisClientConfig = {
+  url: "https://www.pinghome.io",
+};
+
+const whoisInstance = new WhoisClient(config);
+
+await whoisInstance
+  .fetchData()
+  .then((res) => console.log(res))
+  .catch((error) => console.log(error));
+```
+
+See [src/example/index.ts](src/example/index.ts) for a usage example.
+
+## API
+
+### `WhoisClient(options)`
+
+- `url` (string): Domain or URL to query (required)
+- `fallback` (boolean): Enable fallback data extraction (optional)
+- `port` (number): WHOIS server port (default: 43)
+- `whoisServer` (string): WHOIS server to start the query from (optional)
+
+#### Methods
+
+- `fetchData()`: Returns a Promise resolving to WHOIS data.
+
+## License
+
+MIT © 2025 Pinghome

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "jsonified-whois",
+  "version": "1.0.1",
+  "description": "A simple, open-source WHOIS client for Node.js that returns unified data as json",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc",
+    "start": "node --watch --experimental-strip-types src/index.ts"
+  },
+  "repository": "https://github.com/Ping-Home/jsonified-whois",
+  "author": "ISnowFoxI",
+  "license": "MIT",
+  "bugs": "https://github.com/Ping-Home/jsonified-whois/issues",
+  "homepage": "https://github.com/Ping-Home/jsonified-whois#readme",
+  "devDependencies": {
+    "@types/node": "*",
+    "typescript": "*"
+  },
+  "dependencies": {
+    "tldts": "*"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,77 @@
+import type { FieldMatchers, ParserResult } from "./types/index.js";
+
+export const timeoutSeconds = 60;
+
+export const ianaWhoIsServer = "whois.iana.org";
+
+export const parserInitialData: ParserResult = {
+  createdAt: "",
+  domainName: "",
+  expiresAt: "",
+  ipAddresses: {
+    ipv4: [],
+    ipv6: [],
+  },
+  nameServers: [],
+  registrar: "",
+  updateAt: "",
+  queriedWhoisServer: "",
+  raw: "",
+};
+
+export const ianaFieldMatchers: FieldMatchers = [
+  {
+    keywords: ["creation", "created", "registered"],
+    targetKey: "createdAt",
+  },
+  {
+    keywords: ["updated", "changed", "last updated"],
+    targetKey: "updateAt",
+  },
+  {
+    keywords: ["expiry", "expiration", "expires"],
+    targetKey: "expiresAt",
+  },
+  {
+    keywords: ["name server", "nameserver", "nserver"],
+    targetKey: "nameServers",
+    isArray: true,
+  },
+  {
+    keywords: ["whois"],
+    targetKey: "registrar",
+  },
+];
+
+export const gtldFiledMatchers: FieldMatchers = [
+  {
+    keywords: ["creation", "created", "registered"],
+    targetKey: "createdAt",
+  },
+  {
+    keywords: ["updated", "changed", "last updated"],
+    targetKey: "updateAt",
+  },
+  {
+    keywords: ["expiry", "expiration", "expires"],
+    targetKey: "expiresAt",
+  },
+  {
+    keywords: [
+      "name server",
+      "nameserver",
+      "nserver",
+      "nameservers",
+      "hostname",
+    ],
+    targetKey: "nameServers",
+    isArray: true,
+  },
+  {
+    keywords: ["registrar whois server"],
+    targetKey: "registrar",
+  },
+];
+
+export const warnColor = "\x1b[33m";
+export const errorColor = "\x1b[31m";

package/src/example/index.ts

@@ -0,0 +1,13 @@
+import WhoisClient from "../index.ts";
+import type { WhoisClientConfig } from "../types/index.js";
+
+const config: WhoisClientConfig = {
+  url: "https://www.pinghome.io",
+};
+
+const whoisInstance = new WhoisClient(config);
+
+await whoisInstance
+  .fetchData()
+  .then((res) => console.log(res))
+  .catch((error) => console.log(error));

package/src/index.ts

@@ -0,0 +1,128 @@
+import { parser } from "./parser/index.ts";
+import { ianaWhoIsServer, parserInitialData } from "./constants.ts";
+import { getIpAddresses } from "./utils/getIpAddresses.ts";
+import { verifyDomain } from "./utils/verifyDomains.ts";
+import { queryWhoisServer } from "./utils/queryWhoisServer.ts";
+import tldts from "tldts";
+import { getFallbackData } from "./utils/getFallbackData.ts";
+import type {
+  CollectWhoisChain,
+  ExistingRegistryData,
+  IpAddresses,
+  QueryResult,
+  WhoisClientConstructor,
+  WhoisResults,
+} from "./types/index.d.ts";
+import { logError } from "./utils/log.ts";
+
+/**
+ * A client to get basic whois information
+ */
+class WhoisClient {
+  constructor({ url, fallback, port, whoisServer }: WhoisClientConstructor) {
+    try {
+      url && verifyDomain(url);
+      this.port = port || 43;
+      this.whoisServer = whoisServer || ianaWhoIsServer;
+      this.fallbackEnabled = fallback;
+      this.domain = tldts.getDomain(url);
+      this.hostname = tldts.getHostname(url);
+    } catch (error) {
+      logError("Something went wrong when initializing the client \n");
+      throw error;
+    }
+  }
+
+  private port: number = 43;
+  private whoisServer: string = ianaWhoIsServer;
+  private ipAddresses: IpAddresses = {
+    ipv4: [],
+    ipv6: [],
+  };
+  private hostname: string = "";
+  private domain: string = "";
+  private fallbackEnabled: boolean = false;
+  private whoisResults: WhoisResults = [];
+
+  /**
+   * Fetch data for the instantiated domain
+   */
+  public async fetchData() {
+    this.ipAddresses = await getIpAddresses(this.hostname);
+    const response = await this.collectWhoisChain(
+      this.domain,
+      this.whoisServer
+    );
+
+    let lastQuery = { ...response.at(-1) };
+
+    if (this.fallbackEnabled) {
+      lastQuery = getFallbackData(response);
+    }
+
+    delete lastQuery.raw;
+
+    const data = {
+      queryData: response,
+      ...lastQuery,
+    };
+    return JSON.stringify(data);
+  }
+
+  /**
+   * Queries whois servers and collects whois info recursively
+   */
+  private async collectWhoisChain(
+    domain: string,
+    whoisServer: string
+  ): CollectWhoisChain {
+    const existingRegistryData: ExistingRegistryData = this.whoisResults.find(
+      (item) => item.queriedWhoisServer === whoisServer
+    );
+
+    if (
+      existingRegistryData &&
+      (existingRegistryData.registrar.length === 0 ||
+        existingRegistryData.registrar === whoisServer)
+    ) {
+      return this.whoisResults;
+    }
+
+    const response = await this.queryWhoisServer(domain, whoisServer);
+
+    this.whoisResults.push({
+      ...response,
+      ipAddresses: this.ipAddresses,
+    });
+
+    if (!response.registrar) {
+      return this.whoisResults;
+    }
+
+    return await this.collectWhoisChain(domain, response.registrar);
+  }
+
+  /**
+   * Query given whois server and return parsed data with matched keys.
+   */
+  private async queryWhoisServer(
+    domain: string,
+    whoisServer: string
+  ): Promise<QueryResult> {
+    try {
+      const response = await queryWhoisServer(domain, whoisServer, this.port);
+      const isIana = whoisServer === ianaWhoIsServer;
+      const conversionResult = parser(response, isIana);
+      conversionResult.domainName = this.domain;
+      conversionResult.queriedWhoisServer = whoisServer;
+      conversionResult.raw = response;
+      conversionResult.ipAddresses = this.ipAddresses;
+      return conversionResult;
+    } catch (error) {
+      logError(error);
+      return parserInitialData;
+    }
+  }
+}
+
+export default WhoisClient;

package/src/parser/index.ts

@@ -0,0 +1,49 @@
+import {
+  gtldFiledMatchers,
+  ianaFieldMatchers,
+  parserInitialData,
+} from "../constants.ts";
+import type { ParserResult } from "../types/index.d.ts";
+import { normalizer } from "../utils/normalizer.ts";
+
+const nameServers = "nameServers";
+
+export const parser = (data: string, isIana: boolean) => {
+  const splitter = data.endsWith("\r\n") ? "\r\n" : "\n";
+
+  const matchers = isIana ? ianaFieldMatchers : gtldFiledMatchers;
+  const arr = data.split(">>>");
+  const responses = arr[0].split(splitter);
+  const result: ParserResult = { ...parserInitialData };
+
+  responses.forEach((item) => {
+    const [key, value] = item.split(/:(.*)/s);
+    if (!key || !value) return;
+
+    const normalizedKey = normalizer(key);
+    const trimmedValue = value.trim();
+
+    for (const matcher of matchers) {
+      const includesKeyword = matcher.keywords.some((kw) =>
+        normalizedKey.includes(kw)
+      );
+      if (!includesKeyword) {
+        continue;
+      }
+
+      if (matcher.targetKey === nameServers) {
+        const values = trimmedValue
+          .split("\r\n")
+          .map((v) => v.trim())
+          .filter(Boolean);
+        result.nameServers = [...(result.nameServers || []), ...values];
+        break;
+      }
+
+      result[matcher.targetKey] = trimmedValue;
+      break;
+    }
+  });
+
+  return result;
+};

package/src/types/index.d.ts

@@ -0,0 +1,53 @@
+export type IpAddresses = {
+  ipv4: Array<string>;
+  ipv6: Array<string>;
+};
+
+export type ParserResult = {
+  domainName: string;
+  createdAt: string;
+  updateAt: string;
+  expiresAt: string;
+  nameServers: Array<string>;
+  ipAddresses: IpAddresses;
+  registrar: string;
+  queriedWhoisServer: string;
+  raw: string;
+};
+
+export type QueryResult = ParserResult;
+
+export type Parser = (data: string, splitter: string) => ParserResult;
+
+export type Parsers = (data: string) => ParserResult;
+
+export type Normalizer = (str: string) => string;
+
+export type FieldMatcher = {
+  keywords: Array<string>;
+  targetKey: string;
+  isArray?: boolean;
+};
+
+export type FieldMatchers = Array<FieldMatcher>;
+
+export interface WhoisClientConstructor {
+  fallback?: boolean;
+  url: string;
+  port?: number;
+  whoisServer?: string;
+}
+
+export type WhoisClientConfig = WhoisClientConstructor;
+
+export type WhoisResults = Array<QueryResult>;
+
+export type CollectWhoisChain = Promise<WhoisResults | Promise<WhoisResults>>;
+
+export type ExistingRegistryData = QueryResult | undefined;
+
+export type GetFallbackData = (results: WhoisResults) => QueryResult;
+
+export type VerifyDomain = (domain: string) => void;
+
+export type Log = (message: string) => void;

package/src/utils/getFallbackData.ts

@@ -0,0 +1,19 @@
+import type { GetFallbackData } from "../types/index.js";
+
+export const getFallbackData: GetFallbackData = (results) => {
+  const reversedArr = [...results].reverse();
+  let counter = [];
+
+  for (let index in reversedArr) {
+    counter[index] = 0;
+    for (let key in reversedArr[index]) {
+      if (reversedArr[index][key]) {
+        continue;
+      }
+      counter[index]++;
+    }
+  }
+
+  const minLossIndex = counter.indexOf(Math.min(...counter));
+  return { ...reversedArr[minLossIndex] };
+};

package/src/utils/getIpAddresses.ts

@@ -0,0 +1,36 @@
+import { resolve4, resolve6 } from "dns/promises";
+import { logWarning } from "./log.ts";
+
+type IpResult = (domain: string) => Promise<Array<string>>;
+
+type IpAddresses = (domain: string) => Promise<{
+  ipv4: Array<string>;
+  ipv6: Array<string>;
+}>;
+
+const getIpv6: IpResult = async (domain) => {
+  try {
+    return await resolve6(domain);
+  } catch (error) {
+    logWarning("Unable to find IPv6 addresses for " + domain + "\n");
+    return [];
+  }
+};
+
+const getIpv4: IpResult = async (domain: string) => {
+  try {
+    return await resolve4(domain);
+  } catch (error) {
+    logWarning("Unable to find IPv4 addresses for " + domain + "\n");
+    return [];
+  }
+};
+
+export const getIpAddresses: IpAddresses = async (domain) => {
+  const ipv4 = await getIpv4(domain);
+  const ipv6 = await getIpv6(domain);
+  return {
+    ipv4,
+    ipv6,
+  };
+};

package/src/utils/log.ts

@@ -0,0 +1,10 @@
+import { errorColor, warnColor } from "../constants.ts";
+import type { Log } from "../types/index.js";
+
+export const logWarning: Log = (message) => {
+  console.warn(warnColor, message);
+};
+
+export const logError: Log = (message) => {
+  console.error(errorColor, message);
+};

package/src/utils/normalizer.ts

@@ -0,0 +1,8 @@
+import type { Normalizer } from "../types/index.js";
+
+export const normalizer: Normalizer = (str) => {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z\s]/g, "")
+    .trim();
+};

package/src/utils/queryWhoisServer.ts

@@ -0,0 +1,26 @@
+import net from "net";
+import { timeoutSeconds } from "../constants.ts";
+
+type GetWhoisData = (
+  domain: string,
+  whoisServer: string,
+  port: number
+) => Promise<string>;
+
+export const queryWhoisServer: GetWhoisData = async (
+  domain,
+  whoisServer,
+  port
+) => {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    const socket = net.createConnection({ host: whoisServer, port: port }, () =>
+      socket.write(domain + "\r\n")
+    );
+    socket.setTimeout(timeoutSeconds * 1000);
+    socket.on("data", (chunk) => (data += chunk));
+    socket.on("close", () => resolve(data));
+    socket.on("timeout", () => socket.destroy(new Error("Timeout")));
+    socket.on("error", reject);
+  });
+};

package/src/utils/verifyDomains.ts

@@ -0,0 +1,15 @@
+import tldts from "tldts";
+import type { VerifyDomain } from "../types/index.js";
+
+export const verifyDomain: VerifyDomain = (domain) => {
+  if (!domain.length) {
+    throw new Error("Domain input is required");
+  }
+
+  const domainWithoutSuffix: string | null =
+    tldts.getDomainWithoutSuffix(domain);
+
+  if (!domainWithoutSuffix) {
+    throw new Error("Domain is not valid");
+  }
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2020",
+    "sourceMap": true,
+    "outDir": "dist",
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*"]
+}