@wtfalch/email 0.1.1 → 0.4.0

package/dist/mailbox/client.d.ts

@@ -31,13 +31,11 @@ export type MailClientOptions = {
     /** Use a different account than the session's primary one. */
     accountId?: string;
 };
-/**
- * A connection to one JMAP account.
- *
- * Every other module in this package takes one of these. It owns the session
- * document, the account id, and the `jmap-jam` client the wire calls go
- * through; `jmap-jam` itself is not part of this package's public surface.
- */
+/** Passed to every `jmap-jam` call, whose `fetchInit` is spread over the
+ *  request it builds. */
+export declare const JAM_FETCH: {
+    fetchInit: RequestInit;
+};
 export declare class MailClient {
     #private;
     constructor(options: MailClientOptions);

package/dist/mailbox/client.js

@@ -1,5 +1,5 @@
 import { JamClient } from 'jmap-jam';
-import { MailError, guard, toMailError } from "./errors.js";
+import { MailError, guard } from "./errors.js";
 import { expandTemplate } from "./uri.js";
 export const MAIL_CAPABILITY = 'urn:ietf:params:jmap:mail';
 export const SUBMISSION_CAPABILITY = 'urn:ietf:params:jmap:submission';
@@ -16,6 +16,26 @@ function looksLikeSession(value) {
  * document, the account id, and the `jmap-jam` client the wire calls go
  * through; `jmap-jam` itself is not part of this package's public surface.
  */
+/**
+ * Never let the browser answer an authentication challenge for us.
+ *
+ * Every request here carries its own `Authorization` header. If one is
+ * refused, Stalwart answers with both `WWW-Authenticate: Bearer` and
+ * `WWW-Authenticate: Basic`, and a browser that is allowed to use
+ * credentials honours the second by opening its native password prompt —
+ * a modal that hides whatever the application was about to say about the
+ * refusal. `omit` declines that on our behalf: the 401 comes back as an
+ * ordinary response and the application gets to explain it.
+ *
+ * Outside a browser this is inert.
+ */
+const NO_BROWSER_CREDENTIALS = { credentials: 'omit' };
+/** Passed to every `jmap-jam` call, whose `fetchInit` is spread over the
+ *  request it builds. */
+export const JAM_FETCH = { fetchInit: NO_BROWSER_CREDENTIALS };
+/** Handed to `JamClient`'s constructor so its eager session request resolves
+ *  in-process instead of going to the server. See `#open`. */
+const NO_SESSION_URL = 'data:application/json,{}';
 export class MailClient {
     #sessionUrl;
     #wantedAccountId;
@@ -60,37 +80,34 @@ export class MailClient {
     async #open() {
         const authorization = this.#authorization;
         const isBearer = authorization.startsWith('Bearer ');
-        // `JamClient` can only build a `Bearer` header from the string it is
-        // given, so a credential that is not a bearer token (an app password,
-        // which Stalwart takes as Basic) needs the header replaced afterwards.
-        // The constructor has already fired its own session request by then, so
-        // that path reads the session here and discards what the constructor
-        // fetched; the bearer path, which is what the product uses, costs one
-        // request as usual.
+        // `JamClient`'s constructor fires a session request of its own, and we
+        // want neither the request nor its result. It calls `.json()` without
+        // looking at the status, so a refusal arrives as an unreadable parse
+        // error — and, worse, it is a plain same-origin fetch, so a 401 carrying
+        // `WWW-Authenticate: Basic` makes the browser put up its own password
+        // prompt. To a person that is indistinguishable from being asked to sign
+        // in again, on the right domain, when in fact they are already signed in
+        // and the token is the problem.
+        //
+        // So point the constructor at a `data:` URL, which resolves in-process
+        // and never touches the network, and read the session ourselves with the
+        // status checked. `jam.session` is overwritten with that document, and
+        // it is the document — not the URL — that carries `apiUrl`, so nothing
+        // downstream notices.
         const jam = new JamClient({
-            sessionUrl: this.#sessionUrl,
+            sessionUrl: NO_SESSION_URL,
             bearerToken: isBearer ? authorization.slice('Bearer '.length) : '',
         });
-        let doc;
-        if (isBearer) {
-            let loaded;
-            try {
-                loaded = await jam.session;
-            }
-            catch (cause) {
-                // `JamClient.loadSession` calls `.json()` without checking the
-                // status, so a 401 with an HTML body arrives here as a parse error.
-                throw await this.#sessionFailure(authorization, cause);
-            }
-            if (!looksLikeSession(loaded))
-                throw await this.#sessionFailure(authorization, loaded);
-            doc = loaded;
-        }
-        else {
+        // Nothing ever reads the promise the constructor made, and in Node an
+        // unobserved rejection takes the process down. Say so explicitly.
+        void jam.session.catch(() => { });
+        // `JamClient` can only build a `Bearer` header from the string it is
+        // given, so a credential that is not a bearer token — an app password,
+        // which Stalwart takes as Basic — needs the header replaced.
+        if (!isBearer)
             jam.authHeader = authorization;
-            doc = await this.#fetchSession(authorization);
-            jam.session = Promise.resolve(doc);
-        }
+        const doc = await this.#fetchSession(authorization);
+        jam.session = Promise.resolve(doc);
         const accountId = this.#wantedAccountId ?? doc.primaryAccounts?.[MAIL_CAPABILITY];
         if (!accountId) {
             throw new MailError(`the session document names no primary account for ${MAIL_CAPABILITY}; the server may not offer JMAP Mail to this login`, { operation: 'client.connect' });
@@ -110,6 +127,7 @@ export class MailClient {
             response = await fetch(this.#sessionUrl, {
                 headers: { Authorization: authorization, Accept: 'application/json' },
                 cache: 'no-cache',
+                ...NO_BROWSER_CREDENTIALS,
             });
         }
         catch (cause) {
@@ -134,18 +152,6 @@ export class MailClient {
         }
         return parsed;
     }
-    /** Turn a failed or unrecognisable session read into an error that says
-     *  what happened, by asking again with the status checked. */
-    async #sessionFailure(authorization, cause) {
-        try {
-            await this.#fetchSession(authorization);
-        }
-        catch (error) {
-            return toMailError(error, 'client.connect');
-        }
-        // The second read succeeded, so the first was a transient failure.
-        return toMailError(cause, 'client.connect');
-    }
     /** The signed-in person and the account being read. */
     async session() {
         const { doc, accountId } = await this.connect();
@@ -185,6 +191,7 @@ export class MailClient {
         return guard('client.upload', async () => {
             const result = await jam.uploadBlob(accountId, body, {
                 headers: { Authorization: this.#authorization, 'Content-Type': type },
+                ...NO_BROWSER_CREDENTIALS,
             });
             return { blobId: result.blobId, type: result.type, size: result.size };
         });

package/dist/mailbox/identities.d.ts

@@ -1,4 +1,4 @@
-import type { MailClient } from './client.ts';
+import { type MailClient } from './client.ts';
 import type { MailIdentity } from './types.ts';
 /** Every address this account may send as. */
 export declare function identities(client: MailClient): Promise<readonly MailIdentity[]>;

package/dist/mailbox/identities.js

@@ -1,9 +1,10 @@
+import { JAM_FETCH } from "./client.js";
 import { guard } from "./errors.js";
 /** Every address this account may send as. */
 export async function identities(client) {
     const { jam, accountId } = await client.connect();
     return guard('identities', async () => {
-        const [result] = await jam.api.Identity.get({ accountId });
+        const [result] = await jam.api.Identity.get({ accountId }, JAM_FETCH);
         return result.list.map((identity) => ({
             id: identity.id,
             name: identity.name ?? '',

package/dist/mailbox/mailboxes.d.ts

@@ -1,4 +1,4 @@
-import type { MailClient } from './client.ts';
+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 = {

package/dist/mailbox/mailboxes.js

@@ -1,3 +1,4 @@
+import { JAM_FETCH } from "./client.js";
 import { guard } from "./errors.js";
 /** RFC 8621 §2: order by `sortOrder`, and break ties by name. */
 function compare(a, b) {
@@ -101,7 +102,7 @@ export async function mailboxes(client) {
         const [result] = await jam.api.Mailbox.get({
             accountId,
             properties: MAILBOX_PROPERTIES,
-        });
+        }, JAM_FETCH);
         return buildTree(result.list);
     });
 }

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

@@ -1,8 +1,52 @@
 import type { MailClient } from '../client.ts';
+import type { MailError } from '../errors.ts';
+/**
+ * Where the reader is: which mailbox, which conversation.
+ *
+ * Its own type because an application that puts this in the URL has to be
+ * able to name it.
+ */
+export type MailLocation = {
+    mailboxId: string | null;
+    threadId: string | null;
+};
 export type MailProps = {
     client: MailClient;
+    /**
+     * Drive the selection from outside — from the URL, almost always.
+     *
+     * Omit it and the component keeps its own, which is right for a gallery or
+     * an embed. Supply it with `onNavigate` and the two selections become the
+     * application's: `/inbox` and `/thread/abc` can be real addresses that
+     * survive a reload, appear in history and can be sent to someone.
+     *
+     * A partially controlled component is a trap, so this is all or nothing:
+     * pass `location` and you own both fields.
+     */
+    location?: MailLocation;
+    /** Called when something in here wants to move. Required with `location`,
+     *  because without it the controlled selection could never change. */
+    onNavigate?: (to: MailLocation) => void;
+    /**
+     * The right-hand end of the header: who is signed in, and the way out.
+     *
+     * A slot rather than anything this component builds, because `Mail` does
+     * not know how the person got here. It has no idea whether there is a
+     * session, a token, an issuer or a sign-out — and a mail view that grew
+     * opinions about authentication would be a mail view nobody could embed.
+     */
+    account?: React.ReactNode;
+    /**
+     * Called when any of the fetches behind this view fails.
+     *
+     * The views already say "could not load" for themselves; this is for the
+     * application to act on a *class* of failure it alone can answer. The one
+     * that matters is 401: the token expired mid-session, and only the thing
+     * that obtained it can get another.
+     */
+    onError?: (error: MailError) => void;
     /** Now, for the list's relative times. Passed in so stories hold still. */
     now?: Date;
     className?: string;
 };
-export declare function Mail({ client, now, className }: MailProps): import("react").JSX.Element;
+export declare function Mail({ client, location, onNavigate, account, onError, now, className, }: MailProps): import("react").JSX.Element;

package/dist/mailbox/react/Mail.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Button, Command, Icon, Input, Modal, SplitPane } from '@wtfalch/design';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { forwardDraft, replyDraft } from "../drafts.js";
 import { findRole } from "../mailboxes.js";
 import { send } from "../submit.js";
@@ -27,9 +27,25 @@ import { useIdentities, useMailboxes, usePush, useThread, useThreads } from "./h
  * mailboxes as "go to" entries, so moving around never requires the mouse.
  */
 const PAGE = 50;
-export function Mail({ client, now, className }) {
-    const [mailboxId, setMailboxId] = useState(null);
-    const [threadId, setThreadId] = useState(null);
+export function Mail({ client, location, onNavigate, account, onError, now, className, }) {
+    const [ownMailboxId, setOwnMailboxId] = useState(null);
+    const [ownThreadId, setOwnThreadId] = useState(null);
+    /* Controlled when a location was given, and then entirely: reading one
+       field from the caller and the other from here is how a component ends up
+       with two disagreeing ideas of where it is. */
+    const controlled = location !== undefined;
+    const mailboxId = controlled ? location.mailboxId : ownMailboxId;
+    const threadId = controlled ? location.threadId : ownThreadId;
+    const navigate = useCallback((to) => {
+        if (controlled)
+            onNavigate?.(to);
+        else {
+            setOwnMailboxId(to.mailboxId);
+            setOwnThreadId(to.threadId);
+        }
+    }, [controlled, onNavigate]);
+    const setMailboxId = useCallback((next) => navigate({ mailboxId: next, threadId: null }), [navigate]);
+    const setThreadId = useCallback((next) => navigate({ mailboxId, threadId: next }), [navigate, mailboxId]);
     const [position, setPosition] = useState(0);
     const [query, setQuery] = useState('');
     const [text, setText] = useState('');
@@ -48,7 +64,7 @@ export function Mail({ client, now, className }) {
         const inbox = findRole(boxes.data, 'inbox') ?? boxes.data[0];
         if (inbox)
             setMailboxId(inbox.id);
-    }, [boxes.data, mailboxId]);
+    }, [boxes.data, mailboxId, setMailboxId]);
     const threads = useThreads({ mailboxId: mailboxId ?? undefined, text: query, position, limit: PAGE, calculateTotal: true }, client);
     const thread = useThread(threadId, client);
     const refresh = useCallback(() => {
@@ -56,14 +72,24 @@ export function Mail({ client, now, className }) {
         threads.reload();
     }, [boxes.reload, threads.reload]);
     usePush(refresh, client);
+    /* Errors reach the application, but only when they change: these hooks hold
+       their last error while a retry is in flight, so forwarding on every
+       render would call `onError` sixty times for one dead token. */
+    const failure = boxes.error ?? threads.error ?? thread.error ?? identities.error;
+    const reported = useRef(undefined);
+    useEffect(() => {
+        if (!failure || reported.current === failure)
+            return;
+        reported.current = failure;
+        onError?.(failure);
+    }, [failure, onError]);
     const go = useCallback((mailbox) => {
-        setMailboxId(mailbox.id);
-        setThreadId(null);
+        navigate({ mailboxId: mailbox.id, threadId: null });
         setPosition(0);
         setQuery('');
         setText('');
-    }, []);
-    const openThread = useCallback((summary) => setThreadId(summary.id), []);
+    }, [navigate]);
+    const openThread = useCallback((summary) => setThreadId(summary.id), [setThreadId]);
     /* Cmd-K, and Escape out of a search. Bound on the window rather than on a
        container, because the palette has to open from wherever focus is --
        including from inside the message being read. */
@@ -145,5 +171,5 @@ export function Mail({ client, now, className }) {
                                     return;
                                 setText('');
                                 setQuery('');
-                            } }) }), _jsx(Button, { kind: "ghost", onClick: () => setPaletteOpen(true), "aria-label": "Open the palette", children: _jsx(Icon, { name: "bolt" }) })] }), _jsxs(SplitPane, { className: "mail-panes", label: "Mailbox list width", defaultSize: 22, min: 14, max: 40, storageKey: "mail-sidebar", children: [_jsx(MailboxTree, { mailboxes: boxes.data ?? [], selectedId: mailboxId, onSelect: go, loading: boxes.loading }), _jsxs(SplitPane, { label: "Conversation list width", defaultSize: 38, min: 22, max: 60, storageKey: "mail-list", children: [_jsx(ThreadList, { page: threads.data, selectedId: threadId, onSelect: openThread, onPage: setPosition, limit: PAGE, loading: threads.loading, now: now, empty: query ? _jsxs("p", { className: "threads-quiet", children: ["Nothing matches \u201C", query, "\u201D."] }) : undefined }), _jsx(ThreadView, { thread: thread.data, loading: thread.loading, onReply: startReply, onForward: startForward })] })] }), _jsx(Command, { open: paletteOpen, onOpenChange: setPaletteOpen, groups: paletteGroups }), draft && (_jsx(Modal, { title: "New message", width: "46rem", onClose: sending ? undefined : () => setDraft(null), closeDisabled: sending, children: _jsx(Composer, { draft: draft, onChange: setDraft, onSend: doSend, onCancel: () => setDraft(null), identities: identities.data ?? [], sending: sending, error: sendError }) }))] }));
+                            } }) }), _jsx(Button, { kind: "ghost", onClick: () => setPaletteOpen(true), "aria-label": "Open the palette", children: _jsx(Icon, { name: "bolt" }) }), account] }), _jsxs(SplitPane, { className: "mail-panes", label: "Mailbox list width", defaultSize: 22, min: 14, max: 40, storageKey: "mail-sidebar", children: [_jsx(MailboxTree, { mailboxes: boxes.data ?? [], selectedId: mailboxId, onSelect: go, loading: boxes.loading }), _jsxs(SplitPane, { label: "Conversation list width", defaultSize: 38, min: 22, max: 60, storageKey: "mail-list", children: [_jsx(ThreadList, { page: threads.data, selectedId: threadId, onSelect: openThread, onPage: setPosition, limit: PAGE, loading: threads.loading, now: now, empty: query ? _jsxs("p", { className: "threads-quiet", children: ["Nothing matches \u201C", query, "\u201D."] }) : undefined }), _jsx(ThreadView, { thread: thread.data, loading: thread.loading, onReply: startReply, onForward: startForward })] })] }), _jsx(Command, { open: paletteOpen, onOpenChange: setPaletteOpen, groups: paletteGroups }), draft && (_jsx(Modal, { title: "New message", width: "46rem", onClose: sending ? undefined : () => setDraft(null), closeDisabled: sending, children: _jsx(Composer, { draft: draft, onChange: setDraft, onSend: doSend, onCancel: () => setDraft(null), identities: identities.data ?? [], sending: sending, error: sendError }) }))] }));
 }

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

