rollinggo-flight 0.1.0__tar.gz

rollinggo_flight-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+rollinggo-npm-cli/node_modules/
+rollinggo-npm-cli/dist/
+rollinggo-npm-cli/*.tgz
+
+rollinggo-uv-cli/.venv/
+rollinggo-uv-cli/.pytest_cache/
+rollinggo-uv-cli/__pycache__/
+rollinggo-uv-cli/dist/
+rollinggo-uv-cli/src/**/__pycache__/
+rollinggo-uv-cli/tests/**/__pycache__/

rollinggo_flight-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: rollinggo-flight
+Version: 0.1.0
+Summary: RollingGo flight search CLI package for uvx.
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# RollingGo Flight CLI
+
+RollingGo flight search CLI for uvx.
+
+## Install
+
+```bash
+uvx rollinggo-flight search-airports --keyword Hangzhou
+```
+
+## Commands
+
+### search-airports
+
+Search airports by keyword.
+
+```bash
+rollinggo-flight search-airports --api-key <key> --keyword "Hangzhou"
+```
+
+### search-flights
+
+Search flights with structured filters.
+
+```bash
+rollinggo-flight search-flights --api-key <key> \
+  --from-city HGH --to-city CTU \
+  --from-date 2026-05-01 --trip-type ONE_WAY \
+  --adult-number 1 --child-number 0 --cabin-grade ECONOMY
+```

rollinggo_flight-0.1.0/README.md

@@ -0,0 +1,30 @@
+# RollingGo Flight CLI
+
+RollingGo flight search CLI for uvx.
+
+## Install
+
+```bash
+uvx rollinggo-flight search-airports --keyword Hangzhou
+```
+
+## Commands
+
+### search-airports
+
+Search airports by keyword.
+
+```bash
+rollinggo-flight search-airports --api-key <key> --keyword "Hangzhou"
+```
+
+### search-flights
+
+Search flights with structured filters.
+
+```bash
+rollinggo-flight search-flights --api-key <key> \
+  --from-city HGH --to-city CTU \
+  --from-date 2026-05-01 --trip-type ONE_WAY \
+  --adult-number 1 --child-number 0 --cabin-grade ECONOMY
+```

rollinggo_flight-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "rollinggo-flight"
+version = "0.1.0"
+description = "RollingGo flight search CLI package for uvx."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27.0",
+  "pydantic>=2.8.0",
+  "rich>=13.7.0",
+  "typer>=0.12.3",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.2",
+]
+
+[project.scripts]
+rollinggo-flight = "rollinggo_cli.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rollinggo_cli"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

rollinggo_flight-0.1.0/src/rollinggo_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

rollinggo_flight-0.1.0/src/rollinggo_cli/api.py

