@wtfalch/email 0.13.1 → 0.14.0

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 (42) hide show
  1. package/README.md +66 -4
  2. package/dist/mailbox/client.d.ts +22 -1
  3. package/dist/mailbox/client.js +45 -0
  4. package/dist/mailbox/fake/mailbox.js +205 -5
  5. package/dist/mailbox/index.d.ts +11 -7
  6. package/dist/mailbox/index.js +5 -3
  7. package/dist/mailbox/mail.css +13 -0
  8. package/dist/mailbox/mailboxes.d.ts +95 -1
  9. package/dist/mailbox/mailboxes.js +243 -1
  10. package/dist/mailbox/mutate.d.ts +21 -0
  11. package/dist/mailbox/mutate.js +71 -0
  12. package/dist/mailbox/quoted.d.ts +94 -0
  13. package/dist/mailbox/quoted.js +158 -0
  14. package/dist/mailbox/react/Composer.js +13 -1
  15. package/dist/mailbox/react/Mail.js +273 -33
  16. package/dist/mailbox/react/ThreadView.d.ts +13 -1
  17. package/dist/mailbox/react/ThreadView.js +5 -4
  18. package/dist/mailbox/react/index.d.ts +3 -1
  19. package/dist/mailbox/react/index.js +2 -1
  20. package/dist/mailbox/react/quotedHtml.d.ts +105 -0
  21. package/dist/mailbox/react/quotedHtml.js +163 -0
  22. package/dist/mailbox/snooze.d.ts +48 -0
  23. package/dist/mailbox/snooze.js +176 -0
  24. package/dist/mailbox/submit.d.ts +26 -0
  25. package/dist/mailbox/submit.js +88 -7
  26. package/dist/mailbox/threads.js +2 -0
  27. package/dist/mailbox/types.d.ts +40 -0
  28. package/dist/postmaster/apply.d.ts +154 -1
  29. package/dist/postmaster/apply.js +336 -1
  30. package/dist/postmaster/audit.d.ts +22 -1
  31. package/dist/postmaster/audit.js +7 -0
  32. package/dist/postmaster/client.d.ts +49 -0
  33. package/dist/postmaster/client.js +43 -0
  34. package/dist/postmaster/index.d.ts +4 -3
  35. package/dist/postmaster/index.js +3 -2
  36. package/dist/postmaster/objects.js +11 -0
  37. package/dist/postmaster/overview.d.ts +4 -0
  38. package/dist/postmaster/queue.d.ts +111 -0
  39. package/dist/postmaster/queue.js +64 -0
  40. package/dist/postmaster/writes.d.ts +59 -0
  41. package/dist/postmaster/writes.js +106 -0
  42. package/package.json +1 -1
