neuronos-capabilities-lib 0.0.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. neuronos_capabilities/AuthManager/__init__.py +42 -0
  2. neuronos_capabilities/AuthManager/adapters/__init__.py +3 -0
  3. neuronos_capabilities/AuthManager/adapters/clerk_adapter.py +87 -0
  4. neuronos_capabilities/AuthManager/auth_manager.py +237 -0
  5. neuronos_capabilities/AuthManager/config/__init__.py +3 -0
  6. neuronos_capabilities/AuthManager/config/auth_config.py +106 -0
  7. neuronos_capabilities/AuthManager/examples/usage.py +56 -0
  8. neuronos_capabilities/AuthManager/exceptions/__init__.py +13 -0
  9. neuronos_capabilities/AuthManager/exceptions/auth_exceptions.py +23 -0
  10. neuronos_capabilities/AuthManager/ports/__init__.py +3 -0
  11. neuronos_capabilities/AuthManager/ports/auth_port.py +92 -0
  12. neuronos_capabilities/AuthManager/tests/__init__.py +1 -0
  13. neuronos_capabilities/AuthManager/tests/test_clock_skew.py +178 -0
  14. neuronos_capabilities/NotificationsManager/README.md +75 -0
  15. neuronos_capabilities/NotificationsManager/__init__.py +37 -0
  16. neuronos_capabilities/NotificationsManager/adapters/__init__.py +7 -0
  17. neuronos_capabilities/NotificationsManager/adapters/aws.py +146 -0
  18. neuronos_capabilities/NotificationsManager/adapters/console.py +30 -0
  19. neuronos_capabilities/NotificationsManager/adapters/memory.py +143 -0
  20. neuronos_capabilities/NotificationsManager/adapters/postgres.py +214 -0
  21. neuronos_capabilities/NotificationsManager/adapters/templates.py +73 -0
  22. neuronos_capabilities/NotificationsManager/artifact.yaml +64 -0
  23. neuronos_capabilities/NotificationsManager/config/__init__.py +3 -0
  24. neuronos_capabilities/NotificationsManager/config/notifications_config.py +123 -0
  25. neuronos_capabilities/NotificationsManager/entrypoints/__init__.py +1 -0
  26. neuronos_capabilities/NotificationsManager/entrypoints/events.py +36 -0
  27. neuronos_capabilities/NotificationsManager/entrypoints/sender.py +22 -0
  28. neuronos_capabilities/NotificationsManager/exceptions/__init__.py +19 -0
  29. neuronos_capabilities/NotificationsManager/exceptions/notifications_exceptions.py +41 -0
  30. neuronos_capabilities/NotificationsManager/models.py +88 -0
  31. neuronos_capabilities/NotificationsManager/notifications_manager.py +605 -0
  32. neuronos_capabilities/NotificationsManager/ports/__init__.py +110 -0
  33. neuronos_capabilities/NotificationsManager/tests/__init__.py +0 -0
  34. neuronos_capabilities/NotificationsManager/tests/test_aws_adapters.py +93 -0
  35. neuronos_capabilities/NotificationsManager/tests/test_notifications_manager.py +198 -0
  36. neuronos_capabilities/S3Manager/__init__.py +55 -0
  37. neuronos_capabilities/S3Manager/adapters/__init__.py +3 -0
  38. neuronos_capabilities/S3Manager/adapters/aws_adapter.py +400 -0
  39. neuronos_capabilities/S3Manager/artifact.yaml +52 -0
  40. neuronos_capabilities/S3Manager/config/__init__.py +3 -0
  41. neuronos_capabilities/S3Manager/config/s3_config.py +91 -0
  42. neuronos_capabilities/S3Manager/examples/usage.py +86 -0
  43. neuronos_capabilities/S3Manager/exceptions/__init__.py +21 -0
  44. neuronos_capabilities/S3Manager/exceptions/s3_exceptions.py +43 -0
  45. neuronos_capabilities/S3Manager/ports/__init__.py +3 -0
  46. neuronos_capabilities/S3Manager/ports/s3_port.py +499 -0
  47. neuronos_capabilities/S3Manager/s3_manager.py +332 -0
  48. neuronos_capabilities/S3Manager/tests/__init__.py +1 -0
  49. neuronos_capabilities/SQLManager/__init__.py +53 -0
  50. neuronos_capabilities/SQLManager/adapters/__init__.py +0 -0
  51. neuronos_capabilities/SQLManager/adapters/postgres_adapter.py +893 -0
  52. neuronos_capabilities/SQLManager/artifact.yaml +52 -0
  53. neuronos_capabilities/SQLManager/config/__init__.py +0 -0
  54. neuronos_capabilities/SQLManager/config/sql_config.py +175 -0
  55. neuronos_capabilities/SQLManager/examples/testing_library_execution.py +167 -0
  56. neuronos_capabilities/SQLManager/exceptions/__init__.py +0 -0
  57. neuronos_capabilities/SQLManager/exceptions/sql_exceptions.py +117 -0
  58. neuronos_capabilities/SQLManager/migrations/__init__.py +0 -0
  59. neuronos_capabilities/SQLManager/migrations/alembic_manager.py +617 -0
  60. neuronos_capabilities/SQLManager/models/__init__.py +9 -0
  61. neuronos_capabilities/SQLManager/models/base.py +118 -0
  62. neuronos_capabilities/SQLManager/ports/__init__.py +0 -0
  63. neuronos_capabilities/SQLManager/ports/sql_port.py +940 -0
  64. neuronos_capabilities/SQLManager/sql_manager.py +495 -0
  65. neuronos_capabilities/SQLManager/tests/__init__.py +0 -0
  66. neuronos_capabilities/SQLManager/utils/__init__.py +0 -0
  67. neuronos_capabilities/SQLManager/utils/query_builder.py +238 -0
  68. neuronos_capabilities/SQLManager/utils/singleton.py +120 -0
  69. neuronos_capabilities/__init__.py +58 -0
  70. neuronos_capabilities/__version__.py +2 -0
  71. neuronos_capabilities_lib-0.0.2.dist-info/LICENSE +21 -0
  72. neuronos_capabilities_lib-0.0.2.dist-info/METADATA +152 -0
  73. neuronos_capabilities_lib-0.0.2.dist-info/RECORD +75 -0
  74. neuronos_capabilities_lib-0.0.2.dist-info/WHEEL +5 -0
  75. neuronos_capabilities_lib-0.0.2.dist-info/top_level.txt +1 -0