@@ -0,0 +1,67 @@
+import os
+from typing import Any
+
+import httpx
+
+from .constants import DEFAULT_BASE_URL
+from .errors import ApiRequestError, CliValidationError
+
+
+def normalize_base_url(base_url: str | None) -> str:
+    return (base_url or DEFAULT_BASE_URL).rstrip("/")
+
+
+def resolve_api_key(cli_api_key: str | None) -> str:
+    if cli_api_key:
+        return cli_api_key
+
+    env_api_key = os.getenv("ROLLINGGO_API_KEY")
+    if env_api_key:
+        return env_api_key
+
+    raise CliValidationError("Missing API key. Pass --api-key or set ROLLINGGO_API_KEY.")
+
+
+def request_api(
+    method: str,
+    endpoint: str,
+    api_key: str,
+    *,
+    base_url: str | None = None,
+    payload: dict[str, Any] | None = None,
+    transport: httpx.BaseTransport | None = None,
+) -> Any:
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Accept": "application/json",
+    }
+    if method.upper() == "POST":
+        headers["Content-Type"] = "application/json"
+
+    try:
+        with httpx.Client(
+            base_url=normalize_base_url(base_url),
+            timeout=30.0,
+            follow_redirects=True,
+            transport=transport,
+        ) as client:
+            response = client.request(method.upper(), endpoint, json=payload, headers=headers)
+            response.raise_for_status()
+            try:
+                return response.json()
+            except ValueError as exc:
+                raise ApiRequestError(
+                    f"HTTP request succeeded but returned invalid JSON: {exc}"
+                ) from exc
+    except httpx.HTTPStatusError as exc:
+        body = ""
+        try:
+            body = exc.response.text
+        except Exception:
+            body = ""
+        message = body or str(exc)
+        raise ApiRequestError(
+            f"HTTP request failed with status {exc.response.status_code}: {message}"
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise ApiRequestError(f"HTTP request failed: {exc}") from exc

rollinggo_flight-0.1.0/src/rollinggo_cli/cli.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from .api import request_api, resolve_api_key
+from .constants import CABIN_GRADES, DEFAULT_BASE_URL, TRIP_TYPES
+from .errors import ApiRequestError, CliValidationError
+from .models import build_airport_search_payload, build_flight_search_payload
+from .output import print_airport_table, print_flight_table, print_json
+
+AI_HELP_TEXT = (
+    "RollingGo flight CLI.\n\n"
+    "Recommended for AI agents: call standard subcommands with structured options, "
+    "for example `rollinggo-flight search-airports --keyword ...`. "
+    "Results are written to stdout as JSON by default.\n\n"
+    "Parameter discovery: use `rollinggo-flight <command> --help` to inspect required options, "
+    "accepted value formats, and command examples."
+)
+
+SEARCH_AIRPORTS_EXAMPLE = (
+    "Minimal example:\n"
+    '  rollinggo-flight search-airports --api-key <key> --keyword "Hangzhou"'
+)
+
+SEARCH_FLIGHTS_EXAMPLE = (
+    "Minimal example:\n"
+    '  rollinggo-flight search-flights --api-key <key> --from-city HGH --to-city CTU '
+    '--from-date 2026-05-01 --trip-type ONE_WAY --adult-number 1 --child-number 0 --cabin-grade ECONOMY'
+)
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help=AI_HELP_TEXT,
+)
+
+
+def _handle_error(exc: Exception, exit_code: int) -> None:
+    typer.echo(str(exc), err=True)
+    raise typer.Exit(code=exit_code) from exc
+
+
+def _resolve_format(output_format: str, *, allow_table: bool) -> str:
+    if output_format not in ("json", "table"):
+        raise CliValidationError("Output format must be json or table.")
+    if output_format == "table" and not allow_table:
+        raise CliValidationError("--format table is only supported by search-airports and search-flights.")
+    return output_format
+
+
+@app.command(
+    "search-airports",
+    help="Search airports by keyword.",
+    epilog=SEARCH_AIRPORTS_EXAMPLE,
+)
+def search_airports(
+    keyword: Annotated[
+        str,
+        typer.Option(
+            "--keyword",
+            help="Search keyword. Use English city name, airport name, or IATA code. Examples: Hangzhou, HGH.",
+        ),
+    ],
+    api_key: Annotated[
+        str | None,
+        typer.Option(
+            "--api-key",
+            help="RollingGo API key. If omitted, the CLI falls back to ROLLINGGO_API_KEY.",
+        ),
+    ] = None,
+    base_url: Annotated[
+        str,
+        typer.Option(
+            "--base-url",
+            help="Base URL for the RollingGo flight API. Override only for testing or private deployments.",
+        ),
+    ] = DEFAULT_BASE_URL,
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            help="Output format. Use json for machine parsing.",
+        ),
+    ] = "json",
+) -> None:
+    try:
+        output_format = _resolve_format(output_format, allow_table=True)
+        payload = build_airport_search_payload(keyword=keyword)
+        result = request_api(
+            "POST",
+            "/api/mcp/airportsearch",
+            resolve_api_key(api_key),
+            base_url=base_url,
+            payload=payload,
+        )
+        if output_format == "table":
+            print_airport_table(result)
+        else:
+            print_json(result)
+    except CliValidationError as exc:
+        _handle_error(exc, 2)
+    except ApiRequestError as exc:
+        _handle_error(exc, 1)
+
+
+@app.command(
+    "search-flights",
+    help="Search flights with structured filters.",
+    epilog=SEARCH_FLIGHTS_EXAMPLE,
+)
+def search_flights(
+    from_date: Annotated[
+        str,
+        typer.Option(
+            "--from-date",
+            help="Departure date in YYYY-MM-DD format.",
+        ),
+    ],
+    trip_type: Annotated[
+        str,
+        typer.Option(
+            "--trip-type",
+            help=f"Trip type. Supported values: {', '.join(TRIP_TYPES)}.",
+        ),
+    ],
+    adult_number: Annotated[
+        int,
+        typer.Option(
+            "--adult-number",
+            help="Number of adults. Integer >= 1.",
+        ),
+    ],
+    child_number: Annotated[
+        int,
+        typer.Option(
+            "--child-number",
+            help="Number of children. Integer >= 0.",
+        ),
+    ],
+    cabin_grade: Annotated[
+        str,
+        typer.Option(
+            "--cabin-grade",
+            help=f"Cabin class. Supported values: {', '.join(CABIN_GRADES)}.",
+        ),
+    ],
+    api_key: Annotated[
+        str | None,
+        typer.Option(
+            "--api-key",
+            help="RollingGo API key. If omitted, the CLI falls back to ROLLINGGO_API_KEY.",
+        ),
+    ] = None,
+    base_url: Annotated[
+        str,
+        typer.Option(
+            "--base-url",
+            help="Base URL for the RollingGo flight API. Override only for testing or private deployments.",
+        ),
+    ] = DEFAULT_BASE_URL,
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            help="Output format. Use json for machine parsing.",
+        ),
+    ] = "json",
+    ret_date: Annotated[
+        str | None,
+        typer.Option(
+            "--ret-date",
+            help="Return date in YYYY-MM-DD format. Required when --trip-type is ROUND_TRIP.",
+        ),
+    ] = None,
+    from_city: Annotated[
+        str | None,
+        typer.Option(
+            "--from-city",
+            help="Departure city code. Mutually exclusive with --from-airport.",
+        ),
+    ] = None,
+    from_airport: Annotated[
+        str | None,
+        typer.Option(
+            "--from-airport",
+            help="Departure airport code (IATA). Mutually exclusive with --from-city.",
+        ),
+    ] = None,
+    to_city: Annotated[
+        str | None,
+        typer.Option(
+            "--to-city",
+            help="Arrival city code. Mutually exclusive with --to-airport.",
+        ),
+    ] = None,
+    to_airport: Annotated[
+        str | None,
+        typer.Option(
+            "--to-airport",
+            help="Arrival airport code (IATA). Mutually exclusive with --to-city.",
+        ),
+    ] = None,
+) -> None:
+    try:
+        output_format = _resolve_format(output_format, allow_table=True)
+        payload = build_flight_search_payload(
+            adult_number=adult_number,
+            child_number=child_number,
+            cabin_grade=cabin_grade,
+            from_date=from_date,
+            trip_type=trip_type,
+            ret_date=ret_date,
+            from_city=from_city,
+            from_airport=from_airport,
+            to_city=to_city,
+            to_airport=to_airport,
+        )
+        result = request_api(
+            "POST",
+            "/api/mcp/flightsearch",
+            resolve_api_key(api_key),
+            base_url=base_url,
+            payload=payload,
+        )
+        if output_format == "table":
+            print_flight_table(result)
+        else:
+            print_json(result)
+    except CliValidationError as exc:
+        _handle_error(exc, 2)
+    except ApiRequestError as exc:
+        _handle_error(exc, 1)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

