Shipping Carrier Selector

A shipping request arrives with the package's length, width, height, and weight alongside destination, deliveryTimeline, and priorityFactor. These seven fields drive everything downstream, from the validation limits to the per-carrier pricing formulas.

Validation runs on a first hit policy, so the earliest failing guard wins and writes its message to validation.error while setting validation.isValid to false. Non-positive dimensions or weight are rejected first, then weight > 70 trips 'Package exceeds maximum weight limit of 70kg', any side over 200 trips the dimension error, and a deliveryTimeline outside 'standard', 'express', and 'same-day' returns 'Invalid delivery timeline option'. The empty catch-all row at the bottom marks the request valid.

The 70kg ceiling matches the practical cutoff of parcel networks, which hand heavier pieces to freight services, and 200cm is a sensible girth-style limit for conveyor-sortable packages. Rejecting these upfront avoids a failed carrier booking later, and validating the timeline enum here means every later table can branch on it without re-checking for typos.

Routing splits on validation.isValid: requests that passed validation continue to service level mapping and pricing, while the default branch sends everything else straight to the response. That keeps invalid packages from reaching the carrier tables, so the caller gets the validation.error message without any misleading pricing attached.

Timeline-to-tier mapping is a straight first-hit lookup: an invalid request maps to 'none', 'same-day' maps to 'premium', 'express' stays 'express', and 'standard' stays 'standard'. The invalid guard sits on top so a failed validation short-circuits the mapping before any timeline row can match.

Translating a customer-facing timeline into an internal serviceLevel is standard practice in multi-carrier shipping, because carriers are onboarded per service tier rather than per delivery promise. Keeping the mapping in its own table means new tiers or renamed timelines change one table instead of every eligibility rule.

The response returns the assembled decision to the caller: for a rejected package it carries validation.error and validation.isValid false, and for a valid one the eligible carriers with their carrierCosts. Because passThrough is enabled along the graph, the original request fields ride along, which makes the result auditable without re-querying the input.

Eligibility uses a collect hit policy, so every matching row contributes its carrier list and the results are gathered under eligibleCarriers. Rows key on serviceLevel, destination, and a weight cap: 'premium' domestic up to 15kg gets 'SpeedyExpress', 'express' domestic up to 30kg gets 'FastTrack' and 'QuickShip', international express up to 20kg gets 'GlobalExpress' and 'WorldWide', and the standard tiers list three domestic and two international options. A final row adds 'HeavyHauler' for anything between 50 and 70kg.

Per-carrier weight caps like these reflect how carrier contracts really work: premium couriers optimize for light, fast parcels, while heavy pieces need a carrier with the right handling equipment. Collecting all matches instead of picking one preserves the full option set, which the ranking step needs to compare prices.

Chargeable weight is computed here as max([weight, $.volumetricWeight]), with volumetricWeight = (length * width * height) / 5000, the standard dimensional-weight divisor used across the air-parcel industry so bulky-but-light boxes pay for the space they occupy. The baseCosts map then prices each carrier as a base fee plus a per-kg rate, from EcoShip at 8 + 1.1/kg up to HeavyHauler at 40 + 2.0/kg, adding a flat surcharge when isOversized (any side over 100cm) is true. The final carrierCosts list pairs each eligible carrier with its computed cost for the ranking step.