whoispk 1.1.0 → 2.0.0

package/README.md

@@ -1,108 +1,176 @@
-whoispk
-=======
+<div align="center">
 
-[![npm version](http://img.shields.io/npm/v/whoispk.svg?style=flat)](https://npmjs.org/package/whoispk "View this project on npm")
-[![npm](https://img.shields.io/npm/dt/whoispk.svg)]()
-[![Build Status](https://travis-ci.org/abbassiddiqi/whoispk.svg?branch=master)](https://travis-ci.org/abbassiddiqi/whoispk)
-[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg?colorB=9b59b6)](http://opensource.org/licenses/MIT)
+# whoispk
 
-Issue WHOIS lookup for PKNIC (.pk) domain names from the command line.
+**Check whether a `.pk` domain is taken, from your terminal or from Node.js.**
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/whoispk.svg)](https://www.npmjs.com/package/whoispk)
+[![npm downloads](https://img.shields.io/npm/dt/whoispk.svg)](https://www.npmjs.com/package/whoispk)
+[![CI](https://github.com/abbassiddiqi/whoispk/actions/workflows/ci.yml/badge.svg)](https://github.com/abbassiddiqi/whoispk/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/whoispk.svg)](package.json)
+[![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](package.json)
+[![MIT license](https://img.shields.io/badge/license-MIT-9b59b6.svg)](LICENSE)
 
-### Global
+<img src="docs/assets/demo.svg" alt="whoispk checking three domains: daraz.pk is registered, magicnotatall.pk is available, x.pk is not registrable" width="720">
+
+</div>
+
+`.pk` domains don't have a public WHOIS server, so the usual `whois` command can't look them up. whoispk asks PKNIC, the `.pk` registry, and gives you a clear answer: **registered**, **available**, or **not registrable**. It also shows the creation date, expiry date and nameservers.
+
+## Quick start
+
+No install needed:
+
+```sh
+npx whoispk yourbrand
+```
+
+`.pk` is added for you. `yourbrand`, `yourbrand.pk` and `https://www.yourbrand.pk/` all look up the same domain, and `.com.pk`, `.org.pk` and the other second-level names work too.
+
+To have the `whoispk` command always available:
 
 ```sh
 npm install -g whoispk
 ```
 
-#### Usage
+## Features
 
-    whoispk [options] address
+- **Clear answers.** Each domain is registered, available, or not registrable. For a name PKNIC rejects, you get its reason.
+- **Many domains at once.** Pass several names, or pipe in a list. Lookups run in parallel and print in your order.
+- **Made for scripts.** `--json` output, exit codes you can rely on, and no spinner in piped output.
+- **Also a library.** A promise-based API with TypeScript types, timeouts, retries and cancelling.
+- **Small.** No dependencies, about 10 kB installed. It uses Node's built-in `fetch`.
+- **Watched for breakage.** Tests run every week against the real PKNIC site, so a change to their page gets noticed quickly.
 
-    Options:
-      -V, --version  output the version number
-      -h, --help     output usage information
+## Recipes
 
-### Local
+**Check a shortlist of name ideas**, one per line (`#` starts a comment):
 
 ```sh
-npm install whoispk
+whoispk --json < ideas.txt | jq -r '.[] | select(.available) | .domain'
 ```
 
-#### Usage
+**Use it in a shell script:**
+
+```sh
+if whoispk --json chaiwala | jq -e '.available' > /dev/null; then
+  echo "chaiwala.pk is free. Register it!"
+fi
+```
+
+**Warn before your domains expire:**
 
 ```js
-const whoispk = require('whoispk');
+import { lookup } from 'whoispk';
 
-whoispk.lookup('daraz.pk', function (err, domainInfo) {
+for (const name of ['mybrand.pk', 'mybrand.com.pk']) {
+  const r = await lookup(name);
+  if (!r.registered) continue;
+
+  const days = Math.round((Date.parse(r.expireDate) - Date.now()) / 86_400_000);
+  if (days < 30) console.warn(`${r.domain} expires in ${days} days (${r.expireDate})`);
+}
+```
 
-  if (err) {
-    throw err;
-  }
+## CLI
 
-  if (domainInfo.isFound) {
-    console.log(domainInfo.data);
-  } else {
-    console.log('Domain not Found');
-  }
+```
+whoispk [options] <domain...>
 
-});
+  -j, --json             Print results as JSON
+  -t, --timeout <ms>     Per-request timeout (default: 15000)
+  -c, --concurrency <n>  Parallel lookups (default: 3)
+      --no-color         Disable colours (NO_COLOR is respected too)
 ```
 
-or using ES6 Promises:
+The exit code is `0` when every lookup finished, `1` when any failed (e.g. PKNIC couldn't be reached), and `2` for bad usage.
+
+See the **[CLI reference](docs/cli.md)** for the JSON format, stdin input and more.
+
+## Library
+
+```sh
+npm install whoispk
+```
 
 ```js
-const whoispk = require('whoispk');
-
-whoispk
-  .lookup('daraz.pk')
-  .then(function (domainInfo) {
-
-    if (domainInfo.isFound) {
-      console.log(domainInfo.data);
-    } else {
-      console.log('Domain not Found');
-    }
-  })
-  .catch(function (err) {
-    throw err;
-  });
+import { lookup } from 'whoispk';   // or: const { lookup } = require('whoispk');
+
+const result = await lookup('daraz.pk');
 ```
 
-The console will show following information if domainInfo.isFound is true:
 ```js
 {
-  domain_name: 'daraz.pk',
-  registrant: 'Jade E Services Pakistan {Pvt} Limited',
-  address: 'Clifton Karachi; South Sindh 75600Pakistan',
-  create_date: 'May 14, 2012',
-  expire_date: 'May 14, 2018',
-  agent_org: 'iS-Fun Internet Services GmbH',
-  technical_contact: [
-    'Jade E Services Pakistan {Pvt} Limited',
-    'Raja Muneeb Idrees M Admin',
-    'Clifton, Karachi; South Sindh75600'
-  ],
-  billing_contact: [
-    'iS-Fun Internet Services GmbH',
-    'Robin Fundinger',
-    'Karlsbad, 76307'
-  ],
-  nameservers: [
-    'kip.ns.cloudflare.com',
-    'naomi.ns.cloudflare.com'
-  ]
+  domain: 'daraz.pk',
+  status: 'registered',        // 'registered' | 'available' | 'invalid'
+  registered: true,
+  available: false,
+  createDate: '2012-05-14',    // YYYY-MM-DD, or null
+  expireDate: '2028-05-14',    // YYYY-MM-DD, or null
+  nameservers: ['ns1.alibabadns.cn', 'ns1.alibabadns.com', 'ns2.alibabadns.cn', 'ns2.alibabadns.com'],
+  reasons: [],                 // PKNIC's reasons, when status is 'invalid'
+  fields: { 'Domain Name': 'daraz.pk', 'Create Date': 'May 14, 2012', 'Expire Date': 'May 14, 2028' }
 }
 ```
 
-Source of information: http://pknic.net.pk
+Options include `timeout`, `retries`, `signal` and `fetch`. Failures reject with a `WhoisPkError` that has a `code`, such as `TIMEOUT` or `NETWORK_ERROR`. See the **[API reference](docs/api.md)** for all of it.
+
+## FAQ
+
+<details>
+<summary><b>Why isn't the owner's name or contact shown?</b></summary>
+
+PKNIC stopped publishing registrant, address and contact details because of GDPR and ICANN WHOIS policy. Only the dates and nameservers are public now. If you own the domain, you can see the full record by logging in to your PKNIC account.
+</details>
+
+<details>
+<summary><b>Does "available" mean I can definitely register it?</b></summary>
+
+Not quite. It means PKNIC has no record of the domain. PKNIC only checks whether the name is allowed, for example that it isn't reserved or blocked, when you actually register it. Names it rejects straight away, such as ones that are too short, show up as **not registrable**.
+</details>
+
+<details>
+<summary><b>How do I register a domain I found?</b></summary>
+
+Through [PKNIC](https://pknic.net.pk) or one of its registrars. whoispk only looks domains up.
+</details>
+
+<details>
+<summary><b>It says <code>PARSE_ERROR</code>. What now?</b></summary>
+
+PKNIC has probably changed its lookup page. Please [open an issue](https://github.com/abbassiddiqi/whoispk/issues). [How it works](docs/how-it-works.md) explains the parser, if you'd like to send a fix.
+</details>
+
+<details>
+<summary><b>Is there a rate limit?</b></summary>
+
+PKNIC doesn't publish one, but please be considerate. The CLI runs at most 3 lookups at a time by default, and retries only once, after a pause. Avoid checking thousands of names in a tight loop.
+</details>
+
+<details>
+<summary><b>I'm upgrading from 1.x.</b></summary>
+
+Version 2 needs Node.js 20.19 or later. The callback API is gone; use the promise. Dates are now `YYYY-MM-DD`. See the [changelog](CHANGELOG.md).
+</details>
+
+## Documentation
+
+| Guide | What's in it |
+| --- | --- |
+| [CLI reference](docs/cli.md) | Every option, stdin input, JSON output, exit codes, `jq` recipes |
+| [API reference](docs/api.md) | `lookup`, `parse`, `normalizeDomain`, result fields, errors |
+| [How it works](docs/how-it-works.md) | How PKNIC's page is read, and what to do when it changes |
+| [Changelog](CHANGELOG.md) | What changed in each release |
+| [Releasing](docs/releasing.md) | How maintainers publish a new version to npm |
 
 ## Contributing
 
-- Discuss ideas in issues section
-- Spread the word
+Bug reports and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, tests and guidelines.
+
+whoispk started in 2017. You can read about the original version in [this Medium post](https://medium.com/@abbassiddiqi/whoispk-command-line-tool-5ea275926688).
 
 ## License
 
-whoispk is available under [the MIT license](https://github.com/abbassiddiqi/whoispk/blob/master/LICENSE).
+[MIT](LICENSE) © Abbas Siddiqi
+
+whoispk isn't affiliated with or endorsed by PKNIC. Results come from PKNIC's public lookup page and may change without notice.

package/bin/whoispk.js

@@ -1,68 +1,259 @@
 #!/usr/bin/env node
-'use strict';
-
-const chalk = require('chalk');
-const program = require('commander');
-const changeCase = require('change-case');
-
-const pkg = require('../package.json');
-const whoispk = require('../lib/whoispk.js');
-
-program
-  .version(pkg.version)
-  .description(pkg.description)
-  .arguments('<addr>')
-  .action(getDomainInfo)
-  .usage('[options] address')
-  .parse(process.argv);
-
-if (!program.args.length) {
-  program.help();
-}
-
-function getDomainInfo (address) {
-
-  whoispk
-    .lookup(address)
-    .then(function (domainInfo) {
-      printDomainInfo(domainInfo);
-      process.exit(0);
-    })
-    .catch(function (err) {
-      printErrorMessage();
-      process.exit(1);
-    });
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { lookup, ENDPOINT } from '../src/index.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+const HELP = `
+Usage: whoispk [options] <domain...>
+
+Check whether .pk domains are registered, using PKNIC's public lookup.
+".pk" is appended when missing, so "whoispk magic" looks up magic.pk.
+Domains can also be piped in, one per line: cat domains.txt | whoispk
+
+Options:
+  -j, --json           Print results as JSON
+  -t, --timeout <ms>   Per-request timeout in milliseconds (default: 15000)
+  -c, --concurrency <n>  Parallel lookups when checking several domains (default: 3)
+      --no-color       Disable colours (also respects NO_COLOR)
+  -v, --version        Print the version
+  -h, --help           Show this help
+
+Exit codes:
+  0  all lookups completed
+  1  one or more lookups failed (network error, PKNIC down, …)
+  2  invalid usage
+`;
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+let args;
+try {
+  args = parseArgs({
+    allowPositionals: true,
+    options: {
+      json: { type: 'boolean', short: 'j' },
+      timeout: { type: 'string', short: 't' },
+      concurrency: { type: 'string', short: 'c' },
+      'no-color': { type: 'boolean' },
+      version: { type: 'boolean', short: 'v' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  });
+} catch (err) {
+  usageError(err.message);
 }
 
-function printDomainInfo (domainInfo) {
+const { values: opts, positionals } = args;
+
+if (opts.help) {
+  process.stdout.write(HELP.trimStart());
+  process.exit(0);
+}
+if (opts.version) {
+  console.log(pkg.version);
+  process.exit(0);
+}
 
-  if (!domainInfo.isFound) {
-    console.log("");
-    console.log("   Domain not found: " + chalk.inverse(domainInfo.address));
-    console.log(chalk.italic.dim("   This domain is not registered and may be available for registration to you."));
-    console.log("");
+const timeout = parsePositiveInt(opts.timeout, 15_000, '--timeout');
+const concurrency = parsePositiveInt(opts.concurrency, 3, '--concurrency');
+
+let domains = positionals;
+if (!domains.length && !process.stdin.isTTY) {
+  domains = (await readStdin())
+    .split(/\r?\n/)
+    .flatMap((line) => line.replace(/#.*/, '').split(/[\s,]+/))
+    .filter(Boolean);
+}
+if (!domains.length) {
+  process.stdout.write(HELP.trimStart());
+  process.exit(2);
+}
+
+// ---------------------------------------------------------------------------
+// Styling
+// ---------------------------------------------------------------------------
+
+const useColor =
+  !opts['no-color'] &&
+  !('NO_COLOR' in process.env) &&
+  (process.env.FORCE_COLOR ? process.env.FORCE_COLOR !== '0' : Boolean(process.stdout.isTTY));
+
+const ansi = (open, close) => (s) => (useColor ? `\x1b[${open}m${s}\x1b[${close}m` : String(s));
+const c = {
+  bold: ansi(1, 22),
+  dim: ansi(2, 22),
+  red: ansi(31, 39),
+  green: ansi(32, 39),
+  yellow: ansi(33, 39),
+  cyan: ansi(36, 39),
+};
+
+// ---------------------------------------------------------------------------
+// Run lookups (bounded concurrency, printed in input order)
+// ---------------------------------------------------------------------------
+
+const endpoint = process.env.WHOISPK_ENDPOINT || ENDPOINT;
+const spinner = createSpinner(!opts.json && process.stderr.isTTY);
+const limit = createLimiter(concurrency);
+
+let done = 0;
+spinner.update(progressText(done, domains.length));
+
+const pending = domains.map((domain) =>
+  limit(() => lookup(domain, { timeout, endpoint }))
+    .then(
+      (result) => ({ ok: true, input: domain, result }),
+      (error) => ({ ok: false, input: domain, error }),
+    )
+    .finally(() => spinner.update(progressText(++done, domains.length))),
+);
+
+let failed = 0;
+const jsonResults = [];
+
+for (const [i, promise] of pending.entries()) {
+  const outcome = await promise;
+  if (!outcome.ok) failed++;
+
+  if (opts.json) {
+    jsonResults.push(
+      outcome.ok
+        ? outcome.result
+        : { domain: outcome.input, status: 'error', error: { code: outcome.error.code ?? null, message: outcome.error.message } },
+    );
+    continue;
   }
 
-  if (domainInfo.isFound) {
-      console.log("");
-      for (const prop in domainInfo.data) {
-        if (typeof domainInfo.data[prop] == "object") {
-          console.log("");
-          console.log("   " + chalk.italic(changeCase.titleCase(prop) + ":"));
-          domainInfo.data[prop].forEach(function (item) {
-            console.log("\t\t" + chalk(item));
-          });
-        } else {
-          console.log("   " + chalk.italic(changeCase.titleCase(prop) + ":\t") + chalk(domainInfo.data[prop]) );
-        }
-      }
-      console.log("");
+  spinner.clear();
+  if (i > 0) console.log('');
+  console.log(outcome.ok ? formatResult(outcome.result) : formatError(outcome.input, outcome.error));
+}
+
+spinner.stop();
+
+if (opts.json) {
+  console.log(JSON.stringify(jsonResults.length === 1 ? jsonResults[0] : jsonResults, null, 2));
+}
+
+process.exitCode = failed ? 1 : 0;
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+function formatResult(r) {
+  const lines = [];
+  const label = (s) => `  ${c.dim(s.padEnd(13))}`;
+
+  if (r.status === 'registered') {
+    lines.push(`${c.bold(r.domain)}  ${c.red('● Registered')}`);
+    if (r.createDate) lines.push(`${label('Created')}${formatDate(r.createDate)}`);
+    if (r.expireDate) lines.push(`${label('Expires')}${formatDate(r.expireDate)}  ${c.dim(`(${relative(r.expireDate)})`)}`);
+    r.nameservers.forEach((ns, i) => lines.push(`${label(i === 0 ? 'Nameservers' : '')}${ns}`));
+  } else if (r.status === 'available') {
+    lines.push(`${c.bold(r.domain)}  ${c.green('● Available')}`);
+    lines.push(`  ${c.dim('Not registered — may be available for registration.')}`);
+  } else {
+    lines.push(`${c.bold(r.domain)}  ${c.yellow('● Not registrable')}`);
+    for (const reason of r.reasons) lines.push(`  ${c.dim(reason)}`);
   }
+
+  return lines.join('\n');
+}
+
+function formatError(domain, err) {
+  return `${c.bold(domain)}  ${c.red('✖ Lookup failed')}\n  ${c.dim(err.message)}`;
+}
+
+function formatDate(iso) {
+  const [y, m, d] = iso.split('-').map(Number);
+  return `${MONTHS[m - 1]} ${d}, ${y}`;
+}
+
+function relative(iso) {
+  const days = Math.round((Date.parse(`${iso}T00:00:00Z`) - Date.now()) / 86_400_000);
+  if (days === 0) return 'expires today';
+  const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'always' });
+  const abs = Math.abs(days);
+  const [value, unit] =
+    abs >= 330 ? [Math.round(days / 365), 'year'] : abs >= 45 ? [Math.round(days / 30), 'month'] : [days, 'day'];
+  return `${days < 0 ? 'expired ' : 'expires '}${rtf.format(value, unit)}`;
+}
+
+function progressText(n, total) {
+  return total === 1 ? `Looking up ${domains[0]} on PKNIC…` : `Looking up domains on PKNIC… ${n}/${total}`;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createSpinner(enabled) {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let text = '';
+  let frame = 0;
+  let timer = null;
+  const render = () => process.stderr.write(`\r\x1b[K${c.cyan(frames[frame++ % frames.length])} ${text}`);
+  return {
+    update(t) {
+      if (!enabled) return;
+      text = t;
+      if (!timer) {
+        timer = setInterval(render, 80);
+        timer.unref();
+      }
+      render();
+    },
+    clear() {
+      if (enabled && timer) process.stderr.write('\r\x1b[K');
+    },
+    stop() {
+      if (!enabled) return;
+      clearInterval(timer);
+      timer = null;
+      process.stderr.write('\r\x1b[K');
+    },
+  };
+}
+
+function createLimiter(max) {
+  let active = 0;
+  const queue = [];
+  const next = () => {
+    if (active >= max || !queue.length) return;
+    active++;
+    const { fn, resolve, reject } = queue.shift();
+    fn().then(resolve, reject).finally(() => {
+      active--;
+      next();
+    });
+  };
+  return (fn) =>
+    new Promise((resolve, reject) => {
+      queue.push({ fn, resolve, reject });
+      next();
+    });
+}
+
+function parsePositiveInt(raw, fallback, name) {
+  if (raw === undefined) return fallback;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) usageError(`${name} must be a positive integer`);
+  return n;
+}
+
+function usageError(message) {
+  console.error(`whoispk: ${message}\nRun "whoispk --help" for usage.`);
+  process.exit(2);
 }
 
-function printErrorMessage() {
-  console.log("");
-  console.log(chalk.red("   Error!") + " Server connection Error.");
-  console.log("         " + " Please try again.");
-  console.log("");
+async function readStdin() {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
 }

package/package.json

@@ -1,48 +1,55 @@
 {
   "name": "whoispk",
-  "version": "1.1.0",
-  "description": "A robust WHOIS client for PKNIC (.pk) domains",
+  "version": "2.0.0",
+  "description": "Check .pk domain availability and registration details from PKNIC, from the command line or Node.js",
   "keywords": [
     "whois",
     "pk",
     "pknic",
     "whoispk",
-    "pakistan"
+    "pakistan",
+    "domain",
+    "availability",
+    "cli"
   ],
-  "main": "index.js",
-  "preferGlobal": true,
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
-    "whoispk": "./bin/whoispk.js"
+    "whoispk": "bin/whoispk.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.19"
   },
   "scripts": {
-    "test": "mocha"
+    "test": "node --test",
+    "test:live": "WHOISPK_LIVE=1 node --test",
+    "fixtures": "node scripts/update-fixtures.js",
+    "prepublishOnly": "npm test"
   },
   "author": {
     "name": "Abbas Siddiqi",
     "email": "abbas.siddiqi1@gmail.com",
-    "url": "abbassiddiqi.com"
+    "url": "https://abbassiddiqi.com"
   },
   "repository": {
     "type": "git",
-    "url": "git://github.com/abbassiddiqi/whoispk.git"
+    "url": "git+https://github.com/abbassiddiqi/whoispk.git"
   },
   "bugs": {
     "url": "https://github.com/abbassiddiqi/whoispk/issues"
   },
-  "license": {
-    "type": "MIT",
-    "url": "https://github.com/abbassiddiqi/whoispk/blob/master/LICENSE"
-  },
-  "dependencies": {
-    "axios": "^0.16.2",
-    "chalk": "^2.1.0",
-    "change-case": "^3.0.1",
-    "cheerio": "^1.0.0-rc.2",
-    "commander": "^2.11.0",
-    "querystring": "^0.2.0"
-  },
-  "devDependencies": {
-    "chai": "^4.1.1",
-    "mocha": "^3.5.0"
-  }
+  "homepage": "https://github.com/abbassiddiqi/whoispk#readme",
+  "license": "MIT"
 }

package/src/errors.js

@@ -0,0 +1,12 @@
+/**
+ * Error thrown by whoispk. `code` is one of:
+ * INVALID_INPUT, HTTP_ERROR, NETWORK_ERROR, TIMEOUT, ABORTED, PARSE_ERROR.
+ */
+export class WhoisPkError extends Error {
+  constructor(message, { code, cause, status } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = 'WhoisPkError';
+    this.code = code;
+    if (status !== undefined) this.status = status;
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,62 @@
+export type DomainStatus = 'registered' | 'available' | 'invalid';
+
+export interface LookupResult {
+  /** The normalised domain that was looked up, e.g. "daraz.pk". */
+  domain: string;
+  status: DomainStatus;
+  registered: boolean;
+  /** True when PKNIC reports the domain as not registered (it may be available to register). */
+  available: boolean;
+  /** Registration date as YYYY-MM-DD, when registered. */
+  createDate: string | null;
+  /** Expiry date as YYYY-MM-DD, when registered. */
+  expireDate: string | null;
+  /** DNS entries listed by PKNIC, in the order shown. */
+  nameservers: string[];
+  /** Why PKNIC rejected the name, when status is "invalid". */
+  reasons: string[];
+  /** All labelled fields from the record table, verbatim (e.g. { "Create Date": "Nov 7, 2013" }). */
+  fields: Record<string, string>;
+}
+
+export interface LookupOptions {
+  /** Per-request timeout in milliseconds. Default 15000. */
+  timeout?: number;
+  /** Retries on network errors, timeouts, 429 and 5xx. Default 1. */
+  retries?: number;
+  signal?: AbortSignal;
+  /** Override the PKNIC lookup URL. */
+  endpoint?: string;
+  /** Custom fetch implementation. Defaults to the global fetch. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export type WhoisPkErrorCode =
+  | 'INVALID_INPUT'
+  | 'HTTP_ERROR'
+  | 'NETWORK_ERROR'
+  | 'TIMEOUT'
+  | 'ABORTED'
+  | 'PARSE_ERROR';
+
+export class WhoisPkError extends Error {
+  code: WhoisPkErrorCode;
+  /** HTTP status, for HTTP_ERROR. */
+  status?: number;
+}
+
+export const ENDPOINT: string;
+export const USER_AGENT: string;
+
+export function lookup(domain: string, options?: LookupOptions): Promise<LookupResult>;
+export function parse(html: string): Omit<LookupResult, 'domain'> & { domain: string | null };
+export function normalizeDomain(input: string): string;
+
+declare const whoispk: {
+  lookup: typeof lookup;
+  parse: typeof parse;
+  normalizeDomain: typeof normalizeDomain;
+  WhoisPkError: typeof WhoisPkError;
+  ENDPOINT: string;
+};
+export default whoispk;

package/src/index.js

@@ -0,0 +1,118 @@
+import { readFileSync } from 'node:fs';
+import { WhoisPkError } from './errors.js';
+import { parse } from './parse.js';
+
+export { parse, WhoisPkError };
+
+export const ENDPOINT = 'https://pk6.pknic.net.pk/pk5/lookup.PK';
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const USER_AGENT = `whoispk/${version} (+https://github.com/abbassiddiqi/whoispk)`;
+
+/**
+ * Normalise user input into a bare .pk domain name.
+ *
+ *   "https://www.Daraz.pk/some/path" -> "daraz.pk"
+ *   "magic"                          -> "magic.pk"
+ *   "example.com.pk."                -> "example.com.pk"
+ *
+ * @param {string} input
+ * @returns {string}
+ */
+export function normalizeDomain(input) {
+  if (typeof input !== 'string' || !input.trim()) {
+    throw new WhoisPkError('A domain name is required', { code: 'INVALID_INPUT' });
+  }
+
+  let domain = input.trim().toLowerCase();
+  domain = domain.replace(/^[a-z][a-z0-9+.-]*:\/\//, ''); // scheme
+  domain = domain.replace(/^[^@/]*@/, ''); // userinfo
+  domain = domain.replace(/[/?#].*$/, ''); // path, query, fragment
+  domain = domain.replace(/:\d+$/, ''); // port
+  domain = domain.replace(/\.+$/, ''); // trailing dot(s)
+  domain = domain.replace(/^www\./, '');
+
+  if (!domain) {
+    throw new WhoisPkError(`"${input}" is not a valid domain name`, { code: 'INVALID_INPUT' });
+  }
+  if (!domain.endsWith('.pk') && domain !== 'pk') domain += '.pk';
+
+  return domain;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function request(domain, { endpoint, timeout, signal, fetch: fetchImpl }) {
+  const signals = [AbortSignal.timeout(timeout)];
+  if (signal) signals.push(signal);
+
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/x-www-form-urlencoded',
+        accept: 'text/html',
+        'user-agent': USER_AGENT,
+      },
+      body: new URLSearchParams({ name: domain }).toString(),
+      signal: AbortSignal.any(signals),
+    });
+  } catch (err) {
+    if (signal?.aborted) {
+      throw new WhoisPkError('Lookup aborted', { code: 'ABORTED', cause: err });
+    }
+    if (err?.name === 'TimeoutError') {
+      throw new WhoisPkError(`PKNIC did not respond within ${timeout} ms`, { code: 'TIMEOUT', cause: err });
+    }
+    throw new WhoisPkError(`Could not reach PKNIC: ${err?.cause?.message ?? err?.message ?? err}`, {
+      code: 'NETWORK_ERROR',
+      cause: err,
+    });
+  }
+
+  if (!response.ok) {
+    throw new WhoisPkError(`PKNIC responded with HTTP ${response.status}`, {
+      code: 'HTTP_ERROR',
+      status: response.status,
+    });
+  }
+
+  return response.text();
+}
+
+/**
+ * Look up a .pk domain on PKNIC.
+ *
+ * @param {string} input  Domain name, e.g. "daraz.pk" (".pk" is appended if missing).
+ * @param {import('./index.js').LookupOptions} [options]
+ * @returns {Promise<import('./index.js').LookupResult>}
+ */
+export async function lookup(input, options = {}) {
+  const {
+    timeout = 15_000,
+    retries = 1,
+    signal,
+    endpoint = ENDPOINT,
+    fetch: fetchImpl = globalThis.fetch,
+  } = options;
+
+  const domain = normalizeDomain(input);
+
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const html = await request(domain, { endpoint, timeout, signal, fetch: fetchImpl });
+      const result = parse(html);
+      return { ...result, domain: result.domain ?? domain };
+    } catch (err) {
+      const retryable =
+        err.code === 'NETWORK_ERROR' ||
+        err.code === 'TIMEOUT' ||
+        (err.code === 'HTTP_ERROR' && (err.status >= 500 || err.status === 429));
+      if (!retryable || attempt >= retries) throw err;
+      await sleep(500 * 2 ** attempt);
+    }
+  }
+}
+
+export default { lookup, parse, normalizeDomain, WhoisPkError, ENDPOINT };

package/src/parse.js

@@ -0,0 +1,175 @@
+/**
+ * Parser for the HTML returned by PKNIC's public lookup page
+ * (https://pk6.pknic.net.pk/pk5/lookup.PK).
+ *
+ * PKNIC embeds machine-readable marker tags in the page, e.g.
+ * `<XPC_DOMAIN_NOT_AVAILABLE/>` and `<XPC_RESULT_NOTFOUND/>`. Those are used to
+ * decide the status; visible text is only used as a fallback and to extract
+ * the record details.
+ */
+
+import { WhoisPkError } from './errors.js';
+
+const MONTHS = {
+  jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6,
+  jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12,
+};
+
+const ENTITIES = { nbsp: ' ', amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+
+/** Decode the handful of HTML entities PKNIC uses. */
+function decodeEntities(str) {
+  return str.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, entity) => {
+    if (entity[0] === '#') {
+      const code = entity[1] === 'x' || entity[1] === 'X'
+        ? parseInt(entity.slice(2), 16)
+        : parseInt(entity.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : match;
+    }
+    return ENTITIES[entity.toLowerCase()] ?? match;
+  });
+}
+
+/** Strip tags, decode entities and collapse whitespace. */
+function toText(html) {
+  return decodeEntities(html.replace(/<[^>]*>/g, ' '))
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** "Nov 7, 2013" -> "2013-11-07"; returns null if it doesn't look like a date. */
+export function toIsoDate(text) {
+  const m = /^([a-z]{3})[a-z]*\.?\s+(\d{1,2}),?\s+(\d{4})$/i.exec(text.trim());
+  if (!m) return null;
+  const month = MONTHS[m[1].toLowerCase()];
+  if (!month) return null;
+  return `${m[3]}-${String(month).padStart(2, '0')}-${m[2].padStart(2, '0')}`;
+}
+
+/** The main content cell of the page (left column), without HTML comments. */
+function mainSection(html) {
+  const body = html.replace(/<!--[\s\S]*?-->/g, '');
+  const start = body.search(/id=["']?Tmain\b/i);
+  const end = body.search(/id=["']?Tside\b/i);
+  if (start !== -1 && end > start) return body.slice(start, end);
+  return body;
+}
+
+/**
+ * Parse the record table into labelled fields and nameservers.
+ * Rows are laid out as [spacer, label, spacer, value]. A label with no value
+ * (e.g. "DNS Nameservers") starts a list; following unlabelled rows belong to it.
+ */
+function parseRecordTable(section) {
+  const fields = {};
+  const lists = {};
+  let currentList = null;
+
+  // Split on <tr> rather than matching <tr>…</tr>: PKNIC's markup leaves some rows unclosed.
+  for (const row of section.split(/<tr\b[^>]*>/i).slice(1)) {
+    const cells = row
+      .replace(/<\/table>[\s\S]*$/i, '')
+      .split(/<t[dh]\b[^>]*>/i)
+      .slice(1)
+      .map(toText);
+    if (cells.length < 4) continue;
+
+    const label = cells[1].replace(/:$/, '').trim();
+    const value = cells[3];
+
+    if (label && value) {
+      fields[label] = value;
+      currentList = null;
+    } else if (label) {
+      currentList = label;
+      lists[label] = [];
+    } else if (value && currentList) {
+      lists[currentList].push(value);
+    }
+  }
+
+  return { fields, lists };
+}
+
+function findField(fields, pattern) {
+  const key = Object.keys(fields).find((k) => pattern.test(k));
+  return key === undefined ? undefined : fields[key];
+}
+
+/**
+ * Parse a PKNIC lookup response.
+ *
+ * @param {string} html
+ * @returns {import('./index.js').LookupResult}
+ */
+export function parse(html) {
+  if (typeof html !== 'string') {
+    throw new TypeError('parse() expects an HTML string');
+  }
+
+  const markers = new Set([...html.matchAll(/<XPC_([A-Z_]+)\s*\/?>/g)].map((m) => m[1]));
+  const section = mainSection(html);
+
+  const base = {
+    domain: null,
+    status: null,
+    registered: false,
+    available: false,
+    createDate: null,
+    expireDate: null,
+    nameservers: [],
+    reasons: [],
+    fields: {},
+  };
+
+  // --- Available -----------------------------------------------------------
+  const notFound = /Domain not found:\s*(?:<[^>]*>\s*)*([^<\s]+)/i.exec(section);
+  if (markers.has('RESULT_NOTFOUND') || markers.has('DOMAIN_MAYBE_AVAILABLE') || notFound) {
+    return {
+      ...base,
+      domain: notFound ? toText(notFound[1]).toLowerCase() : null,
+      status: 'available',
+      available: true,
+    };
+  }
+
+  // --- Invalid / not registrable --------------------------------------------
+  const errors = [...section.matchAll(/<li\b[^>]*class=["']?error["']?[^>]*>([\s\S]*?)(?=<\/li>|<li\b|<\/ul>|<br|<\/div>)/gi)]
+    .map((m) => toText(m[1]))
+    .filter(Boolean);
+  if (errors.length || /has the following issues/i.test(section)) {
+    const searched = /Your searched domain:\s*<b>([\s\S]*?)<\/b>/i.exec(section);
+    const domain = searched ? toText(searched[1]).toLowerCase() : null;
+    // Reasons are prefixed with the domain ("x.pk: Invalid Domain name …"); drop that prefix.
+    const reasons = errors.map((e) =>
+      domain && e.toLowerCase().startsWith(`${domain}:`) ? e.slice(domain.length + 1).trim() : e,
+    );
+    return { ...base, domain, status: 'invalid', reasons };
+  }
+
+  // --- Registered ------------------------------------------------------------
+  const heading = /The Domain record for\s*([^<\s]+)/i.exec(section);
+  if (heading || /Domain is Registered/i.test(section)) {
+    const { fields, lists } = parseRecordTable(section);
+    const created = findField(fields, /^create/i);
+    const expires = findField(fields, /^expir/i);
+    const nsKey = Object.keys(lists).find((k) => /name\s*servers?/i.test(k));
+    const domain = findField(fields, /^domain name$/i) ?? (heading ? toText(heading[1]) : null);
+
+    return {
+      ...base,
+      domain: domain ? domain.toLowerCase() : null,
+      status: 'registered',
+      registered: true,
+      createDate: created ? toIsoDate(created) : null,
+      expireDate: expires ? toIsoDate(expires) : null,
+      nameservers: nsKey ? lists[nsKey] : [],
+      fields,
+    };
+  }
+
+  throw new WhoisPkError(
+    'Unrecognised response from PKNIC. The lookup page layout may have changed; please open an issue at https://github.com/abbassiddiqi/whoispk/issues',
+    { code: 'PARSE_ERROR' },
+  );
+}

package/.npmignore

@@ -1,6 +0,0 @@
-# dependencies
-node_modules
-
-# misc
-.DS_Store
-npm-debug.log*

package/.travis.yml

@@ -1,6 +0,0 @@
-language: node_js
-node_js:
-  - "7"
-cache:
-  directories:
-    - "node_modules"

package/index.js

@@ -1 +0,0 @@
-module.exports = require('./lib/whoispk.js');

package/lib/whoispk.js

@@ -1,109 +0,0 @@
-'use strict';
-
-const axios = require('axios');
-const cheerio = require('cheerio');
-const changeCase = require('change-case');
-const querystring = require('querystring');
-
-exports.lookup = lookup;
-
-function lookup (addr, options, done) {
-
-  if (typeof addr === "undefined" && !addr) {
-    throw new Error("address cannot be empty");
-  }
-
-  // A callback function is provided
-  if (typeof done === "undefined" && typeof options === "function") {
-    done = options;
-    options = {};
-  }
-
-  // Called via Promise, no Callback function given
-  if (
-    typeof done === "undefined" &&
-    (typeof options === "object" || typeof options === "undefined")
-  ) {
-    options = {};
-    return fetchDomainInfo(addr);
-  }
-
-  Promise.resolve(fetchDomainInfo(addr))
-    .then(function (domainInfo) {
-      done(null, domainInfo);
-    })
-    .catch(function (err) {
-      done(err);
-    });
-}
-
-function fetchDomainInfo (addr) {
-
-  const pknicUrl = "https://pk6.pknic.net.pk/pk5/lookup.PK";
-
-  return axios
-      .post(pknicUrl, querystring.stringify({ name: addr }))
-      .then(function (response) {
-
-        const domainInfo = parseHTMLResponse(response.data);
-        domainInfo.address = addr;
-
-        return domainInfo;
-      });
-}
-
-function parseHTMLResponse (data) {
-
-  const domainInfo = {
-    isFound: false
-  };
-
-  const $ = cheerio.load(data);
-  const $formBox = $(".formbox","#Tmain");
-  const $whiteBox = $(".whitebox", "#Tmain");
-
-  if ($formBox.length) {
-    // Domain Not Found
-  }
-
-  if ($whiteBox.length) {
-    // Domain Found
-
-    domainInfo.isFound = true;
-    domainInfo.data = {};
-
-    const $rows = $whiteBox.find("tr");
-
-    let lastHeading = "";
-
-    $rows.each(function(i, row) {
-
-      const $row = cheerio(row);
-
-      if ($row.children().length == 4) {
-
-        let key   = $row.children().eq(1).text().replace(/\s+/g,' ').trim();
-        let value = $row.children().eq(3).text().replace(/\s+/g,' ').trim();
-
-        key = changeCase.snakeCase(key);
-        key = key.replace(/\:$/,'');
-
-        if (key && value) {
-          if (key == "registrant_name") { key = "registrant"};
-          if (key == "agent_organization") {key = "agent_org"};
-          domainInfo.data[key] = value;
-        }
-        if (key && !value) {
-          lastHeading = key;
-          domainInfo.data[lastHeading] = [];
-        }
-        if (!key && value) {
-          domainInfo.data[lastHeading].push(value);
-        }
-      }
-
-    });
-  }
-
-  return domainInfo;
-}

package/test/test.js

@@ -1,77 +0,0 @@
-const chai = require('chai');
-const expect = require('chai').expect;
-
-const whoispk = require('../lib/whoispk.js');
-
-describe('whoispk', function () {
-
-  describe('lookup', function () {
-
-    it('returns a promise', function () {
-      const promise = whoispk.lookup('daraz.pk');
-      expect(promise.then).to.be.a('function');
-    });
-
-    it('calls callback', function (done) {
-      this.timeout(4000);
-      whoispk.lookup('daraz.pk', function (err, domainInfo) {
-        expect(err).to.be.null;
-        expect(domainInfo).to.be.an('object');
-
-        done();
-      });
-    });
-
-    it('returns domain information via Promise', function (done) {
-      this.timeout(4000);
-      whoispk
-        .lookup('daraz.pk')
-        .then(function (domainInfo) {
-          expect(domainInfo).to.be.an('object');
-          expect(domainInfo.isFound).to.be.true;
-          done();
-        })
-        .catch(function (err) {
-          done(err);
-        });
-    });
-
-    it('returns domain information via Callback', function (done) {
-      this.timeout(4000);
-      whoispk
-        .lookup('daraz.pk', function (err, domainInfo) {
-          if (err) {
-            done(err);
-          } else {
-            expect(domainInfo).to.be.an('object');
-            expect(domainInfo.isFound).to.be.true;
-            done();
-          }
-        });
-    });
-
-    it('returns domain not found via Promise', function (done) {
-      this.timeout(4000);
-      whoispk
-        .lookup('a.pk')
-        .then(function (domainInfo) {
-          expect(domainInfo.isFound).to.be.false;
-          done();
-        })
-        .catch(function (err) {
-          done(err);
-        });
-    });
-
-    it('returns domain not found via Callback', function (done) {
-      this.timeout(4000);
-      whoispk.lookup('a.pk', function (err, domainInfo) {
-        expect(err).to.be.null;
-        expect(domainInfo.isFound).to.be.false;
-        done();
-      });
-    });
-
-  });
-
-});