feat: reject reserved "$" event prefix client-side

Mirrors the server-side validation added in
Flagsmith/flagsmith-analytics-pipeline@8fb51c0 — Flagsmith.track_event
raises ValueError when the event name starts with "$" and isn't a known
system event. Avoids a fire-and-forget 400 round-trip; user gets the
error at the call site.

Only applies to track_event (user-controlled name); track_exposure_event
sets the literal internally and is unaffected.

Author: gagantrivedi

flagsmith/flagsmith.py

@@ -9,6 +9,7 @@
 from urllib3 import Retry
 
 from flagsmith.analytics import (
+    FLAG_EXPOSURE_EVENT,
     AnalyticsProcessor,
     EventProcessor,
     EventProcessorConfig,
@@ -380,6 +381,11 @@ def track_event(
     ) -> None:
         if not self._event_processor:
             raise ValueError("Events must be enabled to track events.")
+        if event.startswith("$") and event != FLAG_EXPOSURE_EVENT:
+            raise ValueError(
+                f'Event name "{event}" uses the reserved "$" prefix '
+                "but is not a known system event."
+            )
         self._event_processor.track_event(
             event=event,
             identifier=identifier,

tests/test_flagsmith.py

@@ -957,6 +957,16 @@ def test_track_event_raises_without_config(api_key: str) -> None:
         flagsmith.track_event("purchase")
 
 
+def test_track_event_rejects_reserved_prefix(api_key: str) -> None:
+    flagsmith = Flagsmith(environment_key=api_key, enable_events=True)
+    try:
+        with pytest.raises(ValueError, match='reserved "\\$" prefix'):
+            flagsmith.track_event("$made_up")
+    finally:
+        if flagsmith._event_processor:
+            flagsmith._event_processor.stop()
+
+
 def test_event_processor_config_without_enable_events_raises(api_key: str) -> None:
     config = EventProcessorConfig(events_api_url="http://test/")
     with pytest.raises(