bookalimo 1.0.0__py3-none-any.whl → 1.0.2__py3-none-any.whl

bookalimo/schemas/{booking.py → shared.py}

@@ -1,6 +1,7 @@
 """
-Pydantic schemas for Book-A-Limo booking operations.
-Includes all models related to pricing, reservations, and booking requests.
+Shared base models for Book-A-Limo API data structures.
+Contains field definitions without serialization opinions -
+request/response variants inherit from these and set appropriate serialization.
 """
 
 import warnings
@@ -14,7 +15,7 @@ import us
 from pydantic import Field, model_validator
 from typing_extensions import Self
 
-from .base import ApiModel
+from .base import SharedModel
 
 
 @lru_cache(maxsize=1)
@@ -28,15 +29,16 @@ def _load_iata_index() -> tuple[dict[str, Any], dict[str, list[str]]]:
     return data, by_country
 
 
+# Enums (no serialization issues)
 class RateType(Enum):
     """Rate types for reservations."""
 
-    P2P = 0  # Point-to-Point (best guess from context)
-    HOURLY = 1  # Hourly (best guess from context)
+    P2P = 0  # Point-to-Point
+    HOURLY = 1  # Hourly
     DAILY = 2  # Daily
     TOUR = 3  # Tour
     ROUND_TRIP = 4  # Round Trip
-    RT_HALF = 5  # RT Half
+    RT_HALF = 5  # Round Trip Half Day
 
 
 class LocationType(Enum):
@@ -76,20 +78,17 @@ class ReservationStatus(Enum):
 
 
 class CardHolderType(Enum):
-    """
-    Credit card holder types (API Documentation Unclear).
-    TODO: Update when API documentation is clarified by the API author.
-    Best guess based on typical credit card processing:
-    """
+    """Credit card holder types."""
 
-    PERSONAL = 0  # Personal/Individual account (best guess)
-    BUSINESS = 1  # Business/Corporate account (best guess)
-    # Note: Add UNKNOWN = 3 if you see this value in responses
-    UNKNOWN = 3  # From example in API doc
+    CORPORATE = 0
+    AGENCY = 1
+    THIRD_PARTY = 2
+    SAME_AS_PASSENGER = 3
 
 
-class City(ApiModel):
-    """City information."""
+# Shared Data Models
+class CityBase(SharedModel):
+    """Base city information."""
 
     city_name: str
     country_code: str = Field(..., description="ISO 3166-1 alpha-2 country code")
@@ -130,15 +129,18 @@ class City(ApiModel):
         )
 
 
-class Address(ApiModel):
-    """
-    Address information.
-    """
+class AddressBase(SharedModel):
+    """Base address information."""
 
     google_geocode: Optional[dict[str, Any]] = Field(
-        default=None, description="Raw Google Geocoding API response (recommended)"
+        default=None,
+        description=(
+            "Raw Google Geocoding API result (recommended). "
+            "Common mistake is to use the response object instead of the result object. "
+            "You must use geocode_response['results'][0] to get the result object."
+        ),
     )
-    city: Optional[City] = Field(
+    city: Optional["CityBase"] = Field(
         default=None, description="Use only if google_geocode not available"
     )
     district: Optional[str] = Field(default=None, description="e.g., Manhattan")
@@ -179,8 +181,8 @@ class Address(ApiModel):
         return self
 
 
-class Airport(ApiModel):
-    """Airport information."""
+class AirportBase(SharedModel):
+    """Base airport information."""
 
     iata_code: str = Field(..., description="3-letter IATA code, e.g., JFK")
     country_code: Optional[str] = Field(default=None, description="ISO 3166-1 alpha-2")
@@ -195,7 +197,7 @@ class Airport(ApiModel):
     )
     flight_number: Optional[str] = Field(default=None, description="e.g., UA1234")
     terminal: Optional[str] = Field(default=None, description="e.g., 7")
