centive-sdk 2.1.0.dev2__tar.gz → 2.2.0.dev4__tar.gz

{centive_sdk-2.1.0.dev2 → centive_sdk-2.2.0.dev4}/CHANGELOG.md

@@ -2,6 +2,92 @@
 
 All notable changes to this project are documented in this file.
 
+## v2.2.0
+
+Unreleased (branch `feature/user-page-tracking`, merged with the v2.1.0
+`on_telemetry` handler from dev; one unified telemetry handler feeds both the
+Centive batcher and the host callback).
+
+### Added
+
+- **Product events (page tracking).** A new websocket frame type,
+  `type: "telemetry"`, carries page views and page leaves from the browser SDK.
+  The server validates each frame (identity, size, per-connection rate), queues
+  the events and forwards them to `POST /anam/events` in batches (every 2 s or
+  50 events). Contract: CentiveAI `docs/product-events/CONTRACTS.md`.
+- `client.telemetry.track(user_id, event_type, properties)` to emit
+  server-side events into the same pipe, `client.telemetry.flush()` and
+  `client.telemetry.stats()`.
+- **Live Aria context relay.** When the `POST /anam/events` response carries
+  `context[]` (Centive believes the user has a live Aria session), the SDK
+  pushes each entry to that user's socket only as a `{"type": "context"}`
+  frame; the browser SDK injects it with `anamClient.addContext`. Counted in
+  `stats()` as `context_received` / `context_delivered`. Anam has no
+  server-side way to inform a running session, so this is the only path.
+- `AsyncSessions.send_events(ProductEventBatchRequest)`.
+- Models: `TelemetryEvent`, `TelemetryFrame`, `TelemetryUserBatch`,
+  `ProductEventBatchRequest`, `ProductEventIngestResponse`.
+- Config: `events_path`, `telemetry_enabled`, `telemetry_flush_max_events`,
+  `telemetry_flush_interval_seconds`, `telemetry_max_queue_events`,
+  `telemetry_max_events_per_frame`, `telemetry_max_frame_bytes`,
+  `telemetry_rate_per_connection_per_minute`.
+
+### Behavior
+
+- The telemetry queue has its own circuit breaker, so a failing events
+  endpoint cannot stop transcript saves (and vice versa).
+- The queue is bounded (`telemetry_max_queue_events`, default 5000); when full
+  the oldest events are dropped and counted in `stats()`. The websocket handler
+  never blocks on telemetry.
+- A `202` from the API is final; its `rejections` (for example
+  `user_not_mapped_to_account`) are counted, never retried. `429`/`5xx`/network
+  errors re-queue the batch; `400`/`401`/`413`/`422` drop it.
+- `413 Payload Too Large` is now mapped to `ValidationError` (previously
+  `ServerError`) for every request, since retrying the same body cannot help.
+- Log redaction now masks `page_path`, `page_title`, `path`, `title` and
+  `referrer_path`.
+
+## 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.2.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: centive-sdk
-Version: 2.1.0.dev2
+Version: 2.2.0.dev4
 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
@@ -194,6 +195,11 @@ an expired connection token.
 | `ws_host`             | `str`           | `0.0.0.0`                               | websocket bind address (`127.0.0.1` behind a proxy) |
 | `ws_port`             | `int`           | `8765`                                  | websocket server port                 |
 | `ws_auth_mode`        | `"token" \| "open"` | `"token"`                           | connection identity binding (see Security) |
+| `telemetry_enabled`   | `bool`        | `True`                              | accept `telemetry` frames and forward page events |
+| `telemetry_flush_interval_seconds` | `float` | `2.0`                     | max time an event waits before being sent |
+| `telemetry_flush_max_events` | `int`  | `50`                                | send when this many events are queued |
+| `telemetry_max_queue_events` | `int`  | `5000`                              | bounded queue; oldest dropped when full |
+| `telemetry_rate_per_connection_per_minute` | `int` | `120`               | telemetry frames accepted per socket per minute |
 | `ws_token_ttl_seconds`| `float`         | `3600.0`                                | how long a connection token stays valid |
 | `ws_allowed_origins`  | `list[str]`     | `None`                                  | allow-list of Origin headers for WS handshakes |
 | `ws_handshake_secret` | `str`           | `None`                                  | static shared secret (legacy `"open"` mode only) |
