entrox-bypass 0.2.0 → 0.3.0

package/README.md

@@ -1,215 +1,287 @@
-# playwright-captcha
+# ⚡ entrox-bypass
 
-> AI-powered automated CAPTCHA solving for Playwright browser automation
+> AI-Powered Browser Automation & CAPTCHA Bypass Solution
 
-[![npm version](https://img.shields.io/npm/v/playwright-captcha.svg)](https://www.npmjs.com/package/playwright-captcha)
+[![npm version](https://img.shields.io/npm/v/entrox-bypass.svg)](https://www.npmjs.com/package/entrox-bypass)
+[![npm downloads](https://img.shields.io/npm/dm/entrox-bypass.svg)](https://www.npmjs.com/package/entrox-bypass)
 [![License: ISC](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/typescript-%23007acc.svg)](https://www.typescriptlang.org/)
+[![Playwright](https://img.shields.io/badge/playwright-2EAD33?logo=playwright&logoColor=white)](https://playwright.dev/)
 
-Automated login & CAPTCHA solving built on [Playwright](https://playwright.dev/), [LangChain](https://www.langchain.com/), and Cloudinary. Solves CAPTCHAs in real-time using AI image recognition via OpenRouter (Google Gemma).
+Automated login, CAPTCHA solving, and browser automation — enhanced with AI-powered image recognition, proxy rotation, human-like behavior simulation, and webhook notifications.
 
-## Features
+## 🚀 Features
 
-- 🤖 **AI-Powered CAPTCHA Solving** — Uses LLMs to read and solve CAPTCHA images automatically
-- 🔐 **Automated Login Flow** — Full end-to-end browser automation with credentials
-- 📦 **Dual Module Support** — Works with both ESM (`import`) and CJS (`require`)
-- ✍️ **TypeScript First** — Full type definitions included
-- ☁️ **Cloudinary Integration** — Efficient image upload & processing pipeline
-- 🧩 **Modular Design** — Use individual functions or the full automation suite
+| Feature | Description |
+|---------|-------------|
+| 🤖 **AI CAPTCHA Solver** | Real-time CAPTCHA recognition using Google Gemma via OpenRouter |
+| 🔐 **Smart Login Flow** | Complete automation: fill, solve, submit with retries |
+| 🛡️ **Bot Detection Evasion** | Human-like delays, randomized timing, anti-detection patterns |
+| 🌐 **Proxy Support** | HTTP/SOCKS proxy with authentication and optional rotation |
+| 🔄 **Auto-Retry** | Exponential backoff retry on failures (configurable attempts) |
+| 💾 **Session Persistence** | Save/restore cookies across sessions |
+| 📹 **Video Recording** | Optional MP4 recording of entire automation flow |
+| 🔔 **Webhook Alerts** | Discord/webhook notifications on success/failure |
+| ☁️ **Cloudinary Integration** | Efficient image upload and CDN delivery |
+| 📦 **Dual Module** | Full ESM + CJS compatibility |
+| ✍️ **TypeScript First** | Comprehensive type definitions included |
 
-## Installation
+## 📦 Installation
 
 ```bash
-npm install playwright-captcha playwright
+# Install package + Playwright
+npm install entrox-bypass playwright
 npx playwright install chromium
 ```
 
-## Quick Start
+## 🛠 Quick Start
 
-### Environment Variables
+### 1. Configure Environment Variables
 
-Create a `.env` file with your credentials:
+Create a `.env` file:
 
 ```env
-# Required: Login credentials
+# Authentication
 EMAIL=your_email@example.com
 PASSWORD=your_password
 
-# Required: AI CAPTCHA solver
+# AI Model (OpenRouter)
 OPENROUTER_API_KEY=sk-or-v1-your-api-key
 
-# Required: Image hosting
+# Image Upload (Cloudinary)
 CLOUDINARY_CLOUD_NAME=your_cloud_name
 CLOUDINARY_API_KEY=your_api_key
 CLOUDINARY_API_SECRET=your_api_secret
 ```
 
-### Full Automated Login
+### 2. Basic Automated Login
 
-```javascript
-import { automateLogin } from 'playwright-captcha';
+```typescript
+import { automateLogin } from 'entrox-bypass';
 
-(async () => {
-  const result = await automateLogin({
-    url: 'https://example.com/login',
-    headless: false,                    // Set true for server environments
-    outputScreenshotPath: './result.png' // Optional screenshot after login
-  });
+const result = await automateLogin({
+  url: 'https://example.com/login',
+});
 
-  if (result.success) {
-    console.log('Logged in successfully!');
-    console.log('Current URL:', result.url);
-    console.log('Page title:', result.title);
-  } else {
-    console.error('Login failed:', result.error);
-  }
-})();
+if (result.success) {
+  console.log('✅ Logged in:', result.url);
+} else {
+  console.error('❌ Failed:', result.error);
+}
 ```
 
-### Solve CAPTCHA Manually
-
-```javascript
-import { chromium } from 'playwright';
-import { solveCaptchaFromPage } from 'playwright-captcha';
-
-const browser = await chromium.launch();
-const page = await browser.newPage();
+### 3. Advanced Configuration (All Features)
 
-await page.goto('https://example.com/login');
-// ... fill form fields ...
-
-// Extract CAPTCHA text from the page
-const captcha = await solveCaptchaFromPage(page);
-console.log('CAPTCHA text:', captcha.text);       // e.g., "X7K9P"
-console.log('Description:', captcha.description);
-
-await browser.close();
+```typescript
+import { automateLogin } from 'entrox-bypass';
+
+const result = await automateLogin({
+  url: 'https://secure-site.com/login',
+  
+  // Override credentials
+  email: 'user@test.com',
+  password: 'secret123',
+  
+  // Anti-detection
+  headless: true,
+  delayRange: { min: 800, max: 2500 },
+  
+  // Retry on failure
+  retryCount: 3,
+  baseRetryDelay: 1500,
+  
+  // Proxy support
+  proxy: {
+    server: 'http://proxy.example.com:8080',
+    username: 'proxy-user',
+    password: 'proxy-pass',
+  },
+  
+  // Session persistence
+  cookieFile: './cookies.json',
+  
+  // Video recording
+  videoPath: './recording.mp4',
+  
+  // Webhook notifications
+  webhookUrl: 'https://discord.com/api/webhooks/xxxxx/yyyyyy',
+  
+  // Output
+  outputScreenshotPath: './success.png',
+});
 ```
 
-## API Reference
+## 📖 API Reference
 
 ### `automateLogin(options)`
 
-Automates the entire login process including CAPTCHA solving.
-
-**Parameters:**
-
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `url` | `string` | ✅ Yes | — | Target login page URL |
-| `loginSelector` | `string` | ❌ No | `#login` | CSS selector for email/login field |
-| `passwordSelector` | `string` | ❌ No | `#password` | CSS selector for password field |
-| `captchaInputSelector` | `string` | ❌ No | `#captcha` | CSS selector for CAPTCHA input field |
-| `submitButtonSelector` | `string` | ❌ No | `button[type='submit']` | CSS selector for submit button |
-| `headless` | `boolean` | ❌ No | `false` | Run browser in headless mode |
-| `outputScreenshotPath` | `string` | ❌ No | — | Path to save post-login screenshot |
-| `screenshotDelay` | `number` | ❌ No | — | Milliseconds to wait before screenshot |
-
-**Returns:** `Promise<LoginResult>`
+Full end-to-end automated login with AI CAPTCHA solving.
 
 ```typescript
+interface LoginOptions {
+  // Required
+  url: string;
+  
+  // Credentials (override env vars)
+  email?: string;
+  password?: string;
+  
+  // Selectors
+  loginSelector?: string;        // default: '#login'
+  passwordSelector?: string;     // default: '#password'
+  captchaInputSelector?: string; // default: '#captcha'
+  submitButtonSelector?: string; // default: "button[type='submit']"
+  
+  // Browser config
+  headless?: boolean;            // default: false
+  
+  // Anti-detection
+  delayRange?: {
+    min: number;  // min delay ms between actions
+    max: number;  // max delay ms between actions
+  };
+  
+  // Retry logic
+  retryCount?: number;           // default: 2
+  baseRetryDelay?: number;       // default: 1000 (ms)
+  
+  // Proxy
+  proxy?: {
+    server: string;
+    username?: string;
+    password?: string;
+  };
+  
+  // Session
+  cookieFile?: string;           // Path to save/restore cookies
+  
+  // Recording
+  videoPath?: string;            // Path for MP4 recording
+  
+  // Notifications
+  webhookUrl?: string;           // Discord/webhook URL
+  
+  // Output
+  outputScreenshotPath?: string; // Post-login screenshot path
+}
+
 interface LoginResult {
   success: boolean;
   url: string;
   title: string;
-  page: Page;           // Playwright page instance (for further interactions)
-  error?: string;       // Error message if failed
+  page: Page;                    // Playwright Page instance
+  error?: string;
 }
 ```
 
----
+**Returns:** `Promise<LoginResult>`
 
-### `solveCaptchaFromPage(page, captchaSelector, outputScreenshotPath?)`
+---
 
-Extracts and solves a CAPTCHA image displayed on the page using AI.
+### `solveCaptchaFromPage(page, options?)`
 
-**Parameters:**
+Extract text from CAPTCHA images using AI recognition.
 
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `page` | `Page` | ✅ Yes | — | Playwright Page instance |
-| `captchaSelector` | `string` | ❌ No | `img.captcha-image` | CSS selector for the CAPTCHA image |
-| `outputScreenshotPath` | `string` | ❌ No | — | Path to save CAPTCHA screenshot |
+```typescript
+async function solveCaptchaFromPage(
+  page: Page,
+  captchaSelector?: string,       // default: 'img.captcha-image'
+  options?: {
+    outputScreenshotPath?: string;
+    maxRetries?: number;          // default: 3
+    retryDelayMs?: number;        // default: 1000
+    timeoutMs?: number;           // default: 30000
+  }
+): Promise<CaptchaResult>;
+```
 
 **Returns:** `Promise<CaptchaResult>`
 
 ```typescript
 interface CaptchaResult {
-  text: string;         // The extracted CAPTCHA text (e.g., "X7K9P")
-  description: string;  // Brief description of the image content
+  text: string;         // Extracted text (e.g., 'X7K9P')
+  description: string;  // Image description
 }
 ```
 
 ---
 
-## Customization
+### Utility Functions
 
-### Change AI Model
+#### `humanDelay`
+Randomized delay utility for bot detection evasion.
 
-```env
-# In your .env file
-LLM_MODEL=google/gemma-4-26b-a4b-it
-```
+```typescript
+import { humanDelay } from 'entrox-bypass';
 
-Supported models (via OpenRouter):
-- `google/gemma-4-26b-a4b-it` (default)
-- `openai/gpt-4o`
-- `anthropic/claude-3.5-sonnet`
-- See [OpenRouter](https://openrouter.ai/models) for more options
+await humanDelay.randomBetween(500, 1500);  // Random delay 0.5-1.5s
+```
 
-### Custom Selectors
+#### `retry`
+Exponential backoff retry wrapper.
 
-If your login page uses different element selectors:
+```typescript
+import { retry } from 'entrox-bypass';
 
-```javascript
-await automateLogin({
-  url: 'https://example.com/signin',
-  loginSelector: '#email-input',
-  passwordSelector: '#password-input',
-  captchaInputSelector: '#captcha-code',
-  submitButtonSelector: '.btn-signin'
+const result = await retry(async () => fetchSomeData(), {
+  maxAttempts: 5,
+  delayMs: 1000,
+  multiplier: 2,
 });
 ```
 
-## Architecture
+## 🌍 Supported LLM Models
 
-```
-┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────┐
-│ Playwright  │───▶│ Cloudinary   │───▶│ OpenRouter   │───▶│   JSON   │
-│ Browser     │    │ (Upload IMG) │    │ (Gemma LLM)  │    │ Response │
-└─────────────┘    └──────────────┘    └─────────────┘    └──────────┘
-        │                                                       │
-        ▼                                                       ▼
-┌─────────────┐                                      ┌──────────────────┐
-│ Fill Form   │◀─────────────────────────────────────│ Extract Text     │
-│ Submit      │                                      └──────────────────┘
-└─────────────┘
+All models via [OpenRouter](https://openrouter.ai):
+
+| Model | Recommended For |
+|-------|-----------------|
+| `google/gemma-4-26b-a4b-it` | CAPTCHA text extraction (default) |
+| `openai/gpt-4o` | Complex visual puzzles |
+| `anthropic/claude-3.5-sonnet` | High accuracy tasks |
+| `meta-llama/llama-3.2-11b-vision-instruct` | Balanced speed/accuracy |
+
+Change model in `.env`:
+```env
+LLM_MODEL=openai/gpt-4o
 ```
 
-## Error Handling
+## 🔒 Security & Best Practices
 
-All functions throw descriptive errors:
+- ✅ **Never commit `.env`** — Use `.env.example` as template
+- ✅ **Use headless mode** on production servers
+- ✅ **Set appropriate timeouts** to prevent hanging
+- ✅ **Respect terms of service** — Only automate sites you own or have permission to test
+- ✅ **Rotate user agents/proxies** when making many requests
 
-```javascript
-try {
-  await automateLogin({ url: 'https://example.com/login' });
-} catch (error) {
-  if (error.name === 'LlmError') {
-    console.error('AI service error:', error.message);
-  } else if (error.name === 'CloudinaryError') {
-    console.error('Upload failed:', error.message);
-  } else {
-    console.error('Browser automation error:', error.message);
-  }
-}
+## 🏗 Architecture
+
+```
+┌─────────────┐    ┌──────────────┐    ┌──────────────┐    ┌─────────────┐
+│  Playwright │───▶│  Cloudinary  │───▶│  OpenRouter   │───▶│  AI Parser  │
+│  Browser    │    │  (Upload)    │    │  (LLM Model)  │    │  JSON Out   │
+└─────────────┘    └──────────────┘    └──────────────┘    └─────────────┘
+        │                                                      │
+        ▼                                                      ▼
+┌─────────────────┐                              ┌──────────────────────┐
+│ Fill Form Fields │◀────────────────────────────│ Extract Text Content │
+│ Submit Actions   │                             └──────────────────────┘
+│ Cookie Handling  │
+│ Webhook Alerts   │
+│ Video Recording  │
+└─────────────────┘
 ```
 
-## Development
+## 🧪 Development
 
 ```bash
-# Clone and install dependencies
-git clone <repo-url>
-cd playwright-captcha
+# Clone repository
+git clone https://github.com/dev-sajid007/entrox-bypass.git
+cd entrox-bypass
+
+# Install dependencies
 npm install
+npx playwright install chromium
 
 # Build bundles (ESM + CJS)
 npm run build
@@ -217,34 +289,61 @@ npm run build
 # Run tests
 npm test
 
-# TypeScript type checking
+# Type checking
 npx tsc --noEmit
+
+# Watch mode during development
+npm run dev
 ```
 
-## Project Structure
+### Project Structure
 
 ```
-playwright-captcha/
+entrox-bypass/
 ├── src/
-│   ├── index.ts          # Public API exports
-│   ├── login.ts          # automateLogin implementation
-│   ├── captchaSolve.ts   # CAPTCHA extraction & solving
-│   ├── cloudinary.ts     # Cloudinary upload config
-│   └── llm.ts            # OpenRouter / Gemma integration
+│   ├── index.ts                # Public API exports
+│   ├── login.ts                # automateLogin implementation
+│   ├── captchaSolve.ts         # CAPTCHA extraction pipeline
+│   ├── cloudinary.ts           # Cloudinary configuration
+│   ├── llm.ts                  # OpenRouter LLM integration
+│   └── utils/
+│       ├── humanDelay.ts       # Bot-evasion timing utilities
+│       └── retry.ts            # Exponential backoff retry logic
 ├── types/
-│   └── index.d.ts        # TypeScript declarations
-├── dist/                 # Built packages (ESM + CJS)
-└── test/                 # Test suite
+│   └── index.d.ts              # TypeScript declarations
+├── dist/                       # Bundled output (published)
+├── test/                       # Jest test suite
+├── .env.example                # Environment template
+├── tsup.config.ts              # Bundle configuration
+└── package.json
 ```
 
-## License
+## 📊 Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 0.3.0 | 2026-10-25 | Added proxy, retry, webhooks, video recording, session persistence |
+| 0.2.0 | 2026-10-25 | Package rename, enhanced AI model support |
+| 0.1.0 | 2026-10-25 | Initial release |
+
+## 📄 License
+
+ISC — Feel free to use in personal and commercial projects.
+
+## 🤝 Contributing
+
+Contributions welcome! Please:
 
-ISC
+1. Fork the repository
+2. Create a feature branch (`feat/your-feature`)
+3. Write tests for new functionality
+4. Ensure all tests pass (`npm test`)
+5. Submit a pull request
 
-## Contributing
+## ⚠️ Disclaimer
 
-Contributions, issues, and feature requests are welcome! Feel free to submit a PR.
+Always obtain proper authorization before automating interactions with any website. Respect robots.txt, rate limits, and terms of service. This tool is designed for legitimate testing and automation purposes only.
 
 ---
 
-> ⚠️ **Note**: Always use this library responsibly. Ensure you have authorization to automate interactions with any website you're targeting. Respect robots.txt and terms of service.
+**Built with ❤️ using Playwright, LangChain, Cloudinary & OpenRouter**