[P2][models] SubscriptionEvent types fields the events API never sends (type, code, payload, created_at) and leaves observed_at/snapshot/deltas untyped #149

Status

Confirmed on 2026-09-13 against the live GET /v1/subscriptions/events body and oilpriceapi-api origin/main app/models/watch_event.rb#as_poll_json. The SDK code is origin/main a5304b3, oilpriceapi/models.py SubscriptionEvent.

Defect

SubscriptionEvent models fields the API does not send, and leaves the fields it does send untyped.

Wire fields the model does not declare, reachable only as untyped pydantic extras (extra="allow"): id, observed_at (ISO string, not parsed to datetime), snapshot, deltas, source, tool_name.

Consequences:

• The docstring example on origin/main, print(event.type, event.code), prints None None for every real event.
• event.created_at is always None.
• Price data (snapshot, deltas) has no type.

Repro

Live body, GET /v1/subscriptions/events?since=99&limit=2, one event shown:

{"id": "d73c7b25-875b-403e-a429-0d7049245c30", "seq": 100,
 "watch_id": "b84b24a0-2b28-4eac-835e-db92bab5c0cb",
 "observed_at": "2026-09-08T16:20:42Z",
 "snapshot": {"BRENT_CRUDE_USD": {"as_of": "2026-09-08T16:16:14Z", "price": 97.27, "currency": "USD", "change_24h_pct": -0.04}},
 "deltas": {"BRENT_CRUDE_USD": {"pct_change": -0.53, "price_change": -0.52}},
 "source": "api", "tool_name": "opa_create_price_subscription"}

from oilpriceapi.models import SubscriptionEvent
e = SubscriptionEvent(**event)
print(e.type, e.code, e.created_at)   # None None None
print(type(e.observed_at))            # <class 'str'>  (an extra, not a datetime)

Expected

Type id, observed_at (a datetime), snapshot, deltas, source and tool_name from the wire shape. Either keep type/code/payload/created_at as deprecated aliases or drop them in a minor release with a CHANGELOG note. Apply to sync and async; they share the model.

PR #147 (#142) already changes the events() docstring example to event.seq, event.watch_id. It does not change the model.