centive-sdk 2.1.0.dev2__py3-none-any.whl → 2.2.0.dev4__py3-none-any.whl

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/_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]"

centive_sdk/async_client.py

@@ -7,6 +7,8 @@ from ._logging import safe_log
 from .config import ClientConfig
 from .models.responses import PauseStatusResponse
 from .resources.async_sessions import AsyncSessions
+from .resources.async_telemetry import AsyncTelemetry
+from .resources.telemetry_batcher import TelemetryBatcher
 from .resources.websocket_server import WebSocketServer
 
 
@@ -40,6 +42,13 @@ 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"]. By default the SDK also forwards these
+        events to Centive (POST /anam/events); the callback is an additional
+        sink. With telemetry_enabled=False and no callback, frames are
+        acknowledged and dropped.
         """
         if api_key is not None:
             options["api_key"] = api_key
@@ -48,7 +57,14 @@ 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._telemetry_batcher = TelemetryBatcher(
+            send=self.sessions.send_events, config=self.config, logger=self._logger
+        )
+        self.telemetry = AsyncTelemetry(self._telemetry_batcher, self._logger)
         self._ws_server: Optional[WebSocketServer] = None
         self._last_pause_status: Optional[PauseStatusResponse] = None
         # One process serves many users; serialize server startup so concurrent
@@ -128,14 +144,38 @@ class AsyncCentiveClient:
                     sessions=self.sessions,
                     config=self.config,
                     logger=self._logger,
+                    telemetry=self._telemetry_batcher,
+                    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.
                 await server.start(host=ws_host, port=ws_port, **ws_options)
                 self._ws_server = server
+                self._telemetry_batcher.on_context = self._relay_live_context
+                self._telemetry_batcher.start()
 
         return self._ws_server.register_user(user_id)
 
+    async def _relay_live_context(self, user_id: str, entry: dict) -> int:
+        """Pushes a Centive context entry to the user's browser as a C4 frame.
+
+        The browser SDK calls anamClient.addContext with it; Anam has no
+        server-side way to inform a running session. Only the connection bound
+        to this user receives it (send_to_user), never a broadcast.
+        """
+        server = self._ws_server
+        if server is None or not server.is_running:
+            return 0
+        frame = {
+            "type": "context",
+            "schema": 1,
+            "content": str(entry.get("content", ""))[:1000],
+            "source": "centive",
+        }
+        if entry.get("expires_at"):
+            frame["expires_at"] = entry["expires_at"]
+        return await server.send_to_user(user_id, frame)
+
     async def get_aria_status(self, user_id: str) -> PauseStatusResponse:
         """Checks if Aria is paused for a user (for UI display purposes).
 
@@ -170,6 +210,9 @@ class AsyncCentiveClient:
             await self._ws_server.stop()
             self._ws_server = None
 
+        # Flush queued page events before the HTTP client goes away.
+        await self._telemetry_batcher.stop()
+
         await self._http_client.aclose()
 
     async def __aenter__(self) -> "AsyncCentiveClient":

centive_sdk/config.py

@@ -38,6 +38,7 @@ class ClientConfig(BaseModel):
     trigger_session_path: str = "/anam/trigger-session"
     save_messages_path: str = "/anam/save-messages"
     pause_status_path: str = "/anam/pause-status"
+    events_path: str = "/anam/events"
     timeout_seconds: float = 10.0
     max_retries: int = 3
     initial_retry_delay: float = 0.5
@@ -83,11 +84,34 @@ 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.
     pause_check_fail_open: bool = True
 
