@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 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. `mailboxes()` returns each node's own `myRights` (what the
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`. `saveDraft` stores a
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. Nothing here parses a rule into
178
- conditions and actions: Stalwart's `SieveScript` object is a name, an active
179
- flag and a blob holding real Sieve source, so a caller past "one sender,
180
- one folder" owns generating that source itself.
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 `withoutAppPassword` exist so that arithmetic
551
- is decided by a unit test rather than at the end of a request.
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 `purgeQueuedMessage` take an
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.wtfalch.dev',
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.wtfalch.dev',
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.wtfalch.dev',
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.wtfalch.dev',
892
+ stalwartUrl: 'https://mail.companyincluded.com',
856
893
  archiveDir: '/var/lib/mail-backup/acme',
857
894
  });
858
895
  ```
@@ -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';
@@ -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;