Fix async client TLS fingerprinting and political ad parsing

- Rewrite async client to use curl_cffi.AsyncSession for Chrome TLS
  impersonation (was httpx-only, getting 403 blocked by Facebook)
- Add async 403 verification challenge handling (matching sync client)
- Fix political ad spend/impression parsing for string formats
- Add from __future__ import annotations for Python 3.9 compatibility
- Update async docs and README to recommend stealth extra
- Bump version to 1.2.0

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

Author: promisingcoder

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-02-21
+
+### Fixed
+- **Async client**: Rewrote to use `curl_cffi.AsyncSession` for TLS fingerprint impersonation, fixing 403 blocks from Facebook. Falls back to `httpx.AsyncClient` when curl_cffi is not installed.
+- **Async client**: Added 403 verification challenge handling (same as sync client), enabling the async client to work without proxies.
+- **Political ads parsing**: Fixed `'str' object has no attribute 'get'` crash when parsing political ads where `spend` is a string (e.g., `"$9K-$10K"`) instead of a dict.
+- **Impression text parsing**: Handle `impressions_with_index` format (`{"impressions_text": ">1M", "impressions_index": 39}`) returned for political ads.
+- **Publisher platform**: Added `publisher_platform` (singular) key lookup alongside plural `publisher_platforms`.
+- **Delivery dates**: Added `start_date`/`end_date` key lookups for delivery times.
+- **Reach parsing**: Added `_parse_reach` classmethod to handle `reach`/`reach_estimate` in string and dict formats.
+- **Audience distributions**: Added `isinstance(item, dict)` guards for demographic and region distribution parsing.
+- **Estimated audience size**: Added `isinstance(dict)` check before calling `.get()`.
+
+### Changed
+- **Python 3.9 compatibility**: Added `from __future__ import annotations` to `models.py` and modernized all type annotations from `Optional[X]` to `X | None`.
+- **Async transport**: The async client now prefers `curl_cffi.AsyncSession` over `httpx.AsyncClient` when both are installed, matching the sync client's TLS impersonation behavior.
+
+## [1.1.0] - 2026-02-21
+
+### Changed
+- Version bump for PyPI release.
+
 ## [1.0.0] - 2026-02-08
 
 ### Added
@@ -68,10 +90,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Optional batch mode for webhook sends
 
 #### Async Support
-- `AsyncMetaAdsClient` using httpx for non-blocking HTTP
+- `AsyncMetaAdsClient` with `curl_cffi.AsyncSession` (preferred) or `httpx.AsyncClient` (fallback)
 - `AsyncMetaAdsCollector` mirroring the sync API with `async for` generators
 - Async `search()`, `collect()`, `collect_to_json()`, `collect_to_csv()`, `search_pages()`
-- Optional dependency: `pip install meta-ads-collector[async]`
+- Optional dependency: `pip install meta-ads-collector[stealth]` (recommended) or `pip install meta-ads-collector[async]`
 
 #### Proxy Support
 - Single proxy configuration (host:port or host:port:user:pass)

README.md

@@ -49,16 +49,16 @@ meta-ads-collector -q "solar panels" -c US -n 10 -o ads.json
 pip install meta-ads-collector
 ```
 
-With async support (requires [httpx](https://www.python-httpx.org/)):
+With stealth TLS fingerprinting (recommended, also enables async support):
 
 ```bash
-pip install meta-ads-collector[async]
+pip install meta-ads-collector[stealth]
 ```
 
-With stealth TLS fingerprinting (requires [curl_cffi](https://github.com/lexiforest/curl_cffi)):
+With async support only (uses [httpx](https://www.python-httpx.org/)):
 
 ```bash
-pip install meta-ads-collector[stealth]
+pip install meta-ads-collector[async]
 ```
 
 From source:
@@ -379,9 +379,13 @@ with MetaAdsCollector() as collector:
 
 ## Async Support
 
-Full async API using httpx (optional dependency).
+Full async API with the same TLS fingerprint impersonation as the sync client.
 
 ```bash
+# Recommended: uses curl_cffi for TLS fingerprinting (same as sync client)
+pip install meta-ads-collector[stealth]
+
+# Alternative: uses httpx (may be detected by Facebook)
 pip install meta-ads-collector[async]
 ```
 
@@ -401,7 +405,7 @@ async def main():
 asyncio.run(main())
 ```
 
-The async collector mirrors the sync API: `search()`, `collect()`, `collect_to_json()`, `collect_to_csv()`, `search_pages()`, `get_stats()`.
+The async collector mirrors the sync API: `search()`, `collect()`, `collect_to_json()`, `collect_to_csv()`, `search_pages()`, `get_stats()`. When `curl_cffi` is installed, the async client uses `curl_cffi.AsyncSession` with Chrome TLS impersonation. Otherwise it falls back to `httpx.AsyncClient`.
 
 ---
 

docs/async.md

@@ -1,14 +1,20 @@
 # Async Usage Guide
 
-`meta-ads-collector` provides a full async API for use with `asyncio`. The async implementation uses [httpx](https://www.python-httpx.org/) instead of `requests`.
+`meta-ads-collector` provides a full async API for use with `asyncio`. The async client uses the same TLS fingerprint impersonation as the sync client to avoid detection.
 
 ## Installation
 
+The async client uses `curl_cffi` (recommended) for TLS fingerprint impersonation, or falls back to `httpx`:
+
 ```bash
+# Recommended: uses curl_cffi (same TLS fingerprinting as sync client)
+pip install meta-ads-collector[stealth]
+
+# Alternative: uses httpx (may get blocked by Facebook's TLS fingerprint detection)
 pip install meta-ads-collector[async]
 ```
 
-This installs `httpx>=0.24.0` as an additional dependency.
+If both `curl_cffi` and `httpx` are installed, `curl_cffi` is preferred automatically.
 
 ## AsyncMetaAdsCollector
 
@@ -135,7 +141,9 @@ async with AsyncMetaAdsClient() as client:
 
 ## Notes
 
-- The async client handles rate limiting with `asyncio.sleep()` instead of `time.sleep()`
+- The async client prefers `curl_cffi.AsyncSession` for TLS fingerprint impersonation, falling back to `httpx.AsyncClient` if curl_cffi is not installed
+- Facebook's 403 verification challenges are handled automatically (same as the sync client)
+- Rate limiting uses `asyncio.sleep()` instead of `time.sleep()`
 - Session initialization is performed asynchronously on the first request
 - Event callbacks are still synchronous (they run in the event loop thread)
 - Proxy rotation with `ProxyPool` works the same way as in the sync client

meta_ads_collector/__init__.py

@@ -32,7 +32,7 @@
 from .url_parser import extract_page_id_from_url
 from .webhooks import WebhookSender
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 __all__ = [
     # Models
     "Ad",