From 637c9bb5c746cac1b8d325662ebdde85a3688ab7 Mon Sep 17 00:00:00 2001
From: Mangabo  Kolawole <onaelmangabo@gmail.com>
Date: Sun, 23 Aug 2026 01:16:15 +0100
Subject: [PATCH] fix: support correlation IDs in Python SDK

---
 CHANGELOG.md           |  5 +++++
 UPGRADING.md           | 19 +++++++++++++++++++
 pyproject.toml         |  2 +-
 src/reconify/models.py |  1 +
 tests/test_client.py   |  2 ++
 uv.lock                |  2 +-
 6 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e16bec8..6bdbf4f 100644
--- a/CHANGELOG.md
+++ b/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.
diff --git a/UPGRADING.md b/UPGRADING.md
index 4ea7ed0..0ac3338 100644
--- a/UPGRADING.md
+++ b/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.
diff --git a/pyproject.toml b/pyproject.toml
index efb8eab..f914cfc 100644
--- a/pyproject.toml
+++ b/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"
diff --git a/src/reconify/models.py b/src/reconify/models.py
index f59f854..1648573 100644
--- a/src/reconify/models.py
+++ b/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
diff --git a/tests/test_client.py b/tests/test_client.py
index 5c0e24c..1ae9a35 100644
--- a/tests/test_client.py
+++ b/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"
 
 
diff --git a/uv.lock b/uv.lock
index f976109..955c344 100644
--- a/uv.lock
+++ b/uv.lock
@@ -567,7 +567,7 @@ wheels = [
 
 [[package]]
 name = "reconify-python"
-version = "1.0.0"
+version = "2.1.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },