@ipgeotrace/browser 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @ipgeotrace/browser
+
+The browser [IPGeoTrace](https://ipgeotrace.com) client. Answers one question — *where is the
+person looking at this page?* — via `GET /resolve/me`, which sees the browser's real connection IP.
+
+Sign up and grab your publishable key at [ipgeotrace.com](https://ipgeotrace.com).
+
+Use it to personalize on the client: auto-select the visitor's country, price in their local
+currency, prefill a phone code, default a timezone or language.
+
+Framework-agnostic: React, Vue, Svelte, and vanilla all use it the same way. The optional reactive
+wrappers (`@ipgeotrace/react`, etc.) are thin sugar on top; you don't need them.
+
+## Install
+
+```sh
+npm add @ipgeotrace/browser
+```
+
+## Usage
+
+```ts
+import { createBrowserClient } from '@ipgeotrace/browser';
+
+const client = createBrowserClient({ publishableKey: 'pk_live_...' });
+
+const result = await client.me();
+if (result.ok) {
+  console.log(result.value.country?.name, result.value.location?.timeZone);
+}
+```
+
+That's it — `me()` calls the API directly from the browser. It's `async` because it makes a network
+request; `await` it and check `result.ok`.
+
+## The key is a publishable key
+
+You put this key in your client-side code on purpose. A publishable key is **safe to expose**
+because it is restricted: domain-locked to your site, scoped to `resolve` / `me` only (no batch, no
+account access), and rate-limited. This is the same model as a Google Maps browser key. Never ship
+your secret server key (`@ipgeotrace/client`) to the browser — that one can run batch lookups and
+spend your whole quota.
+
+> Publishable keys are a planned API feature (domain allowlist + resolve-only scope). Until they
+> ship, treat this package as targeting that model. See
+> [../../API-CONTRACT.md](../../API-CONTRACT.md#publishable-keys-planned).
+
+## Options
+
+```ts
+createBrowserClient({
+  publishableKey: 'pk_live_...',  // required
+  baseUrl: undefined,             // override the API host (staging / self-hosted)
+  timeoutMs: 10_000,
+  fetch: globalThis.fetch,
+});
+```
+
+`me()` is always a live call — it is never cached. The caller's IP can change at any time (VPN,
+Wi-Fi ↔ cellular, moving networks) and the browser never knows its own IP, so there is nothing safe
+to key a cache on. Every `me()` reflects the visitor's location right now. It returns the same
+`Result<GeoResponse>` shape as `@ipgeotrace/client`.
+
+## React, in ~30 lines (no extra package needed)
+
+```tsx
+function useVisitorGeo() {
+  const [state, setState] = useState<GeoResponse | null>(null);
+  useEffect(() => {
+    const client = createBrowserClient({ publishableKey: 'pk_live_...' });
+    const controller = new AbortController();
+    client.me(controller.signal).then((r) => r.ok && setState(r.value));
+    return () => controller.abort();
+  }, []);
+  return state;
+}
+```

package/dist/index.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+var client = require('@ipgeotrace/client');
+
+// src/client.ts
+var PRODUCTION_BASE_URL = "https://lookup.ipgeotrace.com";
+var API_VERSION = "v1";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var KNOWN_ERROR_CODES = new Set(Object.values(client.GeoErrorCodes));
+function createBrowserClient(options) {
+  if (!options.publishableKey) {
+    throw new Error("IPGeoTrace: a publishableKey is required.");
+  }
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const url = `${(options.baseUrl ?? PRODUCTION_BASE_URL).replace(/\/+$/, "")}/${API_VERSION}/resolve/me`;
+  const headers = { Accept: "application/json", "X-Api-Key": options.publishableKey };
+  return {
+    async me(signal) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      const requestSignal = combineSignals(signal, controller.signal);
+      try {
+        const response = await fetchImpl(url, { method: "GET", headers, signal: requestSignal });
+        clearTimeout(timer);
+        if (!response.ok) return { ok: false, error: await readError(response) };
+        const value = await response.json();
+        return { ok: true, value };
+      } catch (cause) {
+        clearTimeout(timer);
+        if (signal?.aborted) throw cause;
+        const timedOut = controller.signal.aborted;
+        return {
+          ok: false,
+          error: {
+            code: timedOut ? client.GeoErrorCodes.Timeout : client.GeoErrorCodes.NetworkError,
+            message: timedOut ? "The request timed out." : "The request could not reach the API."
+          }
+        };
+      }
+    }
+  };
+}
+async function readError(response) {
+  let body = {};
+  try {
+    body = await response.json();
+  } catch {
+    body = {};
+  }
+  const bodyCode = body.code !== void 0 && KNOWN_ERROR_CODES.has(body.code) ? body.code : void 0;
+  return {
+    code: bodyCode ?? statusToCode(response.status),
+    message: body.error ?? response.statusText ?? "The request failed.",
+    statusCode: response.status
+  };
+}
+function statusToCode(status) {
+  switch (status) {
+    case 400:
+      return client.GeoErrorCodes.BadRequest;
+    case 401:
+      return client.GeoErrorCodes.Unauthorized;
+    case 403:
+      return client.GeoErrorCodes.Forbidden;
+    case 404:
+      return client.GeoErrorCodes.NotFound;
+    case 429:
+      return client.GeoErrorCodes.RateLimited;
+    case 503:
+      return client.GeoErrorCodes.ServiceUnavailable;
+    default:
+      return client.GeoErrorCodes.Unknown;
+  }
+}
+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;
+}
+
+Object.defineProperty(exports, "GeoErrorCodes", {
+  enumerable: true,
+  get: function () { return client.GeoErrorCodes; }
+});
+exports.createBrowserClient = createBrowserClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"names":["GeoErrorCodes"],"mappings":"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","file":"index.cjs","sourcesContent":["import { GeoErrorCodes, type GeoError, type GeoErrorCode, type GeoResponse, type Result } from '@ipgeotrace/client';\n\nconst PRODUCTION_BASE_URL = 'https://lookup.ipgeotrace.com';\nconst API_VERSION = 'v1';\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst KNOWN_ERROR_CODES = new Set<string>(Object.values(GeoErrorCodes));\n\nexport interface BrowserClientOptions {\n  publishableKey: string;\n  baseUrl?: string;\n  timeoutMs?: number;\n  fetch?: typeof fetch;\n}\n\nexport interface BrowserClient {\n  me(signal?: AbortSignal): Promise<Result<GeoResponse>>;\n}\n\nexport function createBrowserClient(options: BrowserClientOptions): BrowserClient {\n  if (!options.publishableKey) {\n    throw new Error('IPGeoTrace: a publishableKey is required.');\n  }\n\n  const fetchImpl = options.fetch ?? globalThis.fetch;\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const url = `${(options.baseUrl ?? PRODUCTION_BASE_URL).replace(/\\/+$/, '')}/${API_VERSION}/resolve/me`;\n  const headers: Record<string, string> = { Accept: 'application/json', 'X-Api-Key': options.publishableKey };\n\n  return {\n    async me(signal?: AbortSignal): Promise<Result<GeoResponse>> {\n      const controller = new AbortController();\n      const timer = setTimeout(() => controller.abort(), timeoutMs);\n      const requestSignal = combineSignals(signal, controller.signal);\n\n      try {\n        const response = await fetchImpl(url, { method: 'GET', headers, signal: requestSignal });\n        clearTimeout(timer);\n\n        if (!response.ok) return { ok: false, error: await readError(response) };\n\n        const value = (await response.json()) as GeoResponse;\n        return { ok: true, value };\n      } catch (cause) {\n        clearTimeout(timer);\n        if (signal?.aborted) throw cause;\n        const timedOut = controller.signal.aborted;\n        return {\n          ok: false,\n          error: {\n            code: timedOut ? GeoErrorCodes.Timeout : GeoErrorCodes.NetworkError,\n            message: timedOut ? 'The request timed out.' : 'The request could not reach the API.',\n          },\n        };\n      }\n    },\n  };\n}\n\nasync function readError(response: Response): Promise<GeoError> {\n  let body: { error?: string; code?: string } = {};\n  try {\n    body = (await response.json()) as { error?: string; code?: string };\n  } catch {\n    body = {};\n  }\n  const bodyCode =\n    body.code !== undefined && KNOWN_ERROR_CODES.has(body.code)\n      ? (body.code as GeoErrorCode)\n      : undefined;\n  return {\n    code: bodyCode ?? statusToCode(response.status),\n    message: body.error ?? response.statusText ?? 'The request failed.',\n    statusCode: response.status,\n  };\n}\n\nfunction 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\nfunction combineSignals(external: AbortSignal | undefined, internal: AbortSignal): 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"]}

