@burdenoff/microfe-movethewheels 2026.725.1 → 2026.728.1

package/src/movethewheels/hooks/useEpod.ts

@@ -0,0 +1,410 @@
+/**
+ * Electronic proof-of-delivery (ePOD) capture — BOFF-4399.
+ *
+ * Wire shape mirrors `wspace-movethewheels-svc: src/modules/epod/schema/epod.gql`.
+ * Photo attachments are uploaded through the platform `wspace-files-svc`
+ * 3-step flow (initiateUpload → PUT → completeUpload) — the same pattern used
+ * by other products' file-backed fields (see `microfe-artistrybase`'s
+ * `useArtFiles.ts`) — and only the resulting File ids are sent to
+ * `captureEpod`; no bytes are ever stored by this service.
+ *
+ * Deferred (see BOFF-4399 follow-up notes): barcode/RFID capture and
+ * multi-language delivery instructions.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import type { Order, ProofOfDelivery, SignatureType } from '../types';
+import { executeGraphQL } from '../utils/graphqlClient';
+
+interface ApiProofOfDelivery {
+  id: string;
+  deliveryJobId: string;
+  shipmentId?: string | null;
+  recipientName: string;
+  signatureType: 'DRAWN' | 'TYPED';
+  signatureData: string;
+  photoFileIds?: string[] | null;
+  latitude?: number | null;
+  longitude?: number | null;
+  locationAccuracy?: number | null;
+  deliveredAt: string;
+  capturedByDriverId: string;
+  notes?: string | null;
+}
+
+const EPOD_FIELDS = `
+  id
+  deliveryJobId
+  shipmentId
+  recipientName
+  signatureType
+  signatureData
+  photoFileIds
+  latitude
+  longitude
+  locationAccuracy
+  deliveredAt
+  capturedByDriverId
+  notes
+`;
+
+const GET_EPOD_QUERY = `
+  query GetEpod($deliveryJobId: ID!) {
+    epod(deliveryJobId: $deliveryJobId) {
+      ${EPOD_FIELDS}
+    }
+  }
+`;
+
+const MY_PENDING_EPOD_JOBS_QUERY = `
+  query MyPendingEpodDeliveryJobs($pagination: PaginationInput) {
+    myPendingEpodDeliveryJobs(pagination: $pagination) {
+      id
+      deliveryJobNumber
+      status
+      priority
+      deliveryAddress
+      scheduledDelivery
+      customer {
+        name
+        phone
+      }
+    }
+  }
+`;
+
+const CAPTURE_EPOD_MUTATION = `
+  mutation CaptureEpod($input: CaptureEpodInput!) {
+    captureEpod(input: $input) {
+      ${EPOD_FIELDS}
+    }
+  }
+`;
+
+const INITIATE_UPLOAD_MUTATION = `
+  mutation EpodInitiateUpload($input: InitiateUploadInput!) {
+    initiateUpload(input: $input) {
+      uploadUrl
+      session { id }
+    }
+  }
+`;
+
+const COMPLETE_UPLOAD_MUTATION = `
+  mutation EpodCompleteUpload($input: CompleteUploadInput!) {
+    completeUpload(input: $input) {
+      fileId
+    }
+  }
+`;
+
+const GET_FILE_URL_QUERY = `
+  query EpodFileUrl($id: ID!, $expiresIn: Int) {
+    getFileDownloadUrl(id: $id, expiresIn: $expiresIn)
+  }
+`;
+
+/** 6 hours — comfortably under S3's 604800s (7-day) presign cap. */
+const FILE_URL_TTL_SECONDS = 21600;
+
+function toApiSignatureType(type: SignatureType): 'DRAWN' | 'TYPED' {
+  return type === 'typed' ? 'TYPED' : 'DRAWN';
+}
+
+function mapEpod(pod: ApiProofOfDelivery): ProofOfDelivery {
+  return {
+    id: pod.id,
+    deliveryJobId: pod.deliveryJobId,
+    shipmentId: pod.shipmentId ?? undefined,
+    recipientName: pod.recipientName,
+    signatureType: pod.signatureType === 'TYPED' ? 'typed' : 'drawn',
+    signatureData: pod.signatureData,
+    photoFileIds: pod.photoFileIds ?? [],
+    latitude: pod.latitude ?? undefined,
+    longitude: pod.longitude ?? undefined,
+    locationAccuracy: pod.locationAccuracy ?? undefined,
+    deliveredAt: new Date(pod.deliveredAt),
+    capturedByDriverId: pod.capturedByDriverId,
+    notes: pod.notes ?? undefined,
+  };
+}
+
+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]
+  );
+}
+
+/** The shipper/customer-facing view: the completed ePOD record for a delivery job (or null if not yet captured). */
+export function useEpod(deliveryJobId: string | undefined) {
+  const graphQLOptions = useGraphQLOptions();
+  const [epod, setEpod] = useState<ProofOfDelivery | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const load = useCallback(async () => {
+    if (!deliveryJobId) {
+      setEpod(null);
+      return;
+    }
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await executeGraphQL<{ epod: ApiProofOfDelivery | null }>(
+        graphQLOptions,
+        GET_EPOD_QUERY,
+        { deliveryJobId }
+      );
+      setEpod(data.epod ? mapEpod(data.epod) : null);
+    } catch (fetchError) {
+      setError(fetchError instanceof Error ? fetchError : new Error('Failed to load proof of delivery'));
+      setEpod(null);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [deliveryJobId, graphQLOptions]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  return { epod, isLoading, error, refetch: load };
+}
+
+export interface PendingEpodDeliveryJob {
+  id: string;
+  deliveryJobNumber: string;
+  status: string;
+  priority: string;
+  deliveryAddress: Order['deliveryAddress'] | null;
+  scheduledDelivery?: Date;
+  customerName?: string;
+  customerPhone?: string;
+}
+
+interface ApiPendingJob {
+  id: string;
+  deliveryJobNumber: string;
+  status: string;
+  priority: string;
+  deliveryAddress: Order['deliveryAddress'] | null;
+  scheduledDelivery?: string | null;
+  customer?: { name?: string | null; phone?: string | null } | null;
+}
+
+/** Type C self-list: the CALLING driver's own jobs still awaiting ePOD capture — feeds the capture flow's job picker. */
+export function useMyPendingEpodDeliveryJobs() {
+  const graphQLOptions = useGraphQLOptions();
+  const [jobs, setJobs] = useState<PendingEpodDeliveryJob[]>([]);
+  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<{ myPendingEpodDeliveryJobs: ApiPendingJob[] }>(
+        graphQLOptions,
+        MY_PENDING_EPOD_JOBS_QUERY,
+        { pagination: { limit: 50, offset: 0 } }
+      );
+      setJobs(
+        data.myPendingEpodDeliveryJobs.map((job) => ({
+          id: job.id,
+          deliveryJobNumber: job.deliveryJobNumber,
+          status: job.status,
+          priority: job.priority,
+          deliveryAddress: job.deliveryAddress,
+          scheduledDelivery: job.scheduledDelivery ? new Date(job.scheduledDelivery) : undefined,
+          customerName: job.customer?.name ?? undefined,
+          customerPhone: job.customer?.phone ?? undefined,
+        }))
+      );
+    } catch (fetchError) {
+      setError(
+        fetchError instanceof Error ? fetchError : new Error('Failed to load pending deliveries')
+      );
+      setJobs([]);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [graphQLOptions]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  return { jobs, isLoading, error, refetch: load };
+}
+
+export interface CaptureEpodArgs {
+  deliveryJobId: string;
+  recipientName: string;
+  signatureType: SignatureType;
+  signatureData: string;
+  photoFileIds?: string[];
+  latitude?: number;
+  longitude?: number;
+  locationAccuracy?: number;
+  notes?: string;
+}
+
+/** Driver-facing capture mutation. Identity/ownership is enforced server-side — this never sends a driver id. */
+export function useCaptureEpod() {
+  const graphQLOptions = useGraphQLOptions();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const captureEpod = useCallback(
+    async (args: CaptureEpodArgs): Promise<ProofOfDelivery> => {
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        const data = await executeGraphQL<{ captureEpod: ApiProofOfDelivery }>(
+          graphQLOptions,
+          CAPTURE_EPOD_MUTATION,
+          {
+            input: {
+              deliveryJobId: args.deliveryJobId,
+              recipientName: args.recipientName,
+              signatureType: toApiSignatureType(args.signatureType),
+              signatureData: args.signatureData,
+              photoFileIds: args.photoFileIds,
+              latitude: args.latitude,
+              longitude: args.longitude,
+              locationAccuracy: args.locationAccuracy,
+              notes: args.notes,
+            },
+          }
+        );
+        return mapEpod(data.captureEpod);
+      } catch (captureError) {
+        const err =
+          captureError instanceof Error ? captureError : new Error('Failed to capture proof of delivery');
+        setError(err);
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [graphQLOptions]
+  );
+
+  return { captureEpod, isSubmitting, error };
+}
+
+export interface UploadedEpodPhoto {
+  fileId: string;
+  fileName: string;
+}
+
+/** Uploads a delivery photo via the platform 3-step file flow and resolves to its `fileId`. */
+export function useEpodPhotoUpload() {
+  const graphQLOptions = useGraphQLOptions();
+  const [isUploading, setIsUploading] = useState(false);
+  const [progress, setProgress] = useState(0);
+  const [error, setError] = useState<Error | null>(null);
+
+  const upload = useCallback(
+    async (file: File): Promise<UploadedEpodPhoto> => {
+      setIsUploading(true);
+      setProgress(0);
+      setError(null);
+      try {
+        const dotIndex = file.name.lastIndexOf('.');
+        const extension = dotIndex > -1 ? file.name.slice(dotIndex + 1) : '';
+        const mimeType = file.type || 'application/octet-stream';
+
+        const initiated = await executeGraphQL<{
+          initiateUpload: { uploadUrl: string | null; session: { id: string } };
+        }>(graphQLOptions, INITIATE_UPLOAD_MUTATION, {
+          input: {
+            fileName: file.name,
+            extension,
+            mimeType,
+            fileSize: String(file.size),
+            visibility: 'WORKSPACE',
+          },
+        });
+
+        const { uploadUrl } = initiated.initiateUpload;
+        const sessionId = initiated.initiateUpload.session.id;
+        if (!uploadUrl) {
+          throw new Error('The file service did not return an upload URL.');
+        }
+
+        setProgress(50);
+        const putResponse = await fetch(uploadUrl, {
+          method: 'PUT',
+          headers: { 'Content-Type': mimeType },
+          body: file,
+        });
+        if (!putResponse.ok) {
+          throw new Error(`File storage rejected the upload (HTTP ${putResponse.status}).`);
+        }
+
+        const completed = await executeGraphQL<{ completeUpload: { fileId: string } }>(
+          graphQLOptions,
+          COMPLETE_UPLOAD_MUTATION,
+          { input: { sessionId, fileSize: String(file.size) } }
+        );
+
+        setProgress(100);
+        return { fileId: completed.completeUpload.fileId, fileName: file.name };
+      } catch (uploadError) {
+        const err = uploadError instanceof Error ? uploadError : new Error('The photo could not be uploaded.');
+        setError(err);
+        throw err;
+      } finally {
+        setIsUploading(false);
+      }
+    },
+    [graphQLOptions]
+  );
+
+  return { upload, isUploading, progress, error };
+}
+
+/** Resolves a TTL-safe download URL for a captured delivery photo, for display/download. */
+export function useEpodPhotoUrl(fileId: string | null | undefined) {
+  const graphQLOptions = useGraphQLOptions();
+  const [url, setUrl] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+
+  useEffect(() => {
+    if (!fileId) {
+      setUrl(null);
+      return;
+    }
+    let cancelled = false;
+    setIsLoading(true);
+    executeGraphQL<{ getFileDownloadUrl: string | null }>(graphQLOptions, GET_FILE_URL_QUERY, {
+      id: fileId,
+      expiresIn: FILE_URL_TTL_SECONDS,
+    })
+      .then((data) => {
+        if (!cancelled) setUrl(data.getFileDownloadUrl ?? null);
+      })
+      .catch(() => {
+        if (!cancelled) setUrl(null);
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [fileId, graphQLOptions]);
+
+  return { url, isLoading };
+}

package/src/movethewheels/pages/DeliveryCapturePage.tsx

@@ -0,0 +1,297 @@
+/**
+ * Delivery Capture Page — driver-facing electronic proof-of-delivery (ePOD)
+ * capture flow (BOFF-4399).
+ *
+ * Lists the calling driver's own delivery jobs still awaiting capture
+ * (`myPendingEpodDeliveryJobs`, Type C self-list — no other driver's jobs are
+ * ever visible here) and lets them capture: recipient name, signature
+ * (drawn or typed), an optional delivery photo (uploaded via the platform
+ * files primitive), device GPS if available, and notes. Submitting calls
+ * `captureEpod`, which the backend owner-verifies against the assigned
+ * driver and marks the job DELIVERED.
+ *
+ * Deferred (see BOFF-4399 follow-up notes): barcode/RFID scan-based capture,
+ * multi-language delivery instructions, and the full standalone mobile
+ * driver app (BOFF-3991) — this page is the capture core, reachable from the
+ * existing web MFE.
+ */
+import { useRef, useState } from 'react';
+import {
+  CheckCircle2,
+  Loader2,
+  MapPin,
+  Package,
+  PenLine,
+  Truck,
+  Type as TypeIcon,
+  Upload,
+} from 'lucide-react';
+import { PageLayout } from '../components/PageLayout';
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label, Textarea } from '../components/ui';
+import { SignaturePad, type SignaturePadHandle } from '../components/SignaturePad';
+import { FormError } from '../components/FormError';
+import { Notice, useNotice } from '../components/Notice';
+import {
+  useCaptureEpod,
+  useEpodPhotoUpload,
+  useMyPendingEpodDeliveryJobs,
+  type PendingEpodDeliveryJob,
+} from '../hooks/useEpod';
+import { formatAddress, formatDate } from '../utils/formatters';
+import type { SignatureType } from '../types';
+
+/** 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 }
+    );
+  });
+}
+
+function CaptureForm({
+  job,
+  onCaptured,
+  onCancel,
+}: {
+  job: PendingEpodDeliveryJob;
+  onCaptured: () => void;
+  onCancel: () => void;
+}) {
+  const { captureEpod, isSubmitting, error: captureError } = useCaptureEpod();
+  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 () => {
+    setValidationError(null);
+
+    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;
+    }
+
+    try {
+      let photoFileIds: string[] | undefined;
+      if (photoFile) {
+        const uploaded = await uploadPhoto(photoFile);
+        photoFileIds = [uploaded.fileId];
+      }
+
+      const position = await getCurrentPosition();
+
+      await captureEpod({
+        deliveryJobId: job.id,
+        recipientName: trimmedRecipient,
+        signatureType,
+        signatureData,
+        photoFileIds,
+        latitude: position?.coords.latitude,
+        longitude: position?.coords.longitude,
+        locationAccuracy: position?.coords.accuracy,
+        notes: notes.trim() || undefined,
+      });
+
+      onCaptured();
+    } catch {
+      // captureError / uploadError already carry the message for display below.
+    }
+  };
+
+  const submitting = isSubmitting || isUploading;
+
+  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>
+
+        <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>
+
+        {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}>
+            {submitting ? (
+              <>
+                <Loader2 size={14} className="animate-spin" /> Submitting…
+              </>
+            ) : (
+              <>
+                <CheckCircle2 size={14} /> Confirm delivery
+              </>
+            )}
+          </Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+export default function DeliveryCapturePage() {
+  const { jobs, isLoading, error, refetch } = useMyPendingEpodDeliveryJobs();
+  const [selectedJob, setSelectedJob] = useState<PendingEpodDeliveryJob | null>(null);
+  const { message, notify } = useNotice();
+
+  const handleCaptured = () => {
+    notify('Proof of delivery captured — delivery marked complete.');
+    setSelectedJob(null);
+    refetch();
+  };
+
+  return (
+    <PageLayout
+      title="My Deliveries"
+      subtitle="Capture proof of delivery for your assigned stops"
+      icon={<Truck size={24} />}
+    >
+      <div className="space-y-4">
+        <Notice message={message} />
+
+        {selectedJob ? (
+          <CaptureForm job={selectedJob} onCaptured={handleCaptured} onCancel={() => setSelectedJob(null)} />
+        ) : isLoading ? (
+          <p className="text-text-secondary text-center py-8">Loading your deliveries…</p>
+        ) : error ? (
+          <FormError message={error.message} />
+        ) : jobs.length > 0 ? (
+          <div className="space-y-3">
+            {jobs.map((job) => (
+              <Card key={job.id}>
+                <CardContent className="flex items-center justify-between gap-3 py-4">
+                  <div className="min-w-0">
+                    <p className="font-medium flex items-center gap-2">
+                      <Package size={16} /> {job.deliveryJobNumber}
+                    </p>
+                    {job.deliveryAddress && (
+                      <p className="text-sm text-text-secondary truncate">
+                        {formatAddress(job.deliveryAddress)}
+                      </p>
+                    )}
+                    {job.scheduledDelivery && (
+                      <p className="text-xs text-text-secondary">
+                        Scheduled {formatDate(job.scheduledDelivery, 'short')}
+                      </p>
+                    )}
+                  </div>
+                  <Button type="button" size="sm" onClick={() => setSelectedJob(job)}>
+                    Capture
+                  </Button>
+                </CardContent>
+              </Card>
+            ))}
+          </div>
+        ) : (
+          <div className="text-center py-12">
+            <CheckCircle2 size={40} className="mx-auto mb-3 text-text-secondary opacity-50" />
+            <p className="text-text-secondary">No deliveries awaiting proof of delivery.</p>
+          </div>
+        )}
+      </div>
+    </PageLayout>
+  );
+}