Metadata-Version: 2.4
Name: bookalimo
Version: 0.1.5
Summary: Python wrapper for the Book-A-Limo API
Author-email: Jonathan Oren <jonathan@bookalimo.com>
Maintainer-email: Jonathan Oren <jonathan@bookalimo.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/bookalimo-python
Project-URL: Documentation, https://yourusername.github.io/bookalimo-python
Project-URL: Repository, https://github.com/yourusername/bookalimo-python
Project-URL: Issues, https://github.com/yourusername/bookalimo-python/issues
Project-URL: Changelog, https://github.com/yourusername/bookalimo-python/blob/main/CHANGELOG.md
Keywords: bookalimo,api,transportation,booking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pycountry>=22.0.0
Requires-Dist: us>=3.0.0
Requires-Dist: airportsdata>=20230101
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: httpx[mock]>=0.25.0; extra == "dev"
Requires-Dist: respx>=0.20.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: mkdocs>=1.5.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.0.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.23.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.23.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: httpx[mock]>=0.25.0; extra == "test"
Requires-Dist: respx>=0.20.0; extra == "test"
Dynamic: license-file

# Book-A-Limo Python SDK

[![PyPI version](https://badge.fury.io/py/bookalimo.svg)](https://badge.fury.io/py/bookalimo)
[![Python Support](https://img.shields.io/pypi/pyversions/bookalimo.svg)](https://pypi.org/project/bookalimo/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

A modern, async Python wrapper for the Book-A-Limo API with full type support. Built on top of `httpx` and `pydantic`.

## Table of Contents

- [Book-A-Limo Python SDK](#book-a-limo-python-sdk)
  - [Table of Contents](#table-of-contents)
  - [Features](#features)
  - [Requirements](#requirements)
  - [Installation](#installation)
  - [Quick Start](#quick-start)
  - [Authentication](#authentication)
  - [Core Operations](#core-operations)
    - [Get Pricing](#get-pricing)
    - [Book a Reservation](#book-a-reservation)
  - [Location Builders](#location-builders)
    - [Airport Locations](#airport-locations)
    - [Address Locations](#address-locations)
    - [Stops](#stops)
  - [Advanced](#advanced)
    - [Using Account Info (Travel Agents)](#using-account-info-travel-agents)
    - [Edit / Cancel a Reservation](#edit--cancel-a-reservation)
  - [Error Handling](#error-handling)
  - [Logging](#logging)
    - [Enable Debug Logging](#enable-debug-logging)
    - [Custom Logging](#custom-logging)
    - [Security](#security)
    - [Disable Logging](#disable-logging)
  - [Development](#development)
  - [Security Notes](#security-notes)
  - [License](#license)
  - [Changelog](#changelog)

## Features

* **Asynchronous**
* **Fully Typed** for requests & responses
* **Input validation** including airports and addresses.
* **Clean, minimal interface** for each API operation
* **Custom exceptions & error handling**
* **Tests and examples**

## Requirements

* Python **3.9+** (`pyproject.toml` sets `requires-python = ">=3.9"`)
* An async event loop (examples use `asyncio`)
* Time strings use **`MM/dd/yyyy hh:mm tt`** (e.g., `09/05/2025 12:44 AM`)

## Installation

```bash
pip install bookalimo
```

## Quick Start

```python
import asyncio

from bookalimo import (
    BookALimo,
    create_credentials,
    create_airport_location,
    create_address_location,
)
from bookalimo.models import RateType

async def main():
    # For Travel Agents (customers: pass is_customer=True)
    credentials = create_credentials("TA10007", "your_password")

    async with BookALimo(credentials) as client:
        # Build locations
        pickup = create_airport_location("JFK", "New York")
        dropoff = create_address_location("53 East 34th Street, Manhattan")

        prices = await client.get_prices(
            rate_type=RateType.P2P,
            date_time="09/05/2025 12:44 AM",
            pickup=pickup,
            dropoff=dropoff,
            passengers=2,
            luggage=3,
        )

        print(f"Available cars: {len(prices.prices)}")
        for price in prices.prices:
            print(f"- {price.car_description}: ${price.price}")

if __name__ == "__main__":
    asyncio.run(main())
```

## Authentication

```python
from bookalimo import create_credentials

# Travel Agents
ta_creds = create_credentials("TA10007", "password", is_customer=False)

# Customers
cust_creds = create_credentials("customer@email.com", "password", is_customer=True)
```

## Core Operations

```python
# List Reservations
reservations = await client.list_reservations(is_archive=False)

# Get Reservation Details
details = await client.get_reservation("5452773")
```

### Get Pricing

```python
from bookalimo.models import RateType

prices = await client.get_prices(
    rate_type=RateType.P2P,
    date_time="09/05/2025 12:44 AM",
    pickup=pickup,            # Location
    dropoff=dropoff,          # Location
    passengers=2,
    luggage=3,
    # Optional kwargs:
    # hours=2, stops=[...], account=..., passenger=..., rewards=[...],
    # car_class_code="SD", pets=0, car_seats=0, boosters=0, infants=0,
    # customer_comment="..."
)
```

### Book a Reservation

```python
from bookalimo import create_credit_card, create_passenger
from bookalimo.models import CardHolderType

# Optionally set details first (select car class, add passenger, etc.)
details = await client.set_details(
    token=prices.token,
    car_class_code="SD",
    passenger=create_passenger("John", "Smith", "+19173334455"),
)

# Book with credit card
card = create_credit_card(
    number="4111 1111 1111 1111",  # test PAN
    card_holder="John Smith",
    holder_type=CardHolderType.PERSONAL,
    expiration="01/28",
    cvv="123",
    zip_code="10016",
)

booking = await client.book(token=prices.token, credit_card=card)
print(f"Booked! Confirmation: {booking.reservation_id}")

# Or charge account
booking = await client.book(token=prices.token, method="charge")
```

## Location Builders

### Airport Locations

```python
from bookalimo import create_airport_location

pickup = create_airport_location(
    iata_code="JFK",
    city_name="New York",
    airline_code="UA",
    flight_number="UA1234",
    terminal="7",
)
```

### Address Locations

```python
from bookalimo import create_address_location

dropoff = create_address_location(
    address="53 East 34th Street, Manhattan",
    zip_code="10016",
)
```

### Stops

```python
from bookalimo import create_stop

stops = [
    create_stop("Brooklyn Bridge", is_en_route=False),
    create_stop("Empire State Building", is_en_route=True),
]
```

## Advanced

### Using Account Info (Travel Agents)

```python
from bookalimo.models import Account

account = Account(
    id="TA10007",
    department="Sales",
    booker_first_name="Jane",
    booker_last_name="Agent",
    booker_email="jane@agency.com",
    booker_phone="+19173334455",
)

prices = await client.get_prices(
    # ... required args
    account=account,
)
```

### Edit / Cancel a Reservation

```python
# Edit (e.g., add note or change passengers). Omitting fields leaves them unchanged.
edit_result = await client.edit_reservation(
    confirmation="5452773",
    is_cancel_request=False,
    passengers=3,
    other="Gate pickup",
)

# Cancel
cancel_result = await client.edit_reservation(
    confirmation="5452773",
    is_cancel_request=True,
)
```

## Error Handling

```python
from bookalimo.exceptions import BookALimoError

try:
    reservations = await client.list_reservations()
except BookALimoError as e:
    print(f"API Error: {e}")
    print(f"Status Code: {e.status_code}")
    print(f"Response Data: {e.response_data}")
```

## Logging

By default, no log messages appear. Enable logging for debugging or monitoring.

### Enable Debug Logging

```python
import bookalimo

bookalimo.enable_debug_logging()

async with bookalimo.BookALimo(credentials) as client:
    reservations = await client.list_reservations()  # Shows API calls, timing, etc.
```

Or use the environment variable:
```bash
export BOOKALIMO_LOG_LEVEL=DEBUG
```

### Custom Logging

```python
import logging
import bookalimo

logging.basicConfig(level=logging.INFO)
bookalimo.get_logger().setLevel(logging.WARNING)  # Production setting
```

### Security

Sensitive data is automatically redacted in logs:
- Passwords, tokens, CVV codes: `******`
- API keys: `abc123…89` (first 6, last 2 chars)
- Emails: `j***@example.com`
- Credit cards: `**** **** **** 1234`

### Disable Logging

```python
bookalimo.disable_debug_logging()
```

## Development

```bash
# Clone & setup
git clone https://github.com/yourusername/bookalimo-python.git
cd bookalimo-python
pip install -e ".[dev]"
pre-commit install

# Run tests
pytest
pytest --cov=bookalimo --cov-report=html

# Docs (MkDocs)
mkdocs serve
```

## Security Notes

* Never log raw passwords or credit card numbers.
* Store credentials securely (e.g., environment variables, secrets managers).

## License

This project is licensed under the MIT License — see [`LICENSE`](LICENSE).

## Changelog

See [`CHANGELOG.md`](CHANGELOG.md) for release history.
