handles EU cookie consent (#91)

* handles eu cookie consent

* embedded eu cookie consent into the app

* implemented further passengers options (children and infants)

Author: bdebrabant

docs/filters.md

@@ -67,6 +67,23 @@ passengers = Passengers(
 )
 ```
 
+CLI & programmatic examples
+
+- From the bundled example CLI (`example.py`) you can supply the number of children with the `--children` flag:
+
+```bash
+python example.py --origin LHR --destination SLC --depart_date 2026-05-23 --return_date 2026-05-30 --adults 2 --children 1
+```
+
+- Programmatically, pass the children count into `Passengers` when creating a filter or calling `get_flights`:
+
+```python
+from fast_flights import Passengers, create_filter, get_flights
+
+passengers = Passengers(adults=2, children=1)
+# use create_filter(...) or pass passengers to get_flights(...)
+```
+
 ## Example
 Here's a simple example on how to create a filter:
 
@@ -88,3 +105,64 @@ filter: TFSData = create_filter(
 filter.as_b64()  # Base64-encoded (bytes)
 filter.to_string()  # Serialize to string
 ```
+
+## Passing cookies (binary parameter)
+
+Both `get_flights_from_filter(...)` and `get_flights(...)` accept a new optional parameter `cookies: bytes | None` which allows you to embed cookies as a binary payload that will be forwarded to the underlying fetchers.
+
+Supported cookie formats (the function will try them in this order):
+
+- JSON bytes: UTF-8 JSON encoding of a dict (e.g. `{ "CONSENT": "...", "SOCS": "..." }`). This will be set as `request_kwargs['cookies']`.
+- Pickle bytes: a pickled `dict` of cookie-name -> value; this will be set as `request_kwargs['cookies']`.
+- Raw Cookie header: if the bytes can't be parsed as JSON or pickle, they are decoded as UTF-8 and set as the `Cookie` HTTP header (`request_kwargs['headers']['Cookie']`).
+
+Examples:
+
+- JSON-encoded cookies as bytes (recommended):
+
+```python
+import json
+cookies = {"CONSENT": "PENDING+987", "SOCS": "CAESH..."}
+cookies_bytes = json.dumps(cookies).encode("utf-8")
+result = get_flights_from_filter(filter, cookies=cookies_bytes)
+```
+
+- Raw header example (when you already have a Cookie header string):
+
+```python
+cookies_bytes = b"CONSENT=PENDING+987; SOCS=CAESH..."
+result = get_flights_from_filter(filter, cookies=cookies_bytes)
+```
+
+Backward compatibility:
+
+- You can still pass cookies the old way via `request_kwargs={'cookies': {'CONSENT': '...', 'SOCS': '...'}}` — this is honored when `cookies` (binary) is not provided.
+- If both `cookies` (binary) and `request_kwargs` are provided, the parsed binary `cookies` take precedence and will override any `cookies` or `Cookie` header in `request_kwargs`.
+
+Security and privacy note:
+
+- Cookies may contain sensitive values. Avoid logging or committing cookies into source control and only supply cookies you trust.
+
+### Configurable default consent cookies
+
+The library embeds a small default consent cookie bundle used to bypass common Google consent gating. If you prefer to disable or explicitly control this behavior, both `get_flights_from_filter` and `get_flights` accept a boolean flag `cookie_consent: bool` (default `True`).
+
+- To use the embedded default cookies (the default behavior):
+
+```python
+# will apply embedded default cookies unless you provide cookies/request_kwargs explicitly
+result = get_flights_from_filter(filter, cookie_consent=True)
+```
+
+- To disable automatic application of the embedded default cookies:
+
+```python
+# will NOT add any embedded cookies; you can still pass cookies explicitly via request_kwargs or the binary `cookies` parameter
+result = get_flights_from_filter(filter, cookie_consent=False)
+```
+
+You can also pass the flag through `get_flights`:
+
+```python
+result = get_flights(..., cookie_consent=False)
+```

example.py

@@ -29,6 +29,7 @@ def main():
     parser.add_argument('--depart_date', required=True, help="Beginning trip date (YYYY-MM-DD)")
     parser.add_argument('--return_date', required=True, help="Ending trip date (YYYY-MM-DD)")
     parser.add_argument('--adults', type=int, default=1, help="Number of adult passengers")
+    parser.add_argument('--children', type=int, default=0, help="Number of children passengers")
     parser.add_argument('--type', type=str, default="economy", help="Fare class (economy, premium-economy, business or first)")
     parser.add_argument('--max_stops', type=int, help="Maximum number of stops (optional, [0|1|2])")
     parser.add_argument('--fetch_mode', type=str, default="common", help="Fetch mode: common, fallback, force-fallback, local, bright-data")
@@ -54,7 +55,7 @@ def main():
         seat=args.type,  # Seat (economy, premium-economy, business or first)
         passengers=Passengers(
             adults=args.adults,
-            children=0,
+            children=args.children,
             infants_in_seat=0,
             infants_on_lap=0
         ),
@@ -66,10 +67,17 @@ def main():
         "https://www.google.com/travel/flights?tfs=%s" % b64
     )
 
-    # Get flights with the filter
-    result = get_flights_from_filter(filter,
-                                     mode=args.fetch_mode
-                                     )
+    # Previously we constructed CONSENT/SOCS cookies here and passed them to
+    # get_flights_from_filter; the library now embeds a small default consent
+    # cookie bundle that will be applied automatically when no cookies are
+    # provided. To override or disable this behavior you can pass the
+    # `cookie_consent=False` flag or supply your own `cookies`/`request_kwargs`.
+
+    # Preferred: rely on the embedded default consent cookies (no explicit cookies passed)
+    result = get_flights_from_filter(filter, mode=args.fetch_mode)
+
+    # If you need to disable the embedded cookies and handle cookies yourself:
+    # result = get_flights_from_filter(filter, mode=args.fetch_mode, cookie_consent=False)
 
     try:
         # Manually convert the result to a dictionary before serialization
@@ -80,8 +88,8 @@ def main():
         print(result)
         print("Error details:", str(e))
 
-    # Print price information
-    print("The price is currently", result.current_price)
+    # Print price information safely (result may be decoded or None)
+    print("The price is currently", getattr(result, 'current_price', None))
 
 if __name__ == "__main__":
-    main()
+    main()

fast_flights/__init__.py

@@ -1,4 +1,8 @@
-from .cookies_impl import Cookies
+# Lazy import Cookies to avoid heavy protobuf dependencies during import-time in tests
+def get_cookies_class():
+    from .cookies_impl import Cookies
+    return Cookies
+
 from .core import get_flights_from_filter, get_flights
 from .filter import create_filter
 from .flights_impl import Airport, FlightData, Passengers, TFSData
@@ -18,3 +22,21 @@
     "Cookies",
     "get_flights",
 ]
+
+# Backwards-compatible name: try to resolve Cookies lazily if accessed
+try:
+    # Provide a module-level name that will import on access
+    class _CookiesProxy:
+        def __getattr__(self, name):
+            Cookies = get_cookies_class()
+            return getattr(Cookies, name)
+
+    Cookies = get_cookies_class()
+except Exception:
+    # If import fails, expose a simple proxy that will import when used
+    class _CookiesProxy:
+        def __getattr__(self, name):
+            Cookies = get_cookies_class()
+            return getattr(Cookies, name)
+
+    Cookies = _CookiesProxy()