trodo-python 2.17.0__tar.gz → 2.18.1__tar.gz

{trodo_python-2.17.0 → trodo_python-2.18.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.17.0
+Version: 2.18.1
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -123,7 +123,7 @@ Creates the session and fires `POST /api/sdk/identify`. Use to link a `distinct_
 
 ```python
 user = trodo.identify('user@example.com', session_id=request.cookies.get('trodo_session'))
-# distinct_id is now id_user@example.com — merges with browser events
+# distinct_id is now user@example.com — merges with browser events
 user.track('login')
 ```
 
@@ -171,6 +171,59 @@ trodo.people_set('user-123', {'plan': 'pro'})
 trodo.set_group('user-123', 'company', 'acme')
 ```
 
+### `upsert_user` — identity and traits in one call
+
+Create-or-update a user and their traits idempotently. This is the call a
+stateless request handler makes; safe to run on every request.
+
+```python
+result = trodo.upsert_user(
+    'user-42',
+    properties={'plan': 'pro', 'company': 'Acme'},        # merged
+    set_once={'signup_date': '2026-01-04'},               # fill-if-absent
+    fixed_properties={'last_location_country': 'India'},
+)
+
+result['created']                  # True if this call created the user
+result['applied']['properties']    # ['plan', 'company']
+result['skipped']['fixedProperties']
+```
+
+All three bags are optional. With none of them it still ensures the user
+exists — what you want at signup, before they've produced any runs.
+
+**Fixed vs custom properties.** `properties` / `set_once` are free-form and live
+on the profile as custom properties. `fixed_properties` writes the real columns
+the dashboard filters on, and only a backend-knowable subset is accepted:
+
+| Settable from a backend | Browser-only |
+|---|---|
+| `first_location_country`, `last_location_country` | `device_type`, `browser_name`, `os` |
+| `first_location_city`, `last_location_city` | `first_referrer`, `last_referrer`, `utm_*` |
+
+A browser-only key isn't an error — it comes back in `skipped` with
+`reason: 'BROWSER_ONLY_PROPERTY'` and the rest of the batch still applies. The
+reasoning: a backend supplying a browser name is guessing, and a wrong guess
+silently corrupts attribution reporting.
+
+Where both a browser and a backend write the same column, **the browser wins** —
+it observed the value, the server supplied one — and the server write is
+reported as `BROWSER_OWNED_PROPERTY`.
+
+### Attributing and enriching in one call
+
+`wrap_agent` and `start_run` take an optional `user=` bag, so a request handler
+doesn't need a separate `upsert_user` call it has to sequence correctly:
+
+```python
+with trodo.wrap_agent('support-agent', distinct_id=user_id,
+                      user={'properties': {'plan': 'pro'}}) as run:
+    ...
+```
+
+Applied server-side and non-fatally — a failed trait write never costs you the
+trace. Use `upsert_user` directly when you need to know what landed.
+
 ---
 
 ## AI Agent Tracing (recommended)
@@ -617,10 +670,10 @@ Call `identify()` with the **same value** on the browser and server to merge all
 
 ```python
 # Python
-user.identify('user@example.com')   # → id_user@example.com
+user.identify('user@example.com')   # → user@example.com
 
 # Browser (same value)
-# Trodo.identify('user@example.com') → id_user@example.com
+# Trodo.identify('user@example.com') → user@example.com
 # Events from both sides now appear together in the dashboard
 ```
 

{trodo_python-2.17.0 → trodo_python-2.18.1}/README.md

@@ -92,7 +92,7 @@ Creates the session and fires `POST /api/sdk/identify`. Use to link a `distinct_
 
 ```python
 user = trodo.identify('user@example.com', session_id=request.cookies.get('trodo_session'))
-# distinct_id is now id_user@example.com — merges with browser events
+# distinct_id is now user@example.com — merges with browser events
 user.track('login')
 ```
 
@@ -140,6 +140,59 @@ trodo.people_set('user-123', {'plan': 'pro'})
 trodo.set_group('user-123', 'company', 'acme')
 ```
 
+### `upsert_user` — identity and traits in one call
+
+Create-or-update a user and their traits idempotently. This is the call a
+stateless request handler makes; safe to run on every request.
+
+```python
+result = trodo.upsert_user(
+    'user-42',
+    properties={'plan': 'pro', 'company': 'Acme'},        # merged
+    set_once={'signup_date': '2026-01-04'},               # fill-if-absent
+    fixed_properties={'last_location_country': 'India'},
+)
+
+result['created']                  # True if this call created the user
+result['applied']['properties']    # ['plan', 'company']
+result['skipped']['fixedProperties']
+```
+
+All three bags are optional. With none of them it still ensures the user
+exists — what you want at signup, before they've produced any runs.
+
+**Fixed vs custom properties.** `properties` / `set_once` are free-form and live
+on the profile as custom properties. `fixed_properties` writes the real columns
+the dashboard filters on, and only a backend-knowable subset is accepted:
+
+| Settable from a backend | Browser-only |
+|---|---|
+| `first_location_country`, `last_location_country` | `device_type`, `browser_name`, `os` |
+| `first_location_city`, `last_location_city` | `first_referrer`, `last_referrer`, `utm_*` |
+
+A browser-only key isn't an error — it comes back in `skipped` with
+`reason: 'BROWSER_ONLY_PROPERTY'` and the rest of the batch still applies. The
+reasoning: a backend supplying a browser name is guessing, and a wrong guess
+silently corrupts attribution reporting.
+
+Where both a browser and a backend write the same column, **the browser wins** —
+it observed the value, the server supplied one — and the server write is
+reported as `BROWSER_OWNED_PROPERTY`.
+
+### Attributing and enriching in one call
+
+`wrap_agent` and `start_run` take an optional `user=` bag, so a request handler
+doesn't need a separate `upsert_user` call it has to sequence correctly:
+
+```python
+with trodo.wrap_agent('support-agent', distinct_id=user_id,
+                      user={'properties': {'plan': 'pro'}}) as run:
+    ...
+```
+
+Applied server-side and non-fatally — a failed trait write never costs you the
+trace. Use `upsert_user` directly when you need to know what landed.
+
 ---
 
 ## AI Agent Tracing (recommended)
@@ -586,10 +639,10 @@ Call `identify()` with the **same value** on the browser and server to merge all
 
 ```python
 # Python
-user.identify('user@example.com')   # → id_user@example.com
+user.identify('user@example.com')   # → user@example.com
 
 # Browser (same value)
-# Trodo.identify('user@example.com') → id_user@example.com
+# Trodo.identify('user@example.com') → user@example.com
 # Events from both sides now appear together in the dashboard
 ```
 

{trodo_python-2.17.0 → trodo_python-2.18.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trodo-python"
-version = "2.17.0"
+version = "2.18.1"
 description = "Trodo Analytics SDK for Python — server-side event tracking"
 readme = "README.md"
 license = { text = "ISC" }

trodo_python-2.18.1/tests/test_multi_agent_shape.py

@@ -0,0 +1,106 @@
+"""Multi-agent run shape — one run, sub-agents as ``agent``-kind child spans.
+
+The shape the ``trodo-tracing`` skill teaches: a request that fans out to
+sub-agents produces ONE run whose tree carries an ``agent`` span per sub-agent,
+with each sub-agent's own work nested underneath it. The failure mode this
+guards against is a ``wrap_agent`` per sub-agent, which shatters one request
+into N disconnected runs and loses whole-request cost, latency and the
+delegation tree.
+
+Also covers the module-level ``user`` / ``parent_run_id`` kwargs, which the
+skill's guidance writes and which the top-level wrappers used to silently drop.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+import trodo
+from trodo.otel.wrap_agent import span as span_ctx
+from trodo.otel.wrap_agent import wrap_agent as wrap_agent_ctx
+
+
+def _tree(payload):
+    """{span_id: (name, kind, parent_span_id)} for one ingested run payload."""
+    return {s["span_id"]: (s["name"], s["kind"], s["parent_span_id"]) for s in payload["spans"]}
+
+
+def test_sub_agents_nest_as_agent_spans_in_one_run(processor, http):
+    """A supervisor with two workers and a writer = 1 run, 3 agent spans."""
+    with wrap_agent_ctx(
+        processor=processor, team_site_id="site", agent_name="research_assistant",
+        distinct_id="u_1", conversation_id="thread_1",
+    ) as run:
+        run.set_input([{"role": "user", "content": "why did revenue drop"}])
+
+        with span_ctx("planner", kind="agent") as s:
+            s.set_output({"subtasks": ["pricing", "churn"]})
+
+        for topic in ("pricing", "churn"):
+            with span_ctx(f"researcher:{topic}", kind="agent") as s:
+                s.set_attribute("topic", topic)
+                # The sub-agent's own tool call nests under the sub-agent, not the run.
+                with span_ctx("web_search", kind="tool") as t:
+                    t.set_tool("web_search")
+                    t.set_output({"hits": 3})
+                s.set_output({"topic": topic})
+
+        run.set_output({"answer": "pricing change in March"})
+
+    # Exactly ONE run — not one per sub-agent.
+    assert len(http.run_ingest) == 1
+    payload = http.run_ingest[0]
+    assert payload["run"]["agent_name"] == "research_assistant"
+    assert payload["run"]["conversation_id"] == "thread_1"
+
+    tree = _tree(payload)
+    by_name = {v[0]: (sid, v[1], v[2]) for sid, v in tree.items()}
+
+    # Three agent-kind sub-agent spans, all siblings directly under the run root.
+    parents = set()
+    for name in ("planner", "researcher:pricing", "researcher:churn"):
+        sid, kind, parent = by_name[name]
+        assert kind == "agent", f"{name} should be an agent span, got {kind}"
+        parents.add(parent)
+    assert len(parents) == 1, "sub-agents should be siblings under one run root"
+
+    # Each tool span nests under its own researcher, preserving the delegation tree.
+    tool_parents = {v[2] for sid, v in tree.items() if v[1] == "tool"}
+    researcher_ids = {by_name[n][0] for n in ("researcher:pricing", "researcher:churn")}
+    assert tool_parents == researcher_ids
+
+    # The run rolls up the whole request, which is the point of keeping it one run.
+    assert payload["run"]["span_count"] == 5
+    assert payload["run"]["tool_count"] == 2
+
+
+def test_independently_triggered_sub_agent_links_via_parent_run_id(processor, http):
+    """The other shape: separate runs, linked — for independently-triggered work."""
+    with wrap_agent_ctx(
+        processor=processor, team_site_id="site", agent_name="intake", distinct_id="u_1",
+    ) as parent:
+        parent.set_output({"job": "enrich"})
+
+    with wrap_agent_ctx(
+        processor=processor, team_site_id="site", agent_name="enrichment",
+        distinct_id="u_1", parent_run_id=parent.run_id,
+    ) as child:
+        child.set_output({"done": True})
+
+    assert len(http.run_ingest) == 2
+    assert http.run_ingest[1]["run"]["parent_run_id"] == parent.run_id
+
+
+def test_module_level_wrappers_forward_user_and_parent_run_id():
+    """``trodo.wrap_agent(..., user=...)`` is what the skill tells people to write.
+
+    The module-level wrappers used to drop ``user`` on the floor (and ``agent``
+    also dropped ``parent_run_id``), so the documented call raised TypeError.
+    """
+    for fn, expected in (
+        (trodo.wrap_agent, {"user", "parent_run_id", "conversation_id", "metadata"}),
+        (trodo.agent, {"user", "parent_run_id", "conversation_id", "metadata"}),
+        (trodo.start_run, {"user", "parent_run_id", "conversation_id", "metadata", "input"}),
+    ):
+        params = set(inspect.signature(fn).parameters)
+        assert expected <= params, f"{fn.__name__} is missing {expected - params}"

trodo_python-2.18.1/tests/test_user_traits.py

@@ -0,0 +1,278 @@
+"""User traits — ``upsert_user``, the ``user`` bag on runs, and bounded caches.
+
+The stateless-backend story: a request handler knows who the user is and a few
+things about them for one request, and holds nothing between requests. These
+cover the ways that gets expressed, plus the memory ceiling that makes holding
+per-user state safe in a long-lived process.
+
+Mirrors ``sdks/trodo-node-sdk/tests/userTraits.test.ts``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from trodo.managers.user_manager import UserManager
+from trodo.otel.processor import TrodoSpanProcessor
+from trodo.otel.wrap_agent import start_run
+from trodo.otel.wrap_agent import wrap_agent as wrap_agent_ctx
+from trodo.util.lru import LruDict
+
+
+class UpsertRecorder:
+    """Stands in for HttpClient, recording exact wire payloads."""
+
+    def __init__(self) -> None:
+        self.calls = []
+
+    def post_user_upsert(self, payload):
+        self.calls.append(payload)
+        return {"success": True, "distinctId": payload["distinctId"], "created": False}
+
+
+class RunRecorder:
+    """Stands in for the processor's HTTP client."""
+
+    def __init__(self) -> None:
+        self.ingested = []
+        self.started = []
+
+    def post_run_ingest(self, payload):
+        self.ingested.append(payload)
+        return {"success": True}
+
+    def post_run_start(self, payload):
+        self.started.append(payload)
+        return {"success": True}
+
+    def post_run_end(self, run_id, payload):
+        return {"success": True}
+
+    def post_spans_append(self, run_id, spans):
+        return {"success": True}
+
+    def post_runless_spans(self, spans):
+        return {"success": True}
+
+
+# ---------------------------------------------------------------------------
+# upsert_user
+# ---------------------------------------------------------------------------
+
+
+def test_upsert_sends_every_bag():
+    http = UpsertRecorder()
+    users = UserManager(http)
+
+    users.upsert(
+        "user-42",
+        properties={"plan": "pro"},
+        set_once={"signup_date": "2026-01-04"},
+        fixed_properties={"last_location_country": "India"},
+    )
+
+    assert http.calls[0] == {
+        "distinctId": "user-42",
+        "properties": {"plan": "pro"},
+        "setOnce": {"signup_date": "2026-01-04"},
+        "fixedProperties": {"last_location_country": "India"},
+    }
+
+
+def test_upsert_omits_bags_not_supplied():
+    http = UpsertRecorder()
+    UserManager(http).upsert("user-42", properties={"plan": "pro"})
+
+    # The server tells "no bag" from "empty bag" by presence.
+    assert sorted(http.calls[0].keys()) == ["distinctId", "properties"]
+
+
+def test_upsert_with_no_traits_still_ensures_the_user():
+    http = UpsertRecorder()
+    UserManager(http).upsert("user-new")
+
+    assert http.calls == [{"distinctId": "user-new"}]
+
+
+def test_upsert_uses_camel_case_on_the_wire():
+    """Python callers write snake_case; the wire contract is camelCase."""
+    http = UpsertRecorder()
+    UserManager(http).upsert("user-42", set_once={"a": 1}, fixed_properties={"b": 2})
+
+    assert "setOnce" in http.calls[0]
+    assert "fixedProperties" in http.calls[0]
+    assert "set_once" not in http.calls[0]
+
+
+# ---------------------------------------------------------------------------
+# The `user` bag on runs
+# ---------------------------------------------------------------------------
+
+
+def test_user_bag_rides_on_the_run_payload():
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    with wrap_agent_ctx(
+        processor=processor,
+        team_site_id="site_abc",
+        agent_name="support",
+        distinct_id="user-42",
+        user={"properties": {"plan": "pro"}},
+    ) as run:
+        run.set_output("done")
+
+    processor.force_flush()
+    payload = http.ingested[0]
+    assert payload["run"]["user"] == {"properties": {"plan": "pro"}}
+
+
+def test_user_bag_accepts_snake_case_from_python_callers():
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    with wrap_agent_ctx(
+        processor=processor,
+        team_site_id="site_abc",
+        agent_name="support",
+        distinct_id="user-42",
+        user={"fixed_properties": {"last_location_country": "India"}},
+    ) as run:
+        run.set_output("done")
+
+    processor.force_flush()
+    # Normalised to the camelCase wire key.
+    assert http.ingested[0]["run"]["user"] == {
+        "fixedProperties": {"last_location_country": "India"}
+    }
+
+
+def test_user_bag_absent_when_not_passed():
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    with wrap_agent_ctx(
+        processor=processor,
+        team_site_id="site_abc",
+        agent_name="support",
+        distinct_id="user-42",
+    ) as run:
+        run.set_output("done")
+
+    processor.force_flush()
+    assert http.ingested[0]["run"].get("user") is None
+
+
+def test_empty_bag_is_dropped_rather_than_sent():
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    with wrap_agent_ctx(
+        processor=processor,
+        team_site_id="site_abc",
+        agent_name="support",
+        distinct_id="user-42",
+        user={"properties": {}},
+    ) as run:
+        run.set_output("done")
+
+    processor.force_flush()
+    assert http.ingested[0]["run"].get("user") is None
+
+
+def test_user_bag_travels_when_the_run_fails():
+    """A run that threw is exactly when you still want to know who the user was."""
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    with pytest.raises(ValueError):
+        with wrap_agent_ctx(
+            processor=processor,
+            team_site_id="site_abc",
+            agent_name="support",
+            distinct_id="user-42",
+            user={"properties": {"plan": "pro"}},
+        ):
+            raise ValueError("boom")
+
+    processor.force_flush()
+    run = http.ingested[0]["run"]
+    assert run["status"] == "error"
+    assert run["user"] == {"properties": {"plan": "pro"}}
+
+
+def test_start_run_carries_the_user_bag():
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    start_run(
+        processor=processor,
+        agent_name="support",
+        distinct_id="user-42",
+        user={"properties": {"plan": "pro"}},
+    )
+
+    payload = http.started[0]
+    run = payload.get("run", payload)
+    assert run["user"] == {"properties": {"plan": "pro"}}
+
+
+# ---------------------------------------------------------------------------
+# LruDict — the memory ceiling behind for_user()
+# ---------------------------------------------------------------------------
+
+
+def test_lru_holds_entries_below_the_cap():
+    d = LruDict(3)
+    d.set("a", 1)
+    d.set("b", 2)
+    d.set("c", 3)
+    assert len(d) == 3
+    assert d.get("a") == 1
+
+
+def test_lru_evicts_least_recently_used():
+    d = LruDict(3)
+    for k, v in [("a", 1), ("b", 2), ("c", 3)]:
+        d.set(k, v)
+    d.set("d", 4)
+
+    assert len(d) == 3
+    assert d.get("a") is None
+    assert d.get("d") == 4
+
+
+def test_lru_read_counts_as_use():
+    d = LruDict(3)
+    for k, v in [("a", 1), ("b", 2), ("c", 3)]:
+        d.set(k, v)
+    d.get("a")          # 'a' is newest now, 'b' is oldest
+    d.set("d", 4)
+
+    assert d.get("a") == 1
+    assert d.get("b") is None
+
+
+def test_lru_reset_refreshes_rather_than_duplicating():
+    d = LruDict(2)
+    d.set("a", 1)
+    d.set("b", 2)
+    d.set("a", 99)
+    d.set("c", 3)
+
+    assert d.get("a") == 99
+    assert d.get("b") is None
+    assert len(d) == 2
+
+
+def test_lru_footprint_stays_bounded_across_many_users():
+    d = LruDict(100)
+    for i in range(20_000):
+        d.set(f"user-{i}", i)
+    assert len(d) == 100
+
+
+def test_lru_falls_back_to_default_on_nonsense_cap():
+    d = LruDict(0)
+    d.set("a", 1)
+    assert d.get("a") == 1

{trodo_python-2.17.0 → trodo_python-2.18.1}/trodo/__init__.py

@@ -41,7 +41,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.16.0"
+__version__ = "2.18.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -80,6 +80,7 @@ __all__ = [
     "for_user",
     "track",
     "identify",
+    "upsert_user",
     "people_set",
     "people_set_once",
     "wallet_address",
@@ -256,6 +257,44 @@ def identify(identify_id: str, session_id: Optional[str] = None) -> UserContext:
     return _get_client().identify(identify_id, session_id)
 
 
+def upsert_user(
+    distinct_id: str,
+    *,
+    properties: Optional[Dict[str, Any]] = None,
+    set_once: Optional[Dict[str, Any]] = None,
+    fixed_properties: Optional[Dict[str, Any]] = None,
+):
+    """Create-or-update a user and their traits in one idempotent call.
+
+    The stateless-backend primitive: a request handler knows who the user is and
+    a few things about them for the duration of one request, and this is how you
+    say so. Safe to call on every request.
+
+        trodo.upsert_user(
+            "user-42",
+            properties={"plan": "pro"},
+            set_once={"signup_date": "2026-01-04"},
+            fixed_properties={"last_location_country": "India"},
+        )
+
+    Every bag is optional — with none of them it still ensures the user exists,
+    which is useful at signup, before they have produced any agent runs.
+
+    ``fixed_properties`` writes the real profile columns the dashboard filters
+    on, limited to what a backend can honestly know (country, city). Device,
+    browser, OS, referrer and UTM are browser observations and come back in
+    ``skipped`` instead of being stored.
+
+    Mirrors ``trodo.users.upsert(...)`` in trodo-node.
+    """
+    return _get_client().upsert_user(
+        distinct_id,
+        properties=properties,
+        set_once=set_once,
+        fixed_properties=fixed_properties,
+    )
+
+
 def people_set(distinct_id: str, properties: Dict[str, Any]):
     """Set profile properties for a user — module-level convenience mirroring
     ``trodo.people.set(distinctId, props)`` in trodo-node. Equivalent to
@@ -485,14 +524,21 @@ def wrap_agent(
     conversation_id: Optional[str] = None,
     parent_run_id: Optional[str] = None,
     metadata: Optional[Dict[str, Any]] = None,
+    user: Optional[Dict[str, Any]] = None,
 ) -> _wrap_agent_ctx:
-    """Wrap a block as an agent run — returns a context manager yielding RunHandle."""
+    """Wrap a block as an agent run — returns a context manager yielding RunHandle.
+
+    ``user`` carries profile traits alongside the run — ``{"properties": ...,
+    "set_once": ..., "fixed_properties": ...}`` — so a request handler can
+    attribute the run and enrich the profile in one round trip.
+    """
     return _get_client().wrap_agent(
         agent_name,
         distinct_id=distinct_id,
         conversation_id=conversation_id,
         parent_run_id=parent_run_id,
         metadata=metadata,
+        user=user,
     )
 
 
@@ -501,14 +547,18 @@ def agent(
     *,
     distinct_id: Optional[str] = None,
     conversation_id: Optional[str] = None,
+    parent_run_id: Optional[str] = None,
     metadata: Optional[Dict[str, Any]] = None,
+    user: Optional[Dict[str, Any]] = None,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """Decorator form of wrap_agent."""
     return _get_client().agent(
         agent_name,
         distinct_id=distinct_id,
         conversation_id=conversation_id,
+        parent_run_id=parent_run_id,
         metadata=metadata,
+        user=user,
     )
 
 
@@ -552,6 +602,7 @@ def start_run(
     parent_run_id: Optional[str] = None,
     metadata: Optional[Dict[str, Any]] = None,
     input: Any = None,
+    user: Optional[Dict[str, Any]] = None,
 ) -> str:
     """Open a Run record without a context manager.
 
@@ -568,6 +619,7 @@ def start_run(
         parent_run_id=parent_run_id,
         metadata=metadata,
         input=input,
+        user=user,
     )
 
 

{trodo_python-2.17.0 → trodo_python-2.18.1}/trodo/api/endpoints.py

@@ -4,6 +4,8 @@ EVENTS_BULK = "/api/events/bulk"
 IDENTIFY = "/api/sdk/identify"
 WALLET_ADDRESS = "/api/sdk/wallet-address"
 RESET = "/api/sdk/reset"
+# Identity + traits in one idempotent call.
+USERS_UPSERT = "/api/sdk/users/upsert"
 PEOPLE_SET = "/api/sdk/people/set"
 PEOPLE_SET_ONCE = "/api/sdk/people/set_once"
 PEOPLE_UNSET = "/api/sdk/people/unset"