@reservamos/browser-analytics 1.1.1 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reservamos/browser-analytics",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reservamos/reservamos-browser-analytics.git"

package/src/init.ts

@@ -49,7 +49,7 @@ async function init(config: InitConfig) {
     console.error('Error initializing identification service:', error);
   }
 
-  geolocationService.init();
+  await geolocationService.init();
 
   configService.setEnvironment(isSandbox ? 'sandbox' : 'prod');
   coreApi.setConfig(configService.getCoreAPIConfig());

package/src/services/geolocation.test.ts

@@ -101,11 +101,13 @@ describe('geolocationService', () => {
       'Geolocation Updated At': updatedAt,
       'Geolocation Status': 'granted',
       'Geolocation Accuracy': 12,
-      $latitude: 19.4326,
-      $longitude: -99.1332,
+      latitude: 19.4326,
+      longitude: -99.1332,
+      geolocation_source: 'browser',
     };
 
     expect(coordinates).toEqual({ lat: 19.4326, long: -99.1332 });
+    expect(geolocationService.getGeolocationSource()).toBe('browser');
     expect(trackCustomEventMock).toHaveBeenCalledWith(
       'Geolocation Requested',
       expectedProperties,
@@ -113,8 +115,9 @@ describe('geolocationService', () => {
     expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
       'Geolocation Updated At': updatedAt,
       'Geolocation Status': 'granted',
-      $latitude: 19.4326,
-      $longitude: -99.1332,
+      latitude: 19.4326,
+      longitude: -99.1332,
+      geolocation_source: 'browser',
     });
 
     vi.useRealTimers();
@@ -142,6 +145,7 @@ describe('geolocationService', () => {
     };
 
     expect(coordinates).toBeNull();
+    expect(geolocationService.getGeolocationSource()).toBeNull();
     expect(trackCustomEventMock).toHaveBeenCalledWith(
       'Geolocation Requested',
       expectedProperties,
@@ -217,8 +221,9 @@ describe('geolocationService', () => {
       'Geolocation Updated At': updatedAt,
       'Geolocation Status': 'skipped_cache',
       'Geolocation Accuracy': 25,
-      $latitude: 19.4326,
-      $longitude: -99.1332,
+      latitude: 19.4326,
+      longitude: -99.1332,
+      geolocation_source: 'browser',
     };
 
     expect(coordinates).toEqual({ lat: 19.4326, long: -99.1332 });
@@ -229,33 +234,114 @@ describe('geolocationService', () => {
     expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
       'Geolocation Updated At': updatedAt,
       'Geolocation Status': 'skipped_cache',
-      $latitude: 19.4326,
-      $longitude: -99.1332,
+      latitude: 19.4326,
+      longitude: -99.1332,
+      geolocation_source: 'browser',
     });
   });
 
-  it('ignores malformed geolocation cache entries', async () => {
-    const permissionTimestamp = Date.now().toString();
-    const expectedUpdatedAt = new Date(Number(permissionTimestamp)).toISOString();
+  it('repairs legacy storage by clearing permission timestamp when coordinates are missing', async () => {
+    const updatedAt = '2026-05-07T21:19:00.000Z';
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(updatedAt));
 
-    localStorage.setItem('geolocationPermissionTimestamp', permissionTimestamp);
+    localStorage.setItem('geolocationPermissionTimestamp', Date.now().toString());
     localStorage.setItem('geolocationCache', '{ invalid json');
 
-    vi.stubGlobal('navigator', {
-      geolocation: {
-        getCurrentPosition: () => {
-          throw new Error('getCurrentPosition should not be called');
-        },
-      },
+    mockGeolocationSuccess({
+      coords: { latitude: 19.4326, longitude: -99.1332, accuracy: 15 },
+    } as GeolocationPosition);
+
+    const geolocationService = (await import('./geolocation')).default;
+    await geolocationService.init();
+
+    expect(localStorage.getItem('geolocationPermissionTimestamp')).toBe(
+      Date.parse(updatedAt).toString(),
+    );
+    expect(JSON.parse(localStorage.getItem('geolocationCache') ?? '')).toEqual({
+      lat: 19.4326,
+      long: -99.1332,
+      updatedAt,
+      accuracy: 15,
     });
 
+    vi.useRealTimers();
+  });
+
+  it('requests fresh geolocation when the permission cache is valid but coordinates are missing', async () => {
+    const updatedAt = '2026-05-07T21:19:00.000Z';
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(updatedAt));
+
+    localStorage.setItem('geolocationPermissionTimestamp', Date.now().toString());
+    localStorage.setItem('geolocationCache', '{ invalid json');
+
+    mockGeolocationSuccess({
+      coords: { latitude: 19.4326, longitude: -99.1332, accuracy: 15 },
+    } as GeolocationPosition);
+
     const geolocationService = (await import('./geolocation')).default;
     const coordinates = await geolocationService.init();
 
-    expect(coordinates).toBeNull();
-    expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
-      'Geolocation Updated At': expectedUpdatedAt,
-      'Geolocation Status': 'skipped_cache',
-    });
+    expect(coordinates).toEqual({ lat: 19.4326, long: -99.1332 });
+    expect(trackCustomEventMock).toHaveBeenCalledWith(
+      'Geolocation Requested',
+      {
+        'Geolocation Updated At': updatedAt,
+        'Geolocation Status': 'granted',
+        'Geolocation Accuracy': 15,
+        latitude: 19.4326,
+        longitude: -99.1332,
+        geolocation_source: 'browser',
+      },
+    );
+
+    vi.useRealTimers();
+  });
+
+  it('requests fresh geolocation when the permission cache is older than one hour', async () => {
+    const updatedAt = '2026-05-07T21:19:00.000Z';
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(updatedAt));
+
+    const expiredPermissionTimestamp = (
+      Date.parse(updatedAt) - 60 * 60 * 1000 - 1
+    ).toString();
+
+    localStorage.setItem(
+      'geolocationPermissionTimestamp',
+      expiredPermissionTimestamp,
+    );
+    localStorage.setItem(
+      'geolocationCache',
+      JSON.stringify({
+        lat: 19.4326,
+        long: -99.1332,
+        updatedAt: '2026-05-07T20:00:00.000Z',
+        accuracy: 25,
+      }),
+    );
+
+    mockGeolocationSuccess({
+      coords: { latitude: 20.9674, longitude: -89.5926, accuracy: 8 },
+    } as GeolocationPosition);
+
+    const geolocationService = (await import('./geolocation')).default;
+    const coordinates = await geolocationService.init();
+
+    expect(coordinates).toEqual({ lat: 20.9674, long: -89.5926 });
+    expect(trackCustomEventMock).toHaveBeenCalledWith(
+      'Geolocation Requested',
+      {
+        'Geolocation Updated At': updatedAt,
+        'Geolocation Status': 'granted',
+        'Geolocation Accuracy': 8,
+        latitude: 20.9674,
+        longitude: -89.5926,
+        geolocation_source: 'browser',
+      },
+    );
+
+    vi.useRealTimers();
   });
 });

