@tribe-x/imapsync 0.0.1

package/.env

@@ -0,0 +1,12 @@
+# SOURCE_EMAIL=vendormaster.usa@gmail.com
+# SOURCE_PASSWORD=lwqc ryhs kfyw wxsh
+# DEST_EMAIL=thajmoha@tribe-x.org
+# DEST_PASSWORD=yummygummy
+# LOG_LEVEL=debug
+
+
+SOURCE_EMAIL=tmhajmoha@gmail.com
+SOURCE_PASSWORD=tiuw qsno slup svqh
+DEST_EMAIL=thajmoha@tribe-x.org
+DEST_PASSWORD=yummygummy
+LOG_LEVEL=debug

package/.env.example

@@ -0,0 +1,18 @@
+# source config
+SOURCE_HOST=imap.gmail.com 
+SOURCE_PORT=993
+SOURCE_EMAIL=src@gmail.com
+# provide one of the following for authentication:
+SOURCE_PASSWORD=xxxx xxxx xxxx xxxx
+SOURCE_ACCESS_TOKEN=xx
+
+# destination config
+DEST_HOST=imap.tribe-x.org 
+DEST_PORT=993 
+DEST_EMAIL=dest@example.com
+# provide one of the following for authentication:
+DEST_PASSWORD=password
+DEST_ACCESS_TOKEN=xx
+
+# logging
+LOG_LEVEL=debug

package/.idea/imapsync.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/temp" />
+      <excludeFolder url="file://$MODULE_DIR$/tmp" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/imapsync.iml" filepath="$PROJECT_DIR$/.idea/imapsync.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

package/.vscode/launch.json

