@wtfalch/email 0.14.0 → 0.15.1

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.
@@ -4,7 +4,7 @@
4
4
  * Everything takes a `MailClient` and returns this package's own shapes. The
5
5
  * JMAP wire, and the `jmap-jam` client that speaks it, stay inside.
6
6
  */
7
- export { MailClient, MAIL_CAPABILITY, SUBMISSION_CAPABILITY } from './client.ts';
7
+ export { MailClient, MAIL_CAPABILITY, SIEVE_CAPABILITY, SUBMISSION_CAPABILITY } from './client.ts';
8
8
  export type { MailClientOptions } from './client.ts';
9
9
  export { MailError, toMailError } from './errors.ts';
10
10
  export type { ProblemDetails } from './errors.ts';
@@ -25,6 +25,8 @@ export { cancel, draftPatch, draftToEmail, queued, saveDraft, send, sentPatch }
25
25
  export type { CancelOptions, SaveDraftOptions, SendOptions } from './submit.ts';
26
26
  export { SNOOZED_MAILBOX, snoozeThread, wakeSnoozed } from './snooze.ts';
27
27
  export type { SnoozeOptions } from './snooze.ts';
28
+ export { clearVacationResponse, setVacationResponse, vacationResponse } from './vacation.ts';
29
+ export type { VacationResponseOptions } from './vacation.ts';
28
30
  export { attach } from './attach.ts';
29
31
  export { labelKeyword, listLabels, moveThread, moveToRole, removeFromMailbox, setFlagged, setLabel, setRead, } from './mutate.ts';
30
32
  export type { ListLabelsOptions, MoveOptions } from './mutate.ts';
@@ -32,5 +34,7 @@ export { DEFAULT_MAX_DOWNLOAD_BYTES, downloadAttachment } from './download.ts';
32
34
  export type { DownloadOptions } from './download.ts';
33
35
  export { push } from './push.ts';
34
36
  export type { PushHandle, PushOptions } from './push.ts';
37
+ export { activateSieveScript, deactivateSieveScripts, deleteSieveScript, saveSieveScript, sieveScriptText, sieveScripts, validateSieveScript, } from './sieve.ts';
38
+ export type { SavedSieveScript, SaveSieveScriptOptions, SieveScriptSummary } from './sieve.ts';
35
39
  export { expandTemplate } from './uri.ts';
36
- export type { Attachment, ChangedState, Draft, DraftAttachment, EmailAddress, MailAccount, MailFilter, MailIdentity, MailSession, MailSort, MailboxNode, MailboxRight, MailboxRights, MailboxRole, Message, Queued, Sent, ThreadDetail, ThreadPage, ThreadSummary, } from './types.ts';
40
+ 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';
@@ -4,7 +4,7 @@
4
4
  * Everything takes a `MailClient` and returns this package's own shapes. The
5
5
  * JMAP wire, and the `jmap-jam` client that speaks it, stay inside.
6
6
  */
7
- export { MailClient, MAIL_CAPABILITY, SUBMISSION_CAPABILITY } from "./client.js";
7
+ export { MailClient, MAIL_CAPABILITY, SIEVE_CAPABILITY, SUBMISSION_CAPABILITY } from "./client.js";
8
8
  export { MailError, toMailError } from "./errors.js";
9
9
  export { buildTree, createMailbox, deleteMailbox, findRole, mailboxes, renameMailbox, shareMailbox, unshareMailbox, walk, } from "./mailboxes.js";
10
10
  export { listThreads, queryThreads, summarise } from "./threads.js";
