fix: support correlation IDs in Python SDK

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.1.0
+
+- Added optional `correlation_id` support to the typed monitoring event request
+  model and ingestion serialization.
+
 ## 1.0.0
 
 - Rebuilt the client for the current 13-operation public monitoring API.

UPGRADING.md

@@ -15,3 +15,22 @@ Use these resources:
 Python models use snake_case fields and preserve unknown enum values through
 tolerant string enums. Existing v1 clients can continue using `/v1`; v2
 clients must use the v2 artifact and endpoint.
+
+## Upgrading to 2.1.0
+
+The 2.1.0 client adds the optional `correlation_id` field to
+`MonitoringEvent`. Use it when the same transaction spans services that report
+different references:
+
+```python
+MonitoringEvent(
+    flow="payment_to_wallet",
+    type="payment.succeeded",
+    reference="order-123",
+    entity_id="wallet-123",
+    correlation_id="checkout-123",
+)
+```
+
+The value is sent as event metadata and does not change operation grouping or
+evaluation behavior.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "reconify-python"
-version = "2.0.0"
+version = "2.1.0"
 description = "Typed Python client for the Reconify Public API"
 readme = "README.md"
 requires-python = ">=3.10"

src/reconify/models.py

@@ -131,6 +131,7 @@ class MonitoringEvent(RequestModel):
     entity_id: str
     occurred_at: datetime | None = None
     amount: str | None = None
+    correlation_id: str | None = None
     currency: str | None = None
     data: MonitoringEventData | None = None
     metadata: dict[str, str | int | float | bool] | None = None

tests/test_client.py

@@ -92,6 +92,7 @@ def handler(request: httpx.Request) -> httpx.Response:
                 reference="order-1",
                 entity_id="wallet-1",
                 amount="10.00",
+                correlation_id="checkout-123",
                 currency="USD",
             )
         ]
@@ -104,6 +105,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         client.ingestion.ingest_monitoring_events(body)
 
     assert json.loads(requests[0].content)["events"][0]["entity_id"] == "wallet-1"
+    assert json.loads(requests[0].content)["events"][0]["correlation_id"] == "checkout-123"
     assert requests[0].url.path == "/v2/events"