@rapidmx/web-client 0.25.1 → 0.27.0

package/apps/shared/components/contacts/ContactForm.tsx

@@ -11,13 +11,18 @@ import {
     ContactPatch,
     ContactPhone,
     ContactPostalAddress,
+    contactPhotoUrl,
     createContact,
+    deleteContactPhoto,
     updateContact,
+    uploadContactPhoto,
 } from "../../../../lib/contacts/contactsApi.js";
 import { Mailbox } from "../../../../lib/mail/mailApi.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";
@@ -62,6 +67,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<ContactPostalAddress[]>(contact?.addresses ?? []);
+    // A picture chosen (or the current one dropped) is applied once the contact itself is saved.
+    const [pickedPhoto, setPickedPhoto] = useState<File | null>(null);
+    const [removePhoto, setRemovePhoto] = useState(false);
     const [error, setError] = useState<string | null>(null);
     const [saving, setSaving] = useState(false);
 
@@ -143,6 +151,11 @@ export default function ContactForm({ contact, mailboxUid, folderUid, mailboxes,
                     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);
@@ -191,6 +204,29 @@ export default function ContactForm({ contact, mailboxUid, folderUid, mailboxes,
                 />
             </FormField>
 
+            <div className="flex items-start gap-2">
+                <div className="min-w-0 flex-1">
+                    <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}
+                    />
+                </div>
+                <FavoriteStarButton favorite={favorite} onToggle={() => setFavorite((value) => !value)} />
+            </div>
+
             <div className="grid grid-cols-1 @md:grid-cols-2 gap-3">
                 <FormField label="First name" htmlFor="contact-givenName">
                     <input id="contact-givenName" type="text" className={INPUT_CLASS} value={givenName} onChange={(e) => setGivenName(e.target.value)} />
@@ -209,11 +245,6 @@ export default function ContactForm({ contact, mailboxUid, folderUid, mailboxes,
                 </FormField>
             </div>
 
-            <label className="flex items-center gap-2 text-sm mb-4">
-                <input type="checkbox" checked={favorite} onChange={(e) => setFavorite(e.target.checked)} />
-                Favorite
-            </label>
-
             <FormField label="Categories (comma-separated)" htmlFor="contact-categories">
                 <input
                     id="contact-categories"

package/apps/shared/components/contacts/ContactPhotoField.tsx

@@ -0,0 +1,86 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { 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";
+
+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) {
+    const input = useRef<HTMLInputElement>(null);
+    const [preview, setPreview] = useState<string | undefined>();
+
+    useEffect(() => {
+        if (!picked) {
+            setPreview(undefined);
+            return;
+        }
+        const url = URL.createObjectURL(picked);
+        setPreview(url);
+        return () => URL.revokeObjectURL(url);
+    }, [picked]);
+
+    function handleChange(file: File | undefined) {
+        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 (
+        <div className="flex items-center gap-4 mb-3">
+            <ContactAvatar displayName={displayName || "?"} size={72} photoUrl={shown} email={picked || (currentUrl && !removed) ? undefined : email} />
+            <div className="flex flex-wrap gap-2">
+                <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 = "";
+                    }}
+                />
+                <Button type="button" variant="secondary" className="!w-auto !py-1 !px-3 text-xs" onClick={() => input.current?.click()}>
+                    {hasOwn ? "Change photo" : "Add photo"}
+                </Button>
+                {hasOwn && (
+                    <Button type="button" variant="secondary" className="!w-auto !py-1 !px-3 text-xs" onClick={onRemove}>
+                        Remove photo
+                    </Button>
+                )}
+            </div>
+        </div>
+    );
+}

package/apps/shared/components/contacts/FavoriteStarButton.tsx

@@ -0,0 +1,36 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import { HiOutlineStar, HiStar } from "react-icons/hi2";
+
+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) {
+    return (
+        <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(" ")}
+        >
+            {favorite ? <HiStar aria-hidden="true" className="size-6" /> : <HiOutlineStar aria-hidden="true" className="size-6" />}
+        </button>
+    );
+}

package/apps/shared/components/contacts/ParticipantLink.tsx

@@ -0,0 +1,42 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode } from "react";
+import { useContactCard } from "./ContactCardProvider.js";
+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) {
+    const { show, available } = useContactCard();
+    if (!available) {
+        return <span className={className}>{children}</span>;
+    }
+    return (
+        <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}
+        </button>
+    );
+}

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