@@ -15,8 +15,10 @@ export { attribution, formatAddress, forwardDraft, forwardIntroduction, forwardS
15
15
  export { quoteBoundary, splitQuoted } from "./quoted.js";
16
16
  export { cancel, draftPatch, draftToEmail, queued, saveDraft, send, sentPatch } from "./submit.js";
17
17
  export { SNOOZED_MAILBOX, snoozeThread, wakeSnoozed } from "./snooze.js";
18
+ export { clearVacationResponse, setVacationResponse, vacationResponse } from "./vacation.js";
18
19
  export { attach } from "./attach.js";
19
20
  export { labelKeyword, listLabels, moveThread, moveToRole, removeFromMailbox, setFlagged, setLabel, setRead, } from "./mutate.js";
20
21
  export { DEFAULT_MAX_DOWNLOAD_BYTES, downloadAttachment } from "./download.js";
21
22
  export { push } from "./push.js";
23
+ export { activateSieveScript, deactivateSieveScripts, deleteSieveScript, saveSieveScript, sieveScriptText, sieveScripts, validateSieveScript, } from "./sieve.js";
22
24
  export { expandTemplate } from "./uri.js";
@@ -0,0 +1,76 @@
1
+ import { type MailClient } from './client.ts';
2
+ export type SieveScriptSummary = {
3
+ id: string;
4
+ name: string;
5
+ isActive: boolean;
6
+ blobId: string;
7
+ };
8
+ /** Every Sieve script on the account, active one included. */
9
+ export declare function sieveScripts(client: MailClient): Promise<readonly SieveScriptSummary[]>;
10
+ /**
11
+ * One script's Sieve source.
12
+ *
13
+ * The blob carries no credential of its own (RFC 8620 §6.2), so its bytes
14
+ * are fetched with the same `Authorization` header the API uses — the same
15
+ * reason `downloadAttachment` cannot be a bare `<a href>`.
16
+ */
17
+ export declare function sieveScriptText(client: MailClient, scriptId: string): Promise<string>;
18
+ /**
19
+ * Compile `text` on the server without saving it.
20
+ *
21
+ * `SieveScript/validate` runs the same compiler `SieveScript/set` does
22
+ * (`set.rs:541`), so a script that fails here would also fail a save — this
23
+ * is a sanity check before committing, per RFC 9661.
24
+ */
25
+ export declare function validateSieveScript(client: MailClient, text: string): Promise<void>;
26
+ export type SavedSieveScript = {
27
+ id: string;
28
+ name: string;
29
+ blobId: string;
30
+ };
31
+ export type SaveSieveScriptOptions = {
32
+ /** Replace this script's content and name, instead of creating a new one. */
33
+ scriptId?: string;
34
+ };
35
+ /**
36
+ * Create a script from `text`, or replace one's content when `scriptId` is
37
+ * given. Never activated by this call — see {@link activateSieveScript}.
38
+ *
39
+ * **Not a `SieveScriptSummary`.** A replace's response only carries what
40
+ * changed (`set.rs:290-297`), and `isActive` is never one of those things
41
+ * this call touches, so reporting it here would cost a second
42
+ * `SieveScript/get` nobody asked for — the same reasoning `createMailbox`
43
+ * gives for returning a `NewMailbox` rather than a full `MailboxNode`.
44
+ */
45
+ export declare function saveSieveScript(client: MailClient, name: string, text: string, options?: SaveSieveScriptOptions): Promise<SavedSieveScript>;
46
+ /**
47
+ * Make one script the account's active filter.
48
+ *
49
+ * **`onSuccessActivateScript` alone would fail silently for an id the
50
+ * account does not have.** Stalwart clears it rather than refusing when the
51
+ * id is not the caller's own (`set.rs:96-101`), and with no `create` or
52
+ * `update` in the same call there is nothing left in the response to notice
53
+ * a no-op by. Pairing it with an empty `update` on that same id turns a bad
54
+ * id into an ordinary, checkable `notUpdated` (`set.rs:322-324`'s
55
+ * `notFound` when the id does not resolve to a real script), which is what
56
+ * this checks; a good id updates nothing (the patch is empty) and the pair
57
+ * still activates it.
58
+ */
59
+ export declare function activateSieveScript(client: MailClient, scriptId: string): Promise<void>;
60
+ /**
61
+ * Turn Sieve filtering off for the account: whichever script was active
62
+ * stops running, and nothing replaces it until something is activated
63
+ * again. RFC 9661's `onSuccessDeactivateScript`, one round trip, no id to
64
+ * get wrong — unlike {@link activateSieveScript} there is nothing here for
65
+ * a bad id to silently do nothing to.
66
+ */
67
+ export declare function deactivateSieveScripts(client: MailClient): Promise<void>;
68
+ /**
69
+ * Delete a script.
70
+ *
71
+ * Refused by the server while it is the active one
72
+ * (`type: "scriptIsActive"`, `set.rs:341-346`) — {@link deactivateSieveScripts}
73
+ * first, then delete. This surfaces that refusal rather than guessing at it,
74
+ * the same stance `deleteMailbox` takes on a mailbox with a role.
75
+ */
76
+ export declare function deleteSieveScript(client: MailClient, scriptId: string): Promise<void>;
@@ -0,0 +1,241 @@
1
+ import { JAM_FETCH, SIEVE_CAPABILITY } from "./client.js";
2
+ import { MailError, guard } from "./errors.js";
3
+ /**
4
+ * Per-account Sieve scripts — RFC 9661, "JMAP for Sieve Scripts".
5
+ *
6
+ * **`jmap-jam` has no typed `SieveScript` methods.** Its `Methods` union
7
+ * (`contracts.ts`) only covers RFC 8621/8620/8621's own objects, and its
8
+ * capability table (`capabilities.ts`) does not know
9
+ * `urn:ietf:params:jmap:sieve` either, so `jam.api.SieveScript` does not
10
+ * exist and the automatic `using` it derives from a method name would miss
11
+ * this capability. Every call here goes through `jam.request` directly, with
12
+ * the capability supplied by hand through `using` — the same thing
13
+ * `submit.ts`'s `send()` does to add the mail capability alongside
14
+ * `EmailSubmission/set`.
15
+ *
16
+ * Confirmed against `stalwartlabs/stalwart` at `main`,
17
+ * `02503015580abd6706923d34e9d8e501e76f8634`:
18
+ * - the four methods and the capability string:
19
+ * `crates/jmap-proto/src/request/method.rs:146-149,284-287`,
20
+ * `crates/jmap-proto/src/request/capability.rs:76-77,326,470`;
21
+ * - the object is exactly `{id, name, blobId, isActive}` — no structured
22
+ * condition/action shape to build on:
23
+ * `crates/jmap-proto/src/object/sieve.rs:19-24`;
24
+ * - a create requires an uploaded blob first ("Missing blobId."):
25
+ * `crates/jmap/src/sieve/set.rs:566-569`;
26
+ * - activation is the non-standard `onSuccessActivateScript` /
27
+ * `onSuccessDeactivateScript` set arguments, one round trip, no separate
28
+ * activate call: `crates/jmap-proto/src/object/sieve.rs:93-96`,
29
+ * `crates/jmap/src/sieve/set.rs:371-391`;
30
+ * - deleting the active script is refused
31
+ * (`type: "scriptIsActive"`): `crates/jmap/src/sieve/set.rs:341-346`.
32
+ *
33
+ * **`SieveScript/query` is never called.** RFC 8620 §5.1: an absent `ids`
34
+ * on `Foo/get` returns every object the account has, the same shortcut
35
+ * `identities()` takes for `Identity/get` — a plain `get` lists every script
36
+ * in one call, so the extra `query` round trip buys nothing here.
37
+ */
38
+ const SIEVE_OPTIONS = { using: [SIEVE_CAPABILITY], ...JAM_FETCH };
39
+ /** The one raw call every function below goes through: see the module
40
+ * docblock for why `jam.api` cannot reach `SieveScript/*`. */
41
+ async function sieveCall(jam, method, args) {
42
+ const [result] = await jam.request([method, args], SIEVE_OPTIONS);
43
+ return result;
44
+ }
45
+ /** Every Sieve script on the account, active one included. */
46
+ export async function sieveScripts(client) {
47
+ const { jam, accountId } = await client.connect();
48
+ return guard('sieve scripts', async () => {
49
+ const result = await sieveCall(jam, 'SieveScript/get', { accountId });
50
+ const list = result.list;
51
+ return list.map((script) => ({
52
+ id: script.id,
53
+ name: script.name,
54
+ isActive: script.isActive ?? false,
55
+ blobId: script.blobId,
56
+ }));
57
+ });
58
+ }
59
+ /**
60
+ * One script's Sieve source.
61
+ *
62
+ * The blob carries no credential of its own (RFC 8620 §6.2), so its bytes
63
+ * are fetched with the same `Authorization` header the API uses — the same
64
+ * reason `downloadAttachment` cannot be a bare `<a href>`.
65
+ */
66
+ export async function sieveScriptText(client, scriptId) {
67
+ const { jam, accountId } = await client.connect();
68
+ return guard('sieve script text', async () => {
69
+ const result = await sieveCall(jam, 'SieveScript/get', { accountId, ids: [scriptId] });
70
+ const script = result.list[0];
71
+ if (!script) {
72
+ throw new MailError(`no sieve script ${scriptId} on this account`, {
73
+ type: 'notFound',
74
+ operation: 'sieve script text',
75
+ });
76
+ }
77
+ const url = await client.downloadUrl({
78
+ blobId: script.blobId,
79
+ name: `${script.name}.sieve`,
80
+ type: 'application/sieve',
81
+ });
82
+ const response = await fetch(url, {
83
+ headers: { Authorization: client.authorization },
84
+ credentials: 'omit',
85
+ });
86
+ if (!response.ok) {
87
+ throw new MailError(`the server refused to send the script text (${response.status})`, {
88
+ status: response.status,
89
+ operation: 'sieve script text',
90
+ });
91
+ }
92
+ return response.text();
93
+ });
94
+ }
95
+ /**
96
+ * Compile `text` on the server without saving it.
97
+ *
98
+ * `SieveScript/validate` runs the same compiler `SieveScript/set` does
99
+ * (`set.rs:541`), so a script that fails here would also fail a save — this
100
+ * is a sanity check before committing, per RFC 9661.
101
+ */
102
+ export async function validateSieveScript(client, text) {
103
+ const { jam, accountId } = await client.connect();
104
+ const uploaded = await client.upload(text, 'application/sieve');
105
+ return guard('validate sieve script', async () => {
106
+ const result = await sieveCall(jam, 'SieveScript/validate', {
107
+ accountId,
108
+ blobId: uploaded.blobId,
109
+ });
110
+ const error = result.error;
111
+ if (error) {
112
+ throw new MailError(error.description ?? 'the script did not compile', {
113
+ type: error.type ?? 'invalidScript',
114
+ operation: 'validate sieve script',
115
+ });
116
+ }
117
+ });
118
+ }
119
+ /**
120
+ * Create a script from `text`, or replace one's content when `scriptId` is
121
+ * given. Never activated by this call — see {@link activateSieveScript}.
122
+ *
123
+ * **Not a `SieveScriptSummary`.** A replace's response only carries what
124
+ * changed (`set.rs:290-297`), and `isActive` is never one of those things
125
+ * this call touches, so reporting it here would cost a second
126
+ * `SieveScript/get` nobody asked for — the same reasoning `createMailbox`
127
+ * gives for returning a `NewMailbox` rather than a full `MailboxNode`.
128
+ */
129
+ export async function saveSieveScript(client, name, text, options = {}) {
130
+ const trimmed = name.trim();
131
+ if (!trimmed) {
132
+ throw new MailError('a sieve script needs a name', {
133
+ type: 'invalidArguments',
134
+ operation: 'save sieve script',
135
+ });
136
+ }
137
+ const { jam, accountId } = await client.connect();
138
+ const uploaded = await client.upload(text, 'application/sieve');
139
+ return guard('save sieve script', async () => {
140
+ if (options.scriptId) {
141
+ const scriptId = options.scriptId;
142
+ const result = await sieveCall(jam, 'SieveScript/set', {
143
+ accountId,
144
+ update: { [scriptId]: { name: trimmed, blobId: uploaded.blobId } },
145
+ });
146
+ const notUpdated = result.notUpdated;
147
+ const failure = notUpdated?.[scriptId];
148
+ if (failure) {
149
+ throw new MailError(failure.description ?? 'the server refused to replace the script', {
150
+ type: failure.type ?? 'unknown',
151
+ operation: 'save sieve script',
152
+ });
153
+ }
154
+ return { id: scriptId, name: trimmed, blobId: uploaded.blobId };
155
+ }
156
+ const result = await sieveCall(jam, 'SieveScript/set', {
157
+ accountId,
158
+ create: { script: { name: trimmed, blobId: uploaded.blobId } },
159
+ });
160
+ const created = result.created
161
+ ?.script;
162
+ if (!created) {
163
+ const notCreated = result.notCreated;
164
+ const failure = notCreated?.script;
165
+ throw new MailError(failure?.description ?? 'the server would not create the script', {
166
+ type: failure?.type ?? 'unknown',
167
+ operation: 'save sieve script',
168
+ });
169
+ }
170
+ return { id: created.id, name: trimmed, blobId: created.blobId ?? uploaded.blobId };
171
+ });
172
+ }
173
+ /**
174
+ * Make one script the account's active filter.
175
+ *
176
+ * **`onSuccessActivateScript` alone would fail silently for an id the
177
+ * account does not have.** Stalwart clears it rather than refusing when the
178
+ * id is not the caller's own (`set.rs:96-101`), and with no `create` or
179
+ * `update` in the same call there is nothing left in the response to notice
180
+ * a no-op by. Pairing it with an empty `update` on that same id turns a bad
181
+ * id into an ordinary, checkable `notUpdated` (`set.rs:322-324`'s
182
+ * `notFound` when the id does not resolve to a real script), which is what
183
+ * this checks; a good id updates nothing (the patch is empty) and the pair
184
+ * still activates it.
185
+ */
186
+ export async function activateSieveScript(client, scriptId) {
187
+ const { jam, accountId } = await client.connect();
188
+ return guard('activate sieve script', async () => {
189
+ const result = await sieveCall(jam, 'SieveScript/set', {
190
+ accountId,
191
+ update: { [scriptId]: {} },
192
+ onSuccessActivateScript: scriptId,
193
+ });
194
+ const notUpdated = result.notUpdated;
195
+ const failure = notUpdated?.[scriptId];
196
+ if (failure) {
197
+ throw new MailError(failure.description ?? 'the server refused to activate the script', {
198
+ type: failure.type ?? 'unknown',
199
+ operation: 'activate sieve script',
200
+ });
201
+ }
202
+ });
203
+ }
204
+ /**
205
+ * Turn Sieve filtering off for the account: whichever script was active
206
+ * stops running, and nothing replaces it until something is activated
207
+ * again. RFC 9661's `onSuccessDeactivateScript`, one round trip, no id to
208
+ * get wrong — unlike {@link activateSieveScript} there is nothing here for
209
+ * a bad id to silently do nothing to.
210
+ */
211
+ export async function deactivateSieveScripts(client) {
212
+ const { jam, accountId } = await client.connect();
213
+ return guard('deactivate sieve scripts', async () => {
214
+ await sieveCall(jam, 'SieveScript/set', { accountId, onSuccessDeactivateScript: true });
215
+ });
216
+ }
217
+ /**
218
+ * Delete a script.
219
+ *
220
+ * Refused by the server while it is the active one
221
+ * (`type: "scriptIsActive"`, `set.rs:341-346`) — {@link deactivateSieveScripts}
222
+ * first, then delete. This surfaces that refusal rather than guessing at it,
223
+ * the same stance `deleteMailbox` takes on a mailbox with a role.
224
+ */
225
+ export async function deleteSieveScript(client, scriptId) {
226
+ const { jam, accountId } = await client.connect();
227
+ return guard('delete sieve script', async () => {
228
+ const result = await sieveCall(jam, 'SieveScript/set', {
229
+ accountId,
230
+ destroy: [scriptId],
231
+ });
232
+ const notDestroyed = result.notDestroyed;
233
+ const failure = notDestroyed?.[scriptId];
234
+ if (failure) {
235
+ throw new MailError(failure.description ?? 'the server refused to delete the script', {
236
+ type: failure.type ?? 'unknown',
237
+ operation: 'delete sieve script',
238
+ });
239
+ }
240
+ });
241
+ }
@@ -1,7 +1,35 @@
1
1
  import { type MailClient } from './client.ts';
2
2
  import type { Draft, EmailAddress, MailIdentity, MailboxNode, Queued, Sent } from './types.ts';
3
- /** The JMAP `Email` object a draft becomes. Exported so the shape can be
4
- * asserted without a server. */
3
+ /**
4
+ * The JMAP `Email` object a draft becomes. Exported so the shape can be
5
+ * asserted without a server.
6
+ *
7
+ * **A `calendar` part moves the whole body under `bodyStructure`.** RFC 8621
8
+ * §4.6: a created `Email` MUST NOT mix `bodyStructure` with `textBody`/
9
+ * `htmlBody`/`attachments`, and a `text/calendar` part has nowhere to go in
10
+ * any of those three, so it forces the explicit form -- one
11
+ * `multipart/alternative` holding the readable text (and `html`, if the
12
+ * draft has one) beside the calendar part, the shape #99 found every mail
13
+ * client uses for iTIP. `draft.attachments` has nowhere to go alongside it
14
+ * without folding it into the same structure by hand, which nothing here
15
+ * needs yet (#97 ships compose and parse only), so the two are refused
16
+ * together rather than silently dropping one.
17
+ *
18
+ * **The `method=` parameter rides in the part's own `type` string, not a
19
+ * `header:Content-Type`.** Both name the same header, and RFC 8621 §4.6
20
+ * forbids setting it twice; Stalwart does not enforce that itself and would
21
+ * emit two `Content-Type` headers. Its `Email/set` writes whatever string
22
+ * `type` holds onto the wire unparsed -- `ContentType::new(content_type)`
23
+ * (`crates/jmap/src/email/set.rs:516,562` @
24
+ * `02503015580abd6706923d34e9d8e501e76f8634`) treats it as an opaque token,
25
+ * appending only the `charset`/`name` attributes this package's own
26
+ * `partId` path adds, never stripping or validating what came before them
27
+ * (mail-builder `ContentType::write_header`,
28
+ * `src/headers/content_type.rs:49-63` @
29
+ * `0e87ce2d426d39fcad192df1581fd6776faabd0b`, the commit tagged `v1.0.0`
30
+ * that Stalwart's `Cargo.lock` pins) -- so `text/calendar; method=COUNTER`
31
+ * survives verbatim. See the PR for the full citation.
32
+ */
5
33
  export declare function draftToEmail(draft: Draft, from: readonly EmailAddress[], draftsMailboxId: string): Record<string, unknown>;
6
34
  /** The patch that files a sent message: out of Drafts, into Sent, no longer a
7
35
  * draft. */
@@ -106,9 +106,43 @@ function uniqueAddresses(addresses) {
106
106
  }
107
107
  return result;
108
108
  }
