@burdenoff/microfe-movethewheels 2026.1030.1 → 2026.1031.2

package/src/movethewheels/hooks/useEntityExport.ts

@@ -0,0 +1,130 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+import {
+  GET_MTW_EXPORT_JOB_QUERY,
+  MTW_EXPORT_ENTITY_TYPES,
+  START_MTW_EXPORT_MUTATION,
+  triggerUrlDownload,
+  waitForExportJob,
+  type ExportJobSnapshot,
+  type MtwExportEntity,
+} from '../utils/entityExport';
+
+export type EntityExportState =
+  | { phase: 'idle' }
+  | { phase: 'running'; message: string }
+  | { phase: 'ready'; message: string }
+  | { phase: 'pending'; message: string; jobId: string }
+  | { phase: 'error'; message: string };
+
+export interface UseEntityExportResult {
+  state: EntityExportState;
+  isExporting: boolean;
+  /** Start a CSV export of every record of this entity in the workspace. */
+  startExport: () => void;
+  dismiss: () => void;
+}
+
+/**
+ * Drives the list-page "Export" action: starts an `exportMtwEntities` job for
+ * the page's entity type, waits for wspace-export-svc to build the archive and
+ * starts the download. A job that takes longer than the wait budget keeps
+ * running and is reported as pending, with its id, so the user can collect it
+ * from the shared Exports page.
+ */
+export function useEntityExport(entity: MtwExportEntity, label: string): UseEntityExportResult {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const [state, setState] = useState<EntityExportState>({ phase: 'idle' });
+  const abortRef = useRef<AbortController | null>(null);
+  const runningRef = useRef(false);
+
+  const graphQLOptions = useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+
+  useEffect(() => () => abortRef.current?.abort(), []);
+
+  const startExport = useCallback(() => {
+    // Starting a second job while one is being prepared would only duplicate work.
+    if (runningRef.current) return;
+    if (!workspaceId) {
+      setState({ phase: 'error', message: 'Select a workspace before exporting.' });
+      return;
+    }
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    setState({ phase: 'running', message: `Preparing your ${label} export…` });
+
+    const run = async () => {
+      runningRef.current = true;
+      try {
+        const started = await executeGraphQL<{ exportMtwEntities: ExportJobSnapshot }>(
+          graphQLOptions,
+          START_MTW_EXPORT_MUTATION,
+          {
+            input: {
+              workspaceId,
+              entityTypes: [MTW_EXPORT_ENTITY_TYPES[entity]],
+              format: 'CSV',
+              includeMetadata: true,
+            },
+          },
+          // Starting a job is not idempotent: never replay it on a transient error.
+          'SINGLE_ATTEMPT'
+        );
+        const outcome = await waitForExportJob(
+          started.exportMtwEntities,
+          async (id) => {
+            const data = await executeGraphQL<{ getExportJob: ExportJobSnapshot | null }>(
+              { ...graphQLOptions, signal: controller.signal },
+              GET_MTW_EXPORT_JOB_QUERY,
+              { id }
+            );
+            return data.getExportJob;
+          },
+          { signal: controller.signal }
+        );
+        if (controller.signal.aborted) return;
+        if (outcome.kind === 'ready') {
+          triggerUrlDownload(outcome.downloadUrl);
+          setState({ phase: 'ready', message: `Your ${label} export is downloading.` });
+        } else if (outcome.kind === 'pending') {
+          setState({
+            phase: 'pending',
+            jobId: outcome.jobId,
+            message: `Your ${label} export is still being prepared. It will be available on the Exports page when it finishes.`,
+          });
+        } else {
+          setState({ phase: 'error', message: `Export failed: ${outcome.message}` });
+        }
+      } catch (error) {
+        if (controller.signal.aborted) return;
+        setState({
+          phase: 'error',
+          message:
+            error instanceof Error && error.message
+              ? `Export failed: ${error.message}`
+              : 'Export failed. Please try again.',
+        });
+      } finally {
+        runningRef.current = false;
+      }
+    };
+    void run();
+  }, [entity, graphQLOptions, label, workspaceId]);
+
+  const dismiss = useCallback(() => setState({ phase: 'idle' }), []);
+
+  return { state, isExporting: state.phase === 'running', startExport, dismiss };
+}