+    # Product events (page tracking) forwarded from FE "telemetry" frames to
+    # POST /anam/events. Contract: CentiveAI docs/product-events/CONTRACTS.md.
+    telemetry_enabled: bool = True
+    # Flush when this many events are queued, or after the interval, whichever first.
+    telemetry_flush_max_events: int = 50
+    telemetry_flush_interval_seconds: float = 2.0
+    # Bounded in-memory queue; oldest events are dropped (and counted) when full.
+    telemetry_max_queue_events: int = 5000
+    # Per-frame caps (C1 limits) live above as max_telemetry_* — they are
+    # shared with the validation the host-callback path uses.
+    # Telemetry frames accepted per websocket connection per minute (0 disables).
+    telemetry_rate_per_connection_per_minute: int = 120
+
     incremental_save_enabled: bool = Field(
         default=False,
         description="enable incremental message saving (sends messages to API immediately as they arrive)"

centive_sdk/models/__init__.py

@@ -1,10 +1,27 @@
-from .requests import ToolMappingRequest, TriggerSessionRequest
-from .responses import PauseStatusResponse, ToolMappingResponse, TriggerSessionResponse
+from .requests import (
+    ProductEventBatchRequest,
+    TelemetryEvent,
+    TelemetryFrame,
+    TelemetryUserBatch,
+    ToolMappingRequest,
+    TriggerSessionRequest,
+)
+from .responses import (
+    PauseStatusResponse,
+    ProductEventIngestResponse,
+    ToolMappingResponse,
+    TriggerSessionResponse,
+)
 
 __all__ = [
     "ToolMappingRequest",
     "TriggerSessionRequest",
+    "TelemetryEvent",
+    "TelemetryFrame",
+    "TelemetryUserBatch",
+    "ProductEventBatchRequest",
     "ToolMappingResponse",
     "TriggerSessionResponse",
     "PauseStatusResponse",
+    "ProductEventIngestResponse",
 ]

centive_sdk/models/requests.py

@@ -1,6 +1,6 @@
-from typing import List, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
 class ToolMappingRequest(BaseModel):
@@ -86,3 +86,79 @@ class SessionEndEvent(BaseModel):
     type: Literal["session_end"] = "session_end"
     session_id: str = Field(..., description="session ID")
     user_id: str = Field(..., description="user ID")
+
+
+# ---------------------------------------------------------------------------
+# Product events (page tracking). Contract: CentiveAI docs/product-events/CONTRACTS.md
+# ---------------------------------------------------------------------------
+
+TELEMETRY_MAX_PROPERTIES_BYTES = 4 * 1024
+TELEMETRY_MAX_PATH_CHARS = 2048
+
+
+class TelemetryPage(BaseModel):
+    """page fields of a C1 event."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    path: str = Field(..., min_length=1, max_length=TELEMETRY_MAX_PATH_CHARS)
+    pattern: Optional[str] = Field(default=None, max_length=TELEMETRY_MAX_PATH_CHARS)
+    title: Optional[str] = Field(default=None, max_length=512)
+    referrer_path: Optional[str] = Field(default=None, max_length=TELEMETRY_MAX_PATH_CHARS)
+
+
+class TelemetryEvent(BaseModel):
+    """one C1 event as produced by the browser SDK; forwarded to Centive unchanged."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    client_event_id: str = Field(..., min_length=1, max_length=64)
+    event_type: str = Field(..., min_length=1, max_length=64)
+    occurred_at: str = Field(..., description="iso 8601 timestamp with timezone")
+    browser_session_id: Optional[str] = Field(default=None, max_length=64)
+    page: Optional[TelemetryPage] = None
+    duration_ms: Optional[int] = Field(default=None, ge=0)
+    detection: Optional[str] = Field(default=None, max_length=32)
+    properties: Dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("properties")
+    @classmethod
+    def _bound_properties(cls, value: Dict[str, Any]) -> Dict[str, Any]:
+        import json
+
+        if len(json.dumps(value, separators=(",", ":"), default=str)) > TELEMETRY_MAX_PROPERTIES_BYTES:
+            raise ValueError("properties_too_large")
+        return value
+
+
+class TelemetryFrame(BaseModel):
+    """event payload for type="telemetry" from FE SDK (C1)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    type: Literal["telemetry"] = "telemetry"
+    schema_version: int = Field(default=1, alias="schema")
+    user_id: Optional[str] = Field(default=None, max_length=255)
+    sdk: Optional[str] = Field(default=None, max_length=64)
+    events: List[TelemetryEvent] = Field(..., min_length=1)
+
+
+class TelemetryUserBatch(BaseModel):
+    """events for one end user inside a C2 request."""
+
+    external_user_id: str = Field(..., min_length=1, max_length=255)
+    client_sdk: Optional[str] = Field(default=None, max_length=64)
+    events: List[TelemetryEvent] = Field(..., min_length=1)
+
+
+class ProductEventBatchRequest(BaseModel):
+    """request payload for POST /anam/events (C2)."""
+
+    schema_version: int = Field(default=1, serialization_alias="schema")
+    sdk_version: Optional[str] = None
+    batches: List[TelemetryUserBatch]
+    idempotency_key: Optional[str] = Field(default=None, exclude=True)
+
+    @property
+    def total_events(self) -> int:
+        return sum(len(b.events) for b in self.batches)

centive_sdk/models/responses.py

@@ -59,3 +59,16 @@ class SaveMessagesResponse(BaseModel):
     time_taken: float = 0.0
     error: Optional[str] = None
     raw: Optional[Dict[str, Any]] = None
+
+
+class ProductEventIngestResponse(BaseModel):
+    """response from POST /anam/events (202)."""
+
+    accepted: int = 0
+    rejected: int = 0
+    rejections: list = Field(default_factory=list)
+    # Context for users with a live Aria session; relayed to the browser as a
+    # "context" frame (C4) for anamClient.addContext. Entries look like
+    # {"external_user_id", "content", "expires_at"}.
+    context: list = Field(default_factory=list)
+    raw: Optional[Dict[str, Any]] = None

centive_sdk/resources/async_sessions.py

@@ -8,9 +8,15 @@ from .._logging import safe_log
 from .._retry import calculate_backoff, extract_retry_after, should_retry
 from ..config import ClientConfig
 from ..exceptions import AuthError, NetworkError, RateLimitError, ServerError, ValidationError
-from ..models.requests import SaveMessagesRequest, ToolMappingRequest, TriggerSessionRequest
+from ..models.requests import (
+    ProductEventBatchRequest,
+    SaveMessagesRequest,
+    ToolMappingRequest,
+    TriggerSessionRequest,
+)
 from ..models.responses import (
     PauseStatusResponse,
+    ProductEventIngestResponse,
     SaveMessagesResponse,
     ToolMappingResponse,
     TriggerSessionResponse,
@@ -191,6 +197,35 @@ class AsyncSessions:
             raw=data,
         )
 
+    async def send_events(self, input: ProductEventBatchRequest) -> ProductEventIngestResponse:
+        """Sends a batch of product events (page views) to Centive.
+
+        Contract C2 in CentiveAI docs/product-events/CONTRACTS.md. A 202 is
+        final: the ``rejections`` in the response are not retryable. 429 and
+        5xx are retried with backoff like every other call; 400/413/422 raise
+        ``ValidationError`` and 401 raises ``AuthError``.
+        """
+        url = join_url(self._config.base_url, self._config.events_path)
+        headers = build_headers(self._config.api_key, idempotency_key=input.idempotency_key)
+        payload = input.model_dump(mode="json", by_alias=True)
+        if payload.get("sdk_version") is None:
+            from .. import __version__
+
+            payload["sdk_version"] = f"python/{__version__}"
+
+        response = await self._make_request(url, headers, payload)
+        try:
+            data = response.json()
+        except ValueError:
+            data = {}
+        return ProductEventIngestResponse(
+            accepted=int(data.get("accepted", 0)),
+            rejected=int(data.get("rejected", 0)),
+            rejections=list(data.get("rejections", []) or []),
+            context=list(data.get("context", []) or []),
+            raw=data,
+        )
+
     async def get_pause_status(self, user_id: str) -> PauseStatusResponse:
         """Checks if Aria is paused for a specific user.
 
@@ -381,7 +416,9 @@ class AsyncSessions:
                     error_detail = self._extract_error_message(response)
                     raise AuthError(f"Authentication failed: {error_detail}", request_id=request_id)
 
-                elif response.status_code in [400, 422]:
+                elif response.status_code in [400, 413, 422]:
+                    # 413 is "payload over the API's size caps": retrying the
+                    # same body cannot succeed, so it is a validation failure.
                     error_detail = self._extract_error_message(response)
                     raise ValidationError(
                         f"Validation error: {error_detail}", request_id=request_id

centive_sdk/resources/async_telemetry.py

@@ -0,0 +1,65 @@
+"""Server-side entry point for product events.
+
+Most events arrive from the browser through the websocket ``telemetry`` frame.
+This resource lets the customer's backend emit its own events (for example
+``invoice_paid``) into the same queue, and exposes queue statistics.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from .._logging import safe_log
+from ..models.requests import TelemetryEvent
+from .telemetry_batcher import TelemetryBatcher
+
+
+class AsyncTelemetry:
+    def __init__(self, batcher: TelemetryBatcher, logger: Optional[Any] = None):
+        self._batcher = batcher
+        self._logger = logger
+
+    def track(
+        self,
+        user_id: str,
+        event_type: str,
+        properties: Optional[Dict[str, Any]] = None,
+        *,
+        occurred_at: Optional[datetime] = None,
+        client_event_id: Optional[str] = None,
+        page_path: Optional[str] = None,
+    ) -> bool:
+        """Queues one server-side event for ``user_id``.
+
+        ``user_id`` must come from your own authentication, exactly like
+        ``tool_mapping``. Events for users Centive cannot link to an account are
+        dropped by the API, not stored. Returns False if the event was dropped
+        locally (telemetry disabled or queue full).
+        """
+        when = occurred_at or datetime.now(timezone.utc)
+        if when.tzinfo is None:
+            when = when.replace(tzinfo=timezone.utc)
+        event = TelemetryEvent(
+            client_event_id=client_event_id or str(uuid.uuid4()),
+            event_type=event_type,
+            occurred_at=when.isoformat(),
+            page={"path": page_path} if page_path else None,
+            detection="manual",
+            properties=properties or {},
+        )
+        accepted, dropped = self._batcher.enqueue(user_id, "python/server", [event])
+        if dropped:
+            safe_log(self._logger, "debug", "server-side telemetry event dropped", {"event_type": event_type})
+        return accepted > 0 and dropped == 0
+
+    async def flush(self) -> None:
+        """Sends everything queued right now. Normally not needed; the batcher
+        flushes every ``telemetry_flush_interval_seconds``."""
+        if not self._batcher.is_running:
+            self._batcher.start()
+        await self._batcher.flush()
+
+    def stats(self) -> Dict[str, Any]:
+        return self._batcher.stats()