@burdenoff/microfe-movethewheels 2026.930.5 → 2026.1010.2

package/src/movethewheels/hooks/useFreightRecoveryAction.ts

@@ -0,0 +1,201 @@
+import { useRef, useState } from 'react';
+import { print, type DocumentNode } from 'graphql';
+import { useConditionApi } from './useContainerCondition';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { matchesFreightAcknowledgement } from '../utils/freightAcknowledgement';
+import {
+  SaveFreightCostsDocument,
+  type SaveFreightCostsMutation,
+} from '../../generated/freight-cost-operations';
+import {
+  reuseRecoveryScope,
+  reuseRecoveryContextKey,
+  sameReuseRecoveryScope,
+  type ReuseRecovery,
+} from '../utils/reuseRecovery';
+import {
+  decodeFreightRecovery,
+  encodeFreightRecovery,
+  FREIGHT_RECOVERY_STORAGE,
+} from '../utils/freightRecovery';
+const documents = [SaveFreightCostsDocument];
+function loadRecovery(): { attempt: ReuseRecovery | null; blocked: boolean } {
+  try {
+    const raw = sessionStorage.getItem(FREIGHT_RECOVERY_STORAGE);
+    const attempt = decodeFreightRecovery(raw);
+    return { attempt, blocked: raw !== null && attempt === null };
+  } catch {
+    return { attempt: null, blocked: true };
+  }
+}
+/** F06 retains one unresolved request across entity/context remounts; it never sends automatically. */
+export function useFreightRecoveryAction() {
+  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(FREIGHT_RECOVERY_STORAGE, encodeFreightRecovery(attempt));
+    else {
+      const saved = decodeFreightRecovery(sessionStorage.getItem(FREIGHT_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(FREIGHT_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<SaveFreightCostsMutation>(document, {
+        input: { ...attempt.input, idempotencyKey: attempt.key },
+      });
+      if (!matchesFreightAcknowledgement(result, attempt.input))
+        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 freight operation.');
+      return null;
+    }
+    try {
+      if (sessionStorage.getItem(FREIGHT_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,
+    // A read target never changes the retained intent or grants access across contexts.
+    originalHistoryTarget:
+      pending &&
+      sameReuseRecoveryScope(pending.scope, scope) &&
+      typeof pending.input.shipmentId === 'string' &&
+      pending.input.shipmentId.trim().length > 0 &&
+      pending.input.shipmentId.length <= 200 &&
+      typeof pending.input.estimateReference === 'string' &&
+      pending.input.estimateReference.trim().length > 0 &&
+      pending.input.estimateReference.length <= 200
+        ? {
+            shipmentId: pending.input.shipmentId,
+            estimateReference: pending.input.estimateReference,
+          }
+        : null,
+    contextKey,
+  };
+}

package/src/movethewheels/hooks/useMultiModalShipments.ts

@@ -332,7 +332,8 @@ export function useMultiModalShipments(
             destination: input.destination,
             legs: input.legs.map(toApiLeg),
           },
-        }
+        },
+        'SINGLE_ATTEMPT'
       );
       const created = mapShipment(data.planMultiModalShipment);
       setShipments((previous) => [created, ...previous]);

package/src/movethewheels/hooks/useProcedureAction.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 {
+  PublishProcedureDocument,
+  StartProcedureDocument,
+  RecordProcedureStepDocument,
+  RecordProcedureDeviationDocument,
+  RevokeProcedureDeviationDocument,
+} from '../../generated/logistics-procedure-operations';
+import { procedureAcknowledgement } from '../utils/procedureInput';
+import {
+  reuseRecoveryScope,
+  reuseRecoveryContextKey,
+  sameReuseRecoveryScope,
+  type ReuseRecovery,
+} from '../utils/reuseRecovery';
+import {
+  decodeProcedureRecovery,
+  encodeProcedureRecovery,
+  PROCEDURE_RECOVERY_STORAGE,
+} from '../utils/procedureRecovery';
+const documents = [
+  PublishProcedureDocument,
+  StartProcedureDocument,
+  RecordProcedureStepDocument,
+  RecordProcedureDeviationDocument,
+  RevokeProcedureDeviationDocument,
+];
+function loadRecovery(): { attempt: ReuseRecovery | null; blocked: boolean } {
+  try {
+    const raw = sessionStorage.getItem(PROCEDURE_RECOVERY_STORAGE);
+    const attempt = decodeProcedureRecovery(raw);
+    return { attempt, blocked: raw !== null && attempt === null };
+  } catch {
+    return { attempt: null, blocked: true };
+  }
+}
+/** F05 retains one unresolved request across entity/context remounts; it never sends automatically. */
+export function useProcedureAction() {
+  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(PROCEDURE_RECOVERY_STORAGE, encodeProcedureRecovery(attempt));
+    else {
+      const saved = decodeProcedureRecovery(sessionStorage.getItem(PROCEDURE_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(PROCEDURE_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 (!procedureAcknowledgement(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 procedure operation.');
+      return null;
+    }
+    try {
+      if (sessionStorage.getItem(PROCEDURE_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,
+    contextKey,
+  };
+}

package/src/movethewheels/hooks/useProcedureSelection.ts

@@ -0,0 +1,75 @@
+import { useState } from 'react';
+import {
+  ProcedureContainersDocument,
+  ProcedureCyclesDocument,
+  ProcedureProposalsDocument,
+  type ProcedureContainersQuery,
+  type ProcedureCyclesQuery,
+  type ProcedureProposalsQuery,
+} from '../../generated/logistics-procedure-operations';
+import { useConditionQuery } from './useContainerCondition';
+export function useProcedureSelection(revision: number) {
+  const [containerId, setContainer] = useState(''),
+    [cycleId, setCycle] = useState(''),
+    [proposalId, setProposal] = useState('');
+  const [containerOffset, setContainerOffset] = useState(0),
+    [cycleOffset, setCycleOffset] = useState(0),
+    [proposalOffset, setProposalOffset] = useState(0);
+  const containers = useConditionQuery<ProcedureContainersQuery>(
+    ProcedureContainersDocument,
+    { pagination: { limit: 25, offset: containerOffset } },
+    revision
+  );
+  const cycles = useConditionQuery<ProcedureCyclesQuery>(
+    ProcedureCyclesDocument,
+    containerId ? { containerId, pagination: { limit: 25, offset: cycleOffset } } : null,
+    revision
+  );
+  const proposals = useConditionQuery<ProcedureProposalsQuery>(
+    ProcedureProposalsDocument,
+    cycleId ? { cycleId, pagination: { limit: 25, offset: proposalOffset } } : null,
+    revision
+  );
+  return {
+    containerId,
+    cycleId,
+    proposalId,
+    containerOffset,
+    cycleOffset,
+    proposalOffset,
+    containers,
+    cycles,
+    proposals,
+    cycle: cycles.data?.mtwContainerCyclePage.items.find((row) => row.id === cycleId) ?? null,
+    proposal:
+      proposals.data?.mtwReuseProposalPage.items.find((row) => row.id === proposalId) ?? null,
+    selectContainer: (value: string) => {
+      setContainer(value);
+      setCycle('');
+      setProposal('');
+      setCycleOffset(0);
+      setProposalOffset(0);
+    },
+    selectCycle: (value: string) => {
+      setCycle(value);
+      setProposal('');
+      setProposalOffset(0);
+    },
+    selectProposal: setProposal,
+    pageContainers: (offset: number) => {
+      setContainerOffset(offset);
+      setContainer('');
+      setCycle('');
+      setProposal('');
+    },
+    pageCycles: (offset: number) => {
+      setCycleOffset(offset);
+      setCycle('');
+      setProposal('');
+    },
+    pageProposals: (offset: number) => {
+      setProposalOffset(offset);
+      setProposal('');
+    },
+  };
+}

package/src/movethewheels/hooks/useReuseRecoveryAction.ts

@@ -0,0 +1,192 @@
+import { useRef, useState } from 'react';
+import { print, type DocumentNode } from 'graphql';
+import { useConditionApi } from './useContainerCondition';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import {
+  RecordReturnInstructionDocument,
+  RecordReuseProposalDocument,
+  RecordReuseApprovalDocument,
+  AcceptReuseReservationDocument,
+  TerminateReuseReservationDocument,
+} from '../../generated/empty-reuse-operations';
+import {
+  decodeReuseRecovery,
+  encodeReuseRecovery,
+  REUSE_RECOVERY_STORAGE,
+  reuseRecoveryScope,
+  reuseRecoveryContextKey,
+  sameReuseRecoveryScope,
+  type ReuseRecovery,
+} from '../utils/reuseRecovery';
+const documents = [
+  RecordReturnInstructionDocument,
+  RecordReuseProposalDocument,
+  RecordReuseApprovalDocument,
+  AcceptReuseReservationDocument,
+  TerminateReuseReservationDocument,
+];
+function loadRecovery(): { attempt: ReuseRecovery | null; blocked: boolean } {
+  try {
+    const raw = sessionStorage.getItem(REUSE_RECOVERY_STORAGE);
+    const attempt = decodeReuseRecovery(raw, documents);
+    return { attempt, blocked: raw !== null && attempt === null };
+  } catch {
+    return { attempt: null, blocked: true };
+  }
+}
+/** F02 retains one unresolved request across entity/context remounts; it never sends automatically. */
+export function useReuseRecoveryAction() {
+  const request = useConditionApi();
+  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(REUSE_RECOVERY_STORAGE, encodeReuseRecovery(attempt));
+    else {
+      const saved = decodeReuseRecovery(sessionStorage.getItem(REUSE_RECOVERY_STORAGE), documents);
+      // 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(REUSE_RECOVERY_STORAGE);
+    }
+    pendingRef.current = attempt;
+    setPending(attempt);
+    setBlocked(false);
+  };
+  const send = async <T>(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<T>(document, {
+        input: { ...attempt.input, idempotencyKey: attempt.key },
+      });
+      // 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 <T>(
+    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 reuse operation.');
+      return null;
+    }
+    try {
+      if (sessionStorage.getItem(REUSE_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<T>(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,
+    contextKey,
+  };
+}