feat(rnd-22989): add VoyageCalculator endpoint

[alexspeddingvortexa]

RELATED TICKETS

• https://vortexa.atlassian.net/browse/RND-22989

CHANGELOG

• Add VoyageCalculator endpoint class wrapping POST /v5/voyages/voyage-calculator
• Add VoyageCalculatorResult container with to_list() and to_df() support
• Export VoyageCalculatorType, VoyageCalculatorVesselStatus, VoyageCalculatorAvoidZone type aliases

TESTS

• 8 integration tests covering: ETA/ETD/speed calculations, lat/long origins, avoid zones, delay factor, DataFrame output, column filtering
• Tests hit the real API (skipped in CI via SKIP_TAGS=real)

Run the test suite:

python3 -m pytest tests/endpoints/test_voyage_calculator.py -v

HOW TO TEST THE DEV SDK

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .

Note: If you get ModuleNotFoundError: No module named 'packaging', run:

pip install "packaging>=24.0"

This can happen when upgrading an existing venv where the editable install doesn't fully re-resolve transitive deps.

Then in Python:

from vortexasdk import VoyageCalculator

# Calculate ETA: VLCC from Ras Tanura to Rotterdam at 12 knots
ras_tanura = "539db1548407fd97024391d01a6a2be239b1100f070a137d54a79907d03db6c8"
rotterdam = "68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e"

result = VoyageCalculator().search(
    type="ETA",
    vessel_status="vessel_status_laden_known",
    origin=ras_tanura,
    destination=rotterdam,
    vessel_class="oil_vlcc",
    ETD="2024-03-01T00:00:00.000Z",
    speed=12,
)
print(result.to_df())

# Using lat/long coordinates with avoid zones
result = VoyageCalculator().search(
    type="ETA",
    vessel_status="vessel_status_laden_known",
    origin={"lat": 26.6, "long": 50.1},
    destination={"lat": 51.9, "long": 4.5},
    vessel_class="oil_vlcc",
    ETD="2024-03-01T00:00:00.000Z",
    speed=12,
    avoid_zone=["Suez Canal"],
)
print(result.to_list())

COMMENTS

• Mirrors the POST /voyage-calculator endpoint added to adt-voyages-api in #620
• Uses the response_type="breakdown" path (no pagination) since the endpoint returns at most 1 result
• Follows the same pattern as AnywhereFreightPricingPostPriceDetails

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.