stapel-mailtrap 0.1.1__tar.gz

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 (38) hide show
  1. stapel_mailtrap-0.1.1/LICENSE +21 -0
  2. stapel_mailtrap-0.1.1/PKG-INFO +172 -0
  3. stapel_mailtrap-0.1.1/README.md +144 -0
  4. stapel_mailtrap-0.1.1/__init__.py +53 -0
  5. stapel_mailtrap-0.1.1/admin.py +34 -0
  6. stapel_mailtrap-0.1.1/apps.py +16 -0
  7. stapel_mailtrap-0.1.1/checks.py +50 -0
  8. stapel_mailtrap-0.1.1/conf.py +37 -0
  9. stapel_mailtrap-0.1.1/conftest.py +61 -0
  10. stapel_mailtrap-0.1.1/dto.py +55 -0
  11. stapel_mailtrap-0.1.1/errors.py +20 -0
  12. stapel_mailtrap-0.1.1/management/__init__.py +0 -0
  13. stapel_mailtrap-0.1.1/management/commands/__init__.py +0 -0
  14. stapel_mailtrap-0.1.1/management/commands/purge_trapped_emails.py +56 -0
  15. stapel_mailtrap-0.1.1/migrations/0001_initial.py +34 -0
  16. stapel_mailtrap-0.1.1/migrations/__init__.py +0 -0
  17. stapel_mailtrap-0.1.1/models.py +49 -0
  18. stapel_mailtrap-0.1.1/provider.py +63 -0
  19. stapel_mailtrap-0.1.1/py.typed +0 -0
  20. stapel_mailtrap-0.1.1/pyproject.toml +68 -0
  21. stapel_mailtrap-0.1.1/schemas/emits/mailtrap.email.trapped.json +17 -0
  22. stapel_mailtrap-0.1.1/scope.py +36 -0
  23. stapel_mailtrap-0.1.1/serializers.py +19 -0
  24. stapel_mailtrap-0.1.1/services.py +110 -0
  25. stapel_mailtrap-0.1.1/setup.cfg +4 -0
  26. stapel_mailtrap-0.1.1/stapel_mailtrap.egg-info/PKG-INFO +172 -0
  27. stapel_mailtrap-0.1.1/stapel_mailtrap.egg-info/SOURCES.txt +59 -0
  28. stapel_mailtrap-0.1.1/stapel_mailtrap.egg-info/dependency_links.txt +1 -0
  29. stapel_mailtrap-0.1.1/stapel_mailtrap.egg-info/requires.txt +3 -0
  30. stapel_mailtrap-0.1.1/stapel_mailtrap.egg-info/top_level.txt +1 -0
  31. stapel_mailtrap-0.1.1/tasks.py +51 -0
  32. stapel_mailtrap-0.1.1/tests/test_api.py +74 -0
  33. stapel_mailtrap-0.1.1/tests/test_command_and_task.py +56 -0
  34. stapel_mailtrap-0.1.1/tests/test_provider.py +44 -0
  35. stapel_mailtrap-0.1.1/tests/test_seams.py +77 -0
  36. stapel_mailtrap-0.1.1/tests/test_services.py +93 -0
  37. stapel_mailtrap-0.1.1/urls.py +17 -0
  38. stapel_mailtrap-0.1.1/views.py +125 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Stapel contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,172 @@
