@ubaidbinwaris/linkedin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UbaidBinWaris
+
+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,84 @@
+# LinkedIn Automation Bot
+
+A robust Node.js automation tool designed to interact with LinkedIn using [Playwright](https://playwright.dev/). This bot is built with stealth features to mimic human behavior, manage sessions efficiently, and provide an interactive CLI for control.
+
+## 🚀 Features
+
+- **Stealth Automation**: Uses `puppeteer-extra-plugin-stealth` with Playwright to minimize detection risks.
+- **Session Management**: Automatically saves and loads session states (cookies & local storage) to prevent frequent re-logins.
+- **Headless & Visible Modes**: configurable execution modes for debugging or background operation.
+- **Interactive CLI**: integrated REPL (Read-Eval-Print Loop) to control the bot instance after initialization.
+- **Smart Validation**: robust checks to verify login status and handle checkpoints/verifications manually if needed.
+- **Human-like Behavior**: Implements random delays, mouse movements, and dynamic user agents.
+
+## 🛠️ Prerequisites
+
+- **Node.js** (v14 or higher recommended)
+- **npm** (Node Package Manager)
+- A valid **LinkedIn Account**
+
+## 📦 Installation
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/UbaidBinWaris/linkedin.git
+    cd linkedin
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+
+3.  **Install Playwright browsers:**
+    ```bash
+    npx playwright install chromium
+    ```
+
+## ⚙️ Configuration
+
+1.  Create a `.env` file in the root directory.
+2.  Add your LinkedIn credentials:
+
+    ```env
+    LINKEDIN_EMAIL=your_email@example.com
+    LINKEDIN_PASSWORD=your_password
+    ```
+
+##  ▶️ Usage
+
+### Run in Headless Mode (Default)
+Runs the bot in the background without a visible browser window.
+
+```bash
+npm start
+```
+
+### Run in Visible Mode
+Useful for debugging or if manual intervention (CAPTCHA) is required.
+
+```bash
+npm start -- --visible
+```
+
+### CLI Commands
+Once the bot is running, you can interact with it through the terminal. (See `src/cli/repl.js` for available commands).
+
+## 📂 Project Structure
+
+```
+├── src/
+│   ├── cli/            # Command Line Interface logic
+│   ├── login/          # Login automation & checkpoint handling
+│   ├── session/        # Session storage & management
+│   ├── utils/          # Helper functions (logger, timing, etc.)
+│   └── config.js       # Configuration constants
+├── data/               # Stored session data (cookies, etc.)
+├── logs/               # Application logs
+├── index.js            # Entry point
+└── package.json        # Dependencies & scripts
+```
+
+## ⚠️ Disclaimer
+
+This tool is for educational purposes only. Automating interactions on LinkedIn violates their User Agreement. Use at your own risk. The authors are not responsible for any account bans or restrictions.

package/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+const logger = require("./src/utils/logger");
+require("dotenv").config();
+
+const loginToLinkedIn = require("./src/login/login");
+const REPL = require("./src/cli/repl");
+
+let browserInstance = null;
+
+// Cleanup function to be called by REPL or SIGINT
+async function cleanup() {
+    if (browserInstance) {
+        console.log("Closing browser...");
+        try {
+            await browserInstance.close();
+            console.log("Browser closed.");
+        } catch (err) {
+            console.error("Error closing browser:", err.message);
+        }
+        browserInstance = null;
+    }
+}
+
+// Handle Ctrl+C (SIGINT) for graceful shutdown fallback
+process.on("SIGINT", async () => {
+  console.log("\nReceived stop signal.");
+  await cleanup();
+  process.exit(0);
+});
+
+(async () => {
+  try {
+    // Check command line arguments
+    const args = process.argv.slice(2);
+    const isVisible = args.includes("--visible");
+    const isHeadless = !isVisible;
+
+    console.log(`Starting bot in ${isVisible ? "Visible" : "Headless"} Mode...`);
+    
+    const { browser, context, page } = await loginToLinkedIn({ headless: isHeadless });
+    browserInstance = browser;
+    
+    console.log("Login successful.");
+
+    // Start Interactive CLI
+    const repl = new REPL({ 
+        browser: browserInstance,
+        cleanup: cleanup
+    });
+    repl.start();
+
+  } catch (error) {
+    console.error("Error occurred:", error);
+    process.exit(1);
+  }
+})();

package/index.js

@@ -0,0 +1,11 @@
+const loginToLinkedIn = require('./src/login/login');
+const sessionManager = require('./src/session/sessionManager');
+const config = require('./src/config');
+const logger = require('./src/utils/logger');
+// Exporting the main function and other utilities for library usage
+module.exports = {
+    loginToLinkedIn,
+    sessionManager,
+    config,
+    logger
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ubaidbinwaris/linkedin",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "bin": {
+    "linkedin": "./cli.js"
+  },
+  "files": [
+    "src",
+    "index.js",
+    "cli.js",
+    "Readme.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UbaidBinWaris/linkedin.git"
+  },
+  "keywords": [
+    "linkedin",
+    "automation",
+    "bot",
+    "playwright"
+  ],
+  "author": "UbaidBinWaris",
+  "license": "MIT",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/UbaidBinWaris/linkedin/issues"
+  },
+  "homepage": "https://github.com/UbaidBinWaris/linkedin#readme",
+  "dependencies": {
+    "dotenv": "^17.2.4",
+    "playwright": "^1.58.2",
+    "playwright-extra": "^4.3.6",
+    "puppeteer-extra-plugin-stealth": "^2.11.2",
+    "user-agents": "^1.1.669",
+    "winston": "^3.19.0"
+  }
+}