@@ -0,0 +1,29 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Launch Program",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/src/bin/runMigration.js"
+        },
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Debug Jest Tests",
+            "program": "${workspaceFolder}/node_modules/jest/bin/jest",
+            "args": [
+                "--runInBand",
+                "--watchAll=false"
+            ],
+            "console": "integratedTerminal",
+            "internalConsoleOptions": "neverOpen"
+        }
+    ]
+}

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2025 Tribe-x
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# IMAPSYNC
+
+A Node.js library for migrating emails between IMAP servers. Includes a developer-friendly CLI for testing and local development. Inspired by IMAPSYNC https://imapsync.lamiral.info/
+
+
+## Installation
+`npm install`
+
+## Running the migration (for development)
+### Set up environment variables
+Copy the example environment file and adjust values for your local setup:
+
+```bash
+cp .env.example .env
+```
+### Run the migration script or cli
+
+```bash
+node src/scripts/runMigrations.js
+```
+OR
+```bash
+npm run migrate
+```
+which is equivelent to 
+
+```bash
+node src/bin/cli.js
+```
+
+## Testing
+- to run unittests using jest
+```bash
+npm test
+```
+
+
+## Supported Migration Paths
+
+| Source | Destination | Status | Notes |
+|--------|------------|--------|-------|
+| Gmail  | Iroco      | ⚠️ WIP | Supports Mailbox |
+
+
+## Credentials & Requirements
+
+Before performing a migration, you need to provide the following information for both the **source** and **destination** accounts:
+
+- **Email address** – identifies the account on the IMAP server.
+
+- **Access Token** - OAuth2 access token, if using OAuth2 authentication.
+
+- **Password or app password** – Password for regular authentication.
+
+The requirements vary slightly depending on the email provider:
+
+| Provider | Required Input                          | Notes |
+|----------|----------------------------------------|-------|
+| Gmail    | Email + (OAuth Access Toekn OR App Password)                     | regular password does not work for Gmail. You can either use OAuth access token (recommended by Google) or App Password with 2FA [Learn how to generate an App Password](https://support.google.com/accounts/answer/185833?hl=en) |
+| Iroco    | Email + Password                         | Regular account password is used for IMAP access. |

package/babel.config.cjs

@@ -0,0 +1,5 @@
+module.exports = {
+    presets: [
+        ['@babel/preset-env', { targets: { node: 'current' } }]
+    ],
+};

package/jest.config.js

@@ -0,0 +1,11 @@
+export default {
+    transform: {
+        '^.+\\.js$': 'babel-jest'
+    },
+    // Allow transforming ESM packages in node_modules
+    transformIgnorePatterns: [
+        '/node_modules/(?!(@tribe-x/imap-server)/)'
+    ],
+    maxWorkers: 1,
+    testEnvironment: 'node'
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@tribe-x/imapsync",
+  "version": "0.0.1",
+  "description": "Imapsync command and library to synchronize 2 imap accounts",
+  "main": "src/index.js",
+  "type": "module",
+  "directories": {
+    "test": "test"
+  },
+  "scripts": {
+    "test": "jest",
+    "start": "node src/index.js",
+    "migrate": "node src/bin/cli.js"
+  },
+  "bin": {
+    "imapsync": "src/bin/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/Tribe-X/imapsync"
+  },
+  "keywords": [
+    "imap",
+    "migration",
+    "CLI",
+    "library"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "tribe-x",
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^7.8.6",
+    "@tribe-x/imap-server": "^0.0.25",
+    "imapflow": "^1.0.191",
+    "mailparser": "^3.7.4",
+    "prisma": "^6.12.0",
+    "winston": "^3.17.0",
+    "yargs": "^18.0.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.4",
+    "@babel/preset-env": "^7.28.3",
+    "@jest/globals": "^30.1.2",
+    "babel-jest": "^30.1.2",
+    "dotenv": "^17.2.2",
+    "jest": "^30.1.3"
+  }
+}

package/src/bin/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import { input, password, select } from '@inquirer/prompts';
+import { ImapSyncManager } from '../imap/migrate.js';
+
+(async () => {
+    // Source
+    const sourceHost = await input({
+        message: 'Enter source IMAP host:',
+        initial: 'imap.gmail.com'
+    });
+    const sourcePort = await number({
+        message: 'Enter source IMAP port:',
+        initial: 993
+    });
+    const sourceUser = await input({ message: 'Enter source email:' });
+
+
+    const sourceAuthMethod = await select({
+        message: 'Choose authentication method for source:',
+        choices: ['Password', 'Access Token']
+    });
+
+    let sourcePassword, sourceAccessToken;
+    if (sourceAuthMethod === 'Access Token') {
+        sourceAccessToken = await password({ message: 'Enter source access token:' });
+    } else {
+        sourcePassword = await password({ message: 'Enter source password:' });
+    }
+
+    // Destination
+    const destHost = await input({
+        message: 'Enter destination IMAP host:',
+        initial: 'imap.tribe-x.org'
+    });
+
+    const destPort = await number({
+        message: 'Enter destination IMAP port:',
+        initial: 993
+    });
+    const destUser = await input({ message: 'Enter destination email:' });
+
+    const destAuthMethod = await select({
+        message: 'Choose authentication method for destination:',
+        choices: ['Password', 'Access Token']
+    });
+
+    let destPassword, destAccessToken;
+    if (destAuthMethod === 'Access Token') {
+        destAccessToken = await password({ message: 'Enter destination access token:' });
+    } else {
+        destPassword = await password({ message: 'Enter destination password:' });
+    }
+
+
+    const manager = new ImapSyncManager(
+        {
+            host: sourceHost,
+            port: sourcePort,
+            secure: true,
+            user: sourceUser,
+            ...(sourceAccessToken ? { accessToken: sourceAccessToken } : { password: sourcePassword })
+        },
+        {
+            host: destHost,
+            port: destPort,
+            secure: true,
+            user: destUser,
+            ...(destAccessToken ? { accessToken: destAccessToken } : { password: destPassword })
+        }
+    );
+
+    try {
+        await manager.init();
+        await manager.runFullMigration();
+        console.log('✅ Migration complete!');
+    } catch (err) {
+        console.error('❌ Migration failed:', err.message);
+        process.exit(1);
+    }
+})();

package/src/imap/client.js

@@ -0,0 +1,38 @@
+import { ImapFlow } from 'imapflow';
+
+/**
+ * Creates a connection to an IMAP server
+ * @param {Object} config
+ * @param {string} config.host
+ * @param {number} config.port
+ * @param {boolean} config.secure
+ * @param {string} config.user
+ * @param {string} [config.password] - Optional if using OAuth
+ * @param {string} [config.accessToken] - Optional if using OAuth
+ * @returns {Promise<ImapFlow>}
+ */
+export async function connectToImap(config) {
+    const auth = { user: config.user };
+
+    if (config.accessToken) {
+        // OAuth2 authentication
+        auth.accessToken = config.accessToken;
+    } else if (config.password) {
+        // Password authentication
+        auth.pass = config.password;
+    } else {
+        throw new Error('Either password or accessToken must be provided');
+    }
+
+
+    const client = new ImapFlow({
+        host: config.host,
+        port: config.port,
+        secure: config.secure,
+        auth,
+        keepalive: { interval: 60 * 1000, idleInterval: 10 * 1000, forceNoop: true }
+    });
+
+    await client.connect();
+    return client;
+}

package/src/imap/imapSyncManager.js

@@ -0,0 +1,260 @@
+import { Metrics } from "./metrics.js";
+import pLimit from "p-limit";
+import logger from "../utils/logger.js";
+import Quota from "./model/Quota.js";
+import { ensurePath } from "../lib/pathUtils.js";
+import { fingerprintMessage } from "../lib/fingerprint.js";
+import Mailbox from "./model/Mailbox.js";
+import { ClientType } from "./model/ClientType.js";
+import { ImapWrapper } from "./imapWrapper.js";
+
+const BATCH_SIZE = 100;
+const CONCURRENCY = 10;
+const ALWAYS_SKIP = [
+    '\\All', // avoids duplicates
+];
+
+export class ImapSyncManager {
+    constructor(sourceConfig, destinationConfig, options = {}) {
+        this.source = new ImapWrapper(sourceConfig, "source");
+        this.destination = new ImapWrapper(destinationConfig, "destination");
+        this.metrics = new Metrics();
+        this.batchSize = options.batchSize || BATCH_SIZE;
+        this.concurrency = options.concurrency || CONCURRENCY;
+        this.limit = pLimit(this.concurrency);
+        this.alwaysSkip = new Set(options.alwaysSkip || ALWAYS_SKIP);
+    }
+
+    async init() {
+        await this.source.setupClient();
+        await this.destination.setupClient();
+    }
+
+    async getAccountQuota(clientType) {
+        const client = this.#getClient(clientType);
+
+        try {
+            const quota = await client.getQuota();
+            if (!quota || !quota.storage) {
+                logger.error(`No quota info available for  ${clientType}`);
+                return null;
+            }
+            const { usage, limit, status } = quota.storage;
+
+            return new Quota(usage, limit, status)
+        } catch (err) {
+            logger.error(`Failed to fetch quota for  ${err.message}`);
+            return null;
+        }
+    }
+
+    async listMailboxes(clientType) {
+        const client = this.#getClient(clientType);
+        const boxes = await client.list();
+
+        const mailboxPromises = boxes.map(box =>
+            this.limit(() => this.#toMailbox(clientType, box))
+        );
+        return Promise.all(mailboxPromises);
+    }
+
+    async listTreeMailboxes(clientType) {
+        const mailboxes = await this.listMailboxes(clientType)
+
+        function buildTree(flatList) {
+            const pathMap = new Map();
+            const tree = [];
+
+            for (const box of flatList) {
+                pathMap.set(box.path, box);
+            }
+
+            for (const box of pathMap.values()) {
+                if (box.parentPath && pathMap.has(box.parentPath)) {
+                    pathMap.get(box.parentPath).children.push(box);
+                } else {
+                    tree.push(box);
+                }
+            }
+
+            return tree;
+        }
+
+        return buildTree(mailboxes);
+    }
+
+
+    async migrateMailbox(mailboxOrPath) {
+        const boxPath =
+            typeof mailboxOrPath === "string"
+                ? mailboxOrPath
+                : mailboxOrPath?.path;
+
+        if (!boxPath) {
+            throw new Error("Invalid argument: mailboxOrPath must be a string or a Mailbox object with a path");
+        }
+
+        const destMailboxes = await this.#listSelectableMailboxes('destination');
+        const destPaths = new Set(destMailboxes.map(m => m.path));
+        await ensurePath(
+            boxPath,
+            '/',
+            destPaths,
+            async (p) => { await this.destination.client.mailboxCreate(p) }
+        );
+
+        await this.source.client.mailboxOpen(boxPath);
+        await this.destination.client.mailboxOpen(boxPath);
+
+        const sourceUids = await this.source.client.search({ all: true });
+        const destUids = await this.destination.client.search({ all: true });
+
+
+        const destFingerprints = new Set();
+        for (const msg of await this.destination.fetch(destUids, { headers: true, source: true })) {
+            const fp = await fingerprintMessage(msg);
+            destFingerprints.add(fp);
+        }
+
+        // process source mails in batches
+        for (let i = 0; i < sourceUids.length; i += this.batchSize) {
+            const batch = sourceUids.slice(i, i + this.batchSize);
+            logger.info(`[source] Fetching batch ${i / this.batchSize + 1} (${batch.length} messages)`);
+
+            const messages = await this.source.fetch(batch, {
+                headers: true,
+                source: true,
+                flags: true,
+                internalDate: true
+            });
+
+            // append with concurrency
+            await Promise.all(messages.map(msg => this.limit(async () => {
+                const fp = await fingerprintMessage(msg);
+
+                if (destFingerprints.has(fp)) {
+                    logger.debug(`[destination] Skipping duplicate: ${fp}`);
+                    return;
+                }
+
+                try {
+                    await this.destination.append(boxPath, msg);
+                    this.metrics.recordMessage(msg);
+                    logger.info(`[destination] Migrated: ${fp}`);
+                } catch (err) {
+                    logger.error(`[destination] Failed to migrate message: ${fp}`, { error: err.message });
+                }
+            })));
+        }
+
+    }
+
+    async logoutClients() {
+        try {
+            if (this.source.client.usable) await this.source.client.logout();
+        } catch (err) {
+            logger.warn(`[source] Logout failed: ${err.message}`);
+        }
+
+        try {
+            if (this.destination.client.usable) await this.destination.client.logout();
+        } catch (err) {
+            logger.warn(`[destination] Logout failed: ${err.message}`);
+        }
+    }
+
+    async runFullMigration() {
+        try {
+            const sourceMailboxes = await this.#listSelectableMailboxes('source');
+
+            for (const box of sourceMailboxes) {
+                await this.migrateMailbox(box.path)
+            }
+
+            logger.info('[migration] Migration completed.');
+            logger.info(`[migration] Metrics: ${JSON.stringify(this.metrics.report())}`);
+
+            const source_stats = this.source.client.stats();
+            console.log('Source statistics:', source_stats);
+
+            const dest_stats = this.destination.client.stats();
+            console.log('Destination statistics:', dest_stats);
+        } finally {
+            await this.logoutClients();
+        }
+
+    }
+
+    // Private helper
+
+    async #toMailbox(clientType, box) {
+        const size = await this.#calculateMailboxSize(clientType, box)
+        return Mailbox.fromObject({ ...box, size, children: [] })
+    }
+
+    async #calculateMailboxSize(clientType, box) {
+        if (box.flags?.has('\\Noselect')) {
+            return 0;
+        }
+        const client = this.#getClient(clientType);
+        const selectablePath = box.pathAsListed || box.path;
+
+        let mailbox;
+        try {
+            mailbox = await client.mailboxOpen(selectablePath);
+        } catch (err) {
+            logger.warn(`Skipping non-selectable mailbox: ${selectablePath}`);
+            return 0;
+        }
+        if (!mailbox.exists || mailbox.exists === 0) {
+            return 0;
+        }
+        let totalSize = 0;
+        try {
+            for await (const msg of client.fetch(`1:${mailbox.exists}`, { size: true })) {
+                totalSize += msg.size ?? 0;
+            }
+        } catch (err) {
+            logger.error(`Error fetching size ${selectablePath} - ${err.message}`);
+        }
+
+        return totalSize;
+    }
+
+
+
+    async #listSelectableMailboxes(clientType) {
+        const client = this.#getClient(clientType);
+
+        const mailboxes = await client.list();
+
+        return mailboxes
+            .filter(box => !box.flags.has('\\Noselect'))  // skip unselectable folders
+            .filter(box => !this.alwaysSkip.has(box.specialUse)); // skip ones you always ignore
+    }
+
+    #getClient(clientType) {
+        let client;
+        switch (clientType) {
+            case ClientType.DESTINATION:
+                client = this.destination?.client;
+                break;
+            case ClientType.SOURCE:
+                client = this.source?.client;
+                break;
+            default:
+                throw new Error(`Invalid clientType: ${clientType}`);
+        }
+
+        if (!client) {
+            throw new Error(`Client not initialized for ${clientType}`);
+        }
+
+        return client;
+    }
+
+    setClients(sourceClient, destinationClient) {
+        this.source.client = sourceClient;
+        this.destination.client = destinationClient;
+    }
+}

