@reservamos/browser-analytics 1.0.21 → 1.0.22-alpha.0

package/src/services/geolocation.ts

@@ -1,18 +1,157 @@
 import trackCustomEvent from '@/events/customEvent';
 import { isTrackerReady } from '@/init';
+import mixpanelService from '@/services/mixpanel';
 
-// Add interface for coordinates
 interface Coordinates {
   lat: number;
   long: number;
 }
 
-// Add state to store coordinates
+interface GeolocationCache {
+  lat: number;
+  long: number;
+  updatedAt: string;
+  accuracy?: number;
+}
+
+interface GeolocationTrackingData {
+  status: GeolocationStatus;
+  updatedAt: string;
+  accuracy?: number;
+  errorCode?: number;
+}
+
+/**
+ * Outcome of a geolocation request, sent to Mixpanel on the Geolocation Requested event
+ * and synced to the user profile.
+ *
+ * - `granted` — The browser returned fresh coordinates successfully.
+ * - `denied` — The user blocked location access (PERMISSION_DENIED).
+ * - `error` — The request failed for another reason (timeout, position unavailable, or geolocation unsupported).
+ * - `skipped_cache` — Permission was granted within the last 7 days; cached coordinates were reused without a new browser request.
+ */
+type GeolocationStatus = 'granted' | 'denied' | 'error' | 'skipped_cache';
+
 let currentCoordinates: Coordinates | null = null;
 
-// Constants for local storage keys and time limits
 const GEOLOCATION_PERMISSION_KEY = 'geolocationPermissionTimestamp';
+const GEOLOCATION_CACHE_KEY = 'geolocationCache';
+const GEOLOCATION_TRACK_EVENT = 'Geolocation Requested';
 const SEVEN_DAYS_IN_MS = 7 * 24 * 60 * 60 * 1000;
