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

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

@@ -2,6 +2,51 @@
 
 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

{centive_sdk-2.1.0.dev3 → centive_sdk-2.2.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: centive-sdk
-Version: 2.1.0.dev3
+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
@@ -195,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) |
@@ -518,6 +523,54 @@ 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

{centive_sdk-2.1.0.dev3 → centive_sdk-2.2.0.dev4}/README.md

@@ -162,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) |
@@ -485,6 +490,54 @@ 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

{centive_sdk-2.1.0.dev3 → 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.dev3 → 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.dev3 → 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)

centive_sdk-2.2.0.dev4/blackbox/test_blackbox_telemetry.py

@@ -0,0 +1,250 @@
+"""Blackbox coverage for the ``telemetry`` frame (product events / page tracking).
+
+Same stance as test_blackbox.py: the SDK is an opaque process, mallory holds a
+legitimate token, and every upstream value is a canary. What must hold:
+
+- Events mallory sends are attributed to mallory, never to the user_id in the
+  frame body.
+- Events reach the Centive API in the C2 shape with the org API key.
+- Upstream failures (503, 401) never surface to the browser and never leak
+  their bodies into the customer's logs.
+- A telemetry violation never closes the socket.
+"""
+
+import asyncio
+import json
+import sys
+import uuid
+from pathlib import Path
+
+import pytest
+import websockets
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from harness import CustomerApp, MockApi  # noqa: E402
+from mock_centive_api import API_KEY  # noqa: E402
+
+pytestmark = pytest.mark.asyncio
+
+RECV_TIMEOUT = 10.0
+
+
+@pytest.fixture(scope="module")
+def mock_api():
+    api = MockApi()
+    yield api
+    api.stop()
+
+
+@pytest.fixture(scope="module")
+def app(mock_api, tmp_path_factory):
+    log = tmp_path_factory.mktemp("logs") / "customer.log"
+    application = CustomerApp(mock_api, log, TELEMETRY_FLUSH_INTERVAL_SECONDS="0.2")
+    yield application
+    application.stop()
+
+
+@pytest.fixture(autouse=True)
+def _reset(mock_api):
+    mock_api.reset()
+    yield
+    mock_api.set_fail_mode("none")
+
+
+async def recv_json(ws):
+    return json.loads(await asyncio.wait_for(ws.recv(), timeout=RECV_TIMEOUT))
+
+
+async def connect(url):
+    ws = await websockets.connect(url, open_timeout=RECV_TIMEOUT)
+    await recv_json(ws)  # session payload on connect
+    return ws
+
+
+async def wait_for(predicate, timeout=15.0, interval=0.1):
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+    while loop.time() < deadline:
+        value = predicate()
+        if value:
+            return value
+        await asyncio.sleep(interval)
+    return None
+
+
+def page_view(path="/CANARY-PATH/42", **over):
+    base = {
+        "client_event_id": str(uuid.uuid4()),
+        "event_type": "page_view",
+        "occurred_at": "2026-08-27T10:00:00Z",
+        "browser_session_id": "bs_1",
+        "page": {"path": path, "pattern": "/CANARY-PATH/:id", "title": "CANARY-TITLE"},
+        "detection": "history",
+        "properties": {},
+    }
+    base.update(over)
+    return base
+
+
+def frame(user_id, events):
+    return json.dumps({
+        "type": "telemetry", "schema": 1, "user_id": user_id,
+        "sdk": "aria-sdk/1.0.0", "events": events,
+    })
+
+
+async def test_events_are_forwarded_in_c2_shape_with_api_key(app, mock_api):
+    ws = await connect(app.login("alice"))
+    try:
+        marker = f"/pages/{uuid.uuid4()}"
+        await ws.send(frame("alice", [page_view(path=marker)]))
+        ack = await recv_json(ws)
+        assert ack["type"] == "telemetry_ack" and ack["accepted"] == 1
+
+        posted = await wait_for(lambda: [
+            b for b in mock_api.events()
+            if any(ev["page"]["path"] == marker for bt in b["batches"] for ev in bt["events"])
+        ])
+        assert posted, "event never reached the API"
+        body = posted[0]
+        assert body["schema"] == 1
+        assert body["sdk_version"].startswith("python/")
+        batch = next(b for b in body["batches"] if b["external_user_id"] == "alice")
+        assert batch["client_sdk"] == "aria-sdk/1.0.0"
+
+        keys = [rec["api_key_header"] for rec in mock_api.recorded() if rec["path"] == "/api/anam/events"]
+        assert keys and all(k == API_KEY for k in keys)
+    finally:
+        await ws.close()
+
+
+async def test_forged_user_id_never_reaches_api_and_socket_stays_open(app, mock_api):
+    """Mallory claims to be alice inside the frame body."""
+    ws = await connect(app.login("mallory"))
+    try:
+        marker = f"/forged/{uuid.uuid4()}"
+        await ws.send(frame("alice", [page_view(path=marker)]))
+        first = await recv_json(ws)
+        assert first.get("error") == "IDENTITY_MISMATCH"
+
+        # Still connected: an honest frame goes through.
+        honest = f"/honest/{uuid.uuid4()}"
+        await ws.send(frame("mallory", [page_view(path=honest)]))
+        assert (await recv_json(ws))["accepted"] == 1
+
+        await wait_for(lambda: any(e["page"]["path"] == honest for _, e in mock_api.event_batches()))
+        attributed = [(uid, e["page"]["path"]) for uid, e in mock_api.event_batches()]
+        assert (None, marker) not in attributed
+        assert all(path != marker for _, path in attributed), "forged event was forwarded"
+        assert all(uid != "alice" for uid, _ in attributed), "event attributed to the victim"
+    finally:
+        await ws.close()
+
+
+async def test_frame_without_user_id_is_attributed_to_bound_user(app, mock_api):
+    ws = await connect(app.login("bob"))
+    try:
+        marker = f"/nouser/{uuid.uuid4()}"
+        payload = json.loads(frame("x", [page_view(path=marker)]))
+        del payload["user_id"]
+        await ws.send(json.dumps(payload))
+        assert (await recv_json(ws))["accepted"] == 1
+        pairs = await wait_for(lambda: [p for p in mock_api.event_batches() if p[1]["page"]["path"] == marker])
+        assert pairs and pairs[0][0] == "bob"
+    finally:
+        await ws.close()
+
+
+async def test_upstream_503_body_never_reaches_browser_or_logs(app, mock_api):
+    mock_api.set_fail_mode("events_503")
+    ws = await connect(app.login("alice"))
+    try:
+        await ws.send(frame("alice", [page_view()]))
+        assert (await recv_json(ws))["accepted"] == 1
+        # The SDK retries 5xx with backoff before recording a failure, so
+        # wait for the retries to run out rather than for the first POST.
+        stats = await wait_for(
+            lambda: (lambda s: s if s["flush_failures"] >= 1 else None)(app.telemetry_stats()),
+            timeout=30,
+        )
+        assert stats is not None, "flush never recorded the upstream failure"
+        assert stats["queue_depth"] >= 1  # kept for retry, not lost
+        with pytest.raises(asyncio.TimeoutError):
+            await asyncio.wait_for(ws.recv(), timeout=1.0)
+    finally:
+        await ws.close()
+    logs = app.logs()
+    assert "CANARY-UPSTREAM-ERROR-BODY" not in logs
+    assert "CANARY-UPSTREAM-DSN" not in logs
+    assert API_KEY not in logs
+
+
+async def test_upstream_401_is_dropped_quietly_without_leaking(app, mock_api):
+    mock_api.set_fail_mode("events_401")
+    ws = await connect(app.login("alice"))
+    try:
+        await ws.send(frame("alice", [page_view()]))
+        assert (await recv_json(ws))["accepted"] == 1
+        await wait_for(lambda: mock_api.events(), timeout=10)
+        await wait_for(lambda: app.telemetry_stats()["dropped_non_retryable"] >= 1, timeout=10)
+        with pytest.raises(asyncio.TimeoutError):
+            await asyncio.wait_for(ws.recv(), timeout=1.0)
+    finally:
+        await ws.close()
+    assert API_KEY not in app.logs()
+
+
+async def test_page_paths_do_not_appear_in_info_logs(app, mock_api):
+    ws = await connect(app.login("alice"))
+    try:
+        await ws.send(frame("alice", [page_view(path="/CANARY-SECRET-PATH/99")]))
+        assert (await recv_json(ws))["accepted"] == 1
+        await wait_for(lambda: mock_api.events())
+    finally:
+        await ws.close()
+    info_lines = [line for line in app.logs().splitlines() if not line.startswith("DEBUG")]
+    assert not any("CANARY-SECRET-PATH" in line for line in info_lines)
+
+
+async def test_rejections_from_api_are_final_and_counted(app, mock_api):
+    ws = await connect(app.login("unmapped_carol"))
+    try:
+        await ws.send(frame("unmapped_carol", [page_view(), page_view()]))
+        assert (await recv_json(ws))["accepted"] == 2
+        await wait_for(lambda: mock_api.events())
+        stats = await wait_for(lambda: (lambda s: s if s["rejected"] >= 2 else None)(app.telemetry_stats()))
+        assert stats["rejections_by_reason"].get("user_not_mapped_to_account", 0) >= 2
+        posts_before = len(mock_api.events())
+        await asyncio.sleep(0.8)
+        assert len(mock_api.events()) == posts_before, "rejected events were retried"
+    finally:
+        await ws.close()
+
+
+async def test_server_side_track_is_forwarded(app, mock_api):
+    assert app.track("alice", "invoice_paid") is True
+    pairs = await wait_for(lambda: [p for p in mock_api.event_batches() if p[1]["event_type"] == "invoice_paid"])
+    assert pairs and pairs[0][0] == "alice"
+
+
+async def test_live_context_reaches_only_its_own_user(app, mock_api):
+    """Centive's context for live_alice must arrive on alice's socket and never
+    on another connected user's socket."""
+    alice = await connect(app.login("live_alice"))
+    mallory = await connect(app.login("mallory"))
+    try:
+        await alice.send(frame("live_alice", [page_view()]))
+        assert (await recv_json(alice))["type"] == "telemetry_ack"
+        ctx = await recv_json(alice)
+        assert ctx["type"] == "context"
+        assert ctx["schema"] == 1
+        assert ctx["content"] == "CANARY-CONTEXT-live_alice just opened a page."
+        assert ctx["source"] == "centive"
+        with pytest.raises(asyncio.TimeoutError):
+            await asyncio.wait_for(mallory.recv(), timeout=1.0)
+        stats = await wait_for(lambda: (lambda s: s if s["context_delivered"] >= 1 else None)(app.telemetry_stats()))
+        assert stats is not None
+    finally:
+        await alice.close()
+        await mallory.close()