rollinggo_flight-0.1.0/src/rollinggo_cli/constants.py

@@ -0,0 +1,36 @@
+import os
+
+BASE_URL_STAGING = "https://travelportal-api-staging.aigohotel.com"
+BASE_URL_PRODUCTION = "https://mcp.rollinggo.cn"
+DEFAULT_BASE_URL = os.getenv("ROLLINGGO_API_BASE_URL", BASE_URL_STAGING)
+
+CABIN_GRADES = (
+    "ECONOMY",
+    "PREMIUM_ECONOMY",
+    "BUSINESS",
+    "FIRST",
+)
+
+TRIP_TYPES = (
+    "ONE_WAY",
+    "ROUND_TRIP",
+)
+
+AIRPORT_TABLE_COLUMNS = [
+    ("airportCode", "airportCode"),
+    ("airportName", "airportName"),
+    ("cityCode", "cityCode"),
+    ("cityName", "cityName"),
+    ("countryCode", "countryCode"),
+    ("countryName", "countryName"),
+]
+
+FLIGHT_TABLE_COLUMNS = [
+    ("flightNo", "flightNo"),
+    ("airlineName", "airlineName"),
+    ("fromAirport", "fromAirport"),
+    ("toAirport", "toAirport"),
+    ("fromDate", "fromDate"),
+    ("price", "price"),
+    ("currency", "currency"),
+]

rollinggo_flight-0.1.0/src/rollinggo_cli/errors.py

@@ -0,0 +1,6 @@
+class CliValidationError(Exception):
+    pass
+
+
+class ApiRequestError(Exception):
+    pass

