@reservamos/browser-analytics 1.1.0 → 1.1.2-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reservamos/browser-analytics",
-  "version": "1.1.0",
+  "version": "1.1.2-alpha.0",
   "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,8 +101,8 @@ describe('geolocationService', () => {
       'Geolocation Updated At': updatedAt,
       'Geolocation Status': 'granted',
       'Geolocation Accuracy': 12,
-      $latitude: 19.4326,
-      $longitude: -99.1332,
+      latitude: 19.4326,
+      longitude: -99.1332,
     };
 
     expect(coordinates).toEqual({ lat: 19.4326, long: -99.1332 });
@@ -113,8 +113,8 @@ describe('geolocationService', () => {
     expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
       'Geolocation Updated At': updatedAt,
       'Geolocation Status': 'granted',
-      $latitude: 19.4326,
-      $longitude: -99.1332,
+      latitude: 19.4326,
+      longitude: -99.1332,
     });
 
     vi.useRealTimers();
@@ -217,8 +217,8 @@ 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,
     };
 
     expect(coordinates).toEqual({ lat: 19.4326, long: -99.1332 });
@@ -229,33 +229,111 @@ 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,
     });
   });
 
-  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,
+      },
+    );
+
+    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,
+      },
+    );
+
+    vi.useRealTimers();
   });
 });

package/src/services/geolocation.ts

@@ -17,6 +17,8 @@ interface GeolocationCache {
 interface GeolocationTrackingData {
   status: GeolocationStatus;
   updatedAt: string;
+  lat?: number;
+  long?: number;
   accuracy?: number;
   errorCode?: number;
 }
@@ -28,7 +30,7 @@ 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';
 
@@ -37,7 +39,7 @@ let currentCoordinates: Coordinates | 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 +74,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.
@@ -163,7 +177,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 +188,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 +236,13 @@ 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;
   }
 
   return properties;
@@ -230,10 +262,13 @@ 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;
   }
 
   return properties;
@@ -260,6 +295,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 +303,18 @@ 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,
+        });
+        resolve(currentCoordinates);
+        return;
+      }
     }
 
     const now = Date.now();
@@ -300,13 +336,14 @@ function init(): Promise<Coordinates | null> {
         syncGeolocationToMixpanel({
           status: 'granted',
           updatedAt,
+          lat,
+          long,
           accuracy,
         });
         resolve(currentCoordinates);
       },
       (error) => {
         const status = getGeolocationStatus(error);
-        updatePermissionTimestamp(now);
 
         syncGeolocationToMixpanel({
           status,

package/src/services/mixpanel.ts

@@ -9,6 +9,13 @@ declare global {
 
 const MIXPANEL_DISTINCT_ID_CACHE_KEY = 'mp_distinct_id';
 
+/**
+ * Super property sent on every Mixpanel event. Fixed SDK marker; not configurable via the public API.
+ */
+const EVENT_SOURCE_SUPER_PROPERTY = {
+  'Event Source': 'sdk',
+} as const;
+
 /**
  * Initializes Mixpanel with the provided token and debug flag.
  * @param {string} mixpanelToken - The Mixpanel token used for authenticating API requests.
@@ -26,6 +33,7 @@ function init(
       debug,
       loaded: () => {
         window.mixpanel = mixpanel;
+        mixpanel.register({ ...EVENT_SOURCE_SUPER_PROPERTY });
         resolve();
       },
       ...(proxyUrl && { api_host: proxyUrl }),

package/src/track.ts

@@ -126,8 +126,8 @@ export async function trackEvent(
     const defaultCoordinates: Record<string, string | number> = {};
     const coordinates = geolocationService.getCoordinates();
     if (coordinates) {
-      defaultCoordinates.$latitude = coordinates.lat;
-      defaultCoordinates.$longitude = coordinates.long;
+      defaultCoordinates.latitude = coordinates.lat;
+      defaultCoordinates.longitude = coordinates.long;
     }
     const defaultProperties = {
       'User Fingerprint': fingerprint,