@wtfalch/email 0.4.1 → 0.5.0

package/dist/mailbox/mutate.d.ts

@@ -0,0 +1,51 @@
+import { type MailClient } from './client.ts';
+import type { MailboxNode, MailboxRole } from './types.ts';
+/**
+ * Mark every message in a thread read, or unread.
+ *
+ * Read is what opening a conversation means, so this is called by the view
+ * rather than by a button -- and only when a thread actually has something
+ * unread in it, because a `set` that changes nothing still bumps the account's
+ * state string and wakes every other client's push connection for no reason.
+ */
+export declare function setRead(client: MailClient, threadId: string, read: boolean): Promise<readonly string[]>;
+/** Flag a thread, or clear it. `$flagged` is RFC 8621's keyword for the star
+ *  every mail client draws. */
+export declare function setFlagged(client: MailClient, threadId: string, flagged: boolean): Promise<readonly string[]>;
+export type MoveOptions = {
+    /** The mailbox tree, when the caller already has it. Saves a `Mailbox/get`. */
+    mailboxes?: readonly MailboxNode[];
+};
+/**
+ * Move a thread into one mailbox, out of every other.
+ *
+ * **`mailboxIds` is replaced, not patched.** A message may legitimately sit in
+ * several mailboxes at once, and a "move" that only adds the destination is
+ * the bug where archiving leaves the conversation in the Inbox as well and the
+ * unread count never drops. The whole property is set, which is the one
+ * operation that means what the word means.
+ *
+ * The exception the caller has to know about: a message in Sent that is also
+ * in the Inbox loses the Sent filing when it is archived. That is what every
+ * other client does too, and the alternative -- preserving some mailboxes and
+ * not others -- is a rule nobody can predict.
+ */
+export declare function moveThread(client: MailClient, threadId: string, mailboxId: string): Promise<readonly string[]>;
+/**
+ * Move a thread to the mailbox holding a role -- `archive`, `trash`, `junk`,
+ * `inbox`.
+ *
+ * By role rather than by id because that is how the caller thinks: a toolbar
+ * has an Archive button, not a "move to the mailbox whose id is 4f2" button.
+ * A server that has no such mailbox says so rather than silently doing
+ * nothing, since a delete that quietly fails is the worst kind.
+ */
+export declare function moveToRole(client: MailClient, threadId: string, role: MailboxRole, options?: MoveOptions): Promise<readonly string[]>;
+/**
+ * Take a thread out of one mailbox and leave whatever else it is in.
+ *
+ * The narrow counterpart to `moveThread`, for the one case where replacement
+ * is wrong: removing a conversation from the Inbox when the point is to keep
+ * its other filings. Patches a single pointer rather than the property.
+ */
+export declare function removeFromMailbox(client: MailClient, threadId: string, mailboxId: string): Promise<readonly string[]>;

package/dist/mailbox/mutate.js