rollinggo_flight-0.1.0/src/rollinggo_cli/models.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import re
+from datetime import date
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, ValidationError, field_validator, model_validator
+
+from .constants import CABIN_GRADES, TRIP_TYPES
+from .errors import CliValidationError
+
+OutputFormat = Literal["json", "table"]
+
+DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def _error_message(exc: ValidationError) -> str:
+    first_error = exc.errors()[0]
+    location = ".".join(str(part) for part in first_error["loc"])
+    return f"Invalid value for {location}: {first_error['msg']}"
+
+
+def _validate_date(value: str, field_name: str) -> None:
+    if not DATE_RE.fullmatch(value):
+        raise CliValidationError(f"{field_name} must use YYYY-MM-DD format.")
+
+
+class AirportSearchInput(BaseModel):
+    keyword: str = Field(min_length=1)
+
+    def to_payload(self) -> dict[str, Any]:
+        return {"keyword": self.keyword}
+
+
+class FlightSearchInput(BaseModel):
+    adult_number: int = Field(ge=1)
+    child_number: int = Field(ge=0)
+    cabin_grade: Literal["ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST"]
+    from_date: str
+    trip_type: Literal["ONE_WAY", "ROUND_TRIP"]
+    ret_date: str | None = None
+    from_city: str | None = None
+    from_airport: str | None = None
+    to_city: str | None = None
+    to_airport: str | None = None
+
+    @field_validator("from_date", "ret_date", mode="before")
+    @classmethod
+    def validate_date_format(cls, value: str | None) -> str | None:
+        if value is not None:
+            _validate_date(value, "date")
+        return value
+
+    @model_validator(mode="after")
+    def validate_flight_search(self) -> "FlightSearchInput":
+        if self.trip_type == "ROUND_TRIP" and not self.ret_date:
+            raise ValueError("retDate is required when tripType is ROUND_TRIP.")
+        if not self.from_city and not self.from_airport:
+            raise ValueError("Provide either from_city or from_airport.")
+        if not self.to_city and not self.to_airport:
+            raise ValueError("Provide either to_city or to_airport.")
+        return self
+
+    def to_payload(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "adultNumber": self.adult_number,
+            "childNumber": self.child_number,
+            "cabinGrade": self.cabin_grade,
+            "fromDate": self.from_date,
+            "tripType": self.trip_type,
+        }
+
+        if self.ret_date:
+            payload["retDate"] = self.ret_date
+        if self.from_city:
+            payload["fromCity"] = self.from_city
+        if self.from_airport:
+            payload["fromAirport"] = self.from_airport
+        if self.to_city:
+            payload["toCity"] = self.to_city
+        if self.to_airport:
+            payload["toAirport"] = self.to_airport
+
+        return payload
+
+
+def build_airport_search_payload(**kwargs: Any) -> dict[str, Any]:
+    try:
+        payload = AirportSearchInput(**kwargs)
+    except ValidationError as exc:
+        raise CliValidationError(_error_message(exc)) from exc
+    return payload.to_payload()
+
+
+def build_flight_search_payload(**kwargs: Any) -> dict[str, Any]:
+    try:
+        payload = FlightSearchInput(**kwargs)
+    except ValidationError as exc:
+        raise CliValidationError(_error_message(exc)) from exc
+    return payload.to_payload()

