@burdenoff/microfe-movethewheels 2026.930.5 → 2026.1010.2

package/src/movethewheels/hooks/useConsolidationAction.ts

@@ -0,0 +1,196 @@
+import { useRef, useState } from 'react';
+import { print, type DocumentNode } from 'graphql';
+import { useConditionApi } from './useContainerCondition';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import {
+  SaveConsolidationPlanDocument,
+  RecordConsolidationObservationDocument,
+  SaveConsolidationManifestDocument,
+} from '../../generated/consolidation-operations';
+import { originalConsolidationHistoryTarget } from '../utils/consolidationHistoryTarget';
+import { consolidationAcknowledgement } from '../utils/consolidationInput';
+import {
+  reuseRecoveryScope,
+  reuseRecoveryContextKey,
+  sameReuseRecoveryScope,
+  type ReuseRecovery,
+} from '../utils/reuseRecovery';
+import {
+  decodeConsolidationRecovery,
+  encodeConsolidationRecovery,
+  CONSOLIDATION_RECOVERY_STORAGE,
+} from '../utils/consolidationRecovery';
+const documents = [
+  SaveConsolidationPlanDocument,
+  RecordConsolidationObservationDocument,
+  SaveConsolidationManifestDocument,
+];
+function loadRecovery(): { attempt: ReuseRecovery | null; blocked: boolean } {
+  try {
+    const raw = sessionStorage.getItem(CONSOLIDATION_RECOVERY_STORAGE);
+    const attempt = decodeConsolidationRecovery(raw);
+    return { attempt, blocked: raw !== null && attempt === null };
+  } catch {
+    return { attempt: null, blocked: true };
+  }
+}
+/** F08 retains one unresolved request across entity/context remounts; it never sends automatically. */
+export function useConsolidationAction() {
+  const request = useConditionApi('SINGLE_ATTEMPT');
+  const context = useMoveTheWheels();
+  const scope = reuseRecoveryScope(
+    context.currentUser?.id,
+    context.workspaceId,
+    context.tenantId,
+    context.apiGatewayUrl,
+    context.workspaceToken
+  );
+  const [initial] = useState(loadRecovery);
+  const [pending, setPending] = useState<ReuseRecovery | null>(initial.attempt);
+  const [blocked, setBlocked] = useState(initial.blocked);
+  const pendingRef = useRef(pending);
+  const running = useRef(false);
+  const [busy, setBusy] = useState(false);
+  const contextKey = reuseRecoveryContextKey(scope);
+  const [feedback, setFeedback] = useState<{
+    scopeKey: string;
+    error: string | null;
+    notice: string | null;
+  }>({ scopeKey: contextKey, error: null, notice: null });
+  // Async callbacks retain their submitting context; a new context masks their feedback.
+  const setError = (error: string | null) =>
+    setFeedback({ scopeKey: contextKey, error, notice: null });
+  const setNotice = (notice: string | null) =>
+    setFeedback({ scopeKey: contextKey, error: null, notice });
+  const [revision, setRevision] = useState(0);
+  const retain = (attempt: ReuseRecovery | null, completed?: ReuseRecovery) => {
+    if (attempt)
+      sessionStorage.setItem(CONSOLIDATION_RECOVERY_STORAGE, encodeConsolidationRecovery(attempt));
+    else {
+      const saved = decodeConsolidationRecovery(
+        sessionStorage.getItem(CONSOLIDATION_RECOVERY_STORAGE)
+      );
+      // An older in-flight reply must not erase a subsequently retained attempt after a remount.
+      if (
+        !completed ||
+        (saved?.key === completed.key && sameReuseRecoveryScope(saved.scope, completed.scope))
+      )
+        sessionStorage.removeItem(CONSOLIDATION_RECOVERY_STORAGE);
+    }
+    pendingRef.current = attempt;
+    setPending(attempt);
+    setBlocked(false);
+  };
+  const send = async (attempt: ReuseRecovery) => {
+    if (running.current) return null;
+    if (!sameReuseRecoveryScope(attempt.scope, scope)) {
+      setError(
+        'Return to the original account, organization, workspace and project before retrying.'
+      );
+      return null;
+    }
+    const document = documents.find((item) => print(item) === attempt.operation);
+    if (!document) {
+      setError('The saved operation changed. Check history before abandoning this attempt.');
+      return null;
+    }
+    running.current = true;
+    setBusy(true);
+    setError(null);
+    setNotice(null);
+    try {
+      const result = await request<Record<string, unknown>>(document, {
+        input: { ...attempt.input, idempotencyKey: attempt.key },
+      });
+      if (!consolidationAcknowledgement(result, attempt.input, attempt.scope.actorId))
+        throw new Error(
+          'The save reply could not be confirmed. Keep the original request and check history.'
+        );
+      // Clearing storage may fail after a known reply. Retain the same key rather than making a new intent.
+      retain(null, attempt);
+      setRevision((value) => value + 1);
+      setNotice(attempt.success);
+      return result;
+    } catch (failure) {
+      setError(
+        failure instanceof Error
+          ? failure.message
+          : 'Unable to save. Check history before retrying.'
+      );
+      return null;
+    } finally {
+      running.current = false;
+      setBusy(false);
+    }
+  };
+  const run = async (document: DocumentNode, input: Record<string, unknown>, success: string) => {
+    if (running.current || pendingRef.current || blocked) {
+      setError('Resolve the original request before starting another.');
+      return null;
+    }
+    if (!scope) {
+      setError('Wait for the current account and workspace session.');
+      return null;
+    }
+    const operation = print(document);
+    if (!documents.some((item) => print(item) === operation)) {
+      setError('Unsupported consolidation operation.');
+      return null;
+    }
+    try {
+      if (sessionStorage.getItem(CONSOLIDATION_RECOVERY_STORAGE) !== null) {
+        setError(
+          'A saved request is unresolved. Reload this page and check history before starting another.'
+        );
+        return null;
+      }
+    } catch {
+      setError('This browser cannot retain the request safely. Nothing was sent.');
+      return null;
+    }
+    const attempt: ReuseRecovery = {
+      version: 1,
+      scope,
+      operation,
+      input: structuredClone(input),
+      key: crypto.randomUUID(),
+      success,
+    };
+    try {
+      retain(attempt);
+    } catch {
+      setError('This browser cannot retain the request safely. Nothing was sent.');
+      return null;
+    }
+    return send(attempt);
+  };
+  const retryOriginal = async () => {
+    if (pendingRef.current) await send(pendingRef.current);
+  };
+  const discardAttempt = () => {
+    if (running.current) return;
+    try {
+      retain(null);
+      setError(null);
+      setNotice(null);
+    } catch {
+      setError('Unable to clear the saved attempt. Nothing was sent.');
+    }
+  };
+  return {
+    run,
+    retryOriginal,
+    discardAttempt,
+    refresh: () => setRevision((value) => value + 1),
+    busy,
+    error: feedback.scopeKey === contextKey ? feedback.error : null,
+    notice: feedback.scopeKey === contextKey ? feedback.notice : null,
+    revision,
+    uncertain: pending !== null || blocked,
+    recoveryInvalid: blocked,
+    canRetry: pending !== null && sameReuseRecoveryScope(pending.scope, scope),
+    originalContext: pending?.scope ?? null,
+    originalHistoryTarget: originalConsolidationHistoryTarget(pending, scope),
+    contextKey,
+  };
+}

