hostinfo 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2011-2026 Carter Cole
+
+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,91 @@
+# hostinfo
+
+[![CI](https://github.com/neopunisher/node-hostip/actions/workflows/ci.yml/badge.svg)](https://github.com/neopunisher/node-hostip/actions/workflows/ci.yml)
+[![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.
+
+```js
+import { lookup } from 'hostinfo';
+
+const info = await lookup('8.8.8.8');
+// {
+//   ip: '8.8.8.8',
+//   city: 'Mountain View, CA',
+//   country: 'UNITED STATES',
+//   countryCode: 'US',
+//   latitude: 37.402,
+//   longitude: -122.078
+// }
+```
+
+## Install
+
+```sh
+npm install hostinfo
+```
+
+Requires Node.js 18 or newer. Works from both ESM (`import`) and CommonJS (`require`), and ships TypeScript types.
+
+## API
+
+### `lookup(ip?, options?) → Promise<HostInfo>`
+
+Looks up an IPv4 address. 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.
+
+**Options**
+
+| option | default | |
+| --- | --- | --- |
+| `timeout` | `10000` | Milliseconds before the request aborts. `0` disables. |
+| `signal` | – | Your own `AbortSignal`; overrides `timeout`. |
+| `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`.
+
+### Callback style
+
+The original 2011 signature still works if you pass a function last:
+
+```js
+const { lookup } = require('hostinfo');
+
+lookup('8.8.8.8', (err, info) => {
+  if (err) throw err;
+  console.log(info.city);
+});
+```
+
+> **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
+
+hostip.info is a community-maintained database. It's free and requires no API key, but coverage and accuracy are modest compared to commercial GeoIP databases — treat results as approximate.
+
+## Development
+
+```sh
+npm test            # unit tests (mocked fetch)
+npm run test:live   # also hits the real API
+```
+
+## 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.
+
+One-time setup: on npmjs.com → package **Settings** → **Trusted Publisher**, select GitHub Actions with repository `neopunisher/node-hostip` and workflow `publish.yml`.
+
+## License
+
+MIT © Carter Cole

package/index.d.ts

@@ -0,0 +1,47 @@
+export interface LookupOptions {
+  /**
+   * Milliseconds before the request is aborted. Ignored when `signal` is
+   * provided. Set to 0 to disable. Default: 10000.
+   */
+  timeout?: number;
+  /** Abort the request yourself; overrides `timeout`. */
+  signal?: AbortSignal;
+  /** Alternate API endpoint. Default: "https://api.hostip.info/". */
+  endpoint?: string | URL;
+}
+
+export interface HostInfo {
+  /** The IP address the API answered for. */
+  ip: string | null;
+  /** City name, or null when unknown or a private address. */
+  city: string | null;
+  /** Country name (upper case), or null when unknown. */
+  country: string | null;
+  /** ISO-ish two-letter country code; "XX" when unknown. */
+  countryCode: string | null;
+  latitude: number | null;
+  longitude: number | null;
+}
+
+export type LookupCallback = (error: Error | null, result?: HostInfo) => void;
+
+export class HostInfoError extends Error {
+  name: 'HostInfoError';
+}
+
+/**
+ * Geocode an IP address with the free hostip.info API. Omit `ip` to look up
+ * the caller's own public address. Returns a Promise unless a callback is
+ * given.
+ */
+export function lookup(ip?: string, options?: LookupOptions): Promise<HostInfo>;
+export function lookup(options: LookupOptions): Promise<HostInfo>;
+export function lookup(callback: LookupCallback): void;
+export function lookup(ip: string | undefined, callback: LookupCallback): void;
+export function lookup(ip: string | undefined, options: LookupOptions, callback: LookupCallback): void;
+
+declare const hostinfo: {
+  lookup: typeof lookup;
+  HostInfoError: typeof HostInfoError;
+};
+export default hostinfo;

package/index.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const DEFAULT_ENDPOINT = 'https://api.hostip.info/';
+const DEFAULT_TIMEOUT = 10_000;
+
+class HostInfoError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = 'HostInfoError';
+  }
+}
+
+const XML_ENTITIES = {
+  '&': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&apos;': "'",
+};
+
+function unescapeXml(text) {
+  return text.replace(/&(?:amp|lt|gt|quot|apos);|&#(\d+);|&#x([0-9a-fA-F]+);/g, (match, dec, hex) => {
+    if (dec) return String.fromCodePoint(Number(dec));
+    if (hex) return String.fromCodePoint(Number.parseInt(hex, 16));
+    return XML_ENTITIES[match];
+  });
+}
+
+function extractField(xml, tag) {
+  const match = new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml);
+  if (!match) return null;
+  const value = unescapeXml(match[1].trim());
+  return value === '' ? null : value;
+}
+
+function parseHostipXml(xml) {
+  const block = /<Hostip>([\s\S]*?)<\/Hostip>/.exec(xml);
+  if (!block) {
+    throw new HostInfoError('Unexpected response from hostip.info: missing <Hostip> element');
+  }
+  const inner = block[1];
+
+  let city = extractField(inner, 'gml:name');
+  let country = extractField(inner, 'countryName');
+  // The API reports unknowns as placeholders like "(Unknown city)" or
+  // "(Private Address)"; normalize those to null.
+  if (city !== null && city.startsWith('(')) city = null;
+  if (country !== null && country.startsWith('(')) country = null;
+
+  let latitude = null;
+  let longitude = null;
+  const coordinates = extractField(inner, 'gml:coordinates');
+  if (coordinates !== null) {
+    // hostip.info returns "longitude,latitude"
+    const [lng, lat] = coordinates.split(',').map(Number);
+    if (Number.isFinite(lat) && Number.isFinite(lng)) {
+      latitude = lat;
+      longitude = lng;
+    }
+  }
+
+  return {
+    ip: extractField(inner, 'ip'),
+    city,
+    country,
+    countryCode: extractField(inner, 'countryAbbrev'),
+    latitude,
+    longitude,
+  };
+}
+
+async function lookupAsync(ip, options) {
+  const { timeout = DEFAULT_TIMEOUT, signal, endpoint = DEFAULT_ENDPOINT } = options;
+  const url = new URL(endpoint);
+  if (ip !== undefined && ip !== null) url.searchParams.set('ip', String(ip));
+
+  let response;
+  try {
+    response = await fetch(url, {
+      headers: { accept: 'text/xml' },
+      signal: signal ?? (timeout > 0 ? AbortSignal.timeout(timeout) : undefined),
+    });
+  } catch (cause) {
+    throw new HostInfoError(`Request to hostip.info failed: ${cause.message}`, { cause });
+  }
+  if (!response.ok) {
+    throw new HostInfoError(`hostip.info responded with HTTP ${response.status}`);
+  }
+
+  // The API serves ISO-8859-1, which response.text() would mangle.
+  const xml = new TextDecoder('iso-8859-1').decode(await response.arrayBuffer());
+  return parseHostipXml(xml);
+}
+
+function lookup(ip, options, callback) {
+  if (typeof ip === 'function') {
+    callback = ip;
+    ip = undefined;
+    options = undefined;
+  } else if (typeof options === 'function') {
+    callback = options;
+    options = undefined;
+  }
+  if (typeof ip === 'object' && ip !== null) {
+    options = ip;
+    ip = undefined;
+  }
+
+  const promise = lookupAsync(ip, options ?? {});
+  if (typeof callback !== 'function') return promise;
+  promise.then(
+    (result) => callback(null, result),
+    (error) => callback(error),
+  );
+  return undefined;
+}
+
+module.exports = { lookup, HostInfoError };