package/src/imap/imapWrapper.js

@@ -0,0 +1,99 @@
+import { connectToImap } from './client.js';
+import logger from "../utils/logger.js";
+import { withRetry } from '../utils/retry.js';
+
+
+const SKIP_SPECIAL_USE = [
+    '\\All', // avoids duplicates
+    '\\Trash', // usually not migrated
+    '\\Junk',
+    '\\Spam',
+    '\\Drafts'
+];
+
+
+export class ImapWrapper {
+    constructor(config, label) {
+        this.config = config;
+        this.label = label;
+        this.client = null;
+        this.lastMailbox = null;
+        this._reconnecting = null;
+
+    }
+
+    async setupClient() {
+        this.client = await connectToImap(this.config, this.label);
+
+        // event listens 
+        this.client.on('error', (err) => {
+            logger.error(`[${this.label}] IMAP error: ${err.message}`, { code: err.code });
+        });
+
+        this.client.on('mailboxOpen', (mailbox) => {
+            logger.info(`[${this.label}] Opened mailbox: ${mailbox.path} (${mailbox.exists} messages)`);
+            this.lastMailbox = mailbox.path;
+        });
+
+        this.client.on('mailboxClose', (mailbox) => {
+            logger.info(`[${this.label}] Closed mailbox: ${mailbox.path}`);
+        });
+
+        return this.client;
+    }
+
+    async recreateClient() {
+        logger.warn(`[${this.label}] Recreating client due to connection loss...`);
+        this.client = await this.setupClient();
+        if (this.lastMailbox) {
+            try {
+                await this.client.mailboxOpen(this.lastMailbox);
+            } catch (err) {
+                logger.warn(`[${this.label}] Failed to reopen last mailbox: ${err.message}`);
+            }
+        }
+        return this.client
+    }
+
+    async checkClient() {
+        if (this.client && this.client.usable) {
+            return this.client;
+        }
+        if (!this._reconnecting) {
+            this._reconnecting = this.recreateClient()
+                .finally(() => {
+                    this._reconnecting = null;
+                });
+        }
+        return this._reconnecting;
+    }
+
+    async fetch(uids, options) {
+        return withRetry(async () => {
+            await this.checkClient();
+            const results = [];
+            for await (const msg of this.client.fetch(uids, options)) {
+                results.push(msg);
+            }
+            return results;
+        }).catch(err => {
+            logger.error(`[${this.label}] Fetch failed after retries: ${err.message}`);
+            throw err;
+        });
+    }
+
+    async append(boxPath, msg) {
+        return withRetry(async () => {
+            await this.checkClient();
+            await this.client.append(
+                boxPath,
+                msg.source,
+                Array.from(msg.flags),
+                msg.internalDate
+            );
+        }).catch(err => {
+            logger.error(`[${this.label}] Append failed after retries: ${err.message}`);
+            throw err;
+        });
+    }
+}

