scope-analytics 0.1.5__tar.gz → 0.1.6__tar.gz

{scope_analytics-0.1.5/scope_analytics.egg-info → scope_analytics-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scope-analytics
-Version: 0.1.5
+Version: 0.1.6
 Summary: AI-powered analytics SDK for backend applications with automatic LLM tracking
 Home-page: https://scopeai.dev
 Author: Scope AI
@@ -185,7 +185,7 @@ scope-run --dry-run uvicorn main:app
 | `SCOPE_API_KEY` | Yes | Your Scope Analytics API key |
 | `SCOPE_ENDPOINT` | No | Custom API endpoint |
 | `SCOPE_DEBUG` | No | Set to 'true' for debug logging |
-| `SCOPE_ENVIRONMENT` | No | Environment name (default: production) |
+| `SCOPE_ENVIRONMENT` | No | Environment tag on every event (default: production). When it is unset or `production`, events sent with a key you created for Staging or Development (Setup → Keys) are tagged with that key's environment instead |
 | `SCOPE_CAPTURE_HTTP` | No | Capture outbound calls to other services (default: on; `false` turns it off) |
 | `HTTPS_PROXY` / `NO_PROXY` / `SSL_CERT_FILE` | No | Honoured for the SDK's own connection to Scope (read from the environment only) |
 

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/README.md

@@ -130,7 +130,7 @@ scope-run --dry-run uvicorn main:app
 | `SCOPE_API_KEY` | Yes | Your Scope Analytics API key |
 | `SCOPE_ENDPOINT` | No | Custom API endpoint |
 | `SCOPE_DEBUG` | No | Set to 'true' for debug logging |
-| `SCOPE_ENVIRONMENT` | No | Environment name (default: production) |
+| `SCOPE_ENVIRONMENT` | No | Environment tag on every event (default: production). When it is unset or `production`, events sent with a key you created for Staging or Development (Setup → Keys) are tagged with that key's environment instead |
 | `SCOPE_CAPTURE_HTTP` | No | Capture outbound calls to other services (default: on; `false` turns it off) |
 | `HTTPS_PROXY` / `NO_PROXY` / `SSL_CERT_FILE` | No | Honoured for the SDK's own connection to Scope (read from the environment only) |
 

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/scope_analytics/__init__.py

@@ -6,10 +6,10 @@ AI-powered analytics with automatic LLM conversation tracking
 import atexit
 import logging
 import sys
-from typing import Optional
+from typing import Any, Optional
 
 from .config import ScopeConfig, DEFAULT_REDACT_PATTERNS
-from .context import ScopeContext
+from .context import ScopeContext, accepted_user_id
 from .deployment import DeploymentContext
 from .events import EventFormatter
 from .queue import EventQueue
@@ -503,6 +503,12 @@ class ScopeAnalytics:
         # version at all).
         event.setdefault("sdk_version", self.config.sdk_version)
         event.setdefault("environment", self.config.environment)
+        # The browser's visitor id rides an event the app records in a request a page running Scope's
+        # script made, as on the SDK's own events (0.1.6) — only then: a manual event's fields are the
+        # caller's.
+        anonymous_id = ScopeContext.get_anonymous_id()
+        if anonymous_id:
+            event.setdefault("anonymous_id", anonymous_id)
         if "session_id" not in event:
             # generate_temp (NOT ensure_session_id): ensure_ would PIN the temp id
             # into the contextvar as a side effect — in a long-lived worker with no
@@ -522,7 +528,7 @@ class ScopeAnalytics:
                 f"Manual event '{event_type}' failed validation and was dropped."
             )
 
-    def identify(self, user_id: str, traits: Optional[dict] = None):
+    def identify(self, user_id: Any, traits: Optional[dict] = None):
         """
         Identify a user and stitch their prior anonymous activity to them.
 
@@ -533,7 +539,9 @@ class ScopeAnalytics:
         current request context so subsequent events are attributed to them.
 
         Args:
-            user_id: Unique user identifier (whatever your app uses — email, sub, etc.)
+            user_id: Unique user identifier (whatever your app uses — email, sub, a database id) — text,
+                a whole number (kept as its digits, so 42 and "42" are one person), a UUID or an ObjectId,
+                up to 100 characters; anything else is ignored, and why said once (0.1.6)
             traits: Optional user traits (e.g., email, name, plan)
         """
         # Disabled construction has no formatter/queue (and possibly no config) —
@@ -541,9 +549,12 @@ class ScopeAnalytics:
         if not self.enabled:
             return
 
-        if not user_id:
+        if user_id is None:
             self.config.log("identify() called without a user_id - ignoring")
             return
+        user_id = accepted_user_id(user_id, "identify")
+        if user_id is None:
+            return
 
         # Capture the prior (anonymous) identity BEFORE overwriting the context,
         # so the stitcher can link pre-identification events to this user. Prefer

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/scope_analytics/client.py

@@ -42,6 +42,8 @@ class ScopeAPIClient:
 
         # Discard reasons already said (see _note_discard) — once each, not per batch.
         self._warned_discard_reasons = set()
+        # Single events refused or changed, by (kind, field, reason), already said (_note_refusals).
+        self._warned_refusals = set()
 
         # Create HTTP client
         self.client = self._build_http_client(config)
@@ -156,6 +158,7 @@ class ScopeAPIClient:
             # Check response
             if response.status_code == 200:
                 self._note_discard(response, len(events))
+                self._note_refusals(response)
                 self.config.log(f"✅ Successfully shipped {len(events)} events")
                 return True
             else:
@@ -181,7 +184,8 @@ class ScopeAPIClient:
         ``{"status": "discarded", "reason": ...}`` for a batch it will not keep — an IP the
         project excludes, for instance. Reading only the status code made such batches
         vanish without a word (the SDK logged "shipped"; the dashboard showed nothing).
-        Said once per reason, with where to look."""
+        Said once per reason, with where to look. (Single events it refused or changed:
+        _note_refusals.)"""
         try:
             body = response.json()
         except Exception:  # noqa: BLE001 - a non-JSON 200 is a stored batch as far as we know
@@ -193,8 +197,8 @@ class ScopeAPIClient:
             return
         self._warned_discard_reasons.add(reason)
         # The ingest's IP-exclusion reasons are user_excluded_ip and auto_excluded_login_ip