@@ -0,0 +1,111 @@
1
+ /**
2
+ * The server's own outbound mail queue: every message Stalwart has accepted
3
+ * and not yet finished delivering, across every domain the instance serves.
4
+ *
5
+ * `submit.ts`'s `queued()` (in `@wtfalch/email/mailbox`) is a different
6
+ * thing entirely: it reads one signed-in account's own pending
7
+ * `EmailSubmission`s over the mail JMAP capability. This reads the server's
8
+ * queue itself, over the management API's `x:QueuedMessage` object — a
9
+ * message this instance relays for anyone, seen only by an administrator.
10
+ *
11
+ * The wire shape is `registry::schema::structs::QueuedMessage` on the
12
+ * server (checked against the `stalwartlabs/stalwart` source on 2026-09-22,
13
+ * the struct `tests/src/smtp/management/queue.rs` exercises with real
14
+ * requests). It is **not yet confirmed against a live 0.16.20 instance** the way
15
+ * `overview.ts`'s fixture is — nothing in this package read the mail queue
16
+ * before now — so this reads defensively and never assumes a field it
17
+ * cannot see is present.
18
+ */
19
+ import type { Instance } from './instance.js';
20
+ interface WireQueueExpiry {
21
+ '@type'?: string;
22
+ [property: string]: unknown;
23
+ }
24
+ /**
25
+ * `RecipientStatus` on the wire: `{'@type': 'Scheduled'}`,
26
+ * `{'@type': 'Completed', responseMessage, ...}`, or a
27
+ * `{'@type': 'TemporaryFailure' | 'PermanentFailure', errorType,
28
+ * errorMessage, responseMessage, ...}`. Only the fields a readable error
29
+ * sentence needs are named; the rest travels through `[property: string]`
30
+ * without ever reaching {@link QueueRecipient}.
31
+ */
32
+ interface WireRecipientStatus {
33
+ '@type'?: string;
34
+ errorType?: string;
35
+ errorMessage?: string;
36
+ responseMessage?: string;
37
+ [property: string]: unknown;
38
+ }
39
+ interface WireQueuedRecipient {
40
+ [property: string]: unknown;
41
+ retryCount?: number;
42
+ retryDue?: string;
43
+ expires?: WireQueueExpiry;
44
+ status?: WireRecipientStatus;
45
+ }
46
+ interface WireQueuedMessage {
47
+ [property: string]: unknown;
48
+ id: string;
49
+ createdAt: string;
50
+ nextRetry?: string | null;
51
+ returnPath: string;
52
+ recipients?: Record<string, WireQueuedRecipient>;
53
+ size?: number;
54
+ }
55
+ /** Collapsed from the server's four-way `RecipientStatus` tag to what an
56
+ * admin needs: still trying, landed, or stuck. */
57
+ export type QueueRecipientState = 'scheduled' | 'delivered' | 'deferred' | 'failed';
58
+ export interface QueueRecipient {
59
+ readonly address: string;
60
+ readonly state: QueueRecipientState;
61
+ readonly retryCount: number;
62
+ /** When the server will try this recipient again. `null` once it has
63
+ * delivered or permanently failed — there is nothing left to retry. */
64
+ readonly retryDue: string | null;
65
+ /** The server's account of the last attempt, for `deferred` and `failed`
66
+ * only; `null` for `scheduled` and `delivered`, which have nothing to
67
+ * explain. */
68
+ readonly lastError: string | null;
69
+ }
70
+ export interface QueueMessage {
71
+ readonly id: string;
72
+ /** The envelope sender, or `'<>'` for a bounce with none — the server's
73
+ * own placeholder for an empty return path, carried through rather than
74
+ * turned into `null` so what is shown is what SMTP actually sent. */
75
+ readonly from: string;
76
+ readonly to: readonly string[];
77
+ readonly size: number;
78
+ readonly createdAt: string;
79
+ /** The earliest a still-pending recipient will be retried, or `null` once
80
+ * every recipient has resolved — delivered, or given up on for good. */
81
+ readonly nextRetry: string | null;
82
+ readonly recipients: readonly QueueRecipient[];
83
+ }
84
+ /** Pure: the server's `QueuedMessage` as an admin table row. */
85
+ export declare function queueMessageView(wire: WireQueuedMessage): QueueMessage;
86
+ /**
87
+ * Every message still in the outbound queue.
88
+ *
89
+ * Ordered however the server's `x:QueuedMessage/get` sends its `list` back.
90
+ * With no filter and no sort, `queued_message_query` (the Rust handler)
91
+ * walks the queue's own due-time index ascending, so this comes back
92
+ * soonest-due first — the recipient that has been waiting longest sorts
93
+ * near the top, which is what an admin looking for stuck mail wants. Not
94
+ * re-sorted here: doing that would assume `get` preserves the order its own
95
+ * `query` returned, which JMAP does not promise and this package has no
96
+ * fixture to confirm either way for this object.
97
+ *
98
+ * Reading the queue needs a credential wider than the dashboard's own key
99
+ * grants: `DASHBOARD_PERMISSIONS` (in `./client.ts`) is confirmed only for
100
+ * the five `/email` mailbox operations and does not cover `QueuedMessage`.
101
+ * The permission vocabulary has `sysQueuedMessageGet`, `sysQueuedMessageQuery`,
102
+ * `sysQueuedMessageUpdate` and `sysQueuedMessageDestroy`
103
+ * (`stalwartlabs/stalwart`, `crates/registry/src/schema/enums.rs:2028-2032`,
104
+ * `Sys<Object><Verb>` matching the names `DASHBOARD_PERMISSIONS` already
105
+ * uses for other objects) — present in the source, not yet exercised
106
+ * against a live instance, so this reads and writes with an
107
+ * `'inherit'`-scoped key or the instance administrator's own credential
108
+ * until a narrower key is confirmed to work.
109
+ */
110
+ export declare function loadQueue(instance: Instance): Promise<QueueMessage[]>;
111
+ export type { WireQueuedMessage };
@@ -0,0 +1,64 @@
1
+ function recipientView(address, wire) {
2
+ const tag = wire.status?.['@type'];
3
+ const state = tag === 'Completed'
4
+ ? 'delivered'
5
+ : tag === 'PermanentFailure'
6
+ ? 'failed'
7
+ : tag === 'TemporaryFailure'
8
+ ? 'deferred'
9
+ : 'scheduled';
10
+ const lastError = state === 'deferred' || state === 'failed'
11
+ ? (wire.status?.errorMessage ??
12
+ wire.status?.responseMessage ??
13
+ wire.status?.errorType ??
14
+ 'the server did not say why')
15
+ : null;
16
+ return {
17
+ address,
18
+ state,
19
+ retryCount: typeof wire.retryCount === 'number' ? wire.retryCount : 0,
20
+ retryDue: state === 'delivered' || state === 'failed' ? null : (wire.retryDue ?? null),
21
+ lastError,
22
+ };
23
+ }
24
+ /** Pure: the server's `QueuedMessage` as an admin table row. */
25
+ export function queueMessageView(wire) {
26
+ const recipients = Object.entries(wire.recipients ?? {}).map(([address, r]) => recipientView(address, r));
27
+ return {
28
+ id: wire.id,
29
+ from: wire.returnPath || '<>',
30
+ to: recipients.map((r) => r.address),
31
+ size: typeof wire.size === 'number' ? wire.size : 0,
32
+ createdAt: wire.createdAt,
33
+ nextRetry: wire.nextRetry ?? null,
34
+ recipients,
35
+ };
36
+ }
37
+ /**
38
+ * Every message still in the outbound queue.
39
+ *
40
+ * Ordered however the server's `x:QueuedMessage/get` sends its `list` back.
41
+ * With no filter and no sort, `queued_message_query` (the Rust handler)
42
+ * walks the queue's own due-time index ascending, so this comes back
43
+ * soonest-due first — the recipient that has been waiting longest sorts
44
+ * near the top, which is what an admin looking for stuck mail wants. Not
45
+ * re-sorted here: doing that would assume `get` preserves the order its own
46
+ * `query` returned, which JMAP does not promise and this package has no
47
+ * fixture to confirm either way for this object.
48
+ *
49
+ * Reading the queue needs a credential wider than the dashboard's own key
50
+ * grants: `DASHBOARD_PERMISSIONS` (in `./client.ts`) is confirmed only for
51
+ * the five `/email` mailbox operations and does not cover `QueuedMessage`.
52
+ * The permission vocabulary has `sysQueuedMessageGet`, `sysQueuedMessageQuery`,
53
+ * `sysQueuedMessageUpdate` and `sysQueuedMessageDestroy`
54
+ * (`stalwartlabs/stalwart`, `crates/registry/src/schema/enums.rs:2028-2032`,
55
+ * `Sys<Object><Verb>` matching the names `DASHBOARD_PERMISSIONS` already
56
+ * uses for other objects) — present in the source, not yet exercised
57
+ * against a live instance, so this reads and writes with an
58
+ * `'inherit'`-scoped key or the instance administrator's own credential
59
+ * until a narrower key is confirmed to work.
60
+ */
61
+ export async function loadQueue(instance) {
62
+ const wire = await instance.client.list('QueuedMessage');
63
+ return wire.map(queueMessageView);
64
+ }
@@ -41,6 +41,21 @@ export declare function withoutAlias(account: Pick<WireAccount, 'aliases'>, name
41
41
  * relies on.
42
42
  */
43
43
  export declare function withoutAppPassword(account: Pick<WireAccount, 'credentials'>, credentialId: string): Record<string, Credential>;
44
+ /**
45
+ * The `credentials` list to send so that one API key stops working and
46
+ * every other credential survives.
47
+ *
48
+ * The mirror image of `withoutAppPassword`'s type guard: an entry whose
49
+ * type is not `ApiKey` is not this action's to touch. `Password` is the
50
+ * account's own password; `AppPassword` is a person's, revoked by
51
+ * `withoutAppPassword`. This function's business is exactly the type that
52
+ * one refuses to touch.
53
+ *
54
+ * Surviving entries keep their masked secrets, which the server reads as
55
+ * "leave this one alone" — the behaviour `withPassword` documents and
56
+ * relies on.
57
+ */
58
+ export declare function withoutApiKey(account: Pick<WireAccount, 'credentials'>, credentialId: string): Record<string, Credential>;
44
59
  /**
45
60
  * The `Account` to create for a person, mirroring what
46
61
  * `scripts/mail-sync.mts` sends, minus the password.
@@ -60,3 +75,47 @@ export declare function newAccount(input: {
60
75
  /** Whether the domain delegates passwords to an external directory. */
61
76
  external: boolean;
62
77
  }): Record<string, unknown>;