package/src/movethewheels/hooks/useContainerCondition.ts

@@ -0,0 +1,129 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { print, type DocumentNode } from 'graphql';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL, type GraphQLAttemptPolicy } from '../utils/graphqlClient';
+
+export function useConditionApi(attemptPolicy: GraphQLAttemptPolicy = 'RETRY_TRANSIENT') {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const options = useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+  return useCallback(
+    <T>(document: DocumentNode, variables: Record<string, unknown>) =>
+      executeGraphQL<T>(options, print(document), variables, attemptPolicy),
+    [options, attemptPolicy]
+  );
+}
+
+/** Bounded pages, cancellation of stale responses, and explicit access failures. */
+export function useConditionQuery<T>(
+  document: DocumentNode,
+  variables: Record<string, unknown> | null,
+  revision = 0
+) {
+  const request = useConditionApi();
+  const variablesKey = JSON.stringify(variables);
+  const [state, setState] = useState<{
+    request: typeof request;
+    variablesKey: string;
+    revision: number;
+    data: T | null;
+    error: string | null;
+    loading: boolean;
+  } | null>(null);
+  useEffect(() => {
+    let active = true;
+    const scope = { request, variablesKey, revision };
+    setState({ ...scope, data: null, error: null, loading: variablesKey !== 'null' });
+    if (variablesKey === 'null') return;
+    const parsed: Record<string, unknown> = JSON.parse(variablesKey);
+    void request<T>(document, parsed)
+      .then((data) => {
+        if (active) setState({ ...scope, data, error: null, loading: false });
+      })
+      .catch((failure: unknown) => {
+        if (active)
+          setState({
+            ...scope,
+            data: null,
+            error: failure instanceof Error ? failure.message : 'Unable to load these records.',
+            loading: false,
+          });
+      });
+    return () => {
+      active = false;
+    };
+  }, [document, variablesKey, request, revision]);
+  // Mask during render, before effects run after a context/access or revision change.
+  const current =
+    state?.request === request &&
+    state.variablesKey === variablesKey &&
+    state.revision === revision;
+  return {
+    data: current ? state.data : null,
+    error: current ? state.error : null,
+    loading: current ? state.loading : variablesKey !== 'null',
+  };
+}
+
+/** Preserve a request's idempotency key through transport retries until success. */
+export function useConditionAction() {
+  const request = useConditionApi();
+  const pending = useRef(new Map<string, { key: string; input: Record<string, unknown> }>());
+  const [hasPendingAttempt, setHasPendingAttempt] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [revision, setRevision] = useState(0);
+  const run = async <T>(
+    document: DocumentNode,
+    input: Record<string, unknown>,
+    success: string
+  ) => {
+    // A refreshed server revision must not turn an uncertain committed attempt into a new mutation.
+    const intent = Object.fromEntries(
+      Object.entries(input).filter(([name]) => name !== 'expectedVersion')
+    );
+    const fingerprint = JSON.stringify({ operation: print(document), input: intent });
+    const attempt = pending.current.get(fingerprint) ?? { key: crypto.randomUUID(), input };
+    pending.current.set(fingerprint, attempt);
+    setBusy(true);
+    setError(null);
+    setNotice(null);
+    try {
+      const result = await request<T>(document, {
+        input: { ...attempt.input, idempotencyKey: attempt.key },
+      });
+      pending.current.delete(fingerprint);
+      setHasPendingAttempt(pending.current.size > 0);
+      setRevision((value) => value + 1);
+      setNotice(success);
+      return result;
+    } catch (failure) {
+      setHasPendingAttempt(true);
+      setError(failure instanceof Error ? failure.message : 'Unable to save this record.');
+      return null;
+    } finally {
+      setBusy(false);
+    }
+  };
+  const resetFeedback = () => {
+    setError(null);
+    setNotice(null);
+  };
+  const discardAttempt = () => {
+    pending.current.clear();
+    setHasPendingAttempt(false);
+    resetFeedback();
+  };
+  return { run, busy, error, notice, revision, resetFeedback, hasPendingAttempt, discardAttempt };
+}

