fix: pass groupbyTagSecondLevelKey through beacon-group mapping (website + mobile analyze)

[ppolezhaev]

Problem

get_website_beacon_groups and get_mobile_app_beacon_groups rebuild the caller's group object keeping only groupbyTag and groupbyTagEntity — groupbyTagSecondLevelKey is silently dropped (website: _map_group_fields; mobile: the inline mapping in _build_beacon_groups_query_params). That makes it impossible to group key/value tags (e.g. beacon.meta / mobileBeacon.meta) by a specific sub-key: the API then falls back to enumerating the map's key names instead of splitting by the requested key's values, with no error or warning to the caller.

Repro

1. Report a custom event with meta from any monitored website, e.g. ineum('reportEvent', 'my_event', {meta: {flow: 'checkout'}})
2. Call get_website_beacon_groups with group: {"groupbyTag": "beacon.meta", "groupbyTagEntity": "NOT_APPLICABLE", "groupbyTagSecondLevelKey": "flow"}
3. Expected: groups split by the values of flow (checkout, …). Actual: a list of the meta key names — identical to omitting groupbyTagSecondLevelKey entirely.

Fix

The API models already support the field — both WebsiteBeaconTagGroup and MobileAppBeaconTagGroup declare groupbyTagSecondLevelKey — so this change only forwards it: map the field in both modules (with the same camelCase-variant handling as the existing group fields) and document it in the tool docstrings.

Tests

• website: sub-key passes through mapping; camelCase variant accepted; absent key stays absent.
• mobile: sub-key passes through the query-params builder; absent key stays absent.

uv run test passes (the only failure, TestVersionImport.test_version_fallback_on_exception, is pre-existing on main). uv run ruff check . passes.

Companion to #125 — together they make custom-event meta fully usable through the beacon analyze tools (values in list output, and grouping by sub-key).

🤖 Generated with Claude Code

[NiyathaVS]

Hey @ppolezhaev, you’ll need to update the docstrings exposed by the mobile_app and website smart routers. The docstrings from the smart routers are what get exposed to the LLM, and the LLM uses that information to construct the payload that is ultimately sent to the API. Currently, both routers are still exposing the old behavior, which doesn’t include groupbyTagSecondLevelKey. As a result, the LLM will continue generating payloads without this field, since the validation/logic added in the code itself isn’t visible to the LLM.

Could you please update the router docstrings to reflect the new behavior and include these changes? This will ensure that the LLM knows about the new field and includes it when constructing the payload.

[SLIBM]

beacon_type: "CUSTOM_EVENT" is not a valid beacon type, intended?

[SLIBM]

Thank you @NiyathaVS for your comment, that is also the first thing I noticed in the PR.

But I have given it a bit more thought, and now lean towards more on not having this declared/surfaced in the tool's docstring:

• The field groupbyTagSecondLevelKey is optional and uncommonly used. Everything we put in a tool description is permanent context cost on every request, paid whether or not the field is ever used. An optional, niche grouping modifier is a poor trade against that budget.
• If the only guidance we give in the tool docstring is an example containing the field, models tend to anchor on it and generalize — I'd expect groupbyTagSecondLevelKey to start showing up appended to ordinary groupings like
  beacon.page.name, where it's meaningless. Documenting it properly means explaining that where it applies (only to key/value map tags), how to properly use it and in what cases, which is a fair amount of prose for a rarely-used option. Half-documenting it is worse than not documenting it.

So if we only scope this PR to just unblock callers (like @ppolezhaev) who already know the field and want to pass it, this PR as of now is sufficient for this scope/purpose without explicitly surfacing it in the tool docstring - but @NiyathaVS @sunjit10 , I appreciate your opinion and different arguments for decision on this one.

If we do agree with my proposed scope, then this PR/fix itself looks right to me. I traced the path and the field
survives step that touches group (a nit issue in the tests that I added inline comments for)