@wtfalch/email 0.1.0

package/dist/mailbox/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@wtfalch/mail` — a JMAP mail client core.
+ *
+ * Everything takes a `MailClient` and returns this package's own shapes. The
+ * JMAP wire, and the `jmap-jam` client that speaks it, stay inside.
+ */
+export { MailClient, MAIL_CAPABILITY, SUBMISSION_CAPABILITY } from './client.ts';
+export type { MailClientOptions } from './client.ts';
+export { MailError, toMailError } from './errors.ts';
+export type { ProblemDetails } from './errors.ts';
+export { buildTree, findRole, mailboxes, walk } from './mailboxes.ts';
+export type { FlatMailbox } from './mailboxes.ts';
+export { listThreads, queryThreads, summarise } from './threads.ts';
+export type { ListOptions } from './threads.ts';
+export { DEFAULT_MAX_BODY_BYTES, thread, toMessage } from './thread.ts';
+export type { RawMessage, ThreadOptions } from './thread.ts';
+export { search } from './search.ts';
+export type { SearchOptions } from './search.ts';
+export { identities } from './identities.ts';
+export { attribution, formatAddress, forwardDraft, forwardIntroduction, forwardSubject, quoteText, replyDraft, replySubject, } from './drafts.ts';
+export type { ForwardOptions, ReplyOptions } from './drafts.ts';
+export { draftToEmail, send, sentPatch } from './submit.ts';
+export type { SendOptions } from './submit.ts';
+export { push } from './push.ts';
+export type { PushHandle, PushOptions } from './push.ts';
+export { expandTemplate } from './uri.ts';
+export type { Attachment, ChangedState, Draft, DraftAttachment, EmailAddress, MailFilter, MailIdentity, MailSession, MailSort, MailboxNode, MailboxRole, Message, Sent, ThreadDetail, ThreadPage, ThreadSummary, } from './types.ts';

package/dist/mailbox/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@wtfalch/mail` — a JMAP mail client core.
+ *
+ * Everything takes a `MailClient` and returns this package's own shapes. The
+ * JMAP wire, and the `jmap-jam` client that speaks it, stay inside.
+ */
+export { MailClient, MAIL_CAPABILITY, SUBMISSION_CAPABILITY } from "./client.js";
+export { MailError, toMailError } from "./errors.js";
+export { buildTree, findRole, mailboxes, walk } from "./mailboxes.js";
+export { listThreads, queryThreads, summarise } from "./threads.js";
+export { DEFAULT_MAX_BODY_BYTES, thread, toMessage } from "./thread.js";
+export { search } from "./search.js";
+export { identities } from "./identities.js";
+export { attribution, formatAddress, forwardDraft, forwardIntroduction, forwardSubject, quoteText, replyDraft, replySubject, } from "./drafts.js";
+export { draftToEmail, send, sentPatch } from "./submit.js";
+export { push } from "./push.js";
+export { expandTemplate } from "./uri.js";

package/dist/mailbox/mail.css