package/src/imap/metrics.js

@@ -0,0 +1,21 @@
+export class Metrics {
+    constructor() {
+        this.startTime = Date.now();
+        this.bytesMigrated = 0;
+        this.messagesMigrated = 0;
+    }
+
+    recordMessage(msg) {
+        this.bytesMigrated += Buffer.byteLength(msg.source);
+        this.messagesMigrated++;
+    }
+
+    report() {
+        const elapsed = (Date.now() - this.startTime) / 1000;
+        return {
+            durationSeconds: elapsed,
+            migratedMessages: this.messagesMigrated,
+            migratedMB: (this.bytesMigrated / (1024 * 1024)).toFixed(2)
+        };
+    }
+}

package/src/imap/model/ClientType.js

@@ -0,0 +1,4 @@
+export const ClientType = Object.freeze({
+    SOURCE: "source",
+    DESTINATION: "destination"
+});

package/src/imap/model/Mailbox.js

@@ -0,0 +1,31 @@
+import logger from "../../utils/logger.js";
+
+class Mailbox {
+    constructor(name, path, size = 0, children = [], parentPath = '') {
+        this.name = name;
+        this.path = path;
+        this.size = size; // in bytes
+        this.children = children;
+        this.parentPath = parentPath;
+    }
+
+    static fromObject(obj) {
+        return new Mailbox(
+            obj.name,
+            obj.path,
+            obj.size ?? 0,
+            obj.children ?? [],
+            obj.parentPath ?? '');
+    }
+
+
+    get sizeMB() {
+        return +(this.size / 1024 / 1024).toFixed(2);
+    }
+
+    toString() {
+        return `${this.name} (${this.path}) - ${this.sizeMB} MB`;
+    }
+}
+
+export default Mailbox;

