@wtfalch/email 0.20.0 → 0.24.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 +67 -30
- package/dist/mailbox/index.d.ts +6 -2
- package/dist/mailbox/index.js +3 -1
- package/dist/mailbox/principals.d.ts +48 -0
- package/dist/mailbox/principals.js +111 -0
- package/dist/mailbox/rules.d.ts +102 -0
- package/dist/mailbox/rules.js +318 -0
- package/dist/mailbox/submit.d.ts +20 -1
- package/dist/mailbox/submit.js +125 -0
- package/dist/mailbox/types.d.ts +19 -0
- package/dist/mailbox/vacation.d.ts +4 -0
- package/dist/mailbox/vacation.js +118 -10
- package/dist/postmaster/apply.d.ts +20 -0
- package/dist/postmaster/apply.js +48 -1
- package/dist/postmaster/audit.d.ts +3 -0
- package/dist/postmaster/audit.js +1 -0
- package/dist/postmaster/index.d.ts +3 -2
- package/dist/postmaster/index.js +3 -2
- package/dist/postmaster/mail-copy.d.ts +12 -1
- package/dist/postmaster/mail-copy.js +2 -2
- package/dist/postmaster/mail-takeout.d.ts +31 -0
- package/dist/postmaster/mail-takeout.js +113 -0
- package/dist/postmaster/org-mail-export.d.ts +2 -2
- package/dist/postmaster/writes.d.ts +14 -1
- package/dist/postmaster/writes.js +17 -1
- package/package.json +1 -5
- package/dist/mailbox/fake/index.d.ts +0 -34
- package/dist/mailbox/fake/index.js +0 -85
- package/dist/mailbox/fake/mailbox.d.ts +0 -79
- package/dist/mailbox/fake/mailbox.js +0 -1235
- package/dist/mailbox/fake/sample.d.ts +0 -2
- package/dist/mailbox/fake/sample.js +0 -322
package/README.md
CHANGED
|
@@ -60,7 +60,11 @@ some of RFC 8621 §2's ten rights (`mayReadItems`, `mayAddItems`, …) on that o
|
|
|
60
60
|
mailbox, and `unshareMailbox` takes them back. Both patch `Mailbox/set` at
|
|
61
61
|
`shareWith/<accountId>` rather than sending the whole `shareWith` map, so
|
|
62
62
|
granting or revoking one account's access never touches another's, and needs
|
|
63
|
-
no read first. `
|
|
63
|
+
no read first. `findPrincipals(client, query)` turns an email address or a
|
|
64
|
+
name into the colleague's `accountId` and display name (JMAP principals, same
|
|
65
|
+
domain as the login only; an empty list is nobody, two entries is a choice),
|
|
66
|
+
and `lookupPrincipal` returns the one match or `null`, or throws `ambiguous`.
|
|
67
|
+
`mailboxes()` returns each node's own `myRights` (what the
|
|
64
68
|
signed-in login may do there) and `shareWith` (who else can, and with what),
|
|
65
69
|
both always present, every right explicit — RFC 8621 requires `myRights`, and
|
|
66
70
|
the wire has been seen to fill in every unrequested right on `shareWith` as
|
|
@@ -102,7 +106,13 @@ regardless. `queued` lists everything still held, soonest first, for a
|
|
|
102
106
|
rather than reading the field off an unfiltered one, since that filter is
|
|
103
107
|
what makes the server recheck each submission against the mail queue and
|
|
104
108
|
demote one that already went, instead of answering a stale `'pending'`. Every
|
|
105
|
-
row it returns is safe to hand straight to `cancel`. `
|
|
109
|
+
row it returns is safe to hand straight to `cancel`. `submissions` lists the
|
|
110
|
+
account's sent mail newest first, each with a `state` (`scheduled`, `sending`,
|
|
111
|
+
`delivered`, `failed`, `canceled`) read from `undoStatus` and the server's
|
|
112
|
+
`deliveryStatus`, plus the email's `subject` and `to`; `options.states` and
|
|
113
|
+
`options.limit` (default 100) narrow it, and a `failed` row carries the
|
|
114
|
+
recipient's `smtpReply` as `failure`. `resend` sends a message that is already
|
|
115
|
+
in Sent again, with the identity matching its From, and files nothing. `saveDraft` stores a
|
|
106
116
|
draft in Drafts so it outlives the compose sheet, and given the id it returned
|
|
107
117
|
last time, replaces that draft instead of adding one (messages are immutable,
|
|
108
118
|
so the id changes each save). `send(…, { draftId })` sends and removes the
|
|
@@ -147,6 +157,15 @@ it. `clearVacationResponse` is the shorthand for turning it off — `isEnabled:
|
|
|
147
157
|
false` — without touching the dates or the message, so switching it back on
|
|
148
158
|
does not need them resupplied.
|
|
149
159
|
|
|
160
|
+
The reply has an `audience`: `'anyone'` (default), `'company'` (senders in the
|
|
161
|
+
account's own domain, taken from the first identity) or `'nobody'` (dates and
|
|
162
|
+
text kept, no reply). With the sieve capability the away reply is the vacation
|
|
163
|
+
section of the account's one active script, next to the mail rules, and the
|
|
164
|
+
server's own `VacationResponse` is kept `isEnabled: false` so it never replies
|
|
165
|
+
twice; a hand-written active script refuses an enabling write (`conflict`) but
|
|
166
|
+
can still be turned off. Without the capability only `'anyone'` works and the
|
|
167
|
+
JMAP object is used as before.
|
|
168
|
+
|
|
150
169
|
```ts
|
|
151
170
|
await setVacationResponse(client, {
|
|
152
171
|
isEnabled: true,
|
|
@@ -174,10 +193,14 @@ the server without saving it, for a check before committing. Exactly one
|
|
|
174
193
|
script is active per account: `activateSieveScript(client, id)` makes it the
|
|
175
194
|
one that runs, and `deactivateSieveScripts` turns filtering off entirely.
|
|
176
195
|
`deleteSieveScript` is refused while its target is the active script — the
|
|
177
|
-
server's own guard, deactivate first.
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
196
|
+
server's own guard, deactivate first. Stalwart's `SieveScript` is
|
|
197
|
+
only a name, an active flag and a blob of Sieve source, so rules live in
|
|
198
|
+
this package: `rulesToSieve(rules)` writes Sieve for a list of `MailRule`s
|
|
199
|
+
(from/to/cc/subject contains, has attachment, list-id present; move to a
|
|
200
|
+
folder, add a keyword, mark read, forward a copy, stop), and
|
|
201
|
+
`sieveToRules(script)` reads back only a script that function wrote, using a
|
|
202
|
+
marker line at the top, and gives `null` for a hand-written or edited one.
|
|
203
|
+
Every value is quoted and escaped, so it cannot end its string early.
|
|
181
204
|
|
|
182
205
|
### The React
|
|
183
206
|
|
|
@@ -267,23 +290,6 @@ without pictures.
|
|
|
267
290
|
five `sortOrder: 0`, so the tie-break by name puts Deleted Items first and
|
|
268
291
|
Inbox third. `mailboxes()` still reports what the server said.
|
|
269
292
|
|
|
270
|
-
### A mailbox with no server
|
|
271
|
-
|
|
272
|
-
`@wtfalch/email/mailbox/fake` is an inbox in memory, for stories, for a
|
|
273
|
-
development build and for tests.
|
|
274
|
-
|
|
275
|
-
```ts
|
|
276
|
-
const { client, mailbox, dispose } = fakeMail();
|
|
277
|
-
const tree = await mailboxes(client); // the real function, over the real wire code
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
**It fakes the transport, not the API.** Stubbing the exported functions would
|
|
281
|
-
mean every story exercises the stub while the four-call chain, the result
|
|
282
|
-
references, the body resolution and the null-handling never run. It answers
|
|
283
|
-
JMAP instead. It replaces the global `fetch`, because `jmap-jam` calls the
|
|
284
|
-
bare global and takes no way to pass another one; the replacement delegates
|
|
285
|
-
anything not addressed to it, and `dispose()` puts it back.
|
|
286
|
-
|
|
287
293
|
## What it knows that the RFCs do not
|
|
288
294
|
|
|
289
295
|
**RFC 8621 §7.5's `onSuccessUpdateEmail` collides.** The server returns the
|
|
@@ -547,8 +553,18 @@ directly". Provision the replacement before revoking the one in use.
|
|
|
547
553
|
**A `List<T>` write replaces the whole list.** Adding one alias means sending
|
|
548
554
|
back every alias that survives. A read-modify-write that drops an entry does
|
|
549
555
|
not fail; it deletes somebody's alias, or every app password on their phone.
|
|
550
|
-
`withAlias`, `withoutAlias` and `
|
|
551
|
-
is decided by a unit test rather than at the end of
|
|
556
|
+
`withAlias`, `withoutAlias`, `withoutAppPassword` and `withoutAllAppPasswords`
|
|
557
|
+
exist so that arithmetic is decided by a unit test rather than at the end of
|
|
558
|
+
a request.
|
|
559
|
+
|
|
560
|
+
**Disabling a person's sign-in does not stop their mail by itself.** IMAP and
|
|
561
|
+
SMTP authenticate against the account's own credentials and never consult the
|
|
562
|
+
issuer, so an app password minted before a person is disabled keeps working
|
|
563
|
+
after. `revokeAllAppPasswords` drops every `AppPassword` credential on an
|
|
564
|
+
account at once — the `Password` and any `ApiKey` entries survive untouched —
|
|
565
|
+
for the moment a person must be shut out of mail immediately, alongside
|
|
566
|
+
whatever disables their sign-in. Same self-protection as `revokeAppPassword`:
|
|
567
|
+
refused on the account this app itself signs in as.
|
|
552
568
|
|
|
553
569
|
**A shared mailbox is a `Group` account.** `hr@` that a team reads together is
|
|
554
570
|
an ordinary account whose `@type` is `Group`: same delivery, same aliases, no
|
|
@@ -592,7 +608,8 @@ instead.
|
|
|
592
608
|
## The audit
|
|
593
609
|
|
|
594
610
|
`createMailbox`, `createGroupMailbox`, `addToGroup`, `removeFromGroup`, `addAlias`, `removeAlias`,
|
|
595
|
-
`revokeAppPassword`, `enableHolding`, `retryQueuedMessage` and
|
|
611
|
+
`revokeAppPassword`, `revokeAllAppPasswords`, `enableHolding`, `retryQueuedMessage` and
|
|
612
|
+
`purgeQueuedMessage` take an
|
|
596
613
|
optional last argument, a `PostmasterAudit`: a `write` the host bound to its
|
|
597
614
|
own ledger, the principal it resolved for this request, and the request id
|
|
598
615
|
its log uses. Without one, nothing changes.
|
|
@@ -718,6 +735,26 @@ one shared instance regardless of level; Agora's own org scoping is the
|
|
|
718
735
|
boundary between them, not a Stalwart tenant. Moving an org's old mail in
|
|
719
736
|
from Google or Microsoft — [`wtfalch/email#108`](https://github.com/wtfalch/email/issues/108) — is `mailCopyPlan`, below.
|
|
720
737
|
|
|
738
|
+
## Importing an uploaded Google Takeout archive
|
|
739
|
+
|
|
740
|
+
For a person whose mailbox is over Google's daily download cap, `mailTakeoutPlan`
|
|
741
|
+
decides the Vandelay commands that import an uploaded Takeout `.mbox` into one Stalwart
|
|
742
|
+
account (`import takeout`, then the same `export` step as `mailCopyPlan`; the export
|
|
743
|
+
credential is only named in `exportEnv`, never in argv). It refuses, with
|
|
744
|
+
`MailCopyPlanRefused`, a path that is not an absolute `.mbox` under `uploadDir` in its own
|
|
745
|
+
directory, a size over `TAKEOUT_MAX_BYTES` (50 GiB), and a target naming both id and name or
|
|
746
|
+
neither. Vandelay scans the mbox's whole *directory*, so keep one upload per directory.
|
|
747
|
+
|
|
748
|
+
How it differs from the IMAP route (`mailCopyPlan`):
|
|
749
|
+
|
|
750
|
+
- **Labels differ.** IMAP folders become mailboxes. Takeout carries Gmail labels in
|
|
751
|
+
`X-Gmail-Labels`: each label becomes a mailbox of that name (`Archived` → `Archive`),
|
|
752
|
+
`Inbox`/`Sent`/`Drafts`/`Trash`/`Spam`/`Archive` get the matching Stalwart roles,
|
|
753
|
+
`Starred`/`Important`/`Opened` become the `$flagged`/`$important`/`$seen` keywords, and
|
|
754
|
+
`Category …` labels are dropped. A message with several labels sits in several mailboxes.
|
|
755
|
+
- **The final pass is still IMAP.** A Takeout is a snapshot at export time; mail that arrived
|
|
756
|
+
since is picked up by running the `mailCopyPlan` import afterwards.
|
|
757
|
+
|
|
721
758
|
## Copying an org's old mail with Vandelay
|
|
722
759
|
|
|
723
760
|
Stalwart ships its own migration tool, [`stalwartlabs/vandelay`](https://github.com/stalwartlabs/vandelay):
|
|
@@ -733,13 +770,13 @@ import { mailCopyPlan } from '@wtfalch/email/postmaster';
|
|
|
733
770
|
const plan = mailCopyPlan({
|
|
734
771
|
provider: 'google', // or 'microsoft'
|
|
735
772
|
accounts: [{ source: 'alice@acme.com', targetAccountId: 'a1' }],
|
|
736
|
-
stalwartUrl: 'https://mail.
|
|
773
|
+
stalwartUrl: 'https://mail.companyincluded.com',
|
|
737
774
|
archiveDir: '/var/lib/mail-copy/acme',
|
|
738
775
|
});
|
|
739
776
|
|
|
740
777
|
// plan.accounts[0].importArgv: ['import', 'imap', '--url', 'imaps://imap.gmail.com',
|
|
741
778
|
// '--auth-bearer', '--auth-user=alice@acme.com', '--', '/var/lib/mail-copy/acme/alice%40acme.com.sqlite']
|
|
742
|
-
// plan.accounts[0].exportArgv: ['export', '--url', 'https://mail.
|
|
779
|
+
// plan.accounts[0].exportArgv: ['export', '--url', 'https://mail.companyincluded.com',
|
|
743
780
|
// '--auth-bearer', '--account-id=a1', '--', '/var/lib/mail-copy/acme/alice%40acme.com.sqlite']
|
|
744
781
|
// plan.accounts[0].importEnv / .exportEnv: [{ name: 'VANDELAY_TOKEN', purpose: '…' }] — a
|
|
745
782
|
// variable NAME, never a value.
|
|
@@ -842,7 +879,7 @@ const accounts = await accountsOnDomain(client, 'acme.com');
|
|
|
842
879
|
// 2. The Vandelay commands that pull each one's mail into a local archive.
|
|
843
880
|
const backup = orgMailBackupPlan({
|
|
844
881
|
accounts,
|
|
845
|
-
stalwartUrl: 'https://mail.
|
|
882
|
+
stalwartUrl: 'https://mail.companyincluded.com',
|
|
846
883
|
archiveDir: '/var/lib/mail-backup/acme',
|
|
847
884
|
});
|
|
848
885
|
|
|
@@ -852,7 +889,7 @@ const backup = orgMailBackupPlan({
|
|
|
852
889
|
// archives back in.
|
|
853
890
|
const restore = orgMailRestorePlan({
|
|
854
891
|
accounts: [{ address: 'alice@acme.com', targetAccountId: 'b1' }],
|
|
855
|
-
stalwartUrl: 'https://mail.
|
|
892
|
+
stalwartUrl: 'https://mail.companyincluded.com',
|
|
856
893
|
archiveDir: '/var/lib/mail-backup/acme',
|
|
857
894
|
});
|
|
858
895
|
```
|
package/dist/mailbox/index.d.ts
CHANGED
|
@@ -23,7 +23,7 @@ export { attribution, formatAddress, forwardDraft, forwardIntroduction, forwardS
|
|
|
23
23
|
export type { ForwardOptions, ReplyOptions } from './drafts.ts';
|
|
24
24
|
export { quoteBoundary, splitQuoted } from './quoted.ts';
|
|
25
25
|
export type { QuoteBoundary } from './quoted.ts';
|
|
26
|
-
export { cancel, draftPatch, draftToEmail, queued, saveDraft, send, sentPatch } from './submit.ts';
|
|
26
|
+
export { cancel, draftPatch, draftToEmail, queued, resend, saveDraft, send, sentPatch, submissions, } from './submit.ts';
|
|
27
27
|
export type { CancelOptions, SaveDraftOptions, SendOptions } from './submit.ts';
|
|
28
28
|
export { SNOOZED_MAILBOX, snoozeThread, wakeSnoozed } from './snooze.ts';
|
|
29
29
|
export type { SnoozeOptions } from './snooze.ts';
|
|
@@ -38,5 +38,9 @@ export { push } from './push.ts';
|
|
|
38
38
|
export type { PushHandle, PushOptions } from './push.ts';
|
|
39
39
|
export { activateSieveScript, deactivateSieveScripts, deleteSieveScript, saveSieveScript, sieveScriptText, sieveScripts, validateSieveScript, } from './sieve.ts';
|
|
40
40
|
export type { SavedSieveScript, SaveSieveScriptOptions, SieveScriptSummary } from './sieve.ts';
|
|
41
|
+
export { findPrincipals, lookupPrincipal } from './principals.ts';
|
|
42
|
+
export type { PrincipalMatch } from './principals.ts';
|
|
43
|
+
export { combineScript, isOurScript, rulesToSieve, sieveToRules, splitScript } from './rules.ts';
|
|
44
|
+
export type { MailRule, MailRuleAction, MailRuleCondition, VacationSection, } from './rules.ts';
|
|
41
45
|
export { expandTemplate } from './uri.ts';
|
|
42
|
-
export type { Attachment, ChangedState, Draft, DraftAttachment, EmailAddress, MailAccount, MailFilter, MailIdentity, MailSession, MailSort, MailboxNode, MailboxRight, MailboxRights, MailboxRole, Message, Queued, Sent, ThreadDetail, ThreadPage, ThreadSummary, VacationResponse, } from './types.ts';
|
|
46
|
+
export type { Attachment, ChangedState, Draft, DraftAttachment, EmailAddress, MailAccount, MailFilter, MailIdentity, MailSession, MailSort, MailboxNode, MailboxRight, MailboxRights, MailboxRole, Message, Queued, Sent, Submission, SubmissionState, ThreadDetail, ThreadPage, ThreadSummary, VacationResponse, } from './types.ts';
|
package/dist/mailbox/index.js
CHANGED
|
@@ -14,7 +14,7 @@ export { search } from "./search.js";
|
|
|
14
14
|
export { identities } from "./identities.js";
|
|
15
15
|
export { attribution, formatAddress, forwardDraft, forwardIntroduction, forwardSubject, quoteText, replyDraft, replySubject, } from "./drafts.js";
|
|
16
16
|
export { quoteBoundary, splitQuoted } from "./quoted.js";
|
|
17
|
-
export { cancel, draftPatch, draftToEmail, queued, saveDraft, send, sentPatch } from "./submit.js";
|
|
17
|
+
export { cancel, draftPatch, draftToEmail, queued, resend, saveDraft, send, sentPatch, submissions, } from "./submit.js";
|
|
18
18
|
export { SNOOZED_MAILBOX, snoozeThread, wakeSnoozed } from "./snooze.js";
|
|
19
19
|
export { clearVacationResponse, setVacationResponse, vacationResponse } from "./vacation.js";
|
|
20
20
|
export { attach } from "./attach.js";
|
|
@@ -22,4 +22,6 @@ export { labelKeyword, listLabels, moveThread, moveToRole, removeFromMailbox, se
|
|
|
22
22
|
export { DEFAULT_MAX_DOWNLOAD_BYTES, downloadAttachment } from "./download.js";
|
|
23
23
|
export { push } from "./push.js";
|
|
24
24
|
export { activateSieveScript, deactivateSieveScripts, deleteSieveScript, saveSieveScript, sieveScriptText, sieveScripts, validateSieveScript, } from "./sieve.js";
|
|
25
|
+
export { findPrincipals, lookupPrincipal } from "./principals.js";
|
|
26
|
+
export { combineScript, isOurScript, rulesToSieve, sieveToRules, splitScript } from "./rules.js";
|
|
25
27
|
export { expandTemplate } from "./uri.js";
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { type MailClient } from './client.ts';
|
|
2
|
+
/**
|
|
3
|
+
* Colleague lookup for sharing: the JMAP Principals capability
|
|
4
|
+
* (`urn:ietf:params:jmap:principals`, RFC 9670), `Principal/query` then
|
|
5
|
+
* `Principal/get`.
|
|
6
|
+
*
|
|
7
|
+
* {@link shareMailbox} keys a grant by account id, which nobody types. This
|
|
8
|
+
* turns an email address or a name into that id. `jmap-jam` does not know the
|
|
9
|
+
* capability, so the calls go through `jam.request` with `using` set by hand,
|
|
10
|
+
* the same way `sieve.ts` does.
|
|
11
|
+
*
|
|
12
|
+
* Only principals on the current login's own domain (the part of the session
|
|
13
|
+
* `username` after `@`) are returned, so a lookup cannot name someone outside
|
|
14
|
+
* the organisation.
|
|
15
|
+
*/
|
|
16
|
+
export declare const PRINCIPALS_CAPABILITY = "urn:ietf:params:jmap:principals";
|
|
17
|
+
export type PrincipalMatch = {
|
|
18
|
+
principalId: string;
|
|
19
|
+
/** The account to pass to {@link shareMailbox} as `accountId`. */
|
|
20
|
+
accountId: string;
|
|
21
|
+
name: string;
|
|
22
|
+
email: string;
|
|
23
|
+
/** `individual`, `group` and so on, as the server names it. */
|
|
24
|
+
type: string;
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Who on this login's domain matches `query`.
|
|
28
|
+
*
|
|
29
|
+
* A query with an `@` is matched against the email address, anything else
|
|
30
|
+
* against name and email together. The server decides what "matches" means
|
|
31
|
+
* (Stalwart: a case-insensitive substring), so a short query can return
|
|
32
|
+
* several people: an empty list is "nobody", two or more is for the caller to
|
|
33
|
+
* choose between. A principal with no mail account is left out, since there is
|
|
34
|
+
* nothing to share with.
|
|
35
|
+
*
|
|
36
|
+
* Throws `invalidArguments` for a blank query and `unknownCapability` when the
|
|
37
|
+
* server does not offer principals.
|
|
38
|
+
*/
|
|
39
|
+
export declare function findPrincipals(client: MailClient, query: string): Promise<readonly PrincipalMatch[]>;
|
|
40
|
+
/**
|
|
41
|
+
* The one colleague `query` means, or `null` for nobody.
|
|
42
|
+
*
|
|
43
|
+
* An email address that matches exactly (ignoring case) wins over a longer
|
|
44
|
+
* address that merely contains it. Otherwise two or more matches throw
|
|
45
|
+
* `ambiguous`, with the choices in the message; use {@link findPrincipals}
|
|
46
|
+
* to let a person pick.
|
|
47
|
+
*/
|
|
48
|
+
export declare function lookupPrincipal(client: MailClient, query: string): Promise<PrincipalMatch | null>;
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import { JAM_FETCH, MAIL_CAPABILITY } from "./client.js";
|
|
2
|
+
import { MailError, guard } from "./errors.js";
|
|
3
|
+
/**
|
|
4
|
+
* Colleague lookup for sharing: the JMAP Principals capability
|
|
5
|
+
* (`urn:ietf:params:jmap:principals`, RFC 9670), `Principal/query` then
|
|
6
|
+
* `Principal/get`.
|
|
7
|
+
*
|
|
8
|
+
* {@link shareMailbox} keys a grant by account id, which nobody types. This
|
|
9
|
+
* turns an email address or a name into that id. `jmap-jam` does not know the
|
|
10
|
+
* capability, so the calls go through `jam.request` with `using` set by hand,
|
|
11
|
+
* the same way `sieve.ts` does.
|
|
12
|
+
*
|
|
13
|
+
* Only principals on the current login's own domain (the part of the session
|
|
14
|
+
* `username` after `@`) are returned, so a lookup cannot name someone outside
|
|
15
|
+
* the organisation.
|
|
16
|
+
*/
|
|
17
|
+
export const PRINCIPALS_CAPABILITY = 'urn:ietf:params:jmap:principals';
|
|
18
|
+
const OPTIONS = { using: [PRINCIPALS_CAPABILITY], ...JAM_FETCH };
|
|
19
|
+
const LIMIT = 10;
|
|
20
|
+
/** The mail account of a principal, the personal one if it has several. */
|
|
21
|
+
function mailAccountId(principal) {
|
|
22
|
+
const mail = Object.entries(principal.accounts ?? {}).filter(([, account]) => account.accountCapabilities?.[MAIL_CAPABILITY] !== undefined);
|
|
23
|
+
const [first] = [...mail].sort(([, a], [, b]) => Number(b.isPersonal === true) - Number(a.isPersonal === true));
|
|
24
|
+
return first ? first[0] : null;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Who on this login's domain matches `query`.
|
|
28
|
+
*
|
|
29
|
+
* A query with an `@` is matched against the email address, anything else
|
|
30
|
+
* against name and email together. The server decides what "matches" means
|
|
31
|
+
* (Stalwart: a case-insensitive substring), so a short query can return
|
|
32
|
+
* several people: an empty list is "nobody", two or more is for the caller to
|
|
33
|
+
* choose between. A principal with no mail account is left out, since there is
|
|
34
|
+
* nothing to share with.
|
|
35
|
+
*
|
|
36
|
+
* Throws `invalidArguments` for a blank query and `unknownCapability` when the
|
|
37
|
+
* server does not offer principals.
|
|
38
|
+
*/
|
|
39
|
+
export async function findPrincipals(client, query) {
|
|
40
|
+
const needle = query.trim();
|
|
41
|
+
if (!needle) {
|
|
42
|
+
throw new MailError('a colleague lookup needs an email address or a name', {
|
|
43
|
+
type: 'invalidArguments',
|
|
44
|
+
operation: 'find principals',
|
|
45
|
+
});
|
|
46
|
+
}
|
|
47
|
+
const { jam, doc, accountId } = await client.connect();
|
|
48
|
+
if (!doc.capabilities?.[PRINCIPALS_CAPABILITY]) {
|
|
49
|
+
throw new MailError('the server does not offer principals, so it cannot look up colleagues', {
|
|
50
|
+
type: 'unknownCapability',
|
|
51
|
+
operation: 'find principals',
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
const domain = doc.username.includes('@')
|
|
55
|
+
? doc.username.slice(doc.username.lastIndexOf('@') + 1).toLowerCase()
|
|
56
|
+
: '';
|
|
57
|
+
if (!domain) {
|
|
58
|
+
throw new MailError('the login has no email domain to look colleagues up in', {
|
|
59
|
+
type: 'invalidArguments',
|
|
60
|
+
operation: 'find principals',
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
return guard('find principals', async () => {
|
|
64
|
+
const filter = needle.includes('@') ? { email: needle } : { text: needle };
|
|
65
|
+
const [found] = await jam.request(['Principal/query', { accountId, filter, limit: LIMIT }], OPTIONS);
|
|
66
|
+
const ids = (found.ids ?? []).slice(0, LIMIT);
|
|
67
|
+
if (ids.length === 0)
|
|
68
|
+
return [];
|
|
69
|
+
const [got] = await jam.request([
|
|
70
|
+
'Principal/get',
|
|
71
|
+
{ accountId, ids, properties: ['id', 'type', 'name', 'email', 'accounts'] },
|
|
72
|
+
], OPTIONS);
|
|
73
|
+
const matches = [];
|
|
74
|
+
for (const principal of got.list ?? []) {
|
|
75
|
+
const email = principal.email;
|
|
76
|
+
// No `@` means lastIndexOf is -1 and the whole string would be compared.
|
|
77
|
+
if (!email?.includes('@'))
|
|
78
|
+
continue;
|
|
79
|
+
if (email.slice(email.lastIndexOf('@') + 1).toLowerCase() !== domain)
|
|
80
|
+
continue;
|
|
81
|
+
const account = mailAccountId(principal);
|
|
82
|
+
if (!account)
|
|
83
|
+
continue;
|
|
84
|
+
matches.push({
|
|
85
|
+
principalId: principal.id,
|
|
86
|
+
accountId: account,
|
|
87
|
+
name: principal.name ?? email,
|
|
88
|
+
email,
|
|
89
|
+
type: principal.type ?? 'individual',
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
return matches;
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* The one colleague `query` means, or `null` for nobody.
|
|
97
|
+
*
|
|
98
|
+
* An email address that matches exactly (ignoring case) wins over a longer
|
|
99
|
+
* address that merely contains it. Otherwise two or more matches throw
|
|
100
|
+
* `ambiguous`, with the choices in the message; use {@link findPrincipals}
|
|
101
|
+
* to let a person pick.
|
|
102
|
+
*/
|
|
103
|
+
export async function lookupPrincipal(client, query) {
|
|
104
|
+
const matches = await findPrincipals(client, query);
|
|
105
|
+
const exact = matches.filter((match) => match.email.toLowerCase() === query.trim().toLowerCase());
|
|
106
|
+
const pool = exact.length === 1 ? exact : matches;
|
|
107
|
+
if (pool.length > 1) {
|
|
108
|
+
throw new MailError(`${pool.length} colleagues match ${JSON.stringify(query.trim())}: ${pool.map((match) => match.email).join(', ')}`, { type: 'ambiguous', operation: 'lookup principal' });
|
|
109
|
+
}
|
|
110
|
+
return pool[0] ?? null;
|
|
111
|
+
}
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A small rule model that compiles to Sieve (RFC 5228, with `fileinto`
|
|
3
|
+
* `:create` from RFC 5490, `imap4flags` from RFC 5232 and `copy` from RFC
|
|
4
|
+
* 3894), so a UI can offer "if the sender contains X, move it to Y" without
|
|
5
|
+
* writing Sieve by hand.
|
|
6
|
+
*
|
|
7
|
+
* Only scripts this module wrote are read back. {@link rulesToSieve} puts a
|
|
8
|
+
* marker line at the top that carries the rules as JSON, and
|
|
9
|
+
* {@link sieveToRules} accepts a script only when the marker parses and the
|
|
10
|
+
* script body is exactly what the generator writes for those rules. A
|
|
11
|
+
* hand-written script, or a generated one someone edited, gives `null` and
|
|
12
|
+
* is left alone.
|
|
13
|
+
*
|
|
14
|
+
* The result goes through {@link saveSieveScript} and
|
|
15
|
+
* {@link validateSieveScript} like any other script text.
|
|
16
|
+
*/
|
|
17
|
+
export type MailRuleCondition = {
|
|
18
|
+
kind: 'from' | 'to' | 'cc' | 'subject';
|
|
19
|
+
contains: string;
|
|
20
|
+
} | {
|
|
21
|
+
kind: 'hasAttachment';
|
|
22
|
+
} | {
|
|
23
|
+
kind: 'listId';
|
|
24
|
+
};
|
|
25
|
+
export type MailRuleAction = {
|
|
26
|
+
kind: 'moveTo';
|
|
27
|
+
mailbox: string;
|
|
28
|
+
} | {
|
|
29
|
+
kind: 'addKeyword';
|
|
30
|
+
keyword: string;
|
|
31
|
+
} | {
|
|
32
|
+
kind: 'markRead';
|
|
33
|
+
} | {
|
|
34
|
+
kind: 'forwardTo';
|
|
35
|
+
address: string;
|
|
36
|
+
} | {
|
|
37
|
+
kind: 'stop';
|
|
38
|
+
};
|
|
39
|
+
export type MailRule = {
|
|
40
|
+
/** The caller's own id, kept through a round trip. */
|
|
41
|
+
id: string;
|
|
42
|
+
name: string;
|
|
43
|
+
/** A disabled rule stays in the marker but writes no Sieve. */
|
|
44
|
+
enabled: boolean;
|
|
45
|
+
/** `all`: every condition must hold. `any`: one is enough. */
|
|
46
|
+
match: 'all' | 'any';
|
|
47
|
+
conditions: readonly MailRuleCondition[];
|
|
48
|
+
actions: readonly MailRuleAction[];
|
|
49
|
+
};
|
|
50
|
+
/**
|
|
51
|
+
* Sieve source for `rules`, first enabled rule first.
|
|
52
|
+
*
|
|
53
|
+
* Throws a `MailError` of type `invalidArguments` for a rule with no
|
|
54
|
+
* condition or action, an empty value, a value with a control character, a
|
|
55
|
+
* keyword with a character IMAP forbids, or a forward address that is not
|
|
56
|
+
* `name@host`. Every value is written as a quoted string with `\` and `"`
|
|
57
|
+
* escaped, so no value can end the string early.
|
|
58
|
+
*/
|
|
59
|
+
export declare function rulesToSieve(rules: readonly MailRule[]): string;
|
|
60
|
+
/** The away reply kept in the same script as the rules. */
|
|
61
|
+
export type VacationSection = {
|
|
62
|
+
isEnabled: boolean;
|
|
63
|
+
audience: 'anyone' | 'company' | 'nobody';
|
|
64
|
+
/** The company domain, set by the caller; needed for `company`. */
|
|
65
|
+
domain: string | null;
|
|
66
|
+
fromDate: string | null;
|
|
67
|
+
toDate: string | null;
|
|
68
|
+
subject: string | null;
|
|
69
|
+
textBody: string | null;
|
|
70
|
+
htmlBody: string | null;
|
|
71
|
+
};
|
|
72
|
+
/**
|
|
73
|
+
* One Sieve script holding the rules section and a marked vacation section.
|
|
74
|
+
* `rules` null leaves the rules section out; `vacation` null leaves the
|
|
75
|
+
* vacation section out; `combineScript(rules, null)` is `rulesToSieve(rules)`
|
|
76
|
+
* byte for byte, and `combineScript(null, null)` is `''`.
|
|
77
|
+
*
|
|
78
|
+
* Throws `invalidArguments` for a bad rule or a bad vacation value: a subject
|
|
79
|
+
* with a control character, or a text with one other than line breaks (which
|
|
80
|
+
* are written as CRLF).
|
|
81
|
+
*/
|
|
82
|
+
export declare function combineScript(rules: readonly MailRule[] | null, vacation: VacationSection | null): string;
|
|
83
|
+
/**
|
|
84
|
+
* The rules and vacation a script was combined from. Each part is rebuilt
|
|
85
|
+
* from its marker JSON alone and the whole script must equal the result;
|
|
86
|
+
* `null` for a hand-written or edited script. An empty string is
|
|
87
|
+
* `{ rules: null, vacation: null }`.
|
|
88
|
+
*/
|
|
89
|
+
export declare function splitScript(script: string): {
|
|
90
|
+
rules: MailRule[] | null;
|
|
91
|
+
vacation: VacationSection | null;
|
|
92
|
+
} | null;
|
|
93
|
+
/** True for an empty script and for one this module wrote unchanged; a caller
|
|
94
|
+
* refuses to write over a script for which this is false. */
|
|
95
|
+
export declare function isOurScript(text: string): boolean;
|
|
96
|
+
/**
|
|
97
|
+
* The rules a script was generated from, or `null` when `script` is not one
|
|
98
|
+
* {@link rulesToSieve} wrote unchanged: no marker, a marker that does not
|
|
99
|
+
* parse as rules, or a body that differs from what the generator writes for
|
|
100
|
+
* them.
|
|
101
|
+
*/
|
|
102
|
+
export declare function sieveToRules(script: string): MailRule[] | null;
|