Preserve queued browser event identity across account changes

[leo-paz]

Summary

• flush queued events before changing or clearing browser attribution identity
• keep first-time anonymous-to-known identification batching unchanged
• add regression coverage for account switches and logout
• add a browser SDK patch changeset

Verification

• all 56 browser SDK unit tests passed
• browser SDK typecheck passed
• browser SDK build passed
• Biome check passed

Summary by CodeRabbit

• Bug Fixes

  • Improved batching/flush behavior so queued events are emitted with the correct identity before switching attribution identity or clearing a user.
  • Events created after a user is cleared no longer carry the prior user/customer identity.
  • Identity comparisons are more resilient to casing/whitespace differences, avoiding unnecessary batch splits.

• Tests

  • Added unit tests covering identity transitions, account switching, clearing user state, and identity normalization behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6021c29e-e990-4786-acc7-e33e1d7de5b3

📥 Commits

Reviewing files that changed from the base of the PR and between 471d703 and b547c87.

📒 Files selected for processing (1)

• packages/browser/__tests__/unit/tracker.test.ts

---

Walkthrough

The browser tracker now flushes queued events before attribution identity changes or clearing. Identity comparisons normalize email and trim identifiers, while tests verify previous and subsequent event payload identities.

Changes

Browser identity batch boundaries

Layer / File(s)	Summary
Identity transition flush behavior packages/browser/src/tracker.ts	identify() detects normalized attribution changes and flushes queued events before updating identity; clearUser() flushes before clearing identity state, and applyUser() delegates attribution updates through identify().
Identity boundary validation and release packages/browser/__tests__/unit/tracker.test.ts, .changeset/browser-identity-batch-boundaries.md	Tests verify identity preservation before transitions, identity omission after clearing, and batching across normalization-only differences; the changeset records a browser patch release and the sequencing behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant Outlit
  participant Fetch
  Caller->>Outlit: identify(previous identity)
  Caller->>Outlit: track(event)
  Caller->>Outlit: identify(new identity)
  Outlit->>Fetch: flush queued event with previous identity
  Outlit->>Outlit: update current identity
  Caller->>Outlit: clearUser()
  Outlit->>Fetch: flush queued events with known identity
  Outlit->>Outlit: clear identity state

Loading

Possibly related PRs

• OutlitAI/outlit-sdk#12: Introduced related browser tracker user identity management.
• OutlitAI/outlit-sdk#27: Also changes queued-event flushing around identity transitions.
• OutlitAI/outlit-sdk#160: Overlaps with browser tracker queue and flush handling.

Suggested reviewers: rafa-thayto

Poem

I’m a rabbit guarding each event in line,
Flushing old identities at the boundary sign.
Switch or clear, the batches stay true,
No borrowed ears on events anew.
Hop, hop—accurate tracks for you!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: keeping queued browser event identity stable across account changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/browser-identity-batch-boundaries

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

packages/browser/__tests__/unit/tracker.test.ts (1)

203-274: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a test for hasAttributionChanged's normalization logic.

Both new tests use clearly distinct identities, so the trim/case-insensitive-email normalization added in hasAttributionChanged (tracker.ts lines 371-378) is untested. Worth adding a case verifying that re-identifying with the same email in different casing/whitespace (or same trimmed userId/customerId) does not trigger an extra flush/attribution change.

it("does not flush when identify is called with the same normalized identity", async () => {
  const outlit = new Outlit({ publicKey: "pk_test", autoTrack: false, trackPageviews: false, trackForms: false, trackEngagement: false })
  outlit.enableTracking()
  outlit.identify({ email: "User-A@Example.com " })
  await outlit.flush()

  outlit.track("same_identity_event")
  outlit.identify({ email: "  user-a@example.com" }) // same identity, different case/whitespace
  await outlit.flush()

  const payloads = vi.mocked(global.fetch).mock.calls.map(([, options]) => JSON.parse(String(options?.body)))
  // Expect the track event and the re-identify to batch together in one flush call,
  // rather than being split by an unnecessary attribution-change flush.
  expect(payloads).toHaveLength(2)
})

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/browser/__tests__/unit/tracker.test.ts` around lines 203 - 274, Add
a test in the tracker unit-test suite covering hasAttributionChanged
normalization: identify with an email containing different casing and
surrounding whitespace, queue an event, then identify the same normalized email
and flush. Assert no extra attribution-change flush occurs by verifying both
actions remain in the expected single post-initial-identification payload, while
preserving the existing distinct-identity tests.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/browser/__tests__/unit/tracker.test.ts`:
- Around line 203-274: Add a test in the tracker unit-test suite covering
hasAttributionChanged normalization: identify with an email containing different
casing and surrounding whitespace, queue an event, then identify the same
normalized email and flush. Assert no extra attribution-change flush occurs by
verifying both actions remain in the expected single post-initial-identification
payload, while preserving the existing distinct-identity tests.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 19b17f31-cabc-4841-a44a-2fd8da94f701

📥 Commits

Reviewing files that changed from the base of the PR and between 7f5ee85 and 471d703.

📒 Files selected for processing (3)

• .changeset/browser-identity-batch-boundaries.md
• packages/browser/__tests__/unit/tracker.test.ts
• packages/browser/src/tracker.ts