@burdenoff/microfe-movethewheels 2026.1031.6 → 2026.1101.2

package/src/movethewheels/MoveTheWheelsRoot.tsx

@@ -25,6 +25,7 @@ import {
   Store,
   ArrowDownUp,
   Settings,
+  Plug,
 } from 'lucide-react';
 import { MoveTheWheelsProvider } from './providers/MoveTheWheelsProvider';
 import { ModuleSettingsProvider } from './providers/ModuleSettingsProvider';
@@ -309,6 +310,13 @@ const NavRegistrar: FC<Pick<MoveTheWheelsRootProps, 'registerNavItems' | 'basePa
           icon: <Bot size={16} />,
           order: 13,
         },
+        {
+          id: 'mtw-integrations',
+          label: tr('movethewheels.root.nav.integrations', 'Integrations'),
+          path: joinPath(basePath, 'integrations'),
+          icon: <Plug size={16} />,
+          order: 98,
+        },
         {
           id: 'mtw-settings',
           label: tr('movethewheels.root.nav.settings', 'Settings'),

package/src/movethewheels/MoveTheWheelsRoutes.tsx

@@ -75,6 +75,7 @@ const CustomerDetailsPage = lazy(() => import('./pages/CustomerDetailsPage'));
 const MarketplacePage = lazy(() => import('./pages/MarketplacePage'));
 const ImportExportPage = lazy(() => import('./pages/ImportExportPage'));
 const SettingsPage = lazy(() => import('./pages/SettingsPage'));
+const IntegrationsPage = lazy(() => import('./pages/IntegrationsPage'));
 const RoutesPage = lazy(() => import('./pages/RoutesPage'));
 const RouteDetailsPage = lazy(() => import('./pages/RouteDetailsPage'));
 const AnalyticsPage = lazy(() => import('./pages/AnalyticsPage'));
@@ -172,6 +173,9 @@ export function MoveTheWheelsRoutes() {
         {/* Workspace operational defaults: currency, units, time zone (BOFF-10488) */}
         <Route path="settings" element={<SettingsPage />} />
 
+        {/* Carrier, ELD and GPS tracking feeds as signed webhooks (BOFF-4404) */}
+        <Route path="integrations" element={<IntegrationsPage />} />
+
         {/* Routes */}
         <Route path="routes" element={<RoutesPage />} />
         <Route path="routes/trip-utilization" element={<TripUtilizationPage />} />

package/src/movethewheels/components/EpodCaptureForm.tsx

@@ -0,0 +1,343 @@
+/**
+ * ePOD capture form (BOFF-4399), extracted from the driver deliveries page so
+ * the BOFF-3991 driver day view can open it from a stop's detail screen.
+ *
+ * Captures recipient name, signature (drawn or typed), an optional delivery
+ * photo (uploaded via the platform files primitive), device GPS if available,
+ * and notes, after the driver reviews the linked shipment status and attests
+ * completion. `captureEpod` owner-verifies the calling driver server-side.
+ */
+import { useEffect, useRef, useState } from 'react';
+import {
+  CheckCircle2,
+  Loader2,
+  MapPin,
+  PenLine,
+  Truck,
+  Type as TypeIcon,
+  Upload,
+} from 'lucide-react';
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label, Textarea } from './ui';
+import { SignaturePad, type SignaturePadHandle } from './SignaturePad';
+import { FormError } from './FormError';
+import { useCaptureEpod, useEpodPhotoUpload, type PendingEpodDeliveryJob } from '../hooks/useEpod';
+import { formatAddress } from '../utils/formatters';
+import type { SignatureType } from '../types';
+import { useShipmentStatusQuery } from '../hooks/useShipmentStatusAuthority';
+import { StatusAuthorityOwnedDeliveryDocument } from '../../generated/shipment-status-authority-operations';
+import type { StatusAuthorityOwnedDeliveryQuery } from '../../generated/shipment-status-authority-operations';
+
+/** Resolves the device's current position, if the browser grants it. Never blocks submission. */
+function getCurrentPosition(): Promise<GeolocationPosition | null> {
+  return new Promise((resolve) => {
+    if (!navigator.geolocation) {
+      resolve(null);
+      return;
+    }
+    navigator.geolocation.getCurrentPosition(
+      (position) => resolve(position),
+      () => resolve(null),
+      { enableHighAccuracy: true, timeout: 8000, maximumAge: 30000 }
+    );
+  });
+}
+
+export function EpodCaptureForm({
+  job,
+  onCaptured,
+  onCancel,
+  offline = false,
+}: {
+  job: PendingEpodDeliveryJob;
+  onCaptured: (deliveryJobId: string) => void;
+  onCancel: () => void;
+  /**
+   * True while the device has no network. Capture needs the live linked
+   * shipment status and an acknowledged server write, so it is blocked
+   * rather than queued while offline.
+   */
+  offline?: boolean;
+}) {
+  const { captureEpod, isSubmitting, error: captureError, captureFeedback } = useCaptureEpod();
+  const [statusRefresh, setStatusRefresh] = useState(0);
+  const ownedStatus = useShipmentStatusQuery<StatusAuthorityOwnedDeliveryQuery>(
+    StatusAuthorityOwnedDeliveryDocument,
+    { deliveryJobId: job.id },
+    statusRefresh
+  );
+  const [completionAttestation, setCompletionAttestation] = useState(false);
+  const uploadedPhoto = useRef<{ file: File; id: string } | null>(null);
+  const submissionLock = useRef(false);
+  const active = useRef(true);
+  useEffect(() => {
+    active.current = true;
+    return () => {
+      active.current = false;
+    };
+  }, []);
+  const [preparing, setPreparing] = useState(false);
+  const [requiredStatusRefresh, setRequiredStatusRefresh] = useState(0);
+  const { upload: uploadPhoto, isUploading, error: uploadError } = useEpodPhotoUpload();
+  const signaturePadRef = useRef<SignaturePadHandle>(null);
+
+  const [recipientName, setRecipientName] = useState('');
+  const [signatureType, setSignatureType] = useState<SignatureType>('drawn');
+  const [typedSignature, setTypedSignature] = useState('');
+  const [photoFile, setPhotoFile] = useState<File | null>(null);
+  const [notes, setNotes] = useState('');
+  const [validationError, setValidationError] = useState<string | null>(null);
+
+  const handleSubmit = async () => {
+    if (submissionLock.current) return;
+    setValidationError(null);
+    if (offline) {
+      setValidationError('You are offline. Reconnect to confirm this delivery.');
+      return;
+    }
+    if (
+      ownedStatus.loading ||
+      ownedStatus.error ||
+      !ownedStatus.data ||
+      statusRefresh < requiredStatusRefresh ||
+      !completionAttestation ||
+      captureFeedback?.kind === 'UNKNOWN'
+    ) {
+      setValidationError(
+        'Review the current linked shipment status and confirm completion before capture. Do not resend an uncertain capture.'
+      );
+      return;
+    }
+
+    const trimmedRecipient = recipientName.trim();
+    if (!trimmedRecipient) {
+      setValidationError('Recipient name is required.');
+      return;
+    }
+
+    const signatureData =
+      signatureType === 'typed'
+        ? typedSignature.trim()
+        : (signaturePadRef.current?.toDataUrl() ?? null);
+    if (!signatureData) {
+      setValidationError(
+        signatureType === 'typed'
+          ? 'Type the recipient full name as their signature.'
+          : 'A signature is required.'
+      );
+      return;
+    }
+
+    submissionLock.current = true;
+    setPreparing(true);
+    try {
+      let photoFileIds: string[] | undefined;
+      if (photoFile) {
+        if (uploadedPhoto.current?.file === photoFile) photoFileIds = [uploadedPhoto.current.id];
+        else {
+          const uploaded = await uploadPhoto(photoFile);
+          uploadedPhoto.current = { file: photoFile, id: uploaded.fileId };
+          photoFileIds = [uploaded.fileId];
+        }
+      }
+
+      if (!active.current) return;
+      const position = await getCurrentPosition();
+      if (!active.current) return;
+
+      const proof = await captureEpod({
+        expectedShipmentId: ownedStatus.data.myEpodShipmentStatus?.id ?? null,
+        expectedShipmentStatusRevision: ownedStatus.data.myEpodShipmentStatus?.statusRevision,
+        completionAttestation,
+        deliveryJobId: job.id,
+        recipientName: trimmedRecipient,
+        signatureType,
+        signatureData,
+        photoFileIds,
+        latitude: position?.coords.latitude,
+        longitude: position?.coords.longitude,
+        locationAccuracy: position?.coords.accuracy,
+        notes: notes.trim() || undefined,
+      });
+
+      if (!active.current) return;
+      onCaptured(proof.deliveryJobId);
+    } catch {
+      setCompletionAttestation(false);
+      setRequiredStatusRefresh(statusRefresh + 1);
+      // captureError / uploadError already carry the message for display below.
+    } finally {
+      submissionLock.current = false;
+      setPreparing(false);
+    }
+  };
+
+  const submitting = isSubmitting || isUploading || preparing;
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          <Truck size={18} /> Capture delivery for {job.deliveryJobNumber}
+        </CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="text-sm text-text-secondary space-y-1">
+          {job.customerName && <p>Recipient on file: {job.customerName}</p>}
+          {job.deliveryAddress && <p>{formatAddress(job.deliveryAddress)}</p>}
+        </div>
+        <section aria-label="Linked shipment status" className="space-y-2">
+          <p>
+            Recorded shipment:{' '}
+            {ownedStatus.data?.myEpodShipmentStatus
+              ? `${ownedStatus.data.myEpodShipmentStatus.status.toLowerCase().replaceAll('_', ' ')} · revision ${ownedStatus.data.myEpodShipmentStatus.statusRevision}`
+              : ownedStatus.data
+                ? 'No linked shipment'
+                : 'Loading current record'}
+          </p>
+          {ownedStatus.error && <p role="alert">{ownedStatus.error}</p>}
+          <Button
+            variant="outline"
+            disabled={ownedStatus.loading || submitting}
+            onClick={() => {
+              setCompletionAttestation(false);
+              setStatusRefresh((value) => value + 1);
+            }}
+          >
+            Refresh linked status
+          </Button>
+          <label className="flex items-start gap-2">
+            <input
+              type="checkbox"
+              checked={completionAttestation}
+              disabled={
+                ownedStatus.loading ||
+                !!ownedStatus.error ||
+                submitting ||
+                statusRefresh < requiredStatusRefresh ||
+                captureFeedback?.kind === 'UNKNOWN'
+              }
+              onChange={(event) => setCompletionAttestation(event.target.checked)}
+            />
+            I reviewed the recorded linked status and attest to this delivery completion.
+          </label>
+          <p>
+            This records an assigned driver's attestation; it does not independently verify physical
+            freight movement.
+          </p>
+          {captureFeedback && <p role="status">{captureFeedback.message}</p>}
+        </section>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="epod-recipient-name">Recipient name</Label>
+          <Input
+            id="epod-recipient-name"
+            value={recipientName}
+            onChange={(event) => setRecipientName(event.target.value)}
+            placeholder="Who received the delivery?"
+          />
+        </div>
+
+        <div className="space-y-1.5">
+          <Label>Signature</Label>
+          <div className="flex gap-2">
+            <Button
+              type="button"
+              variant={signatureType === 'drawn' ? 'default' : 'outline'}
+              size="sm"
+              onClick={() => setSignatureType('drawn')}
+            >
+              <PenLine size={14} /> Draw
+            </Button>
+            <Button
+              type="button"
+              variant={signatureType === 'typed' ? 'default' : 'outline'}
+              size="sm"
+              onClick={() => setSignatureType('typed')}
+            >
+              <TypeIcon size={14} /> Type name instead
+            </Button>
+          </div>
+          {signatureType === 'drawn' ? (
+            <SignaturePad ref={signaturePadRef} />
+          ) : (
+            <Input
+              value={typedSignature}
+              onChange={(event) => setTypedSignature(event.target.value)}
+              placeholder="Type full name as signature"
+            />
+          )}
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="epod-photo">Delivery photo (optional)</Label>
+          <div className="flex items-center gap-2">
+            <input
+              id="epod-photo"
+              type="file"
+              accept="image/*"
+              capture="environment"
+              onChange={(event) => setPhotoFile(event.target.files?.[0] ?? null)}
+              className="text-sm"
+            />
+            {photoFile && <Upload size={14} className="text-text-secondary" />}
+          </div>
+          {photoFile && <p className="text-xs text-text-secondary">{photoFile.name}</p>}
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="epod-notes">Notes (optional)</Label>
+          <Textarea
+            id="epod-notes"
+            value={notes}
+            onChange={(event) => setNotes(event.target.value)}
+            placeholder="e.g. Left with front desk, gate code used, etc."
+            rows={2}
+          />
+        </div>
+
+        <p className="flex items-center gap-1.5 text-xs text-text-secondary">
+          <MapPin size={12} /> Device GPS is captured automatically when permitted by the browser.
+        </p>
+
+        {offline && (
+          <p role="alert" className="text-sm text-text-secondary">
+            You are offline. Your entries stay on this screen; reconnect to confirm the delivery.
+          </p>
+        )}
+        {validationError && <FormError message={validationError} />}
+        {captureError && <FormError message={captureError.message} />}
+        {uploadError && <FormError message={uploadError.message} />}
+
+        <div className="flex gap-2 justify-end">
+          <Button type="button" variant="outline" onClick={onCancel} disabled={submitting}>
+            Cancel
+          </Button>
+          <Button
+            type="button"
+            onClick={() => void handleSubmit()}
+            disabled={
+              submitting ||
+              offline ||
+              ownedStatus.loading ||
+              !!ownedStatus.error ||
+              !ownedStatus.data ||
+              statusRefresh < requiredStatusRefresh ||
+              !completionAttestation ||
+              captureFeedback?.kind === 'UNKNOWN'
+            }
+          >
+            {submitting ? (
+              <>
+                <Loader2 size={14} className="animate-spin" /> Submitting…
+              </>
+            ) : (
+              <>
+                <CheckCircle2 size={14} /> Confirm delivery
+              </>
+            )}
+          </Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

package/src/movethewheels/hooks/index.ts

@@ -80,6 +80,15 @@ export {
   type EntityDocumentType,
 } from './useEntityDocuments';
 
+// Driver day view (mobile driver task list) — BOFF-3991
+export {
+  useMyDeliveryDay,
+  useOnlineStatus,
+  type DriverDay,
+  type DriverStop,
+  type DriverStopState,
+} from './useDriverDay';
+
 // Electronic proof of delivery (ePOD) capture — BOFF-4399
 export {
   useEpod,

package/src/movethewheels/hooks/useCarrierIntegrations.ts

@@ -0,0 +1,221 @@
+/**
+ * Carrier and telematics integration hooks (BOFF-4404).
+ *
+ * Reads and writes the workspace's `MtwIntegration` rows and their delivery
+ * log through wspace-movethewheels-svc's integration module. The service
+ * validates every write (supported provider, signing-secret length) and never
+ * returns the signing secret.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+import {
+  CREATE_INTEGRATION_MUTATION,
+  DELETE_INTEGRATION_MUTATION,
+  INTEGRATION_COUNTS_QUERY,
+  INTEGRATION_EVENTS_QUERY,
+  LIST_INTEGRATIONS_QUERY,
+  UPDATE_INTEGRATION_MUTATION,
+  type CarrierIntegration,
+  type CarrierIntegrationEvent,
+  type IntegrationStatus,
+  type SupportedProvider,
+} from '../utils/carrierIntegrations';
+
+export interface CreateCarrierIntegrationInput {
+  provider: SupportedProvider;
+  name: string;
+  apiSecret: string;
+}
+
+export interface UpdateCarrierIntegrationInput {
+  name?: string;
+  status?: IntegrationStatus;
+  apiSecret?: string;
+}
+
+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]
+  );
+}
+
+function toError(error: unknown, fallback: string): Error {
+  return error instanceof Error ? error : new Error(fallback);
+}
+
+export function useCarrierIntegrations(options: {
+  status?: IntegrationStatus;
+  limit: number;
+  offset: number;
+}) {
+  const graphQLOptions = useGraphQLOptions();
+  const { status, limit, offset } = options;
+  const [integrations, setIntegrations] = useState<CarrierIntegration[]>([]);
+  const [total, setTotal] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  // Only the latest request may update state: a slower response for a
+  // previous filter or page must not overwrite the current view.
+  const latestRequest = useRef(0);
+
+  const load = useCallback(async () => {
+    const request = ++latestRequest.current;
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await executeGraphQL<{
+        integrations: CarrierIntegration[];
+        integrationsCount: number;
+      }>(graphQLOptions, LIST_INTEGRATIONS_QUERY, {
+        filter: status ? { status } : undefined,
+        pagination: { limit, offset },
+      });
+      if (request !== latestRequest.current) return;
+      setIntegrations(data.integrations);
+      setTotal(data.integrationsCount);
+    } catch (loadError) {
+      if (request !== latestRequest.current) return;
+      setError(toError(loadError, 'Failed to load integrations'));
+    } finally {
+      if (request === latestRequest.current) setIsLoading(false);
+    }
+  }, [graphQLOptions, status, limit, offset]);
+
+  useEffect(() => {
+    void load();
+    return () => {
+      // Invalidate the in-flight request when the filter, page or unmount changes.
+      latestRequest.current += 1;
+    };
+  }, [load]);
+
+  // A refetch requested by a mutation that started under an earlier filter or
+  // page must load the view that is current when it completes, not the one
+  // captured when the mutation started.
+  const latestLoad = useRef(load);
+  useEffect(() => {
+    latestLoad.current = load;
+  }, [load]);
+  const refetch = useCallback(() => latestLoad.current(), []);
+
+  return { integrations, total, isLoading, error, refetch };
+}
+
+/** Workspace-wide feed counts (all and active) in one request, independent of the list filter. */
+export function useCarrierIntegrationCounts() {
+  const graphQLOptions = useGraphQLOptions();
+  const [counts, setCounts] = useState<{ all: number; active: number }>({ all: 0, active: 0 });
+  const latestRequest = useRef(0);
+
+  const load = useCallback(async () => {
+    const request = ++latestRequest.current;
+    try {
+      const data = await executeGraphQL<{ all: number; active: number }>(
+        graphQLOptions,
+        INTEGRATION_COUNTS_QUERY,
+        {}
+      );
+      if (request === latestRequest.current) setCounts({ all: data.all, active: data.active });
+    } catch {
+      // The list request surfaces load errors; the counts keep their last value.
+    }
+  }, [graphQLOptions]);
+
+  useEffect(() => {
+    void load();
+    return () => {
+      latestRequest.current += 1;
+    };
+  }, [load]);
+
+  return { ...counts, refetch: load };
+}
+
+/** The most recent deliveries for one integration, newest first. */
+export function useCarrierIntegrationEvents(
+  integrationId: string | null,
+  refreshKey: number,
+  limit = 20
+) {
+  const graphQLOptions = useGraphQLOptions();
+  const [events, setEvents] = useState<CarrierIntegrationEvent[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!integrationId) {
+      setEvents([]);
+      return;
+    }
+    let cancelled = false;
+    setIsLoading(true);
+    setError(null);
+    executeGraphQL<{ integrationEvents: CarrierIntegrationEvent[] }>(
+      graphQLOptions,
+      INTEGRATION_EVENTS_QUERY,
+      { integrationId, pagination: { limit, offset: 0 } }
+    )
+      .then((data) => {
+        if (!cancelled) setEvents(data.integrationEvents);
+      })
+      .catch((loadError: unknown) => {
+        if (!cancelled) setError(toError(loadError, 'Failed to load deliveries'));
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [graphQLOptions, integrationId, refreshKey, limit]);
+
+  return { events, isLoading, error };
+}
+
+export function useCarrierIntegrationActions() {
+  const graphQLOptions = useGraphQLOptions();
+
+  return useMemo(
+    () => ({
+      create: async (input: CreateCarrierIntegrationInput) => {
+        // A lost response must not create a second integration with a secret
+        // the operator never saw, so the write is attempted once.
+        const data = await executeGraphQL<{ createIntegration: CarrierIntegration }>(
+          graphQLOptions,
+          CREATE_INTEGRATION_MUTATION,
+          { input: { ...input, name: input.name.trim(), status: 'ACTIVE' } },
+          'SINGLE_ATTEMPT'
+        );
+        return data.createIntegration;
+      },
+      update: async (id: string, input: UpdateCarrierIntegrationInput) => {
+        const data = await executeGraphQL<{ updateIntegration: CarrierIntegration }>(
+          graphQLOptions,
+          UPDATE_INTEGRATION_MUTATION,
+          { id, input: input.name !== undefined ? { ...input, name: input.name.trim() } : input }
+        );
+        return data.updateIntegration;
+      },
+      remove: async (id: string) => {
+        const data = await executeGraphQL<{ deleteIntegration: boolean }>(
+          graphQLOptions,
+          DELETE_INTEGRATION_MUTATION,
+          { id }
+        );
+        return data.deleteIntegration;
+      },
+    }),
+    [graphQLOptions]
+  );
+}