centive-sdk 2.1.0.dev2__tar.gz → 2.1.0.dev3__tar.gz

{centive_sdk-2.1.0.dev2 → centive_sdk-2.1.0.dev3}/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to this project are documented in this file.
 
+## v2.1.0
+
+Unreleased
+
+### Added
+
+- **Page-telemetry frames from the FE SDK are now handled.**
+  `@centive/aria-sdk` 1.1.0+ sends `{"type": "telemetry", ...}` page-view and
+  page-leave events over the existing Aria websocket. The server previously had
+  no branch for them, so every event fell through to the generic
+  `"message received"` reply and was discarded.
+- **`on_telemetry` client option.** Pass a callable to `AsyncCentiveClient` —
+  `on_telemetry(user_id: str, frame: dict)`, sync or async, with the events at
+  `frame["events"]` and the producer's `frame["schema"]` / `frame["sdk"]`
+  alongside them — to receive those events. The SDK relays and forgets:
+  nothing is stored and nothing is sent to the Centive API. Without a callback
+  the frame is acknowledged with `accepted: 0` and dropped.
+- **Events are attributed to the connection's bound user**, not to the frame's
+  `user_id`. A forged `user_id` is rejected with `IDENTITY_MISMATCH`, as on
+  every other frame type. Telemetry carries a `browser_session_id` (a client
+  tab) rather than a chat `session_id`, so no session is created or looked up.
+- **The producer's caps are mirrored server-side**:
+  `max_telemetry_events_per_frame` (100), `max_telemetry_frame_bytes` (65536)
+  and `max_telemetry_properties_bytes` (4096). The transport cap
+  (`ws_max_size`, 1 MiB) is far too loose to catch a buggy or hostile client.
+  A frame over a cap is **acknowledged, not errored** —
+  `{"type": "telemetry_ack", "accepted": 0, "dropped": N, "reason": ...}` with
+  `reason` one of `frame_too_large`, `too_many_events`, `properties_too_large`
+  — because the frontend parses `telemetry_ack` and ignores error frames, so a
+  cap breach reported as an error would be invisible to it.
+- A **malformed** frame still takes the ordinary error channel:
+  `INVALID_TELEMETRY_FORMAT` for missing or wrong-typed required fields.
+- **The schema version is forwarded, not gated on.** `frame["schema"]` is
+  checked for shape and passed through, so a future producer version whose
+  events are still well-formed keeps working against this SDK rather than
+  requiring a lockstep backend deploy.
+- `event_type` is treated as an open set: an event kind the server does not
+  recognize is forwarded, not rejected.
+- A callback that raises cannot close the connection. The frame is acked as
+  dropped with `reason: "handler_error"` and the error goes to the server log.
+
 ## v2.0.0
 
 Released: 2026-08-11