@@ -0,0 +1,451 @@
+/* The mail client's own layout. Everything visual comes from
+   `@wtfalch/design`'s tokens; nothing here defines a colour, a radius or a
+   space of its own. Import it after the design stylesheet. */
+
+.mail {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+  background: var(--bg);
+  color: var(--text);
+  font-size: var(--text-sm);
+}
+
+.mail-bar {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  padding: var(--space-3);
+  border-bottom: var(--border-width) solid var(--border);
+  flex: none;
+}
+
+.mail-search {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+.mail-panes {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+/* ---------------------------------------------------------------- mailboxes */
+.mailboxes {
+  height: 100%;
+  background: var(--panel);
+}
+.mailboxes-quiet,
+.threads-quiet,
+.message-quiet {
+  margin: 0;
+  padding: var(--space-4);
+  color: var(--muted);
+  font-size: var(--text-xs);
+}
+
+.mailboxes-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.mailboxes-list .mailboxes-list {
+  padding-left: var(--space-3);
+}
+
+.mailbox {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  width: 100%;
+  padding: var(--space-2) var(--space-3);
+  padding-left: calc(var(--space-3) + var(--depth, 0) * var(--space-3));
+  border: none;
+  background: transparent;
+  color: var(--muted);
+  font: inherit;
+  font-size: var(--text-sm);
+  text-align: left;
+  cursor: pointer;
+}
+
+.mailbox:hover {
+  background: var(--panel-2);
+  color: var(--text);
+}
+.mailbox:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+}
+.mailbox.on {
+  background: var(--panel-2);
+  color: var(--text);
+}
+/* Unread is weight, so it survives a theme, a projector and a reader who
+   cannot tell the colours apart. */
+.mailbox.unread {
+  color: var(--text);
+  font-weight: var(--weight-strong);
+}
+
+.mailbox-icon {
+  flex: none;
+  width: var(--space-4);
+  height: var(--space-4);
+}
+.mailbox-name {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.mailbox-count {
+  flex: none;
+  font-size: var(--text-2xs);
+  font-variant-numeric: tabular-nums;
+}
+
+/* ------------------------------------------------------------------ threads */
+.threads {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+  background: var(--panel);
+}
+.threads-scroll {
+  flex: 1 1 auto;
+}
+.threads-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.threads-pager {
+  flex: none;
+  padding: 0 var(--space-3);
+  border-top: var(--border-width) solid var(--border);
+}
+
+.thread-row {
+  display: grid;
+  gap: var(--space-1);
+  width: 100%;
+  padding: var(--space-3);
+  border: none;
+  border-bottom: var(--border-width) solid var(--border);
+  background: transparent;
+  color: var(--muted);
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.thread-row:hover {
+  background: var(--panel-2);
+}
+.thread-row:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+}
+.thread-row.on {
+  background: var(--panel-2);
+}
+.thread-row.unread {
+  color: var(--text);
+}
+.thread-row.unread .thread-subject-text {
+  font-weight: var(--weight-strong);
+}
+
+.thread-top {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+.thread-who {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+.thread-nobody {
+  color: var(--muted);
+  font-style: italic;
+}
+.thread-when {
+  flex: none;
+  font-size: var(--text-2xs);
+  color: var(--muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.thread-subject {
+  display: flex;
+  align-items: baseline;
+  gap: var(--space-2);
+  min-width: 0;
+}
+.thread-dot {
+  flex: none;
+  color: var(--accent);
+}
+.thread-subject-text {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.thread-count {
+  flex: none;
+  padding: 0 var(--space-1);
+  border: var(--border-width) solid var(--border);
+  border-radius: var(--radius-pill);
+  font-size: var(--text-2xs);
+  color: var(--muted);
+}
+
+.thread-preview {
+  color: var(--muted);
+  font-size: var(--text-xs);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.thread-marks {
+  display: flex;
+  gap: var(--space-1);
+  flex-wrap: wrap;
+}
+
+/* --------------------------------------------------------------- one thread */
+.thread {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+.thread-head {
+  flex: none;
+  padding: var(--space-4);
+  border-bottom: var(--border-width) solid var(--border);
+}
+.thread-title {
+  margin: 0;
+  font-size: var(--text-lg);
+  font-weight: var(--weight-strong);
+}
+.thread-meta {
+  margin: var(--space-1) 0 0;
+  color: var(--muted);
+  font-size: var(--text-xs);
+}
+.thread-body {
+  flex: 1 1 auto;
+}
+
+.messages {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.message {
+  border-bottom: var(--border-width) solid var(--border);
+}
+.message-head {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: 0 var(--space-4);
+}
+
+.message-toggle {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: var(--space-3) 0;
+  border: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.message-toggle:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+}
+.message-when {
+  flex: none;
+  margin-left: auto;
+  color: var(--muted);
+  font-size: var(--text-2xs);
+}
+.message-nobody {
+  color: var(--muted);
+  font-style: italic;
+}
+
+.message-body {
+  padding: 0 var(--space-4) var(--space-4);
+}
+.message-lines {
+  margin-bottom: var(--space-3);
+}
+.message-line {
+  margin: 0;
+  color: var(--muted);
+  font-size: var(--text-xs);
+  display: flex;
+  gap: var(--space-2);
+}
+.message-line-label {
+  min-width: var(--space-6);
+}
+
+/* Plain-text mail carries its own line breaks and its own quote markers.
+   Reflowing it destroys both, so it is shown as written. */
+.message-text,
+.message-source {
+  margin: 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font-family: inherit;
+  font-size: var(--text-sm);
+  line-height: var(--line-height);
+  color: var(--text);
+}
+
+.message-source {
+  margin-top: var(--space-2);
+  padding: var(--space-3);
+  border-radius: var(--radius);
+  background: var(--panel-2);
+  font-family: var(--font-mono);
+  font-size: var(--text-xs);
+  max-height: 20rem;
+  overflow: auto;
+}
+
+.message-html {
+  display: grid;
+  gap: var(--space-2);
+  justify-items: start;
+}
+
+.attachments {
+  list-style: none;
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  margin: var(--space-4) 0 0;
+  padding: 0;
+}
+
+.attachment {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-2) var(--space-3);
+  border: var(--border-width) solid var(--border);
+  border-radius: var(--radius);
+  background: var(--panel-2);
+  color: var(--text);
+  font: inherit;
+  font-size: var(--text-xs);
+  cursor: pointer;
+}
+
+.attachment:hover:not(:disabled) {
+  border-color: var(--accent);
+}
+.attachment:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+}
+.attachment:disabled {
+  cursor: default;
+  color: var(--muted);
+}
+.attachment-icon {
+  flex: none;
+  width: var(--space-4);
+  height: var(--space-4);
+  color: var(--muted);
+}
+.attachment-size {
+  color: var(--muted);
+}
+
+/* ----------------------------------------------------------------- composer */
+.composer {
+  display: grid;
+  gap: var(--space-3);
+}
+
+.composer-addresses {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-1);
+  padding: var(--space-1);
+  border: var(--border-width) solid var(--border);
+  border-radius: var(--radius);
+  background: var(--control);
+}
+
+.composer-addresses:focus-within {
+  border-color: var(--accent);
+}
+
+/* The input is a seam in the row of chips rather than a box of its own: two
+   nested boxes make the field look broken at every width. */
+.composer-address-input {
+  flex: 1 1 8rem;
+  min-width: 6rem;
+  border: none;
+  background: transparent;
+  box-shadow: none;
+}
+
+.composer-address-input:focus {
+  outline: none;
+  box-shadow: none;
+}
+
+.composer-files {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: grid;
+  gap: var(--space-1);
+}
+.composer-files li {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+.composer-file {
+  font-size: var(--text-xs);
+}
+
+.composer-actions {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+.composer-hint {
+  color: var(--muted);
+  font-size: var(--text-xs);
+}
+.composer-error {
+  margin: 0;
+  color: var(--bad);
+  font-size: var(--text-xs);
+}

package/dist/mailbox/mailboxes.d.ts

@@ -0,0 +1,33 @@
+import type { MailClient } from './client.ts';
+import type { MailboxNode, MailboxRole } from './types.ts';
+/** A mailbox as the server returns it, before the tree is built. */
+export type FlatMailbox = {
+    id: string;
+    name: string;
+    parentId: string | null;
+    role: MailboxRole | null;
+    sortOrder: number;
+    totalEmails: number;
+    unreadEmails: number;
+    totalThreads: number;
+    unreadThreads: number;
+    isSubscribed: boolean;
+};
+/**
+ * Build the mailbox tree from the flat list the server returns.
+ *
+ * Two shapes the server can legally produce, and one it should not, all have
+ * to come out as a usable tree:
+ *
+ * - a mailbox whose parent is not in the list (the account may hide it, or
+ *   the list may be a filtered subset) becomes a root, so it stays visible;
+ * - a cycle, which RFC 8621 forbids but nothing on the wire prevents, is
+ *   broken by only visiting each mailbox once.
+ */
+export declare function buildTree(list: readonly FlatMailbox[]): readonly MailboxNode[];
+/** Walk a tree depth-first, parents before children. */
+export declare function walk(nodes: readonly MailboxNode[]): Generator<MailboxNode>;
+/** The first mailbox with a given role, e.g. `drafts`. */
+export declare function findRole(nodes: readonly MailboxNode[], role: MailboxRole): MailboxNode | undefined;
+/** Every mailbox in the account, as a tree. */
+export declare function mailboxes(client: MailClient): Promise<readonly MailboxNode[]>;

package/dist/mailbox/mailboxes.js

@@ -0,0 +1,107 @@
+import { guard } from "./errors.js";
+/** RFC 8621 §2: order by `sortOrder`, and break ties by name. */
+function compare(a, b) {
+    if (a.sortOrder !== b.sortOrder)
+        return a.sortOrder - b.sortOrder;
+    const left = a.name.toLowerCase();
+    const right = b.name.toLowerCase();
+    if (left !== right)
+        return left < right ? -1 : 1;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/**
+ * Build the mailbox tree from the flat list the server returns.
+ *
+ * Two shapes the server can legally produce, and one it should not, all have
+ * to come out as a usable tree:
+ *
+ * - a mailbox whose parent is not in the list (the account may hide it, or
+ *   the list may be a filtered subset) becomes a root, so it stays visible;
+ * - a cycle, which RFC 8621 forbids but nothing on the wire prevents, is
+ *   broken by only visiting each mailbox once.
+ */
+export function buildTree(list) {
+    const byId = new Map(list.map((mailbox) => [mailbox.id, mailbox]));
+    const childrenOf = new Map();
+    for (const mailbox of list) {
+        const parentId = mailbox.parentId !== null && byId.has(mailbox.parentId) ? mailbox.parentId : null;
+        const siblings = childrenOf.get(parentId);
+        if (siblings)
+            siblings.push(mailbox);
+        else
+            childrenOf.set(parentId, [mailbox]);
+    }
+    for (const siblings of childrenOf.values())
+        siblings.sort(compare);
+    const visited = new Set();
+    const build = (mailbox, ancestry) => {
+        visited.add(mailbox.id);
+        const path = [...ancestry, mailbox.name];
+        const children = (childrenOf.get(mailbox.id) ?? [])
+            .filter((child) => !visited.has(child.id))
+            .map((child) => build(child, path));
+        return {
+            id: mailbox.id,
+            name: mailbox.name,
+            parentId: mailbox.parentId,
+            role: mailbox.role,
+            sortOrder: mailbox.sortOrder,
+            totalEmails: mailbox.totalEmails,
+            unreadEmails: mailbox.unreadEmails,
+            totalThreads: mailbox.totalThreads,
+            unreadThreads: mailbox.unreadThreads,
+            isSubscribed: mailbox.isSubscribed,
+            path,
+            children,
+        };
+    };
+    const roots = (childrenOf.get(null) ?? []).map((mailbox) => build(mailbox, []));
+    // Anything a cycle kept out of the tree is attached at the root rather than
+    // dropped: a mailbox the caller cannot see is worse than one shown flat.
+    // `visited` is re-read as the loop goes, because building one stranded
+    // mailbox pulls the rest of its cycle in as children.
+    const stranded = [];
+    for (const mailbox of [...list].sort(compare)) {
+        if (visited.has(mailbox.id))
+            continue;
+        stranded.push(build(mailbox, []));
+    }
+    return [...roots, ...stranded];
+}
+/** Walk a tree depth-first, parents before children. */
+export function* walk(nodes) {
+    for (const node of nodes) {
+        yield node;
+        yield* walk(node.children);
+    }
+}
+/** The first mailbox with a given role, e.g. `drafts`. */
+export function findRole(nodes, role) {
+    for (const node of walk(nodes))
+        if (node.role === role)
+            return node;
+    return undefined;
+}
+const MAILBOX_PROPERTIES = [
+    'id',
+    'name',
+    'parentId',
+    'role',
+    'sortOrder',
+    'totalEmails',
+    'unreadEmails',
+    'totalThreads',
+    'unreadThreads',
+    'isSubscribed',
+];
+/** Every mailbox in the account, as a tree. */
+export async function mailboxes(client) {
+    const { jam, accountId } = await client.connect();
+    return guard('mailboxes', async () => {
+        const [result] = await jam.api.Mailbox.get({
+            accountId,
+            properties: MAILBOX_PROPERTIES,
+        });
+        return buildTree(result.list);
+    });
+}

package/dist/mailbox/push.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Push, as server-sent events.
+ *
+ * RFC 8620 §7.3 puts the event source behind the same authentication as the
+ * API, and the browser `EventSource` cannot send an `Authorization` header —
+ * it has no way to set headers at all. `jmap-jam`'s `connectEventSource`
+ * therefore only works against a server that accepts a cookie or a token in
+ * the query string, which is not what a bearer token is.
+ *
+ * So the stream is read with `fetch`, which takes the same header every other
+ * request carries, and the handful of lines of SSE framing are parsed here.
+ * This works unchanged in a browser and in Node.
+ */
+import type { MailClient } from './client.ts';
+import type { ChangedState } from './types.ts';
+export type PushOptions = {
+    /** Which types to be told about. `*` is everything. */
+    types?: readonly string[] | '*';
+    /** Seconds between the server's keep-alive pings. */
+    ping?: number;
+    /** Called when the connection drops and again when it comes back, so a UI
+     *  can say it is stale. */
+    onConnectionChange?: (connected: boolean) => void;
+    /** Called for an error that did not stop the retry loop. */
+    onError?: (error: unknown) => void;
+};
+export type PushHandle = {
+    /** Stop listening. The connection closes and no handler runs again. */
+    close: () => void;
+};
+/**
+ * Watch for changes on the account.
+ *
+ * `handler` is called with the changed state strings for this account; a
+ * value that differs from the one a previous read returned means that type
+ * has changed and its list should be refetched. The stream reconnects on its
+ * own with a backoff, so the handle only has to be closed when the caller is
+ * finished with it.
+ */
+export declare function push(client: MailClient, handler: (changed: ChangedState) => void, options?: PushOptions): PushHandle;