@@ -205,10 +211,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 +523,133 @@ client = AsyncCentiveClient(
 
 For details on WebSocket event formats, see `websocket_messages.md`.
 
+## Page Tracking (Product Events)
+
+From v2.2.0 the websocket server also accepts `type: "telemetry"` frames from
+the browser SDK. These carry page views and page leaves for the connected end
+user. The SDK validates each frame, queues the events, and forwards them to
+Centive in batches (every 2 seconds or 50 events, whichever comes first).
+
+Nothing is required from your code beyond what you already do for the avatar:
+`initialize_websocket()` starts the queue and `aclose()` flushes it.
+
+```python
+# Optional: emit your own server-side events into the same pipe.
+client.telemetry.track(user_id, "invoice_paid", {"amount": 120})
+
+# Optional: inspect the queue.
+client.telemetry.stats()
+# {'enqueued': 412, 'sent': 410, 'accepted': 398, 'rejected': 12,
+#  'rejections_by_reason': {'user_not_mapped_to_account': 12}, 'queue_depth': 2, ...}
+```
+
+Context back to Aria: when a user has a live Aria session, Centive answers the
+events call with short context lines ("The user just opened the Invoices
+page."). The SDK pushes each one to that user's browser as a `context` frame
+and the browser SDK hands it to the avatar with `anamClient.addContext`. This
+is why page tracking exists: Aria knows where the user is while they talk.
+
+What Centive keeps: only events for end users that `tool_mapping` linked to an
+account in your organization. Events for other users come back in the `202`
+response as `rejected` with reason `user_not_mapped_to_account`; they are
+counted in `stats()` and never retried. If that number is high, the
+`company_name` you pass to `tool_mapping` does not match the account names in
+Centive.
+
+Safety properties:
+
+- The browser cannot spoof identity: the frame's `user_id` must match the user
+  bound to the socket, exactly like transcript frames.
+- Frames over 100 events or 64 KB, and more than 120 frames per minute per
+  connection, are dropped with a reasoned ack. The socket is never closed for
+  a telemetry violation.
+- The queue is bounded (`telemetry_max_queue_events`, default 5000). When full,
+  the oldest events are dropped and counted. The websocket handler never blocks.
+- Telemetry has its own circuit breaker; a failing events endpoint cannot stop
+  transcript saves.
+- Set `telemetry_enabled=False` to turn the feature off entirely.
+
+Wire contract: `docs/product-events/CONTRACTS.md` in the CentiveAI repository.
+
+## 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.2.0.dev4}/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
@@ -161,6 +162,11 @@ an expired connection token.
 | `ws_host`             | `str`           | `0.0.0.0`                               | websocket bind address (`127.0.0.1` behind a proxy) |
 | `ws_port`             | `int`           | `8765`                                  | websocket server port                 |
 | `ws_auth_mode`        | `"token" \| "open"` | `"token"`                           | connection identity binding (see Security) |
+| `telemetry_enabled`   | `bool`        | `True`                              | accept `telemetry` frames and forward page events |
+| `telemetry_flush_interval_seconds` | `float` | `2.0`                     | max time an event waits before being sent |
+| `telemetry_flush_max_events` | `int`  | `50`                                | send when this many events are queued |
+| `telemetry_max_queue_events` | `int`  | `5000`                              | bounded queue; oldest dropped when full |
+| `telemetry_rate_per_connection_per_minute` | `int` | `120`               | telemetry frames accepted per socket per minute |
 | `ws_token_ttl_seconds`| `float`         | `3600.0`                                | how long a connection token stays valid |
 | `ws_allowed_origins`  | `list[str]`     | `None`                                  | allow-list of Origin headers for WS handshakes |
 | `ws_handshake_secret` | `str`           | `None`                                  | static shared secret (legacy `"open"` mode only) |
@@ -172,10 +178,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 +490,133 @@ client = AsyncCentiveClient(
 
 For details on WebSocket event formats, see `websocket_messages.md`.
 
+## Page Tracking (Product Events)
+
+From v2.2.0 the websocket server also accepts `type: "telemetry"` frames from
+the browser SDK. These carry page views and page leaves for the connected end
+user. The SDK validates each frame, queues the events, and forwards them to
+Centive in batches (every 2 seconds or 50 events, whichever comes first).
+
+Nothing is required from your code beyond what you already do for the avatar:
+`initialize_websocket()` starts the queue and `aclose()` flushes it.
+
+```python
+# Optional: emit your own server-side events into the same pipe.
+client.telemetry.track(user_id, "invoice_paid", {"amount": 120})
+
+# Optional: inspect the queue.
+client.telemetry.stats()
+# {'enqueued': 412, 'sent': 410, 'accepted': 398, 'rejected': 12,
+#  'rejections_by_reason': {'user_not_mapped_to_account': 12}, 'queue_depth': 2, ...}
+```
+
+Context back to Aria: when a user has a live Aria session, Centive answers the
+events call with short context lines ("The user just opened the Invoices
+page."). The SDK pushes each one to that user's browser as a `context` frame
+and the browser SDK hands it to the avatar with `anamClient.addContext`. This
+is why page tracking exists: Aria knows where the user is while they talk.
+
+What Centive keeps: only events for end users that `tool_mapping` linked to an
+account in your organization. Events for other users come back in the `202`
+response as `rejected` with reason `user_not_mapped_to_account`; they are
+counted in `stats()` and never retried. If that number is high, the
+`company_name` you pass to `tool_mapping` does not match the account names in
+Centive.
+
+Safety properties:
+
+- The browser cannot spoof identity: the frame's `user_id` must match the user
+  bound to the socket, exactly like transcript frames.
+- Frames over 100 events or 64 KB, and more than 120 frames per minute per
+  connection, are dropped with a reasoned ack. The socket is never closed for
+  a telemetry violation.
+- The queue is bounded (`telemetry_max_queue_events`, default 5000). When full,
+  the oldest events are dropped and counted. The websocket handler never blocks.
+- Telemetry has its own circuit breaker; a failing events endpoint cannot stop
+  transcript saves.
+- Set `telemetry_enabled=False` to turn the feature off entirely.
+
+Wire contract: `docs/product-events/CONTRACTS.md` in the CentiveAI repository.
+
+## 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.2.0.dev4}/blackbox/customer_app.py

@@ -6,6 +6,8 @@ the blackbox suite exercises the published artifact rather than the source tree.
 Driven over stdin so no extra web framework is needed:
     login <user_id>   -> prints "URL <websocket url>" or "URL none" (paused)
     stats             -> prints "STATS <json>"
+    telemetry_stats   -> prints "STATS <json>" for the product-events queue
+    track <user> <ev> -> queues a server-side product event, prints "TRACKED true|false"
     quit              -> shuts down
 
 Everything the SDK logs goes to LOG_FILE, which the suite scans for canaries.
@@ -45,6 +47,14 @@ def build_client() -> AsyncCentiveClient:
         options["incremental_save_enabled"] = True
     if os.environ.get("MAX_SESSIONS_PER_USER"):
         options["max_sessions_per_user"] = int(os.environ["MAX_SESSIONS_PER_USER"])
+    if os.environ.get("TELEMETRY_FLUSH_INTERVAL_SECONDS"):
+        options["telemetry_flush_interval_seconds"] = float(
+            os.environ["TELEMETRY_FLUSH_INTERVAL_SECONDS"]
+        )
+    if os.environ.get("TELEMETRY_RATE_PER_CONNECTION_PER_MINUTE"):
+        options["telemetry_rate_per_connection_per_minute"] = int(
+            os.environ["TELEMETRY_RATE_PER_CONNECTION_PER_MINUTE"]
+        )
     if os.environ.get("MAX_STREAM_MESSAGES_PER_SESSION"):
         options["max_stream_messages_per_session"] = int(
             os.environ["MAX_STREAM_MESSAGES_PER_SESSION"]
@@ -88,6 +98,17 @@ async def main() -> int:
                 print(f"STATS {json.dumps(stats)}", flush=True)
                 continue
 
+            if cmd == "telemetry_stats":
+                print(f"STATS {json.dumps(client.telemetry.stats())}", flush=True)
+                continue
+
+            if cmd == "track":
+                # track <user_id> <event_type>: a server-side event, as a
+                # customer backend would emit for e.g. "invoice_paid".
+                ok = client.telemetry.track(parts[1], parts[2], {"source": "customer_app"})
+                print(f"TRACKED {json.dumps(ok)}", flush=True)
+                continue
+
             print(f"ERROR unknown command {cmd}", flush=True)
     finally:
         await client.aclose()

{centive_sdk-2.1.0.dev2 → centive_sdk-2.2.0.dev4}/blackbox/harness.py

@@ -102,6 +102,22 @@ class MockApi:
             if rec["path"] == "/api/anam/save-messages"
         ]
 
+    def events(self) -> list:
+        """Recorded POST /anam/events bodies, oldest first."""
+        return [
+            rec["body"] for rec in self.recorded()
+            if rec["path"] == "/api/anam/events"
+        ]
+
+    def event_batches(self) -> list:
+        """Flattened (external_user_id, event) pairs across all recorded posts."""
+        pairs = []
+        for body in self.events():
+            for batch in body.get("batches", []):
+                for event in batch.get("events", []):
+                    pairs.append((batch.get("external_user_id"), event))
+        return pairs
+
     def set_fail_mode(self, mode: str) -> None:
         httpx.post(f"{self.control_url}/fail", json={"mode": mode}, timeout=10).raise_for_status()
 
@@ -162,6 +178,16 @@ class CustomerApp:
         assert reply.startswith("STATS "), f"unexpected reply: {reply}"
         return json.loads(reply[6:])
 
+    def telemetry_stats(self) -> dict:
+        reply = self._command("telemetry_stats")
+        assert reply.startswith("STATS "), f"unexpected reply: {reply}"
+        return json.loads(reply[6:])
+
+    def track(self, user_id: str, event_type: str) -> bool:
+        reply = self._command(f"track {user_id} {event_type}")
+        assert reply.startswith("TRACKED "), f"unexpected reply: {reply}"
+        return json.loads(reply[8:])
+
     def is_alive(self) -> bool:
         return self.proc.poll() is None
 

{centive_sdk-2.1.0.dev2 → centive_sdk-2.2.0.dev4}/blackbox/mock_centive_api.py

@@ -169,6 +169,45 @@ class Handler(BaseHTTPRequestHandler):
             })
             return
 
+        if path == "/api/anam/events":
+            if _fail_mode["mode"] == "events_503":
+                self._send(503, UPSTREAM_ERROR_BODY)
+                return
+            if _fail_mode["mode"] == "events_401":
+                self._send(401, {"detail": "Invalid API key CANARY-401-DETAIL"})
+                return
+            total = sum(len(b.get("events", [])) for b in body.get("batches", []))
+            # Users whose id starts with "unmapped" stand in for end users the
+            # real API cannot link to an account: rejected, never stored.
+            rejections = [
+                {
+                    "external_user_id": b["external_user_id"],
+                    "reason": "user_not_mapped_to_account",
+                    "count": len(b.get("events", [])),
+                }
+                for b in body.get("batches", [])
+                if str(b.get("external_user_id", "")).startswith("unmapped")
+            ]
+            rejected = sum(r["count"] for r in rejections)
+            # Users whose id starts with "live" stand in for end users with a
+            # running Aria session: Centive hands back context for the browser.
+            context = [
+                {
+                    "external_user_id": b["external_user_id"],
+                    "content": f"CANARY-CONTEXT-{b['external_user_id']} just opened a page.",
+                    "expires_at": "2099-01-01T00:00:00Z",
+                }
+                for b in body.get("batches", [])
+                if str(b.get("external_user_id", "")).startswith("live")
+            ]
+            self._send(202, {
+                "accepted": total - rejected,
+                "rejected": rejected,
+                "rejections": rejections,
+                "context": context,
+            })
+            return
+
         if path == "/api/anam/save-messages":
             if _fail_mode["mode"] == "save_400":
                 self._send(400, UPSTREAM_ERROR_BODY)