{centive_sdk-2.1.0.dev2 → centive_sdk-2.1.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: centive-sdk
-Version: 2.1.0.dev2
+Version: 2.1.0.dev3
 Summary: Python SDK for Centive backend integration
 Project-URL: Homepage, https://github.com/TheAgenticAI/centive-backend-sdk
 Project-URL: Repository, https://github.com/TheAgenticAI/centive-backend-sdk
@@ -40,6 +40,7 @@ Production-quality Python SDK for integrating Centive into your backend services
 - ✅ **Sync & Async Support** - Use `CentiveClient` for synchronous code or `AsyncCentiveClient` for async/await
 - ✅ **WebSocket Server** - Real-time communication with frontend SDKs
 - ✅ **Message Accumulation** - Capture and save Anam AI conversation messages automatically
+- ✅ **Page Telemetry** - Receive FE SDK page-view events through an `on_telemetry` callback
 - ✅ **Automatic Retries** - Exponential backoff with jitter for transient failures
 - ✅ **Type Safety** - Full Pydantic validation and type hints throughout
 - ✅ **Error Handling** - Comprehensive typed exceptions for all error scenarios
@@ -205,10 +206,14 @@ an expired connection token.
 | `max_message_content_chars` | `int`     | `32768`                                 | longest single message accepted        |
 | `max_session_id_chars` | `int`          | `200`                                   | longest `session_id` accepted          |
 | `max_connections_per_user` | `int`      | `5`                                     | concurrent websocket connections per user |
+| `max_telemetry_events_per_frame` | `int` | `100`                                | events accepted per telemetry frame    |
+| `max_telemetry_frame_bytes` | `int`     | `65536`                                 | largest telemetry frame accepted (UTF-8 bytes) |
+| `max_telemetry_properties_bytes` | `int` | `4096`                                | serialized `properties` per telemetry event |
 | `pause_check_fail_open` | `bool`        | `True`                                  | proceed as active if the pause check fails; `False` withholds access |
 | `circuit_breaker_threshold` | `int`     | `5`                                     | failures before circuit opens         |
 | `circuit_breaker_recovery_seconds` | `float` | `60.0`                            | time before circuit recovery attempt  |
 | `logger`              | `Optional[Any]` | `None`                                  | custom logger instance for debugging  |
+| `on_telemetry`        | `Optional[Callable]` | `None`                             | host sink for page-telemetry frames (see Page Telemetry) |
 
 ### Example with Custom Configuration
 
@@ -513,6 +518,85 @@ client = AsyncCentiveClient(
 
 For details on WebSocket event formats, see `websocket_messages.md`.
 
+## Page Telemetry
+
+The FE SDK (`@centive/aria-sdk` 1.1.0+) sends page-view and page-leave events over
+the same websocket as the chat traffic. The BE SDK validates them, attributes them
+to the connection's authenticated user, and hands them to a callback you supply.
+**It stores nothing and forwards nothing to the Centive API** — where the events go
+is entirely your decision.
+
+Your callback receives two arguments: `user_id`, the identity bound to the websocket
+connection (never a value the browser claimed), and `frame`, the validated frame.
+The events are at `frame["events"]`; `frame["schema"]` and `frame["sdk"]` carry the
+producer's schema version and SDK version, which are worth storing alongside them.
+
+```python
+async def record_page_events(user_id: str, frame: dict) -> None:
+    await analytics.insert_many(
+        {**event, "user_id": user_id, "sdk": frame.get("sdk")}
+        for event in frame["events"]
+    )
+
+client = AsyncCentiveClient(
+    api_key="sk_live_your_api_key",
+    on_telemetry=record_page_events,  # sync callables work too
+)
+```
+
+`**event` is spread *first*, never last: events are forwarded verbatim with
+no key filtering, so a client-supplied `user_id` inside an event would
+otherwise overwrite the identity the server already verified. Keep the
+trusted `user_id` and `sdk` after the spread.
+
+Each event carries `client_event_id`, `event_type`, `occurred_at`,
+`browser_session_id`, `detection`, and usually a `page` object
+(`path`, `pattern`, `title`, `referrer_path`) plus `duration_ms` on `page_leave`.
+`event_type` is an open set — new client-side event kinds reach your callback
+rather than being rejected, so switch on the values you know and ignore the rest.
+Each of `client_event_id`, `event_type`, `occurred_at` and `browser_session_id`
+is capped at 256 characters; over that, the whole frame is rejected with
+`INVALID_TELEMETRY_FORMAT` rather than truncated, so keep custom `event_type`
+values well under that.
+
+`telemetry_ack` carries one of five `reason` values whenever `accepted` is
+less than the event count:
+
+| `reason` | Meaning |
+| --- | --- |
+| `frame_too_large` | frame exceeded the 64 KB wire-size cap |
+| `too_many_events` | frame exceeded the 100-events-per-frame cap |
+| `properties_too_large` | one event's `properties` exceeded the 4 KB cap |
+| `no_telemetry_handler` | no `on_telemetry` callback is configured |
+| `handler_error` | the callback raised; see your logger for the exception |
+
+Behavior worth knowing:
+
+- **Without `on_telemetry`, events are dropped.** The frame is still acknowledged,
+  with `accepted: 0` and `reason: "no_telemetry_handler"`, so the frontend never
+  stalls waiting on a sink that does not exist.
+- **A callback that raises cannot break the connection.** The frame is acked as
+  dropped (`reason: "handler_error"`) and the exception goes to your logger.
+- **A sync callback runs on the event loop.** If yours does real work — a database
+  write, an HTTP call — make it `async`, or hand off to a queue.
+- **The producer's own caps are enforced here too** (100 events per frame, 64 KB
+  per frame, 4 KB of `properties` per event). An over-cap frame never reaches your
+  callback; it is acknowledged with `accepted: 0` and a `reason` of
+  `too_many_events`, `frame_too_large` or `properties_too_large`. A *malformed*
+  frame gets the ordinary error response instead (`INVALID_TELEMETRY_FORMAT`).
+- **A newer `schema` is not an error.** The SDK does not gate on the version, so
+  a future FE SDK release keeps working without a backend deploy. Branch on
+  `frame["schema"]` yourself if your storage ever needs to.
+- **`properties._dropped`** is a counter the browser SDK reports when its own buffer
+  had to evict events. It is relayed to your callback verbatim; the SDK never acts
+  on it.
+- **`properties._properties_dropped`** replaces the entire `properties` object with
+  `{"_properties_dropped": true}` when the browser's own properties blob exceeded
+  4 KB before it was ever sent. Unlike `_dropped`, this is not a count alongside
+  intact data — it means the original properties are gone entirely, not truncated.
+- **There is no rate limiting.** The frontend understands a
+  `reason: "rate_limited"` ack, but the SDK never sends one today.
+
 ## Advanced Usage
 
 ### Concurrent Tool Mapping (Async)

{centive_sdk-2.1.0.dev2 → centive_sdk-2.1.0.dev3}/README.md

@@ -7,6 +7,7 @@ Production-quality Python SDK for integrating Centive into your backend services
 - ✅ **Sync & Async Support** - Use `CentiveClient` for synchronous code or `AsyncCentiveClient` for async/await
 - ✅ **WebSocket Server** - Real-time communication with frontend SDKs
 - ✅ **Message Accumulation** - Capture and save Anam AI conversation messages automatically
+- ✅ **Page Telemetry** - Receive FE SDK page-view events through an `on_telemetry` callback
 - ✅ **Automatic Retries** - Exponential backoff with jitter for transient failures
 - ✅ **Type Safety** - Full Pydantic validation and type hints throughout
 - ✅ **Error Handling** - Comprehensive typed exceptions for all error scenarios
@@ -172,10 +173,14 @@ an expired connection token.
 | `max_message_content_chars` | `int`     | `32768`                                 | longest single message accepted        |
 | `max_session_id_chars` | `int`          | `200`                                   | longest `session_id` accepted          |
 | `max_connections_per_user` | `int`      | `5`                                     | concurrent websocket connections per user |
+| `max_telemetry_events_per_frame` | `int` | `100`                                | events accepted per telemetry frame    |
+| `max_telemetry_frame_bytes` | `int`     | `65536`                                 | largest telemetry frame accepted (UTF-8 bytes) |
+| `max_telemetry_properties_bytes` | `int` | `4096`                                | serialized `properties` per telemetry event |
 | `pause_check_fail_open` | `bool`        | `True`                                  | proceed as active if the pause check fails; `False` withholds access |
 | `circuit_breaker_threshold` | `int`     | `5`                                     | failures before circuit opens         |
 | `circuit_breaker_recovery_seconds` | `float` | `60.0`                            | time before circuit recovery attempt  |
 | `logger`              | `Optional[Any]` | `None`                                  | custom logger instance for debugging  |
+| `on_telemetry`        | `Optional[Callable]` | `None`                             | host sink for page-telemetry frames (see Page Telemetry) |
 
 ### Example with Custom Configuration
 
@@ -480,6 +485,85 @@ client = AsyncCentiveClient(
 
 For details on WebSocket event formats, see `websocket_messages.md`.
 
+## Page Telemetry
+
+The FE SDK (`@centive/aria-sdk` 1.1.0+) sends page-view and page-leave events over
+the same websocket as the chat traffic. The BE SDK validates them, attributes them
+to the connection's authenticated user, and hands them to a callback you supply.
+**It stores nothing and forwards nothing to the Centive API** — where the events go
+is entirely your decision.
+
+Your callback receives two arguments: `user_id`, the identity bound to the websocket
+connection (never a value the browser claimed), and `frame`, the validated frame.
+The events are at `frame["events"]`; `frame["schema"]` and `frame["sdk"]` carry the
+producer's schema version and SDK version, which are worth storing alongside them.
+
+```python
+async def record_page_events(user_id: str, frame: dict) -> None:
+    await analytics.insert_many(
+        {**event, "user_id": user_id, "sdk": frame.get("sdk")}
+        for event in frame["events"]
+    )
+
+client = AsyncCentiveClient(
+    api_key="sk_live_your_api_key",
+    on_telemetry=record_page_events,  # sync callables work too
+)
+```
+
+`**event` is spread *first*, never last: events are forwarded verbatim with
+no key filtering, so a client-supplied `user_id` inside an event would
+otherwise overwrite the identity the server already verified. Keep the
+trusted `user_id` and `sdk` after the spread.
+
+Each event carries `client_event_id`, `event_type`, `occurred_at`,
+`browser_session_id`, `detection`, and usually a `page` object
+(`path`, `pattern`, `title`, `referrer_path`) plus `duration_ms` on `page_leave`.
+`event_type` is an open set — new client-side event kinds reach your callback
+rather than being rejected, so switch on the values you know and ignore the rest.
+Each of `client_event_id`, `event_type`, `occurred_at` and `browser_session_id`
+is capped at 256 characters; over that, the whole frame is rejected with
+`INVALID_TELEMETRY_FORMAT` rather than truncated, so keep custom `event_type`
+values well under that.
+
+`telemetry_ack` carries one of five `reason` values whenever `accepted` is
+less than the event count:
+
+| `reason` | Meaning |
+| --- | --- |
+| `frame_too_large` | frame exceeded the 64 KB wire-size cap |
+| `too_many_events` | frame exceeded the 100-events-per-frame cap |
+| `properties_too_large` | one event's `properties` exceeded the 4 KB cap |
+| `no_telemetry_handler` | no `on_telemetry` callback is configured |
+| `handler_error` | the callback raised; see your logger for the exception |
+
+Behavior worth knowing:
+
+- **Without `on_telemetry`, events are dropped.** The frame is still acknowledged,
+  with `accepted: 0` and `reason: "no_telemetry_handler"`, so the frontend never
+  stalls waiting on a sink that does not exist.
+- **A callback that raises cannot break the connection.** The frame is acked as
+  dropped (`reason: "handler_error"`) and the exception goes to your logger.
+- **A sync callback runs on the event loop.** If yours does real work — a database
+  write, an HTTP call — make it `async`, or hand off to a queue.
+- **The producer's own caps are enforced here too** (100 events per frame, 64 KB
+  per frame, 4 KB of `properties` per event). An over-cap frame never reaches your
+  callback; it is acknowledged with `accepted: 0` and a `reason` of
+  `too_many_events`, `frame_too_large` or `properties_too_large`. A *malformed*
+  frame gets the ordinary error response instead (`INVALID_TELEMETRY_FORMAT`).
+- **A newer `schema` is not an error.** The SDK does not gate on the version, so
+  a future FE SDK release keeps working without a backend deploy. Branch on
+  `frame["schema"]` yourself if your storage ever needs to.
+- **`properties._dropped`** is a counter the browser SDK reports when its own buffer
+  had to evict events. It is relayed to your callback verbatim; the SDK never acts
+  on it.
+- **`properties._properties_dropped`** replaces the entire `properties` object with
+  `{"_properties_dropped": true}` when the browser's own properties blob exceeded
+  4 KB before it was ever sent. Unlike `_dropped`, this is not a count alongside
+  intact data — it means the original properties are gone entirely, not truncated.
+- **There is no rate limiting.** The frontend understands a
+  `reason: "rate_limited"` ack, but the SDK never sends one today.
+
 ## Advanced Usage
 
 ### Concurrent Tool Mapping (Async)

{centive_sdk-2.1.0.dev2 → centive_sdk-2.1.0.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "centive-sdk"
-version = "2.1.0.dev2"
+version = "2.1.0.dev3"
 description = "Python SDK for Centive backend integration"
 readme = "README.md"
 license = "MIT"

{centive_sdk-2.1.0.dev2 → centive_sdk-2.1.0.dev3}/src/centive_sdk/async_client.py

@@ -40,6 +40,11 @@ class AsyncCentiveClient:
 
         api_key and base_url fall back to the CENTIVE_API_KEY and CENTIVE_BASE_URL
         environment variables when not passed explicitly.
+
+        Pass on_telemetry=<callable> to receive page-telemetry frames from the FE
+        SDK: on_telemetry(user_id: str, frame: dict), sync or async, with the
+        events at frame["events"]. The SDK does not store them — without a
+        callback they are acknowledged and dropped.
         """
         if api_key is not None:
             options["api_key"] = api_key
@@ -48,6 +53,9 @@ class AsyncCentiveClient:
         self.config = ClientConfig(**options)
         self._http_client = httpx.AsyncClient()
         self._logger = options.get("logger")
+        # Same pattern as logger: a callable, not config data, so it rides in
+        # **options and is read out here. ClientConfig ignores unknown keys.
+        self._on_telemetry = options.get("on_telemetry")
         self.sessions = AsyncSessions(self._http_client, self.config, self._logger)
         self._ws_server: Optional[WebSocketServer] = None
         self._last_pause_status: Optional[PauseStatusResponse] = None
@@ -128,6 +136,7 @@ class AsyncCentiveClient:
                     sessions=self.sessions,
                     config=self.config,
                     logger=self._logger,
+                    on_telemetry=self._on_telemetry,
                 )
                 # Publish only after a successful bind, so a failed start does
                 # not leave a dead server in place and wedge every later call.

{centive_sdk-2.1.0.dev2 → centive_sdk-2.1.0.dev3}/src/centive_sdk/config.py

@@ -83,6 +83,16 @@ class ClientConfig(BaseModel):
     # Concurrent websocket connections accepted per user.
     max_connections_per_user: int = 5
 
+    # Page-telemetry frames (type="telemetry") from the FE SDK. These mirror the
+    # aria-sdk producer's own caps (MAX_EVENTS_PER_FRAME, MAX_FRAME_BYTES,
+    # MAX_PROPERTIES_BYTES). They bound what reaches the on_telemetry callback
+    # and keep the ack honest against the producer's own limits — the frame
+    # itself is still parsed up to the far looser ws_max_size (1 MiB) transport
+    # cap regardless of these.
+    max_telemetry_events_per_frame: int = 100
+    max_telemetry_frame_bytes: int = 65_536
+    max_telemetry_properties_bytes: int = 4_096
+
     # When the pause-status check fails (upstream 5xx, rate limit, network), the
     # SDK proceeds as active so a Centive outage does not hide every avatar. Set
     # False to fail closed and withhold connections instead.

{centive_sdk-2.1.0.dev2 → centive_sdk-2.1.0.dev3}/src/centive_sdk/resources/websocket_server.py

@@ -1,9 +1,10 @@
+import inspect
 import json
 import secrets
 import time
 import warnings
 from collections import deque
-from typing import TYPE_CHECKING, Any, Deque, Dict, Optional, Set, Tuple
+from typing import TYPE_CHECKING, Any, Callable, Deque, Dict, Optional, Set, Tuple
 from urllib.parse import parse_qs, urlparse
 
 import websockets
@@ -23,6 +24,22 @@ if TYPE_CHECKING:
 
 from .message_accumulator import MessageAccumulator
 
+# Short identifier fields on a telemetry event. Not a config knob: the frame
+# byte cap already bounds the whole payload, this only stops one field from
+# eating the entire budget.
+_MAX_TELEMETRY_FIELD_CHARS = 256
+
+# The fields the producer always populates (TA-aria-sdk src/core/types.ts:40-49).
+# event_type is checked for presence and shape only — never against a value set.
+# The producer's own types call the set open, so an event kind added on the
+# client must reach the host callback rather than be rejected here.
+_TELEMETRY_REQUIRED_FIELDS = (
+    "client_event_id",
+    "event_type",
+    "occurred_at",
+    "browser_session_id",
+)
+
 
 class WebSocketServer:
     """websocket server for FE SDK connections, session triggers, and message accumulation.
@@ -36,10 +53,16 @@ class WebSocketServer:
         sessions: "AsyncSessions",
         config: ClientConfig,
         logger: Optional[Any] = None,
+        on_telemetry: Optional[Callable[[str, dict], Any]] = None,
     ):
         self._sessions = sessions
         self._config = config
         self._logger = logger
+        # Host sink for page-telemetry frames. The SDK relays and forgets them:
+        # there is no Centive telemetry endpoint and nothing is stored here.
+        # Called as on_telemetry(user_id, frame); may be sync or async. See
+        # _handle_telemetry.
+        self._on_telemetry = on_telemetry
         self._server: Optional[websockets.WebSocketServer] = None
         self._clients: Set[WebSocketServerProtocol] = set()
         self._running = False
@@ -173,6 +196,82 @@ class WebSocketServer:
                 return "MESSAGE_TOO_LARGE"
         return None
 
+    def _validate_telemetry(self, data: dict, raw_message: Any) -> Optional[Tuple[str, str]]:
+        """Validates a page-telemetry frame.
+
+        Returns None when the frame is acceptable, else a (kind, code) pair. The
+        two kinds leave the handler by different channels on purpose:
+
+        - ("cap", <reason>): well-formed but over one of the producer's own
+          limits. Acked with that reason, because the producer parses
+          telemetry_ack and ignores everything else (TA-aria-sdk
+          src/core/queue.ts:65-71) — a cap breach sent as an error frame would
+          be invisible to it. Flow-control signals added later (rate limiting)
+          belong in this same field.
+        - ("invalid", <ERROR_CODE>): a protocol error, which goes where every
+          other protocol error in this server goes, an "error" frame.
+
+        The caps mirror the producer's (100 events, 64 KB frame, 4 KB properties
+        per event). They bound what reaches the on_telemetry callback and keep
+        the ack honest against the producer's own limits — they do not bound
+        what the server parses: _process_message already ran json.loads on the
+        whole frame, up to the far looser ws_max_size (1 MiB) transport cap,
+        before this check ever runs. The frame is measured on the raw wire
+        bytes for the same reason the producer measures it there:
+        re-serializing the parsed object would not reproduce what was sent.
+        """
+        raw = raw_message.encode("utf-8") if isinstance(raw_message, str) else raw_message
+        if len(raw) > self._config.max_telemetry_frame_bytes:
+            return ("cap", "frame_too_large")
+
+        # Shape-checked and forwarded, never gated on its value: rejecting an
+        # unknown version would make a producer bump a lockstep deploy, and the
+        # per-event checks below reject an incompatible shape on its own merits.
+        # isinstance(x, int) is also true for bool, so that's excluded explicitly.
+        schema = data.get("schema")
+        if not isinstance(schema, int) or isinstance(schema, bool):
+            return ("invalid", "INVALID_TELEMETRY_FORMAT")
+
+        # The producer always populates sdk (TA-aria-sdk src/core/types.ts:40-49)
+        # and the README tells hosts to read frame["sdk"], so a frame missing it
+        # must be rejected here rather than reach the callback and KeyError.
+        sdk = data.get("sdk")
+        if not isinstance(sdk, str) or not sdk:
+            return ("invalid", "INVALID_TELEMETRY_FORMAT")
+
+        events = data.get("events")
+        if not isinstance(events, list) or not events:
+            return ("invalid", "INVALID_TELEMETRY_FORMAT")
+        if len(events) > self._config.max_telemetry_events_per_frame:
+            return ("cap", "too_many_events")
+
+        properties_limit = self._config.max_telemetry_properties_bytes
+
+        for event in events:
+            if not isinstance(event, dict):
+                return ("invalid", "INVALID_TELEMETRY_FORMAT")
+
+            for field in _TELEMETRY_REQUIRED_FIELDS:
+                value = event.get(field)
+                if not isinstance(value, str) or not value:
+                    return ("invalid", "INVALID_TELEMETRY_FORMAT")
+                if len(value) > _MAX_TELEMETRY_FIELD_CHARS:
+                    return ("invalid", "INVALID_TELEMETRY_FORMAT")
+
+            properties = event.get("properties")
+            if properties is None:
+                continue
+            if not isinstance(properties, dict):
+                return ("invalid", "INVALID_TELEMETRY_FORMAT")
+            # No spaces, matching JSON.stringify: json.dumps's default separators
+            # add a byte per comma/colon that the producer's own size check never
+            # counts, which would cap a payload the producer judged to be fine.
+            properties_json = json.dumps(properties, separators=(",", ":"))
+            if len(properties_json.encode("utf-8")) > properties_limit:
+                return ("cap", "properties_too_large")
+
+        return None
+
     def _purge_expired_tokens(self) -> None:
         now = time.monotonic()
         expired = [t for t, (_, exp) in self._connection_tokens.items() if exp <= now]
@@ -539,6 +638,12 @@ class WebSocketServer:
             await self._handle_session_end(websocket, data, client_info)
             return
 
+        if msg_type == "telemetry":
+            # The raw message goes along: the frame byte cap is on what was
+            # actually sent, and re-serializing `data` would not reproduce it.
+            await self._handle_telemetry(websocket, data, message, client_info)
+            return
+
         if "user_trigger" in data:
             await self._handle_trigger(websocket, data, client_info)
             return
@@ -839,6 +944,125 @@ class WebSocketServer:
             is_complete=True,
         )
 
