@rapidmx/web-client 0.25.1 → 0.27.0

package/dist/apps/shared/components/contacts/ContactCardProvider.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import { parseVCards } from "../../../../lib/contacts/vcard.js";
+import { listMailboxes } from "../../../../lib/mail/mailApi.js";
+import { useApiClient } from "../../../../lib/util/apiClientContext.js";
+import { MAILBOX_LIST_LIMIT, MailConnectionContext } from "../../mail/useMailConnection.js";
+import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
+import ContactCard from "./ContactCard.js";
+import { addCardsToAddressBook, contactScope, loadFolders, scopeMailboxes } from "./contactCardData.js";
+const CardContext = createContext({ show: () => undefined, addVCards: () => Promise.resolve({ added: 0, skipped: 0 }), available: false });
+/** Shows a person's contact card from anywhere inside `AppShell` - see `ContactCard`. */
+export function useContactCard() {
+    return useContext(CardContext);
+}
+/**
+ * Owns the one contact card that can be open. Mounted once in `AppShell` (inside the compose provider, whose windows the card's "Email" opens), so
+ * a participant is clickable in every app. The card is a modal: focus goes into it, and back to the participant that was clicked when it closes.
+ */
+export default function ContactCardProvider({ children, userUid }) {
+    const client = useApiClient();
+    const connection = useContext(MailConnectionContext);
+    const [shown, setShown] = useState(null);
+    const show = useCallback((participant, context) => {
+        setShown((previous) => ({ participant, context, id: (previous?.id ?? 0) + 1 }));
+    }, []);
+    const addVCards = useCallback(async (text, message) => {
+        const cards = parseVCards(text);
+        // The frame's mailboxes when it has them; a page rendered outside it asks.
+        const mailboxes = connection?.status === "ready" ? connection.mailboxes : await listMailboxes({ limit: MAILBOX_LIST_LIMIT }, client);
+        const folders = await loadFolders(scopeMailboxes(mailboxes, userUid, message), client);
+        const result = await addCardsToAddressBook(cards, contactScope(mailboxes, folders, userUid, message), client);
+        clearPinnedSignerCache();
+        return result;
+    }, [connection, client, userUid]);
+    const value = useMemo(() => ({ show, addVCards, available: true }), [show, addVCards]);
+    return (_jsxs(CardContext.Provider, { value: value, children: [children, shown && _jsx(ContactCard, { participant: shown.participant, context: shown.context, userUid: userUid, onClose: () => setShown(null) }, shown.id)] }));
+}

package/dist/apps/shared/components/contacts/ContactDetailPane.d.ts

