@agenticmail/core 0.7.4 → 0.7.5

package/dist/index.cjs

@@ -994,14 +994,79 @@ var MailReceiver = class {
       lock.release();
     }
   }
-  async deleteMessage(uid, mailbox = "INBOX") {
+  /**
+   * Permanently remove a single message via IMAP EXPUNGE.
+   *
+   * DANGEROUS — EXPUNGE is mailbox-wide. The IMAP semantics are:
+   *
+   *   1. STORE +FLAGS (\Deleted) on the target UID
+   *   2. EXPUNGE → removes EVERY message in the mailbox that has
+   *      \Deleted set, not just the one we just flagged
+   *
+   * If any other messages in the mailbox already had \Deleted
+   * (from a previous half-completed delete, an agent operation,
+   * an external client) they all vanish too. This is the IMAP
+   * spec, not an ImapFlow quirk.
+   *
+   * Callers that just want "delete this email" — i.e. the Gmail
+   * UX — should use `moveToTrash()` instead, which moves the
+   * message to the trash mailbox without touching \Deleted.
+   * Reserve `expungeMessage` for explicit "empty trash" /
+   * permanent-delete UI paths.
+   *
+   * If the server supports UIDPLUS (RFC 4315), we use UID EXPUNGE
+   * to limit the scope to the target UID — even then, callers
+   * should treat this as the destructive option.
+   */
+  async expungeMessage(uid, mailbox = "INBOX") {
     const lock = await this.client.getMailboxLock(mailbox);
     try {
+      const caps = this.client.capabilities;
+      const hasUidPlus = caps && (Array.isArray(caps) ? caps.includes("UIDPLUS") : caps.has("UIDPLUS"));
+      if (hasUidPlus) {
+        await this.client.messageFlagsAdd(String(uid), ["\\Deleted"], { uid: true });
+        const exec = this.client.exec;
+        if (typeof exec === "function") {
+          await exec.call(this.client, "UID EXPUNGE", [String(uid)]);
+          return;
+        }
+      }
       await this.client.messageDelete(String(uid), { uid: true });
     } finally {
       lock.release();
     }
   }
+  /**
+   * Move a single message to the trash mailbox.
+   *
+   * This is the Gmail / Outlook "delete" semantics — the user
+   * still sees the message under Trash and can restore it. No
+   * \Deleted flag is set, no EXPUNGE happens, so other messages
+   * in the source mailbox are untouched.
+   *
+   * `trashMailbox` is the IMAP folder name (varies by server:
+   * Stalwart uses "Deleted Items" by default; Gmail uses
+   * "[Gmail]/Trash"; etc.). Callers should pass the discovered
+   * name rather than hard-coding.
+   */
+  async moveToTrash(uid, fromMailbox, trashMailbox) {
+    if (fromMailbox === trashMailbox) {
+      throw new Error("source and trash mailbox are the same; use expungeMessage for permanent delete");
+    }
+    return this.moveMessage(uid, fromMailbox, trashMailbox);
+  }
+  /**
+   * Back-compat alias for callers that haven't migrated to the
+   * explicit moveToTrash / expungeMessage split yet. Behaviour is
+   * unchanged: this still EXPUNGES (mailbox-wide). New callers
+   * should use moveToTrash() unless they specifically want the
+   * destructive variant.
+   *
+   * @deprecated Use moveToTrash() or expungeMessage() instead.
+   */
+  async deleteMessage(uid, mailbox = "INBOX") {
+    return this.expungeMessage(uid, mailbox);
+  }
   /** Mark a message as unseen (unread) */
   async markUnseen(uid, mailbox = "INBOX") {
     const lock = await this.client.getMailboxLock(mailbox);
@@ -1030,10 +1095,34 @@ var MailReceiver = class {
     }
   }
   /** Move a message to another folder */
+  /**
+   * Move a single message from one mailbox to another.
+   *
+   * Uses the IMAP MOVE extension (RFC 6851) when the server
+   * advertises it — that command is atomic and scoped: only the
+   * named UID moves, no other mailbox state is touched.
+   *
+   * Falls back to **COPY + STORE +\Deleted on the source UID
+   * ONLY (no EXPUNGE)** when the server doesn't support MOVE.
+   * The source message is left in place with the `\Deleted`
+   * flag; it disappears on the next expunge from a permanent-
+   * delete action. This is intentional: a mailbox-wide EXPUNGE
+   * here would wipe every previously-`\Deleted` message in the
+   * source mailbox as a side effect, which was the bug that
+   * cleared a user's inbox in 0.8.32. Leaving the flag set is
+   * the safe fallback.
+   */
   async moveMessage(uid, fromMailbox, toMailbox) {
     const lock = await this.client.getMailboxLock(fromMailbox);
     try {
-      await this.client.messageMove(String(uid), toMailbox, { uid: true });
+      const caps = this.client.capabilities;
+      const hasMove = caps && (Array.isArray(caps) ? caps.includes("MOVE") : caps.has("MOVE"));
+      if (hasMove) {
+        await this.client.messageMove(String(uid), toMailbox, { uid: true });
+        return;
+      }
+      await this.client.messageCopy(String(uid), toMailbox, { uid: true });
+      await this.client.messageFlagsAdd(String(uid), ["\\Deleted"], { uid: true });
     } finally {
       lock.release();
     }
@@ -1098,12 +1187,28 @@ var MailReceiver = class {
       lock.release();
     }
   }
-  /** Batch move multiple messages to another folder */
+  /**
+   * Batch move multiple messages to another folder.
+   *
+   * Same safety model as `moveMessage`: prefers the IMAP MOVE
+   * extension (atomic, scoped per UID); falls back to
+   * COPY + STORE \Deleted with NO mailbox-wide EXPUNGE so an
+   * existing `\Deleted` flag on an unrelated message can't
+   * be amplified into a full inbox wipe.
+   */
   async batchMove(uids, fromMailbox, toMailbox) {
     if (uids.length === 0) return;
+    const range = uids.join(",");
     const lock = await this.client.getMailboxLock(fromMailbox);
     try {
-      await this.client.messageMove(uids.join(","), toMailbox, { uid: true });
+      const caps = this.client.capabilities;
+      const hasMove = caps && (Array.isArray(caps) ? caps.includes("MOVE") : caps.has("MOVE"));
+      if (hasMove) {
+        await this.client.messageMove(range, toMailbox, { uid: true });
+        return;
+      }
+      await this.client.messageCopy(range, toMailbox, { uid: true });
+      await this.client.messageFlagsAdd(range, ["\\Deleted"], { uid: true });
     } finally {
       lock.release();
     }

package/dist/index.d.cts

@@ -470,6 +470,54 @@ declare class MailReceiver {
     fetchMessage(uid: number, mailbox?: string): Promise<Buffer>;
     search(criteria: SearchCriteria, mailbox?: string): Promise<number[]>;
     markSeen(uid: number, mailbox?: string): Promise<void>;
+    /**
+     * Permanently remove a single message via IMAP EXPUNGE.
+     *
+     * DANGEROUS — EXPUNGE is mailbox-wide. The IMAP semantics are:
+     *
+     *   1. STORE +FLAGS (\Deleted) on the target UID
+     *   2. EXPUNGE → removes EVERY message in the mailbox that has
+     *      \Deleted set, not just the one we just flagged
+     *
+     * If any other messages in the mailbox already had \Deleted
+     * (from a previous half-completed delete, an agent operation,
+     * an external client) they all vanish too. This is the IMAP
+     * spec, not an ImapFlow quirk.
+     *
+     * Callers that just want "delete this email" — i.e. the Gmail
+     * UX — should use `moveToTrash()` instead, which moves the
+     * message to the trash mailbox without touching \Deleted.
+     * Reserve `expungeMessage` for explicit "empty trash" /
+     * permanent-delete UI paths.
+     *
+     * If the server supports UIDPLUS (RFC 4315), we use UID EXPUNGE
+     * to limit the scope to the target UID — even then, callers
+     * should treat this as the destructive option.
+     */
+    expungeMessage(uid: number, mailbox?: string): Promise<void>;
+    /**
+     * Move a single message to the trash mailbox.
+     *
+     * This is the Gmail / Outlook "delete" semantics — the user
+     * still sees the message under Trash and can restore it. No
+     * \Deleted flag is set, no EXPUNGE happens, so other messages
+     * in the source mailbox are untouched.
+     *
+     * `trashMailbox` is the IMAP folder name (varies by server:
+     * Stalwart uses "Deleted Items" by default; Gmail uses
+     * "[Gmail]/Trash"; etc.). Callers should pass the discovered
+     * name rather than hard-coding.
+     */
+    moveToTrash(uid: number, fromMailbox: string, trashMailbox: string): Promise<void>;
+    /**
+     * Back-compat alias for callers that haven't migrated to the
+     * explicit moveToTrash / expungeMessage split yet. Behaviour is
+     * unchanged: this still EXPUNGES (mailbox-wide). New callers
+     * should use moveToTrash() unless they specifically want the
+     * destructive variant.
+     *
+     * @deprecated Use moveToTrash() or expungeMessage() instead.
+     */
     deleteMessage(uid: number, mailbox?: string): Promise<void>;
     /** Mark a message as unseen (unread) */
     markUnseen(uid: number, mailbox?: string): Promise<void>;
@@ -481,6 +529,23 @@ declare class MailReceiver {
      */
     setStarred(uid: number, starred: boolean, mailbox?: string): Promise<void>;
     /** Move a message to another folder */
+    /**
+     * Move a single message from one mailbox to another.
+     *
+     * Uses the IMAP MOVE extension (RFC 6851) when the server
+     * advertises it — that command is atomic and scoped: only the
+     * named UID moves, no other mailbox state is touched.
+     *
+     * Falls back to **COPY + STORE +\Deleted on the source UID
+     * ONLY (no EXPUNGE)** when the server doesn't support MOVE.
+     * The source message is left in place with the `\Deleted`
+     * flag; it disappears on the next expunge from a permanent-
+     * delete action. This is intentional: a mailbox-wide EXPUNGE
+     * here would wipe every previously-`\Deleted` message in the
+     * source mailbox as a side effect, which was the bug that
+     * cleared a user's inbox in 0.8.32. Leaving the flag set is
+     * the safe fallback.
+     */
     moveMessage(uid: number, fromMailbox: string, toMailbox: string): Promise<void>;
     /** List all IMAP folders/mailboxes */
     listFolders(): Promise<FolderInfo[]>;
@@ -494,7 +559,15 @@ declare class MailReceiver {
     batchDelete(uids: number[], mailbox?: string): Promise<void>;
     /** Batch fetch raw message content for multiple UIDs */
     batchFetch(uids: number[], mailbox?: string): Promise<Map<number, Buffer>>;
-    /** Batch move multiple messages to another folder */
+    /**
+     * Batch move multiple messages to another folder.
+     *
+     * Same safety model as `moveMessage`: prefers the IMAP MOVE
+     * extension (atomic, scoped per UID); falls back to
+     * COPY + STORE \Deleted with NO mailbox-wide EXPUNGE so an
+     * existing `\Deleted` flag on an unrelated message can't
+     * be amplified into a full inbox wipe.
+     */
     batchMove(uids: number[], fromMailbox: string, toMailbox: string): Promise<void>;
     /** Append a raw RFC822 message to a mailbox (e.g. "Sent") with given flags */
     appendMessage(raw: Buffer, mailbox: string, flags?: string[]): Promise<void>;

package/dist/index.d.ts

@@ -470,6 +470,54 @@ declare class MailReceiver {
     fetchMessage(uid: number, mailbox?: string): Promise<Buffer>;
     search(criteria: SearchCriteria, mailbox?: string): Promise<number[]>;
     markSeen(uid: number, mailbox?: string): Promise<void>;
+    /**
+     * Permanently remove a single message via IMAP EXPUNGE.
+     *
+     * DANGEROUS — EXPUNGE is mailbox-wide. The IMAP semantics are:
+     *
+     *   1. STORE +FLAGS (\Deleted) on the target UID
+     *   2. EXPUNGE → removes EVERY message in the mailbox that has
+     *      \Deleted set, not just the one we just flagged
+     *
+     * If any other messages in the mailbox already had \Deleted
+     * (from a previous half-completed delete, an agent operation,
+     * an external client) they all vanish too. This is the IMAP
+     * spec, not an ImapFlow quirk.
+     *
+     * Callers that just want "delete this email" — i.e. the Gmail
+     * UX — should use `moveToTrash()` instead, which moves the
+     * message to the trash mailbox without touching \Deleted.
+     * Reserve `expungeMessage` for explicit "empty trash" /
+     * permanent-delete UI paths.
+     *
+     * If the server supports UIDPLUS (RFC 4315), we use UID EXPUNGE
+     * to limit the scope to the target UID — even then, callers
+     * should treat this as the destructive option.
+     */
+    expungeMessage(uid: number, mailbox?: string): Promise<void>;
+    /**
+     * Move a single message to the trash mailbox.
+     *
+     * This is the Gmail / Outlook "delete" semantics — the user
+     * still sees the message under Trash and can restore it. No
+     * \Deleted flag is set, no EXPUNGE happens, so other messages
+     * in the source mailbox are untouched.
+     *
+     * `trashMailbox` is the IMAP folder name (varies by server:
+     * Stalwart uses "Deleted Items" by default; Gmail uses
+     * "[Gmail]/Trash"; etc.). Callers should pass the discovered
+     * name rather than hard-coding.
+     */
+    moveToTrash(uid: number, fromMailbox: string, trashMailbox: string): Promise<void>;
+    /**
+     * Back-compat alias for callers that haven't migrated to the
+     * explicit moveToTrash / expungeMessage split yet. Behaviour is
+     * unchanged: this still EXPUNGES (mailbox-wide). New callers
+     * should use moveToTrash() unless they specifically want the
+     * destructive variant.
+     *
+     * @deprecated Use moveToTrash() or expungeMessage() instead.
+     */
     deleteMessage(uid: number, mailbox?: string): Promise<void>;
     /** Mark a message as unseen (unread) */
     markUnseen(uid: number, mailbox?: string): Promise<void>;
@@ -481,6 +529,23 @@ declare class MailReceiver {
      */
     setStarred(uid: number, starred: boolean, mailbox?: string): Promise<void>;
     /** Move a message to another folder */
+    /**
+     * Move a single message from one mailbox to another.
+     *
+     * Uses the IMAP MOVE extension (RFC 6851) when the server
+     * advertises it — that command is atomic and scoped: only the
+     * named UID moves, no other mailbox state is touched.
+     *
+     * Falls back to **COPY + STORE +\Deleted on the source UID
+     * ONLY (no EXPUNGE)** when the server doesn't support MOVE.
+     * The source message is left in place with the `\Deleted`
+     * flag; it disappears on the next expunge from a permanent-
+     * delete action. This is intentional: a mailbox-wide EXPUNGE
+     * here would wipe every previously-`\Deleted` message in the
+     * source mailbox as a side effect, which was the bug that
+     * cleared a user's inbox in 0.8.32. Leaving the flag set is
+     * the safe fallback.
+     */
     moveMessage(uid: number, fromMailbox: string, toMailbox: string): Promise<void>;
     /** List all IMAP folders/mailboxes */
     listFolders(): Promise<FolderInfo[]>;
@@ -494,7 +559,15 @@ declare class MailReceiver {
     batchDelete(uids: number[], mailbox?: string): Promise<void>;
     /** Batch fetch raw message content for multiple UIDs */
     batchFetch(uids: number[], mailbox?: string): Promise<Map<number, Buffer>>;
-    /** Batch move multiple messages to another folder */
+    /**
+     * Batch move multiple messages to another folder.
+     *
+     * Same safety model as `moveMessage`: prefers the IMAP MOVE
+     * extension (atomic, scoped per UID); falls back to
+     * COPY + STORE \Deleted with NO mailbox-wide EXPUNGE so an
+     * existing `\Deleted` flag on an unrelated message can't
+     * be amplified into a full inbox wipe.
+     */
     batchMove(uids: number[], fromMailbox: string, toMailbox: string): Promise<void>;
     /** Append a raw RFC822 message to a mailbox (e.g. "Sent") with given flags */
     appendMessage(raw: Buffer, mailbox: string, flags?: string[]): Promise<void>;

package/dist/index.js

@@ -240,14 +240,79 @@ var MailReceiver = class {
       lock.release();
     }
   }
-  async deleteMessage(uid, mailbox = "INBOX") {
+  /**
+   * Permanently remove a single message via IMAP EXPUNGE.
+   *
+   * DANGEROUS — EXPUNGE is mailbox-wide. The IMAP semantics are:
+   *
+   *   1. STORE +FLAGS (\Deleted) on the target UID
+   *   2. EXPUNGE → removes EVERY message in the mailbox that has
+   *      \Deleted set, not just the one we just flagged
+   *
+   * If any other messages in the mailbox already had \Deleted
+   * (from a previous half-completed delete, an agent operation,
+   * an external client) they all vanish too. This is the IMAP
+   * spec, not an ImapFlow quirk.
+   *
+   * Callers that just want "delete this email" — i.e. the Gmail
+   * UX — should use `moveToTrash()` instead, which moves the
+   * message to the trash mailbox without touching \Deleted.
+   * Reserve `expungeMessage` for explicit "empty trash" /
+   * permanent-delete UI paths.
+   *
+   * If the server supports UIDPLUS (RFC 4315), we use UID EXPUNGE
+   * to limit the scope to the target UID — even then, callers
+   * should treat this as the destructive option.
+   */
+  async expungeMessage(uid, mailbox = "INBOX") {
     const lock = await this.client.getMailboxLock(mailbox);
     try {
+      const caps = this.client.capabilities;
+      const hasUidPlus = caps && (Array.isArray(caps) ? caps.includes("UIDPLUS") : caps.has("UIDPLUS"));
+      if (hasUidPlus) {
+        await this.client.messageFlagsAdd(String(uid), ["\\Deleted"], { uid: true });
+        const exec = this.client.exec;
+        if (typeof exec === "function") {
+          await exec.call(this.client, "UID EXPUNGE", [String(uid)]);
+          return;
+        }
+      }
       await this.client.messageDelete(String(uid), { uid: true });
     } finally {
       lock.release();
     }
   }
+  /**
+   * Move a single message to the trash mailbox.
+   *
+   * This is the Gmail / Outlook "delete" semantics — the user
+   * still sees the message under Trash and can restore it. No
+   * \Deleted flag is set, no EXPUNGE happens, so other messages
+   * in the source mailbox are untouched.
+   *
+   * `trashMailbox` is the IMAP folder name (varies by server:
+   * Stalwart uses "Deleted Items" by default; Gmail uses
+   * "[Gmail]/Trash"; etc.). Callers should pass the discovered
+   * name rather than hard-coding.
+   */
+  async moveToTrash(uid, fromMailbox, trashMailbox) {
+    if (fromMailbox === trashMailbox) {
+      throw new Error("source and trash mailbox are the same; use expungeMessage for permanent delete");
+    }
+    return this.moveMessage(uid, fromMailbox, trashMailbox);
+  }
+  /**
+   * Back-compat alias for callers that haven't migrated to the
+   * explicit moveToTrash / expungeMessage split yet. Behaviour is
+   * unchanged: this still EXPUNGES (mailbox-wide). New callers
+   * should use moveToTrash() unless they specifically want the
+   * destructive variant.
+   *
+   * @deprecated Use moveToTrash() or expungeMessage() instead.
+   */
+  async deleteMessage(uid, mailbox = "INBOX") {
+    return this.expungeMessage(uid, mailbox);
+  }
   /** Mark a message as unseen (unread) */
   async markUnseen(uid, mailbox = "INBOX") {
     const lock = await this.client.getMailboxLock(mailbox);
@@ -276,10 +341,34 @@ var MailReceiver = class {
     }
   }
   /** Move a message to another folder */
+  /**
+   * Move a single message from one mailbox to another.
+   *
+   * Uses the IMAP MOVE extension (RFC 6851) when the server
+   * advertises it — that command is atomic and scoped: only the
+   * named UID moves, no other mailbox state is touched.
+   *
+   * Falls back to **COPY + STORE +\Deleted on the source UID
+   * ONLY (no EXPUNGE)** when the server doesn't support MOVE.
+   * The source message is left in place with the `\Deleted`
+   * flag; it disappears on the next expunge from a permanent-
+   * delete action. This is intentional: a mailbox-wide EXPUNGE
+   * here would wipe every previously-`\Deleted` message in the
+   * source mailbox as a side effect, which was the bug that
+   * cleared a user's inbox in 0.8.32. Leaving the flag set is
+   * the safe fallback.
+   */
   async moveMessage(uid, fromMailbox, toMailbox) {
     const lock = await this.client.getMailboxLock(fromMailbox);
     try {
-      await this.client.messageMove(String(uid), toMailbox, { uid: true });
+      const caps = this.client.capabilities;
+      const hasMove = caps && (Array.isArray(caps) ? caps.includes("MOVE") : caps.has("MOVE"));
+      if (hasMove) {
+        await this.client.messageMove(String(uid), toMailbox, { uid: true });
+        return;
+      }
+      await this.client.messageCopy(String(uid), toMailbox, { uid: true });
+      await this.client.messageFlagsAdd(String(uid), ["\\Deleted"], { uid: true });
     } finally {
       lock.release();
     }
@@ -344,12 +433,28 @@ var MailReceiver = class {
       lock.release();
     }
   }
-  /** Batch move multiple messages to another folder */
+  /**
+   * Batch move multiple messages to another folder.
+   *
+   * Same safety model as `moveMessage`: prefers the IMAP MOVE
+   * extension (atomic, scoped per UID); falls back to
+   * COPY + STORE \Deleted with NO mailbox-wide EXPUNGE so an
+   * existing `\Deleted` flag on an unrelated message can't
+   * be amplified into a full inbox wipe.
+   */
   async batchMove(uids, fromMailbox, toMailbox) {
     if (uids.length === 0) return;
+    const range = uids.join(",");
     const lock = await this.client.getMailboxLock(fromMailbox);
     try {
-      await this.client.messageMove(uids.join(","), toMailbox, { uid: true });
+      const caps = this.client.capabilities;
+      const hasMove = caps && (Array.isArray(caps) ? caps.includes("MOVE") : caps.has("MOVE"));
+      if (hasMove) {
+        await this.client.messageMove(range, toMailbox, { uid: true });
+        return;
+      }
+      await this.client.messageCopy(range, toMailbox, { uid: true });
+      await this.client.messageFlagsAdd(range, ["\\Deleted"], { uid: true });
     } finally {
       lock.release();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/core",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Core SDK for AgenticMail — email, SMS, and phone number access for AI agents",
   "type": "module",
   "main": "dist/index.js",