Metadata-Version: 2.4
Name: undetected-playwright-ecom
Version: 1.6.0
Summary: Undetected Playwright for media buyers — scale Facebook/TikTok/Google ads & Shopify without fingerprint bans. Multilogin CDP.
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,undetected,antidetect,multilogin,cdp,cloudflare,turnstile,datadome,perimeterx,kasada,akamai,shopify,stripe,dropshipping,amazon,ebay,ecommerce,sneaker-bot,ticket-bot,nft,crypto,airdrop,web3,instagram,tiktok,facebook,linkedin,twitter,social-media,web-scraping,price-monitoring,serp,seo,affiliate,cpa,bot-bypass,fingerprint,webdriver,human-behavior,automation,media-buyer,facebook-ads,tiktok-ads,google-ads,business-manager,ad-account-disabled,dropshipping-ads,payment-hold
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.**

> **Cho media buyer / người chạy ads:** BM bị restrict? Shopify hold? Stripe đóng?  
> `pip install undetected-playwright-ecom` → `stealth-ecom onboard` → [Multilogin SAAS50](https://t.me/Multilogin_Scripts_Bot)

![Build Passing](https://img.shields.io/badge/build-passing-brightgreen)
![PyPI Version](https://img.shields.io/badge/pypi-1.6.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 built for **media buyers, dropshippers, and affiliate runners** who scale Facebook/TikTok/Google ads and need automation that doesn't leak fingerprints. Connect Playwright to Multilogin X over CDP — survive ad account reviews, Shopify payment holds, and Stripe Radar.

---

## For Media Buyers — Your Search → Our Solution

| You Google this… | This package does… |
|------------------|-------------------|
| `facebook ad account disabled` | `MediaBuyerToolkit.warmup_account(FACEBOOK)` |
| `run multiple facebook ad accounts` | 1 Multilogin profile per account + `scale_checklist()` |
| `shopify payments on hold` | `ShopifyCheckoutHelper` + stealth fingerprint |
| `multilogin playwright automation` | `StealthSession` + `stealth-ecom doctor` |
| `tiktok ads account suspended` | Platform preset warmup + ban signal scan |

```bash
stealth-ecom onboard          # see your buyer journey + next steps
stealth-ecom doctor --json    # pre-flight before spending ad budget
python examples/facebook_ads_account_warmup.py
```

Full journey map: **[docs/ADS_RUNNER_JOURNEY.md](docs/ADS_RUNNER_JOURNEY.md)**

---

## 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 |
| `AsyncStealthBrowser` | Async CDP connector for concurrent pipelines |
| `StealthBrowser` | Sync CDP connector for Multilogin X stealth profiles |
| `BanDetector` | Detect Cloudflare / Datadome / Shopify hard blocks |
| `ShopifyCheckoutHelper` | Human-type checkout fields with auto selector map |
| `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 |
| `retry_on_failure` | Exponential-backoff retry decorator |
| `StealthLogger` | Color-coded enterprise telemetry |
| `stealth-ecom niches` | **25+ buyer niches** with SEO keywords & Multilogin CTAs |
| `ProfilePool` | Scale N Multilogin profiles (multi CDP port) |
| `StealthConfig` | JSON config for profiles, proxies, cookies |
| `AffiliateContentGenerator` | Auto-generate Telegram/SEO affiliate posts |
| `stealth-ecom` CLI | `warmup`, `content`, `config-init`, `onboard`, `doctor` |

---

## Industry Niches — Every Multilogin Buyer Persona

`undetected-playwright-ecom` targets **every search intent** that leads to antidetect browser adoption. Run `stealth-ecom niches` to list all clusters.

### E-Commerce & Payments
| Niche | Search keywords | Example |
|-------|-----------------|---------|
| Shopify / Dropshipping | `shopify checkout automation`, `stripe radar bypass` | `shopify_checkout_automation.py` |
| Amazon Seller | `amazon seller automation`, `seller central bot` | `amazon_seller_automation.py` |
| eBay / Walmart | `ebay automation playwright`, `marketplace multi account` | — |

### WAF / Anti-Bot Bypass
| Niche | Search keywords | Example |
|-------|-----------------|---------|
| Cloudflare Turnstile | `cloudflare turnstile bypass python`, `playwright cloudflare` | `bypass_cloudflare_turnstile.py` |
| Datadome | `datadome bypass python`, `datadome playwright` | `datadome_bypass_playwright.py` |
| PerimeterX / Kasada | `perimeterx bypass`, `kasada python` | — |

### Hype & Limited Drops
| Niche | Search keywords | Example |
|-------|-----------------|---------|
| Sneaker bots | `sneaker bot python`, `snkrs bot`, `shopify drop bot` | `sneaker_drop_monitor.py` |
| Ticket drops | `ticketmaster bot`, `ticket bot playwright` | — |
| NFT / Crypto mint | `nft mint bot`, `airdrop farmer python` | `crypto_airdrop_farmer.py` |

### Social Media Automation
| Niche | Search keywords | Example |
|-------|-----------------|---------|
| Instagram | `instagram automation playwright`, `insta multi account` | `instagram_stealth_login.py` |
| TikTok | `tiktok bot python`, `tiktok account warmup` | `tiktok_account_warmup.py` |
| LinkedIn | `linkedin automation`, `linkedin outreach bot` | `linkedin_outreach_automation.py` |
| Facebook / X | `facebook ads automation`, `twitter bot python` | — |

### Scraping & Data
| Niche | Search keywords | Example |
|-------|-----------------|---------|
| Web scraping | `playwright scraping stealth`, `undetected scraper` | `web_scraping_stealth.py` |
| Price monitoring | `price monitoring bot`, `competitor scraper` | — |
| Google SERP / SEO | `serp checker python`, `google scraping stealth` | — |

### Marketing & Growth
| Niche | Search keywords | Promo |
|-------|-----------------|-------|
| Affiliate / CPA | `cpa funnel automation`, `affiliate bot python` | SAAS50 |
| Account farming | `account farming python`, `multi account browser` | SAAS50 + MIN50 |
| SMS / OTP verify | `sms verification bot`, `otp automation` | MIN50 |

Full playbook: **[docs/NICHE_PLAYBOOK.md](docs/NICHE_PLAYBOOK.md)**

```bash
stealth-ecom niches --search shopify
stealth-ecom niches --id cloudflare-turnstile
```

---

## 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.ban_detector.raise_if_blocked()
    session.human.human_click("button.add-to-cart")
    session.shopify.detect_checkout_ready()
    session.watcher.wait_for_turnstile(timeout_s=30)
```

### CLI

```bash
pip install undetected-playwright-ecom
stealth-ecom config-init --profiles 5
stealth-ecom warmup --platform facebook --port 35000
stealth-ecom content --niche media-buyer-scale
stealth-ecom content --query facebook --lang vi
stealth-ecom doctor --json
```

### 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` | Cloudflare Turnstile bypass |
| `examples/datadome_bypass_playwright.py` | Datadome bypass demo |
| `examples/shopify_checkout_automation.py` | Shopify checkout `human_type` |
| `examples/amazon_seller_automation.py` | Amazon Seller Central stealth |
| `examples/sneaker_drop_monitor.py` | Sneaker / hype drop monitor |
| `examples/instagram_stealth_login.py` | Instagram multi-account login |
| `examples/tiktok_account_warmup.py` | TikTok warmup scroll patterns |
| `examples/linkedin_outreach_automation.py` | LinkedIn outreach stealth |
| `examples/crypto_airdrop_farmer.py` | Crypto airdrop / sybil isolation |
| `examples/web_scraping_stealth.py` | Undetected web scraping |
| `examples/verify_stealth_score.py` | Pre-flight fingerprint probe |
| `examples/facebook_ads_account_warmup.py` | **Media buyer** FB warmup + health check |
| `examples/media_buyer_scale_playbook.py` | Multi-platform scale playbook |
| `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.6.0
git push origin v1.6.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)**
