@wtfalch/email 0.13.0 → 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.
- package/README.md +66 -4
- package/dist/mailbox/client.d.ts +22 -1
- package/dist/mailbox/client.js +45 -0
- package/dist/mailbox/fake/mailbox.js +205 -5
- package/dist/mailbox/index.d.ts +11 -7
- package/dist/mailbox/index.js +5 -3
- package/dist/mailbox/mail.css +13 -0
- package/dist/mailbox/mailboxes.d.ts +95 -1
- package/dist/mailbox/mailboxes.js +243 -1
- package/dist/mailbox/mutate.d.ts +21 -0
- package/dist/mailbox/mutate.js +71 -0
- package/dist/mailbox/quoted.d.ts +94 -0
- package/dist/mailbox/quoted.js +158 -0
- package/dist/mailbox/react/Composer.js +13 -1
- package/dist/mailbox/react/Mail.js +273 -33
- package/dist/mailbox/react/ThreadView.d.ts +13 -1
- package/dist/mailbox/react/ThreadView.js +5 -4
- package/dist/mailbox/react/index.d.ts +3 -1
- package/dist/mailbox/react/index.js +2 -1
- package/dist/mailbox/react/layout.d.ts +13 -8
- package/dist/mailbox/react/layout.js +36 -7
- package/dist/mailbox/react/quotedHtml.d.ts +105 -0
- package/dist/mailbox/react/quotedHtml.js +163 -0
- package/dist/mailbox/snooze.d.ts +48 -0
- package/dist/mailbox/snooze.js +176 -0
- package/dist/mailbox/submit.d.ts +26 -0
- package/dist/mailbox/submit.js +88 -7
- package/dist/mailbox/threads.js +2 -0
- package/dist/mailbox/types.d.ts +40 -0
- package/dist/postmaster/apply.d.ts +154 -1
- package/dist/postmaster/apply.js +336 -1
- package/dist/postmaster/audit.d.ts +22 -1
- package/dist/postmaster/audit.js +7 -0
- package/dist/postmaster/client.d.ts +49 -0
- package/dist/postmaster/client.js +43 -0
- package/dist/postmaster/index.d.ts +4 -3
- package/dist/postmaster/index.js +3 -2
- package/dist/postmaster/objects.js +11 -0
- package/dist/postmaster/overview.d.ts +4 -0
- package/dist/postmaster/queue.d.ts +111 -0
- package/dist/postmaster/queue.js +64 -0
- package/dist/postmaster/writes.d.ts +59 -0
- package/dist/postmaster/writes.js +106 -0
- package/package.json +1 -1
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import { JAM_FETCH } from "./client.js";
|
|
2
|
+
import { MailError, guard } from "./errors.js";
|
|
3
|
+
import { findRole, mailboxes } from "./mailboxes.js";
|
|
4
|
+
/**
|
|
5
|
+
* Snooze: take a thread out of the Inbox until a time, then put it back.
|
|
6
|
+
*
|
|
7
|
+
* **JMAP has no snooze, so this is two halves.** `snoozeThread` moves the
|
|
8
|
+
* thread into a top-level mailbox named Snoozed (made on first use) and
|
|
9
|
+
* stamps each message with a keyword holding the wake time.
|
|
10
|
+
* `wakeSnoozed` moves every thread whose time has come back to the Inbox,
|
|
11
|
+
* unread. Nothing in a mail server calls `wakeSnoozed`; the host runs it on
|
|
12
|
+
* a timer. That is the part of snooze that is server work, and a library
|
|
13
|
+
* cannot own a clock.
|
|
14
|
+
*
|
|
15
|
+
* **The wake time is a keyword, `$snoozed:<unix seconds>`.** A message has
|
|
16
|
+
* no free-form property to hold a date, and a keyword is stored, searchable
|
|
17
|
+
* and survives every client. RFC 8621 keywords may contain `:` and digits.
|
|
18
|
+
*/
|
|
19
|
+
/** The name the Snoozed mailbox is found and made by. */
|
|
20
|
+
export const SNOOZED_MAILBOX = 'Snoozed';
|
|
21
|
+
const WAKE = '$snoozed:';
|
|
22
|
+
/** RFC 6901 §3: `~` and `/` inside a pointer segment are escaped. A keyword
|
|
23
|
+
* read back from the server may hold either, so a patch key built from one
|
|
24
|
+
* must escape. */
|
|
25
|
+
function pointer(segment) {
|
|
26
|
+
return segment.replaceAll('~', '~0').replaceAll('/', '~1');
|
|
27
|
+
}
|
|
28
|
+
function wakeKeyword(until) {
|
|
29
|
+
return `${WAKE}${Math.floor(until.getTime() / 1000)}`;
|
|
30
|
+
}
|
|
31
|
+
/** The wake time a message carries, in milliseconds, or `null`. */
|
|
32
|
+
function wakeTime(keywords) {
|
|
33
|
+
for (const keyword of Object.keys(keywords ?? {})) {
|
|
34
|
+
if (!keyword.startsWith(WAKE))
|
|
35
|
+
continue;
|
|
36
|
+
const seconds = Number(keyword.slice(WAKE.length));
|
|
37
|
+
if (Number.isInteger(seconds))
|
|
38
|
+
return seconds * 1000;
|
|
39
|
+
}
|
|
40
|
+
return null;
|
|
41
|
+
}
|
|
42
|
+
function refused(result, operation) {
|
|
43
|
+
const notUpdated = result.notUpdated;
|
|
44
|
+
const first = notUpdated ? Object.values(notUpdated)[0] : undefined;
|
|
45
|
+
if (first) {
|
|
46
|
+
throw new MailError(first.description ?? `the server refused to ${operation}`, {
|
|
47
|
+
type: first.type ?? 'unknown',
|
|
48
|
+
operation,
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
function findSnoozed(tree) {
|
|
53
|
+
return tree.find((box) => box.name === SNOOZED_MAILBOX && box.parentId === null);
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Snooze a thread until `until`: out of every mailbox, into Snoozed.
|
|
57
|
+
*
|
|
58
|
+
* Messages in Sent or Drafts stay where they are. They are my own copies,
|
|
59
|
+
* not mail waiting for me, and waking files into the Inbox: a sent reply
|
|
60
|
+
* moved into Snoozed would come back as if it had been received.
|
|
61
|
+
*
|
|
62
|
+
* Snoozing a thread that is already snoozed moves its wake time; the old
|
|
63
|
+
* one is removed rather than left beside it. A time in the past is allowed
|
|
64
|
+
* and simply wakes on the next `wakeSnoozed`, since what "now" is belongs
|
|
65
|
+
* to the host's clock, not this call's.
|
|
66
|
+
*
|
|
67
|
+
* Returns the ids of the messages that moved.
|
|
68
|
+
*/
|
|
69
|
+
export async function snoozeThread(client, threadId, until, options = {}) {
|
|
70
|
+
if (Number.isNaN(until.getTime())) {
|
|
71
|
+
throw new MailError('snooze needs a valid date', {
|
|
72
|
+
type: 'invalidArguments',
|
|
73
|
+
operation: 'snooze',
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
const { jam, accountId } = await client.connect();
|
|
77
|
+
const tree = options.mailboxes ?? (await mailboxes(client));
|
|
78
|
+
return guard('snooze', async () => {
|
|
79
|
+
let snoozedId = findSnoozed(tree)?.id;
|
|
80
|
+
if (!snoozedId) {
|
|
81
|
+
const [made] = await jam.api.Mailbox.set({ accountId, create: { snoozed: { name: SNOOZED_MAILBOX, parentId: null } } }, JAM_FETCH);
|
|
82
|
+
snoozedId = made.created?.snoozed?.id;
|
|
83
|
+
if (!snoozedId) {
|
|
84
|
+
const failure = Object.values((made.notCreated ?? {}))[0];
|
|
85
|
+
throw new MailError(failure?.description ?? 'the server would not make a Snoozed mailbox', {
|
|
86
|
+
type: failure?.type ?? 'unknown',
|
|
87
|
+
operation: 'snooze',
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
const [thread] = await jam.api.Thread.get({ accountId, ids: [threadId] }, JAM_FETCH);
|
|
92
|
+
const ids = thread.list?.[0]?.emailIds ?? [];
|
|
93
|
+
if (ids.length === 0) {
|
|
94
|
+
throw new MailError(`no thread ${threadId} on this account`, {
|
|
95
|
+
type: 'notFound',
|
|
96
|
+
operation: 'snooze',
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
const [found] = await jam.api.Email.get({ accountId, ids, properties: ['keywords', 'mailboxIds'] }, JAM_FETCH);
|
|
100
|
+
const mine = new Set([findRole(tree, 'sent')?.id, findRole(tree, 'drafts')?.id]);
|
|
101
|
+
const moving = [];
|
|
102
|
+
const stale = new Set();
|
|
103
|
+
for (const email of found.list) {
|
|
104
|
+
if (Object.keys(email.mailboxIds ?? {}).some((box) => mine.has(box)))
|
|
105
|
+
continue;
|
|
106
|
+
moving.push(email.id);
|
|
107
|
+
for (const keyword of Object.keys(email.keywords ?? {})) {
|
|
108
|
+
if (keyword.startsWith(WAKE))
|
|
109
|
+
stale.add(keyword);
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
if (moving.length === 0)
|
|
113
|
+
return [];
|
|
114
|
+
const patch = { mailboxIds: { [snoozedId]: true } };
|
|
115
|
+
for (const keyword of stale)
|
|
116
|
+
patch[`keywords/${pointer(keyword)}`] = null;
|
|
117
|
+
patch[`keywords/${pointer(wakeKeyword(until))}`] = true;
|
|
118
|
+
const update = {};
|
|
119
|
+
for (const id of moving)
|
|
120
|
+
update[id] = patch;
|
|
121
|
+
const [result] = await jam.api.Email.set({ accountId, update: update }, JAM_FETCH);
|
|
122
|
+
refused(result, 'snooze');
|
|
123
|
+
return moving;
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Wake every snoozed thread whose time is at or before `now`: back to the
|
|
128
|
+
* Inbox, unread, wake time removed.
|
|
129
|
+
*
|
|
130
|
+
* Meant for a timer the host runs, every minute or so. `now` is a
|
|
131
|
+
* parameter so the host's clock decides, and a test can pass its own.
|
|
132
|
+
* Returns the ids of the threads that woke; an account that has never
|
|
133
|
+
* snoozed anything returns none without making a mailbox.
|
|
134
|
+
*/
|
|
135
|
+
export async function wakeSnoozed(client, now = new Date(), options = {}) {
|
|
136
|
+
const { jam, accountId } = await client.connect();
|
|
137
|
+
const tree = options.mailboxes ?? (await mailboxes(client));
|
|
138
|
+
const snoozed = findSnoozed(tree);
|
|
139
|
+
if (!snoozed)
|
|
140
|
+
return [];
|
|
141
|
+
const inbox = findRole(tree, 'inbox');
|
|
142
|
+
if (!inbox) {
|
|
143
|
+
throw new MailError('the account has no Inbox to wake mail into', {
|
|
144
|
+
type: 'notFound',
|
|
145
|
+
operation: 'wake',
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
return guard('wake', async () => {
|
|
149
|
+
const [query] = await jam.api.Email.query({ accountId, filter: { inMailbox: snoozed.id } }, JAM_FETCH);
|
|
150
|
+
if (query.ids.length === 0)
|
|
151
|
+
return [];
|
|
152
|
+
const [found] = await jam.api.Email.get({ accountId, ids: query.ids, properties: ['threadId', 'keywords'] }, JAM_FETCH);
|
|
153
|
+
const update = {};
|
|
154
|
+
const woke = new Set();
|
|
155
|
+
for (const email of found.list) {
|
|
156
|
+
const at = wakeTime(email.keywords);
|
|
157
|
+
if (at === null || at > now.getTime())
|
|
158
|
+
continue;
|
|
159
|
+
const patch = {
|
|
160
|
+
mailboxIds: { [inbox.id]: true },
|
|
161
|
+
'keywords/$seen': null,
|
|
162
|
+
};
|
|
163
|
+
for (const keyword of Object.keys(email.keywords ?? {})) {
|
|
164
|
+
if (keyword.startsWith(WAKE))
|
|
165
|
+
patch[`keywords/${pointer(keyword)}`] = null;
|
|
166
|
+
}
|
|
167
|
+
update[email.id] = patch;
|
|
168
|
+
woke.add(email.threadId);
|
|
169
|
+
}
|
|
170
|
+
if (woke.size === 0)
|
|
171
|
+
return [];
|
|
172
|
+
const [result] = await jam.api.Email.set({ accountId, update: update }, JAM_FETCH);
|
|
173
|
+
refused(result, 'wake');
|
|
174
|
+
return [...woke];
|
|
175
|
+
});
|
|
176
|
+
}
|
package/dist/mailbox/submit.d.ts
CHANGED
|
@@ -29,12 +29,38 @@ export type SendOptions = {
|
|
|
29
29
|
* byte-identical to a plain send. Travels as RFC 4865's `holdFor` SMTP
|
|
30
30
|
* parameter, which the server validates as 1..=999999999. */
|
|
31
31
|
delay?: number;
|
|
32
|
+
/** A draft `saveDraft()` stored. It is replaced by the message sent, so
|
|
33
|
+
* Drafts is left without it. What goes out is always the `Draft` passed
|
|
34
|
+
* to `send()`, never what was last saved. */
|
|
35
|
+
draftId?: string;
|
|
36
|
+
};
|
|
37
|
+
export type SaveDraftOptions = {
|
|
38
|
+
/** The identity to fill `from` with, when the caller already has it. */
|
|
39
|
+
identity?: MailIdentity;
|
|
40
|
+
/** The mailbox tree, when the caller already has it. */
|
|
41
|
+
mailboxes?: readonly MailboxNode[];
|
|
32
42
|
};
|
|
33
43
|
export type CancelOptions = {
|
|
34
44
|
/** The mailbox tree, when the caller already has it. Saves a
|
|
35
45
|
* `Mailbox/get`. */
|
|
36
46
|
mailboxes?: readonly MailboxNode[];
|
|
37
47
|
};
|
|
48
|
+
/**
|
|
49
|
+
* Store a draft in Drafts, so it survives the compose sheet closing.
|
|
50
|
+
*
|
|
51
|
+
* Called with the id it returned last time, it replaces that draft rather
|
|
52
|
+
* than adding a second. RFC 8621 messages are immutable, so "replace" is a
|
|
53
|
+
* create followed by a destroy; the id changes every save,
|
|
54
|
+
* which is why the new one is returned. The thread does not change, because
|
|
55
|
+
* the draft keeps its `inReplyTo` and `references`.
|
|
56
|
+
*
|
|
57
|
+
* `from` is filled from the identity when the draft has none, as `send()`
|
|
58
|
+
* does, so a saved draft reads the same as the message it becomes.
|
|
59
|
+
*/
|
|
60
|
+
export declare function saveDraft(client: MailClient, draft: Draft, draftId?: string, options?: SaveDraftOptions): Promise<{
|
|
61
|
+
id: string;
|
|
62
|
+
threadId: string;
|
|
63
|
+
}>;
|
|
38
64
|
/**
|
|
39
65
|
* Send a draft.
|
|
40
66
|
*
|
package/dist/mailbox/submit.js
CHANGED
|
@@ -47,6 +47,54 @@ function checkDelay(delay) {
|
|
|
47
47
|
* Without an envelope the server derives recipients from the headers, but
|
|
48
48
|
* it strips the Bcc header before delivery, so a delayed send has to list
|
|
49
49
|
* every recipient explicitly here or the blind ones are silently dropped. */
|
|
50
|
+
/**
|
|
51
|
+
* Refuse to replace anything that is not a draft.
|
|
52
|
+
*
|
|
53
|
+
* Replacing is a destroy, and an id is only a string: a caller that passed a
|
|
54
|
+
* received message's id by mistake would delete it for good. So the id is
|
|
55
|
+
* read first, and anything without `$draft` is refused. An id that no longer
|
|
56
|
+
* exists is allowed through: the old draft is already gone, which is what
|
|
57
|
+
* replacing it wanted.
|
|
58
|
+
*/
|
|
59
|
+
async function checkIsDraft(jam, accountId, draftId, operation) {
|
|
60
|
+
const [found] = await jam.api.Email.get({ accountId, ids: [draftId], properties: ['keywords'] }, JAM_FETCH);
|
|
61
|
+
const email = found.list?.[0];
|
|
62
|
+
if (email && !email.keywords?.$draft) {
|
|
63
|
+
throw new MailError(`${draftId} is not a draft, so it will not be replaced`, {
|
|
64
|
+
type: 'invalidArguments',
|
|
65
|
+
operation,
|
|
66
|
+
});
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
/** A replaced draft that could not be destroyed, other than because it was
|
|
70
|
+
* already gone. The new one exists, so the message says so. */
|
|
71
|
+
function checkReplaced(notDestroyed, draftId, savedAs, operation) {
|
|
72
|
+
const failure = notDestroyed?.[draftId];
|
|
73
|
+
if (!failure || failure.type === 'notFound')
|
|
74
|
+
return;
|
|
75
|
+
throw new MailError(`saved as ${savedAs}, but the earlier draft ${draftId} could not be removed: ${failure.description ?? failure.type}`, { type: failure.type ?? 'unknown', operation });
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Create `email` in Drafts, then destroy `draftId` if one was given.
|
|
79
|
+
*
|
|
80
|
+
* Two `Email/set` calls, not one. RFC 8620 §5.3 applies a create and a
|
|
81
|
+
* destroy in the same call independently, so a server may destroy the old
|
|
82
|
+
* draft while refusing the new one, and the draft would be lost. The destroy
|
|
83
|
+
* is only sent once the create has succeeded.
|
|
84
|
+
*/
|
|
85
|
+
async function createReplacing(jam, accountId, email, draftId, operation) {
|
|
86
|
+
if (draftId)
|
|
87
|
+
await checkIsDraft(jam, accountId, draftId, operation);
|
|
88
|
+
const [created] = await jam.api.Email.set({ accountId, create: { draft: email } }, JAM_FETCH);
|
|
89
|
+
const result = created.created?.draft;
|
|
90
|
+
if (!result)
|
|
91
|
+
failed('draft', created.notCreated);
|
|
92
|
+
if (draftId) {
|
|
93
|
+
const [destroyed] = await jam.api.Email.set({ accountId, destroy: [draftId] }, JAM_FETCH);
|
|
94
|
+
checkReplaced(destroyed.notDestroyed, draftId, result.id, operation);
|
|
95
|
+
}
|
|
96
|
+
return result;
|
|
97
|
+
}
|
|
50
98
|
function uniqueAddresses(addresses) {
|
|
51
99
|
const seen = new Set();
|
|
52
100
|
const result = [];
|
|
@@ -125,6 +173,44 @@ export function draftPatch(sentMailboxId, draftsMailboxId) {
|
|
|
125
173
|
'keywords/$seen': null,
|
|
126
174
|
};
|
|
127
175
|
}
|
|
176
|
+
/**
|
|
177
|
+
* Store a draft in Drafts, so it survives the compose sheet closing.
|
|
178
|
+
*
|
|
179
|
+
* Called with the id it returned last time, it replaces that draft rather
|
|
180
|
+
* than adding a second. RFC 8621 messages are immutable, so "replace" is a
|
|
181
|
+
* create followed by a destroy; the id changes every save,
|
|
182
|
+
* which is why the new one is returned. The thread does not change, because
|
|
183
|
+
* the draft keeps its `inReplyTo` and `references`.
|
|
184
|
+
*
|
|
185
|
+
* `from` is filled from the identity when the draft has none, as `send()`
|
|
186
|
+
* does, so a saved draft reads the same as the message it becomes.
|
|
187
|
+
*/
|
|
188
|
+
export async function saveDraft(client, draft, draftId, options = {}) {
|
|
189
|
+
const { jam, accountId } = await client.connect();
|
|
190
|
+
const tree = options.mailboxes ?? (await mailboxes(client));
|
|
191
|
+
const drafts = findRole(tree, 'drafts');
|
|
192
|
+
if (!drafts) {
|
|
193
|
+
throw new MailError('the account has no Drafts mailbox to save in', {
|
|
194
|
+
type: 'notFound',
|
|
195
|
+
operation: 'save draft',
|
|
196
|
+
});
|
|
197
|
+
}
|
|
198
|
+
let from = draft.from;
|
|
199
|
+
if (!from || from.length === 0) {
|
|
200
|
+
const identity = options.identity ?? (await identities(client)).find((one) => one.id === draft.identityId);
|
|
201
|
+
if (!identity) {
|
|
202
|
+
throw new MailError(`no identity ${draft.identityId} on this account`, {
|
|
203
|
+
type: 'notFound',
|
|
204
|
+
operation: 'save draft',
|
|
205
|
+
});
|
|
206
|
+
}
|
|
207
|
+
from = [{ name: identity.name, email: identity.email }];
|
|
208
|
+
}
|
|
209
|
+
return guard('save draft', async () => {
|
|
210
|
+
const email = await createReplacing(jam, accountId, draftToEmail(draft, from, drafts.id), draftId, 'save draft');
|
|
211
|
+
return { id: email.id, threadId: email.threadId };
|
|
212
|
+
});
|
|
213
|
+
}
|
|
128
214
|
/**
|
|
129
215
|
* Send a draft.
|
|
130
216
|
*
|
|
@@ -187,14 +273,9 @@ export async function send(client, draft, options = {}) {
|
|
|
187
273
|
rcptTo: uniqueAddresses([...draft.to, ...(draft.cc ?? []), ...(draft.bcc ?? [])]),
|
|
188
274
|
}
|
|
189
275
|
: undefined;
|
|
276
|
+
const { draftId } = options;
|
|
190
277
|
return guard('send', async () => {
|
|
191
|
-
const
|
|
192
|
-
accountId,
|
|
193
|
-
create: { draft: draftToEmail(draft, from, drafts.id) },
|
|
194
|
-
}, JAM_FETCH);
|
|
195
|
-
const email = created.created?.draft;
|
|
196
|
-
if (!email)
|
|
197
|
-
failed('draft', created.notCreated);
|
|
278
|
+
const email = await createReplacing(jam, accountId, draftToEmail(draft, from, drafts.id), draftId, 'send');
|
|
198
279
|
const [submitted] = await jam.api.EmailSubmission.set({
|
|
199
280
|
accountId,
|
|
200
281
|
create: {
|
package/dist/mailbox/threads.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { JAM_FETCH } from "./client.js";
|
|
2
2
|
import { guard } from "./errors.js";
|
|
3
|
+
import { labelsOf } from "./mutate.js";
|
|
3
4
|
/** What a list row needs from the newest message in each thread. */
|
|
4
5
|
const SUMMARY_PROPERTIES = [
|
|
5
6
|
'id',
|
|
@@ -76,6 +77,7 @@ export function summarise(threadId, latest, members) {
|
|
|
76
77
|
hasAttachment: all.some((message) => message.hasAttachment === true),
|
|
77
78
|
isFlagged: all.some((message) => keywords(message, '$flagged')),
|
|
78
79
|
isDraft: keywords(latest, '$draft'),
|
|
80
|
+
labels: [...new Set(all.flatMap((message) => labelsOf(message.keywords)))].sort(),
|
|
79
81
|
mailboxIds: [...mailboxIds],
|
|
80
82
|
};
|
|
81
83
|
}
|
package/dist/mailbox/types.d.ts
CHANGED
|
@@ -27,6 +27,10 @@ export type MailSession = {
|
|
|
27
27
|
accountId: string;
|
|
28
28
|
/** The account's display name. */
|
|
29
29
|
accountName: string;
|
|
30
|
+
/** False when the account being read is not this login's own: a shared
|
|
31
|
+
* mailbox it is a member of, or one an ACL granted it. A composer can say
|
|
32
|
+
* which mailbox a reply will come from rather than assuming "me". */
|
|
33
|
+
isPersonal: boolean;
|
|
30
34
|
isReadOnly: boolean;
|
|
31
35
|
/** True when the account may submit mail, so a composer can be hidden
|
|
32
36
|
* rather than failing at send. */
|
|
@@ -39,6 +43,32 @@ export type MailSession = {
|
|
|
39
43
|
* not say, which RFC 8621 permits. */
|
|
40
44
|
maxSizeAttachmentsPerEmail: number | null;
|
|
41
45
|
};
|
|
46
|
+
/**
|
|
47
|
+
* One mailbox a login can read, as the session document names it.
|
|
48
|
+
*
|
|
49
|
+
* A person reaches more than their own mailbox whenever they belong to a
|
|
50
|
+
* shared one: the server puts every group the account is a member of, and
|
|
51
|
+
* everything an ACL grants it, into the same session alongside the personal
|
|
52
|
+
* account. Which one this package reads is fixed when the client is built
|
|
53
|
+
* (`MailClientOptions.accountId`), so an app that wants a switcher reads this
|
|
54
|
+
* list and builds a client per mailbox.
|
|
55
|
+
*/
|
|
56
|
+
export type MailAccount = {
|
|
57
|
+
id: string;
|
|
58
|
+
/** The display name the server gives the account, usually its address. */
|
|
59
|
+
name: string;
|
|
60
|
+
/** False for a shared mailbox. */
|
|
61
|
+
isPersonal: boolean;
|
|
62
|
+
isReadOnly: boolean;
|
|
63
|
+
/** Whether mail can be sent from this account, so a shared mailbox that is
|
|
64
|
+
* read-only to this person does not offer a composer. */
|
|
65
|
+
maySubmit: boolean;
|
|
66
|
+
};
|
|
67
|
+
/** RFC 8621 §2's ten mailbox rights: what a login may do on one mailbox,
|
|
68
|
+
* its own or one shared with it. */
|
|
69
|
+
export type MailboxRight = 'mayReadItems' | 'mayAddItems' | 'mayRemoveItems' | 'maySetSeen' | 'maySetKeywords' | 'mayCreateChild' | 'mayRename' | 'maySubmit' | 'mayDelete' | 'mayShare';
|
|
70
|
+
/** Every right, each either granted or not. */
|
|
71
|
+
export type MailboxRights = Readonly<Record<MailboxRight, boolean>>;
|
|
42
72
|
/** A mailbox with its children, as the tree the server's flat list describes. */
|
|
43
73
|
export type MailboxNode = {
|
|
44
74
|
id: string;
|
|
@@ -51,6 +81,13 @@ export type MailboxNode = {
|
|
|
51
81
|
totalThreads: number;
|
|
52
82
|
unreadThreads: number;
|
|
53
83
|
isSubscribed: boolean;
|
|
84
|
+
/** What this login may do here — always present; the server derives it
|
|
85
|
+
* from ownership plus whatever `shareWith` grants. */
|
|
86
|
+
myRights: MailboxRights;
|
|
87
|
+
/** Every account this mailbox has been shared with, and the rights each
|
|
88
|
+
* was given. Empty when nobody but the owner can reach it. Keyed by
|
|
89
|
+
* account id, the same id `MailAccount.id` and `client.accounts()` use. */
|
|
90
|
+
shareWith: Readonly<Record<string, MailboxRights>>;
|
|
54
91
|
/** The names from the root down to and including this one, e.g.
|
|
55
92
|
* `['Archive', '2026']`. A stable label, and a sort key. */
|
|
56
93
|
path: readonly string[];
|
|
@@ -77,6 +114,9 @@ export type ThreadSummary = {
|
|
|
77
114
|
hasAttachment: boolean;
|
|
78
115
|
isFlagged: boolean;
|
|
79
116
|
isDraft: boolean;
|
|
117
|
+
/** Labels on any of the thread's messages, lowercase and sorted (see
|
|
118
|
+
* `setLabel`). */
|
|
119
|
+
labels: readonly string[];
|
|
80
120
|
/** Every mailbox the thread's messages sit in. */
|
|
81
121
|
mailboxIds: readonly string[];
|
|
82
122
|
};
|
|
@@ -2,7 +2,7 @@ import type { PostmasterAudit } from './audit.js';
|
|
|
2
2
|
import type { Instance } from './instance.js';
|
|
3
3
|
export interface Applied {
|
|
4
4
|
/** For the audit row's `targetType`. */
|
|
5
|
-
readonly targetType: 'mailbox' | 'mail_alias' | 'mail_app_password' | 'mail_settings';
|
|
5
|
+
readonly targetType: 'mailbox' | 'mail_group' | 'mail_group_member' | 'mail_alias' | 'mail_app_password' | 'mail_api_key' | 'mail_settings' | 'mail_queue_message';
|
|
6
6
|
/** For its `targetId`: the address or the credential, never a secret. */
|
|
7
7
|
readonly targetId: string;
|
|
8
8
|
readonly before: unknown;
|
|
@@ -23,6 +23,51 @@ export declare function createMailbox(instance: Instance, input: {
|
|
|
23
23
|
description?: string | null;
|
|
24
24
|
external: boolean;
|
|
25
25
|
}, audit?: PostmasterAudit): Promise<Applied>;
|
|
26
|
+
/**
|
|
27
|
+
* Make a shared mailbox — one address a team reads together, each with their
|
|
28
|
+
* own login.
|
|
29
|
+
*
|
|
30
|
+
* The same duplicate check as `createMailbox`, and against the same accounts:
|
|
31
|
+
* a group and a person compete for one local part, because both are accounts
|
|
32
|
+
* and mail to the address goes to exactly one of them.
|
|
33
|
+
*
|
|
34
|
+
* It is created empty. Nobody reads it until `addToGroup` names somebody,
|
|
35
|
+
* which is also why this needs no password: a shared mailbox is never signed
|
|
36
|
+
* in to.
|
|
37
|
+
*/
|
|
38
|
+
export declare function createGroupMailbox(instance: Instance, input: {
|
|
39
|
+
local: string;
|
|
40
|
+
domainId: string;
|
|
41
|
+
apex: string;
|
|
42
|
+
description?: string | null;
|
|
43
|
+
}, audit?: PostmasterAudit): Promise<Applied>;
|
|
44
|
+
/**
|
|
45
|
+
* Let somebody read a shared mailbox, with their own login.
|
|
46
|
+
*
|
|
47
|
+
* The membership is written on the *person*, not on the mailbox: Stalwart
|
|
48
|
+
* turns an account's `memberGroupIds` into secondary accounts on that
|
|
49
|
+
* person's session, which is how `hr@` appears beside their own mail.
|
|
50
|
+
*
|
|
51
|
+
* Both accounts are re-read first, and both are confined to the domain the
|
|
52
|
+
* caller resolved — the same reason every other write here re-reads. The
|
|
53
|
+
* group is read as well as the person because a membership naming an account
|
|
54
|
+
* that is not a shared mailbox would be accepted by the server and mean
|
|
55
|
+
* nothing.
|
|
56
|
+
*/
|
|
57
|
+
export declare function addToGroup(instance: Instance, input: {
|
|
58
|
+
accountId: string;
|
|
59
|
+
groupId: string;
|
|
60
|
+
domainId: string;
|
|
61
|
+
apex: string;
|
|
62
|
+
}, audit?: PostmasterAudit): Promise<Applied>;
|
|
63
|
+
/** Take a shared mailbox away from somebody. Their own mail is untouched:
|
|
64
|
+
* this removes the membership, not the account. */
|
|
65
|
+
export declare function removeFromGroup(instance: Instance, input: {
|
|
66
|
+
accountId: string;
|
|
67
|
+
groupId: string;
|
|
68
|
+
domainId: string;
|
|
69
|
+
apex: string;
|
|
70
|
+
}, audit?: PostmasterAudit): Promise<Applied>;
|
|
26
71
|
export declare function addAlias(instance: Instance, input: {
|
|
27
72
|
accountId: string;
|
|
28
73
|
name: string;
|
|
@@ -60,6 +105,30 @@ export declare function revokeAppPassword(instance: Instance, input: {
|
|
|
60
105
|
domainId: string;
|
|
61
106
|
apex: string;
|
|
62
107
|
}, audit?: PostmasterAudit): Promise<Applied>;
|
|
108
|
+
/**
|
|
109
|
+
* Stop one API key working. The secret is never read, here or anywhere
|
|
110
|
+
* else: the entry is identified by its id and the surviving entries go back
|
|
111
|
+
* with the masked secrets the server sent, which it reads as "leave these
|
|
112
|
+
* alone".
|
|
113
|
+
*
|
|
114
|
+
* **Never on the account the acting credential belongs to.** Every API key
|
|
115
|
+
* this package mints (`StalwartClient.createApiKey`) is as powerful as the
|
|
116
|
+
* whole account it was minted for, and this app itself may be authenticated
|
|
117
|
+
* as one — carrying no account name, so `revokeAppPassword`'s
|
|
118
|
+
* `isOurOwnAccount` cannot see it (`instance.user` is `null` for an
|
|
119
|
+
* `ApiKey`). `isCallersOwnAccount` asks the server instead, over a fresh
|
|
120
|
+
* `GET /jmap/session` made with this same credential, and refuses to touch
|
|
121
|
+
* *any* credential on the account it names back — the whole account, not
|
|
122
|
+
* only the literal key in use, the same width `revokeAppPassword` blocks
|
|
123
|
+
* for the administrator's app passwords, because a second key left on that
|
|
124
|
+
* account is still this panel's own way back in.
|
|
125
|
+
*/
|
|
126
|
+
export declare function revokeApiKey(instance: Instance, input: {
|
|
127
|
+
accountId: string;
|
|
128
|
+
credentialId: string;
|
|
129
|
+
domainId: string;
|
|
130
|
+
apex: string;
|
|
131
|
+
}, audit?: PostmasterAudit): Promise<Applied>;
|
|
63
132
|
/**
|
|
64
133
|
* How long this instance will hold a message before sending it, as the
|
|
65
134
|
* server's own duration (`'30d'`), or `null` when it will not hold one at
|
|
@@ -84,3 +153,87 @@ export declare function holdLimit(instance: Instance): Promise<string | null>;
|
|
|
84
153
|
* server now says.
|
|
85
154
|
*/
|
|
86
155
|
export declare function enableHolding(instance: Instance, audit?: PostmasterAudit): Promise<Applied>;
|
|
156
|
+
export interface SpamSettingsView {
|
|
157
|
+
readonly enabled: boolean;
|
|
158
|
+
/** Mail from an address in the recipient's own contacts skips scoring. */
|
|
159
|
+
readonly trustContacts: boolean;
|
|
160
|
+
/** A reply to a thread the account started skips scoring. */
|
|
161
|
+
readonly trustReplies: boolean;
|
|
162
|
+
/** How long a first-time sender is held before being let through, in
|
|
163
|
+
* milliseconds. `null` for no greylisting. */
|
|
164
|
+
readonly greylistForMs: number | null;
|
|
165
|
+
/** The score at and above which a message is tagged spam. */
|
|
166
|
+
readonly scoreSpam: number;
|
|
167
|
+
/** The score at and above which a message is silently discarded. */
|
|
168
|
+
readonly scoreDiscard: number;
|
|
169
|
+
/** The score at and above which a message is rejected at SMTP time. */
|
|
170
|
+
readonly scoreReject: number;
|
|
171
|
+
/** A URL the server pulls extra scoring rules from. `null` for none. */
|
|
172
|
+
readonly rulesUrl: string | null;
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* Whether this instance filters spam at all, and where its thresholds sit.
|
|
176
|
+
* Every tenant's mail gets whatever this singleton says until a caller
|
|
177
|
+
* changes it -- there is no per-mailbox override in Stalwart 0.16.
|
|
178
|
+
*/
|
|
179
|
+
export declare function spamSettings(instance: Instance): Promise<SpamSettingsView>;
|
|
180
|
+
export interface SpamSettingsInput {
|
|
181
|
+
enabled?: boolean;
|
|
182
|
+
trustContacts?: boolean;
|
|
183
|
+
trustReplies?: boolean;
|
|
184
|
+
greylistForMs?: number | null;
|
|
185
|
+
scoreSpam?: number;
|
|
186
|
+
scoreDiscard?: number;
|
|
187
|
+
scoreReject?: number;
|
|
188
|
+
rulesUrl?: string | null;
|
|
189
|
+
}
|
|
190
|
+
/**
|
|
191
|
+
* Change baseline spam control for every mailbox this instance serves:
|
|
192
|
+
* whether filtering runs at all, the three score thresholds, whether a
|
|
193
|
+
* contact or a reply skips scoring, greylisting, and the extra-rules URL.
|
|
194
|
+
*
|
|
195
|
+
* **The reload is not optional**, for the same reason `enableHolding`'s
|
|
196
|
+
* is not: Stalwart applies a changed setting only after a `ReloadSettings`
|
|
197
|
+
* action, and a write without one is stored but inert until the next
|
|
198
|
+
* restart. `before`/`after` are both read fresh, so what is recorded is
|
|
199
|
+
* what the server now actually enforces.
|
|
200
|
+
*
|
|
201
|
+
* Every field is checked before the wire: a non-finite score is refused
|
|
202
|
+
* the way the server's own `Float` would refuse it (its `RegistryJsonPatch`
|
|
203
|
+
* impl, in `registry::types::float::Float`, rejects NaN and infinities on
|
|
204
|
+
* a patch), a `greylistForMs` of zero or less is refused the way its
|
|
205
|
+
* `Duration` would be (`registry::types::duration::Duration`'s own patch
|
|
206
|
+
* requires a positive u64), and an empty patch is refused because a write
|
|
207
|
+
* that changes nothing
|
|
208
|
+
* still bumps this instance's every mailbox onto a fresh `ReloadSettings`
|
|
209
|
+
* for no reason.
|
|
210
|
+
*/
|
|
211
|
+
export declare function updateSpamSettings(instance: Instance, input: SpamSettingsInput, audit?: PostmasterAudit): Promise<Applied>;
|
|
212
|
+
/**
|
|
213
|
+
* Try every still-pending recipient on a queued message again, right now,
|
|
214
|
+
* instead of waiting for its scheduled retry.
|
|
215
|
+
*
|
|
216
|
+
* Only `scheduled` and `deferred` recipients are patched — a `delivered` or
|
|
217
|
+
* `failed` one has nothing left to retry, and the server itself ignores a
|
|
218
|
+
* `retryDue` write against a `PermanentFailure` recipient (confirmed in
|
|
219
|
+
* `tests/src/smtp/management/queue.rs`), so this does not even try. A
|
|
220
|
+
* message with nothing pending is refused before the wire, since patching
|
|
221
|
+
* zero recipients would report success for a retry that touched nothing.
|
|
222
|
+
*
|
|
223
|
+
* **The read this refuses on, and the write right after it, are not one
|
|
224
|
+
* transaction.** Stalwart 0.16 has no `ifInState` for this object either
|
|
225
|
+
* (the reason `missingSince` exists for Account writes, in the header
|
|
226
|
+
* above), and here the other party racing the write is not a second admin
|
|
227
|
+
* but the server's own delivery engine, which resolves recipients
|
|
228
|
+
* continuously. A recipient this call means to retry can deliver, or fail
|
|
229
|
+
* for good, in the moment between the read and the write — so this re-reads
|
|
230
|
+
* once more after writing and reports what is actually still pending,
|
|
231
|
+
* rather than assuming the patch reached everyone it was sent for.
|
|
232
|
+
*/
|
|
233
|
+
export declare function retryQueuedMessage(instance: Instance, id: string, audit?: PostmasterAudit): Promise<Applied>;
|
|
234
|
+
/**
|
|
235
|
+
* Take a message out of the queue for good. It will not be retried, and
|
|
236
|
+
* nothing tells whoever sent it or the recipients it was ever delivered —
|
|
237
|
+
* the same silence a real MTA gives a message it drops.
|
|
238
|
+
*/
|
|
239
|
+
export declare function purgeQueuedMessage(instance: Instance, id: string, audit?: PostmasterAudit): Promise<Applied>;
|