package/dist/index.d.cts

@@ -0,0 +1,15 @@
+import { Result, GeoResponse } from '@ipgeotrace/client';
+export { GeoError, GeoErrorCode, GeoErrorCodes, GeoResponse, Result } from '@ipgeotrace/client';
+
+interface BrowserClientOptions {
+    publishableKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+interface BrowserClient {
+    me(signal?: AbortSignal): Promise<Result<GeoResponse>>;
+}
+declare function createBrowserClient(options: BrowserClientOptions): BrowserClient;
+
+export { type BrowserClient, type BrowserClientOptions, createBrowserClient };

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { Result, GeoResponse } from '@ipgeotrace/client';
+export { GeoError, GeoErrorCode, GeoErrorCodes, GeoResponse, Result } from '@ipgeotrace/client';
+
+interface BrowserClientOptions {
+    publishableKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+interface BrowserClient {
+    me(signal?: AbortSignal): Promise<Result<GeoResponse>>;
+}
+declare function createBrowserClient(options: BrowserClientOptions): BrowserClient;
+
+export { type BrowserClient, type BrowserClientOptions, createBrowserClient };

package/dist/index.js

@@ -0,0 +1,87 @@
+import { GeoErrorCodes } from '@ipgeotrace/client';
+export { GeoErrorCodes } from '@ipgeotrace/client';
+
+// src/client.ts
+var PRODUCTION_BASE_URL = "https://lookup.ipgeotrace.com";
+var API_VERSION = "v1";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var KNOWN_ERROR_CODES = new Set(Object.values(GeoErrorCodes));
+function createBrowserClient(options) {
+  if (!options.publishableKey) {
+    throw new Error("IPGeoTrace: a publishableKey is required.");
+  }
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const url = `${(options.baseUrl ?? PRODUCTION_BASE_URL).replace(/\/+$/, "")}/${API_VERSION}/resolve/me`;
+  const headers = { Accept: "application/json", "X-Api-Key": options.publishableKey };
+  return {
+    async me(signal) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      const requestSignal = combineSignals(signal, controller.signal);
+      try {
+        const response = await fetchImpl(url, { method: "GET", headers, signal: requestSignal });
+        clearTimeout(timer);
+        if (!response.ok) return { ok: false, error: await readError(response) };
+        const value = await response.json();
+        return { ok: true, value };
+      } catch (cause) {
+        clearTimeout(timer);
+        if (signal?.aborted) throw cause;
+        const timedOut = controller.signal.aborted;
+        return {
+          ok: false,
+          error: {
+            code: timedOut ? GeoErrorCodes.Timeout : GeoErrorCodes.NetworkError,
+            message: timedOut ? "The request timed out." : "The request could not reach the API."
+          }
+        };
+      }
+    }
+  };
+}
+async function readError(response) {
+  let body = {};
+  try {
+    body = await response.json();
+  } catch {
+    body = {};
+  }
+  const bodyCode = body.code !== void 0 && KNOWN_ERROR_CODES.has(body.code) ? body.code : void 0;
+  return {
+    code: bodyCode ?? statusToCode(response.status),
+    message: body.error ?? response.statusText ?? "The request failed.",
+    statusCode: response.status
+  };
+}
+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;
+  }
+}
+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;
+}
+
+export { createBrowserClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { GeoErrorCodes, type GeoError, type GeoErrorCode, type GeoResponse, type Result } from '@ipgeotrace/client';\n\nconst PRODUCTION_BASE_URL = 'https://lookup.ipgeotrace.com';\nconst API_VERSION = 'v1';\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst KNOWN_ERROR_CODES = new Set<string>(Object.values(GeoErrorCodes));\n\nexport interface BrowserClientOptions {\n  publishableKey: string;\n  baseUrl?: string;\n  timeoutMs?: number;\n  fetch?: typeof fetch;\n}\n\nexport interface BrowserClient {\n  me(signal?: AbortSignal): Promise<Result<GeoResponse>>;\n}\n\nexport function createBrowserClient(options: BrowserClientOptions): BrowserClient {\n  if (!options.publishableKey) {\n    throw new Error('IPGeoTrace: a publishableKey is required.');\n  }\n\n  const fetchImpl = options.fetch ?? globalThis.fetch;\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const url = `${(options.baseUrl ?? PRODUCTION_BASE_URL).replace(/\\/+$/, '')}/${API_VERSION}/resolve/me`;\n  const headers: Record<string, string> = { Accept: 'application/json', 'X-Api-Key': options.publishableKey };\n\n  return {\n    async me(signal?: AbortSignal): Promise<Result<GeoResponse>> {\n      const controller = new AbortController();\n      const timer = setTimeout(() => controller.abort(), timeoutMs);\n      const requestSignal = combineSignals(signal, controller.signal);\n\n      try {\n        const response = await fetchImpl(url, { method: 'GET', headers, signal: requestSignal });\n        clearTimeout(timer);\n\n        if (!response.ok) return { ok: false, error: await readError(response) };\n\n        const value = (await response.json()) as GeoResponse;\n        return { ok: true, value };\n      } catch (cause) {\n        clearTimeout(timer);\n        if (signal?.aborted) throw cause;\n        const timedOut = controller.signal.aborted;\n        return {\n          ok: false,\n          error: {\n            code: timedOut ? GeoErrorCodes.Timeout : GeoErrorCodes.NetworkError,\n            message: timedOut ? 'The request timed out.' : 'The request could not reach the API.',\n          },\n        };\n      }\n    },\n  };\n}\n\nasync function readError(response: Response): Promise<GeoError> {\n  let body: { error?: string; code?: string } = {};\n  try {\n    body = (await response.json()) as { error?: string; code?: string };\n  } catch {\n    body = {};\n  }\n  const bodyCode =\n    body.code !== undefined && KNOWN_ERROR_CODES.has(body.code)\n      ? (body.code as GeoErrorCode)\n      : undefined;\n  return {\n    code: bodyCode ?? statusToCode(response.status),\n    message: body.error ?? response.statusText ?? 'The request failed.',\n    statusCode: response.status,\n  };\n}\n\nfunction 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\nfunction combineSignals(external: AbortSignal | undefined, internal: AbortSignal): 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"]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ipgeotrace/browser",
+  "version": "0.1.0",
+  "description": "Browser IPGeoTrace client. Resolve the current visitor's location with a publishable key.",
+  "keywords": [
+    "ipgeotrace",
+    "geolocation",
+    "geoip",
+    "browser",
+    "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,
+  "dependencies": {
+    "@ipgeotrace/client": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}