@burdenoff/microfe-movethewheels 2026.728.1 → 2026.731.2

package/src/movethewheels/hooks/useMultiModalShipments.ts

@@ -0,0 +1,344 @@
+/**
+ * Multi-modal freight execution (BOFF-4398).
+ *
+ * Wire shape matches wspace-movethewheels-svc: src/modules/shipment/schema/shipment.gql
+ * (MtwShipment, MtwShipmentLeg, MtwFreightRateQuote). Field names here are kept in
+ * lockstep with that schema — verify against the deployed schema before renaming
+ * anything (see BOFF-3922 schema-drift guard / prior MFE-schema-drift incidents).
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+
+export type TransportMode = 'ROAD' | 'AIR' | 'OCEAN' | 'RAIL';
+export type ShipmentLegStatus =
+  'PLANNED' | 'BOOKED' | 'IN_TRANSIT' | 'ARRIVED' | 'DELIVERED' | 'CANCELLED';
+export type OceanContainerType = 'LCL' | 'FCL_20FT' | 'FCL_40FT' | 'FCL_40FT_HC';
+
+export interface FreightRateBreakdownLine {
+  label: string;
+  amount: number;
+}
+
+export interface FreightRateQuote {
+  mode: TransportMode;
+  chargeableWeightKg?: number | null;
+  ratePerUnit: number;
+  calculatedCost: number;
+  currency: string;
+  breakdown: FreightRateBreakdownLine[];
+}
+
+export interface ShipmentLegDraft {
+  mode: TransportMode;
+  origin: { address?: string };
+  destination: { address?: string };
+  distanceKm?: number;
+  weightKg?: number;
+  lengthCm?: number;
+  widthCm?: number;
+  heightCm?: number;
+  volumeCbm?: number;
+  containerType?: OceanContainerType;
+  containerCount?: number;
+  carrierName?: string;
+}
+
+export interface ShipmentLeg extends ShipmentLegDraft {
+  id: string;
+  legNumber: number;
+  status: ShipmentLegStatus;
+  chargeableWeightKg?: number | null;
+  calculatedCost?: number | null;
+  currency: string;
+}
+
+export interface MultiModalShipment {
+  id: string;
+  shipmentNumber: string;
+  status: string;
+  primaryMode: TransportMode;
+  isMultiModal: boolean;
+  totalFreightCost?: number | null;
+  freightCurrency?: string | null;
+  origin: { address?: string };
+  destination: { address?: string };
+  createdAt: string;
+  legs: ShipmentLeg[];
+}
+
+interface ApiShipmentLeg {
+  id: string;
+  legNumber: number;
+  mode: TransportMode;
+  status: ShipmentLegStatus;
+  origin: Record<string, unknown> | null;
+  destination: Record<string, unknown> | null;
+  distanceKm?: number | null;
+  weightKg?: number | null;
+  lengthCm?: number | null;
+  widthCm?: number | null;
+  heightCm?: number | null;
+  volumeCbm?: number | null;
+  containerType?: OceanContainerType | null;
+  containerCount?: number | null;
+  carrierName?: string | null;
+  chargeableWeightKg?: number | null;
+  calculatedCost?: number | null;
+  currency: string;
+}
+
+interface ApiShipment {
+  id: string;
+  shipmentNumber: string;
+  status: string;
+  primaryMode: TransportMode;
+  isMultiModal: boolean;
+  totalFreightCost?: number | null;
+  freightCurrency?: string | null;
+  origin: Record<string, unknown> | null;
+  destination: Record<string, unknown> | null;
+  createdAt: string;
+  legs: ApiShipmentLeg[];
+}
+
+const LEG_FIELDS = `
+  id
+  legNumber
+  mode
+  status
+  origin
+  destination
+  distanceKm
+  weightKg
+  lengthCm
+  widthCm
+  heightCm
+  volumeCbm
+  containerType
+  containerCount
+  carrierName
+  chargeableWeightKg
+  calculatedCost
+  currency
+`;
+
+const SHIPMENT_FIELDS = `
+  id
+  shipmentNumber
+  status
+  primaryMode
+  isMultiModal
+  totalFreightCost
+  freightCurrency
+  origin
+  destination
+  createdAt
+  legs {
+    ${LEG_FIELDS}
+  }
+`;
+
+const MULTI_MODAL_SHIPMENTS_QUERY = `
+  query ListMultiModalShipments($pagination: PaginationInput) {
+    shipments(filter: { isMultiModal: true }, pagination: $pagination) {
+      ${SHIPMENT_FIELDS}
+    }
+  }
+`;
+
+const CALCULATE_FREIGHT_RATE_QUERY = `
+  query CalculateFreightRate($input: FreightRateInput!) {
+    calculateFreightRate(input: $input) {
+      mode
+      chargeableWeightKg
+      ratePerUnit
+      calculatedCost
+      currency
+      breakdown {
+        label
+        amount
+      }
+    }
+  }
+`;
+
+const PLAN_MULTI_MODAL_SHIPMENT_MUTATION = `
+  mutation PlanMultiModalShipment($input: PlanMultiModalShipmentInput!) {
+    planMultiModalShipment(input: $input) {
+      ${SHIPMENT_FIELDS}
+    }
+  }
+`;
+
+function toApiLeg(leg: ShipmentLegDraft) {
+  return {
+    mode: leg.mode,
+    origin: leg.origin,
+    destination: leg.destination,
+    distanceKm: leg.distanceKm,
+    weightKg: leg.weightKg,
+    lengthCm: leg.lengthCm,
+    widthCm: leg.widthCm,
+    heightCm: leg.heightCm,
+    volumeCbm: leg.volumeCbm,
+    containerType: leg.containerType,
+    containerCount: leg.containerCount,
+    carrierName: leg.carrierName,
+  };
+}
+
+// FreightRateInput (shipment.gql) is intentionally narrower than
+// CreateShipmentLegInput — it has no origin/destination/carrierName, only
+// the fields that actually drive a rate calculation. Sending the full leg
+// shape (as toApiLeg does for planMultiModalShipment/addShipmentLeg) trips
+// GraphQL input-coercion on unknown fields, which the gateway surfaces as a
+// masked "Unexpected error." 500 instead of a validation error — so this
+// mapper must stay in lockstep with FreightRateInput's exact field set.
+function toFreightRateInput(leg: ShipmentLegDraft) {
+  return {
+    mode: leg.mode,
+    distanceKm: leg.distanceKm,
+    weightKg: leg.weightKg,
+    lengthCm: leg.lengthCm,
+    widthCm: leg.widthCm,
+    heightCm: leg.heightCm,
+    volumeCbm: leg.volumeCbm,
+    containerType: leg.containerType,
+    containerCount: leg.containerCount,
+  };
+}
+
+function mapLeg(leg: ApiShipmentLeg): ShipmentLeg {
+  return {
+    id: leg.id,
+    legNumber: leg.legNumber,
+    mode: leg.mode,
+    status: leg.status,
+    origin: (leg.origin as { address?: string } | null) ?? {},
+    destination: (leg.destination as { address?: string } | null) ?? {},
+    distanceKm: leg.distanceKm ?? undefined,
+    weightKg: leg.weightKg ?? undefined,
+    lengthCm: leg.lengthCm ?? undefined,
+    widthCm: leg.widthCm ?? undefined,
+    heightCm: leg.heightCm ?? undefined,
+    volumeCbm: leg.volumeCbm ?? undefined,
+    containerType: leg.containerType ?? undefined,
+    containerCount: leg.containerCount ?? undefined,
+    carrierName: leg.carrierName ?? undefined,
+    chargeableWeightKg: leg.chargeableWeightKg,
+    calculatedCost: leg.calculatedCost,
+    currency: leg.currency,
+  };
+}
+
+function mapShipment(shipment: ApiShipment): MultiModalShipment {
+  return {
+    id: shipment.id,
+    shipmentNumber: shipment.shipmentNumber,
+    status: shipment.status,
+    primaryMode: shipment.primaryMode,
+    isMultiModal: shipment.isMultiModal,
+    totalFreightCost: shipment.totalFreightCost,
+    freightCurrency: shipment.freightCurrency,
+    origin: (shipment.origin as { address?: string } | null) ?? {},
+    destination: (shipment.destination as { address?: string } | null) ?? {},
+    createdAt: shipment.createdAt,
+    legs: (shipment.legs ?? []).map(mapLeg),
+  };
+}
+
+function useGraphqlOptions() {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  return useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+}
+
+export function useMultiModalShipments() {
+  const graphQLOptions = useGraphqlOptions();
+  const [shipments, setShipments] = useState<MultiModalShipment[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const load = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await executeGraphQL<{ shipments: ApiShipment[] }>(
+        graphQLOptions,
+        MULTI_MODAL_SHIPMENTS_QUERY,
+        { pagination: { limit: 100, offset: 0 } }
+      );
+      setShipments(data.shipments.map(mapShipment));
+    } catch (fetchError) {
+      setError(
+        fetchError instanceof Error ? fetchError : new Error('Failed to load multi-modal shipments')
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  }, [graphQLOptions]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const calculateFreightRate = useCallback(
+    async (leg: ShipmentLegDraft): Promise<FreightRateQuote> => {
+      const data = await executeGraphQL<{ calculateFreightRate: FreightRateQuote }>(
+        graphQLOptions,
+        CALCULATE_FREIGHT_RATE_QUERY,
+        { input: toFreightRateInput(leg) }
+      );
+      return data.calculateFreightRate;
+    },
+    [graphQLOptions]
+  );
+
+  const planMultiModalShipment = useCallback(
+    async (input: {
+      shipmentNumber: string;
+      customerId?: string;
+      origin: { address?: string };
+      destination: { address?: string };
+      legs: ShipmentLegDraft[];
+    }): Promise<MultiModalShipment> => {
+      const data = await executeGraphQL<{ planMultiModalShipment: ApiShipment }>(
+        graphQLOptions,
+        PLAN_MULTI_MODAL_SHIPMENT_MUTATION,
+        {
+          input: {
+            shipmentNumber: input.shipmentNumber,
+            customerId: input.customerId,
+            origin: input.origin,
+            destination: input.destination,
+            legs: input.legs.map(toApiLeg),
+          },
+        }
+      );
+      const created = mapShipment(data.planMultiModalShipment);
+      setShipments((previous) => [created, ...previous]);
+      return created;
+    },
+    [graphQLOptions]
+  );
+
+  return {
+    shipments,
+    isLoading,
+    error,
+    refetch: () => void load(),
+    calculateFreightRate,
+    planMultiModalShipment,
+  };
+}

package/src/movethewheels/pages/DashboardPage.tsx

@@ -16,6 +16,7 @@ import {
   MapPin,
   ChevronRight,
   Activity,
+  Ship,
 } from 'lucide-react';
 import { PageLayout, PageSection } from '../components/PageLayout';
 import { MetricCard, MetricGrid, type MetricDelta } from '../components/MetricCard';
@@ -158,6 +159,11 @@ export default function DashboardPage() {
               icon: <MapPin size={16} />,
               onSelect: () => goTo('tracking/live'),
             },
+            {
+              label: t('movethewheels.dashboard.actions.multiModal', 'Multi-Modal Freight'),
+              icon: <Ship size={16} />,
+              onSelect: () => goTo('shipments/multi-modal'),
+            },
           ]}
         />
       }