+/** Max wait for a high-accuracy position fix before the browser reports TIMEOUT. */
+const GEOLOCATION_REQUEST_TIMEOUT_MS = 10_000;
+const GEOLOCATION_OPTIONS: PositionOptions = {
+  enableHighAccuracy: true,
+  timeout: GEOLOCATION_REQUEST_TIMEOUT_MS,
+  maximumAge: 0,
+};
+
+/**
+ * Reads a value from localStorage, returning null when storage is unavailable.
+ * @param {string} key - Storage key to read.
+ * @returns {string | null} Stored value or null.
+ */
+function safeGetItem(key: string): string | null {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes a value to localStorage, ignoring failures when storage is unavailable.
+ * @param {string} key - Storage key to write.
+ * @param {string} value - Value to persist.
+ */
+function safeSetItem(key: string, value: string): void {
+  try {
+    localStorage.setItem(key, value);
+  } catch {
+    // Storage may be blocked (private mode, quota exceeded, etc.)
+  }
+}
+
+/**
+ * Converts a Unix timestamp to an ISO 8601 string.
+ * @param {number} timestamp - Unix timestamp in milliseconds.
+ * @returns {string} ISO 8601 formatted timestamp.
+ */
+function toISO(timestamp: number): string {
+  return new Date(timestamp).toISOString();
+}
+
+/**
+ * Validates parsed localStorage data against the geolocation cache schema.
+ * @param {unknown} value - Parsed JSON value.
+ * @returns {value is GeolocationCache} Whether the value is a valid cache entry.
+ */
+function isGeolocationCache(value: unknown): value is GeolocationCache {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const cache = value as Record<string, unknown>;
+
+  return (
+    typeof cache.lat === 'number' &&
+    typeof cache.long === 'number' &&
+    typeof cache.updatedAt === 'string' &&
+    (cache.accuracy === undefined || typeof cache.accuracy === 'number')
+  );
+}
+
+/**
+ * Loads persisted geolocation coordinates from local storage.
+ * @returns {GeolocationCache | null} Cached coordinates or null if unavailable or invalid.
+ */
+function loadCoordinatesFromStorage(): GeolocationCache | null {
+  const raw = safeGetItem(GEOLOCATION_CACHE_KEY);
+
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isGeolocationCache(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persists geolocation coordinates and their last update timestamp.
+ * @param {Coordinates} coords - The coordinates to persist.
+ * @param {string} updatedAt - ISO timestamp of the last update.
+ * @param {number} [accuracy] - Accuracy radius in meters reported by the browser.
+ */
+function saveCoordinatesToStorage(
+  coords: Coordinates,
+  updatedAt: string,
+  accuracy?: number,
+): void {
+  safeSetItem(
+    GEOLOCATION_CACHE_KEY,
+    JSON.stringify({
+      lat: coords.lat,
+      long: coords.long,
+      updatedAt,
+      ...(accuracy !== undefined && { accuracy }),
+    }),
+  );
+}
+
+/**
+ * Restores in-memory coordinates from local storage when available.
+ */
+function restoreCoordinatesFromStorage(): void {
+  const cache = loadCoordinatesFromStorage();
+
+  if (cache) {
+    currentCoordinates = { lat: cache.lat, long: cache.long };
+  }
+}
 
 /**
  * Checks if the geolocation permission timestamp is still valid.
@@ -32,60 +171,167 @@ function isPermissionTimestampValid(
  * @param {number} timestamp - The current timestamp to store.
  */
 function updatePermissionTimestamp(timestamp: number): void {
-  localStorage.setItem(GEOLOCATION_PERMISSION_KEY, timestamp.toString());
+  safeSetItem(GEOLOCATION_PERMISSION_KEY, timestamp.toString());
+}
+
+/**
+ * Maps a GeolocationPositionError to a geolocation status.
+ * Permission denial maps to `denied`; timeout and position unavailable map to `error`.
+ * @param {GeolocationPositionError} error - The geolocation error returned by the browser.
+ * @returns {GeolocationStatus} The normalized geolocation status.
+ */
+function getGeolocationStatus(
+  error: GeolocationPositionError,
+): GeolocationStatus {
+  return error.code === error.PERMISSION_DENIED ? 'denied' : 'error';
+}
+
+/**
+ * Builds the geolocation properties sent with the Geolocation Requested event.
+ * @param {GeolocationTrackingData} data - Geolocation outcome metadata.
+ * @returns {Record<string, string | number>} Properties to send to Mixpanel.
+ */
+function buildGeolocationEventProperties(
+  data: GeolocationTrackingData,
+): Record<string, string | number> {
+  const properties: Record<string, string | number> = {
+    'Geolocation Updated At': data.updatedAt,
+    'Geolocation Status': data.status,
+  };
+
+  if (data.accuracy !== undefined) {
+    properties['Geolocation Accuracy'] = data.accuracy;
+  }
+
+  if (data.errorCode !== undefined) {
+    properties['Geolocation Error Code'] = data.errorCode;
+  }
+
+  const coordinates = getCoordinates();
+  if (coordinates) {
+    properties.$latitude = coordinates.lat;
+    properties.$longitude = coordinates.long;
+  }
+
+  return properties;
+}
+
+/**
+ * Builds the geolocation properties synced to the Mixpanel user profile.
+ * Diagnostic fields such as accuracy and error codes are excluded.
+ * @param {GeolocationTrackingData} data - Geolocation outcome metadata.
+ * @returns {Record<string, string | number>} Profile properties to set on the user.
+ */
+function buildGeolocationProfileProperties(
+  data: GeolocationTrackingData,
+): Record<string, string | number> {
+  const properties: Record<string, string | number> = {
+    'Geolocation Updated At': data.updatedAt,
+    'Geolocation Status': data.status,
+  };
+
+  const coordinates = getCoordinates();
+  if (coordinates) {
+    properties.$latitude = coordinates.lat;
+    properties.$longitude = coordinates.long;
+  }
+
+  return properties;
+}
+
+/**
+ * Tracks the geolocation outcome and updates the Mixpanel user profile.
+ * @param {GeolocationTrackingData} data - Geolocation outcome metadata.
+ */
+function syncGeolocationToMixpanel(data: GeolocationTrackingData): void {
+  if (!isTrackerReady()) {
+    return;
+  }
+
+  const eventProperties = buildGeolocationEventProperties(data);
+  const profileProperties = buildGeolocationProfileProperties(data);
+  trackCustomEvent(GEOLOCATION_TRACK_EVENT, eventProperties);
+  mixpanelService.setPeopleProperties(profileProperties);
 }
 
 /**
- * Initializes geolocation service and retrieves user coordinates
- * @returns {Promise<Coordinates | null>} Promise resolving to coordinates or null if geolocation fails/is denied
+ * Initializes geolocation, requests coordinates when the cache window expired,
+ * and syncs the outcome to Mixpanel. The returned promise always resolves.
+ * @returns {Promise<Coordinates | null>} Cached or fresh coordinates, or null on failure.
  */
 function init(): Promise<Coordinates | null> {
+  restoreCoordinatesFromStorage();
+
   return new Promise((resolve) => {
-    const lastPermissionTimestamp = localStorage.getItem(
-      GEOLOCATION_PERMISSION_KEY,
-    );
+    const lastPermissionTimestamp = safeGetItem(GEOLOCATION_PERMISSION_KEY);
 
     if (isPermissionTimestampValid(lastPermissionTimestamp)) {
+      const cache = loadCoordinatesFromStorage();
+      const updatedAt = cache?.updatedAt
+        ?? (lastPermissionTimestamp
+          ? toISO(parseInt(lastPermissionTimestamp, 10))
+          : new Date().toISOString());
+
+      syncGeolocationToMixpanel({
+        status: 'skipped_cache',
+        updatedAt,
+        accuracy: cache?.accuracy,
+      });
       resolve(currentCoordinates);
       return;
     }
 
-    const GEOLOCATION_TRACK_EVENT = 'Geolocation Requested';
     const now = Date.now();
+    const updatedAt = toISO(now);
+
+    if (!navigator.geolocation?.getCurrentPosition) {
+      syncGeolocationToMixpanel({ status: 'error', updatedAt });
+      resolve(null);
+      return;
+    }
 
     navigator.geolocation.getCurrentPosition(
       (geolocation) => {
-        const { latitude: lat, longitude: long } = geolocation.coords;
+        const { latitude: lat, longitude: long, accuracy } = geolocation.coords;
         currentCoordinates = { lat, long };
+        saveCoordinatesToStorage(currentCoordinates, updatedAt, accuracy);
         updatePermissionTimestamp(now);
-        if (isTrackerReady()) {
-          trackCustomEvent(GEOLOCATION_TRACK_EVENT, {
-            geolocationAccepted: true,
-          });
-        }
+
+        syncGeolocationToMixpanel({
+          status: 'granted',
+          updatedAt,
+          accuracy,
+        });
         resolve(currentCoordinates);
       },
-      () => {
+      (error) => {
+        const status = getGeolocationStatus(error);
         updatePermissionTimestamp(now);
-        if (isTrackerReady()) {
-          trackCustomEvent(GEOLOCATION_TRACK_EVENT, {
-            geolocationAccepted: false,
-          });
-        }
+
+        syncGeolocationToMixpanel({
+          status,
+          updatedAt,
+          errorCode: error.code,
+        });
         resolve(null);
       },
+      GEOLOCATION_OPTIONS,
     );
   });
 }
 
 /**
- * Returns the currently cached coordinates or null if no coordinates are available
- * @returns {Coordinates | null} The cached coordinates or null if unavailable
+ * Returns the currently cached coordinates or null if no coordinates are available.
+ * @returns {Coordinates | null} The cached coordinates or null if unavailable.
  */
 function getCoordinates(): Coordinates | null {
   return currentCoordinates;
 }
 
+/**
+ * Geolocation service for tracking user location with caching support.
+ * Handles permission requests, coordinate retrieval, and analytics sync to Mixpanel.
+ */
 const geolocationService = {
   init,
   getCoordinates,

package/src/services/mixpanel.ts

@@ -62,6 +62,18 @@ function attachProperty(key: string, value: unknown): void {
   mixpanel.people.union(key, [value]);
 }
 
+/**
+ * Sets people properties for the current Mixpanel user without changing their distinct ID.
+ * @param {Record<string, unknown>} properties - Profile properties to set on the current user.
+ */
+function setPeopleProperties(properties: Record<string, unknown>): void {
+  if (!isReady()) {
+    return;
+  }
+
+  mixpanel.people.set(properties);
+}
+
 /**
  * Checks if the Mixpanel tracker is ready.
  * @returns {boolean} Returns true if the Mixpanel tracker is ready, otherwise false.
@@ -118,6 +130,7 @@ const mixpanelService = {
   track,
   identify,
   attachProperty,
+  setPeopleProperties,
   getMixpanelDistinctId,
 };
 

package/src/services/validator/validator.ts

@@ -1,5 +1,6 @@
 import { z, ZodError, ZodSchema } from 'zod';
 import { customEventSchema } from '@/events/customEvent/customEventSchema';
+import { geolocationSelectedSchema } from '@/events/geolocationSelected';
 import IdentifySchema from '@/events/identify/identifySchema';
 import { interestInHomeSchema } from '@/events/interestInHome';
 import { interestInSearchSchema } from '@/events/interestInSearch';
@@ -94,6 +95,7 @@ const eventSchemas: Record<string, z.ZodSchema> = {
   'View Results': viewResultsSchema,
   'Purchase Attempt': purchaseAttemptSchema,
   'Picked Departure': pickedDepartureSchema,
+  'Geolocation Selected': geolocationSelectedSchema,
 };
 
 type EventDataSchema = z.infer<