@iann29/rastro 0.1.0-alpha.2 → 0.1.0-alpha.3

package/src/component/geo.ts

@@ -0,0 +1,779 @@
+import { v } from "convex/values";
+import type { Doc, Id } from "./_generated/dataModel.js";
+import { env, internalAction, internalMutation } from "./_generated/server.js";
+import type { MutationCtx } from "./_generated/server.js";
+import {
+  AGGREGATE_SHARDS,
+  DAY_MS,
+  DIMENSION_SLOTS,
+  HOURLY_AGGREGATE_SHARDS,
+  HOUR_MS,
+  MAX_BATCH_EVENT_GROUPS,
+  MAX_BATCH_EVENTS,
+  MAX_EVENTS_PER_SESSION_WINDOW,
+} from "./constants.js";
+import { eventBatchKey, eventBucketStart } from "./eventStore.js";
+import { isPlainRecord } from "./guards.js";
+import { sanitizeContext, stableHash } from "./sanitize.js";
+import {
+  trackerEventValidator,
+  type IngestContext,
+} from "./validators.js";
+
+export type GeoIpProvider = "ipinfo" | "ipwhois";
+export type GeoIpStatus = "disabled" | "ready" | "missingToken";
+export type IpKind = "public" | "private" | "invalid" | "unavailable";
+export type ClientIpSource = "native" | "forwarded" | "unavailable";
+
+type GeoContext = Pick<
+  IngestContext,
+  "country" | "city" | "latitude" | "longitude"
+>;
+
+type Fetcher = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+const GEOIP_TIMEOUT_MS = 1_500;
+const MAX_ENRICHMENT_SESSIONS = 4;
+const DEFAULT_GEOIP_DAILY_LIMIT = 1_000;
+const MAX_GEOIP_DAILY_LIMIT = 1_000_000;
+
+const geoContextValidator = v.object({
+  country: v.optional(v.string()),
+  city: v.optional(v.string()),
+  latitude: v.optional(v.number()),
+  longitude: v.optional(v.number()),
+});
+
+const geoCandidateEventValidator = trackerEventValidator.pick(
+  "eventId",
+  "sessionId",
+  "visitorId",
+  "timestamp",
+  "sequence",
+);
+const geoAggregateEventValidator = v.object({
+  sessionId: v.string(),
+  timestamp: v.number(),
+  priorCountry: v.string(),
+});
+
+export const probe = internalAction({
+  args: { ip: v.optional(v.string()) },
+  returns: v.object({
+    ipAvailable: v.boolean(),
+    requestIpKind: v.union(
+      v.literal("public"),
+      v.literal("private"),
+      v.literal("invalid"),
+      v.literal("unavailable"),
+    ),
+    provider: v.union(v.literal("ipinfo"), v.literal("ipwhois"), v.null()),
+    status: v.union(
+      v.literal("disabled"),
+      v.literal("ready"),
+      v.literal("missingToken"),
+    ),
+    location: v.union(geoContextValidator, v.null()),
+  }),
+  handler: async (ctx, args) => {
+    const metadata = await readRequestMetadata(ctx);
+    const provider = env.RASTRO_GEOIP_PROVIDER;
+    const status = geoIpStatus(provider, env.RASTRO_GEOIP_TOKEN);
+    const ip = args.ip && args.ip.length <= 64 ? args.ip : metadata.ip;
+    const location =
+      ip && provider && status === "ready"
+        ? await resolveGeoIp(ip, provider, env.RASTRO_GEOIP_TOKEN)
+        : undefined;
+    return {
+      ipAvailable: metadata.ip !== null,
+      requestIpKind: classifyIp(metadata.ip),
+      provider: provider ?? null,
+      status,
+      location: location ?? null,
+    };
+  },
+});
+
+export const claimEnrichment = internalMutation({
+  args: {
+    siteId: v.id("sites"),
+    events: v.array(geoCandidateEventValidator),
+    dailyLimit: v.number(),
+  },
+  returns: v.object({
+    sessionIds: v.array(v.string()),
+    events: v.array(geoAggregateEventValidator),
+  }),
+  handler: async (ctx, args) => {
+    if (
+      args.events.length === 0 ||
+      args.events.length > MAX_BATCH_EVENTS ||
+      !Number.isSafeInteger(args.dailyLimit) ||
+      args.dailyLimit < 0 ||
+      args.dailyLimit > MAX_GEOIP_DAILY_LIMIT
+    ) {
+      return { sessionIds: [], events: [] };
+    }
+    const groups = new Map<
+      string,
+      { sessionId: string; bucketStart: number; eventIds: Set<string> }
+    >();
+    for (const event of args.events) {
+      const bucketStart = eventBucketStart(event.timestamp);
+      const key = eventBatchKey(event.sessionId, bucketStart);
+      const group = groups.get(key) ?? {
+        sessionId: event.sessionId,
+        bucketStart,
+        eventIds: new Set<string>(),
+      };
+      group.eventIds.add(event.eventId);
+      groups.set(key, group);
+    }
+    if (groups.size > MAX_BATCH_EVENT_GROUPS) {
+      return { sessionIds: [], events: [] };
+    }
+    const persistedEvents = new Map<string, Map<string, string | undefined>>();
+    await Promise.all(
+      [...groups].map(async ([key, group]) => {
+        const batches = await ctx.db
+          .query("eventBatches")
+          .withIndex("by_siteId_and_sessionId_and_bucketStart", (range) =>
+            range
+              .eq("siteId", args.siteId)
+              .eq("sessionId", group.sessionId)
+              .eq("bucketStart", group.bucketStart),
+          )
+          .take(MAX_EVENTS_PER_SESSION_WINDOW + 1);
+        persistedEvents.set(
+          key,
+          new Map(
+            batches.flatMap((batch) =>
+              batch.events
+                .filter((event) => group.eventIds.has(event.eventId))
+                .map((event) => [
+                  event.eventId,
+                  event.aggregateCountry ?? event.country,
+                ] as const),
+            ),
+          ),
+        );
+      }),
+    );
+    const eligible: string[] = [];
+    const initialEvents = args.events.filter((event) => event.sequence === 0);
+    for (const event of initialEvents) {
+      if (eligible.includes(event.sessionId)) continue;
+      const persisted = persistedEvents.get(
+        eventBatchKey(event.sessionId, eventBucketStart(event.timestamp)),
+      );
+      if (!persisted?.has(event.eventId)) continue;
+      const session = await ctx.db
+        .query("sessions")
+        .withIndex("by_siteId_and_sessionId", (range) =>
+          range.eq("siteId", args.siteId).eq("sessionId", event.sessionId),
+        )
+        .unique();
+      if (
+        !session ||
+        session.visitorId !== event.visitorId ||
+        session.startedAt !== event.timestamp ||
+        session.geoLookupAttemptedAt !== undefined ||
+        (session.latitude !== undefined && session.longitude !== undefined)
+      ) {
+        continue;
+      }
+      eligible.push(event.sessionId);
+    }
+    const now = Date.now();
+    const dayStart = Math.floor(now / DAY_MS) * DAY_MS;
+    const budget = await ctx.db
+      .query("geoLookupBudgets")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .unique();
+    const used = budget?.dayStart === dayStart ? budget.count : 0;
+    const sessionIds = eligible.slice(
+      0,
+      Math.max(0, Math.min(MAX_ENRICHMENT_SESSIONS, args.dailyLimit - used)),
+    );
+    for (const sessionId of sessionIds) {
+      const session = await ctx.db
+        .query("sessions")
+        .withIndex("by_siteId_and_sessionId", (range) =>
+          range.eq("siteId", args.siteId).eq("sessionId", sessionId),
+        )
+        .unique();
+      if (!session || session.geoLookupAttemptedAt !== undefined) continue;
+      await ctx.db.patch("sessions", session._id, {
+        geoLookupAttemptedAt: now,
+      });
+    }
+    if (sessionIds.length > 0) {
+      if (budget) {
+        await ctx.db.patch("geoLookupBudgets", budget._id, {
+          dayStart,
+          count: used + sessionIds.length,
+        });
+      } else {
+        await ctx.db.insert("geoLookupBudgets", {
+          siteId: args.siteId,
+          dayStart,
+          count: sessionIds.length,
+        });
+      }
+    }
+    const claimed = new Set(sessionIds);
+    const seenEvents = new Set<string>();
+    const correctionEvents: Array<{
+      sessionId: string;
+      timestamp: number;
+      priorCountry: string;
+    }> = [];
+    for (const event of args.events) {
+      const key = `${eventBatchKey(event.sessionId, eventBucketStart(event.timestamp))}:${event.eventId}`;
+      if (
+        seenEvents.has(key) ||
+        !claimed.has(event.sessionId) ||
+        !persistedEvents
+          .get(eventBatchKey(event.sessionId, eventBucketStart(event.timestamp)))
+          ?.has(event.eventId)
+      ) {
+        continue;
+      }
+      seenEvents.add(key);
+      const priorCountry = persistedEvents
+        .get(
+          eventBatchKey(event.sessionId, eventBucketStart(event.timestamp)),
+        )
+        ?.get(event.eventId);
+      if (priorCountry === undefined) continue;
+      correctionEvents.push({
+        sessionId: event.sessionId,
+        timestamp: event.timestamp,
+        priorCountry,
+      });
+    }
+    return { sessionIds, events: correctionEvents };
+  },
+});
+
+export const applyEnrichment = internalMutation({
+  args: {
+    siteId: v.id("sites"),
+    sessionIds: v.array(v.string()),
+    events: v.array(geoAggregateEventValidator),
+    context: geoContextValidator,
+  },
+  returns: v.number(),
+  handler: async (ctx, args) => {
+    if (
+      args.sessionIds.length === 0 ||
+      args.sessionIds.length > MAX_ENRICHMENT_SESSIONS ||
+      args.events.length > MAX_BATCH_EVENTS
+    ) {
+      return 0;
+    }
+    const context = sanitizeContext(args.context);
+    const sessionCountries = new Map<string, string>();
+    let updated = 0;
+    for (const sessionId of new Set(args.sessionIds)) {
+      const session = await ctx.db
+        .query("sessions")
+        .withIndex("by_siteId_and_sessionId", (range) =>
+          range.eq("siteId", args.siteId).eq("sessionId", sessionId),
+        )
+        .unique();
+      if (!session || session.geoLookupAttemptedAt === undefined) continue;
+      const sessionCountry = session.country ?? context.country;
+      if (sessionCountry) sessionCountries.set(sessionId, sessionCountry);
+      const sessionGeo = missingGeo(session, context);
+      if (Object.keys(sessionGeo).length > 0) {
+        await ctx.db.patch("sessions", session._id, sessionGeo);
+      }
+      const liveSession = await ctx.db
+        .query("liveSessions")
+        .withIndex("by_siteId_and_sessionId", (range) =>
+          range.eq("siteId", args.siteId).eq("sessionId", sessionId),
+        )
+        .unique();
+      if (liveSession) {
+        const liveGeo = missingGeo(liveSession, context);
+        if (Object.keys(liveGeo).length > 0) {
+          await ctx.db.patch("liveSessions", liveSession._id, liveGeo);
+        }
+      }
+      updated += 1;
+    }
+    if (sessionCountries.size > 0) {
+      await correctCountryAggregates(
+        ctx,
+        args.siteId,
+        args.events,
+        sessionCountries,
+      );
+    }
+    return updated;
+  },
+});
+
+export function geoIpDailyLimit(value: string | undefined): number {
+  if (value === undefined) return DEFAULT_GEOIP_DAILY_LIMIT;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) &&
+    parsed >= 0 &&
+    parsed <= MAX_GEOIP_DAILY_LIMIT
+    ? parsed
+    : DEFAULT_GEOIP_DAILY_LIMIT;
+}
+
+export function geoIpStatus(
+  provider: GeoIpProvider | undefined,
+  token: string | undefined,
+): GeoIpStatus {
+  if (!provider) return "disabled";
+  if (provider === "ipinfo" && !token) return "missingToken";
+  return "ready";
+}
+
+export async function readRequestMetadata(ctx: {
+  meta: {
+    getRequestMetadata(): Promise<{
+      ip: string | null;
+      userAgent: string | null;
+    }>;
+  };
+}): Promise<{ ip: string | null; userAgent: string | null }> {
+  try {
+    const metadata = await ctx.meta.getRequestMetadata();
+    return { ip: metadata.ip, userAgent: metadata.userAgent };
+  } catch {
+    // Older self-hosted runtimes and convex-test may not implement this syscall.
+    return { ip: null, userAgent: null };
+  }
+}
+
+export async function resolveGeoIp(
+  ip: string,
+  provider: GeoIpProvider,
+  token: string | undefined,
+  fetcher: Fetcher = fetch,
+): Promise<GeoContext | undefined> {
+  if (geoIpStatus(provider, token) !== "ready" || classifyIp(ip) !== "public") {
+    return undefined;
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), GEOIP_TIMEOUT_MS);
+  try {
+    const response = await fetcher(
+      geoIpRequest(ip, provider, token),
+      provider === "ipinfo"
+        ? {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: controller.signal,
+          }
+        : { signal: controller.signal },
+    );
+    if (!response.ok) return undefined;
+    const value: unknown = await response.json();
+    return provider === "ipinfo"
+      ? parseIpinfoResponse(value)
+      : parseIpwhoisResponse(value);
+  } catch {
+    return undefined;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function classifyIp(ip: string | null): IpKind {
+  if (ip === null || ip.trim() === "") return "unavailable";
+  const normalized = ip.trim().toLowerCase();
+  const ipv4 = /^\d+\.\d+\.\d+\.\d+$/.test(normalized) ? normalized : undefined;
+  if (ipv4) return classifyIpv4(ipv4);
+  if (!normalized.includes(":")) return "invalid";
+  return classifyIpv6(normalized);
+}
+
+export function resolveClientIp(
+  nativeIp: string | null,
+  headers: Headers,
+  trustProxy = false,
+): { ip: string | null; source: ClientIpSource } {
+  if (classifyIp(nativeIp) === "public") {
+    return { ip: nativeIp, source: "native" };
+  }
+  // Forwarded headers require an explicit operator trust decision and a
+  // private immediate peer so direct client requests cannot spoof the IP.
+  if (!trustProxy || classifyIp(nativeIp) !== "private") {
+    return { ip: null, source: "unavailable" };
+  }
+  const candidates = [
+    ...(headers.get("x-forwarded-for")?.split(",").reverse() ?? []),
+    headers.get("x-real-ip"),
+    headers.get("cf-connecting-ip"),
+  ];
+  for (const candidate of candidates) {
+    const ip = normalizeForwardedIp(candidate);
+    if (ip && classifyIp(ip) === "public") {
+      return { ip, source: "forwarded" };
+    }
+  }
+  return { ip: null, source: "unavailable" };
+}
+
+export function isTrustedProxyRequest(
+  nativeIp: string | null,
+  trustProxy: boolean,
+): boolean {
+  return trustProxy && classifyIp(nativeIp) === "private";
+}
+
+function classifyIpv4(ip: string): Exclude<IpKind, "unavailable"> {
+  const octets = ip.split(".").map(Number);
+  if (
+    octets.length !== 4 ||
+    octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)
+  ) {
+    return "invalid";
+  }
+  const [a, b, c] = octets as [number, number, number, number];
+  if (
+    a === 0 ||
+    a === 10 ||
+    a === 127 ||
+    (a === 100 && b >= 64 && b <= 127) ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 0 && c === 0) ||
+    (a === 192 && b === 0 && c === 2) ||
+    (a === 192 && b === 168) ||
+    (a === 198 && (b === 18 || b === 19)) ||
+    (a === 198 && b === 51 && c === 100) ||
+    (a === 203 && b === 0 && c === 113) ||
+    a >= 224
+  ) {
+    return "private";
+  }
+  return "public";
+}
+
+function classifyIpv6(ip: string): Exclude<IpKind, "unavailable"> {
+  const groups = parseIpv6(ip);
+  if (!groups) return "invalid";
+  if (
+    groups.every((group) => group === 0) ||
+    (groups.slice(0, 7).every((group) => group === 0) && groups[7] === 1) ||
+    (groups[0]! & 0xfe00) === 0xfc00 ||
+    (groups[0]! & 0xffc0) === 0xfe80 ||
+    (groups[0]! & 0xffc0) === 0xfec0 ||
+    (groups[0]! & 0xff00) === 0xff00 ||
+    (groups[0] === 0x0100 && groups.slice(1, 4).every((group) => group === 0)) ||
+    (groups[0] === 0x0064 && groups[1] === 0xff9b && groups[2] === 1) ||
+    (groups[0] === 0x2001 && (groups[1]! & 0xfe00) === 0) ||
+    (groups[0] === 0x2001 && groups[1] === 0x0db8) ||
+    groups[0] === 0x2002 ||
+    (groups[0]! & 0xfff0) === 0x3ff0
+  ) {
+    return "private";
+  }
+  if (groups.slice(0, 6).every((group) => group === 0)) {
+    return "private";
+  }
+  if (
+    groups.slice(0, 5).every((group) => group === 0) &&
+    groups[5] === 0xffff
+  ) {
+    const ipv4 = `${groups[6]! >> 8}.${groups[6]! & 255}.${groups[7]! >> 8}.${groups[7]! & 255}`;
+    return classifyIpv4(ipv4);
+  }
+  // Current globally routable unicast allocations are within 2000::/3.
+  // Unknown/special space fails closed so it is never sent to a provider.
+  return (groups[0]! & 0xe000) === 0x2000 ? "public" : "private";
+}
+
+function parseIpv6(ip: string): number[] | undefined {
+  let normalized = ip;
+  const dottedTail = normalized.match(/(\d+\.\d+\.\d+\.\d+)$/)?.[1];
+  if (dottedTail) {
+    if (classifyIpv4(dottedTail) === "invalid") return undefined;
+    const octets = dottedTail.split(".").map(Number);
+    normalized =
+      normalized.slice(0, -dottedTail.length) +
+      `${((octets[0]! << 8) | octets[1]!).toString(16)}:${((octets[2]! << 8) | octets[3]!).toString(16)}`;
+  }
+  const halves = normalized.split("::");
+  if (halves.length > 2) return undefined;
+  const left = halves[0] ? halves[0].split(":") : [];
+  const right = halves[1] ? halves[1].split(":") : [];
+  if (
+    [...left, ...right].some((group) => !/^[0-9a-f]{1,4}$/.test(group)) ||
+    (halves.length === 1 && left.length !== 8) ||
+    (halves.length === 2 && left.length + right.length >= 8)
+  ) {
+    return undefined;
+  }
+  const fill =
+    halves.length === 2
+      ? Array<number>(8 - left.length - right.length).fill(0)
+      : [];
+  return [...left.map(hexGroup), ...fill, ...right.map(hexGroup)];
+}
+
+function hexGroup(value: string): number {
+  return Number.parseInt(value, 16);
+}
+
+function normalizeForwardedIp(value: string | null): string | undefined {
+  if (!value) return undefined;
+  let normalized = value.trim().replace(/^"|"$/g, "");
+  if (normalized.startsWith("[")) {
+    const end = normalized.indexOf("]");
+    return end > 0 ? normalized.slice(1, end) : undefined;
+  }
+  if (/^\d+\.\d+\.\d+\.\d+:\d+$/.test(normalized)) {
+    normalized = normalized.slice(0, normalized.lastIndexOf(":"));
+  }
+  return normalized || undefined;
+}
+
+async function correctCountryAggregates(
+  ctx: MutationCtx,
+  siteId: Id<"sites">,
+  events: Array<{
+    sessionId: string;
+    timestamp: number;
+    priorCountry: string;
+  }>,
+  sessionCountries: Map<string, string>,
+): Promise<void> {
+  const corrections = new Map<
+    string,
+    {
+      granularity: "hour" | "day";
+      bucketStart: number;
+      shard: number;
+      moves: Map<string, { from: string; to: string; count: number }>;
+    }
+  >();
+  for (const event of events) {
+    const country = sessionCountries.get(event.sessionId);
+    if (!country || country === event.priorCountry) continue;
+    for (const granularity of ["hour", "day"] as const) {
+      const interval = granularity === "hour" ? HOUR_MS : DAY_MS;
+      const bucketStart = Math.floor(event.timestamp / interval) * interval;
+      const shard = stableHash(event.sessionId) %
+        (granularity === "hour" ? HOURLY_AGGREGATE_SHARDS : AGGREGATE_SHARDS);
+      const key = `${granularity}:${bucketStart}:${shard}`;
+      const correction = corrections.get(key) ?? {
+        granularity,
+        bucketStart,
+        shard,
+        moves: new Map<string, { from: string; to: string; count: number }>(),
+      };
+      const moveKey = `${event.priorCountry}:${country}`;
+      const move = correction.moves.get(moveKey) ?? {
+        from: event.priorCountry,
+        to: country,
+        count: 0,
+      };
+      move.count += 1;
+      correction.moves.set(moveKey, move);
+      corrections.set(key, correction);
+    }
+  }
+  for (const correction of corrections.values()) {
+    const bucket = await ctx.db
+      .query("aggregateBuckets")
+      .withIndex(
+        "by_siteId_and_granularity_and_bucketStart_and_shard",
+        (range) =>
+          range
+            .eq("siteId", siteId)
+            .eq("granularity", correction.granularity)
+            .eq("bucketStart", correction.bucketStart)
+            .eq("shard", correction.shard),
+      )
+      .unique();
+    if (!bucket) continue;
+    let dimensions = bucket.dimensions;
+    let changed = false;
+    for (const move of correction.moves.values()) {
+      const corrected = moveCountryCount(
+        dimensions,
+        move.from,
+        move.to,
+        move.count,
+      );
+      if (corrected) {
+        dimensions = corrected;
+        changed = true;
+      }
+    }
+    if (changed) {
+      await ctx.db.patch("aggregateBuckets", bucket._id, { dimensions });
+    }
+  }
+}
+
+function moveCountryCount(
+  current: Doc<"aggregateBuckets">["dimensions"],
+  from: string,
+  to: string,
+  requested: number,
+): Doc<"aggregateBuckets">["dimensions"] | undefined {
+  const dimensions = current.map((slot) => ({ ...slot }));
+  let sourceIndex = dimensions.findIndex(
+    (slot) => slot.type === "country" && slot.value === from,
+  );
+  if (sourceIndex < 0) {
+    sourceIndex = dimensions.findIndex(
+      (slot) => slot.type === "country" && slot.value === "(other)",
+    );
+  }
+  if (sourceIndex < 0) return undefined;
+  const source = dimensions[sourceIndex]!;
+  const moved = Math.min(source.count, requested);
+  if (moved <= 0) return undefined;
+  source.count -= moved;
+  if (source.count === 0 && source.revenueCents === 0) {
+    dimensions.splice(sourceIndex, 1);
+  }
+  const target = dimensions.find(
+    (slot) => slot.type === "country" && slot.value === to,
+  );
+  if (target) {
+    target.count += moved;
+    return dimensions;
+  }
+  const countrySlots = dimensions.filter((slot) => slot.type === "country");
+  if (countrySlots.length < DIMENSION_SLOTS - 1) {
+    const occupied = new Set(countrySlots.map((slot) => slot.slot));
+    let slot = stableHash(to) % DIMENSION_SLOTS;
+    while (occupied.has(slot)) slot = (slot + 1) % DIMENSION_SLOTS;
+    dimensions.push({
+      type: "country",
+      slot,
+      value: to,
+      count: moved,
+      revenueCents: 0,
+    });
+    return dimensions;
+  }
+  const overflow = countrySlots.find((slot) => slot.value === "(other)");
+  if (overflow) {
+    overflow.count += moved;
+    return dimensions;
+  }
+  const occupied = new Set(countrySlots.map((slot) => slot.slot));
+  if (countrySlots.length < DIMENSION_SLOTS) {
+    let slot = stableHash("(other)") % DIMENSION_SLOTS;
+    while (occupied.has(slot)) slot = (slot + 1) % DIMENSION_SLOTS;
+    dimensions.push({
+      type: "country",
+      slot,
+      value: "(other)",
+      count: moved,
+      revenueCents: 0,
+    });
+    return dimensions;
+  }
+  let replacement = countrySlots[0]!;
+  for (const candidate of countrySlots.slice(1)) {
+    if (candidate.count < replacement.count) replacement = candidate;
+  }
+  replacement.value = "(other)";
+  replacement.count += moved;
+  return dimensions;
+}
+
+function missingGeo(existing: GeoContext, context: GeoContext): GeoContext {
+  const coordinates =
+    (existing.latitude === undefined || existing.longitude === undefined) &&
+    context.latitude !== undefined &&
+    context.longitude !== undefined
+      ? { latitude: context.latitude, longitude: context.longitude }
+      : {};
+  return {
+    ...(existing.country === undefined && context.country !== undefined
+      ? { country: context.country }
+      : {}),
+    ...(existing.city === undefined && context.city !== undefined
+      ? { city: context.city }
+      : {}),
+    ...coordinates,
+  };
+}
+
+function geoIpRequest(
+  ip: string,
+  provider: GeoIpProvider,
+  token: string | undefined,
+): URL {
+  const encodedIp = encodeURIComponent(ip);
+  if (provider === "ipinfo") {
+    return new URL(`https://api.ipinfo.io/lookup/${encodedIp}`);
+  }
+  const url = new URL(
+    token
+      ? `https://ipwhois.pro/${encodedIp}`
+      : `https://ipwho.is/${encodedIp}`,
+  );
+  url.searchParams.set(
+    "fields",
+    "success,country_code,city,latitude,longitude",
+  );
+  if (token) url.searchParams.set("key", token);
+  return url;
+}
+
+function parseIpinfoResponse(value: unknown): GeoContext | undefined {
+  if (!isPlainRecord(value) || !isPlainRecord(value.geo)) return undefined;
+  return geoContext({
+    country: value.geo.country_code,
+    city: value.geo.city,
+    latitude: value.geo.latitude,
+    longitude: value.geo.longitude,
+  });
+}
+
+function parseIpwhoisResponse(value: unknown): GeoContext | undefined {
+  if (!isPlainRecord(value) || value.success === false) return undefined;
+  return geoContext({
+    country: value.country_code,
+    city: value.city,
+    latitude: value.latitude,
+    longitude: value.longitude,
+  });
+}
+
+function geoContext(value: Record<string, unknown>): GeoContext | undefined {
+  const country = typeof value.country === "string" ? value.country : undefined;
+  const city = typeof value.city === "string" ? value.city : undefined;
+  const latitude = finiteNumber(value.latitude);
+  const longitude = finiteNumber(value.longitude);
+  const coordinates =
+    latitude !== undefined &&
+    longitude !== undefined &&
+    latitude >= -90 &&
+    latitude <= 90 &&
+    longitude >= -180 &&
+    longitude <= 180
+      ? { latitude, longitude }
+      : {};
+  if (!country && !city && Object.keys(coordinates).length === 0) {
+    return undefined;
+  }
+  return {
+    ...(country ? { country } : {}),
+    ...(city ? { city } : {}),
+    ...coordinates,
+  };
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}