@@ -21,4 +21,4 @@ export type { ThreadViewProps } from './ThreadView.tsx';
 export { Composer, parseAddresses } from './Composer.tsx';
 export type { ComposerProps } from './Composer.tsx';
 export { Mail } from './Mail.tsx';
-export type { MailProps } from './Mail.tsx';
+export type { MailLocation, MailProps } from './Mail.tsx';

package/dist/mailbox/submit.d.ts

@@ -1,4 +1,4 @@
-import type { MailClient } from './client.ts';
+import { type MailClient } from './client.ts';
 import type { Draft, EmailAddress, MailIdentity, MailboxNode, Sent } from './types.ts';
 /** The JMAP `Email` object a draft becomes. Exported so the shape can be
  *  asserted without a server. */

package/dist/mailbox/submit.js

@@ -1,3 +1,4 @@
+import { JAM_FETCH } from "./client.js";
 import { MailError, guard } from "./errors.js";
 import { identities } from "./identities.js";
 import { findRole, mailboxes } from "./mailboxes.js";
@@ -119,7 +120,7 @@ export async function send(client, draft, options = {}) {
         const [created] = await jam.api.Email.set({
             accountId,
             create: { draft: draftToEmail(draft, from, drafts.id) },
-        });
+        }, JAM_FETCH);
         const email = created.created?.draft;
         if (!email)
             failed('draft', created.notCreated);
