fix: gate identify on the tracking policy, and make wallet markers expire and dedup like the web SDK

src/FormoAnalytics.ts

@@ -700,7 +700,14 @@ export class FormoAnalytics implements IFormoAnalytics {
     try {
       const { userId, address, providerName, rdns } = params;
       logger.info("Identify", address, userId, providerName, rdns);
-      if (this.hasOptedOutTracking()) return;
+      // The full policy, not consent alone: identify persists the user id
+      // and marks the wallet before trackEvent applies the chain gate, and
+      // a marker written on an excluded chain would silence a later
+      // identify on an allowed one.
+      if (!this.shouldTrack()) {
+        logger.info("identify() skipped: tracking is suppressed for this visitor or chain");
+        return;
+      }
 
       let validAddress: Address | undefined = undefined;
       if (address) {
@@ -723,26 +730,21 @@ export class FormoAnalytics implements IFormoAnalytics {
         storage().set(SESSION_USER_ID_KEY, userId);
       }
 
-      // Check for duplicate identify
-      const isAlreadyIdentified = validAddress
-        ? this.session.isWalletIdentified(validAddress, rdns || "")
-        : false;
-
-      if (isAlreadyIdentified) {
-        logger.info(
-          `Identify: Wallet ${providerName || "Unknown"} with address ${validAddress} already identified`
-        );
-        return;
-      }
-
-      // Mark as identified
+      // Dedup on the effective user, as the wire event carries it, not only
+      // the argument: a re-identify that changes the user is sent again.
       if (validAddress) {
-        this.session.markWalletIdentified(validAddress, rdns || "");
+        if (this.session.isWalletIdentified(validAddress, rdns || "", this.currentUserId, properties)) {
+          logger.info(
+            `Identify: Wallet ${providerName || "Unknown"} with address ${validAddress} already identified`
+          );
+          return;
+        }
+        this.session.markWalletIdentified(validAddress, rdns || "", this.currentUserId, properties);
       }
 
       await this.trackEvent(
         EventType.IDENTIFY,
-        { address: validAddress, providerName, userId, rdns },
+        { address: validAddress, providerName, userId: this.currentUserId, rdns },
         properties,
         context,
         callback
@@ -764,7 +766,7 @@ export class FormoAnalytics implements IFormoAnalytics {
     // The full policy, not consent alone: a detect refused by the chain gate
     // after the marker is written would silence the wallet for the session.
     if (!this.shouldTrack()) {
-      logger.info("detect() skipped: tracking is suppressed for this wallet or chain");
+      logger.info("detect() skipped: tracking is suppressed for this visitor or chain");
       return;
     }
     if (this.session.isWalletDetected(rdns)) {

src/__tests__/FormoAnalytics.test.ts

@@ -543,6 +543,19 @@ describe('FormoAnalytics', () => {
       expect(mockEventManager.addEvent).not.toHaveBeenCalled();
     });
 
+    it('identify() without a user id carries the effective user on the wire, as the marker does', async () => {
+      analytics.currentUserId = 'restored-user';
+      mockEventManager.addEvent.mockClear();
+
+      await analytics.identify({ address: '0x51377e9B985Bb90B7c091B9a7d30C93d4c9c1CEf', rdns: 'io.metamask' });
+
+      const event = mockEventManager.addEvent.mock.calls.at(-1)?.[0];
+      expect(event.userId).toBe('restored-user');
+      expect(mockSession.markWalletIdentified).toHaveBeenCalledWith(
+        '0x51377e9B985Bb90B7c091B9a7d30C93d4c9c1CEf', 'io.metamask', 'restored-user', undefined
+      );
+    });
+
     it('treats a null or undefined idempotency_key as no key and strips the property', async () => {
       for (const idempotency_key of [undefined, null]) {
         mockEventManager.addEvent.mockClear();
@@ -815,6 +828,78 @@ describe('FormoAnalytics', () => {
     });
   });
 
+  describe('identify() tracking gate', () => {
+    const address = '0x742d35cc6634c0532925a3b844bc9e7595f3f6d2';
+
+    it('writes nothing on an excluded chain, and identifies on an allowed one', async () => {
+      analytics.options.tracking = { excludeChains: [1] };
+      analytics.currentChainId = 1;
+
+      await analytics.identify({ address, userId: 'user-1', rdns: 'io.metamask' });
+
+      expect(analytics.currentAddress).toBeUndefined();
+      expect(analytics.currentUserId).toBeUndefined();
+      expect(mockStorageInstance.set).not.toHaveBeenCalledWith('user_id', expect.anything());
+      expect(mockSession.markWalletIdentified).not.toHaveBeenCalled();
+      expect(mockEventManager.addEvent).not.toHaveBeenCalled();
+
+      analytics.currentChainId = 137;
+      await analytics.identify({ address, userId: 'user-1', rdns: 'io.metamask' });
+
+      expect(mockStorageInstance.set).toHaveBeenCalledWith('user_id', 'user-1');
+      expect(mockSession.markWalletIdentified).toHaveBeenCalledWith(
+        expect.any(String),
+        'io.metamask',
+        'user-1',
+        undefined
+      );
+      expect(mockEventManager.addEvent).toHaveBeenCalledWith(
+        expect.objectContaining({ type: 'identify', userId: 'user-1' }),
+        expect.any(String),
+        'user-1'
+      );
+    });
+
+    it('writes nothing when tracking is off', async () => {
+      analytics.options.tracking = false;
+
+      await analytics.identify({ address, userId: 'user-1' });
+
+      expect(analytics.currentAddress).toBeUndefined();
+      expect(mockStorageInstance.set).not.toHaveBeenCalledWith('user_id', expect.anything());
+      expect(mockSession.markWalletIdentified).not.toHaveBeenCalled();
+      expect(mockEventManager.addEvent).not.toHaveBeenCalled();
+    });
+
+    it('checks and marks the wallet with the user id and the properties', async () => {
+      const properties = { plan: 'pro' };
+
+      await analytics.identify({ address, userId: 'user-1', rdns: 'io.metamask' }, properties);
+
+      expect(mockSession.isWalletIdentified).toHaveBeenCalledWith(
+        expect.any(String),
+        'io.metamask',
+        'user-1',
+        properties
+      );
+      expect(mockSession.markWalletIdentified).toHaveBeenCalledWith(
+        expect.any(String),
+        'io.metamask',
+        'user-1',
+        properties
+      );
+    });
+
+    it('skips the event when the session already holds this identity', async () => {
+      mockSession.isWalletIdentified.mockReturnValue(true);
+
+      await analytics.identify({ address, userId: 'user-1' });
+
+      expect(mockSession.markWalletIdentified).not.toHaveBeenCalled();
+      expect(mockEventManager.addEvent).not.toHaveBeenCalled();
+    });
+  });
+
   describe('optOutTracking()', () => {
     it('should clear the anonymous id and the stored attribution as well', () => {
       analytics.optOutTracking();

src/__tests__/eventManager.test.ts

@@ -95,6 +95,44 @@ describe("EventManager custom-event identity", () => {
     expect(b![3].dedupKey).toBe(a![3].dedupKey);
   });
 
+  it("fingerprints the same properties the same whatever their key order", async () => {
+    const { queue, manager } = makeManager();
+
+    await manager.addEvent({ type: "track", event: "Purchase", properties: { currency: "USD", amount: 10 } });
+    await manager.addEvent({ type: "track", event: "Purchase", properties: { amount: 10, currency: "USD" } });
+
+    const [a, b] = enqueueCalls(queue);
+    expect(b![3].dedupKey).toBe(a![3].dedupKey);
+  });
+
+  it("sorts keys in nested objects too", async () => {
+    const { queue, manager } = makeManager();
+
+    await manager.addEvent({
+      type: "track",
+      event: "Purchase",
+      properties: { item: { sku: "x", qty: 1 }, currency: "USD" },
+    });
+    await manager.addEvent({
+      type: "track",
+      event: "Purchase",
+      properties: { currency: "USD", item: { qty: 1, sku: "x" } },
+    });
+
+    const [a, b] = enqueueCalls(queue);
+    expect(b![3].dedupKey).toBe(a![3].dedupKey);
+  });
+
+  it("keeps array order in the fingerprint", async () => {
+    const { queue, manager } = makeManager();
+
+    await manager.addEvent({ type: "track", event: "Purchase", properties: { tags: ["a", "b"] } });
+    await manager.addEvent({ type: "track", event: "Purchase", properties: { tags: ["b", "a"] } });
+
+    const [a, b] = enqueueCalls(queue);
+    expect(b![3].dedupKey).not.toBe(a![3].dedupKey);
+  });
+
   it("keeps caller-supplied context in the fingerprint", async () => {
     const { queue, manager } = makeManager();
     const call = { type: "track" as const, event: "Order Placed", properties: { market: "ZEC" } };

src/__tests__/eventQueue.test.ts

@@ -514,7 +514,9 @@ describe("EventQueue", () => {
       expect(fetchMock).toHaveBeenCalledTimes(1);
 
       // Opt out, then the same event is produced again and re-enqueued.
+      // Only sends after the opt-out count from here on.
       queue.clear();
+      fetchMock.mockClear();
       await queue.enqueue(makeEvent(1));
       await settle();
 
@@ -524,8 +526,6 @@ describe("EventQueue", () => {
       await settle();
 
       // A third identical enqueue must still be recognised as a duplicate.
-      fetchMock.mockClear();
-      fetchMock.mockResolvedValue({ ok: true, status: 200 });
       await queue.enqueue(makeEvent(1));
       await queue.flush();
       await settle();
@@ -539,6 +539,26 @@ describe("EventQueue", () => {
     });
   });
 
+  describe("first event after clear()", () => {
+    it("ships at once instead of waiting for the batch interval", async () => {
+      const queue = makeQueue({ flushAt: 20 });
+
+      await queue.enqueue(makeEvent(1));
+      await settle();
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      // Opt out, then opt in: the next event starts a fresh lifecycle.
+      queue.clear();
+      await queue.enqueue(makeEvent(2));
+      await settle();
+
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(sentEvents().map((e) => e.event)).toEqual(["event-1", "event-2"]);
+
+      await queue.cleanup();
+    });
+  });
+
   describe("enqueue racing clear()", () => {
     it("drops an event whose hashing was still pending when the user opted out", async () => {
       const queue = makeQueue();
@@ -1161,6 +1181,32 @@ describe("EventQueue dedup window", () => {
     }
   });
 
+  it("collapses two events whose properties differ only in key order", async () => {
+    const queue = makeQueue();
+
+    await queue.enqueue(event({ properties: { currency: "USD", amount: 10 } }));
+    await settle();
+    await queue.enqueue(event({ properties: { amount: 10, currency: "USD" } }));
+    await queue.flush();
+    await settle();
+
+    expect(sent()).toHaveLength(1);
+    await queue.cleanup();
+  });
+
+  it("keeps two events whose array order differs", async () => {
+    const queue = makeQueue();
+
+    await queue.enqueue(event({ properties: { tags: ["a", "b"] } }));
+    await settle();
+    await queue.enqueue(event({ properties: { tags: ["b", "a"] } }));
+    await queue.flush();
+    await settle();
+
+    expect(sent()).toHaveLength(2);
+    await queue.cleanup();
+  });
+
   it("gives separate unkeyed custom events distinct random ids", async () => {
     const queue = makeQueue();