@push.rocks/smartjmap 1.0.0 → 2.1.0

package/ts/classes.memorymailbackend.ts

@@ -0,0 +1,850 @@
+import type { IJmapEmailAddress, IJmapEmailBodyPart, IJmapEmailBodyValue } from './classes.jmapclient.js';
+import {
+  JmapBackendError,
+  type IJmapAccountInfo,
+  type IJmapBlobRecord,
+  type IJmapChanges,
+  type IJmapEmailCreate,
+  type IJmapEmailFilter,
+  type IJmapEmailQueryOptions,
+  type IJmapEmailQueryResult,
+  type IJmapEmailRecord,
+  type IJmapEmailSetRequest,
+  type IJmapEmailSetResult,
+  type IJmapEmailUpdate,
+  type IJmapEnvelope,
+  type IJmapGetResult,
+  type IJmapIdentityRecord,
+  type IJmapMailBackend,
+  type IJmapMailboxRecord,
+  type IJmapStateChange,
+  type IJmapSubmissionInput,
+  type IJmapSubmissionRecord,
+  type IJmapThreadRecord,
+  type TJmapChangeListener,
+  type TJmapPrincipal,
+} from './interfaces.backend.js';
+
+/** A change-log entry: which ids changed at which numeric state. */
+export interface IMemoryChangeEntry {
+  state: number;
+  created: string[];
+  updated: string[];
+  destroyed: string[];
+}
+
+/** Base mailbox fields stored in memory; counters are computed on read. */
+export interface IMemoryMailbox {
+  id: string;
+  name: string;
+  role: string | null;
+  parentId: string | null;
+  sortOrder: number;
+}
+
+/** A stored submission, including the envelope and raw payload for inspection. */
+export interface IMemorySubmission extends IJmapSubmissionRecord {
+  envelope: IJmapEnvelope;
+  message: Uint8Array;
+}
+
+/** The in-memory per-account store, exposed publicly for test assertions. */
+export interface IMemoryMailAccount {
+  username: string;
+  accountId: string;
+  mailboxes: Map<string, IMemoryMailbox>;
+  emails: Map<string, IJmapEmailRecord>;
+  blobs: Map<string, IJmapBlobRecord>;
+  submissions: Map<string, IMemorySubmission>;
+  identities: IJmapIdentityRecord[];
+  emailState: number;
+  emailChanges: IMemoryChangeEntry[];
+  mailboxState: number;
+  mailboxChanges: IMemoryChangeEntry[];
+  threadIdsBySubject: Map<string, string>;
+  idCounter: number;
+}
+
+/** Seeding input for `addEmail`: a convenience superset of an Email create. */
+export interface IMemoryEmailInput {
+  from: IJmapEmailAddress | IJmapEmailAddress[];
+  to: IJmapEmailAddress | IJmapEmailAddress[];
+  cc?: IJmapEmailAddress[];
+  bcc?: IJmapEmailAddress[];
+  subject?: string;
+  textBody?: string;
+  htmlBody?: string;
+  keywords?: Record<string, boolean>;
+  receivedAt?: string;
+  attachments?: Array<{ name: string; type: string; content: string | Uint8Array }>;
+}
+
+const textEncoder = new TextEncoder();
+
+/**
+ * Strips reply/forward prefixes and collapses whitespace so replies group
+ * into the same thread. This normalized-subject heuristic is a documented
+ * simplification of real References-header threading.
+ */
+const normalizeSubject = (subject: string | null | undefined): string =>
+  (subject ?? '')
+    .toLowerCase()
+    .replace(/^(\s*(re|fwd|fw|aw|wg)(\[\d+\])?\s*:\s*)+/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/**
+ * The in-memory reference implementation of `IJmapMailBackend`, used as the
+ * default backend of `JmapServer` for offline testing. Accounts are keyed by
+ * username (accountId = `account_<username>`) and auto-created on first
+ * reference. Seeding helpers: `addAccount`, `createMailbox`, `addEmail`.
+ *
+ * Documented simplifications: thread ids derive from normalized subjects (not
+ * References headers), raw RFC 5322 blobs render headers + the text body only
+ * (attachments are separate blobs, not MIME-encoded into the raw message),
+ * the change log grows unboundedly (one entry per mutation), and destroyed
+ * emails leave their blobs in the blob store.
+ */
+export class MemoryMailBackend implements IJmapMailBackend {
+  public accounts: Map<string, IMemoryMailAccount> = new Map();
+  private changeListeners: Set<TJmapChangeListener> = new Set();
+
+  // ======================
+  // seeding helpers
+  // ======================
+
+  /** Ensures an account exists for the username and returns it. */
+  public addAccount(username: string): IMemoryMailAccount {
+    return this.ensureAccount(username);
+  }
+
+  /** Creates a mailbox (name must be unique per account). Returns the mailbox id. */
+  public createMailbox(username: string, name: string, role?: string): string {
+    const account = this.ensureAccount(username);
+    for (const mailbox of account.mailboxes.values()) {
+      if (mailbox.name === name) {
+        throw new Error(`Mailbox "${name}" already exists for user "${username}".`);
+      }
+    }
+    const id = `mailbox_${++account.idCounter}`;
+    account.mailboxes.set(id, {
+      id,
+      name,
+      role: role ?? null,
+      parentId: null,
+      sortOrder: account.mailboxes.size,
+    });
+    account.mailboxState += 1;
+    account.mailboxChanges.push({
+      state: account.mailboxState,
+      created: [id],
+      updated: [],
+      destroyed: [],
+    });
+    this.emitChange({
+      accountId: account.accountId,
+      changed: { Mailbox: String(account.mailboxState) },
+    });
+    return id;
+  }
+
+  /**
+   * Seeds an email into a mailbox (matched by name or role), bumps the Email
+   * state, and notifies change listeners — connected JmapServers turn this
+   * into a StateChange push. Returns the email id.
+   */
+  public addEmail(username: string, mailboxName: string, input: IMemoryEmailInput): string {
+    const account = this.ensureAccount(username);
+    const mailbox = Array.from(account.mailboxes.values()).find(
+      (candidate) => candidate.name === mailboxName || candidate.role === mailboxName
+    );
+    if (!mailbox) {
+      throw new Error(`Mailbox "${mailboxName}" does not exist for user "${username}".`);
+    }
+
+    const from = Array.isArray(input.from) ? input.from : [input.from];
+    const to = Array.isArray(input.to) ? input.to : [input.to];
+    const textBody = input.textBody ?? '';
+
+    const bodyValues: Record<string, { value: string }> = { text: { value: textBody } };
+    const textBodyParts: IJmapEmailBodyPart[] = [{ partId: 'text', type: 'text/plain' }];
+    const htmlBodyParts: IJmapEmailBodyPart[] = [];
+    if (typeof input.htmlBody === 'string') {
+      bodyValues.html = { value: input.htmlBody };
+      htmlBodyParts.push({ partId: 'html', type: 'text/html' });
+    }
+
+    const attachmentParts: IJmapEmailBodyPart[] = [];
+    for (const attachment of input.attachments ?? []) {
+      const data =
+        typeof attachment.content === 'string'
+          ? textEncoder.encode(attachment.content)
+          : attachment.content;
+      const blobId = `blob_seed_${++account.idCounter}`;
+      account.blobs.set(blobId, { data, type: attachment.type, name: attachment.name });
+      attachmentParts.push({
+        partId: null,
+        blobId,
+        name: attachment.name,
+        type: attachment.type,
+        disposition: 'attachment',
+      });
+    }
+
+    const record = this.buildEmailRecord(account, {
+      mailboxIds: { [mailbox.id]: true },
+      keywords: input.keywords ?? {},
+      from,
+      to,
+      cc: input.cc ?? null,
+      bcc: input.bcc ?? null,
+      subject: input.subject ?? null,
+      receivedAt: input.receivedAt,
+      bodyValues,
+      textBody: textBodyParts,
+      htmlBody: htmlBodyParts,
+      attachments: attachmentParts,
+    });
+    account.emails.set(record.id, record);
+    this.bumpEmailState(account, { created: [record.id] }, new Set([mailbox.id]));
+    return record.id;
+  }
+
+  // ======================
+  // IJmapMailBackend
+  // ======================
+
+  public async resolveAccount(principal: TJmapPrincipal): Promise<IJmapAccountInfo | null> {
+    const account = this.ensureAccount(principal.username);
+    return {
+      accountId: account.accountId,
+      name: account.username,
+      isPersonal: true,
+      isReadOnly: false,
+    };
+  }
+
+  public async getMailboxes(
+    accountId: string,
+    ids: string[] | null
+  ): Promise<IJmapGetResult<IJmapMailboxRecord>> {
+    const account = this.requireAccountById(accountId);
+    const notFound: string[] = [];
+    let mailboxes: IMemoryMailbox[];
+    if (ids === null) {
+      mailboxes = Array.from(account.mailboxes.values());
+    } else {
+      mailboxes = [];
+      for (const id of ids) {
+        const mailbox = account.mailboxes.get(id);
+        if (mailbox) {
+          mailboxes.push(mailbox);
+        } else {
+          notFound.push(id);
+        }
+      }
+    }
+    const list = mailboxes.map((mailbox) => {
+      const emails = Array.from(account.emails.values()).filter(
+        (email) => email.mailboxIds[mailbox.id]
+      );
+      const unread = emails.filter((email) => !email.keywords.$seen);
+      const threadIds = new Set(emails.map((email) => email.threadId));
+      const unreadThreadIds = new Set(unread.map((email) => email.threadId));
+      return {
+        ...mailbox,
+        totalEmails: emails.length,
+        unreadEmails: unread.length,
+        totalThreads: threadIds.size,
+        unreadThreads: unreadThreadIds.size,
+        isSubscribed: true,
+      };
+    });
+    return { state: String(account.mailboxState), list, notFound };
+  }
+
+  public async getMailboxChanges(
+    accountId: string,
+    sinceState: string,
+    maxChanges?: number
+  ): Promise<IJmapChanges | null> {
+    const account = this.requireAccountById(accountId);
+    return this.collectChanges(account.mailboxChanges, account.mailboxState, sinceState, maxChanges);
+  }
+
+  public async getEmails(
+    accountId: string,
+    ids: string[],
+    _properties?: string[] | null
+  ): Promise<IJmapGetResult<IJmapEmailRecord>> {
+    // The properties hint is ignored: records live in memory, so projecting
+    // early saves nothing. The server applies the final projection.
+    const account = this.requireAccountById(accountId);
+    const list: IJmapEmailRecord[] = [];
+    const notFound: string[] = [];
+    for (const id of ids) {
+      const email = account.emails.get(id);
+      if (email) {
+        list.push(email);
+      } else {
+        notFound.push(id);
+      }
+    }
+    return { state: String(account.emailState), list, notFound };
+  }
+
+  public async queryEmails(
+    accountId: string,
+    options: IJmapEmailQueryOptions
+  ): Promise<IJmapEmailQueryResult> {
+    const account = this.requireAccountById(accountId);
+    const filter = options.filter ?? {};
+    let emails = Array.from(account.emails.values()).filter((email) =>
+      this.matchesFilter(email, filter)
+    );
+    const comparator = (options.sort ?? []).find((entry) => entry.property === 'receivedAt');
+    if (comparator) {
+      emails.sort((a, b) => {
+        const comparison = a.receivedAt.localeCompare(b.receivedAt);
+        return comparator.isAscending === false ? -comparison : comparison;
+      });
+    }
+    const total = emails.length;
+    const position = options.position ?? 0;
+    let ids = emails.map((email) => email.id).slice(position);
+    if (typeof options.limit === 'number') {
+      ids = ids.slice(0, options.limit);
+    }
+    const result: IJmapEmailQueryResult = {
+      queryState: String(account.emailState),
+      ids,
+      position,
+    };
+    if (options.calculateTotal) {
+      result.total = total;
+    }
+    return result;
+  }
+
+  public async getEmailChanges(
+    accountId: string,
+    sinceState: string,
+    maxChanges?: number
+  ): Promise<IJmapChanges | null> {
+    const account = this.requireAccountById(accountId);
+    return this.collectChanges(account.emailChanges, account.emailState, sinceState, maxChanges);
+  }
+
+  public async setEmails(
+    accountId: string,
+    request: IJmapEmailSetRequest
+  ): Promise<IJmapEmailSetResult> {
+    const account = this.requireAccountById(accountId);
+    const oldState = String(account.emailState);
+    const created: Record<string, IJmapEmailRecord> = {};
+    const notCreated: Record<string, { type: string; description?: string }> = {};
+    const updated: string[] = [];
+    const notUpdated: Record<string, { type: string; description?: string }> = {};
+    const destroyed: string[] = [];
+    const notDestroyed: Record<string, { type: string; description?: string }> = {};
+    const affectedMailboxIds = new Set<string>();
+
+    for (const [creationId, spec] of Object.entries(request.create ?? {})) {
+      try {
+        const record = this.buildEmailRecord(account, spec);
+        account.emails.set(record.id, record);
+        created[creationId] = record;
+        for (const mailboxId of Object.keys(record.mailboxIds)) {
+          affectedMailboxIds.add(mailboxId);
+        }
+      } catch (error) {
+        notCreated[creationId] = this.toSetError(error);
+      }
+    }
+
+    for (const [id, update] of Object.entries(request.update ?? {})) {
+      const email = account.emails.get(id);
+      if (!email) {
+        notUpdated[id] = { type: 'notFound', description: `Email "${id}" does not exist.` };
+        continue;
+      }
+      try {
+        const previousMailboxIds = Object.keys(email.mailboxIds);
+        this.applyEmailUpdate(account, email, update);
+        for (const mailboxId of [...previousMailboxIds, ...Object.keys(email.mailboxIds)]) {
+          affectedMailboxIds.add(mailboxId);
+        }
+        updated.push(id);
+      } catch (error) {
+        notUpdated[id] = this.toSetError(error);
+      }
+    }
+
+    for (const id of request.destroy ?? []) {
+      const email = account.emails.get(id);
+      if (email) {
+        for (const mailboxId of Object.keys(email.mailboxIds)) {
+          affectedMailboxIds.add(mailboxId);
+        }
+        account.emails.delete(id);
+        destroyed.push(id);
+      } else {
+        notDestroyed[id] = { type: 'notFound', description: `Email "${id}" does not exist.` };
+      }
+    }
+
+    const createdIds = Object.values(created).map((record) => record.id);
+    if (createdIds.length || updated.length || destroyed.length) {
+      this.bumpEmailState(
+        account,
+        { created: createdIds, updated, destroyed },
+        affectedMailboxIds
+      );
+    }
+
+    return {
+      oldState,
+      newState: String(account.emailState),
+      created,
+      notCreated,
+      updated,
+      notUpdated,
+      destroyed,
+      notDestroyed,
+    };
+  }
+
+  public async getThreads(
+    accountId: string,
+    ids: string[]
+  ): Promise<IJmapGetResult<IJmapThreadRecord>> {
+    const account = this.requireAccountById(accountId);
+    const byThread = new Map<string, IJmapEmailRecord[]>();
+    for (const email of account.emails.values()) {
+      const bucket = byThread.get(email.threadId);
+      if (bucket) {
+        bucket.push(email);
+      } else {
+        byThread.set(email.threadId, [email]);
+      }
+    }
+    const list: IJmapThreadRecord[] = [];
+    const notFound: string[] = [];
+    for (const id of ids) {
+      const emails = byThread.get(id);
+      if (emails) {
+        emails.sort((a, b) => a.receivedAt.localeCompare(b.receivedAt));
+        list.push({ id, emailIds: emails.map((email) => email.id) });
+      } else {
+        notFound.push(id);
+      }
+    }
+    return { state: String(account.emailState), list, notFound };
+  }
+
+  public async uploadBlob(
+    accountId: string,
+    data: Uint8Array,
+    type: string
+  ): Promise<{ blobId: string; size: number }> {
+    const account = this.requireAccountById(accountId);
+    const blobId = `blob_upload_${++account.idCounter}`;
+    account.blobs.set(blobId, { data, type });
+    return { blobId, size: data.length };
+  }
+
+  public async getBlob(accountId: string, blobId: string): Promise<IJmapBlobRecord | null> {
+    const account = this.requireAccountById(accountId);
+    return account.blobs.get(blobId) ?? null;
+  }
+
+  public async getIdentities(accountId: string): Promise<IJmapGetResult<IJmapIdentityRecord>> {
+    const account = this.requireAccountById(accountId);
+    return { state: '0', list: account.identities, notFound: [] };
+  }
+
+  public async submitEmail(
+    accountId: string,
+    submission: IJmapSubmissionInput
+  ): Promise<IJmapSubmissionRecord> {
+    const account = this.requireAccountById(accountId);
+    const id = `submission_${++account.idCounter}`;
+    const record: IMemorySubmission = {
+      id,
+      emailId: submission.emailId,
+      identityId: submission.identityId,
+      undoStatus: 'final',
+      sendAt: new Date().toISOString(),
+      envelope: submission.envelope,
+      message: submission.message,
+    };
+    account.submissions.set(id, record);
+    return {
+      id: record.id,
+      emailId: record.emailId,
+      identityId: record.identityId,
+      undoStatus: record.undoStatus,
+      sendAt: record.sendAt,
+    };
+  }
+
+  public subscribeToChanges(listener: TJmapChangeListener): () => void {
+    this.changeListeners.add(listener);
+    return () => {
+      this.changeListeners.delete(listener);
+    };
+  }
+
+  // ======================
+  // internal helpers
+  // ======================
+
+  private ensureAccount(username: string): IMemoryMailAccount {
+    const existing = this.accounts.get(username);
+    if (existing) {
+      return existing;
+    }
+    const email = username.includes('@') ? username : `${username}@example.com`;
+    const account: IMemoryMailAccount = {
+      username,
+      accountId: `account_${username}`,
+      mailboxes: new Map(),
+      emails: new Map(),
+      blobs: new Map(),
+      submissions: new Map(),
+      identities: [{ id: 'identity_1', name: username, email, mayDelete: false }],
+      emailState: 0,
+      emailChanges: [],
+      mailboxState: 0,
+      mailboxChanges: [],
+      threadIdsBySubject: new Map(),
+      idCounter: 0,
+    };
+    this.accounts.set(username, account);
+    return account;
+  }
+
+  private requireAccountById(accountId: string): IMemoryMailAccount {
+    for (const account of this.accounts.values()) {
+      if (account.accountId === accountId) {
+        return account;
+      }
+    }
+    throw new JmapBackendError('accountNotFound', `Account "${accountId}" does not exist.`);
+  }
+
+  private matchesFilter(email: IJmapEmailRecord, filter: IJmapEmailFilter): boolean {
+    const addressMatch = (
+      addresses: IJmapEmailAddress[] | null | undefined,
+      needle: string
+    ): boolean =>
+      (addresses ?? []).some(
+        (address) =>
+          address.email.toLowerCase().includes(needle) ||
+          (address.name ?? '').toLowerCase().includes(needle)
+      );
+    if (typeof filter.inMailbox === 'string' && !email.mailboxIds[filter.inMailbox]) {
+      return false;
+    }
+    if (typeof filter.subject === 'string') {
+      if (!(email.subject ?? '').toLowerCase().includes(filter.subject.toLowerCase())) {
+        return false;
+      }
+    }
+    if (typeof filter.from === 'string' && !addressMatch(email.from, filter.from.toLowerCase())) {
+      return false;
+    }
+    if (typeof filter.to === 'string' && !addressMatch(email.to, filter.to.toLowerCase())) {
+      return false;
+    }
+    if (typeof filter.text === 'string') {
+      const needle = filter.text.toLowerCase();
+      const inBodies = Object.values(email.bodyValues).some((bodyValue) =>
+        bodyValue.value.toLowerCase().includes(needle)
+      );
+      const inAddresses =
+        addressMatch(email.from, needle) ||
+        addressMatch(email.to, needle) ||
+        addressMatch(email.cc, needle) ||
+        addressMatch(email.bcc, needle);
+      if (!(email.subject ?? '').toLowerCase().includes(needle) && !inBodies && !inAddresses) {
+        return false;
+      }
+    }
+    if (typeof filter.before === 'string' && !(email.receivedAt < filter.before)) {
+      return false;
+    }
+    if (typeof filter.after === 'string' && !(email.receivedAt >= filter.after)) {
+      return false;
+    }
+    if (typeof filter.hasKeyword === 'string' && !email.keywords[filter.hasKeyword]) {
+      return false;
+    }
+    if (typeof filter.notKeyword === 'string' && email.keywords[filter.notKeyword]) {
+      return false;
+    }
+    return true;
+  }
+
+  /** Builds a full email record from a validated create spec. Throws JmapBackendError. */
+  private buildEmailRecord(account: IMemoryMailAccount, spec: IJmapEmailCreate): IJmapEmailRecord {
+    const mailboxIds = spec.mailboxIds;
+    if (!mailboxIds || !Object.keys(mailboxIds).length) {
+      throw new JmapBackendError('invalidProperties', 'Email create requires mailboxIds.');
+    }
+    for (const mailboxId of Object.keys(mailboxIds)) {
+      if (!account.mailboxes.has(mailboxId)) {
+        throw new JmapBackendError('invalidProperties', `Mailbox "${mailboxId}" does not exist.`);
+      }
+    }
+
+    const id = `email_${++account.idCounter}`;
+    const receivedAt = spec.receivedAt ?? new Date().toISOString();
+    const bodyValues = spec.bodyValues ?? {};
+    const resolveValue = (part: IJmapEmailBodyPart): string =>
+      part.partId != null ? bodyValues[part.partId]?.value ?? '' : '';
+    const textBodyParts = (spec.textBody ?? []).map((part) => ({
+      partId: part.partId ?? null,
+      type: part.type ?? 'text/plain',
+      size: resolveValue(part).length,
+    }));
+    const htmlBodyParts = (spec.htmlBody ?? []).map((part) => ({
+      partId: part.partId ?? null,
+      type: part.type ?? 'text/html',
+      size: resolveValue(part).length,
+    }));
+    const textValue = textBodyParts
+      .map((part) => (part.partId != null ? bodyValues[part.partId]?.value ?? '' : ''))
+      .join('\n');
+
+    const attachmentParts: IJmapEmailBodyPart[] = [];
+    for (const part of spec.attachments ?? []) {
+      if (typeof part.blobId !== 'string') {
+        throw new JmapBackendError('invalidProperties', 'Attachment parts require a blobId.');
+      }
+      const blob = account.blobs.get(part.blobId);
+      if (!blob) {
+        throw new JmapBackendError('invalidProperties', `Blob "${part.blobId}" does not exist.`);
+      }
+      attachmentParts.push({
+        partId: null,
+        blobId: part.blobId,
+        name: part.name ?? blob.name ?? null,
+        type: part.type ?? blob.type,
+        size: blob.data.length,
+        disposition: part.disposition ?? 'attachment',
+      });
+    }
+
+    const from = spec.from ?? [];
+    const to = spec.to ?? [];
+    // Simplified raw RFC 5322 rendering: headers plus the text body. Attachments
+    // remain separate blobs and are not MIME-encoded into the raw message.
+    const rawLines = [
+      `From: ${from.map((address) => address.email).join(', ')}`,
+      `To: ${to.map((address) => address.email).join(', ')}`,
+      `Subject: ${spec.subject ?? ''}`,
+      `Date: ${receivedAt}`,
+      '',
+      textValue,
+    ];
+    const rawData = textEncoder.encode(rawLines.join('\r\n'));
+    const blobId = `blob_${id}`;
+    account.blobs.set(blobId, { data: rawData, type: 'message/rfc822', name: `${id}.eml` });
+
+    const normalizedBodyValues: Record<string, IJmapEmailBodyValue> = {};
+    for (const [partId, bodyValue] of Object.entries(bodyValues)) {
+      normalizedBodyValues[partId] = { value: bodyValue.value ?? '', isTruncated: false };
+    }
+
+    const attachmentBytes = attachmentParts.reduce((sum, part) => sum + (part.size ?? 0), 0);
+    return {
+      id,
+      blobId,
+      threadId: this.resolveThreadId(account, spec.subject ?? null),
+      mailboxIds: { ...mailboxIds },
+      keywords: { ...(spec.keywords ?? {}) },
+      size: rawData.length + attachmentBytes,
+      receivedAt,
+      sentAt: spec.sentAt ?? receivedAt,
+      messageId: spec.messageId ?? null,
+      inReplyTo: spec.inReplyTo ?? null,
+      references: spec.references ?? null,
+      sender: spec.sender ?? null,
+      subject: spec.subject ?? null,
+      from: spec.from ?? null,
+      to: spec.to ?? null,
+      cc: spec.cc ?? null,
+      bcc: spec.bcc ?? null,
+      replyTo: spec.replyTo ?? null,
+      hasAttachment: attachmentParts.length > 0,
+      preview: textValue.slice(0, 100),
+      bodyValues: normalizedBodyValues,
+      textBody: textBodyParts,
+      htmlBody: htmlBodyParts,
+      attachments: attachmentParts,
+    };
+  }
+
+  /** Applies a normalized email update in place. Throws JmapBackendError. */
+  private applyEmailUpdate(
+    account: IMemoryMailAccount,
+    email: IJmapEmailRecord,
+    update: IJmapEmailUpdate
+  ): void {
+    let keywords = update.keywords ? { ...update.keywords } : { ...email.keywords };
+    for (const [keyword, value] of Object.entries(update.keywordsPatch ?? {})) {
+      if (value === true) {
+        keywords[keyword] = true;
+      } else {
+        delete keywords[keyword];
+      }
+    }
+    let mailboxIds = update.mailboxIds ? { ...update.mailboxIds } : { ...email.mailboxIds };
+    for (const [mailboxId, value] of Object.entries(update.mailboxIdsPatch ?? {})) {
+      if (value === true) {
+        mailboxIds[mailboxId] = true;
+      } else {
+        delete mailboxIds[mailboxId];
+      }
+    }
+    for (const mailboxId of Object.keys(mailboxIds)) {
+      if (!account.mailboxes.has(mailboxId)) {
+        throw new JmapBackendError('invalidProperties', `Mailbox "${mailboxId}" does not exist.`);
+      }
+    }
+    if (!Object.keys(mailboxIds).length) {
+      throw new JmapBackendError(
+        'invalidProperties',
+        'An email must belong to at least one mailbox; destroy it instead.'
+      );
+    }
+    email.keywords = keywords;
+    email.mailboxIds = mailboxIds;
+  }
+
+  private resolveThreadId(account: IMemoryMailAccount, subject: string | null): string {
+    const normalized = normalizeSubject(subject);
+    if (!normalized) {
+      return `thread_${++account.idCounter}`;
+    }
+    const existing = account.threadIdsBySubject.get(normalized);
+    if (existing) {
+      return existing;
+    }
+    const threadId = `thread_${++account.idCounter}`;
+    account.threadIdsBySubject.set(normalized, threadId);
+    return threadId;
+  }
+
+  private collectChanges(
+    entries: IMemoryChangeEntry[],
+    currentState: number,
+    sinceState: string,
+    maxChanges?: number
+  ): IJmapChanges | null {
+    const since = Number(sinceState);
+    if (!Number.isFinite(since) || since < 0 || since > currentState) {
+      return null;
+    }
+    const pending = entries.filter((entry) => entry.state > since);
+    let included = pending;
+    let hasMoreChanges = false;
+    if (typeof maxChanges === 'number' && maxChanges > 0) {
+      included = [];
+      let count = 0;
+      for (const entry of pending) {
+        const entryCount = entry.created.length + entry.updated.length + entry.destroyed.length;
+        if (included.length && count + entryCount > maxChanges) {
+          hasMoreChanges = true;
+          break;
+        }
+        included.push(entry);
+        count += entryCount;
+      }
+    }
+    const created = new Set<string>();
+    const updated = new Set<string>();
+    const destroyed = new Set<string>();
+    for (const entry of included) {
+      for (const id of entry.created) {
+        created.add(id);
+      }
+      for (const id of entry.updated) {
+        updated.add(id);
+      }
+      for (const id of entry.destroyed) {
+        if (created.has(id)) {
+          // created and destroyed within the window: omit entirely
+          created.delete(id);
+        } else {
+          destroyed.add(id);
+        }
+        updated.delete(id);
+      }
+    }
+    for (const id of created) {
+      updated.delete(id);
+    }
+    const newState = hasMoreChanges
+      ? String(included[included.length - 1]!.state)
+      : String(currentState);
+    return {
+      oldState: String(since),
+      newState,
+      hasMoreChanges,
+      created: Array.from(created),
+      updated: Array.from(updated),
+      destroyed: Array.from(destroyed),
+    };
+  }
+
+  private bumpEmailState(
+    account: IMemoryMailAccount,
+    change: { created?: string[]; updated?: string[]; destroyed?: string[] },
+    affectedMailboxIds: Set<string>
+  ): void {
+    account.emailState += 1;
+    account.emailChanges.push({
+      state: account.emailState,
+      created: change.created ?? [],
+      updated: change.updated ?? [],
+      destroyed: change.destroyed ?? [],
+    });
+    const changed: Record<string, string> = {
+      Email: String(account.emailState),
+      Thread: String(account.emailState),
+    };
+    if (affectedMailboxIds.size) {
+      account.mailboxState += 1;
+      account.mailboxChanges.push({
+        state: account.mailboxState,
+        created: [],
+        updated: Array.from(affectedMailboxIds),
+        destroyed: [],
+      });
+      changed.Mailbox = String(account.mailboxState);
+    }
+    this.emitChange({ accountId: account.accountId, changed });
+  }
+
+  private emitChange(change: IJmapStateChange): void {
+    for (const listener of Array.from(this.changeListeners)) {
+      try {
+        listener(change);
+      } catch {
+        // listeners must not break mutation paths
+      }
+    }
+  }
+
+  private toSetError(error: unknown): { type: string; description?: string } {
+    if (error instanceof JmapBackendError) {
+      return { type: error.type, description: error.message };
+    }
+    return {
+      type: 'invalidProperties',
+      description: error instanceof Error ? error.message : String(error),
+    };
+  }
+}