fix(common): don't drop device overrides when the user agent looks like a server

[avionicharshit-byte]

fixes #466

parseUserAgent returned parsedServerUa before it ever looked at overrides, so __os, __model, __brand and __device were silently dropped for any sdk whose user agent matches the server heuristic. that is every non-browser sdk, since a plain name/version string is what SINGLE_NAME_VERSION_REGEX matches.

the shortcut is now taken only when the caller has not said what the device is.

behaviour change worth flagging: events from native sdks that send device overrides are no longer treated as server events, so in events.incoming-event.ts they open their own session with a real deviceId instead of riding along on an existing one with an empty one. that is the point of the fix, but it does change what lands in clickhouse for anyone already sending overrides from a non-browser sdk.

two tests added to parser-user-agent.test.ts: a native sdk ua plus overrides resolves to the real device (fails on main), and the same ua with no device overrides is still a server (passes on main, there to show the shortcut is intact).

@openpanel/common suite: 63 passed. typecheck clean.

Summary by CodeRabbit

• Bug Fixes
  • Improved device detection for non-browser SDK user agents with device information overrides.
  • Preserved operating system, device, brand, and model details instead of incorrectly classifying these requests as server devices.
  • IP-only overrides continue to use server-device detection as expected.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e2926b63-6db2-4b81-9690-78014ef612fa

📥 Commits

Reviewing files that changed from the base of the PR and between 663959d and 6e5e631.

📒 Files selected for processing (2)

• packages/common/server/parser-user-agent.test.ts
• packages/common/server/parser-user-agent.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The user-agent parser now preserves device overrides for server-like non-browser SDK user agents. It still returns the server result when no device overrides are present. Tests cover both paths.

Changes

User-agent override handling

Layer / File(s)	Summary
Override detection and parser flow packages/common/server/parser-user-agent.ts	The parser checks __os, __device, __brand, and __model for non-empty string overrides before returning the server result.
Override behavior validation packages/common/server/parser-user-agent.test.ts	Tests verify that device overrides produce a non-server result and that an IP-only override keeps the server result.

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

Merge Risk: 🔵 Low · up to 6e5e6

This change preserves device overrides for native SDK events, but events without an explicit device ID may use a fallback based on project, IP address, and user agent, allowing same-project profiles with matching values to share or overwrite session attribution. The PR is mergeable with explicit owner awareness and follow-up to require a stable device identifier or strengthen the fallback.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: preserving device overrides when the user agent matches the server heuristic.
Linked Issues check	✅ Passed	The changes satisfy issue #466. parseUserAgent now preserves non-empty __os, __device, __brand, and __model overrides instead of returning the server placeholder, and tests cover SDK user ag…
Out of Scope Changes check	✅ Passed	The changes are limited to the parser behavior and related tests required by issue #466. No unrelated code changes are identified.

Full details: Linked Issues check

Explanation

The changes satisfy issue #466. parseUserAgent now preserves non-empty __os, __device, __brand, and __model overrides instead of returning the server placeholder, and tests cover SDK user agents with and without overrides.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[CLAassistant]

All committers have signed the CLA.