@reservamos/browser-analytics 1.1.8-alpha.1 → 1.1.8-alpha.3

package/src/services/mixpanel.ts

@@ -59,6 +59,7 @@ function init(
   return new Promise<void>((resolve) => {
     mixpanel.init(mixpanelToken, {
       debug,
+      batch_flush_interval_ms: 1000,
       loaded: () => {
         if (attempt !== initialization) {
           resolve();
@@ -105,21 +106,7 @@ function identify(
   trackingLifecycle.identify(userId);
   mixpanel.identify(userId);
   if (!updateCachedDistinctId(userId)) report?.('cache', 'unavailable');
-  if (!report) {
-    mixpanel.people.set(properties);
-    return;
-  }
-  const observer = observeIdentifyResult('people', report);
-  try {
-    mixpanel.people.set(properties, (response) => {
-      const status = typeof response === 'number' ? response : response?.status;
-      observer.complete(
-        status === 1 ? undefined : status === 0 ? 'failed' : 'unconfirmed',
-      );
-    });
-  } catch {
-    observer.complete('failed');
-  }
+  writePeopleProperties(properties, report);
 }
 
 /**
@@ -142,12 +129,51 @@ function attachProperty(key: string, value: unknown): void {
  * 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 {
+function setPeopleProperties(
+  properties: Record<string, unknown>,
+  report?: IdentifyReporter,
+  onAccepted?: () => void,
+): void {
   if (!isReady()) {
     return;
   }
 
-  mixpanel.people.set(properties);
+  writePeopleProperties(properties, report, onAccepted);
+}
+
+/** Restores people readiness only when the native persisted identity still matches. */
+function restorePeopleProperties(
+  userId: string,
+  properties: Record<string, unknown>,
+  report: IdentifyReporter,
+  onAccepted: () => void,
+): void {
+  if (!isReady() || mixpanel.get_distinct_id() !== userId) return;
+  mixpanel.identify(userId);
+  writePeopleProperties(properties, report, onAccepted);
+}
+
+function writePeopleProperties(
+  properties: Record<string, unknown>,
+  report?: IdentifyReporter,
+  onAccepted?: () => void,
+): void {
+  if (!report && !onAccepted) {
+    mixpanel.people.set(properties);
+    return;
+  }
+  const observer = report ? observeIdentifyResult('people', report) : undefined;
+  try {
+    mixpanel.people.set(properties, (response) => {
+      const status = typeof response === 'number' ? response : response?.status;
+      if (status === 1) onAccepted?.();
+      observer?.complete(
+        status === 1 ? undefined : status === 0 ? 'failed' : 'unconfirmed',
+      );
+    });
+  } catch {
+    observer?.complete('failed');
+  }
 }
 
 /**
@@ -178,7 +204,7 @@ function track(eventName: string, properties: Record<string, unknown>): void {
  * @returns {string | null} The live or cached distinct ID, or null when neither is available.
  */
 export const getMixpanelDistinctId = (): string | null => {
-  const distinctId = mixpanel?.get_distinct_id?.();
+  const distinctId = isReady() ? mixpanel.get_distinct_id() : null;
   if (distinctId) {
     updateCachedDistinctId(distinctId);
     return distinctId;
@@ -214,6 +240,7 @@ const mixpanelService = {
   identify,
   attachProperty,
   setPeopleProperties,
+  restorePeopleProperties,
   getMixpanelDistinctId,
 };
 

package/src/services/profileEnrichment.ts

@@ -0,0 +1,258 @@
+import type { IdentifyReporter } from '@/util/identifyAttempt';
+import { z } from 'zod';
+import {
+  createAnonymousProfileForIdentify,
+  prepareAnonymousProfileForIdentify,
+  requestPreparedAnonymousProfile,
+} from '@/profiles/createAnonymousProfile/createAnonymousProfile';
+import mixpanelService from '@/services/mixpanel';
+import trackingLifecycle from '@/services/trackingLifecycle';
+import {
+  createIdentifyReporter,
+  waitForIdentifyStage,
+} from '@/util/identifyAttempt';
+
+const STORAGE_KEY = 'reservamos_pending_profile_v1';
+const LIFETIME_MS = 10 * 60 * 1000;
+const MAX_ATTEMPTS = 3;
+const MAX_BYTES = 4096;
+const profileIdSchema = z.union([
+  z.string().min(1),
+  z.number().int().positive(),
+]);
+const requestSchema = z
+  .object({
+    identifier_key: z.enum(['email', 'phone']),
+    identifier_value: z.string().min(1),
+    identifiers: z.array(
+      z.object({ key: z.string().min(1), value: z.string().min(1) }).strict(),
+    ),
+    details: z.record(z.string()),
+  })
+  .strict();
+const pendingSchema = z
+  .object({
+    version: z.literal(1),
+    id: z.string().min(1),
+    userId: z.string().min(1),
+    scope: z.string().min(1),
+    expiresAt: z.number().int(),
+    attempts: z.number().int().min(1).max(MAX_ATTEMPTS),
+    request: requestSchema.optional(),
+    profileId: profileIdSchema.optional(),
+  })
+  .strict()
+  .refine((entry) => entry.request || entry.profileId);
+type PendingProfile = z.infer<typeof pendingSchema>;
+interface ProfileLink {
+  id: z.infer<typeof profileIdSchema>;
+}
+interface RecoveryScope {
+  project: string;
+  proxy?: string;
+  apiBaseUrl: string;
+  appName?: string;
+}
+let scope: string | undefined;
+let generation = 0;
+
+function remove(report: IdentifyReporter, id?: string): void {
+  try {
+    if (id) {
+      const stored = JSON.parse(
+        sessionStorage.getItem(STORAGE_KEY) || 'null',
+      ) as PendingProfile | null;
+      if (stored?.id !== id) return;
+    }
+    sessionStorage.removeItem(STORAGE_KEY);
+  } catch {
+    report('cache', 'unavailable');
+  }
+}
+
+function save(entry: PendingProfile, report: IdentifyReporter): boolean {
+  try {
+    const serialized = JSON.stringify(entry);
+    if (new Blob([serialized]).size > MAX_BYTES) {
+      remove(report);
+      report('cache', 'unavailable');
+      return false;
+    }
+    sessionStorage.setItem(STORAGE_KEY, serialized);
+    return true;
+  } catch {
+    remove(report);
+    report('cache', 'unavailable');
+    return false;
+  }
+}
+
+function read(report: IdentifyReporter): PendingProfile | undefined {
+  try {
+    const serialized = sessionStorage.getItem(STORAGE_KEY);
+    if (!serialized) return undefined;
+    if (new Blob([serialized]).size > MAX_BYTES) throw new Error();
+    const entry = pendingSchema.parse(JSON.parse(serialized));
+    if (
+      entry.expiresAt <= Date.now() ||
+      entry.expiresAt > Date.now() + LIFETIME_MS
+    ) {
+      remove(report);
+      return undefined;
+    }
+    return entry;
+  } catch {
+    remove(report);
+    report('cache', 'unavailable');
+    return undefined;
+  }
+}
+
+function currentUserIs(userId: string): boolean {
+  return (
+    mixpanelService.isReady() &&
+    mixpanelService.getMixpanelDistinctId() === userId
+  );
+}
+
+async function resolveProfile(
+  userId: string,
+  properties: Record<string, string | number | boolean | undefined>,
+  isCurrent: () => boolean,
+  report: IdentifyReporter,
+  entry?: PendingProfile,
+  recovering = false,
+): Promise<ProfileLink | undefined> {
+  if (!isCurrent()) return undefined;
+  const profile =
+    entry?.profileId !== undefined
+      ? { id: entry.profileId }
+      : await waitForIdentifyStage(
+          'profile',
+          3000,
+          (context) =>
+            isCurrent()
+              ? entry?.request
+                ? requestPreparedAnonymousProfile(entry.request)
+                : createAnonymousProfileForIdentify(
+                    { ...properties },
+                    context.report,
+                  )
+              : Promise.resolve(undefined),
+          report,
+        );
+  if (!isCurrent()) return undefined;
+  if (!profile) {
+    if (entry && entry.attempts >= MAX_ATTEMPTS) remove(report, entry.id);
+    return undefined;
+  }
+  const parsedId = profileIdSchema.safeParse(profile.id);
+  if (!parsedId.success) {
+    report('profile', 'failed');
+    return undefined;
+  }
+  const profileId = parsedId.data;
+  if (entry) save({ ...entry, request: undefined, profileId }, report);
+  const accepted = () => {
+    if (entry && isCurrent()) remove(report, entry.id);
+  };
+  try {
+    const properties = { reservamos_one_id: profileId };
+    if (recovering) {
+      mixpanelService.restorePeopleProperties(
+        userId,
+        properties,
+        report,
+        accepted,
+      );
+    } else if (entry) {
+      mixpanelService.setPeopleProperties(properties, report, accepted);
+    } else {
+      mixpanelService.setPeopleProperties(properties, report);
+    }
+  } catch {
+    report('profile', 'failed');
+  }
+  return { id: profileId };
+}
+
+/** Records the original normalized request while preserving the ordinary in-memory enrichment. */
+function enrich(
+  userId: string,
+  properties: Record<string, string | number | boolean | undefined>,
+  isActive: () => boolean,
+  report: IdentifyReporter,
+): Promise<ProfileLink | undefined> {
+  if (!isActive()) return Promise.resolve(undefined);
+  const attempt = ++generation;
+  let request: z.infer<typeof requestSchema> | undefined;
+  if (scope) {
+    try {
+      const prepared = requestSchema.safeParse(
+        prepareAnonymousProfileForIdentify({ ...properties }, report),
+      );
+      if (prepared.success) request = prepared.data;
+    } catch {
+      // The ordinary bounded request below retains its existing validation handling.
+    }
+  }
+  const entry: PendingProfile | undefined =
+    scope && request
+      ? {
+          version: 1,
+          id: `${Date.now()}-${Math.random()}`,
+          userId,
+          scope,
+          expiresAt: Date.now() + LIFETIME_MS,
+          attempts: 1,
+          request,
+        }
+      : undefined;
+  if (entry) save(entry, report);
+  else if (scope) remove(report);
+  const isCurrent = () =>
+    attempt === generation &&
+    isActive() &&
+    (!entry || Date.now() < entry.expiresAt) &&
+    (!scope || currentUserIs(userId));
+  return resolveProfile(userId, properties, isCurrent, report, entry);
+}
+
+/** Resumes only matching tab-local work after Mixpanel and Core configuration are ready. */
+function initialize(configuration: RecoveryScope): void {
+  scope = JSON.stringify([
+    configuration.project,
+    configuration.proxy ?? '',
+    configuration.apiBaseUrl,
+    configuration.appName ?? '',
+  ]);
+  const attempt = ++generation;
+  const report = createIdentifyReporter();
+  const entry = read(report);
+  if (!entry) return;
+  if (
+    entry.scope !== scope ||
+    !currentUserIs(entry.userId) ||
+    (entry.profileId === undefined && entry.attempts >= MAX_ATTEMPTS)
+  ) {
+    remove(report, entry.id);
+    return;
+  }
+  const lifecycle = trackingLifecycle.capture();
+  const isCurrent = () =>
+    attempt === generation &&
+    lifecycle() &&
+    Date.now() < entry.expiresAt &&
+    currentUserIs(entry.userId);
+  const resumed = {
+    ...entry,
+    attempts: entry.attempts + (entry.profileId === undefined ? 1 : 0),
+  };
+  if (entry.profileId === undefined && !save(resumed, report)) return;
+  const scopedReport: IdentifyReporter = (...args) => {
+    if (isCurrent()) report(...args);
+  };
+  void resolveProfile(entry.userId, {}, isCurrent, scopedReport, resumed, true);
+}
+
+export default { enrich, initialize };

package/src/track.storage.test.ts

@@ -1,4 +1,5 @@
 import coreApi from '@reservamos/js-api-client/core';
+import mixpanel from 'mixpanel-browser';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import fingerprintService from '@/services/fingerprint';
 import mixpanelService from '@/services/mixpanel';
@@ -10,7 +11,22 @@ const { getVisitorData, init, client } = vi.hoisted(() => ({
   client: vi.fn(),
 }));
 
-// Keep the SDK Fingerprint cache, tracking, validation, and relay real.
+const { provider } = vi.hoisted(() => ({
+  provider: {
+    init: vi.fn((_token: string, config: { loaded: () => void }) =>
+      config.loaded(),
+    ),
+    register: vi.fn(),
+    set_config: vi.fn(),
+    identify: vi.fn(),
+    track: vi.fn(),
+    get_distinct_id: vi.fn(() => 'live-id'),
+    people: { set: vi.fn(), union: vi.fn() },
+  },
+}));
+vi.mock('mixpanel-browser', () => ({ default: provider }));
+
+// Keep the SDK Fingerprint cache, Mixpanel service, tracking, validation, and relay real.
 vi.mock('@fingerprintjs/fingerprintjs-pro-spa', () => ({
   FingerprintJSPro: {
     defaultEndpoint: 'https://fpjscdn.net',
@@ -57,6 +73,7 @@ const checkout = {
 describe('tracking with blocked SDK Fingerprint cache writes', () => {
   beforeEach(async () => {
     localStorage.clear();
+    await mixpanelService.init('test-storage-token');
     client.mockImplementation(() => ({ init, getVisitorData }));
     init.mockResolvedValue(undefined);
     getVisitorData.mockResolvedValue({
@@ -67,14 +84,8 @@ describe('tracking with blocked SDK Fingerprint cache writes', () => {
       cacheHit: false,
     });
     await fingerprintService.initFingerprint('test-api-key');
-    vi.spyOn(mixpanelService, 'isReady').mockReturnValue(true);
-    vi.spyOn(mixpanelService, 'getMixpanelDistinctId').mockReturnValue(
-      'live-id',
-    );
-    vi.spyOn(mixpanelService, 'track').mockImplementation(() => undefined);
-    vi.spyOn(mixpanelService, 'setPeopleProperties').mockImplementation(
-      () => undefined,
-    );
+    vi.spyOn(mixpanel, 'get_distinct_id').mockReturnValue('live-id');
+    vi.spyOn(mixpanel.people, 'set').mockImplementation(() => undefined);
     vi.spyOn(coreApi.fingerprint, 'sendObservation').mockResolvedValue(true);
     vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
       throw new DOMException('Blocked', 'SecurityError');
@@ -96,16 +107,20 @@ describe('tracking with blocked SDK Fingerprint cache writes', () => {
     async (eventName, properties, eligible) => {
       await trackEvent(eventName, properties);
 
-      expect(mixpanelService.track).toHaveBeenCalledOnce();
-      expect(mixpanelService.track).toHaveBeenCalledWith(
+      expect(mixpanel.track).toHaveBeenCalledOnce();
+      expect(mixpanel.track).toHaveBeenCalledWith(
         eventName,
         expect.objectContaining({
           'User Fingerprint': expect.any(String),
           'product': 'web',
         }),
       );
+      /**
+       * Checks effects that may finish after event submission during background refresh.
+       * @returns {void} Throws until the expected profile and relay effects are observed.
+       */
       const verifyIdentificationEffects = () => {
-        expect(mixpanelService.setPeopleProperties).toHaveBeenCalledWith({
+        expect(mixpanel.people.set).toHaveBeenCalledWith({
           'Visitor Found': true,
         });
         expect(coreApi.fingerprint.sendObservation).toHaveBeenCalledTimes(