@cocreate/utils 1.44.2 → 1.44.3

package/src/cloudProviders.js

@@ -0,0 +1,150 @@
+/**
+ * Comprehensive Cloud Provider Registry (ESM)
+ * Maps infrastructure probes (AWS, GCP, Azure, DigitalOcean, OCI, Hetzner, Vultr, Equinix)
+ * to exact geographical coordinates (lat/lng), country, and region IDs.
+ */
+export const cloudProviders = [
+    // AWS Regions
+    { provider: 'aws', region: 'us-east-1', name: 'N. Virginia', country: 'US', lat: 38.9489, lng: -77.4499 },
+    { provider: 'aws', region: 'us-east-2', name: 'Ohio', country: 'US', lat: 40.1089, lng: -82.9545 },
+    { provider: 'aws', region: 'us-west-1', name: 'N. California', country: 'US', lat: 37.3541, lng: -121.9552 },
+    { provider: 'aws', region: 'us-west-2', name: 'Oregon', country: 'US', lat: 45.8399, lng: -119.7006 },
+    { provider: 'aws', region: 'ca-central-1', name: 'Montreal', country: 'CA', lat: 45.5017, lng: -73.5673 },
+    { provider: 'aws', region: 'eu-central-1', name: 'Frankfurt', country: 'DE', lat: 50.1109, lng: 8.6821 },
+    { provider: 'aws', region: 'eu-west-1', name: 'Ireland', country: 'IE', lat: 53.3498, lng: -6.2603 },
+    { provider: 'aws', region: 'eu-west-2', name: 'London', country: 'GB', lat: 51.5074, lng: -0.1278 },
+    { provider: 'aws', region: 'eu-west-3', name: 'Paris', country: 'FR', lat: 48.8566, lng: 2.3522 },
+    { provider: 'aws', region: 'eu-north-1', name: 'Stockholm', country: 'SE', lat: 59.3293, lng: 18.0686 },
+    { provider: 'aws', region: 'eu-south-1', name: 'Milan', country: 'IT', lat: 45.4642, lng: 9.1900 },
+    { provider: 'aws', region: 'ap-northeast-1', name: 'Tokyo', country: 'JP', lat: 35.6762, lng: 139.6503 },
+    { provider: 'aws', region: 'ap-northeast-2', name: 'Seoul', country: 'KR', lat: 37.5665, lng: 126.9780 },
+    { provider: 'aws', region: 'ap-northeast-3', name: 'Osaka', country: 'JP', lat: 34.6937, lng: 135.5023 },
+    { provider: 'aws', region: 'ap-southeast-1', name: 'Singapore', country: 'SG', lat: 1.3521, lng: 103.8198 },
+    { provider: 'aws', region: 'ap-southeast-2', name: 'Sydney', country: 'AU', lat: -33.8688, lng: 151.2093 },
+    { provider: 'aws', region: 'ap-south-1', name: 'Mumbai', country: 'IN', lat: 19.0760, lng: 72.8777 },
+    { provider: 'aws', region: 'sa-east-1', name: 'São Paulo', country: 'BR', lat: -23.5505, lng: -46.6333 },
+    { provider: 'aws', region: 'af-south-1', name: 'Cape Town', country: 'ZA', lat: -33.9249, lng: 18.4241 },
+    { provider: 'aws', region: 'me-south-1', name: 'Bahrain', country: 'BH', lat: 26.0667, lng: 50.5577 },
+
+    // GCP Regions
+    { provider: 'gcp', region: 'us-central1', name: 'Iowa', country: 'US', lat: 41.2619, lng: -95.8608 },
+    { provider: 'gcp', region: 'us-east1', name: 'South Carolina', country: 'US', lat: 33.1960, lng: -80.0131 },
+    { provider: 'gcp', region: 'us-east4', name: 'N. Virginia', country: 'US', lat: 38.9489, lng: -77.4499 },
+    { provider: 'gcp', region: 'us-west1', name: 'Oregon', country: 'US', lat: 45.6018, lng: -121.1842 },
+    { provider: 'gcp', region: 'us-west2', name: 'Los Angeles', country: 'US', lat: 34.0522, lng: -118.2437 },
+    { provider: 'gcp', region: 'northamerica-northeast1', name: 'Montreal', country: 'CA', lat: 45.5017, lng: -73.5673 },
+    { provider: 'gcp', region: 'southamerica-east1', name: 'São Paulo', country: 'BR', lat: -23.5505, lng: -46.6333 },
+    { provider: 'gcp', region: 'europe-west1', name: 'Belgium', country: 'BE', lat: 50.4541, lng: 3.8258 },
+    { provider: 'gcp', region: 'europe-west2', name: 'London', country: 'GB', lat: 51.5074, lng: -0.1278 },
+    { provider: 'gcp', region: 'europe-west3', name: 'Frankfurt', country: 'DE', lat: 50.1109, lng: 8.6821 },
+    { provider: 'gcp', region: 'europe-west4', name: 'Eemshaven', country: 'NL', lat: 53.4373, lng: 6.8335 },
+    { provider: 'gcp', region: 'asia-east1', name: 'Taiwan', country: 'TW', lat: 24.0518, lng: 120.5161 },
+    { provider: 'gcp', region: 'asia-east2', name: 'Hong Kong', country: 'HK', lat: 22.3193, lng: 114.1694 },
+    { provider: 'gcp', region: 'asia-northeast1', name: 'Tokyo', country: 'JP', lat: 35.6762, lng: 139.6503 },
+    { provider: 'gcp', region: 'asia-northeast2', name: 'Osaka', country: 'JP', lat: 34.6937, lng: 135.5023 },
+    { provider: 'gcp', region: 'asia-southeast1', name: 'Singapore', country: 'SG', lat: 1.3521, lng: 103.8198 },
+    { provider: 'gcp', region: 'asia-south1', name: 'Mumbai', country: 'IN', lat: 19.0760, lng: 72.8777 },
+    { provider: 'gcp', region: 'australia-southeast1', name: 'Sydney', country: 'AU', lat: -33.8688, lng: 151.2093 },
+
+    // Azure Regions
+    { provider: 'azure', region: 'eastus', name: 'Virginia', country: 'US', lat: 37.3719, lng: -79.8164 },
+    { provider: 'azure', region: 'eastus2', name: 'Virginia 2', country: 'US', lat: 36.6681, lng: -78.3881 },
+    { provider: 'azure', region: 'westus', name: 'California', country: 'US', lat: 37.7833, lng: -122.4167 },
+    { provider: 'azure', region: 'westus2', name: 'Washington', country: 'US', lat: 47.2330, lng: -119.8520 },
+    { provider: 'azure', region: 'centralus', name: 'Iowa', country: 'US', lat: 41.5908, lng: -93.6208 },
+    { provider: 'azure', region: 'canadacentral', name: 'Toronto', country: 'CA', lat: 43.6532, lng: -79.3832 },
+    { provider: 'azure', region: 'brazilsouth', name: 'São Paulo', country: 'BR', lat: -23.5505, lng: -46.6333 },
+    { provider: 'azure', region: 'northeurope', name: 'Ireland', country: 'IE', lat: 53.3498, lng: -6.2603 },
+    { provider: 'azure', region: 'westeurope', name: 'Netherlands', country: 'NL', lat: 52.3676, lng: 4.9041 },
+    { provider: 'azure', region: 'ukwest', name: 'Cardiff', country: 'GB', lat: 51.4815, lng: -3.1791 },
+    { provider: 'azure', region: 'ukeast', name: 'London', country: 'GB', lat: 51.5074, lng: -0.1278 },
+    { provider: 'azure', region: 'francecentral', name: 'Paris', country: 'FR', lat: 48.8566, lng: 2.3522 },
+    { provider: 'azure', region: 'germanywestcentral', name: 'Frankfurt', country: 'DE', lat: 50.1109, lng: 8.6821 },
+    { provider: 'azure', region: 'japaneast', name: 'Tokyo', country: 'JP', lat: 35.6762, lng: 139.6503 },
+    { provider: 'azure', region: 'japanwest', name: 'Osaka', country: 'JP', lat: 34.6937, lng: 135.5023 },
+    { provider: 'azure', region: 'southeastasia', name: 'Singapore', country: 'SG', lat: 1.3521, lng: 103.8198 },
+    { provider: 'azure', region: 'australiaeast', name: 'New South Wales', country: 'AU', lat: -33.8688, lng: 151.2093 },
+    { provider: 'azure', region: 'centralindia', name: 'Pune', country: 'IN', lat: 18.5204, lng: 73.8567 },
+
+    // DigitalOcean Regions
+    { provider: 'digitalocean', region: 'nyc1', name: 'New York 1', country: 'US', lat: 40.7128, lng: -74.0060 },
+    { provider: 'digitalocean', region: 'nyc3', name: 'New York 3', country: 'US', lat: 40.7128, lng: -74.0060 },
+    { provider: 'digitalocean', region: 'sfo3', name: 'San Francisco', country: 'US', lat: 37.7749, lng: -122.4194 },
+    { provider: 'digitalocean', region: 'ams3', name: 'Amsterdam', country: 'NL', lat: 52.3676, lng: 4.9041 },
+    { provider: 'digitalocean', region: 'sgp1', name: 'Singapore', country: 'SG', lat: 1.3521, lng: 103.8198 },
+    { provider: 'digitalocean', region: 'lon1', name: 'London', country: 'GB', lat: 51.5074, lng: -0.1278 },
+    { provider: 'digitalocean', region: 'fra1', name: 'Frankfurt', country: 'DE', lat: 50.1109, lng: 8.6821 },
+    { provider: 'digitalocean', region: 'tor1', name: 'Toronto', country: 'CA', lat: 43.6532, lng: -79.3832 },
+    { provider: 'digitalocean', region: 'blr1', name: 'Bangalore', country: 'IN', lat: 12.9716, lng: 77.5946 },
+    { provider: 'digitalocean', region: 'syd1', name: 'Sydney', country: 'AU', lat: -33.8688, lng: 151.2093 },
+
+    // OCI Regions
+    { provider: 'oci', region: 'us-ashburn-1', name: 'Ashburn', country: 'US', lat: 39.0438, lng: -77.4874 },
+    { provider: 'oci', region: 'us-phoenix-1', name: 'Phoenix', country: 'US', lat: 33.4484, lng: -112.0740 },
+    { provider: 'oci', region: 'us-sanjose-1', name: 'San Jose', country: 'US', lat: 37.3382, lng: -121.8863 },
+    { provider: 'oci', region: 'ca-toronto-1', name: 'Toronto', country: 'CA', lat: 43.6532, lng: -79.3832 },
+    { provider: 'oci', region: 'sa-saopaulo-1', name: 'São Paulo', country: 'BR', lat: -23.5505, lng: -46.6333 },
+    { provider: 'oci', region: 'eu-frankfurt-1', name: 'Frankfurt', country: 'DE', lat: 50.1109, lng: 8.6821 },
+    { provider: 'oci', region: 'eu-zurich-1', name: 'Zurich', country: 'CH', lat: 47.3769, lng: 8.5417 },
+    { provider: 'oci', region: 'eu-amsterdam-1', name: 'Amsterdam', country: 'NL', lat: 52.3676, lng: 4.9041 },
+    { provider: 'oci', region: 'uk-london-1', name: 'London', country: 'GB', lat: 51.5074, lng: -0.1278 },
+    { provider: 'oci', region: 'ap-tokyo-1', name: 'Tokyo', country: 'JP', lat: 35.6762, lng: 139.6503 },
+    { provider: 'oci', region: 'ap-osaka-1', name: 'Osaka', country: 'JP', lat: 34.6937, lng: 135.5023 },
+    { provider: 'oci', region: 'ap-seoul-1', name: 'Seoul', country: 'KR', lat: 37.5665, lng: 126.9780 },
+    { provider: 'oci', region: 'ap-sydney-1', name: 'Sydney', country: 'AU', lat: -33.8688, lng: 151.2093 },
+    { provider: 'oci', region: 'ap-mumbai-1', name: 'Mumbai', country: 'IN', lat: 19.0760, lng: 72.8777 },
+    { provider: 'oci', region: 'me-jeddah-1', name: 'Jeddah', country: 'SA', lat: 21.5433, lng: 39.1728 },
+
+    // Hetzner Regions
+    { provider: 'hetzner', region: 'fsn1', name: 'Falkenstein', country: 'DE', lat: 50.4779, lng: 12.3713 },
+    { provider: 'hetzner', region: 'nbg1', name: 'Nuremberg', country: 'DE', lat: 49.4521, lng: 11.0767 },
+    { provider: 'hetzner', region: 'hel1', name: 'Helsinki', country: 'FI', lat: 60.1699, lng: 24.9384 },
+    { provider: 'hetzner', region: 'ash', name: 'Ashburn', country: 'US', lat: 39.0438, lng: -77.4874 },
+    { provider: 'hetzner', region: 'hil', name: 'Hillsboro', country: 'US', lat: 45.5229, lng: -122.9898 },
+    { provider: 'hetzner', region: 'sin', name: 'Singapore', country: 'SG', lat: 1.3521, lng: 103.8198 },
+
+    // Vultr Regions
+    { provider: 'vultr', region: 'ewr', name: 'New Jersey', country: 'US', lat: 40.7128, lng: -74.0060 },
+    { provider: 'vultr', region: 'ord', name: 'Chicago', country: 'US', lat: 41.8781, lng: -87.6298 },
+    { provider: 'vultr', region: 'dfw', name: 'Dallas', country: 'US', lat: 32.7767, lng: -96.7970 },
+    { provider: 'vultr', region: 'sea', name: 'Seattle', country: 'US', lat: 47.6062, lng: -122.3321 },
+    { provider: 'vultr', region: 'lax', name: 'Los Angeles', country: 'US', lat: 34.0522, lng: -118.2437 },
+    { provider: 'vultr', region: 'atl', name: 'Atlanta', country: 'US', lat: 33.7490, lng: -84.3880 },
+    { provider: 'vultr', region: 'mia', name: 'Miami', country: 'US', lat: 25.7617, lng: -80.1918 },
+    { provider: 'vultr', region: 'sjc', name: 'Silicon Valley', country: 'US', lat: 37.3382, lng: -121.8863 },
+    { provider: 'vultr', region: 'yto', name: 'Toronto', country: 'CA', lat: 43.6532, lng: -79.3832 },
+    { provider: 'vultr', region: 'sao', name: 'São Paulo', country: 'BR', lat: -23.5505, lng: -46.6333 },
+    { provider: 'vultr', region: 'ams', name: 'Amsterdam', country: 'NL', lat: 52.3676, lng: 4.9041 },
+    { provider: 'vultr', region: 'fra', name: 'Frankfurt', country: 'DE', lat: 50.1109, lng: 8.6821 },
+    { provider: 'vultr', region: 'lhr', name: 'London', country: 'GB', lat: 51.5074, lng: -0.1278 },
+    { provider: 'vultr', region: 'par', name: 'Paris', country: 'FR', lat: 48.8566, lng: 2.3522 },
+    { provider: 'vultr', region: 'sgp', name: 'Singapore', country: 'SG', lat: 1.3521, lng: 103.8198 },
+    { provider: 'vultr', region: 'nrt', name: 'Tokyo', country: 'JP', lat: 35.6762, lng: 139.6503 },
+    { provider: 'vultr', region: 'icn', name: 'Seoul', country: 'KR', lat: 37.5665, lng: 126.9780 },
+    { provider: 'vultr', region: 'syd', name: 'Sydney', country: 'AU', lat: -33.8688, lng: 151.2093 },
+    { provider: 'vultr', region: 'mel', name: 'Melbourne', country: 'AU', lat: -37.8136, lng: 144.9631 },
+    { provider: 'vultr', region: 'blr', name: 'Bangalore', country: 'IN', lat: 12.9716, lng: 77.5946 },
+    { provider: 'vultr', region: 'jnb', name: 'Johannesburg', country: 'ZA', lat: -26.2041, lng: 28.0473 },
+
+    // Equinix Regions
+    { provider: 'equinix', region: 'da', name: 'Dallas', country: 'US', lat: 32.7767, lng: -96.7970 },
+    { provider: 'equinix', region: 'ny', name: 'New York', country: 'US', lat: 40.7128, lng: -74.0060 },
+    { provider: 'equinix', region: 'sv', name: 'Silicon Valley', country: 'US', lat: 37.3382, lng: -121.8863 },
+    { provider: 'equinix', region: 'ch', name: 'Chicago', country: 'US', lat: 41.8781, lng: -87.6298 },
+    { provider: 'equinix', region: 'la', name: 'Los Angeles', country: 'US', lat: 34.0522, lng: -118.2437 },
+    { provider: 'equinix', region: 'se', name: 'Seattle', country: 'US', lat: 47.6062, lng: -122.3321 },
+    { provider: 'equinix', region: 'at', name: 'Atlanta', country: 'US', lat: 33.7490, lng: -84.3880 },
+    { provider: 'equinix', region: 'tr', name: 'Toronto', country: 'CA', lat: 43.6532, lng: -79.3832 },
+    { provider: 'equinix', region: 'sp', name: 'São Paulo', country: 'BR', lat: -23.5505, lng: -46.6333 },
+    { provider: 'equinix', region: 'fr', name: 'Frankfurt', country: 'DE', lat: 50.1109, lng: 8.6821 },
+    { provider: 'equinix', region: 'am', name: 'Amsterdam', country: 'NL', lat: 52.3676, lng: 4.9041 },
+    { provider: 'equinix', region: 'ld', name: 'London', country: 'GB', lat: 51.5074, lng: -0.1278 },
+    { provider: 'equinix', region: 'pa', name: 'Paris', country: 'FR', lat: 48.8566, lng: 2.3522 },
+    { provider: 'equinix', region: 'ma', name: 'Madrid', country: 'ES', lat: 40.4168, lng: -3.7038 },
+    { provider: 'equinix', region: 'ty', name: 'Tokyo', country: 'JP', lat: 35.6762, lng: 139.6503 },
+    { provider: 'equinix', region: 'sg', name: 'Singapore', country: 'SG', lat: 1.3521, lng: 103.8198 },
+    { provider: 'equinix', region: 'hk', name: 'Hong Kong', country: 'HK', lat: 22.3193, lng: 114.1694 },
+    { provider: 'equinix', region: 'sy', name: 'Sydney', country: 'AU', lat: -33.8688, lng: 151.2093 }
+];
+
+export default cloudProviders