package/src/imap/model/Quota.js

@@ -0,0 +1,26 @@
+
+class Quota {
+    /**
+     * @param {number} usage - Used storage in bytes
+     * @param {number} limit - Storage limit in bytes
+     * @param {string} status - Status string (e.g., "80%")
+     */
+    constructor(usage, limit, status) {
+        this.usage = usage;
+        this.limit = limit;
+        this.status = status;
+    }
+
+    /**
+     * Returns usage and limit in MB for easier readability.
+     */
+    get infoMB() {
+        return {
+            usageMB: +(this.usage / 1024 / 1024).toFixed(2),
+            limitMB: +(this.limit / 1024 / 1024).toFixed(2),
+            status: this.status
+        };
+    }
+}
+
+export default Quota;

package/src/index.js

@@ -0,0 +1,2 @@
+import { migrateMailbox } from './imap/migrate.js';
+export { migrateMailbox };

package/src/lib/fingerprint.js

@@ -0,0 +1,34 @@
+import crypto from 'crypto';
+import { simpleParser } from 'mailparser';
+
+async function getMessageId(message) {
+    // Use headers if available, fallback to source
+    const buffer = Buffer.from(message.headers ?? message.source);
+
+    // Parse only the headers
+    const parsed = await simpleParser(buffer, {
+        skipHtmlToText: true,
+        skipTextToHtml: true
+    });
+
+    if (parsed.messageId) {
+        // normalize: strip <> and lowercase
+        return parsed.messageId.replace(/^<|>$/g, "").toLowerCase();
+    }
+    return null;
+}
+
+
+/**
+ * Generate a fingerprint for a message
+ * - Prefer Message-ID
+ * - Fallback: SHA256 hash of raw source
+ */
+export async function fingerprintMessage(msg) {
+    const messageId = await getMessageId(msg);
+    if (messageId) return `mid:${messageId.trim()}`;
+    return `hash:${crypto
+        .createHash("sha256")
+        .update(Buffer.from(msg.source))
+        .digest("hex")}`;
+}