package/src/cli/repl.js

@@ -0,0 +1,68 @@
+const readline = require("readline");
+
+class REPL {
+  constructor(context = {}) {
+    this.context = context;
+    this.rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: "linkedin-bot> ",
+    });
+  }
+
+  start() {
+    console.log("Interactive CLI started. Type 'help' for commands.");
+    this.rl.prompt();
+
+    this.rl.on("line", async (line) => {
+      const input = line.trim();
+      
+      switch (input) {
+        case "help":
+          console.log(`
+Available commands:
+  status    - Show bot status
+  exit      - Stop the bot and exit
+  quit      - Alias for exit
+  help      - Show this help message
+          `);
+          break;
+
+        case "status":
+            if (this.context.browser && this.context.browser.isConnected()) {
+                console.log("Status: 🟢 Connected");
+                const pages = this.context.browser.contexts()[0]?.pages().length || 0;
+                console.log(`Open pages: ${pages}`);
+            } else {
+                console.log("Status: 🔴 Disconnected");
+            }
+            break;
+
+        case "exit":
+        case "quit":
+          console.log("Exiting...");
+          this.rl.close();
+          if (this.context.cleanup) {
+              await this.context.cleanup();
+          }
+          process.exit(0);
+          break;
+
+        case "":
+          break;
+
+        default:
+          console.log(`Unknown command: '${input}'. Type 'help' for available commands.`);
+          break;
+      }
+      this.rl.prompt();
+    });
+
+    this.rl.on("close", () => {
+      console.log("\nCLI session ended.");
+      process.exit(0);
+    });
+  }
+}
+
+module.exports = REPL;

package/src/config.js

@@ -0,0 +1,14 @@
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
+module.exports = {
+  // Session expiry time: 30 days
+  SESSION_MAX_AGE: 30 * ONE_DAY_MS, 
+
+  // Selectors to verify if the session is valid (logged in)
+  VALIDATION_SELECTORS: [
+    '.global-nav__search',
+    'input[placeholder="Search"]',
+    '#global-nav-typeahead',
+    '.feed-shared-update-v2' // Feed post container
+  ]
+};

