From 6332621114a45f0c30170f23f10ffbf569a3ef55 Mon Sep 17 00:00:00 2001
From: clcl777 <77223796+clcl777@users.noreply.github.com>
Date: Sat, 4 Oct 2025 18:43:19 +0900
Subject: [PATCH 1/4] add cursor document

---
 .cursor/rules/documentation.mdc      | 48 ++++++++++++++++++++
 .cursor/rules/enums-generation.mdc   | 53 +++++++++++++++++++++++
 .cursor/rules/fetch-strategies.mdc   | 65 ++++++++++++++++++++++++++++
 .cursor/rules/project-structure.mdc  | 58 +++++++++++++++++++++++++
 .cursor/rules/protobuf.mdc           | 42 ++++++++++++++++++
 .cursor/rules/python-conventions.mdc | 41 ++++++++++++++++++
 .cursor/rules/testing.mdc            | 52 ++++++++++++++++++++++
 7 files changed, 359 insertions(+)
 create mode 100644 .cursor/rules/documentation.mdc
 create mode 100644 .cursor/rules/enums-generation.mdc
 create mode 100644 .cursor/rules/fetch-strategies.mdc
 create mode 100644 .cursor/rules/project-structure.mdc
 create mode 100644 .cursor/rules/protobuf.mdc
 create mode 100644 .cursor/rules/python-conventions.mdc
 create mode 100644 .cursor/rules/testing.mdc

