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.