PTHMINT-119: SSE event stream support and EventManager#59
Open
zulquer wants to merge 4 commits into
Open
Conversation
zulquer
force-pushed
the
PTHMINT-118
branch
2 times, most recently
from
a3ccc41 to
08221e9
Compare
Introduce Server-Sent Events support and higher-level helpers for subscribing to order event streams. Adds multisafepay.client.sse (ServerSentEvent, ServerSentEventStream, StreamingResponse) and an EventStream adapter under api.paths.events.stream to deserialize SSE payloads into Event/EventData models. Adds EventManager for subscribing by token or from an Order response, and exposes get_event_manager() on the Sdk. Extend Order response to include events_token/events_url/events_stream_url with normalization for backward compatibility with legacy event_token/event_stream_url fields. Include an example (examples/event_manager/subscribe_events.py), update examples/order_manager/cloud_pos_order.py, update README with usage and env vars, export SSE types from client.__init__, and add unit and e2e tests for stream and manager behavior. Also contains small formatting/.env and test tweaks.
Introduce streaming HTTP support across the SDK: add HTTPStreamResponse and open_stream(...) to the HTTPTransport protocol and export HTTPStreamResponse from transport package. Update RequestsTransport to share request preparation with a new open_stream implementation and return a _RequestsStreamResponse adapter that exposes readline(), close(), and raise_for_status(). Modify SSE client and EventStream to use the configured transport.open_stream(...) (and raise a clear error if the transport lacks streaming support), and pass the client transport from EventManager to EventStream.open. Update README and unit tests to reflect streaming behavior and ensure streams are closed on failing status checks.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #59 +/- ##
==========================================
- Coverage 92.96% 92.61% -0.35%
==========================================
Files 172 180 +8
Lines 3027 3331 +304
==========================================
+ Hits 2814 3085 +271
- Misses 213 246 +33 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
Introduces a Server-Sent Events (SSE) subscription API for order events. Adds a transport-level streaming abstraction (HTTPStreamResponse / open_stream), a generic ServerSentEventStream parser in the client layer, an events-path EventStream + response models (Event, EventData), and an EventManager exposed via the SDK. Also adds backward-compatible singular/plural event field aliases to Order and a runnable example + E2E test for Cloud POS event streaming.
Changes:
- New SSE streaming stack:
HTTPStreamResponseprotocol +RequestsTransport.open_streamadapter,ServerSentEventStreamparser, events-pathEventStreamand response models,EventManageron the SDK. - Backward-compat normalization between
events_*andevent_*fields onOrder, plus publicAUTH_SCOPE_*aliases re-exposed onClient. - New
examples/event_manager/subscribe_events.py, E2E fixtures/test for SSE, and README documentation for SSE usage and required env vars.
Reviewed changes
Copilot reviewed 26 out of 27 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/multisafepay/transport/http_transport.py | Adds HTTPStreamResponse protocol and open_stream to HTTPTransport; reorders class definitions. |
| src/multisafepay/transport/requests_transport.py | Adds streaming adapter _RequestsStreamResponse and shared _prepare_request used by request/open_stream. |
| src/multisafepay/transport/init.py | Exports HTTPStreamResponse. |
| src/multisafepay/client/sse.py | Generic ServerSentEvent / ServerSentEventStream parser and opener using the configured transport. |
| src/multisafepay/client/client.py | Public AUTH_SCOPE_* constants re-exported from ScopedCredentialResolver. |
| src/multisafepay/client/init.py | Re-exports SSE types. |
| src/multisafepay/api/paths/events/event_manager.py | EventManager with subscribe_events / subscribe_order_events. |
| src/multisafepay/api/paths/events/init.py | Exports EventManager. |
| src/multisafepay/api/paths/events/stream/init.py | Events-path EventStream adapter wrapping the generic SSE stream. |
| src/multisafepay/api/paths/events/stream/response/event.py | Event response model with recursive payload adaptation. |
| src/multisafepay/api/paths/events/stream/response/components/event_data.py | EventData model and EventDataPayload union. |
| src/multisafepay/api/paths/events/stream/response/{init,components/init}.py | Package exports. |
| src/multisafepay/api/paths/orders/response/order_response.py | Adds events_* fields and _normalize_event_fields aliasing. |
| src/multisafepay/sdk.py | Adds get_event_manager(). |
| examples/event_manager/subscribe_events.py | Cloud POS order creation + SSE subscription example. |
| examples/order_manager/cloud_pos_order.py | Minor formatting cleanup. |
| README.md | Documents transport streaming, event-stream usage, env vars. |
| .env.example | Trailing-newline fix. |
| tests/multisafepay/unit/api/path/events/** | Unit tests for EventManager and event-path EventStream. |
| tests/multisafepay/unit/api/path/orders/response/test_unit_order_response.py | Tests singular/plural event field normalization. |
| tests/multisafepay/unit/transport/test_unit_transport.py | Test for RequestsTransport.open_stream. |
| tests/multisafepay/unit/test_unit_sdk.py | Test for Sdk.get_event_manager(). |
| tests/multisafepay/unit/client/test_unit_client.py | Test for Client.AUTH_SCOPE_* aliases. |
| tests/multisafepay/e2e/examples/event_manager/{conftest.py,test_subscribe_events.py} | E2E fixtures and test for SSE subscription against Cloud POS. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Add a runtime-checkable HTTPStreamingTransport protocol that extends HTTPTransport with open_stream and update the SDK to require it for SSE subscriptions. Adjust sse client to use isinstance checks and improve error messaging; export the new protocol from transport package. Rename order response fields to events_token/events_url/events_stream_url while keeping backward-compatible aliases, add an assertion in SSE payload adaptation, update README to document the HTTPStreamingTransport requirement, and update/add unit tests to cover the protocol split and new error messages.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
EventManagerclass (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]EventStreamclass (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:
Event,EventData, andEventDataPayload, including recursive deserialization for nested payloads. [1] [2] [3] [4]Order Response Backward Compatibility:
Orderresponse 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:
subscribe_events.pydemonstrating how to create a Cloud POS order and subscribe to its event stream using the new API.Client Exports:
ServerSentEventandServerSentEventStreamfrom the client package for easier access.