package/src/movethewheels/hooks/useContainerLifecycle.ts

@@ -0,0 +1,291 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { print } from 'graphql';
+import {
+  ContainerRegistryDocument,
+  ContainerCyclesDocument,
+  ContainerEventsDocument,
+  RegisterContainerDocument,
+  OpenContainerCycleDocument,
+  RecordContainerEventDocument,
+  CloseContainerCycleDocument,
+  type ContainerEquipmentFieldsFragment,
+  type ContainerCycleFieldsFragment,
+  type ContainerEventFieldsFragment,
+  type ContainerRegistryQuery,
+  type ContainerCyclesQuery,
+  type ContainerEventsQuery,
+  type RegisterContainerMutation,
+  type OpenContainerCycleMutation,
+  type RecordContainerEventMutation,
+  type CloseContainerCycleMutation,
+  type RegisterMtwContainerInput,
+  type OpenMtwContainerCycleInput,
+  type RecordMtwContainerEventInput,
+} from '../../generated/container-operations';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+
+export const EQUIPMENT_TYPES = [
+  'DRY_20',
+  'DRY_40',
+  'HIGH_CUBE_40',
+  'REEFER_20',
+  'REEFER_40',
+  'OPEN_TOP',
+  'FLAT_RACK',
+  'TANK',
+  'OTHER',
+] as const;
+export const CONTAINER_EVENT_TYPES = [
+  'GATE_OUT',
+  'LOADED',
+  'DISCHARGED',
+  'AVAILABLE_FOR_PICKUP',
+  'GATE_IN',
+  'DELIVERED',
+  'EMPTY_READY',
+  'RETURN_REQUESTED',
+  'EMPTY_RETURNED',
+  'RETURN_ACCEPTED',
+  'POSITION_UPDATE',
+] as const;
+export type EquipmentType = (typeof EQUIPMENT_TYPES)[number];
+export type ContainerEventType = (typeof CONTAINER_EVENT_TYPES)[number];
+export type ContainerEventKind = 'ACTUAL' | 'PLANNED' | 'ESTIMATED';
+
+export type ContainerRecord = ContainerEquipmentFieldsFragment;
+export type ContainerCycle = ContainerCycleFieldsFragment;
+export type ContainerEvent = ContainerEventFieldsFragment;
+
+const PAGE_SIZE = 25;
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : 'The operation could not be completed.';
+}
+
+/** Source-labelled physical equipment; cargo shipment completion does not close a cycle. */
+export function useContainerLifecycle() {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const options = useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+  const [containers, setContainers] = useState<ContainerRecord[]>([]);
+  const [cycles, setCycles] = useState<ContainerCycle[]>([]);
+  const [events, setEvents] = useState<ContainerEvent[]>([]);
+  const [hasMore, setHasMore] = useState(false);
+  const [hasMoreCycles, setHasMoreCycles] = useState(false);
+  const [hasMoreEvents, setHasMoreEvents] = useState(false);
+  const [containerId, setContainerId] = useState('');
+  const [cycleId, setCycleId] = useState('');
+  const [page, setPage] = useState(0);
+  const [cyclePage, setCyclePage] = useState(0);
+  const [eventPage, setEventPage] = useState(0);
+  const [revision, setRevision] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [cyclesLoading, setCyclesLoading] = useState(false);
+  const [eventsLoading, setEventsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [cycleError, setCycleError] = useState<string | null>(null);
+  const [eventError, setEventError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    setContainers([]);
+    setHasMore(false);
+    void executeGraphQL<ContainerRegistryQuery>(options, print(ContainerRegistryDocument), {
+      pagination: { limit: PAGE_SIZE, offset: page * PAGE_SIZE },
+    })
+      .then((data) => {
+        if (!cancelled) {
+          setContainers(data.mtwContainerPage.items);
+          setHasMore(data.mtwContainerPage.hasMore);
+        }
+      })
+      .catch((failure: unknown) => {
+        if (!cancelled) setError(describeError(failure));
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [options, page, revision]);
+
+  // Clear selections whenever the security/workspace context changes.
+  useEffect(() => {
+    setContainerId('');
+    setCycleId('');
+    setPage(0);
+    setCyclePage(0);
+    setEventPage(0);
+  }, [options]);
+
+  useEffect(() => {
+    let cancelled = false;
+    setCycles([]);
+    setHasMoreCycles(false);
+    setCycleError(null);
+    if (!containerId) {
+      setCyclesLoading(false);
+      return;
+    }
+    setCyclesLoading(true);
+    void executeGraphQL<ContainerCyclesQuery>(options, print(ContainerCyclesDocument), {
+      containerId,
+      pagination: { limit: PAGE_SIZE, offset: cyclePage * PAGE_SIZE },
+    })
+      .then((data) => {
+        if (!cancelled) {
+          setCycles(data.mtwContainerCyclePage.items);
+          setHasMoreCycles(data.mtwContainerCyclePage.hasMore);
+        }
+      })
+      .catch((failure: unknown) => {
+        if (!cancelled) setCycleError(describeError(failure));
+      })
+      .finally(() => {
+        if (!cancelled) setCyclesLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [options, containerId, cyclePage, revision]);
+
+  useEffect(() => {
+    let cancelled = false;
+    setEvents([]);
+    setHasMoreEvents(false);
+    setEventError(null);
+    if (!cycleId) {
+      setEventsLoading(false);
+      return;
+    }
+    setEventsLoading(true);
+    void executeGraphQL<ContainerEventsQuery>(options, print(ContainerEventsDocument), {
+      cycleId,
+      pagination: { limit: PAGE_SIZE, offset: eventPage * PAGE_SIZE },
+    })
+      .then((data) => {
+        if (!cancelled) {
+          setEvents(data.mtwContainerEventPage.items);
+          setHasMoreEvents(data.mtwContainerEventPage.hasMore);
+        }
+      })
+      .catch((failure: unknown) => {
+        if (!cancelled) setEventError(describeError(failure));
+      })
+      .finally(() => {
+        if (!cancelled) setEventsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [options, cycleId, eventPage, revision]);
+
+  const refresh = useCallback(() => setRevision((value) => value + 1), []);
+  // Keep the same key after an uncertain response so a manual retry replays the
+  // committed operation. Changed payloads and confirmed successes start new work.
+  const pendingMutations = useRef(new Map<string, { fingerprint: string; key: string }>());
+  const retryKey = (operation: string, payload: unknown) => {
+    const fingerprint = JSON.stringify(payload);
+    const pending = pendingMutations.current.get(operation);
+    if (pending?.fingerprint === fingerprint) return pending.key;
+    const key = crypto.randomUUID();
+    pendingMutations.current.set(operation, { fingerprint, key });
+    return key;
+  };
+  const selectContainer = (id: string) => {
+    setContainerId(id);
+    setCycleId('');
+    setCyclePage(0);
+    setEventPage(0);
+  };
+  const selectCycle = (id: string) => {
+    setCycleId(id);
+    setEventPage(0);
+  };
+  const register = async (input: Omit<RegisterMtwContainerInput, 'idempotencyKey'>) => {
+    const data = await executeGraphQL<RegisterContainerMutation>(
+      options,
+      print(RegisterContainerDocument),
+      { input: { ...input, idempotencyKey: retryKey('register', input) } }
+    );
+    pendingMutations.current.delete('register');
+    setPage(0);
+    refresh();
+    selectContainer(data.registerMtwContainer.id);
+  };
+  const openCycle = async (input: Omit<OpenMtwContainerCycleInput, 'idempotencyKey'>) => {
+    const data = await executeGraphQL<OpenContainerCycleMutation>(
+      options,
+      print(OpenContainerCycleDocument),
+      { input: { ...input, idempotencyKey: retryKey('open', input) } }
+    );
+    pendingMutations.current.delete('open');
+    setCyclePage(0);
+    refresh();
+    selectCycle(data.openMtwContainerCycle.id);
+  };
+  const recordEvent = async (input: Omit<RecordMtwContainerEventInput, 'idempotencyKey'>) => {
+    await executeGraphQL<RecordContainerEventMutation>(
+      options,
+      print(RecordContainerEventDocument),
+      { input: { ...input, idempotencyKey: retryKey('record', input) } }
+    );
+    pendingMutations.current.delete('record');
+    setEventPage(0);
+    refresh();
+  };
+  const closeCycle = async (cycle: ContainerCycle) => {
+    const input = { cycleId: cycle.id, expectedVersion: cycle.version };
+    await executeGraphQL<CloseContainerCycleMutation>(options, print(CloseContainerCycleDocument), {
+      input: {
+        ...input,
+        idempotencyKey: retryKey('close', input),
+      },
+    });
+    pendingMutations.current.delete('close');
+    refresh();
+  };
+  return {
+    containers,
+    cycles,
+    events,
+    containerId,
+    cycleId,
+    loading,
+    cyclesLoading,
+    eventsLoading,
+    error,
+    cycleError,
+    eventError,
+    page,
+    setPage,
+    cyclePage,
+    setCyclePage,
+    eventPage,
+    setEventPage,
+    hasMore,
+    hasMoreCycles,
+    hasMoreEvents,
+    selectContainer,
+    selectCycle,
+    refresh,
+    register,
+    openCycle,
+    recordEvent,
+    closeCycle,
+  };
+}

package/src/movethewheels/hooks/useEmptyReuseAction.ts

@@ -0,0 +1,72 @@
+import { useRef, useState } from 'react';
+import { print, type DocumentNode } from 'graphql';
+import { useConditionApi } from './useContainerCondition';
+import { reuseAttempt } from '../utils/reuseAttempt';
+
+/** An uncertain retry keeps its original body and key, even after a read refresh. */
+export function useEmptyReuseAction() {
+  const request = useConditionApi();
+  const pending = useRef<{
+    fingerprint: string;
+    input: Record<string, unknown>;
+    key: string;
+    document: DocumentNode;
+    success: string;
+  } | null>(null);
+  const running = useRef(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [uncertain, setUncertain] = useState(false);
+  const [revision, setRevision] = useState(0);
+  const run = async <T>(
+    document: DocumentNode,
+    input: Record<string, unknown>,
+    success: string
+  ) => {
+    if (running.current) return null;
+    const selected = reuseAttempt(pending.current, print(document), input, () =>
+      crypto.randomUUID()
+    );
+    const attempt =
+      pending.current === selected ? pending.current : { ...selected, document, success };
+    pending.current = attempt;
+    running.current = true;
+    setBusy(true);
+    setError(null);
+    setNotice(null);
+    try {
+      const result = await request<T>(document, {
+        input: { ...attempt.input, idempotencyKey: attempt.key },
+      });
+      pending.current = null;
+      setUncertain(false);
+      setRevision((value) => value + 1);
+      setNotice(success);
+      return result;
+    } catch (failure) {
+      setUncertain(true);
+      setError(
+        failure instanceof Error
+          ? failure.message
+          : 'Unable to save. Refresh history before retrying.'
+      );
+      return null;
+    } finally {
+      running.current = false;
+      setBusy(false);
+    }
+  };
+  const retryOriginal = async () => {
+    const attempt = pending.current;
+    if (attempt) await run(attempt.document, attempt.input, attempt.success);
+  };
+  const refresh = () => setRevision((value) => value + 1);
+  const discardAttempt = () => {
+    pending.current = null;
+    setUncertain(false);
+    setError(null);
+    setNotice(null);
+  };
+  return { run, retryOriginal, busy, error, notice, uncertain, revision, refresh, discardAttempt };
+}