@interfere/react 9.0.2 → 10.0.0

package/dist/tracking/api.d.mts

@@ -1,21 +1,47 @@
-import { IngestTarget } from "../transport/http.mjs";
+import { IngestTarget } from "../internal/config.mjs";
+import { DeviceManager } from "./device.mjs";
+import { GeoDetector } from "./geo.mjs";
+import { SessionId } from "@interfere/types/data/session";
 import { IdentifyParams } from "@interfere/types/sdk/identify";
 
 //#region src/tracking/api.d.ts
-declare function bootstrap(sessionTarget: IngestTarget): void;
-declare const device: {
+interface SessionTrackerOptions {
+  device?: DeviceManager;
+  fetcher?: typeof globalThis.fetch;
+  geo?: GeoDetector;
+  target: IngestTarget;
+}
+declare class SessionTracker {
+  private readonly target;
+  private readonly fetcher;
+  private readonly device;
+  private readonly geo;
+  private mgr;
+  private currentIdentity;
+  private identifiedSessionId;
+  private syncedSessionId;
+  private syncAttemptMs;
+  private generation;
+  constructor(opts: SessionTrackerOptions);
+  start(): void;
+  sessionId(): SessionId | null;
+  windowId(): string | null;
   getDeviceId(): string | null;
   getFpHash(): string | null;
-};
-declare const session: {
-  getId(): string | null;
-  getWindowId(): string | null;
-};
-declare const identity: {
-  get(): IdentifyParams | null;
-  set(params: IdentifyParams): Promise<void>;
-  clear(): void;
-};
-declare function teardown(): void;
+  /**
+   * Identity headers (session / window / device). Layered onto the
+   * session/identify POSTs alongside the target's static headers
+   * (content-type + auth + force-enable).
+   */
+  headers(): Record<string, string>;
+  getIdentity(): IdentifyParams | null;
+  identify(params: IdentifyParams): Promise<void>;
+  clearIdentity(): void;
+  dispose(): void;
+  private requestHeaders;
+  private ensureSynced;
+  private syncSession;
+  private onRotate;
+}
 //#endregion
-export { bootstrap, device, identity, session, teardown };
+export { SessionTracker, SessionTrackerOptions };

package/dist/tracking/api.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.mts","names":[],"sources":["../../src/tracking/api.ts"],"mappings":";;;;iBAyFgB,SAAA,CAAU,aAAA,EAAe,YAAA;AAAA,cAY5B,MAAA;EAQZ,WAAA;EAAA,SAAA;AAAA;AAAA,cAEY,OAAA;EAYZ,KAAA;EAAA,WAAA;AAAA;AAAA,cAEY,QAAA;SACJ,cAAA;cAIW,cAAA,GAAiB,OAAA;;;iBAgDrB,QAAA,CAAA"}
+{"version":3,"file":"api.d.mts","names":[],"sources":["../../src/tracking/api.ts"],"mappings":";;;;;;;UAaiB,qBAAA;EACf,MAAA,GAAS,aAAA;EACT,OAAA,UAAiB,UAAA,CAAW,KAAA;EAC5B,GAAA,GAAM,WAAA;EACN,MAAA,EAAQ,YAAA;AAAA;AAAA,cAGG,cAAA;EAAA,iBACM,MAAA;EAAA,iBACA,OAAA;EAAA,iBACA,MAAA;EAAA,iBACA,GAAA;EAAA,QAET,GAAA;EAAA,QACA,eAAA;EAAA,QACA,mBAAA;EAAA,QACA,eAAA;EAAA,QACA,aAAA;EAAA,QACA,UAAA;cAEI,IAAA,EAAM,qBAAA;EAOlB,KAAA,CAAA;EAaA,SAAA,CAAA,GAAa,SAAA;EAQb,QAAA,CAAA;EAIA,WAAA,CAAA;EAIA,SAAA,CAAA;EAjDyB;;;;;EA0DzB,OAAA,CAAA,GAAW,MAAA;EAiBX,WAAA,CAAA,GAAe,cAAA;EAIT,QAAA,CAAS,MAAA,EAAQ,cAAA,GAAiB,OAAA;EAiDxC,aAAA,CAAA;EAKA,OAAA,CAAA;EAAA,QAQQ,cAAA;EAAA,QAOA,YAAA;EAAA,QAcA,WAAA;EAAA,QA0BM,QAAA;AAAA"}

package/dist/tracking/api.mjs

@@ -1,107 +1,86 @@
 import { createLogger } from "../util/log.mjs";
-import { getDeviceId, getFpHash, initDevice, whenDeviceReady, whenFingerprintReady } from "./device.mjs";
-import { buildHeaders } from "../transport/http.mjs";
-import { detectCountryCode, resetGeo } from "./geo.mjs";
+import { DeviceManager } from "./device.mjs";
+import { GeoDetector } from "./geo.mjs";
 import { SessionManager } from "./session.mjs";
 //#region src/tracking/api.ts
 const log = createLogger("tracking");
-let mgr = null;
-let target = null;
-let currentIdentity = null;
-let identifiedSessionId = null;
-let syncedSessionId = null;
-let syncAttemptMs = 0;
-let generation = 0;
 const SYNC_COOLDOWN_MS = 5e3;
