where-is-ip 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Huy Dang
+
+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

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# where-is-ip
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Look up public IPv4 and IPv6 locations with automatic fallback and no API key.
+
+## Install
+
+Install [`where-is-ip`](https://www.npmjs.com/package/where-is-ip) from npm.
+
+```sh
+npm install where-is-ip
+```
+
+## Usage
+
+The package supports modern browsers and Node.js 18 or later.
+
+### npm
+
+```js
+import { geoip } from "where-is-ip";
+
+const location = await geoip.lookup("8.8.8.8");
+const currentLocation = await geoip.lookup();
+```
+
+For CommonJS, use `const { geoip } = require("where-is-ip")`.
+
+### Browser via CDN
+
+Import the ESM bundle from jsDelivr.
+
+```html
+<script type="module">
+  import { geoip } from "https://cdn.jsdelivr.net/npm/where-is-ip@latest";
+
+  console.log(await geoip.lookup("8.8.8.8"));
+</script>
+```
+
+### Methods
+
+| Method | Looks up |
+| --- | --- |
+| `geoip.lookup(ip)` | The specified public IPv4 or IPv6 address. |
+| `geoip.lookup()` | The visitor's public IP in a browser or the server's outgoing IP in Node.js. |
+
+### Result
+
+```ts
+export interface GeoIpResult {
+  ip: string;
+  countryCode: string;
+  countryName: string | null;
+  region: string | null;
+  city: string | null;
+  latitude: number | null;
+  longitude: number | null;
+  provider: string;
+}
+```
+
+## Providers
+
+Providers are tried in table order with a 2-second timeout per attempt.
+
+| Provider | ID | Specified IP | Caller IP | Browser |
+| --- | --- | :---: | :---: | :---: |
+| [FreeIPAPI](https://freeipapi.com/) | `freeipapi` | ✓ | ✓ | ✓ |
+| [IPWhois](https://ipwhois.io/) | `ipwhois` | ✓ | ✓ | ✓ |
+| [GeoJS](https://www.geojs.io/) | `geojs` | ✓ | ✓ | ✓ |
+| [IP2Location.io](https://www.ip2location.io/) | `ip2location` | ✓ | ✓ | — |
+| [IP Info](https://ip-info.com/) | `ip-info` | ✓ | ✓ | ✓ |
+| [IPinfo](https://ipinfo.io/) | `ipinfo` | ✓ | ✓ | ✓ |
+| [Country.is](https://country.is/) | `country-is` | ✓ | ✓ | ✓ |
+| [Cloudflare Trace](https://www.cloudflare.com/) | `cloudflare` | — | ✓ | ✓ |

package/dist/index.cjs

@@ -0,0 +1,275 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  geoip: () => geoip
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/providers/shared.ts
+function withSelfLookup(provider) {
+  return { ...provider, lookupSelf: () => provider.lookup() };
+}
+async function fetchJson(url, init) {
+  const data = readObject(await fetchBody(url, (response) => response.json(), init));
+  if (!data) throw new Error("Expected a JSON object");
+  return data;
+}
+function fetchText(url) {
+  return fetchBody(url, (response) => response.text());
+}
+async function fetchBody(url, read, init) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 2e3);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return await read(response);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function normalizeLocation(fields) {
+  return {
+    ip: readText(fields.ip),
+    countryCode: readCountryCode(fields.countryCode),
+    countryName: readText(fields.countryName),
+    region: readText(fields.region),
+    city: readText(fields.city),
+    latitude: readCoordinate(fields.latitude, 90),
+    longitude: readCoordinate(fields.longitude, 180)
+  };
+}
+function readObject(value) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+}
+function readText(value) {
+  const text = typeof value === "string" ? value.trim() : "";
+  return text && text !== "-" ? text : null;
+}
+function readCountryCode(value) {
+  const code = readText(value)?.toUpperCase();
+  return code && /^[A-Z]{2}$/.test(code) ? code : null;
+}
+function readCoordinate(value, limit) {
+  if (typeof value !== "number" && readText(value) === null) return null;
+  const coordinate = Number(value);
+  return Number.isFinite(coordinate) && Math.abs(coordinate) <= limit ? coordinate : null;
+}
+
+// src/providers/cloudflare.ts
+var cloudflare = {
+  name: "cloudflare",
+  async lookupSelf() {
+    const trace = await fetchText("https://www.cloudflare.com/cdn-cgi/trace");
+    const ip = trace.match(/^ip=(.*)$/m)?.[1];
+    const countryCode = trace.match(/^loc=(.*)$/m)?.[1].trim().toUpperCase();
+    return normalizeLocation({
+      ip,
+      countryCode: countryCode === "XX" ? null : countryCode
+    });
+  }
+};
+
+// src/providers/country-is.ts
+var countryIs = withSelfLookup({
+  name: "country-is",
+  async lookup(ip) {
+    const data = await fetchJson(`https://api.country.is/${ip ?? ""}?fields=city,location`);
+    const location = readObject(data.location);
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country,
+      city: data.city,
+      latitude: location?.latitude,
+      longitude: location?.longitude
+    });
+  }
+});
+
+// src/providers/freeipapi.ts
+var freeipapi = withSelfLookup({
+  name: "freeipapi",
+  async lookup(ip) {
+    const url = ip ? `https://free.freeipapi.com/api/v1/json/${ip}` : "https://free.freeipapi.com/api/v1/json";
+    const data = await fetchJson(url);
+    return normalizeLocation({
+      ip: data.ipAddress,
+      countryCode: data.countryCode,
+      countryName: data.countryName,
+      region: data.regionName,
+      city: data.cityName,
+      latitude: data.latitude,
+      longitude: data.longitude
+    });
+  }
+});
+
+// src/providers/geojs.ts
+var geojs = withSelfLookup({
+  name: "geojs",
+  async lookup(ip) {
+    const data = await fetchJson(`https://get.geojs.io/v1/ip/geo${ip ? `/${ip}` : ""}.json`);
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country_code,
+      countryName: data.country,
+      region: data.region,
+      city: data.city,
+      latitude: data.latitude,
+      longitude: data.longitude
+    });
+  }
+});
+
+// src/providers/ip-info.ts
+var ipInfo = withSelfLookup({
+  name: "ip-info",
+  async lookup(ip) {
+    const url = ip ? `https://ip-info.com/json?ip=${encodeURIComponent(ip)}` : "https://ip-info.com/json";
+    const data = await fetchJson(url);
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country,
+      countryName: data.country_name,
+      region: data.region,
+      city: data.city,
+      latitude: data.latitude,
+      longitude: data.longitude
+    });
+  }
+});
+
+// src/providers/ip2location.ts
+var ip2location = withSelfLookup({
+  name: "ip2location",
+  serverOnly: true,
+  async lookup(ip) {
+    const url = ip ? `https://api.ip2location.io/?ip=${encodeURIComponent(ip)}` : "https://api.ip2location.io/?format=json";
+    const data = await fetchJson(url);
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country_code,
+      countryName: data.country_name,
+      region: data.region_name,
+      city: data.city_name,
+      latitude: data.latitude,
+      longitude: data.longitude
+    });
+  }
+});
+
+// src/providers/ipinfo.ts
+var ipinfo = withSelfLookup({
+  name: "ipinfo",
+  async lookup(ip) {
+    const data = await fetchJson(`https://ipinfo.io${ip ? `/${ip}` : ""}/json`);
+    const [latitude, longitude] = readText(data.loc)?.split(",") ?? [];
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country,
+      region: data.region,
+      city: data.city,
+      latitude,
+      longitude
+    });
+  }
+});
+
+// src/providers/ipwhois.ts
+var ipwhois = withSelfLookup({
+  name: "ipwhois",
+  async lookup(ip) {
+    const data = await fetchJson(`https://ipwho.is/${ip ?? ""}`);
+    if (data.success !== true) throw new Error(readText(data.message) ?? "Lookup was unsuccessful");
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country_code,
+      countryName: data.country,
+      region: data.region,
+      city: data.city,
+      latitude: data.latitude,
+      longitude: data.longitude
+    });
+  }
+});
+
+// src/providers/index.ts
+var providers = [
+  freeipapi,
+  ipwhois,
+  geojs,
+  ip2location,
+  ipInfo,
+  ipinfo,
+  countryIs,
+  cloudflare
+];
+function getProviders() {
+  const isServer = typeof globalThis.location === "undefined";
+  return providers.filter((provider) => isServer || !provider.serverOnly);
+}
+
+// src/lookup.ts
+async function lookup(ip) {
+  const address = ip === void 0 ? void 0 : normalizeIp(ip);
+  const providers2 = getProviders();
+  const errors = [];
+  for (const provider of providers2) {
+    try {
+      const attempt = address === void 0 ? provider.lookupSelf?.() : provider.lookup?.(address);
+      if (!attempt) continue;
+      const { ip: detectedIp, countryCode, ...location } = await attempt;
+      if (!countryCode) {
+        errors.push(new Error(`${provider.name} response did not include a country code`));
+        continue;
+      }
+      return { ip: address ?? normalizeIp(detectedIp), countryCode, ...location, provider: provider.name };
+    } catch (cause) {
+      errors.push(new Error(`${provider.name} lookup failed`, { cause }));
+    }
+  }
+  throw new AggregateError(errors, `IP geolocation failed for ${address ?? "the caller"}`);
+}
+function normalizeIp(input) {
+  if (typeof input !== "string") throw new TypeError("Expected an IP address string");
+  const ip = input.trim();
+  const octets = ip.split(".");
+  const validOctet = (octet) => /^(0|[1-9]\d{0,2})$/.test(octet) && Number(octet) <= 255;
+  if (octets.length === 4 && octets.every(validOctet)) return ip;
+  if (ip.includes(":") && /^[a-f\d:.]+$/i.test(ip)) {
+    try {
+      new URL(`https://[${ip}]/`);
+      return ip;
+    } catch {
+    }
+  }
+  throw new TypeError(`Invalid IP address: ${input}`);
+}
+
+// src/index.ts
+var geoip = { lookup };
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  geoip
+});