1
+ Metadata-Version: 2.4
2
+ Name: stapel-mailtrap
3
+ Version: 0.1.1
4
+ Summary: Email trap (mail catcher) for the Stapel framework — capture outbound email in dev/staging
5
+ License: MIT
6
+ Project-URL: Homepage, https://github.com/usestapel/stapel-mailtrap
7
+ Project-URL: Repository, https://github.com/usestapel/stapel-mailtrap
8
+ Project-URL: Documentation, https://github.com/usestapel/stapel-mailtrap#readme
9
+ Project-URL: Changelog, https://github.com/usestapel/stapel-mailtrap/blob/main/CHANGELOG.md
10
+ Project-URL: Issues, https://github.com/usestapel/stapel-mailtrap/issues
11
+ Keywords: django,stapel,email,mailtrap,mailcatcher
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Framework :: Django
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.11
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: stapel-core<0.9,>=0.8
26
+ Provides-Extra: all
27
+ Dynamic: license-file
28
+
29
+ # stapel-mailtrap
30
+
31
+ [![CI](https://github.com/usestapel/stapel-mailtrap/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-mailtrap/actions/workflows/ci.yml)
32
+ [![codecov](https://codecov.io/gh/usestapel/stapel-mailtrap/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-mailtrap)
33
+
34
+ > An email trap (mail catcher) for dev/staging: outbound mail is captured into
35
+ > a `TrappedEmail` journal instead of being sent, and browsed through a
36
+ > read-only "Mail" API. Plugs into stapel-notifications' email-provider seam by
37
+ > dotted path — no module-to-module import.
38
+
39
+ Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps
40
+ that deploy as a monolith or as microservices without changing module code.
41
+
42
+ ## Install
43
+
44
+ ```bash
45
+ pip install stapel-mailtrap
46
+ ```
47
+
48
+ ```python
49
+ # settings.py
50
+ INSTALLED_APPS = [
51
+ # ...
52
+ "stapel_mailtrap",
53
+ ]
54
+
55
+ # urls.py
56
+ path("mailtrap/", include("stapel_mailtrap.urls"))
57
+ ```
58
+
59
+ ```bash
60
+ python manage.py migrate
61
+ ```
62
+
63
+ ## Trapping notifications email
64
+
65
+ Point stapel-notifications' email provider at the trap — one setting, no code:
66
+
67
+ ```python
68
+ STAPEL_NOTIFICATIONS = {
69
+ "EMAIL_PROVIDER": "stapel_mailtrap.provider.MailtrapEmailProvider",
70
+ }
71
+ ```
72
+
73
+ Every email stapel-notifications would send is now persisted and inspectable
74
+ instead. The provider matches the notifications email duck type
75
+ (`send(recipient, subject, html_body, headers)`) — see MODULE.md §3.
76
+
77
+ ## Trapping any backend
78
+
79
+ For a host whose own mail path should trap, call the service directly:
80
+
81
+ ```python
82
+ from stapel_mailtrap import trap_email
83
+
84
+ trap_email(
85
+ to_email="alice@example.com",
86
+ from_email="bot@example.com",
87
+ subject="Your code",
88
+ body_html="<b>123456</b>",
89
+ body_text="123456",
90
+ attachments=[{"filename": "invoice.pdf", "content_type": "application/pdf", "size": 8123}],
91
+ scope_key="workspace-42", # opaque host scope
92
+ )
93
+ ```
94
+
95
+ It persists the row and emits `mailtrap.email.trapped` transactionally.
96
+ Attachments are **metadata only** — raw bytes are never stored.
97
+
98
+ ## HTTP API ("Письма" / Mail)
99
+
100
+ Read-only (the trap is filled by the provider / `trap_email`, never via the API):
101
+
102
+ | Route | Meaning |
103
+ |---|---|
104
+ | `GET mailtrap/emails/` | Trapped emails, newest first, paginated (anchor); `?scope_key=` filters |
105
+ | `GET mailtrap/emails/<uuid>/` | One trapped email — full HTML/text bodies + attachment metadata |
106
+
107
+ Default permission is staff/service only (trapped mail can contain OTPs and
108
+ magic links). Override `permission_classes` and set a `SCOPE_PROVIDER` for
109
+ per-tenant visibility — see MODULE.md.
110
+
111
+ ## Retention
112
+
113
+ ```python
114
+ STAPEL_MAILTRAP = {
115
+ "MAX_EMAILS": 1000, # hard cap on stored rows (0 disables)
116
+ "TTL_DAYS": 30, # delete rows older than N days (0 disables)
117
+ }
118
+ ```
119
+
120
+ Run the sweep from any scheduler:
121
+
122
+ ```bash
123
+ python manage.py purge_trapped_emails # --dry-run supported
124
+ ```
125
+
126
+ Or schedule the Celery task (celery is an optional host dependency):
127
+
128
+ ```python
129
+ CELERY_BEAT_SCHEDULE = {
130
+ "purge-trapped-emails": {
131
+ "task": "stapel_mailtrap.tasks.purge_trapped_emails",
132
+ "schedule": crontab(hour=3, minute=0), # nightly
133
+ },
134
+ }
135
+ ```
136
+
137
+ ## Settings
138
+
139
+ All configuration lives in the `STAPEL_MAILTRAP` namespace (dict setting, flat
140
+ setting, or env var — resolved lazily):
141
+
142
+ | Key | Default | Meaning |
143
+ |---|---|---|
144
+ | `SCOPE_PROVIDER` | `"stapel_mailtrap.scope.DefaultScopeProvider"` | Dotted path to a `ScopeProvider` subclass — the multi-tenant seam. |
145
+ | `MAX_EMAILS` | `1000` | Retention count cap (0 disables). |
146
+ | `TTL_DAYS` | `30` | Retention age cap in days (0 disables). |
147
+ | `STORE_BODY` | `True` | `False` stores the envelope only (bodies empty). |
148
+
149
+ ## comm surface
150
+
151
+ | Kind | Name | Contract |
152
+ |---|---|---|
153
+ | Event | `mailtrap.email.trapped` | `{email_id, to, from?, subject, scope_key, attachment_count, trapped_at}` — [schema](schemas/emits/mailtrap.email.trapped.json) |
154
+
155
+ ## Extension points
156
+
157
+ See [MODULE.md](MODULE.md) — the agent-facing map of every fork-free seam
158
+ (settings, the `ScopeProvider` seam, the notifications email-provider adapter
159
+ with its duck-typed contract, serializer seams, permissions, comm surface,
160
+ system checks).
161
+
162
+ ## Development
163
+
164
+ ```bash
165
+ pip install -e . && pip install pytest pytest-django pytest-cov ruff jsonschema
166
+ ./setup-hooks.sh
167
+ pytest tests/
168
+ ```
169
+
170
+ ## License
171
+
172
+ MIT
@@ -0,0 +1,144 @@
1
+ # stapel-mailtrap
2
+
3
+ [![CI](https://github.com/usestapel/stapel-mailtrap/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-mailtrap/actions/workflows/ci.yml)
4
+ [![codecov](https://codecov.io/gh/usestapel/stapel-mailtrap/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-mailtrap)
5
+
6
+ > An email trap (mail catcher) for dev/staging: outbound mail is captured into
7
+ > a `TrappedEmail` journal instead of being sent, and browsed through a
8
+ > read-only "Mail" API. Plugs into stapel-notifications' email-provider seam by
9
+ > dotted path — no module-to-module import.
10
+
11
+ Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps
12
+ that deploy as a monolith or as microservices without changing module code.
13
+
14
+ ## Install
15
+
16
+ ```bash
17
+ pip install stapel-mailtrap
18
+ ```
19
+
20
+ ```python
21
+ # settings.py
22
+ INSTALLED_APPS = [
23
+ # ...
24
+ "stapel_mailtrap",
25
+ ]
26
+
27
+ # urls.py
28
+ path("mailtrap/", include("stapel_mailtrap.urls"))
29
+ ```
30
+
31
+ ```bash
32
+ python manage.py migrate
33
+ ```
34
+
35
+ ## Trapping notifications email
36
+
37
+ Point stapel-notifications' email provider at the trap — one setting, no code:
38
+
39
+ ```python
40
+ STAPEL_NOTIFICATIONS = {
41
+ "EMAIL_PROVIDER": "stapel_mailtrap.provider.MailtrapEmailProvider",
42
+ }
43
+ ```
44
+
45
+ Every email stapel-notifications would send is now persisted and inspectable
46
+ instead. The provider matches the notifications email duck type
47
+ (`send(recipient, subject, html_body, headers)`) — see MODULE.md §3.
48
+
49
+ ## Trapping any backend
50
+
51
+ For a host whose own mail path should trap, call the service directly:
52
+
53
+ ```python
54
+ from stapel_mailtrap import trap_email
55
+
56
+ trap_email(
57
+ to_email="alice@example.com",
58
+ from_email="bot@example.com",
59
+ subject="Your code",
60
+ body_html="<b>123456</b>",
61
+ body_text="123456",
62
+ attachments=[{"filename": "invoice.pdf", "content_type": "application/pdf", "size": 8123}],
63
+ scope_key="workspace-42", # opaque host scope
64
+ )
65
+ ```
66
+
67
+ It persists the row and emits `mailtrap.email.trapped` transactionally.
68
+ Attachments are **metadata only** — raw bytes are never stored.
69
+
70
+ ## HTTP API ("Письма" / Mail)
71
+
72
+ Read-only (the trap is filled by the provider / `trap_email`, never via the API):
73
+
74
+ | Route | Meaning |
75
+ |---|---|
76
+ | `GET mailtrap/emails/` | Trapped emails, newest first, paginated (anchor); `?scope_key=` filters |
77
+ | `GET mailtrap/emails/<uuid>/` | One trapped email — full HTML/text bodies + attachment metadata |
78
+
79
+ Default permission is staff/service only (trapped mail can contain OTPs and
80
+ magic links). Override `permission_classes` and set a `SCOPE_PROVIDER` for
81
+ per-tenant visibility — see MODULE.md.
82
+
83
+ ## Retention
84
+
85
+ ```python
86
+ STAPEL_MAILTRAP = {
87
+ "MAX_EMAILS": 1000, # hard cap on stored rows (0 disables)
88
+ "TTL_DAYS": 30, # delete rows older than N days (0 disables)
89
+ }
90
+ ```
91
+
92
+ Run the sweep from any scheduler:
93
+
94
+ ```bash
95
+ python manage.py purge_trapped_emails # --dry-run supported
96
+ ```
97
+
98
+ Or schedule the Celery task (celery is an optional host dependency):
99
+
100
+ ```python
101
+ CELERY_BEAT_SCHEDULE = {
102
+ "purge-trapped-emails": {
103
+ "task": "stapel_mailtrap.tasks.purge_trapped_emails",
104
+ "schedule": crontab(hour=3, minute=0), # nightly
105
+ },
106
+ }
107
+ ```
108
+
109
+ ## Settings
110
+
111
+ All configuration lives in the `STAPEL_MAILTRAP` namespace (dict setting, flat
112
+ setting, or env var — resolved lazily):
113
+
114
+ | Key | Default | Meaning |
115
+ |---|---|---|
116
+ | `SCOPE_PROVIDER` | `"stapel_mailtrap.scope.DefaultScopeProvider"` | Dotted path to a `ScopeProvider` subclass — the multi-tenant seam. |
117
+ | `MAX_EMAILS` | `1000` | Retention count cap (0 disables). |
118
+ | `TTL_DAYS` | `30` | Retention age cap in days (0 disables). |
119
+ | `STORE_BODY` | `True` | `False` stores the envelope only (bodies empty). |
120
+
121
+ ## comm surface
122
+
123
+ | Kind | Name | Contract |
124
+ |---|---|---|
125
+ | Event | `mailtrap.email.trapped` | `{email_id, to, from?, subject, scope_key, attachment_count, trapped_at}` — [schema](schemas/emits/mailtrap.email.trapped.json) |
126
+
127
+ ## Extension points
128
+
129
+ See [MODULE.md](MODULE.md) — the agent-facing map of every fork-free seam
130
+ (settings, the `ScopeProvider` seam, the notifications email-provider adapter
131
+ with its duck-typed contract, serializer seams, permissions, comm surface,
132
+ system checks).
133
+
134
+ ## Development
135
+
136
+ ```bash
137
+ pip install -e . && pip install pytest pytest-django pytest-cov ruff jsonschema
138
+ ./setup-hooks.sh
139
+ pytest tests/
140
+ ```
141
+
142
+ ## License
143
+
144
+ MIT
@@ -0,0 +1,53 @@
1
+ """stapel-mailtrap — an email trap (mail catcher) for the Stapel framework.
2
+
3
+ In dev/staging, outbound mail must not leave the box (system-design S4: SMTP
4
+ is closed). This module is the sink: an email "provider" that, instead of
5
+ sending, persists every message as a ``TrappedEmail`` row and emits
6
+ ``mailtrap.email.trapped``. A read-only DRF API ("Письма" / Mail) lists and
7
+ inspects captured mail. It plugs into stapel-notifications' email-provider
8
+ seam **by dotted path** — no module imports another (invariant I2).
9
+
10
+ Public API (lazily exported, PEP 562 — importing this package never pulls in
11
+ Django or requires configured settings):
12
+
13
+ - ``mailtrap_settings`` — resolved app settings (``stapel_mailtrap.conf``).
14
+ - ``MailtrapEmailProvider`` — the notifications email-provider adapter
15
+ (dotted path for ``STAPEL_NOTIFICATIONS["EMAIL_PROVIDER"]``).
16
+ - ``ScopeProvider`` / ``DefaultScopeProvider`` — the multi-tenant scope seam.
17
+ - ``trap_email`` — persist one message + emit ``mailtrap.email.trapped``.
18
+ - ``purge_expired`` — retention sweep (TTL + MAX_EMAILS cap).
19
+ """
20
+
21
+ __all__ = [
22
+ "DefaultScopeProvider",
23
+ "MailtrapEmailProvider",
24
+ "ScopeProvider",
25
+ "mailtrap_settings",
26
+ "purge_expired",
27
+ "trap_email",
28
+ ]
29
+
30
+ # name -> submodule that defines it. Resolution is deferred until first
31
+ # attribute access so that `import stapel_mailtrap` stays Django-free.
32
+ _LAZY_EXPORTS = {
33
+ "mailtrap_settings": ".conf",
34
+ "MailtrapEmailProvider": ".provider",
35
+ "ScopeProvider": ".scope",
36
+ "DefaultScopeProvider": ".scope",
37
+ "trap_email": ".services",
38
+ "purge_expired": ".services",
39
+ }
40
+
41
+
42
+ def __getattr__(name):
43
+ if name in _LAZY_EXPORTS:
44
+ from importlib import import_module
45
+
46
+ value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
47
+ globals()[name] = value # cache for subsequent lookups
48
+ return value
49
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
50
+
51
+
52
+ def __dir__():
53
+ return sorted(set(globals()) | set(__all__))
@@ -0,0 +1,34 @@
1
+ """Read-only admin for the trapped-email journal (docs/library-standard.md §2).
2
+
3
+ The trap is filled by the notifications provider / ``trap_email`` — never by
4
+ hand — so the admin is inspect-only; deletion is allowed for manual cleanup.
5
+ """
6
+ from django.contrib import admin
7
+
8
+ from .models import TrappedEmail
9
+
10
+
11
+ @admin.register(TrappedEmail)
12
+ class TrappedEmailAdmin(admin.ModelAdmin):
13
+ list_display = ["id", "subject", "to_email", "from_email", "scope_key", "created_at"]
14
+ list_filter = ["scope_key", "created_at"]
15
+ search_fields = ["to_email", "from_email", "subject", "scope_key"]
16
+ readonly_fields = [
17
+ "id",
18
+ "to_email",
19
+ "from_email",
20
+ "subject",
21
+ "body_html",
22
+ "body_text",
23
+ "attachments",
24
+ "headers",
25
+ "scope_key",
26
+ "created_at",
27
+ ]
28
+ ordering = ["-created_at"]
29
+
30
+ def has_add_permission(self, request):
31
+ return False
32
+
33
+ def has_change_permission(self, request, obj=None):
34
+ return False
@@ -0,0 +1,16 @@
1
+ from django.apps import AppConfig
2
+
3
+
4
+ class MailtrapConfig(AppConfig):
5
+ name = "stapel_mailtrap"
6
+ label = "mailtrap"
7
+ verbose_name = "Mail trap"
8
+ default_auto_field = "django.db.models.BigAutoField"
9
+
10
+ def ready(self):
11
+ # Import-time side effects: system checks + error-key registration.
12
+ # Keep each in its own module. The email-provider adapter is resolved
13
+ # lazily by stapel-notifications (dotted path), so nothing to register
14
+ # here for it.
15
+ from . import checks # noqa: F401
16
+ from . import errors # noqa: F401
@@ -0,0 +1,50 @@
1
+ """Django system checks for stapel-mailtrap configuration.
2
+
3
+ Policy (docs/library-standard.md §3.7): E-level for configuration the service
4
+ cannot run with; W-level for entries that degrade lazily. The scope provider is
5
+ W-level on purpose: a broken ``SCOPE_PROVIDER`` degrades the API (it may raise
6
+ per request), it must not block deploys — the trap keeps capturing mail either
7
+ way. IDs:
8
+
9
+ - ``stapel_mailtrap.W001`` — ``SCOPE_PROVIDER`` dotted path fails to import.
10
+ - ``stapel_mailtrap.W002`` — ``SCOPE_PROVIDER`` resolves to something that is
11
+ not a ``ScopeProvider`` subclass.
12
+ """
13
+ from __future__ import annotations
14
+
15
+ import inspect
16
+
17
+ from django.core import checks
18
+
19
+
20
+ @checks.register("stapel_mailtrap")
21
+ def check_scope_provider(app_configs, **kwargs):
22
+ from .conf import mailtrap_settings
23
+ from .scope import ScopeProvider
24
+
25
+ try:
26
+ provider = mailtrap_settings.SCOPE_PROVIDER
27
+ except ImportError as exc:
28
+ return [
29
+ checks.Warning(
30
+ f"STAPEL_MAILTRAP['SCOPE_PROVIDER'] cannot be imported: {exc}",
31
+ hint=(
32
+ "Fix the dotted path or install the missing dependency; "
33
+ "the Mail API will fail to scope until it resolves."
34
+ ),
35
+ id="stapel_mailtrap.W001",
36
+ )
37
+ ]
38
+ if not (inspect.isclass(provider) and issubclass(provider, ScopeProvider)):
39
+ return [
40
+ checks.Warning(
41
+ f"STAPEL_MAILTRAP['SCOPE_PROVIDER'] resolves to {provider!r}, "
42
+ "which is not a stapel_mailtrap.scope.ScopeProvider subclass.",
43
+ hint="Implement the ScopeProvider seam (see MODULE.md).",
44
+ id="stapel_mailtrap.W002",
45
+ )
46
+ ]
47
+ return []
48
+
49
+
50
+ __all__ = ["check_scope_provider"]
@@ -0,0 +1,37 @@
1
+ """Settings namespace for stapel-mailtrap.
2
+
3
+ All configuration is read through ``mailtrap_settings`` (lazily, at call
4
+ time) — never via module-level ``os.getenv`` (values would freeze at import,
5
+ docs/library-standard.md §3.1). Resolution order per key:
6
+ ``settings.STAPEL_MAILTRAP`` dict -> flat Django setting of the same name ->
7
+ environment variable -> default below.
8
+
9
+ Dotted-path keys listed in ``import_strings`` are resolved with
10
+ ``import_string`` — the fork-free escape hatch for swappable behavior.
11
+ """
12
+ from stapel_core.conf import AppSettings
13
+
14
+ mailtrap_settings = AppSettings(
15
+ "STAPEL_MAILTRAP",
16
+ defaults={
17
+ # Dotted path to a stapel_mailtrap.scope.ScopeProvider subclass —
18
+ # the multi-tenant seam (single strategy, REPLACE semantics). The
19
+ # default is a single global scope (every mail gets scope_key="").
20
+ "SCOPE_PROVIDER": "stapel_mailtrap.scope.DefaultScopeProvider",
21
+ # Retention: hard cap on stored messages. The retention sweep
22
+ # (services.purge_expired / the purge_trapped_emails command / the
23
+ # Celery task) deletes the oldest rows beyond this many. 0 disables
24
+ # the count cap.
25
+ "MAX_EMAILS": 1000,
26
+ # Retention: delete messages older than this many days. 0 disables
27
+ # the age cap.
28
+ "TTL_DAYS": 30,
29
+ # Store rendered HTML/text bodies on the row. A host that only needs
30
+ # the envelope (to/from/subject) for a lighter footprint can set this
31
+ # False; bodies are then stored empty.
32
+ "STORE_BODY": True,
33
+ },
34
+ import_strings=("SCOPE_PROVIDER",),
35
+ )
36
+
37
+ __all__ = ["mailtrap_settings"]
@@ -0,0 +1,61 @@
1
+ def pytest_configure(config):
2
+ from django.conf import settings
3
+
4
+ if not settings.configured:
5
+ settings.configure(
6
+ SECRET_KEY="test-secret-key-not-for-production",
7
+ INSTALLED_APPS=[
8
+ "django.contrib.contenttypes",
9
+ "django.contrib.auth",
10
+ "django.contrib.sessions",
11
+ "django.contrib.admin",
12
+ "django.contrib.messages",
13
+ "stapel_core.django.users",
14
+ "rest_framework",
15
+ "stapel_mailtrap",
16
+ ],
17
+ AUTH_USER_MODEL="users.User",
18
+ DATABASES={
19
+ "default": {
20
+ "ENGINE": "django.db.backends.sqlite3",
21
+ "NAME": ":memory:",
22
+ }
23
+ },
24
+ DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
25
+ DEFAULT_FROM_EMAIL="noreply@example.com",
26
+ USE_TZ=True,
27
+ ROOT_URLCONF="stapel_mailtrap.tests.urls",
28
+ CACHES={
29
+ "default": {
30
+ "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
31
+ }
32
+ },
33
+ # Synchronous in-process comm with schema validation ON, so the
34
+ # committed contract in schemas/emits/ is enforced by the tests.
35
+ STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
36
+ STAPEL_COMM={
37
+ "OUTBOX_ENABLED": False,
38
+ "ACTION_TRANSPORT": "inprocess",
39
+ "VALIDATE_SCHEMAS": True,
40
+ },
41
+ MIGRATION_MODULES={
42
+ "users": None,
43
+ },
44
+ )
45
+ import django
46
+
47
+ django.setup()
48
+
49
+ from stapel_core.comm.schemas import autoload_schemas
50
+
51
+ autoload_schemas()
52
+
53
+
54
+ import pytest # noqa: E402
55
+
56
+
57
+ @pytest.fixture
58
+ def api_client():
59
+ from rest_framework.test import APIClient
60
+
61
+ return APIClient()
@@ -0,0 +1,55 @@
1
+ """Dataclass DTOs — the API models of stapel-mailtrap (never ORM instances)."""
2
+ from dataclasses import dataclass, field
3
+ from typing import List
4
+
5
+
6
+ @dataclass
7
+ class TrappedEmailListItem:
8
+ """A trapped email in the list view (envelope, no bodies).
9
+
10
+ Attributes:
11
+ id: Message id (UUID).
12
+ to_email: Recipient address.
13
+ from_email: Sender address.
14
+ subject: Subject line.
15
+ scope_key: Opaque host scope (workspace/org/project/tenant).
16
+ attachment_count: Number of attachments (metadata only).
17
+ created_at: Capture time (tz-aware ISO 8601).
18
+ """
19
+
20
+ id: str
21
+ to_email: str
22
+ from_email: str
23
+ subject: str
24
+ scope_key: str
25
+ attachment_count: int
26
+ created_at: str
27
+
28
+
29
+ @dataclass
30
+ class TrappedEmailDetail:
31
+ """A trapped email in the detail view (full bodies + attachment metadata).
32
+
33
+ Attributes:
34
+ id: Message id (UUID).
35
+ to_email: Recipient address.
36
+ from_email: Sender address.
37
+ subject: Subject line.
38
+ body_html: Rendered HTML body (empty when STORE_BODY is off).
39
+ body_text: Plain-text body (empty when STORE_BODY is off).
40
+ attachments: Attachment metadata dicts (filename/content_type/size).
41
+ headers: Header snapshot.
42
+ scope_key: Opaque host scope.
43
+ created_at: Capture time (tz-aware ISO 8601).
44
+ """
45
+
46
+ id: str
47
+ to_email: str
48
+ from_email: str
49
+ subject: str
50
+ body_html: str
51
+ body_text: str
52
+ attachments: List[dict] = field(default_factory=list)
53
+ headers: dict = field(default_factory=dict)
54
+ scope_key: str = ""
55
+ created_at: str = ""
@@ -0,0 +1,20 @@
1
+ """i18n error keys of stapel-mailtrap.
2
+
3
+ Only ``error.<status>.<slug>`` keys leave this package — human-readable
4
+ strings are translations, never literals in responses
5
+ (docs/library-standard.md §3.6).
6
+ """
7
+ from stapel_core.django.api.errors import register_service_errors
8
+
9
+ ERR_404_EMAIL_NOT_FOUND = "error.404.mailtrap_email_not_found"
10
+
11
+ STAPEL_MAILTRAP_ERRORS = {
12
+ ERR_404_EMAIL_NOT_FOUND: "Trapped email not found",
13
+ }
14
+
15
+ register_service_errors(STAPEL_MAILTRAP_ERRORS)
16
+
17
+ __all__ = [
18
+ "ERR_404_EMAIL_NOT_FOUND",
19
+ "STAPEL_MAILTRAP_ERRORS",
20
+ ]
File without changes
File without changes