-function syncSession(sessionId, deviceId, fpHash) {
-	if (!target) return;
-	syncAttemptMs = Date.now();
-	syncedSessionId = sessionId;
-	fetch(target.url, {
-		method: "POST",
-		headers: buildHeaders(target.headers),
-		body: JSON.stringify({
-			sessionId,
-			deviceId,
-			fpHash
-		}),
-		keepalive: true,
-		signal: AbortSignal.timeout(1e4)
-	}).then((res) => {
-		if (!res.ok) syncedSessionId = null;
-	}).catch(() => {
-		syncedSessionId = null;
-		log.warn("session sync failed, will retry");
-	});
-}
-function ensureSynced(sessionId) {
-	if (syncedSessionId === sessionId) return;
-	if (Date.now() - syncAttemptMs < SYNC_COOLDOWN_MS) return;
-	syncSession(sessionId, getDeviceId(), getFpHash());
-}
-async function onRotate(sessionId) {
+var SessionTracker = class {
+	target;
+	fetcher;
+	device;
+	geo;
+	mgr = null;
+	currentIdentity = null;
+	identifiedSessionId = null;
 	syncedSessionId = null;
-	syncAttemptMs = Date.now();
-	if (!target) return;
-	const gen = generation;
-	const [deviceId, fpHash] = await Promise.all([whenDeviceReady(), whenFingerprintReady()]);
-	if (gen !== generation) return;
-	log.debug("POST session %s (device=%s fp=%s)", sessionId, deviceId ?? "pending", fpHash ?? "none");
-	syncSession(sessionId, deviceId, fpHash);
-}
-function bootstrap(sessionTarget) {
-	target = sessionTarget;
-	initDevice();
-	detectCountryCode();
-	mgr = new SessionManager((id) => {
-		onRotate(id).catch(() => {});
-	});
-}
-const device = {
+	syncAttemptMs = 0;
+	generation = 0;
+	constructor(opts) {
+		this.target = opts.target;
+		this.fetcher = opts.fetcher ?? globalThis.fetch.bind(globalThis);
+		this.device = opts.device ?? new DeviceManager();
+		this.geo = opts.geo ?? new GeoDetector();
+	}
+	start() {
+		this.device.init();
+		this.geo.detect();
+		this.mgr = new SessionManager((id) => {
+			this.onRotate(id).catch(() => {});
+		});
+	}
+	sessionId() {
+		const id = this.mgr?.getSessionId() ?? null;
+		if (id) this.ensureSynced(id);
+		return id;
+	}
+	windowId() {
+		return this.mgr?.getWindowId() ?? null;
+	}
 	getDeviceId() {
-		return getDeviceId();
-	},
+		return this.device.getDeviceId();
+	}
 	getFpHash() {
-		return getFpHash();
+		return this.device.getFpHash();
 	}
-};
-const session = {
-	getId() {
-		const id = mgr?.getSessionId() ?? null;
-		if (id) ensureSynced(id);
-		return id;
-	},
-	getWindowId() {
-		return mgr?.getWindowId() ?? null;
+	/**
+	* Identity headers (session / window / device). Layered onto the
+	* session/identify POSTs alongside the target's static headers
+	* (content-type + auth + force-enable).
+	*/
+	headers() {
+		const h = {};
+		const sid = this.mgr?.getSessionId() ?? null;
+		if (sid) h["x-interfere-session"] = sid;
+		const wid = this.mgr?.getWindowId() ?? null;
+		if (wid) h["x-interfere-window"] = wid;
+		const did = this.device.getDeviceId();
+		if (did) h["x-interfere-device"] = did;
+		return h;
 	}
-};
-const identity = {
-	get() {
-		return currentIdentity;
-	},
-	async set(params) {
-		if (!(mgr && target)) return;
-		const sessionId = mgr.getSessionId();
-		if (identifiedSessionId === sessionId) {
+	getIdentity() {
+		return this.currentIdentity;
+	}
+	async identify(params) {
+		if (!this.mgr) return;
+		const sessionId = this.mgr.getSessionId();
+		if (this.identifiedSessionId === sessionId) {
 			log.debug("skipped, already identified for session %s", sessionId);
 			return;
 		}
-		currentIdentity = params;
-		identifiedSessionId = sessionId;
-		const gen = generation;
-		const [deviceId, fpHash, country] = await Promise.all([
-			whenDeviceReady(),
-			whenFingerprintReady(),
-			detectCountryCode()
-		]);
-		if (gen !== generation || !target) {
-			identifiedSessionId = null;
+		this.currentIdentity = params;
+		this.identifiedSessionId = sessionId;
+		const gen = this.generation;
+		const [fpHash, country] = await Promise.all([this.device.whenFingerprintReady(), this.geo.detect()]);
+		const deviceId = this.device.getDeviceId();
+		if (gen !== this.generation) {
+			this.identifiedSessionId = null;
 			return;
 		}
-		log.info("PUT session %s → user %s", sessionId, params.identifier);
-		fetch(target.url, {
-			method: "PUT",
-			headers: buildHeaders(target.headers),
+		log.info("POST session %s → user %s", sessionId, params.identifier);
+		this.fetcher(`${this.target.url}/identify`, {
+			method: "POST",
+			headers: this.requestHeaders(),
 			body: JSON.stringify({
 				sessionId,
 				deviceId,
@@ -112,23 +91,62 @@ const identity = {
 			keepalive: true,
 			signal: AbortSignal.timeout(1e4)
 		}).catch(() => {
-			identifiedSessionId = null;
+			this.identifiedSessionId = null;
 			log.warn("identify failed for session %s", sessionId);
 		});
-	},
-	clear() {
-		currentIdentity = null;
-		identifiedSessionId = null;
+	}
+	clearIdentity() {
+		this.currentIdentity = null;
+		this.identifiedSessionId = null;
+	}
+	dispose() {
+		this.generation += 1;
+		this.clearIdentity();
+		this.syncedSessionId = null;
+		this.syncAttemptMs = 0;
+		this.mgr = null;
+	}
+	requestHeaders() {
+		return {
+			...Object.fromEntries(this.target.headers.entries()),
+			...this.headers()
+		};
+	}
+	ensureSynced(sessionId) {
+		if (this.syncedSessionId === sessionId) return;
+		if (Date.now() - this.syncAttemptMs < SYNC_COOLDOWN_MS) return;
+		this.syncSession(sessionId, this.device.getDeviceId(), this.device.getFpHash());
+	}
+	syncSession(sessionId, deviceId, fpHash) {
+		this.syncAttemptMs = Date.now();
+		this.syncedSessionId = sessionId;
+		this.fetcher(this.target.url, {
+			method: "POST",
+			headers: this.requestHeaders(),
+			body: JSON.stringify({
+				sessionId,
+				deviceId,
+				fpHash
+			}),
+			keepalive: true,
+			signal: AbortSignal.timeout(1e4)
+		}).then((res) => {
+			if (!res.ok) this.syncedSessionId = null;
+		}).catch(() => {
+			this.syncedSessionId = null;
+			log.warn("session sync failed, will retry");
+		});
+	}
+	async onRotate(sessionId) {
+		this.syncedSessionId = null;
+		this.syncAttemptMs = Date.now();
+		const gen = this.generation;
+		const fpHash = await this.device.whenFingerprintReady();
+		const deviceId = this.device.getDeviceId();
+		if (gen !== this.generation) return;
+		log.debug("POST session %s (device=%s fp=%s)", sessionId, deviceId ?? "pending", fpHash ?? "none");
+		this.syncSession(sessionId, deviceId, fpHash);
 	}
 };
-function teardown() {
-	generation += 1;
-	identity.clear();
-	resetGeo();
-	syncedSessionId = null;
-	syncAttemptMs = 0;
-	mgr = null;
-	target = null;
-}
 //#endregion
-export { bootstrap, device, identity, session, teardown };
+export { SessionTracker };

package/dist/tracking/api.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"api.mjs","names":[],"sources":["../../src/tracking/api.ts"],"sourcesContent":["import type { IdentifyParams } from \"@interfere/types/sdk/identify\";\n\nimport { buildHeaders, type IngestTarget } from \"../transport/http.js\";\nimport { createLogger } from \"../util/log.js\";\nimport {\n  getDeviceId,\n  getFpHash,\n  initDevice,\n  whenDeviceReady,\n  whenFingerprintReady,\n} from \"./device.js\";\nimport { detectCountryCode, resetGeo } from \"./geo.js\";\nimport { SessionManager } from \"./session.js\";\n\nconst log = createLogger(\"tracking\");\n\nlet mgr: SessionManager | null = null;\nlet target: IngestTarget | null = null;\nlet currentIdentity: IdentifyParams | null = null;\nlet identifiedSessionId: string | null = null;\n\nlet syncedSessionId: string | null = null;\nlet syncAttemptMs = 0;\nlet generation = 0;\nconst SYNC_COOLDOWN_MS = 5000;\n\nfunction syncSession(\n  sessionId: string,\n  deviceId: string | null,\n  fpHash: string | null\n): void {\n  if (!target) {\n    return;\n  }\n\n  syncAttemptMs = Date.now();\n  syncedSessionId = sessionId;\n\n  fetch(target.url, {\n    method: \"POST\",\n    headers: buildHeaders(target.headers),\n    body: JSON.stringify({ sessionId, deviceId, fpHash }),\n    keepalive: true,\n    signal: AbortSignal.timeout(10_000),\n  })\n    .then((res) => {\n      if (!res.ok) {\n        syncedSessionId = null;\n      }\n    })\n    .catch(() => {\n      syncedSessionId = null;\n      log.warn(\"session sync failed, will retry\");\n    });\n}\n\nfunction ensureSynced(sessionId: string): void {\n  if (syncedSessionId === sessionId) {\n    return;\n  }\n  if (Date.now() - syncAttemptMs < SYNC_COOLDOWN_MS) {\n    return;\n  }\n  syncSession(sessionId, getDeviceId(), getFpHash());\n}\n\nasync function onRotate(sessionId: string): Promise<void> {\n  syncedSessionId = null;\n  syncAttemptMs = Date.now();\n  if (!target) {\n    return;\n  }\n  const gen = generation;\n  const [deviceId, fpHash] = await Promise.all([\n    whenDeviceReady(),\n    whenFingerprintReady(),\n  ]);\n  if (gen !== generation) {\n    return;\n  }\n  log.debug(\n    \"POST session %s (device=%s fp=%s)\",\n    sessionId,\n    deviceId ?? \"pending\",\n    fpHash ?? \"none\"\n  );\n  syncSession(sessionId, deviceId, fpHash);\n}\n\nexport function bootstrap(sessionTarget: IngestTarget): void {\n  target = sessionTarget;\n  initDevice();\n  detectCountryCode();\n\n  mgr = new SessionManager((id) => {\n    onRotate(id).catch(() => {\n      /* best-effort */\n    });\n  });\n}\n\nexport const device = {\n  getDeviceId(): string | null {\n    return getDeviceId();\n  },\n\n  getFpHash(): string | null {\n    return getFpHash();\n  },\n};\n\nexport const session = {\n  getId(): string | null {\n    const id = mgr?.getSessionId() ?? null;\n    if (id) {\n      ensureSynced(id);\n    }\n    return id;\n  },\n\n  getWindowId(): string | null {\n    return mgr?.getWindowId() ?? null;\n  },\n};\n\nexport const identity = {\n  get(): IdentifyParams | null {\n    return currentIdentity;\n  },\n\n  async set(params: IdentifyParams): Promise<void> {\n    if (!(mgr && target)) {\n      return;\n    }\n    const sessionId = mgr.getSessionId();\n    if (identifiedSessionId === sessionId) {\n      log.debug(\"skipped, already identified for session %s\", sessionId);\n      return;\n    }\n\n    currentIdentity = params;\n    identifiedSessionId = sessionId;\n\n    const gen = generation;\n    const [deviceId, fpHash, country] = await Promise.all([\n      whenDeviceReady(),\n      whenFingerprintReady(),\n      detectCountryCode(),\n    ]);\n    if (gen !== generation || !target) {\n      identifiedSessionId = null;\n      return;\n    }\n    log.info(\"PUT session %s → user %s\", sessionId, params.identifier);\n    fetch(target.url, {\n      method: \"PUT\",\n      headers: buildHeaders(target.headers),\n      body: JSON.stringify({\n        sessionId,\n        deviceId,\n        fpHash,\n        ...params,\n        ...(country && { country }),\n      }),\n      keepalive: true,\n      signal: AbortSignal.timeout(10_000),\n    }).catch(() => {\n      identifiedSessionId = null;\n      log.warn(\"identify failed for session %s\", sessionId);\n    });\n  },\n\n  clear(): void {\n    currentIdentity = null;\n    identifiedSessionId = null;\n  },\n};\n\nexport function teardown(): void {\n  generation += 1;\n  identity.clear();\n  resetGeo();\n  syncedSessionId = null;\n  syncAttemptMs = 0;\n  mgr = null;\n  target = null;\n}\n"],"mappings":"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"}
+{"version":3,"file":"api.mjs","names":[],"sources":["../../src/tracking/api.ts"],"sourcesContent":["import type { SessionId } from \"@interfere/types/data/session\";\nimport type { IdentifyParams } from \"@interfere/types/sdk/identify\";\n\nimport type { IngestTarget } from \"../internal/config.js\";\nimport { createLogger } from \"../util/log.js\";\nimport { DeviceManager } from \"./device.js\";\nimport { GeoDetector } from \"./geo.js\";\nimport { SessionManager } from \"./session.js\";\n\nconst log = createLogger(\"tracking\");\n\nconst SYNC_COOLDOWN_MS = 5000;\n\nexport interface SessionTrackerOptions {\n  device?: DeviceManager;\n  fetcher?: typeof globalThis.fetch;\n  geo?: GeoDetector;\n  target: IngestTarget;\n}\n\nexport class SessionTracker {\n  private readonly target: IngestTarget;\n  private readonly fetcher: typeof globalThis.fetch;\n  private readonly device: DeviceManager;\n  private readonly geo: GeoDetector;\n\n  private mgr: SessionManager | null = null;\n  private currentIdentity: IdentifyParams | null = null;\n  private identifiedSessionId: string | null = null;\n  private syncedSessionId: string | null = null;\n  private syncAttemptMs = 0;\n  private generation = 0;\n\n  constructor(opts: SessionTrackerOptions) {\n    this.target = opts.target;\n    this.fetcher = opts.fetcher ?? globalThis.fetch.bind(globalThis);\n    this.device = opts.device ?? new DeviceManager();\n    this.geo = opts.geo ?? new GeoDetector();\n  }\n\n  start(): void {\n    this.device.init();\n    // Best-effort warm-up; `GeoDetector.detect()` swallows its own errors and\n    // resolves to `null`, so we don't need to attach a `.catch`. If `identify`\n    // runs before the geo result lands, the country field is just omitted.\n    this.geo.detect();\n    this.mgr = new SessionManager((id) => {\n      this.onRotate(id).catch(() => {\n        /* best-effort */\n      });\n    });\n  }\n\n  sessionId(): SessionId | null {\n    const id = this.mgr?.getSessionId() ?? null;\n    if (id) {\n      this.ensureSynced(id);\n    }\n    return id;\n  }\n\n  windowId(): string | null {\n    return this.mgr?.getWindowId() ?? null;\n  }\n\n  getDeviceId(): string | null {\n    return this.device.getDeviceId();\n  }\n\n  getFpHash(): string | null {\n    return this.device.getFpHash();\n  }\n\n  /**\n   * Identity headers (session / window / device). Layered onto the\n   * session/identify POSTs alongside the target's static headers\n   * (content-type + auth + force-enable).\n   */\n  headers(): Record<string, string> {\n    const h: Record<string, string> = {};\n    const sid = this.mgr?.getSessionId() ?? null;\n    if (sid) {\n      h[\"x-interfere-session\"] = sid;\n    }\n    const wid = this.mgr?.getWindowId() ?? null;\n    if (wid) {\n      h[\"x-interfere-window\"] = wid;\n    }\n    const did = this.device.getDeviceId();\n    if (did) {\n      h[\"x-interfere-device\"] = did;\n    }\n    return h;\n  }\n\n  getIdentity(): IdentifyParams | null {\n    return this.currentIdentity;\n  }\n\n  async identify(params: IdentifyParams): Promise<void> {\n    if (!this.mgr) {\n      return;\n    }\n    const sessionId = this.mgr.getSessionId();\n    if (this.identifiedSessionId === sessionId) {\n      log.debug(\"skipped, already identified for session %s\", sessionId);\n      return;\n    }\n\n    this.currentIdentity = params;\n    this.identifiedSessionId = sessionId;\n\n    const gen = this.generation;\n    const [fpHash, country] = await Promise.all([\n      this.device.whenFingerprintReady(),\n      this.geo.detect(),\n    ]);\n    const deviceId = this.device.getDeviceId();\n    if (gen !== this.generation) {\n      this.identifiedSessionId = null;\n      return;\n    }\n    // Append the path to the existing target. `new URL(\"/identify\", base)`\n    // is wrong on both axes: in proxy mode `target.url` is relative\n    // (`/api/interfere/v1/session`) so the URL constructor throws\n    // synchronously — `currentIdentity` is set but no fetch fires; in\n    // pub-token mode the path-absolute \"/identify\" replaces the target's\n    // path, hitting `/identify` at the origin instead of the collector's\n    // `/v1/session/identify` route. Plain string concatenation gets both.\n    log.info(\"POST session %s → user %s\", sessionId, params.identifier);\n    this.fetcher(`${this.target.url}/identify`, {\n      method: \"POST\",\n      headers: this.requestHeaders(),\n      body: JSON.stringify({\n        sessionId,\n        deviceId,\n        fpHash,\n        ...params,\n        ...(country && { country }),\n      }),\n      keepalive: true,\n      signal: AbortSignal.timeout(10_000),\n    }).catch(() => {\n      this.identifiedSessionId = null;\n      log.warn(\"identify failed for session %s\", sessionId);\n    });\n  }\n\n  clearIdentity(): void {\n    this.currentIdentity = null;\n    this.identifiedSessionId = null;\n  }\n\n  dispose(): void {\n    this.generation += 1;\n    this.clearIdentity();\n    this.syncedSessionId = null;\n    this.syncAttemptMs = 0;\n    this.mgr = null;\n  }\n\n  private requestHeaders(): Record<string, string> {\n    return {\n      ...Object.fromEntries(this.target.headers.entries()),\n      ...this.headers(),\n    };\n  }\n\n  private ensureSynced(sessionId: string): void {\n    if (this.syncedSessionId === sessionId) {\n      return;\n    }\n    if (Date.now() - this.syncAttemptMs < SYNC_COOLDOWN_MS) {\n      return;\n    }\n    this.syncSession(\n      sessionId,\n      this.device.getDeviceId(),\n      this.device.getFpHash()\n    );\n  }\n\n  private syncSession(\n    sessionId: string,\n    deviceId: string | null,\n    fpHash: string | null\n  ): void {\n    this.syncAttemptMs = Date.now();\n    this.syncedSessionId = sessionId;\n\n    this.fetcher(this.target.url, {\n      method: \"POST\",\n      headers: this.requestHeaders(),\n      body: JSON.stringify({ sessionId, deviceId, fpHash }),\n      keepalive: true,\n      signal: AbortSignal.timeout(10_000),\n    })\n      .then((res) => {\n        if (!res.ok) {\n          this.syncedSessionId = null;\n        }\n      })\n      .catch(() => {\n        this.syncedSessionId = null;\n        log.warn(\"session sync failed, will retry\");\n      });\n  }\n\n  private async onRotate(sessionId: string): Promise<void> {\n    this.syncedSessionId = null;\n    this.syncAttemptMs = Date.now();\n    const gen = this.generation;\n    const fpHash = await this.device.whenFingerprintReady();\n    const deviceId = this.device.getDeviceId();\n    if (gen !== this.generation) {\n      return;\n    }\n    log.debug(\n      \"POST session %s (device=%s fp=%s)\",\n      sessionId,\n      deviceId ?? \"pending\",\n      fpHash ?? \"none\"\n    );\n    this.syncSession(sessionId, deviceId, fpHash);\n  }\n}\n"],"mappings":"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"}

package/dist/tracking/device.d.mts

@@ -1,9 +1,32 @@
 //#region src/tracking/device.d.ts
-declare function initDevice(): void;
-declare function getDeviceId(): string | null;
-declare function getFpHash(): string | null;
-declare function whenDeviceReady(): Promise<string | null>;
-declare function whenFingerprintReady(): Promise<string | null>;
-declare function resetDevice(): void;
+/**
+ * Producer of an opaque, stable per-browser fingerprint hash. The default
+ * dynamic-imports the FingerprintJS OSS library and self-defers via
+ * `requestIdleCallback` so the ~1.5s of synchronous font / canvas / WebGL
+ * probing the library performs on a cold load doesn't land on the
+ * hydration tick. Tests inject a fixed-value provider that resolves
+ * immediately — they pay nothing for the production deferral.
+ */
+type FingerprintProvider = () => Promise<string | null>;
+/**
+ * Resolves on the next browser idle frame, capped at 5s. Falls back to
+ * `setTimeout(0)` (next macrotask) on hosts without
+ * `requestIdleCallback`. Exported only for the unit test that pins the
+ * "default provider gates fingerprint work via RIC" contract — not part
+ * of the package's public surface.
+ */
+declare function whenIdle(): Promise<void>;
+declare class DeviceManager {
+  private deviceId;
+  private fpHash;
+  private fpPending;
+  private readonly fingerprintProvider;
+  constructor(fingerprintProvider?: FingerprintProvider);
+  init(): void;
+  private startFingerprint;
+  getDeviceId(): string | null;
+  getFpHash(): string | null;
+  whenFingerprintReady(): Promise<string | null>;
+}
 //#endregion
-export { getDeviceId, getFpHash, initDevice, resetDevice, whenDeviceReady, whenFingerprintReady };
+export { DeviceManager, FingerprintProvider, whenIdle };

package/dist/tracking/device.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"device.d.mts","names":[],"sources":["../../src/tracking/device.ts"],"mappings":";iBA+CgB,UAAA,CAAA;AAAA,iBAiDA,WAAA,CAAA;AAAA,iBAIA,SAAA,CAAA;AAAA,iBAIA,eAAA,CAAA,GAAmB,OAAA;AAAA,iBAOnB,oBAAA,CAAA,GAAwB,OAAA;AAAA,iBAOxB,WAAA,CAAA"}
+{"version":3,"file":"device.d.mts","names":[],"sources":["../../src/tracking/device.ts"],"mappings":";;AAgBA;;;;;AAWA;;KAXY,mBAAA,SAA4B,OAAA;;;AAkFxC;;;;;iBAvEgB,QAAA,CAAA,GAAY,OAAA;AAAA,cAuEf,aAAA;EAAA,QACH,QAAA;EAAA,QACA,MAAA;EAAA,QACA,SAAA;EAAA,iBACS,mBAAA;cAEL,mBAAA,GAAsB,mBAAA;EAKlC,IAAA,CAAA;EAAA,QAkCQ,gBAAA;EAkBR,WAAA,CAAA;EAIA,SAAA,CAAA;EAIA,oBAAA,CAAA,GAAwB,OAAA;AAAA"}

package/dist/tracking/device.mjs

@@ -4,9 +4,37 @@ const log = createLogger("device");
 const LS_KEY = "interfere:device_id";
 const COOKIE_NAME = "interfere_did";
 const COOKIE_MAX_AGE_DAYS = 400;
-let deviceId = null;
-let fpHash = null;
-let fpPending = null;
+const FP_IDLE_TIMEOUT_MS = 5e3;
+/**
+* Resolves on the next browser idle frame, capped at 5s. Falls back to
+* `setTimeout(0)` (next macrotask) on hosts without
+* `requestIdleCallback`. Exported only for the unit test that pins the
+* "default provider gates fingerprint work via RIC" contract — not part
+* of the package's public surface.
+*/
+function whenIdle() {
+	return new Promise((resolve) => {
+		if (typeof globalThis.requestIdleCallback === "function") {
+			globalThis.requestIdleCallback(() => resolve(), { timeout: FP_IDLE_TIMEOUT_MS });
+			return;
+		}
+		setTimeout(resolve, 0);
+	});
+}
+const defaultFingerprintProvider = async () => {
+	await whenIdle();
+	try {
+		const result = await (await (await import("@fingerprintjs/fingerprintjs")).load()).get();
+		if (!result.visitorId) {
+			log.error("Fingerprinting returned an empty visitor id; visitor identity will be cookie-only");
+			return null;
+		}
+		return result.visitorId;
+	} catch (err) {
+		log.error("fingerprint init failed; visitor identity will be cookie-only", err);
+		return null;
+	}
+};
 function tryLocalStorage() {
 	try {
 		const s = globalThis.localStorage;
@@ -31,50 +59,46 @@ function setCookie(name, value) {
 function generateId() {
 	return crypto.randomUUID();
 }
-function initDevice() {
-	if (deviceId) return;
-	const ls = tryLocalStorage();
-	const fromLs = ls?.getItem(LS_KEY) ?? null;
-	const fromCookie = getCookie(COOKIE_NAME);
-	deviceId = fromLs ?? fromCookie ?? generateId();
-	if (!fromLs && ls) ls.setItem(LS_KEY, deviceId);
-	if (!fromCookie) setCookie(COOKIE_NAME, deviceId);
-	if (fromLs && !fromCookie) setCookie(COOKIE_NAME, deviceId);
-	if (fromCookie && !fromLs && ls) ls.setItem(LS_KEY, deviceId);
-	log.debug("device %s (ls=%s cookie=%s)", deviceId, !!fromLs, !!fromCookie);
-	initFpHash();
-}
-function initFpHash() {
-	if (fpHash || fpPending) return;
-	fpPending = (async () => {
-		try {
-			fpHash = (await (await (await import("@fingerprintjs/fingerprintjs")).load()).get()).visitorId;
-			log.debug("fpHash %s", fpHash);
-			return fpHash;
-		} catch {
-			log.warn("fp hash failed");
-			return null;
-		}
-	})();
-}
-function getDeviceId() {
-	return deviceId;
-}
-function getFpHash() {
-	return fpHash;
-}
-function whenDeviceReady() {
-	if (deviceId) return Promise.resolve(deviceId);
-	return Promise.resolve(null);
-}
-function whenFingerprintReady() {
-	if (fpHash) return Promise.resolve(fpHash);
-	return fpPending ?? Promise.resolve(null);
-}
-function resetDevice() {
+var DeviceManager = class {
 	deviceId = null;
 	fpHash = null;
 	fpPending = null;
-}
+	fingerprintProvider;
+	constructor(fingerprintProvider) {
+		this.fingerprintProvider = fingerprintProvider ?? defaultFingerprintProvider;
+	}
+	init() {
+		if (this.deviceId) return;
+		const ls = tryLocalStorage();
+		const fromLs = ls?.getItem(LS_KEY) ?? null;
+		const fromCookie = getCookie(COOKIE_NAME);
+		this.deviceId = fromLs ?? fromCookie ?? generateId();
+		if (!fromLs && ls) ls.setItem(LS_KEY, this.deviceId);
+		if (!fromCookie) setCookie(COOKIE_NAME, this.deviceId);
+		if (fromLs && !fromCookie) setCookie(COOKIE_NAME, this.deviceId);
+		if (fromCookie && !fromLs && ls) ls.setItem(LS_KEY, this.deviceId);
+		log.debug("device %s (ls=%s cookie=%s)", this.deviceId, !!fromLs, !!fromCookie);
+		this.startFingerprint();
+	}
+	startFingerprint() {
+		if (this.fpHash || this.fpPending) return;
+		this.fpPending = (async () => {
+			const hash = await this.fingerprintProvider();
+			this.fpHash = hash;
+			if (hash) log.debug("fpHash %s", hash);
+			return hash;
+		})();
+	}
+	getDeviceId() {
+		return this.deviceId;
+	}
+	getFpHash() {
+		return this.fpHash;
+	}
+	whenFingerprintReady() {
+		if (this.fpHash) return Promise.resolve(this.fpHash);
+		return this.fpPending ?? Promise.resolve(null);
+	}
+};
 //#endregion
-export { getDeviceId, getFpHash, initDevice, resetDevice, whenDeviceReady, whenFingerprintReady };
+export { DeviceManager, whenIdle };

package/dist/tracking/device.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"device.mjs","names":[],"sources":["../../src/tracking/device.ts"],"sourcesContent":["import { createLogger } from \"../util/log.js\";\n\nconst log = createLogger(\"device\");\n\nconst LS_KEY = \"interfere:device_id\";\nconst COOKIE_NAME = \"interfere_did\";\nconst COOKIE_MAX_AGE_DAYS = 400;\n\nlet deviceId: string | null = null;\nlet fpHash: string | null = null;\nlet fpPending: Promise<string | null> | null = null;\n\nfunction tryLocalStorage(): Storage | null {\n  try {\n    const s = globalThis.localStorage;\n    const key = \"__interfere_device_probe__\";\n    s.setItem(key, \"1\");\n    s.removeItem(key);\n    return s;\n  } catch {\n    return null;\n  }\n}\n\nfunction getCookie(name: string): string | null {\n  if (typeof document === \"undefined\") {\n    return null;\n  }\n  const match = document.cookie\n    .split(\"; \")\n    .find((c) => c.startsWith(`${name}=`));\n  return match ? decodeURIComponent(match.split(\"=\")[1] ?? \"\") : null;\n}\n\nfunction setCookie(name: string, value: string): void {\n  if (typeof document === \"undefined\") {\n    return;\n  }\n  const maxAge = COOKIE_MAX_AGE_DAYS * 24 * 60 * 60;\n  // biome-ignore lint/suspicious/noDocumentCookie: Cookie Store API is async and not universally supported; synchronous access is required here\n  document.cookie = `${name}=${encodeURIComponent(value)};path=/;max-age=${maxAge};SameSite=Lax`;\n}\n\nfunction generateId(): string {\n  return crypto.randomUUID();\n}\n\nexport function initDevice(): void {\n  if (deviceId) {\n    return;\n  }\n\n  const ls = tryLocalStorage();\n  const fromLs = ls?.getItem(LS_KEY) ?? null;\n  const fromCookie = getCookie(COOKIE_NAME);\n\n  deviceId = fromLs ?? fromCookie ?? generateId();\n\n  if (!fromLs && ls) {\n    ls.setItem(LS_KEY, deviceId);\n  }\n  if (!fromCookie) {\n    setCookie(COOKIE_NAME, deviceId);\n  }\n  if (fromLs && !fromCookie) {\n    setCookie(COOKIE_NAME, deviceId);\n  }\n  if (fromCookie && !fromLs && ls) {\n    ls.setItem(LS_KEY, deviceId);\n  }\n\n  log.debug(\"device %s (ls=%s cookie=%s)\", deviceId, !!fromLs, !!fromCookie);\n\n  initFpHash();\n}\n\nfunction initFpHash(): void {\n  if (fpHash || fpPending) {\n    return;\n  }\n\n  fpPending = (async () => {\n    try {\n      const FingerprintJS = await import(\"@fingerprintjs/fingerprintjs\");\n      const fp = await FingerprintJS.load();\n      const result = await fp.get();\n      fpHash = result.visitorId;\n      log.debug(\"fpHash %s\", fpHash);\n      return fpHash;\n    } catch {\n      log.warn(\"fp hash failed\");\n      return null;\n    }\n  })();\n}\n\nexport function getDeviceId(): string | null {\n  return deviceId;\n}\n\nexport function getFpHash(): string | null {\n  return fpHash;\n}\n\nexport function whenDeviceReady(): Promise<string | null> {\n  if (deviceId) {\n    return Promise.resolve(deviceId);\n  }\n  return Promise.resolve(null);\n}\n\nexport function whenFingerprintReady(): Promise<string | null> {\n  if (fpHash) {\n    return Promise.resolve(fpHash);\n  }\n  return fpPending ?? Promise.resolve(null);\n}\n\nexport function resetDevice(): void {\n  deviceId = null;\n  fpHash = null;\n  fpPending = null;\n}\n"],"mappings":";;AAEA,MAAM,MAAM,aAAa,SAAS;AAElC,MAAM,SAAS;AACf,MAAM,cAAc;AACpB,MAAM,sBAAsB;AAE5B,IAAI,WAA0B;AAC9B,IAAI,SAAwB;AAC5B,IAAI,YAA2C;AAE/C,SAAS,kBAAkC;AACzC,KAAI;EACF,MAAM,IAAI,WAAW;EACrB,MAAM,MAAM;AACZ,IAAE,QAAQ,KAAK,IAAI;AACnB,IAAE,WAAW,IAAI;AACjB,SAAO;SACD;AACN,SAAO;;;AAIX,SAAS,UAAU,MAA6B;AAC9C,KAAI,OAAO,aAAa,YACtB,QAAO;CAET,MAAM,QAAQ,SAAS,OACpB,MAAM,KAAK,CACX,MAAM,MAAM,EAAE,WAAW,GAAG,KAAK,GAAG,CAAC;AACxC,QAAO,QAAQ,mBAAmB,MAAM,MAAM,IAAI,CAAC,MAAM,GAAG,GAAG;;AAGjE,SAAS,UAAU,MAAc,OAAqB;AACpD,KAAI,OAAO,aAAa,YACtB;CAEF,MAAM,SAAS,sBAAsB,KAAK,KAAK;AAE/C,UAAS,SAAS,GAAG,KAAK,GAAG,mBAAmB,MAAM,CAAC,kBAAkB,OAAO;;AAGlF,SAAS,aAAqB;AAC5B,QAAO,OAAO,YAAY;;AAG5B,SAAgB,aAAmB;AACjC,KAAI,SACF;CAGF,MAAM,KAAK,iBAAiB;CAC5B,MAAM,SAAS,IAAI,QAAQ,OAAO,IAAI;CACtC,MAAM,aAAa,UAAU,YAAY;AAEzC,YAAW,UAAU,cAAc,YAAY;AAE/C,KAAI,CAAC,UAAU,GACb,IAAG,QAAQ,QAAQ,SAAS;AAE9B,KAAI,CAAC,WACH,WAAU,aAAa,SAAS;AAElC,KAAI,UAAU,CAAC,WACb,WAAU,aAAa,SAAS;AAElC,KAAI,cAAc,CAAC,UAAU,GAC3B,IAAG,QAAQ,QAAQ,SAAS;AAG9B,KAAI,MAAM,+BAA+B,UAAU,CAAC,CAAC,QAAQ,CAAC,CAAC,WAAW;AAE1E,aAAY;;AAGd,SAAS,aAAmB;AAC1B,KAAI,UAAU,UACZ;AAGF,cAAa,YAAY;AACvB,MAAI;AAIF,aAAS,OADY,OADJ,MADW,OAAO,iCACJ,MAAM,EACb,KAAK,EACb;AAChB,OAAI,MAAM,aAAa,OAAO;AAC9B,UAAO;UACD;AACN,OAAI,KAAK,iBAAiB;AAC1B,UAAO;;KAEP;;AAGN,SAAgB,cAA6B;AAC3C,QAAO;;AAGT,SAAgB,YAA2B;AACzC,QAAO;;AAGT,SAAgB,kBAA0C;AACxD,KAAI,SACF,QAAO,QAAQ,QAAQ,SAAS;AAElC,QAAO,QAAQ,QAAQ,KAAK;;AAG9B,SAAgB,uBAA+C;AAC7D,KAAI,OACF,QAAO,QAAQ,QAAQ,OAAO;AAEhC,QAAO,aAAa,QAAQ,QAAQ,KAAK;;AAG3C,SAAgB,cAAoB;AAClC,YAAW;AACX,UAAS;AACT,aAAY"}
+{"version":3,"file":"device.mjs","names":[],"sources":["../../src/tracking/device.ts"],"sourcesContent":["import { createLogger } from \"../util/log.js\";\n\nconst log = createLogger(\"device\");\n\nconst LS_KEY = \"interfere:device_id\";\nconst COOKIE_NAME = \"interfere_did\";\nconst COOKIE_MAX_AGE_DAYS = 400;\n\n/**\n * Producer of an opaque, stable per-browser fingerprint hash. The default\n * dynamic-imports the FingerprintJS OSS library and self-defers via\n * `requestIdleCallback` so the ~1.5s of synchronous font / canvas / WebGL\n * probing the library performs on a cold load doesn't land on the\n * hydration tick. Tests inject a fixed-value provider that resolves\n * immediately — they pay nothing for the production deferral.\n */\nexport type FingerprintProvider = () => Promise<string | null>;\n\nconst FP_IDLE_TIMEOUT_MS = 5000;\n\n/**\n * Resolves on the next browser idle frame, capped at 5s. Falls back to\n * `setTimeout(0)` (next macrotask) on hosts without\n * `requestIdleCallback`. Exported only for the unit test that pins the\n * \"default provider gates fingerprint work via RIC\" contract — not part\n * of the package's public surface.\n */\nexport function whenIdle(): Promise<void> {\n  return new Promise((resolve) => {\n    if (typeof globalThis.requestIdleCallback === \"function\") {\n      globalThis.requestIdleCallback(() => resolve(), {\n        timeout: FP_IDLE_TIMEOUT_MS,\n      });\n      return;\n    }\n    setTimeout(resolve, 0);\n  });\n}\n\nconst defaultFingerprintProvider: FingerprintProvider = async () => {\n  await whenIdle();\n  try {\n    const FingerprintJS = await import(\"@fingerprintjs/fingerprintjs\");\n    const fp = await FingerprintJS.load();\n    const result = await fp.get();\n    if (!result.visitorId) {\n      log.error(\n        \"Fingerprinting returned an empty visitor id; visitor identity will be cookie-only\"\n      );\n\n      return null;\n    }\n    return result.visitorId;\n  } catch (err) {\n    log.error(\n      \"fingerprint init failed; visitor identity will be cookie-only\",\n      err\n    );\n\n    return null;\n  }\n};\n\nfunction tryLocalStorage(): Storage | null {\n  try {\n    const s = globalThis.localStorage;\n    const key = \"__interfere_device_probe__\";\n    s.setItem(key, \"1\");\n    s.removeItem(key);\n    return s;\n  } catch {\n    return null;\n  }\n}\n\nfunction getCookie(name: string): string | null {\n  if (typeof document === \"undefined\") {\n    return null;\n  }\n  const match = document.cookie\n    .split(\"; \")\n    .find((c) => c.startsWith(`${name}=`));\n  return match ? decodeURIComponent(match.split(\"=\")[1] ?? \"\") : null;\n}\n\nfunction setCookie(name: string, value: string): void {\n  if (typeof document === \"undefined\") {\n    return;\n  }\n  const maxAge = COOKIE_MAX_AGE_DAYS * 24 * 60 * 60;\n  // biome-ignore lint/suspicious/noDocumentCookie: Cookie Store API is async and not universally supported; synchronous access is required here\n  document.cookie = `${name}=${encodeURIComponent(value)};path=/;max-age=${maxAge};SameSite=Lax`;\n}\n\nfunction generateId(): string {\n  return crypto.randomUUID();\n}\n\nexport class DeviceManager {\n  private deviceId: string | null = null;\n  private fpHash: string | null = null;\n  private fpPending: Promise<string | null> | null = null;\n  private readonly fingerprintProvider: FingerprintProvider;\n\n  constructor(fingerprintProvider?: FingerprintProvider) {\n    this.fingerprintProvider =\n      fingerprintProvider ?? defaultFingerprintProvider;\n  }\n\n  init(): void {\n    if (this.deviceId) {\n      return;\n    }\n\n    const ls = tryLocalStorage();\n    const fromLs = ls?.getItem(LS_KEY) ?? null;\n    const fromCookie = getCookie(COOKIE_NAME);\n\n    this.deviceId = fromLs ?? fromCookie ?? generateId();\n\n    if (!fromLs && ls) {\n      ls.setItem(LS_KEY, this.deviceId);\n    }\n    if (!fromCookie) {\n      setCookie(COOKIE_NAME, this.deviceId);\n    }\n    if (fromLs && !fromCookie) {\n      setCookie(COOKIE_NAME, this.deviceId);\n    }\n    if (fromCookie && !fromLs && ls) {\n      ls.setItem(LS_KEY, this.deviceId);\n    }\n\n    log.debug(\n      \"device %s (ls=%s cookie=%s)\",\n      this.deviceId,\n      !!fromLs,\n      !!fromCookie\n    );\n\n    this.startFingerprint();\n  }\n\n  private startFingerprint(): void {\n    if (this.fpHash || this.fpPending) {\n      return;\n    }\n\n    this.fpPending = (async () => {\n      const hash = await this.fingerprintProvider();\n      this.fpHash = hash;\n      if (hash) {\n        log.debug(\"fpHash %s\", hash);\n      }\n      // No log on null — the provider is responsible for surfacing its own\n      // failure mode (the default provider logs at error level; custom\n      // providers can choose). Logging here too would double-count.\n      return hash;\n    })();\n  }\n\n  getDeviceId(): string | null {\n    return this.deviceId;\n  }\n\n  getFpHash(): string | null {\n    return this.fpHash;\n  }\n\n  whenFingerprintReady(): Promise<string | null> {\n    if (this.fpHash) {\n      return Promise.resolve(this.fpHash);\n    }\n    return this.fpPending ?? Promise.resolve(null);\n  }\n}\n"],"mappings":";;AAEA,MAAM,MAAM,aAAa,SAAS;AAElC,MAAM,SAAS;AACf,MAAM,cAAc;AACpB,MAAM,sBAAsB;AAY5B,MAAM,qBAAqB;;;;;;;;AAS3B,SAAgB,WAA0B;CACxC,OAAO,IAAI,SAAS,YAAY;EAC9B,IAAI,OAAO,WAAW,wBAAwB,YAAY;GACxD,WAAW,0BAA0B,SAAS,EAAE,EAC9C,SAAS,oBACV,CAAC;GACF;;EAEF,WAAW,SAAS,EAAE;GACtB;;AAGJ,MAAM,6BAAkD,YAAY;CAClE,MAAM,UAAU;CAChB,IAAI;EAGF,MAAM,SAAS,OAAM,OADJ,MADW,OAAO,iCACJ,MAAM,EACb,KAAK;EAC7B,IAAI,CAAC,OAAO,WAAW;GACrB,IAAI,MACF,oFACD;GAED,OAAO;;EAET,OAAO,OAAO;UACP,KAAK;EACZ,IAAI,MACF,iEACA,IACD;EAED,OAAO;;;AAIX,SAAS,kBAAkC;CACzC,IAAI;EACF,MAAM,IAAI,WAAW;EACrB,MAAM,MAAM;EACZ,EAAE,QAAQ,KAAK,IAAI;EACnB,EAAE,WAAW,IAAI;EACjB,OAAO;SACD;EACN,OAAO;;;AAIX,SAAS,UAAU,MAA6B;CAC9C,IAAI,OAAO,aAAa,aACtB,OAAO;CAET,MAAM,QAAQ,SAAS,OACpB,MAAM,KAAK,CACX,MAAM,MAAM,EAAE,WAAW,GAAG,KAAK,GAAG,CAAC;CACxC,OAAO,QAAQ,mBAAmB,MAAM,MAAM,IAAI,CAAC,MAAM,GAAG,GAAG;;AAGjE,SAAS,UAAU,MAAc,OAAqB;CACpD,IAAI,OAAO,aAAa,aACtB;CAEF,MAAM,SAAS,sBAAsB,KAAK,KAAK;CAE/C,SAAS,SAAS,GAAG,KAAK,GAAG,mBAAmB,MAAM,CAAC,kBAAkB,OAAO;;AAGlF,SAAS,aAAqB;CAC5B,OAAO,OAAO,YAAY;;AAG5B,IAAa,gBAAb,MAA2B;CACzB,WAAkC;CAClC,SAAgC;CAChC,YAAmD;CACnD;CAEA,YAAY,qBAA2C;EACrD,KAAK,sBACH,uBAAuB;;CAG3B,OAAa;EACX,IAAI,KAAK,UACP;EAGF,MAAM,KAAK,iBAAiB;EAC5B,MAAM,SAAS,IAAI,QAAQ,OAAO,IAAI;EACtC,MAAM,aAAa,UAAU,YAAY;EAEzC,KAAK,WAAW,UAAU,cAAc,YAAY;EAEpD,IAAI,CAAC,UAAU,IACb,GAAG,QAAQ,QAAQ,KAAK,SAAS;EAEnC,IAAI,CAAC,YACH,UAAU,aAAa,KAAK,SAAS;EAEvC,IAAI,UAAU,CAAC,YACb,UAAU,aAAa,KAAK,SAAS;EAEvC,IAAI,cAAc,CAAC,UAAU,IAC3B,GAAG,QAAQ,QAAQ,KAAK,SAAS;EAGnC,IAAI,MACF,+BACA,KAAK,UACL,CAAC,CAAC,QACF,CAAC,CAAC,WACH;EAED,KAAK,kBAAkB;;CAGzB,mBAAiC;EAC/B,IAAI,KAAK,UAAU,KAAK,WACtB;EAGF,KAAK,aAAa,YAAY;GAC5B,MAAM,OAAO,MAAM,KAAK,qBAAqB;GAC7C,KAAK,SAAS;GACd,IAAI,MACF,IAAI,MAAM,aAAa,KAAK;GAK9B,OAAO;MACL;;CAGN,cAA6B;EAC3B,OAAO,KAAK;;CAGd,YAA2B;EACzB,OAAO,KAAK;;CAGd,uBAA+C;EAC7C,IAAI,KAAK,QACP,OAAO,QAAQ,QAAQ,KAAK,OAAO;EAErC,OAAO,KAAK,aAAa,QAAQ,QAAQ,KAAK"}

package/dist/tracking/geo.d.mts

@@ -1,5 +1,13 @@
 //#region src/tracking/geo.d.ts
-declare function detectCountryCode(): Promise<string | null>;
-declare function resetGeo(): void;
+declare class GeoDetector {
+  private cached;
+  private pending;
+  private failed;
+  private readonly fetcher;
+  constructor(fetcher?: typeof globalThis.fetch);
+  detect(): Promise<string | null>;
+  getCountry(): string | null;
+  private fetchCountryCode;
+}
 //#endregion
-export { detectCountryCode, resetGeo };
+export { GeoDetector };

package/dist/tracking/geo.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"geo.d.mts","names":[],"sources":["../../src/tracking/geo.ts"],"mappings":";iBAwCgB,iBAAA,CAAA,GAAqB,OAAA;AAAA,iBAuBrB,QAAA,CAAA"}
+{"version":3,"file":"geo.d.mts","names":[],"sources":["../../src/tracking/geo.ts"],"mappings":";cAea,WAAA;EAAA,QACH,MAAA;EAAA,QACA,OAAA;EAAA,QACA,MAAA;EAAA,iBACS,OAAA;cAEL,OAAA,UAAiB,UAAA,CAAW,KAAA;EAIxC,MAAA,CAAA,GAAU,OAAA;EAuBV,UAAA,CAAA;EAAA,QAIc,gBAAA;AAAA"}