package/src/services/geolocation.ts

@@ -14,11 +14,20 @@ interface GeolocationCache {
   accuracy?: number;
 }
 
+/**
+ * Origin of the coordinates attached to geolocation events and profiles.
+ * - `browser` — Coordinates from the Geolocation API or a prior browser session cache.
+ */
+type GeolocationSource = 'browser';
+
 interface GeolocationTrackingData {
   status: GeolocationStatus;
   updatedAt: string;
+  lat?: number;
+  long?: number;
   accuracy?: number;
   errorCode?: number;
+  source?: GeolocationSource;
 }
 
 /**
@@ -28,16 +37,17 @@ interface GeolocationTrackingData {
  * - `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.
+ * - `skipped_cache` — Permission was granted within the last hour; cached coordinates were reused without a new browser request.
  */
 type GeolocationStatus = 'granted' | 'denied' | 'error' | 'skipped_cache';
 
 let currentCoordinates: Coordinates | null = null;
+let currentSource: GeolocationSource | null = null;
 
 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;
+const ONE_HOUR_IN_MS = 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 = {
@@ -72,6 +82,18 @@ function safeSetItem(key: string, value: string): void {
   }
 }
 
+/**
+ * Removes a value from localStorage, ignoring failures when storage is unavailable.
+ * @param {string} key - Storage key to remove.
+ */
+function safeRemoveItem(key: string): void {
+  try {
+    localStorage.removeItem(key);
+  } 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.
@@ -150,6 +172,7 @@ function restoreCoordinatesFromStorage(): void {
 
   if (cache) {
     currentCoordinates = { lat: cache.lat, long: cache.long };
+    currentSource = 'browser';
   }
 }
 
@@ -163,7 +186,7 @@ function isPermissionTimestampValid(
 ): boolean {
   if (!lastPermissionTimestamp) return false;
   const now = Date.now();
-  return now - parseInt(lastPermissionTimestamp, 10) < SEVEN_DAYS_IN_MS;
+  return now - parseInt(lastPermissionTimestamp, 10) < ONE_HOUR_IN_MS;
 }
 
 /**
@@ -174,6 +197,21 @@ function updatePermissionTimestamp(timestamp: number): void {
   safeSetItem(GEOLOCATION_PERMISSION_KEY, timestamp.toString());
 }
 
+/**
+ * Repairs inconsistent localStorage left by older SDK versions that persisted a
+ * permission timestamp even when coordinates were never cached (e.g. after deny or error).
+ * Runs automatically on init so users do not need to clear storage after upgrading.
+ */
+function repairLegacyGeolocationStorage(): void {
+  if (!safeGetItem(GEOLOCATION_PERMISSION_KEY)) {
+    return;
+  }
+
+  if (!loadCoordinatesFromStorage()) {
+    safeRemoveItem(GEOLOCATION_PERMISSION_KEY);
+  }
+}
+
 /**
  * Maps a GeolocationPositionError to a geolocation status.
  * Permission denial maps to `denied`; timeout and position unavailable map to `error`.
@@ -207,10 +245,17 @@ function buildGeolocationEventProperties(
     properties['Geolocation Error Code'] = data.errorCode;
   }
 
-  const coordinates = getCoordinates();
-  if (coordinates) {
-    properties.$latitude = coordinates.lat;
-    properties.$longitude = coordinates.long;
+  if (
+    (data.status === 'granted' || data.status === 'skipped_cache') &&
+    data.lat !== undefined &&
+    data.long !== undefined
+  ) {
+    properties.latitude = data.lat;
+    properties.longitude = data.long;
+  }
+
+  if (data.source !== undefined) {
+    properties.geolocation_source = data.source;
   }
 
   return properties;
@@ -230,10 +275,17 @@ function buildGeolocationProfileProperties(
     'Geolocation Status': data.status,
   };
 
-  const coordinates = getCoordinates();
-  if (coordinates) {
-    properties.$latitude = coordinates.lat;
-    properties.$longitude = coordinates.long;
+  if (
+    (data.status === 'granted' || data.status === 'skipped_cache') &&
+    data.lat !== undefined &&
+    data.long !== undefined
+  ) {
+    properties.latitude = data.lat;
+    properties.longitude = data.long;
+  }
+
+  if (data.source !== undefined) {
+    properties.geolocation_source = data.source;
   }
 
   return properties;
@@ -260,6 +312,7 @@ function syncGeolocationToMixpanel(data: GeolocationTrackingData): void {
  * @returns {Promise<Coordinates | null>} Cached or fresh coordinates, or null on failure.
  */
 function init(): Promise<Coordinates | null> {
+  repairLegacyGeolocationStorage();
   restoreCoordinatesFromStorage();
 
   return new Promise((resolve) => {
@@ -267,18 +320,19 @@ function init(): Promise<Coordinates | null> {
 
     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;
+
+      if (cache) {
+        syncGeolocationToMixpanel({
+          status: 'skipped_cache',
+          updatedAt: cache.updatedAt,
+          lat: cache.lat,
+          long: cache.long,
+          accuracy: cache.accuracy,
+          source: 'browser',
+        });
+        resolve(currentCoordinates);
+        return;
+      }
     }
 
     const now = Date.now();
@@ -294,19 +348,22 @@ function init(): Promise<Coordinates | null> {
       (geolocation) => {
         const { latitude: lat, longitude: long, accuracy } = geolocation.coords;
         currentCoordinates = { lat, long };
+        currentSource = 'browser';
         saveCoordinatesToStorage(currentCoordinates, updatedAt, accuracy);
         updatePermissionTimestamp(now);
 
         syncGeolocationToMixpanel({
           status: 'granted',
           updatedAt,
+          lat,
+          long,
           accuracy,
+          source: 'browser',
         });
         resolve(currentCoordinates);
       },
       (error) => {
         const status = getGeolocationStatus(error);
-        updatePermissionTimestamp(now);
 
         syncGeolocationToMixpanel({
           status,
@@ -328,6 +385,14 @@ function getCoordinates(): Coordinates | null {
   return currentCoordinates;
 }
 
+/**
+ * Returns the source of the currently cached coordinates, or null when unavailable.
+ * @returns {GeolocationSource | null} The geolocation source or null if no coordinates are cached.
+ */
+function getGeolocationSource(): GeolocationSource | null {
+  return currentSource;
+}
+
 /**
  * Geolocation service for tracking user location with caching support.
  * Handles permission requests, coordinate retrieval, and analytics sync to Mixpanel.
@@ -335,6 +400,7 @@ function getCoordinates(): Coordinates | null {
 const geolocationService = {
   init,
   getCoordinates,
+  getGeolocationSource,
 };
 
 export default geolocationService;

package/src/track.ts

@@ -125,9 +125,13 @@ export async function trackEvent(
     const fingerprint = await fingerprintService.getFingerprint(cacheOnly);
     const defaultCoordinates: Record<string, string | number> = {};
     const coordinates = geolocationService.getCoordinates();
+    const geolocationSource = geolocationService.getGeolocationSource();
     if (coordinates) {
-      defaultCoordinates.$latitude = coordinates.lat;
-      defaultCoordinates.$longitude = coordinates.long;
+      defaultCoordinates.latitude = coordinates.lat;
+      defaultCoordinates.longitude = coordinates.long;
+    }
+    if (geolocationSource) {
+      defaultCoordinates.geolocation_source = geolocationSource;
     }
     const defaultProperties = {
       'User Fingerprint': fingerprint,