@ipgeotrace/client 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @ipgeotrace/client
+
+Isomorphic [IPGeoTrace](https://ipgeotrace.com) client for **Node 18+, edge runtimes, Deno, and
+Bun**. Resolve a single IP or a batch of up to 100, with optional caching and automatic retries.
+Zero runtime dependencies, `fetch`-based.
+
+Sign up and grab your API key at [ipgeotrace.com](https://ipgeotrace.com).
+
+This is the server-side, secret-key client — you supply the IP. For the browser (resolve the
+current visitor, no secret key), use [`@ipgeotrace/browser`](../browser).
+
+## Install
+
+```sh
+npm add @ipgeotrace/client
+```
+
+## Quick start
+
+```ts
+import { IpGeoTraceClient } from '@ipgeotrace/client';
+
+const client = new IpGeoTraceClient({ apiKey: process.env.IPGEOTRACE_API_KEY! });
+
+const result = await client.resolve('8.8.8.8');
+if (result.ok) {
+  console.log(`${result.value.city?.name}, ${result.value.country?.name}`);
+} else {
+  console.log(`failed: ${result.error.code}`);
+}
+```
+
+The IP is always supplied by you: a signup form, a webhook payload, a stored audit log. Invalid IPs
+are caught locally (`invalid_ip`) with no wasted round trip.
+
+## Results, not exceptions
+
+Every call returns `Result<T>` — `{ ok: true, value } | { ok: false, error }`. Check `ok` and
+TypeScript narrows `value` (or `error`) for you. The only thrown thing is caller cancellation via
+an `AbortSignal`:
+
+```ts
+const controller = new AbortController();
+const result = await client.resolve('8.8.8.8', controller.signal);
+```
+
+## Batch lookups
+
+```ts
+const batch = await client.resolveBatch(logins.map((l) => l.ip));
+if (batch.ok) {
+  for (const item of batch.value.results) {
+    report.add(item.ip, item.found ? item.country?.name : item.error);
+  }
+}
+```
+
+Results come back in request order, one item per address. A single bad address fails as its own
+item (`found: false, error`) without failing the batch. With caching on, cached IPs are served
+locally and only the misses are sent; if every IP is a hit, no request is made and
+`batch.value.fromCache` is `true`.
+
+## Configuration
+
+```ts
+const client = new IpGeoTraceClient({
+  apiKey: '...',
+  environment: 'production',   // or 'sandbox'; ignored when baseUrl is set
+  baseUrl: undefined,          // absolute override for self-hosted / staging
+  timeoutMs: 10_000,
+  maxRetries: 2,               // retries 429 (rate_limited) and 503, honoring Retry-After
+  cache: true,                 // or supply your own GeoCache (Redis, etc.)
+  cacheTtlMs: 5 * 60_000,
+  fetch: globalThis.fetch,     // override on Node < 18 or to inject a proxy agent
+});
+```
+
+Only successful lookups are cached, never errors. A throwing cache never breaks a lookup — the
+client falls back to calling the API.
+
+## Errors
+
+On failure, `error` carries the reason:
+
+```ts
+interface GeoError {
+  code: GeoErrorCode;         // GeoErrorCodes.*
+  message: string;
+  statusCode?: number;
+  retryAfterSeconds?: number;
+}
+```
+
+Codes: `unauthorized`, `invalid_ip`, `bad_request`, `not_found`, `rate_limited`, `quota_exceeded`,
+`license_inactive`, `forbidden`, `service_unavailable`, `network_error`, `timeout`,
+`invalid_response`, `unknown`.

package/dist/index.cjs

@@ -0,0 +1,337 @@
+'use strict';
+
+// src/cache.ts
+var MemoryGeoCache = class {
+  store = /* @__PURE__ */ new Map();
+  get(ip) {
+    const entry = this.store.get(ip);
+    if (!entry) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.store.delete(ip);
+      return void 0;
+    }
+    return entry.value;
+  }
+  set(ip, value, ttlMs) {
+    this.store.set(ip, { value, expiresAt: Date.now() + ttlMs });
+  }
+};
+
+// src/errors.ts
+var GeoErrorCodes = {
+  Unauthorized: "unauthorized",
+  InvalidIp: "invalid_ip",
+  BadRequest: "bad_request",
+  NotFound: "not_found",
+  RateLimited: "rate_limited",
+  QuotaExceeded: "quota_exceeded",
+  LicenseInactive: "license_inactive",
+  Forbidden: "forbidden",
+  ServiceUnavailable: "service_unavailable",
+  NetworkError: "network_error",
+  Timeout: "timeout",
+  InvalidResponse: "invalid_response",
+  Unknown: "unknown"
+};
+function statusToCode(status) {
+  switch (status) {
+    case 400:
+      return GeoErrorCodes.BadRequest;
+    case 401:
+      return GeoErrorCodes.Unauthorized;
+    case 403:
+      return GeoErrorCodes.Forbidden;
+    case 404:
+      return GeoErrorCodes.NotFound;
+    case 429:
+      return GeoErrorCodes.RateLimited;
+    case 503:
+      return GeoErrorCodes.ServiceUnavailable;
+    default:
+      return GeoErrorCodes.Unknown;
+  }
+}
+
+// src/internal/ip.ts
+var IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+var IPV6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|::(ffff(:0{1,4})?:)?((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d))$/;
+function isValidIp(ip) {
+  return IPV4.test(ip) || IPV6.test(ip);
+}
+function isPrivateOrReservedIp(ip) {
+  const normalized = ip.trim().toLowerCase();
+  return normalized.includes(":") ? isPrivateIpv6(normalized) : isPrivateIpv4(normalized);
+}
+function isPrivateIpv4(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return false;
+  const octets = parts.map((part) => Number(part));
+  if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return false;
+  const a = octets[0];
+  const b = octets[1];
+  if (a === 0 || a === 10 || a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  return false;
+}
+function isPrivateIpv6(ip) {
+  if (ip === "::1" || ip === "::") return true;
+  const mapped = ip.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (mapped) return isPrivateIpv4(mapped[1]);
+  const hextet = parseInt(ip.split(":")[0] ?? "", 16);
+  if (Number.isNaN(hextet)) return false;
+  if (hextet >= 64512 && hextet <= 65023) return true;
+  if (hextet >= 65152 && hextet <= 65215) return true;
+  return false;
+}
+
+// src/result.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error) {
+  return { ok: false, error };
+}
+
+// src/internal/http.ts
+var KNOWN_ERROR_CODES = new Set(Object.values(GeoErrorCodes));
+async function send(config, method, path, body, signal) {
+  const url = `${config.baseUrl}${path}`;
+  let attempt = 0;
+  while (true) {
+    const timeoutController = new AbortController();
+    const timer = setTimeout(() => timeoutController.abort(), config.timeoutMs);
+    const requestSignal = combineSignals(signal, timeoutController.signal);
+    try {
+      const response = await config.fetchImpl(url, {
+        method,
+        headers: {
+          "X-Api-Key": config.apiKey,
+          Accept: "application/json",
+          ...body === void 0 ? {} : { "Content-Type": "application/json" }
+        },
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: requestSignal
+      });
+      clearTimeout(timer);
+      if (response.ok) return await parseJson(response);
+      const error = await readError(response);
+      if (shouldRetry(error.code) && attempt < config.maxRetries) {
+        attempt += 1;
+        await sleep(backoff(attempt, error.retryAfterSeconds));
+        continue;
+      }
+      return err(error);
+    } catch (cause) {
+      clearTimeout(timer);
+      if (signal?.aborted) throw cause;
+      const timedOut = timeoutController.signal.aborted;
+      const code = timedOut ? GeoErrorCodes.Timeout : GeoErrorCodes.NetworkError;
+      if (attempt < config.maxRetries) {
+        attempt += 1;
+        await sleep(backoff(attempt));
+        continue;
+      }
+      return err({
+        code,
+        message: timedOut ? "The request timed out." : "The request could not reach the API."
+      });
+    }
+  }
+}
+async function parseJson(response) {
+  try {
+    return ok(await response.json());
+  } catch {
+    return err({
+      code: GeoErrorCodes.InvalidResponse,
+      message: "The API returned a response that could not be read.",
+      statusCode: response.status
+    });
+  }
+}
+async function readError(response) {
+  let parsed = {};
+  try {
+    parsed = await response.json();
+  } catch {
+    parsed = {};
+  }
+  const bodyCode = parsed.code !== void 0 && KNOWN_ERROR_CODES.has(parsed.code) ? parsed.code : void 0;
+  const code = bodyCode ?? statusToCode(response.status);
+  return {
+    code,
+    message: parsed.error ?? response.statusText ?? "The request failed.",
+    statusCode: response.status,
+    retryAfterSeconds: parseRetryAfter(response.headers.get("retry-after"))
+  };
+}
+function shouldRetry(code) {
+  return code === GeoErrorCodes.RateLimited || code === GeoErrorCodes.ServiceUnavailable;
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : void 0;
+}
+var BASE_BACKOFF_MS = 200;
+var MAX_BACKOFF_MS = 2e3;
+function backoff(attempt, retryAfterSeconds) {
+  if (retryAfterSeconds !== void 0) return retryAfterSeconds * 1e3;
+  const exponential = Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** (attempt - 1));
+  return exponential + Math.floor(Math.random() * BASE_BACKOFF_MS);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function combineSignals(external, internal) {
+  if (!external) return internal;
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (external.aborted || internal.aborted) controller.abort();
+  external.addEventListener("abort", abort, { once: true });
+  internal.addEventListener("abort", abort, { once: true });
+  return controller.signal;
+}
+
+// src/options.ts
+var PRODUCTION_BASE_URL = "https://lookup.ipgeotrace.com";
+var SANDBOX_BASE_URL = "https://lookup.dev.ipgeotrace.com";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_CACHE_TTL_MS = 5 * 6e4;
+function resolveConfig(options, defaultCache) {
+  if (!options.apiKey) throw new Error("IPGeoTrace: an apiKey is required.");
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  if (timeoutMs <= 0) throw new Error("IPGeoTrace: timeoutMs must be greater than zero.");
+  if (maxRetries < 0) throw new Error("IPGeoTrace: maxRetries cannot be negative.");
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("IPGeoTrace: no global fetch available; pass options.fetch (Node < 18).");
+  }
+  let cache;
+  if (options.cache === true) cache = defaultCache();
+  else if (options.cache) cache = options.cache;
+  return {
+    apiKey: options.apiKey,
+    baseUrl: resolveBaseUrl(options),
+    timeoutMs,
+    maxRetries,
+    cache,
+    cacheTtlMs: options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS,
+    fetchImpl
+  };
+}
+function resolveBaseUrl(options) {
+  const base = options.baseUrl ?? (options.environment === "sandbox" ? SANDBOX_BASE_URL : PRODUCTION_BASE_URL);
+  return base.replace(/\/+$/, "");
+}
+
+// src/client.ts
+var MAX_BATCH_SIZE = 100;
+var API_VERSION = "v1";
+var IpGeoTraceClient = class {
+  config;
+  cache;
+  constructor(options) {
+    this.config = resolveConfig(options, () => new MemoryGeoCache());
+    this.cache = this.config.cache;
+  }
+  async resolve(ip, signal) {
+    if (!isValidIp(ip)) {
+      return err({ code: GeoErrorCodes.InvalidIp, message: `'${ip}' is not a valid IP address.` });
+    }
+    const cached = await this.readCache(ip);
+    if (cached) return ok(cached);
+    const result = await send(this.config, "GET", `/${API_VERSION}/resolve/${encodeURIComponent(ip)}`, void 0, signal);
+    if (result.ok) await this.writeCache(ip, result.value);
+    return result;
+  }
+  async resolveBatch(ips, signal) {
+    const requested = [...ips];
+    if (requested.length === 0) {
+      return err({ code: GeoErrorCodes.BadRequest, message: "At least one IP address is required." });
+    }
+    if (requested.length > MAX_BATCH_SIZE) {
+      return err({ code: GeoErrorCodes.BadRequest, message: `A batch may contain at most ${MAX_BATCH_SIZE} IP addresses.` });
+    }
+    const byIp = /* @__PURE__ */ new Map();
+    const misses = [];
+    for (const ip of requested) {
+      if (!isValidIp(ip)) {
+        byIp.set(ip, { ip, found: false, error: GeoErrorCodes.InvalidIp });
+        continue;
+      }
+      const cached = await this.readCache(ip);
+      if (cached) {
+        byIp.set(ip, toBatchItem(cached));
+        continue;
+      }
+      misses.push(ip);
+    }
+    let fromCache = true;
+    if (misses.length > 0) {
+      const response = await send(this.config, "POST", `/${API_VERSION}/resolve/batch`, { ips: misses }, signal);
+      if (!response.ok) return response;
+      fromCache = false;
+      const items = response.value.results;
+      for (let i = 0; i < items.length; i += 1) {
+        const item = items[i];
+        if (!item) continue;
+        const key = misses[i] ?? item.ip;
+        byIp.set(key, item);
+        if (item.found) await this.writeCache(key, toGeoResponse(item));
+      }
+    }
+    const results = requested.map((ip) => byIp.get(ip) ?? { ip, found: false, error: GeoErrorCodes.Unknown });
+    return ok({ results, fromCache });
+  }
+  async readCache(ip) {
+    if (!this.cache) return void 0;
+    try {
+      return await this.cache.get(ip) ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  async writeCache(ip, value) {
+    if (!this.cache) return;
+    try {
+      await this.cache.set(ip, value, this.config.cacheTtlMs);
+    } catch {
+      return;
+    }
+  }
+};
+function toGeoResponse(item) {
+  return {
+    ip: item.ip,
+    ipVersion: item.ip.includes(":") ? 6 : 4,
+    continent: item.continent,
+    country: item.country,
+    region: item.region,
+    city: item.city,
+    location: item.location,
+    asn: item.asn,
+    isp: item.isp
+  };
+}
+function toBatchItem(response) {
+  const { ipVersion: _ipVersion, ...rest } = response;
+  return { ...rest, found: true };
+}
+
+exports.GeoErrorCodes = GeoErrorCodes;
+exports.IpGeoTraceClient = IpGeoTraceClient;
+exports.MemoryGeoCache = MemoryGeoCache;
+exports.PRODUCTION_BASE_URL = PRODUCTION_BASE_URL;
+exports.SANDBOX_BASE_URL = SANDBOX_BASE_URL;
+exports.err = err;
+exports.isPrivateOrReservedIp = isPrivateOrReservedIp;
+exports.isValidIp = isValidIp;
+exports.ok = ok;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cache.ts","../src/errors.ts","../src/internal/ip.ts","../src/result.ts","../src/internal/http.ts","../src/options.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { GeoResponse } from './types.js';\n\nexport interface GeoCache {\n  get(ip: string): Promise<GeoResponse | undefined> | GeoResponse | undefined;\n  set(ip: string, value: GeoResponse, ttlMs: number): Promise<void> | void;\n}\n\ninterface Entry {\n  value: GeoResponse;\n  expiresAt: number;\n}\n\nexport class MemoryGeoCache implements GeoCache {\n  private readonly store = new Map<string, Entry>();\n\n  get(ip: string): GeoResponse | undefined {\n    const entry = this.store.get(ip);\n    if (!entry) return undefined;\n    if (entry.expiresAt <= Date.now()) {\n      this.store.delete(ip);\n      return undefined;\n    }\n    return entry.value;\n  }\n\n  set(ip: string, value: GeoResponse, ttlMs: number): void {\n    this.store.set(ip, { value, expiresAt: Date.now() + ttlMs });\n  }\n}\n","export const GeoErrorCodes = {\n  Unauthorized: 'unauthorized',\n  InvalidIp: 'invalid_ip',\n  BadRequest: 'bad_request',\n  NotFound: 'not_found',\n  RateLimited: 'rate_limited',\n  QuotaExceeded: 'quota_exceeded',\n  LicenseInactive: 'license_inactive',\n  Forbidden: 'forbidden',\n  ServiceUnavailable: 'service_unavailable',\n  NetworkError: 'network_error',\n  Timeout: 'timeout',\n  InvalidResponse: 'invalid_response',\n  Unknown: 'unknown',\n} as const;\n\nexport type GeoErrorCode = (typeof GeoErrorCodes)[keyof typeof GeoErrorCodes];\n\nexport interface GeoError {\n  code: GeoErrorCode;\n  message: string;\n  statusCode?: number;\n  retryAfterSeconds?: number;\n}\n\nexport function statusToCode(status: number): GeoErrorCode {\n  switch (status) {\n    case 400:\n      return GeoErrorCodes.BadRequest;\n    case 401:\n      return GeoErrorCodes.Unauthorized;\n    case 403:\n      return GeoErrorCodes.Forbidden;\n    case 404:\n      return GeoErrorCodes.NotFound;\n    case 429:\n      return GeoErrorCodes.RateLimited;\n    case 503:\n      return GeoErrorCodes.ServiceUnavailable;\n    default:\n      return GeoErrorCodes.Unknown;\n  }\n}\n","const IPV4 =\n  /^(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}$/;\n\nconst IPV6 =\n  /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|::(ffff(:0{1,4})?:)?((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d))$/;\n\nexport function isValidIp(ip: string): boolean {\n  return IPV4.test(ip) || IPV6.test(ip);\n}\n\nexport function isPrivateOrReservedIp(ip: string): boolean {\n  const normalized = ip.trim().toLowerCase();\n  return normalized.includes(':') ? isPrivateIpv6(normalized) : isPrivateIpv4(normalized);\n}\n\nfunction isPrivateIpv4(ip: string): boolean {\n  const parts = ip.split('.');\n  if (parts.length !== 4) return false;\n  const octets = parts.map((part) => Number(part));\n  if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return false;\n\n  const a = octets[0]!;\n  const b = octets[1]!;\n  if (a === 0 || a === 10 || a === 127) return true;\n  if (a === 169 && b === 254) return true;\n  if (a === 172 && b >= 16 && b <= 31) return true;\n  if (a === 192 && b === 168) return true;\n  if (a === 100 && b >= 64 && b <= 127) return true;\n  return false;\n}\n\nfunction isPrivateIpv6(ip: string): boolean {\n  if (ip === '::1' || ip === '::') return true;\n\n  const mapped = ip.match(/^::ffff:(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$/);\n  if (mapped) return isPrivateIpv4(mapped[1]!);\n\n  const hextet = parseInt(ip.split(':')[0] ?? '', 16);\n  if (Number.isNaN(hextet)) return false;\n  if (hextet >= 0xfc00 && hextet <= 0xfdff) return true;\n  if (hextet >= 0xfe80 && hextet <= 0xfebf) return true;\n  return false;\n}\n","import type { GeoError } from './errors.js';\n\nexport type Result<T> = { ok: true; value: T } | { ok: false; error: GeoError };\n\nexport function ok<T>(value: T): Result<T> {\n  return { ok: true, value };\n}\n\nexport function err<T = never>(error: GeoError): Result<T> {\n  return { ok: false, error };\n}\n","import { type GeoError, type GeoErrorCode, GeoErrorCodes, statusToCode } from '../errors.js';\nimport { err, ok, type Result } from '../result.js';\nimport type { ResolvedConfig } from '../options.js';\n\ninterface ApiErrorBody {\n  error?: string;\n  code?: string;\n}\n\nconst KNOWN_ERROR_CODES = new Set<string>(Object.values(GeoErrorCodes));\n\nexport async function send<T>(\n  config: ResolvedConfig,\n  method: 'GET' | 'POST',\n  path: string,\n  body: unknown,\n  signal: AbortSignal | undefined,\n): Promise<Result<T>> {\n  const url = `${config.baseUrl}${path}`;\n  let attempt = 0;\n\n  while (true) {\n    const timeoutController = new AbortController();\n    const timer = setTimeout(() => timeoutController.abort(), config.timeoutMs);\n    const requestSignal = combineSignals(signal, timeoutController.signal);\n\n    try {\n      const response = await config.fetchImpl(url, {\n        method,\n        headers: {\n          'X-Api-Key': config.apiKey,\n          Accept: 'application/json',\n          ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),\n        },\n        body: body === undefined ? undefined : JSON.stringify(body),\n        signal: requestSignal,\n      });\n      clearTimeout(timer);\n\n      if (response.ok) return await parseJson<T>(response);\n\n      const error = await readError(response);\n      if (shouldRetry(error.code) && attempt < config.maxRetries) {\n        attempt += 1;\n        await sleep(backoff(attempt, error.retryAfterSeconds));\n        continue;\n      }\n      return err(error);\n    } catch (cause) {\n      clearTimeout(timer);\n      if (signal?.aborted) throw cause;\n\n      const timedOut = timeoutController.signal.aborted;\n      const code = timedOut ? GeoErrorCodes.Timeout : GeoErrorCodes.NetworkError;\n      if (attempt < config.maxRetries) {\n        attempt += 1;\n        await sleep(backoff(attempt));\n        continue;\n      }\n      return err({\n        code,\n        message: timedOut ? 'The request timed out.' : 'The request could not reach the API.',\n      });\n    }\n  }\n}\n\nasync function parseJson<T>(response: Response): Promise<Result<T>> {\n  try {\n    return ok((await response.json()) as T);\n  } catch {\n    return err({\n      code: GeoErrorCodes.InvalidResponse,\n      message: 'The API returned a response that could not be read.',\n      statusCode: response.status,\n    });\n  }\n}\n\nasync function readError(response: Response): Promise<GeoError> {\n  let parsed: ApiErrorBody = {};\n  try {\n    parsed = (await response.json()) as ApiErrorBody;\n  } catch {\n    parsed = {};\n  }\n\n  const bodyCode =\n    parsed.code !== undefined && KNOWN_ERROR_CODES.has(parsed.code)\n      ? (parsed.code as GeoErrorCode)\n      : undefined;\n  const code = bodyCode ?? statusToCode(response.status);\n  return {\n    code,\n    message: parsed.error ?? response.statusText ?? 'The request failed.',\n    statusCode: response.status,\n    retryAfterSeconds: parseRetryAfter(response.headers.get('retry-after')),\n  };\n}\n\nfunction shouldRetry(code: GeoErrorCode): boolean {\n  return code === GeoErrorCodes.RateLimited || code === GeoErrorCodes.ServiceUnavailable;\n}\n\nfunction parseRetryAfter(value: string | null): number | undefined {\n  if (!value) return undefined;\n  const seconds = Number(value);\n  return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;\n}\n\nconst BASE_BACKOFF_MS = 200;\nconst MAX_BACKOFF_MS = 2_000;\n\nfunction backoff(attempt: number, retryAfterSeconds?: number): number {\n  if (retryAfterSeconds !== undefined) return retryAfterSeconds * 1_000;\n  const exponential = Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** (attempt - 1));\n  return exponential + Math.floor(Math.random() * BASE_BACKOFF_MS);\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nfunction combineSignals(\n  external: AbortSignal | undefined,\n  internal: AbortSignal,\n): AbortSignal {\n  if (!external) return internal;\n  const controller = new AbortController();\n  const abort = () => controller.abort();\n  if (external.aborted || internal.aborted) controller.abort();\n  external.addEventListener('abort', abort, { once: true });\n  internal.addEventListener('abort', abort, { once: true });\n  return controller.signal;\n}\n","import type { GeoCache } from './cache.js';\n\nexport type IpGeoTraceEnvironment = 'production' | 'sandbox';\n\nexport const PRODUCTION_BASE_URL = 'https://lookup.ipgeotrace.com';\nexport const SANDBOX_BASE_URL = 'https://lookup.dev.ipgeotrace.com';\n\nexport interface IpGeoTraceClientOptions {\n  apiKey: string;\n  environment?: IpGeoTraceEnvironment;\n  baseUrl?: string;\n  timeoutMs?: number;\n  maxRetries?: number;\n  cache?: GeoCache | boolean;\n  cacheTtlMs?: number;\n  fetch?: typeof fetch;\n}\n\nexport interface ResolvedConfig {\n  apiKey: string;\n  baseUrl: string;\n  timeoutMs: number;\n  maxRetries: number;\n  cache?: GeoCache;\n  cacheTtlMs: number;\n  fetchImpl: typeof fetch;\n}\n\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst DEFAULT_MAX_RETRIES = 2;\nconst DEFAULT_CACHE_TTL_MS = 5 * 60_000;\n\nexport function resolveConfig(\n  options: IpGeoTraceClientOptions,\n  defaultCache: () => GeoCache,\n): ResolvedConfig {\n  if (!options.apiKey) throw new Error('IPGeoTrace: an apiKey is required.');\n\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;\n  if (timeoutMs <= 0) throw new Error('IPGeoTrace: timeoutMs must be greater than zero.');\n  if (maxRetries < 0) throw new Error('IPGeoTrace: maxRetries cannot be negative.');\n\n  const fetchImpl = options.fetch ?? globalThis.fetch;\n  if (typeof fetchImpl !== 'function') {\n    throw new Error('IPGeoTrace: no global fetch available; pass options.fetch (Node < 18).');\n  }\n\n  let cache: GeoCache | undefined;\n  if (options.cache === true) cache = defaultCache();\n  else if (options.cache) cache = options.cache;\n\n  return {\n    apiKey: options.apiKey,\n    baseUrl: resolveBaseUrl(options),\n    timeoutMs,\n    maxRetries,\n    cache,\n    cacheTtlMs: options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS,\n    fetchImpl,\n  };\n}\n\nfunction resolveBaseUrl(options: IpGeoTraceClientOptions): string {\n  const base = options.baseUrl ?? (options.environment === 'sandbox' ? SANDBOX_BASE_URL : PRODUCTION_BASE_URL);\n  return base.replace(/\\/+$/, '');\n}\n","import { type GeoCache, MemoryGeoCache } from './cache.js';\nimport { GeoErrorCodes } from './errors.js';\nimport { isValidIp } from './internal/ip.js';\nimport { send } from './internal/http.js';\nimport {\n  type IpGeoTraceClientOptions,\n  resolveConfig,\n  type ResolvedConfig,\n} from './options.js';\nimport { err, ok, type Result } from './result.js';\nimport type { BatchItem, BatchResponse, GeoResponse } from './types.js';\n\nconst MAX_BATCH_SIZE = 100;\nconst API_VERSION = 'v1';\n\nexport class IpGeoTraceClient {\n  private readonly config: ResolvedConfig;\n  private readonly cache?: GeoCache;\n\n  constructor(options: IpGeoTraceClientOptions) {\n    this.config = resolveConfig(options, () => new MemoryGeoCache());\n    this.cache = this.config.cache;\n  }\n\n  async resolve(ip: string, signal?: AbortSignal): Promise<Result<GeoResponse>> {\n    if (!isValidIp(ip)) {\n      return err({ code: GeoErrorCodes.InvalidIp, message: `'${ip}' is not a valid IP address.` });\n    }\n\n    const cached = await this.readCache(ip);\n    if (cached) return ok(cached);\n\n    const result = await send<GeoResponse>(this.config, 'GET', `/${API_VERSION}/resolve/${encodeURIComponent(ip)}`, undefined, signal);\n    if (result.ok) await this.writeCache(ip, result.value);\n    return result;\n  }\n\n  async resolveBatch(ips: Iterable<string>, signal?: AbortSignal): Promise<Result<BatchResponse>> {\n    const requested = [...ips];\n    if (requested.length === 0) {\n      return err({ code: GeoErrorCodes.BadRequest, message: 'At least one IP address is required.' });\n    }\n    if (requested.length > MAX_BATCH_SIZE) {\n      return err({ code: GeoErrorCodes.BadRequest, message: `A batch may contain at most ${MAX_BATCH_SIZE} IP addresses.` });\n    }\n\n    const byIp = new Map<string, BatchItem>();\n    const misses: string[] = [];\n    for (const ip of requested) {\n      if (!isValidIp(ip)) {\n        byIp.set(ip, { ip, found: false, error: GeoErrorCodes.InvalidIp });\n        continue;\n      }\n      const cached = await this.readCache(ip);\n      if (cached) {\n        byIp.set(ip, toBatchItem(cached));\n        continue;\n      }\n      misses.push(ip);\n    }\n\n    let fromCache = true;\n    if (misses.length > 0) {\n      const response = await send<{ results: BatchItem[] }>(this.config, 'POST', `/${API_VERSION}/resolve/batch`, { ips: misses }, signal);\n      if (!response.ok) return response;\n      fromCache = false;\n      const items = response.value.results;\n      for (let i = 0; i < items.length; i += 1) {\n        const item = items[i];\n        if (!item) continue;\n        const key = misses[i] ?? item.ip;\n        byIp.set(key, item);\n        if (item.found) await this.writeCache(key, toGeoResponse(item));\n      }\n    }\n\n    const results = requested.map((ip) => byIp.get(ip) ?? { ip, found: false, error: GeoErrorCodes.Unknown });\n    return ok({ results, fromCache });\n  }\n\n  private async readCache(ip: string): Promise<GeoResponse | undefined> {\n    if (!this.cache) return undefined;\n    try {\n      return (await this.cache.get(ip)) ?? undefined;\n    } catch {\n      return undefined;\n    }\n  }\n\n  private async writeCache(ip: string, value: GeoResponse): Promise<void> {\n    if (!this.cache) return;\n    try {\n      await this.cache.set(ip, value, this.config.cacheTtlMs);\n    } catch {\n      return;\n    }\n  }\n}\n\nfunction toGeoResponse(item: BatchItem): GeoResponse {\n  return {\n    ip: item.ip,\n    ipVersion: item.ip.includes(':') ? 6 : 4,\n    continent: item.continent,\n    country: item.country,\n    region: item.region,\n    city: item.city,\n    location: item.location,\n    asn: item.asn,\n    isp: item.isp,\n  };\n}\n\nfunction toBatchItem(response: GeoResponse): BatchItem {\n  const { ipVersion: _ipVersion, ...rest } = response;\n  return { ...rest, found: true };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,143 @@
+interface GeoResponse {
+    ip: string;
+    ipVersion: number;
+    continent?: Continent;
+    country?: Country;
+    region?: Region;
+    city?: City;
+    location?: GeoLocation;
+    asn?: Asn;
+    isp?: Isp;
+}
+interface Continent {
+    code?: string;
+    name?: string;
+}
+interface Country {
+    code?: string;
+    code3?: string;
+    name?: string;
+    currency?: string;
+    currencyName?: string;
+    phoneCode?: string;
+    languages?: string[];
+}
+interface Region {
+    code?: string;
+    name?: string;
+}
+interface City {
+    name?: string;
+    postalCode?: string;
+    population?: number;
+}
+interface GeoLocation {
+    latitude?: number;
+    longitude?: number;
+    accuracyRadiusKm?: number;
+    timeZone?: string;
+    gmtOffset?: number;
+}
+interface Asn {
+    number?: number;
+    name?: string;
+    type?: string;
+}
+interface Isp {
+    name?: string;
+}
+interface BatchResponse {
+    results: BatchItem[];
+    fromCache: boolean;
+}
+interface BatchItem {
+    ip: string;
+    found: boolean;
+    error?: string;
+    continent?: Continent;
+    country?: Country;
+    region?: Region;
+    city?: City;
+    location?: GeoLocation;
+    asn?: Asn;
+    isp?: Isp;
+}
+
+interface GeoCache {
+    get(ip: string): Promise<GeoResponse | undefined> | GeoResponse | undefined;
+    set(ip: string, value: GeoResponse, ttlMs: number): Promise<void> | void;
+}
+declare class MemoryGeoCache implements GeoCache {
+    private readonly store;
+    get(ip: string): GeoResponse | undefined;
+    set(ip: string, value: GeoResponse, ttlMs: number): void;
+}
+
+type IpGeoTraceEnvironment = 'production' | 'sandbox';
+declare const PRODUCTION_BASE_URL = "https://lookup.ipgeotrace.com";
+declare const SANDBOX_BASE_URL = "https://lookup.dev.ipgeotrace.com";
+interface IpGeoTraceClientOptions {
+    apiKey: string;
+    environment?: IpGeoTraceEnvironment;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    cache?: GeoCache | boolean;
+    cacheTtlMs?: number;
+    fetch?: typeof fetch;
+}
+
+declare const GeoErrorCodes: {
+    readonly Unauthorized: "unauthorized";
+    readonly InvalidIp: "invalid_ip";
+    readonly BadRequest: "bad_request";
+    readonly NotFound: "not_found";
+    readonly RateLimited: "rate_limited";
+    readonly QuotaExceeded: "quota_exceeded";
+    readonly LicenseInactive: "license_inactive";
+    readonly Forbidden: "forbidden";
+    readonly ServiceUnavailable: "service_unavailable";
+    readonly NetworkError: "network_error";
+    readonly Timeout: "timeout";
+    readonly InvalidResponse: "invalid_response";
+    readonly Unknown: "unknown";
+};
+type GeoErrorCode = (typeof GeoErrorCodes)[keyof typeof GeoErrorCodes];
+interface GeoError {
+    code: GeoErrorCode;
+    message: string;
+    statusCode?: number;
+    retryAfterSeconds?: number;
+}
+
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: GeoError;
+};
+declare function ok<T>(value: T): Result<T>;
+declare function err<T = never>(error: GeoError): Result<T>;
+
+declare class IpGeoTraceClient {
+    private readonly config;
+    private readonly cache?;
+    constructor(options: IpGeoTraceClientOptions);
+    resolve(ip: string, signal?: AbortSignal): Promise<Result<GeoResponse>>;
+    resolveBatch(ips: Iterable<string>, signal?: AbortSignal): Promise<Result<BatchResponse>>;
+    private readCache;
+    private writeCache;
+}
+
+declare function isValidIp(ip: string): boolean;
+declare function isPrivateOrReservedIp(ip: string): boolean;
+
+type GeoLookupStatus = 'resolved' | 'skipped' | 'failed' | 'not_attempted';
+interface GeoLookup {
+    status: GeoLookupStatus;
+    value?: GeoResponse;
+    error?: GeoError;
+}
+
+export { type Asn, type BatchItem, type BatchResponse, type City, type Continent, type Country, type GeoCache, type GeoError, type GeoErrorCode, GeoErrorCodes, type GeoLocation, type GeoLookup, type GeoLookupStatus, type GeoResponse, IpGeoTraceClient, type IpGeoTraceClientOptions, type IpGeoTraceEnvironment, type Isp, MemoryGeoCache, PRODUCTION_BASE_URL, type Region, type Result, SANDBOX_BASE_URL, err, isPrivateOrReservedIp, isValidIp, ok };

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+interface GeoResponse {
+    ip: string;
+    ipVersion: number;
+    continent?: Continent;
+    country?: Country;
+    region?: Region;
+    city?: City;
+    location?: GeoLocation;
+    asn?: Asn;
+    isp?: Isp;
+}
+interface Continent {
+    code?: string;
+    name?: string;
+}
+interface Country {
+    code?: string;
+    code3?: string;
+    name?: string;
+    currency?: string;
+    currencyName?: string;
+    phoneCode?: string;
+    languages?: string[];
+}
+interface Region {
+    code?: string;
+    name?: string;
+}
+interface City {
+    name?: string;
+    postalCode?: string;
+    population?: number;
+}
+interface GeoLocation {
+    latitude?: number;
+    longitude?: number;
+    accuracyRadiusKm?: number;
+    timeZone?: string;
+    gmtOffset?: number;
+}
+interface Asn {
+    number?: number;
+    name?: string;
+    type?: string;
+}
+interface Isp {
+    name?: string;
+}
+interface BatchResponse {
+    results: BatchItem[];
+    fromCache: boolean;
+}
+interface BatchItem {
+    ip: string;
+    found: boolean;
+    error?: string;
+    continent?: Continent;
+    country?: Country;
+    region?: Region;
+    city?: City;
+    location?: GeoLocation;
+    asn?: Asn;
+    isp?: Isp;
+}
+
+interface GeoCache {
+    get(ip: string): Promise<GeoResponse | undefined> | GeoResponse | undefined;
+    set(ip: string, value: GeoResponse, ttlMs: number): Promise<void> | void;
+}
+declare class MemoryGeoCache implements GeoCache {
+    private readonly store;
+    get(ip: string): GeoResponse | undefined;
+    set(ip: string, value: GeoResponse, ttlMs: number): void;
+}
+
+type IpGeoTraceEnvironment = 'production' | 'sandbox';
+declare const PRODUCTION_BASE_URL = "https://lookup.ipgeotrace.com";
+declare const SANDBOX_BASE_URL = "https://lookup.dev.ipgeotrace.com";
+interface IpGeoTraceClientOptions {
+    apiKey: string;
+    environment?: IpGeoTraceEnvironment;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    cache?: GeoCache | boolean;
+    cacheTtlMs?: number;
+    fetch?: typeof fetch;
+}
+
+declare const GeoErrorCodes: {
+    readonly Unauthorized: "unauthorized";
+    readonly InvalidIp: "invalid_ip";
+    readonly BadRequest: "bad_request";
+    readonly NotFound: "not_found";
+    readonly RateLimited: "rate_limited";
+    readonly QuotaExceeded: "quota_exceeded";
+    readonly LicenseInactive: "license_inactive";
+    readonly Forbidden: "forbidden";
+    readonly ServiceUnavailable: "service_unavailable";
+    readonly NetworkError: "network_error";
+    readonly Timeout: "timeout";
+    readonly InvalidResponse: "invalid_response";
+    readonly Unknown: "unknown";
+};
+type GeoErrorCode = (typeof GeoErrorCodes)[keyof typeof GeoErrorCodes];
+interface GeoError {
+    code: GeoErrorCode;
+    message: string;
+    statusCode?: number;
+    retryAfterSeconds?: number;
+}
+
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: GeoError;
+};
+declare function ok<T>(value: T): Result<T>;
+declare function err<T = never>(error: GeoError): Result<T>;
+
+declare class IpGeoTraceClient {
+    private readonly config;
+    private readonly cache?;
+    constructor(options: IpGeoTraceClientOptions);
+    resolve(ip: string, signal?: AbortSignal): Promise<Result<GeoResponse>>;
+    resolveBatch(ips: Iterable<string>, signal?: AbortSignal): Promise<Result<BatchResponse>>;
+    private readCache;
+    private writeCache;
+}
+
+declare function isValidIp(ip: string): boolean;
+declare function isPrivateOrReservedIp(ip: string): boolean;
+
+type GeoLookupStatus = 'resolved' | 'skipped' | 'failed' | 'not_attempted';
+interface GeoLookup {
+    status: GeoLookupStatus;
+    value?: GeoResponse;
+    error?: GeoError;
+}
+
+export { type Asn, type BatchItem, type BatchResponse, type City, type Continent, type Country, type GeoCache, type GeoError, type GeoErrorCode, GeoErrorCodes, type GeoLocation, type GeoLookup, type GeoLookupStatus, type GeoResponse, IpGeoTraceClient, type IpGeoTraceClientOptions, type IpGeoTraceEnvironment, type Isp, MemoryGeoCache, PRODUCTION_BASE_URL, type Region, type Result, SANDBOX_BASE_URL, err, isPrivateOrReservedIp, isValidIp, ok };

package/dist/index.js

@@ -0,0 +1,327 @@
+// src/cache.ts
+var MemoryGeoCache = class {
+  store = /* @__PURE__ */ new Map();
+  get(ip) {
+    const entry = this.store.get(ip);
+    if (!entry) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.store.delete(ip);
+      return void 0;
+    }
+    return entry.value;
+  }
+  set(ip, value, ttlMs) {
+    this.store.set(ip, { value, expiresAt: Date.now() + ttlMs });
+  }
+};
+
+// src/errors.ts
+var GeoErrorCodes = {
+  Unauthorized: "unauthorized",
+  InvalidIp: "invalid_ip",
+  BadRequest: "bad_request",
+  NotFound: "not_found",
+  RateLimited: "rate_limited",
+  QuotaExceeded: "quota_exceeded",
+  LicenseInactive: "license_inactive",
+  Forbidden: "forbidden",
+  ServiceUnavailable: "service_unavailable",
+  NetworkError: "network_error",
+  Timeout: "timeout",
+  InvalidResponse: "invalid_response",
+  Unknown: "unknown"
+};
+function statusToCode(status) {
+  switch (status) {
+    case 400:
+      return GeoErrorCodes.BadRequest;
+    case 401:
+      return GeoErrorCodes.Unauthorized;
+    case 403:
+      return GeoErrorCodes.Forbidden;
+    case 404:
+      return GeoErrorCodes.NotFound;
+    case 429:
+      return GeoErrorCodes.RateLimited;
+    case 503:
+      return GeoErrorCodes.ServiceUnavailable;
+    default:
+      return GeoErrorCodes.Unknown;
+  }
+}
+
+// src/internal/ip.ts
+var IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+var IPV6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|::(ffff(:0{1,4})?:)?((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d))$/;
+function isValidIp(ip) {
+  return IPV4.test(ip) || IPV6.test(ip);
+}
+function isPrivateOrReservedIp(ip) {
+  const normalized = ip.trim().toLowerCase();
+  return normalized.includes(":") ? isPrivateIpv6(normalized) : isPrivateIpv4(normalized);
+}
+function isPrivateIpv4(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return false;
+  const octets = parts.map((part) => Number(part));
+  if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return false;
+  const a = octets[0];
+  const b = octets[1];
+  if (a === 0 || a === 10 || a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  return false;
+}
+function isPrivateIpv6(ip) {
+  if (ip === "::1" || ip === "::") return true;
+  const mapped = ip.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (mapped) return isPrivateIpv4(mapped[1]);
+  const hextet = parseInt(ip.split(":")[0] ?? "", 16);
+  if (Number.isNaN(hextet)) return false;
+  if (hextet >= 64512 && hextet <= 65023) return true;
+  if (hextet >= 65152 && hextet <= 65215) return true;
+  return false;
+}
+
+// src/result.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error) {
+  return { ok: false, error };
+}
+
+// src/internal/http.ts
+var KNOWN_ERROR_CODES = new Set(Object.values(GeoErrorCodes));
+async function send(config, method, path, body, signal) {
+  const url = `${config.baseUrl}${path}`;
+  let attempt = 0;
+  while (true) {
+    const timeoutController = new AbortController();
+    const timer = setTimeout(() => timeoutController.abort(), config.timeoutMs);
+    const requestSignal = combineSignals(signal, timeoutController.signal);
+    try {
+      const response = await config.fetchImpl(url, {
+        method,
+        headers: {
+          "X-Api-Key": config.apiKey,
+          Accept: "application/json",
+          ...body === void 0 ? {} : { "Content-Type": "application/json" }
+        },
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: requestSignal
+      });
+      clearTimeout(timer);
+      if (response.ok) return await parseJson(response);
+      const error = await readError(response);
+      if (shouldRetry(error.code) && attempt < config.maxRetries) {
+        attempt += 1;
+        await sleep(backoff(attempt, error.retryAfterSeconds));
+        continue;
+      }
+      return err(error);
+    } catch (cause) {
+      clearTimeout(timer);
+      if (signal?.aborted) throw cause;
+      const timedOut = timeoutController.signal.aborted;
+      const code = timedOut ? GeoErrorCodes.Timeout : GeoErrorCodes.NetworkError;
+      if (attempt < config.maxRetries) {
+        attempt += 1;
+        await sleep(backoff(attempt));
+        continue;
+      }
+      return err({
+        code,
+        message: timedOut ? "The request timed out." : "The request could not reach the API."
+      });
+    }
+  }
+}
+async function parseJson(response) {
+  try {
+    return ok(await response.json());
+  } catch {
+    return err({
+      code: GeoErrorCodes.InvalidResponse,
+      message: "The API returned a response that could not be read.",
+      statusCode: response.status
+    });
+  }
+}
+async function readError(response) {
+  let parsed = {};
+  try {
+    parsed = await response.json();
+  } catch {
+    parsed = {};
+  }
+  const bodyCode = parsed.code !== void 0 && KNOWN_ERROR_CODES.has(parsed.code) ? parsed.code : void 0;
+  const code = bodyCode ?? statusToCode(response.status);
+  return {
+    code,
+    message: parsed.error ?? response.statusText ?? "The request failed.",
+    statusCode: response.status,
+    retryAfterSeconds: parseRetryAfter(response.headers.get("retry-after"))
+  };
+}
+function shouldRetry(code) {
+  return code === GeoErrorCodes.RateLimited || code === GeoErrorCodes.ServiceUnavailable;
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : void 0;
+}
+var BASE_BACKOFF_MS = 200;
+var MAX_BACKOFF_MS = 2e3;
+function backoff(attempt, retryAfterSeconds) {
+  if (retryAfterSeconds !== void 0) return retryAfterSeconds * 1e3;
+  const exponential = Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** (attempt - 1));
+  return exponential + Math.floor(Math.random() * BASE_BACKOFF_MS);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function combineSignals(external, internal) {
+  if (!external) return internal;
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (external.aborted || internal.aborted) controller.abort();
+  external.addEventListener("abort", abort, { once: true });
+  internal.addEventListener("abort", abort, { once: true });
+  return controller.signal;
+}
+
+// src/options.ts
+var PRODUCTION_BASE_URL = "https://lookup.ipgeotrace.com";
+var SANDBOX_BASE_URL = "https://lookup.dev.ipgeotrace.com";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_CACHE_TTL_MS = 5 * 6e4;
+function resolveConfig(options, defaultCache) {
+  if (!options.apiKey) throw new Error("IPGeoTrace: an apiKey is required.");
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  if (timeoutMs <= 0) throw new Error("IPGeoTrace: timeoutMs must be greater than zero.");
+  if (maxRetries < 0) throw new Error("IPGeoTrace: maxRetries cannot be negative.");
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("IPGeoTrace: no global fetch available; pass options.fetch (Node < 18).");
+  }
+  let cache;
+  if (options.cache === true) cache = defaultCache();
+  else if (options.cache) cache = options.cache;
+  return {
+    apiKey: options.apiKey,
+    baseUrl: resolveBaseUrl(options),
+    timeoutMs,
+    maxRetries,
+    cache,
+    cacheTtlMs: options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS,
+    fetchImpl
+  };
+}
+function resolveBaseUrl(options) {
+  const base = options.baseUrl ?? (options.environment === "sandbox" ? SANDBOX_BASE_URL : PRODUCTION_BASE_URL);
+  return base.replace(/\/+$/, "");
+}
+
+// src/client.ts
+var MAX_BATCH_SIZE = 100;
+var API_VERSION = "v1";
+var IpGeoTraceClient = class {
+  config;
+  cache;
+  constructor(options) {
+    this.config = resolveConfig(options, () => new MemoryGeoCache());
+    this.cache = this.config.cache;
+  }
+  async resolve(ip, signal) {
+    if (!isValidIp(ip)) {
+      return err({ code: GeoErrorCodes.InvalidIp, message: `'${ip}' is not a valid IP address.` });
+    }
+    const cached = await this.readCache(ip);
+    if (cached) return ok(cached);
+    const result = await send(this.config, "GET", `/${API_VERSION}/resolve/${encodeURIComponent(ip)}`, void 0, signal);
+    if (result.ok) await this.writeCache(ip, result.value);
+    return result;
+  }
+  async resolveBatch(ips, signal) {
+    const requested = [...ips];
+    if (requested.length === 0) {
+      return err({ code: GeoErrorCodes.BadRequest, message: "At least one IP address is required." });
+    }
+    if (requested.length > MAX_BATCH_SIZE) {
+      return err({ code: GeoErrorCodes.BadRequest, message: `A batch may contain at most ${MAX_BATCH_SIZE} IP addresses.` });
+    }
+    const byIp = /* @__PURE__ */ new Map();
+    const misses = [];
+    for (const ip of requested) {
+      if (!isValidIp(ip)) {
+        byIp.set(ip, { ip, found: false, error: GeoErrorCodes.InvalidIp });
+        continue;
+      }
+      const cached = await this.readCache(ip);
+      if (cached) {
+        byIp.set(ip, toBatchItem(cached));
+        continue;
+      }
+      misses.push(ip);
+    }
+    let fromCache = true;
+    if (misses.length > 0) {
+      const response = await send(this.config, "POST", `/${API_VERSION}/resolve/batch`, { ips: misses }, signal);
+      if (!response.ok) return response;
+      fromCache = false;
+      const items = response.value.results;
+      for (let i = 0; i < items.length; i += 1) {
+        const item = items[i];
+        if (!item) continue;
+        const key = misses[i] ?? item.ip;
+        byIp.set(key, item);
+        if (item.found) await this.writeCache(key, toGeoResponse(item));
+      }
+    }
+    const results = requested.map((ip) => byIp.get(ip) ?? { ip, found: false, error: GeoErrorCodes.Unknown });
+    return ok({ results, fromCache });
+  }
+  async readCache(ip) {
+    if (!this.cache) return void 0;
+    try {
+      return await this.cache.get(ip) ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  async writeCache(ip, value) {
+    if (!this.cache) return;
+    try {
+      await this.cache.set(ip, value, this.config.cacheTtlMs);
+    } catch {
+      return;
+    }
+  }
+};
+function toGeoResponse(item) {
+  return {
+    ip: item.ip,
+    ipVersion: item.ip.includes(":") ? 6 : 4,
+    continent: item.continent,
+    country: item.country,
+    region: item.region,
+    city: item.city,
+    location: item.location,
+    asn: item.asn,
+    isp: item.isp
+  };
+}
+function toBatchItem(response) {
+  const { ipVersion: _ipVersion, ...rest } = response;
+  return { ...rest, found: true };
+}
+
+export { GeoErrorCodes, IpGeoTraceClient, MemoryGeoCache, PRODUCTION_BASE_URL, SANDBOX_BASE_URL, err, isPrivateOrReservedIp, isValidIp, ok };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cache.ts","../src/errors.ts","../src/internal/ip.ts","../src/result.ts","../src/internal/http.ts","../src/options.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { GeoResponse } from './types.js';\n\nexport interface GeoCache {\n  get(ip: string): Promise<GeoResponse | undefined> | GeoResponse | undefined;\n  set(ip: string, value: GeoResponse, ttlMs: number): Promise<void> | void;\n}\n\ninterface Entry {\n  value: GeoResponse;\n  expiresAt: number;\n}\n\nexport class MemoryGeoCache implements GeoCache {\n  private readonly store = new Map<string, Entry>();\n\n  get(ip: string): GeoResponse | undefined {\n    const entry = this.store.get(ip);\n    if (!entry) return undefined;\n    if (entry.expiresAt <= Date.now()) {\n      this.store.delete(ip);\n      return undefined;\n    }\n    return entry.value;\n  }\n\n  set(ip: string, value: GeoResponse, ttlMs: number): void {\n    this.store.set(ip, { value, expiresAt: Date.now() + ttlMs });\n  }\n}\n","export const GeoErrorCodes = {\n  Unauthorized: 'unauthorized',\n  InvalidIp: 'invalid_ip',\n  BadRequest: 'bad_request',\n  NotFound: 'not_found',\n  RateLimited: 'rate_limited',\n  QuotaExceeded: 'quota_exceeded',\n  LicenseInactive: 'license_inactive',\n  Forbidden: 'forbidden',\n  ServiceUnavailable: 'service_unavailable',\n  NetworkError: 'network_error',\n  Timeout: 'timeout',\n  InvalidResponse: 'invalid_response',\n  Unknown: 'unknown',\n} as const;\n\nexport type GeoErrorCode = (typeof GeoErrorCodes)[keyof typeof GeoErrorCodes];\n\nexport interface GeoError {\n  code: GeoErrorCode;\n  message: string;\n  statusCode?: number;\n  retryAfterSeconds?: number;\n}\n\nexport function statusToCode(status: number): GeoErrorCode {\n  switch (status) {\n    case 400:\n      return GeoErrorCodes.BadRequest;\n    case 401:\n      return GeoErrorCodes.Unauthorized;\n    case 403:\n      return GeoErrorCodes.Forbidden;\n    case 404:\n      return GeoErrorCodes.NotFound;\n    case 429:\n      return GeoErrorCodes.RateLimited;\n    case 503:\n      return GeoErrorCodes.ServiceUnavailable;\n    default:\n      return GeoErrorCodes.Unknown;\n  }\n}\n","const IPV4 =\n  /^(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}$/;\n\nconst IPV6 =\n  /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|::(ffff(:0{1,4})?:)?((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d))$/;\n\nexport function isValidIp(ip: string): boolean {\n  return IPV4.test(ip) || IPV6.test(ip);\n}\n\nexport function isPrivateOrReservedIp(ip: string): boolean {\n  const normalized = ip.trim().toLowerCase();\n  return normalized.includes(':') ? isPrivateIpv6(normalized) : isPrivateIpv4(normalized);\n}\n\nfunction isPrivateIpv4(ip: string): boolean {\n  const parts = ip.split('.');\n  if (parts.length !== 4) return false;\n  const octets = parts.map((part) => Number(part));\n  if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return false;\n\n  const a = octets[0]!;\n  const b = octets[1]!;\n  if (a === 0 || a === 10 || a === 127) return true;\n  if (a === 169 && b === 254) return true;\n  if (a === 172 && b >= 16 && b <= 31) return true;\n  if (a === 192 && b === 168) return true;\n  if (a === 100 && b >= 64 && b <= 127) return true;\n  return false;\n}\n\nfunction isPrivateIpv6(ip: string): boolean {\n  if (ip === '::1' || ip === '::') return true;\n\n  const mapped = ip.match(/^::ffff:(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$/);\n  if (mapped) return isPrivateIpv4(mapped[1]!);\n\n  const hextet = parseInt(ip.split(':')[0] ?? '', 16);\n  if (Number.isNaN(hextet)) return false;\n  if (hextet >= 0xfc00 && hextet <= 0xfdff) return true;\n  if (hextet >= 0xfe80 && hextet <= 0xfebf) return true;\n  return false;\n}\n","import type { GeoError } from './errors.js';\n\nexport type Result<T> = { ok: true; value: T } | { ok: false; error: GeoError };\n\nexport function ok<T>(value: T): Result<T> {\n  return { ok: true, value };\n}\n\nexport function err<T = never>(error: GeoError): Result<T> {\n  return { ok: false, error };\n}\n","import { type GeoError, type GeoErrorCode, GeoErrorCodes, statusToCode } from '../errors.js';\nimport { err, ok, type Result } from '../result.js';\nimport type { ResolvedConfig } from '../options.js';\n\ninterface ApiErrorBody {\n  error?: string;\n  code?: string;\n}\n\nconst KNOWN_ERROR_CODES = new Set<string>(Object.values(GeoErrorCodes));\n\nexport async function send<T>(\n  config: ResolvedConfig,\n  method: 'GET' | 'POST',\n  path: string,\n  body: unknown,\n  signal: AbortSignal | undefined,\n): Promise<Result<T>> {\n  const url = `${config.baseUrl}${path}`;\n  let attempt = 0;\n\n  while (true) {\n    const timeoutController = new AbortController();\n    const timer = setTimeout(() => timeoutController.abort(), config.timeoutMs);\n    const requestSignal = combineSignals(signal, timeoutController.signal);\n\n    try {\n      const response = await config.fetchImpl(url, {\n        method,\n        headers: {\n          'X-Api-Key': config.apiKey,\n          Accept: 'application/json',\n          ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),\n        },\n        body: body === undefined ? undefined : JSON.stringify(body),\n        signal: requestSignal,\n      });\n      clearTimeout(timer);\n\n      if (response.ok) return await parseJson<T>(response);\n\n      const error = await readError(response);\n      if (shouldRetry(error.code) && attempt < config.maxRetries) {\n        attempt += 1;\n        await sleep(backoff(attempt, error.retryAfterSeconds));\n        continue;\n      }\n      return err(error);\n    } catch (cause) {\n      clearTimeout(timer);\n      if (signal?.aborted) throw cause;\n\n      const timedOut = timeoutController.signal.aborted;\n      const code = timedOut ? GeoErrorCodes.Timeout : GeoErrorCodes.NetworkError;\n      if (attempt < config.maxRetries) {\n        attempt += 1;\n        await sleep(backoff(attempt));\n        continue;\n      }\n      return err({\n        code,\n        message: timedOut ? 'The request timed out.' : 'The request could not reach the API.',\n      });\n    }\n  }\n}\n\nasync function parseJson<T>(response: Response): Promise<Result<T>> {\n  try {\n    return ok((await response.json()) as T);\n  } catch {\n    return err({\n      code: GeoErrorCodes.InvalidResponse,\n      message: 'The API returned a response that could not be read.',\n      statusCode: response.status,\n    });\n  }\n}\n\nasync function readError(response: Response): Promise<GeoError> {\n  let parsed: ApiErrorBody = {};\n  try {\n    parsed = (await response.json()) as ApiErrorBody;\n  } catch {\n    parsed = {};\n  }\n\n  const bodyCode =\n    parsed.code !== undefined && KNOWN_ERROR_CODES.has(parsed.code)\n      ? (parsed.code as GeoErrorCode)\n      : undefined;\n  const code = bodyCode ?? statusToCode(response.status);\n  return {\n    code,\n    message: parsed.error ?? response.statusText ?? 'The request failed.',\n    statusCode: response.status,\n    retryAfterSeconds: parseRetryAfter(response.headers.get('retry-after')),\n  };\n}\n\nfunction shouldRetry(code: GeoErrorCode): boolean {\n  return code === GeoErrorCodes.RateLimited || code === GeoErrorCodes.ServiceUnavailable;\n}\n\nfunction parseRetryAfter(value: string | null): number | undefined {\n  if (!value) return undefined;\n  const seconds = Number(value);\n  return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;\n}\n\nconst BASE_BACKOFF_MS = 200;\nconst MAX_BACKOFF_MS = 2_000;\n\nfunction backoff(attempt: number, retryAfterSeconds?: number): number {\n  if (retryAfterSeconds !== undefined) return retryAfterSeconds * 1_000;\n  const exponential = Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** (attempt - 1));\n  return exponential + Math.floor(Math.random() * BASE_BACKOFF_MS);\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nfunction combineSignals(\n  external: AbortSignal | undefined,\n  internal: AbortSignal,\n): AbortSignal {\n  if (!external) return internal;\n  const controller = new AbortController();\n  const abort = () => controller.abort();\n  if (external.aborted || internal.aborted) controller.abort();\n  external.addEventListener('abort', abort, { once: true });\n  internal.addEventListener('abort', abort, { once: true });\n  return controller.signal;\n}\n","import type { GeoCache } from './cache.js';\n\nexport type IpGeoTraceEnvironment = 'production' | 'sandbox';\n\nexport const PRODUCTION_BASE_URL = 'https://lookup.ipgeotrace.com';\nexport const SANDBOX_BASE_URL = 'https://lookup.dev.ipgeotrace.com';\n\nexport interface IpGeoTraceClientOptions {\n  apiKey: string;\n  environment?: IpGeoTraceEnvironment;\n  baseUrl?: string;\n  timeoutMs?: number;\n  maxRetries?: number;\n  cache?: GeoCache | boolean;\n  cacheTtlMs?: number;\n  fetch?: typeof fetch;\n}\n\nexport interface ResolvedConfig {\n  apiKey: string;\n  baseUrl: string;\n  timeoutMs: number;\n  maxRetries: number;\n  cache?: GeoCache;\n  cacheTtlMs: number;\n  fetchImpl: typeof fetch;\n}\n\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst DEFAULT_MAX_RETRIES = 2;\nconst DEFAULT_CACHE_TTL_MS = 5 * 60_000;\n\nexport function resolveConfig(\n  options: IpGeoTraceClientOptions,\n  defaultCache: () => GeoCache,\n): ResolvedConfig {\n  if (!options.apiKey) throw new Error('IPGeoTrace: an apiKey is required.');\n\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;\n  if (timeoutMs <= 0) throw new Error('IPGeoTrace: timeoutMs must be greater than zero.');\n  if (maxRetries < 0) throw new Error('IPGeoTrace: maxRetries cannot be negative.');\n\n  const fetchImpl = options.fetch ?? globalThis.fetch;\n  if (typeof fetchImpl !== 'function') {\n    throw new Error('IPGeoTrace: no global fetch available; pass options.fetch (Node < 18).');\n  }\n\n  let cache: GeoCache | undefined;\n  if (options.cache === true) cache = defaultCache();\n  else if (options.cache) cache = options.cache;\n\n  return {\n    apiKey: options.apiKey,\n    baseUrl: resolveBaseUrl(options),\n    timeoutMs,\n    maxRetries,\n    cache,\n    cacheTtlMs: options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS,\n    fetchImpl,\n  };\n}\n\nfunction resolveBaseUrl(options: IpGeoTraceClientOptions): string {\n  const base = options.baseUrl ?? (options.environment === 'sandbox' ? SANDBOX_BASE_URL : PRODUCTION_BASE_URL);\n  return base.replace(/\\/+$/, '');\n}\n","import { type GeoCache, MemoryGeoCache } from './cache.js';\nimport { GeoErrorCodes } from './errors.js';\nimport { isValidIp } from './internal/ip.js';\nimport { send } from './internal/http.js';\nimport {\n  type IpGeoTraceClientOptions,\n  resolveConfig,\n  type ResolvedConfig,\n} from './options.js';\nimport { err, ok, type Result } from './result.js';\nimport type { BatchItem, BatchResponse, GeoResponse } from './types.js';\n\nconst MAX_BATCH_SIZE = 100;\nconst API_VERSION = 'v1';\n\nexport class IpGeoTraceClient {\n  private readonly config: ResolvedConfig;\n  private readonly cache?: GeoCache;\n\n  constructor(options: IpGeoTraceClientOptions) {\n    this.config = resolveConfig(options, () => new MemoryGeoCache());\n    this.cache = this.config.cache;\n  }\n\n  async resolve(ip: string, signal?: AbortSignal): Promise<Result<GeoResponse>> {\n    if (!isValidIp(ip)) {\n      return err({ code: GeoErrorCodes.InvalidIp, message: `'${ip}' is not a valid IP address.` });\n    }\n\n    const cached = await this.readCache(ip);\n    if (cached) return ok(cached);\n\n    const result = await send<GeoResponse>(this.config, 'GET', `/${API_VERSION}/resolve/${encodeURIComponent(ip)}`, undefined, signal);\n    if (result.ok) await this.writeCache(ip, result.value);\n    return result;\n  }\n\n  async resolveBatch(ips: Iterable<string>, signal?: AbortSignal): Promise<Result<BatchResponse>> {\n    const requested = [...ips];\n    if (requested.length === 0) {\n      return err({ code: GeoErrorCodes.BadRequest, message: 'At least one IP address is required.' });\n    }\n    if (requested.length > MAX_BATCH_SIZE) {\n      return err({ code: GeoErrorCodes.BadRequest, message: `A batch may contain at most ${MAX_BATCH_SIZE} IP addresses.` });\n    }\n\n    const byIp = new Map<string, BatchItem>();\n    const misses: string[] = [];\n    for (const ip of requested) {\n      if (!isValidIp(ip)) {\n        byIp.set(ip, { ip, found: false, error: GeoErrorCodes.InvalidIp });\n        continue;\n      }\n      const cached = await this.readCache(ip);\n      if (cached) {\n        byIp.set(ip, toBatchItem(cached));\n        continue;\n      }\n      misses.push(ip);\n    }\n\n    let fromCache = true;\n    if (misses.length > 0) {\n      const response = await send<{ results: BatchItem[] }>(this.config, 'POST', `/${API_VERSION}/resolve/batch`, { ips: misses }, signal);\n      if (!response.ok) return response;\n      fromCache = false;\n      const items = response.value.results;\n      for (let i = 0; i < items.length; i += 1) {\n        const item = items[i];\n        if (!item) continue;\n        const key = misses[i] ?? item.ip;\n        byIp.set(key, item);\n        if (item.found) await this.writeCache(key, toGeoResponse(item));\n      }\n    }\n\n    const results = requested.map((ip) => byIp.get(ip) ?? { ip, found: false, error: GeoErrorCodes.Unknown });\n    return ok({ results, fromCache });\n  }\n\n  private async readCache(ip: string): Promise<GeoResponse | undefined> {\n    if (!this.cache) return undefined;\n    try {\n      return (await this.cache.get(ip)) ?? undefined;\n    } catch {\n      return undefined;\n    }\n  }\n\n  private async writeCache(ip: string, value: GeoResponse): Promise<void> {\n    if (!this.cache) return;\n    try {\n      await this.cache.set(ip, value, this.config.cacheTtlMs);\n    } catch {\n      return;\n    }\n  }\n}\n\nfunction toGeoResponse(item: BatchItem): GeoResponse {\n  return {\n    ip: item.ip,\n    ipVersion: item.ip.includes(':') ? 6 : 4,\n    continent: item.continent,\n    country: item.country,\n    region: item.region,\n    city: item.city,\n    location: item.location,\n    asn: item.asn,\n    isp: item.isp,\n  };\n}\n\nfunction toBatchItem(response: GeoResponse): BatchItem {\n  const { ipVersion: _ipVersion, ...rest } = response;\n  return { ...rest, found: true };\n}\n"]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ipgeotrace/client",
+  "version": "0.1.0",
+  "description": "Isomorphic IPGeoTrace client for Node, edge, Deno, and Bun. Single and batch IP geolocation with caching and retries.",
+  "keywords": [
+    "ipgeotrace",
+    "geolocation",
+    "geoip",
+    "ip",
+    "typescript"
+  ],
+  "license": "MIT",
+  "homepage": "https://ipgeotrace.com",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.17"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}