package/index.mjs

@@ -0,0 +1,4 @@
+import hostinfo from './index.js';
+
+export const { lookup, HostInfoError } = hostinfo;
+export default hostinfo;

package/package.json

@@ -1,32 +1,46 @@
 {
-    "name": "hostinfo",
-    "description": "Uses the hostinfo database to geocode ip addresses",
-    "version": "0.0.1",
-        "tags" : ["geoip", "hostinfo", "util", "utility"],
-    "author" : "Carter Cole <node@cartercole.com>",
-    "maintainers":[
-        {
-            "name":"Carter Cole",
-            "email":"node@cartercole.com"
-        }
-    ],
-    "homepage": "http://blog.cartercole.com",
-    "repository" : {
-        "type" : "git",
-        "url" : "git://github.com/neopunisher/node-hostip.git"
-    },
-    "main" : "main.js",
-    "licenses" : [
-        {
-            "type": "MIT",
-            "url": "http://www.opensource.org/licenses/mit-license.php"
-        }
-    ],"bugs" :
-  { "web" : "https://github.com/neopunisher/node-hostip/issues" },
-    "dependencies": {
-        "xml2js": ">= 0.1.9",
-       "request": ">= 2.1.0"
-    },
-    "engine": [ "node >=0.4.1" ]
+  "name": "hostinfo",
+  "version": "1.0.0",
+  "description": "Geocode IP addresses to city, country, and coordinates with the free hostip.info API. Zero dependencies.",
+  "keywords": [
+    "geoip",
+    "hostinfo",
+    "hostip",
+    "geocode",
+    "geolocation",
+    "ip"
+  ],
+  "homepage": "https://github.com/neopunisher/node-hostip#readme",
+  "bugs": {
+    "url": "https://github.com/neopunisher/node-hostip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neopunisher/node-hostip.git"
+  },
+  "license": "MIT",
+  "author": "Carter Cole <node@cartercole.com>",
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:live": "LIVE_TEST=1 node --test"
+  }
 }
-

package/main.js

@@ -1,12 +0,0 @@
-var xml2js = require('xml2js'),
-    request = require('request');
-
-exports.lookup = function (ip,cb){
-request({uri: "http://api.hostip.info/?ip="+ip}, function (error, response, body) {
-var parser = new xml2js.Parser();
-parser.addListener('end', function(obj){
-cb(null,obj);
-});
-parser.parseString(body);
-});
-}