78
+ /**
79
+ * A shared mailbox: `hr@`, `support@`, an address a team reads together
80
+ * rather than a person's own.
81
+ *
82
+ * On the server this is an account like any other — the same object, the
83
+ * same delivery, the same aliases — whose `@type` is `Group` instead of
84
+ * `User`. What makes it shared is on the *people*: an account naming this
85
+ * group in `memberGroupIds` reaches it with their own credential, as a
86
+ * second account in the same JMAP session. So a group is created empty here
87
+ * and filled by `addToGroup`.
88
+ *
89
+ * It takes no password and no `external` flag, unlike `newAccount`: nobody
90
+ * ever signs in as a shared mailbox, so there is no first secret to show
91
+ * once, and the question a personal mailbox has to ask — does this domain
92
+ * keep its own passwords — does not arise.
93
+ */
94
+ export declare function newGroup(input: {
95
+ local: string;
96
+ domainId: string;
97
+ description?: string | null;
98
+ }): Record<string, unknown>;
99
+ /**
100
+ * The `memberGroupIds` to send so that this account also reads `groupId`.
101
+ *
102
+ * **A membership map is a set, not a list.** The server sends and takes
103
+ * `{"<id>": true}`, and an entry whose value is not `true` is dropped on the
104
+ * way in, so what is sent is the whole surviving set — the same replace-the-
105
+ * lot rule as `aliases`, and the same reason these functions are worth
106
+ * testing.
107
+ *
108
+ * A duplicate is refused rather than sent, because sending it would report
109
+ * that somebody was added when the set was already exactly this.
110
+ */
111
+ export declare function withMembership(account: Pick<WireAccount, 'memberGroupIds'>, groupId: string): Record<string, boolean>;
112
+ /**
113
+ * The `memberGroupIds` to send so that this account no longer reads
114
+ * `groupId`. Refuses when the membership is absent, so a stale page cannot
115
+ * send the set back unchanged and report that it took access away.
116
+ */
117
+ export declare function withoutMembership(account: Pick<WireAccount, 'memberGroupIds'>, groupId: string): Record<string, boolean>;
118
+ /** The group ids on an account, in the order the server sent them. Only
119
+ * entries the server marked `true` count: it drops the others on read, so a
120
+ * write that kept them would add back what somebody just removed. */
121
+ export declare function membershipIds(account: Pick<WireAccount, 'memberGroupIds'>): string[];
@@ -94,6 +94,31 @@ export function withoutAppPassword(account, credentialId) {
94
94
  }
