feat(perps): support account notifications in session reads and events

[kartojal]

Description

Adds perps account notifications to the SDK, covering both REST reads and live session events.

What's included

• Notification models (models/perps/notifications.py): typed, discriminated union PerpsNotification covering position opened/increased/reduced/closed, limit order canceled, liquidation warning (isolated and cross variants, discriminated by margin_type), and position liquidated. Entries carry account-scoped read state (read_at) via PerpsNotificationEntry.
• Session reads:
  • session.list_notifications(since_seq=..., limit=...) newest-first paginator whose pages also report the account's unread count and durable_source_seq high-water mark (for backfilling after a gap).
  • session.mark_notifications_read(ids=... | up_to=...) mark by explicit ids, or everything up to and including a given entry.
• Session events: new PerpsNotificationEvent on the notifications channel, added to PerpsSessionEvent.
• Resync handling: notification frames carry the source engine sequence, which is not dense per channel, so local sequence-gap detection is disabled for notifications. Instead, server-sent resync control frames are surfaced as PerpsResyncEvent with a new reason="server" (plus optional timestamp), where sequence is the highest engine sequence among the dropped notifications.

Tests

Unit coverage for the account actions (listing, paging with since_seq, mark-read), event parsing (including server resync frames), and session wiring (~380 new test lines).

---

Note

Medium Risk
Adds new account APIs and changes resync semantics for notifications (no client gap detection, new server resync reason); liquidation-related payloads are user-facing but read-only with validation and tests.

Overview
Adds perps account notifications end-to-end: typed notification payloads, REST list/mark-read, and a live notifications session channel.

REST: list_notifications pages newest-first via /v1/account/notifications, carrying unread and durable_source_seq on each page and pinning optional since_seq / limit across cursor pages. mark_notifications_read accepts explicit ids or an up_to entry (base64url {ts, id} before cursor).

Session: Subscribes to notifications; exposes the same list/mark-read helpers. PerpsNotificationEvent joins PerpsSessionEvent. Notification sequences are not treated like dense per-channel seqs—local sequence_gap resync is skipped for notifications; server type: resync frames become PerpsResyncEvent with reason="server" (optional timestamp).

New discriminated notification models cover position lifecycle, limit cancel, liquidation warnings (isolated/cross), and liquidations; public exports updated in models/perps and perps.py.

^{Reviewed by Cursor Bugbot for commit 2b0bfe9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 29d71f6. Configure here.}

[naruto11eth]

approved. verified the contract against the spec sync (docs#256): the {ts,id} cursor encoding, the inclusive since_seq re-sent with follow-up cursors, the non-dense engine sq justifying the gap-detection opt-out, and the 7-kind set all match the documented protocol exactly.

two small things: this carries #188's commits, so land that one first and rebase. and the synthetic empty page reports unread=0 / durable_source_seq=0 — since the docs give durable_source_seq operational meaning as a backfill anchor, a fabricated 0 there could mislead; int | None would be honest. non-blocking.