109
- /** The JMAP `Email` object a draft becomes. Exported so the shape can be
110
- * asserted without a server. */
109
+ /**
110
+ * The JMAP `Email` object a draft becomes. Exported so the shape can be
111
+ * asserted without a server.
112
+ *
113
+ * **A `calendar` part moves the whole body under `bodyStructure`.** RFC 8621
114
+ * §4.6: a created `Email` MUST NOT mix `bodyStructure` with `textBody`/
115
+ * `htmlBody`/`attachments`, and a `text/calendar` part has nowhere to go in
116
+ * any of those three, so it forces the explicit form -- one
117
+ * `multipart/alternative` holding the readable text (and `html`, if the
118
+ * draft has one) beside the calendar part, the shape #99 found every mail
119
+ * client uses for iTIP. `draft.attachments` has nowhere to go alongside it
120
+ * without folding it into the same structure by hand, which nothing here
121
+ * needs yet (#97 ships compose and parse only), so the two are refused
122
+ * together rather than silently dropping one.
123
+ *
124
+ * **The `method=` parameter rides in the part's own `type` string, not a
125
+ * `header:Content-Type`.** Both name the same header, and RFC 8621 §4.6
126
+ * forbids setting it twice; Stalwart does not enforce that itself and would
127
+ * emit two `Content-Type` headers. Its `Email/set` writes whatever string
128
+ * `type` holds onto the wire unparsed -- `ContentType::new(content_type)`
129
+ * (`crates/jmap/src/email/set.rs:516,562` @
130
+ * `02503015580abd6706923d34e9d8e501e76f8634`) treats it as an opaque token,
131
+ * appending only the `charset`/`name` attributes this package's own
132
+ * `partId` path adds, never stripping or validating what came before them
133
+ * (mail-builder `ContentType::write_header`,
134
+ * `src/headers/content_type.rs:49-63` @
135
+ * `0e87ce2d426d39fcad192df1581fd6776faabd0b`, the commit tagged `v1.0.0`
136
+ * that Stalwart's `Cargo.lock` pins) -- so `text/calendar; method=COUNTER`
137
+ * survives verbatim. See the PR for the full citation.
138
+ */
111
139
  export function draftToEmail(draft, from, draftsMailboxId) {
140
+ if (draft.calendar && draft.attachments?.length) {
141
+ throw new MailError('a calendar part cannot be combined with file attachments yet', {
142
+ type: 'invalidProperties',
143
+ operation: 'draftToEmail',
144
+ });
145
+ }
112
146
  const bodyValues = {};
113
147
  const textBody = [];
114
148
  const htmlBody = [];
@@ -126,6 +160,26 @@ export function draftToEmail(draft, from, draftsMailboxId) {
126
160
  bodyValues.text = { value: '' };
127
161
  textBody.push({ partId: 'text', type: 'text/plain' });
128
162
  }
163
+ let body;
164
+ if (draft.calendar) {
165
+ bodyValues.calendar = { value: draft.calendar.ics };
166
+ body = {
167
+ bodyStructure: {
168
+ type: 'multipart/alternative',
169
+ subParts: [
170
+ ...textBody,
171
+ ...htmlBody,
172
+ { partId: 'calendar', type: `text/calendar; method=${draft.calendar.method}` },
173
+ ],
174
+ },
175
+ };
176
+ }
177
+ else {
178
+ body = {
179
+ ...(textBody.length ? { textBody } : {}),
180
+ ...(htmlBody.length ? { htmlBody } : {}),
181
+ };
182
+ }
129
183
  return {
130
184
  mailboxIds: { [draftsMailboxId]: true },
131
185
  keywords: { $draft: true, $seen: true },
@@ -138,8 +192,7 @@ export function draftToEmail(draft, from, draftsMailboxId) {
138
192
  ...(draft.inReplyTo?.length ? { inReplyTo: draft.inReplyTo } : {}),
139
193
  ...(draft.references?.length ? { references: draft.references } : {}),
140
194
  bodyValues,
141
- ...(textBody.length ? { textBody } : {}),
142
- ...(htmlBody.length ? { htmlBody } : {}),
195
+ ...body,
143
196
  ...(draft.attachments?.length
144
197
  ? {
145
198
  attachments: draft.attachments.map((attachment) => ({
@@ -5,6 +5,7 @@
5
5
  * should not have to turn that on to use this package. The JMAP wire types
6
6
  * stay behind the client.
7
7
  */
8
+ import type { CalendarPart } from '../imip/types.ts';
8
9
  /**
9
10
  * A mailbox address, with the display name when the message carried one.
10
11
  *
@@ -221,6 +222,12 @@ export type Draft = {
221
222
  /** Blobs to attach: freshly uploaded, or carried from a message being
222
223
  * forwarded. */
223
224
  attachments?: readonly DraftAttachment[];
225
+ /** A `COUNTER` or `DECLINECOUNTER` (`@wtfalch/email/imip`'s `counter`/
226
+ * `declineCounter`) to send alongside the text, RFC 6047 §2.4's shape
227
+ * every mail client uses for iTIP. `draftToEmail` sends it inline in a
228
+ * `multipart/alternative`; a draft with one may not also carry
229
+ * `attachments` (see `draftToEmail`'s doc comment for why). */
230
+ calendar?: CalendarPart;
224
231
  };
225
232
  export type DraftAttachment = {
226
233
  blobId: string;
@@ -268,6 +275,19 @@ export type Queued = {
268
275
  * assumption this type bakes in. */
269
276
  undoStatus: 'pending' | 'final' | 'canceled';
270
277
  };
278
+ /** RFC 8621 §8's out-of-office responder: one object per account, `null`
279
+ * fields left to the server's own defaults. */
280
+ export type VacationResponse = {
281
+ isEnabled: boolean;
282
+ /** The response starts here, or immediately when `null`. ISO 8601 UTC. */
283
+ fromDate: string | null;
284
+ /** The response ends here, or never when `null`. ISO 8601 UTC. */
285
+ toDate: string | null;
286
+ /** `null` lets the server pick an appropriate subject. */
287
+ subject: string | null;
288
+ textBody: string | null;
289
+ htmlBody: string | null;
290
+ };
271
291
  /** The per-type state strings a push event carries. A value that differs
272
292
  * from the one a previous call returned means that type changed. */
273
293
  export type ChangedState = {
@@ -0,0 +1,32 @@
1
+ import { type MailClient } from './client.ts';
2
+ import type { VacationResponse } from './types.ts';
3
+ /** The account's vacation response as it stands now. */
4
+ export declare function vacationResponse(client: MailClient): Promise<VacationResponse>;
5
+ export type VacationResponseOptions = {
6
+ /** Whether a message arriving now should get the auto-reply. */
7
+ isEnabled: boolean;
8
+ /** The window the response is sent in. `undefined` leaves a bound as the
9
+ * server already has it; `null` clears it -- immediately for `fromDate`,
10
+ * indefinitely for `toDate`. ISO 8601 UTC, as `Sent.sendAt` is. */
11
+ fromDate?: string | null;
12
+ toDate?: string | null;
13
+ /** `undefined` leaves it alone; `null` clears it back to the server's own
14
+ * default subject. */
15
+ subject?: string | null;
16
+ textBody?: string | null;
17
+ htmlBody?: string | null;
18
+ };
19
+ /**
20
+ * Set the vacation response: whether it is on, its window, and its message.
21
+ *
22
+ * A field left out of `options` is not sent, so the server keeps whatever it
23
+ * already has for that field; pass `null` to clear one. `isEnabled` is the
24
+ * only field that always goes -- **clearing the response, in the sense the
25
+ * host acts on, is `setVacationResponse(client, { isEnabled: false })`**,
26
+ * which leaves the dates and the message as they were so turning the
27
+ * responder back on does not need to resupply them.
28
+ */
29
+ export declare function setVacationResponse(client: MailClient, options: VacationResponseOptions): Promise<void>;
30
+ /** Turn the vacation response off, leaving its dates and message untouched.
31
+ * The one-field shorthand for `setVacationResponse(client, { isEnabled: false })`. */
32
+ export declare function clearVacationResponse(client: MailClient): Promise<void>;
@@ -0,0 +1,79 @@
1
+ import { JAM_FETCH } from "./client.js";
2
+ import { MailError, guard } from "./errors.js";
3
+ /**
4
+ * The vacation auto-reply: RFC 8621 §8's `VacationResponse`, over the
5
+ * `urn:ietf:params:jmap:vacationresponse` capability.
6
+ *
7
+ * **One object per account, and it is never created or destroyed.** RFC 8621
8
+ * §8.1 fixes its id at `singleton`, so `vacationResponse()` always reads that
9
+ * one object and `setVacationResponse()` always **updates** it -- there is no
10
+ * `create` here the way `createMailbox` has one.
11
+ *
12
+ * **No `using` override is needed, unlike `submit.ts`'s `send`/`cancel`.**
13
+ * `jmap-jam` derives the capabilities a request declares from the method
14
+ * names it is sending, and its own built-in map already keys `VacationResponse`
15
+ * to `urn:ietf:params:jmap:vacationresponse` (`jmap-jam`'s `Requests`/capability
16
+ * table, alongside `Mailbox` → mail and `EmailSubmission` → submission) --
17
+ * confirmed against the installed `jmap-jam@0.13.6`. That table is keyed by
18
+ * the method name being *sent*, so it is only `send`/`cancel`'s implicit
19
+ * `Email/set` (a method never named in the request) that needs `using` forced
20
+ * by hand; a plain `VacationResponse/get` or `/set` names itself.
21
+ */
22
+ const SINGLETON = 'singleton';
23
+ function fromRaw(raw) {
24
+ return {
25
+ isEnabled: raw.isEnabled,
26
+ fromDate: raw.fromDate ?? null,
27
+ toDate: raw.toDate ?? null,
28
+ subject: raw.subject ?? null,
29
+ textBody: raw.textBody ?? null,
30
+ htmlBody: raw.htmlBody ?? null,
31
+ };
32
+ }
33
+ /** The account's vacation response as it stands now. */
34
+ export async function vacationResponse(client) {
35
+ const { jam, accountId } = await client.connect();
36
+ return guard('vacation response', async () => {
37
+ const [result] = await jam.api.VacationResponse.get({ accountId }, JAM_FETCH);
38
+ const found = result.list[0];
39
+ if (!found) {
40
+ throw new MailError('the account has no vacation response to read', {
41
+ type: 'notFound',
42
+ operation: 'vacation response',
43
+ });
44
+ }
45
+ return fromRaw(found);
46
+ });
47
+ }
48
+ /**
49
+ * Set the vacation response: whether it is on, its window, and its message.
50
+ *
51
+ * A field left out of `options` is not sent, so the server keeps whatever it
52
+ * already has for that field; pass `null` to clear one. `isEnabled` is the
53
+ * only field that always goes -- **clearing the response, in the sense the
54
+ * host acts on, is `setVacationResponse(client, { isEnabled: false })`**,
55
+ * which leaves the dates and the message as they were so turning the
56
+ * responder back on does not need to resupply them.
57
+ */
58
+ export async function setVacationResponse(client, options) {
59
+ const { jam, accountId } = await client.connect();
60
+ const { isEnabled, ...rest } = options;
61
+ const patch = { isEnabled };
62
+ for (const [key, value] of Object.entries(rest)) {
63
+ if (value !== undefined)
64
+ patch[key] = value;
65
+ }
66
+ return guard('set vacation response', async () => {
67
+ const [result] = await jam.api.VacationResponse.set({ accountId, update: { [SINGLETON]: patch } }, JAM_FETCH);
68
+ const notUpdated = result.notUpdated;
69
+ const failure = notUpdated?.[SINGLETON];
70
+ if (failure) {
71
+ throw new MailError(failure.description ?? 'the server refused to set the vacation response', { type: failure.type ?? 'unknown', operation: 'set vacation response' });
72
+ }
73
+ });
74
+ }
75
+ /** Turn the vacation response off, leaving its dates and message untouched.
76
+ * The one-field shorthand for `setVacationResponse(client, { isEnabled: false })`. */
77
+ export function clearVacationResponse(client) {
78
+ return setVacationResponse(client, { isEnabled: false });
79
+ }
@@ -23,4 +23,6 @@ export { overview, pickDomain, type AccountView, type CredentialSummary, type Do
23
23
  export { MailWriteRefused, membershipIds, newAccount, newGroup, withAlias, withMembership, withoutAlias, withoutApiKey, withoutAppPassword, withoutMembership, } from './writes.js';
24
24
  export { addAlias, addToGroup, createGroupMailbox, createMailbox, enableHolding, holdLimit, purgeQueuedMessage, removeAlias, removeFromGroup, retryQueuedMessage, revokeApiKey, revokeAppPassword, spamSettings, updateSpamSettings, type Applied, type SpamSettingsInput, type SpamSettingsView, } from './apply.js';
25
25
  export { loadQueue, queueMessageView, type QueueMessage, type QueueRecipient, type QueueRecipientState, } from './queue.js';
26
+ export { applyOrgMail, dkimRecordsFromZoneFile, parkOrgMail, type DnsRecordSpec, type OrgMailMode, type OrgMailOptions, type OrgMailOrg, type OrgMailResult, } from './org-mail.js';
26
27
  export { POSTMASTER_AUDIT_EVENTS, type PostmasterAudit, type PostmasterAuditAction, type PostmasterAuditEvent, } from './audit.js';
28
+ export { MailCopyPlanRefused, mailCopyPlan, type MailCopyAccount, type MailCopyAccountPlan, type MailCopyEnv, type MailCopyOptions, type MailCopyPlan, type MailCopyProvider, } from './mail-copy.js';
@@ -23,4 +23,6 @@ export { overview, pickDomain, } from './overview.js';
23
23
  export { MailWriteRefused, membershipIds, newAccount, newGroup, withAlias, withMembership, withoutAlias, withoutApiKey, withoutAppPassword, withoutMembership, } from './writes.js';
24
24
  export { addAlias, addToGroup, createGroupMailbox, createMailbox, enableHolding, holdLimit, purgeQueuedMessage, removeAlias, removeFromGroup, retryQueuedMessage, revokeApiKey, revokeAppPassword, spamSettings, updateSpamSettings, } from './apply.js';
25
25
  export { loadQueue, queueMessageView, } from './queue.js';
26
+ export { applyOrgMail, dkimRecordsFromZoneFile, parkOrgMail, } from './org-mail.js';
26
27
  export { POSTMASTER_AUDIT_EVENTS, } from './audit.js';
28
+ export { MailCopyPlanRefused, mailCopyPlan, } from './mail-copy.js';