@@ -0,0 +1,132 @@
+import { JAM_FETCH } from "./client.js";
+import { MailError, guard } from "./errors.js";
+import { findRole, mailboxes } from "./mailboxes.js";
+/**
+ * Changing mail rather than reading it: what is read, what is flagged, and
+ * which mailbox a conversation sits in.
+ *
+ * **A thread, not a message.** Every function here takes a thread id, because
+ * a thread is what a person selects and what they mean. Archiving "the one
+ * from Ada" and leaving her second message in the Inbox is not a thing anyone
+ * asked for; nor is a conversation that is half read. RFC 8621 has no
+ * `Thread/set` -- a thread is derived from its messages and cannot be written
+ * -- so each of these resolves the thread's members and patches all of them in
+ * one `Email/set`.
+ *
+ * **Two round trips, and it cannot be one.** Everywhere else in this package
+ * a chain of calls goes in a single request by JMAP result reference, which
+ * is how a page of threads costs one trip. That does not work here:
+ * `Email/set`'s `update` is a map *keyed by id*, and a result reference can
+ * fill an argument but not build the keys of one. So the member ids come back
+ * before the patch goes out. The cost is one extra trip per action, not one
+ * per message -- a twelve-message thread still patches in a single `set`.
+ *
+ * **Nothing here is optimistic.** These resolve when the server has accepted
+ * the change and return the ids that moved; the caller refetches. A mail
+ * client that draws a message as read before the server agrees is a mail
+ * client that shows the wrong unread count after a failure, and the count is
+ * the one number people trust.
+ */
+/** RFC 6901 §3, the same escape `submit.ts` needs: `~` and `/` inside a
+ *  pointer segment are escaped, and mailbox ids are the server's to choose. */
+function pointer(segment) {
+    return segment.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+/**
+ * A patch applied to every message in a thread.
+ *
+ * A thread that resolves to no messages is an error rather than a no-op: the
+ * id came from a list this client drew, so an empty answer means the thread
+ * was moved or expunged under the person, and reporting success for an action
+ * that touched nothing is how a client tells somebody their mail is filed
+ * when it is not.
+ */
+async function patchThread(client, threadId, patch, operation) {
+    const { jam, accountId } = await client.connect();
+    return guard(operation, async () => {
+        const [thread] = await jam.api.Thread.get({ accountId, ids: [threadId] }, JAM_FETCH);
+        const ids = thread.list?.[0]?.emailIds ?? [];
+        if (ids.length === 0) {
+            throw new MailError(`no thread ${threadId} on this account`, {
+                type: 'notFound',
+                operation,
+            });
+        }
+        const update = {};
+        for (const id of ids)
+            update[id] = patch;
+        const [result] = await jam.api.Email.set({ accountId, update: update }, JAM_FETCH);
+        const refused = result.notUpdated;
+        const first = refused ? Object.values(refused)[0] : undefined;
+        if (first) {
+            throw new MailError(first.description ?? `the server refused to ${operation}`, {
+                type: first.type ?? 'unknown',
+                operation,
+            });
+        }
+        return ids;
+    });
+}
+/**
+ * Mark every message in a thread read, or unread.
+ *
+ * Read is what opening a conversation means, so this is called by the view
+ * rather than by a button -- and only when a thread actually has something
+ * unread in it, because a `set` that changes nothing still bumps the account's
+ * state string and wakes every other client's push connection for no reason.
+ */
+export function setRead(client, threadId, read) {
+    return patchThread(client, threadId, { 'keywords/$seen': read ? true : null }, read ? 'mark read' : 'mark unread');
+}
+/** Flag a thread, or clear it. `$flagged` is RFC 8621's keyword for the star
+ *  every mail client draws. */
+export function setFlagged(client, threadId, flagged) {
+    return patchThread(client, threadId, { 'keywords/$flagged': flagged ? true : null }, flagged ? 'flag' : 'unflag');
+}
+/**
+ * Move a thread into one mailbox, out of every other.
+ *
+ * **`mailboxIds` is replaced, not patched.** A message may legitimately sit in
+ * several mailboxes at once, and a "move" that only adds the destination is
+ * the bug where archiving leaves the conversation in the Inbox as well and the
+ * unread count never drops. The whole property is set, which is the one
+ * operation that means what the word means.
+ *
+ * The exception the caller has to know about: a message in Sent that is also
+ * in the Inbox loses the Sent filing when it is archived. That is what every
+ * other client does too, and the alternative -- preserving some mailboxes and
+ * not others -- is a rule nobody can predict.
+ */
+export function moveThread(client, threadId, mailboxId) {
+    return patchThread(client, threadId, { mailboxIds: { [mailboxId]: true } }, 'move');
+}
+/**
+ * Move a thread to the mailbox holding a role -- `archive`, `trash`, `junk`,
+ * `inbox`.
+ *
+ * By role rather than by id because that is how the caller thinks: a toolbar
+ * has an Archive button, not a "move to the mailbox whose id is 4f2" button.
+ * A server that has no such mailbox says so rather than silently doing
+ * nothing, since a delete that quietly fails is the worst kind.
+ */
+export async function moveToRole(client, threadId, role, options = {}) {
+    const tree = options.mailboxes ?? (await mailboxes(client));
+    const target = findRole(tree, role);
+    if (!target) {
+        throw new MailError(`the account has no ${role} mailbox to move to`, {
+            type: 'notFound',
+            operation: 'move',
+        });
+    }
+    return moveThread(client, threadId, target.id);
+}
+/**
+ * Take a thread out of one mailbox and leave whatever else it is in.
+ *
+ * The narrow counterpart to `moveThread`, for the one case where replacement
+ * is wrong: removing a conversation from the Inbox when the point is to keep
+ * its other filings. Patches a single pointer rather than the property.
+ */
+export function removeFromMailbox(client, threadId, mailboxId) {
+    return patchThread(client, threadId, { [`mailboxIds/${pointer(mailboxId)}`]: null }, 'move');
+}

package/dist/mailbox/react/Composer.d.ts

@@ -16,6 +16,11 @@ import type { Draft, EmailAddress, MailIdentity } from '../types.ts';
  * **Cc and Bcc are hidden until wanted.** Three empty address fields at the
  * top of every message is three fields to tab through to reach the subject.
  *
+ * **Cmd-Enter sends.** Reaching for the mouse to finish a message you typed
+ * is the one interruption a composer can always avoid, and every mail client
+ * worth using has had this key since the nineties. The button stays, because
+ * a shortcut nobody is told about is not an affordance.
+ *
  * The draft is the caller's state, so a reply arrives already filled in by
  * `replyDraft` and this is only the surface that edits it.
  */

package/dist/mailbox/react/Composer.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { Button, Field, Identity, Input, Select, Textarea } from '@wtfalch/design';
+import { Button, Field, Icon, Identity, Input, Select, Textarea } from '@wtfalch/design';
 import { useState } from 'react';
 /** Split what somebody typed into addresses. Commas and semicolons both
  *  separate, because both get typed and both get pasted. */
@@ -27,7 +27,16 @@ export function Composer({ draft, onChange, onSend, onCancel, identities, sendin
             event.preventDefault();
             if (canSend)
                 void onSend();
-        }, children: [identities.length > 1 && (_jsx(Field, { label: "From", children: (field) => (_jsx(Select, { id: field.id, block: true, value: draft.identityId, onChange: (event) => set({ identityId: event.target.value }), children: identities.map((identity) => (_jsx("option", { value: identity.id, children: identity.name ? `${identity.name} <${identity.email}>` : identity.email }, identity.id))) })) })), _jsx(AddressField, { label: "To", people: draft.to, onChange: (to) => set({ to }), trail: !showCopies && (_jsx(Button, { kind: "ghost", size: "sm", onClick: () => setShowCopies(true), type: "button", children: "Cc / Bcc" })) }), showCopies && (_jsxs(_Fragment, { children: [_jsx(AddressField, { label: "Cc", people: draft.cc ?? [], onChange: (cc) => set({ cc }) }), _jsx(AddressField, { label: "Bcc", people: draft.bcc ?? [], onChange: (bcc) => set({ bcc }) })] })), _jsx(Field, { label: "Subject", children: (field) => (_jsx(Input, { ...field, block: true, value: draft.subject, onChange: (event) => set({ subject: event.target.value }) })) }), _jsx(Field, { label: "Message", children: (field) => (_jsx(Textarea, { ...field, rows: 12, value: draft.text ?? '', onChange: (event) => set({ text: event.target.value }) })) }), (draft.attachments?.length ?? 0) > 0 && (_jsx("ul", { className: "composer-files", children: draft.attachments?.map((file) => (_jsxs("li", { children: [_jsx("span", { className: "composer-file", children: file.name }), _jsx(Button, { kind: "ghost", size: "sm", type: "button", onClick: () => set({ attachments: draft.attachments?.filter((f) => f.blobId !== file.blobId) }), "aria-label": `Remove ${file.name}`, children: "Remove" })] }, file.blobId))) })), error && (_jsx("p", { className: "composer-error", role: "alert", children: error })), _jsxs("div", { className: "composer-actions", children: [_jsx(Button, { kind: "primary", type: "submit", disabled: !canSend, busy: sending, children: sending ? 'Sending…' : 'Send' }), onCancel && (_jsx(Button, { kind: "ghost", type: "button", onClick: onCancel, disabled: sending, children: "Discard" })), draft.to.length === 0 && _jsx("span", { className: "composer-hint", children: "Add a recipient to send." })] })] }));
+        }, 
+        /* On the form, not the textarea: it should work from the subject and
+           from the address chips too, which is where you notice you are done. */
+        onKeyDown: (event) => {
+            if (event.key !== 'Enter' || !(event.metaKey || event.ctrlKey))
+                return;
+            event.preventDefault();
+            if (canSend)
+                void onSend();
+        }, children: [identities.length > 1 && (_jsx(Field, { label: "From", children: (field) => (_jsx(Select, { id: field.id, block: true, value: draft.identityId, onChange: (event) => set({ identityId: event.target.value }), children: identities.map((identity) => (_jsx("option", { value: identity.id, children: identity.name ? `${identity.name} <${identity.email}>` : identity.email }, identity.id))) })) })), _jsx(AddressField, { label: "To", people: draft.to, onChange: (to) => set({ to }), trail: !showCopies && (_jsx(Button, { kind: "ghost", size: "sm", onClick: () => setShowCopies(true), type: "button", children: "Cc / Bcc" })) }), showCopies && (_jsxs(_Fragment, { children: [_jsx(AddressField, { label: "Cc", people: draft.cc ?? [], onChange: (cc) => set({ cc }) }), _jsx(AddressField, { label: "Bcc", people: draft.bcc ?? [], onChange: (bcc) => set({ bcc }) })] })), _jsx(Field, { label: "Subject", children: (field) => (_jsx(Input, { ...field, block: true, value: draft.subject, onChange: (event) => set({ subject: event.target.value }) })) }), _jsx(Field, { label: "Message", children: (field) => (_jsx(Textarea, { ...field, rows: 12, value: draft.text ?? '', onChange: (event) => set({ text: event.target.value }) })) }), (draft.attachments?.length ?? 0) > 0 && (_jsx("ul", { className: "composer-files", children: draft.attachments?.map((file) => (_jsxs("li", { children: [_jsx("span", { className: "composer-file", children: file.name }), _jsx(Button, { kind: "ghost", size: "sm", type: "button", onClick: () => set({ attachments: draft.attachments?.filter((f) => f.blobId !== file.blobId) }), "aria-label": `Remove ${file.name}`, children: "Remove" })] }, file.blobId))) })), error && (_jsx("p", { className: "composer-error", role: "alert", children: error })), _jsxs("div", { className: "composer-actions", children: [_jsxs(Button, { kind: "primary", type: "submit", disabled: !canSend, busy: sending, children: [_jsx(Icon, { name: "send", size: 15 }), " ", sending ? 'Sending…' : 'Send'] }), onCancel && (_jsx(Button, { kind: "ghost", type: "button", onClick: onCancel, disabled: sending, children: "Discard" })), _jsx("span", { className: "composer-hint", children: draft.to.length === 0 ? ('Add a recipient to send.') : (_jsxs(_Fragment, { children: [_jsx("kbd", { children: "\u2318" }), _jsx("kbd", { children: "\u21B5" }), " to send"] })) })] })] }));
 }
 function AddressField({ label, people, onChange, trail, }) {
     const [typed, setTyped] = useState('');