@reservamos/browser-analytics 1.1.8-alpha.0 → 1.1.8-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reservamos/browser-analytics",
-  "version": "1.1.8-alpha.0",
+  "version": "1.1.8-alpha.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reservamos/reservamos-browser-analytics.git"
@@ -74,7 +74,7 @@
   "devDependencies": {
     "@eslint/js": "^9.9.1",
     "@ianvs/prettier-plugin-sort-imports": "^4.3.1",
-    "@reservamos/js-api-client": "6.28.0",
+    "@reservamos/js-api-client": "6.28.1",
     "@types/eslint__js": "^8.42.3",
     "@types/jsdom": "^21.1.6",
     "@types/mixpanel-browser": "^2.50.0",

package/src/events/identify/identify.robustness.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import trackingLifecycle from '@/services/trackingLifecycle';
 import identify from './identify';
 
 const mocks = vi.hoisted(() => ({
@@ -8,6 +9,7 @@ const mocks = vi.hoisted(() => ({
   ready: vi.fn(),
   identify: vi.fn(),
   attach: vi.fn(),
+  people: vi.fn(),
   fingerprint: vi.fn(),
   validate: vi.fn(),
   error: vi.fn(),
@@ -26,6 +28,7 @@ vi.mock('@/services/mixpanel', () => ({
     isReady: mocks.ready,
     identify: mocks.identify,
     attachProperty: mocks.attach,
+    setPeopleProperties: mocks.people,
   },
 }));
 vi.mock('@/services/fingerprint', () => ({
@@ -60,30 +63,123 @@ describe('identify bounded local attempt', () => {
     vi.unstubAllGlobals();
   });
 
-  it('awaits the local profile and includes its ID before identifying', async () => {
-    let finish: (value: { id: string }) => void = () => undefined;
-    mocks.profile.mockReturnValue(
-      new Promise((resolve) => {
-        finish = resolve;
-      }),
+  it('submits and resolves before a two-second redirect despite a 2.5-second profile', async () => {
+    mocks.profile.mockImplementation(
+      () =>
+        new Promise((resolve) =>
+          setTimeout(() => resolve({ id: 'profile' }), 2500),
+        ),
     );
+    const properties = { email: 'test@example.com', firstName: 'Test' };
     let finished = false;
-    const pending = identify('user', { email: 'test@example.com' }).then(() => {
+    void identify('user', properties).then(() => {
       finished = true;
     });
     await vi.advanceTimersByTimeAsync(1);
-    expect(finished).toBe(false);
-    expect(mocks.identify).not.toHaveBeenCalled();
-    finish({ id: 'profile' });
-    await pending;
+    expect(finished).toBe(true);
     expect(mocks.identify).toHaveBeenCalledWith(
       'user',
-      expect.objectContaining({ reservamos_one_id: 'profile' }),
+      expect.objectContaining({ $email: 'test@example.com' }),
       expect.any(Function),
     );
-    expect(vi.getTimerCount()).toBe(0);
+    expect(mocks.people).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1999);
+    expect(mocks.identify).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(500);
+    expect(mocks.people).toHaveBeenCalledWith(
+      { reservamos_one_id: 'profile' },
+      expect.any(Function),
+    );
+    expect(mocks.identify).toHaveBeenCalledTimes(1);
+    expect(properties).toEqual({
+      email: 'test@example.com',
+      firstName: 'Test',
+    });
   });
 
+  it.each(['new-user', 'reinitialize'] as const)(
+    'suppresses late enrichment after %s',
+    async (transition) => {
+      let finish!: (value: { id: string }) => void;
+      let finishFingerprint!: (value: string) => void;
+      mocks.fingerprint.mockReturnValueOnce(
+        new Promise((resolve) => {
+          finishFingerprint = resolve;
+        }),
+      );
+      mocks.profile.mockReturnValueOnce(
+        new Promise((resolve) => {
+          finish = resolve;
+        }),
+      );
+      await identify('old-user');
+      if (transition === 'new-user') await identify('new-user');
+      else {
+        trackingLifecycle.beginInitialization();
+        trackingLifecycle.beginInitialization();
+      }
+      finish({ id: 'old-profile' });
+      finishFingerprint('old-fingerprint');
+      await vi.advanceTimersByTimeAsync(0);
+      expect(mocks.people).not.toHaveBeenCalled();
+      expect(mocks.attach).not.toHaveBeenCalled();
+    },
+  );
+
+  it('attaches current fingerprint once', async () => {
+    mocks.fingerprint.mockResolvedValue('current-fingerprint');
+    await identify('user');
+    await vi.advanceTimersByTimeAsync(0);
+    expect(mocks.attach).toHaveBeenCalledWith(
+      'Known Fingerprints',
+      'current-fingerprint',
+    );
+    expect(mocks.attach).toHaveBeenCalledTimes(1);
+  });
+  it('retains the created profile ID in background datalake payload without mutating input', async () => {
+    mocks.profile.mockResolvedValue({ id: 'created-profile' });
+    mocks.coordinates.mockReturnValue({ lat: 1, long: 2 });
+    const properties = {
+      email: 'test@example.com',
+      firstName: 'Test',
+      lastName: 'User',
+    };
+    await identify('user', properties);
+    await vi.advanceTimersByTimeAsync(0);
+    const request = fetchMock.mock.calls[0][1] as RequestInit;
+    expect(JSON.parse(request.body as string).profile_params).toEqual(
+      expect.objectContaining({
+        reservamos_one_id: 'created-profile',
+        distinct_id: 'user',
+        first_name: 'Test',
+        last_name: 'User',
+      }),
+    );
+    expect(properties).toEqual({
+      email: 'test@example.com',
+      firstName: 'Test',
+      lastName: 'User',
+    });
+  });
+  it('does not identify an old user after readiness belongs to a replacement init', async () => {
+    trackingLifecycle.beginInitialization();
+    mocks.ready.mockReturnValue(false);
+    const pending = identify('old-user');
+    trackingLifecycle.beginInitialization();
+    mocks.ready.mockReturnValue(true);
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    await pending;
+    expect(mocks.identify).not.toHaveBeenCalled();
+  });
+  it('does not start optional requests after the attempt is superseded before their microtask', async () => {
+    const pending = identify('old-user');
+    await Promise.resolve();
+    trackingLifecycle.beginInitialization();
+    await pending;
+    await vi.advanceTimersByTimeAsync(0);
+    expect(mocks.profile).not.toHaveBeenCalled();
+    expect(mocks.fingerprint).not.toHaveBeenCalled();
+  });
   it('runs readiness once and removes its listener', async () => {
     mocks.ready.mockReturnValue(false);
     const remove = vi.spyOn(window, 'removeEventListener');
@@ -94,6 +190,7 @@ describe('identify bounded local attempt', () => {
     await pending;
     expect(mocks.identify).toHaveBeenCalledTimes(1);
     expect(remove).toHaveBeenCalledWith('Tracker Ready', expect.any(Function));
+    await vi.advanceTimersByTimeAsync(0);
     expect(vi.getTimerCount()).toBe(0);
   });
 
@@ -141,6 +238,7 @@ describe('identify bounded local attempt', () => {
   it('continues after profile rejection with controlled diagnostics', async () => {
     mocks.profile.mockRejectedValue(new Error('private@example.com'));
     await identify('private-id');
+    await vi.advanceTimersByTimeAsync(0);
     expect(mocks.identify).toHaveBeenCalledTimes(1);
     expect(mocks.error).toHaveBeenCalledWith(
       'Identify',
@@ -171,6 +269,7 @@ describe('identify bounded local attempt', () => {
     mocks.coordinates.mockReturnValue({ lat: 1, long: 2 });
     fetchMock.mockReturnValue(new Promise(() => undefined));
     await identify('user');
+    await vi.advanceTimersByTimeAsync(0);
     expect(fetchMock).toHaveBeenCalledWith(
       'https://example.test/api/v1/datalake/identify',
       expect.objectContaining({

package/src/events/identify/identify.ts

@@ -4,6 +4,7 @@ import configService from '@/services/config';
 import { getFingerprintForIdentify } from '@/services/fingerprint';
 import geolocationService from '@/services/geolocation';
 import mixpanelService from '@/services/mixpanel';
+import trackingLifecycle from '@/services/trackingLifecycle';
 import validatorService from '@/services/validator';
 import {
   createIdentifyReporter,
@@ -15,6 +16,7 @@ import { DefaultProperties } from './identifySchema';
 
 const KNOWN_PROPERTIES = ['firstName', 'lastName', 'email', 'phone'];
 const FINGERPRINT_PROPERTY = 'Known Fingerprints';
+let latestAttempt = 0;
 
 export interface UserProperties
   extends DefaultProperties,
@@ -112,21 +114,87 @@ const identifyWithLocation = async (
   }
 };
 
+async function enrichProfileAndLocation(
+  userId: string,
+  properties: UserProperties,
+  isActive: () => boolean,
+  report: IdentifyReporter,
+): Promise<void> {
+  const profile = await waitForIdentifyStage(
+    'profile',
+    3000,
+    (context) =>
+      isActive()
+        ? createAnonymousProfileForIdentify({ ...properties }, context.report)
+        : Promise.resolve(undefined),
+    report,
+  );
+  if (!isActive()) return;
+  const enriched = {
+    ...properties,
+    ...(profile && { reservamos_one_id: profile.id }),
+  };
+  if (profile) {
+    try {
+      mixpanelService.setPeopleProperties(
+        { reservamos_one_id: profile.id },
+        report,
+      );
+    } catch {
+      report('profile', 'failed');
+    }
+  }
+  void identifyWithLocation(userId, enriched, report);
+}
+
+async function enrichFingerprint(
+  isActive: () => boolean,
+  report: IdentifyReporter,
+): Promise<void> {
+  const fingerprint = await waitForIdentifyStage(
+    'fingerprint',
+    2000,
+    (context) =>
+      !isActive()
+        ? Promise.resolve('')
+        : getFingerprintForIdentify({
+            isActive: () => context.isActive() && isActive(),
+            report: context.report,
+          }),
+    report,
+  );
+  if (!fingerprint || !isActive()) return;
+  try {
+    mixpanelService.attachProperty(FINGERPRINT_PROPERTY, fingerprint);
+  } catch {
+    report('fingerprint', 'failed');
+  }
+}
+
 /**
- * Identifies a user with given properties and fingerprint.
+ * Applies identity and initial properties before optional enrichment.
  * @param {string} userId - The unique identifier for the user.
- * @param {UserProperties} properties - Optional user properties.
- * @returns {Promise<void>} Resolves after a bounded local attempt, not confirmed remote delivery.
+ * @param {UserProperties} properties - Optional user properties; never mutated.
+ * @returns {Promise<void>} Resolves after the local identity submission, not enrichment or remote delivery.
  */
 async function identify(
   userId: string,
   properties: UserProperties = {},
 ): Promise<void> {
+  const attempt = ++latestAttempt;
+  const input = { ...properties };
   const report = createIdentifyReporter();
-  if (!(await waitForIdentifyReady(report))) return;
+  const initialLifecycle = trackingLifecycle.capture();
+  if (
+    !(await waitForIdentifyReady(report)) ||
+    attempt !== latestAttempt ||
+    !initialLifecycle()
+  )
+    return;
+  let submitted = false;
   try {
     try {
-      validatorService.parseIdentifyProps(properties);
+      validatorService.parseIdentifyProps(input);
       if (!userId) {
         report('validation', 'invalid_input');
         return;
@@ -135,40 +203,22 @@ async function identify(
       report('validation', 'invalid_input');
       return;
     }
-    const anonymousProfile = await waitForIdentifyStage(
-      'profile',
-      3000,
-      (context) =>
-        createAnonymousProfileForIdentify({ ...properties }, context.report),
-      report,
-    );
-
-    if (anonymousProfile) {
-      properties.reservamos_one_id = anonymousProfile.id;
-    }
-    const mappedProps = mapProperties(properties);
     try {
-      mixpanelService.identify(userId, mappedProps, report);
+      mixpanelService.identify(userId, mapProperties(input), report);
     } catch {
       report('mixpanel', 'failed');
+      return;
     }
-    const fingerprint = await waitForIdentifyStage(
-      'fingerprint',
-      2000,
-      getFingerprintForIdentify,
-      report,
-    );
-    if (fingerprint) {
-      try {
-        mixpanelService.attachProperty(FINGERPRINT_PROPERTY, fingerprint);
-      } catch {
-        report('fingerprint', 'failed');
-      }
-    }
-  } catch {
-    report('mixpanel', 'failed');
+    const currentLifecycle = trackingLifecycle.capture();
+    const isActive = () => attempt === latestAttempt && currentLifecycle();
+    const scopedReport: IdentifyReporter = (...args) => {
+      if (isActive()) report(...args);
+    };
+    submitted = true;
+    void enrichProfileAndLocation(userId, input, isActive, scopedReport);
+    void enrichFingerprint(isActive, scopedReport);
   } finally {
-    void identifyWithLocation(userId, properties, report);
+    if (!submitted) void identifyWithLocation(userId, { ...input }, report);
   }
 }
 

package/src/events/passengersCreated/passengersCreatedSchema.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+import paymentAttemptSchema from '@/events/paymentAttempt/paymentAttemptSchema';
+import validatorService from '@/services/validator';
+import passengersCreatedSchema from './passengersCreatedSchema';
+
+const trip = {
+  'Departure Arrival': '2026-10-20T14:30:00',
+  'Departure Destination': 'Destination City',
+  'Departure Destination Terminal': 'Destination Terminal',
+  'Departure Line': 'Synthetic Line',
+  'Departure Origin': 'Origin City',
+  'Departure Origin Terminal': 'Origin Terminal',
+  'Departure Price': 450.5,
+  'Departure Route': 'Origin City - Destination City',
+  'Departure Stops': 1,
+  'Departure Time': '2026-10-20T08:00:00',
+  'Departure Transport Type': 'bus',
+  'Departure Transporter': 'Synthetic Transporter',
+  'Recommended Trip': false,
+};
+
+const passenger = {
+  'Passenger Birthdate': '1990-01-01',
+  'Passenger Seat': '12',
+  'Passenger Name': 'Synthetic Passenger',
+  'Passenger Document Type': 'passport',
+  'Passenger Document Id': 'X0000000',
+};
+
+const basePayload = {
+  'Trips': [trip],
+  'Passenger Count': 1,
+  'Trip Count': 1,
+  'Total': 450.5,
+  'product': 'web',
+  'Passengers': [passenger],
+};
+
+const paymentAttemptPayload = { ...basePayload, 'Payment Type': 'card' };
+
+const without = (source: object, key: string) =>
+  Object.fromEntries(Object.entries(source).filter(([name]) => name !== key));
+
+describe('passengersCreatedSchema', () => {
+  it('accepts a valid payload without Coupon', () => {
+    expect(passengersCreatedSchema.parse(basePayload)).toEqual(basePayload);
+  });
+
+  it('accepts a valid payload with Coupon', () => {
+    const payload = { ...basePayload, Coupon: 'PROMO10' };
+
+    expect(passengersCreatedSchema.parse(payload)).toEqual(payload);
+  });
+
+  it.each([10, true, null, {}])('rejects Coupon given as %j', (coupon) => {
+    expect(
+      passengersCreatedSchema.safeParse({ ...basePayload, Coupon: coupon })
+        .success,
+    ).toBe(false);
+  });
+
+  it('rejects an empty Coupon', () => {
+    expect(
+      passengersCreatedSchema.safeParse({ ...basePayload, Coupon: '' }).success,
+    ).toBe(false);
+  });
+
+  it('keeps rejecting keys outside the schema', () => {
+    const result = passengersCreatedSchema.safeParse({
+      ...basePayload,
+      Insurance: true,
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0]?.code).toBe('unrecognized_keys');
+  });
+
+  it('accepts the payload shape previously rejected for its Coupon key', () => {
+    expect(() =>
+      validatorService.parseEventProps('Passengers Created', {
+        ...basePayload,
+        Coupon: 'PROMO10',
+      }),
+    ).not.toThrow();
+  });
+
+  it('rejects a trip without Departure Arrival', () => {
+    expect(
+      passengersCreatedSchema.safeParse({
+        ...basePayload,
+        Trips: [without(trip, 'Departure Arrival')],
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe('checkout events with an empty passenger list', () => {
+  it.each([
+    ['Passengers Created', passengersCreatedSchema, basePayload],
+    ['Payment Attempt', paymentAttemptSchema, paymentAttemptPayload],
+  ] as const)(
+    '%s rejects an empty Passengers list',
+    (_name, schema, payload) => {
+      const result = schema.safeParse({ ...payload, Passengers: [] });
+
+      expect(result.success).toBe(false);
+      expect(result.error?.issues.map((issue) => issue.message)).toContain(
+        'Passengers must have at least 1 items',
+      );
+    },
+  );
+
+  it.each([
+    ['Passengers Created', passengersCreatedSchema, basePayload],
+    ['Payment Attempt', paymentAttemptSchema, paymentAttemptPayload],
+  ] as const)(
+    '%s accepts an omitted Passengers list',
+    (_name, schema, payload) => {
+      expect(schema.safeParse(without(payload, 'Passengers')).success).toBe(
+        true,
+      );
+    },
+  );
+});
+
+describe('Coupon parity with Payment Attempt', () => {
+  it.each(['PROMO10', '', 10])(
+    'gives the same verdict for Coupon %j',
+    (coupon) => {
+      const passengersCreated = passengersCreatedSchema.safeParse({
+        ...basePayload,
+        Coupon: coupon,
+      });
+      const paymentAttempt = paymentAttemptSchema.safeParse({
+        ...paymentAttemptPayload,
+        Coupon: coupon,
+      });
+
+      expect(passengersCreated.success).toBe(paymentAttempt.success);
+    },
+  );
+});

package/src/events/passengersCreated/passengersCreatedSchema.ts

@@ -1,5 +1,10 @@
 import { z } from 'zod';
-import { arrayField, intField, numberField } from '@/util/primitiveFields';
+import {
+  arrayField,
+  intField,
+  numberField,
+  stringField,
+} from '@/util/primitiveFields';
 import productValidation from '@/util/productValidation';
 import passengerSchema from '../sharedSchemas/passengerSchema';
 import tripSchema from '../sharedSchemas/tripSchema';
@@ -12,6 +17,7 @@ const passengersCreatedSchema = z
     'Total': numberField('Total'),
     'product': productValidation,
     'Passengers': arrayField(passengerSchema, 'Passengers', 1).optional(),
+    'Coupon': stringField('Coupon').optional(),
   })
   .strict();
 

package/src/events/purchaseConfirmation/purchaseConfirmation.integration.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, expect, it, vi } from 'vitest';
+import analytics from '@/index';
+import mixpanelService from '@/services/mixpanel';
+
+vi.mock('@/services/mixpanel', () => ({
+  default: {
+    isReady: vi.fn().mockReturnValue(true),
+    track: vi.fn(),
+    getMixpanelDistinctId: vi.fn().mockReturnValue('identified-user'),
+  },
+}));
+
+afterEach(() => {
+  vi.clearAllMocks();
+  localStorage.clear();
+});
+
+it('exposes the asynchronous wait through the public analytics facade', async () => {
+  localStorage.setItem(
+    'default_fingerprint_cache',
+    JSON.stringify({
+      fingerprint: 'cached-visitor',
+      expiresAt: Date.now() + 60000,
+    }),
+  );
+  await expect(analytics.identifiers.waitForFingerprintId()).resolves.toBe(
+    'cached-visitor',
+  );
+  expect(analytics.identifiers.getFingerprintId()).toBe('cached-visitor');
+});
+
+it('validates and submits confirmation product through the real tracking pipeline', async () => {
+  analytics.track.purchaseConfirmation({
+    'Operation Id': 'ORDER-1',
+    'Payment Status': 'confirmed',
+    'product': 'web',
+  });
+  await vi.waitFor(() =>
+    expect(mixpanelService.track).toHaveBeenCalledWith(
+      'Purchase Confirmation Viewed',
+      expect.objectContaining({
+        'Operation Id': 'ORDER-1',
+        'Payment Status': 'confirmed',
+        'product': 'web',
+      }),
+    ),
+  );
+  expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+});

package/src/events/purchaseConfirmation/purchaseConfirmation.test.ts

@@ -28,6 +28,22 @@ describe('purchaseConfirmationSchema', () => {
     expect(purchaseConfirmationSchema.parse(payload)).toEqual(payload);
   });
 
+  it.each(['confirmed', 'pending_pix'] as const)(
+    'preserves optional product for %s',
+    (status) => {
+      const payload = {
+        'Operation Id': 'MOB-123',
+        'Payment Status': status,
+        'product': 'web',
+      };
+      expect(purchaseConfirmationSchema.parse(payload)).toEqual(payload);
+      expect(
+        purchaseConfirmationSchema.safeParse({ ...payload, product: 'invalid' })
+          .success,
+      ).toBe(false);
+    },
+  );
+
   it('rejects a payload missing Operation Id', () => {
     expect(() =>
       purchaseConfirmationSchema.parse({ 'Payment Status': 'confirmed' }),
@@ -81,6 +97,7 @@ describe('trackPurchaseConfirmation', () => {
     const eventData = {
       'Operation Id': 'MOB-123',
       'Payment Status': 'confirmed' as const,
+      'product': 'web' as const,
     };
     const meta = { source: 'checkout' };
 

package/src/events/purchaseConfirmation/purchaseConfirmationSchema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import productValidation from '@/util/productValidation';
 
 const purchaseConfirmationSchema = z
   .object({
@@ -6,6 +7,7 @@ const purchaseConfirmationSchema = z
     'Payment Status': z.enum(['confirmed', 'pending_pix']),
     'Payment Type': z.string().optional(),
     'Total': z.number().optional(),
+    'product': productValidation.optional(),
   })
   .strict();
 

package/src/events/sharedSchemas/tripSchema.ts

@@ -1,10 +1,5 @@
 import { z } from 'zod';
-import {
-  dateField,
-  intField,
-  numberField,
-  stringField,
-} from '@/util/primitiveFields';
+import { dateField, numberField, stringField } from '@/util/primitiveFields';
 
 const tripSchema = z.object({
   'Departure Arrival': dateField('Departure Arrival'),
@@ -17,7 +12,7 @@ const tripSchema = z.object({
   'Departure Origin Terminal': stringField('Departure Origin Terminal'),
   'Departure Price': numberField('Departure Price'),
   'Departure Route': stringField('Departure Route'),
-  'Departure Stops': intField('Departure Stops'),
+  'Departure Stops': z.number().int(),
   'Departure Time': dateField('Departure Time'),
   'Departure Transport Type': stringField('Departure Transport Type'),
   'Departure Transporter': stringField('Departure Transporter'),
@@ -31,7 +26,7 @@ const tripSchema = z.object({
   'Return Origin Terminal': stringField('Return Origin Terminal').optional(),
   'Return Price': numberField('Return Price').optional(),
   'Return Route': stringField('Return Route').optional(),
-  'Return Stops': intField('Return Stops').optional(),
+  'Return Stops': z.number().int().optional(),
   'Return Time': dateField('Return Time').optional(),
   'Return Transport Type': stringField('Return Transport Type').optional(),
   'Return Transporter': stringField('Return Transporter').optional(),

package/src/index.ts

@@ -51,6 +51,7 @@ const analytics = {
   identify,
   identifiers: {
     getFingerprintId: fingerprintService.getCachedFingerprint,
+    waitForFingerprintId: fingerprintService.waitForFingerprintId,
     getDistinctId: mixpanelService.getMixpanelDistinctId,
   },
   profiles: {