@burdenoff/microfe-movethewheels 2026.726.1 → 2026.731.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 };
+}