-    arriving_from_city: Optional[City] = None
+    arriving_from_city: Optional["CityBase"] = None
     meet_greet: Optional[int] = Field(
         default=None,
         description="Meet & greet option ID. Leave empty on price request to see options.",
@@ -226,12 +228,12 @@ class Airport(ApiModel):
         return self
 
 
-class Location(ApiModel):
-    """Location (address or airport)."""
+class LocationBase(SharedModel):
+    """Base location (address or airport)."""
 
     type: LocationType
-    address: Optional[Address] = None
-    airport: Optional[Airport] = None
+    address: Optional["AddressBase"] = None
+    airport: Optional["AirportBase"] = None
 
     @model_validator(mode="after")
     def validate_location(self) -> Self:
@@ -244,15 +246,15 @@ class Location(ApiModel):
         return self
 
 
-class Stop(ApiModel):
-    """Stop information."""
+class StopBase(SharedModel):
+    """Base stop information."""
 
     description: str = Field(..., description="Address, place name, or comment")
     is_en_route: bool = Field(..., description="True if stop is en-route")
 
 
-class Account(ApiModel):
-    """Travel agency or corporate account info."""
+class AccountBase(SharedModel):
+    """Base travel agency or corporate account info."""
 
     id: str = Field(..., description="TA or corporate account number")
     department: Optional[str] = None
@@ -262,8 +264,8 @@ class Account(ApiModel):
     booker_phone: Optional[str] = Field(default=None, description="E164 format")
 
 
-class Passenger(ApiModel):
-    """Passenger information."""
+class PassengerBase(SharedModel):
+    """Base passenger information."""
 
     first_name: str
     last_name: str
@@ -271,15 +273,15 @@ class Passenger(ApiModel):
     phone: str = Field(..., description="E164 format recommended")
 
 
-class Reward(ApiModel):
-    """Reward account information."""
+class RewardBase(SharedModel):
+    """Base reward account information."""
 
     type: RewardType
     value: str = Field(..., description="Reward account number")
 
 
-class CreditCard(ApiModel):
-    """Credit card information."""
+class CreditCardBase(SharedModel):
+    """Base credit card information."""
 
     number: str
     expiration: str = Field(..., description="MM/YY format")
@@ -288,12 +290,12 @@ class CreditCard(ApiModel):
     zip: Optional[str] = None
     holder_type: Optional[CardHolderType] = Field(
         default=None,
-        description="Card holder type - API documentation unclear, using best guess",
+        description="Card holder type",
     )
 
 
-class BreakdownItem(ApiModel):
-    """Price breakdown item."""
+class BreakdownItemBase(SharedModel):
+    """Base price breakdown item."""
 
     name: str
     value: float
@@ -302,28 +304,28 @@ class BreakdownItem(ApiModel):
     )
 
 
-class MeetGreetAdditional(ApiModel):
-    """Additional meet & greet charges."""
+class MeetGreetAdditionalBase(SharedModel):
+    """Base additional meet & greet charges."""
 
     name: str
     price: float
 
 
-class MeetGreet(ApiModel):
-    """Meet & greet option."""
+class MeetGreetBase(SharedModel):
+    """Base meet & greet option."""
 
     id: int
     name: str
     base_price: float
     instructions: str
-    additional: list[MeetGreetAdditional]
+    additional: list["MeetGreetAdditionalBase"]
     total_price: float
     fees: float
     reservation_price: float
 
 
-class Price(ApiModel):
-    """Car class pricing information."""
+class PriceBase(SharedModel):
+    """Base car class pricing information."""
 
     car_class: str
     car_description: str
@@ -335,11 +337,11 @@ class Price(ApiModel):
     image_256: str = Field(alias="image256")
     image_512: str = Field(alias="image512")
     default_meet_greet: Optional[int] = None
-    meet_greets: list[MeetGreet] = Field(default_factory=list)
+    meet_greets: list["MeetGreetBase"] = Field(default_factory=list)
 
 
-class Reservation(ApiModel):
-    """Basic reservation information."""
+class ReservationBase(SharedModel):
+    """Base reservation information."""
 
     confirmation_number: str
     is_archive: bool
@@ -353,168 +355,3 @@ class Reservation(ApiModel):
     dropoff: str
     car_class: str
     status: Optional[ReservationStatus] = None
