medre-adapter-chatmail 0.1.0__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.
- medre_adapter_chatmail-0.1.0/LICENSE +21 -0
- medre_adapter_chatmail-0.1.0/PKG-INFO +232 -0
- medre_adapter_chatmail-0.1.0/README.md +212 -0
- medre_adapter_chatmail-0.1.0/pyproject.toml +75 -0
- medre_adapter_chatmail-0.1.0/setup.cfg +4 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/__init__.py +1 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/adapter.py +773 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/cli.py +253 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/cli_contrib.py +63 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/codec.py +182 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/compat.py +5 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/config.py +170 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/fake.py +109 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/metadata.py +39 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/plugin.py +120 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/py.typed +0 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/renderer.py +185 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/sample.py +9 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/session.py +316 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/state.py +209 -0
- medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/stopped_declaration.py +334 -0
- medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/PKG-INFO +232 -0
- medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/SOURCES.txt +47 -0
- medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/dependency_links.txt +1 -0
- medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/entry_points.txt +5 -0
- medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/requires.txt +10 -0
- medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/top_level.txt +1 -0
- medre_adapter_chatmail-0.1.0/tests/test_chatmail_rpc_retirement_sdk.py +504 -0
- medre_adapter_chatmail-0.1.0/tests/test_cli.py +280 -0
- medre_adapter_chatmail-0.1.0/tests/test_cli_contrib.py +92 -0
- medre_adapter_chatmail-0.1.0/tests/test_common_diagnostics.py +50 -0
- medre_adapter_chatmail-0.1.0/tests/test_config_codec_renderer.py +348 -0
- medre_adapter_chatmail-0.1.0/tests/test_distribution_license.py +28 -0
- medre_adapter_chatmail-0.1.0/tests/test_durable_runtime.py +595 -0
- medre_adapter_chatmail-0.1.0/tests/test_live.py +256 -0
- medre_adapter_chatmail-0.1.0/tests/test_native_health.py +153 -0
- medre_adapter_chatmail-0.1.0/tests/test_native_reply.py +527 -0
- medre_adapter_chatmail-0.1.0/tests/test_native_reply_sdk.py +26 -0
- medre_adapter_chatmail-0.1.0/tests/test_native_sender_attribution.py +271 -0
- medre_adapter_chatmail-0.1.0/tests/test_native_setup_instructions.py +217 -0
- medre_adapter_chatmail-0.1.0/tests/test_pin_literal_hygiene.py +124 -0
- medre_adapter_chatmail-0.1.0/tests/test_plugin_api_version.py +11 -0
- medre_adapter_chatmail-0.1.0/tests/test_project_tooling.py +78 -0
- medre_adapter_chatmail-0.1.0/tests/test_recorded_native_reply_evidence.py +108 -0
- medre_adapter_chatmail-0.1.0/tests/test_relay_prefix_surface.py +78 -0
- medre_adapter_chatmail-0.1.0/tests/test_review_regressions.py +124 -0
- medre_adapter_chatmail-0.1.0/tests/test_sdk_contract.py +100 -0
- medre_adapter_chatmail-0.1.0/tests/test_stopped_declaration.py +366 -0
- medre_adapter_chatmail-0.1.0/tests/test_stopped_native_restore.py +178 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jeremiah K.
|
|
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,232 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: medre-adapter-chatmail
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Chatmail conversations for MEDRE through the official core RPC client
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Classifier: Typing :: Typed
|
|
7
|
+
Requires-Python: >=3.11
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Requires-Dist: medre<0.2.0,>=0.1.0
|
|
11
|
+
Requires-Dist: deltachat-rpc-client==2.69.0
|
|
12
|
+
Requires-Dist: deltachat-rpc-server==2.69.0
|
|
13
|
+
Provides-Extra: test
|
|
14
|
+
Requires-Dist: pytest==9.2.0; extra == "test"
|
|
15
|
+
Requires-Dist: pytest-asyncio==1.5.0; extra == "test"
|
|
16
|
+
Requires-Dist: pytest-timeout==2.4.0; extra == "test"
|
|
17
|
+
Requires-Dist: pytest-cov==7.1.0; extra == "test"
|
|
18
|
+
Requires-Dist: jsonschema==4.26.0; extra == "test"
|
|
19
|
+
Dynamic: license-file
|
|
20
|
+
|
|
21
|
+
# MEDRE Chatmail adapter
|
|
22
|
+
|
|
23
|
+
Bridge accepted Chatmail group conversations and direct chats through the official
|
|
24
|
+
Python RPC client and native Chatmail core. The provider supplies plain-text
|
|
25
|
+
rendering, durable ingress checkpoints, a bounded outbound queue, and an
|
|
26
|
+
SDK-free fake for offline development.
|
|
27
|
+
|
|
28
|
+
## Install
|
|
29
|
+
|
|
30
|
+
For a persistent bridge, keep core and adapters in one locked uv project:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
uv init --bare medre-bridge
|
|
34
|
+
cd medre-bridge
|
|
35
|
+
uv add 'medre @ git+https://github.com/jeremiah-k/medre.git@main' \
|
|
36
|
+
'medre-adapter-chatmail @ git+https://github.com/jeremiah-k/medre-adapter-chatmail.git@main'
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Both RPC packages are installed together; no Rust build or separate daemon
|
|
40
|
+
installation is needed. Use immutable Git revisions for reproducible deployments.
|
|
41
|
+
`uv run --locked` preserves the project lock when starting commands.
|
|
42
|
+
|
|
43
|
+
For a persistent MEDRE tool installation, `medre adapters install chatmail`
|
|
44
|
+
adds the provider to the same environment. Provision through `medre adapter
|
|
45
|
+
chatmail`; a separately exposed helper executable is unnecessary. The
|
|
46
|
+
standalone `medre-chatmail` entry point remains available in activated project
|
|
47
|
+
environments and uses the same arguments and execution path.
|
|
48
|
+
|
|
49
|
+
## Set up a profile
|
|
50
|
+
|
|
51
|
+
Provisioning proceeds through explicit stages: prerequisites, profile
|
|
52
|
+
provisioning, conversation acceptance and discovery, then offline
|
|
53
|
+
configuration and verification. Profile creation and invitation acceptance
|
|
54
|
+
happen only on these commands; runtime startup never creates an identity or
|
|
55
|
+
accepts an invitation. Chatmail declares no `medre config native` form:
|
|
56
|
+
a profile needs the pinned native tooling that `medre adapter chatmail`
|
|
57
|
+
drives, so the provider contributes these commands instead of an offline
|
|
58
|
+
setup form. On cores that provide the typed setup-instructions seam, the
|
|
59
|
+
provider declares this journey as ordered setup instructions and
|
|
60
|
+
`medre config native --transport chatmail --adapter-id mail --output PATH`
|
|
61
|
+
renders it offline with an `informational_only` classification: the
|
|
62
|
+
contributed commands appear verbatim with a purpose and an evidence note
|
|
63
|
+
each, core never executes them, and no file is written. On older cores this
|
|
64
|
+
README remains the source of the journey. Each stage below states what its
|
|
65
|
+
observations prove and what they leave unproven.
|
|
66
|
+
|
|
67
|
+
> The commands in this journey use `--adapter mail` as an **example** instance.
|
|
68
|
+
> Replace that value consistently with the actual configured provider ID before
|
|
69
|
+
> running commands. `medre config native` displays instructions only; it does
|
|
70
|
+
> not substitute IDs, provision accounts, or create a bridge.
|
|
71
|
+
|
|
72
|
+
### Prerequisites
|
|
73
|
+
|
|
74
|
+
- The provider installed in MEDRE's environment (above), with the RPC client
|
|
75
|
+
and native server it ships together.
|
|
76
|
+
- A relay's private `DCACCOUNT:` or `DCLOGIN:` QR payload for `init`.
|
|
77
|
+
- An invitation QR payload (`OPENPGP4FPR:` or an `i.delta.chat` link) for
|
|
78
|
+
each conversation to bridge.
|
|
79
|
+
- A terminal with echo control for hidden input, or `--qr-stdin` for
|
|
80
|
+
automation. Credentials never belong in command arguments or committed
|
|
81
|
+
files.
|
|
82
|
+
- The bridge stopped and no other client using the profile. The profile is
|
|
83
|
+
dedicated to one adapter instance; concurrent MEDRE commands refuse the
|
|
84
|
+
profile lock, and an unrelated Chatmail client does not honor that lock.
|
|
85
|
+
|
|
86
|
+
### Stage 1: provision the profile
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
uv run --locked medre adapter chatmail init --adapter mail
|
|
90
|
+
uv run --locked medre adapter chatmail accounts --adapter mail
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`init` reads the relay's private QR payload with hidden terminal input,
|
|
94
|
+
creates the profile on this explicit command only, and keeps an existing
|
|
95
|
+
configured account. `accounts` lists local account IDs and their configured
|
|
96
|
+
state without exposing credentials. A configured profile proves that the
|
|
97
|
+
native core reports this account configured. Profile provisioning is not
|
|
98
|
+
relay service acceptance: relay-side limits surface only through later
|
|
99
|
+
delivery feedback, and this stage sends nothing.
|
|
100
|
+
|
|
101
|
+
### Stage 2: accept conversations and discover chat IDs
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
uv run --locked medre adapter chatmail join --adapter mail
|
|
105
|
+
uv run --locked medre adapter chatmail chats --adapter mail --groups --json
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`join` reads one contact or group invitation, completes the native secure
|
|
109
|
+
join for it, and waits until the native core reports that the chat can send.
|
|
110
|
+
`chats` lists ordinary conversations of this profile, groups first;
|
|
111
|
+
`--groups` limits discovery to groups, and omitting it includes direct
|
|
112
|
+
conversations. A joined chat proves that this conversation is accepted and
|
|
113
|
+
natively sendable. It does not prove that bridge messages reach their
|
|
114
|
+
recipients.
|
|
115
|
+
|
|
116
|
+
### Stage 3: configure and verify offline
|
|
117
|
+
|
|
118
|
+
Save a private `connections.yaml` using the accepted chat IDs from `chats`:
|
|
119
|
+
|
|
120
|
+
```yaml
|
|
121
|
+
adapters:
|
|
122
|
+
chatmail:
|
|
123
|
+
mail:
|
|
124
|
+
adapter_kind: real
|
|
125
|
+
account_id: 1 # Replace with the ID reported by 'accounts'.
|
|
126
|
+
chats: [12] # Replace with the accepted chat IDs from this profile.
|
|
127
|
+
origin_label: Chatmail
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Then validate without contacting the profile:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
uv run --locked medre config check --config connections.yaml
|
|
134
|
+
uv run --locked medre routes plan --config connections.yaml
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Both commands run entirely offline against the typed configuration model.
|
|
138
|
+
This fragment describes one connection, not a complete bridge: its route plan
|
|
139
|
+
has no delivery legs until a second adapter and explicit routes are added.
|
|
140
|
+
Use `medre config bridge` to construct those legs, then run both checks again.
|
|
141
|
+
Neither a valid config nor a nonempty route plan proves peer delivery.
|
|
142
|
+
`medre smoke` exercises the SDK-free fake only; real configurations are
|
|
143
|
+
rejected by fake smoke. An initial `deferred` result with `local_queue`
|
|
144
|
+
confirmation records retention in the private pending-delivery journal only;
|
|
145
|
+
SMTP handoff is pending. Later correlated `remote_service` feedback confirms
|
|
146
|
+
SMTP-server acceptance, with notes differentiated by native state: the outgoing
|
|
147
|
+
server accepted the message but recipient delivery and reading are unconfirmed,
|
|
148
|
+
or a native MDN (read receipt) confirms reading.
|
|
149
|
+
|
|
150
|
+
## Configuration reference
|
|
151
|
+
|
|
152
|
+
Add routes using decimal channel strings, such as `source_channel: "12"` or
|
|
153
|
+
`dest_channel: "12"`. Chat IDs are local to a profile; contact addresses are not
|
|
154
|
+
used to guess conversation identity. Run `medre config check` before starting
|
|
155
|
+
the bridge. Explicit `accounts_dir`, `state_dir` and `rpc_server_path` overrides
|
|
156
|
+
are available for existing profiles and native server installations.
|
|
157
|
+
|
|
158
|
+
Profiles default to MEDRE's instance state directory, under
|
|
159
|
+
`adapters/mail/chatmail/accounts`. `MEDRE_HOME` and the usual XDG paths are
|
|
160
|
+
honored. Use the same `--adapter` and `--accounts-dir` options for setup and
|
|
161
|
+
runtime configuration. Once a runtime YAML exists, `--config bridge.yaml
|
|
162
|
+
--adapter mail` selects its profile and account directly, including for the
|
|
163
|
+
`chats` discovery above.
|
|
164
|
+
|
|
165
|
+
Use `--qr-stdin` to supply a QR payload through standard input in automation.
|
|
166
|
+
Keep the profile, MEDRE database and pending-delivery journal together when
|
|
167
|
+
backing up state.
|
|
168
|
+
|
|
169
|
+
## Delivery and rendering
|
|
170
|
+
|
|
171
|
+
- Preserve plain text and MEDRE attribution. When core uniquely binds an earlier
|
|
172
|
+
message to a native reference in the same private profile and chat,
|
|
173
|
+
a reply uses Delta Chat's native quote UI (`quotedMessageId`). If the target
|
|
174
|
+
cannot be verified, retain a readable inline reply instead. Threads still use
|
|
175
|
+
core's inline fallback. Refuse text exceeding the configured UTF-8 budget.
|
|
176
|
+
- Baseline existing history on first use. Resume after the last durable checkpoint
|
|
177
|
+
on subsequent starts, committing the cursor only after canonical admission.
|
|
178
|
+
- Keep partial text messages pending. Exclude self echoes, blocked contacts,
|
|
179
|
+
informational controls, edits and unsupported media from fresh-message ingress.
|
|
180
|
+
- Return local queue admission as deferred delivery. Report SMTP acceptance only
|
|
181
|
+
after the native core confirms outgoing-server acceptance; recipient delivery
|
|
182
|
+
and reading remain unconfirmed without separate MDN evidence. Neither claims
|
|
183
|
+
relay acceptance or bridge confidentiality.
|
|
184
|
+
- Retain exact attempt/native-ID correlation until core accepts delivery feedback.
|
|
185
|
+
Recover correlated native jobs without resending. Abandon unsent or uncertain
|
|
186
|
+
work recovered across a restart, requiring inspection before an explicit retry.
|
|
187
|
+
- Expose encryption/signature observations in native metadata, alongside the
|
|
188
|
+
sender's chatmail address, native send/receive timestamps and validated
|
|
189
|
+
conversation facts; attribution carries the address as the sender handle.
|
|
190
|
+
A bounded opted-in `public_facts` projection (currently
|
|
191
|
+
`encrypted_and_signed`) feeds core's transport-neutral bridge context.
|
|
192
|
+
Confidentiality across the bridge and identity puppeting are not implied.
|
|
193
|
+
|
|
194
|
+
Attachments, native edits/deletes/reactions, forwarded read receipts, typing
|
|
195
|
+
notifications and puppeting are not advertised. The native core owns SMTP/IMAP,
|
|
196
|
+
cryptography, protocol retries and account storage. MEDRE owns routing and
|
|
197
|
+
lifecycle authority.
|
|
198
|
+
|
|
199
|
+
See the [provider contract](docs/spec/chatmail.md) and
|
|
200
|
+
[configuration schema](docs/schemas/config.schema.json).
|
|
201
|
+
|
|
202
|
+
## Develop and test
|
|
203
|
+
|
|
204
|
+
Use the locked uv development workflow in [contributing](CONTRIBUTING.md).
|
|
205
|
+
It supports core and provider checkouts at arbitrary locations; select the
|
|
206
|
+
native SDK tier explicitly after synchronization.
|
|
207
|
+
|
|
208
|
+
The default tier excludes native SDK and live tests. The SDK tier runs the actual
|
|
209
|
+
pinned RPC client and server against temporary local profiles without an external
|
|
210
|
+
mail service. CI runs both tiers on Python 3.11–3.14 and qualifies the adapter
|
|
211
|
+
against core `main`, resolved once per run. Keep `MEDRE_CORE_REF` unset;
|
|
212
|
+
workflow dispatch accepts an exact candidate core revision.
|
|
213
|
+
The run summary records both resolved commit IDs. SDK constraints are exported
|
|
214
|
+
from core's lock without installing private core test helpers into this provider.
|
|
215
|
+
|
|
216
|
+
The [live test](tests/test_live.py) accepts an explicitly prepared relay/profile
|
|
217
|
+
fixture. Native quote presentation requires that independent-peer campaign on
|
|
218
|
+
the candidate revision before merging or releasing native reply support; API-shape
|
|
219
|
+
tests alone do not qualify it. See [live testing](docs/live-testing.md). All service fixtures use
|
|
220
|
+
ordinary container permissions; no host system configuration is required by this
|
|
221
|
+
provider's tests.
|
|
222
|
+
|
|
223
|
+
Per-message native sender attribution is enabled by default. Delta Chat recipients
|
|
224
|
+
see the original sender and origin as a message display name while the bridge
|
|
225
|
+
account and contact profile remain unchanged. Set `native_sender_attribution: false`
|
|
226
|
+
to keep only the configured body prefix. See [the provider contract](docs/spec/chatmail.md#per-message-native-attribution)
|
|
227
|
+
and [the two-receipt native qualification](docs/evidence/native-sender-2026-10-25.json).
|
|
228
|
+
|
|
229
|
+
## Development tooling
|
|
230
|
+
|
|
231
|
+
See [contributing](CONTRIBUTING.md) for the shared Trunk quality gate and uv-based
|
|
232
|
+
editable development workflow.
|
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
# MEDRE Chatmail adapter
|
|
2
|
+
|
|
3
|
+
Bridge accepted Chatmail group conversations and direct chats through the official
|
|
4
|
+
Python RPC client and native Chatmail core. The provider supplies plain-text
|
|
5
|
+
rendering, durable ingress checkpoints, a bounded outbound queue, and an
|
|
6
|
+
SDK-free fake for offline development.
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
For a persistent bridge, keep core and adapters in one locked uv project:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
uv init --bare medre-bridge
|
|
14
|
+
cd medre-bridge
|
|
15
|
+
uv add 'medre @ git+https://github.com/jeremiah-k/medre.git@main' \
|
|
16
|
+
'medre-adapter-chatmail @ git+https://github.com/jeremiah-k/medre-adapter-chatmail.git@main'
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Both RPC packages are installed together; no Rust build or separate daemon
|
|
20
|
+
installation is needed. Use immutable Git revisions for reproducible deployments.
|
|
21
|
+
`uv run --locked` preserves the project lock when starting commands.
|
|
22
|
+
|
|
23
|
+
For a persistent MEDRE tool installation, `medre adapters install chatmail`
|
|
24
|
+
adds the provider to the same environment. Provision through `medre adapter
|
|
25
|
+
chatmail`; a separately exposed helper executable is unnecessary. The
|
|
26
|
+
standalone `medre-chatmail` entry point remains available in activated project
|
|
27
|
+
environments and uses the same arguments and execution path.
|
|
28
|
+
|
|
29
|
+
## Set up a profile
|
|
30
|
+
|
|
31
|
+
Provisioning proceeds through explicit stages: prerequisites, profile
|
|
32
|
+
provisioning, conversation acceptance and discovery, then offline
|
|
33
|
+
configuration and verification. Profile creation and invitation acceptance
|
|
34
|
+
happen only on these commands; runtime startup never creates an identity or
|
|
35
|
+
accepts an invitation. Chatmail declares no `medre config native` form:
|
|
36
|
+
a profile needs the pinned native tooling that `medre adapter chatmail`
|
|
37
|
+
drives, so the provider contributes these commands instead of an offline
|
|
38
|
+
setup form. On cores that provide the typed setup-instructions seam, the
|
|
39
|
+
provider declares this journey as ordered setup instructions and
|
|
40
|
+
`medre config native --transport chatmail --adapter-id mail --output PATH`
|
|
41
|
+
renders it offline with an `informational_only` classification: the
|
|
42
|
+
contributed commands appear verbatim with a purpose and an evidence note
|
|
43
|
+
each, core never executes them, and no file is written. On older cores this
|
|
44
|
+
README remains the source of the journey. Each stage below states what its
|
|
45
|
+
observations prove and what they leave unproven.
|
|
46
|
+
|
|
47
|
+
> The commands in this journey use `--adapter mail` as an **example** instance.
|
|
48
|
+
> Replace that value consistently with the actual configured provider ID before
|
|
49
|
+
> running commands. `medre config native` displays instructions only; it does
|
|
50
|
+
> not substitute IDs, provision accounts, or create a bridge.
|
|
51
|
+
|
|
52
|
+
### Prerequisites
|
|
53
|
+
|
|
54
|
+
- The provider installed in MEDRE's environment (above), with the RPC client
|
|
55
|
+
and native server it ships together.
|
|
56
|
+
- A relay's private `DCACCOUNT:` or `DCLOGIN:` QR payload for `init`.
|
|
57
|
+
- An invitation QR payload (`OPENPGP4FPR:` or an `i.delta.chat` link) for
|
|
58
|
+
each conversation to bridge.
|
|
59
|
+
- A terminal with echo control for hidden input, or `--qr-stdin` for
|
|
60
|
+
automation. Credentials never belong in command arguments or committed
|
|
61
|
+
files.
|
|
62
|
+
- The bridge stopped and no other client using the profile. The profile is
|
|
63
|
+
dedicated to one adapter instance; concurrent MEDRE commands refuse the
|
|
64
|
+
profile lock, and an unrelated Chatmail client does not honor that lock.
|
|
65
|
+
|
|
66
|
+
### Stage 1: provision the profile
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
uv run --locked medre adapter chatmail init --adapter mail
|
|
70
|
+
uv run --locked medre adapter chatmail accounts --adapter mail
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`init` reads the relay's private QR payload with hidden terminal input,
|
|
74
|
+
creates the profile on this explicit command only, and keeps an existing
|
|
75
|
+
configured account. `accounts` lists local account IDs and their configured
|
|
76
|
+
state without exposing credentials. A configured profile proves that the
|
|
77
|
+
native core reports this account configured. Profile provisioning is not
|
|
78
|
+
relay service acceptance: relay-side limits surface only through later
|
|
79
|
+
delivery feedback, and this stage sends nothing.
|
|
80
|
+
|
|
81
|
+
### Stage 2: accept conversations and discover chat IDs
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
uv run --locked medre adapter chatmail join --adapter mail
|
|
85
|
+
uv run --locked medre adapter chatmail chats --adapter mail --groups --json
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`join` reads one contact or group invitation, completes the native secure
|
|
89
|
+
join for it, and waits until the native core reports that the chat can send.
|
|
90
|
+
`chats` lists ordinary conversations of this profile, groups first;
|
|
91
|
+
`--groups` limits discovery to groups, and omitting it includes direct
|
|
92
|
+
conversations. A joined chat proves that this conversation is accepted and
|
|
93
|
+
natively sendable. It does not prove that bridge messages reach their
|
|
94
|
+
recipients.
|
|
95
|
+
|
|
96
|
+
### Stage 3: configure and verify offline
|
|
97
|
+
|
|
98
|
+
Save a private `connections.yaml` using the accepted chat IDs from `chats`:
|
|
99
|
+
|
|
100
|
+
```yaml
|
|
101
|
+
adapters:
|
|
102
|
+
chatmail:
|
|
103
|
+
mail:
|
|
104
|
+
adapter_kind: real
|
|
105
|
+
account_id: 1 # Replace with the ID reported by 'accounts'.
|
|
106
|
+
chats: [12] # Replace with the accepted chat IDs from this profile.
|
|
107
|
+
origin_label: Chatmail
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Then validate without contacting the profile:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
uv run --locked medre config check --config connections.yaml
|
|
114
|
+
uv run --locked medre routes plan --config connections.yaml
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Both commands run entirely offline against the typed configuration model.
|
|
118
|
+
This fragment describes one connection, not a complete bridge: its route plan
|
|
119
|
+
has no delivery legs until a second adapter and explicit routes are added.
|
|
120
|
+
Use `medre config bridge` to construct those legs, then run both checks again.
|
|
121
|
+
Neither a valid config nor a nonempty route plan proves peer delivery.
|
|
122
|
+
`medre smoke` exercises the SDK-free fake only; real configurations are
|
|
123
|
+
rejected by fake smoke. An initial `deferred` result with `local_queue`
|
|
124
|
+
confirmation records retention in the private pending-delivery journal only;
|
|
125
|
+
SMTP handoff is pending. Later correlated `remote_service` feedback confirms
|
|
126
|
+
SMTP-server acceptance, with notes differentiated by native state: the outgoing
|
|
127
|
+
server accepted the message but recipient delivery and reading are unconfirmed,
|
|
128
|
+
or a native MDN (read receipt) confirms reading.
|
|
129
|
+
|
|
130
|
+
## Configuration reference
|
|
131
|
+
|
|
132
|
+
Add routes using decimal channel strings, such as `source_channel: "12"` or
|
|
133
|
+
`dest_channel: "12"`. Chat IDs are local to a profile; contact addresses are not
|
|
134
|
+
used to guess conversation identity. Run `medre config check` before starting
|
|
135
|
+
the bridge. Explicit `accounts_dir`, `state_dir` and `rpc_server_path` overrides
|
|
136
|
+
are available for existing profiles and native server installations.
|
|
137
|
+
|
|
138
|
+
Profiles default to MEDRE's instance state directory, under
|
|
139
|
+
`adapters/mail/chatmail/accounts`. `MEDRE_HOME` and the usual XDG paths are
|
|
140
|
+
honored. Use the same `--adapter` and `--accounts-dir` options for setup and
|
|
141
|
+
runtime configuration. Once a runtime YAML exists, `--config bridge.yaml
|
|
142
|
+
--adapter mail` selects its profile and account directly, including for the
|
|
143
|
+
`chats` discovery above.
|
|
144
|
+
|
|
145
|
+
Use `--qr-stdin` to supply a QR payload through standard input in automation.
|
|
146
|
+
Keep the profile, MEDRE database and pending-delivery journal together when
|
|
147
|
+
backing up state.
|
|
148
|
+
|
|
149
|
+
## Delivery and rendering
|
|
150
|
+
|
|
151
|
+
- Preserve plain text and MEDRE attribution. When core uniquely binds an earlier
|
|
152
|
+
message to a native reference in the same private profile and chat,
|
|
153
|
+
a reply uses Delta Chat's native quote UI (`quotedMessageId`). If the target
|
|
154
|
+
cannot be verified, retain a readable inline reply instead. Threads still use
|
|
155
|
+
core's inline fallback. Refuse text exceeding the configured UTF-8 budget.
|
|
156
|
+
- Baseline existing history on first use. Resume after the last durable checkpoint
|
|
157
|
+
on subsequent starts, committing the cursor only after canonical admission.
|
|
158
|
+
- Keep partial text messages pending. Exclude self echoes, blocked contacts,
|
|
159
|
+
informational controls, edits and unsupported media from fresh-message ingress.
|
|
160
|
+
- Return local queue admission as deferred delivery. Report SMTP acceptance only
|
|
161
|
+
after the native core confirms outgoing-server acceptance; recipient delivery
|
|
162
|
+
and reading remain unconfirmed without separate MDN evidence. Neither claims
|
|
163
|
+
relay acceptance or bridge confidentiality.
|
|
164
|
+
- Retain exact attempt/native-ID correlation until core accepts delivery feedback.
|
|
165
|
+
Recover correlated native jobs without resending. Abandon unsent or uncertain
|
|
166
|
+
work recovered across a restart, requiring inspection before an explicit retry.
|
|
167
|
+
- Expose encryption/signature observations in native metadata, alongside the
|
|
168
|
+
sender's chatmail address, native send/receive timestamps and validated
|
|
169
|
+
conversation facts; attribution carries the address as the sender handle.
|
|
170
|
+
A bounded opted-in `public_facts` projection (currently
|
|
171
|
+
`encrypted_and_signed`) feeds core's transport-neutral bridge context.
|
|
172
|
+
Confidentiality across the bridge and identity puppeting are not implied.
|
|
173
|
+
|
|
174
|
+
Attachments, native edits/deletes/reactions, forwarded read receipts, typing
|
|
175
|
+
notifications and puppeting are not advertised. The native core owns SMTP/IMAP,
|
|
176
|
+
cryptography, protocol retries and account storage. MEDRE owns routing and
|
|
177
|
+
lifecycle authority.
|
|
178
|
+
|
|
179
|
+
See the [provider contract](docs/spec/chatmail.md) and
|
|
180
|
+
[configuration schema](docs/schemas/config.schema.json).
|
|
181
|
+
|
|
182
|
+
## Develop and test
|
|
183
|
+
|
|
184
|
+
Use the locked uv development workflow in [contributing](CONTRIBUTING.md).
|
|
185
|
+
It supports core and provider checkouts at arbitrary locations; select the
|
|
186
|
+
native SDK tier explicitly after synchronization.
|
|
187
|
+
|
|
188
|
+
The default tier excludes native SDK and live tests. The SDK tier runs the actual
|
|
189
|
+
pinned RPC client and server against temporary local profiles without an external
|
|
190
|
+
mail service. CI runs both tiers on Python 3.11–3.14 and qualifies the adapter
|
|
191
|
+
against core `main`, resolved once per run. Keep `MEDRE_CORE_REF` unset;
|
|
192
|
+
workflow dispatch accepts an exact candidate core revision.
|
|
193
|
+
The run summary records both resolved commit IDs. SDK constraints are exported
|
|
194
|
+
from core's lock without installing private core test helpers into this provider.
|
|
195
|
+
|
|
196
|
+
The [live test](tests/test_live.py) accepts an explicitly prepared relay/profile
|
|
197
|
+
fixture. Native quote presentation requires that independent-peer campaign on
|
|
198
|
+
the candidate revision before merging or releasing native reply support; API-shape
|
|
199
|
+
tests alone do not qualify it. See [live testing](docs/live-testing.md). All service fixtures use
|
|
200
|
+
ordinary container permissions; no host system configuration is required by this
|
|
201
|
+
provider's tests.
|
|
202
|
+
|
|
203
|
+
Per-message native sender attribution is enabled by default. Delta Chat recipients
|
|
204
|
+
see the original sender and origin as a message display name while the bridge
|
|
205
|
+
account and contact profile remain unchanged. Set `native_sender_attribution: false`
|
|
206
|
+
to keep only the configured body prefix. See [the provider contract](docs/spec/chatmail.md#per-message-native-attribution)
|
|
207
|
+
and [the two-receipt native qualification](docs/evidence/native-sender-2026-10-25.json).
|
|
208
|
+
|
|
209
|
+
## Development tooling
|
|
210
|
+
|
|
211
|
+
See [contributing](CONTRIBUTING.md) for the shared Trunk quality gate and uv-based
|
|
212
|
+
editable development workflow.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "medre-adapter-chatmail"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Chatmail conversations for MEDRE through the official core RPC client"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.11"
|
|
7
|
+
license = "MIT"
|
|
8
|
+
classifiers = ["Typing :: Typed"]
|
|
9
|
+
dependencies = [
|
|
10
|
+
"medre>=0.1.0,<0.2.0",
|
|
11
|
+
"deltachat-rpc-client==2.69.0",
|
|
12
|
+
"deltachat-rpc-server==2.69.0",
|
|
13
|
+
]
|
|
14
|
+
|
|
15
|
+
[project.scripts]
|
|
16
|
+
medre-chatmail = "medre.adapters.chatmail.cli:main"
|
|
17
|
+
|
|
18
|
+
[project.entry-points."medre.adapters"]
|
|
19
|
+
chatmail = "medre.adapters.chatmail.plugin:adapter_spec"
|
|
20
|
+
|
|
21
|
+
[project.optional-dependencies]
|
|
22
|
+
test = [
|
|
23
|
+
"pytest==9.2.0",
|
|
24
|
+
"pytest-asyncio==1.5.0",
|
|
25
|
+
"pytest-timeout==2.4.0",
|
|
26
|
+
"pytest-cov==7.1.0",
|
|
27
|
+
"jsonschema==4.26.0",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
[build-system]
|
|
31
|
+
requires = ["setuptools>=77"]
|
|
32
|
+
build-backend = "setuptools.build_meta"
|
|
33
|
+
|
|
34
|
+
[tool.setuptools.packages.find]
|
|
35
|
+
where = ["src"]
|
|
36
|
+
|
|
37
|
+
[tool.setuptools.package-data]
|
|
38
|
+
"medre.adapters.chatmail" = ["py.typed"]
|
|
39
|
+
|
|
40
|
+
[tool.pytest.ini_options]
|
|
41
|
+
asyncio_mode = "auto"
|
|
42
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
43
|
+
testpaths = ["tests"]
|
|
44
|
+
pythonpath = ["src"]
|
|
45
|
+
filterwarnings = ["error"]
|
|
46
|
+
timeout = 30
|
|
47
|
+
addopts = "-m 'not chatmail_sdk and not live'"
|
|
48
|
+
markers = [
|
|
49
|
+
"chatmail_sdk: contracts against the released RPC client and native server",
|
|
50
|
+
"live: opt-in tests against an explicitly configured Chatmail relay",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
[tool.ruff]
|
|
54
|
+
line-length = 88
|
|
55
|
+
|
|
56
|
+
[tool.ruff.lint]
|
|
57
|
+
select = ["F", "E4", "E7", "E9", "B", "ASYNC", "RUF100"]
|
|
58
|
+
# Lifecycle timeout parameters implement the MEDRE contract.
|
|
59
|
+
ignore = ["ASYNC109"]
|
|
60
|
+
|
|
61
|
+
[tool.black]
|
|
62
|
+
target-version = ["py311"]
|
|
63
|
+
|
|
64
|
+
[tool.mypy]
|
|
65
|
+
python_version = "3.11"
|
|
66
|
+
strict = true
|
|
67
|
+
explicit_package_bases = true
|
|
68
|
+
follow_imports = "silent"
|
|
69
|
+
|
|
70
|
+
[[tool.mypy.overrides]]
|
|
71
|
+
module = ["deltachat_rpc_client", "deltachat_rpc_client.*"]
|
|
72
|
+
ignore_missing_imports = true
|
|
73
|
+
|
|
74
|
+
[tool.isort]
|
|
75
|
+
profile = "black"
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Chatmail provider; SDK imports belong to the native session boundary."""
|