@push.rocks/smartjmap 1.0.0 → 2.1.0

package/ts/classes.jmapclient.ts

@@ -140,6 +140,13 @@ export interface ISmartJmapMessage {
   raw: IJmapEmail;
 }
 
+/** An attachment reference for outgoing mail; upload the bytes first via `uploadBlob`. */
+export interface IJmapOutgoingAttachment {
+  blobId: string;
+  type: string;
+  name?: string;
+}
+
 export interface IJmapOutgoingEmail {
   /** Sender; defaults to the address of the account's first JMAP Identity. */
   from?: IJmapEmailAddress;
@@ -149,6 +156,8 @@ export interface IJmapOutgoingEmail {
   subject?: string;
   textBody?: string;
   htmlBody?: string;
+  /** Attachments referencing blobs previously uploaded with `uploadBlob`. */
+  attachments?: IJmapOutgoingAttachment[];
 }
 
 export interface IJmapSendResult {
@@ -156,6 +165,14 @@ export interface IJmapSendResult {
   submissionId: string;
 }
 
+/** The upload endpoint's response (RFC 8620 §6.1). */
+export interface IJmapUploadResult {
+  accountId: string;
+  blobId: string;
+  type: string;
+  size: number;
+}
+
 /** Error thrown for HTTP-level (RFC 7807 problem details) and JMAP method-level errors. */
 export class JmapError extends Error {
   public httpStatus?: number;
@@ -195,20 +212,26 @@ const EMAIL_PROPERTIES = [
   'attachments',
 ];
 
+interface IConnectionGeneration {
+  id: number;
+  abortController: AbortController;
+  session: IJmapSession | null;
+  accountId: string;
+  apiUrl: string;
+  mailbox: IJmapMailbox | null;
+  connected: boolean;
+  lastEmailState: string | null;
+  seenEmailIds: Set<string>;
+  pollTimer: ReturnType<typeof setInterval> | null;
+  sseAbortController: AbortController | null;
+  fetchingDeltas: boolean;
+  deltaQueued: boolean;
+}
+
 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;
+  private generationCounter = 0;
+  private connectionGeneration: IConnectionGeneration | null = null;
 
   constructor(config: IJmapClientConfig) {
     super();
@@ -239,21 +262,31 @@ export class JmapClient extends plugins.events.EventEmitter {
    * 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;
+    const previousGeneration = this.connectionGeneration;
+    const generation = this.createConnectionGeneration();
+    this.connectionGeneration = generation;
+    if (previousGeneration) {
+      this.teardownGeneration(
+        previousGeneration,
+        new Error('JMAP connection was superseded by a newer connect().')
+      );
+    }
     try {
       const response = await fetch(this.config.sessionUrl, {
         headers: {
           authorization: this.getAuthHeader(),
           accept: 'application/json',
         },
+        signal: generation.abortController.signal,
       });
+      this.assertCurrentGeneration(generation);
       if (!response.ok) {
-        throw await this.createHttpError(response, 'Failed to fetch JMAP session');
+        const error = await this.createHttpError(response, 'Failed to fetch JMAP session');
+        this.assertCurrentGeneration(generation);
+        throw error;
       }
       const session = (await response.json()) as IJmapSession;
+      this.assertCurrentGeneration(generation);
       if (!session.capabilities || !(JMAP_CORE_CAPABILITY in session.capabilities)) {
         throw new Error(`JMAP session is missing the ${JMAP_CORE_CAPABILITY} capability.`);
       }
@@ -266,29 +299,31 @@ export class JmapClient extends plugins.events.EventEmitter {
       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();
+      generation.session = session;
+      generation.accountId = accountId;
+      generation.apiUrl = new URL(session.apiUrl, this.config.sessionUrl).toString();
 
-      this.mailbox = await this.resolveMailbox();
+      generation.mailbox = await this.resolveMailbox(generation);
+      this.assertCurrentGeneration(generation);
       // 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;
+      generation.lastEmailState = await this.fetchEmailState(generation);
+      this.assertCurrentGeneration(generation);
+      generation.connected = true;
       this.emit('connected');
 
-      await this.emitInitialEmails();
-      this.startWatching();
+      await this.emitInitialEmails(generation);
+      this.assertCurrentGeneration(generation);
+      this.startWatching(generation);
     } 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;
+      if (!this.isCurrentGeneration(generation)) {
+        return;
+      }
+      const shouldEmitError = !generation.abortController.signal.aborted;
+      this.connectionGeneration = null;
+      generation.connected = false;
+      this.teardownGeneration(generation, error);
+      if (!shouldEmitError) return;
       this.emit('error', error);
     }
   }
@@ -298,10 +333,13 @@ export class JmapClient extends plugins.events.EventEmitter {
    * '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;
+    const generation = this.connectionGeneration;
+    if (!generation) return;
+    this.connectionGeneration = null;
+    const wasConnected = generation.connected;
+    generation.connected = false;
+    this.teardownGeneration(generation, new Error('JMAP client disconnected.'));
+    if (wasConnected) {
       this.emit('disconnected');
     }
   }
@@ -313,10 +351,18 @@ export class JmapClient extends plugins.events.EventEmitter {
    * JmapError with `httpStatus`/`problemType`/`jmapErrorType` fields.
    */
   public async request(methodCalls: TJmapMethodCall[]): Promise<TJmapMethodResponse[]> {
-    if (!this.apiUrl) {
+    return await this.requestWithGeneration(this.requireConnectedGeneration(), methodCalls);
+  }
+
+  private async requestWithGeneration(
+    generation: IConnectionGeneration,
+    methodCalls: TJmapMethodCall[]
+  ): Promise<TJmapMethodResponse[]> {
+    this.assertCurrentGeneration(generation);
+    if (!generation.apiUrl) {
       throw new Error('JmapClient is not connected yet — call connect() first.');
     }
-    const response = await fetch(this.apiUrl, {
+    const response = await fetch(generation.apiUrl, {
       method: 'POST',
       headers: {
         authorization: this.getAuthHeader(),
@@ -327,11 +373,16 @@ export class JmapClient extends plugins.events.EventEmitter {
         using: [JMAP_CORE_CAPABILITY, JMAP_MAIL_CAPABILITY, JMAP_SUBMISSION_CAPABILITY],
         methodCalls,
       }),
+      signal: generation.abortController.signal,
     });
+    this.assertCurrentGeneration(generation);
     if (!response.ok) {
-      throw await this.createHttpError(response, 'JMAP API request failed');
+      const error = await this.createHttpError(response, 'JMAP API request failed');
+      this.assertCurrentGeneration(generation);
+      throw error;
     }
     const parsed = (await response.json()) as { methodResponses?: TJmapMethodResponse[] };
+    this.assertCurrentGeneration(generation);
     const methodResponses = parsed.methodResponses ?? [];
     for (const [name, args, callId] of methodResponses) {
       if (name === 'error') {
@@ -350,8 +401,14 @@ export class JmapClient extends plugins.events.EventEmitter {
 
   /** 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 await this.getMailboxesWithGeneration(this.requireConnectedGeneration());
+  }
+
+  private async getMailboxesWithGeneration(
+    generation: IConnectionGeneration
+  ): Promise<IJmapMailbox[]> {
+    const responses = await this.requestWithGeneration(generation, [
+      ['Mailbox/get', { accountId: generation.accountId, ids: null }, 'mb0'],
     ]);
     return (responses[0][1].list ?? []) as IJmapMailbox[];
   }
@@ -363,29 +420,44 @@ export class JmapClient extends plugins.events.EventEmitter {
   public async queryEmails(
     filter?: Record<string, any>,
     limit?: number
+  ): Promise<ISmartJmapMessage[]> {
+    return await this.queryEmailsWithGeneration(
+      this.requireConnectedGeneration(),
+      filter,
+      limit
+    );
+  }
+
+  private async queryEmailsWithGeneration(
+    generation: IConnectionGeneration,
+    filter?: Record<string, any>,
+    limit?: number
   ): Promise<ISmartJmapMessage[]> {
     const effectiveFilter =
-      filter ?? (this.mailbox ? { inMailbox: this.mailbox.id } : {});
+      filter ?? (generation.mailbox ? { inMailbox: generation.mailbox.id } : {});
     const queryArgs: Record<string, any> = {
-      accountId: this.accountId,
+      accountId: generation.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 responses = await this.requestWithGeneration(generation, [
+      ['Email/query', queryArgs, 'q0'],
+    ]);
     const ids: string[] = responses[0][1].ids ?? [];
     if (!ids.length) {
       return [];
     }
-    const emails = await this.getEmailObjects(ids);
+    const emails = await this.getEmailObjects(generation, 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]);
+    const generation = this.requireConnectedGeneration();
+    const [email] = await this.getEmailObjects(generation, [id]);
     if (!email) {
       throw new Error(`Email "${id}" not found.`);
     }
@@ -394,12 +466,59 @@ export class JmapClient extends plugins.events.EventEmitter {
 
   /** 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 });
+    await this.updateEmail(this.requireConnectedGeneration(), 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 });
+    await this.updateEmail(this.requireConnectedGeneration(), emailId, { 'keywords/$seen': true });
+  }
+
+  /** Convenience: removes the $seen keyword via an Email/set keywords patch. */
+  public async markUnseen(emailId: string): Promise<void> {
+    await this.updateEmail(this.requireConnectedGeneration(), emailId, { 'keywords/$seen': null });
+  }
+
+  /** Convenience: adds or removes the $flagged keyword. */
+  public async setFlagged(emailId: string, flagged: boolean): Promise<void> {
+    await this.updateEmail(this.requireConnectedGeneration(), emailId, {
+      'keywords/$flagged': flagged ? true : null,
+    });
+  }
+
+  /**
+   * Replaces the email's mailbox membership. Pass one mailbox id for a
+   * provider-style move, or multiple ids when the remote JMAP account
+   * supports multi-mailbox membership.
+   */
+  public async setMailboxes(emailId: string, mailboxIds: string[]): Promise<void> {
+    const generation = this.requireConnectedGeneration();
+    const uniqueMailboxIds = [...new Set(mailboxIds.filter(Boolean))];
+    if (!uniqueMailboxIds.length) {
+      throw new Error('setMailboxes requires at least one mailbox id.');
+    }
+    await this.updateEmail(generation, emailId, {
+      mailboxIds: Object.fromEntries(uniqueMailboxIds.map((mailboxId) => [mailboxId, true])),
+    });
+  }
+
+  /** Permanently destroys an email via Email/set. */
+  public async destroyEmail(emailId: string): Promise<void> {
+    const generation = this.requireConnectedGeneration();
+    const responses = await this.requestWithGeneration(generation, [
+      ['Email/set', { accountId: generation.accountId, destroy: [emailId] }, 'd0'],
+    ]);
+    const result = responses[0][1];
+    const notDestroyed = result.notDestroyed?.[emailId];
+    if (notDestroyed) {
+      throw new JmapError(
+        `Email/set destroy of "${emailId}" failed: ${notDestroyed.type}${notDestroyed.description ? ` — ${notDestroyed.description}` : ''}`,
+        {
+          jmapErrorType: notDestroyed.type,
+          jmapErrorDescription: notDestroyed.description,
+        }
+      );
+    }
   }
 
   /**
@@ -408,8 +527,9 @@ export class JmapClient extends plugins.events.EventEmitter {
    * 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 generation = this.requireConnectedGeneration();
+    const identityResponses = await this.requestWithGeneration(generation, [
+      ['Identity/get', { accountId: generation.accountId }, 'i0'],
     ]);
     const identities: any[] = identityResponses[0][1].list ?? [];
     const identity =
@@ -422,11 +542,11 @@ export class JmapClient extends plugins.events.EventEmitter {
     const from: IJmapEmailAddress =
       outgoing.from ?? { name: identity.name ?? null, email: identity.email };
 
-    const mailboxes = await this.getMailboxes();
+    const mailboxes = await this.getMailboxesWithGeneration(generation);
     const targetMailbox =
       mailboxes.find((mb) => mb.role === 'sent') ??
       mailboxes.find((mb) => mb.role === 'drafts') ??
-      this.mailbox;
+      generation.mailbox;
     if (!targetMailbox) {
       throw new Error('No mailbox available to store the outgoing email in.');
     }
@@ -466,13 +586,21 @@ export class JmapClient extends plugins.events.EventEmitter {
     if (htmlBodyParts.length) {
       emailCreate.htmlBody = htmlBodyParts;
     }
+    if (outgoing.attachments?.length) {
+      emailCreate.attachments = outgoing.attachments.map((attachment) => ({
+        blobId: attachment.blobId,
+        type: attachment.type,
+        name: attachment.name ?? null,
+        disposition: 'attachment',
+      }));
+    }
 
-    const responses = await this.request([
-      ['Email/set', { accountId: this.accountId, create: { newEmail: emailCreate } }, 'c0'],
+    const responses = await this.requestWithGeneration(generation, [
+      ['Email/set', { accountId: generation.accountId, create: { newEmail: emailCreate } }, 'c0'],
       [
         'EmailSubmission/set',
         {
-          accountId: this.accountId,
+          accountId: generation.accountId,
           create: { newSubmission: { emailId: '#newEmail', identityId: identity.id } },
         },
         'c1',
@@ -500,6 +628,46 @@ export class JmapClient extends plugins.events.EventEmitter {
     return { emailId: createdEmail.id, submissionId: createdSubmission.id };
   }
 
+  /**
+   * Uploads raw bytes to the session's uploadUrl (RFC 8620 §6.1) and returns
+   * the stored blob's id, type, and size. Use the blobId in
+   * `sendEmail({ attachments: [...] })` or any other blob reference.
+   */
+  public async uploadBlob(
+    data: Uint8Array,
+    type: string = 'application/octet-stream'
+  ): Promise<IJmapUploadResult> {
+    const generation = this.requireConnectedGeneration();
+    const template = generation.session?.uploadUrl;
+    if (!template) {
+      throw new Error('JMAP session provides no uploadUrl — call connect() first.');
+    }
+    const expanded = template.replace('{accountId}', encodeURIComponent(generation.accountId));
+    const url = new URL(expanded, this.config.sessionUrl).toString();
+    // Re-wrap so the bytes are backed by a plain ArrayBuffer (BodyInit-safe).
+    const body =
+      data.buffer instanceof ArrayBuffer ? (data as Uint8Array<ArrayBuffer>) : new Uint8Array(data);
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        authorization: this.getAuthHeader(),
+        'content-type': type,
+        accept: 'application/json',
+      },
+      body,
+      signal: generation.abortController.signal,
+    });
+    this.assertCurrentGeneration(generation);
+    if (!response.ok) {
+      const error = await this.createHttpError(response, 'Failed to upload blob');
+      this.assertCurrentGeneration(generation);
+      throw error;
+    }
+    const result = (await response.json()) as IJmapUploadResult;
+    this.assertCurrentGeneration(generation);
+    return result;
+  }
+
   /**
    * Downloads a blob's raw bytes using the session downloadUrl template
    * (RFC 8620 §6.2: {accountId}, {blobId}, {type}, {name}).
@@ -509,29 +677,93 @@ export class JmapClient extends plugins.events.EventEmitter {
     type: string = 'application/octet-stream',
     name: string = 'blob'
   ): Promise<Uint8Array> {
-    const template = this.session?.downloadUrl;
+    const generation = this.requireConnectedGeneration();
+    const template = generation.session?.downloadUrl;
     if (!template) {
       throw new Error('JMAP session provides no downloadUrl — call connect() first.');
     }
     const expanded = template
-      .replace('{accountId}', encodeURIComponent(this.accountId))
+      .replace('{accountId}', encodeURIComponent(generation.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() },
+      signal: generation.abortController.signal,
     });
+    this.assertCurrentGeneration(generation);
     if (!response.ok) {
-      throw await this.createHttpError(response, `Failed to download blob "${blobId}"`);
+      const error = await this.createHttpError(response, `Failed to download blob "${blobId}"`);
+      this.assertCurrentGeneration(generation);
+      throw error;
     }
-    return new Uint8Array(await response.arrayBuffer());
+    const data = new Uint8Array(await response.arrayBuffer());
+    this.assertCurrentGeneration(generation);
+    return data;
   }
 
   // ======================
   // internal helpers
   // ======================
 
+  private createConnectionGeneration(): IConnectionGeneration {
+    return {
+      id: ++this.generationCounter,
+      abortController: new AbortController(),
+      session: null,
+      accountId: '',
+      apiUrl: '',
+      mailbox: null,
+      connected: false,
+      lastEmailState: null,
+      seenEmailIds: new Set(),
+      pollTimer: null,
+      sseAbortController: null,
+      fetchingDeltas: false,
+      deltaQueued: false,
+    };
+  }
+
+  private isCurrentGeneration(generation: IConnectionGeneration): boolean {
+    return (
+      this.connectionGeneration === generation &&
+      !generation.abortController.signal.aborted
+    );
+  }
+
+  private assertCurrentGeneration(generation: IConnectionGeneration): void {
+    if (this.isCurrentGeneration(generation)) return;
+    const reason = generation.abortController.signal.reason;
+    throw reason instanceof Error
+      ? reason
+      : new Error(`JMAP connection generation ${generation.id} is no longer active.`);
+  }
+
+  private requireConnectedGeneration(): IConnectionGeneration {
+    const generation = this.connectionGeneration;
+    if (!generation || !generation.connected) {
+      throw new Error('JmapClient is not connected yet — call connect() first.');
+    }
+    this.assertCurrentGeneration(generation);
+    return generation;
+  }
+
+  private teardownGeneration(generation: IConnectionGeneration, reason: unknown): void {
+    if (!generation.abortController.signal.aborted) {
+      generation.abortController.abort(reason);
+    }
+    if (generation.sseAbortController) {
+      generation.sseAbortController.abort(reason);
+      generation.sseAbortController = null;
+    }
+    if (generation.pollTimer) {
+      clearInterval(generation.pollTimer);
+      generation.pollTimer = null;
+    }
+    generation.deltaQueued = false;
+  }
+
   private getAuthHeader(): string {
     const auth = this.config.auth as Partial<IJmapClientAuthBearer & IJmapClientAuthBasic>;
     if (typeof auth.accessToken === 'string') {
@@ -558,9 +790,9 @@ export class JmapClient extends plugins.events.EventEmitter {
     );
   }
 
-  private async resolveMailbox(): Promise<IJmapMailbox> {
-    const responses = await this.request([
-      ['Mailbox/get', { accountId: this.accountId, ids: null }, 'mb0'],
+  private async resolveMailbox(generation: IConnectionGeneration): Promise<IJmapMailbox> {
+    const responses = await this.requestWithGeneration(generation, [
+      ['Mailbox/get', { accountId: generation.accountId, ids: null }, 'mb0'],
     ]);
     const list = (responses[0][1].list ?? []) as IJmapMailbox[];
     const wanted = this.config.mailbox ?? 'INBOX';
@@ -574,19 +806,22 @@ export class JmapClient extends plugins.events.EventEmitter {
     return mailbox;
   }
 
-  private async fetchEmailState(): Promise<string> {
-    const responses = await this.request([
-      ['Email/get', { accountId: this.accountId, ids: [] }, 'st0'],
+  private async fetchEmailState(generation: IConnectionGeneration): Promise<string> {
+    const responses = await this.requestWithGeneration(generation, [
+      ['Email/get', { accountId: generation.accountId, ids: [] }, 'st0'],
     ]);
     return String(responses[0][1].state ?? '');
   }
 
-  private async getEmailObjects(ids: string[]): Promise<IJmapEmail[]> {
-    const responses = await this.request([
+  private async getEmailObjects(
+    generation: IConnectionGeneration,
+    ids: string[]
+  ): Promise<IJmapEmail[]> {
+    const responses = await this.requestWithGeneration(generation, [
       [
         'Email/get',
         {
-          accountId: this.accountId,
+          accountId: generation.accountId,
           ids,
           properties: EMAIL_PROPERTIES,
           fetchAllBodyValues: true,
@@ -597,9 +832,13 @@ export class JmapClient extends plugins.events.EventEmitter {
     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'],
+  private async updateEmail(
+    generation: IConnectionGeneration,
+    emailId: string,
+    patch: Record<string, any>
+  ): Promise<void> {
+    const responses = await this.requestWithGeneration(generation, [
+      ['Email/set', { accountId: generation.accountId, update: { [emailId]: patch } }, 'u0'],
     ]);
     const result = responses[0][1];
     const notUpdated = result.notUpdated?.[emailId];
@@ -647,31 +886,33 @@ export class JmapClient extends plugins.events.EventEmitter {
     };
   }
 
-  private emitMessage(message: ISmartJmapMessage): void {
-    if (this.seenEmailIds.has(message.id)) {
+  private emitMessage(
+    generation: IConnectionGeneration,
+    message: ISmartJmapMessage
+  ): void {
+    if (!this.isCurrentGeneration(generation) || generation.seenEmailIds.has(message.id)) {
       return;
     }
-    this.seenEmailIds.add(message.id);
+    generation.seenEmailIds.add(message.id);
     this.emit('message', message);
   }
 
-  private async emitInitialEmails(): Promise<void> {
-    const messages = await this.queryEmails();
+  private async emitInitialEmails(generation: IConnectionGeneration): Promise<void> {
+    const messages = await this.queryEmailsWithGeneration(generation);
+    this.assertCurrentGeneration(generation);
     // queryEmails sorts newest first; emit oldest first for natural ordering
     for (const message of messages.reverse()) {
-      this.emitMessage(message);
+      this.emitMessage(generation, message);
     }
   }
 
-  private startWatching(): void {
-    if (this.stopped) {
-      return;
-    }
-    const eventSourceUrl = this.session?.eventSourceUrl;
+  private startWatching(generation: IConnectionGeneration): void {
+    if (!this.isCurrentGeneration(generation)) return;
+    const eventSourceUrl = generation.session?.eventSourceUrl;
     if (eventSourceUrl) {
-      this.startEventStream(eventSourceUrl);
+      this.startEventStream(generation, eventSourceUrl);
     } else {
-      this.startPolling();
+      this.startPolling(generation);
     }
   }
 
@@ -681,7 +922,11 @@ export class JmapClient extends plugins.events.EventEmitter {
    * EventSource because JMAP requires an Authorization header, which the
    * WHATWG EventSource API cannot send.
    */
-  private startEventStream(templateUrl: string): void {
+  private startEventStream(
+    generation: IConnectionGeneration,
+    templateUrl: string
+  ): void {
+    if (!this.isCurrentGeneration(generation)) return;
     const expanded = templateUrl
       .replace('{types}', '*')
       .replace('{closeafter}', 'no')
@@ -689,29 +934,41 @@ export class JmapClient extends plugins.events.EventEmitter {
     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();
+    if (generation.sseAbortController) {
+      generation.sseAbortController.abort(
+        new Error('JMAP event stream was superseded.')
+      );
     }
     const abortController = new AbortController();
-    this.sseAbortController = abortController;
-    void this.runEventStream(url, abortController);
+    generation.sseAbortController = abortController;
+    void this.runEventStream(generation, url, abortController);
   }
 
-  private async runEventStream(url: string, abortController: AbortController): Promise<void> {
+  private async runEventStream(
+    generation: IConnectionGeneration,
+    url: string,
+    abortController: AbortController
+  ): Promise<void> {
     try {
+      const signal = AbortSignal.any([
+        generation.abortController.signal,
+        abortController.signal,
+      ]);
       const response = await fetch(url, {
         headers: {
           authorization: this.getAuthHeader(),
           accept: 'text/event-stream',
         },
-        signal: abortController.signal,
+        signal,
       });
+      this.assertCurrentGeneration(generation);
+      if (abortController.signal.aborted) return;
       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();
+      void this.fetchDeltas(generation);
 
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
@@ -720,6 +977,8 @@ export class JmapClient extends plugins.events.EventEmitter {
       let dataLines: string[] = [];
       while (true) {
         const { done, value } = await reader.read();
+        this.assertCurrentGeneration(generation);
+        if (abortController.signal.aborted) return;
         if (done) {
           break;
         }
@@ -730,7 +989,7 @@ export class JmapClient extends plugins.events.EventEmitter {
           buffer = buffer.slice(newlineIndex + 1);
           if (line === '') {
             if (dataLines.length) {
-              this.handleEventStreamEvent(eventName, dataLines.join('\n'));
+              this.handleEventStreamEvent(generation, eventName, dataLines.join('\n'));
             }
             eventName = 'message';
             dataLines = [];
@@ -746,28 +1005,37 @@ export class JmapClient extends plugins.events.EventEmitter {
       }
       // 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;
+      if (this.isCurrentGeneration(generation) && !abortController.signal.aborted) {
+        if (generation.sseAbortController === abortController) {
+          generation.sseAbortController = null;
         }
-        this.startPolling();
+        this.startPolling(generation);
       }
     } catch (error) {
-      if (this.stopped || abortController.signal.aborted) {
+      if (
+        !this.isCurrentGeneration(generation) ||
+        generation.abortController.signal.aborted ||
+        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;
+      abortController.abort(error);
+      if (generation.sseAbortController === abortController) {
+        generation.sseAbortController = null;
       }
-      this.startPolling();
+      this.startPolling(generation);
     }
   }
 
-  private handleEventStreamEvent(eventName: string, data: string): void {
+  private handleEventStreamEvent(
+    generation: IConnectionGeneration,
+    eventName: string,
+    data: string
+  ): void {
+    if (!this.isCurrentGeneration(generation)) return;
     let parsed: any;
     try {
       parsed = JSON.parse(data);
@@ -777,72 +1045,73 @@ export class JmapClient extends plugins.events.EventEmitter {
     if (eventName !== 'state' && parsed?.['@type'] !== 'StateChange') {
       return;
     }
-    const changed = parsed?.changed?.[this.accountId];
+    const changed = parsed?.changed?.[generation.accountId];
     const emailState = changed?.Email;
-    if (typeof emailState === 'string' && emailState !== this.lastEmailState) {
-      void this.fetchDeltas();
+    if (typeof emailState === 'string' && emailState !== generation.lastEmailState) {
+      void this.fetchDeltas(generation);
     }
   }
 
-  private startPolling(): void {
-    if (this.pollTimer || this.stopped) {
+  private startPolling(generation: IConnectionGeneration): void {
+    if (generation.pollTimer || !this.isCurrentGeneration(generation)) {
       return;
     }
     const interval = this.config.pollIntervalMs ?? 30000;
-    this.pollTimer = setInterval(() => {
-      void this.fetchDeltas();
+    generation.pollTimer = setInterval(() => {
+      void this.fetchDeltas(generation);
     }, interval);
   }
 
-  private async fetchDeltas(): Promise<void> {
-    if (this.stopped) {
+  private async fetchDeltas(generation: IConnectionGeneration): Promise<void> {
+    if (!this.isCurrentGeneration(generation)) return;
+    if (generation.fetchingDeltas) {
+      generation.deltaQueued = true;
       return;
     }
-    if (this.fetchingDeltas) {
-      this.deltaQueued = true;
-      return;
-    }
-    this.fetchingDeltas = true;
+    generation.fetchingDeltas = true;
     try {
       do {
-        this.deltaQueued = false;
-        await this.fetchDeltasOnce();
-      } while (this.deltaQueued && !this.stopped);
+        generation.deltaQueued = false;
+        await this.fetchDeltasOnce(generation);
+      } while (generation.deltaQueued && this.isCurrentGeneration(generation));
     } finally {
-      this.fetchingDeltas = false;
+      generation.fetchingDeltas = false;
     }
   }
 
-  private async fetchDeltasOnce(): Promise<void> {
+  private async fetchDeltasOnce(generation: IConnectionGeneration): 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'],
+      while (hasMore && this.isCurrentGeneration(generation)) {
+        const sinceState = generation.lastEmailState;
+        const responses = await this.requestWithGeneration(generation, [
+          ['Email/changes', { accountId: generation.accountId, sinceState }, 'ch0'],
         ]);
+        this.assertCurrentGeneration(generation);
         const changes = responses[0][1];
-        this.lastEmailState = String(changes.newState ?? sinceState);
-        hasMore = changes.hasMoreChanges === true && this.lastEmailState !== sinceState;
+        generation.lastEmailState = String(changes.newState ?? sinceState);
+        hasMore =
+          changes.hasMoreChanges === true && generation.lastEmailState !== sinceState;
         const createdIds: string[] = changes.created ?? [];
         if (createdIds.length) {
-          const emails = await this.getEmailObjects(createdIds);
+          const emails = await this.getEmailObjects(generation, createdIds);
+          this.assertCurrentGeneration(generation);
           for (const email of emails) {
-            if (this.mailbox && email.mailboxIds?.[this.mailbox.id]) {
-              this.emitMessage(this.toMessage(email));
+            if (generation.mailbox && email.mailboxIds?.[generation.mailbox.id]) {
+              this.emitMessage(generation, this.toMessage(email));
             }
           }
         }
       }
     } catch (error) {
-      if (this.stopped) {
-        return;
-      }
+      if (!this.isCurrentGeneration(generation)) return;
       if ((error as JmapError)?.jmapErrorType === 'cannotCalculateChanges') {
         try {
-          await this.resyncViaQuery();
+          await this.resyncViaQuery(generation);
         } catch (resyncError) {
-          this.emit('error', resyncError);
+          if (this.isCurrentGeneration(generation)) {
+            this.emit('error', resyncError);
+          }
         }
       } else {
         this.emit('error', error);
@@ -851,22 +1120,14 @@ export class JmapClient extends plugins.events.EventEmitter {
   }
 
   /** Full resync fallback when the server cannot calculate changes. */
-  private async resyncViaQuery(): Promise<void> {
-    this.lastEmailState = await this.fetchEmailState();
-    const messages = await this.queryEmails();
+  private async resyncViaQuery(generation: IConnectionGeneration): Promise<void> {
+    const state = await this.fetchEmailState(generation);
+    this.assertCurrentGeneration(generation);
+    generation.lastEmailState = state;
+    const messages = await this.queryEmailsWithGeneration(generation);
+    this.assertCurrentGeneration(generation);
     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;
+      this.emitMessage(generation, message);
     }
   }
 }