package/src/movethewheels/hooks/useShipmentRisk.ts

@@ -0,0 +1,195 @@
+/**
+ * Shipment delivery-risk forecast (BOFF-10397).
+ *
+ * Reads `mtwShipmentRiskForecast` for one shipment — the deterministic
+ * forecast wspace-movethewheels-svc computes from the shipment's legs,
+ * routes, tracking events, vehicle and carrier history — together with the
+ * few shipment fields the recommended actions need. The actions call the
+ * mutation the forecast names (`updateShipment` to re-promise,
+ * `addTrackingEvent` to record a tracking update); reassigning a vehicle
+ * happens on the order page.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+import type { RiskSignalCode } from '../utils/trackingAlerts';
+
+export type RiskLevel = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH';
+export type RiskRecommendedAction =
+  'NONE' | 'MONITOR' | 'REPROMISE_DELIVERY' | 'REQUEST_TRACKING_UPDATE' | 'REASSIGN_VEHICLE';
+
+export interface RiskSignal {
+  code: RiskSignalCode;
+  weight: number;
+  minutes: number | null;
+  ratio: number | null;
+}
+
+export interface ShipmentRiskForecast {
+  shipmentId: string;
+  shipmentNumber: string;
+  status: string;
+  method: string;
+  promisedDelivery: string | null;
+  predictedDeliveryEarliest: string | null;
+  predictedDeliveryLatest: string | null;
+  predictedSlipMinutes: number;
+  riskScore: number;
+  riskLevel: RiskLevel;
+  atRisk: boolean;
+  breached: boolean;
+  signals: RiskSignal[];
+  recommendedAction: RiskRecommendedAction;
+  recommendedMutation: string | null;
+  evaluatedAt: string;
+}
+
+export interface RiskShipment {
+  id: string;
+  deliveryJobId: string | null;
+  estimatedDelivery: string | null;
+}
+
+const SHIPMENT_RISK_QUERY = `
+  query ShipmentRiskForecast($shipmentId: ID!) {
+    mtwShipmentRiskForecast(shipmentId: $shipmentId) {
+      shipmentId
+      shipmentNumber
+      status
+      method
+      promisedDelivery
+      predictedDeliveryEarliest
+      predictedDeliveryLatest
+      predictedSlipMinutes
+      riskScore
+      riskLevel
+      atRisk
+      breached
+      signals {
+        code
+        weight
+        minutes
+        ratio
+      }
+      recommendedAction
+      recommendedMutation
+      evaluatedAt
+    }
+    shipment(id: $shipmentId) {
+      id
+      deliveryJobId
+      estimatedDelivery
+    }
+  }
+`;
+
+const REPROMISE_SHIPMENT_MUTATION = `
+  mutation RepromiseShipment($id: ID!, $input: UpdateShipmentInput!) {
+    updateShipment(id: $id, input: $input) {
+      id
+      estimatedDelivery
+    }
+  }
+`;
+
+const RECORD_TRACKING_UPDATE_MUTATION = `
+  mutation RecordTrackingUpdate($input: AddTrackingEventInput!) {
+    addTrackingEvent(input: $input) {
+      id
+      timestamp
+    }
+  }
+`;
+
+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 useShipmentRisk(shipmentId: string | undefined) {
+  const graphQLOptions = useGraphqlOptions();
+  const [forecast, setForecast] = useState<ShipmentRiskForecast | null>(null);
+  const [shipment, setShipment] = useState<RiskShipment | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const load = useCallback(async () => {
+    if (!shipmentId) {
+      setForecast(null);
+      setShipment(null);
+      return;
+    }
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await executeGraphQL<{
+        mtwShipmentRiskForecast: ShipmentRiskForecast;
+        shipment: RiskShipment | null;
+      }>(graphQLOptions, SHIPMENT_RISK_QUERY, { shipmentId });
+      setForecast(data.mtwShipmentRiskForecast);
+      setShipment(data.shipment);
+    } catch (fetchError) {
+      setError(
+        fetchError instanceof Error ? fetchError : new Error('Failed to load the risk forecast')
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  }, [graphQLOptions, shipmentId]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  /** Move the shipment's promised delivery to `estimatedDelivery` (ISO date-time). */
+  const repromise = useCallback(
+    async (estimatedDelivery: string): Promise<void> => {
+      if (!shipmentId) return;
+      await executeGraphQL(
+        graphQLOptions,
+        REPROMISE_SHIPMENT_MUTATION,
+        { id: shipmentId, input: { estimatedDelivery } },
+        'SINGLE_ATTEMPT'
+      );
+      await load();
+    },
+    [graphQLOptions, load, shipmentId]
+  );
+
+  /** Record a fresh in-transit tracking update reported by the driver or carrier. */
+  const recordTrackingUpdate = useCallback(
+    async (details: string): Promise<void> => {
+      if (!shipmentId) return;
+      await executeGraphQL(
+        graphQLOptions,
+        RECORD_TRACKING_UPDATE_MUTATION,
+        { input: { shipmentId, eventType: 'IN_TRANSIT', details } },
+        'SINGLE_ATTEMPT'
+      );
+      await load();
+    },
+    [graphQLOptions, load, shipmentId]
+  );
+
+  return {
+    forecast,
+    shipment,
+    isLoading,
+    error,
+    refetch: () => void load(),
+    repromise,
+    recordTrackingUpdate,
+  };
+}

