@gera2ld/imap 0.0.1

package/README.md

@@ -0,0 +1,273 @@
+# IMAP Client
+
+A lightweight IMAP client for Node.js that supports real-time email monitoring using IDLE mode.
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { ImapClient } from '@gera2ld/imap';
+
+const client = new ImapClient({
+  host: 'imap.example.com',
+  port: 993,
+  secure: true,
+  user: 'your-email@example.com',
+  password: 'your-password',
+});
+
+// Connect and authenticate
+await client.connect();
+
+// Select a mailbox
+await client.selectMailbox('INBOX');
+
+// Perform operations like fetching messages
+const messages = await client.fetchMessages('1:*', ['UID', 'ENVELOPE']);
+console.log(messages);
+
+// Disconnect
+await client.disconnect();
+```
+
+### Watching for New Mails and Deletions Using IDLE Mode
+
+```typescript
+import { ImapClient } from '@gera2ld/imap';
+
+async function watchEmails() {
+  const client = new ImapClient({
+    host: 'imap.example.com',
+    port: 993,
+    secure: true,
+    user: 'your-email@example.com',
+    password: 'your-password',
+  });
+
+  try {
+    // Connect and authenticate
+    await client.connect();
+    
+    // Select the mailbox to watch (e.g., INBOX)
+    await client.selectMailbox('INBOX');
+    
+    // Listen for new emails
+    client.on('newmail', (info) => {
+      console.log(`New mail received! Total messages in mailbox: ${info.count}`);
+      // Handle new email notification
+    });
+    
+    // Listen for message deletions
+    client.on('expunge', (info) => {
+      console.log(`Message deleted! Sequence number: ${info.seq}`);
+      // Handle message deletion
+    });
+    
+    // Listen for other changes
+    client.on('fetch', (message) => {
+      console.log(`Message ${message.seq} updated with attributes:`, message.attributes);
+    });
+    
+    // Start listening for real-time updates using IDLE mode
+    await client.startIdle();
+    console.log('Now listening for new emails and deletions...');
+    
+    // Keep the program running to continue listening
+    // Set up graceful shutdown
+    const handleShutdown = async () => {
+      console.log('Shutting down gracefully...');
+      try {
+        // Stop listening for updates
+        await client.stopIdle();
+        // Disconnect from the server
+        await client.disconnect();
+        console.log('Disconnected from IMAP server');
+        process.exit(0);
+      } catch (err) {
+        console.error('Error during shutdown:', err);
+        process.exit(1);
+      }
+    };
+
+    // Listen for termination signals
+    process.on('SIGINT', handleShutdown);
+    process.on('SIGTERM', handleShutdown);
+
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+// Run the example
+watchEmails();
+```
+
+## Authentication
+
+The client supports multiple authentication methods:
+
+### Password Authentication
+```typescript
+const client = new ImapClient({
+  host: 'imap.example.com',
+  port: 993,
+  secure: true,
+  user: 'your-email@example.com',
+  password: 'your-password',
+});
+```
+
+### XOAUTH2 Authentication
+```typescript
+const client = new ImapClient({
+  host: 'imap.example.com',
+  port: 993,
+  secure: true,
+  user: 'your-email@example.com',
+  accessToken: 'your-oauth-token',
+});
+
+// Or with a function that returns a token
+const client = new ImapClient({
+  host: 'imap.example.com',
+  port: 993,
+  secure: true,
+  user: 'your-email@example.com',
+  accessToken: async () => {
+    // Return a fresh access token
+    return await getFreshAccessToken();
+  },
+});
+```
+
+## Available Events
+
+- `newmail`: Emitted when new messages arrive in the mailbox
+- `expunge`: Emitted when messages are deleted from the mailbox
+- `fetch`: Emitted when message attributes are updated
+- `recent`: Emitted when the number of recent messages changes
+- `flags`: Emitted when message flags change
+- `list`: Emitted when mailbox list information is received
+- `response`: Emitted for raw IMAP responses
+- `error`: Emitted when an error occurs
+- `close`: Emitted when the connection is closed
+
+## API
+
+### ImapClient(options)
+
+Creates a new IMAP client instance.
+
+#### Options
+
+- `host` (string): The IMAP server hostname
+- `port` (number): The IMAP server port (typically 143 for non-secure, 993 for secure)
+- `secure` (boolean): Whether to use TLS/SSL connection
+- `user` (string): The username/email address
+- `password` (string, optional): The password for authentication
+- `accessToken` (string | function, optional): Access token for XOAUTH2 authentication
+
+### connect()
+
+Connects to the IMAP server and performs authentication.
+
+### disconnect()
+
+Disconnects from the IMAP server and cleans up resources.
+
+### selectMailbox(mailbox)
+
+Selects a mailbox for subsequent operations.
+
+### listMailboxes()
+
+Lists all mailboxes on the server.
+
+### fetchMessages(sequence, [items], [options])
+
+Fetches messages from the currently selected mailbox.
+- `items` (optional): The message data items to fetch (e.g., ['UID', 'ENVELOPE', 'BODY.PEEK[]']). Defaults to ['UID', 'ENVELOPE', 'FLAGS']
+- `options` (optional): Additional options for the fetch operation
+  - `uid` (boolean, default: true): Whether to use UID-based fetch
+
+### searchMessages(criteria, [options])
+
+Searches messages in the currently selected mailbox based on the given criteria.
+- `options` (optional): Additional options for the search operation
+  - `uid` (boolean, default: true): Whether to use UID-based search
+
+### setFlags(sequence, operation, flags, [options])
+
+Sets flags on messages in the currently selected mailbox.
+- `operation`: The flag operation ('+' to add flags, '-' to remove flags, '=' to replace all flags)
+- `flags`: Array of flags to operate on (e.g., ['\\Seen', '\\Flagged'])
+- `options` (optional): Additional options for the operation
+  - `uid` (boolean, default: true): Whether to use UID-based operation
+
+### markAsSeen(sequence, [options])
+
+Marks messages as seen in the currently selected mailbox.
+- `options` (optional): Additional options for the operation
+  - `uid` (boolean, default: true): Whether to use UID-based operation
+
+### markAsUnseen(sequence, [options])
+
+Marks messages as unseen in the currently selected mailbox.
+- `options` (optional): Additional options for the operation
+  - `uid` (boolean, default: true): Whether to use UID-based operation
+
+### deleteMessages(sequence, [options])
+
+Deletes messages in the currently selected mailbox.
+- `options` (optional): Additional options for the operation
+  - `uid` (boolean, default: true): Whether to use UID-based operation
+
+### moveMessages(sequence, destinationMailbox, [options])
+
+Moves messages to a different mailbox.
+- `options` (optional): Additional options for the operation
+  - `uid` (boolean, default: true): Whether to use UID-based operation
+
+### startIdle()
+
+Manually starts IDLE mode for real-time updates.
+
+### stopIdle()
+
+Manually stops IDLE mode.
+
+## Utilities
+
+The package also exports utility functions for working with IMAP:
+
+### formatDateForImap(date)
+
+Formats a Date object to the IMAP date format used in SEARCH commands (e.g., SINCE, ON).
+The format is "DD-MMM-YYYY" (e.g., "01-Jan-2023").
+
+```typescript
+import { formatDateForImap } from '@gera2ld/imap';
+
+const date = new Date('2023-01-15');
+const imapDate = formatDateForImap(date); // "15-Jan-2023"
+
+// Use in search commands
+await client.searchMessages(`SINCE ${imapDate}`);
+```
+
+### formatDateTimeForImap(date)
+
+Formats a Date object to the IMAP datetime format used in SEARCH commands.
+The format is "DD-MMM-YYYY HH:MM:SS +ZZZZ" (e.g., "01-Jan-2023 12:00:00 +0000").
+
+```typescript
+import { formatDateTimeForImap } from '@gera2ld/imap';
+
+const date = new Date('2023-01-15T14:30:00Z');
+const imapDateTime = formatDateTimeForImap(date); // "15-Jan-2023 14:30:00 +0000"
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,129 @@
+import { EventEmitter } from 'node:events';
+import type { ParsedResponse } from './parser';
+import type { FetchMessage, ImapClientOptions, MailboxInfo } from './types';
+type ImapClientEvents = {
+    newmail: [{
+        count: number;
+    }];
+    expunge: [{
+        seq: number;
+    }];
+    recent: [{
+        count: number;
+    }];
+    flags: [{
+        flags: any[];
+    }];
+    response: [ParsedResponse];
+    send: [string];
+    error: [Error];
+    close: [];
+};
+export declare class ImapClient extends EventEmitter<ImapClientEvents> {
+    private options;
+    private connector;
+    private parser;
+    private tagCounter;
+    private tagPrefix;
+    private pendingCommand;
+    constructor(options: ImapClientOptions);
+    private nextTag;
+    /**
+     * Register a pending command and return a promise that resolves when the response arrives.
+     * Throws if another command is already pending.
+     */
+    private registerPendingCommand;
+    /**
+     * Send a raw command to the server.
+     */
+    private sendCommand;
+    /**
+     * Execute a command and wait for its response.
+     * Processes matching untagged responses as they arrive via onResponse, filters out nulls.
+     * Non-matching responses are emitted as events.
+     *
+     * @param command - The IMAP command to send (e.g., 'LIST "" "*"', 'UID SEARCH ALL')
+     * @param matchCommand - Optional command name to match in responses (e.g., 'LIST', 'SEARCH', 'FETCH'). Required when onResponse is provided.
+     * @param onResponse - Optional function to transform each matching untagged response as it arrives. Return null to skip.
+     * @returns Promise with tagged response and array of transformed items
+     */
+    private executeCommand;
+    /**
+     * Handle incoming data lines from the connector.
+     */
+    private handleResponse;
+    private handleAsyncNotification;
+    private parseFetchAttributes;
+    /**
+     * Connect to the IMAP server and authenticate.
+     */
+    connect(): Promise<void>;
+    private processResponses;
+    /**
+     * Authenticate with the server.
+     */
+    login(): Promise<void>;
+    /**
+     * List all mailboxes.
+     */
+    listMailboxes(): Promise<MailboxInfo[]>;
+    /**
+     * Select a mailbox.
+     */
+    selectMailbox(mailbox: string): Promise<void>;
+    /**
+     * Search messages.
+     */
+    searchMessages(criteria: string, options?: Partial<{
+        uid: boolean;
+    }>): Promise<number[]>;
+    /**
+     * Fetch messages.
+     */
+    fetchMessages(sequence: string, items?: string[], options?: Partial<{
+        uid: boolean;
+    }>): Promise<FetchMessage[]>;
+    /**
+     * Set flags on messages.
+     */
+    setFlags(sequence: string, operation: '+' | '-' | '=', flags: string[], options?: Partial<{
+        uid: boolean;
+    }>): Promise<void>;
+    /**
+     * Mark messages as seen.
+     */
+    markAsSeen(sequence: string, options?: Partial<{
+        uid: boolean;
+    }>): Promise<void>;
+    /**
+     * Mark messages as unseen.
+     */
+    markAsUnseen(sequence: string, options?: Partial<{
+        uid: boolean;
+    }>): Promise<void>;
+    /**
+     * Delete messages.
+     */
+    deleteMessages(sequence: string, options?: Partial<{
+        uid: boolean;
+    }>): Promise<void>;
+    /**
+     * Move messages to another mailbox.
+     */
+    moveMessages(sequence: string, destinationMailbox: string, options?: Partial<{
+        uid: boolean;
+    }>): Promise<void>;
+    /**
+     * Start IDLE mode.
+     */
+    startIdle(): Promise<void>;
+    /**
+     * Stop IDLE mode.
+     */
+    stopIdle(): Promise<void>;
+    /**
+     * Disconnect from the server.
+     */
+    disconnect(): Promise<void>;
+}
+export {};

package/dist/connector.d.ts

@@ -0,0 +1,20 @@
+import { BufferReader } from '@gera2ld/common';
+export interface ConnectorOptions {
+    host: string;
+    port: number;
+    secure: boolean;
+}
+export interface ConnectorCallbacks {
+    onError?: (err: Error) => void;
+    onClose?: () => void;
+}
+export declare class Connector {
+    private options;
+    private _socket;
+    reader: BufferReader;
+    isConnected: boolean;
+    constructor(options: ConnectorOptions);
+    connect(callbacks?: ConnectorCallbacks): Promise<void>;
+    write(data: string): void;
+    disconnect(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './client';
+export * from './parser';
+export * from './util';

package/dist/index.js

@@ -0,0 +1,642 @@
+import { EventEmitter as S } from "node:events";
+import * as T from "node:net";
+import * as $ from "node:tls";
+const b = "=", w = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+let g;
+function I() {
+  return g ||= O(w), g;
+}
+function O(r) {
+  const t = new Array(255);
+  for (let e = 0; e < r.length; e += 1)
+    t[r.charCodeAt(e)] = e;
+  return t;
+}
+function M(r, t) {
+  const e = t[r];
+  if (e == null) throw new Error("Unable to parse base64 string.");
+  return e;
+}
+function D(r, t, e) {
+  let s = "", n = 0;
+  for (; n < r.length; ) {
+    const o = r[n++], i = r[n++], a = r[n++];
+    if (s += t[o >> 2], s += t[(o & 3) << 4 | (i || 0) >> 4], i == null ? s += b : s += t[(i & 15) << 2 | (a || 0) >> 6], a == null) {
+      s += b;
+      break;
+    }
+    s += t[a & 63];
+  }
+  return s;
+}
+function v(r, t) {
+  let e = r.length;
+  for (; e > 0 && r[e - 1] === "="; ) e -= 1;
+  const s = Math.ceil(e / 4), n = new Uint8Array(3 * s);
+  let o = 0, i = 0, a = 0;
+  for (i = 0; i < s; i += 1) {
+    let l = 0;
+    for (a = 0; a < 4; a += 1) {
+      o = i * 4 + a;
+      const f = r[o];
+      if (!f || f === b) break;
+      l |= M(r.charCodeAt(o), t) << (3 - a) * 6;
+    }
+    n[i * 3] = l >> 16, n[i * 3 + 1] = l >> 8 & 255, n[i * 3 + 2] = l & 255;
+  }
+  if (o < e - 1 || a === 1) throw new Error("Invalid base64 string");
+  let c = 3 * s;
+  for (; a < 4; a += 1) c -= 1;
+  return n.subarray(0, c);
+}
+function U(r) {
+  return D(r, w);
+}
+function y(r) {
+  return v(r, I());
+}
+function N(r) {
+  return new TextEncoder().encode(r);
+}
+function E(r) {
+  return new TextDecoder().decode(r);
+}
+function m() {
+  const r = {
+    status: "pending"
+  };
+  return r.promise = new Promise((t, e) => {
+    r.resolve = t, r.reject = e;
+  }), r.promise.then(
+    () => {
+      r.status = "resolved";
+    },
+    () => {
+      r.status = "rejected";
+    }
+  ), r;
+}
+const F = new Uint8Array([13, 10]);
+class L {
+  buffer = new Uint8Array(0);
+  requests = [];
+  isClosed = !1;
+  read(t = 8192) {
+    const e = m();
+    return this.requests.push({
+      deferred: e,
+      handle: () => {
+        const s = Math.min(t, this.buffer.length), n = this.buffer.subarray(0, s);
+        return this.buffer = this.buffer.subarray(s), e.resolve(n), !0;
+      }
+    }), this.processBuffer(), e.promise;
+  }
+  readExact(t) {
+    const e = m();
+    return this.requests.push({
+      deferred: e,
+      handle: () => {
+        if (t > this.buffer.length) return !1;
+        const s = this.buffer.subarray(0, t);
+        return this.buffer = this.buffer.subarray(t), e.resolve(s), !0;
+      }
+    }), this.processBuffer(), e.promise;
+  }
+  readUntil(t = F) {
+    typeof t == "string" && (t = N(t));
+    const e = m();
+    return this.requests.push({
+      deferred: e,
+      handle: () => {
+        const s = P(this.buffer, t);
+        if (s < 0) return !1;
+        const n = s + t.length, o = this.buffer.subarray(0, n);
+        return this.buffer = this.buffer.subarray(n), e.resolve(o), !0;
+      }
+    }), this.processBuffer(), e.promise;
+  }
+  feed(t) {
+    if (this.isClosed) throw new Error("Buffer is closed");
+    this.buffer = B(this.buffer, t), this.processBuffer();
+  }
+  close() {
+    this.isClosed = !0, this.processBuffer();
+  }
+  processBuffer() {
+    for (; this.requests.length; ) {
+      const t = this.requests[0];
+      if (!t.handle())
+        if (this.isClosed)
+          t.deferred.reject(new Error("Buffer is closed"));
+        else break;
+      this.requests.shift();
+    }
+  }
+}
+function B(r, t) {
+  const e = new Uint8Array(r.length + t.length);
+  return e.set(r, 0), e.set(t, r.length), e;
+}
+function P(r, t) {
+  if (!t.length) return 0;
+  for (let e = 0; e <= r.length - t.length; e += 1) {
+    let s;
+    for (s = 0; s < t.length && r[e + s] === t[s]; s += 1)
+      ;
+    if (s === t.length) return e;
+  }
+  return -1;
+}
+class R {
+  options;
+  _socket = null;
+  reader = new L();
+  isConnected = !1;
+  constructor(t) {
+    this.options = t;
+  }
+  async connect(t) {
+    return new Promise((e, s) => {
+      const n = this.options.secure ? $.connect({
+        host: this.options.host,
+        port: this.options.port,
+        rejectUnauthorized: !1
+      }) : T.connect({
+        host: this.options.host,
+        port: this.options.port
+      });
+      this._socket = n, n.on("data", (o) => {
+        this.reader.feed(o);
+      }), n.on("connect", () => {
+        this.isConnected = !0, e();
+      }), n.on("error", (o) => {
+        t?.onError?.(o), s(o);
+      }), n.on("close", () => {
+        this.isConnected = !1, t?.onClose?.();
+      });
+    });
+  }
+  write(t) {
+    if (!this._socket)
+      throw new Error("Not connected");
+    this._socket.write(t);
+  }
+  disconnect() {
+    this._socket && (this._socket.end(), this._socket.destroy(), this._socket = null);
+  }
+}
+class j {
+  decode(t) {
+    return new TextDecoder().decode(t);
+  }
+  async *parse(t) {
+    for (; ; ) {
+      const e = await t.readUntil();
+      if (e.length === 0) break;
+      const s = this.decode(e);
+      if (s.startsWith("+ "))
+        yield {
+          symbol: "+",
+          text: s.slice(2)
+        };
+      else {
+        const n = s.split(" ");
+        let o = "", i, a;
+        s.startsWith("* ") ? (o = "*", n.shift(), isNaN(+n[0]) ? a = n.shift() : a = n.splice(1, 1)[0]) : (i = n.shift(), a = n.shift());
+        let c = n.join(" ");
+        const l = {
+          command: a,
+          stack: [[]],
+          brackets: []
+        };
+        for (; c; ) {
+          this.parseAttributes(l, c);
+          const f = l.stack.at(-1), h = f.at(-1), p = typeof h == "string" && h.match(/^\{(\d+)\}\r\n$/);
+          if (p) {
+            const x = +p[1], A = this.decode(await t.readExact(x));
+            f.pop(), f.push(A);
+          }
+          if (!l.brackets.length) break;
+          c = this.decode(await t.readUntil());
+        }
+        yield o ? {
+          symbol: o,
+          command: a,
+          attributes: l.stack[0]
+        } : {
+          symbol: "",
+          tag: i,
+          command: a,
+          attributes: l.stack[0]
+        };
+      }
+    }
+  }
+  parseAttributes(t, e) {
+    let s = !1, n = !0, o = !1, i = "";
+    const a = () => {
+      if (!i) return;
+      let c;
+      isNaN(+i) ? i.toLowerCase() === "nil" ? c = null : c = i : c = +i, t.stack.at(-1).push(c), i = "";
+    };
+    for (let c = 0; c < e.length; c += 1) {
+      const l = e[c];
+      if (s)
+        l === '"' ? (s = !1, a()) : (l === "\\" && (c += 1), i += e[c]);
+      else if (l === '"')
+        s = !0;
+      else if (l === " ")
+        a();
+      else if ((n ? "([" : "(").includes(l)) {
+        t.brackets.push(l);
+        const f = [];
+        t.stack.at(-1).push(f), t.stack.push(f), l === "[" && (o = !0);
+      } else if ((o ? "])" : ")").includes(l)) {
+        const f = t.brackets.pop();
+        if (!["()", "[]"].includes(f + l))
+          throw new Error("Invalid bracket");
+        a(), t.stack.pop(), l === "]" && (o = !1);
+      } else
+        i += e[c];
+      n = !1;
+    }
+    a();
+  }
+}
+const k = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec"
+];
+function H(r) {
+  const t = String(r.getDate()).padStart(2, "0"), e = k[r.getMonth()], s = r.getFullYear();
+  return `${t}-${e}-${s}`;
+}
+function z(r) {
+  const t = String(r.getDate()).padStart(2, "0"), e = k[r.getMonth()], s = r.getFullYear(), n = String(r.getHours()).padStart(2, "0"), o = String(r.getMinutes()).padStart(2, "0"), i = String(r.getSeconds()).padStart(2, "0"), a = -r.getTimezoneOffset(), c = a >= 0 ? "+" : "-", l = Math.abs(a), f = String(Math.floor(l / 60)).padStart(
+    2,
+    "0"
+  ), h = String(l % 60).padStart(2, "0"), p = `${c}${f}${h}`;
+  return `${t}-${e}-${s} ${n}:${o}:${i} ${p}`;
+}
+function d(r) {
+  return !Array.isArray(r) || r.length < 4 ? {} : {
+    name: C(r[0] ?? "") || void 0,
+    adl: r[1] ?? void 0,
+    mailbox: r[2] ?? void 0,
+    host: r[3] ?? void 0
+  };
+}
+function C(r) {
+  return r.split(/\s+/).map((t) => {
+    if (t.startsWith("=?") && t.endsWith("?=")) {
+      const [e, s, n] = t.slice(2, -2).split("?");
+      if (e.toLowerCase() !== "utf-8")
+        throw new Error(`Charset is not supported: ${e}`);
+      let o;
+      if (s === "B")
+        o = y(n);
+      else {
+        const i = [];
+        for (let a = 0; a < n.length; a += 1)
+          if (n[a] === "=") {
+            const c = n.slice(a + 1, a + 3);
+            i.push(parseInt(c, 16)), a += 2;
+          } else
+            i.push(n.charCodeAt(a));
+        o = new Uint8Array(i);
+      }
+      return E(o);
+    }
+    return t;
+  }).join("");
+}
+const u = { uid: !0 };
+function _(r, t) {
+  const e = `user=${r}
auth=Bearer ${t}

`;
+  return U(new TextEncoder().encode(e));
+}
+class G extends S {
+  options;
+  connector;
+  parser;
+  tagCounter = 0;
+  tagPrefix = "A";
+  pendingCommand = null;
+  constructor(t) {
+    super(), this.options = t, this.parser = new j(), this.connector = new R({
+      host: t.host,
+      port: t.port,
+      secure: t.secure
+    });
+  }
+  nextTag() {
+    return this.tagPrefix + this.tagCounter++;
+  }
+  /**
+   * Register a pending command and return a promise that resolves when the response arrives.
+   * Throws if another command is already pending.
+   */
+  registerPendingCommand(t, e, s) {
+    if (this.pendingCommand)
+      throw new Error(
+        `Cannot execute ${e} command while another operation ("${this.pendingCommand.command}") is in progress.`
+      );
+    const n = m();
+    return this.pendingCommand = {
+      tag: t,
+      command: e,
+      callback: s,
+      deferred: n
+    }, n.promise.finally(() => {
+      this.pendingCommand = null;
+    }), n.promise;
+  }
+  /**
+   * Send a raw command to the server.
+   */
+  sendCommand(t) {
+    this.emit("send", t), this.connector.write(`${t}\r
+`);
+  }
+  /**
+   * Execute a command and wait for its response.
+   * Processes matching untagged responses as they arrive via onResponse, filters out nulls.
+   * Non-matching responses are emitted as events.
+   *
+   * @param command - The IMAP command to send (e.g., 'LIST "" "*"', 'UID SEARCH ALL')
+   * @param matchCommand - Optional command name to match in responses (e.g., 'LIST', 'SEARCH', 'FETCH'). Required when onResponse is provided.
+   * @param onResponse - Optional function to transform each matching untagged response as it arrives. Return null to skip.
+   * @returns Promise with tagged response and array of transformed items
+   */
+  async executeCommand(t, e) {
+    const s = this.nextTag(), n = t.split(" ");
+    let o = n.shift();
+    if (o === "UID" && (o = n.shift()), !o) throw new Error("Invalid command");
+    const i = this.registerPendingCommand(s, o, e);
+    this.sendCommand(`${s} ${t}`), await i;
+  }
+  /**
+   * Handle incoming data lines from the connector.
+   */
+  handleResponse(t) {
+    this.emit("response", t);
+    const e = this.pendingCommand, s = () => {
+      t.symbol === "*" && this.handleAsyncNotification(t);
+    };
+    if (e) {
+      const n = () => {
+        t.symbol === "" && t.tag === e.tag ? t.command === "OK" ? e.deferred.resolve() : e.deferred.reject(new Error(t.command)) : s();
+      };
+      e.callback ? e.callback({
+        response: t,
+        pending: e,
+        next: s,
+        fallback: n
+      }) : n();
+    } else
+      s();
+  }
+  handleAsyncNotification(t) {
+    switch (t.command) {
+      case "EXISTS":
+        this.emit("newmail", { count: t.attributes[0] });
+        break;
+      case "EXPUNGE":
+        this.emit("expunge", { seq: t.attributes[0] });
+        break;
+      case "RECENT":
+        this.emit("recent", { count: t.attributes[0] });
+        break;
+      case "FLAGS":
+        this.emit("flags", { flags: t.attributes[0] });
+        break;
+    }
+  }
+  parseFetchAttributes(t, e) {
+    const s = { seq: t };
+    if (Array.isArray(e))
+      for (let n = 0; n < e.length; n += 2) {
+        const o = e[n]?.toUpperCase(), i = e[n + 1];
+        switch (o) {
+          case "UID":
+            s.uid = i;
+            break;
+          case "FLAGS":
+            s.flags = Array.isArray(i) ? i : [i];
+            break;
+          case "ENVELOPE":
+            s.envelope = {
+              date: i?.[0],
+              subject: C(i?.[1]),
+              from: i?.[2]?.map(d) ?? [],
+              sender: i?.[3]?.map(d) ?? [],
+              replyTo: i?.[4]?.map(d) ?? [],
+              to: i?.[5]?.map(d) ?? [],
+              cc: i?.[6]?.map(d) ?? [],
+              bcc: i?.[7]?.map(d) ?? [],
+              inReplyTo: i?.[8],
+              messageId: i?.[9]
+            };
+            break;
+          case "INTERNALDATE":
+            s.internalDate = i;
+            break;
+          case "RFC822.SIZE":
+            s.size = i;
+            break;
+          case "BODY[]":
+            s.body = i;
+            break;
+          case "RFC822.TEXT":
+          case "BODY[TEXT]":
+            s.text = i;
+            break;
+          case "BODY[HTML]":
+            s.html = i;
+            break;
+          default:
+            s.attributes ||= {}, s.attributes[o] = i;
+            break;
+        }
+      }
+    return s;
+  }
+  /**
+   * Connect to the IMAP server and authenticate.
+   */
+  async connect() {
+    await this.connector.connect({
+      onError: (t) => this.emit("error", t),
+      onClose: () => this.emit("close")
+    }), this.processResponses(), await this.registerPendingCommand("", "", ({ response: t, pending: e, next: s }) => {
+      t.symbol === "*" && t.command === "OK" ? e.deferred.resolve() : s();
+    }), await this.login();
+  }
+  async processResponses() {
+    for await (const t of this.parser.parse(this.connector.reader))
+      this.handleResponse(t);
+  }
+  /**
+   * Authenticate with the server.
+   */
+  async login() {
+    if (this.options.accessToken) {
+      const t = typeof this.options.accessToken == "function" ? await this.options.accessToken() : this.options.accessToken, e = _(this.options.user, t);
+      await this.executeCommand(
+        `AUTHENTICATE XOAUTH2 ${e}`,
+        ({ response: s, pending: n, fallback: o }) => {
+          s.symbol === "+" ? n.deferred.reject(
+            new Error(E(y(s.text)))
+          ) : o();
+        }
+      );
+    } else if (this.options.password)
+      await this.executeCommand(
+        `LOGIN "${this.options.user}" "${this.options.password}"`
+      );
+    else
+      throw new Error("Either password or accessToken must be provided");
+  }
+  /**
+   * List all mailboxes.
+   */
+  async listMailboxes() {
+    const t = [];
+    return await this.executeCommand('LIST "" "*"', ({ response: e, fallback: s }) => {
+      if (e.symbol === "*" && e.command === "LIST") {
+        const n = {
+          attributes: e.attributes[0],
+          delimiter: e.attributes[1],
+          name: e.attributes[2]
+        };
+        t.push(n);
+      } else
+        s();
+    }), t;
+  }
+  /**
+   * Select a mailbox.
+   */
+  async selectMailbox(t) {
+    await this.executeCommand(`SELECT "${t}"`);
+  }
+  /**
+   * Search messages.
+   */
+  async searchMessages(t, e) {
+    const n = { ...u, ...e }.uid ? "UID " : "";
+    let o = [];
+    return await this.executeCommand(
+      `${n}SEARCH ${t}`,
+      ({ response: i, fallback: a }) => {
+        i.symbol === "*" && i.command === "SEARCH" ? o = [...o, ...i.attributes] : a();
+      }
+    ), o;
+  }
+  /**
+   * Fetch messages.
+   */
+  async fetchMessages(t, e = ["UID", "ENVELOPE", "FLAGS"], s) {
+    const i = `${{ ...u, ...s }.uid ? "UID " : ""}FETCH ${t} (${e.join(" ")})`, a = [];
+    return await this.executeCommand(i, ({ response: c, fallback: l }) => {
+      if (c.symbol === "*" && c.command === "FETCH") {
+        const f = c.attributes[0], h = c.attributes[1];
+        a.push(this.parseFetchAttributes(f, h));
+      } else
+        l();
+    }), a;
+  }
+  /**
+   * Set flags on messages.
+   */
+  async setFlags(t, e, s, n) {
+    const i = { ...u, ...n }.uid ? "UID " : "", a = s.join(" ");
+    await this.executeCommand(
+      `${i}STORE ${t} ${e}FLAGS (${a})`
+    );
+  }
+  /**
+   * Mark messages as seen.
+   */
+  async markAsSeen(t, e) {
+    const s = { ...u, ...e };
+    await this.setFlags(t, "+", ["\\Seen"], s);
+  }
+  /**
+   * Mark messages as unseen.
+   */
+  async markAsUnseen(t, e) {
+    const s = { ...u, ...e };
+    await this.setFlags(t, "-", ["\\Seen"], s);
+  }
+  /**
+   * Delete messages.
+   */
+  async deleteMessages(t, e) {
+    const s = { ...u, ...e };
+    await this.setFlags(t, "+", ["\\Deleted"], s), await this.executeCommand("EXPUNGE");
+  }
+  /**
+   * Move messages to another mailbox.
+   */
+  async moveMessages(t, e, s) {
+    const o = { ...u, ...s }.uid ? "UID " : "";
+    await this.executeCommand(
+      `${o}MOVE ${t} "${e}"`
+    );
+  }
+  /**
+   * Start IDLE mode.
+   */
+  async startIdle() {
+    const t = m();
+    let e = !1;
+    return this.executeCommand("IDLE", ({ response: s, pending: n, fallback: o }) => {
+      if (e)
+        o();
+      else if (s.symbol === "+")
+        e = !0, t.resolve();
+      else {
+        const i = new Error(s.command);
+        t.reject(i), n.deferred.resolve(t.promise);
+      }
+    }), t.promise;
+  }
+  /**
+   * Stop IDLE mode.
+   */
+  async stopIdle() {
+    if (this.pendingCommand?.command !== "IDLE")
+      throw new Error("IDLE mode is not active");
+    return this.sendCommand("DONE"), this.pendingCommand.deferred.promise;
+  }
+  /**
+   * Disconnect from the server.
+   */
+  async disconnect() {
+    if (this.pendingCommand?.command === "IDLE")
+      try {
+        await this.stopIdle();
+      } catch {
+      }
+    this.connector.disconnect();
+  }
+}
+export {
+  G as ImapClient,
+  j as ImapParser,
+  C as decodeRfc2047,
+  H as formatDateForImap,
+  z as formatDateTimeForImap,
+  d as parseAddress
+};

package/dist/parser.d.ts

@@ -0,0 +1,22 @@
+import type { BufferReader } from '@gera2ld/common';
+export interface TaggedResponse {
+    symbol: '';
+    tag: string;
+    command: string;
+    attributes: any[];
+}
+export interface UntaggedResponse {
+    symbol: '*';
+    command: string;
+    attributes: any[];
+}
+export interface ContinuationResponse {
+    symbol: '+';
+    text: string;
+}
+export type ParsedResponse = TaggedResponse | UntaggedResponse | ContinuationResponse;
+export declare class ImapParser {
+    private decode;
+    parse(reader: BufferReader): AsyncGenerator<ParsedResponse, void, unknown>;
+    private parseAttributes;
+}

package/dist/parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+export interface ImapClientOptions {
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    password?: string;
+    accessToken?: string | (() => Promise<string>);
+    debug?: boolean;
+}
+export interface Address {
+    name?: string;
+    adl?: string;
+    mailbox?: string;
+    host?: string;
+}
+export interface MessageEnvelope {
+    date?: string;
+    subject?: string;
+    from?: Address[];
+    sender?: Address[];
+    replyTo?: Address[];
+    to?: Address[];
+    cc?: Address[];
+    bcc?: Address[];
+    inReplyTo?: string;
+    messageId?: string;
+}
+export interface FetchMessage {
+    seq: number;
+    attributes?: Record<string, any>;
+    uid?: number;
+    flags?: string[];
+    envelope?: MessageEnvelope;
+    body?: any;
+    text?: string;
+    html?: string;
+    internalDate?: string;
+    size?: number;
+}
+export interface MailboxInfo {
+    attributes: string[];
+    delimiter: string;
+    name: string;
+}

package/dist/util.d.ts

@@ -0,0 +1,19 @@
+import type { Address } from './types';
+/**
+ * Formats a Date object to the IMAP date format used in SEARCH commands (e.g., SINCE, ON).
+ * The format is "DD-MMM-YYYY" (e.g., "01-Jan-2023").
+ *
+ * @param date The date to format
+ * @returns The formatted date string in IMAP format
+ */
+export declare function formatDateForImap(date: Date): string;
+/**
+ * Formats a Date object to the IMAP datetime format used in SEARCH commands.
+ * The format is "DD-MMM-YYYY HH:MM:SS +ZZZZ" (e.g., "01-Jan-2023 12:00:00 +0000").
+ *
+ * @param date The date to format
+ * @returns The formatted datetime string in IMAP format
+ */
+export declare function formatDateTimeForImap(date: Date): string;
+export declare function parseAddress(addressComponent: (string | null)[]): Address;
+export declare function decodeRfc2047(str: string): string;

package/dist/util.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@gera2ld/imap",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils.js",
+      "types": "./dist/utils.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@gera2ld/common": "^0.0.1"
+  },
+  "scripts": {
+    "clean": "del-cli dist tsconfig.tsbuildinfo",
+    "build:types": "tsc",
+    "build:js": "vite build",
+    "build": "pnpm clean && pnpm /^build:/"
+  }
+}