Coverage for src/lexigram/notification/hooks.py: 100%

1"""Root hook payload surface for lexigram-notification. 

2 

3Defines canonical payload dataclasses for notification delivery hook points. 

4Actual hook registration and invocation use the framework's string-keyed 

5``HookRegistryProtocol`` action/filter APIs. 

6""" 

7 

8from __future__ import annotations 

9 

10from dataclasses import dataclass 

11 

12__all__ = [ 

13 "EmailDispatchedHook", 

14 "EmailRenderedHook", 

15 "InboxMessageCreatedHook", 

16 "InboxMessageReadHook", 

17 "NotificationFailedHook", 

18 "NotificationSentHook", 

19] 

20 

21 

22# === Existing Notification Hooks === 

23 

24 

25@dataclass(frozen=True, kw_only=True) 

26class NotificationSentHook: 

27 """Payload fired when a notification is successfully dispatched. 

28 

29 Attributes: 

30 channel: Delivery channel used (e.g. ``"email"``, ``"sms"``, ``"push"``). 

31 recipient_id: Identifier of the notification recipient. 

32 """ 

33 

34 channel: str 

35 recipient_id: str 

36 

37 

38@dataclass(frozen=True, kw_only=True) 

39class NotificationFailedHook: 

40 """Payload fired when a notification dispatch attempt fails. 

41 

42 Attributes: 

43 channel: Delivery channel that failed. 

44 recipient_id: Identifier of the intended recipient. 

45 reason: Short description of the failure. 

46 """ 

47 

48 channel: str 

49 recipient_id: str 

50 reason: str 

51 

52 

53# === Mail Hooks (merged from mail/hooks.py) === 

54 

55 

56@dataclass(frozen=True) 

57class EmailDispatchedHook: 

58 """Payload fired when an email is dispatched to the sending provider. 

59 

60 Attributes: 

61 recipient: Email address of the recipient. 

62 message_id: Provider-assigned message identifier. 

63 backend: Name of the sending backend (e.g., "sendgrid", "ses"). 

64 """ 

65 

66 recipient: str 

67 message_id: str 

68 backend: str 

69 

70 

71@dataclass(frozen=True) 

72class EmailRenderedHook: 

73 """Payload fired when an email template is rendered. 

74 

75 Attributes: 

76 template_name: Name of the template used. 

77 recipient: Target recipient email address. 

78 """ 

79 

80 template_name: str 

81 recipient: str 

82 

83 

84# === Inbox Hooks (merged from inbox/hooks.py) === 

85 

86 

87@dataclass(frozen=True) 

88class InboxMessageCreatedHook: 

89 """Payload fired when a new message is added to a user's inbox. 

90 

91 Attributes: 

92 message_id: Unique identifier of the inbox message. 

93 user_id: Identifier of the recipient user. 

94 """ 

95 

96 message_id: str 

97 user_id: str 

98 

99 

100@dataclass(frozen=True) 

101class InboxMessageReadHook: 

102 """Payload fired when a user opens an inbox message. 

103 

104 Attributes: 

105 message_id: Unique identifier of the inbox message. 

106 user_id: Identifier of the user who read the message. 

107 """ 

108 

109 message_id: str 

110 user_id: str