@@ -0,0 +1,220 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { CalendarEvent, listCalendarEvents } from "../../../../lib/calendar/calendarApi.js";
+import { type CalendarOccurrence, expandAllOccurrences } from "../../../../lib/calendar/recurrence.js";
+import { type Contact, createContact, listContactsInFolders } from "../../../../lib/contacts/contactsApi.js";
+import { type ParsedVCardContact, parseVCards } from "../../../../lib/contacts/vcard.js";
+import {
+    type Attachment,
+    type Folder,
+    type Mailbox,
+    type Message,
+    attachmentContentUrl,
+    getMessage,
+    listAttachments,
+    listFolders,
+} from "../../../../lib/mail/mailApi.js";
+import { search } from "../../../../lib/search/searchApi.js";
+import { ApiRequestError, type ApiClient } from "../../../../lib/util/api.js";
+import { ownMailboxes, primaryMailbox } from "../../mail/primaryMailbox.js";
+import {
+    type Participant,
+    cardForAddress,
+    contactInputFor,
+    contactInputFromCard,
+    findContactByAddress,
+    isVCardAttachment,
+    normalizeAddress,
+    ownContactCard,
+    withoutDuplicates,
+} 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 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: readonly Mailbox[], userUid: string | undefined, message?: Message): Mailbox[] {
+    const own = ownMailboxes(mailboxes, userUid);
+    const scope = own.length > 0 ? own : [primaryMailbox(mailboxes, userUid)].filter((mailbox): mailbox is 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: readonly Mailbox[], client?: ApiClient): Promise<Folder[]> {
+    const lists = await Promise.all(mailboxes.map((mailbox) => listFolders(mailbox.uid, client).catch(() => [] as Folder[])));
+    return lists.flat();
+}
+
+/** The contact the address belongs to in `folders`' contacts folders, if any. */
+export async function findContact(folders: readonly Folder[], address: string, client?: ApiClient): Promise<Contact | undefined> {
+    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: readonly Mailbox[], address: string, client?: ApiClient): Promise<Message[]> {
+    const pages = await Promise.all(
+        mailboxes.flatMap((mailbox) =>
+            (["from", "to"] as const).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 is 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: readonly Folder[], address: string, now: Date, client?: ApiClient): Promise<CalendarOccurrence[]> {
+    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: CalendarEvent) =>
+                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: string): Promise<string> {
+    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: ContactCardContext, client?: ApiClient): Promise<Attachment[]> {
+    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: Participant, context: ContactCardContext, client?: ApiClient): Promise<ParsedVCardContact | undefined> {
+    try {
+        const isSender = !!context.message && normalizeAddress(context.message.from.address) === normalizeAddress(participant.address);
+        let fallback: ParsedVCardContact | undefined;
+        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 ??= 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: readonly Mailbox[], folders: readonly Folder[], userUid: string | undefined, message?: Message): { mailboxUid: string; folderUid: string } {
+    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: Participant,
+    card: ParsedVCardContact | undefined,
+    scope: { mailboxUid: string; folderUid: string },
+    client?: ApiClient,
+): Promise<Contact> {
+    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: Mailbox, mailboxes: readonly Mailbox[], userUid: string | undefined, client?: ApiClient): Promise<File> {
+    let own: Contact | undefined;
+    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" });
+}
+
+/** 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 async function addCardsToAddressBook(
+    cards: readonly ParsedVCardContact[],
+    scope: { mailboxUid: string; folderUid: string },
+    client?: ApiClient,
+): Promise<AddCardsResult> {
+    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 {
+    readonly added: number;
+
+    constructor(failure: unknown, added: number) {
+        super(failure instanceof Error ? failure.message : "Could not add the contact.");
+        this.name = "AddCardsError";
+        this.added = added;
+    }
+}

package/apps/shared/components/contacts/participantDetails.ts

@@ -0,0 +1,169 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The pure rules behind the contact card (`ContactCard`), the "Add to address book" action of a vCard attachment and the compose window's
+ * "Attach my contact card": who a participant is, whether they are external, which contact (or vCard) describes them and what a new contact
+ * made from them holds. No network and no React - the calls that use these are in `contactCardData.ts`.
+ */
+import type { Contact, ContactEmail, ContactInput, ContactPhone, ContactPostalAddress } from "../../../../lib/contacts/contactsApi.js";
+import { contactToVCard, type ParsedVCardContact } from "../../../../lib/contacts/vcard.js";
+import { splitMailAddress } from "../../../../lib/mail/mailAddress.js";
+import type { Mailbox } from "../../../../lib/mail/mailApi.js";
+
+/** Someone who took part in a message or an event: a sender, a recipient, an organizer, a guest. */
+export interface Participant {
+    address: string;
+    displayName?: string;
+}
+
+/** The MIME types a vCard file travels as. */
+const VCARD_MIME_TYPES = new Set(["text/vcard", "text/x-vcard", "text/directory", "application/vcard"]);
+
+/** Whether an attachment is a vCard: by its MIME type (parameters such as `; charset=utf-8` ignored), else by a `.vcf`/`.vcard` name. */
+export function isVCardAttachment(attachment: { filename?: string; mimeType?: string }): boolean {
+    const mimeType = (attachment.mimeType ?? "").split(";")[0].trim().toLowerCase();
+    return VCARD_MIME_TYPES.has(mimeType) || /\.(vcf|vcard)$/i.test(attachment.filename ?? "");
+}
+
+/** An address in the form two of them are compared by. */
+export function normalizeAddress(address: string): string {
+    return address.trim().toLowerCase();
+}
+
+/** The name to show for a participant: their own when distinct from the address, else the address's local part. */
+export function participantName(participant: Participant): string {
+    const { name, address } = splitMailAddress(participant);
+    if (name) {
+        return name;
+    }
+    const at = address.lastIndexOf("@");
+    return at > 0 ? address.slice(0, at) : address;
+}
+
+/** A display name as given name + surname: `Doe, Jane` and `Jane Doe` are both Jane Doe; a single word is only a given name, and a middle name stays with the given. */
+export function splitPersonName(displayName: string): { givenName?: string; surname?: string } {
+    const name = displayName.trim();
+    const comma = name.indexOf(",");
+    if (comma > 0) {
+        return { givenName: name.slice(comma + 1).trim() || undefined, surname: name.slice(0, comma).trim() };
+    }
+    const parts = name.split(/\s+/).filter(Boolean);
+    if (parts.length < 2) {
+        return { givenName: parts[0] };
+    }
+    return { givenName: parts.slice(0, -1).join(" "), surname: parts[parts.length - 1] };
+}
+
+/** The first of `contacts` with an email equal (case-insensitively) to `address`. */
+export function findContactByAddress(contacts: readonly Contact[], address: string): Contact | undefined {
+    const wanted = normalizeAddress(address);
+    return contacts.find((contact) => contact.emails.some((email) => normalizeAddress(email.address) === wanted));
+}
+
+/** The domains (lower case) of every address of `mailboxes` - primary and aliases. */
+export function ownDomains(mailboxes: readonly Pick<Mailbox, "primarySmtpAddress" | "aliasAddresses">[]): Set<string> {
+    const domains = new Set<string>();
+    for (const mailbox of mailboxes) {
+        for (const address of [mailbox.primarySmtpAddress, ...(mailbox.aliasAddresses ?? [])]) {
+            const at = address.lastIndexOf("@");
+            if (at > 0) {
+                domains.add(address.slice(at + 1).trim().toLowerCase());
+            }
+        }
+    }
+    return domains;
+}
+
+/** Whether `address` is outside the user's own domains. An address with no domain at all is not called external. */
+export function isExternalAddress(address: string, domains: ReadonlySet<string>): boolean {
+    const at = address.lastIndexOf("@");
+    return at > 0 && !domains.has(address.slice(at + 1).trim().toLowerCase());
+}
+
+/** The card of `cards` that carries `address`; when none does and `orFirst` (the message's sender - a vCard a person attaches is their own), the first card. */
+export function cardForAddress(cards: readonly ParsedVCardContact[], address: string, orFirst: boolean): ParsedVCardContact | undefined {
+    const wanted = normalizeAddress(address);
+    return cards.find((card) => (card.emails ?? []).some((email) => normalizeAddress(email.address) === wanted)) ?? (orFirst ? cards[0] : undefined);
+}
+
+/** A `ContactInput` whose lists are always there. */
+export type KnownPerson = ContactInput & { emails: ContactEmail[]; phones: ContactPhone[]; addresses: ContactPostalAddress[] };
+
+/**
+ * What a new contact for `participant` holds: everything the vCard `card` says (when there is one) and always the participant's address. The
+ * name is the vCard's, else the participant's, else the address's local part; given name and surname are the vCard's `N`, else split from the name.
+ */
+export function contactInputFor(
+    participant: Participant,
+    card: ParsedVCardContact | undefined,
+    scope: { mailboxUid: string; folderUid: string },
+): KnownPerson {
+    // A vCard with no name at all is parsed as "Unnamed contact": not a name worth keeping over the participant's own.
+    const cardName = card && (card.givenName || card.surname || card.displayName !== "Unnamed contact") ? card.displayName : "";
+    const displayName = cardName || participantName(participant);
+    const emails: ContactEmail[] = [...(card?.emails ?? [])];
+    if (!emails.some((email) => normalizeAddress(email.address) === normalizeAddress(participant.address))) {
+        emails.push({ address: participant.address.trim(), type: "other" });
+    }
+    const names = card?.givenName || card?.surname ? { givenName: card.givenName, surname: card.surname } : splitPersonName(displayName);
+    return {
+        ...scope,
+        displayName,
+        givenName: names.givenName,
+        surname: names.surname,
+        emails,
+        phones: card?.phones ?? [],
+        addresses: card?.addresses ?? [],
+        company: card?.company,
+        jobTitle: card?.jobTitle,
+        notes: card?.notes,
+    };
+}
+
+/** A contact made from a vCard on its own, for "Add to address book": the card's own name and details, with the given/surname split when it lacks them. */
+export function contactInputFromCard(card: ParsedVCardContact, scope: { mailboxUid: string; folderUid: string }): KnownPerson {
+    const names = card.givenName || card.surname ? { givenName: card.givenName, surname: card.surname } : splitPersonName(card.displayName);
+    return { ...card, ...scope, ...names, emails: card.emails ?? [], phones: card.phones ?? [], addresses: card.addresses ?? [] };
+}
+
+/** The cards that are not yet in the address book, and how many were: a card is a duplicate when one of its emails is a stored contact's or an earlier card's. */
+export function withoutDuplicates(
+    cards: readonly ParsedVCardContact[],
+    existing: readonly Contact[],
+): { fresh: ParsedVCardContact[]; skipped: number } {
+    const known = new Set(existing.flatMap((contact) => contact.emails.map((email) => normalizeAddress(email.address))));
+    const fresh: ParsedVCardContact[] = [];
+    for (const card of cards) {
+        const addresses = (card.emails ?? []).map((email) => normalizeAddress(email.address));
+        if (addresses.some((address) => known.has(address))) {
+            continue;
+        }
+        addresses.forEach((address) => known.add(address));
+        fresh.push(card);
+    }
+    return { fresh, skipped: cards.length - fresh.length };
+}
+
+/** The sender's own vCard, and the name it is filed under. It is built from - the mailbox's name and primary address, with the phones, company and title of the user's own contact entry when they have one (never its other emails or postal addresses: a card that is sent out says only what it should). */
+export function ownContactCard(mailbox: Pick<Mailbox, "displayName" | "primarySmtpAddress">, own: Contact | undefined): { displayName: string; vcard: string } {
+    const displayName = own?.displayName || mailbox.displayName || participantName({ address: mailbox.primarySmtpAddress });
+    const names = own?.givenName || own?.surname ? { givenName: own.givenName, surname: own.surname } : splitPersonName(displayName);
+    const vcard = contactToVCard({
+        uid: "",
+        version: 0,
+        dateCreated: "",
+        dateModified: "",
+        mailboxUid: "",
+        folderUid: "",
+        displayName,
+        ...names,
+        emails: [{ address: mailbox.primarySmtpAddress, type: "work" }],
+        phones: own?.phones ?? [],
+        addresses: [],
+        company: own?.company,
+        jobTitle: own?.jobTitle,
+    });
+    return { displayName, vcard };
+}