@@ -0,0 +1,178 @@
1
+ """Clock-skew tolerance on JWT verification (ClerkAdapter + AuthConfig).
2
+
3
+ The bug these pin: `_decode_token` called `jwt.decode` with no `leeway`, so PyJWT
4
+ rejected any token whose `iat` was even one second ahead of the host clock —
5
+
6
+ ImmatureSignatureError: The token is not yet valid (iat)
7
+ (PyJWT api_jwt.py: `if iat > (now + leeway)`)
8
+
9
+ The provider stamps `iat` with its own clock, so a host running slightly behind
10
+ failed EVERY request, and a client could not compensate: re-minting a token
11
+ produces a later `iat` still.
12
+
13
+ The leeway must not become a way around verification, so these tests also assert
14
+ that a foreign signature, a genuinely expired token and a wrong issuer are all
15
+ still rejected.
16
+ """
17
+
18
+ import time
19
+
20
+ import jwt
21
+ import pytest
22
+ from cryptography.hazmat.primitives.asymmetric import rsa
23
+
24
+ from neuronos_capabilities.AuthManager.adapters.clerk_adapter import ClerkAdapter
25
+ from neuronos_capabilities.AuthManager.config.auth_config import AuthConfig
26
+ from neuronos_capabilities.AuthManager.exceptions.auth_exceptions import (
27
+ ConfigurationError,
28
+ TokenError,
29
+ )
30
+
31
+ JWKS_URL = "https://example.clerk.accounts.dev/.well-known/jwks.json"
32
+
33
+
34
+ def _rsa_key():
35
+ return rsa.generate_private_key(public_exponent=65537, key_size=2048)
36
+
37
+
38
+ def _token(private_key, **overrides):
39
+ now = int(time.time())
40
+ claims = {"sub": "user_123", "org_id": "org_123", "iat": now, "exp": now + 60}
41
+ claims.update(overrides)
42
+ return jwt.encode(claims, private_key, algorithm="RS256")
43
+
44
+
45
+ def _adapter(private_key, **config_kwargs):
46
+ """A ClerkAdapter whose JWKS resolves to `private_key`'s public key."""
47
+ adapter = ClerkAdapter(AuthConfig(jwks_url=JWKS_URL, **config_kwargs))
48
+ public_key = private_key.public_key()
49
+
50
+ class _FakeJWKSClient:
51
+ def get_signing_key_from_jwt(self, token):
52
+ class _SigningKey:
53
+ key = public_key
54
+
55
+ return _SigningKey()
56
+
57
+ adapter._jwks_client = _FakeJWKSClient()
58
+ return adapter
59
+
60
+
61
+ # ─── config ─────────────────────────────────────────────────────────────────
62
+
63
+ def test_default_leeway_is_thirty_seconds():
64
+ assert AuthConfig(jwks_url=JWKS_URL).leeway_seconds == 30
65
+
66
+
67
+ def test_leeway_reads_env_var(monkeypatch):
68
+ monkeypatch.setenv("NEURONOS_AUTH_LEEWAY_SECONDS", "90")
69
+ assert AuthConfig(jwks_url=JWKS_URL).leeway_seconds == 90
70
+
71
+
72
+ def test_explicit_zero_wins_over_env(monkeypatch):
73
+ """Asking for strict clocks must not be silently overridden by the env."""
74
+ monkeypatch.setenv("NEURONOS_AUTH_LEEWAY_SECONDS", "90")
75
+ assert AuthConfig(jwks_url=JWKS_URL, leeway_seconds=0).leeway_seconds == 0
76
+
77
+
78
+ def test_non_integer_env_var_is_a_configuration_error(monkeypatch):
79
+ monkeypatch.setenv("NEURONOS_AUTH_LEEWAY_SECONDS", "a-while")
80
+ with pytest.raises(ConfigurationError):
81
+ AuthConfig(jwks_url=JWKS_URL)
82
+
83
+
84
+ def test_negative_leeway_is_a_configuration_error():
85
+ with pytest.raises(ConfigurationError):
86
+ AuthConfig(jwks_url=JWKS_URL, leeway_seconds=-1)
87
+
88
+
89
+ def test_leeway_is_serialized():
90
+ assert AuthConfig(jwks_url=JWKS_URL, leeway_seconds=15).to_dict()[
91
+ "leeway_seconds"
92
+ ] == 15
93
+
94
+
95
+ # ─── the bug ────────────────────────────────────────────────────────────────
96
+
97
+ def test_token_issued_one_second_in_the_future_is_accepted():
98
+ """The exact production failure: host clock 1s behind the issuer."""
99
+ key = _rsa_key()
100
+ adapter = _adapter(key)
101
+ token = _token(key, iat=int(time.time()) + 1)
102
+
103
+ assert adapter.verify_token(token)["sub"] == "user_123"
104
+
105
+
106
+ def test_future_iat_within_leeway_is_accepted():
107
+ key = _rsa_key()
108
+ adapter = _adapter(key, leeway_seconds=30)
109
+ token = _token(key, iat=int(time.time()) + 25)
110
+
111
+ assert adapter.verify_token(token)["sub"] == "user_123"
112
+
113
+
114
+ def test_token_a_second_past_expiry_is_accepted():
115
+ key = _rsa_key()
116
+ adapter = _adapter(key)
117
+ now = int(time.time())
118
+ token = _token(key, iat=now - 61, exp=now - 1)
119
+
120
+ assert adapter.verify_token(token)["sub"] == "user_123"
121
+
122
+
123
+ @pytest.mark.asyncio
124
+ async def test_async_path_shares_the_tolerance():
125
+ key = _rsa_key()
126
+ adapter = _adapter(key)
127
+ token = _token(key, iat=int(time.time()) + 1)
128
+
129
+ payload = await adapter.verify_token_async(token)
130
+ assert payload["sub"] == "user_123"
131
+
132
+
133
+ # ─── the tolerance is bounded, and never bypasses verification ──────────────
134
+
135
+ def test_future_iat_beyond_leeway_is_rejected():
136
+ key = _rsa_key()
137
+ adapter = _adapter(key, leeway_seconds=30)
138
+ token = _token(key, iat=int(time.time()) + 3600)
139
+
140
+ with pytest.raises(TokenError):
141
+ adapter.verify_token(token)
142
+
143
+
144
+ def test_genuinely_expired_token_is_rejected():
145
+ key = _rsa_key()
146
+ adapter = _adapter(key, leeway_seconds=30)
147
+ now = int(time.time())
148
+ token = _token(key, iat=now - 7200, exp=now - 3600)
149
+
150
+ with pytest.raises(TokenError):
151
+ adapter.verify_token(token)
152
+
153
+
154
+ def test_zero_leeway_still_rejects_a_future_iat():
155
+ key = _rsa_key()
156
+ adapter = _adapter(key, leeway_seconds=0)
157
+ token = _token(key, iat=int(time.time()) + 5)
158
+
159
+ with pytest.raises(TokenError):
160
+ adapter.verify_token(token)
161
+
162
+
163
+ def test_foreign_signature_is_rejected_regardless_of_leeway():
164
+ """Leeway forgives the clock, never the signature."""
165
+ adapter = _adapter(_rsa_key(), leeway_seconds=300)
166
+ token = _token(_rsa_key(), iat=int(time.time()) + 1) # signed by another key
167
+
168
+ with pytest.raises(TokenError):
169
+ adapter.verify_token(token)
170
+
171
+
172
+ def test_wrong_issuer_is_rejected():
173
+ key = _rsa_key()
174
+ adapter = _adapter(key, issuer="https://expected.example.com")
175
+ token = _token(key, iss="https://attacker.example.com")
176
+
177
+ with pytest.raises(TokenError):
178
+ adapter.verify_token(token)
@@ -0,0 +1,75 @@
1
+ # NotificationsManager
2
+
3
+ In-app notices and email for any NeuronOS project. **One send path** for everything, from an
4
+ invitation to a campaign of 50,000:
5
+
6
+ ```
7
+ API (NotificationsManager.publish) → Postgres (message + bell) → SQS lane (realtime | bulk, FIFO)
8
+ → Lambda sender (outside the VPC) → SES
9
+ SES events → SNS → SQS events → Lambda events (inside the VPC) → Postgres (status, history, suppression)
10
+ Future sends: EventBridge Scheduler drops the built message in the lane at that minute.
11
+ ```
12
+
13
+ - **The API decides and records; it never sends.** Queuing takes ~20 ms; the email arrives in 1–3 s.
14
+ - **The sender is dumb:** it takes a built message and calls SES. No database, no business.
15
+ - **Retries and deduplication are SQS's.** FIFO dedup by message id; a temporary error comes back
16
+ after a backoff (30 s, 2 min, 10 min, 30 min); the 5th failure is recorded as `failed` and moves
17
+ to the DLQ. A permanent error is recorded and not retried.
18
+ - **Two lanes:** `realtime` (invitations, alerts) and `bulk` (newsletters, onboarding), with their
19
+ own queue and concurrency, so a campaign never delays an invitation.
20
+
21
+ ## Use (API)
22
+ ```python
23
+ from neuronos_capabilities.NotificationsManager import Catalog, EventSpec, NotificationsManager, Recipient
24
+
25
+ catalog = Catalog([
26
+ EventSpec("member_invited", "transactional"), # can't be turned off
27
+ EventSpec("usage_alert", "alerts"),
28
+ EventSpec("newsletter", "marketing", channels=("email",), lane="bulk"),
29
+ ])
30
+ nm = NotificationsManager.from_env(catalog, db=sql_manager) # Postgres store on your SQLManager
31
+ nm.create_tables() # schema NOTIF_SCHEMA ("notifications")
32
+
33
+ nm.publish("member_invited", [Recipient("u1", "ana@acme.co", "Ana", "es")],
34
+ {"org": "Acme", "inviter": "Eva", "message": "Welcome!"}, link="https://app/accept")
35
+ nm.schedule("trial_ending", recipients, data, send_at=datetime(2026, 11, 1, 14, tzinfo=timezone.utc))
36
+ nm.cancel(message_id)
37
+
38
+ nm.inbox("u1"); nm.unread_count("u1"); nm.mark_read("u1") # the bell
39
+ nm.preferences("u1"); nm.set_preference("u1", "alerts", "email", False)
40
+ nm.unsubscribe(token) # your public one-click endpoint
41
+ nm.history(message_id) # the message and all its events
42
+ nm.resend(message_id)
43
+ ```
44
+ Every method has an `_async` twin.
45
+
46
+ **Categories** (what a person can turn off): `transactional` (never), `alerts`, `activity`,
47
+ `product`, `marketing`. `product` and `marketing` go with the marketing SES configuration set and
48
+ carry `List-Unsubscribe` one-click.
49
+
50
+ ## Templates
51
+ One Jinja file per event and locale in `NOTIF_TEMPLATE_DIR`: `<event>.<locale>.j2` with blocks
52
+ `title` and `inapp` (the bell), `subject`, `html` and `text` (optional: derived from the HTML). An
53
+ optional `_layout.<locale>.j2` wraps the HTML (`{{ content }}`). A missing locale falls back to
54
+ the default one. Every template gets the data plus `recipient`, `link`, `unsubscribe_url`, and
55
+ `count` (folded notices).
56
+
57
+ ## Message status
58
+ `scheduled → queued → retrying → sent → delivered`, or `failed`, `bounced`, `complained`. Never
59
+ sent: `skipped` (turned off, no address, disabled), `suppressed`, `cancelled`. Late or repeated
60
+ events never move a message back. Each event is kept in `message_events`.
61
+
62
+ ## Lambdas
63
+ Build both zips (Python 3.12, `x86_64` or `arm64`): `neuronos_capabilities/NotificationsManager/build_lambdas.sh`
64
+
65
+ | Lambda | Handler | Where | Needs |
66
+ |---|---|---|---|
67
+ | `notification-sender` | `…entrypoints.sender.handler` | Outside the VPC | SQS triggers on both lanes (partial batch response), `ses:SendEmail`, `sqs:SendMessage` to events, `sqs:ChangeMessageVisibility` on the lanes |
68
+ | `notification-events` | `…entrypoints.events.handler` | Inside the VPC (reaches Postgres) | SQS trigger on events; `PG_*` env vars |
69
+
70
+ ## Local
71
+ With no queue URLs the manager uses an in-memory queue and the console channel: `publish` runs
72
+ the whole path right away and writes each email as an `.html` file in `NOTIF_CONSOLE_DIR`.
73
+
74
+ ## Configuration
75
+ See `config/notifications_config.py` (`NotificationsConfig.from_env`) for every variable.
@@ -0,0 +1,37 @@
1
+ """
2
+ NotificationsManager — notifications capability for NeuronOS projects.
3
+
4
+ In-app notices and email (SES) through one send path: API → SQS lane (realtime | bulk) →
5
+ sender Lambda → SES → events (SNS → SQS) → events Lambda → Postgres. Scheduled sends with
6
+ EventBridge Scheduler. Per-person preferences by category, suppression of bounced and
7
+ complaining addresses, one-click unsubscribe.
8
+
9
+ Example:
10
+ from neuronos_capabilities.NotificationsManager import (
11
+ Catalog, EventSpec, NotificationsManager, Recipient)
12
+
13
+ catalog = Catalog([EventSpec("member_invited"), EventSpec("usage_alert", "alerts")])
14
+ nm = NotificationsManager.from_env(catalog, db=sql_manager)
15
+ nm.publish("member_invited", [Recipient("u1", "ana@acme.co", "Ana", "es")], {"org": "Acme"})
16
+ """
17
+
18
+ from .config import CATEGORIES, CHANNELS, LANES, NotificationsConfig
19
+ from .exceptions import (
20
+ ChannelError,
21
+ ConfigurationError,
22
+ NotificationsError,
23
+ PermanentChannelError,
24
+ RetryableChannelError,
25
+ TemplateError,
26
+ UnknownEventError,
27
+ )
28
+ from .models import Catalog, EventSpec, Recipient, Rendered
29
+ from .notifications_manager import NotificationsManager
30
+
31
+ __all__ = [
32
+ "CATEGORIES", "CHANNELS", "LANES", "Catalog", "ChannelError", "ConfigurationError", "EventSpec",
33
+ "NotificationsConfig", "NotificationsError", "NotificationsManager", "PermanentChannelError", "Recipient",
34
+ "Rendered", "RetryableChannelError", "TemplateError", "UnknownEventError",
35
+ ]
36
+
37
+ __version__ = "1.0.0"
@@ -0,0 +1,7 @@
1
+ """Adapters. The memory and console ones load with no extra dependency; AWS (``aws``),
2
+ Postgres (``postgres``) and Jinja (``templates``) are imported from their modules when used."""
3
+
4
+ from .console import ConsoleChannel
5
+ from .memory import MemoryQueue, MemoryScheduler, MemoryStore
6
+
7
+ __all__ = ["ConsoleChannel", "MemoryQueue", "MemoryScheduler", "MemoryStore"]
@@ -0,0 +1,146 @@
1
+ """AWS adapters: SES (email), SQS (lanes and events) and EventBridge Scheduler (future sends).
2
+ boto3 clients can be injected (tests, custom sessions)."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import hashlib
7
+ import json
8
+ from typing import Any, Dict, Optional
9
+
10
+ from ..config import NotificationsConfig
11
+ from ..exceptions import ConfigurationError, PermanentChannelError, RetryableChannelError
12
+ from ..ports import ChannelPort, QueuePort, SchedulerPort
13
+
14
+ #: SES errors where trying again later can work. Anything else from SES is permanent.
15
+ RETRYABLE_SES = {"Throttling", "ThrottlingException", "TooManyRequestsException", "LimitExceededException",
16
+ "SendingPausedException", "ServiceUnavailable", "InternalFailure", "InternalServiceError",
17
+ "RequestTimeout", "AccountSuspendedException"}
18
+
19
+
20
+ def _client(service: str, config: NotificationsConfig, client=None):
21
+ if client is not None:
22
+ return client
23
+ import boto3
24
+
25
+ return boto3.client(service, region_name=config.region) if config.region else boto3.client(service)
26
+
27
+
28
+ def _tag(v: Optional[str]) -> str:
29
+ # SES tag values: letters, digits, _ - and . only
30
+ return "".join(ch if ch.isalnum() or ch in "_-." else "_" for ch in str(v or "none"))[:256] or "none"
31
+
32
+
33
+ def queue_arn(url: str) -> str:
34
+ """https://sqs.us-east-1.amazonaws.com/123456789012/name → arn:aws:sqs:us-east-1:123456789012:name"""
35
+ try:
36
+ host, account, name = url.split("://", 1)[1].split("/")[:3]
37
+ region = host.split(".")[1]
38
+ except (IndexError, ValueError):
39
+ raise ConfigurationError(f"Not an SQS queue URL: {url}") from None
40
+ return f"arn:aws:sqs:{region}:{account}:{name}"
41
+
42
+
43
+ def group_of(key: str, groups: int = 64) -> str:
44
+ """FIFO message group: one person's messages keep their order, different people go in parallel."""
45
+ return f"g{int(hashlib.sha1(key.encode()).hexdigest(), 16) % groups}"
46
+
47
+
48
+ class SESChannel(ChannelPort):
49
+ def __init__(self, config: NotificationsConfig, client=None):
50
+ self.config = config
51
+ self.client = _client("sesv2", config, client)
52
+
53
+ def send(self, message: Dict[str, Any]) -> Dict[str, Any]:
54
+ from botocore.exceptions import BotoCoreError, ClientError
55
+
56
+ simple: Dict[str, Any] = {
57
+ "Subject": {"Data": message.get("subject") or "", "Charset": "UTF-8"},
58
+ "Body": {"Html": {"Data": message.get("html") or "", "Charset": "UTF-8"},
59
+ "Text": {"Data": message.get("text") or "", "Charset": "UTF-8"}},
60
+ }
61
+ headers = [{"Name": k, "Value": v} for k, v in (message.get("headers") or {}).items()]
62
+ if headers:
63
+ simple["Headers"] = headers
64
+ req: Dict[str, Any] = {
65
+ "FromEmailAddress": message.get("from") or self.config.email_from,
66
+ "Destination": {"ToAddresses": [message["to"]]},
67
+ "Content": {"Simple": simple},
68
+ # the tag is how SES's events find our row again (events Lambda)
69
+ "EmailTags": [{"Name": "message_id", "Value": _tag(message.get("id"))},
70
+ {"Name": "event", "Value": _tag(message.get("event"))},
71
+ {"Name": "category", "Value": _tag(message.get("category"))}],
72
+ }
73
+ if message.get("reply_to") or self.config.email_reply_to:
74
+ req["ReplyToAddresses"] = [message.get("reply_to") or self.config.email_reply_to]
75
+ if message.get("configuration_set"):
76
+ req["ConfigurationSetName"] = message["configuration_set"]
77
+ try:
78
+ out = self.client.send_email(**req)
79
+ except ClientError as exc:
80
+ err = exc.response.get("Error", {})
81
+ code, msg = err.get("Code", ""), err.get("Message", str(exc))
82
+ if code in RETRYABLE_SES or exc.response.get("ResponseMetadata", {}).get("HTTPStatusCode", 0) >= 500:
83
+ raise RetryableChannelError(msg, code=code) from exc
84
+ raise PermanentChannelError(msg, code=code) from exc
85
+ except BotoCoreError as exc: # network, endpoint, credentials
86
+ raise RetryableChannelError(str(exc), code=type(exc).__name__) from exc
87
+ return {"provider_id": out.get("MessageId")}
88
+
89
+
90
+ class SQSQueue(QueuePort):
91
+ def __init__(self, config: NotificationsConfig, client=None):
92
+ self.config = config
93
+ self.client = _client("sqs", config, client)
94
+
95
+ def url(self, queue: str) -> str:
96
+ url = self.config.queue_urls.get(queue)
97
+ if not url:
98
+ raise ConfigurationError(f"No queue URL for {queue}")
99
+ return url
100
+
101
+ def send(self, queue, body, *, group_id=None, dedup_id=None):
102
+ url = self.url(queue)
103
+ req: Dict[str, Any] = {"QueueUrl": url, "MessageBody": json.dumps(body, default=str)}
104
+ if url.endswith(".fifo"):
105
+ req["MessageGroupId"] = group_id or "default"
106
+ if dedup_id:
107
+ req["MessageDeduplicationId"] = dedup_id[:128]
108
+ self.client.send_message(**req)
109
+
110
+ def retry_later(self, source_arn, receipt, delay_s):
111
+ # arn:aws:sqs:region:account:name → its URL
112
+ _, _, _, region, account, name = source_arn.split(":", 5)
113
+ url = next((u for u in self.config.queue_urls.values() if u.rstrip("/").endswith(f"/{account}/{name}")),
114
+ f"https://sqs.{region}.amazonaws.com/{account}/{name}")
115
+ self.client.change_message_visibility(QueueUrl=url, ReceiptHandle=receipt,
116
+ VisibilityTimeout=max(0, min(43200, int(delay_s))))
117
+
118
+
119
+ class EventBridgeScheduler(SchedulerPort):
120
+ def __init__(self, config: NotificationsConfig, client=None):
121
+ if not config.scheduler_group or not config.scheduler_role_arn:
122
+ raise ConfigurationError("scheduler_group and scheduler_role_arn are required for eventbridge")
123
+ self.config = config
124
+ self.client = _client("scheduler", config, client)
125
+
126
+ def create(self, name, at, queue, body, *, group_id):
127
+ url = self.config.queue_urls.get(queue)
128
+ if not url:
129
+ raise ConfigurationError(f"No queue URL for {queue}")
130
+ target: Dict[str, Any] = {"Arn": queue_arn(url), "RoleArn": self.config.scheduler_role_arn,
131
+ "Input": json.dumps(body, default=str)}
132
+ if url.endswith(".fifo"):
133
+ target["SqsParameters"] = {"MessageGroupId": group_id} # dedup: content-based on the queue
134
+ self.client.create_schedule(Name=name[:64], GroupName=self.config.scheduler_group,
135
+ ScheduleExpression=f"at({at.strftime('%Y-%m-%dT%H:%M:%S')})",
136
+ ScheduleExpressionTimezone="UTC", FlexibleTimeWindow={"Mode": "OFF"},
137
+ Target=target, ActionAfterCompletion="DELETE")
138
+
139
+ def delete(self, name):
140
+ try:
141
+ self.client.delete_schedule(Name=name[:64], GroupName=self.config.scheduler_group)
142
+ return True
143
+ except Exception as exc: # already fired or gone
144
+ if "ResourceNotFound" in type(exc).__name__ or "ResourceNotFound" in str(exc):
145
+ return False
146
+ raise
@@ -0,0 +1,30 @@
1
+ """Local email channel: writes each message as an .html file you can open, and logs it."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import logging
7
+ import os
8
+ import re
9
+ import time
10
+ import uuid
11
+
12
+ from ..ports import ChannelPort
13
+
14
+ logger = logging.getLogger("notifications")
15
+
16
+
17
+ class ConsoleChannel(ChannelPort):
18
+ def __init__(self, folder: str):
19
+ self.folder = folder
20
+
21
+ def send(self, message):
22
+ os.makedirs(self.folder, exist_ok=True)
23
+ pid = f"console-{uuid.uuid4().hex[:12]}"
24
+ safe = re.sub(r"[^A-Za-z0-9_.-]+", "_", f"{message.get('event')}-{message.get('to')}")[:120]
25
+ path = os.path.join(self.folder, f"{time.strftime('%Y%m%d-%H%M%S')}-{safe}.html")
26
+ meta = {k: message.get(k) for k in ("id", "to", "from", "subject", "event", "category", "headers")}
27
+ with open(path, "w", encoding="utf-8") as f:
28
+ f.write(f"<!-- {json.dumps(meta, default=str)} -->\n{message.get('html') or message.get('text') or ''}")
29
+ logger.info("notification %s → %s: %s", message.get("event"), message.get("to"), path)
30
+ return {"provider_id": pid, "path": path, "local": True}
@@ -0,0 +1,143 @@
1
+ """In-memory queue, scheduler and store: tests and local runs without AWS or a database."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ import threading
7
+ import uuid
8
+ from datetime import datetime
9
+ from typing import Any, Dict, List, Optional
10
+
11
+ from ..ports import QueuePort, SchedulerPort, StorePort
12
+
13
+
14
+ class MemoryQueue(QueuePort):
15
+ def __init__(self):
16
+ self.messages: Dict[str, List[Dict[str, Any]]] = {}
17
+ self.retries: List[tuple] = []
18
+ self._dedup: set = set()
19
+ self._lock = threading.Lock()
20
+
21
+ def send(self, queue, body, *, group_id=None, dedup_id=None):
22
+ with self._lock:
23
+ if dedup_id and (queue, dedup_id) in self._dedup: # like an SQS FIFO queue
24
+ return
25
+ if dedup_id:
26
+ self._dedup.add((queue, dedup_id))
27
+ self.messages.setdefault(queue, []).append({"body": copy.deepcopy(body), "group_id": group_id,
28
+ "dedup_id": dedup_id})
29
+
30
+ def retry_later(self, source_arn, receipt, delay_s):
31
+ self.retries.append((source_arn, receipt, delay_s))
32
+
33
+ def take(self, queue: str) -> List[Dict[str, Any]]:
34
+ """Test helper: the bodies waiting in a queue (removed)."""
35
+ with self._lock:
36
+ out = [m["body"] for m in self.messages.get(queue, [])]
37
+ self.messages[queue] = []
38
+ return out
39
+
40
+
41
+ class MemoryScheduler(SchedulerPort):
42
+ def __init__(self):
43
+ self.schedules: Dict[str, Dict[str, Any]] = {}
44
+
45
+ def create(self, name, at, queue, body, *, group_id):
46
+ self.schedules[name] = {"at": at, "queue": queue, "body": copy.deepcopy(body), "group_id": group_id}
47
+
48
+ def delete(self, name):
49
+ return self.schedules.pop(name, None) is not None
50
+
51
+ def fire_due(self, now: datetime, queue: QueuePort) -> int:
52
+ """Local/test helper: what EventBridge does at the right minute."""
53
+ due = [n for n, s in self.schedules.items() if s["at"] <= now]
54
+ for n in due:
55
+ s = self.schedules.pop(n)
56
+ queue.send(s["queue"], s["body"], group_id=s["group_id"], dedup_id=s["body"].get("id"))
57
+ return len(due)
58
+
59
+
60
+ class MemoryStore(StorePort):
61
+ def __init__(self):
62
+ self.messages: Dict[str, Dict[str, Any]] = {}
63
+ self.events: Dict[str, Dict[str, Any]] = {}
64
+ self.inbox_items: Dict[str, Dict[str, Any]] = {}
65
+ self.prefs: Dict[tuple, bool] = {}
66
+ self.suppressed: Dict[str, Dict[str, Any]] = {}
67
+ self._lock = threading.RLock()
68
+
69
+ # ── messages ──
70
+ def create_message(self, row):
71
+ with self._lock:
72
+ row = {"id": row.get("id") or str(uuid.uuid4()), "attempts": 0, "provider_id": None, "error": None, **row}
73
+ self.messages[row["id"]] = row
74
+ return dict(row)
75
+
76
+ def get_message(self, message_id):
77
+ r = self.messages.get(message_id)
78
+ return dict(r) if r else None
79
+
80
+ def update_message(self, message_id, **fields):
81
+ with self._lock:
82
+ if message_id in self.messages:
83
+ self.messages[message_id].update(fields)
84
+
85
+ def add_event(self, event):
86
+ with self._lock:
87
+ if event["key"] in self.events:
88
+ return False
89
+ self.events[event["key"]] = dict(event)
90
+ return True
91
+
92
+ def events_of(self, message_id):
93
+ return sorted((dict(e) for e in self.events.values() if e["message_id"] == message_id), key=lambda e: e["at"])
94
+
95
+ def messages_of(self, recipient_id, limit=50):
96
+ rows = [dict(m) for m in self.messages.values() if m["recipient_id"] == recipient_id]
97
+ return sorted(rows, key=lambda m: m["created_at"], reverse=True)[:limit]
98
+
99
+ # ── inbox ──
100
+ def create_inbox(self, item):
101
+ with self._lock:
102
+ item = {"id": str(uuid.uuid4()), "agg_count": 1, "read_at": None, **item}
103
+ self.inbox_items[item["id"]] = item
104
+ return dict(item)
105
+
106
+ def open_inbox_aggregate(self, recipient_id, aggregation_key, since):
107
+ return next((dict(i) for i in self.inbox_items.values()
108
+ if i["recipient_id"] == recipient_id and i.get("aggregation_key") == aggregation_key
109
+ and i["read_at"] is None and i["created_at"] >= since), None)
110
+
111
+ def update_inbox(self, item_id, **fields):
112
+ with self._lock:
113
+ self.inbox_items[item_id].update(fields)
114
+
115
+ def inbox(self, recipient_id, limit=20, before: Optional[datetime] = None):
116
+ items = [i for i in self.inbox_items.values()
117
+ if i["recipient_id"] == recipient_id and (before is None or i["created_at"] < before)]
118
+ return [dict(i) for i in sorted(items, key=lambda i: i["created_at"], reverse=True)[:limit]]
119
+
120
+ def unread_count(self, recipient_id):
121
+ return sum(1 for i in self.inbox_items.values() if i["recipient_id"] == recipient_id and i["read_at"] is None)
122
+
123
+ def mark_read(self, recipient_id, ids, at):
124
+ n = 0
125
+ for i in self.inbox_items.values():
126
+ if i["recipient_id"] == recipient_id and i["read_at"] is None and (ids is None or i["id"] in ids):
127
+ i["read_at"] = at
128
+ n += 1
129
+ return n
130
+
131
+ # ── preferences and suppression ──
132
+ def preferences(self, recipient_id):
133
+ return {key: v for (rid, key), v in self.prefs.items() if rid == recipient_id}
134
+
135
+ def set_preference(self, recipient_id, category, channel, enabled):
136
+ self.prefs[(recipient_id, f"{category}:{channel}")] = bool(enabled)
137
+
138
+ def is_suppressed(self, address):
139
+ return bool(address) and address.lower() in self.suppressed
140
+
141
+ def suppress(self, address, channel, reason):
142
+ if address:
143
+ self.suppressed.setdefault(address.lower(), {"channel": channel, "reason": reason})