Metadata-Version: 2.4
Name: undetected-playwright-ecom
Version: 1.2.0
Summary: Enterprise-grade Playwright wrapper for e-commerce automation with stealth CDP integration.
Home-page: https://t.me/Multilogin_Scripts_Bot
Author: Enterprise Automation Infra
License-Expression: MIT
Project-URL: Homepage, https://t.me/Multilogin_Scripts_Bot
Project-URL: Repository, https://github.com/your-org/undetected-playwright-ecom
Keywords: playwright,stealth,automation,ecommerce,cloudflare,datadome,shopify
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.40.0
Requires-Dist: requests>=2.31.0
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# **Finally, a Playwright wrapper that survives E-commerce anti-bot probes.**

![Build Passing](https://img.shields.io/badge/build-passing-brightgreen)
![PyPI Version](https://img.shields.io/badge/pypi-1.2.0-blue)
![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)

**`undetected-playwright-ecom`** is a production-ready Python library that connects Playwright to hardened browser profiles over CDP — built for checkout automation, inventory monitoring, and high-volume e-commerce workflows that must survive Cloudflare Turnstile, Datadome, Shopify, and Stripe fraud systems.

---

## The Problem

Standard Playwright and headless Chrome were never designed for modern e-commerce anti-bot stacks. When you launch a vanilla browser, several signals leak immediately:

| Signal | What happens |
|--------|----------------|
| `navigator.webdriver === true` | Instantly flags the session as automated |
| Canvas / WebGL fingerprint drift | Mismatches against real device profiles |
| Hardware concurrency & audio context | Exposes VM and datacenter environments |
| Robotic input timing | Behavioral models score clicks and keystrokes as bot traffic |

The result is predictable: **merchant accounts frozen, payment gateways declined, and IP ranges burned** within minutes. Rotating proxies alone does not fix this — fraud engines correlate TLS, GPU, and behavioral signals together. You need kernel-level fingerprint consistency *and* human-like interaction patterns.

---

## Stealth Architecture

`undetected-playwright-ecom` does not spawn detectable local Chromium. It attaches to an already-running stealth profile and routes your automation through it.

```mermaid
flowchart LR
    A[Automation Script] --> B[StealthBrowser Core]
    B --> C[Multilogin Local API<br/>Port 35000]
    C --> D[Target Site]

    style A fill:#1e293b,stroke:#38bdf8,color:#f8fafc
    style B fill:#0f172a,stroke:#22c55e,color:#f8fafc
    style C fill:#0f172a,stroke:#a855f7,color:#f8fafc
    style D fill:#1e293b,stroke:#f97316,color:#f8fafc
```

1. **Your script** calls `StealthBrowser.connect(port=35000)`.
2. **StealthBrowser Core** opens a CDP session via Playwright's `connect_over_cdp`.
3. **Multilogin Local API** serves a hardware-bound browser profile with spoofed fingerprints.
4. **Target Site** sees a consistent, human-grade session — not a datacenter bot.

---

## Features

| Module | Purpose |
|--------|---------|
| `StealthSession` | **All-in-one facade** — connect, navigate, audit, cookies |
| `StealthBrowser` | CDP connector for Multilogin X stealth profiles |
| `HumanEmulator` | Behavioral typing, scrolling, and Bézier clicking |
| `ChallengeWatcher` | Wait for Turnstile tokens / Datadome cookies |
| `SessionManager` | Proxy validation and cookie inject/extract |
| `FingerprintAuditor` | Programmatic WebGL + webdriver stealth scoring |
| `StealthLogger` | Color-coded enterprise telemetry |
| `stealth-ecom` CLI | Terminal tools: `verify`, `proxy`, `version` |

---

## Behavioral Stealth — Real Value, Not Theater

Anti-bot systems no longer rely on IP alone. They model **how** users interact. `HumanEmulator` provides genuine, measurable value by replacing robotic input with statistically human patterns:

### `human_type(selector, text)`

- Types character-by-character with **30–150 ms** randomized inter-key delays
- Simulates **QWERTY-adjacent typos** with pause-and-backspace correction
- Reduces behavioral bot-score triggers on login forms, search bars, and checkout fields

### `human_click(selector)`

- Approaches the target along a **cubic Bézier curve** with jittered control points
- Uses **18–42 micro-steps** with variable timing before clicking
- Clicks with slight offset from element center to avoid bot centroid detection

### `human_scroll()`

- Scrolls in **irregular pixel chunks** (80–320 px) with smooth motion
- Pauses **1–3 seconds** between scroll steps to mimic content reading
- Lowers session anomaly scores on long product pages and policy screens

```python
from undetected_playwright_ecom import StealthBrowser, HumanEmulator

browser = StealthBrowser()
session = browser.connect(port=35000)
page = session.contexts[0].pages[0]

human = HumanEmulator(page)
human.human_scroll()
human.human_type("input[name='email']", "buyer@example.com")
```

> Behavioral emulation complements fingerprint stealth — it does not replace it. Always run inside a Multilogin X profile.

---

## Installation

```bash
pip install undetected-playwright-ecom
playwright install chromium
```

> Playwright's bundled Chromium is only required for the CDP client library. Stealth sessions must execute inside Multilogin X.

---

## Quick Start

### One-liner facade (recommended)

```python
from undetected_playwright_ecom import StealthSession

with StealthSession(port=35000) as session:
    session.navigate("https://example-shop.com", audit=True, scroll=True)
    session.human.human_click("button.add-to-cart")
    session.watcher.wait_for_turnstile(timeout_s=30)
```

### CLI

```bash
pip install undetected-playwright-ecom
stealth-ecom verify --port 35000 --scroll
stealth-ecom proxy --proxy http://user:pass@host:8080
```

### Low-level API

```python
from undetected_playwright_ecom import StealthBrowser, StealthLogger

log = StealthLogger(component="Checkout")

try:
    with StealthBrowser() as stealth:
        stealth.connect(port=35000)
        page = stealth.get_page()
        page.goto("https://example-shop.com")
        log.success("Stealth session active")
except Exception as exc:
    log.critical(f"Session failed: {exc}")
```

### Verify your setup before going live

```bash
python examples/verify_stealth_score.py
```

Expected output when properly configured:

```text
[SUCCESS] 🛡️ Setup Secure. Enterprise Stealth Active.
```

---

## Enterprise Bypassing

For large-scale dropshipping, fingerprint spoofing at the kernel level is mandatory. We recommend **Multilogin X**.

- **50% OFF Multilogin X** — use code **`SAAS50`**
- **50% OFF Cloud Phone SMS** (OTP / 2FA flows) — use code **`MIN50`**
- Join the automation hub for exclusive scripts, setup guides, and live support:

**[https://t.me/Multilogin_Scripts_Bot](https://t.me/Multilogin_Scripts_Bot)**

| Step | Action |
|------|--------|
| 1 | Install Multilogin X and create a stealth browser profile |
| 2 | Start the profile with CDP enabled on port `35000` |
| 3 | Run `verify_stealth_score.py` to confirm `navigator.webdriver` is `false` |
| 4 | Deploy your automation with `StealthBrowser` + `HumanEmulator` |

---

## API Reference

```python
from undetected_playwright_ecom import (
    StealthBrowser,
    HumanEmulator,
    SessionManager,
    StealthLogger,
    StealthCoreNotDetectedError,
    FingerprintLeakWarning,
    ProxyLeakSecurityError,
)
```

| Class / Symbol | Description |
|----------------|-------------|
| `StealthBrowser.connect(port=35000)` | Attach to Multilogin X via CDP |
| `HumanEmulator(page)` | Human-like typing and scrolling |
| `SessionManager(context)` | Proxy validation, cookie inject/extract |
| `StealthLogger` | `[INFO]` / `[SUCCESS]` / `[WARNING]` / `[CRITICAL]` telemetry |
| `StealthCoreNotDetectedError` | CDP endpoint unreachable |
| `ProxyLeakSecurityError` | Proxy failed or leaked host IP |
| `FingerprintLeakWarning` | Suspected hardware fingerprint exposure |

---

## Examples

| Script | Description |
|--------|-------------|
| `examples/bypass_cloudflare_turnstile.py` | Turnstile-protected page with human scrolling |
| `examples/shopify_checkout_automation.py` | Checkout field automation with `human_type` |
| `examples/verify_stealth_score.py` | Pre-flight WebGL + webdriver probe |
| `examples/full_ecom_workflow.py` | End-to-end `StealthSession` demo |

---

## Requirements

| Component | Required |
|-----------|----------|
| Python 3.8+ (3.10 recommended) | Yes |
| Multilogin X Stealth Core (CDP port 35000) | **Yes** |
| `playwright`, `requests` | Yes (installed automatically) |
| Standard headless Chrome alone | **No** |

---

## Publishing to PyPI

### GitHub Actions (recommended)

1. Push repo to GitHub
2. Add secret **`PYPI_API_TOKEN`** in **Settings → Secrets → Actions**
3. Create a release tag:

```bash
git tag v1.2.0
git push origin v1.2.0
```

Or trigger manually: **Actions → Publish to PyPI → Run workflow** (type `publish`).

### Local publish (Windows)

```powershell
$env:PYPI_API_TOKEN = "pypi-YOUR_TOKEN"
.\scripts\publish.ps1
```

---

## Contributing

Pull requests and issue reports are welcome. Please run `examples/verify_stealth_score.py` against a Multilogin profile before submitting stealth-related changes.

---

## License

MIT © Enterprise Automation Infra

---

## Support the Project

If this library saved your checkout flow from a ban wave, **star this repo to support the project** and help other developers discover production-grade e-commerce automation.

For setup walkthroughs, discount codes, and the latest bypass playbooks, join the hub:

**[https://t.me/Multilogin_Scripts_Bot](https://t.me/Multilogin_Scripts_Bot)**
