@ubaidbinwaris/linkedin 1.0.13 → 1.1.0

package/Readme.md

@@ -1,185 +1,115 @@
-# LinkedIn Automation Bot & Module 🤖
+# LinkedIn Session Manager & Automation Service (v2.0.0)
 
-A robust, stealthy Node.js automation tool designed to interact with LinkedIn using [Playwright](https://playwright.dev/). This package can be used as a standalone **CLI tool** or integrated as a **Module** into larger applications (supporting database storage, custom logging, and headless controls).
+A robust, deterministic backend service foundation for managing multiple LinkedIn accounts with strict concurrency control and session isolation. 
 
-> **⚠️ 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.
+> **v2.0.0 Change**: This major version pivots from a CLI tool to a backend service architecture. It removes "stealth" plugins and "auto-resolution" magic in favor of stability, reliability, and "fail-fast" principles.
 
----
+## Core Features
 
-## 🚀 Key Features
+- **Multi-User Architecture**: Designed to handle hundreds of accounts safely.
+- **Concurrency Control**: In-memory locking (`SessionLock`) prevents parallel login attempts for the same user.
+- **Session Isolation**:
+  - Sessions stored as `SHA-256` hashes of emails (privacy).
+  - AES-256 Encryption for session data.
+- **Smart Validation**:
+  - Trusts sessions validated within the last 10 minutes (reduces feed navigation load).
+  - Automatically refreshes older sessions.
+- **Deterministic Flow**:
+  - **Launch** -> **Check Session** -> **Login** -> **Fail/Success**.
+  - **Fail Fast**: If a checkpoint/challenge is detected, it throws `CHECKPOINT_DETECTED` immediately, allowing the upper layer (API/Worker) to handle it (e.g., notify admin).
 
--   **🕵️‍♂️ Stealth Automation**: Leverages `puppeteer-extra-plugin-stealth` to minimize detection risks.
--   **👥 Multi-User Support**: Manage multiple LinkedIn accounts with isolated sessions.
--   **💾 Flexible Session Storage**: Store sessions in local files (default) or **inject your own database adapter** (MongoDB, Postgres, Redis, etc.).
--   **🖥️ Dual Modes**:
-    -   **Headless**: Runs efficiently in the background.
-    -   **Visible**: Watch the bot work for debugging.
--   **⌨️ CLI & Interactive REPL**: Control the bot directly from the terminal.
--   **🔌 Module Integration**: Easily integrate into existing Express/Node.js servers with custom logging and webhook-style checkpoint handling.
--   **🧠 Smart Validation**: Automatically detects checkpoints (CAPTCHA/Pin) and allows manual resolution via terminal or callback.
+## Installation
 
----
-
-## 📦 Installation
-
-### 1. Install via NPM
 ```bash
 npm install @ubaidbinwaris/linkedin
 ```
 
-### 2. (Optional) Clone for Source Usage
-```bash
-git clone https://github.com/UbaidBinWaris/linkedin.git
-cd linkedin
-npm install
-npx playwright install chromium
+## Architecture
+
+```mermaid
+graph TD
+    A[API/Worker Request] --> B{Acquire User Lock}
+    B -- Busy --> C[Throw BUSY Error]
+    B -- Acquired --> D[Launch Standard Playwright]
+    D --> E{Load Session}
+    E -- Valid & Recent --> F[Return Context (Skip Feed)]
+    E -- Stale/None --> G[Navigate to Feed]
+    G --> H{Is Logged In?}
+    H -- Yes --> I[Update Validation Timestamp]
+    I --> F
+    H -- No --> J[Perform Credential Login]
+    J --> K{Checkpoint?}
+    K -- Yes --> L[Throw CHECKPOINT_DETECTED]
+    K -- No --> M[Login Success]
+    M --> I
+    F --> N[Release Lock (on Task Completion)]
 ```
 
----
-
-## ▶️ Usage: CLI Mode
-
-You can run the bot directly from the command line.
+## Usage
 
-### 1. Quick Start (Single User)
-Create a `.env` file with your credentials:
-```env
-LINKEDIN_EMAIL=your_email@example.com
-LINKEDIN_PASSWORD=your_password
-```
-Then run:
-```bash
-npm start
-```
+### Basic Login
 
-### 2. Multi-User Mode
-To manage multiple accounts, create a `users.js` file in the root directory:
+The `loginToLinkedIn` function now handles locking internally. If you try to call it twice for the same user simultaneously, the second call will fail with a `BUSY` error.
 
-**File:** `users.js`
 ```javascript
-module.exports = [
-    { username: "alice@example.com", password: "password123" },
-    { username: "bob@company.com", password: "securePass!" }
-];
-```
-
-Run the bot:
-```bash
-npm start
-```
-The CLI will prompt you to select which user to log in as:
-```text
-Select a user to login:
-1. alice@example.com
-2. bob@company.com
-3. Use Environment Variables (.env)
+const { loginToLinkedIn } = require('@ubaidbinwaris/linkedin');
+
+(async () => {
+    try {
+        const { browser, page } = await loginToLinkedIn({
+            headless: true
+        }, {
+            username: 'user@example.com',
+            password: 'secret-password'
+        });
+
+        console.log("Logged in and active!");
+        
+        // Output session status
+        console.log(`Needs Validation? ${page.context().needsValidation}`);
+
+        // Do work...
+        
+        await browser.close();
+    } catch (err) {
+        if (err.message === 'CHECKPOINT_DETECTED') {
+            console.error("Manual intervention required for this account.");
+        } else if (err.message.startsWith('BUSY')) {
+            console.error("User is currently busy with another task.");
+        } else {
+            console.error("Login failed:", err);
+        }
+    }
+})();
 ```
 
----
-
-## 🔌 Usage: Module Integration
+### Custom Session Storage
 
-This package is designed to be embedded in larger systems (e.g., a SaaS backend managing hundreds of accounts).
+You can link this to a database (Redis/Postgres) instead of local files.
 
-### Import
 ```javascript
-const linkedin = require('@ubaidbinwaris/linkedin');
-```
-
-### 1. Custom Session Storage (Database Integration)
-By default, sessions are saved as JSON files in `data/linkedin/`. You can override this to save sessions directly in your database.
+const { setSessionStorage } = require('@ubaidbinwaris/linkedin');
 
-```javascript
-// Example: Using a generic database
-linkedin.setSessionStorage({
-    async read(username) {
-        // Fetch encrypted session string from your DB
-        const user = await db.users.findOne({ email: username });
-        return user ? user.linkedinSession : null;
+setSessionStorage({
+    read: async (email) => {
+        // Fetch encrypted string from DB
+        return await db.sessions.findOne({ where: { email } });
     },
-    async write(username, data) {
-        // Save encrypted session string to your DB
-        await db.users.updateOne(
-            { email: username }, 
-            { $set: { linkedinSession: data } },
-            { upsert: true }
-        );
+    write: async (email, data) => {
+        // Save encrypted string to DB
+        await db.sessions.upsert({ email, data });
     }
 });
 ```
 
-### 2. Custom Logger
-Redirect bot logs to your application's logging system (e.g., Winston, Pino, Bunyan).
-
-```javascript
-linkedin.setLogger({
-    info: (msg) => console.log(`[BOT INFO] ${msg}`),
-    error: (msg) => console.error(`[BOT ERROR] ${msg}`),
-    warn: (msg) => console.warn(`[BOT WARN] ${msg}`),
-    debug: (msg) => console.debug(`[BOT DEBUG] ${msg}`)
-});
-```
-
-### 3. Login & Headless Control
-When running on a server, you can't use the terminal to solve CAPTCHAs. Use the `onCheckpoint` callback to handle verification requests (e.g., trigger an alert).
-
-```javascript
-const credentials = { 
-    username: "alice@example.com", 
-    password: "password123" 
-};
-
-try {
-    const { browser, page } = await linkedin.loginToLinkedIn({
-        headless: true,
-        // Callback when LinkedIn asks for verification
-        onCheckpoint: async () => {
-            console.log("⚠️ Checkpoint detected! Pausing for manual intervention...");
-            
-            // Example: Send an email/Slack alert to admin
-            await sendAdminAlert(`User ${credentials.username} needs verification!`);
-            
-            // Wait for admin to signal resolution (e.g. via DB flag or API call)
-            await waitForAdminResolution();
-            
-            console.log("Resuming login...");
-        }
-    }, credentials);
-
-    console.log("Login successful!");
-    
-    // Do automation tasks...
-    await browser.close();
-
-} catch (err) {
-    console.error("Login failed:", err);
-}
-```
-
----
-
-## 🛠️ Configuration Options
-
-| Option | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `headless` | `boolean` | `false` | Run browser in background. |
-| `slowMo` | `number` | `50` | Delay between actions (ms). |
-| `proxy` | `string` | `undefined` | Proxy URL (e.g., `http://user:pass@host:port`). |
-| `onCheckpoint` | `function` | `null` | Async callback triggered when verification is needed. |
-
----
-
-## ❓ Troubleshooting
-
-### "Checkpoint Detected"
--   **CLI Mode**: The bot will pause and ask you to open a visible browser. Press ENTER to open it, solve the CAPTCHA, and the bot will confirm success and resume.
--   **Module Mode**: Ensure you provide an `onCheckpoint` callback to handle this event, otherwise the promise will reject or hang depending on implementation.
-
-### Session Files
--   Sessions are encrypted and contain timestamps.
--   If `setSessionStorage` is NOT used, files are stored in `data/linkedin/<sanitized_username>.json`.
-
----
-
-## 📄 License
-MIT License.
+## Directory Structure
+
+*   `src/session/`:
+    *   `SessionLock.js`: In-memory concurrency control.
+    *   `sessionManager.js`: Hashing, encryption, validation logic.
+*   `src/login/`:
+    *   `login.js`: Deterministic login flow.
+*   `src/browser/`:
+    *   `launcher.js`: Standard Playwright launcher (no stealth plugins).
+*   `src/auth/`:
+    *   `checkpoint.js`: Simple detection logic.

package/index.js

@@ -1,14 +1,13 @@
+// Main entry point
 const loginToLinkedIn = require('./src/login/login');
-const sessionManager = require('./src/session/sessionManager');
+const { setSessionDir, setSessionStorage } = require('./src/session/sessionManager');
+const { setLogger } = require('./src/utils/logger');
 const config = require('./src/config');
-const logger = require('./src/utils/logger'); // This is now the proxy object
-// Exporting the main function and other utilities for library usage
+
 module.exports = {
     loginToLinkedIn,
-    sessionManager,
-    setSessionDir: sessionManager.setSessionDir,
-    setSessionStorage: sessionManager.setSessionStorage,
-    setLogger: logger.setLogger,
-    config,
-    logger
+    setSessionDir,
+    setSessionStorage,
+    setLogger,
+    config
 };

package/package.json

@@ -1,11 +1,8 @@
 {
   "name": "@ubaidbinwaris/linkedin",
-  "version": "1.0.13",
+  "version": "1.1.0",
   "description": "",
   "main": "index.js",
-  "bin": {
-    "linkedin": "cli.js"
-  },
   "files": [
     "src",
     "index.js",
@@ -37,9 +34,6 @@
   "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/auth/actions.js

@@ -0,0 +1,49 @@
+const logger = require("../utils/logger");
+const { randomDelay } = require("../utils/time");
+
+const LINKEDIN_LOGIN = "https://www.linkedin.com/login";
+
+/**
+ * Performs credential-based login.
+ */
+async function performCredentialLogin(page, email, password) {
+  logger.info("Proceeding to credential login...");
+
+  if (!page.url().includes("login") && !page.url().includes("uas/request-password-reset")) {
+     await page.goto(LINKEDIN_LOGIN, { waitUntil: 'domcontentloaded' });
+     await randomDelay(1000, 2000);
+  }
+
+  logger.info("Entering credentials...");
+  
+  await page.click('input[name="session_key"]');
+  await randomDelay(500, 1000);
+  await page.type('input[name="session_key"]', email, { delay: 100 });
+  
+  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"]')
+  ]);
+}
+
+/**
+ * Checks if the user is currently logged in (on feed).
+ */
+async function isLoggedIn(page) {
+  try {
+    await page.waitForSelector(".global-nav__search, #global-nav-typeahead", { timeout: 10000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { performCredentialLogin, isLoggedIn };

package/src/auth/checkpoint.js

@@ -0,0 +1,31 @@
+/**
+ * Detects if a checkpoint/verification is triggered.
+ * Returns true if intervention is needed.
+ */
+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;
+    }
+
+    try {
+      await page.waitForSelector("h1:has-text('Security Verification')", { timeout: 1000 });
+      return true;
+    } catch (e) {
+      // Element not found
+    }
+
+    return false;
+  } catch (error) {
+    logger.error(`Error during checkpoint detection: ${error.message}`);
+    return false;
+  }
+}
+
+module.exports = { detectCheckpoint };

package/src/browser/launcher.js

@@ -0,0 +1,62 @@
+const { chromium } = require("playwright");
+const logger = require("../utils/logger");
+const { loadSession } = require("../session/sessionManager");
+
+/**
+ * Creates and launches a browser instance.
+ * @param {Object} options - Launch options
+ */
+async function createBrowser(options = {}) {
+  const launchOptions = {
+    headless: options.headless !== undefined ? options.headless : true,
+    args: [
+      "--no-sandbox", 
+      "--disable-setuid-sandbox",
+    ],
+    ...options
+  };
+
+  logger.info("Launching browser (Standard Playwright)...");
+  return await chromium.launch(launchOptions);
+}
+
+/**
+ * Creates or loads a browser context.
+ * @param {import('playwright').Browser} browser
+ * @param {string} email - for session loading
+ */
+async function createContext(browser, email) {
+  const contextOptions = {
+    userAgent: getRandomUserAgent(),
+    viewport: getRandomViewport(),
+    locale: 'en-US',
+    timezoneId: 'America/New_York',
+    permissions: ['geolocation'],
+    ignoreHTTPSErrors: true,
+  };
+
+  logger.info(`Checking for saved session for ${email}...`);
+  const storedContext = await loadSession(browser, contextOptions, email);
+
+  if (storedContext) {
+    logger.info("Session stored context loaded.");
+    return storedContext;
+  }
+
+  logger.info("No valid session found. Creating new context.");
+  return await browser.newContext(contextOptions);
+}
+
+function getRandomViewport() {
+  const width = 1280 + Math.floor(Math.random() * 640);
+  const height = 720 + Math.floor(Math.random() * 360);
+  return { width, height };
+}
+
+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`;
+}
+
+module.exports = { createBrowser, createContext };

package/src/login/login.js

@@ -101,17 +101,92 @@ async function performCredentialLogin(page, email, password) {
 
 
 async function handleCheckpoint(page, options) {
+  // Initial check
   if (!(await detectCheckpoint(page))) return;
 
+  logger.warn("Checkpoint detected.");
+
   if (options.headless) {
-    throw new Error("Checkpoint detected in headless mode.");
-  }
+    logger.info("Headless mode detected. Attempting auto-resolution...");
+
+    // ---------------------------------------------------------
+    // STRATEGY 1: Click Simple Buttons (Yes, Skip, Continue)
+    // ---------------------------------------------------------
+    try {
+      const clicked = await page.evaluate(() => {
+        const candidates = Array.from(document.querySelectorAll('button, a, [role="button"], input[type="submit"], input[type="button"]'));
+        const targetText = ['Yes', 'Skip', 'Not now', 'Continue', 'Sign in', 'Verify', 'Let’s do it', 'Next'];
+        
+        const btn = candidates.find(b => {
+            const text = (b.innerText || b.value || '').trim();
+            return targetText.some(t => text.includes(t));
+        });
+
+        if (btn) {
+            btn.click();
+            return true;
+        }
+        return false;
+      });
+
+      if (clicked) {
+        logger.info("Clicked a resolution button. Waiting for navigation...");
+        await page.waitForTimeout(3000);
+        
+        // Check if resolved
+        if (!(await detectCheckpoint(page))) {
+             logger.info("Checkpoint resolved via button click!");
+             return;
+        }
+      }
+    } catch (e) {
+      logger.warn(`Auto-resolve button click failed: ${e.message}`);
+    }
+
+    // ---------------------------------------------------------
+    // STRATEGY 2: Mobile App Verification (Wait & Poll)
+    // ---------------------------------------------------------
+    try {
+        const isMobileVerif = await page.evaluate(() => {
+            const text = document.body.innerText;
+            return text.includes("Open your LinkedIn app") || 
+                   text.includes("Tap Yes on the prompt") ||
+                   text.includes("verification request to your device");
+        });
+
+        if (isMobileVerif) {
+            logger.info("Mobile verification detected. Waiting 2 minutes for manual approval on device...");
+            
+            try {
+                // Poll for feed URL for 120 seconds
+                // We use a loop or waitForFunction
+                await page.waitForFunction(() => {
+                    return window.location.href.includes("/feed") || 
+                           document.querySelector('.global-nav__search');
+                }, { timeout: 120000 });
+
+                logger.info("Mobile verification successful! Resuming...");
+                return;
+            } catch (timeoutErr) {
+                logger.warn("Mobile verification timed out.");
+            }
+        }
+    } catch (e) {
+         logger.warn(`Mobile verification check failed: ${e.message}`);
+    }
 
-  logger.warn("Verification required. Please complete manually.");
+    // Re-check after attempts
+    if (await detectCheckpoint(page)) {
+        throw new Error("Checkpoint detected in headless mode and auto-resolution failed.");
+    }
 
-  await waitForUserResume(
-    "Complete verification in browser, then press ENTER..."
-  );
+  } else {
+    // Visible mode
+    logger.warn("Verification required. Please complete manually.");
+    await waitForUserResume(
+      "Complete verification in browser, then press ENTER..."
+    );
+  }
 }
 
 async function detectCheckpoint(page) {
@@ -120,7 +195,8 @@ async function detectCheckpoint(page) {
   return (
     url.includes("checkpoint") ||
     url.includes("challenge") ||
-    url.includes("verification")
+    url.includes("verification") ||
+    url.includes("consumer-login/error")
   );
 }
 

package/src/session/SessionLock.js

@@ -0,0 +1,52 @@
+const logger = require("../utils/logger");
+
+/**
+ * In-memory lock map to prevent simultaneous login attempts for the same user.
+ * Map<email, Promise<any>>
+ */
+const activeLogins = new Map();
+
+const SessionLock = {
+  /**
+   * Executes a function with an exclusive lock for the given email.
+   * If a lock exists, it waits for it to release (or chains onto it? 
+   * Actually user requested: "if activeLogins.has(email) { return activeLogins.get(email); }"
+   * This means if a login is in progress, return that SAME promise. Join the existing attempt.)
+   * 
+   * @param {string} email 
+   * @param {Function} fn - Async function to execute
+   * @returns {Promise<any>}
+   */
+  async withLoginLock(email, fn) {
+    if (activeLogins.has(email)) {
+      logger.info(`[SessionLock] ${email} is already logging in. Joining existing request...`);
+      return activeLogins.get(email);
+    }
+
+    logger.info(`[SessionLock] Acquiring lock for ${email}...`);
+    
+    // Create a promise that wraps the execution
+    const promise = (async () => {
+      try {
+        return await fn();
+      } finally {
+        activeLogins.delete(email);
+        logger.info(`[SessionLock] Releasing lock for ${email}.`);
+      }
+    })();
+
+    activeLogins.set(email, promise);
+    return promise;
+  },
+
+  /**
+   * Checks if a user is currently locked.
+   * @param {string} email
+   * @returns {boolean}
+   */
+  isLocked(email) {
+    return activeLogins.has(email);
+  }
+};
+
+module.exports = SessionLock;

package/src/session/sessionManager.js

@@ -2,6 +2,7 @@ const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
 const logger = require("../utils/logger");
+const SessionLock = require("./SessionLock"); // Keeping specific import, though widely used via login
 
 let sessionDir = path.join(process.cwd(), "data", "linkedin");
 
@@ -14,11 +15,7 @@ function setSessionDir(dirPath) {
 }
 
 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) {
@@ -39,55 +36,44 @@ function decrypt(text) {
     decrypted += decipher.final('utf8');
     return decrypted;
   } catch (error) {
-    // If decryption fails, it might be a plain JSON file or invalid key
     return null;
   }
 }
 
 /**
- * Sanitizes a username to be safe for filenames.
- * Replaces special characters with underscores or descriptive text.
- * @param {string} username 
- * @returns {string}
+ * Generates a SHA-256 hash of the email to use as filename.
+ * Privacy + filesystem safety.
+ * @param {string} email 
+ * @returns {string} hex hash
  */
-function sanitizeUsername(username) {
-  if (!username) return "default_session";
-  return username
-    .replace(/@/g, "_at_")
-    .replace(/\./g, "_dot_")
-    .replace(/[^a-zA-Z0-9_\-]/g, "_");
+function getSessionHash(email) {
+  if (!email) return "default";
+  return crypto.createHash("sha256").update(email).digest("hex");
 }
 
-function getSessionPath(username) {
-  const filename = `${sanitizeUsername(username)}.json`;
+function getSessionPath(email) {
+  const filename = `${getSessionHash(email)}.json`;
   return path.join(sessionDir, filename);
 }
 
-function sessionExists(username) {
-  return fs.existsSync(getSessionPath(username));
+function sessionExists(email) {
+  return fs.existsSync(getSessionPath(email));
 }
 
-const { SESSION_MAX_AGE } = require("../config");
+const { SESSION_MAX_AGE } = require("../config"); // Assuming this exists, typically 7 days?
+
+// Validation Cache Duration (10 minutes)
+const VALIDATION_CACHE_MS = 10 * 60 * 1000;
 
 const defaultStorage = {
-  /**
-   * Reads session data for a user.
-   * @param {string} username 
-   * @returns {Promise<string|null>} Encrypted session string or null
-   */
-  async read(username) {
-    const filePath = getSessionPath(username);
+  async read(email) {
+    const filePath = getSessionPath(email);
     if (!fs.existsSync(filePath)) return null;
     return fs.readFileSync(filePath, "utf-8");
   },
   
-  /**
-   * Writes session data for a user.
-   * @param {string} username 
-   * @param {string} data - Encrypted session string
-   */
-  async write(username, data) {
-    const filePath = getSessionPath(username);
+  async write(email, data) {
+    const filePath = getSessionPath(email);
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, data, "utf-8");
   }
@@ -95,10 +81,6 @@ const defaultStorage = {
 
 let currentStorage = defaultStorage;
 
-/**
- * Sets a custom session storage adapter.
- * @param {Object} adapter - Object with read(username) and write(username, data) methods.
- */
 function setSessionStorage(adapter) {
   if (adapter && typeof adapter.read === 'function' && typeof adapter.write === 'function') {
     currentStorage = adapter;
@@ -108,47 +90,43 @@ function setSessionStorage(adapter) {
 }
 
 /**
- * Saves the browser context storage state to an encrypted file/storage with a timestamp.
+ * Saves the browser context state.
  * @param {import('playwright').BrowserContext} context 
- * @param {string} [username] - The username to associate with this session
+ * @param {string} email 
+ * @param {boolean} [isValidated] - If true, updates lastValidatedAt
  */
-async function saveSession(context, username) {
+async function saveSession(context, email, isValidated = false) {
   try {
     const state = await context.storageState();
     
-    // Wrap state with metadata
+    // Load existing metadata if possible to preserve creation time? 
+    // For now, simpler to just overwrite, but we might lose 'createdAt' if we had it.
+    // Let's just write new.
+    
     const sessionData = {
-      timestamp: Date.now(),
+      timestamp: Date.now(), // Last saved
+      lastValidatedAt: isValidated ? Date.now() : undefined,
       state: state
+      // Future: proxy binding here
     };
 
     const jsonString = JSON.stringify(sessionData);
     const encryptedData = encrypt(jsonString);
     
-    await currentStorage.write(username || "default", encryptedData);
+    await currentStorage.write(email || "default", encryptedData);
 
-    logger.info(`Session saved successfully for ${username || "default"} (Encrypted & Timestamped) 🔒`);
+    logger.info(`Session saved for ${email} (Validated: ${isValidated}) 🔒`);
   } catch (error) {
     logger.error(`Failed to save session: ${error.message}`);
   }
 }
 
 /**
- * Loads the session from storage and creates a new context.
- * Checks for session expiry.
- * @param {import('playwright').Browser} browser 
- * @param {Object} options - Context options
- * @param {string} [username] - The username to load session for
- * @returns {Promise<import('playwright').BrowserContext>}
+ * Loads the session.
+ * @returns {Promise<{ context: import('playwright').BrowserContext, needsValidation: boolean }>}
  */
-async function loadSession(browser, options = {}, username) {
-  const user = username || "default";
-
-  // Check existence if storage supports it, otherwise generic check
-  // For custom storage, read() returning null implies not found.
-  
-  // Note: sessionExists is tied to FS. We should deprecate it or update it.
-  // But for now, let's rely on read() returning null.
+async function loadSession(browser, options = {}, email) {
+  const user = email || "default";
 
   try {
     const fileContent = await currentStorage.read(user);
@@ -158,54 +136,47 @@ async function loadSession(browser, options = {}, username) {
       return null;
     }
 
-    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).");
+    let sessionData = null;
+    let state = null;
+
+    // Decrypt
+    const decrypted = decrypt(fileContent);
+    if (decrypted) {
+      try {
+        sessionData = JSON.parse(decrypted);
+      } catch (e) {
+        logger.error("Failed to parse session JSON.");
+        return null;
       }
-    } catch (e) {
-      // Not JSON, try decrypting
-      const decrypted = decrypt(fileContent);
-      if (decrypted) {
+    } else {
+        // Fallback for legacy plain JSON? 
         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 data. It might be corrupt or key mismatch.");
-         return null;
-      }
+            sessionData = JSON.parse(fileContent);
+        } catch(e) {}
     }
 
-    // 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.`);
+    if (!sessionData || !sessionData.state) {
+        logger.warn("Invalid or corrupt session data.");
         return null;
-      }
-      state = sessionData.state;
-      logger.info(`Loaded active session for ${username || "default"} (Age: ${Math.round(age / 1000 / 60)} mins) 🔓.`);
+    }
+
+    // Check Age (Total expiry)
+    const age = Date.now() - sessionData.timestamp;
+    if (SESSION_MAX_AGE && age > SESSION_MAX_AGE) {
+         logger.warn(`Session expired (Age: ${age}ms).`);
+         return null;
+    }
+
+    state = sessionData.state;
+
+    // Check Validation Freshness
+    let needsValidation = true;
+    if (sessionData.lastValidatedAt) {
+        const valAge = Date.now() - sessionData.lastValidatedAt;
+        if (valAge < VALIDATION_CACHE_MS) {
+            needsValidation = false;
+            logger.info(`Session validation cached (Age: ${Math.round(valAge/1000)}s). Skipping checks.`);
+        }
     }
 
     const context = await browser.newContext({
@@ -213,7 +184,13 @@ async function loadSession(browser, options = {}, username) {
       ...options
     });
     
+    // Attach metadata to context for caller to check? 
+    // Or return object? Returning object is a breaking change for internal API but we are in v2.
+    // Let's attach to context object directly as a property for convenience
+    context.needsValidation = needsValidation;
+    
     return context;
+
   } catch (error) {
     logger.error(`Error loading session: ${error.message}`);
     return null;
@@ -226,5 +203,6 @@ module.exports = {
   sessionExists,
   getSessionPath,
   saveSession,
-  loadSession
+  loadSession,
+  SessionLock
 };

package/cli.js

@@ -1,84 +0,0 @@
-#!/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);
-    
-    if (args.includes("--help") || args.includes("-h")) {
-        console.log(`
-LinkedIn Automation CLI
-
-Usage:
-  linkedin [options]
-
-Options:
-  --visible       Run in visible mode (default is headless)
-  --help, -h      Show this help message
-  --version, -v   Show version number
-`);
-        process.exit(0);
-    }
-
-    if (args.includes("--version") || args.includes("-v")) {
-        const packageJson = require("./package.json");
-        console.log(`v${packageJson.version}`);
-        process.exit(0);
-    }
-
-const { selectUser } = require("./src/cli/userSelection");
-
-    const isVisible = args.includes("--visible");
-    const isHeadless = !isVisible;
-
-    // Select User
-    const credentials = await selectUser();
-
-    console.log(`Starting bot in ${isVisible ? "Visible" : "Headless"} Mode...`);
-    
-    // Pass credentials (or null) to login function
-    const { browser, context, page } = await loginToLinkedIn({ headless: isHeadless }, credentials);
-    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/src/cli/repl.js

@@ -1,68 +0,0 @@
-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/cli/userSelection.js

@@ -1,73 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-const readline = require('readline');
-const logger = require('../utils/logger');
-
-const USERS_FILE = path.join(process.cwd(), 'users.js');
-
-/**
- * Loads users from users.js and prompts for selection if multiple exist.
- * @returns {Promise<Object|null>} Selected credentials { username, password } or null if using env.
- */
-async function selectUser() {
-    if (!fs.existsSync(USERS_FILE)) {
-        logger.info("No users.js file found. Using environment variables.");
-        return null;
-    }
-
-    let users = [];
-    try {
-        users = require(USERS_FILE);
-        if (!Array.isArray(users) || users.length === 0) {
-            logger.warn("users.js exists but exports an empty array or invalid format.");
-            return null;
-        }
-    } catch (error) {
-        logger.error(`Error loading users.js: ${error.message}`);
-        return null;
-    }
-
-    if (users.length === 1) {
-        logger.info(`Single user found in users.js: ${users[0].username}`);
-        return users[0];
-    }
-
-    // Multiple users - Prompt for selection
-    console.log('\nSelect a user to login:');
-    users.forEach((u, index) => {
-        console.log(`${index + 1}. ${u.username}`);
-    });
-    console.log(`${users.length + 1}. Use Environment Variables (.env)`);
-
-    const selectedIndex = await new Promise((resolve) => {
-        const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout
-        });
-
-        const ask = () => {
-            rl.question('\nEnter number: ', (answer) => {
-                const num = parseInt(answer);
-                if (!isNaN(num) && num >= 1 && num <= users.length + 1) {
-                    rl.close();
-                    resolve(num - 1);
-                } else {
-                    console.log('Invalid selection. Try again.');
-                    ask();
-                }
-            });
-        };
-        ask();
-    });
-
-    if (selectedIndex === users.length) {
-        logger.info("Selected: Environment Variables");
-        return null; // Fallback to env
-    }
-
-    const selectedUser = users[selectedIndex];
-    logger.info(`Selected user: ${selectedUser.username}`);
-    return selectedUser;
-}
-
-module.exports = { selectUser };