{"_id":"@ipgeotrace/client","name":"@ipgeotrace/client","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"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"}},"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"},"_id":"@ipgeotrace/client@0.1.0","_integrity":"sha512-x9YM0jmGVJC2mGonEMSwuraKZnTGgJ10hIZz9dhmUOwKKRyw0Ftcm3jqxAFrXDjppwmQzopIN9HYyyXU8DE0Qw==","_resolved":"/private/var/folders/1c/l77yr26d3cbbvw8pdsz8wvnc0000gn/T/69f16ee974bf710c8765c49f1bf434e7/ipgeotrace-client-0.1.0.tgz","_from":"file:ipgeotrace-client-0.1.0.tgz","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-x9YM0jmGVJC2mGonEMSwuraKZnTGgJ10hIZz9dhmUOwKKRyw0Ftcm3jqxAFrXDjppwmQzopIN9HYyyXU8DE0Qw==","shasum":"e58c4333673d5f5ddcd1c1f9c8eb00bedec0b687","tarball":"https://registry.npmjs.org/@ipgeotrace/client/-/client-0.1.0.tgz","fileCount":8,"unpackedSize":87924,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIALOb/1DKohqliX0PLDpbEQlj6U0vBJ93pT0cZgSo7stAiEA0cUHlqcz6C3pOxOdJ+Xkjlqrz+ZIbdQhYGt0vVCkzRk="}]},"_npmUser":{"name":"nertil","email":"pocinertili@gmail.com"},"directories":{},"maintainers":[{"name":"nertil","email":"pocinertili@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/client_0.1.0_1783091058612_0.9513224207141124"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T15:04:18.465Z","0.1.0":"2026-07-03T15:04:18.794Z","modified":"2026-07-03T15:04:19.059Z"},"maintainers":[{"name":"nertil","email":"pocinertili@gmail.com"}],"description":"Isomorphic IPGeoTrace client for Node, edge, Deno, and Bun. Single and batch IP geolocation with caching and retries.","homepage":"https://ipgeotrace.com","keywords":["ipgeotrace","geolocation","geoip","ip","typescript"],"license":"MIT","readme":"# @ipgeotrace/client\n\nIsomorphic [IPGeoTrace](https://ipgeotrace.com) client for **Node 18+, edge runtimes, Deno, and\nBun**. Resolve a single IP or a batch of up to 100, with optional caching and automatic retries.\nZero runtime dependencies, `fetch`-based.\n\nSign up and grab your API key at [ipgeotrace.com](https://ipgeotrace.com).\n\nThis is the server-side, secret-key client — you supply the IP. For the browser (resolve the\ncurrent visitor, no secret key), use [`@ipgeotrace/browser`](../browser).\n\n## Install\n\n```sh\nnpm add @ipgeotrace/client\n```\n\n## Quick start\n\n```ts\nimport { IpGeoTraceClient } from '@ipgeotrace/client';\n\nconst client = new IpGeoTraceClient({ apiKey: process.env.IPGEOTRACE_API_KEY! });\n\nconst result = await client.resolve('8.8.8.8');\nif (result.ok) {\n  console.log(`${result.value.city?.name}, ${result.value.country?.name}`);\n} else {\n  console.log(`failed: ${result.error.code}`);\n}\n```\n\nThe IP is always supplied by you: a signup form, a webhook payload, a stored audit log. Invalid IPs\nare caught locally (`invalid_ip`) with no wasted round trip.\n\n## Results, not exceptions\n\nEvery call returns `Result<T>` — `{ ok: true, value } | { ok: false, error }`. Check `ok` and\nTypeScript narrows `value` (or `error`) for you. The only thrown thing is caller cancellation via\nan `AbortSignal`:\n\n```ts\nconst controller = new AbortController();\nconst result = await client.resolve('8.8.8.8', controller.signal);\n```\n\n## Batch lookups\n\n```ts\nconst batch = await client.resolveBatch(logins.map((l) => l.ip));\nif (batch.ok) {\n  for (const item of batch.value.results) {\n    report.add(item.ip, item.found ? item.country?.name : item.error);\n  }\n}\n```\n\nResults come back in request order, one item per address. A single bad address fails as its own\nitem (`found: false, error`) without failing the batch. With caching on, cached IPs are served\nlocally and only the misses are sent; if every IP is a hit, no request is made and\n`batch.value.fromCache` is `true`.\n\n## Configuration\n\n```ts\nconst client = new IpGeoTraceClient({\n  apiKey: '...',\n  environment: 'production',   // or 'sandbox'; ignored when baseUrl is set\n  baseUrl: undefined,          // absolute override for self-hosted / staging\n  timeoutMs: 10_000,\n  maxRetries: 2,               // retries 429 (rate_limited) and 503, honoring Retry-After\n  cache: true,                 // or supply your own GeoCache (Redis, etc.)\n  cacheTtlMs: 5 * 60_000,\n  fetch: globalThis.fetch,     // override on Node < 18 or to inject a proxy agent\n});\n```\n\nOnly successful lookups are cached, never errors. A throwing cache never breaks a lookup — the\nclient falls back to calling the API.\n\n## Errors\n\nOn failure, `error` carries the reason:\n\n```ts\ninterface GeoError {\n  code: GeoErrorCode;         // GeoErrorCodes.*\n  message: string;\n  statusCode?: number;\n  retryAfterSeconds?: number;\n}\n```\n\nCodes: `unauthorized`, `invalid_ip`, `bad_request`, `not_found`, `rate_limited`, `quota_exceeded`,\n`license_inactive`, `forbidden`, `service_unavailable`, `network_error`, `timeout`,\n`invalid_response`, `unknown`.\n","readmeFilename":"README.md","_rev":"1-af270601d952b9ed9b5baa057abb637a"}