@@ -11,6 +11,8 @@ export interface ContactDetailPaneProps {
     /** Called after one of the contact's key changes was accepted or kept, or turned out to be stale - the caller
      * re-reads the contact. */
     onKeysChanged?: () => void;
+    /** Called with the contact after the star was toggled, so the caller shows the changed contact. */
+    onChanged?: (contact: Contact) => void;
     /** `false` when the reader is known not to be able to change this contact's keys (the actions are hidden); `undefined`
      * when unknown (they're hidden after a 403). */
     canResolveKeys?: boolean;
@@ -20,4 +22,4 @@ export interface ContactDetailPaneProps {
  * always visible alongside the contact list) and the mobile detail route
  * (`apps/www/contacts/[uid].tsx`, a full page on its own reached by tapping a contact row).
  */
-export default function ContactDetailPane({ contact, onEdit, onDelete, backHref, onKeysChanged, canResolveKeys }: ContactDetailPaneProps): React.JSX.Element;
+export default function ContactDetailPane({ contact, onEdit, onDelete, backHref, onKeysChanged, onChanged, canResolveKeys }: ContactDetailPaneProps): React.JSX.Element;

package/dist/apps/shared/components/contacts/ContactDetailPane.js

@@ -4,6 +4,11 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { useState } from "react";
+import { contactPhotoUrl, setContactFavorite } from "../../../../lib/contacts/contactsApi.js";
+import CopyIconButton from "../../../../lib/components/buttons/CopyIconButton.js";
+import { useApiClient } from "../../../../lib/util/apiClientContext.js";
+import { notifyApiError } from "../../notifications/apiErrors.js";
+import FavoriteStarButton from "./FavoriteStarButton.js";
 import Button from "../../../../lib/components/buttons/Button.js";
 import ContactAvatar from "../../../../lib/components/avatar/ContactAvatar.js";
 import KeyChangeReview from "./KeyChangeReview.js";
@@ -27,19 +32,29 @@ function RevocationBadge({ label }) {
  * always visible alongside the contact list) and the mobile detail route
  * (`apps/www/contacts/[uid].tsx`, a full page on its own reached by tapping a contact row).
  */
-export default function ContactDetailPane({ contact, onEdit, onDelete, backHref, onKeysChanged, canResolveKeys }) {
+export default function ContactDetailPane({ contact, onEdit, onDelete, backHref, onKeysChanged, onChanged, canResolveKeys }) {
+    const client = useApiClient();
     // The outcome of the last key decision, kept per contact so selecting another contact doesn't carry it over.
     const [keyNotice, setKeyNotice] = useState(null);
     const notice = keyNotice?.contactUid === contact.uid ? keyNotice.text : null;
     const keyConflicts = contact.keyConflicts ?? [];
     const previousKeys = contact.previousKeys ?? [];
+    async function handleToggleFavorite() {
+        try {
+            const changed = await setContactFavorite(contact, !contact.favorite, client);
+            onChanged?.(changed);
+        }
+        catch (err) {
+            notifyApiError(err, "Couldn't update this contact");
+        }
+    }
     // Pinned signing keys vouch for signatures, so the pinned-signer cache is dropped along with re-reading the contact.
     function refresh(text) {
         setKeyNotice({ contactUid: contact.uid, text });
         clearPinnedSignerCache();
         onKeysChanged?.();
     }
-    return (_jsxs("div", { role: "region", "aria-label": "Contact details", className: "max-w-xl flex flex-col gap-5", children: [backHref && (_jsx("a", { href: backHref, className: "text-sm text-primary-dark hover:underline", children: "\u2190 Back to contacts" })), _jsxs("div", { className: "flex items-start justify-between gap-4", children: [_jsxs("div", { className: "flex items-center gap-3", children: [_jsx(ContactAvatar, { displayName: contact.displayName, size: 48 }), _jsxs("div", { children: [_jsx("h1", { className: "text-xl font-bold tracking-tight", children: contact.displayName }), contact.jobTitle && contact.company && (_jsxs("p", { className: "text-sm text-text-muted mt-0.5", children: [contact.jobTitle, " at ", contact.company] }))] })] }), _jsxs("div", { className: "flex gap-2 shrink-0", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onEdit, children: "Edit" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto text-danger", onClick: onDelete, children: "Delete" })] })] }), _jsxs("div", { className: "bg-surface border border-border rounded-md p-6 flex flex-col gap-4 text-sm", children: [contact.emails.length > 0 && (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Email" }), contact.emails.map((e, i) => (_jsxs("div", { children: [e.address, " ", _jsxs("span", { className: "text-text-muted", children: ["(", e.type, ")"] })] }, i)))] })), contact.phones.length > 0 && (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Phone" }), contact.phones.map((p, i) => (_jsxs("div", { children: [p.phoneNumber, " ", _jsxs("span", { className: "text-text-muted", children: ["(", p.type, ")"] })] }, i)))] })), contact.addresses.length > 0 && (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Address" }), contact.addresses.map((a, i) => (_jsx("div", { children: [a.street, a.city, a.state, a.postalCode, a.country].filter(Boolean).join(", ") }, i)))] })), contact.categories && contact.categories.length > 0 && (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Categories" }), _jsx("div", { children: contact.categories.join(", ") })] })), contact.notes && (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Notes" }), _jsx("div", { children: contact.notes })] })), (contact.keys && contact.keys.length > 0) ||
+    return (_jsxs("div", { role: "region", "aria-label": "Contact details", className: "max-w-xl flex flex-col gap-5", children: [backHref && (_jsx("a", { href: backHref, className: "text-sm text-primary-dark hover:underline", children: "\u2190 Back to contacts" })), _jsxs("div", { className: "flex items-start justify-between gap-4", children: [_jsxs("div", { className: "flex items-center gap-3", children: [_jsx(ContactAvatar, { displayName: contact.displayName, size: 48, photoUrl: contactPhotoUrl(contact), email: contact.emails[0]?.address }), _jsxs("div", { children: [_jsxs("h1", { className: "text-xl font-bold tracking-tight", children: [contact.displayName, _jsx(FavoriteStarButton, { favorite: !!contact.favorite, onToggle: () => void handleToggleFavorite(), className: "ml-1 align-middle" })] }), contact.jobTitle && contact.company && (_jsxs("p", { className: "text-sm text-text-muted mt-0.5", children: [contact.jobTitle, " at ", contact.company] }))] })] }), _jsxs("div", { className: "flex gap-2 shrink-0", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onEdit, children: "Edit" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto text-danger", onClick: onDelete, children: "Delete" })] })] }), _jsxs("div", { className: "bg-surface border border-border rounded-md p-6 flex flex-col gap-4 text-sm", children: [contact.emails.length > 0 && (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Email" }), contact.emails.map((e, i) => (_jsxs("div", { children: [e.address, _jsx(CopyIconButton, { value: e.address, label: "Copy email address", className: "mx-0.5" }), " ", _jsxs("span", { className: "text-text-muted", children: ["(", e.type, ")"] })] }, i)))] })), contact.phones.length > 0 && (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Phone" }), contact.phones.map((p, i) => (_jsxs("div", { children: [p.phoneNumber, " ", _jsxs("span", { className: "text-text-muted", children: ["(", p.type, ")"] })] }, i)))] })), contact.addresses.length > 0 && (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Address" }), contact.addresses.map((a, i) => (_jsx("div", { children: [a.street, a.city, a.state, a.postalCode, a.country].filter(Boolean).join(", ") }, i)))] })), contact.categories && contact.categories.length > 0 && (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Categories" }), _jsx("div", { children: contact.categories.join(", ") })] })), contact.notes && (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Notes" }), _jsx("div", { children: contact.notes })] })), (contact.keys && contact.keys.length > 0) ||
                         contact.encryptPreference ||
                         keyConflicts.length > 0 ||
                         previousKeys.length > 0 ? (_jsxs("div", { children: [_jsx("div", { className: "text-text-muted text-xs font-bold uppercase tracking-wide mb-1", children: "Encryption" }), notice && (_jsx("p", { role: "status", className: "mb-2 py-2 px-3 rounded-sm bg-surface-alt text-text", children: notice })), keyConflicts.map((conflict) => {

package/dist/apps/shared/components/contacts/ContactForm.js

@@ -5,10 +5,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 ///////////////////////////////////////////////////////////////////////////////
 import { useState } from "react";
 import { ApiRequestError } from "../../../../lib/util/api.js";
-import { createContact, updateContact, } from "../../../../lib/contacts/contactsApi.js";
+import { contactPhotoUrl, createContact, deleteContactPhoto, updateContact, uploadContactPhoto, } from "../../../../lib/contacts/contactsApi.js";
 import Alert from "../../../../lib/components/feedback/Alert.js";
 import Button from "../../../../lib/components/buttons/Button.js";
 import FormField from "../../../../lib/components/forms/FormField.js";
+import ContactPhotoField from "./ContactPhotoField.js";
+import FavoriteStarButton from "./FavoriteStarButton.js";
 import { useApiClient } from "../../../../lib/util/apiClientContext.js";
 import { findWellKnownFolderUid } from "../../mail/findWellKnownFolderUid.js";
 import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
@@ -36,6 +38,9 @@ export default function ContactForm({ contact, mailboxUid, folderUid, mailboxes,
     // Every stored address is kept and editable - editing a contact must never silently drop addresses
     // beyond the first.
     const [addresses, setAddresses] = useState(contact?.addresses ?? []);
+    // A picture chosen (or the current one dropped) is applied once the contact itself is saved.
+    const [pickedPhoto, setPickedPhoto] = useState(null);
+    const [removePhoto, setRemovePhoto] = useState(false);
     const [error, setError] = useState(null);
     const [saving, setSaving] = useState(false);
     function updateEmail(index, patch) {
@@ -107,6 +112,12 @@ export default function ContactForm({ contact, mailboxUid, folderUid, mailboxes,
                     ...input,
                 }, client);
             }
+            if (pickedPhoto) {
+                saved = await uploadContactPhoto(saved.uid, saved.version, pickedPhoto);
+            }
+            else if (removePhoto && saved.photoBlobKey) {
+                saved = await deleteContactPhoto(saved.uid, saved.version, client);
+            }
             // A message opened later in this page load must see the changed contact's signing keys.
             clearPinnedSignerCache();
             onSaved(saved);
@@ -118,5 +129,12 @@ export default function ContactForm({ contact, mailboxUid, folderUid, mailboxes,
             setSaving(false);
         }
     }
-    return (_jsxs("form", { onSubmit: handleSubmit, className: "@container flex min-h-0 flex-1 flex-col", children: [_jsx("div", { className: "min-h-0 flex-1 overflow-y-auto p-6", children: _jsxs("div", { className: "flex max-w-xl flex-col gap-1", children: [_jsx("h1", { className: "text-xl font-bold uppercase tracking-wide mb-3", children: contact ? "Edit contact" : "New contact" }), error && _jsx(Alert, { children: error }), !contact && mailboxes && mailboxes.length > 1 && (_jsx(FormField, { label: "Mailbox", htmlFor: "contact-mailbox", children: _jsx("select", { id: "contact-mailbox", className: `${SELECT_CLASS} w-full`, value: targetMailboxUid, onChange: (e) => setTargetMailboxUid(e.target.value), children: mailboxes.map((mb) => (_jsxs("option", { value: mb.uid, children: [mb.displayName, mb.ownerUserUid ? "" : " (shared)"] }, mb.uid))) }) })), _jsx(FormField, { label: "Display name", htmlFor: "contact-displayName", children: _jsx("input", { id: "contact-displayName", type: "text", className: INPUT_CLASS, value: displayName, onChange: (e) => setDisplayName(e.target.value) }) }), _jsxs("div", { className: "grid grid-cols-1 @md:grid-cols-2 gap-3", children: [_jsx(FormField, { label: "First name", htmlFor: "contact-givenName", children: _jsx("input", { id: "contact-givenName", type: "text", className: INPUT_CLASS, value: givenName, onChange: (e) => setGivenName(e.target.value) }) }), _jsx(FormField, { label: "Last name", htmlFor: "contact-surname", children: _jsx("input", { id: "contact-surname", type: "text", className: INPUT_CLASS, value: surname, onChange: (e) => setSurname(e.target.value) }) })] }), _jsxs("div", { className: "grid grid-cols-1 @md:grid-cols-2 gap-3", children: [_jsx(FormField, { label: "Company", htmlFor: "contact-company", children: _jsx("input", { id: "contact-company", type: "text", className: INPUT_CLASS, value: company, onChange: (e) => setCompany(e.target.value) }) }), _jsx(FormField, { label: "Job title", htmlFor: "contact-jobTitle", children: _jsx("input", { id: "contact-jobTitle", type: "text", className: INPUT_CLASS, value: jobTitle, onChange: (e) => setJobTitle(e.target.value) }) })] }), _jsxs("label", { className: "flex items-center gap-2 text-sm mb-4", children: [_jsx("input", { type: "checkbox", checked: favorite, onChange: (e) => setFavorite(e.target.checked) }), "Favorite"] }), _jsx(FormField, { label: "Categories (comma-separated)", htmlFor: "contact-categories", children: _jsx("input", { id: "contact-categories", type: "text", className: INPUT_CLASS, value: categoriesText, onChange: (e) => setCategoriesText(e.target.value), placeholder: "VIP, Work" }) }), _jsx(FormField, { label: "Email", htmlFor: "contact-emails", children: _jsxs("div", { id: "contact-emails", className: "flex flex-col gap-2", children: [emails.map((email, i) => (_jsxs("div", { className: "flex gap-2", children: [_jsx("input", { type: "email", className: `${INPUT_CLASS} flex-1`, value: email.address, onChange: (e) => updateEmail(i, { address: e.target.value }), "aria-label": `Email address ${i + 1}` }), _jsx("select", { className: SELECT_CLASS, value: email.type, onChange: (e) => updateEmail(i, { type: e.target.value }), "aria-label": `Email type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) }), _jsx("button", { type: "button", onClick: () => removeEmail(i), className: "text-sm text-danger px-2", "aria-label": `Remove email ${i + 1}`, children: "\u00D7" })] }, i))), _jsx("button", { type: "button", onClick: () => setEmails((prev) => [...prev, { address: "", type: "work" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add email" })] }) }), _jsx(FormField, { label: "Phone", htmlFor: "contact-phones", children: _jsxs("div", { id: "contact-phones", className: "flex flex-col gap-2", children: [phones.map((phone, i) => (_jsxs("div", { className: "flex gap-2", children: [_jsx("input", { type: "tel", className: `${INPUT_CLASS} flex-1`, value: phone.phoneNumber, onChange: (e) => updatePhone(i, { phoneNumber: e.target.value }), "aria-label": `Phone number ${i + 1}` }), _jsx("select", { className: SELECT_CLASS, value: phone.type, onChange: (e) => updatePhone(i, { type: e.target.value }), "aria-label": `Phone type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) }), _jsx("button", { type: "button", onClick: () => removePhone(i), className: "text-sm text-danger px-2", "aria-label": `Remove phone ${i + 1}`, children: "\u00D7" })] }, i))), _jsx("button", { type: "button", onClick: () => setPhones((prev) => [...prev, { phoneNumber: "", type: "work" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add phone" })] }) }), _jsx(FormField, { label: "Address", htmlFor: "contact-address", children: _jsxs("div", { className: "flex flex-col gap-3", children: [addresses.map((address, i) => (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsxs("div", { className: "grid grid-cols-1 @md:grid-cols-2 gap-2", children: [_jsx("input", { type: "text", placeholder: "Street", className: INPUT_CLASS, value: address.street ?? "", onChange: (e) => updateAddress(i, { street: e.target.value }) }), _jsx("input", { type: "text", placeholder: "City", className: INPUT_CLASS, value: address.city ?? "", onChange: (e) => updateAddress(i, { city: e.target.value }) }), _jsx("input", { type: "text", placeholder: "State/Province", className: INPUT_CLASS, value: address.state ?? "", onChange: (e) => updateAddress(i, { state: e.target.value }) }), _jsx("input", { type: "text", placeholder: "Postal code", className: INPUT_CLASS, value: address.postalCode ?? "", onChange: (e) => updateAddress(i, { postalCode: e.target.value }) }), _jsx("input", { type: "text", placeholder: "Country", className: INPUT_CLASS, value: address.country ?? "", onChange: (e) => updateAddress(i, { country: e.target.value }) }), _jsx("select", { className: SELECT_CLASS, value: address.type, onChange: (e) => updateAddress(i, { type: e.target.value }), "aria-label": i === 0 ? "Address type" : `Address type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) })] }), _jsx("button", { type: "button", onClick: () => removeAddress(i), className: "self-start text-xs font-medium text-danger hover:underline", "aria-label": i === 0 ? "Remove address" : `Remove address ${i + 1}`, children: "Remove address" })] }, i))), _jsx("button", { type: "button", onClick: () => setAddresses((prev) => [...prev, { type: "home" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add address" })] }) }), _jsx(FormField, { label: "Notes", htmlFor: "contact-notes", children: _jsx("textarea", { id: "contact-notes", rows: 3, className: INPUT_CLASS, value: notes, onChange: (e) => setNotes(e.target.value) }) })] }) }), _jsxs("div", { className: "rr-solid sticky bottom-14 z-10 flex shrink-0 gap-3 border-t border-border bg-surface px-6 py-3 md:bottom-0", children: [_jsx(Button, { type: "submit", loading: saving, disabled: saving, className: "!w-auto", children: "Save" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onCancel, children: "Cancel" })] })] }));
+    return (_jsxs("form", { onSubmit: handleSubmit, className: "@container flex min-h-0 flex-1 flex-col", children: [_jsx("div", { className: "min-h-0 flex-1 overflow-y-auto p-6", children: _jsxs("div", { className: "flex max-w-xl flex-col gap-1", children: [_jsx("h1", { className: "text-xl font-bold uppercase tracking-wide mb-3", children: contact ? "Edit contact" : "New contact" }), error && _jsx(Alert, { children: error }), !contact && mailboxes && mailboxes.length > 1 && (_jsx(FormField, { label: "Mailbox", htmlFor: "contact-mailbox", children: _jsx("select", { id: "contact-mailbox", className: `${SELECT_CLASS} w-full`, value: targetMailboxUid, onChange: (e) => setTargetMailboxUid(e.target.value), children: mailboxes.map((mb) => (_jsxs("option", { value: mb.uid, children: [mb.displayName, mb.ownerUserUid ? "" : " (shared)"] }, mb.uid))) }) })), _jsx(FormField, { label: "Display name", htmlFor: "contact-displayName", children: _jsx("input", { id: "contact-displayName", type: "text", className: INPUT_CLASS, value: displayName, onChange: (e) => setDisplayName(e.target.value) }) }), _jsxs("div", { className: "flex items-start gap-2", children: [_jsx("div", { className: "min-w-0 flex-1", children: _jsx(ContactPhotoField, { displayName: displayName, email: emails[0]?.address, currentUrl: contact && contactPhotoUrl(contact), picked: pickedPhoto, removed: removePhoto, onPick: (file) => {
+                                            setPickedPhoto(file);
+                                            setRemovePhoto(false);
+                                            setError(null);
+                                        }, onRemove: () => {
+                                            setPickedPhoto(null);
+                                            setRemovePhoto(true);
+                                        }, onReject: setError }) }), _jsx(FavoriteStarButton, { favorite: favorite, onToggle: () => setFavorite((value) => !value) })] }), _jsxs("div", { className: "grid grid-cols-1 @md:grid-cols-2 gap-3", children: [_jsx(FormField, { label: "First name", htmlFor: "contact-givenName", children: _jsx("input", { id: "contact-givenName", type: "text", className: INPUT_CLASS, value: givenName, onChange: (e) => setGivenName(e.target.value) }) }), _jsx(FormField, { label: "Last name", htmlFor: "contact-surname", children: _jsx("input", { id: "contact-surname", type: "text", className: INPUT_CLASS, value: surname, onChange: (e) => setSurname(e.target.value) }) })] }), _jsxs("div", { className: "grid grid-cols-1 @md:grid-cols-2 gap-3", children: [_jsx(FormField, { label: "Company", htmlFor: "contact-company", children: _jsx("input", { id: "contact-company", type: "text", className: INPUT_CLASS, value: company, onChange: (e) => setCompany(e.target.value) }) }), _jsx(FormField, { label: "Job title", htmlFor: "contact-jobTitle", children: _jsx("input", { id: "contact-jobTitle", type: "text", className: INPUT_CLASS, value: jobTitle, onChange: (e) => setJobTitle(e.target.value) }) })] }), _jsx(FormField, { label: "Categories (comma-separated)", htmlFor: "contact-categories", children: _jsx("input", { id: "contact-categories", type: "text", className: INPUT_CLASS, value: categoriesText, onChange: (e) => setCategoriesText(e.target.value), placeholder: "VIP, Work" }) }), _jsx(FormField, { label: "Email", htmlFor: "contact-emails", children: _jsxs("div", { id: "contact-emails", className: "flex flex-col gap-2", children: [emails.map((email, i) => (_jsxs("div", { className: "flex gap-2", children: [_jsx("input", { type: "email", className: `${INPUT_CLASS} flex-1`, value: email.address, onChange: (e) => updateEmail(i, { address: e.target.value }), "aria-label": `Email address ${i + 1}` }), _jsx("select", { className: SELECT_CLASS, value: email.type, onChange: (e) => updateEmail(i, { type: e.target.value }), "aria-label": `Email type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) }), _jsx("button", { type: "button", onClick: () => removeEmail(i), className: "text-sm text-danger px-2", "aria-label": `Remove email ${i + 1}`, children: "\u00D7" })] }, i))), _jsx("button", { type: "button", onClick: () => setEmails((prev) => [...prev, { address: "", type: "work" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add email" })] }) }), _jsx(FormField, { label: "Phone", htmlFor: "contact-phones", children: _jsxs("div", { id: "contact-phones", className: "flex flex-col gap-2", children: [phones.map((phone, i) => (_jsxs("div", { className: "flex gap-2", children: [_jsx("input", { type: "tel", className: `${INPUT_CLASS} flex-1`, value: phone.phoneNumber, onChange: (e) => updatePhone(i, { phoneNumber: e.target.value }), "aria-label": `Phone number ${i + 1}` }), _jsx("select", { className: SELECT_CLASS, value: phone.type, onChange: (e) => updatePhone(i, { type: e.target.value }), "aria-label": `Phone type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) }), _jsx("button", { type: "button", onClick: () => removePhone(i), className: "text-sm text-danger px-2", "aria-label": `Remove phone ${i + 1}`, children: "\u00D7" })] }, i))), _jsx("button", { type: "button", onClick: () => setPhones((prev) => [...prev, { phoneNumber: "", type: "work" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add phone" })] }) }), _jsx(FormField, { label: "Address", htmlFor: "contact-address", children: _jsxs("div", { className: "flex flex-col gap-3", children: [addresses.map((address, i) => (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsxs("div", { className: "grid grid-cols-1 @md:grid-cols-2 gap-2", children: [_jsx("input", { type: "text", placeholder: "Street", className: INPUT_CLASS, value: address.street ?? "", onChange: (e) => updateAddress(i, { street: e.target.value }) }), _jsx("input", { type: "text", placeholder: "City", className: INPUT_CLASS, value: address.city ?? "", onChange: (e) => updateAddress(i, { city: e.target.value }) }), _jsx("input", { type: "text", placeholder: "State/Province", className: INPUT_CLASS, value: address.state ?? "", onChange: (e) => updateAddress(i, { state: e.target.value }) }), _jsx("input", { type: "text", placeholder: "Postal code", className: INPUT_CLASS, value: address.postalCode ?? "", onChange: (e) => updateAddress(i, { postalCode: e.target.value }) }), _jsx("input", { type: "text", placeholder: "Country", className: INPUT_CLASS, value: address.country ?? "", onChange: (e) => updateAddress(i, { country: e.target.value }) }), _jsx("select", { className: SELECT_CLASS, value: address.type, onChange: (e) => updateAddress(i, { type: e.target.value }), "aria-label": i === 0 ? "Address type" : `Address type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) })] }), _jsx("button", { type: "button", onClick: () => removeAddress(i), className: "self-start text-xs font-medium text-danger hover:underline", "aria-label": i === 0 ? "Remove address" : `Remove address ${i + 1}`, children: "Remove address" })] }, i))), _jsx("button", { type: "button", onClick: () => setAddresses((prev) => [...prev, { type: "home" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add address" })] }) }), _jsx(FormField, { label: "Notes", htmlFor: "contact-notes", children: _jsx("textarea", { id: "contact-notes", rows: 3, className: INPUT_CLASS, value: notes, onChange: (e) => setNotes(e.target.value) }) })] }) }), _jsxs("div", { className: "rr-solid sticky bottom-14 z-10 flex shrink-0 gap-3 border-t border-border bg-surface px-6 py-3 md:bottom-0", children: [_jsx(Button, { type: "submit", loading: saving, disabled: saving, className: "!w-auto", children: "Save" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onCancel, children: "Cancel" })] })] }));
 }

package/dist/apps/shared/components/contacts/ContactPhotoField.d.ts

@@ -0,0 +1,21 @@
+import React from "react";
+export interface ContactPhotoFieldProps {
+    displayName: string;
+    /** The contact's first address, for the Gravatar shown while they have no picture of their own. */
+    email?: string;
+    /** The picture the contact has now (`contactPhotoUrl()`), if any. */
+    currentUrl?: string;
+    /** The picture chosen to replace it, not uploaded until the contact is saved; `null` for none. */
+    picked: File | null;
+    /** Whether the current picture is to be removed when the contact is saved. */
+    removed: boolean;
+    onPick: (file: File) => void;
+    onRemove: () => void;
+    /** Called with the reason a chosen file was turned down. */
+    onReject: (message: string) => void;
+}
+/**
+ * The picture of a contact in the edit form: the avatar as it is (their picture, else Gravatar, else initials) with "Change photo" and, when
+ * there is a picture of their own, "Remove photo". A file is checked here (type and size) and only uploaded when the form is saved.
+ */
+export default function ContactPhotoField({ displayName, email, currentUrl, picked, removed, onPick, onRemove, onReject }: ContactPhotoFieldProps): React.JSX.Element;

package/dist/apps/shared/components/contacts/ContactPhotoField.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, useState } from "react";
+import ContactAvatar from "../../../../lib/components/avatar/ContactAvatar.js";
+import Button from "../../../../lib/components/buttons/Button.js";
+import { CONTACT_PHOTO_MAX_BYTES, CONTACT_PHOTO_TYPES } from "../../../../lib/contacts/contactsApi.js";
+/**
+ * The picture of a contact in the edit form: the avatar as it is (their picture, else Gravatar, else initials) with "Change photo" and, when
+ * there is a picture of their own, "Remove photo". A file is checked here (type and size) and only uploaded when the form is saved.
+ */
+export default function ContactPhotoField({ displayName, email, currentUrl, picked, removed, onPick, onRemove, onReject }) {
+    const input = useRef(null);
+    const [preview, setPreview] = useState();
+    useEffect(() => {
+        if (!picked) {
+            setPreview(undefined);
+            return;
+        }
+        const url = URL.createObjectURL(picked);
+        setPreview(url);
+        return () => URL.revokeObjectURL(url);
+    }, [picked]);
+    function handleChange(file) {
+        if (!file) {
+            return;
+        }
+        if (!CONTACT_PHOTO_TYPES.includes(file.type)) {
+            onReject("Choose a JPEG, PNG, GIF or WebP image.");
+        }
+        else if (file.size > CONTACT_PHOTO_MAX_BYTES) {
+            onReject("Choose an image no larger than 1 MB.");
+        }
+        else {
+            onPick(file);
+        }
+    }
+    const shown = picked ? preview : removed ? undefined : currentUrl;
+    const hasOwn = !!picked || (!!currentUrl && !removed);
+    return (_jsxs("div", { className: "flex items-center gap-4 mb-3", children: [_jsx(ContactAvatar, { displayName: displayName || "?", size: 72, photoUrl: shown, email: picked || (currentUrl && !removed) ? undefined : email }), _jsxs("div", { className: "flex flex-wrap gap-2", children: [_jsx("input", { ref: input, type: "file", accept: CONTACT_PHOTO_TYPES.join(","), "aria-label": "Contact photo file", className: "sr-only", tabIndex: -1, onChange: (e) => {
+                            handleChange(e.target.files?.[0]);
+                            e.target.value = "";
+                        } }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto !py-1 !px-3 text-xs", onClick: () => input.current?.click(), children: hasOwn ? "Change photo" : "Add photo" }), hasOwn && (_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto !py-1 !px-3 text-xs", onClick: onRemove, children: "Remove photo" }))] })] }));
+}

package/dist/apps/shared/components/contacts/FavoriteStarButton.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+export interface FavoriteStarButtonProps {
+    favorite: boolean;
+    onToggle: () => void;
+    disabled?: boolean;
+    className?: string;
+}
+/** The star that marks a contact as a favorite: filled when it is one. A toggle button (`aria-pressed`) named "Favorite". */
+export default function FavoriteStarButton({ favorite, onToggle, disabled, className }: FavoriteStarButtonProps): React.JSX.Element;

package/dist/apps/shared/components/contacts/FavoriteStarButton.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { HiOutlineStar, HiStar } from "react-icons/hi2";
+/** The star that marks a contact as a favorite: filled when it is one. A toggle button (`aria-pressed`) named "Favorite". */
+export default function FavoriteStarButton({ favorite, onToggle, disabled, className }) {
+    return (_jsx("button", { type: "button", "aria-label": "Favorite", title: favorite ? "Remove from favorites" : "Add to favorites", "aria-pressed": favorite, disabled: disabled, onClick: onToggle, className: [
+            "inline-flex items-center justify-center rounded-sm p-1 hover:bg-surface-alt disabled:opacity-50 focus-visible:outline-2 focus-visible:outline-primary",
+            favorite ? "text-warning" : "text-text-muted hover:text-text",
+            className,
+        ]
+            .filter(Boolean)
+            .join(" "), children: favorite ? _jsx(HiStar, { "aria-hidden": "true", className: "size-6" }) : _jsx(HiOutlineStar, { "aria-hidden": "true", className: "size-6" }) }));
+}

package/dist/apps/shared/components/contacts/ParticipantLink.d.ts

@@ -0,0 +1,18 @@
+import React, { ReactNode } from "react";
+import type { ContactCardContext } from "./contactCardData.js";
+import type { Participant } from "./participantDetails.js";
+export interface ParticipantLinkProps {
+    participant: Participant;
+    /** The message the participant was met in - see `ContactCardValue.show`. */
+    context?: ContactCardContext;
+    /** The button's accessible name, when what it shows has none of its own (an avatar). */
+    label?: string;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * A participant of a message or an event (a sender, a recipient, an organizer, a guest) that opens their contact card when clicked: a real
+ * button, underlined on hover and with a visible focus ring, named by what it shows. Outside a `ContactCardProvider` it is plain text. Never
+ * put one inside another button or link.
+ */
+export default function ParticipantLink({ participant, context, label, className, children }: ParticipantLinkProps): React.JSX.Element;

package/dist/apps/shared/components/contacts/ParticipantLink.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContactCard } from "./ContactCardProvider.js";
+/**
+ * A participant of a message or an event (a sender, a recipient, an organizer, a guest) that opens their contact card when clicked: a real
+ * button, underlined on hover and with a visible focus ring, named by what it shows. Outside a `ContactCardProvider` it is plain text. Never
+ * put one inside another button or link.
+ */
+export default function ParticipantLink({ participant, context, label, className, children }) {
+    const { show, available } = useContactCard();
+    if (!available) {
+        return _jsx("span", { className: className, children: children });
+    }
+    return (_jsx("button", { type: "button", "aria-label": label, onClick: () => show(participant, context), className: ["text-left rounded-sm hover:underline focus-visible:underline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary", className]
+            .filter(Boolean)
+            .join(" "), children: children }));
+}

package/dist/apps/shared/components/contacts/contactCardData.d.ts

@@ -0,0 +1,69 @@
+import { type CalendarOccurrence } from "../../../../lib/calendar/recurrence.js";
+import { type Contact } from "../../../../lib/contacts/contactsApi.js";
+import { type ParsedVCardContact } from "../../../../lib/contacts/vcard.js";
+import { type Attachment, type Folder, type Mailbox, type Message } from "../../../../lib/mail/mailApi.js";
+import { type ApiClient } from "../../../../lib/util/api.js";
+import { type Participant } from "./participantDetails.js";
+/** What the card is opened for besides who: the message the participant was met in, and that message's attachments when the caller already has them. */
+export interface ContactCardContext {
+    message?: Message;
+    attachments?: Attachment[];
+}
+/** How many recent messages and upcoming events the card lists. */
+export declare const CARD_LIST_SIZE = 5;
+/** How far ahead "upcoming" looks, in days. */
+export declare const UPCOMING_DAYS = 60;
+/** The most vCard attachments and the most bytes of one that are read to fill a contact in. */
+export declare const MAX_VCARD_FILES = 3;
+export declare const MAX_VCARD_BYTES: number;
+/** The mailboxes whose data the card reads: the user's own, else the primary/first one, plus the message's mailbox when it is one they can reach. */
+export declare function scopeMailboxes(mailboxes: readonly Mailbox[], userUid: string | undefined, message?: Message): Mailbox[];
+/** Every folder of `mailboxes`. A mailbox whose folders cannot be listed is left out rather than failing the rest. */
+export declare function loadFolders(mailboxes: readonly Mailbox[], client?: ApiClient): Promise<Folder[]>;
+/** The contact the address belongs to in `folders`' contacts folders, if any. */
+export declare function findContact(folders: readonly Folder[], address: string, client?: ApiClient): Promise<Contact | undefined>;
+/** The last `CARD_LIST_SIZE` messages to or from `address` in `mailboxes`, newest first. */
+export declare function loadRecentMessages(mailboxes: readonly Mailbox[], address: string, client?: ApiClient): Promise<Message[]>;
+/** The next `CARD_LIST_SIZE` events within `UPCOMING_DAYS` from `now` that `address` organizes or is invited to, soonest first. */
+export declare function loadUpcomingEvents(folders: readonly Folder[], address: string, now: Date, client?: ApiClient): Promise<CalendarOccurrence[]>;
+/** A vCard attachment's text. */
+export declare function fetchVCardText(attachmentUid: string): Promise<string>;
+/**
+ * The vCard of the context message that describes `participant`: the first attachment holding a card with their address, else - only for the
+ * message's sender, whose own vCard it presumably is - the first card there is. `undefined` when there is none, and for any failure to read one:
+ * a vCard only adds detail, it is never needed.
+ */
+export declare function loadParticipantCard(participant: Participant, context: ContactCardContext, client?: ApiClient): Promise<ParsedVCardContact | undefined>;
+/** Where a new contact goes: the message's mailbox when it is one of the user's own, else their primary mailbox - in that mailbox's contacts folder. */
+export declare function contactScope(mailboxes: readonly Mailbox[], folders: readonly Folder[], userUid: string | undefined, message?: Message): {
+    mailboxUid: string;
+    folderUid: string;
+};
+/** Stores a contact for `participant` with everything known - the name, the address and whatever `card` says. */
+export declare function createContactFor(participant: Participant, card: ParsedVCardContact | undefined, scope: {
+    mailboxUid: string;
+    folderUid: string;
+}, client?: ApiClient): Promise<Contact>;
+/**
+ * The sender's own contact card as a file to attach, `<display name>.vcf`: the mailbox being sent from (its name and primary address) with the phones, company and
+ * title of the user's own contact entry for that address, when they have one in their own mailboxes' address books. A lookup that fails just leaves those out.
+ */
+export declare function buildOwnCardFile(mailbox: Mailbox, mailboxes: readonly Mailbox[], userUid: string | undefined, client?: ApiClient): Promise<File>;
+/** The outcome of adding a vCard file's cards to the address book. */
+export interface AddCardsResult {
+    added: number;
+    skipped: number;
+}
+/**
+ * Adds every card of a vCard file to the contacts folder `scope` names, skipping the ones whose email is already a stored contact's (or an earlier
+ * card's in the same file). A card that cannot be stored fails the whole call after the earlier ones were added - `AddCardsError` says how many.
+ */
+export declare function addCardsToAddressBook(cards: readonly ParsedVCardContact[], scope: {
+    mailboxUid: string;
+    folderUid: string;
+}, client?: ApiClient): Promise<AddCardsResult>;
+/** A card failed to store: the message is the failure's and `added` how many cards were stored before it. */
+export declare class AddCardsError extends Error {
+    readonly added: number;
+    constructor(failure: unknown, added: number);
+}

package/dist/apps/shared/components/contacts/contactCardData.js

@@ -0,0 +1,158 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * What the contact card (`ContactCard`) and the vCard attachment actions read and write: the user's contact and calendar folders, the contact
+ * behind an address, the last messages to or from it, its upcoming events, and the calls that make a contact from a participant or a vCard.
+ * Every function takes the `ApiClient` to use (`useApiClient()`), like the API modules under `lib/`.
+ */
+import { addDays } from "date-fns";
+import { listCalendarEvents } from "../../../../lib/calendar/calendarApi.js";
+import { expandAllOccurrences } from "../../../../lib/calendar/recurrence.js";
+import { createContact, listContactsInFolders } from "../../../../lib/contacts/contactsApi.js";
+import { parseVCards } from "../../../../lib/contacts/vcard.js";
+import { attachmentContentUrl, getMessage, listAttachments, listFolders, } from "../../../../lib/mail/mailApi.js";
+import { search } from "../../../../lib/search/searchApi.js";
+import { ApiRequestError } from "../../../../lib/util/api.js";
+import { ownMailboxes, primaryMailbox } from "../../mail/primaryMailbox.js";
+import { cardForAddress, contactInputFor, contactInputFromCard, findContactByAddress, isVCardAttachment, normalizeAddress, ownContactCard, withoutDuplicates, } from "./participantDetails.js";
+/** How many recent messages and upcoming events the card lists. */
+export const CARD_LIST_SIZE = 5;
+/** How far ahead "upcoming" looks, in days. */
+export const UPCOMING_DAYS = 60;
+/** The most vCard attachments and the most bytes of one that are read to fill a contact in. */
+export const MAX_VCARD_FILES = 3;
+export const MAX_VCARD_BYTES = 256 * 1024;
+/** The mailboxes whose data the card reads: the user's own, else the primary/first one, plus the message's mailbox when it is one they can reach. */
+export function scopeMailboxes(mailboxes, userUid, message) {
+    const own = ownMailboxes(mailboxes, userUid);
+    const scope = own.length > 0 ? own : [primaryMailbox(mailboxes, userUid)].filter((mailbox) => !!mailbox);
+    const messageMailbox = mailboxes.find((mailbox) => mailbox.uid === message?.mailboxUid);
+    return messageMailbox && !scope.includes(messageMailbox) ? [...scope, messageMailbox] : scope;
+}
+/** Every folder of `mailboxes`. A mailbox whose folders cannot be listed is left out rather than failing the rest. */
+export async function loadFolders(mailboxes, client) {
+    const lists = await Promise.all(mailboxes.map((mailbox) => listFolders(mailbox.uid, client).catch(() => [])));
+    return lists.flat();
+}
+/** The contact the address belongs to in `folders`' contacts folders, if any. */
+export async function findContact(folders, address, client) {
+    const uids = folders.filter((folder) => folder.type === "contacts").map((folder) => folder.uid);
+    return findContactByAddress(await listContactsInFolders(uids, client), address);
+}
+/** The last `CARD_LIST_SIZE` messages to or from `address` in `mailboxes`, newest first. */
+export async function loadRecentMessages(mailboxes, address, client) {
+    const pages = await Promise.all(mailboxes.flatMap((mailbox) => ["from", "to"].map((role) => search("", { types: ["message"], [role]: address, limit: CARD_LIST_SIZE, mailboxUid: mailbox.uid }, client))));
+    const uids = [...new Set(pages.flatMap((page) => page.results.map((result) => result.entityUid)))];
+    // A hit can briefly outlive its message: one that no longer resolves is dropped.
+    const messages = (await Promise.all(uids.map((uid) => getMessage(uid, client).catch(() => null)))).filter((message) => !!message);
+    return messages.sort((a, b) => Date.parse(b.receivedDate) - Date.parse(a.receivedDate)).slice(0, CARD_LIST_SIZE);
+}
+/** The next `CARD_LIST_SIZE` events within `UPCOMING_DAYS` from `now` that `address` organizes or is invited to, soonest first. */
+export async function loadUpcomingEvents(folders, address, now, client) {
+    const wanted = normalizeAddress(address);
+    const calendars = folders.filter((folder) => folder.type === "calendar");
+    const lists = await Promise.all(calendars.map((folder) => listCalendarEvents(folder.uid, client)));
+    const involved = lists
+        .flat()
+        .filter((event) => event.status !== "cancelled" &&
+        (normalizeAddress(event.organizer.address) === wanted ||
+            (event.attendees ?? []).some((attendee) => normalizeAddress(attendee.address) === wanted)));
+    return expandAllOccurrences(involved, now, addDays(now, UPCOMING_DAYS))
+        .sort((a, b) => Date.parse(a.startDate) - Date.parse(b.startDate))
+        .slice(0, CARD_LIST_SIZE);
+}
+/** A vCard attachment's text. */
+export async function fetchVCardText(attachmentUid) {
+    const res = await fetch(attachmentContentUrl(attachmentUid), { credentials: "include" });
+    if (!res.ok) {
+        throw new ApiRequestError(res.statusText || "Could not load this contact card.", res.status);
+    }
+    return res.text();
+}
+/** The message's vCard attachments: `context.attachments` when given, else the message's own list. */
+async function vCardAttachments(context, client) {
+    const { message } = context;
+    const attachments = context.attachments ?? (message?.hasAttachments ? await listAttachments(message.folderUid, message.uid, client) : []);
+    return attachments.filter((attachment) => isVCardAttachment(attachment) && attachment.sizeBytes <= MAX_VCARD_BYTES).slice(0, MAX_VCARD_FILES);
+}
+/**
+ * The vCard of the context message that describes `participant`: the first attachment holding a card with their address, else - only for the
+ * message's sender, whose own vCard it presumably is - the first card there is. `undefined` when there is none, and for any failure to read one:
+ * a vCard only adds detail, it is never needed.
+ */
+export async function loadParticipantCard(participant, context, client) {
+    try {
+        const isSender = !!context.message && normalizeAddress(context.message.from.address) === normalizeAddress(participant.address);
+        let fallback;
+        for (const attachment of await vCardAttachments(context, client)) {
+            const cards = parseVCards(await fetchVCardText(attachment.uid));
+            const match = cardForAddress(cards, participant.address, false);
+            if (match) {
+                return match;
+            }
+            fallback ?? (fallback = cards[0]);
+        }
+        return isSender ? fallback : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Where a new contact goes: the message's mailbox when it is one of the user's own, else their primary mailbox - in that mailbox's contacts folder. */
+export function contactScope(mailboxes, folders, userUid, message) {
+    const own = ownMailboxes(mailboxes, userUid);
+    const mailbox = own.find((candidate) => candidate.uid === message?.mailboxUid) ?? primaryMailbox(mailboxes, userUid);
+    const folder = folders.find((candidate) => candidate.mailboxUid === mailbox?.uid && candidate.type === "contacts");
+    if (!mailbox || !folder) {
+        throw new Error("There is no contacts folder to add this contact to.");
+    }
+    return { mailboxUid: mailbox.uid, folderUid: folder.uid };
+}
+/** Stores a contact for `participant` with everything known - the name, the address and whatever `card` says. */
+export function createContactFor(participant, card, scope, client) {
+    return createContact(contactInputFor(participant, card, scope), client);
+}
+/**
+ * The sender's own contact card as a file to attach, `<display name>.vcf`: the mailbox being sent from (its name and primary address) with the phones, company and
+ * title of the user's own contact entry for that address, when they have one in their own mailboxes' address books. A lookup that fails just leaves those out.
+ */
+export async function buildOwnCardFile(mailbox, mailboxes, userUid, client) {
+    let own;
+    try {
+        const mine = ownMailboxes(mailboxes, userUid);
+        own = await findContact(await loadFolders(mine.length > 0 ? mine : [mailbox], client), mailbox.primarySmtpAddress, client);
+    }
+    catch {
+        // The card is still worth sending without them.
+    }
+    const { displayName, vcard } = ownContactCard(mailbox, own);
+    return new File([vcard], `${displayName.replace(/[\\/:*?"<>|]/g, "").trim() || "Contact"}.vcf`, { type: "text/vcard" });
+}
+/**
+ * Adds every card of a vCard file to the contacts folder `scope` names, skipping the ones whose email is already a stored contact's (or an earlier
+ * card's in the same file). A card that cannot be stored fails the whole call after the earlier ones were added - `AddCardsError` says how many.
+ */
+export async function addCardsToAddressBook(cards, scope, client) {
+    const { fresh, skipped } = withoutDuplicates(cards, await listContactsInFolders([scope.folderUid], client));
+    let added = 0;
+    for (const card of fresh) {
+        try {
+            await createContact(contactInputFromCard(card, scope), client);
+            added += 1;
+        }
+        catch (err) {
+            throw new AddCardsError(err, added);
+        }
+    }
+    return { added, skipped };
+}
+/** A card failed to store: the message is the failure's and `added` how many cards were stored before it. */
+export class AddCardsError extends Error {
+    constructor(failure, added) {
+        super(failure instanceof Error ? failure.message : "Could not add the contact.");
+        this.name = "AddCardsError";
+        this.added = added;
+    }
+}