Fix client for current Meta API and harden detection avoidance

- Fix __hsi regex extraction (key changed from "hsi" to "__hsi")
- Add retry logic to challenge POST with backoff
- Update Chrome versions to 140-145 in fingerprint pool
- Add curl_cffi TLS fingerprint impersonation (optional stealth dep)
- Add dynamic extraction for v parameter and x-asbd-id
- Fix typeahead endpoint: add required adType/isMobile variables,
  handle new dict response structure, update field name mapping
- Fix cookie iteration for curl_cffi compatibility
- Update fallback __rev token to current value
- Update docs: add stealth install option, fix architecture details,
  correct SEARCH_KEYWORD constant value, fix contributing clone URL

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: promisingcoder

README.md

@@ -55,12 +55,18 @@ With async support (requires [httpx](https://www.python-httpx.org/)):
 pip install meta-ads-collector[async]
 ```
 
+With stealth TLS fingerprinting (requires [curl_cffi](https://github.com/lexiforest/curl_cffi)):
+
+```bash
+pip install meta-ads-collector[stealth]
+```
+
 From source:
 
 ```bash
 git clone https://github.com/promisingcoder/MetaAdsCollector.git
 cd meta-ads-collector
-pip install -e ".[dev]"
+pip install -e ".[dev,async,stealth]"
 ```
 
 **Requirements:** Python 3.9+
@@ -79,7 +85,7 @@ pip install -e ".[dev]"
 - **Collection Reporting** -- summary statistics with throughput metrics
 - **Export Formats** -- JSON, CSV, JSONL
 - **Stream Mode** -- yield lifecycle events alongside ads through a single iterator
-- **Detection Avoidance** -- browser fingerprint randomization, dynamic token extraction, session management
+- **Detection Avoidance** -- browser fingerprint randomization, TLS fingerprint impersonation (via `curl_cffi`), dynamic token extraction, session management
 
 ---
 

docs/api-reference.md

@@ -62,7 +62,7 @@ Search for ads and yield results as an iterator.
 | `country` | `str` | `"US"` | ISO 3166-1 alpha-2 country code |
 | `ad_type` | `str` | `"ALL"` | Ad type filter (`"ALL"`, `"POLITICAL_AND_ISSUE_ADS"`, `"HOUSING_ADS"`, `"EMPLOYMENT_ADS"`, `"CREDIT_ADS"`) |
 | `status` | `str` | `"ACTIVE"` | Status filter (`"ACTIVE"`, `"INACTIVE"`, `"ALL"`) |
-| `search_type` | `str` | `"KEYWORD_EXACT_PHRASE"` | Search type (`"KEYWORD_EXACT_PHRASE"`, `"KEYWORD_UNORDERED"`, `"PAGE"`) |
+| `search_type` | `str` | `"KEYWORD_UNORDERED"` | Search type (`"KEYWORD_EXACT_PHRASE"`, `"KEYWORD_UNORDERED"`, `"PAGE"`) |
 | `page_ids` | `list[str] \| None` | `None` | Filter by specific page IDs |
 | `sort_by` | `str \| None` | `"SORT_BY_TOTAL_IMPRESSIONS"` | Sort order (`"SORT_BY_TOTAL_IMPRESSIONS"` or `None` for relevancy) |
 | `max_results` | `int \| None` | `None` | Maximum ads to collect (`None` = no limit) |
@@ -160,7 +160,7 @@ Close the collector and release resources.
 | `STATUS_ACTIVE` | `"ACTIVE"` |
 | `STATUS_INACTIVE` | `"INACTIVE"` |
 | `STATUS_ALL` | `"ALL"` |
-| `SEARCH_KEYWORD` | `"KEYWORD_EXACT_PHRASE"` |
+| `SEARCH_KEYWORD` | `"KEYWORD_UNORDERED"` |
 | `SEARCH_EXACT` | `"KEYWORD_EXACT_PHRASE"` |
 | `SEARCH_UNORDERED` | `"KEYWORD_UNORDERED"` |
 | `SEARCH_PAGE` | `"PAGE"` |
@@ -722,7 +722,7 @@ Format a CollectionReport as a JSON string.
 
 | Constant | Value |
 |---|---|
-| `SEARCH_KEYWORD` | `"KEYWORD_EXACT_PHRASE"` |
+| `SEARCH_KEYWORD` | `"KEYWORD_UNORDERED"` |
 | `SEARCH_EXACT` | `"KEYWORD_EXACT_PHRASE"` |
 | `SEARCH_UNORDERED` | `"KEYWORD_UNORDERED"` |
 | `SEARCH_PAGE` | `"PAGE"` |

docs/architecture.md

@@ -90,10 +90,12 @@ MetaAdsClient.initialize()
 | `lsd` | CSRF protection (mandatory) | `"LSD",[],{"token":"..."}`, `name="lsd" value="..."` |
 | `__rev` / `__spin_r` | Build revision | `"__spin_r":12345`, `"server_revision":12345` |
 | `__spin_t` | Timestamp | `"__spin_t":12345` |
-| `__hsi` | Session ID | `"hsi":"12345"` |
+| `__hsi` | Session ID | `"__hsi":"12345"` (with fallback to `"hsi":"12345"`) |
 | `fb_dtsg` | DTSG token | `"DTSGInitialData",[],{"token":"..."}` |
-| `__dyn` | Dynamic modules hash | `"__dyn":"..."` |
-| `__csr` | CSR hash | `"__csr":"..."` |
+| `__dyn` | Dynamic modules hash | `"__dyn":"..."` (no longer reliably present in HTML; fallback values used) |
+| `__csr` | CSR hash | `"__csr":"..."` (no longer reliably present in HTML; fallback values used) |
+| `v` | Version parameter | `"v":"fbece7"` (dynamically extracted when available) |
+| `x-asbd-id` | ASBD identifier | `"asbd_id":"359341"` (dynamically extracted when available) |
 | `jazoest` | Anti-abuse token | `"jazoest":12345` or computed from LSD |
 
 Fallback values from `constants.py` are used when extraction fails.
@@ -170,9 +172,9 @@ Sessions become stale after `MAX_SESSION_AGE` (30 minutes by default). Before ea
 
 `_refresh_session()` performs a full re-initialization:
 
-1. Close the old `requests.Session`
+1. Close the old session (`requests.Session` or `curl_cffi.requests.Session`)
 2. Generate a new `BrowserFingerprint`
-3. Create a fresh session with new headers
+3. Create a fresh session with new headers (preferring `curl_cffi` when available)
 4. Re-run `initialize()` to get new tokens
 5. Track consecutive refresh failures to prevent infinite loops
 
@@ -192,14 +194,18 @@ If `max_refresh_attempts` consecutive refreshes fail, `SessionExpiredError` is r
 
 `fingerprint.py` generates randomized but internally-consistent browser identities. Each session gets a unique combination of:
 
-- **Chrome version**: Randomly selected from 8 recent versions (125--132)
+- **Chrome version**: Randomly selected from 6 recent versions (140--145)
 - **Platform**: Windows or macOS with matching User-Agent OS string and `sec-ch-ua-platform`
 - **Viewport**: 8 common screen resolutions
 - **DPR**: 5 device pixel ratio values
 - **"Not A Brand" hint**: 4 variations matching real Chrome behavior
 
 All headers derived from the fingerprint are self-consistent -- the Chrome version in the User-Agent matches `sec-ch-ua`, the platform in the UA matches `sec-ch-ua-platform`, etc.
 
+### TLS Fingerprint Impersonation
+
+When the optional `curl_cffi` dependency is installed (`pip install meta-ads-collector[stealth]`), the client uses `curl_cffi.requests.Session(impersonate="chrome")` instead of `requests.Session`. This provides Chrome-like TLS fingerprints (JA3/JA4) at the connection level, making requests indistinguishable from a real Chrome browser to TLS-based bot detection systems. If `curl_cffi` is not installed, the library falls back to `requests.Session` transparently.
+
 ### Request Mimicry
 
 The client replicates the exact request patterns of a real browser:

docs/contributing.md

@@ -13,16 +13,16 @@ Contributions to `meta-ads-collector` are welcome. This guide covers the develop
 ### Clone and Install
 
 ```bash
-git clone https://github.com/Yossef/meta-ads-collector.git
-cd meta-ads-collector
+git clone https://github.com/promisingcoder/MetaAdsCollector.git
+cd MetaAdsCollector
 
 # Create a virtual environment
 python -m venv .venv
 source .venv/bin/activate  # Linux/macOS
 # .venv\Scripts\activate   # Windows
 
 # Install in editable mode with all dev dependencies
-pip install -e ".[dev,async]"
+pip install -e ".[dev,async,stealth]"
 ```
 
 Or use the Makefile:
@@ -37,6 +37,7 @@ make install-dev
 |---|---|---|
 | (none) | `requests>=2.28.0` | Always (core dependency) |
 | `async` | `httpx>=0.24.0` | When working on async modules |
+| `stealth` | `curl_cffi>=0.7.0` | For TLS fingerprint impersonation (recommended) |
 | `dev` | `pytest`, `pytest-cov`, `pytest-asyncio`, `ruff`, `mypy`, `types-requests` | Always for development |
 
 ## Running Tests

docs/quickstart.md

@@ -8,6 +8,12 @@ Get from zero to collecting ads in under 60 seconds.
 pip install meta-ads-collector
 ```
 
+For stealth TLS fingerprinting (recommended for production use):
+
+```bash
+pip install meta-ads-collector[stealth]
+```
+
 ## Python API
 
 ```python

meta_ads_collector/async_client.py

@@ -478,7 +478,7 @@ async def search_ads(
             "sessionID": session_id,
             "source": None,
             "startDate": None,
-            "v": "fbece7",
+            "v": self._tokens.get("v", "fbece7"),
             "viewAllPageID": "0",
         }
 
@@ -597,7 +597,7 @@ async def search_pages(
 
         from urllib.parse import quote
 
-        variables = {"queryString": query, "country": country}
+        variables = {"queryString": query, "country": country, "adType": "ALL", "isMobile": False}
         typeahead_doc_id = self._doc_ids.get(
             "useAdLibraryTypeaheadSuggestionDataSourceQuery", DOC_ID_TYPEAHEAD,
         )