diff --git a/.cursor/rules/documentation.mdc b/.cursor/rules/documentation.mdc
new file mode 100644
index 00000000..e49dabd9
--- /dev/null
+++ b/.cursor/rules/documentation.mdc
@@ -0,0 +1,48 @@
+---
+globs: docs/*.md,mkdocs.yml,README.md
+---
+
+# Documentation Guidelines
+
+## Documentation Structure
+- [README.md](mdc:README.md) - Main project documentation with examples and background
+- [docs/](mdc:docs/) - Extended documentation using MkDocs
+- [mkdocs.yml](mdc:mkdocs.yml) - MkDocs configuration
+
+## Documentation Files
+- [docs/index.md](mdc:docs/index.md) - Documentation homepage
+- [docs/airports.md](mdc:docs/airports.md) - Airport enum usage and examples  
+- [docs/fallbacks.md](mdc:docs/fallbacks.md) - Fallback strategy documentation
+- [docs/filters.md](mdc:docs/filters.md) - Filter creation guide
+- [docs/local.md](mdc:docs/local.md) - Local Playwright setup and usage
+
+## Building Documentation
+```bash
+mkdocs build
+mkdocs serve  # For local preview
+```
+
+## Documentation Style
+- Use clear, concise language
+- Include code examples with type annotations
+- Explain the "why" not just the "how"
+- Add real-world use cases
+- Keep examples up-to-date with the API
+
+## README.md
+- Keep the README focused on getting started quickly
+- Include installation instructions
+- Show a complete, working example
+- Link to full documentation
+- Explain the project's unique value (Protobuf-based, fast, strongly-typed)
+
+## Code Examples in Docs
+- All code examples should be tested and working
+- Use realistic data (valid airports, future dates)
+- Show type annotations to highlight strong typing
+- Demonstrate error handling where relevant
+
+## Changelog
+- Document major changes in README
+- Use version numbers to track API changes
+- Highlight breaking changes clearly
diff --git a/.cursor/rules/enums-generation.mdc b/.cursor/rules/enums-generation.mdc
new file mode 100644
index 00000000..be923af5
--- /dev/null
+++ b/.cursor/rules/enums-generation.mdc
@@ -0,0 +1,53 @@
+---
+globs: enums/*.py,enums/*.csv,fast_flights/_generated_enum.py
+---
+
+# Airport Enum Generation
+
+## Overview
+The project auto-generates a Python enum of all airports from a CSV file to provide autocomplete functionality for airport codes.
+
+## Files
+- [enums/airports.csv](mdc:enums/airports.csv) - Source data for airports (IATA codes and names)
+- [enums/generate_enums.py](mdc:enums/generate_enums.py) - Generator script
+- [fast_flights/_generated_enum.py](mdc:fast_flights/_generated_enum.py) - Generated Airport enum
+
+## Regenerating Enums
+To regenerate the airport enums after updating the CSV:
+```bash
+python enums/generate_enums.py
+```
+
+## CSV Format
+The airports.csv should have:
+- First row: headers
+- Each subsequent row: airport data with IATA code and airport name
+
+## Generated Code
+- Never manually edit `fast_flights/_generated_enum.py`
+- The generated `Airport` enum provides IDE autocomplete
+- Each enum value is the IATA 3-letter code
+
+## Usage
+```python
+from fast_flights import FlightData, Airport
+
+# With enum (provides autocomplete)
+flight = FlightData(
+    date="2025-01-01",
+    from_airport=Airport.TAIPEI_SONGSHAN_AIRPORT,  # Autocomplete available!
+    to_airport=Airport.TOKYO_HANEDA_AIRPORT
+)
+
+# With string (also works)
+flight = FlightData(
+    date="2025-01-01", 
+    from_airport="TPE",
+    to_airport="HND"
+)
+```
+
+## Adding New Airports
+1. Add the airport to [enums/airports.csv](mdc:enums/airports.csv)
+2. Run `python enums/generate_enums.py`
+3. The new airport will be available in the `Airport` enum
diff --git a/.cursor/rules/fetch-strategies.mdc b/.cursor/rules/fetch-strategies.mdc
new file mode 100644
index 00000000..8fa2b1bd
--- /dev/null
+++ b/.cursor/rules/fetch-strategies.mdc
@@ -0,0 +1,65 @@
+---
+description: Guidelines for implementing and working with different fetch strategies
+---
+
+# Fetch Strategy Implementation
+
+## Overview
+The project supports multiple fetch strategies to handle different scenarios (rate limiting, blocking, regional restrictions, etc.).
+
+## Strategy Files
+- [fast_flights/primp.py](mdc:fast_flights/primp.py) & [fast_flights/primp.pyi](mdc:fast_flights/primp.pyi) - Fast HTTP client with browser impersonation (default)
+- [fast_flights/fallback_playwright.py](mdc:fast_flights/fallback_playwright.py) - Serverless Playwright fallback
+- [fast_flights/local_playwright.py](mdc:fast_flights/local_playwright.py) - Local Playwright implementation
+- [fast_flights/bright_data_fetch.py](mdc:fast_flights/bright_data_fetch.py) - Bright Data proxy integration
+
+## Fetch Strategy Pattern
+All fetch strategies should:
+1. Accept `params: dict` as parameter (containing `tfs`, `hl`, `tfu`, `curr`)
+2. Return a `Response` object (or compatible object) with:
+   - `.status_code` property
+   - `.text` property (HTML content)
+   - `.text_markdown` property (for error messages)
+
+## Response Interface
+```python
+class Response:
+    status_code: int
+    text: str
+    text_markdown: str  # Markdown-formatted version for debugging
+```
+
+## When to Use Each Strategy
+
+### primp (default/common mode)
+- Fastest option
+- Uses browser impersonation to avoid basic detection
+- Works for most requests
+- No external dependencies beyond the primp library
+
+### Fallback Playwright
+- Automatically triggered when primp fails (in fallback mode)
+- Uses serverless Playwright functions
+- Handles JavaScript rendering and more complex anti-bot measures
+- Slower but more reliable
+
+### Local Playwright  
+- For development and testing
+- Requires local Playwright installation (`pip install fast-flights[local]`)
+- Useful for debugging issues with the scraper
+
+### Bright Data
+- For production use with proxy service
+- Requires Bright Data credentials
+- Most reliable but has cost implications
+
+## Error Handling
+- Fetch strategies should raise `AssertionError` if status code is not 200
+- Core module catches `AssertionError` and falls back to Playwright in fallback mode
+- If parsing fails, retry with force-fallback mode to ensure JavaScript rendering
+
+## Adding New Strategies
+1. Create a new file in `fast_flights/` (e.g., `my_fetch.py`)
+2. Implement a function that accepts `params: dict` and returns `Response`
+3. Add the strategy to the mode options in [fast_flights/core.py](mdc:fast_flights/core.py)
+4. Update type hints to include the new mode literal
diff --git a/.cursor/rules/project-structure.mdc b/.cursor/rules/project-structure.mdc
new file mode 100644
index 00000000..6baeeba0
--- /dev/null
+++ b/.cursor/rules/project-structure.mdc
@@ -0,0 +1,58 @@
+---
+alwaysApply: true
+---
+
+# Fast-Flights Project Structure
+
+## Overview
+This is a Python-based Google Flights scraper that uses Protocol Buffers to decode Google's base64-encoded flight data. The project provides a strongly-typed API for fetching flight information.
+
+## Core Architecture
+
+### Main Entry Points
+- [fast_flights/__init__.py](mdc:fast_flights/__init__.py) - Public API exports
+- [fast_flights/core.py](mdc:fast_flights/core.py) - Primary flight fetching logic with multiple fetch modes
+
+### Key Components
+
+1. **Flight Data & Filters**
+   - [fast_flights/flights_impl.py](mdc:fast_flights/flights_impl.py) - Typed implementations of `FlightData`, `Passengers`, and `TFSData`
+   - [fast_flights/filter.py](mdc:fast_flights/filter.py) - Filter creation utilities
+
+2. **Protocol Buffers**
+   - [fast_flights/flights.proto](mdc:fast_flights/flights.proto) - Flight data protobuf schema
+   - [fast_flights/cookies.proto](mdc:fast_flights/cookies.proto) - Cookie/consent protobuf schema
+   - [fast_flights/flights_pb2.py](mdc:fast_flights/flights_pb2.py) - Generated protobuf code
+   - [fast_flights/cookies_pb2.py](mdc:fast_flights/cookies_pb2.py) - Generated protobuf code
+
+3. **Fetch Strategies**
+   - `primp` Client (default) - Fast HTTP client with browser impersonation
+   - `fallback_playwright` - Serverless Playwright fallback for blocked requests
+   - `local_playwright` - Local Playwright for development/testing
+   - `bright_data` - Bright Data proxy service
+
+4. **Data Processing**
+   - [fast_flights/schema.py](mdc:fast_flights/schema.py) - Response data models (`Result`, `Flight`)
+   - [fast_flights/decoder.py](mdc:fast_flights/decoder.py) - JavaScript data decoder for alternative data source
+   - HTML parsing using `selectolax.lexbor`
+
+5. **Generated Code**
+   - [fast_flights/_generated_enum.py](mdc:fast_flights/_generated_enum.py) - Auto-generated Airport enum
+   - [enums/generate_enums.py](mdc:enums/generate_enums.py) - Script to generate airport enums from CSV
+
+## Fetch Modes
+- `common` - Uses primp HTTP client only
+- `fallback` - Tries primp, falls back to Playwright if it fails
+- `force-fallback` - Forces Playwright usage
+- `local` - Uses local Playwright installation
+- `bright-data` - Uses Bright Data proxy service
+
+## Data Sources
+- `html` - Parses HTML response (default)
+- `js` - Parses JavaScript data from `<script>` tags
+
+## Key Patterns
+- All date strings should be in ISO format (YYYY-MM-DD)
+- Airport codes are 3-letter IATA codes
+- Strong typing throughout with dataclasses and typed implementations
+- Protobuf used for efficient data serialization
diff --git a/.cursor/rules/protobuf.mdc b/.cursor/rules/protobuf.mdc
new file mode 100644
index 00000000..79405b0f
--- /dev/null
+++ b/.cursor/rules/protobuf.mdc
@@ -0,0 +1,42 @@
+---
+globs: *.proto,*_pb2.py
+---
+
+# Protocol Buffers Guidelines
+
+## Proto Files
+- Use `syntax = "proto3"` at the top of all .proto files
+- Follow Google's protobuf style guide for naming conventions
+- Place .proto files in the main package directory ([fast_flights/](mdc:fast_flights/))
+
+## Generated Files
+- Never manually edit `*_pb2.py` files - they are auto-generated
+- Regenerate proto files after any .proto changes using:
+  ```bash
+  protoc --python_out=. fast_flights/flights.proto
+  protoc --python_out=. fast_flights/cookies.proto
+  ```
+
+## Working with Protobuf
+- Create typed wrapper classes for protobuf messages (see [fast_flights/flights_impl.py](mdc:fast_flights/flights_impl.py))
+- Use the `attach()` pattern to populate protobuf messages from typed wrappers
+- Serialize with `.SerializeToString()` and deserialize with `.ParseFromString()`
+- Base64 encode protobuf data when sending to Google Flights API
+
+## Type Annotations
+- Use `TYPE_CHECKING` to avoid runtime imports of protobuf types
+- Annotate protobuf message types as `Any` under TYPE_CHECKING block for type checkers
+
+## Common Patterns
+```python
+# Serialization
+info = PB.Info()
+# ... populate info ...
+raw = info.SerializeToString()
+encoded = base64.b64encode(raw)
+
+# Deserialization
+raw = base64.b64decode(encoded_string)
+pb = PB.SomeMessage()
+pb.ParseFromString(raw)
+```
diff --git a/.cursor/rules/python-conventions.mdc b/.cursor/rules/python-conventions.mdc
new file mode 100644
index 00000000..f85fa7e7
--- /dev/null
+++ b/.cursor/rules/python-conventions.mdc
@@ -0,0 +1,41 @@
+---
+globs: *.py,*.pyi
+---
+
+# Python Coding Conventions
+
+## Type Annotations
+- Always use type hints for function parameters and return values
+- Use `from typing import` for complex types (Literal, Optional, Union, List, etc.)
+- Use `TYPE_CHECKING` for circular imports and type-only imports
+- Prefer `Optional[T]` over `T | None` for Python 3.8 compatibility
+- Use `Union[A, B]` instead of `A | B` for Python 3.8 compatibility
+
+## Python Version
+- Target Python 3.8+ as specified in [pyproject.toml](mdc:pyproject.toml)
+- Avoid using features only available in Python 3.9+
+
+## Dataclasses and Slots
+- Use `__slots__` for performance-critical classes (e.g., `FlightData`)
+- Use `@dataclass` from dataclasses module for simple data containers
+- Prefer explicit `__init__` methods when custom validation is needed
+
+## Overloads
+- Use `@overload` decorator from typing module for functions with different return types based on parameters
+- Always provide a non-overload implementation as the final definition
+
+## Assertions and Validation
+- Use `assert` for invariants and preconditions
+- Raise `ValueError` for invalid user input
+- Raise `RuntimeError` for unexpected runtime states
+- Include descriptive error messages
+
+## Imports
+- Group imports: standard library, third-party, local
+- Use absolute imports from package root (e.g., `from .schema import Result`)
+- Keep `__all__` exports updated in `__init__.py` files
+
+## Documentation
+- Use docstrings for public functions and classes
+- Follow Google-style docstring format with Args and Returns sections
+- Include type information in docstrings where helpful for users
diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc
new file mode 100644
index 00000000..de7b4d53
--- /dev/null
+++ b/.cursor/rules/testing.mdc
@@ -0,0 +1,52 @@
+---
+globs: test_*.py,*_test.py
+---
+
+# Testing Guidelines
+
+## Test Files
+- Place test files in the project root (e.g., [test.py](mdc:test.py), [test_bright_data.py](mdc:test_bright_data.py))
+- Name test files with `test_` prefix or `_test` suffix
+- Each test file should be runnable independently
+
+## Test Structure
+```python
+from fast_flights import get_flights, FlightData, Passengers, Result
+
+# Test with real API calls
+result: Result = get_flights(
+    flight_data=[
+        FlightData(date="2025-01-01", from_airport="TPE", to_airport="MYJ")
+    ],
+    trip="one-way",
+    seat="economy",
+    passengers=Passengers(adults=2, children=1),
+    fetch_mode="fallback",  # Use fallback mode for reliability
+)
+
+assert result.flights, "Should return flights"
+print(result)
+```
+
+## Testing Best Practices
+- Use descriptive assertions with error messages
+- Test with multiple fetch modes when relevant
+- Use real dates in the future (not past dates)
+- Test edge cases: multi-city trips, different seat classes, various passenger combinations
+- Verify both successful responses and error handling
+
+## Data for Testing
+- Use valid 3-letter IATA airport codes
+- Test with international routes to catch regional issues
+- Consider time zones and date line crossing scenarios
+
+## Testing Fetch Strategies
+- Test with `fetch_mode="common"` first (fastest)
+- Use `fetch_mode="fallback"` for more reliable tests
+- Test `fetch_mode="local"` when Playwright is installed
+- Only test `fetch_mode="bright-data"` with valid credentials
+
+## Jupyter Notebooks
+- Use [data_discovery.ipynb](mdc:data_discovery.ipynb) for exploratory testing and debugging
+- Keep notebooks for documentation and experimentation
+- Export important discoveries to proper test files

From 04d397f2c5f511dda9ec5c1b55327db06fa954ea Mon Sep 17 00:00:00 2001
From: clcl777 <77223796+clcl777@users.noreply.github.com>
Date: Sat, 4 Oct 2025 19:13:24 +0900
Subject: [PATCH 2/4] wip

---
 fast_flights/flights_impl.py | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/fast_flights/flights_impl.py b/fast_flights/flights_impl.py
index 5bd49e0d..137489de 100644
--- a/fast_flights/flights_impl.py
+++ b/fast_flights/flights_impl.py
@@ -1,6 +1,7 @@
 """Typed implementation of flights_pb2.py"""
 
 import base64
+from datetime import datetime
 from dataclasses import dataclass
 from typing import Any, List, Optional, TYPE_CHECKING, Literal, Union
 
@@ -39,6 +40,20 @@ def __init__(
         max_stops: Optional[int] = None,
         airlines: Optional[List[str]] = None,
     ):
+        # Validate date format and ensure it's not in the past
+        try:
+            date_obj = datetime.strptime(date, "%Y-%m-%d").date()
+        except ValueError:
+            raise ValueError(
+                f"Invalid date format: {date}. Date must be in YYYY-MM-DD format."
+            )
+        
+        today = datetime.now().date()
+        if date_obj < today:
+            raise ValueError(
+                f"Date cannot be in the past. Provided date: {date}, Today: {today}"
+            )
+        
         self.date = date
         self.from_airport = (
             from_airport.value if isinstance(from_airport, Airport) else from_airport

From 835b883dff10b5e37d014c4f6789a0172f79f5d2 Mon Sep 17 00:00:00 2001
From: clcl777 <77223796+clcl777@users.noreply.github.com>
Date: Sat, 4 Oct 2025 19:27:45 +0900
Subject: [PATCH 3/4] wip

---
 fast_flights/__init__.py     |  8 ++++++--
 fast_flights/core.py         | 31 +++++++++++++++++++++++--------
 fast_flights/filter.py       |  8 ++++----
 fast_flights/flights_impl.py | 34 +++++++++++++++++++++++++++++++---
 4 files changed, 64 insertions(+), 17 deletions(-)

diff --git a/fast_flights/__init__.py b/fast_flights/__init__.py
index db669926..f78d3081 100644
--- a/fast_flights/__init__.py
+++ b/fast_flights/__init__.py
@@ -1,7 +1,7 @@
 from .cookies_impl import Cookies
-from .core import get_flights_from_filter, get_flights
+from .core import get_flights_from_filter, get_flights, DataSource, FetchMode
 from .filter import create_filter
-from .flights_impl import Airport, FlightData, Passengers, TFSData
+from .flights_impl import Airport, FlightData, Passengers, TFSData, TripType, SeatType
 from .schema import Flight, Result
 from .search import search_airport
 
@@ -17,4 +17,8 @@
     "search_airport",
     "Cookies",
     "get_flights",
+    "DataSource",
+    "FetchMode",
+    "TripType",
+    "SeatType",
 ]
diff --git a/fast_flights/core.py b/fast_flights/core.py
index 6b11aafb..a3af62b4 100644
--- a/fast_flights/core.py
+++ b/fast_flights/core.py
@@ -1,12 +1,12 @@
 import re
 import json
-from typing import List, Literal, Optional, Union, overload
+from typing import List, Literal, Optional, Union, overload, get_args
 
 from selectolax.lexbor import LexborHTMLParser, LexborNode
 
 from .decoder import DecodedResult, ResultDecoder
 from .schema import Flight, Result
-from .flights_impl import FlightData, Passengers
+from .flights_impl import FlightData, Passengers, TripType, SeatType
 from .filter import TFSData
 from .fallback_playwright import fallback_playwright_fetch
 from .bright_data_fetch import bright_data_fetch
@@ -14,6 +14,7 @@
 
 
 DataSource = Literal['html', 'js']
+FetchMode = Literal["common", "fallback", "force-fallback", "local", "bright-data"]
 
 def fetch(params: dict) -> Response:
     client = Client(impersonate="chrome_126", verify=False)
@@ -26,7 +27,7 @@ def get_flights_from_filter(
     filter: TFSData,
     currency: str = "",
     *,
-    mode: Literal["common", "fallback", "force-fallback", "local", "bright-data"] = "common",
+    mode: FetchMode = "common",
     data_source: Literal['js'] = ...,
 ) -> Union[DecodedResult, None]: ...
 
@@ -35,7 +36,7 @@ def get_flights_from_filter(
     filter: TFSData,
     currency: str = "",
     *,
-    mode: Literal["common", "fallback", "force-fallback", "local", "bright-data"] = "common",
+    mode: FetchMode = "common",
     data_source: Literal['html'],
 ) -> Result: ...
 
@@ -43,9 +44,23 @@ def get_flights_from_filter(
     filter: TFSData,
     currency: str = "",
     *,
-    mode: Literal["common", "fallback", "force-fallback", "local", "bright-data"] = "common",
+    mode: FetchMode = "common",
     data_source: DataSource = 'html',
 ) -> Union[Result, DecodedResult, None]:
+    # Validate mode parameter
+    valid_modes = get_args(FetchMode)
+    if mode not in valid_modes:
+        raise ValueError(
+            f"Invalid fetch mode: {mode}. Must be one of {list(valid_modes)}"
+        )
+    
+    # Validate data_source parameter
+    valid_data_sources = get_args(DataSource)
+    if data_source not in valid_data_sources:
+        raise ValueError(
+            f"Invalid data_source: {data_source}. Must be one of {list(valid_data_sources)}"
+        )
+    
     data = filter.as_b64()
 
     params = {
@@ -86,10 +101,10 @@ def get_flights_from_filter(
 def get_flights(
     *,
     flight_data: List[FlightData],
-    trip: Literal["round-trip", "one-way", "multi-city"],
+    trip: TripType,
     passengers: Passengers,
-    seat: Literal["economy", "premium-economy", "business", "first"],
-    fetch_mode: Literal["common", "fallback", "force-fallback", "local", "bright-data"] = "common",
+    seat: SeatType,
+    fetch_mode: FetchMode = "common",
     max_stops: Optional[int] = None,
     data_source: DataSource = 'html',
 ) -> Union[Result, DecodedResult, None]:
diff --git a/fast_flights/filter.py b/fast_flights/filter.py
index 67171f0a..22702b8d 100644
--- a/fast_flights/filter.py
+++ b/fast_flights/filter.py
@@ -1,12 +1,12 @@
-from typing import Literal, List, Optional
-from .flights_impl import FlightData, Passengers, TFSData
+from typing import List, Optional
+from .flights_impl import FlightData, Passengers, TFSData, TripType, SeatType
 
 def create_filter(
     *,
     flight_data: List[FlightData],
-    trip: Literal["round-trip", "one-way", "multi-city"],
+    trip: TripType,
     passengers: Passengers,
-    seat: Literal["economy", "premium-economy", "business", "first"],
+    seat: SeatType,
     max_stops: Optional[int] = None,
 ) -> TFSData:
     """Create a filter. (``?tfs=``)
diff --git a/fast_flights/flights_impl.py b/fast_flights/flights_impl.py
index 137489de..6a9c0873 100644
--- a/fast_flights/flights_impl.py
+++ b/fast_flights/flights_impl.py
@@ -3,7 +3,7 @@
 import base64
 from datetime import datetime
 from dataclasses import dataclass
-from typing import Any, List, Optional, TYPE_CHECKING, Literal, Union
+from typing import Any, List, Optional, TYPE_CHECKING, Literal, Union, get_args
 
 from . import flights_pb2 as PB
 from ._generated_enum import Airport
@@ -13,6 +13,10 @@
 
 AIRLINE_ALLIANCES = ["SKYTEAM", "STAR_ALLIANCE", "ONEWORLD"]
 
+# Type aliases for validation
+TripType = Literal["round-trip", "one-way", "multi-city"]
+SeatType = Literal["economy", "premium-economy", "business", "first"]
+
 class FlightData:
     """Represents flight data.
 
@@ -178,9 +182,9 @@ def as_b64(self) -> bytes:
     def from_interface(
         *,
         flight_data: List[FlightData],
-        trip: Literal["round-trip", "one-way", "multi-city"],
+        trip: TripType,
         passengers: Passengers,
-        seat: Literal["economy", "premium-economy", "business", "first"],
+        seat: SeatType,
         max_stops: Optional[int] = None,  # Add max_stops to the method signature
     ):
         """Use ``?tfs=`` from an interface.
@@ -192,6 +196,30 @@ def from_interface(
             seat ("economy" | "premium-economy" | "business" | "first"): Seat.
             max_stops (int, optional): Maximum number of stops.
         """
+        # Validate trip parameter
+        valid_trips = get_args(TripType)
+        if trip not in valid_trips:
+            raise ValueError(
+                f"Invalid trip type: {trip}. Must be one of {list(valid_trips)}"
+            )
+        
+        # Validate seat parameter
+        valid_seats = get_args(SeatType)
+        if seat not in valid_seats:
+            raise ValueError(
+                f"Invalid seat type: {seat}. Must be one of {list(valid_seats)}"
+            )
+        
+        # Validate flight_data
+        if not flight_data:
+            raise ValueError("flight_data must contain at least one FlightData object")
+        
+        # Validate trip-specific requirements
+        if trip == "round-trip" and len(flight_data) < 2:
+            raise ValueError(
+                f"round-trip requires at least 2 FlightData objects, but got {len(flight_data)}"
+            )
+        
         trip_t = {
             "round-trip": PB.Trip.ROUND_TRIP,
             "one-way": PB.Trip.ONE_WAY,

From e27b5af5c67302cbdac04aa1e4d15e0c12090059 Mon Sep 17 00:00:00 2001
From: clcl777 <77223796+clcl777@users.noreply.github.com>
Date: Sat, 4 Oct 2025 19:30:46 +0900
Subject: [PATCH 4/4] wip

---
 .cursor/rules/documentation.mdc      | 48 --------------------
 .cursor/rules/enums-generation.mdc   | 53 -----------------------
 .cursor/rules/fetch-strategies.mdc   | 65 ----------------------------
 .cursor/rules/project-structure.mdc  | 58 -------------------------
 .cursor/rules/protobuf.mdc           | 42 ------------------
 .cursor/rules/python-conventions.mdc | 41 ------------------
 .cursor/rules/testing.mdc            | 52 ----------------------
 7 files changed, 359 deletions(-)
 delete mode 100644 .cursor/rules/documentation.mdc
 delete mode 100644 .cursor/rules/enums-generation.mdc
 delete mode 100644 .cursor/rules/fetch-strategies.mdc
 delete mode 100644 .cursor/rules/project-structure.mdc
 delete mode 100644 .cursor/rules/protobuf.mdc
 delete mode 100644 .cursor/rules/python-conventions.mdc
 delete mode 100644 .cursor/rules/testing.mdc

diff --git a/.cursor/rules/documentation.mdc b/.cursor/rules/documentation.mdc
deleted file mode 100644
index e49dabd9..00000000
--- a/.cursor/rules/documentation.mdc
+++ /dev/null
@@ -1,48 +0,0 @@
----
-globs: docs/*.md,mkdocs.yml,README.md
----
-
-# Documentation Guidelines
-
-## Documentation Structure
-- [README.md](mdc:README.md) - Main project documentation with examples and background
-- [docs/](mdc:docs/) - Extended documentation using MkDocs
-- [mkdocs.yml](mdc:mkdocs.yml) - MkDocs configuration
-
-## Documentation Files
-- [docs/index.md](mdc:docs/index.md) - Documentation homepage
-- [docs/airports.md](mdc:docs/airports.md) - Airport enum usage and examples  
-- [docs/fallbacks.md](mdc:docs/fallbacks.md) - Fallback strategy documentation
-- [docs/filters.md](mdc:docs/filters.md) - Filter creation guide
-- [docs/local.md](mdc:docs/local.md) - Local Playwright setup and usage
-
-## Building Documentation
-```bash
-mkdocs build
-mkdocs serve  # For local preview
-```
-
-## Documentation Style
-- Use clear, concise language
-- Include code examples with type annotations
-- Explain the "why" not just the "how"
-- Add real-world use cases
-- Keep examples up-to-date with the API
-
-## README.md
-- Keep the README focused on getting started quickly
-- Include installation instructions
-- Show a complete, working example
-- Link to full documentation
-- Explain the project's unique value (Protobuf-based, fast, strongly-typed)
-
-## Code Examples in Docs
-- All code examples should be tested and working
-- Use realistic data (valid airports, future dates)
-- Show type annotations to highlight strong typing
-- Demonstrate error handling where relevant
-
-## Changelog
-- Document major changes in README
-- Use version numbers to track API changes
-- Highlight breaking changes clearly
diff --git a/.cursor/rules/enums-generation.mdc b/.cursor/rules/enums-generation.mdc
deleted file mode 100644
index be923af5..00000000
--- a/.cursor/rules/enums-generation.mdc
+++ /dev/null
@@ -1,53 +0,0 @@
----
-globs: enums/*.py,enums/*.csv,fast_flights/_generated_enum.py
----
-
-# Airport Enum Generation
-
-## Overview
-The project auto-generates a Python enum of all airports from a CSV file to provide autocomplete functionality for airport codes.
-
-## Files
-- [enums/airports.csv](mdc:enums/airports.csv) - Source data for airports (IATA codes and names)
-- [enums/generate_enums.py](mdc:enums/generate_enums.py) - Generator script
-- [fast_flights/_generated_enum.py](mdc:fast_flights/_generated_enum.py) - Generated Airport enum
-
-## Regenerating Enums
-To regenerate the airport enums after updating the CSV:
-```bash
-python enums/generate_enums.py
-```
-
-## CSV Format
-The airports.csv should have:
-- First row: headers
-- Each subsequent row: airport data with IATA code and airport name
-
-## Generated Code
-- Never manually edit `fast_flights/_generated_enum.py`
-- The generated `Airport` enum provides IDE autocomplete
-- Each enum value is the IATA 3-letter code
-
-## Usage
-```python
-from fast_flights import FlightData, Airport
-
-# With enum (provides autocomplete)
-flight = FlightData(
-    date="2025-01-01",
-    from_airport=Airport.TAIPEI_SONGSHAN_AIRPORT,  # Autocomplete available!
-    to_airport=Airport.TOKYO_HANEDA_AIRPORT
-)
-
-# With string (also works)
-flight = FlightData(
-    date="2025-01-01", 
-    from_airport="TPE",
-    to_airport="HND"
-)
-```
-
-## Adding New Airports
-1. Add the airport to [enums/airports.csv](mdc:enums/airports.csv)
-2. Run `python enums/generate_enums.py`
-3. The new airport will be available in the `Airport` enum
diff --git a/.cursor/rules/fetch-strategies.mdc b/.cursor/rules/fetch-strategies.mdc
deleted file mode 100644
index 8fa2b1bd..00000000
--- a/.cursor/rules/fetch-strategies.mdc
+++ /dev/null
@@ -1,65 +0,0 @@
----
-description: Guidelines for implementing and working with different fetch strategies
----
-
-# Fetch Strategy Implementation
-
-## Overview
-The project supports multiple fetch strategies to handle different scenarios (rate limiting, blocking, regional restrictions, etc.).
-
-## Strategy Files
-- [fast_flights/primp.py](mdc:fast_flights/primp.py) & [fast_flights/primp.pyi](mdc:fast_flights/primp.pyi) - Fast HTTP client with browser impersonation (default)
-- [fast_flights/fallback_playwright.py](mdc:fast_flights/fallback_playwright.py) - Serverless Playwright fallback
-- [fast_flights/local_playwright.py](mdc:fast_flights/local_playwright.py) - Local Playwright implementation
-- [fast_flights/bright_data_fetch.py](mdc:fast_flights/bright_data_fetch.py) - Bright Data proxy integration
-
-## Fetch Strategy Pattern
-All fetch strategies should:
-1. Accept `params: dict` as parameter (containing `tfs`, `hl`, `tfu`, `curr`)
-2. Return a `Response` object (or compatible object) with:
-   - `.status_code` property
-   - `.text` property (HTML content)
-   - `.text_markdown` property (for error messages)
-
-## Response Interface
-```python
-class Response:
-    status_code: int
-    text: str
-    text_markdown: str  # Markdown-formatted version for debugging
-```
-
-## When to Use Each Strategy
-
-### primp (default/common mode)
-- Fastest option
-- Uses browser impersonation to avoid basic detection
-- Works for most requests
-- No external dependencies beyond the primp library
-
-### Fallback Playwright
-- Automatically triggered when primp fails (in fallback mode)
-- Uses serverless Playwright functions
-- Handles JavaScript rendering and more complex anti-bot measures
-- Slower but more reliable
-
-### Local Playwright  
-- For development and testing
-- Requires local Playwright installation (`pip install fast-flights[local]`)
-- Useful for debugging issues with the scraper
-
-### Bright Data
-- For production use with proxy service
-- Requires Bright Data credentials
-- Most reliable but has cost implications
-
-## Error Handling
-- Fetch strategies should raise `AssertionError` if status code is not 200
-- Core module catches `AssertionError` and falls back to Playwright in fallback mode
-- If parsing fails, retry with force-fallback mode to ensure JavaScript rendering
-
-## Adding New Strategies
-1. Create a new file in `fast_flights/` (e.g., `my_fetch.py`)
-2. Implement a function that accepts `params: dict` and returns `Response`
-3. Add the strategy to the mode options in [fast_flights/core.py](mdc:fast_flights/core.py)
-4. Update type hints to include the new mode literal
diff --git a/.cursor/rules/project-structure.mdc b/.cursor/rules/project-structure.mdc
deleted file mode 100644
index 6baeeba0..00000000
--- a/.cursor/rules/project-structure.mdc
+++ /dev/null
@@ -1,58 +0,0 @@
----
-alwaysApply: true
----
-
-# Fast-Flights Project Structure
-
-## Overview
-This is a Python-based Google Flights scraper that uses Protocol Buffers to decode Google's base64-encoded flight data. The project provides a strongly-typed API for fetching flight information.
-
-## Core Architecture
-
-### Main Entry Points
-- [fast_flights/__init__.py](mdc:fast_flights/__init__.py) - Public API exports
-- [fast_flights/core.py](mdc:fast_flights/core.py) - Primary flight fetching logic with multiple fetch modes
-
-### Key Components
-
-1. **Flight Data & Filters**
-   - [fast_flights/flights_impl.py](mdc:fast_flights/flights_impl.py) - Typed implementations of `FlightData`, `Passengers`, and `TFSData`
-   - [fast_flights/filter.py](mdc:fast_flights/filter.py) - Filter creation utilities
-
-2. **Protocol Buffers**
-   - [fast_flights/flights.proto](mdc:fast_flights/flights.proto) - Flight data protobuf schema
-   - [fast_flights/cookies.proto](mdc:fast_flights/cookies.proto) - Cookie/consent protobuf schema
-   - [fast_flights/flights_pb2.py](mdc:fast_flights/flights_pb2.py) - Generated protobuf code
-   - [fast_flights/cookies_pb2.py](mdc:fast_flights/cookies_pb2.py) - Generated protobuf code
-
-3. **Fetch Strategies**
-   - `primp` Client (default) - Fast HTTP client with browser impersonation
-   - `fallback_playwright` - Serverless Playwright fallback for blocked requests
-   - `local_playwright` - Local Playwright for development/testing
-   - `bright_data` - Bright Data proxy service
-
-4. **Data Processing**
-   - [fast_flights/schema.py](mdc:fast_flights/schema.py) - Response data models (`Result`, `Flight`)
-   - [fast_flights/decoder.py](mdc:fast_flights/decoder.py) - JavaScript data decoder for alternative data source
-   - HTML parsing using `selectolax.lexbor`
-
-5. **Generated Code**
-   - [fast_flights/_generated_enum.py](mdc:fast_flights/_generated_enum.py) - Auto-generated Airport enum
-   - [enums/generate_enums.py](mdc:enums/generate_enums.py) - Script to generate airport enums from CSV
-
-## Fetch Modes
-- `common` - Uses primp HTTP client only
-- `fallback` - Tries primp, falls back to Playwright if it fails
-- `force-fallback` - Forces Playwright usage
-- `local` - Uses local Playwright installation
-- `bright-data` - Uses Bright Data proxy service
-
-## Data Sources
-- `html` - Parses HTML response (default)
-- `js` - Parses JavaScript data from `<script>` tags
-
-## Key Patterns
-- All date strings should be in ISO format (YYYY-MM-DD)
-- Airport codes are 3-letter IATA codes
-- Strong typing throughout with dataclasses and typed implementations
-- Protobuf used for efficient data serialization
diff --git a/.cursor/rules/protobuf.mdc b/.cursor/rules/protobuf.mdc
deleted file mode 100644
index 79405b0f..00000000
--- a/.cursor/rules/protobuf.mdc
+++ /dev/null
@@ -1,42 +0,0 @@
----
-globs: *.proto,*_pb2.py
----
-
-# Protocol Buffers Guidelines
-
-## Proto Files
-- Use `syntax = "proto3"` at the top of all .proto files
-- Follow Google's protobuf style guide for naming conventions
-- Place .proto files in the main package directory ([fast_flights/](mdc:fast_flights/))
-
-## Generated Files
-- Never manually edit `*_pb2.py` files - they are auto-generated
-- Regenerate proto files after any .proto changes using:
-  ```bash
-  protoc --python_out=. fast_flights/flights.proto
-  protoc --python_out=. fast_flights/cookies.proto
-  ```
-
-## Working with Protobuf
-- Create typed wrapper classes for protobuf messages (see [fast_flights/flights_impl.py](mdc:fast_flights/flights_impl.py))
-- Use the `attach()` pattern to populate protobuf messages from typed wrappers
-- Serialize with `.SerializeToString()` and deserialize with `.ParseFromString()`
-- Base64 encode protobuf data when sending to Google Flights API
-
-## Type Annotations
-- Use `TYPE_CHECKING` to avoid runtime imports of protobuf types
-- Annotate protobuf message types as `Any` under TYPE_CHECKING block for type checkers
-
-## Common Patterns
-```python
-# Serialization
-info = PB.Info()
-# ... populate info ...
-raw = info.SerializeToString()
-encoded = base64.b64encode(raw)
-
-# Deserialization
-raw = base64.b64decode(encoded_string)
-pb = PB.SomeMessage()
-pb.ParseFromString(raw)
-```
diff --git a/.cursor/rules/python-conventions.mdc b/.cursor/rules/python-conventions.mdc
deleted file mode 100644
index f85fa7e7..00000000
--- a/.cursor/rules/python-conventions.mdc
+++ /dev/null
@@ -1,41 +0,0 @@
----
-globs: *.py,*.pyi
----
-
-# Python Coding Conventions
-
-## Type Annotations
-- Always use type hints for function parameters and return values
-- Use `from typing import` for complex types (Literal, Optional, Union, List, etc.)
-- Use `TYPE_CHECKING` for circular imports and type-only imports
-- Prefer `Optional[T]` over `T | None` for Python 3.8 compatibility
-- Use `Union[A, B]` instead of `A | B` for Python 3.8 compatibility
-
-## Python Version
-- Target Python 3.8+ as specified in [pyproject.toml](mdc:pyproject.toml)
-- Avoid using features only available in Python 3.9+
-
-## Dataclasses and Slots
-- Use `__slots__` for performance-critical classes (e.g., `FlightData`)
-- Use `@dataclass` from dataclasses module for simple data containers
-- Prefer explicit `__init__` methods when custom validation is needed
-
-## Overloads
-- Use `@overload` decorator from typing module for functions with different return types based on parameters
-- Always provide a non-overload implementation as the final definition
-
-## Assertions and Validation
-- Use `assert` for invariants and preconditions
-- Raise `ValueError` for invalid user input
-- Raise `RuntimeError` for unexpected runtime states
-- Include descriptive error messages
-
-## Imports
-- Group imports: standard library, third-party, local
-- Use absolute imports from package root (e.g., `from .schema import Result`)
-- Keep `__all__` exports updated in `__init__.py` files
-
-## Documentation
-- Use docstrings for public functions and classes
-- Follow Google-style docstring format with Args and Returns sections
-- Include type information in docstrings where helpful for users
diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc
deleted file mode 100644
index de7b4d53..00000000
--- a/.cursor/rules/testing.mdc
+++ /dev/null
@@ -1,52 +0,0 @@
----
-globs: test_*.py,*_test.py
----
-
-# Testing Guidelines
-
-## Test Files
-- Place test files in the project root (e.g., [test.py](mdc:test.py), [test_bright_data.py](mdc:test_bright_data.py))
-- Name test files with `test_` prefix or `_test` suffix
-- Each test file should be runnable independently
-
-## Test Structure
-```python
-from fast_flights import get_flights, FlightData, Passengers, Result
-
-# Test with real API calls
-result: Result = get_flights(
-    flight_data=[
-        FlightData(date="2025-01-01", from_airport="TPE", to_airport="MYJ")
-    ],
-    trip="one-way",
-    seat="economy",
-    passengers=Passengers(adults=2, children=1),
-    fetch_mode="fallback",  # Use fallback mode for reliability
-)
-
-assert result.flights, "Should return flights"
-print(result)
-```
-
-## Testing Best Practices
-- Use descriptive assertions with error messages
-- Test with multiple fetch modes when relevant
-- Use real dates in the future (not past dates)
-- Test edge cases: multi-city trips, different seat classes, various passenger combinations
-- Verify both successful responses and error handling
-
-## Data for Testing
-- Use valid 3-letter IATA airport codes
-- Test with international routes to catch regional issues
-- Consider time zones and date line crossing scenarios
-
-## Testing Fetch Strategies
-- Test with `fetch_mode="common"` first (fastest)
-- Use `fetch_mode="fallback"` for more reliable tests
-- Test `fetch_mode="local"` when Playwright is installed
-- Only test `fetch_mode="bright-data"` with valid credentials
-
-## Jupyter Notebooks
-- Use [data_discovery.ipynb](mdc:data_discovery.ipynb) for exploratory testing and debugging
-- Keep notebooks for documentation and experimentation
-- Export important discoveries to proper test files