package/src/login/login.js

@@ -0,0 +1,261 @@
+const logger = require("../utils/logger");
+// Use playwright-extra with the stealth plugin
+const { chromium } = require("playwright-extra");
+const stealth = require("puppeteer-extra-plugin-stealth")();
+chromium.use(stealth);
+
+const { waitForUserResume } = require("../utils/terminal");
+const { sessionExists, saveSession, loadSession } = require("../session/sessionManager");
+const { randomDelay } = require("../utils/time");
+
+/**
+ * Validates that necessary environment variables are set.
+ * @throws {Error} If credentials are missing.
+ */
+function validateCredentials() {
+  if (!process.env.LINKEDIN_EMAIL || !process.env.LINKEDIN_PASSWORD) {
+    throw new Error("Missing LINKEDIN_EMAIL or LINKEDIN_PASSWORD in environment variables.");
+  }
+}
+
+/**
+ * Detects if a checkpoint/verification is triggered.
+ * @param {import('playwright').Page} page
+ * @returns {Promise<boolean>}
+ */
+async function detectCheckpoint(page) {
+  try {
+    const url = page.url();
+    if (
+      url.includes("checkpoint") ||
+      url.includes("challenge") ||
+      url.includes("verification") ||
+      url.includes("consumer-login/error")
+    ) {
+      return true;
+    }
+
+    // Also check for specific checkpoint elements if URL check isn't enough
+    // This is a non-blocking check with a short timeout
+    try {
+      await page.waitForSelector("h1:has-text('Security Verification')", { timeout: 1000 });
+      return true;
+    } catch (e) {
+      // Element not found, likely no checkpoint
+    }
+
+    return false;
+  } catch (error) {
+    logger.error(`Error during checkpoint detection: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Generates random viewport dimensions.
+ */
+function getRandomViewport() {
+  const width = 1280 + Math.floor(Math.random() * 640); // 1280 - 1920
+  const height = 720 + Math.floor(Math.random() * 360); // 720 - 1080
+  return { width, height };
+}
+
+/**
+ * Generates a random User-Agent string (simplified for now, ideally use a library).
+ */
+function getRandomUserAgent() {
+  const versions = ["120.0.0.0", "121.0.0.0", "122.0.0.0"];
+  const version = versions[Math.floor(Math.random() * versions.length)];
+  return `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${version} Safari/537.36`;
+}
+
+/**
+ * Main login function.
+ * @param {Object} options - Launch options for the browser.
+ * @param {boolean} [options.headless=false] - Whether to run in headless mode.
+ * @param {number} [options.slowMo=50] - Slow motion delay in ms.
+ * @param {string} [options.proxy] - Optional proxy server URL.
+ */
+async function loginToLinkedIn(options = {}) {
+  logger.info("Starting LinkedIn login process with stealth mode...");
+
+  try {
+    validateCredentials();
+  } catch (error) {
+    logger.error(error.message);
+    throw error;
+  }
+
+  const launchOptions = {
+    headless: options.headless !== undefined ? options.headless : false,
+    slowMo: options.slowMo || 50,
+    args: [
+      "--no-sandbox", 
+      "--disable-setuid-sandbox",
+      "--disable-blink-features=AutomationControlled" // Extra stealth
+    ],
+    ...options,
+  };
+
+  logger.info(`Launching browser...`);
+  const browser = await chromium.launch(launchOptions);
+
+  let context;
+  let page;
+
+  const contextOptions = {
+    userAgent: getRandomUserAgent(),
+    viewport: getRandomViewport(),
+    locale: 'en-US',
+    timezoneId: 'America/New_York', // Align with proxy if used, otherwise standard
+    permissions: ['geolocation'],
+    ignoreHTTPSErrors: true,
+  };
+
+  try {
+    // -----------------------------
+    // STEP 1: Try Using Saved Session
+    // -----------------------------
+    logger.info("Checking for saved session...");
+    context = await loadSession(browser, contextOptions);
+
+    if (context) {
+      logger.info("Session stored context created.");
+    } else {
+      logger.info("No valid session found. Starting fresh context.");
+      context = await browser.newContext(contextOptions);
+    }
+
+    page = await context.newPage();
+
+    // Set a default timeout for all actions
+    page.setDefaultTimeout(30000);
+
+    logger.info("Navigating to LinkedIn feed...");
+    await page.goto("https://www.linkedin.com/feed/", {
+      waitUntil: "domcontentloaded",
+    });
+
+    // Human-like pause
+    await randomDelay(2000, 4000);
+
+    // Check for checkpoint immediately after navigation
+    if (await detectCheckpoint(page)) {
+      logger.warn("Checkpoint detected immediately. Manual verification required.");
+      await waitForUserResume("Complete verification in the opened browser, then press ENTER here to continue...");
+    }
+
+const { VALIDATION_SELECTORS } = require("../config");
+
+    // Verify Session Validity
+    try {
+      // Check for any of the validation selectors
+      const isLoggedIn = await Promise.race([
+        Promise.any(VALIDATION_SELECTORS.map(selector => 
+            page.waitForSelector(selector, { timeout: 15000 }).then(() => true)
+        )),
+        page.waitForSelector('.login-form, #username, input[name="session_key"]', { timeout: 5000 }).then(() => false)
+      ]).catch(() => false);
+
+      if (isLoggedIn) {
+        logger.info("Session is valid. Login successful.");
+        return { browser, context, page };
+      } else {
+        logger.info("Session invalid or redirected to login page.");
+      }
+    } catch (err) {
+      logger.info("Could not verify session state. Proceeding to credential login.");
+    }
+
+    // CRITICAL FIX: If session was invalid, we MUST close the current context
+    // and start fresh. Otherwise, retained cookies might cause redirect loops
+    // (e.g. we go to /login, but LinkedIn sees cookies and redirects to /feed,
+    // so we can't find the email input).
+    logger.info("Closing invalid/expired session context...");
+    await context.close();
+    
+    logger.info("Starting fresh context for credential login...");
+    context = await browser.newContext(contextOptions);
+    page = await context.newPage();
+    page.setDefaultTimeout(30000);
+
+    // -----------------------------
+    // STEP 2: Credential Login
+    // -----------------------------
+    logger.info("Proceeding to credential login...");
+    
+    if (!page.url().includes("login") && !page.url().includes("uas/request-password-reset")) {
+       await page.goto("https://www.linkedin.com/login", { waitUntil: 'domcontentloaded' });
+       await randomDelay(1000, 2000);
+    }
+
+    const email = process.env.LINKEDIN_EMAIL;
+    const password = process.env.LINKEDIN_PASSWORD;
+
+    logger.info("Entering credentials...");
+    
+    // Simulate human typing
+    await page.click('input[name="session_key"]');
+    await randomDelay(500, 1000);
+    await page.type('input[name="session_key"]', email, { delay: 100 }); // Type with delay
+    
+    await randomDelay(1000, 2000);
+    
+    await page.click('input[name="session_password"]');
+    await page.type('input[name="session_password"]', password, { delay: 100 });
+    
+    await randomDelay(1000, 2000);
+
+    logger.info("Submitting login form...");
+    await Promise.all([
+      page.waitForNavigation({ waitUntil: 'domcontentloaded' }),
+      page.click('button[type="submit"]')
+    ]);
+
+    // Check for checkpoint again
+    if (await detectCheckpoint(page)) {
+      logger.warn("Checkpoint detected after login attempt. Manual verification required.");
+      await waitForUserResume("Complete verification in the opened browser, then press ENTER here to continue...");
+    }
+
+    // -----------------------------
+    // Post-Login Verification
+    // -----------------------------
+    logger.info("Verifying login success...");
+    try {
+        await page.waitForURL("**/feed**", { timeout: 20000 });
+        
+        // Wait for at least one validation selector
+        await Promise.any(VALIDATION_SELECTORS.map(selector => 
+            page.waitForSelector(selector, { timeout: 15000 })
+        ));
+        
+        logger.info("Login confirmed ✅");
+
+        // Save session state
+        await saveSession(context);
+        logger.info("Session state saved 💾");
+
+        return { browser, context, page };
+
+    } catch (err) {
+        logger.error("Login failed or timed out waiting for feed.");
+        const screenshotPath = `error_login_${Date.now()}.png`;
+        try {
+            await page.screenshot({ path: screenshotPath });
+            logger.info(`Screenshot saved to ${screenshotPath}`);
+        } catch (opts) {
+             console.error("Failed to take error screenshot");
+        }
+        
+        throw new Error("Login failed: Could not reach feed page.");
+    }
+
+  } catch (error) {
+    logger.error(`Critical error in loginToLinkedIn: ${error.message}`);
+    if (browser) await browser.close();
+    throw error;
+  }
+}
+
+module.exports = loginToLinkedIn;

package/src/session/sessionManager.js

@@ -0,0 +1,155 @@
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const logger = require("../utils/logger");
+
+const SESSION_PATH = path.join(__dirname, "../../data/session.json");
+const ALGORITHM = "aes-256-cbc";
+// Use a fixed key if not provided in env (for development convenience, but ideally should be in env)
+// Ensure the key is 32 bytes.
+const SECRET_KEY = process.env.SESSION_SECRET || "default_insecure_secret_key_32_bytes_long!!";
+
+// Ensure key is exactly 32 bytes for aes-256-cbc
+const key = crypto.createHash("sha256").update(String(SECRET_KEY)).digest();
+
+function encrypt(text) {
+  const iv = crypto.randomBytes(16);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+  let encrypted = cipher.update(text, 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+  return iv.toString('hex') + ':' + encrypted;
+}
+
+function decrypt(text) {
+  try {
+    const textParts = text.split(':');
+    const iv = Buffer.from(textParts.shift(), 'hex');
+    const encryptedText = textParts.join(':');
+    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+    let decrypted = decipher.update(encryptedText, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    return decrypted;
+  } catch (error) {
+    // If decryption fails, it might be a plain JSON file or invalid key
+    return null;
+  }
+}
+
+function sessionExists() {
+  return fs.existsSync(SESSION_PATH);
+}
+
+function getSessionPath() {
+  return SESSION_PATH;
+}
+
+const { SESSION_MAX_AGE } = require("../config");
+
+/**
+ * Saves the browser context storage state to an encrypted file with a timestamp.
+ * @param {import('playwright').BrowserContext} context 
+ */
+async function saveSession(context) {
+  try {
+    const state = await context.storageState();
+    
+    // Wrap state with metadata
+    const sessionData = {
+      timestamp: Date.now(),
+      state: state
+    };
+
+    const jsonString = JSON.stringify(sessionData);
+    const encryptedData = encrypt(jsonString);
+    
+    fs.mkdirSync(path.dirname(SESSION_PATH), { recursive: true });
+    fs.writeFileSync(SESSION_PATH, encryptedData, "utf-8");
+    logger.info("Session saved successfully (Encrypted & Timestamped) 🔒");
+  } catch (error) {
+    logger.error(`Failed to save session: ${error.message}`);
+  }
+}
+
+/**
+ * Loads the session from the encrypted file and creates a new context.
+ * Checks for session expiry.
+ * @param {import('playwright').Browser} browser 
+ * @param {Object} options - Context options
+ * @returns {Promise<import('playwright').BrowserContext>}
+ */
+async function loadSession(browser, options = {}) {
+  if (!sessionExists()) {
+    logger.info("No session file found.");
+    return null;
+  }
+
+  try {
+    const fileContent = fs.readFileSync(SESSION_PATH, "utf-8");
+    let sessionData;
+    let state;
+
+    // Try verifying if it is already JSON (legacy/plain)
+    try {
+      const parsed = JSON.parse(fileContent);
+      
+      // Check if it matches the new structure { timestamp, state }
+      if (parsed.timestamp && parsed.state) {
+        sessionData = parsed; // It was plain JSON but with new structure (unlikely but possible)
+      } else {
+        // It's the old structure (just storageState)
+        state = parsed;
+        logger.info("Loaded plain JSON session (Legacy).");
+      }
+    } catch (e) {
+      // Not JSON, try decrypting
+      const decrypted = decrypt(fileContent);
+      if (decrypted) {
+        try {
+          const parsedDecrypted = JSON.parse(decrypted);
+           // Check if it matches the new structure { timestamp, state }
+          if (parsedDecrypted.timestamp && parsedDecrypted.state) {
+            sessionData = parsedDecrypted;
+          } else {
+             // It's the old encrypted structure (just storageState)
+             state = parsedDecrypted;
+             logger.info("Loaded encrypted session (Legacy structure).");
+          }
+        } catch (parseError) {
+           logger.error("Failed to parse decrypted session.");
+           return null;
+        }
+      } else {
+         logger.error("Failed to decrypt session file. It might be corrupt or key mismatch.");
+         return null;
+      }
+    }
+
+    // Process new structure if found
+    if (sessionData) {
+      const age = Date.now() - sessionData.timestamp;
+      if (age > SESSION_MAX_AGE) {
+        logger.warn(`Session expired. Age: ${age}ms > Max: ${SESSION_MAX_AGE}ms. Rejecting session.`);
+        return null;
+      }
+      state = sessionData.state;
+      logger.info(`Loaded active session (Age: ${Math.round(age / 1000 / 60)} mins) 🔓.`);
+    }
+
+    const context = await browser.newContext({
+      storageState: state,
+      ...options
+    });
+    
+    return context;
+  } catch (error) {
+    logger.error(`Error loading session: ${error.message}`);
+    return null;
+  }
+}
+
+module.exports = {
+  sessionExists,
+  getSessionPath,
+  saveSession,
+  loadSession
+};

package/src/utils/logger.js

@@ -0,0 +1,30 @@
+const { createLogger, format, transports } = require("winston");
+const path = require("path");
+const fs = require("fs");
+
+const logDir = path.join(__dirname, "../../logs");
+
+if (!fs.existsSync(logDir)) {
+  fs.mkdirSync(logDir, { recursive: true });
+}
+
+const logger = createLogger({
+  level: "info",
+  format: format.combine(
+    format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+    format.printf(({ timestamp, level, message }) => {
+      return `${timestamp} [${level.toUpperCase()}] ${message}`;
+    })
+  ),
+  transports: [
+    new transports.File({
+      filename: path.join(logDir, "error.log"),
+      level: "error",
+    }),
+    new transports.File({
+      filename: path.join(logDir, "combined.log"),
+    }),
+  ],
+});
+
+module.exports = logger;

package/src/utils/terminal.js

@@ -0,0 +1,17 @@
+const readline = require("readline");
+
+function waitForUserResume(message = "Press ENTER to continue...") {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(message, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+module.exports = { waitForUserResume };

package/src/utils/time.js

@@ -0,0 +1,12 @@
+/**
+ * Returns a promise that resolves after a random delay between min and max milliseconds.
+ * @param {number} min - Minimum delay in ms.
+ * @param {number} max - Maximum delay in ms.
+ * @returns {Promise<void>}
+ */
+function randomDelay(min = 1000, max = 3000) {
+  const delay = Math.floor(Math.random() * (max - min + 1)) + min;
+  return new Promise((resolve) => setTimeout(resolve, delay));
+}
+
+module.exports = { randomDelay };