@push.rocks/smartjmap 1.0.0

package/ts/classes.jmapclient.ts

@@ -0,0 +1,872 @@
+import * as plugins from './smartjmap.plugins.js';
+
+export const JMAP_CORE_CAPABILITY = 'urn:ietf:params:jmap:core';
+export const JMAP_MAIL_CAPABILITY = 'urn:ietf:params:jmap:mail';
+export const JMAP_SUBMISSION_CAPABILITY = 'urn:ietf:params:jmap:submission';
+
+export interface IJmapClientAuthBearer {
+  /** OAuth2 / API access token sent as `Authorization: Bearer <token>`. */
+  accessToken: string;
+}
+
+export interface IJmapClientAuthBasic {
+  user: string;
+  pass: string;
+}
+
+export type TJmapClientAuth = IJmapClientAuthBearer | IJmapClientAuthBasic;
+
+export interface IJmapClientConfig {
+  /**
+   * URL of the JMAP session resource.
+   * Callers can pass the autodiscovery endpoint, e.g. `https://host/.well-known/jmap`;
+   * relative URLs inside the session object are resolved against this URL.
+   */
+  sessionUrl: string;
+  /** Either `{ accessToken }` (Bearer) or `{ user, pass }` (Basic) — exactly one shape. */
+  auth: TJmapClientAuth;
+  /**
+   * Mailbox to watch for new messages. Defaults to 'INBOX' semantics:
+   * resolved via the Mailbox with role 'inbox', falling back to a
+   * case-insensitive name match.
+   */
+  mailbox?: string;
+  /** Fallback polling cadence in ms, used when the event stream is unavailable. Default 30000. */
+  pollIntervalMs?: number;
+}
+
+/** A single JMAP method call: [methodName, arguments, methodCallId] (RFC 8620 §3.2). */
+export type TJmapMethodCall = [string, Record<string, any>, string];
+/** A single JMAP method response: [methodName, arguments, methodCallId] (RFC 8620 §3.4). */
+export type TJmapMethodResponse = [string, Record<string, any>, string];
+
+export interface IJmapSession {
+  capabilities: Record<string, any>;
+  accounts: Record<string, any>;
+  primaryAccounts: Record<string, string>;
+  username?: string;
+  apiUrl: string;
+  downloadUrl: string;
+  uploadUrl?: string;
+  eventSourceUrl?: string;
+  state?: string;
+}
+
+export interface IJmapMailbox {
+  id: string;
+  name: string;
+  role?: string | null;
+  parentId?: string | null;
+  sortOrder?: number;
+  totalEmails?: number;
+  unreadEmails?: number;
+  totalThreads?: number;
+  unreadThreads?: number;
+}
+
+export interface IJmapEmailAddress {
+  name?: string | null;
+  email: string;
+}
+
+export interface IJmapEmailBodyPart {
+  partId?: string | null;
+  blobId?: string;
+  size?: number;
+  name?: string | null;
+  type?: string;
+  charset?: string | null;
+  disposition?: string | null;
+  cid?: string | null;
+}
+
+export interface IJmapEmailBodyValue {
+  value: string;
+  isTruncated?: boolean;
+  isEncodingProblem?: boolean;
+}
+
+/** The raw JMAP Email object (RFC 8621 §4) — the subset of properties this client requests. */
+export interface IJmapEmail {
+  id: string;
+  blobId: string;
+  threadId: string;
+  mailboxIds: Record<string, boolean>;
+  keywords: Record<string, boolean>;
+  size?: number;
+  receivedAt?: string;
+  sentAt?: string | null;
+  subject?: string | null;
+  from?: IJmapEmailAddress[] | null;
+  to?: IJmapEmailAddress[] | null;
+  cc?: IJmapEmailAddress[] | null;
+  bcc?: IJmapEmailAddress[] | null;
+  replyTo?: IJmapEmailAddress[] | null;
+  hasAttachment?: boolean;
+  preview?: string;
+  bodyValues?: Record<string, IJmapEmailBodyValue>;
+  textBody?: IJmapEmailBodyPart[];
+  htmlBody?: IJmapEmailBodyPart[];
+  attachments?: IJmapEmailBodyPart[];
+}
+
+export interface IJmapAttachment {
+  blobId: string;
+  name?: string;
+  type?: string;
+  size?: number;
+}
+
+/** The message shape emitted on 'message' events and returned by the query/get helpers. */
+export interface ISmartJmapMessage {
+  id: string;
+  blobId: string;
+  threadId: string;
+  mailboxIds: Record<string, boolean>;
+  keywords: Record<string, boolean>;
+  from: IJmapEmailAddress[];
+  to: IJmapEmailAddress[];
+  cc: IJmapEmailAddress[];
+  bcc: IJmapEmailAddress[];
+  replyTo: IJmapEmailAddress[];
+  subject?: string;
+  receivedAt?: string;
+  /** Plain-text body, resolved from the JMAP bodyValues. */
+  textBody: string;
+  /** HTML body, resolved from the JMAP bodyValues; undefined when the email has no text/html part. */
+  htmlBody?: string;
+  attachments: IJmapAttachment[];
+  /** The full raw JMAP Email object as returned by Email/get. */
+  raw: IJmapEmail;
+}
+
+export interface IJmapOutgoingEmail {
+  /** Sender; defaults to the address of the account's first JMAP Identity. */
+  from?: IJmapEmailAddress;
+  to: IJmapEmailAddress[];
+  cc?: IJmapEmailAddress[];
+  bcc?: IJmapEmailAddress[];
+  subject?: string;
+  textBody?: string;
+  htmlBody?: string;
+}
+
+export interface IJmapSendResult {
+  emailId: string;
+  submissionId: string;
+}
+
+/** Error thrown for HTTP-level (RFC 7807 problem details) and JMAP method-level errors. */
+export class JmapError extends Error {
+  public httpStatus?: number;
+  public problemType?: string;
+  public problemDetail?: string;
+  public jmapErrorType?: string;
+  public jmapErrorDescription?: string;
+  public jmapCallId?: string;
+
+  constructor(message: string, fields: Partial<JmapError> = {}) {
+    super(message);
+    this.name = 'JmapError';
+    Object.assign(this, fields);
+  }
+}
+
+const EMAIL_PROPERTIES = [
+  'id',
+  'blobId',
+  'threadId',
+  'mailboxIds',
+  'keywords',
+  'size',
+  'receivedAt',
+  'sentAt',
+  'subject',
+  'from',
+  'to',
+  'cc',
+  'bcc',
+  'replyTo',
+  'hasAttachment',
+  'preview',
+  'bodyValues',
+  'textBody',
+  'htmlBody',
+  'attachments',
+];
+
+export class JmapClient extends plugins.events.EventEmitter {
+  private config: IJmapClientConfig;
+  private session: IJmapSession | null = null;
+  private accountId: string = '';
+  private apiUrl: string = '';
+  private mailbox: IJmapMailbox | null = null;
+  private connected: boolean = false;
+  private stopped: boolean = false;
+  private lastEmailState: string | null = null;
+  private seenEmailIds: Set<string> = new Set();
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private sseAbortController: AbortController | null = null;
+  private fetchingDeltas: boolean = false;
+  private deltaQueued: boolean = false;
+
+  constructor(config: IJmapClientConfig) {
+    super();
+
+    const auth = config.auth as Partial<IJmapClientAuthBearer & IJmapClientAuthBasic>;
+    const hasBearer = typeof auth.accessToken === 'string';
+    const hasBasic = typeof auth.user === 'string' && typeof auth.pass === 'string';
+    if (!hasBearer && !hasBasic) {
+      throw new Error(
+        'JmapClient requires auth as either { accessToken } (Bearer) or { user, pass } (Basic).'
+      );
+    }
+    if (hasBearer && (typeof auth.user === 'string' || typeof auth.pass === 'string')) {
+      throw new Error('JmapClient auth accepts either { accessToken } or { user, pass }, not both.');
+    }
+    if (typeof config.sessionUrl !== 'string' || !config.sessionUrl) {
+      throw new Error('JmapClient requires a sessionUrl, e.g. https://host/.well-known/jmap');
+    }
+
+    this.config = config;
+  }
+
+  /**
+   * Fetches and validates the JMAP session, resolves the target mailbox,
+   * emits 'connected', emits 'message' for every email currently in the
+   * mailbox, then watches for new mail via the JMAP event source (SSE),
+   * falling back to polling when the event stream is unavailable.
+   * Failures are emitted as 'error' events; connect() does not throw.
+   */
+  public async connect(): Promise<void> {
+    // Reconnecting on the same instance is supported; release any watchers
+    // from a previous connect() so no SSE stream or poll timer is stranded.
+    this.teardownWatchers();
+    this.stopped = false;
+    try {
+      const response = await fetch(this.config.sessionUrl, {
+        headers: {
+          authorization: this.getAuthHeader(),
+          accept: 'application/json',
+        },
+      });
+      if (!response.ok) {
+        throw await this.createHttpError(response, 'Failed to fetch JMAP session');
+      }
+      const session = (await response.json()) as IJmapSession;
+      if (!session.capabilities || !(JMAP_CORE_CAPABILITY in session.capabilities)) {
+        throw new Error(`JMAP session is missing the ${JMAP_CORE_CAPABILITY} capability.`);
+      }
+      if (!(JMAP_MAIL_CAPABILITY in session.capabilities)) {
+        throw new Error(`JMAP session is missing the ${JMAP_MAIL_CAPABILITY} capability.`);
+      }
+      const accountId =
+        session.primaryAccounts?.[JMAP_MAIL_CAPABILITY] ??
+        session.primaryAccounts?.[JMAP_CORE_CAPABILITY];
+      if (!accountId) {
+        throw new Error('JMAP session has no primary account for urn:ietf:params:jmap:mail.');
+      }
+      this.session = session;
+      this.accountId = accountId;
+      this.apiUrl = new URL(session.apiUrl, this.config.sessionUrl).toString();
+
+      this.mailbox = await this.resolveMailbox();
+      // Capture the Email state before the initial sweep so no change is lost
+      // between the sweep and the start of watching (dedupe handles overlap).
+      this.lastEmailState = await this.fetchEmailState();
+
+      if (this.stopped) {
+        // disconnect() was called while connect() was in flight.
+        return;
+      }
+      this.connected = true;
+      this.emit('connected');
+
+      await this.emitInitialEmails();
+      this.startWatching();
+    } catch (error) {
+      // Clean up anything that may have been started; this instance holds no
+      // sockets or timers after a failed connect.
+      this.teardownWatchers();
+      this.connected = false;
+      this.emit('error', error);
+    }
+  }
+
+  /**
+   * Stops watching (event stream and/or polling timer) and emits
+   * 'disconnected' when the client was connected. Leaves no open handles.
+   */
+  public async disconnect(): Promise<void> {
+    this.stopped = true;
+    this.teardownWatchers();
+    if (this.connected) {
+      this.connected = false;
+      this.emit('disconnected');
+    }
+  }
+
+  /**
+   * Core JMAP method-call helper (RFC 8620 §3.2): POSTs { using, methodCalls }
+   * to the session's apiUrl and returns the methodResponses. HTTP problem
+   * details (RFC 7807) and JMAP `error` method responses are thrown as
+   * JmapError with `httpStatus`/`problemType`/`jmapErrorType` fields.
+   */
+  public async request(methodCalls: TJmapMethodCall[]): Promise<TJmapMethodResponse[]> {
+    if (!this.apiUrl) {
+      throw new Error('JmapClient is not connected yet — call connect() first.');
+    }
+    const response = await fetch(this.apiUrl, {
+      method: 'POST',
+      headers: {
+        authorization: this.getAuthHeader(),
+        'content-type': 'application/json',
+        accept: 'application/json',
+      },
+      body: JSON.stringify({
+        using: [JMAP_CORE_CAPABILITY, JMAP_MAIL_CAPABILITY, JMAP_SUBMISSION_CAPABILITY],
+        methodCalls,
+      }),
+    });
+    if (!response.ok) {
+      throw await this.createHttpError(response, 'JMAP API request failed');
+    }
+    const parsed = (await response.json()) as { methodResponses?: TJmapMethodResponse[] };
+    const methodResponses = parsed.methodResponses ?? [];
+    for (const [name, args, callId] of methodResponses) {
+      if (name === 'error') {
+        throw new JmapError(
+          `JMAP method error "${args?.type}"${args?.description ? `: ${args.description}` : ''} (call ${callId})`,
+          {
+            jmapErrorType: args?.type,
+            jmapErrorDescription: args?.description,
+            jmapCallId: callId,
+          }
+        );
+      }
+    }
+    return methodResponses;
+  }
+
+  /** Returns all mailboxes of the account (Mailbox/get with ids: null). */
+  public async getMailboxes(): Promise<IJmapMailbox[]> {
+    const responses = await this.request([
+      ['Mailbox/get', { accountId: this.accountId, ids: null }, 'mb0'],
+    ]);
+    return (responses[0][1].list ?? []) as IJmapMailbox[];
+  }
+
+  /**
+   * Runs Email/query (default filter: the watched mailbox) followed by a full
+   * Email/get and returns resolved messages, newest first.
+   */
+  public async queryEmails(
+    filter?: Record<string, any>,
+    limit?: number
+  ): Promise<ISmartJmapMessage[]> {
+    const effectiveFilter =
+      filter ?? (this.mailbox ? { inMailbox: this.mailbox.id } : {});
+    const queryArgs: Record<string, any> = {
+      accountId: this.accountId,
+      filter: effectiveFilter,
+      sort: [{ property: 'receivedAt', isAscending: false }],
+    };
+    if (typeof limit === 'number') {
+      queryArgs.limit = limit;
+    }
+    const responses = await this.request([['Email/query', queryArgs, 'q0']]);
+    const ids: string[] = responses[0][1].ids ?? [];
+    if (!ids.length) {
+      return [];
+    }
+    const emails = await this.getEmailObjects(ids);
+    return emails.map((email) => this.toMessage(email));
+  }
+
+  /** Fetches a single email with all body values resolved (RFC 8621 §4.2, fetchAllBodyValues). */
+  public async getEmail(id: string): Promise<ISmartJmapMessage> {
+    const [email] = await this.getEmailObjects([id]);
+    if (!email) {
+      throw new Error(`Email "${id}" not found.`);
+    }
+    return this.toMessage(email);
+  }
+
+  /** Replaces the full keywords object of an email via Email/set. */
+  public async setKeywords(emailId: string, keywords: Record<string, boolean>): Promise<void> {
+    await this.updateEmail(emailId, { keywords });
+  }
+
+  /** Convenience: sets the $seen keyword via an Email/set keywords patch. */
+  public async markSeen(emailId: string): Promise<void> {
+    await this.updateEmail(emailId, { 'keywords/$seen': true });
+  }
+
+  /**
+   * Sends an email: Identity/get lookup, Email/set create (into the mailbox
+   * with role 'sent', falling back to 'drafts', then the watched mailbox) and
+   * EmailSubmission/set referencing the created email.
+   */
+  public async sendEmail(outgoing: IJmapOutgoingEmail): Promise<IJmapSendResult> {
+    const identityResponses = await this.request([
+      ['Identity/get', { accountId: this.accountId }, 'i0'],
+    ]);
+    const identities: any[] = identityResponses[0][1].list ?? [];
+    const identity =
+      (outgoing.from
+        ? identities.find((candidate) => candidate.email === outgoing.from!.email)
+        : undefined) ?? identities[0];
+    if (!identity) {
+      throw new Error('No JMAP identity available for sending.');
+    }
+    const from: IJmapEmailAddress =
+      outgoing.from ?? { name: identity.name ?? null, email: identity.email };
+
+    const mailboxes = await this.getMailboxes();
+    const targetMailbox =
+      mailboxes.find((mb) => mb.role === 'sent') ??
+      mailboxes.find((mb) => mb.role === 'drafts') ??
+      this.mailbox;
+    if (!targetMailbox) {
+      throw new Error('No mailbox available to store the outgoing email in.');
+    }
+
+    const bodyValues: Record<string, { value: string }> = {};
+    const textBodyParts: IJmapEmailBodyPart[] = [];
+    const htmlBodyParts: IJmapEmailBodyPart[] = [];
+    if (typeof outgoing.textBody === 'string') {
+      bodyValues.text = { value: outgoing.textBody };
+      textBodyParts.push({ partId: 'text', type: 'text/plain' });
+    }
+    if (typeof outgoing.htmlBody === 'string') {
+      bodyValues.html = { value: outgoing.htmlBody };
+      htmlBodyParts.push({ partId: 'html', type: 'text/html' });
+    }
+    if (!textBodyParts.length && !htmlBodyParts.length) {
+      throw new Error('sendEmail requires textBody and/or htmlBody.');
+    }
+
+    const emailCreate: Record<string, any> = {
+      mailboxIds: { [targetMailbox.id]: true },
+      keywords: { $seen: true },
+      from: [from],
+      to: outgoing.to,
+      subject: outgoing.subject,
+      bodyValues,
+    };
+    if (outgoing.cc) {
+      emailCreate.cc = outgoing.cc;
+    }
+    if (outgoing.bcc) {
+      emailCreate.bcc = outgoing.bcc;
+    }
+    if (textBodyParts.length) {
+      emailCreate.textBody = textBodyParts;
+    }
+    if (htmlBodyParts.length) {
+      emailCreate.htmlBody = htmlBodyParts;
+    }
+
+    const responses = await this.request([
+      ['Email/set', { accountId: this.accountId, create: { newEmail: emailCreate } }, 'c0'],
+      [
+        'EmailSubmission/set',
+        {
+          accountId: this.accountId,
+          create: { newSubmission: { emailId: '#newEmail', identityId: identity.id } },
+        },
+        'c1',
+      ],
+    ]);
+
+    const emailSetResult = responses.find((entry) => entry[2] === 'c0')?.[1] ?? {};
+    const createdEmail = emailSetResult.created?.newEmail;
+    if (!createdEmail) {
+      const notCreated = emailSetResult.notCreated?.newEmail;
+      throw new JmapError(
+        `Email/set create failed${notCreated ? `: ${notCreated.type}${notCreated.description ? ` — ${notCreated.description}` : ''}` : ''}`,
+        { jmapErrorType: notCreated?.type, jmapErrorDescription: notCreated?.description }
+      );
+    }
+    const submissionSetResult = responses.find((entry) => entry[2] === 'c1')?.[1] ?? {};
+    const createdSubmission = submissionSetResult.created?.newSubmission;
+    if (!createdSubmission) {
+      const notCreated = submissionSetResult.notCreated?.newSubmission;
+      throw new JmapError(
+        `EmailSubmission/set create failed${notCreated ? `: ${notCreated.type}${notCreated.description ? ` — ${notCreated.description}` : ''}` : ''}`,
+        { jmapErrorType: notCreated?.type, jmapErrorDescription: notCreated?.description }
+      );
+    }
+    return { emailId: createdEmail.id, submissionId: createdSubmission.id };
+  }
+
+  /**
+   * Downloads a blob's raw bytes using the session downloadUrl template
+   * (RFC 8620 §6.2: {accountId}, {blobId}, {type}, {name}).
+   */
+  public async downloadBlob(
+    blobId: string,
+    type: string = 'application/octet-stream',
+    name: string = 'blob'
+  ): Promise<Uint8Array> {
+    const template = this.session?.downloadUrl;
+    if (!template) {
+      throw new Error('JMAP session provides no downloadUrl — call connect() first.');
+    }
+    const expanded = template
+      .replace('{accountId}', encodeURIComponent(this.accountId))
+      .replace('{blobId}', encodeURIComponent(blobId))
+      .replace('{type}', encodeURIComponent(type))
+      .replace('{name}', encodeURIComponent(name));
+    const url = new URL(expanded, this.config.sessionUrl).toString();
+    const response = await fetch(url, {
+      headers: { authorization: this.getAuthHeader() },
+    });
+    if (!response.ok) {
+      throw await this.createHttpError(response, `Failed to download blob "${blobId}"`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  // ======================
+  // internal helpers
+  // ======================
+
+  private getAuthHeader(): string {
+    const auth = this.config.auth as Partial<IJmapClientAuthBearer & IJmapClientAuthBasic>;
+    if (typeof auth.accessToken === 'string') {
+      return `Bearer ${auth.accessToken}`;
+    }
+    return `Basic ${Buffer.from(`${auth.user}:${auth.pass}`).toString('base64')}`;
+  }
+
+  private async createHttpError(response: Response, messagePrefix: string): Promise<JmapError> {
+    let problemType: string | undefined;
+    let problemDetail: string | undefined;
+    try {
+      const body = (await response.json()) as any;
+      if (body && typeof body === 'object') {
+        problemType = typeof body.type === 'string' ? body.type : undefined;
+        problemDetail = typeof body.detail === 'string' ? body.detail : undefined;
+      }
+    } catch {
+      // non-JSON error body
+    }
+    return new JmapError(
+      `${messagePrefix}: HTTP ${response.status}${problemDetail ? ` — ${problemDetail}` : ''}${problemType ? ` (${problemType})` : ''}`,
+      { httpStatus: response.status, problemType, problemDetail }
+    );
+  }
+
+  private async resolveMailbox(): Promise<IJmapMailbox> {
+    const responses = await this.request([
+      ['Mailbox/get', { accountId: this.accountId, ids: null }, 'mb0'],
+    ]);
+    const list = (responses[0][1].list ?? []) as IJmapMailbox[];
+    const wanted = this.config.mailbox ?? 'INBOX';
+    const wantedLower = wanted.toLowerCase();
+    const byRole = list.find((mb) => (mb.role ?? '').toLowerCase() === wantedLower);
+    const byName = list.find((mb) => mb.name.toLowerCase() === wantedLower);
+    const mailbox = byRole ?? byName;
+    if (!mailbox) {
+      throw new Error(`JMAP mailbox "${wanted}" not found (no role or name match).`);
+    }
+    return mailbox;
+  }
+
+  private async fetchEmailState(): Promise<string> {
+    const responses = await this.request([
+      ['Email/get', { accountId: this.accountId, ids: [] }, 'st0'],
+    ]);
+    return String(responses[0][1].state ?? '');
+  }
+
+  private async getEmailObjects(ids: string[]): Promise<IJmapEmail[]> {
+    const responses = await this.request([
+      [
+        'Email/get',
+        {
+          accountId: this.accountId,
+          ids,
+          properties: EMAIL_PROPERTIES,
+          fetchAllBodyValues: true,
+        },
+        'g0',
+      ],
+    ]);
+    return (responses[0][1].list ?? []) as IJmapEmail[];
+  }
+
+  private async updateEmail(emailId: string, patch: Record<string, any>): Promise<void> {
+    const responses = await this.request([
+      ['Email/set', { accountId: this.accountId, update: { [emailId]: patch } }, 'u0'],
+    ]);
+    const result = responses[0][1];
+    const notUpdated = result.notUpdated?.[emailId];
+    if (notUpdated) {
+      throw new JmapError(
+        `Email/set update of "${emailId}" failed: ${notUpdated.type}${notUpdated.description ? ` — ${notUpdated.description}` : ''}`,
+        { jmapErrorType: notUpdated.type, jmapErrorDescription: notUpdated.description }
+      );
+    }
+  }
+
+  private toMessage(email: IJmapEmail): ISmartJmapMessage {
+    const bodyValues = email.bodyValues ?? {};
+    const resolveParts = (parts: IJmapEmailBodyPart[]): string =>
+      parts
+        .map((part) => (part.partId != null ? bodyValues[part.partId]?.value : undefined))
+        .filter((value): value is string => typeof value === 'string')
+        .join('\n');
+    const htmlParts = (email.htmlBody ?? []).filter((part) => part.type === 'text/html');
+    const attachments: IJmapAttachment[] = (email.attachments ?? [])
+      .filter((part) => typeof part.blobId === 'string')
+      .map((part) => ({
+        blobId: part.blobId as string,
+        name: part.name ?? undefined,
+        type: part.type,
+        size: part.size,
+      }));
+    return {
+      id: email.id,
+      blobId: email.blobId,
+      threadId: email.threadId,
+      mailboxIds: email.mailboxIds ?? {},
+      keywords: email.keywords ?? {},
+      from: email.from ?? [],
+      to: email.to ?? [],
+      cc: email.cc ?? [],
+      bcc: email.bcc ?? [],
+      replyTo: email.replyTo ?? [],
+      subject: email.subject ?? undefined,
+      receivedAt: email.receivedAt,
+      textBody: resolveParts(email.textBody ?? []),
+      htmlBody: htmlParts.length ? resolveParts(htmlParts) : undefined,
+      attachments,
+      raw: email,
+    };
+  }
+
+  private emitMessage(message: ISmartJmapMessage): void {
+    if (this.seenEmailIds.has(message.id)) {
+      return;
+    }
+    this.seenEmailIds.add(message.id);
+    this.emit('message', message);
+  }
+
+  private async emitInitialEmails(): Promise<void> {
+    const messages = await this.queryEmails();
+    // queryEmails sorts newest first; emit oldest first for natural ordering
+    for (const message of messages.reverse()) {
+      this.emitMessage(message);
+    }
+  }
+
+  private startWatching(): void {
+    if (this.stopped) {
+      return;
+    }
+    const eventSourceUrl = this.session?.eventSourceUrl;
+    if (eventSourceUrl) {
+      this.startEventStream(eventSourceUrl);
+    } else {
+      this.startPolling();
+    }
+  }
+
+  /**
+   * Watches the JMAP event source (RFC 8620 §7.3) by parsing SSE frames from
+   * a fetch body stream. A hand-rolled parser is used instead of the global
+   * EventSource because JMAP requires an Authorization header, which the
+   * WHATWG EventSource API cannot send.
+   */
+  private startEventStream(templateUrl: string): void {
+    const expanded = templateUrl
+      .replace('{types}', '*')
+      .replace('{closeafter}', 'no')
+      .replace('{ping}', '30');
+    const url = new URL(expanded, this.config.sessionUrl).toString();
+    // Last stream wins under any interleaving: abort a previous stream before
+    // installing the new controller.
+    if (this.sseAbortController) {
+      this.sseAbortController.abort();
+    }
+    const abortController = new AbortController();
+    this.sseAbortController = abortController;
+    void this.runEventStream(url, abortController);
+  }
+
+  private async runEventStream(url: string, abortController: AbortController): Promise<void> {
+    try {
+      const response = await fetch(url, {
+        headers: {
+          authorization: this.getAuthHeader(),
+          accept: 'text/event-stream',
+        },
+        signal: abortController.signal,
+      });
+      if (!response.ok || !response.body) {
+        throw new Error(`JMAP event source unavailable (HTTP ${response.status}).`);
+      }
+      // The stream is live; catch up on anything that changed between the
+      // initial state snapshot and the stream being established.
+      void this.fetchDeltas();
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      let eventName = 'message';
+      let dataLines: string[] = [];
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        let newlineIndex: number;
+        while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+          const line = buffer.slice(0, newlineIndex).replace(/\r$/, '');
+          buffer = buffer.slice(newlineIndex + 1);
+          if (line === '') {
+            if (dataLines.length) {
+              this.handleEventStreamEvent(eventName, dataLines.join('\n'));
+            }
+            eventName = 'message';
+            dataLines = [];
+          } else if (line.startsWith(':')) {
+            // comment / keepalive
+          } else if (line.startsWith('event:')) {
+            eventName = line.slice(6).trim();
+          } else if (line.startsWith('data:')) {
+            dataLines.push(line.slice(5).replace(/^ /, ''));
+          }
+          // id: and retry: fields are irrelevant here
+        }
+      }
+      // Stream ended server-side: fall back to polling (mirroring the catch
+      // guards so a superseded stream's continuation stays inert).
+      if (!this.stopped && !abortController.signal.aborted) {
+        if (this.sseAbortController === abortController) {
+          this.sseAbortController = null;
+        }
+        this.startPolling();
+      }
+    } catch (error) {
+      if (this.stopped || abortController.signal.aborted) {
+        return;
+      }
+      // Event stream unavailable or broken: abort so any held response body
+      // (e.g. an unconsumed non-OK response) releases its connection, then
+      // fall back to polling.
+      abortController.abort();
+      if (this.sseAbortController === abortController) {
+        this.sseAbortController = null;
+      }
+      this.startPolling();
+    }
+  }
+
+  private handleEventStreamEvent(eventName: string, data: string): void {
+    let parsed: any;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (eventName !== 'state' && parsed?.['@type'] !== 'StateChange') {
+      return;
+    }
+    const changed = parsed?.changed?.[this.accountId];
+    const emailState = changed?.Email;
+    if (typeof emailState === 'string' && emailState !== this.lastEmailState) {
+      void this.fetchDeltas();
+    }
+  }
+
+  private startPolling(): void {
+    if (this.pollTimer || this.stopped) {
+      return;
+    }
+    const interval = this.config.pollIntervalMs ?? 30000;
+    this.pollTimer = setInterval(() => {
+      void this.fetchDeltas();
+    }, interval);
+  }
+
+  private async fetchDeltas(): Promise<void> {
+    if (this.stopped) {
+      return;
+    }
+    if (this.fetchingDeltas) {
+      this.deltaQueued = true;
+      return;
+    }
+    this.fetchingDeltas = true;
+    try {
+      do {
+        this.deltaQueued = false;
+        await this.fetchDeltasOnce();
+      } while (this.deltaQueued && !this.stopped);
+    } finally {
+      this.fetchingDeltas = false;
+    }
+  }
+
+  private async fetchDeltasOnce(): Promise<void> {
+    try {
+      let hasMore = true;
+      while (hasMore && !this.stopped) {
+        const sinceState = this.lastEmailState;
+        const responses = await this.request([
+          ['Email/changes', { accountId: this.accountId, sinceState }, 'ch0'],
+        ]);
+        const changes = responses[0][1];
+        this.lastEmailState = String(changes.newState ?? sinceState);
+        hasMore = changes.hasMoreChanges === true && this.lastEmailState !== sinceState;
+        const createdIds: string[] = changes.created ?? [];
+        if (createdIds.length) {
+          const emails = await this.getEmailObjects(createdIds);
+          for (const email of emails) {
+            if (this.mailbox && email.mailboxIds?.[this.mailbox.id]) {
+              this.emitMessage(this.toMessage(email));
+            }
+          }
+        }
+      }
+    } catch (error) {
+      if (this.stopped) {
+        return;
+      }
+      if ((error as JmapError)?.jmapErrorType === 'cannotCalculateChanges') {
+        try {
+          await this.resyncViaQuery();
+        } catch (resyncError) {
+          this.emit('error', resyncError);
+        }
+      } else {
+        this.emit('error', error);
+      }
+    }
+  }
+
+  /** Full resync fallback when the server cannot calculate changes. */
+  private async resyncViaQuery(): Promise<void> {
+    this.lastEmailState = await this.fetchEmailState();
+    const messages = await this.queryEmails();
+    for (const message of messages.reverse()) {
+      this.emitMessage(message);
+    }
+  }
+
+  private teardownWatchers(): void {
+    if (this.sseAbortController) {
+      this.sseAbortController.abort();
+      this.sseAbortController = null;
+    }
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+}