@burdenoff/microfe-movethewheels 2026.1012.1 → 2026.1013.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burdenoff/microfe-movethewheels",
-  "version": "2026.1012.1",
+  "version": "2026.1013.1",
   "description": "Burdenoff MoveTheWheels Microfrontend - Logistics & Supply Chain Management Platform",
   "type": "module",
   "files": [
@@ -36,7 +36,7 @@
     "format": "prettier --write \"src/**/*.{ts,tsx}\"",
     "type:check": "bash scripts/build-limits.sh tsc --noEmit",
     "validate:schema-drift": "graphql-schema-drift",
-    "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run codegen && bun run validate:schema-drift && bun run lint:sanity && bun run format && bun run type:check && bun run verify:live-logistics-contract && bun run verify:empty-reuse-retry && bun run verify:empty-reuse-recovery && bun run verify:trip-utilization-input && bun run verify:trip-draft-context && bun run verify:stock-binding-input && bun run verify:stock-observation-input && bun run verify:pending-pick-input && bun run verify:freight-input && bun run verify:freight-recovery && bun run verify:procedure-input && bun run verify:consolidation && bun run verify:multimodal-single-attempt && bun run verify:workspace-predispatch && bun run verify:tracking-quality-outcomes && bun run verify:shipment-status-authority && bun run verify:braces-depth && bun run build && bun run build-storybook'",
+    "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run codegen && bun run validate:schema-drift && bun run lint:sanity && bun run format && bun run type:check && bun run verify:live-logistics-contract && bun run verify:empty-reuse-retry && bun run verify:empty-reuse-recovery && bun run verify:trip-utilization-input && bun run verify:trip-draft-context && bun run verify:stock-binding-input && bun run verify:stock-observation-input && bun run verify:pending-pick-input && bun run verify:freight-input && bun run verify:freight-recovery && bun run verify:procedure-input && bun run verify:consolidation && bun run verify:multimodal-single-attempt && bun run verify:workspace-predispatch && bun run verify:tracking-quality-outcomes && bun run verify:shipment-status-authority && bun run verify:free-time-permissions && bun run verify:braces-depth && bun run build && bun run build-storybook'",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "test:storybook": "test-storybook",
@@ -64,7 +64,8 @@
     "verify:consolidation": "bun scripts/verify-consolidation-input.mjs && bun scripts/verify-consolidation-recovery-hook.mjs && bun scripts/verify-consolidation-mounted-hook.mjs",
     "verify:tracking-quality-outcomes": "bun test scripts/verify-tracking-quality-outcomes.test.ts",
     "verify:braces-depth": "bun test scripts/braces-depth-patch.test.ts",
-    "verify:shipment-status-authority": "bun scripts/verify-shipment-status-command.mjs"
+    "verify:shipment-status-authority": "bun scripts/verify-shipment-status-command.mjs",
+    "verify:free-time-permissions": "bun scripts/verify-free-time-permission-gates.mjs"
   },
   "dependencies": {
     "@apollo/client": "^4.0.11",

package/src/movethewheels/hooks/useContainerLifecycle.ts

@@ -64,7 +64,7 @@ function describeError(error: unknown): string {
 }
 
 /** Source-labelled physical equipment; cargo shipment completion does not close a cycle. */
-export function useContainerLifecycle() {
+export function useContainerLifecycle(readEnabled = true) {
   const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
     useMoveTheWheels();
   const options = useMemo(
@@ -103,6 +103,10 @@ export function useContainerLifecycle() {
     setError(null);
     setContainers([]);
     setHasMore(false);
+    if (!readEnabled) {
+      setLoading(false);
+      return;
+    }
     void executeGraphQL<ContainerRegistryQuery>(options, print(ContainerRegistryDocument), {
       pagination: { limit: PAGE_SIZE, offset: page * PAGE_SIZE },
     })
@@ -121,7 +125,7 @@ export function useContainerLifecycle() {
     return () => {
       cancelled = true;
     };
-  }, [options, page, revision]);
+  }, [options, page, revision, readEnabled]);
 
   // Clear selections whenever the security/workspace context changes.
   useEffect(() => {
@@ -137,7 +141,7 @@ export function useContainerLifecycle() {
     setCycles([]);
     setHasMoreCycles(false);
     setCycleError(null);
-    if (!containerId) {
+    if (!readEnabled || !containerId) {
       setCyclesLoading(false);
       return;
     }
@@ -161,14 +165,14 @@ export function useContainerLifecycle() {
     return () => {
       cancelled = true;
     };
-  }, [options, containerId, cyclePage, revision]);
+  }, [options, containerId, cyclePage, revision, readEnabled]);
 
   useEffect(() => {
     let cancelled = false;
     setEvents([]);
     setHasMoreEvents(false);
     setEventError(null);
-    if (!cycleId) {
+    if (!readEnabled || !cycleId) {
       setEventsLoading(false);
       return;
     }
@@ -192,7 +196,7 @@ export function useContainerLifecycle() {
     return () => {
       cancelled = true;
     };
-  }, [options, cycleId, eventPage, revision]);
+  }, [options, cycleId, eventPage, revision, readEnabled]);
 
   const refresh = useCallback(() => setRevision((value) => value + 1), []);
   // Keep the same key after an uncertain response so a manual retry replays the

package/src/movethewheels/hooks/useEpod.ts

@@ -11,7 +11,7 @@
  * Deferred (see BOFF-4399 follow-up notes): barcode/RFID capture and
  * multi-language delivery instructions.
  */
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { parse } from 'graphql';
 import { useShipmentStatusCommand } from './useShipmentStatusAuthority';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
@@ -212,51 +212,127 @@ interface ApiPendingJob {
 export function useMyPendingEpodDeliveryJobs(options: { limit?: number; offset?: number } = {}) {
   const { limit = 20, offset = 0 } = options;
   const graphQLOptions = useGraphQLOptions();
-  const [jobs, setJobs] = useState<PendingEpodDeliveryJob[]>([]);
-  const [totalJobs, setTotalJobs] = useState(0);
-  const [hasMore, setHasMore] = useState(false);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
+  const scopeKey = JSON.stringify([
+    graphQLOptions.apiGatewayUrl,
+    graphQLOptions.workspaceId,
+    graphQLOptions.tenantId,
+    graphQLOptions.actorId,
+  ]);
+  const readKey = JSON.stringify([scopeKey, limit, offset]);
+  // A validated capture ACK makes this stop ineligible for capture immediately.
+  // Keep that fact for this actor/scope while a pending-list refresh is delayed.
+  // This is an in-memory UI exclusion, never a fabricated server job update.
+  const acknowledgedJobs = useRef({ scopeKey, ids: new Set<string>() });
+  const requestId = useRef(0);
+  const [snapshot, setSnapshot] = useState<{
+    scopeKey: string;
+    readKey: string;
+    jobs: PendingEpodDeliveryJob[];
+    totalJobs: number;
+    hasMore: boolean;
+    isLoading: boolean;
+    error: Error | null;
+  }>({ scopeKey, readKey, jobs: [], totalJobs: 0, hasMore: false, isLoading: true, error: null });
 
   const load = useCallback(async () => {
-    setIsLoading(true);
-    setError(null);
+    const request = ++requestId.current;
+    if (acknowledgedJobs.current.scopeKey !== scopeKey) {
+      acknowledgedJobs.current = { scopeKey, ids: new Set<string>() };
+    }
+    setSnapshot((previous) => ({
+      scopeKey,
+      readKey,
+      jobs: previous.readKey === readKey ? previous.jobs : [],
+      totalJobs: previous.readKey === readKey ? previous.totalJobs : 0,
+      hasMore: previous.readKey === readKey ? previous.hasMore : false,
+      isLoading: true,
+      error: null,
+    }));
     try {
       const data = await executeGraphQL<{
         myPendingEpodDeliveryJobs: ApiPendingJob[];
         myPendingEpodDeliveryJobsCount: number;
       }>(graphQLOptions, MY_PENDING_EPOD_JOBS_QUERY, { pagination: { limit, offset } });
-      setTotalJobs(data.myPendingEpodDeliveryJobsCount ?? 0);
-      setHasMore(
-        offset + data.myPendingEpodDeliveryJobs.length < data.myPendingEpodDeliveryJobsCount
-      );
-      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,
-        }))
-      );
+      if (request !== requestId.current) return;
+      const rows = data.myPendingEpodDeliveryJobs;
+      const total = data.myPendingEpodDeliveryJobsCount ?? 0;
+      const excluded = rows.filter((job) => acknowledgedJobs.current.ids.has(job.id)).length;
+      setSnapshot({
+        scopeKey,
+        readKey,
+        totalJobs: Math.max(0, total - excluded),
+        // Pagination still follows the server page, including any excluded row.
+        hasMore: offset + rows.length < total,
+        jobs: rows
+          .filter((job) => !acknowledgedJobs.current.ids.has(job.id))
+          .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,
+          })),
+        isLoading: false,
+        error: null,
+      });
     } catch (fetchError) {
-      setError(
-        fetchError instanceof Error ? fetchError : new Error('Failed to load pending deliveries')
-      );
-      setJobs([]);
-    } finally {
-      setIsLoading(false);
+      if (request !== requestId.current) return;
+      setSnapshot({
+        scopeKey,
+        readKey,
+        jobs: [],
+        totalJobs: 0,
+        hasMore: false,
+        isLoading: false,
+        error:
+          fetchError instanceof Error ? fetchError : new Error('Failed to load pending deliveries'),
+      });
     }