{centive_sdk-2.1.0.dev3 → centive_sdk-2.2.0.dev4}/pyproject.toml

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

{centive_sdk-2.1.0.dev3 → centive_sdk-2.2.0.dev4}/src/centive_sdk/__init__.py

@@ -14,21 +14,27 @@ from .exceptions import (
 from .models.requests import (
     MessageHistoryEvent,
     MessageStreamEvent,
+    ProductEventBatchRequest,
     SaveMessagesRequest,
     SessionEndEvent,
     SessionMessage,
     SessionMetadata,
     StreamMessage,
+    TelemetryEvent,
+    TelemetryFrame,
+    TelemetryUserBatch,
     ToolMappingRequest,
     TriggerSessionRequest,
 )
 from .models.responses import (
     PauseStatusResponse,
+    ProductEventIngestResponse,
     SaveMessagesResponse,
     ToolMappingResponse,
     TriggerSessionResponse,
 )
 from .resources.message_accumulator import MessageAccumulator
+from .resources.telemetry_batcher import TelemetryBatcher
 from .resources.websocket_server import WebSocketServer
 
 try:
@@ -52,14 +58,20 @@ __all__ = [
     "MessageHistoryEvent",
     "MessageStreamEvent",
     "SessionEndEvent",
+    "TelemetryEvent",
+    "TelemetryFrame",
+    "TelemetryUserBatch",
+    "ProductEventBatchRequest",
     # Response Models
     "ToolMappingResponse",
     "TriggerSessionResponse",
     "SaveMessagesResponse",
     "PauseStatusResponse",
+    "ProductEventIngestResponse",
     # Resources
     "WebSocketServer",
     "MessageAccumulator",
+    "TelemetryBatcher",
     # Exceptions
     "CentiveError",
     "AuthError",

{centive_sdk-2.1.0.dev3 → centive_sdk-2.2.0.dev4}/src/centive_sdk/_logging.py

@@ -72,6 +72,11 @@ def redact_request_data(data: dict) -> dict:
     if "company_name" in redacted:
         redacted["company_name"] = mask_string(str(redacted["company_name"]))
 
+    # Page paths and titles can carry identifiers from the customer's app.
+    for path_field in ("page_path", "page_title", "path", "title", "referrer_path"):
+        if path_field in redacted:
+            redacted[path_field] = mask_string(str(redacted[path_field]))
+
     for secret_field in ("api_key", "token", "connection_token", "ws_handshake_secret"):
         if secret_field in redacted:
             redacted[secret_field] = "[REDACTED]"