package/src/movethewheels/hooks/useTracking.ts

@@ -13,6 +13,11 @@ import {
   useDrivers,
 } from './useFleet';
 import { mapOrder, type ApiOrder, useOrder } from './useOrders';
+import {
+  mapTrackingAlert,
+  sortTrackingAlerts,
+  type ApiTrackingAlert,
+} from '../utils/trackingAlerts';
 
 interface UseTrackingOptions {
   entityId?: string;
@@ -205,10 +210,27 @@ const ACTIVE_DELIVERIES_QUERY = `
 const TRACKING_ALERTS_QUERY = `
   query GetTrackingAlerts {
     trackingAlerts {
+      id
       shipmentId
       shipmentNumber
       alertType
       message
+      riskScore
+      promisedDelivery
+      predictedDelivery
+      signals
+      acknowledged
+      acknowledgedAt
+    }
+  }
+`;
+
+const ACKNOWLEDGE_TRACKING_ALERT_MUTATION = `
+  mutation AcknowledgeMtwTrackingAlert($shipmentId: ID!, $alertType: MtwTrackingAlertType!) {
+    acknowledgeMtwTrackingAlert(shipmentId: $shipmentId, alertType: $alertType) {
+      id
+      acknowledged
+      acknowledgedAt
     }
   }
 `;
@@ -631,24 +653,11 @@ export function useTrackingAlerts() {
     setIsLoading(true);
     setError(null);
     try {
-      const data = await executeGraphQL<{
-        trackingAlerts: Array<{
-          shipmentId: string;
-          shipmentNumber: string;
-          alertType: string;
-          message: string;
-        }>;
-      }>(graphQLOptions, TRACKING_ALERTS_QUERY);
-
-      setAlerts(
-        data.trackingAlerts.map((alert) => ({
-          id: `${alert.shipmentId}-${alert.alertType}`,
-          type: 'delay',
-          severity: 'medium',
-          message: `${alert.shipmentNumber}: ${alert.message}`,
-          acknowledged: false,
-        }))
+      const data = await executeGraphQL<{ trackingAlerts: ApiTrackingAlert[] }>(
+        graphQLOptions,
+        TRACKING_ALERTS_QUERY
       );
+      setAlerts(sortTrackingAlerts(data.trackingAlerts.map(mapTrackingAlert)));
     } catch (fetchError) {
       setError(
         fetchError instanceof Error ? fetchError : new Error('Failed to load tracking alerts')
@@ -664,11 +673,46 @@ export function useTrackingAlerts() {
 
   const unacknowledgedAlerts = useMemo(() => alerts.filter((item) => !item.acknowledged), [alerts]);
 
-  const acknowledgeAlert = useCallback(async (alertId: string): Promise<void> => {
-    setAlerts((previous) =>
-      previous.map((item) => (item.id === alertId ? { ...item, acknowledged: true } : item))
-    );
-  }, []);
+  /**
+   * Persist the acknowledgement server-side (BOFF-10397) so it survives a
+   * reload and is shared with the rest of the workspace. The alert is hidden
+   * optimistically and restored if the mutation fails.
+   */
+  const acknowledgeAlert = useCallback(
+    async (alertId: string): Promise<void> => {
+      const target = alerts.find((item) => item.id === alertId);
+      if (!target?.shipmentId || !target.kind) return;
+      setAlerts((previous) =>
+        previous.map((item) => (item.id === alertId ? { ...item, acknowledged: true } : item))
+      );
+      try {
+        const data = await executeGraphQL<{
+          acknowledgeMtwTrackingAlert: {
+            id: string;
+            acknowledged: boolean;
+            acknowledgedAt: string;
+          };
+        }>(
+          graphQLOptions,
+          ACKNOWLEDGE_TRACKING_ALERT_MUTATION,
+          // Idempotent upsert server-side, so transient retries are safe.
+          { shipmentId: target.shipmentId, alertType: target.kind }
+        );
+        const acknowledgedAt = new Date(data.acknowledgeMtwTrackingAlert.acknowledgedAt);
+        setAlerts((previous) =>
+          previous.map((item) =>
+            item.id === alertId ? { ...item, acknowledged: true, acknowledgedAt } : item
+          )
+        );
+      } catch (ackError) {
+        setAlerts((previous) =>
+          previous.map((item) => (item.id === alertId ? { ...item, acknowledged: false } : item))
+        );
+        throw ackError instanceof Error ? ackError : new Error('Failed to acknowledge alert');
+      }
+    },
+    [alerts, graphQLOptions]
+  );
 
   return {
     alerts,

package/src/movethewheels/pages/CustomersPage.tsx

@@ -15,10 +15,18 @@ import { useDebouncedValue } from '../hooks/useDebouncedValue';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatDate } from '../utils/formatters';
 import { joinPath } from '../utils/navigation';
+import { useEntityExport } from '../hooks/useEntityExport';
+import { ExportStatusBanner } from '../components/ExportStatusBanner';
 import type { Customer } from '../types';
 
 export default function CustomersPage() {
   const { basePath, navigate } = useMoveTheWheels();
+  const {
+    state: exportState,
+    isExporting,
+    startExport,
+    dismiss: dismissExport,
+  } = useEntityExport('customers', 'customer');
   const [page, setPage] = useState(0);
   const [pageSize, setPageSize] = useState(25);
   const [search, setSearch] = useState('');
@@ -104,9 +112,9 @@ export default function CustomersPage() {
           actions={[
             { label: 'Refresh', icon: <RefreshCw size={16} />, onSelect: () => refetch() },
             {
-              label: 'Export',
+              label: isExporting ? 'Exporting…' : 'Export',
               icon: <Download size={16} />,
-              onSelect: () => goTo('import-export'),
+              onSelect: startExport,
             },
           ]}
         />
@@ -117,6 +125,7 @@ export default function CustomersPage() {
         satisfaction ratings here, and open a customer to see their order history before booking the
         next shipment.
       </PagePurpose>
+      <ExportStatusBanner state={exportState} onDismiss={dismissExport} />
 
       {/* Customer base at a glance — premium stat cards */}
       <div>

package/src/movethewheels/pages/DashboardPage.tsx

@@ -21,6 +21,7 @@ import {
 import { PageLayout, PageSection } from '../components/PageLayout';
 import { MetricCard, MetricGrid, type MetricDelta } from '../components/MetricCard';
 import { StatusBadge } from '../components/StatusBadge';
+import { TrackingAlertList } from '../components/TrackingAlertList';
 import { LogisticsMap, type LogisticsMarker } from '../components/maps';
 import { VolumeBar } from '../components/charts';
 import { deliveryMarkerStatus, firstRealLatLng } from '../utils/mapMarkers';
@@ -67,7 +68,7 @@ export default function DashboardPage() {
   const { stats: orderStats } = useOrderStats();
   const { stats: fleetStats } = useFleetStats();
   const { activeDeliveries } = useLiveTracking();
-  const { unacknowledgedAlerts } = useTrackingAlerts();
+  const { unacknowledgedAlerts, acknowledgeAlert, refetch: refetchAlerts } = useTrackingAlerts();
 
   const orderSpark = useMemo(
     () => analytics.trends.dailyOrders.map((d) => d.orders),
@@ -265,25 +266,14 @@ export default function DashboardPage() {
             </CardHeader>
             <CardContent>
               {unacknowledgedAlerts.length > 0 ? (
-                <div className="space-y-3">
-                  {unacknowledgedAlerts.slice(0, 4).map((alert) => (
-                    <div
-                      key={alert.id}
-                      className={`rounded-lg p-3 text-sm ${
-                        alert.severity === 'critical' || alert.severity === 'high'
-                          ? 'bg-status-error-bg-subtle'
-                          : 'bg-status-warning-bg-subtle'
-                      }`}
-                    >
-                      <p className="font-medium">{alert.message}</p>
-                      <p className="mt-1 text-xs text-text-secondary">
-                        {alert.timestamp
-                          ? formatDate(alert.timestamp, 'relative')
-                          : 'Time not recorded'}
-                      </p>
-                    </div>
-                  ))}
-                </div>
+                <TrackingAlertList
+                  alerts={unacknowledgedAlerts}
+                  limit={4}
+                  t={t}
+                  onAcknowledge={acknowledgeAlert}
+                  onOpenOrder={(deliveryJobId) => goTo(`orders/${deliveryJobId}`)}
+                  onChanged={refetchAlerts}
+                />
               ) : (
                 <p className="py-4 text-center text-sm text-text-secondary">
                   {t(

package/src/movethewheels/pages/DriversPage.tsx

@@ -37,6 +37,8 @@ import { useDebouncedValue } from '../hooks/useDebouncedValue';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatDate } from '../utils/formatters';
 import { joinPath } from '../utils/navigation';
+import { useEntityExport } from '../hooks/useEntityExport';
+import { ExportStatusBanner } from '../components/ExportStatusBanner';
 import { DRIVER_STATUS_LABELS } from '../constants';
 import type { Driver, DriverStatus } from '../types';
 
@@ -52,6 +54,12 @@ const STATUS_OPTIONS: Array<{ value: DriverStatus | 'all'; label: string }> = [
 
 export default function DriversPage() {
   const { basePath, navigate } = useMoveTheWheels();
+  const {
+    state: exportState,
+    isExporting,
+    startExport,
+    dismiss: dismissExport,
+  } = useEntityExport('drivers', 'driver');
   const [page, setPage] = useState(0);
   const [pageSize, setPageSize] = useState(25);
   const [search, setSearch] = useState('');
@@ -224,9 +232,9 @@ export default function DriversPage() {
           actions={[
             { label: 'Refresh', icon: <RefreshCw size={16} />, onSelect: () => refetch() },
             {
-              label: 'Export',
+              label: isExporting ? 'Exporting…' : 'Export',
               icon: <Download size={16} />,
-              onSelect: () => goTo('import-export'),
+              onSelect: startExport,
             },
           ]}
         />
@@ -237,6 +245,7 @@ export default function DriversPage() {
         contact number and the vehicle they are on — open a driver to review their record before
         assigning them to an order or route.
       </PagePurpose>
+      <ExportStatusBanner state={exportState} onDismiss={dismissExport} />
 
       {/* Workforce at a glance — premium stat cards */}
       <div>

package/src/movethewheels/pages/LiveTrackingPage.tsx

@@ -28,13 +28,20 @@ import { useLiveTracking, useTrackingAlerts } from '../hooks/useTracking';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatDate } from '../utils/formatters';
 import { joinPath } from '../utils/navigation';
+import { TrackingAlertList } from '../components/TrackingAlertList';
+import { useI18n } from '@burdenoff/fe-libs/shared/providers/shell/I18nProvider';
 
 type LiveFilter = 'all' | 'in_transit' | 'out_for_delivery' | 'other';
 
 export default function LiveTrackingPage() {
   const { basePath, navigate } = useMoveTheWheels();
   const { activeDeliveries, isLoading, refetch } = useLiveTracking();
-  const { unacknowledgedAlerts } = useTrackingAlerts();
+  const { t: translate } = useI18n();
+  const t = (key: string, fallback: string): string => {
+    const value = translate(key);
+    return value === key ? fallback : value;
+  };
+  const { unacknowledgedAlerts, acknowledgeAlert, refetch: refetchAlerts } = useTrackingAlerts();
   const [viewMode, setViewMode] = useState<'map' | 'list'>('map');
   const [selectedDelivery, setSelectedDelivery] = useState<string | null>(null);
   const [filter, setFilter] = useState<LiveFilter>('all');
@@ -420,7 +427,7 @@ export default function LiveTrackingPage() {
           <Card>
             <CardHeader>
               <CardTitle className="flex items-center gap-2">
-                Alerts
+                {t('movethewheels.tracking.live.alerts', 'Alerts')}
                 {unacknowledgedAlerts.length > 0 && (
                   <Badge variant="destructive">{unacknowledgedAlerts.length}</Badge>
                 )}
@@ -428,28 +435,19 @@ export default function LiveTrackingPage() {
             </CardHeader>
             <CardContent>
               {unacknowledgedAlerts.length > 0 ? (
-                <div className="space-y-3">
-                  {unacknowledgedAlerts.slice(0, 5).map((alert) => (
-                    <div
-                      key={alert.id}
-                      className={`p-3 rounded-lg text-sm ${
-                        alert.severity === 'critical' || alert.severity === 'high'
-                          ? 'bg-status-error-bg-subtle'
-                          : 'bg-status-warning-bg-subtle'
-                      }`}
-                    >
-                      <p className="font-medium">{alert.message}</p>
-                      <p className="text-xs text-text-secondary mt-1">
-                        {alert.timestamp
-                          ? formatDate(alert.timestamp, 'relative')
-                          : 'Time not recorded'}
-                      </p>
-                    </div>
-                  ))}
-                </div>
+                <TrackingAlertList
+                  alerts={unacknowledgedAlerts}
+                  limit={5}
+                  t={t}
+                  onAcknowledge={acknowledgeAlert}
+                  onOpenOrder={(deliveryJobId) => goTo(`orders/${deliveryJobId}`)}
+                  onChanged={refetchAlerts}
+                />
               ) : (
                 <div className="text-center text-text-secondary py-4">
-                  <p className="text-sm">No active alerts</p>
+                  <p className="text-sm">
+                    {t('movethewheels.tracking.live.noAlerts', 'No active alerts')}
+                  </p>
                 </div>
               )}
             </CardContent>