-
-
-class EditableReservationRequest(ApiModel):
-    """
-    Editable reservation for modifications.
-
-    Note: API documentation inconsistency - credit_card marked as required in model
-    but omitted in edit examples. Making it optional as edit requests may not need it.
-    TODO: Clarify with API author when credit_card is actually required.
-    """
-
-    confirmation: str
-    is_cancel_request: bool = False
-    rate_type: Optional[RateType] = None
-    pickup_date: Optional[str] = Field(default=None, description="MM/dd/yyyy format")
-    pickup_time: Optional[str] = Field(default=None, description="hh:mm tt format")
-    stops: Optional[list[Stop]] = None
-    credit_card: Optional[CreditCard] = Field(
-        default=None,
-        description="Conditionally required - unclear from API docs when exactly",
-    )
-    passengers: Optional[int] = None
-    luggage: Optional[int] = None
-    pets: Optional[int] = None
-    car_seats: Optional[int] = None
-    boosters: Optional[int] = None
-    infants: Optional[int] = None
-    other: Optional[str] = Field(default=None, description="Other changes not listed")
-
-
-# Request/Response Models
-
-
-class PriceRequest(ApiModel):
-    """Request for getting prices."""
-
-    rate_type: RateType
-    date_time: str = Field(..., description="MM/dd/yyyy hh:mm tt format")
-    pickup: Location
-    dropoff: Location
-    hours: Optional[int] = Field(default=None, description="For hourly rate_type only")
-    passengers: int
-    luggage: int
-    stops: Optional[list[Stop]] = None
-    account: Optional[Account] = Field(
-        default=None, description="TAs must provide for commission"
-    )
-    passenger: Optional[Passenger] = None
-    rewards: Optional[list[Reward]] = None
-    car_class_code: Optional[str] = Field(
-        default=None, description="e.g., 'SD' for specific car class"
-    )
-    pets: Optional[int] = None
-    car_seats: Optional[int] = None
-    boosters: Optional[int] = None
-    infants: Optional[int] = None
-    customer_comment: Optional[str] = None
-
-
-class PriceResponse(ApiModel):
-    """Response from get prices."""
-
-    token: str
-    prices: list[Price]
-
-
-class DetailsRequest(ApiModel):
-    """Request for setting reservation details."""
-
-    token: str
-    car_class_code: Optional[str] = None
-    pickup: Optional[Location] = None
-    dropoff: Optional[Location] = None
-    stops: Optional[list[Stop]] = None
-    account: Optional[Account] = None
-    passenger: Optional[Passenger] = None
-    rewards: Optional[list[Reward]] = None
-    pets: Optional[int] = None
-    car_seats: Optional[int] = None
-    boosters: Optional[int] = None
-    infants: Optional[int] = None
-    customer_comment: Optional[str] = None
-    ta_fee: Optional[float] = Field(
-        default=None, description="For Travel Agencies - additional fee in USD"
-    )
-
-
-class DetailsResponse(ApiModel):
-    """Response from set details."""
-
-    price: float
-    breakdown: list[BreakdownItem]
-
-
-class BookRequest(ApiModel):
-    """Request for booking reservation."""
-
-    token: str
-    promo: Optional[str] = None
-    method: Optional[str] = Field(
-        default=None, description="'charge' for charge accounts"
-    )
-    credit_card: Optional[CreditCard] = None
-
-    @model_validator(mode="after")
-    def validate_book_request(self) -> Self:
-        """Validate that either method or credit_card is provided."""
-        if not self.method and not self.credit_card:
-            raise ValueError("Either method='charge' or credit_card must be provided")
-
-        return self
-
-
-class BookResponse(ApiModel):
-    """Response from book reservation."""
-
-    reservation_id: str
-
-
-class ListReservationsRequest(ApiModel):
-    """Request for listing reservations."""
-
-    is_archive: bool = False
-
-
-class ListReservationsResponse(ApiModel):
-    """Response from list reservations."""
-
-    success: bool
-    reservations: list[Reservation] = Field(default_factory=list)
-    error: Optional[str] = None
-
-
-class GetReservationRequest(ApiModel):
-    """Request for getting reservation details."""
-
-    confirmation: str
-
-
-class GetReservationResponse(ApiModel):
-    """Response from get reservation."""
-
-    reservation: EditableReservationRequest
-    is_editable: bool
-    status: Optional[ReservationStatus] = None
-    is_cancellation_pending: bool
-    car_description: Optional[str] = None
-    cancellation_policy: Optional[str] = None
-    pickup_type: LocationType
-    pickup_description: str
-    dropoff_type: LocationType
-    dropoff_description: str
-    additional_services: Optional[str] = None
-    payment_method: Optional[str] = None
-    breakdown: list[BreakdownItem] = Field(default_factory=list)
-    passenger_name: Optional[str] = None
-    evoucher_url: Optional[str] = None
-    receipt_url: Optional[str] = None
-    pending_changes: list[list[str]] = Field(default_factory=list)
-
-
-class EditReservationResponse(ApiModel):
-    """Response from edit reservation."""
-
-    success: bool

bookalimo/services/pricing.py

@@ -1,14 +1,10 @@
 """Pricing service for getting quotes and updating trip details."""
 