package/src/lib/pathUtils.js

@@ -0,0 +1,30 @@
+/**
+ * Ensure a nested folder structure exists by creating missing parts.
+ *
+ * @param {string} fullPath - Full path like "Parent/Sub1/Sub2"
+ * @param {string} delimiter - Path separator ("/" for IMAP, path.sep for OS)
+ * @param {Set<string>} existing - Known existing paths
+ * @param {Function} creator - Function that creates a folder (async)
+ *        signature: async (path: string) => void
+ */
+export async function ensurePath(fullPath, delimiter, existing, creator) {
+    const parts = fullPath.split(delimiter);
+    let current = "";
+
+    for (const part of parts) {
+        current = current ? `${current}${delimiter}${part}` : part;
+
+        if (!existing.has(current)) {
+            try {
+                await creator(current);
+            } catch (err) {
+                if (err.responseText.includes("Mailbox already exists")) {
+                    console.log(`Already exists: ${current}`);
+                } else {
+                    throw err;
+                }
+            }
+            existing.add(current); // mark as created
+        }
+    }
+}

package/src/scripts/cleanupDestination.js

@@ -0,0 +1,62 @@
+import dotenv from 'dotenv';
+import { connectToImap } from "../imap/client.js";
+
+dotenv.config();
+
+(async () => {
+    const destUser = process.env.DEST_EMAIL;
+    const destPassword = process.env.DEST_PASSWORD;
+    const destAccessToken = process.env.DEST_ACCESS_TOKEN;
+
+    if (!destUser) {
+        console.error('Please set DEST_EMAIL in your .env file');
+        process.exit(1);
+    }
+
+    if (!destPassword && !destAccessToken) {
+        console.error('Please set either DEST_PASSWORD or DEST_ACCESS_TOKEN in your .env file');
+        process.exit(1);
+    }
+
+    const destHost = process.env.DEST_HOST || 'imap.tribe-x.org';
+    const destPort = parseInt(process.env.DEST_PORT, 10) || 993;
+
+
+    const destinationConfig = {
+        host: destHost,
+        port: destPort,
+        secure: true,
+        user: destUser,
+        ...(destAccessToken ? { accessToken: destAccessToken } : { password: destPassword })
+    };
+
+    const client = await connectToImap(destinationConfig);
+
+    try {
+        console.log('Connected to destination provider');
+
+        for await (const mailbox of await client.list()) {
+            console.log(`Cleaning mailbox: ${mailbox.path}`);
+
+            await client.mailboxOpen(mailbox.path);
+
+            const messages = await client.search({});
+            if (messages.length === 0) {
+                console.log(`No messages found in ${mailbox.path}`);
+                continue;
+            }
+
+            await client.messageFlagsAdd(messages, ['\\Deleted']);
+
+            await client.mailboxClose({ expunge: true });
+
+            console.log(`Deleted ${messages.length} messages from ${mailbox.path}`);
+        }
+
+        console.log('Destination mailboxes cleaned up!');
+    } catch (err) {
+        console.error('Error cleaning destination:', err);
+    } finally {
+        await client.logout();
+    }
+})();

