diff --git a/codegen/templates/events.py.tmpl b/codegen/templates/events.py.tmpl index f79fa323..fd2f6deb 100644 --- a/codegen/templates/events.py.tmpl +++ b/codegen/templates/events.py.tmpl @@ -27,13 +27,13 @@ from ._events import ( UnknownEvent, verify_event_signature, ) -{{- if .ObjectTypes }} from .types import ( + EventObjectType, + EventType, {{- range .ObjectTypes }} {{ . }}, {{- end }} ) -{{- end }} {{ range .Events -}} @@ -45,9 +45,9 @@ class {{ .ClassName }}(FetchableEvent[{{ .ObjectType }}]): {{ .ObjectType }}. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = {{ printf "%q" .EventType }} + EVENT_TYPE: typing.ClassVar[EventType] = {{ printf "%q" .EventType }} type: typing.Literal[{{ printf "%q" .EventType }}] = pydantic.Field(default={{ printf "%q" .EventType }}, frozen=True) - _object_type: typing.ClassVar[str | None] = {{ printf "%q" .ObjectKind }} + _object_type: typing.ClassVar[EventObjectType | None] = {{ printf "%q" .ObjectKind }} _response_model: typing.ClassVar[typing.Type[pydantic.BaseModel]] = {{ .ObjectType }} @@ -58,7 +58,7 @@ KnownEventNotification = ({{ range $index, $event := .Events }}{{ if $index }} | KnownEventNotification = EventNotification {{ end }} -_EVENT_MODELS: typing.Dict[str, typing.Type[EventNotification]] = { +_EVENT_MODELS: typing.Dict[EventType, typing.Type[EventNotification]] = { {{- range .Events }} {{ printf "%q" .EventType }}: {{ .ClassName }}, {{- end }} diff --git a/sumup/_events.py b/sumup/_events.py index bb9264ff..6eebbedf 100644 --- a/sumup/_events.py +++ b/sumup/_events.py @@ -9,12 +9,13 @@ import re import time from collections.abc import Awaitable, Callable -from typing import Annotated, ClassVar, Generic, TypeVar, cast +from typing import ClassVar, Generic, TypeVar, cast import httpx import pydantic from ._exceptions import APIError, SumupError, _wrap_request_errors +from .types import EventObject, EventObjectType, EventType, WebhooksEvent SIGNATURE_HEADER = "X-SumUp-Webhook-Signature" """Header containing the signing timestamp and signature. Pass its complete value.""" @@ -25,7 +26,6 @@ Read the body before JSON middleware. Parsing and reserializing can change the signed bytes and cause verification to fail. """ -_NonemptyString = Annotated[str, pydantic.Field(strict=True, min_length=1)] _ObjectT = TypeVar("_ObjectT", bound=pydantic.BaseModel) @@ -68,21 +68,7 @@ class EventObjectUrlError(EventError): """ -class EventObject(pydantic.BaseModel): - """Reference to the resource associated with an event. - - Attributes: - id: Identifier of the referenced resource. - type: Resource type, such as "member" or "reader". - url: API URL used by the event's fetch_object() or fetch_object_async(). - """ - - id: _NonemptyString - type: _NonemptyString - url: _NonemptyString - - -class EventNotification(pydantic.BaseModel): +class EventNotification(WebhooksEvent): """Metadata shared by known events and UnknownEvent. Notifications contain a resource reference. Known event classes provide @@ -96,13 +82,12 @@ class EventNotification(pydantic.BaseModel): object: Reference to the associated API resource. """ - id: _NonemptyString - type: _NonemptyString = pydantic.Field(frozen=True) + # Pydantic freezes the inherited discriminator at runtime. + type: EventType = pydantic.Field(frozen=True) # ty: ignore[invalid-mutable-override] created_at: pydantic.AwareDatetime - object: EventObject _client: httpx.Client | httpx.AsyncClient | None = pydantic.PrivateAttr(default=None) - _object_type: ClassVar[str | None] = None + _object_type: ClassVar[EventObjectType | None] = None @pydantic.field_validator("object") @classmethod @@ -123,7 +108,7 @@ class UnknownEvent(EventNotification): class FetchableEvent(EventNotification, Generic[_ObjectT]): """Base for known events with typed resource fetching.""" - EVENT_TYPE: ClassVar[str] + EVENT_TYPE: ClassVar[EventType] _response_model: ClassVar[type[pydantic.BaseModel]] def _parse_response(self, response: httpx.Response) -> _ObjectT: @@ -215,9 +200,9 @@ def __init__( self._secret = secret self._fallback = fallback self._client = client - self._callbacks: dict[str, _ErasedCallback] = {} + self._callbacks: dict[EventType, _ErasedCallback] = {} - def _register(self, event_type: str, callback: _ErasedCallback) -> None: + def _register(self, event_type: EventType, callback: _ErasedCallback) -> None: if not callable(callback): raise EventHandlerRegistrationError("an event callback is required") if event_type in self._callbacks: diff --git a/sumup/events.py b/sumup/events.py index 8c3e09a3..ec4b7669 100644 --- a/sumup/events.py +++ b/sumup/events.py @@ -30,6 +30,8 @@ ) from .types import ( Checkout, + EventObjectType, + EventType, Member, Reader, Role, @@ -45,11 +47,11 @@ class CheckoutCreatedEvent(FetchableEvent[Checkout]): Checkout. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "checkouts.created" + EVENT_TYPE: typing.ClassVar[EventType] = "checkouts.created" type: typing.Literal["checkouts.created"] = pydantic.Field( default="checkouts.created", frozen=True ) - _object_type: typing.ClassVar[str | None] = "checkout" + _object_type: typing.ClassVar[EventObjectType | None] = "checkout" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Checkout @@ -61,11 +63,11 @@ class CheckoutExpiredEvent(FetchableEvent[Checkout]): Checkout. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "checkouts.expired" + EVENT_TYPE: typing.ClassVar[EventType] = "checkouts.expired" type: typing.Literal["checkouts.expired"] = pydantic.Field( default="checkouts.expired", frozen=True ) - _object_type: typing.ClassVar[str | None] = "checkout" + _object_type: typing.ClassVar[EventObjectType | None] = "checkout" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Checkout @@ -77,11 +79,11 @@ class CheckoutFailedEvent(FetchableEvent[Checkout]): Checkout. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "checkouts.failed" + EVENT_TYPE: typing.ClassVar[EventType] = "checkouts.failed" type: typing.Literal["checkouts.failed"] = pydantic.Field( default="checkouts.failed", frozen=True ) - _object_type: typing.ClassVar[str | None] = "checkout" + _object_type: typing.ClassVar[EventObjectType | None] = "checkout" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Checkout @@ -93,9 +95,9 @@ class CheckoutPaidEvent(FetchableEvent[Checkout]): Checkout. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "checkouts.paid" + EVENT_TYPE: typing.ClassVar[EventType] = "checkouts.paid" type: typing.Literal["checkouts.paid"] = pydantic.Field(default="checkouts.paid", frozen=True) - _object_type: typing.ClassVar[str | None] = "checkout" + _object_type: typing.ClassVar[EventObjectType | None] = "checkout" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Checkout @@ -107,11 +109,11 @@ class CheckoutUpdatedEvent(FetchableEvent[Checkout]): Checkout. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "checkouts.updated" + EVENT_TYPE: typing.ClassVar[EventType] = "checkouts.updated" type: typing.Literal["checkouts.updated"] = pydantic.Field( default="checkouts.updated", frozen=True ) - _object_type: typing.ClassVar[str | None] = "checkout" + _object_type: typing.ClassVar[EventObjectType | None] = "checkout" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Checkout @@ -123,9 +125,9 @@ class MemberCreatedEvent(FetchableEvent[Member]): Member. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "members.created" + EVENT_TYPE: typing.ClassVar[EventType] = "members.created" type: typing.Literal["members.created"] = pydantic.Field(default="members.created", frozen=True) - _object_type: typing.ClassVar[str | None] = "member" + _object_type: typing.ClassVar[EventObjectType | None] = "member" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Member @@ -137,9 +139,9 @@ class MemberDeletedEvent(FetchableEvent[Member]): Member. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "members.deleted" + EVENT_TYPE: typing.ClassVar[EventType] = "members.deleted" type: typing.Literal["members.deleted"] = pydantic.Field(default="members.deleted", frozen=True) - _object_type: typing.ClassVar[str | None] = "member" + _object_type: typing.ClassVar[EventObjectType | None] = "member" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Member @@ -151,9 +153,9 @@ class MemberUpdatedEvent(FetchableEvent[Member]): Member. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "members.updated" + EVENT_TYPE: typing.ClassVar[EventType] = "members.updated" type: typing.Literal["members.updated"] = pydantic.Field(default="members.updated", frozen=True) - _object_type: typing.ClassVar[str | None] = "member" + _object_type: typing.ClassVar[EventObjectType | None] = "member" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Member @@ -165,9 +167,9 @@ class ReaderCreatedEvent(FetchableEvent[Reader]): Reader. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "readers.created" + EVENT_TYPE: typing.ClassVar[EventType] = "readers.created" type: typing.Literal["readers.created"] = pydantic.Field(default="readers.created", frozen=True) - _object_type: typing.ClassVar[str | None] = "reader" + _object_type: typing.ClassVar[EventObjectType | None] = "reader" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Reader @@ -179,9 +181,9 @@ class ReaderDeletedEvent(FetchableEvent[Reader]): Reader. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "readers.deleted" + EVENT_TYPE: typing.ClassVar[EventType] = "readers.deleted" type: typing.Literal["readers.deleted"] = pydantic.Field(default="readers.deleted", frozen=True) - _object_type: typing.ClassVar[str | None] = "reader" + _object_type: typing.ClassVar[EventObjectType | None] = "reader" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Reader @@ -193,9 +195,9 @@ class RoleCreatedEvent(FetchableEvent[Role]): Role. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "roles.created" + EVENT_TYPE: typing.ClassVar[EventType] = "roles.created" type: typing.Literal["roles.created"] = pydantic.Field(default="roles.created", frozen=True) - _object_type: typing.ClassVar[str | None] = "role" + _object_type: typing.ClassVar[EventObjectType | None] = "role" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Role @@ -207,9 +209,9 @@ class RoleDeletedEvent(FetchableEvent[Role]): Role. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "roles.deleted" + EVENT_TYPE: typing.ClassVar[EventType] = "roles.deleted" type: typing.Literal["roles.deleted"] = pydantic.Field(default="roles.deleted", frozen=True) - _object_type: typing.ClassVar[str | None] = "role" + _object_type: typing.ClassVar[EventObjectType | None] = "role" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Role @@ -221,9 +223,9 @@ class RoleUpdatedEvent(FetchableEvent[Role]): Role. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "roles.updated" + EVENT_TYPE: typing.ClassVar[EventType] = "roles.updated" type: typing.Literal["roles.updated"] = pydantic.Field(default="roles.updated", frozen=True) - _object_type: typing.ClassVar[str | None] = "role" + _object_type: typing.ClassVar[EventObjectType | None] = "role" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Role @@ -235,9 +237,9 @@ class SaleCompletedEvent(FetchableEvent[Sale]): Sale. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "sales.completed" + EVENT_TYPE: typing.ClassVar[EventType] = "sales.completed" type: typing.Literal["sales.completed"] = pydantic.Field(default="sales.completed", frozen=True) - _object_type: typing.ClassVar[str | None] = "sale" + _object_type: typing.ClassVar[EventObjectType | None] = "sale" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Sale @@ -249,9 +251,9 @@ class SaleUpdatedEvent(FetchableEvent[Sale]): Sale. The notification itself contains a resource reference. """ - EVENT_TYPE: typing.ClassVar[str] = "sales.updated" + EVENT_TYPE: typing.ClassVar[EventType] = "sales.updated" type: typing.Literal["sales.updated"] = pydantic.Field(default="sales.updated", frozen=True) - _object_type: typing.ClassVar[str | None] = "sale" + _object_type: typing.ClassVar[EventObjectType | None] = "sale" _response_model: typing.ClassVar[builtins.type[pydantic.BaseModel]] = Sale @@ -274,7 +276,7 @@ class SaleUpdatedEvent(FetchableEvent[Sale]): ) -_EVENT_MODELS: dict[str, type[EventNotification]] = { +_EVENT_MODELS: dict[EventType, type[EventNotification]] = { "checkouts.created": CheckoutCreatedEvent, "checkouts.expired": CheckoutExpiredEvent, "checkouts.failed": CheckoutFailedEvent, diff --git a/tests/test_events.py b/tests/test_events.py index 330d3763..02228b18 100644 --- a/tests/test_events.py +++ b/tests/test_events.py @@ -12,6 +12,7 @@ EventCallbackError, EventHandlerRegistrationError, EventNotification, + EventObject, EventObjectUrlError, EventPayloadError, EventSignatureError, @@ -25,7 +26,8 @@ UnknownEvent, verify_event_signature, ) -from sumup.types import Problem, Reader +from sumup.types import EventObject as GeneratedEventObject +from sumup.types import Problem, Reader, WebhooksEvent _NOW = 1788696000 _SECRET = "event_secret_test" @@ -118,6 +120,22 @@ def test_known_event_type_default_and_validation(): assert raised.value.errors()[0]["type"] == "literal_error" +def test_event_models_extend_generated_schemas(sdk): + event = sdk.parse_event_notification_without_verification(_body()) + assert isinstance(event, WebhooksEvent) + assert EventObject is GeneratedEventObject + assert isinstance(event.object, GeneratedEventObject) + assert WebhooksEvent.model_validate(event.model_dump()).model_dump() == event.model_dump() + + +def test_unknown_event_preserves_future_object_types(sdk): + payload = json.loads(_body("future.event")) + payload["object"]["type"] = "future_resource" + event = sdk.parse_event_notification_without_verification(json.dumps(payload)) + assert isinstance(event, UnknownEvent) + assert event.object.type == "future_resource" + + @pytest.mark.parametrize( "body", [b'{ "name": "caf\xc3\xa9" }\n', bytearray(b"body"), memoryview(b"body"), "café"] ) @@ -198,13 +216,11 @@ def test_parse_rejects_invalid_payload(sdk, body): @pytest.mark.parametrize( "field,value", [ - ("id", ""), ("type", []), ("created_at", "2026-04-11"), ("created_at", "2026-04-11T10:00:00"), ("created_at", "2026-02-30T10:00:00Z"), ("object", None), - ("object.id", ""), ("object.type", "member"), ("object.url", 123), ],