feat(voy-calc): support batch request

[valeriiashmyhlo]

RELATED TICKETS

• adt-voyages-api PR #623

CHANGELOG

• Add batch_search() method to VoyageCalculator — accepts up to 5 route specifications in a single request and returns results with correlation fields (origin, destination, vessel_class, avoid_zone) alongside calculation results (ETA, ETD, speed, duration)
• Add VoyageCalculatorRoute TypedDict with Required markers on mandatory keys (type, vessel_status, origin, destination) for type-checker safety
• Add VoyageCalculatorBatchResult container with metadata field for per-item status messages
• Bump version to 1.0.32

TESTS

• 7 integration tests in TestVoyageCalculatorBatch covering: multi-route batch, single-route batch, to_df(), column filtering, metadata access, avoid_zone support
• 2 unit tests in TestVoyageCalculatorBatchValidation for client-side validation: max 5 routes exceeded, empty routes list
• All tests pass against production API

COMMENTS

• The batch endpoint sends a raw JSON array as the POST body (not wrapped in a key), so batch_search calls retry_post directly rather than going through search_with_client which expects dict payloads
• Response handling uses the shared _handle_response from client.py for consistent error logging and JSONDecodeError safety
• Existing search() method is unchanged — fully backwards compatible

[Copilot]

🟡 Changes recommended

There are correctness/contract issues in the new typing (required keys not represented) and a JSON decoding error path that currently raises an unhelpful exception.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds batch-request support to the Voyage Calculator endpoint, enabling multiple voyage calculations (up to 5 routes) to be submitted in a single API call and returned in a dedicated result container.

Changes:

• Added VoyageCalculator.batch_search() with request shaping, max-routes validation, and response mapping into a new result type.
• Introduced VoyageCalculatorBatchResult (with metadata) plus DataFrame/list helpers for batch responses.
• Exported the new VoyageCalculatorRoute type and added real-API tests covering batch behavior.

File summaries

File	Description
vortexasdk/endpoints/voyage_calculator.py	Adds batch request route typing and batch_search() implementation.
vortexasdk/endpoints/voyage_calculator_result.py	Adds VoyageCalculatorBatchResult container with metadata and to_df().
vortexasdk/endpoints/init.py	Re-exports VoyageCalculatorRoute from the endpoints package.
vortexasdk/init.py	Re-exports VoyageCalculatorRoute from the top-level package.
tests/endpoints/test_voyage_calculator.py	Adds integration tests for batch search, dataframe output, metadata, and max-routes validation.

Review details

Suppressed comments (1)

vortexasdk/endpoints/voyage_calculator.py:41

• VoyageCalculatorRoute is declared with total=False, which makes all keys optional for type-checkers, but the docstring states type, vessel_status, origin, and destination are required. Mark these four keys as Required[...] so static typing matches the API contract.

    type: VoyageCalculatorType
    vessel_status: VoyageCalculatorVesselStatus
    origin: Union[str, LatLong]
    destination: Union[str, LatLong]

• Files reviewed: 5/5 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.