package/src/scripts/runMigration.js

@@ -0,0 +1,64 @@
+import { ImapSyncManager } from '../imap/migrate.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+(async () => {
+    const sourceUser = process.env.SOURCE_EMAIL;
+    const destUser = process.env.DEST_EMAIL;
+
+    const sourcePassword = process.env.SOURCE_PASSWORD;
+    const sourceAccessToken = process.env.SOURCE_ACCESS_TOKEN;
+
+    const destPassword = process.env.DEST_PASSWORD;
+    const destAccessToken = process.env.DEST_ACCESS_TOKEN;
+
+    if (!sourceUser || !destUser) {
+        console.error('Please set SOURCE_EMAIL and DEST_EMAIL in your .env file');
+        process.exit(1);
+    }
+
+    if (!sourcePassword && !sourceAccessToken) {
+        console.error('Please set either SOURCE_PASSWORD or SOURCE_ACCESS_TOKEN in your .env file');
+        process.exit(1);
+    }
+
+    if (!destPassword && !destAccessToken) {
+        console.error('Please set either DEST_PASSWORD or DEST_ACCESS_TOKEN in your .env file');
+        process.exit(1);
+    }
+
+    // Optional host & port from .env, defaults to 993
+    const sourceHost = process.env.SOURCE_HOST || 'imap.gmail.com';
+    const sourcePort = parseInt(process.env.SOURCE_PORT, 10) || 993;
+
+    const destHost = process.env.DEST_HOST || 'imap.tribe-x.org';
+    const destPort = parseInt(process.env.DEST_PORT, 10) || 993;
+
+    const manager = new ImapSyncManager(
+        {
+            host: sourceHost,
+            port: sourcePort,
+            secure: true,
+            user: sourceUser,
+            ...(sourceAccessToken ? { accessToken: sourceAccessToken } : { password: sourcePassword })
+        },
+        {
+            host: destHost,
+            port: destPort,
+            secure: true,
+            user: destUser,
+            ...(destAccessToken ? { accessToken: destAccessToken } : { password: destPassword })
+        }
+    );
+
+    try {
+        await manager.init();
+        await manager.runFullMigration();
+        console.log('✅ Migration complete!');
+    } catch (err) {
+        console.error('❌ Migration failed:', err.message);
+        process.exit(1);
+    }
+
+})();

