foil-server 0.2.3__tar.gz → 0.2.4__tar.gz

{foil_server-0.2.3 → foil_server-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foil-server
-Version: 0.2.3
+Version: 0.2.4
 Summary: Official Foil Python server SDK
 Project-URL: Homepage, https://github.com/abxy-labs/foil-server-python
 Project-URL: Repository, https://github.com/abxy-labs/foil-server-python
@@ -57,6 +57,8 @@ client = Foil(secret_key="sk_live_...")
 
 page = client.sessions.list(verdict="bot", limit=25)
 session = client.sessions.get("sid_123")
+client.sessions.attach_client_user("sid_123", "user_123")
+client.sessions.clear_client_user("sid_123")
 ```
 
 ### Sealed token verification

{foil_server-0.2.3 → foil_server-0.2.4}/README.md

@@ -42,6 +42,8 @@ client = Foil(secret_key="sk_live_...")
 
 page = client.sessions.list(verdict="bot", limit=25)
 session = client.sessions.get("sid_123")
+client.sessions.attach_client_user("sid_123", "user_123")
+client.sessions.clear_client_user("sid_123")
 ```
 
 ### Sealed token verification

{foil_server-0.2.3 → foil_server-0.2.4}/foil_server/client.py

@@ -145,6 +145,9 @@ def _parse_session_summary(data: dict[str, Any]) -> SessionSummary:
         object=str(data["object"]),
         id=str(data["id"]),
         created_at=data.get("created_at"),
+        client_user_id=data.get("client_user_id")
+        if isinstance(data.get("client_user_id"), str) or data.get("client_user_id") is None
+        else None,
         latest_decision=_parse_decision(dict(data["latest_decision"])),
         visitor_fingerprint=_parse_visitor_fingerprint_link(data.get("visitor_fingerprint")),
     )
@@ -155,6 +158,9 @@ def _parse_session_detail(data: dict[str, Any]) -> SessionDetail:
         object=str(data["object"]),
         id=str(data["id"]),
         created_at=data.get("created_at"),
+        client_user_id=data.get("client_user_id")
+        if isinstance(data.get("client_user_id"), str) or data.get("client_user_id") is None
+        else None,
         decision=_parse_session_decision(dict(data["decision"])),
         highlights=[dict(item) for item in data.get("highlights", []) if isinstance(item, dict)],
         attribution=dict(data.get("attribution")) if isinstance(data.get("attribution"), dict) else None,
@@ -570,6 +576,22 @@ class SessionsAPI(_BaseAPI):
         response = self._client._request_json("GET", f"/v1/sessions/{session_id}")
         return _parse_session_detail(dict(response["data"]))
 