package/src/createUpdate.js

@@ -1,35 +1,7 @@
 import { dotNotationToObject } from "./dotNotationToObject.js";
 import { objectToDotNotation } from "./objectToDotNotation.js";
 import { getValueFromObject } from "./getValueFromObject.js";
-
-function isEqualArray(arr1, arr2) {
-	if (arr1.length !== arr2.length) {
-		return false;
-	}
-	for (let i = 0; i < arr1.length; i++) {
-		if (!isEqualObject(arr1[i], arr2[i])) {
-			return false;
-		}
-	}
-	return true;
-}
-
-function isEqualObject(obj1, obj2) {
-	const keys1 = Object.keys(obj1);
-	const keys2 = Object.keys(obj2);
-
-	if (keys1.length !== keys2.length) {
-		return false;
-	}
-
-	for (const key of keys1) {
-		if (obj1[key] !== obj2[key]) {
-			return false;
-		}
-	}
-
-	return true;
-}
+import { isEqualArray, isEqualObject } from "./dataQuery.js";
 
 function dotNotationToObjectUpdate(data, object = {}) {
 	try {

package/src/dataQuery.js

@@ -1,7 +1,7 @@
 import { getValueFromObject } from "./getValueFromObject.js";
 import { isValidDate } from "./isValidDate.js";
 
-function isEqualArray(arr1, arr2) {
+export function isEqualArray(arr1, arr2) {
 	if (arr1.length !== arr2.length) {
 		return false;
 	}
@@ -13,7 +13,7 @@ function isEqualArray(arr1, arr2) {
 	return true;
 }
 
-function isEqualObject(obj1, obj2) {
+export function isEqualObject(obj1, obj2) {
 	const keys1 = Object.keys(obj1);
 	const keys2 = Object.keys(obj2);
 

package/src/getClientInfo.js

@@ -0,0 +1,357 @@
+/********************************************************************************
+ * Copyright (C) 2026 CoCreate LLC and Contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ ********************************************************************************/
+
+import getCountryLocation from './getCountryLocation.js';
+import cloudProviders from './cloudProviders.js';
+
+// Strict validation patterns for IPv4 and IPv6 addresses
+const IPV4_REGEX = /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/;
+const IPV6_REGEX = /^(?:[a-fA-F0-9]{1,4}:){7}[a-fA-F0-9]{1,4}$/;
+
+// Operational defaults and fallback configurations
+const DEFAULT_TIMEOUT_MS = 3000;
+const LOCAL_FALLBACK_IP = "127.0.0.1";
+const SESSION_STORAGE_KEY = "client_info";
+
+// Single environment flags
+const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+const isNode = typeof process !== "undefined" && process.versions && !!process.versions.node;
+
+// Single ordered list of rich JSON geolocation providers
+const PROVIDERS = [
+    {
+        name: "ipapi.co",
+        url: "https://ipapi.co/json/",
+        parser: (data) => ({
+            ip: data.ip,
+            city: data.city,
+            region: data.region,
+            country: data.country_name,
+            countryCode: data.country_code,
+            latitude: (data.latitude != null && data.latitude !== "") ? parseFloat(data.latitude) : null,
+            longitude: (data.longitude != null && data.longitude !== "") ? parseFloat(data.longitude) : null,
+            timezone: data.timezone,
+            org: data.org || data.asn,
+        })
+    },
+    {
+        name: "ip-api.com",
+        url: "https://ip-api.com/json/?fields=status,message,country,countryCode,region,regionName,city,lat,lon,timezone,isp,org,query",
+        parser: (data) => {
+            if (data.status !== "success") return null;
+            return {
+                ip: data.query,
+                city: data.city,
+                region: data.regionName,
+                country: data.country,
+                countryCode: data.countryCode,
+                latitude: (data.lat != null && data.lat !== "") ? parseFloat(data.lat) : null,
+                longitude: (data.lon != null && data.lon !== "") ? parseFloat(data.lon) : null,
+                timezone: data.timezone,
+                org: data.org || data.isp,
+            };
+        }
+    },
+    {
+        name: "ipwho.is",
+        url: "https://ipwho.is/",
+        parser: (data) => {
+            if (!data.success) return null;
+            return {
+                ip: data.ip,
+                city: data.city,
+                region: data.region,
+                country: data.country,
+                countryCode: data.country_code,
+                latitude: (data.latitude != null && data.latitude !== "") ? parseFloat(data.latitude) : null,
+                longitude: (data.longitude != null && data.longitude !== "") ? parseFloat(data.longitude) : null,
+                timezone: data.timezone?.id,
+                org: data.connection?.isp || data.connection?.org,
+            };
+        }
+    },
+    {
+        name: "my-ip.io",
+        url: "https://api.my-ip.io/v2/ip.json",
+        parser: (data) => {
+            if (!data || !data.success) return null;
+            return {
+                ip: data.ip,
+                city: data.city,
+                region: data.region,
+                country: data.country?.name,
+                countryCode: data.country?.code,
+                latitude: (data.location?.lat != null && data.location.lat !== "") ? parseFloat(data.location.lat) : null,
+                longitude: (data.location?.lon != null && data.location.lon !== "") ? parseFloat(data.location.lon) : null,
+                timezone: data.timeZone,
+                org: data.asn?.name,
+            };
+        }
+    }
+];
+
+/**
+ * Internal helper to perform fetch requests with an AbortSignal timeout.
+ */
+async function fetchWithTimeout(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: { "Accept": "application/json, text/plain, */*" }
+        });
+        clearTimeout(timeoutId);
+        return response;
+    } catch (err) {
+        clearTimeout(timeoutId);
+        throw err;
+    }
+}
+
+/**
+ * Internal helper to validate IPv4 and IPv6 strings.
+ */
+function isValidIP(ip) {
+    if (typeof ip !== "string") return false;
+    const cleanIp = ip.trim();
+    return IPV4_REGEX.test(cleanIp) || IPV6_REGEX.test(cleanIp);
+}
+
+/**
+ * Inspects node OS network interfaces to find a valid non-internal local IP.
+ */
+function getLocalNodeIP() {
+    if (!isNode) return null;
+    try {
+        const req = typeof __non_webpack_require__ !== "undefined" ? __non_webpack_require__ : require;
+        const os = req("os");
+        const interfaces = os.networkInterfaces();
+        for (const interfaceName of Object.keys(interfaces)) {
+            for (const iface of interfaces[interfaceName]) {
+                if (!iface.internal && iface.family === "IPv4" && iface.address) {
+                    return iface.address;
+                }
+            }
+        }
+    } catch (e) {
+        // Fallback gracefully if restricted
+    }
+    return null;
+}
+
+/**
+ * Resolves a raw client information object into concrete latitude, longitude, and ISO country code.
+ * Optimized path:
+ * 1. Direct valid coordinates -> Immediate return with continent added
+ * 2. Missing coordinates but region present -> Attempt cloud region match for lat/lon
+ * 3. Fallback -> Return getCountryLocation coordinates
+ *
+ * @param {Object|string} info - Client telemetry or location metadata
+ * @returns {{latitude: number, longitude: number, countryCode: string, continent: string}|null} Resolved location object
+ */
+export function resolveInfo(info) {
+    if (!info || typeof info !== 'object') return null;
+
+    const { latitude, longitude, countryCode, region } = info;
+    
+    // Fetch location data; use fallback empty object in case of undefined return
+    const countryLocation = getCountryLocation(countryCode) || {};
+
+    // 1. Direct path: Valid numeric coordinates present
+    if (latitude !== null && longitude !== null && latitude !== undefined && longitude !== undefined) {
+        return { 
+            latitude, 
+            longitude, 
+            countryCode, 
+            continent: countryLocation.continent || null
+        };
+    }
+
+    // 2. Region String Match Path: Try cloudProviders if coordinates are missing
+    if (region) {
+        const cleanRegion = String(region).trim().toLowerCase();
+        const match = cloudProviders.find(cloud =>
+            cloud.name && cloud.name.toLowerCase().includes(cleanRegion)
+        );
+
+        if (match) {
+            // If the cloud provider match has a specific country, update the continent reference
+            const matchCountryCode = match.country || countryCode;
+            const matchLocation = match.country ? (getCountryLocation(match.country) || {}) : countryLocation;
+            
+            return {
+                latitude: match.lat ?? match.latitude ?? null,
+                longitude: match.lng ?? match.longitude ?? null,
+                countryCode: matchCountryCode,
+                continent: matchLocation.continent || countryLocation.continent || null 
+            };
+        }
+    }
+
+    // 3. Ultimate Fallback: Use getCountryLocation coordinates
+    return {
+        latitude: countryLocation.latitude ?? countryLocation.lat ?? null,
+        longitude: countryLocation.longitude ?? countryLocation.lng ?? null,
+        countryCode: countryLocation.countryCode ?? countryLocation.country ?? countryCode,
+        continent: countryLocation.continent || null
+    };
+}
+
+/**
+ * Formats data into a normalized client information payload.
+ */
+function normalizeInfoPayload(rawData = {}, sourceProvider = "unknown", isPartial = false, isLocal = false) {
+    const payload = {
+        ip: rawData.ip || LOCAL_FALLBACK_IP,
+        city: rawData.city || null,
+        region: rawData.region || null,
+        country: rawData.country || null,
+        countryCode: rawData.countryCode || null,
+        latitude: typeof rawData.latitude === "number" && !isNaN(rawData.latitude) ? rawData.latitude : null,
+        longitude: typeof rawData.longitude === "number" && !isNaN(rawData.longitude) ? rawData.longitude : null,
+        timezone: rawData.timezone || null,
+        org: rawData.org || null,
+        source: sourceProvider,
+        isPartial,
+        isLocal,
+        timestamp: Date.now()
+    };
+
+    // Enhance and normalize the payload using the external fallback maps
+    const resolved = resolveInfo(payload);
+    
+    if (resolved) {
+        payload.latitude = resolved.latitude ?? payload.latitude;
+        payload.longitude = resolved.longitude ?? payload.longitude;
+        payload.continent = resolved.continent || null;
+        
+        if (resolved.countryCode) {
+            payload.countryCode = resolved.countryCode;
+        }
+    } else {
+        payload.continent = null;
+    }
+
+    return payload;
+}
+
+/**
+ * Internal resolver that attempts provider endpoints sequentially.
+ */
+async function fetchClientInfo(options = {}) {
+    const timeout = options.timeout || DEFAULT_TIMEOUT_MS;
+
+    // Single iteration loop over ordered JSON providers
+    for (const provider of PROVIDERS) {
+        try {
+            const res = await fetchWithTimeout(provider.url, timeout);
+            if (res.ok) {
+                const json = await res.json();
+                const parsed = provider.parser(json);
+
+                if (parsed && isValidIP(parsed.ip)) {
+                    const isPartial = Boolean(provider.isPartial || !parsed.city);
+                    return normalizeInfoPayload(parsed, provider.name, isPartial, false);
+                }
+            }
+        } catch (err) {
+            // Fail silently and try the next provider
+        }
+    }
+
+    // Local Interface Fallback if all external APIs fail
+    const localNodeIp = getLocalNodeIP();
+    const finalIp = localNodeIp || LOCAL_FALLBACK_IP;
+
+    return normalizeInfoPayload({ ip: finalIp }, localNodeIp ? "node:os" : "fallback", true, true);
+}
+
+// Single set of module-level references for active promise and resolved payload
+let cachedInfoPromise = null;
+let cachedInfoPayload = null;
+
+/**
+ * Single unified function to retrieve client IP, location, and network metadata.
+ * Returns the same in-memory object reference across calls.
+ * 
+ * @param {Object} [options]
+ * @param {number} [options.timeout=3000] Hard timeout limit per request (ms)
+ * @param {boolean} [options.bypassCache=false] Force a fresh network request
+ * @returns {Promise<Object>} Standardized location object
+ */
+export async function getClientInfo(options = {}) {
+    const { bypassCache = false } = options;
+
+    // 1. Return existing in-memory object reference if available
+    if (!bypassCache && cachedInfoPayload) {
+        return cachedInfoPayload;
+    }
+
+    // 2. Return active in-flight request promise if currently executing
+    if (!bypassCache && cachedInfoPromise) {
+        return cachedInfoPromise;
+    }
+
+    // 3. Rehydrate from browser sessionStorage across page refreshes
+    if (!bypassCache && isBrowser) {
+        try {
+            const stored = sessionStorage.getItem(SESSION_STORAGE_KEY);
+            if (stored) {
+                const parsed = JSON.parse(stored);
+                if (parsed && isValidIP(parsed.ip)) {
+                    cachedInfoPayload = parsed;
+                    return cachedInfoPayload;
+                }
+            }
+        } catch (e) {
+            // Fall back silently
+        }
+    }
+
+    // 4. Fetch fresh network data, assign to cachedInfoPayload, and persist to sessionStorage
+    cachedInfoPromise = fetchClientInfo(options).then((info) => {
+        cachedInfoPayload = info;
+        cachedInfoPromise = null;
+
+        if (isBrowser) {
+            try {
+                sessionStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify(info));
+            } catch (e) {
+                // Ignore storage errors
+            }
+        }
+        return cachedInfoPayload;
+    }).catch((err) => {
+        cachedInfoPromise = null;
+        throw err;
+    });
+
+    return cachedInfoPromise;
+}
+
+// Automatically listen for browser network reconnects to refresh location data
+if (isBrowser) {
+    window.addEventListener("online", () => {
+        getClientInfo({ bypassCache: true }).catch(() => {
+            // Suppress background reconnect error
+        });
+    });
+}
+
+export default getClientInfo;

package/src/getClockOffset.js

@@ -0,0 +1,46 @@
+/********************************************************************************
+ * Copyright (C) 2026 CoCreate and Contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ ********************************************************************************/
+
+let clockOffset = 0;
+const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+
+// Runs EXACTLY ONCE across your entire app load
+if (isBrowser) {
+  const t0 = Date.now();
+  fetch('/api/ping', { method: 'HEAD' })
+    .then((res) => {
+      const serverDateStr = res.headers.get('date');
+      if (serverDateStr) {
+        const t1 = Date.now();
+        const tServer = new Date(serverDateStr).getTime();
+        const latency = Math.floor((t1 - t0) / 2);
+        clockOffset = tServer - (t0 + latency);
+      }
+    })
+    .catch(() => {
+      clockOffset = 0;
+    });
+}
+
+/**
+ * Returns the cached time offset in milliseconds.
+ * Always 0 on the server (NTP-managed) or fallback.
+ */
+export function getClockOffset() {
+  return clockOffset;
+}