package/src/utils/logger.js

@@ -0,0 +1,21 @@
+import { createLogger, format, transports } from "winston";
+
+const logger = createLogger({
+    level: process.env.LOG_LEVEL || "info", // default to "info"
+    format: format.combine(
+        format.timestamp(),
+        format.colorize(), // nice colors in console
+        format.printf(({ level, message, timestamp, ...meta }) => {
+            return `[${timestamp}] [${level}] ${message} ${
+                Object.keys(meta).length ? JSON.stringify(meta) : ""
+            }`;
+        })
+    ),
+    transports: [
+        new transports.Console(),
+        new transports.File({ filename: "logs/error.log", level: "error" }),
+        new transports.File({ filename: "logs/combined.log" }),
+    ],
+});
+
+export default logger;

package/src/utils/retry.js

@@ -0,0 +1,33 @@
+import logger from "../utils/logger.js";
+
+const retryableCodes = ["ECONNRESET", "ETIMEDOUT", "EAI_AGAIN", "ENOTFOUND"];
+const permanentImapErrors = ["OVERQUOTA", "NO", "BAD"];
+
+export async function withRetry(fn, { retries = 3, delay = 1000 } = {}) {
+    let attempt = 0;
+
+    while (true) {
+        try {
+            return await fn();
+        } catch (err) {
+            attempt++;
+
+            // Check if permanent IMAP error
+            if (permanentImapErrors.some(e => err.response?.includes(e) || err.message?.includes(e))) {
+                logger.error(`[retry] Permanent failure (not retrying) with code ${err.code} : ${err.message}`);
+                throw err;
+            }
+
+            // Check if transient network error
+            const isRetryable = retryableCodes.includes(err.code);
+
+            if (!isRetryable || attempt > retries) {
+                logger.error(`[retry] Failed after ${attempt} attempts: ${err.message}`);
+                throw err;
+            }
+
+            logger.warn(`[retry] Attempt ${attempt} failed: ${err.message}. Retrying in ${delay}ms...`);
+            await new Promise(res => setTimeout(res, delay));
+        }
+    }
+}