-  }, [graphQLOptions, limit, offset]);
+  }, [graphQLOptions, limit, offset, scopeKey, readKey]);
+
+  const cancelPendingRead = useCallback(() => {
+    requestId.current++;
+  }, []);
 
   useEffect(() => {
     void load();
-  }, [load]);
+    return cancelPendingRead;
+  }, [load, cancelPendingRead]);
+
+  const retireAcknowledgedJob = useCallback(
+    (deliveryJobId: string) => {
+      if (
+        acknowledgedJobs.current.scopeKey !== scopeKey ||
+        acknowledgedJobs.current.ids.has(deliveryJobId)
+      )
+        return;
+      acknowledgedJobs.current.ids.add(deliveryJobId);
+      setSnapshot((previous) => {
+        if (previous.scopeKey !== scopeKey) return previous;
+        const removed = previous.jobs.some((job) => job.id === deliveryJobId);
+        return {
+          ...previous,
+          jobs: previous.jobs.filter((job) => job.id !== deliveryJobId),
+          totalJobs: Math.max(0, previous.totalJobs - (removed ? 1 : 0)),
+        };
+      });
+    },
+    [scopeKey]
+  );
 
-  return { jobs, totalJobs, hasMore, isLoading, error, refetch: load };
+  const current = snapshot.readKey === readKey;
+  return {
+    jobs: current ? snapshot.jobs : [],
+    totalJobs: current ? snapshot.totalJobs : 0,
+    hasMore: current && snapshot.hasMore,
+    isLoading: !current || snapshot.isLoading,
+    error: current ? snapshot.error : null,
+    refetch: load,
+    retireAcknowledgedJob,
+  };
 }
 
 export interface CaptureEpodArgs {

package/src/movethewheels/hooks/useShipmentPermissions.ts

@@ -0,0 +1,38 @@
+import { useCallback, useLayoutEffect, useRef } from 'react';
+import { usePermissions } from '@burdenoff/fe-libs/shared/providers/shell';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+
+/** Match ordinary effective permissions to this page's current actor and workspace. */
+export function useShipmentPermissions() {
+  const permissions = usePermissions();
+  const { workspaceId, currentUser } = useMoveTheWheels();
+  const currentScope = Boolean(
+    workspaceId &&
+    currentUser?.id &&
+    permissions.scopeId === workspaceId &&
+    (permissions.isSuperAdmin ||
+      (permissions.permissions?.scopeId === workspaceId &&
+        permissions.permissions.actorId === currentUser.id))
+  );
+  const ready = currentScope && !permissions.isLoading && !permissions.error;
+  const canRead = ready && permissions.hasPermission('shipment:read');
+  const canCreate = canRead && permissions.hasPermission('shipment:create');
+  const canUpdate = canRead && permissions.hasPermission('shipment:update');
+  const current = useRef({ create: false, update: false });
+  useLayoutEffect(() => {
+    current.current = { create: canCreate, update: canUpdate };
+    return () => {
+      // Retained callbacks from a revoked or unmounted scope cannot submit a command.
+      current.current = { create: false, update: false };
+    };
+  }, [canCreate, canUpdate]);
+  const allows = useCallback((action: 'create' | 'update') => current.current[action], []);
+  return {
+    canRead,
+    canCreate,
+    canUpdate,
+    allows,
+    loading: permissions.isLoading,
+    failed: Boolean(permissions.error),
+  };
+}