hostinfo 1.0.0 → 2.0.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/hostinfo)](https://www.npmjs.com/package/hostinfo)
 [![npm downloads](https://img.shields.io/npm/dm/hostinfo)](https://www.npmjs.com/package/hostinfo)
 
-Geocode IP addresses to city, country, and coordinates using the free, community-built [hostip.info](https://www.hostip.info/) API. Zero dependencies.
+Geocode IP addresses to city, country, and coordinates using the free, community-built [hostip.info](https://www.hostip.info/) API. When hostip.info has no answer, it can fall back to reverse DNS and traceroute. Zero dependencies.
 
 ```js
 import { lookup } from 'hostinfo';
@@ -26,30 +26,171 @@ const info = await lookup('8.8.8.8');
 npm install hostinfo
 ```
 
-Requires Node.js 18 or newer. Works from both ESM (`import`) and CommonJS (`require`), and ships TypeScript types.
+Requires Node.js 22.12 or newer. Written in TypeScript and published as ESM with bundled types; CommonJS callers can still `require('hostinfo')` thanks to Node's built-in `require(esm)` support.
 
 ## API
 
 ### `lookup(ip?, options?) → Promise<HostInfo>`
 
-Looks up an IPv4 address. Omit `ip` to geocode the caller's own public address:
+Looks up an IPv4 address (anything else rejects with a `TypeError`, since hostip.info has no IPv6 data). Omit `ip` to geocode the caller's own public address:
 
 ```js
 const whereAmI = await lookup();
 ```
 
-Fields that hostip.info does not know are `null` — for private addresses and unrecognized IPs you'll get `city: null`, `country: null`, and `countryCode: 'XX'`. Coordinates are only present for IPs mapped to a city.
+Fields that hostip.info does not know are `null`, including `countryCode` (the API's `"XX"` placeholder becomes `null`). Coordinates are only present for IPs mapped to a city. Private addresses (see [`isPrivateIPv4`](#isprivateipv4ip--boolean)) resolve to all-`null` fields immediately, without a request.
 
 **Options**
 
 | option | default | |
 | --- | --- | --- |
 | `timeout` | `10000` | Milliseconds before the request aborts. `0` disables. |
-| `signal` | – | Your own `AbortSignal`; overrides `timeout`. |
+| `signal` | – | Your own `AbortSignal`; combined with `timeout`, whichever fires first aborts. |
 | `endpoint` | `https://api.hostip.info/` | Alternate API base URL. |
 
 Failures (network, HTTP status, unparseable response) reject with a `HostInfoError`; network errors keep the underlying error on `.cause`.
 
+### `locate(ip, options?) → Promise<Location>`
+
+Best-effort geolocation when hostip.info comes up empty. It tries, in order:
+
+1. **hostip.info** — same as `lookup()`.
+2. **Reverse DNS** — network operators usually put a location code in router and server hostnames (`108-254-2-1.lightspeed.hstntx.sbcglobal.net` → Houston, `ae-5.r21.lsanca07.us.bb.gin.ntt.net` → Los Angeles). `locate` recognizes CLLI codes, airport codes, and city names for about 120 major network hubs.
+3. **Traceroute** (opt-in with `trace: true`) — runs a traceroute to the target and borrows the location of the closest hop that has one.
+
+```js
+import { locate } from 'hostinfo';
+
+const where = await locate('32.130.20.13', { trace: true });
+// {
+//   ip: '32.130.20.13', city: 'Richardson, TX', country: 'UNITED STATES', countryCode: 'US',
+//   latitude: null, longitude: null, hostname: null,
+//   source: 'traceroute',
+//   via: { hop: 4, ip: '71.149.39.230', rtt: 13.2, hostname: null, info: { … }, hint: null }
+// }
+```
+
+The result has all the `HostInfo` fields plus:
+
+| field | |
+| --- | --- |
+| `hostname` | The target's reverse DNS name, or `null`. |
+| `source` | Where `city`/coordinates came from: `'hostip'`, `'hostname'`, `'traceroute'`, or `null` if nothing was found. |
+| `via` | For `'traceroute'`, the hop whose location was used. |
+
+Takes the `lookup()` options plus `trace` (`true` or [trace options](#traceip-options--promisetraceresult)). Treat `'hostname'` and especially `'traceroute'` answers as rough: the hop nearest the target is often in the same metro area, but it can also be a regional hub hundreds of miles away.
+
+### `trace(ip, options?) → Promise<TraceResult>`
+
+Runs the system `traceroute` (macOS/Linux) or `tracert` (Windows) to an IPv4 address. It reports every hop, and where the trail goes cold if the target never answers:
+
+```js
+import { trace } from 'hostinfo';
+
+const { hops, reached, stopped, lastResponding } = await trace('198.51.100.7');
+if (!reached) console.log(`Dropped after hop ${lastResponding?.hop} (${lastResponding?.hostname ?? lastResponding?.ip})`);
+```
+
+Each hop is `{ hop, ip, rtt, hostname, info, hint }`. `ip` is `null` for a probe that timed out (`*`). `info` is hostip.info's answer, and `hint` is the location guessed from `hostname`. [Private hops](#isprivateipv4ip--boolean) are never sent to hostip.info. `stopped` is `'reached'`, `'max-hops'`, `'gave-up'`, or `'timeout'`.
+
+| option | default | |
+| --- | --- | --- |
+| `maxHops` | `30` | Highest TTL to probe. |
+| `probeTimeout` | `1000` | Milliseconds to wait per probe. macOS/Linux round this up to whole seconds. |
+| `giveUpAfter` | `5` | Stop after this many silent hops in a row. `0` runs all the way to `maxHops`. |
+| `timeout` | `60000` | Cut the trace short after this many milliseconds and return the hops so far. `0` disables. |
+| `signal` | – | Abort the trace. The promise rejects with the signal's reason. |
+| `geolocate` | `true` | Look up each hop's hostname and location. |
+| `endpoint` | – | Alternate hostip.info endpoint. |
+
+Rejects with a `HostInfoError` if traceroute isn't installed (e.g. minimal Linux containers: `apt install traceroute`).
+
+### `reverse(ip, options?) → Promise<string[]>`
+
+Reverse DNS (PTR) lookup for an IPv4 or IPv6 address. Returns `[]` when there's no record. Options: `timeout` (default `5000`) and `signal`.
+
+### `whois(ip, options?) → Promise<WhoisInfo>`
+
+Registration data for the network an IPv4 or IPv6 address belongs to, from [ARIN's RDAP service](https://www.arin.net/resources/registry/whois/rdap/). ARIN redirects addresses held by other registries (RIPE, APNIC, LACNIC, AFRINIC) to the right one automatically.
+
+```js
+const info = await whois('8.8.8.8');
+// {
+//   organization: 'Google LLC', name: 'GOGL', handle: 'NET-8-8-8-0-2',
+//   startAddress: '8.8.8.0', endAddress: '8.8.8.255', cidrs: ['8.8.8.0/24'],
+//   type: 'DIRECT ALLOCATION', abuseEmail: 'network-abuse@google.com',
+//   registry: 'whois.arin.net', contacts: [ … ], …
+// }
+```
+
+`contacts` lists every entity in the record with its `roles`, `name`, `org`, `email`, `phone`, and `address`. Options: `timeout` (default `10000`), `signal`, and `endpoint` (an alternate RDAP base URL). Rejects with a `HostInfoError` on network or HTTP errors.
+
+### `hintFromHostname(hostname) → LocationHint | null`
+
+The hostname heuristic on its own: `{ code, city, countryCode, latitude, longitude }` or `null`.
+
+```js
+hintFromHostname('be2345.ccr41.fra03.atlas.cogentco.com'); // { code: 'fra', city: 'Frankfurt', … }
+```
+
+### `isPrivateIPv4(ip) → boolean`
+
+True for IPv4 addresses that aren't publicly routable: loopback, link-local, RFC 1918, carrier-grade NAT (`100.64.0.0/10`), IETF protocol assignments (`192.0.0.0/24`), benchmarking (`198.18.0.0/15`), multicast (`224.0.0.0/4`), and reserved space (`240.0.0.0/4`). The TEST-NET documentation ranges are deliberately not included. `false` for anything that isn't an IPv4 address.
+
+### Command line
+
+```sh
+npx hostinfo 8.8.8.8          # locate an address (or omit it for your own public IP)
+npx hostinfo 8.8.8.8 --trace  # fall back to a traceroute if needed
+npx hostinfo trace example.com
+npx hostinfo reverse 1.1.1.1
+npx hostinfo whois 8.8.8.8     # owner, range, and abuse contact from ARIN
+npx hostinfo mcp               # run as an MCP server (see below)
+```
+
+Hostnames are resolved to an IPv4 address first. Add `--json` for machine-readable output.
+
+```
+$ npx hostinfo trace 1.1.1.1
+traceroute to 1.1.1.1
+ 1  192.168.86.1       9.518 ms
+ 2  192.168.1.254     12.512 ms
+ 3  108.254.2.1       13.706 ms  108-254-2-1.lightspeed.hstntx.sbcglobal.net  Houston, TX? (from "hstntx")
+ 4  71.149.39.230      12.02 ms  Richardson, TX, UNITED STATES
+ ...
+11  1.1.1.1           20.103 ms  one.one.one.one  Buffalo, NY, UNITED STATES
+```
+
+A `?` marks a location guessed from the hostname rather than reported by hostip.info.
+
+### MCP server (for AI assistants)
+
+`hostinfo mcp` runs a [Model Context Protocol](https://modelcontextprotocol.io/) server over stdio, so Claude, Cursor, VS Code, and other MCP clients can geolocate, trace, and WHOIS addresses for you. Add it to your client's config:
+
+```json
+{
+  "mcpServers": {
+    "hostinfo": { "command": "npx", "args": ["-y", "hostinfo", "mcp"] }
+  }
+}
+```
+
+With Claude Code: `claude mcp add hostinfo -- npx -y hostinfo mcp`.
+
+| tool | arguments | |
+| --- | --- | --- |
+| `locate` | `target?`, `trace?` | [`locate()`](#locateip-options--promiselocation); omit `target` for the server's own public IP |
+| `traceroute` | `target`, `maxHops?` | [`trace()`](#traceip-options--promisetraceresult) |
+| `reverse_dns` | `target` | [`reverse()`](#reverseip-options--promisestring) |
+| `whois` | `target` | [`whois()`](#whoisip-options--promisewhoisinfo) |
+| `hostname_hint` | `hostname` | [`hintFromHostname()`](#hintfromhostnamehostname--locationhint--null) |
+
+`target` can be an IP address or a hostname. All tools are read-only, and results are the same JSON the library returns. Like the rest of the package, the server has no dependencies. (Traceroute runs on the machine hosting the server, so it measures that machine's path.)
+
+### For AI coding tools
+
+[`llms.txt`](llms.txt) is a condensed API reference for LLMs, and it ships in the package at `node_modules/hostinfo/llms.txt`. Contributors' agents should read [`AGENTS.md`](AGENTS.md).
+
 ### Callback style
 
 The original 2011 signature still works if you pass a function last:
@@ -63,6 +204,8 @@ lookup('8.8.8.8', (err, info) => {
 });
 ```
 
+> **Upgrading from 1.x:** the package is now ESM-only (CommonJS `require` still works on Node 22.12+), Node 18/20 are no longer supported, non-IPv4 input rejects with a `TypeError` instead of silently returning "(Private Address)", an unknown `countryCode` is `null` instead of `'XX'`, private addresses no longer hit the network, and `signal` no longer disables `timeout`.
+>
 > **Upgrading from 0.0.2:** the result is now the flat object shown above rather than the raw `xml2js` parse of the API response, and the `request`/`xml2js` dependencies are gone.
 
 ## Accuracy
@@ -72,19 +215,24 @@ hostip.info is a community-maintained database. It's free and requires no API ke
 ## Development
 
 ```sh
-npm test            # unit tests (mocked fetch)
+npm install
+npm run typecheck   # tsc over src and tests
+npm test            # builds dist/, then runs unit tests (mocked fetch) and package-export checks
 npm run test:live   # also hits the real API
 ```
 
+The published package runs on Node 22.12+, but the tests run the TypeScript sources directly, which needs type stripping (on by default from Node 22.18).
+
 ## Releasing
 
 Publishing is automated with GitHub Actions via [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) — no npm tokens stored in the repo:
 
 1. Bump `version` in `package.json`, commit, and push (CI must be green).
 2. Create a GitHub release with a matching `vX.Y.Z` tag.
-3. The [publish workflow](.github/workflows/publish.yml) runs the tests and publishes to npm with provenance.
+3. The [publish workflow](.github/workflows/publish.yml) runs the tests and stages the version on npm (`npm stage publish`) with provenance.
+4. Approve the staged version with 2FA — on npmjs.com under **Staged Packages**, or with `npm stage approve <stage-id>` (the id is in the workflow log).
 
-One-time setup: on npmjs.com → package **Settings** → **Trusted Publisher**, select GitHub Actions with repository `neopunisher/node-hostip` and workflow `publish.yml`.
+One-time setup: on npmjs.com → package **Settings** → **Trusted Publisher**, select GitHub Actions with repository `neopunisher/node-hostip` and workflow `publish.yml`, leaving direct `npm publish` disallowed (staging-only).
 
 ## License
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { locate } from './locate.js';
+import { lookup } from './lookup.js';
+import { serveMcp } from './mcp.js';
+import { toIP, toIPv4 } from './resolve.js';
+import { reverse } from './reverse.js';
+import { trace } from './trace.js';
+import { whois } from './whois.js';
+const USAGE = `Usage:
+  hostinfo [ip|host]          Locate an address (your own public IP if omitted)
+  hostinfo trace <ip|host>    Traceroute, with each hop's hostname and location
+  hostinfo reverse <ip|host>  Reverse DNS (PTR) names
+  hostinfo whois <ip|host>    Network owner, range, and abuse contact (ARIN RDAP)
+  hostinfo mcp                Run as an MCP server over stdio (for AI assistants)
+
+Options:
+  --trace     Let \`hostinfo <ip>\` fall back to a traceroute (slow)
+  --json      Print raw JSON
+  -h, --help  Show this help`;
+function place(info) {
+    if (!info)
+        return null;
+    const parts = [info.city, info.country ?? info.countryCode].filter((p) => p !== null);
+    return parts.length > 0 ? parts.join(', ') : null;
+}
+function formatLocation(result) {
+    const lines = [result.ip ?? '(unknown ip)'];
+    if (result.hostname)
+        lines.push(`  hostname  ${result.hostname}`);
+    lines.push(`  location  ${place(result) ?? 'unknown'}`);
+    if (result.latitude !== null && result.longitude !== null) {
+        lines.push(`  coords    ${result.latitude}, ${result.longitude}`);
+    }
+    if (result.source) {
+        const via = result.via ? ` (hop ${result.via.hop}, ${result.via.ip})` : '';
+        lines.push(`  source    ${result.source}${via}`);
+    }
+    return lines.join('\n');
+}
+function formatWhois(info) {
+    const range = info.startAddress && info.endAddress ? `${info.startAddress} - ${info.endAddress}` : null;
+    const rows = [
+        ['org', info.organization],
+        ['network', [info.name, info.handle && `(${info.handle})`].filter(Boolean).join(' ') || null],
+        ['range', [range, info.cidrs.join(', ')].filter(Boolean).join('  ') || null],
+        ['type', info.type],
+        ['country', info.country],
+        ['abuse', info.abuseEmail],
+        ['registered', info.registered],
+        ['updated', info.updated],
+        ['registry', info.registry],
+    ];
+    const lines = [info.ip];
+    for (const [label, value] of rows)
+        if (value)
+            lines.push(`  ${label.padEnd(10)}  ${value}`);
+    return lines.join('\n');
+}
+function formatHop(hop) {
+    const n = String(hop.hop).padStart(2);
+    if (hop.ip === null)
+        return `${n}  *`;
+    const rtt = hop.rtt === null ? '' : `${hop.rtt} ms`;
+    const where = place(hop.info) ?? (hop.hint ? `${hop.hint.city}? (from "${hop.hint.code}")` : '');
+    return [`${n}  ${hop.ip.padEnd(15)}  ${rtt.padStart(10)}`, hop.hostname, where]
+        .filter(Boolean)
+        .join('  ');
+}
+function formatTrace(result) {
+    const lines = [`traceroute to ${result.target}`, ...result.hops.map(formatHop)];
+    if (!result.reached) {
+        const last = result.lastResponding;
+        lines.push(`did not reach ${result.target} (${result.stopped})`);
+        if (last)
+            lines.push(`last responding hop: ${last.hop} ${last.ip}`);
+    }
+    return lines.join('\n');
+}
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            json: { type: 'boolean' },
+            trace: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    if (values.help)
+        return console.log(USAGE);
+    const [first, second] = positionals;
+    if (first === 'mcp')
+        return serveMcp();
+    const command = first === 'trace' || first === 'reverse' || first === 'whois' ? first : 'locate';
+    const target = command === 'locate' ? first : second;
+    if (command !== 'locate' && target === undefined) {
+        console.error(USAGE);
+        process.exitCode = 2;
+        return;
+    }
+    const controller = new AbortController();
+    process.once('SIGINT', () => controller.abort());
+    const { signal } = controller;
+    const print = (value, format) => console.log(values.json ? JSON.stringify(value, null, 2) : format());
+    if (command === 'trace') {
+        const result = await trace(await toIPv4(target), { signal });
+        return print(result, () => formatTrace(result));
+    }
+    if (command === 'whois') {
+        const info = await whois(await toIP(target), { signal });
+        return print(info, () => formatWhois(info));
+    }
+    if (command === 'reverse') {
+        const names = await reverse(await toIP(target), { signal });
+        return print(names, () => (names.length > 0 ? names.join('\n') : '(no PTR records)'));
+    }
+    // Without a target, ask hostip.info who we are first.
+    const ip = target === undefined ? (await lookup({ signal })).ip : await toIPv4(target);
+    if (ip === null)
+        throw new Error('hostip.info did not report your public IP');
+    const result = await locate(ip, { signal, ...(values.trace && { trace: { signal } }) });
+    print(result, () => formatLocation(result));
+}
+main().catch((error) => {
+    console.error(`hostinfo: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});

package/dist/hints.d.ts

@@ -0,0 +1,15 @@
+export interface LocationHint {
+    /** The part of the hostname that matched, e.g. "lax" or "hstntx". */
+    code: string;
+    city: string;
+    countryCode: string;
+    latitude: number;
+    longitude: number;
+}
+/**
+ * Guess where a router or server sits from the location code embedded in its
+ * hostname (e.g. "ae-1.r20.lax01.us.bb.gin.ntt.net" → Los Angeles). Returns
+ * null when nothing recognizable is found. This is a heuristic: treat it as a
+ * hint, not a fact.
+ */
+export declare function hintFromHostname(hostname: string): LocationHint | null;

package/dist/hints.js

@@ -0,0 +1,176 @@
+// Network operators name routers after where they sit, using CLLI codes
+// (6 letters, North America), IATA airport codes, or plain city names:
+//   108-254-2-1.lightspeed.hstntx.sbcglobal.net   -> Houston
+//   ae-5.r21.lsanca07.us.bb.gin.ntt.net           -> Los Angeles
+//   be2345.ccr41.fra03.atlas.cogentco.com         -> Frankfurt
+// Each row: city, country code, latitude, longitude, space-separated codes.
+const PLACES = [
+    // North America
+    ['Ashburn, VA', 'US', 39.04, -77.49, 'asbnva ashburn'],
+    ['Washington, DC', 'US', 38.9, -77.04, 'washdc iad dca washington'],
+    ['Reston, VA', 'US', 38.96, -77.36, 'rstnva reston'],
+    ['Richmond, VA', 'US', 37.54, -77.44, 'rcmdva ric richmond'],
+    ['Baltimore, MD', 'US', 39.29, -76.61, 'bltmmd bwi baltimore'],
+    ['New York, NY', 'US', 40.71, -74.01, 'nycmny nyc jfk lga newyork'],
+    ['Newark, NJ', 'US', 40.74, -74.17, 'nwrknj ewr newark'],
+    ['Philadelphia, PA', 'US', 39.95, -75.17, 'phlapa phl philadelphia'],
+    ['Pittsburgh, PA', 'US', 40.44, -80.0, 'pitbpa pit pittsburgh'],
+    ['Boston, MA', 'US', 42.36, -71.06, 'bstnma bos boston'],
+    ['Atlanta, GA', 'US', 33.75, -84.39, 'atlnga atl atlanta'],
+    ['Miami, FL', 'US', 25.76, -80.19, 'miamfl mia miami'],
+    ['Orlando, FL', 'US', 28.54, -81.38, 'orldfl mco orlando'],
+    ['Tampa, FL', 'US', 27.95, -82.46, 'tampfl tpa tampa'],
+    ['Jacksonville, FL', 'US', 30.33, -81.66, 'jcvlfl jax jacksonville'],
+    ['Charlotte, NC', 'US', 35.23, -80.84, 'chrlnc clt charlotte'],
+    ['Raleigh, NC', 'US', 35.78, -78.64, 'rlghnc rdu raleigh'],
+    ['Nashville, TN', 'US', 36.16, -86.78, 'nsvltn bna nashville'],
+    ['Chicago, IL', 'US', 41.88, -87.63, 'chcgil ord mdw chicago'],
+    ['Detroit, MI', 'US', 42.33, -83.05, 'dtrtmi dtw detroit'],
+    ['Cleveland, OH', 'US', 41.5, -81.69, 'clevoh cle cleveland'],
+    ['Columbus, OH', 'US', 39.96, -83.0, 'clmboh cmh columbus'],
+    ['Cincinnati, OH', 'US', 39.1, -84.51, 'cncnoh cvg cincinnati'],
+    ['Indianapolis, IN', 'US', 39.77, -86.16, 'ipltin ind indianapolis'],
+    ['Milwaukee, WI', 'US', 43.04, -87.91, 'mlwkwi mke milwaukee'],
+    ['Minneapolis, MN', 'US', 44.98, -93.27, 'mplsmn msp minneapolis'],
+    ['St. Louis, MO', 'US', 38.63, -90.2, 'stlsmo stl stlouis'],
+    ['Kansas City, MO', 'US', 39.1, -94.58, 'kscymo mci kansascity'],
+    ['Omaha, NE', 'US', 41.26, -95.93, 'omahne oma omaha'],
+    ['Dallas, TX', 'US', 32.78, -96.8, 'dllstx dfw dal dallas'],
+    ['Houston, TX', 'US', 29.76, -95.37, 'hstntx iah hou houston'],
+    ['Austin, TX', 'US', 30.27, -97.74, 'austtx aus austin'],
+    ['San Antonio, TX', 'US', 29.42, -98.49, 'snantx sanantonio'],
+    ['Oklahoma City, OK', 'US', 35.47, -97.52, 'okcyok okc oklahomacity'],
+    ['New Orleans, LA', 'US', 29.95, -90.07, 'nworla msy neworleans'],
+    ['Denver, CO', 'US', 39.74, -104.99, 'dnvrco den denver'],
+    ['Salt Lake City, UT', 'US', 40.76, -111.89, 'slkcut slc saltlake saltlakecity'],
+    ['Phoenix, AZ', 'US', 33.45, -112.07, 'phnxaz phx phoenix'],
+    ['Las Vegas, NV', 'US', 36.17, -115.14, 'lsvgnv las lasvegas'],
+    ['Los Angeles, CA', 'US', 34.05, -118.24, 'lsanca lax losangeles'],
+    ['San Diego, CA', 'US', 32.72, -117.16, 'sndgca sandiego'],
+    ['San Jose, CA', 'US', 37.34, -121.89, 'snjsca sjc sanjose'],
+    ['Santa Clara, CA', 'US', 37.35, -121.96, 'sntcca santaclara'],
+    ['Palo Alto, CA', 'US', 37.44, -122.14, 'plalca paloalto'],
+    ['San Francisco, CA', 'US', 37.77, -122.42, 'snfcca sfo sanfrancisco'],
+    ['Sacramento, CA', 'US', 38.58, -121.49, 'scrmca smf sacramento'],
+    ['Portland, OR', 'US', 45.52, -122.68, 'ptldor pdx portland'],
+    ['Seattle, WA', 'US', 47.61, -122.33, 'sttlwa sea seattle'],
+    ['Honolulu, HI', 'US', 21.31, -157.86, 'hnllhi hnl honolulu'],
+    ['Anchorage, AK', 'US', 61.22, -149.9, 'anchak anc anchorage'],
+    ['Toronto', 'CA', 43.65, -79.38, 'yyz toronto'],
+    ['Montreal', 'CA', 45.5, -73.57, 'mtl yul montreal'],
+    ['Vancouver', 'CA', 49.28, -123.12, 'yvr vancouver'],
+    ['Mexico City', 'MX', 19.43, -99.13, 'mex mexico'],
+    // Europe
+    ['London', 'GB', 51.51, -0.13, 'lon lhr london'],
+    ['Manchester', 'GB', 53.48, -2.24, 'manchester'],
+    ['Dublin', 'IE', 53.35, -6.26, 'dub dublin'],
+    ['Amsterdam', 'NL', 52.37, 4.9, 'ams amsterdam'],
+    ['Brussels', 'BE', 50.85, 4.35, 'bru brussels'],
+    ['Paris', 'FR', 48.86, 2.35, 'par cdg paris'],
+    ['Marseille', 'FR', 43.3, 5.37, 'mrs marseille'],
+    ['Frankfurt', 'DE', 50.11, 8.68, 'fra frankfurt'],
+    ['Berlin', 'DE', 52.52, 13.4, 'ber berlin'],
+    ['Munich', 'DE', 48.14, 11.58, 'muc munich muenchen'],
+    ['Hamburg', 'DE', 53.55, 9.99, 'hamburg'],
+    ['Düsseldorf', 'DE', 51.23, 6.77, 'dus duesseldorf dusseldorf'],
+    ['Zurich', 'CH', 47.38, 8.54, 'zrh zurich'],
+    ['Geneva', 'CH', 46.2, 6.14, 'gva geneva'],
+    ['Vienna', 'AT', 48.21, 16.37, 'vie vienna'],
+    ['Milan', 'IT', 45.46, 9.19, 'mxp lin milan'],
+    ['Rome', 'IT', 41.9, 12.5, 'fco rome'],
+    ['Madrid', 'ES', 40.42, -3.7, 'mad madrid'],
+    ['Barcelona', 'ES', 41.39, 2.17, 'bcn barcelona'],
+    ['Lisbon', 'PT', 38.72, -9.14, 'lis lisbon'],
+    ['Copenhagen', 'DK', 55.68, 12.57, 'cph copenhagen'],
+    ['Stockholm', 'SE', 59.33, 18.07, 'arn sto stockholm'],
+    ['Oslo', 'NO', 59.91, 10.75, 'osl oslo'],
+    ['Helsinki', 'FI', 60.17, 24.94, 'hel helsinki'],
+    ['Warsaw', 'PL', 52.23, 21.01, 'waw warsaw'],
+    ['Prague', 'CZ', 50.08, 14.44, 'prg prague'],
+    ['Budapest', 'HU', 47.5, 19.04, 'bud budapest'],
+    ['Bucharest', 'RO', 44.43, 26.1, 'otp bucharest'],
+    ['Sofia', 'BG', 42.7, 23.32, 'sof sofia'],
+    ['Athens', 'GR', 37.98, 23.73, 'ath athens'],
+    ['Istanbul', 'TR', 41.01, 28.98, 'ist istanbul'],
+    ['Kyiv', 'UA', 50.45, 30.52, 'kbp kiev kyiv'],
+    // Middle East & Africa
+    ['Tel Aviv', 'IL', 32.09, 34.78, 'tlv telaviv'],
+    ['Dubai', 'AE', 25.2, 55.27, 'dxb dubai'],
+    ['Johannesburg', 'ZA', -26.2, 28.05, 'jnb johannesburg'],
+    ['Cape Town', 'ZA', -33.92, 18.42, 'cpt capetown'],
+    ['Lagos', 'NG', 6.52, 3.38, 'lagos'],
+    ['Nairobi', 'KE', -1.29, 36.82, 'nbo nairobi'],
+    // Asia-Pacific
+    ['Tokyo', 'JP', 35.68, 139.69, 'tyo nrt hnd tokyo'],
+    ['Osaka', 'JP', 34.69, 135.5, 'osa kix osaka'],
+    ['Seoul', 'KR', 37.57, 126.98, 'sel icn seoul'],
+    ['Hong Kong', 'HK', 22.32, 114.17, 'hkg hongkong'],
+    ['Taipei', 'TW', 25.03, 121.57, 'tpe taipei'],
+    ['Singapore', 'SG', 1.35, 103.82, 'sin singapore'],
+    ['Kuala Lumpur', 'MY', 3.14, 101.69, 'kul kualalumpur'],
+    ['Bangkok', 'TH', 13.76, 100.5, 'bkk bangkok'],
+    ['Jakarta', 'ID', -6.21, 106.85, 'cgk jakarta'],
+    ['Manila', 'PH', 14.6, 120.98, 'mnl manila'],
+    ['Mumbai', 'IN', 19.08, 72.88, 'bom mumbai'],
+    ['Delhi', 'IN', 28.61, 77.21, 'del delhi'],
+    ['Chennai', 'IN', 13.08, 80.27, 'maa chennai'],
+    ['Sydney', 'AU', -33.87, 151.21, 'syd sydney'],
+    ['Melbourne', 'AU', -37.81, 144.96, 'mel melbourne'],
+    ['Perth', 'AU', -31.95, 115.86, 'perth'],
+    ['Auckland', 'NZ', -36.85, 174.76, 'akl auckland'],
+    // South America
+    ['São Paulo', 'BR', -23.55, -46.63, 'sao gru saopaulo'],
+    ['Rio de Janeiro', 'BR', -22.91, -43.17, 'rio gig riodejaneiro'],
+    ['Buenos Aires', 'AR', -34.6, -58.38, 'eze bue buenosaires'],
+    ['Santiago', 'CL', -33.45, -70.67, 'scl santiago'],
+    ['Bogotá', 'CO', 4.71, -74.07, 'bog bogota'],
+    ['Lima', 'PE', -12.05, -77.04, 'lim lima'],
+];
+// Lower number wins: a 6-letter CLLI code is the most specific, a 3-letter
+// airport code the most likely to collide with an unrelated abbreviation.
+const CLLI = 0;
+const NAME = 1;
+const AIRPORT = 2;
+const CODES = new Map();
+for (const place of PLACES) {
+    const codes = place[4].split(' ');
+    // CLLI codes are exactly six letters ending in a two-letter state; the
+    // first code on a North American row is always its CLLI code.
+    const hasClli = place[1] === 'US' && codes[0].length === 6;
+    codes.forEach((code, i) => {
+        const rank = hasClli && i === 0 ? CLLI : code.length === 3 ? AIRPORT : NAME;
+        CODES.set(code, { rank, place });
+    });
+}
+/**
+ * Guess where a router or server sits from the location code embedded in its
+ * hostname (e.g. "ae-1.r20.lax01.us.bb.gin.ntt.net" → Los Angeles). Returns
+ * null when nothing recognizable is found. This is a heuristic: treat it as a
+ * hint, not a fact.
+ */
+export function hintFromHostname(hostname) {
+    const labels = hostname.toLowerCase().replace(/\.$/, '').split('.');
+    // The registrable domain ("ntt.net", "cogentco.com") names the operator,
+    // not the location, so leave it out.
+    const words = labels
+        .slice(0, -2)
+        .flatMap((label) => label.split(/[^a-z]+/))
+        .filter((word) => word.length > 0);
+    // Also try adjacent words joined, so "san-jose" and "los-angeles" match.
+    const candidates = [
+        ...words,
+        ...words.slice(1).map((word, i) => words[i] + word),
+        ...words.slice(2).map((word, i) => words[i] + words[i + 1] + word),
+    ];
+    let best;
+    for (const code of candidates) {
+        const entry = CODES.get(code);
+        // Strict < keeps the leftmost match within a rank.
+        if (entry && (best === undefined || entry.rank < best.rank))
+            best = { code, ...entry };
+    }
+    if (!best)
+        return null;
+    const [city, countryCode, latitude, longitude] = best.place;
+    return { code: best.code, city, countryCode, latitude, longitude };
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { hintFromHostname } from './hints.ts';
+import { locate } from './locate.ts';
+import { HostInfoError, lookup } from './lookup.ts';
+import { reverse } from './reverse.ts';
+import { isPrivateIPv4 } from './private.ts';
+import { trace } from './trace.ts';
+import { whois } from './whois.ts';
+export { hintFromHostname, type LocationHint } from './hints.ts';
+export { locate, type LocateOptions, type Location } from './locate.ts';
+export { HostInfoError, lookup, type HostInfo, type LookupCallback, type LookupOptions, } from './lookup.ts';
+export { reverse, type ReverseOptions } from './reverse.ts';
+export { isPrivateIPv4 } from './private.ts';
+export { trace, type TraceHop, type TraceOptions, type TraceResult } from './trace.ts';
+export { whois, type WhoisContact, type WhoisInfo, type WhoisOptions } from './whois.ts';
+declare const hostinfo: {
+    lookup: typeof lookup;
+    locate: typeof locate;
+    reverse: typeof reverse;
+    trace: typeof trace;
+    whois: typeof whois;
+    hintFromHostname: typeof hintFromHostname;
+    isPrivateIPv4: typeof isPrivateIPv4;
+    HostInfoError: typeof HostInfoError;
+};
+export default hostinfo;

package/dist/index.js

@@ -0,0 +1,25 @@
+import { hintFromHostname } from './hints.js';
+import { locate } from './locate.js';
+import { HostInfoError, lookup } from './lookup.js';
+import { reverse } from './reverse.js';
+import { isPrivateIPv4 } from './private.js';
+import { trace } from './trace.js';
+import { whois } from './whois.js';
+export { hintFromHostname } from './hints.js';
+export { locate } from './locate.js';
+export { HostInfoError, lookup, } from './lookup.js';
+export { reverse } from './reverse.js';
+export { isPrivateIPv4 } from './private.js';
+export { trace } from './trace.js';
+export { whois } from './whois.js';
+const hostinfo = {
+    lookup,
+    locate,
+    reverse,
+    trace,
+    whois,
+    hintFromHostname,
+    isPrivateIPv4,
+    HostInfoError,
+};
+export default hostinfo;

package/dist/locate.d.ts

@@ -0,0 +1,28 @@
+import { type HostInfo, type LookupOptions } from './lookup.ts';
+import { type TraceHop, type TraceOptions } from './trace.ts';
+export interface LocateOptions extends LookupOptions {
+    /**
+     * When neither hostip.info nor the target's hostname gives a city, traceroute
+     * to the target and borrow the location of the closest hop that has one.
+     * Pass `true` or trace options. Slow (seconds) — default: false.
+     */
+    trace?: boolean | TraceOptions;
+}
+export interface Location extends HostInfo {
+    /** The target's reverse DNS name, if it has one. */
+    hostname: string | null;
+    /**
+     * Where `city` and the coordinates came from: hostip.info, a location code
+     * in the target's hostname, or a traceroute hop. null when no city was found.
+     */
+    source: 'hostip' | 'hostname' | 'traceroute' | null;
+    /** For `source: 'traceroute'`, the hop whose location was used. */
+    via: TraceHop | null;
+}
+/**
+ * Best-effort geolocation for an IPv4 address. Asks hostip.info first, then
+ * falls back to location codes in the target's reverse DNS name (e.g.
+ * "…lax01.example.net"), and optionally to a traceroute. Check `source` to see
+ * how much to trust the answer.
+ */
+export declare function locate(ip: string, options?: LocateOptions): Promise<Location>;