linkbay-shipping 0.1.0
Shipping management and carrier integrations for FastAPI applications
License: MIT
Requires Python: >=3.8
Keywords: shipping, fastapi, carrier, shipstation, easypost, dhl, ups, tracking

# LinkBay Shipping

**Multi-carrier shipping management and integrations for FastAPI applications**

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

## Features

- 🚚 **Multi-Carrier Support**: ShipStation, EasyPost, DHL, UPS, FedEx
- 💰 **Real-Time Rates**: Get live shipping rates from carrier APIs
- 🏷️ **Label Generation**: Create and download shipping labels
- 📦 **Tracking**: Track shipments and handle webhook notifications
- ⚙️ **Flexible Configuration**: Support for manual rates (flat, weight-based, price-based)
- 🌍 **Shipping Zones**: Define zones (EU, US, Rest of World) with custom rates
- 🔌 **FastAPI Integration**: Ready-to-use API endpoints

## Installation

```bash
pip install linkbay-shipping
```

For development:
```bash
pip install linkbay-shipping[dev]
```

## Quick Start

### 1. Configure Carriers

```python
from linkbay_shipping.services.shipping_service import ShippingService
from linkbay_shipping.carriers.base import CarrierConfig
from linkbay_shipping.schemas.shipping import CarrierType

# Initialize service
shipping_service = ShippingService()

# Configure ShipStation
shipping_service.configure_carrier(
    CarrierType.SHIPSTATION,
    CarrierConfig(
        api_key="your_api_key",
        api_secret="your_api_secret",
        test_mode=True,
    )
)

# Configure EasyPost
shipping_service.configure_carrier(
    CarrierType.EASYPOST,
    CarrierConfig(
        api_key="your_easypost_key",
        test_mode=True,
    )
)
```

### 2. Calculate Shipping Rates

```python
from linkbay_shipping.services.rate_calculator import RateCalculator
from linkbay_shipping.schemas.shipping import Address

# Get configured carriers
carriers = {
    carrier_type: shipping_service.get_carrier(carrier_type)
    for carrier_type in shipping_service.list_configured_carriers()
}

calculator = RateCalculator(carriers)

# Define addresses
origin = Address(
    country="US",
    postal_code="10001",
    city="New York",
    state="NY",
)

destination = Address(
    country="US",
    postal_code="90001",
    city="Los Angeles",
    state="CA",
)

# Calculate rates
rates = await calculator.calculate_rates(
    origin=origin,
    destination=destination,
    weight=2.5,
    weight_unit="kg",
)

for rate in rates:
    print(f"{rate.service_name}: {rate.rate} {rate.currency}")
```

### 3. Create Shipment and Generate Label

```python
from linkbay_shipping.services.label_generator import LabelGenerator
from linkbay_shipping.schemas.shipping import CreateShipmentRequest

generator = LabelGenerator(carriers)

request = CreateShipmentRequest(
    order_id="ORDER-123",
    carrier=CarrierType.EASYPOST,
    service_code="First",
    origin=origin,
    destination=destination,
    weight=2.5,
    weight_unit="kg",
)

shipment = await generator.create_label(request)
print(f"Tracking: {shipment.tracking_number}")
print(f"Label URL: {shipment.label_url}")
```

## FastAPI Integration

Include the pre-built router in your FastAPI application:

```python
from fastapi import FastAPI
from linkbay_shipping.api import router

app = FastAPI()
app.include_router(router)
```

See the complete documentation in the main README above.

## License

MIT License - see [LICENSE](LICENSE) file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions, please open an issue on GitHub.

## Author

Alessio Quagliara - quagliara.alessio@gmail.com