+    async def _handle_telemetry(
+        self,
+        websocket: WebSocketServerProtocol,
+        data: dict,
+        raw_message: Any,
+        client_info: str,
+    ) -> None:
+        """handles a page-telemetry frame from the FE SDK.
+
+        The SDK is a relay here, not a store: a validated frame goes to the
+        host's on_telemetry callback and is forgotten. There is no Centive
+        telemetry endpoint, and nothing is buffered.
+
+        Telemetry frames carry a browser_session_id (a client tab, rolled over
+        on idle) rather than the chat session_id, so identity is enforced with
+        session_id=None: the frame's own user_id is still checked against the
+        connection's bound identity, but the session-ownership backstop, which
+        is specific to accumulated chat sessions, does not apply.
+        """
+        if self._config.ws_auth_mode == "open":
+            user_id = data.get("user_id")
+            # Stricter than the sibling handlers on purpose: they only
+            # f-string user_id into a session key, but this one crosses a
+            # public API boundary (on_telemetry is documented as user_id: str).
+            if not isinstance(user_id, str) or not user_id:
+                await websocket.send(json.dumps({
+                    "status": "error",
+                    "message": "missing user_id",
+                    "error": "MISSING_FIELDS",
+                }))
+                return
+        else:
+            user_id = await self._enforce_frame_identity(websocket, data, None, client_info)
+            if user_id is None:
+                return
+
+        async def ack(accepted: int, dropped: int, reason: Optional[str] = None) -> None:
+            frame = {
+                "status": "ok",
+                "type": "telemetry_ack",
+                "accepted": accepted,
+                "dropped": dropped,
+            }
+            if reason is not None:
+                frame["reason"] = reason
+            await websocket.send(json.dumps(frame))
+
+        events = data.get("events")
+        # A rejected frame may not even hold a list here, and 0 is the honest
+        # count when there is nothing countable to report as dropped.
+        #
+        # _validate_telemetry checks frame_too_large before checking that
+        # events is a list, so an oversized frame with a missing/malformed
+        # events field reports accepted: 0, dropped: 0 here — the frame was
+        # still dropped in full, this 0 is just an uncounted one, not a bug.
+        event_count = len(events) if isinstance(events, list) else 0
+
+        failure = self._validate_telemetry(data, raw_message)
+        if failure is not None:
+            kind, code = failure
+            if kind == "cap":
+                # Caps are flow control, so they leave through the channel the
+                # producer actually parses. An error frame would be invisible.
+                await ack(0, event_count, code)
+            else:
+                await websocket.send(json.dumps({
+                    "status": "error",
+                    "message": "invalid telemetry payload",
+                    "error": code,
+                }))
+            return
+
+        if self._on_telemetry is None:
+            # Acked rather than errored: the frame was fine, this deployment
+            # simply has nowhere to put it. The producer does not retry on a
+            # non-zero `dropped`, which is what we want.
+            await ack(0, event_count, "no_telemetry_handler")
+            return
+
+        try:
+            # The whole validated frame goes over, not just the events: `schema`
+            # and `sdk` matter to anyone storing them, and `user_id` is the
+            # trusted identity, not the frame's (which _enforce_frame_identity
+            # has already proven absent or equal).
+            #
+            # ponytail: a blocking sync callback stalls the event loop; hosts
+            # doing real work should hand off to a queue or an executor.
+            result = self._on_telemetry(user_id, data)
+            if inspect.isawaitable(result):
+                await result
+        except Exception as e:
+            # A host callback must never take the connection down with it, and
+            # the client has no ack-based retry, so the frame is simply lost.
+            #
+            # error is the exception type only, never str(e): the callback got
+            # the whole frame, so its exception text is host-authored over
+            # user-navigation data (page.path, page.title, properties) that
+            # safe_log's redaction does not cover. Do not "improve" this back
+            # to str(e).
+            safe_log(
+                self._logger,
+                "error",
+                "on_telemetry callback failed, dropping frame",
+                {"client": client_info, "user_id": user_id, "error": type(e).__name__},
+            )
+            await ack(0, event_count, "handler_error")
+            return
+
+        # Counts only: page paths, titles and properties are navigation data
+        # that safe_log's redaction does not cover.
+        safe_log(
+            self._logger,
+            "debug",
+            "telemetry received",
+            {"client": client_info, "user_id": user_id, "event_count": event_count},
+        )
+
+        await ack(event_count, 0)
+
     async def _save_disconnected_sessions(
         self,
         session_keys: Set[str],

{centive_sdk-2.1.0.dev2 → centive_sdk-2.1.0.dev3}/tests/conftest.py

@@ -110,6 +110,42 @@ def session_end_event_data():
     }
 
 