-        # (datacenter_ip exists but never fires for backend events); anything else gets the
-        # generic pointer rather than a guess.
+        # (the datacenter filter that never ran was removed from ingest on 2026-10-09); anything
+        # else gets the generic pointer rather than a guess.
         if reason.endswith("_ip"):
             where = (
                 "Events from this machine's IP are excluded for this project — see Setup → "
@@ -208,6 +212,37 @@ class ScopeAPIClient:
             f"This is said once per reason."
         )
 
+    def _note_refusals(self, response) -> None:
+        """The ingest judges each event on its own: one it cannot keep is refused alone, and one
+        it keeps with a change (an id it cannot keep, half of a character) is stored without it
+        — and the 200 says so, under ``rejected`` and ``repaired``: each event's place in the
+        batch, the field and the reason. Until the ingest judged each event, one such event
+        refused the whole batch. Said once per (field, reason), like a discard."""
+        try:
+            body = response.json()
+        except Exception:  # noqa: BLE001 - a non-JSON 200 is a stored batch as far as we know
+            return
+        if not isinstance(body, dict):
+            return
+        said = {
+            "rejected": "Scope refused an event ({why}); each event of a batch is judged on its own. "
+                        "This is said once per reason.",
+            "repaired": "Scope stored an event with a change ({why}). This is said once per reason.",
+        }
+        for kind, text in said.items():
+            problems = body.get(kind)
+            for problem in problems if isinstance(problems, list) else []:
+                if not isinstance(problem, dict):
+                    continue
+                field, reason = problem.get("field"), problem.get("reason")
+                # a reply not shaped as ours is not ours to say (nor to fail the shipped batch over)
+                if not isinstance(reason, str) or not (field is None or isinstance(field, str)):
+                    continue
+                if (kind, field, reason) in self._warned_refusals:
+                    continue
+                self._warned_refusals.add((kind, field, reason))
+                self.config.warn(text.format(why=f"{field}: {reason}" if field else reason))
+
     def test_connection(self) -> bool:
         """
         Test connection to API

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/scope_analytics/context.py

@@ -6,7 +6,9 @@ Handles session ID propagation across async boundaries
 import contextvars
 import functools
 import inspect
-from typing import Optional
+import logging
+import numbers
+from typing import Any, Optional
 from contextlib import contextmanager
 import uuid
 
@@ -70,6 +72,66 @@ _provider_call_in_flight: contextvars.ContextVar[bool] = contextvars.ContextVar(
 )
 
 
+# The longest id Scope keeps — a session, a visitor, a user: the ingest refuses a longer one (the Node
+# SDK's MAX_ID_LENGTH).
+MAX_ID_LENGTH = 100
+
+
+def fit_id(value: Any) -> Optional[str]:
+    """A session or visitor id from a request header as Scope keeps it: the text without the spaces
+    around it, of 1 to MAX_ID_LENGTH characters, else None — never cut, since a cut id could name
+    another session or visitor (0.1.6; the Node SDK's fitId). A session header that is not one falls
+    back to a temp session, as a missing one does."""
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    return value if 0 < len(value) <= MAX_ID_LENGTH else None
+
+
+# Why an app's id was ignored, each said once per process (a refused type is named, never the id).
+_warned_refused_user_id: set = set()
+
+
+def _refused(call: str, why: str) -> None:
+    if why not in _warned_refused_user_id:
+        _warned_refused_user_id.add(why)
+        logging.getLogger("scope_analytics").warning(
+            "[Scope SDK] %s() takes your app's id for the user — text, a whole number, a UUID or an ObjectId, "
+            "up to %d characters; one was ignored (%s)", call, MAX_ID_LENGTH, why)
+    return None
+
+
+def accepted_user_id(user_id: Any, call: str) -> Optional[str]:
+    """The app's id for a user as Scope keeps it — its text, of 1 to MAX_ID_LENGTH characters — or None,
+    and why said once per process (0.1.6). Text is kept as given; a whole number becomes its digits (42
+    and "42" are one person: a number used to ride the event as a number, and identify(0) was ignored as
+    if no id had been given); a UUID or an ObjectId (a Mongo id, Beanie's too) becomes its text, as 0.1.5
+    sent it. True/False, a float, a list and any other object are no id: Scope would keep whatever its
+    text happens to be (the Node SDK's rule refuses an object for the same reason; it keeps any number).
+    None gives no id and says nothing."""
+    if user_id is None:
+        return None
+    if isinstance(user_id, bool):
+        return _refused(call, "true/false")
+    if isinstance(user_id, numbers.Integral):
+        # past 100 digits it is no id; refused before it is turned into text, which Python 3.11+ refuses
+        # for one of more than 4,300 digits by raising — into the app's own call
+        if int(user_id).bit_length() > 333:   # 10**100 is 333 bits: anything longer has over 100 digits
+            return _refused(call, f"over {MAX_ID_LENGTH} characters")
+        text = str(int(user_id))
+    elif isinstance(user_id, str):
+        text = user_id
+    elif isinstance(user_id, uuid.UUID) or any(c.__name__ == "ObjectId" for c in type(user_id).__mro__):
+        text = str(user_id)
+    else:
+        return _refused(call, f"a {type(user_id).__name__}")
+    if not text:
+        return _refused(call, "empty")
+    if len(text) > MAX_ID_LENGTH:
+        return _refused(call, f"over {MAX_ID_LENGTH} characters")
+    return text
+
+
 class ScopeContext:
     """
     Manages request-scoped context using Python's contextvars.
@@ -99,14 +161,21 @@ class ScopeContext:
         return session_id_context.get()
 
     @staticmethod
-    def set_user_id(user_id: str) -> None:
+    def set_user_id(user_id: Any) -> None:
         """
         Set the user ID for the current context
 
         Args:
-            user_id: User ID from backend application
+            user_id: The app's id for the user — text, a whole number (kept as its digits), a UUID or an
+                ObjectId, up to 100 characters; anything else is ignored, and why said once (0.1.6). None
+                clears it.
         """
-        user_id_context.set(user_id)
+        if user_id is None:
+            user_id_context.set(None)
+            return
+        accepted = accepted_user_id(user_id, "set_user_id")
+        if accepted is not None:
+            user_id_context.set(accepted)
 
     @staticmethod
     def get_user_id() -> Optional[str]:

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/scope_analytics/events.py

@@ -153,6 +153,10 @@ class EventFormatter:
             "timestamp": datetime.now(timezone.utc).isoformat(),
             "session_id": session_id or ScopeContext.ensure_session_id(),
             "user_id": user_id,
+            # the browser's visitor id (X-Scope-Anonymous-ID), when a page running Scope's script made the
+            # request — beside user_id, which a login token's user replaces (0.1.6): the sign-in and the
+            # browser it was used in, recorded together. None when no page sent one.
+            "anonymous_id": ScopeContext.get_anonymous_id(),
 
             # Request context for conversation correlation
             # This enables the fallback chain: thread_id → session_id+url → session_id
@@ -234,6 +238,7 @@ class EventFormatter:
             "timestamp": datetime.now(timezone.utc).isoformat(),
             "session_id": session_id or ScopeContext.ensure_session_id(),
             "user_id": user_id,
+            "anonymous_id": ScopeContext.get_anonymous_id(),   # as on llm_call (0.1.6)
 
             # HTTP request specific fields
             "method": method,
@@ -330,6 +335,7 @@ class EventFormatter:
             # count. One background session per process says what actually happened.
             "session_id": session_id or ScopeContext.background_session_id(),
             "user_id": user_id,
+            "anonymous_id": ScopeContext.get_anonymous_id(),   # as on llm_call (0.1.6)
 
             # API call specific fields
             "method": method,

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/scope_analytics/middleware.py

@@ -27,7 +27,7 @@ import time
 import base64
 import json
 from typing import Optional, Callable, Any
-from .context import ScopeContext
+from .context import ScopeContext, MAX_ID_LENGTH, fit_id
 
 logger = logging.getLogger("scope_analytics.middleware")
 
@@ -184,13 +184,14 @@ def _extract_user_id_from_jwt(auth_header: Optional[str]) -> Optional[str]:
         payload_bytes = base64.b64decode(payload_b64)
         payload = json.loads(payload_bytes.decode("utf-8"))
 
-        # Look for user ID in standard claims
+        # Look for user ID in standard claims — an object or a list names no user (the next claim
+        # may), and an id longer than Scope keeps is no user either: the browser's visitor id stands
+        # instead, as in the Node SDK (a longer one was dropped from every event it rode in)
         for claim in JWT_USER_ID_CLAIMS:
-            if claim in payload:
-                user_id = payload[claim]
-                # Convert to string if needed
-                if user_id is not None:
-                    return str(user_id)
+            user_id = payload.get(claim)
+            if user_id is not None and not isinstance(user_id, (dict, list)):
+                user_id = str(user_id)
+                return user_id if len(user_id) <= MAX_ID_LENGTH else None
 
         return None
 
@@ -226,11 +227,12 @@ def _auto_set_identity_from_headers(headers: dict) -> None:
         if key.lower() == "x-scope-anonymous-id":
             anonymous_id = value
             break
-    # Defensive: ignore an absurd client-supplied value. It would be rejected at
-    # ingestion anyway (user_id is length-capped), but don't carry it around or
-    # let it become a runaway index key.
-    if anonymous_id and len(anonymous_id) > 256:
-        anonymous_id = None
+    # This id becomes the events' user_id, and Scope keeps a user id of at most
+    # MAX_ID_LENGTH characters (a longer one is dropped from its event; until
+    # 2026-10-29 it cost the whole batch). Longer is ignored, as if absent —
+    # never cut, since a cut id could name another visitor — and the spaces
+    # around it are not part of it (0.1.6, as the Node SDK reads it).
+    anonymous_id = fit_id(anonymous_id)
     if anonymous_id:
         ScopeContext.set_anonymous_id(anonymous_id)
 
@@ -267,22 +269,25 @@ def extract_session_from_headers(headers: dict) -> Optional[str]:
         headers: Dictionary of HTTP headers
 
     Returns:
-        Session ID if found, None otherwise
+        Session ID if found and one Scope keeps (fit_id: 1–100 characters, the spaces around it
+        not part of it), None otherwise — so a session the ingest would refuse falls back to a temp
+        session for the whole request, as a missing one does (0.1.6), instead of each of the
+        request's events getting a session of its own at the ingest
     """
     # Try exact case first
     session_id = headers.get(SESSION_HEADER)
     if session_id:
-        return session_id
+        return fit_id(session_id)
 
     # Try lowercase
     session_id = headers.get(SESSION_HEADER_LOWER)
     if session_id:
-        return session_id
+        return fit_id(session_id)
 
     # Try case-insensitive search
     for key, value in headers.items():
         if key.lower() == SESSION_HEADER_LOWER:
-            return value
+            return fit_id(value)
 
     return None
 
@@ -398,9 +403,9 @@ class ScopeSessionMiddleware:
             session_id = ScopeContext.generate_temp_session_id()
             ScopeContext.set_session_id(session_id)
             if self.log_missing_session:
-                logger.debug(f"No X-Scope-Session-ID header, generated temp: {session_id}")
+                logger.debug(f"No usable X-Scope-Session-ID header, generated temp: {session_id}")
         elif self.log_missing_session:
-            logger.warning("No X-Scope-Session-ID header and temp generation disabled")
+            logger.warning("No usable X-Scope-Session-ID header and temp generation disabled")
 
         # Auto-extract user_id from JWT (for identity stitching)
         _auto_set_identity_from_headers(headers)
@@ -528,9 +533,9 @@ class FlaskScopeMiddleware:
             session_id = ScopeContext.generate_temp_session_id()
             ScopeContext.set_session_id(session_id)
             if self.log_missing_session:
-                logger.debug(f"No X-Scope-Session-ID header, generated temp: {session_id}")
+                logger.debug(f"No usable X-Scope-Session-ID header, generated temp: {session_id}")
         elif self.log_missing_session:
-            logger.warning("No X-Scope-Session-ID header and temp generation disabled")
+            logger.warning("No usable X-Scope-Session-ID header and temp generation disabled")
 
         # Auto-extract user_id from JWT (for identity stitching)
         _auto_set_identity_from_headers(headers)
@@ -618,7 +623,7 @@ def init_flask_session_tracking(app, generate_temp_session: bool = True):
         # Start timing
         g.scope_start_time = time.time()
 
-        session_id = request.headers.get(SESSION_HEADER)
+        session_id = fit_id(request.headers.get(SESSION_HEADER))
         if session_id:
             ScopeContext.set_session_id(session_id)
             g.scope_session_id = session_id
@@ -631,6 +636,11 @@ def init_flask_session_tracking(app, generate_temp_session: bool = True):
         flask_headers = dict(request.headers)
         _auto_set_identity_from_headers(flask_headers)
 
+        # The request's URL, referrer, thread id and User-Agent for the events it makes, as every other
+        # entry point sets them (0.1.6): until then an llm_call on a zero-code Flask app carried none, so
+        # an X-Scope-Thread-ID header was never read there
+        _set_request_context(flask_headers, request.path)
+
     @app.after_request
     def track_http_request_and_clear_context(response):
         # Track HTTP request
@@ -688,11 +698,13 @@ def get_scope_session():
     from fastapi import Request
 
     async def dependency(request: Request) -> str:
-        session_id = request.headers.get(SESSION_HEADER)
+        session_id = fit_id(request.headers.get(SESSION_HEADER))
         if session_id:
             ScopeContext.set_session_id(session_id)
         else:
             session_id = ScopeContext.ensure_session_id()
+        # the login token's user and the page's visitor id, as the middleware reads them (0.1.6)
+        _auto_set_identity_from_headers(dict(request.headers))
         return session_id
 
     return dependency
@@ -741,6 +753,7 @@ class DjangoScopeMiddleware:
         # Also check for direct header (some configurations)
         if not session_id:
             session_id = request.headers.get(SESSION_HEADER)
+        session_id = fit_id(session_id)
 
         if session_id:
             ScopeContext.set_session_id(session_id)
@@ -748,9 +761,9 @@ class DjangoScopeMiddleware:
             session_id = ScopeContext.generate_temp_session_id()
             ScopeContext.set_session_id(session_id)
             if self.log_missing_session:
-                logger.debug(f"No X-Scope-Session-ID header, generated temp: {session_id}")
+                logger.debug(f"No usable X-Scope-Session-ID header, generated temp: {session_id}")
         elif self.log_missing_session:
-            logger.warning("No X-Scope-Session-ID header and temp generation disabled")
+            logger.warning("No usable X-Scope-Session-ID header and temp generation disabled")
 
         # Auto-extract user_id from JWT (for identity stitching)
         # Django stores headers in META with HTTP_ prefix

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/scope_analytics/supported_versions.py

@@ -36,9 +36,10 @@ SUPPORTED_VERSIONS = {
         # 3.x (2026-09): the majors keep the modern client shape, so the structural routing and
         # both capture surfaces are unchanged — verified by the contract cells below (3.8.0 at
         # 0.1.3; 3.14.1 at 0.1.4; 3.24.0 at 0.1.5, which also added the with_raw_response cells; 3.26.1
-        # by the 0.1.5 publish dry run, 2026-10-09 — the whole suite green on it but this drift check).
-        "max_tested": "3.26.1",
-        "ci_matrix": ["1.0.0", "1.30.0", "1.57.0", "2.41.0", "2.46.0", "3.8.0", "3.14.1", "3.24.0", "3.26.1"],
+        # by the 0.1.5 publish dry run, 2026-10-09 — the whole suite green on it but this drift check;
+        # 3.42.1 by the 0.1.6 publish dry run, 2026-11-03, the same way, and its contract cell).
+        "max_tested": "3.42.1",
+        "ci_matrix": ["1.0.0", "1.30.0", "1.57.0", "2.41.0", "2.46.0", "3.8.0", "3.14.1", "3.24.0", "3.26.1", "3.42.1"],
     },
     "anthropic": {
         "import_name": "anthropic",
@@ -53,8 +54,11 @@ SUPPORTED_VERSIONS = {
         # (1.4.0 verified at 0.1.3; 1.6.0 at 0.1.4; 1.11.0 at 0.1.5 — with_raw_response included,
         # whose wrapper in 1.x is APIResponse with a coroutine parse() on the async client; 1.12.1 by
         # the 0.1.5 publish dry run, 2026-10-09).
-        "max_tested": "1.12.1",
-        "ci_matrix": ["0.18.0", "0.30.0", "0.40.0", "0.116.0", "1.4.0", "1.6.0", "1.11.0", "1.12.1"],
+        # 2.x (2026-10-21): the 0.1.6 publish dry run (2026-11-03) ran the whole suite green on 2.4.0 but
+        # this drift check — the patch surfaces are there and captured — and the 2.0.0 and 2.4.0 contract
+        # cells hold it.
+        "max_tested": "2.4.0",
+        "ci_matrix": ["0.18.0", "0.30.0", "0.40.0", "0.116.0", "1.4.0", "1.6.0", "1.11.0", "1.12.1", "2.0.0", "2.4.0"],
     },
     "gemini": {
         # Targets the LEGACY google-generativeai SDK (import google.generativeai), which gemini_patch.py
@@ -82,9 +86,10 @@ SUPPORTED_VERSIONS = {
         "min_supported": "1.0.0",      # the unified SDK GA'd at v1.x (~May 2025)
         # Verified by tests/test_capture_contract_google.py against 1.60.0 AND 2.11.0 (current as of
         # 2026-07; the 2.0 major's breaking changes were interactions-only — generate_content stable);
-        # 2.22.0 at 0.1.3, 2.23.0 at 0.1.4, 2.28.0 at 0.1.5; 2.29.0 by the 0.1.5 publish dry run.
-        "max_tested": "2.29.0",
-        "ci_matrix": ["1.0.0", "1.60.0", "2.11.0", "2.22.0", "2.23.0", "2.28.0", "2.29.0"],
+        # 2.22.0 at 0.1.3, 2.23.0 at 0.1.4, 2.28.0 at 0.1.5; 2.29.0 by the 0.1.5 publish dry run; 2.34.0 by
+        # the 0.1.6 publish dry run (2026-11-03) and its contract cell.
+        "max_tested": "2.34.0",
+        "ci_matrix": ["1.0.0", "1.60.0", "2.11.0", "2.22.0", "2.23.0", "2.28.0", "2.29.0", "2.34.0"],
     },
 }
 

{scope_analytics-0.1.5 → scope_analytics-0.1.6/scope_analytics.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scope-analytics
-Version: 0.1.5
+Version: 0.1.6
 Summary: AI-powered analytics SDK for backend applications with automatic LLM tracking
 Home-page: https://scopeai.dev
 Author: Scope AI
@@ -185,7 +185,7 @@ scope-run --dry-run uvicorn main:app
 | `SCOPE_API_KEY` | Yes | Your Scope Analytics API key |
 | `SCOPE_ENDPOINT` | No | Custom API endpoint |
 | `SCOPE_DEBUG` | No | Set to 'true' for debug logging |
-| `SCOPE_ENVIRONMENT` | No | Environment name (default: production) |
+| `SCOPE_ENVIRONMENT` | No | Environment tag on every event (default: production). When it is unset or `production`, events sent with a key you created for Staging or Development (Setup → Keys) are tagged with that key's environment instead |
 | `SCOPE_CAPTURE_HTTP` | No | Capture outbound calls to other services (default: on; `false` turns it off) |
 | `HTTPS_PROXY` / `NO_PROXY` / `SSL_CERT_FILE` | No | Honoured for the SDK's own connection to Scope (read from the environment only) |
 

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/scope_analytics.egg-info/SOURCES.txt

@@ -40,6 +40,7 @@ tests/test_frameworks_langchain.py
 tests/test_http_patch.py
 tests/test_identify.py
 tests/test_identity_bridge.py
+tests/test_ids_0_1_6.py
 tests/test_manual_event_and_debug_output.py
 tests/test_patch_versions.py
 tests/test_query_scrub.py

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/setup.py

@@ -11,7 +11,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="scope-analytics",
-    version="0.1.5",
+    version="0.1.6",
     author="Scope AI",
     author_email="support@scopeai.dev",
     description="AI-powered analytics SDK for backend applications with automatic LLM tracking",

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/tests/test_discard_reply.py

@@ -137,3 +137,49 @@ def test_a_reason_that_merely_contains_ip_does_not_get_the_ip_pointer(caplog):
     finally:
         sdk.shutdown()
         sink.close()
+
+
+def test_an_event_scope_refused_or_changed_is_said_once_per_reason(caplog):
+    """The ingest judges each event on its own and says, in a 200, which it refused or kept with
+    a change — before, one such event refused the whole batch and the SDK said "could not deliver"."""
+    caplog.set_level(logging.WARNING, logger="scope_analytics")
+    reply = {"status": "success", "events_received": 3, "events_stored": 2, "events_rejected": 1,
+             "events_repaired": 1,
+             "rejected": [{"index": 0, "field": "session_id", "reason": "String should have at most 100 characters"}],
+             "repaired": [{"index": 1, "field": "user_id",
+                           "reason": "String should have at most 100 characters; the event was kept without it"}]}
+    sink = _Sink(reply)
+    sdk = _sdk(sink)
+    try:
+        for tag in ("a", "b"):
+            sdk.track_event("probe", {"tag": tag})
+            sdk.flush()
+        said = [w for w in _warnings(caplog) if "Scope refused" in w or "Scope stored" in w]
+        assert len(said) == 2, said                             # once per reason, not per batch
+        assert "(session_id: String should have at most 100 characters)" in said[0] and "judged on its own" in said[0]
+        assert "Scope stored an event with a change (user_id: String should have" in said[1]
+        sink.reply = {**reply, "rejected": [{"index": 0, "field": None, "reason": "An event must be a JSON object"}]}
+        sdk.track_event("probe", {"tag": "c"})
+        sdk.flush()
+        assert any("Scope refused an event (An event must be a JSON object)" in w for w in _warnings(caplog))
+        assert not [w for w in _warnings(caplog) if "discarded" in w.lower()]
+    finally:
+        sdk.shutdown()
+        sink.close()
+
+
+def test_a_reply_not_shaped_as_scopes_says_nothing_and_fails_no_batch(caplog):
+    """A field or reason that is not text (a proxy's reply, say) is not Scope's to say — and must not
+    make a stored batch look undelivered."""
+    caplog.set_level(logging.WARNING, logger="scope_analytics")
+    sink = _Sink({"status": "success", "events_stored": 1, "events_rejected": 1,
+                  "rejected": [{"index": 0, "field": ["x"], "reason": {"a": 1}}, "nonsense", {"reason": None}]})
+    sdk = _sdk(sink)
+    try:
+        sdk.track_event("probe", {"tag": "a"})
+        sdk.flush()
+        assert sink.batches == 1
+        assert not [w for w in _warnings(caplog) if "Scope refused" in w or "Could not deliver" in w]
+    finally:
+        sdk.shutdown()
+        sink.close()

{scope_analytics-0.1.5 → scope_analytics-0.1.6}/tests/test_identity_bridge.py

@@ -86,6 +86,52 @@ def test_absurdly_long_anon_header_is_ignored():
     ScopeContext.clear()
 
 
+def test_anon_header_is_kept_up_to_the_ingests_100_characters_and_never_cut():
+    """It becomes the events' user_id, and the ingest keeps a user id of at most 100
+    characters: until 2026-10-29 one of 101-256 refused the whole batch it rode in."""
+    from scope_analytics.middleware import MAX_ID_LENGTH
+
+    assert MAX_ID_LENGTH == 100
+    ScopeContext.clear()
+    _auto_set_identity_from_headers({"X-Scope-Anonymous-ID": "a" * 100})
+    assert ScopeContext.get_anonymous_id() == "a" * 100
+    assert ScopeContext.get_user_id() == "a" * 100
+    ScopeContext.clear()
+    _auto_set_identity_from_headers({"X-Scope-Anonymous-ID": "a" * 101})
+    assert ScopeContext.get_anonymous_id() is None        # ignored, as if absent
+    assert ScopeContext.get_user_id() is None
+    ScopeContext.clear()
+    # a JWT's user still names the request when the header is ignored
+    _auto_set_identity_from_headers({"Authorization": f"Bearer {_unsigned_jwt({'sub': 'real_user'})}",
+                                     "X-Scope-Anonymous-ID": "a" * 101})
+    assert ScopeContext.get_user_id() == "real_user" and ScopeContext.get_anonymous_id() is None
+    ScopeContext.clear()
+
+
+def test_a_token_user_past_100_characters_gives_way_to_the_visitor_id():
+    """Node's fitId, in Python: the ingest drops a user id over 100 characters from every event
+    it rides in, so the browser's visitor id names the request instead."""
+    ScopeContext.clear()
+    token = _unsigned_jwt({"sub": "s" * 101})
+    _auto_set_identity_from_headers({"Authorization": f"Bearer {token}", "X-Scope-Anonymous-ID": "user_anon_5"})
+    assert ScopeContext.get_user_id() == "user_anon_5"
+    ScopeContext.clear()
+    _auto_set_identity_from_headers({"Authorization": f"Bearer {_unsigned_jwt({'sub': 's' * 100})}"})
+    assert ScopeContext.get_user_id() == "s" * 100
+    ScopeContext.clear()
+
+
+def test_a_token_claim_that_is_an_object_names_no_user_and_the_next_claim_may():
+    ScopeContext.clear()
+    token = _unsigned_jwt({"sub": {"id": 7, "email": "a@b.example"}, "user_id": "u_7"})
+    _auto_set_identity_from_headers({"Authorization": f"Bearer {token}"})
+    assert ScopeContext.get_user_id() == "u_7"             # never "{'id': 7, 'email': ...}"
+    ScopeContext.clear()
+    _auto_set_identity_from_headers({"Authorization": f"Bearer {_unsigned_jwt({'user': ['a', 'b']})}"})
+    assert ScopeContext.get_user_id() is None
+    ScopeContext.clear()
+
+
 if __name__ == "__main__":
     tests = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
     for t in tests:

scope_analytics-0.1.6/tests/test_ids_0_1_6.py

@@ -0,0 +1,390 @@
+"""Ids as Scope keeps them, and the browser's visitor id on every server event (scope-analytics 0.1.6,
+the Node SDK's rules):
+
+  (a) a session header the ingest would refuse — over 100 characters, or only spaces — falls back to a
+      temp session for the whole request, at every entry point (ASGI, the WSGI wrapper, Flask's hooks,
+      FastAPI's dependency, Django), and the spaces around a header's id are not part of it. Until 0.1.6
+      the header's value was the session as it came: the ingest gave each of the request's events a
+      session of its own instead
+  (b) identify() and ScopeContext.set_user_id() take text, a whole number (kept as its digits — until
+      0.1.6 a number rode the event as a number, and identify(0) was ignored as if no id were given), a
+      UUID or an ObjectId (as their text, as 0.1.5 sent them); anything else (over 100 characters,
+      empty, True, a float, a list, any other object) is ignored, why said once per process (the type
+      named, never the id); None says nothing; set_user_id(None) clears; a number of thousands of digits
+      is refused without raising into the app
+  (d) the Flask hooks set the request's URL, referrer, thread id and User-Agent for its events, and the
+      FastAPI dependency reads the token's user and the page's visitor id, as the middleware does
+  (c) every event the SDK makes in a request — llm_call, http_request, external_api_call — carries the
+      browser's visitor id (X-Scope-Anonymous-ID) as anonymous_id beside user_id: with a login token,
+      the sign-in and the browser it was used in, recorded together. None when no page sent one; an
+      app's own event (track_event) gets it only when there is one, and keeps its own
+
+No network: every SDK here ships nowhere and records into a list.
+"""
+import asyncio
+import base64
+import json
+import logging
+import uuid
+from types import SimpleNamespace
+
+import pytest
+
+from scope_analytics import ScopeAnalytics
+from scope_analytics import context as scope_context
+from scope_analytics.context import MAX_ID_LENGTH, ScopeContext, accepted_user_id, fit_id
+from scope_analytics.middleware import (
+    DjangoScopeMiddleware,
+    FlaskScopeMiddleware,
+    ScopeSessionMiddleware,
+    extract_session_from_headers,
+    get_scope_session,
+)
+
+KEY = "sk_test_fake_local_only"
+LONG = "s" * (MAX_ID_LENGTH + 1)
+EDGE = "s" * MAX_ID_LENGTH
+
+
+@pytest.fixture(autouse=True)
+def _clean(monkeypatch):
+    """No deployment event at construction, a clean context, and the once-per-process warning re-armed."""
+    from scope_analytics.deployment import DeploymentContext
+    monkeypatch.setattr(DeploymentContext, "should_emit_deployment_detected", lambda self: False)
+    monkeypatch.setattr(scope_context, "_warned_refused_user_id", set())
+    ScopeContext.clear()
+    yield
+    ScopeContext.clear()
+
+
+@pytest.fixture
+def sdk():
+    s = ScopeAnalytics(api_key=KEY, endpoint="http://127.0.0.1:1", capture_http=False, auto_patch=False,
+                       batch_timeout_seconds=30)
+    s.client.ship_events = lambda events: True
+    s.captured = []
+    s.queue.enqueue = lambda event: s.captured.append(event)
+    yield s
+    s.shutdown()
+
+
+def _jwt(claims):
+    payload = base64.urlsafe_b64encode(json.dumps(claims).encode()).decode().rstrip("=")
+    return f"hdr.{payload}.sig"
+
+
+def _http_requests(sdk):
+    return [e for e in sdk.captured if e.get("event_type") == "http_request"]
+
+
+# ---------------------------------------------------------------- (a) the session header
+
+def test_fit_id_keeps_an_id_of_1_to_100_characters_without_the_spaces_around_it():
+    assert fit_id("sess_1") == "sess_1"
+    assert fit_id("  sess_1 \t") == "sess_1"
+    assert fit_id(EDGE) == EDGE
+    assert fit_id(LONG) is None, "never cut: a cut id could name another session"
+    assert fit_id("   ") is None
+    assert fit_id("") is None
+    assert fit_id(None) is None
+    assert fit_id(12345) is None
+
+
+def test_extract_session_from_headers_fits_every_spelling():
+    assert extract_session_from_headers({"X-Scope-Session-ID": " sess_1 "}) == "sess_1"
+    assert extract_session_from_headers({"x-scope-session-id": LONG}) is None
+    assert extract_session_from_headers({"X-SCOPE-SESSION-ID": "   "}) is None
+    assert extract_session_from_headers({"X-Scope-Session-Id": EDGE}) == EDGE
+
+
+def _run_asgi(headers):
+    seen = {}
+
+    async def app(scope, receive, send):
+        seen["session"] = ScopeContext.get_session_id()
+        await send({"type": "http.response.start", "status": 200, "headers": []})
+        await send({"type": "http.response.body", "body": b"ok"})
+
+    scope = {"type": "http", "method": "GET", "path": "/api/chat", "query_string": b"", "client": ("10.0.0.9", 1),
+             "headers": [(k.lower().encode(), v.encode()) for k, v in headers.items()]}
+
+    async def receive():
+        return {"type": "http.request", "body": b"", "more_body": False}
+
+    async def send(message):
+        pass
+
+    asyncio.run(ScopeSessionMiddleware(app)(scope, receive, send))
+    return seen["session"]
+
+
+def _run_wsgi(environ_headers):
+    seen = {}
+
+    def app(environ, start_response):
+        seen["session"] = ScopeContext.get_session_id()
+        start_response("200 OK", [])
+        return [b"ok"]
+
+    environ = {"REQUEST_METHOD": "GET", "PATH_INFO": "/api/chat", "QUERY_STRING": "", "REMOTE_ADDR": "10.0.0.9",
+               **environ_headers}
+    list(FlaskScopeMiddleware(app)(environ, lambda status, headers, exc_info=None: None))
+    return seen["session"]
+
+
+class _DjangoRequest:
+    """What DjangoScopeMiddleware reads from a Django request — no Django needed."""
+
+    def __init__(self, meta):
+        self.META = {"REMOTE_ADDR": "10.0.0.9", **meta}
+        self.method = "GET"
+        self.path = "/api/chat"
+        self.GET = {}
+        self.content_type = None
+        self.headers = {k[5:].replace("_", "-").title(): v for k, v in meta.items() if k.startswith("HTTP_")}
+
+
+def _run_django(meta):
+    seen = {}
+
+    def get_response(request):
+        seen["session"] = ScopeContext.get_session_id()
+        return SimpleNamespace(status_code=200)
+
+    DjangoScopeMiddleware(get_response)(_DjangoRequest(meta))
+    return seen["session"]
+
+
+@pytest.mark.parametrize("run, header", [
+    (_run_asgi, lambda v: {"X-Scope-Session-ID": v}),
+    (_run_wsgi, lambda v: {"HTTP_X_SCOPE_SESSION_ID": v}),
+    (_run_django, lambda v: {"HTTP_X_SCOPE_SESSION_ID": v}),
+], ids=["asgi", "wsgi", "django"])
+def test_every_middleware_keeps_a_usable_session_and_falls_back_for_one_the_ingest_would_refuse(sdk, run, header):
+    assert run(header(" sess_browser ")) == "sess_browser", "the spaces around it are not part of it"
+    assert run(header(EDGE)) == EDGE
+    long_session = run(header(LONG))
+    assert long_session.startswith("temp_") and long_session != LONG, "over 100: a temp session, as if absent"
+    assert run(header("   ")).startswith("temp_")
+    # the request's own event carries the session the request ran in, so its events share one
+    sessions = [e["session_id"] for e in _http_requests(sdk)]
+    assert sessions[0] == "sess_browser" and sessions[2] == long_session
+
+
+def test_flask_hooks_keep_a_usable_session_and_fall_back_for_one_the_ingest_would_refuse(sdk):
+    flask = pytest.importorskip("flask")
+    from scope_analytics.middleware import init_flask_session_tracking
+
+    app = flask.Flask(__name__)
+    init_flask_session_tracking(app)
+    seen = []
+
+    @app.route("/api/chat")
+    def chat():
+        seen.append(ScopeContext.get_session_id())
+        return "ok"
+
+    client = app.test_client()
+    client.get("/api/chat", headers={"X-Scope-Session-ID": " sess_browser "})
+    client.get("/api/chat", headers={"X-Scope-Session-ID": LONG})
+    assert seen[0] == "sess_browser"
+    assert seen[1].startswith("temp_")
+
+
+def test_fastapi_dependency_keeps_a_usable_session_and_falls_back_for_one_the_ingest_would_refuse():
+    pytest.importorskip("fastapi")
+    dependency = get_scope_session()
+    kept = asyncio.run(dependency(SimpleNamespace(headers={"X-Scope-Session-ID": " sess_browser "})))
+    assert kept == "sess_browser"
+    ScopeContext.clear()
+    fallback = asyncio.run(dependency(SimpleNamespace(headers={"X-Scope-Session-ID": LONG})))
+    assert fallback.startswith("temp_")
+
+
+def test_the_visitor_header_is_fitted_the_same_way(sdk):
+    _run_asgi({"X-Scope-Anonymous-ID": " user_v1 "})
+    _run_asgi({"X-Scope-Anonymous-ID": LONG})
+    first, second = _http_requests(sdk)
+    assert first["anonymous_id"] == "user_v1" and first["user_id"] == "user_v1"
+    assert second["anonymous_id"] is None and second["user_id"] is None
+
+
+# ---------------------------------------------------------------- (b) the app's id for a user
+
+class ObjectId:
+    """bson's ObjectId, as an app's Mongo id arrives — matched by its class name, no bson import."""
+
+    def __init__(self, hexid):
+        self.hexid = hexid
+
+    def __str__(self):
+        return self.hexid
+
+
+class PydanticObjectId(ObjectId):
+    """Beanie's id: a subclass with another name."""
+
+
+UID = uuid.UUID("6f1c2a52-0d4e-4f4b-9a9e-2b8a1c3d4e5f")
+
+
+@pytest.mark.parametrize("given, kept", [
+    ("user_42", "user_42"), (42, "42"), (0, "0"), (-7, "-7"), ("0", "0"), (EDGE, EDGE), (" padded ", " padded "),
+    (UID, "6f1c2a52-0d4e-4f4b-9a9e-2b8a1c3d4e5f"),
+    (ObjectId("65a1b2c3d4e5f60718293a4b"), "65a1b2c3d4e5f60718293a4b"),
+    (PydanticObjectId("65a1b2c3d4e5f60718293a4c"), "65a1b2c3d4e5f60718293a4c"),
+    (10 ** 99, "1" + "0" * 99),
+])
+def test_accepted_user_id_keeps_text_whole_numbers_uuids_and_objectids(given, kept):
+    assert accepted_user_id(given, "identify") == kept
+
+
+@pytest.mark.parametrize("given", [LONG, "", True, False, 3.5, 42.0, {"id": 1}, ["u"], object(), 10 ** 100, 10 ** 5000],
+                         ids=["long", "empty", "true", "false", "float", "whole-float", "dict", "list", "object",
+                              "101-digits", "5001-digits"])   # a 5,001-digit number cannot even be a test's name
+def test_accepted_user_id_refuses_anything_else_without_raising(given):
+    assert accepted_user_id(given, "identify") is None
+
+
+def test_no_id_given_says_nothing(caplog):
+    with caplog.at_level(logging.WARNING, logger="scope_analytics"):
+        assert accepted_user_id(None, "identify") is None
+    assert [r for r in caplog.records if r.name == "scope_analytics"] == []
+
+
+def test_why_an_id_was_ignored_is_said_once_per_reason_never_the_id(caplog):
+    with caplog.at_level(logging.WARNING, logger="scope_analytics"):
+        accepted_user_id(LONG, "identify")
+        accepted_user_id(LONG + "x", "identify")
+        accepted_user_id(3.5, "set_user_id")
+        accepted_user_id(2.5, "identify")
+        accepted_user_id(True, "identify")
+        accepted_user_id(None, "identify")
+    said = [r.getMessage() for r in caplog.records if r.name == "scope_analytics"]
+    assert len(said) == 3, said
+    assert "identify() takes your app's id for the user" in said[0] and "(over 100 characters)" in said[0]
+    assert "set_user_id() takes" in said[1] and "(a float)" in said[1]
+    assert "(true/false)" in said[2]
+    assert not any(LONG in m for m in said), "the id itself is never logged"
+
+
+def test_set_user_id_keeps_a_number_as_its_digits_ignores_a_refused_id_and_none_clears(caplog):
+    ScopeContext.set_user_id(42)
+    assert ScopeContext.get_user_id() == "42"
+    ScopeContext.set_user_id(UID)
+    assert ScopeContext.get_user_id() == str(UID)
+    with caplog.at_level(logging.WARNING, logger="scope_analytics"):
+        ScopeContext.set_user_id(LONG)
+    assert ScopeContext.get_user_id() == str(UID), "a refused id leaves the one there"
+    assert any("set_user_id() takes" in r.getMessage() for r in caplog.records)
+    ScopeContext.set_user_id(None)
+    assert ScopeContext.get_user_id() is None
+
+
+def test_identify_takes_a_number_as_its_digits_zero_is_an_id_and_a_uuid_as_its_text(sdk):
+    sdk.identify(42, {"plan": "pro"})
+    sdk.identify(0)
+    sdk.identify(UID)
+    identifies = [e for e in sdk.captured if e["event_type"] == "identify"]
+    assert [e["identified_user_id"] for e in identifies] == ["42", "0", str(UID)]
+    assert ScopeContext.get_user_id() == str(UID)
+
+
+def test_identify_ignores_an_id_the_ingest_would_refuse_and_none_quietly(sdk, caplog):
+    with caplog.at_level(logging.WARNING, logger="scope_analytics"):
+        sdk.identify(None)
+        assert [r for r in caplog.records if r.name == "scope_analytics"] == [], "no id given: nothing to say"
+        sdk.identify(LONG)
+        sdk.identify("")
+        sdk.identify(10 ** 5000)
+    assert [e for e in sdk.captured if e["event_type"] == "identify"] == []
+    said = [r.getMessage() for r in caplog.records if "takes your app's id" in r.getMessage()]
+    assert len(said) == 2, said          # over 100 characters (twice), empty
+    assert ScopeContext.get_user_id() is None
+
+
+# ---------------------------------------------------------------- (d) the Flask hooks and the FastAPI dependency
+
+def test_flask_hooks_set_the_requests_context_for_its_events(sdk):
+    flask = pytest.importorskip("flask")
+    from scope_analytics.middleware import init_flask_session_tracking
+
+    app = flask.Flask(__name__)
+    init_flask_session_tracking(app)
+    seen = {}
+
+    @app.route("/api/chat")
+    def chat():
+        seen.update(url=ScopeContext.get_url(), thread=ScopeContext.get_thread_id(),
+                    referrer=ScopeContext.get_referrer(), visitor=ScopeContext.get_anonymous_id())
+        return "ok"
+
+    app.test_client().get("/api/chat", headers={
+        "X-Scope-Thread-ID": "thread-9", "Referer": "https://app.example.com/page", "X-Scope-Anonymous-ID": "user_v1"})
+    assert seen == {"url": "/api/chat", "thread": "thread-9", "referrer": "https://app.example.com/page",
+                    "visitor": "user_v1"}
+
+
+def test_fastapi_dependency_reads_the_token_user_and_the_visitor_id():
+    pytest.importorskip("fastapi")
+    dependency = get_scope_session()
+
+    async def request():   # the context the dependency sets is the request's own: read inside it
+        await dependency(SimpleNamespace(headers={
+            "X-Scope-Session-ID": "sess_browser", "X-Scope-Anonymous-ID": "user_v1",
+            "Authorization": "Bearer " + _jwt({"sub": "u_signed_in"})}))
+        return ScopeContext.get_user_id(), ScopeContext.get_anonymous_id()
+
+    assert asyncio.run(request()) == ("u_signed_in", "user_v1")
+
+
+# ---------------------------------------------------------------- (c) the browser's visitor id on every server event
+
+def _formatter(sdk):
+    return sdk.event_formatter
+
+
+def test_every_event_the_sdk_makes_in_a_request_carries_the_visitor_id_beside_the_sign_in(sdk):
+    ScopeContext.set_session_id("sess_browser")
+    ScopeContext.set_anonymous_id("user_v1")
+    ScopeContext.set_user_id("u_signed_in")
+    f = _formatter(sdk)
+    events = [
+        f.format_llm_call(provider="openai", model="m", messages=[{"role": "user", "content": "hi"}], response="yo",
+                          tokens={"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}, latency_ms=1.0),
+        f.format_http_request(method="GET", path="/api/chat", status_code=200, latency_ms=1.0),
+        f.format_external_api_call(method="GET", url="https://api.example.com/x", status_code=200, latency_ms=1.0),
+    ]
+    for event in events:
+        assert (event["user_id"], event["anonymous_id"]) == ("u_signed_in", "user_v1"), event["event_type"]
+
+
+def test_with_no_page_the_visitor_id_is_none(sdk):
+    f = _formatter(sdk)
+    events = [
+        f.format_llm_call(provider="openai", model="m", messages=[], response="", latency_ms=1.0),
+        f.format_http_request(method="GET", path="/health", status_code=200, latency_ms=1.0),
+        f.format_external_api_call(method="GET", url="https://api.example.com/x", status_code=200, latency_ms=1.0),
+    ]
+    assert [e["anonymous_id"] for e in events] == [None, None, None]
+
+
+def test_a_request_with_a_login_token_records_the_sign_in_and_the_browser_together(sdk):
+    _run_asgi({
+        "X-Scope-Session-ID": "sess_browser",
+        "X-Scope-Anonymous-ID": "user_v1",
+        "Authorization": "Bearer " + _jwt({"sub": "u_signed_in"}),
+    })
+    (event,) = _http_requests(sdk)
+    assert (event["session_id"], event["user_id"], event["anonymous_id"]) == ("sess_browser", "u_signed_in", "user_v1")
+
+
+def test_an_apps_own_event_gets_the_visitor_id_only_when_there_is_one_and_keeps_its_own(sdk):
+    sdk.track_event("plan_upgraded", {"plan": "pro"})
+    ScopeContext.set_anonymous_id("user_v1")
+    sdk.track_event("plan_upgraded", {"plan": "team"})
+    sdk.track_event("plan_upgraded", {"plan": "max", "anonymous_id": "the_apps_own"})
+    no_page, in_request, own = [e for e in sdk.captured if e["event_type"] == "plan_upgraded"]
+    assert "anonymous_id" not in no_page, "an app's own event's fields are the caller's: nothing added when no page sent one"
+    assert in_request["anonymous_id"] == "user_v1"
+    assert own["anonymous_id"] == "the_apps_own"