+    def attach_client_user(self, session_id: str, client_user_id: str) -> SessionDetail:
+        response = self._client._request_json(
+            "PATCH",
+            f"/v1/sessions/{session_id}",
+            body={"client_user_id": client_user_id},
+        )
+        return _parse_session_detail(dict(response["data"]))
+
+    def clear_client_user(self, session_id: str) -> SessionDetail:
+        response = self._client._request_json(
+            "PATCH",
+            f"/v1/sessions/{session_id}",
+            body={"client_user_id": None},
+        )
+        return _parse_session_detail(dict(response["data"]))
+
     def iter(
         self,
         *,

{foil_server-0.2.3 → foil_server-0.2.4}/foil_server/types.py

@@ -72,6 +72,7 @@ class SessionSummary:
     object: str
     id: str
     created_at: str | None
+    client_user_id: str | None
     latest_decision: Decision
     visitor_fingerprint: VisitorFingerprintLink | None
 
@@ -81,6 +82,7 @@ class SessionDetail:
     object: str
     id: str
     created_at: str | None
+    client_user_id: str | None
     decision: SessionDecision
     highlights: list[dict[str, Any]]
     attribution: dict[str, Any] | None

{foil_server-0.2.3 → foil_server-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "foil-server"
-version = "0.2.3"
+version = "0.2.4"
 description = "Official Foil Python server SDK"
 readme = "README.md"
 license = { text = "MIT" }

{foil_server-0.2.3 → foil_server-0.2.4}/spec/fixtures/api/sessions/detail.json

@@ -3,6 +3,7 @@
     "object": "session",
     "id": "sid_0123456789abcdefghjkmnpqrs",
     "created_at": "2026-03-24T20:00:00.000Z",
+    "client_user_id": "user_123",
     "decision": {
       "event_id": "evt_23456789abcdefghjkmnpqrstv",
       "automation_status": "automated",

{foil_server-0.2.3 → foil_server-0.2.4}/spec/fixtures/api/sessions/list.json

@@ -4,6 +4,7 @@
       "object": "session",
       "id": "sid_0123456789abcdefghjkmnpqrs",
       "created_at": "2026-03-24T20:00:00.000Z",
+      "client_user_id": "user_123",
       "latest_decision": {
         "event_id": "evt_23456789abcdefghjkmnpqrstv",
         "verdict": "human",

{foil_server-0.2.3 → foil_server-0.2.4}/spec/fixtures/manifest.json

@@ -36,6 +36,12 @@
       "method": "get",
       "status": "200"
     },
+    {
+      "file": "api/sessions/detail.json",
+      "path": "/v1/sessions/{sessionId}",
+      "method": "patch",
+      "status": "200"
+    },
     {
       "file": "api/fingerprints/list.json",
       "path": "/v1/fingerprints",

{foil_server-0.2.3 → foil_server-0.2.4}/spec/openapi.json

@@ -14,11 +14,11 @@
   "tags": [
     {
       "name": "Sessions",
-      "description": "Durable session readback endpoints."
+      "description": "Session readback endpoints."
     },
     {
       "name": "Visitor fingerprints",
-      "description": "Durable visitor fingerprint readback endpoints."
+      "description": "Visitor fingerprint readback endpoints."
     },
     {
       "name": "Organizations",
@@ -103,6 +103,7 @@
                         "object": "session",
                         "id": "sid_87wfetm98myh9awj0dpt28a3kc",
                         "created_at": "2026-03-24T20:00:00.000Z",
+                        "client_user_id": "user_123",
                         "latest_decision": {
                           "event_id": "evt_srwqc0yqhz4bxvtrdtf69q7vkr",
                           "verdict": "human",
@@ -279,6 +280,7 @@
                       "object": "session",
                       "id": "sid_87wfetm98myh9awj0dpt28a3kc",
                       "created_at": "2026-03-24T20:00:00.000Z",
+                      "client_user_id": "user_123",
                       "decision": {
                         "event_id": "evt_srwqc0yqhz4bxvtrdtf69q7vkr",
                         "automation_status": "automated",
@@ -908,6 +910,87 @@
           }
         },
         "description": "Requires the `sessions:read` secret-key scope."
+      },
+      "patch": {
+        "tags": [
+          "Sessions"
+        ],
+        "operationId": "updateSession",
+        "summary": "Update a session",
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/SessionId",
+              "example": "sid_87wfetm98myh9awj0dpt28a3kc"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateSessionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated session detail response.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SessionDetailResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid API key.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Secret key missing the required `sessions:update` scope.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Session not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiErrorEnvelope"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Invalid update payload.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "description": "Set or clear the customer-supplied `client_user_id` for a session. Requires the `sessions:update` secret-key scope."
       }
     },
     "/v1/fingerprints": {
@@ -2139,6 +2222,7 @@
                   "environment": "live",
                   "scopes": [
                     "sessions:read",
+                    "sessions:update",
                     "fingerprints:read"
                   ]
                 }
@@ -7292,6 +7376,7 @@
                     "*",
                     "sessions:list",
                     "sessions:read",
+                    "sessions:update",
                     "fingerprints:list",
                     "fingerprints:read",
                     "organizations:create",
@@ -7674,6 +7759,7 @@
                 "*",
                 "sessions:list",
                 "sessions:read",
+                "sessions:update",
                 "fingerprints:list",
                 "fingerprints:read",
                 "organizations:create",
@@ -7703,6 +7789,7 @@
           "environment": "live",
           "scopes": [
             "sessions:read",
+            "sessions:update",
             "fingerprints:read"
           ]
         },
@@ -10343,6 +10430,7 @@
                     "*",
                     "sessions:list",
                     "sessions:read",
+                    "sessions:update",
                     "fingerprints:list",
                     "fingerprints:read",
                     "organizations:create",
@@ -11725,7 +11813,8 @@
           "device",
           "analysis_coverage",
           "signals_fired",
-          "client_telemetry"
+          "client_telemetry",
+          "client_user_id"
         ],
         "properties": {
           "object": {
@@ -11744,6 +11833,15 @@
             "format": "date-time",
             "example": "2026-03-24T20:00:00.000Z"
           },
+          "client_user_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "maxLength": 256,
+            "description": "Customer-supplied identifier for the end user associated with this Foil session. Set with PATCH /v1/sessions/{sessionId}.",
+            "example": "user_123"
+          },
           "decision": {
             "$ref": "#/components/schemas/SessionDetailDecision",
             "example": {
@@ -12647,6 +12745,7 @@
           "object": "session",
           "id": "sid_87wfetm98myh9awj0dpt28a3kc",
           "created_at": "2026-03-24T20:00:00.000Z",
+          "client_user_id": "user_123",
           "decision": {
             "event_id": "evt_srwqc0yqhz4bxvtrdtf69q7vkr",
             "automation_status": "automated",
@@ -13379,6 +13478,7 @@
               "object": "session",
               "id": "sid_87wfetm98myh9awj0dpt28a3kc",
               "created_at": "2026-03-24T20:00:00.000Z",
+              "client_user_id": "user_123",
               "decision": {
                 "event_id": "evt_srwqc0yqhz4bxvtrdtf69q7vkr",
                 "automation_status": "automated",
@@ -13903,6 +14003,7 @@
             "object": "session",
             "id": "sid_87wfetm98myh9awj0dpt28a3kc",
             "created_at": "2026-03-24T20:00:00.000Z",
+            "client_user_id": "user_123",
             "decision": {
               "event_id": "evt_srwqc0yqhz4bxvtrdtf69q7vkr",
               "automation_status": "automated",
@@ -15263,6 +15364,7 @@
                 "object": "session",
                 "id": "sid_87wfetm98myh9awj0dpt28a3kc",
                 "created_at": "2026-03-24T20:00:00.000Z",
+                "client_user_id": "user_123",
                 "latest_decision": {
                   "event_id": "evt_srwqc0yqhz4bxvtrdtf69q7vkr",
                   "verdict": "human",
@@ -15289,6 +15391,7 @@
                 "object": "session",
                 "id": "sid_87wfetm98myh9awj0dpt28a3kc",
                 "created_at": "2026-03-24T20:00:00.000Z",
+                "client_user_id": "user_123",
                 "latest_decision": {
                   "event_id": "evt_srwqc0yqhz4bxvtrdtf69q7vkr",
                   "verdict": "human",
@@ -15332,6 +15435,7 @@
               "object": "session",
               "id": "sid_87wfetm98myh9awj0dpt28a3kc",
               "created_at": "2026-03-24T20:00:00.000Z",
+              "client_user_id": "user_123",
               "latest_decision": {
                 "event_id": "evt_srwqc0yqhz4bxvtrdtf69q7vkr",
                 "verdict": "human",
@@ -18169,7 +18273,8 @@
           "id",
           "created_at",
           "latest_decision",
-          "visitor_fingerprint"
+          "visitor_fingerprint",
+          "client_user_id"
         ],
         "properties": {
           "object": {
@@ -18188,6 +18293,15 @@
             "format": "date-time",
             "example": "2026-03-24T20:00:00.000Z"
           },
+          "client_user_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "maxLength": 256,
+            "description": "Customer-supplied identifier for the end user associated with this Foil session. Set with PATCH /v1/sessions/{sessionId}.",
+            "example": "user_123"
+          },
           "latest_decision": {
             "$ref": "#/components/schemas/Decision",
             "example": {
@@ -18232,6 +18346,7 @@
           "object": "session",
           "id": "sid_87wfetm98myh9awj0dpt28a3kc",
           "created_at": "2026-03-24T20:00:00.000Z",
+          "client_user_id": "user_123",
           "latest_decision": {
             "event_id": "evt_srwqc0yqhz4bxvtrdtf69q7vkr",
             "verdict": "human",
@@ -18314,6 +18429,7 @@
                 "*",
                 "sessions:list",
                 "sessions:read",
+                "sessions:update",
                 "fingerprints:list",
                 "fingerprints:read",
                 "organizations:create",
@@ -18495,6 +18611,27 @@
           "status": "active"
         }
       },
+      "UpdateSessionRequest": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "client_user_id"
+        ],
+        "properties": {
+          "client_user_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "maxLength": 256,
+            "description": "Customer-supplied identifier for the end user associated with this Foil session. Set with PATCH /v1/sessions/{sessionId}.",
+            "example": "user_123"
+          }
+        },
+        "example": {
+          "client_user_id": "user_123"
+        }
+      },
       "UpdateWebhookEndpointRequest": {
         "type": "object",
         "additionalProperties": false,

{foil_server-0.2.3 → foil_server-0.2.4}/tests/test_client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import os
 import unittest
 
@@ -142,6 +143,7 @@ class ClientTests(unittest.TestCase):
         try:
             session = client.sessions.get("sid_0123456789abcdefghjkmnpqrs")
             self.assertEqual(session.id, "sid_0123456789abcdefghjkmnpqrs")
+            self.assertEqual(session.client_user_id, "user_123")
             self.assertIsNone(session.native_runtime_integrity)
             self.assertIsNone(session.native_app)
             self.assertIsNone(session.native_carrier)
@@ -155,6 +157,27 @@ class ClientTests(unittest.TestCase):
         finally:
             client.close()
 
+    def test_attach_and_clear_client_user_id(self) -> None:
+        session_fixture = load_fixture("api/sessions/detail.json")
+        seen_bodies: list[dict[str, object]] = []
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            self.assertEqual(request.method, "PATCH")
+            self.assertEqual(request.url.path, "/v1/sessions/sid_0123456789abcdefghjkmnpqrs")
+            self.assertEqual(request.headers["Authorization"], "Bearer sk_live_test")
+            seen_bodies.append(json.loads(request.content.decode("utf-8")))
+            return json_response(session_fixture)
+
+        client = Foil(secret_key="sk_live_test", transport=httpx.MockTransport(handler))
+        try:
+            attached = client.sessions.attach_client_user("sid_0123456789abcdefghjkmnpqrs", "user_123")
+            cleared = client.sessions.clear_client_user("sid_0123456789abcdefghjkmnpqrs")
+            self.assertEqual(attached.id, "sid_0123456789abcdefghjkmnpqrs")
+            self.assertEqual(cleared.id, "sid_0123456789abcdefghjkmnpqrs")
+            self.assertEqual(seen_bodies, [{"client_user_id": "user_123"}, {"client_user_id": None}])
+        finally:
+            client.close()
+
     def test_organizations_and_api_keys(self) -> None:
         organization_fixture = load_fixture("api/organizations/organization.json")
         organization_create_fixture = load_fixture("api/organizations/organization-create.json")

{foil_server-0.2.3 → foil_server-0.2.4}/tests/test_contract.py

@@ -104,6 +104,14 @@ class ContractTests(unittest.TestCase):
         self.assertEqual(schemas["ApiKeyId"]["pattern"], "^key_[0123456789abcdefghjkmnpqrstvwxyz]{26}$")
 
         self.assertEqual(strip_examples(schemas["SessionSummary"]["properties"]["id"]), {"$ref": "#/components/schemas/SessionId"})
+        self.assertEqual(
+            strip_examples(schemas["SessionSummary"]["properties"]["client_user_id"]),
+            {
+                "type": ["string", "null"],
+                "maxLength": 256,
+                "description": "Customer-supplied identifier for the end user associated with this Foil session. Set with PATCH /v1/sessions/{sessionId}.",
+            },
+        )
         self.assertEqual(strip_examples(schemas["Organization"]["properties"]["status"]), {"$ref": "#/components/schemas/OrganizationStatus"})
         self.assertEqual(strip_examples(schemas["ApiKey"]["properties"]["status"]), {"$ref": "#/components/schemas/ApiKeyStatus"})
         self.assertEqual(
@@ -113,7 +121,7 @@ class ContractTests(unittest.TestCase):
         self.assertEqual(schemas["OrganizationStatus"]["enum"], ["active", "suspended", "deleted"])
         self.assertEqual(schemas["ApiKeyStatus"]["enum"], ["active", "rotating", "revoked"])
         self.assertTrue(
-            {"decision", "highlights", "attribution", "web_bot_auth", "network", "runtime_integrity", "visitor_fingerprint", "connection_fingerprint", "previous_decisions", "request", "browser", "device", "analysis_coverage", "signals_fired", "client_telemetry"}.issubset(
+            {"client_user_id", "decision", "highlights", "attribution", "web_bot_auth", "network", "runtime_integrity", "visitor_fingerprint", "connection_fingerprint", "previous_decisions", "request", "browser", "device", "analysis_coverage", "signals_fired", "client_telemetry"}.issubset(
                 set(schemas["SessionDetail"]["required"])
             )
         )
@@ -157,6 +165,8 @@ class ContractTests(unittest.TestCase):
 
         self.assertEqual(paths["/v1/sessions"]["get"]["operationId"], "listSessions")
         self.assertEqual(paths["/v1/sessions"]["get"]["tags"], ["Sessions"])
+        self.assertEqual(paths["/v1/sessions/{sessionId}"]["patch"]["operationId"], "updateSession")
+        self.assertEqual(paths["/v1/sessions/{sessionId}"]["patch"]["tags"], ["Sessions"])
         self.assertEqual(paths["/v1/fingerprints/{visitorId}"]["get"]["operationId"], "getVisitorFingerprint")
         self.assertEqual(paths["/v1/fingerprints/{visitorId}"]["get"]["tags"], ["Visitor fingerprints"])
         self.assertEqual(paths["/v1/organizations/{organizationId}"]["patch"]["operationId"], "updateOrganization")