@magmacomputing/tempo-plugin-geo 1.2.0 → 1.4.0

package/dist/index.js

@@ -274,7 +274,7 @@ function isNumeric(str) {
       return false;
   }
 }
-var isType, isPrimitive, isReference, isIterable, isString, isText, isNumber, RE_BIGINT_LITERAL, isInteger, isArray, isArrayLike, isObject, isDate, isRegExp, isSymbol, isSymbolFor, isSafeKey, isNullish, isUndefined, isDefined, isFunction, isCallable, isMap, isSet, isError, isLocale, isEmpty;
+var isType, isPrimitive, isReference, isIterable, isString, isText, isNumber, RE_BIGINT_LITERAL, isInteger, isBoolean, isArray, isArrayLike, isObject, isDate, isRegExp, isSymbol, isSymbolFor, isSafeKey, isNullish, isUndefined, isDefined, isFunction, isCallable, isMap, isSet, isError, isLocale, isEmpty;
 var init_assertion_library = __esm({
   "../../library/dist/common/primitives/assertion.library.js"() {
     "use strict";
@@ -289,6 +289,7 @@ var init_assertion_library = __esm({
     isNumber = (obj) => Number.isFinite(obj);
     RE_BIGINT_LITERAL = /^[+-]?[0-9]+n$/;
     isInteger = (obj) => typeof obj === "bigint";
+    isBoolean = (obj) => typeof obj === "boolean";
     isArray = (obj) => Array.isArray(obj);
     isArrayLike = (obj) => protoType(obj) === "Object" && "length" in obj && Object.keys(obj).every((key) => key === "length" || isNumber(Number(key)));
     isObject = (obj) => isType(obj, "Object");
@@ -2774,8 +2775,8 @@ __export(sdk_exports, {
 __reExport(sdk_exports, sdk_star);
 import * as sdk_star from "@magmacomputing/tempo/plugin/sdk";
 import { definePlugin as originalPlugin, defineTerm as originalTerm } from "@magmacomputing/tempo/plugin/sdk";
-var definePlugin = (config) => originalPlugin({ ...config, version: "1.2.0" });
-var defineTerm = (config) => originalTerm({ ...config, version: "1.2.0" });
+var definePlugin = (config) => originalPlugin({ ...config, version: "1.4.0" });
+var defineTerm = (config) => originalTerm({ ...config, version: "1.4.0" });
 
 // ../../library/dist/common/runtime/mapper.library.js
 init_utility_library();
@@ -2794,8 +2795,13 @@ function evaluate(...values) {
 }
 
 // ../../library/dist/common/runtime/mapper.library.js
+init_cache_class();
 var MAP_KEY2 = "_magma_geo_";
 var DEFAULT_GEO_TTL = 24 * 60 * 60 * 1e3;
+var DEFAULT_REVERSE_GEO_ENDPOINT = "https://api.bigdatacloud.net/data/reverse-geocode-client";
+var DEFAULT_REVERSE_GEO_TIMEOUT = 3e3;
+var DEFAULT_REVERSE_GEO_MAX_BYTES = 64 * 1024;
+var DEFAULT_SPATIAL_CACHE_SIZE = 1e3;
 var GEO_PROPERTIES = [
   "latitude",
   "lat",
@@ -2810,13 +2816,33 @@ var GEO_PROPERTIES = [
   "timezone",
   "tz"
 ];
-var normalizeLat = (lat) => isNumber(lat) && lat >= -90 && lat <= 90 ? Math.round(lat * 1e3) / 1e3 : void 0;
-var normalizeLng = (lng) => isNumber(lng) && lng >= -180 && lng <= 180 ? Math.round(lng * 1e3) / 1e3 : void 0;
-var normalizeCoords = (lat, lng) => {
-  const nLat = normalizeLat(lat);
-  const nLng = normalizeLng(lng);
-  return nLat !== void 0 && nLng !== void 0 ? { lat: nLat, lng: nLng } : void 0;
+var parseCoordNumber = (val) => {
+  if (!isDefined(val) || isBoolean(val))
+    return NaN;
+  if (isString(val)) {
+    const trimmed = val.trim();
+    return trimmed.length > 0 ? Number(trimmed) : NaN;
+  }
+  return isNumber(val) ? val : NaN;
+};
+var normalizeLat = (lat, round = true) => {
+  const n = parseCoordNumber(lat);
+  if (!isNumber(n) || n < -90 || n > 90)
+    return void 0;
+  return round ? Math.round(n * 1e3) / 1e3 : n;
+};
+var normalizeLng = (lng, round = true) => {
+  const n = parseCoordNumber(lng);
+  if (!isNumber(n) || n < -180 || n > 180)
+    return void 0;
+  return round ? Math.round(n * 1e3) / 1e3 : n;
+};
+var normalizeCoords = (lat, lng, round = true) => {
+  const nLat = normalizeLat(lat, round);
+  const nLng = normalizeLng(lng, round);
+  return isDefined(nLat) && isDefined(nLng) ? { lat: nLat, lng: nLng } : void 0;
 };
+var normalizeElevation = (elevation) => isNumber(elevation) ? Math.round(elevation * 1e3) / 1e3 : void 0;
 var resolveSphere = (sphere, lat) => {
   if (sphere === "north" || sphere === "south" || sphere === "equator")
     return sphere;
@@ -2824,35 +2850,47 @@ var resolveSphere = (sphere, lat) => {
     return lat > 1e-3 ? "north" : lat < -1e-3 ? "south" : "equator";
   return void 0;
 };
-var coerceGeo = (input) => {
+var parseCoordinatePair = (input, normalize = true) => {
   if (isString(input) && input.includes(",")) {
-    const segments = input.split(",").map((s) => s.trim());
-    const parts = segments.map((s) => s === "" ? NaN : Number(s));
-    if (parts.length >= 2 && !isNaN(parts[0]) && !isNaN(parts[1])) {
-      const coords = normalizeCoords(parts[0], parts[1]);
-      if (coords) {
-        const result2 = { latitude: coords.lat, longitude: coords.lng };
-        const sphere2 = resolveSphere(void 0, coords.lat);
-        if (sphere2)
-          result2.sphere = sphere2;
-        return result2;
+    const parts = input.split(",").map((s) => s.trim());
+    return parts.length >= 2 ? normalizeCoords(parts[0], parts[1], normalize) : void 0;
+  }
+  return Array.isArray(input) && input.length >= 2 ? normalizeCoords(input[0], input[1], normalize) : void 0;
+};
+var assembleGeoConfig = (coords, meta) => {
+  const lat = "lat" in coords ? coords.lat : coords.latitude;
+  const lng = "lng" in coords ? coords.lng : coords.longitude;
+  const nLat = normalizeLat(lat);
+  const nLng = normalizeLng(lng);
+  const sphere = resolveSphere(meta?.sphere, nLat ?? lat);
+  const elevation = normalizeElevation(meta?.elevation);
+  return {
+    latitude: nLat ?? lat,
+    longitude: nLng ?? lng,
+    ...sphere ? { sphere } : {},
+    ...isString(meta?.city) && !isEmpty(meta.city) ? { city: meta.city.trim() } : {},
+    ...isString(meta?.country) && !isEmpty(meta.country) ? { country: meta.country.trim() } : {},
+    ...elevation !== void 0 ? { elevation } : {},
+    ...isString(meta?.timezone) && !isEmpty(meta.timezone) ? { timezone: meta.timezone.trim() } : {}
+  };
+};
+var extractCustomProperties = (source, excludedKeys = GEO_PROPERTIES) => {
+  const custom = {};
+  if (isReference(source)) {
+    for (const key of Object.keys(source)) {
+      if (isSafeKey(key) && !excludedKeys.includes(key)) {
+        custom[key] = source[key];
       }
     }
-    return void 0;
   }
+  return custom;
+};
+var coerceGeo = (input) => {
+  const pair = parseCoordinatePair(input);
+  if (pair)
+    return assembleGeoConfig(pair);
   if (isPrimitive(input))
     return void 0;
-  if (Array.isArray(input) && input.length >= 2) {
-    const coords = normalizeCoords(input[0], input[1]);
-    if (coords) {
-      const result2 = { latitude: coords.lat, longitude: coords.lng };
-      const sphere2 = resolveSphere(void 0, coords.lat);
-      if (sphere2)
-        result2.sphere = sphere2;
-      return result2;
-    }
-    return void 0;
-  }
   const geo = input.geo ?? input;
   const cfg = input.config?.geo ?? input.config;
   const lat = evaluate(geo?.latitude, geo?.lat, input.latitude, input.lat, cfg?.latitude, cfg?.lat);
@@ -2869,8 +2907,9 @@ var coerceGeo = (input) => {
     result.latitude = nLat;
   if (nLng !== void 0)
     result.longitude = nLng;
-  if (isNumber(elevation))
-    result.elevation = Math.round(elevation * 1e3) / 1e3;
+  const nElevation = normalizeElevation(elevation);
+  if (nElevation !== void 0)
+    result.elevation = nElevation;
   const resolvedSphere = resolveSphere(sphere, result.latitude);
   if (resolvedSphere)
     result.sphere = resolvedSphere;
@@ -2881,12 +2920,8 @@ var coerceGeo = (input) => {
   if (isString(timezone))
     result.timezone = timezone;
   const explicitGeo = isReference(input.geo) ? input.geo : isReference(input.config?.geo) ? input.config.geo : void 0;
-  if (isReference(explicitGeo)) {
-    for (const key of Object.keys(explicitGeo)) {
-      if (isSafeKey(key) && !GEO_PROPERTIES.includes(key))
-        result[key] = explicitGeo[key];
-    }
-  }
+  const customKeys = extractCustomProperties(explicitGeo);
+  Object.assign(result, customKeys);
   return Object.keys(result).length > 0 ? result : void 0;
 };
 var resolveCacheKey = (keyOrOpts) => {
@@ -2895,16 +2930,25 @@ var resolveCacheKey = (keyOrOpts) => {
     return trimmed.startsWith(MAP_KEY2) ? trimmed : `${MAP_KEY2}:${trimmed}`;
   }
   if (keyOrOpts && isObject(keyOrOpts)) {
+    const provider = keyOrOpts.provider ?? activeGeoProvider;
+    const providerPrefix = provider && isString(provider.name) && !isEmpty(provider.name) ? `provider:${provider.name}` : void 0;
     const k = keyOrOpts.key ?? keyOrOpts.ip ?? keyOrOpts.query;
-    if (isString(k) && !isEmpty(k))
-      return `${MAP_KEY2}:${k.trim()}`;
+    if (isString(k) && !isEmpty(k)) {
+      const trimmedKey = k.trim();
+      return providerPrefix ? `${MAP_KEY2}:${providerPrefix}:${trimmedKey}` : `${MAP_KEY2}:${trimmedKey}`;
+    }
+    if (providerPrefix) {
+      return `${MAP_KEY2}:${providerPrefix}`;
+    }
+  } else if (activeGeoProvider && isString(activeGeoProvider.name) && !isEmpty(activeGeoProvider.name)) {
+    return `${MAP_KEY2}:provider:${activeGeoProvider.name}`;
   }
   return MAP_KEY2;
 };
 var getStashedGeo = (keyOrOpts) => {
   const cacheKey = resolveCacheKey(keyOrOpts);
   try {
-    const raw = getStorage(cacheKey) ?? (typeof localStorage !== "undefined" ? localStorage.getItem(cacheKey) : void 0);
+    const raw = getStorage(cacheKey) ?? (isCallable(globalThis.localStorage?.getItem) ? globalThis.localStorage.getItem(cacheKey) : void 0);
     if (!raw)
       return void 0;
     const parsed = isString(raw) && (raw.startsWith("{") || raw.startsWith("[")) ? JSON.parse(raw) : raw;
@@ -2914,35 +2958,23 @@ var getStashedGeo = (keyOrOpts) => {
         return void 0;
       }
     }
-    if (isString(parsed) && parsed.includes(",")) {
-      const parts = parsed.split(",").map((s) => parseFloat(s.trim()));
-      const coords = normalizeCoords(parts[0], parts[1]);
-      if (coords) {
-        return {
-          latitude: coords.lat,
-          longitude: coords.lng,
-          sphere: resolveSphere(void 0, coords.lat)
-        };
-      }
-    }
+    const pair = parseCoordinatePair(parsed);
+    if (pair)
+      return assembleGeoConfig(pair);
     if (isObject(parsed)) {
       const rawCoords = parsed.geolocation?.coords ?? parsed.coords ?? parsed;
       const lat = rawCoords?.latitude ?? rawCoords?.lat;
       const lng = rawCoords?.longitude ?? rawCoords?.lng ?? rawCoords?.lon ?? rawCoords?.long;
       const coords = normalizeCoords(lat, lng);
       if (coords) {
-        const result = { latitude: coords.lat, longitude: coords.lng };
         const elevation = parsed.elevation ?? rawCoords.elevation;
-        if (isNumber(elevation))
-          result.elevation = Math.round(elevation * 1e3) / 1e3;
-        result.sphere = resolveSphere(parsed.sphere, coords.lat);
-        if (isString(parsed.country))
-          result.country = parsed.country;
-        if (isString(parsed.city))
-          result.city = parsed.city;
-        if (isString(parsed.timezone))
-          result.timezone = parsed.timezone;
-        return result;
+        return assembleGeoConfig(coords, {
+          elevation,
+          sphere: parsed.sphere,
+          country: parsed.country,
+          city: parsed.city,
+          timezone: parsed.timezone
+        });
       }
     }
   } catch {
@@ -2958,7 +2990,15 @@ var clearStashedGeo = (keyOrOpts) => {
   const cacheKey = resolveCacheKey(keyOrOpts);
   setStorage(cacheKey, void 0);
 };
+var activeGeoProvider;
+function setGeoProvider(provider) {
+  activeGeoProvider = provider;
+}
+function getGeoProvider() {
+  return activeGeoProvider;
+}
 var geoLookup = async (opts = {}) => {
+  const provider = opts.provider ?? activeGeoProvider;
   const useCache = opts.refresh !== true;
   if (useCache) {
     const stashed = getStashedGeo(opts);
@@ -2974,26 +3014,45 @@ var geoLookup = async (opts = {}) => {
       };
     }
   }
-  const { type } = getContext();
   let res;
-  switch (type) {
-    case CONTEXT.Browser: {
-      const { geoLocation: geoLocation2 } = await Promise.resolve().then(() => (init_mapper_library(), mapper_library_exports));
-      const browserRes = await geoLocation2(opts);
-      if (browserRes.error)
-        return { error: browserRes.error };
-      const lat = browserRes.coords?.latitude;
-      const lng = browserRes.coords?.longitude;
-      res = { ...browserRes, lat, lng, latitude: lat, longitude: lng };
-      break;
+  if (provider && isFunction(provider.lookup)) {
+    try {
+      const providerRes = await provider.lookup(opts);
+      if (providerRes) {
+        res = providerRes;
+        if (providerRes.error && opts.fallback === false)
+          return providerRes;
+      } else if (opts.fallback === false) {
+        return { error: "Provider returned null and fallback is disabled" };
+      }
+    } catch (err) {
+      if (opts.fallback === false)
+        return { error: err?.message ?? "Provider lookup failed" };
     }
-    case CONTEXT.WebWorker:
-    case CONTEXT.NodeJS:
-    case CONTEXT.Deno:
-    default: {
-      const { serverGeoLocation: serverGeoLocation2 } = await Promise.resolve().then(() => (init_mapper_library2(), mapper_library_exports2));
-      res = await serverGeoLocation2(opts);
-      break;
+  }
+  if (!res || res.error) {
+    if (opts.fallback === false && (provider || res?.error))
+      return res && res.error ? res : { error: "Geolocation resolution failed and fallback is disabled" };
+    const { type } = getContext();
+    switch (type) {
+      case CONTEXT.Browser: {
+        const { geoLocation: geoLocation2 } = await Promise.resolve().then(() => (init_mapper_library(), mapper_library_exports));
+        const browserRes = await geoLocation2(opts);
+        if (browserRes.error)
+          return { error: browserRes.error };
+        const lat = browserRes.coords?.latitude;
+        const lng = browserRes.coords?.longitude;
+        res = { ...browserRes, lat, lng, latitude: lat, longitude: lng };
+        break;
+      }
+      case CONTEXT.WebWorker:
+      case CONTEXT.NodeJS:
+      case CONTEXT.Deno:
+      default: {
+        const { serverGeoLocation: serverGeoLocation2 } = await Promise.resolve().then(() => (init_mapper_library2(), mapper_library_exports2));
+        res = await serverGeoLocation2(opts);
+        break;
+      }
     }
   }
   const rawLat = res.latitude ?? res.lat;
@@ -3006,15 +3065,7 @@ var geoLookup = async (opts = {}) => {
     res.latitude = coords.lat;
     res.longitude = coords.lng;
     res.sphere = sphere;
-    const stashPayload = {
-      latitude: coords.lat,
-      longitude: coords.lng,
-      sphere,
-      ...isString(res.city) ? { city: res.city } : {},
-      ...isString(res.country) ? { country: res.country } : {},
-      ...isNumber(res.elevation) ? { elevation: Math.round(res.elevation * 1e3) / 1e3 } : {},
-      ...isString(res.timezone) ? { timezone: res.timezone } : {}
-    };
+    const stashPayload = assembleGeoConfig(coords, res);
     try {
       const ttl = isNumber(opts.ttl) ? opts.ttl : DEFAULT_GEO_TTL;
       stashGeo(stashPayload, ttl, opts);
@@ -3023,14 +3074,183 @@ var geoLookup = async (opts = {}) => {
   }
   return res;
 };
+var requestModulePromise2 = null;
+var getRequestModule2 = () => {
+  if (!requestModulePromise2)
+    requestModulePromise2 = Promise.resolve().then(() => (init_request_library(), request_library_exports));
+  return requestModulePromise2;
+};
+var reverseGeoCache = new BoundedCache(DEFAULT_SPATIAL_CACHE_SIZE, DEFAULT_GEO_TTL);
+var isValidGeoEndpoint = (urlStr) => {
+  try {
+    const parsed = new URL(urlStr);
+    return parsed.protocol === "https:" || parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+};
+var getSpatialCacheKey = (lat, lng, sourceOrOpts) => {
+  const bucket = `${lat.toFixed(2)},${lng.toFixed(2)}`;
+  if (isString(sourceOrOpts) && !isEmpty(sourceOrOpts)) {
+    return `${bucket}:${sourceOrOpts.trim()}`;
+  }
+  if (isObject(sourceOrOpts)) {
+    const hasExplicitProvider = Object.hasOwn(sourceOrOpts, "provider");
+    const provider = hasExplicitProvider ? sourceOrOpts.provider : activeGeoProvider;
+    const providerName = provider && isString(provider.name) && !isEmpty(provider.name) ? provider.name.trim() : void 0;
+    const rawEndpoint = isString(sourceOrOpts.reverseEndpoint ?? sourceOrOpts.reverseGeoEndpoint) && !isEmpty(sourceOrOpts.reverseEndpoint ?? sourceOrOpts.reverseGeoEndpoint) ? (sourceOrOpts.reverseEndpoint ?? sourceOrOpts.reverseGeoEndpoint).trim() : void 0;
+    const endpoint = rawEndpoint && isValidGeoEndpoint(rawEndpoint) ? rawEndpoint : void 0;
+    if (providerName && endpoint)
+      return `${bucket}:${providerName}:${endpoint}`;
+    if (providerName)
+      return `${bucket}:${providerName}`;
+    if (endpoint)
+      return `${bucket}:${endpoint}`;
+  } else if (activeGeoProvider && isString(activeGeoProvider.name) && !isEmpty(activeGeoProvider.name)) {
+    return `${bucket}:${activeGeoProvider.name.trim()}`;
+  }
+  return bucket;
+};
+async function reverseGeocode(coords, opts) {
+  const coerced = coerceGeo(coords);
+  if (!coerced || !isNumber(coerced.latitude) || !isNumber(coerced.longitude))
+    return null;
+  const lat = coerced.latitude;
+  const lng = coerced.longitude;
+  const key = getSpatialCacheKey(lat, lng, opts);
+  const useCache = opts?.refresh !== true;
+  if (useCache) {
+    const cached = reverseGeoCache.get(key);
+    if (cached) {
+      return {
+        ...cached,
+        latitude: lat,
+        longitude: lng,
+        sphere: resolveSphere(cached.sphere, lat),
+        elevation: isNumber(cached.elevation) ? cached.elevation : coerced.elevation,
+        timezone: isString(cached.timezone) ? cached.timezone : coerced.timezone
+      };
+    }
+  }
+  const hasExplicitProvider = isObject(opts) && Object.hasOwn(opts, "provider");
+  const provider = hasExplicitProvider ? opts.provider : activeGeoProvider;
+  if (provider && isFunction(provider.reverseGeocode)) {
+    try {
+      const res = await provider.reverseGeocode(coerced, opts);
+      if (res && isObject(res)) {
+        const result = assembleGeoConfig({ lat, lng }, {
+          sphere: res.sphere,
+          city: res.city,
+          country: res.country,
+          elevation: isNumber(res.elevation) ? res.elevation : coerced.elevation,
+          timezone: isString(res.timezone) ? res.timezone : coerced.timezone
+        });
+        const cachePayload = assembleGeoConfig({ lat, lng }, {
+          sphere: res.sphere,
+          city: res.city,
+          country: res.country,
+          timezone: res.timezone
+        });
+        reverseGeoCache.set(key, cachePayload);
+        return result;
+      }
+      if (opts?.fallback === false)
+        return null;
+    } catch (err) {
+      if (opts?.fallback === false)
+        throw err;
+    }
+  } else if (opts?.fallback === false && (provider || hasExplicitProvider)) {
+    return null;
+  }
+  const rawReverseEndpoint = opts?.reverseEndpoint ?? opts?.reverseGeoEndpoint;
+  if (isText(rawReverseEndpoint)) {
+    const rawEndpoint = rawReverseEndpoint.trim();
+    if (!isValidGeoEndpoint(rawEndpoint))
+      return opts?.fallback === false ? null : coerced;
+  }
+  const customEndpoint = isText(rawReverseEndpoint) ? rawReverseEndpoint.trim() : void 0;
+  const fallbackKey = getSpatialCacheKey(lat, lng, customEndpoint ?? "default");
+  if (useCache) {
+    const cachedFallback = reverseGeoCache.get(fallbackKey);
+    if (cachedFallback) {
+      return {
+        ...cachedFallback,
+        latitude: lat,
+        longitude: lng,
+        sphere: resolveSphere(cachedFallback.sphere, lat),
+        elevation: isNumber(cachedFallback.elevation) ? cachedFallback.elevation : coerced.elevation,
+        timezone: isString(cachedFallback.timezone) ? cachedFallback.timezone : coerced.timezone
+      };
+    }
+  }
+  let endpoint;
+  if (customEndpoint) {
+    if (/\{(?:latitude|lat|longitude|lng|lon)\}/i.test(customEndpoint)) {
+      endpoint = customEndpoint.replace(/\{latitude\}/gi, encodeURIComponent(lat)).replace(/\{lat\}/gi, encodeURIComponent(lat)).replace(/\{longitude\}/gi, encodeURIComponent(lng)).replace(/\{lng\}/gi, encodeURIComponent(lng)).replace(/\{lon\}/gi, encodeURIComponent(lng));
+    } else {
+      const sep = customEndpoint.includes("?") ? "&" : "?";
+      endpoint = `${customEndpoint}${sep}latitude=${encodeURIComponent(lat)}&longitude=${encodeURIComponent(lng)}`;
+    }
+  } else {
+    endpoint = `${DEFAULT_REVERSE_GEO_ENDPOINT}?latitude=${lat}&longitude=${lng}&localityLanguage=en`;
+  }
+  try {
+    const timeout = isNumber(opts?.timeout) && opts.timeout > 0 ? opts.timeout : DEFAULT_REVERSE_GEO_TIMEOUT;
+    const maxBytes = isNumber(opts?.maxBytes) && opts.maxBytes > 0 ? opts.maxBytes : DEFAULT_REVERSE_GEO_MAX_BYTES;
+    const { fetchRequest: fetchRequest2 } = await getRequestModule2();
+    const data = await fetchRequest2(endpoint, {}, { timeout, maxBytes });
+    if (isObject(data)) {
+      const city = isText(data.city) ? data.city.trim() : isText(data.locality) ? data.locality.trim() : isText(data.principalSubdivision) ? data.principalSubdivision.trim() : void 0;
+      const country = isText(data.countryCode) ? data.countryCode.trim() : isText(data.countryName) ? data.countryName.trim() : void 0;
+      const result = assembleGeoConfig({ lat, lng }, {
+        city,
+        country,
+        elevation: coerced.elevation,
+        timezone: coerced.timezone
+      });
+      if (isText(city) || isText(country)) {
+        const cachePayload = assembleGeoConfig({ lat, lng }, {
+          city,
+          country
+        });
+        reverseGeoCache.set(fallbackKey, cachePayload);
+      }
+      return result;
+    }
+  } catch {
+  }
+  return coerced;
+}
+async function forwardGeocode(query, opts) {
+  const provider = opts?.provider ?? activeGeoProvider;
+  return provider && isFunction(provider.forwardGeocode) ? provider.forwardGeocode(query, opts) : null;
+}
 var resolveGeoCoordinates = async (input, opts = {}) => {
   const coerced = coerceGeo(input);
-  if (coerced && isNumber(coerced.latitude) && isNumber(coerced.longitude))
+  if (coerced && isNumber(coerced.latitude) && isNumber(coerced.longitude)) {
+    const shouldReverse = opts.reverse === true || opts.autoReverse === true;
+    if (shouldReverse && (!coerced.city || !coerced.country)) {
+      const reversed = await reverseGeocode(coerced, opts);
+      if (reversed) {
+        return {
+          ...reversed,
+          ...coerced,
+          city: isText(coerced.city) ? coerced.city : reversed.city,
+          country: isText(coerced.country) ? coerced.country : reversed.country,
+          lat: coerced.latitude,
+          lng: coerced.longitude,
+          latitude: coerced.latitude,
+          longitude: coerced.longitude
+        };
+      }
+    }
     return {
       ...coerced,
       lat: coerced.latitude,
       lng: coerced.longitude
     };
+  }
   const stashed = opts.refresh === true ? void 0 : getStashedGeo(opts);
   if (stashed && isNumber(stashed.latitude) && isNumber(stashed.longitude))
     return {
@@ -3053,102 +3273,37 @@ var resolveGeoCoordinates = async (input, opts = {}) => {
   }
   return null;
 };
-function haversineDistance(from, to, unit = "km") {
-  const c1 = coerceGeo(from);
-  const c2 = coerceGeo(to);
-  if (!c1 || !c2 || !isNumber(c1.latitude) || !isNumber(c1.longitude) || !isNumber(c2.latitude) || !isNumber(c2.longitude)) {
-    return NaN;
-  }
-  const toRad = Math.PI / 180;
-  const lat1 = c1.latitude * toRad;
-  const lng1 = c1.longitude * toRad;
-  const lat2 = c2.latitude * toRad;
-  const lng2 = c2.longitude * toRad;
-  const dLat = lat2 - lat1;
-  const dLng = lng2 - lng1;
-  const a = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
-  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
-  let radius;
-  if (unit === "miles") {
-    radius = 3958.7613;
-  } else if (unit === "m") {
-    radius = 63710088e-1;
-  } else {
-    radius = 6371.0088;
-  }
-  const dist = radius * c;
-  return unit === "m" ? Math.round(dist) : Math.round(dist * 1e3) / 1e3;
-}
-var resolveCivilTimezoneOffset = (tz, epochMs) => {
-  try {
-    if (typeof Temporal !== "undefined" && typeof Temporal.Instant?.fromEpochMilliseconds === "function") {
-      const zdt = Temporal.Instant.fromEpochMilliseconds(epochMs).toZonedDateTimeISO(tz);
-      return zdt.offsetNanoseconds / 6e10;
-    }
-    const parts = new Intl.DateTimeFormat("en-US", {
-      timeZone: tz,
-      timeZoneName: "longOffset",
-      year: "numeric"
-    }).formatToParts(new Date(epochMs));
-    const tzPart = parts.find((p) => p.type === "timeZoneName")?.value;
-    if (tzPart) {
-      if (tzPart === "GMT" || tzPart === "UTC")
-        return 0;
-      const match = tzPart.match(/GMT([+-])(\d{2}):(\d{2})/);
-      if (match) {
-        const sign = match[1] === "-" ? -1 : 1;
-        return sign * (parseInt(match[2], 10) * 60 + parseInt(match[3], 10));
-      }
-    }
-  } catch {
-  }
-  return void 0;
-};
-function solarOffset(coords, options) {
-  const geo = coerceGeo(coords);
-  if (!geo || !isNumber(geo.latitude) || !isNumber(geo.longitude) || isNaN(geo.latitude) || isNaN(geo.longitude)) {
-    return NaN;
-  }
-  const lng = geo.longitude;
-  const tz = options?.timeZone ?? (isReference(coords) ? coords.timezone ?? coords.tz : void 0) ?? geo.timezone;
-  const dateVal = options?.date ?? (isReference(coords) && isNumber(coords.epoch?.ms) ? coords.epoch.ms : Date.now());
-  const epochMs = typeof dateVal === "number" ? dateVal : isString(dateVal) ? Date.parse(dateVal) : isDate(dateVal) ? dateVal.getTime() : isReference(dateVal) && isNumber(dateVal?.epoch?.ms) ? dateVal.epoch.ms : Date.now();
-  if (!Number.isFinite(epochMs))
-    return NaN;
-  const offsetMinutes = isText(tz) ? resolveCivilTimezoneOffset(tz, epochMs) : void 0;
-  const refMeridian = offsetMinutes !== void 0 ? offsetMinutes / 60 * 15 : Math.round(lng / 15) * 15;
-  const deltaLng = lng - refMeridian;
-  let offsetMin = deltaLng * 4;
-  if (options?.apparent) {
-    const d = new Date(epochMs);
-    const startOfYear = Date.UTC(d.getUTCFullYear(), 0, 1);
-    const dayOfYear = Math.floor((epochMs - startOfYear) / 864e5) + 1;
-    const gamma = 2 * Math.PI / 365 * (dayOfYear - 1);
-    const eqTime = 229.18 * (75e-6 + 1868e-6 * Math.cos(gamma) - 0.032077 * Math.sin(gamma) - 0.014615 * Math.cos(2 * gamma) - 0.040849 * Math.sin(2 * gamma));
-    offsetMin += eqTime;
-  }
-  const unit = options?.unit ?? "minutes";
-  let res;
-  if (unit === "seconds") {
-    res = offsetMin * 60;
-  } else if (unit === "hours") {
-    res = offsetMin / 60;
-  } else {
-    res = offsetMin;
-  }
-  const precision = options?.precision ?? 2;
-  const factor = Math.pow(10, precision);
-  return Math.round(res * factor) / factor;
-}
 
 // src/index.ts
 init_mapper_library2();
 init_mapper_library();
 init_assertion_library();
+import {
+  resolveCulturalLocale
+} from "@magmacomputing/tempo-fns";
+var NON_GEO_CONTROL_KEYS = [
+  "setTimezone",
+  "setLocale",
+  "refresh",
+  "ttl",
+  "endpoint",
+  "timeout",
+  "maxBytes",
+  "highAccuracy",
+  "catch",
+  "debug",
+  "geo",
+  "provider",
+  "fallback",
+  "reverse",
+  "autoReverse"
+];
 var GeoPlugin = definePlugin({
   name: "geo",
   install(TempoClass, options) {
     const installedClass = TempoClass || this;
+    if (options?.provider)
+      setGeoProvider(options.provider);
     const getEffectiveOptions = (callSiteOpts, instance) => {
       const classOpts = installedClass.config?.pluginOptions?.geo;
       const instanceOpts = instance?.config?.pluginOptions?.geo;
@@ -3164,11 +3319,13 @@ var GeoPlugin = definePlugin({
         lookup: (opts) => geoLookup(getEffectiveOptions(opts)),
         resolve: (target, opts) => resolveGeoCoordinates(target, getEffectiveOptions(opts, target)),
         coerce: coerceGeo,
-        distance: haversineDistance,
-        solarOffset,
         stash: stashGeo,
         clear: clearStashedGeo,
         get: getStashedGeo,
+        setProvider: setGeoProvider,
+        getProvider: getGeoProvider,
+        reverse: (coords, opts) => reverseGeocode(coords, getEffectiveOptions(opts)),
+        forward: (query, opts) => forwardGeocode(query, getEffectiveOptions(opts)),
         server: serverGeoLocation,
         browser: geoLocation,
         get current() {
@@ -3185,6 +3342,7 @@ var GeoPlugin = definePlugin({
     TempoClass.prototype.geoLocate = async function(opts) {
       const effectiveOpts = getEffectiveOptions(opts, this);
       const setTimezone = effectiveOpts?.setTimezone !== false;
+      const setLocale = effectiveOpts?.setLocale ?? true;
       const coords = await resolveGeoCoordinates(this, effectiveOpts);
       if (coords) {
         const existingGeo = isObject(this.config.geo) ? this.config.geo : {};
@@ -3196,7 +3354,7 @@ var GeoPlugin = definePlugin({
         const callSiteGeo = coerceGeo(opts) ?? {};
         if (isObject(opts)) {
           for (const key of Object.keys(opts)) {
-            if (isSafeKey(key) && !["setTimezone", "refresh", "ttl", "endpoint", "timeout", "catch", "debug", "geo"].includes(key)) {
+            if (isSafeKey(key) && !NON_GEO_CONTROL_KEYS.includes(key)) {
               if (!GEO_PROPERTIES.includes(key))
                 customKeys[key] = opts[key];
             }
@@ -3209,17 +3367,20 @@ var GeoPlugin = definePlugin({
           ...isNumber(preservedElevation) ? { elevation: preservedElevation } : {},
           ...callSiteGeo
         };
-        if (isNumber(mergedGeo.latitude)) mergedGeo.latitude = Math.round(mergedGeo.latitude * 1e3) / 1e3;
-        if (isNumber(mergedGeo.longitude)) mergedGeo.longitude = Math.round(mergedGeo.longitude * 1e3) / 1e3;
-        if (!mergedGeo.sphere && isNumber(mergedGeo.latitude)) {
-          mergedGeo.sphere = mergedGeo.latitude > 1e-3 ? "north" : mergedGeo.latitude < -1e-3 ? "south" : "equator";
-        }
+        const lat = mergedGeo.latitude;
+        const lng = mergedGeo.longitude;
+        if (isNumber(lat)) mergedGeo.latitude = Math.round(lat * 1e3) / 1e3;
+        if (isNumber(lng)) mergedGeo.longitude = Math.round(lng * 1e3) / 1e3;
+        if (!mergedGeo.sphere && isNumber(lat))
+          mergedGeo.sphere = lat > 1e-3 ? "north" : lat < -1e-3 ? "south" : "equator";
         let instance = this;
         const targetTz = mergedGeo.timezone;
         if (setTimezone && isString(targetTz) && !isEmpty(targetTz))
           instance = this.set({ timeZone: targetTz });
+        const targetLocale = mergedGeo.country || isString(setLocale) ? resolveCulturalLocale(this.locale ?? this.config.locale, mergedGeo.country, setLocale) : void 0;
         return new TempoClass(instance, {
           ...instance.config,
+          ...targetLocale ? { locale: targetLocale } : {},
           geo: (0, sdk_exports.deepFreeze)(mergedGeo),
           ...mergedGeo.sphere ? { sphere: mergedGeo.sphere } : {}
         });
@@ -3229,12 +3390,6 @@ var GeoPlugin = definePlugin({
     TempoClass.prototype.geoLookup = async function(opts) {
       return resolveGeoCoordinates(this, getEffectiveOptions(opts, this));
     };
-    TempoClass.prototype.geoDistance = function(other, unit) {
-      return haversineDistance(this, other, unit);
-    };
-    TempoClass.prototype.geoSolarOffset = function(options2) {
-      return solarOffset(this, options2);
-    };
   }
 });
 var geoPlugin = GeoPlugin;
@@ -3242,18 +3397,22 @@ var index_default = GeoPlugin;
 export {
   GEO_PROPERTIES,
   GeoPlugin,
+  NON_GEO_CONTROL_KEYS,
   clearStashedGeo,
   coerceGeo,
   index_default as default,
+  forwardGeocode,
   geoLocation,
   geoLookup,
   geoPlugin,
+  getGeoProvider,
   getStashedGeo,
-  haversineDistance,
+  resolveCulturalLocale,
   resolveGeoCoordinates,
+  reverseGeocode,
   serverGeoCoords,
   serverGeoLocation,
   serverMapHemisphere,
-  solarOffset,
+  setGeoProvider,
   stashGeo
 };