-from typing import Any
-
-from ..schemas.booking import (
+from ..schemas import (
     DetailsRequest,
     DetailsResponse,
-    Location,
     PriceRequest,
     PriceResponse,
-    RateType,
 )
 from ..transport.base import AsyncBaseTransport, BaseTransport
 
@@ -19,86 +15,28 @@ class AsyncPricingService:
     def __init__(self, transport: AsyncBaseTransport):
         self._transport = transport
 
-    async def quote(
-        self,
-        rate_type: RateType,
-        date_time: str,
-        pickup: Location,
-        dropoff: Location,
-        passengers: int,
-        luggage: int,
-        **opts: Any,
-    ) -> PriceResponse:
+    async def quote(self, request: PriceRequest) -> PriceResponse:
         """
         Get pricing for a trip.
 
         Args:
-            rate_type: Rate type (P2P, HOURLY, etc.)
-            date_time: Date and time in 'MM/dd/yyyy hh:mm tt' format
-            pickup: Pickup location
-            dropoff: Dropoff location
-            passengers: Number of passengers
-            luggage: Number of luggage pieces
-            **opts: Optional fields like hours, stops, account, car_class_code,
-                   passenger, rewards, pets, car_seats, boosters, infants,
-                   customer_comment
+            request: Complete pricing request with all trip details
 
         Returns:
             PriceResponse with pricing information and session token
         """
-        # Build request with optional fields
-        request_data: dict[str, Any] = {
-            "rate_type": rate_type,
-            "date_time": date_time,
-            "pickup": pickup,
-            "dropoff": dropoff,
-            "passengers": passengers,
-            "luggage": luggage,
-        }
-
-        # Add optional fields if provided
-        optional_fields = [
-            "hours",
-            "stops",
-            "account",
-            "passenger",
-            "rewards",
-            "car_class_code",
-            "pets",
-            "car_seats",
-            "boosters",
-            "infants",
-            "customer_comment",
-        ]
-
-        for field in optional_fields:
-            if field in opts and opts[field] is not None:
-                request_data[field] = opts[field]
-
-        request = PriceRequest(**request_data)
         return await self._transport.post("/booking/price/", request, PriceResponse)
 
-    async def update_details(self, token: str, **details: Any) -> DetailsResponse:
+    async def update_details(self, request: DetailsRequest) -> DetailsResponse:
         """
         Update reservation details and get updated pricing.
 
         Args:
-            token: Session token from quote()
-            **details: Fields to update (car_class_code, pickup, dropoff,
-                      stops, account, passenger, rewards, pets, car_seats,
-                      boosters, infants, customer_comment, ta_fee)
+            request: Complete details request with token and fields to update
 
         Returns:
             DetailsResponse with updated pricing
         """
-        request_data: dict[str, Any] = {"token": token}
-
-        # Add provided details
-        for key, value in details.items():
-            if value is not None:
-                request_data[key] = value
-
-        request = DetailsRequest(**request_data)
         return await self._transport.post("/booking/details/", request, DetailsResponse)
 
 
@@ -108,84 +46,26 @@ class PricingService:
     def __init__(self, transport: BaseTransport):
         self._transport = transport
 
-    def quote(
-        self,
-        rate_type: RateType,
-        date_time: str,
-        pickup: Location,
-        dropoff: Location,
-        passengers: int,
-        luggage: int,
-        **opts: Any,
-    ) -> PriceResponse:
+    def quote(self, request: PriceRequest) -> PriceResponse:
         """
         Get pricing for a trip.
 
         Args:
-            rate_type: Rate type (P2P, HOURLY, etc.)
-            date_time: Date and time in 'MM/dd/yyyy hh:mm tt' format
-            pickup: Pickup location
-            dropoff: Location
-            passengers: Number of passengers
-            luggage: Number of luggage pieces
-            **opts: Optional fields like hours, stops, account, car_class_code,
-                   passenger, rewards, pets, car_seats, boosters, infants,
-                   customer_comment
+            request: Complete pricing request with all trip details
 
         Returns:
             PriceResponse with pricing information and session token
         """
-        # Build request with optional fields
-        request_data: dict[str, Any] = {
-            "rate_type": rate_type,
-            "date_time": date_time,
-            "pickup": pickup,
-            "dropoff": dropoff,
-            "passengers": passengers,
-            "luggage": luggage,
-        }
-
-        # Add optional fields if provided
-        optional_fields = [
-            "hours",
-            "stops",
-            "account",
-            "passenger",
-            "rewards",
-            "car_class_code",
-            "pets",
-            "car_seats",
-            "boosters",
-            "infants",
-            "customer_comment",
-        ]
-
-        for field in optional_fields:
-            if field in opts and opts[field] is not None:
-                request_data[field] = opts[field]
-
-        request = PriceRequest(**request_data)
         return self._transport.post("/booking/price/", request, PriceResponse)
 
-    def update_details(self, token: str, **details: Any) -> DetailsResponse:
+    def update_details(self, request: DetailsRequest) -> DetailsResponse:
         """
         Update reservation details and get updated pricing.
 
         Args:
-            token: Session token from quote()
-            **details: Fields to update (car_class_code, pickup, dropoff,
-                      stops, account, passenger, rewards, pets, car_seats,
-                      boosters, infants, customer_comment, ta_fee)
+            request: Complete details request with token and fields to update
 
         Returns:
             DetailsResponse with updated pricing
         """
-        request_data: dict[str, Any] = {"token": token}
-
-        # Add provided details
-        for key, value in details.items():
-            if value is not None:
-                request_data[key] = value
-
-        request = DetailsRequest(**request_data)
         return self._transport.post("/booking/details/", request, DetailsResponse)