@ubaidbinwaris/linkedin 1.1.7 → 2.0.0

package/Readme.md

@@ -1,55 +1,85 @@
-# LinkedIn Session Manager & Automation Service (v2.0.0)
+# @ubaidbinwaris/linkedin - Enterprise Automation Service
 
-A robust, deterministic backend service foundation for managing multiple LinkedIn accounts with strict concurrency control and session isolation. 
+![Version](https://img.shields.io/npm/v/@ubaidbinwaris/linkedin?style=flat-square)
+![License](https://img.shields.io/npm/l/@ubaidbinwaris/linkedin?style=flat-square)
+![Node](https://img.shields.io/node/v/@ubaidbinwaris/linkedin?style=flat-square)
 
-> **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.
+A professional, deterministic backend service library for managing multiple LinkedIn accounts with strict concurrency control, session isolation, and enterprise-grade security.
 
-## Core Features
+> **v1.1.7 Update**: Introduces "Smart Mobile Verification" with Visible Browser Fallback.
 
-- **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).
+## 🚀 Key Features
 
-## Installation
+*   **🛡️ Multi-User Concurrency**: Built-in `SessionLock` prevents race conditions. Impossible to double-login the same user.
+*   **🔒 Enterprise Security**:
+    *   Sessions stored as `SHA-256` hashed filenames (GDPR/Privacy friendly).
+    *   Data encrypted with `AES-256-CBC` before storage.
+*   **🧠 Smart Validation**:
+    *   Caches validation checks for 10 minutes to minimize ban risk from excessive reloading.
+    *   Automatically refreshes stale sessions.
+*   **📱 Mobile & Fallback Support**:
+    *   **Phase 1**: Detects "Open LinkedIn App" prompt and waits 2 minutes for user approval.
+    *   **Phase 2**: If mobile fails, automatically launches a **Visible Browser** for manual intervention.
 
-```bash
-npm install @ubaidbinwaris/linkedin
-```
+## 🏗️ Architecture
 
-## Architecture
+The library follows a strict **Fail-Fast** or **Resolution** flow. It does not use "stealth" plugins, relying instead on standard browser behavior and human intervention protocols.
 
 ```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)]
+sequenceDiagram
+    participant API as API/Worker
+    participant Pkg as LinkedIn Package
+    participant Browser as Playwright
+    participant Store as Session Store
+
+    API->>Pkg: loginToLinkedIn(email, pass)
+    Pkg->>Pkg: Acquire Lock (SessionLock)
+    alt is Locked
+        Pkg-->>API: Throw BUSY Error
+    end
+
+    Pkg->>Browser: Launch (Headless)
+    Pkg->>Store: Load Context
+    
+    alt Session Valid & Recent
+        Pkg-->>API: Return Page (Skip Feed)
+    else Session Stale/Invalid
+        Pkg->>Browser: Goto Feed
+        
+        alt Login Required
+            Pkg->>Browser: Fill Credentials
+            Pkg->>Browser: Submit
+            
+            opt Checkpoint Detected
+                Pkg->>Browser: Check Mobile Prompt
+                alt Mobile Prompt Found
+                    Pkg->>Pkg: Wait 2 Mins for Feed URL
+                end
+                
+                alt Mobile Failed
+                    Pkg->>Browser: Close Headless
+                    Pkg->>Browser: Launch VISIBLE Browser
+                    Pkg->>Browser: Re-Fill Credentials
+                    Pkg->>Pkg: Wait for Manual Use
+                end
+            end
+        end
+        
+        Pkg->>Store: Save Session (Encrypted)
+        Pkg-->>API: Return Page
+    end
 ```
 
-## Usage
+## 📦 Installation
 
-### Basic Login
+```bash
+npm install @ubaidbinwaris/linkedin
+```
 
-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.
+## 💻 Usage
+
+### 1. Basic Implementation
+The simplest way to use the package. Locks and session management are handled automatically.
 
 ```javascript
 const { loginToLinkedIn } = require('@ubaidbinwaris/linkedin');
@@ -57,59 +87,70 @@ const { loginToLinkedIn } = require('@ubaidbinwaris/linkedin');
 (async () => {
     try {
         const { browser, page } = await loginToLinkedIn({
-            headless: true
+            headless: true // Will auto-switch to false if fallback needed
         }, {
-            username: 'user@example.com',
-            password: 'secret-password'
+            username: 'alice@example.com',
+            password: 'secure_password'
         });
 
-        console.log("Logged in and active!");
+        console.log("✅ Logged in successfully!");
         
-        // Output session status
-        console.log(`Needs Validation? ${page.context().needsValidation}`);
+        // ... Perform scraping/automation tasks ...
 
-        // 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.");
+            console.error("❌ Critical: Account requires manual ID verification.");
+        } else if (err.message.includes('BUSY')) {
+            console.error("⚠️  User is already running a task.");
         } else {
-            console.error("Login failed:", err);
+            console.error("Error:", err.message);
         }
     }
 })();
 ```
 
-### Custom Session Storage
-
-You can link this to a database (Redis/Postgres) instead of local files.
+### 2. Custom Storage (Database Integration)
+By default, sessions are saved to `./sessions`. Override this to use Redis, MongoDB, or PostgreSQL.
 
 ```javascript
 const { setSessionStorage } = require('@ubaidbinwaris/linkedin');
 
 setSessionStorage({
     read: async (email) => {
-        // Fetch encrypted string from DB
-        return await db.sessions.findOne({ where: { email } });
+        // Return encrypted JSON string from your DB
+        const result = await db.query('SELECT session_data FROM users WHERE email = $1', [email]);
+        return result.rows[0]?.session_data; 
     },
     write: async (email, data) => {
-        // Save encrypted string to DB
-        await db.sessions.upsert({ email, data });
+        // Save encrypted JSON string to your DB
+        await db.query('UPDATE users SET session_data = $1 WHERE email = $2', [data, email]);
     }
 });
 ```
 
-## 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.
+### 3. Custom Logger
+Pipe internal logs to your own system (e.g., Winston, UI Stream).
+
+```javascript
+const { setLogger } = require('@ubaidbinwaris/linkedin');
+
+setLogger({
+    info: (msg) => console.log(`[LI-INFO] ${msg}`),
+    warn: (msg) => console.warn(`[LI-WARN] ${msg}`),
+    error: (msg) => console.error(`[LI-ERR] ${msg}`)
+});
+```
+
+## 🚨 Error Reference
+
+| Error Message | Meaning | Handling Action |
+| :--- | :--- | :--- |
+| `CHECKPOINT_DETECTED` | Security challenge (ID upload/Captcha) could not be resolved. | Notify admin. Manual Login required. |
+| `CHECKPOINT_DETECTED_M` | Manual Fallback (Visible Browser) timed out. | User didn't interact in time. Retry. |
+| `BUSY: ...` | A task is already running for this email. | Queue the request or reject it. |
+| `LOGIN_FAILED` | Credentials accepted, but session could not be verified. | Check proxy/network. |
+
+## License
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubaidbinwaris/linkedin",
-  "version": "1.1.7",
+  "version": "2.0.0",
   "description": "",
   "main": "index.js",
   "files": [

package/LICENSE

@@ -1,21 +0,0 @@
-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.