package/dist/index.d.cts

@@ -0,0 +1,13 @@
+export interface GeoIpResult {
+    ip: string;
+    countryCode: string;
+    countryName: string | null;
+    region: string | null;
+    city: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    provider: string;
+}
+export declare const geoip: {
+    lookup(ip?: string): Promise<GeoIpResult>;
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export interface GeoIpResult {
+    ip: string;
+    countryCode: string;
+    countryName: string | null;
+    region: string | null;
+    city: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    provider: string;
+}
+export declare const geoip: {
+    lookup(ip?: string): Promise<GeoIpResult>;
+};

package/dist/index.js

@@ -0,0 +1,248 @@
+// src/providers/shared.ts
+function withSelfLookup(provider) {
+  return { ...provider, lookupSelf: () => provider.lookup() };
+}
+async function fetchJson(url, init) {
+  const data = readObject(await fetchBody(url, (response) => response.json(), init));
+  if (!data) throw new Error("Expected a JSON object");
+  return data;
+}
+function fetchText(url) {
+  return fetchBody(url, (response) => response.text());
+}
+async function fetchBody(url, read, init) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 2e3);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return await read(response);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function normalizeLocation(fields) {
+  return {
+    ip: readText(fields.ip),
+    countryCode: readCountryCode(fields.countryCode),
+    countryName: readText(fields.countryName),
+    region: readText(fields.region),
+    city: readText(fields.city),
+    latitude: readCoordinate(fields.latitude, 90),
+    longitude: readCoordinate(fields.longitude, 180)
+  };
+}
+function readObject(value) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+}
+function readText(value) {
+  const text = typeof value === "string" ? value.trim() : "";
+  return text && text !== "-" ? text : null;
+}
+function readCountryCode(value) {
+  const code = readText(value)?.toUpperCase();
+  return code && /^[A-Z]{2}$/.test(code) ? code : null;
+}
+function readCoordinate(value, limit) {
+  if (typeof value !== "number" && readText(value) === null) return null;
+  const coordinate = Number(value);
+  return Number.isFinite(coordinate) && Math.abs(coordinate) <= limit ? coordinate : null;
+}
+
+// src/providers/cloudflare.ts
+var cloudflare = {
+  name: "cloudflare",
+  async lookupSelf() {
+    const trace = await fetchText("https://www.cloudflare.com/cdn-cgi/trace");
+    const ip = trace.match(/^ip=(.*)$/m)?.[1];
+    const countryCode = trace.match(/^loc=(.*)$/m)?.[1].trim().toUpperCase();
+    return normalizeLocation({
+      ip,
+      countryCode: countryCode === "XX" ? null : countryCode
+    });
+  }
+};
+
+// src/providers/country-is.ts
+var countryIs = withSelfLookup({
+  name: "country-is",
+  async lookup(ip) {
+    const data = await fetchJson(`https://api.country.is/${ip ?? ""}?fields=city,location`);
+    const location = readObject(data.location);
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country,
+      city: data.city,
+      latitude: location?.latitude,
+      longitude: location?.longitude
+    });
+  }
+});
+
+// src/providers/freeipapi.ts
+var freeipapi = withSelfLookup({
+  name: "freeipapi",
+  async lookup(ip) {
+    const url = ip ? `https://free.freeipapi.com/api/v1/json/${ip}` : "https://free.freeipapi.com/api/v1/json";
+    const data = await fetchJson(url);
+    return normalizeLocation({
+      ip: data.ipAddress,
+      countryCode: data.countryCode,
+      countryName: data.countryName,
+      region: data.regionName,
+      city: data.cityName,
+      latitude: data.latitude,
+      longitude: data.longitude
+    });
+  }
+});
+
+// src/providers/geojs.ts
+var geojs = withSelfLookup({
+  name: "geojs",
+  async lookup(ip) {
+    const data = await fetchJson(`https://get.geojs.io/v1/ip/geo${ip ? `/${ip}` : ""}.json`);
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country_code,
+      countryName: data.country,
+      region: data.region,
+      city: data.city,
+      latitude: data.latitude,
+      longitude: data.longitude
+    });
+  }
+});
+
+// src/providers/ip-info.ts
+var ipInfo = withSelfLookup({
+  name: "ip-info",
+  async lookup(ip) {
+    const url = ip ? `https://ip-info.com/json?ip=${encodeURIComponent(ip)}` : "https://ip-info.com/json";
+    const data = await fetchJson(url);
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country,
+      countryName: data.country_name,
+      region: data.region,
+      city: data.city,
+      latitude: data.latitude,
+      longitude: data.longitude
+    });
+  }
+});
+
+// src/providers/ip2location.ts
+var ip2location = withSelfLookup({
+  name: "ip2location",
+  serverOnly: true,
+  async lookup(ip) {
+    const url = ip ? `https://api.ip2location.io/?ip=${encodeURIComponent(ip)}` : "https://api.ip2location.io/?format=json";
+    const data = await fetchJson(url);
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country_code,
+      countryName: data.country_name,
+      region: data.region_name,
+      city: data.city_name,
+      latitude: data.latitude,
+      longitude: data.longitude
+    });
+  }
+});
+
+// src/providers/ipinfo.ts
+var ipinfo = withSelfLookup({
+  name: "ipinfo",
+  async lookup(ip) {
+    const data = await fetchJson(`https://ipinfo.io${ip ? `/${ip}` : ""}/json`);
+    const [latitude, longitude] = readText(data.loc)?.split(",") ?? [];
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country,
+      region: data.region,
+      city: data.city,
+      latitude,
+      longitude
+    });
+  }
+});
+
+// src/providers/ipwhois.ts
+var ipwhois = withSelfLookup({
+  name: "ipwhois",
+  async lookup(ip) {
+    const data = await fetchJson(`https://ipwho.is/${ip ?? ""}`);
+    if (data.success !== true) throw new Error(readText(data.message) ?? "Lookup was unsuccessful");
+    return normalizeLocation({
+      ip: data.ip,
+      countryCode: data.country_code,
+      countryName: data.country,
+      region: data.region,
+      city: data.city,
+      latitude: data.latitude,
+      longitude: data.longitude
+    });
+  }
+});
+
+// src/providers/index.ts
+var providers = [
+  freeipapi,
+  ipwhois,
+  geojs,
+  ip2location,
+  ipInfo,
+  ipinfo,
+  countryIs,
+  cloudflare
+];
+function getProviders() {
+  const isServer = typeof globalThis.location === "undefined";
+  return providers.filter((provider) => isServer || !provider.serverOnly);
+}
+
+// src/lookup.ts
+async function lookup(ip) {
+  const address = ip === void 0 ? void 0 : normalizeIp(ip);
+  const providers2 = getProviders();
+  const errors = [];
+  for (const provider of providers2) {
+    try {
+      const attempt = address === void 0 ? provider.lookupSelf?.() : provider.lookup?.(address);
+      if (!attempt) continue;
+      const { ip: detectedIp, countryCode, ...location } = await attempt;
+      if (!countryCode) {
+        errors.push(new Error(`${provider.name} response did not include a country code`));
+        continue;
+      }
+      return { ip: address ?? normalizeIp(detectedIp), countryCode, ...location, provider: provider.name };
+    } catch (cause) {
+      errors.push(new Error(`${provider.name} lookup failed`, { cause }));
+    }
+  }
+  throw new AggregateError(errors, `IP geolocation failed for ${address ?? "the caller"}`);
+}
+function normalizeIp(input) {
+  if (typeof input !== "string") throw new TypeError("Expected an IP address string");
+  const ip = input.trim();
+  const octets = ip.split(".");
+  const validOctet = (octet) => /^(0|[1-9]\d{0,2})$/.test(octet) && Number(octet) <= 255;
+  if (octets.length === 4 && octets.every(validOctet)) return ip;
+  if (ip.includes(":") && /^[a-f\d:.]+$/i.test(ip)) {
+    try {
+      new URL(`https://[${ip}]/`);
+      return ip;
+    } catch {
+    }
+  }
+  throw new TypeError(`Invalid IP address: ${input}`);
+}
+
+// src/index.ts
+var geoip = { lookup };
+export {
+  geoip
+};

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "where-is-ip",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Look up IP locations with native fetch and automatic fallback between keyless providers.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omyto/where-is-ip.git"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "jsdelivr": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.cjs",
+    "dist/index.d.ts",
+    "dist/index.d.cts"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/build.mjs",
+    "prepack": "npm run build"
+  },
+  "keywords": ["ip-geolocation", "geoip", "ip-lookup", "ip-location", "ipv4", "ipv6"],
+  "devDependencies": {
+    "esbuild": "0.28.1",
+    "typescript": "5.9.3"
+  }
+}