@@ -137,7 +138,7 @@ export async function send(client, draft, options = {}) {
         // declare the mail capability as well as submission. jmap-jam derives
         // capabilities from the method names alone and would send only
         // submission and core.
-        { using: ['urn:ietf:params:jmap:mail'] });
+        { using: ['urn:ietf:params:jmap:mail'], ...JAM_FETCH });
         const submission = submitted.created?.submission;
         if (!submission)
             failed('submission', submitted.notCreated);

package/dist/mailbox/thread.d.ts

@@ -1,4 +1,4 @@
-import type { MailClient } from './client.ts';
+import { type MailClient } from './client.ts';
 import type { EmailAddress, Message, ThreadDetail } from './types.ts';
 /** A body part as `Email/get` returns it. */
 type BodyPart = {

package/dist/mailbox/thread.js

@@ -1,3 +1,4 @@
+import { JAM_FETCH } from "./client.js";
 import { MailError, guard } from "./errors.js";
 import { expandTemplate } from "./uri.js";
 const MESSAGE_PROPERTIES = [
@@ -125,7 +126,7 @@ export async function thread(client, threadId, options = {}) {
                 maxBodyValueBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
             });
             return { threads, messages };
-        });
+        }, JAM_FETCH);
         const found = results.threads.list;
         if (found.length === 0) {
             throw new MailError(`no thread ${threadId} in this account`, {

package/dist/mailbox/threads.d.ts

@@ -1,4 +1,4 @@
-import type { MailClient } from './client.ts';
+import { type MailClient } from './client.ts';
 import type { EmailAddress, MailFilter, MailSort, ThreadPage, ThreadSummary } from './types.ts';
 type SummaryEmail = {
     id: string;

package/dist/mailbox/threads.js

@@ -1,3 +1,4 @@
+import { JAM_FETCH } from "./client.js";
 import { guard } from "./errors.js";
 /** What a list row needs from the newest message in each thread. */
 const SUMMARY_PROPERTIES = [
@@ -121,7 +122,7 @@ export async function queryThreads(client, filter, options = {}) {
                 properties: MEMBER_PROPERTIES,
             });
             return { query, latest, threads, members };
-        });
+        }, JAM_FETCH);
         const query = results.query;
         const latest = results.latest;
         const threads = results.threads;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/email",
-  "version": "0.1.1",
+  "version": "0.4.0",
   "description": "The wtfalch estate: reading a mailbox over JMAP, and administering the Stalwart server it lives on. Two entries with no code in common.",
   "license": "MIT",
   "type": "module",
@@ -33,11 +33,14 @@
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "dist",
-    "LICENSE",
-    "README.md"
-  ],
+  "files": ["dist", "LICENSE", "README.md"],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/mailbox/react/mail.css dist/mailbox/mail.css",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "record-fixtures": "node scripts/record-fixtures.mjs"
+  },
   "peerDependencies": {
     "@wtfalch/design": ">=0.4.0",
     "react": "^19.0.0",
@@ -72,20 +75,8 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "keywords": [
-    "jmap",
-    "email",
-    "mail",
-    "stalwart",
-    "rfc8621"
-  ],
+  "keywords": ["jmap", "email", "mail", "stalwart", "rfc8621"],
   "dependencies": {
     "jmap-jam": "^0.13.6"
-  },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/mailbox/react/mail.css dist/mailbox/mail.css",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "record-fixtures": "node scripts/record-fixtures.mjs"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 William Tallis Falch
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.