PTHMINT-119: SSE event stream support and EventManager

[zulquer]

This pull request introduces a new event streaming API for order events, allowing clients to subscribe to real-time updates using server-sent events (SSE). It includes new response models, event stream handling, and updates for backward compatibility with both singular and plural event field names in order responses.

The most important changes are:

Event Streaming API Implementation:

• Added the EventManager class (event_manager.py) and its public interface (__init__.py) to manage event stream subscriptions for orders. This provides methods to subscribe to event streams using event tokens and URLs, or directly from order response objects. [1] [2]
• Introduced the EventStream class (stream/__init__.py) to handle server-sent event streams, including deserialization of payloads and context manager support. This enables iteration over live event messages from the SSE endpoint.

Event Response Models:

• Added new response models for SSE events: Event, EventData, and EventDataPayload, including recursive deserialization for nested payloads. [1] [2] [3] [4]

Order Response Backward Compatibility:

• Updated the Order response model to support both singular and plural forms of event-related fields (events_token, event_token, etc.), with normalization logic to ensure compatibility with different API payloads. [1] [2] [3]

Example Usage:

• Added a new example script subscribe_events.py demonstrating how to create a Cloud POS order and subscribe to its event stream using the new API.

Client Exports:

• Re-exported ServerSentEvent and ServerSentEventStream from the client package for easier access.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.44%. Comparing base (8954459) to head (e36297e).

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #59      +/-   ##
==========================================
- Coverage   92.83%   92.44%   -0.39%     
==========================================
  Files         164      172       +8     
  Lines        2889     3192     +303     
==========================================
+ Hits         2682     2951     +269     
- Misses        207      241      +34     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.