95
95
  return indexed(existing.filter((c) => c !== target));
96
96
  }
97
+ /**
98
+ * The `credentials` list to send so that one API key stops working and
99
+ * every other credential survives.
100
+ *
101
+ * The mirror image of `withoutAppPassword`'s type guard: an entry whose
102
+ * type is not `ApiKey` is not this action's to touch. `Password` is the
103
+ * account's own password; `AppPassword` is a person's, revoked by
104
+ * `withoutAppPassword`. This function's business is exactly the type that
105
+ * one refuses to touch.
106
+ *
107
+ * Surviving entries keep their masked secrets, which the server reads as
108
+ * "leave this one alone" — the behaviour `withPassword` documents and
109
+ * relies on.
110
+ */
111
+ export function withoutApiKey(account, credentialId) {
112
+ const existing = entriesOf(account.credentials);
113
+ const target = existing.find((c) => c.credentialId === credentialId);
114
+ if (!target) {
115
+ throw new MailWriteRefused('that credential is not on this mailbox any more');
116
+ }
117
+ if (target['@type'] !== 'ApiKey') {
118
+ throw new MailWriteRefused(`that credential is a ${target['@type']}, not an API key; only API keys are revoked here`);
119
+ }
120
+ return indexed(existing.filter((c) => c !== target));
121
+ }
97
122
  /**
98
123
  * The `Account` to create for a person, mirroring what
99
124
  * `scripts/mail-sync.mts` sends, minus the password.
@@ -129,3 +154,84 @@ export function newAccount(input) {
129
154
  memberGroupIds: {},
130
155
  };
131
156
  }
157
+ /**
158
+ * A shared mailbox: `hr@`, `support@`, an address a team reads together
159
+ * rather than a person's own.
160
+ *
161
+ * On the server this is an account like any other — the same object, the
162
+ * same delivery, the same aliases — whose `@type` is `Group` instead of
163
+ * `User`. What makes it shared is on the *people*: an account naming this
164
+ * group in `memberGroupIds` reaches it with their own credential, as a
165
+ * second account in the same JMAP session. So a group is created empty here
166
+ * and filled by `addToGroup`.
167
+ *
168
+ * It takes no password and no `external` flag, unlike `newAccount`: nobody
169
+ * ever signs in as a shared mailbox, so there is no first secret to show
170
+ * once, and the question a personal mailbox has to ask — does this domain
171
+ * keep its own passwords — does not arise.
172
+ */
173
+ export function newGroup(input) {
174
+ const local = input.local.trim().toLowerCase();
175
+ if (!local)
176
+ throw new MailWriteRefused('a shared mailbox needs a name');
177
+ if (local.includes('@')) {
178
+ throw new MailWriteRefused(`"${input.local}" looks like a whole address; a mailbox is named by its local part`);
179
+ }
180
+ return {
181
+ '@type': 'Group',
182
+ name: local,
183
+ domainId: input.domainId,
184
+ description: input.description ?? null,
185
+ roles: { '@type': 'Default' },
186
+ permissions: { '@type': 'Inherit' },
187
+ quotas: {},
188
+ aliases: {},
189
+ };
190
+ }
191
+ /**
192
+ * The `memberGroupIds` to send so that this account also reads `groupId`.
193
+ *
194
+ * **A membership map is a set, not a list.** The server sends and takes
195
+ * `{"<id>": true}`, and an entry whose value is not `true` is dropped on the
196
+ * way in, so what is sent is the whole surviving set — the same replace-the-
197
+ * lot rule as `aliases`, and the same reason these functions are worth
198
+ * testing.
199
+ *
200
+ * A duplicate is refused rather than sent, because sending it would report
201
+ * that somebody was added when the set was already exactly this.
202
+ */
203
+ export function withMembership(account, groupId) {
204
+ const wanted = groupId.trim();
205
+ if (!wanted)
206
+ throw new MailWriteRefused('a membership needs a shared mailbox to name');
207
+ const existing = membershipIds(account);
208
+ if (existing.includes(wanted)) {
209
+ throw new MailWriteRefused('this person already reads that shared mailbox');
210
+ }
211
+ return asSet([...existing, wanted]);
212
+ }
213
+ /**
214
+ * The `memberGroupIds` to send so that this account no longer reads
215
+ * `groupId`. Refuses when the membership is absent, so a stale page cannot
216
+ * send the set back unchanged and report that it took access away.
217
+ */
218
+ export function withoutMembership(account, groupId) {
219
+ const wanted = groupId.trim();
220
+ const existing = membershipIds(account);
221
+ const kept = existing.filter((id) => id !== wanted);
222
+ if (kept.length === existing.length) {
223
+ throw new MailWriteRefused('this person does not read that shared mailbox');
224
+ }
225
+ return asSet(kept);
226
+ }
227
+ /** The group ids on an account, in the order the server sent them. Only
228
+ * entries the server marked `true` count: it drops the others on read, so a
229
+ * write that kept them would add back what somebody just removed. */
230
+ export function membershipIds(account) {
231
+ return Object.entries(account.memberGroupIds ?? {})
232
+ .filter(([, on]) => on === true)
233
+ .map(([id]) => id);
234
+ }
235
+ function asSet(ids) {
236
+ return Object.fromEntries(ids.map((id) => [id, true]));
237
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wtfalch/email",
3
- "version": "0.13.1",
3
+ "version": "0.14.0",
4
4
  "description": "The wtfalch estate: reading a mailbox over JMAP, and administering the Stalwart server it lives on. Two entries with no code in common.",
5
5
  "license": "MIT",
6
6
  "type": "module",