From f580d0ffe897bcfebd264f827c30fb79a19aaf46 Mon Sep 17 00:00:00 2001
From: "paperclip-resolver[bot]"
 <3736210+paperclip-resolver[bot]@users.noreply.github.com>
Date: Tue, 2 Jun 2026 11:31:13 -0400
Subject: [PATCH] docs(timestamp): document `timestamp` as
 delivery/feed-freshness (OpticOdds-parity) + bump 0.5.0

The API now emits a single per-odd `timestamp` (delivery / last-refreshed,
advances every ingest cycle, matching OpticOdds), replacing odds_changed_at/
last_seen_at/wire_received_at. The SDK already modeled `timestamp` (was always
null); this clarifies its semantics on OddsLine + ArbitrageLeg. No model change.

Refs SHA-1048
Type: docs
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md           | 11 +++++++++++
 pyproject.toml         |  2 +-
 src/sharpapi/models.py |  5 +++++
 3 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9c6acf0..bb1e649 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 All notable changes to the `sharpapi` Python SDK are documented here.
 
+## 0.5.0 — 2026-06-02
+
+### Changed
+
+- `OddsLine.timestamp` / `ArbitrageLeg.timestamp` documented as the **delivery /
+  last-refreshed** feed-freshness timestamp (advances every ingest cycle),
+  matching OpticOdds' `timestamp` — NOT a price-last-changed time. The API now
+  populates this field (previously always `null`). The removed
+  `odds_changed_at` / `last_seen_at` / `wire_received_at` were never modeled by
+  this SDK, so no model change is needed. (SHA-1048)
+
 ## 0.4.0 — 2026-05-31
 
 ### Added
diff --git a/pyproject.toml b/pyproject.toml
index 338d3b8..b92b4b7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sharpapi"
-version = "0.4.0"
+version = "0.5.0"
 description = "Official Python SDK for the SharpAPI real-time sports betting odds API"
 readme = "README.md"
 license = "MIT"
diff --git a/src/sharpapi/models.py b/src/sharpapi/models.py
index f4ec9ef..1cd74bc 100644
--- a/src/sharpapi/models.py
+++ b/src/sharpapi/models.py
@@ -219,6 +219,9 @@ class OddsLine(BaseModel):
     probability: float
     line: float | None = None
     event_start_time: str | None = None
+    # ISO 8601 — when SharpAPI last refreshed this odd through its pipeline
+    # (advances every ingest cycle). A feed-freshness / delivery signal matching
+    # OpticOdds' `timestamp`; NOT a price-last-changed time. (SHA-1048)
     timestamp: str | None = None
     is_live: bool = False
     # True (default) = market open and bettable; False = market suspended/closed
@@ -315,6 +318,8 @@ class ArbitrageLeg(BaseModel):
     odds_decimal: float
     implied_probability: float | None = None
     stake_percent: float
+    # ISO 8601 last-refreshed (feed-freshness) timestamp for this leg's odd —
+    # see OddsLine.timestamp. (SHA-1048)
     timestamp: str | None = None
     external_event_id: str | None = None
     selection_id: str | None = None