rollinggo_flight-0.1.0/src/rollinggo_cli/output.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+from .constants import AIRPORT_TABLE_COLUMNS, FLIGHT_TABLE_COLUMNS
+
+
+def remove_field(data: Any, field_name: str) -> Any:
+    if isinstance(data, dict):
+        return {
+            key: remove_field(value, field_name)
+            for key, value in data.items()
+            if key != field_name
+        }
+    if isinstance(data, list):
+        return [remove_field(item, field_name) for item in data]
+    return data
+
+
+def print_json(data: Any) -> None:
+    sys.stdout.write(json.dumps(data, ensure_ascii=False, indent=2))
+    sys.stdout.write("\n")
+
+
+def _find_rows(data: Any, identifier_keys: tuple[str, ...]) -> list[dict[str, Any]]:
+    if isinstance(data, list):
+        return [row for row in data if isinstance(row, dict)]
+
+    if isinstance(data, dict):
+        if any(key in data for key in identifier_keys):
+            return [data]
+
+        for key in ("data", "airPortInformationList", "flightInformationList", "items", "results", "list"):
+            value = data.get(key)
+            if isinstance(value, list):
+                return [row for row in value if isinstance(row, dict)]
+            if isinstance(value, dict):
+                nested_rows = _find_rows(value, identifier_keys)
+                if nested_rows:
+                    return nested_rows
+
+        for value in data.values():
+            nested_rows = _find_rows(value, identifier_keys)
+            if nested_rows:
+                return nested_rows
+
+    return []
+
+
+def print_airport_table(data: Any) -> None:
+    table = Table()
+    for header, _ in AIRPORT_TABLE_COLUMNS:
+        table.add_column(header)
+
+    for row in _find_rows(data, ("airportCode", "airportName")):
+        table.add_row(*[str(row.get(key, "")) for _, key in AIRPORT_TABLE_COLUMNS])
+
+    console = Console(file=sys.stdout)
+    console.print(table)
+
+
+def print_flight_table(data: Any) -> None:
+    table = Table()
+    for header, _ in FLIGHT_TABLE_COLUMNS:
+        table.add_column(header)
+
+    for row in _find_rows(data, ("flightNo", "airlineName")):
+        table.add_row(*[str(row.get(key, "")) for _, key in FLIGHT_TABLE_COLUMNS])
+
+    console = Console(file=sys.stdout)
+    console.print(table)

rollinggo_flight-0.1.0/tests/test_models.py

@@ -0,0 +1,102 @@
+import pytest
+
+from rollinggo_cli.models import (
+    build_airport_search_payload,
+    build_flight_search_payload,
+)
+
+
+def test_airport_search_payload():
+    payload = build_airport_search_payload(keyword="Hangzhou")
+    assert payload == {"keyword": "Hangzhou"}
+
+
+def test_airport_search_payload_empty_keyword():
+    with pytest.raises(Exception):
+        build_airport_search_payload(keyword="")
+
+
+def test_flight_search_one_way():
+    payload = build_flight_search_payload(
+        adult_number=1,
+        child_number=0,
+        cabin_grade="ECONOMY",
+        from_date="2026-05-01",
+        trip_type="ONE_WAY",
+        from_city="HGH",
+        to_city="CTU",
+    )
+    assert payload["adultNumber"] == 1
+    assert payload["childNumber"] == 0
+    assert payload["cabinGrade"] == "ECONOMY"
+    assert payload["fromDate"] == "2026-05-01"
+    assert payload["tripType"] == "ONE_WAY"
+    assert payload["fromCity"] == "HGH"
+    assert payload["toCity"] == "CTU"
+    assert "retDate" not in payload
+
+
+def test_flight_search_round_trip():
+    payload = build_flight_search_payload(
+        adult_number=2,
+        child_number=1,
+        cabin_grade="BUSINESS",
+        from_date="2026-05-01",
+        trip_type="ROUND_TRIP",
+        ret_date="2026-05-10",
+        from_airport="HGH",
+        to_airport="TFU",
+    )
+    assert payload["retDate"] == "2026-05-10"
+    assert payload["fromAirport"] == "HGH"
+    assert payload["toAirport"] == "TFU"
+
+
+def test_flight_search_round_trip_missing_ret_date():
+    with pytest.raises(Exception):
+        build_flight_search_payload(
+            adult_number=1,
+            child_number=0,
+            cabin_grade="ECONOMY",
+            from_date="2026-05-01",
+            trip_type="ROUND_TRIP",
+            from_city="HGH",
+            to_city="CTU",
+        )
+
+
+def test_flight_search_missing_origin():
+    with pytest.raises(Exception):
+        build_flight_search_payload(
+            adult_number=1,
+            child_number=0,
+            cabin_grade="ECONOMY",
+            from_date="2026-05-01",
+            trip_type="ONE_WAY",
+            to_city="CTU",
+        )
+
+
+def test_flight_search_missing_destination():
+    with pytest.raises(Exception):
+        build_flight_search_payload(
+            adult_number=1,
+            child_number=0,
+            cabin_grade="ECONOMY",
+            from_date="2026-05-01",
+            trip_type="ONE_WAY",
+            from_city="HGH",
+        )
+
+
+def test_flight_search_invalid_date():
+    with pytest.raises(Exception):
+        build_flight_search_payload(
+            adult_number=1,
+            child_number=0,
+            cabin_grade="ECONOMY",
+            from_date="2026/05/01",
+            trip_type="ONE_WAY",
+            from_city="HGH",
+            to_city="CTU",
+        )