Metadata-Version: 2.5
Name: warpfreight
Version: 0.1.1
Summary: Official Python client for the Warp freight API — keyless quoting, booking, and tracking.
Project-URL: Homepage, https://www.wearewarp.com
Project-URL: Documentation, https://www.wearewarp.com/developers
Project-URL: Repository, https://github.com/warpfreight/warpfreight-python
Project-URL: Issues, https://github.com/warpfreight/warpfreight-python/issues
Author-email: Warp <developers@wearewarp.com>
License: MIT
License-File: LICENSE
Keywords: api,freight,logistics,ltl,sdk,shipping,warp,warpfreight
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# warpfreight

The official Python client for the [Warp](https://www.wearewarp.com) freight API. Quote real, bookable freight prices with no API key, no account, and no card. Book and track once you have a key.

```bash
pip install warpfreight
```

Zero third-party dependencies — it uses only the Python standard library.

## Quote (keyless)

```python
from warpfreight import WarpFreight

warp = WarpFreight()  # no key needed to quote

q = warp.quote(
    origin_zip="90001",
    destination_zip="10001",
    pickup_date="2026-09-01",
    pallets=2,
    weight_lbs_per_pallet=500,
    commodity="auto parts",
    length_in=48, width_in=40, height_in=48,
)

print(q["price_usd"], q["transit_days"], q["quote_id"])
```

The price is real and bookable. `quote_id` is an opaque, bookable token — pass it straight to `book()`.

### Compare every mode in one call

The same palletized load can move as LTL, full truckload, a cargo van, or a 26' box truck, often at very different prices. `compare_modes` prices all of them keylessly and hands back the recommended one:

```python
result = warp.compare_modes(
    origin_zip="90001", destination_zip="10001",
    pickup_date="2026-09-01", pallets=2, weight_lbs_per_pallet=500,
)
```

Modes Warp can't serve for a lane come back explicitly unavailable with the reason, so nothing is silently dropped.

## Book (needs an API key + a card)

Quoting is keyless; booking spends money, so it needs a key and a card on file. Get a key instantly at [wearewarp.com/developers](https://www.wearewarp.com/developers) — no card required to issue one.

```python
warp = WarpFreight(api_key="wak_live_...")  # or set WARPFREIGHT_API_KEY

booking = warp.book(quote_id=q["quote_id"], reference="PO-4471")
print(booking["shipment_number"])
```

If the account has no card on file, `book()` raises a `WarpFreightError` with `code == "WARPFREIGHT_PAYMENT_REQUIRED"` and a `checkout_url` to add one. The quote stays valid.

## Track

```python
t = warp.track("S-199806-2617")
print(t["status"])
```

## Configuration

The API key is resolved in this order:

1. `WarpFreight(api_key="...")`
2. `WARPFREIGHT_API_KEY` environment variable
3. `WARP_API_KEY` (deprecated alias — still works, warns once)

## Errors

Every failure raises `WarpFreightError`:

```python
from warpfreight import WarpFreight, WarpFreightError

try:
    warp.book(quote_id="wq_expired")
except WarpFreightError as e:
    print(e.code)          # e.g. "WARPFREIGHT_QUOTE_EXPIRED"
    print(e.status)        # HTTP status
    print(e.checkout_url)  # set when a card is required
```

`code` is prefixed `WARPFREIGHT_` so it stays greppable and attributable when pasted into a search box or an AI assistant.

## License

MIT