+@pytest.fixture
+def telemetry_event_data():
+    """A page-telemetry frame exactly as @centive/aria-sdk 1.1.0-dev.4 sends it."""
+    return {
+        "type": "telemetry",
+        "schema": 1,
+        "user_id": "user_123",
+        "sdk": "aria-sdk/1.1.0-dev.4",
+        "events": [
+            {
+                "client_event_id": "3f8b0c62-1f3a-4a1e-9c1e-0f2d7a5b6c11",
+                "event_type": "page_view",
+                "occurred_at": "2026-09-01T10:00:00.000Z",
+                "browser_session_id": "bs_9a1c4e7b2d",
+                "page": {
+                    "path": "/dashboard",
+                    "pattern": "/dashboard",
+                    "title": "Dashboard",
+                },
+                "duration_ms": None,
+                "detection": "navigation-api",
+            },
+            {
+                "client_event_id": "5d2a91f4-7c60-4b93-8a2f-1e4c8d0b3a77",
+                "event_type": "page_leave",
+                "occurred_at": "2026-09-01T10:00:42.000Z",
+                "browser_session_id": "bs_9a1c4e7b2d",
+                "page": {"path": "/dashboard", "referrer_path": "/"},
+                "duration_ms": 42000,
+                "detection": "history",
+                "properties": {"_dropped": 3},
+            },
+        ],
+    }
+
+
 @pytest.fixture
 def pause_status_not_paused_response():
     return {