# 👻 Ghost Node — Auction Sniper

A modular, multi-threaded auction sniper for Windows 11 with human-mimicry,
Telegram C2 command, and a cyber-terminal dashboard.

---

## Architecture

```
worker.py
├── Thread A  — FastAPI + Dashboard (port 7000)
├── Thread B  — Async Playwright Scraper (nuclear_engine)
└── Thread C  — Telegram C2 Command Listener
```

## File Structure

```
ghost_node/
├── database.py       # SQLAlchemy engine & session factory
├── models.py         # ORM models, heuristic scoring, DB seeder
├── worker.py         # FastAPI routes + scraper + Telegram C2
├── dashboard.html    # Cyberpunk terminal UI (5 tabs)
├── requirements.txt
└── README.md
```

---

## Installation (Windows 11, Python 3.11+)

```powershell
# 1. Create virtual environment
python -m venv .venv
.venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Install Chromium for Playwright
playwright install chromium

# 4. Launch Ghost Node
python worker.py
```

Then open: **http://localhost:7000**

---

## Quick Setup via Dashboard

1. **Settings tab** — Enter your Telegram Bot Token and Chat ID, set cycle timer.
2. **Keywords tab** — Your top search terms are pre-seeded (RTX 4090, Tab S10, etc.).
3. **Target Sites tab** — eBay UK and eBay US are pre-seeded with `{keyword}` templates.
4. The engine starts automatically — watch the Dashboard for live stats.
5. Optional resilience features — per-site visible override (`custom_visible_browser`, ignored when global `show_browser=true`) plus keyword batching with pinned “Keyword Retry Tracking” in the dashboard.

---

## Retry Tracking Mechanics

- Per-site visibility precedence:
  - `show_browser=true` forces visible mode for all sites and ignores per-site `custom_visible_browser`.
  - `show_browser=false` applies per-site visibility (`custom_visible_browser=1` visible, `0` headless).
- Keyword batching is controlled by `keyword_batch_enabled`.
- Persistent retry state is stored in `scrape_rounds` + `scrape_round_items` with statuses:
  `pending`, `in_progress`, `done`, `failed`.
- Pending retries have a 4-hour window per active round; expired pending/in-progress items are marked failed.
- The dashboard "Keyword Retry Tracking" section is sourced from `GET /api/scrape/progress`.
  - Pinned items are pending retries with `attempt_count > 0`.
  - Hourly warning due-state is returned as `warn_due` using `last_hour_warn_at` fallback logic (`first_pending_at`, then round start).

---

## Telegram C2 Commands

| Command     | Action                                      |
|-------------|---------------------------------------------|
| `/status`   | Node health report (engine, uptime, alerts) |
| `/pause`    | Pause the scraper engine                    |
| `/resume`   | Resume the scraper engine                   |
| `/listings` | Last 5 captured listings                    |

---

## Heuristic Scoring

**Positive (+10):** GB, RAM, Unlocked, SSD, RTX, GPU, S10, NVMe, OLED  
**Negative (−10):** Cover, Case, Sleeve, Box Only, Broken, For Parts, Faulty

Only listings with **score ≥ 0** trigger Telegram alerts.  
Keyword weight multiplies the base score.

---

## Baghdad Network Optimisations

- 60-second global page timeout per navigation
- Per-site try/except — one timeout never crashes the full cycle
- Resource blocking (images/fonts/videos) for faster loads
- 5–15s randomised jitter between keywords

---

## Adding New Sites

In the **Target Sites** tab:
- **Name**: Human label (e.g. `Gumtree UK`)
- **URL Template**: Full search URL with `{keyword}` placeholder  
  e.g. `https://www.gumtree.com/search?search_category=all&q={keyword}`
- **Search Selector**: CSS selector for the search box (leave blank to use URL directly)

---

## Notes

- `sniper.db` is created automatically in the working directory on first run.
- All config (Telegram token, timer) is persisted to SQLite on every Save.
- Playwright-stealth is implemented via `add_init_script` to avoid detection.
- Rotating user-agents are applied per browser context (one context per site per cycle).