@burdenoff/microfe-movethewheels 2026.930.5 → 2026.1010.1

package/src/movethewheels/utils/freightDraft.ts

@@ -0,0 +1,170 @@
+import type {
+  MtwFreightFactsInput,
+  MtwFreightLineInput,
+  MtwFreightFxInput,
+  SaveMtwFreightEstimateInput,
+} from '../../generated/freight-cost-operations';
+export const freightCategories = [
+  'BASE_FREIGHT',
+  'FUEL',
+  'PRE_CARRIAGE',
+  'ON_CARRIAGE',
+  'ORIGIN_HANDLING',
+  'DESTINATION_HANDLING',
+  'INSURANCE',
+  'ACCESSORIAL',
+  'TAX_ESTIMATE',
+  'DUTY_ESTIMATE',
+  'BROKER',
+  'FREE_TIME_EXPOSURE',
+  'OTHER',
+] as const;
+export const freightLabel = (value: string): string =>
+  value
+    .toLowerCase()
+    .replaceAll('_', ' ')
+    .replace(/^./, (c) => c.toUpperCase());
+export const freightNullable = (value: string): string | null => value.trim() || null;
+/** Money never passes through Number; sourced fixed amounts must fit the declared scale exactly. */
+export function fixedFreightMinor(value: string, digits: number): string | null {
+  if (!value.trim()) return null;
+  if (
+    !/^(0|[1-9][0-9]{0,19})(\.[0-9]+)?$/.test(value) ||
+    !Number.isInteger(digits) ||
+    digits < 0 ||
+    digits > 4
+  )
+    throw new Error('Use a nonnegative decimal amount in the stated currency convention.');
+  const [whole, fraction = ''] = value.split('.');
+  if (fraction.length > digits)
+    throw new Error(
+      'The sourced amount has more decimal places than the recorded currency convention.'
+    );
+  return (
+    BigInt(whole) * 10n ** BigInt(digits) +
+    BigInt(fraction.padEnd(digits, '0') || '0')
+  ).toString();
+}
+/** Match supported decimal zero spellings without rounding or accepting invalid quantities. */
+export function isFreightDecimalZero(value: string | null | undefined): boolean {
+  return (
+    typeof value === 'string' &&
+    /^(0|[1-9][0-9]{0,19})(\.[0-9]{1,18})?$/.test(value) &&
+    BigInt(value.replace('.', '')) === 0n
+  );
+}
+export function freightMoney(minor: string | null | undefined, digits: number): string {
+  if (minor === null || minor === undefined) return 'Unknown';
+  const value = BigInt(minor)
+    .toString()
+    .padStart(digits + 1, '0');
+  return digits ? `${value.slice(0, -digits)}.${value.slice(-digits)}` : value;
+}
+export function freightInstant(value: string): string {
+  const date = new Date(value);
+  if (!value || !Number.isFinite(date.getTime())) throw new Error('Choose a valid date and time.');
+  const result = date.toISOString();
+  if (!/^[0-9]{4}-/.test(result)) throw new Error('Use a four-digit year.');
+  return result;
+}
+export function freightLocalTime(value: string): string {
+  const date = new Date(value);
+  return new Date(date.getTime() - date.getTimezoneOffset() * 60000).toISOString().slice(0, 19);
+}
+export function newFreightLine(): MtwFreightLineInput {
+  return {
+    id: crypto.randomUUID(),
+    category: 'BASE_FREIGHT',
+    description: 'Base freight',
+    payerReference: null,
+    payerLabel: null,
+    disposition: 'UNKNOWN',
+    inclusionParentLineId: null,
+    currency: { code: 'USD', minorUnitDigits: 2 },
+    amountBasis: 'UNKNOWN',
+    quantity: null,
+    unit: null,
+    unitRateMajor: null,
+    amountMinor: null,
+    zeroReason: null,
+    sourceReference: null,
+    sourceRevision: null,
+  };
+}
+export function newFreightFacts(): MtwFreightFactsInput {
+  return {
+    kind: 'ESTIMATE',
+    title: 'Freight cost estimate',
+    commercialScope: '',
+    sourceReference: '',
+    sourceRevision: '',
+    pricingAt: new Date().toISOString(),
+    quotedAt: null,
+    validFrom: null,
+    validUntil: null,
+    reportingCurrency: null,
+    rounding: 'HALF_UP_LINE',
+    lines: [newFreightLine()],
+    requirements: freightCategories.map((category) => ({
+      category,
+      status: 'UNKNOWN',
+      reason: null,
+      sourceReference: null,
+      sourceRevision: null,
+    })),
+    fx: [],
+  };
+}
+export function newFreightFx(): MtwFreightFxInput {
+  const now = new Date().toISOString();
+  return {
+    fromCurrency: { code: 'USD', minorUnitDigits: 2 },
+    toCurrency: { code: 'EUR', minorUnitDigits: 2 },
+    rate: '',
+    observedAt: now,
+    effectiveFrom: now,
+    effectiveUntil: now,
+    sourceReference: '',
+    sourceRevision: '',
+  };
+}
+export interface FreightDraftPin {
+  shipmentId: string;
+  shipmentUpdatedAt: string;
+  estimateReference: string;
+  previousId: string | null;
+  version: number;
+}
+export function freightPinMatches(
+  pin: FreightDraftPin,
+  shipment: { id: string; updatedAt: string } | null | undefined,
+  latest: { id: string; version: number } | null
+): boolean {
+  return (
+    shipment?.id === pin.shipmentId &&
+    shipment.updatedAt === pin.shipmentUpdatedAt &&
+    (latest?.id ?? null) === pin.previousId &&
+    (latest?.version ?? 0) === pin.version
+  );
+}
+export function freightSaveInput(
+  pin: FreightDraftPin,
+  shipment: { id: string; updatedAt: string } | null | undefined,
+  latest: { id: string; version: number } | null,
+  facts: MtwFreightFactsInput,
+  evidence: SaveMtwFreightEstimateInput['evidence']
+): Omit<SaveMtwFreightEstimateInput, 'idempotencyKey'> {
+  if (!freightPinMatches(pin, shipment, latest))
+    throw new Error(
+      'The shipment or cost history changed. Refresh and review before starting a new draft.'
+    );
+  return {
+    shipmentId: pin.shipmentId,
+    estimateReference: pin.estimateReference,
+    expectedShipmentUpdatedAt: pin.shipmentUpdatedAt,
+    expectedPreviousVersionId: pin.previousId,
+    expectedVersion: pin.version,
+    facts: structuredClone(facts),
+    evidence: structuredClone(evidence),
+  };
+}

package/src/movethewheels/utils/freightRecovery.ts

@@ -0,0 +1,79 @@
+import { print } from 'graphql';
+import { SaveFreightCostsDocument } from '../../generated/freight-cost-operations';
+import type { ReuseRecovery } from './reuseRecovery';
+export const FREIGHT_RECOVERY_STORAGE = 'movethewheels.freight.unresolved.v1';
+export function decodeFreightRecovery(raw: string | null): ReuseRecovery | null {
+  if (!raw || new TextEncoder().encode(raw).byteLength > 200000) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (
+      typeof value !== 'object' ||
+      value === null ||
+      !('version' in value) ||
+      value.version !== 1 ||
+      !('scope' in value) ||
+      !('input' in value) ||
+      !('operation' in value) ||
+      value.operation !== print(SaveFreightCostsDocument) ||
+      !('key' in value) ||
+      typeof value.key !== 'string' ||
+      !value.key ||
+      value.key.length > 200 ||
+      !('success' in value) ||
+      typeof value.success !== 'string' ||
+      value.success.length > 500
+    )
+      return null;
+    if (
+      typeof value.input !== 'object' ||
+      value.input === null ||
+      Array.isArray(value.input) ||
+      typeof value.scope !== 'object' ||
+      value.scope === null
+    )
+      return null;
+    const scope = value.scope;
+    if (
+      !('actorId' in scope) ||
+      typeof scope.actorId !== 'string' ||
+      !scope.actorId ||
+      !('workspaceId' in scope) ||
+      typeof scope.workspaceId !== 'string' ||
+      !scope.workspaceId ||
+      !('tenantId' in scope) ||
+      typeof scope.tenantId !== 'string' ||
+      !('organizationId' in scope) ||
+      typeof scope.organizationId !== 'string' ||
+      !scope.organizationId ||
+      !('gateway' in scope) ||
+      typeof scope.gateway !== 'string' ||
+      !('projectId' in scope) ||
+      (scope.projectId !== null && typeof scope.projectId !== 'string')
+    )
+      return null;
+    return {
+      version: 1,
+      scope: {
+        actorId: scope.actorId,
+        workspaceId: scope.workspaceId,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        gateway: scope.gateway,
+        projectId: scope.projectId,
+      },
+      operation: value.operation,
+      // The owning document is exact and input is an object; field authority remains backend-validated.
+      input: structuredClone(value.input) as Record<string, unknown>,
+      key: value.key,
+      success: value.success,
+    };
+  } catch {
+    return null;
+  }
+}
+export function encodeFreightRecovery(attempt: ReuseRecovery): string {
+  const raw = JSON.stringify(attempt);
+  if (!decodeFreightRecovery(raw))
+    throw new Error('Cannot safely retain this freight request. Nothing was sent.');
+  return raw;
+}

package/src/movethewheels/utils/graphqlClient.ts

@@ -1,3 +1,5 @@
+export type GraphQLAttemptPolicy = 'RETRY_TRANSIENT' | 'SINGLE_ATTEMPT';
+
 interface GraphQLRequestOptions {
   apiGatewayUrl?: string;
   authToken?: string;
@@ -106,7 +108,8 @@ function releaseSlot(): void {
 export async function executeGraphQL<TData>(
   options: GraphQLRequestOptions,
   query: string,
-  variables?: Record<string, unknown>
+  variables?: Record<string, unknown>,
+  attemptPolicy: GraphQLAttemptPolicy = 'RETRY_TRANSIENT'
 ): Promise<TData> {
   const url = resolveGraphqlUrl(options.apiGatewayUrl);
   const headers: Record<string, string> = {
@@ -126,7 +129,12 @@ export async function executeGraphQL<TData>(
   // and always release the slot when this call settles (success or failure).
   await acquireSlot();
   try {
-    return await runWithRetries<TData>(url, headers, body);
+    return await runWithRetries<TData>(
+      url,
+      headers,
+      body,
+      attemptPolicy === 'SINGLE_ATTEMPT' ? 0 : MAX_RETRIES
+    );
   } finally {
     releaseSlot();
   }
@@ -148,12 +156,13 @@ async function readGraphqlErrorMessage(response: Response): Promise<string | nul
 async function runWithRetries<TData>(
   url: string,
   headers: Record<string, string>,
-  body: string
+  body: string,
+  retries: number
 ): Promise<TData> {
   let lastError: Error = new Error('GraphQL request failed');
 
-  for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
-    const canRetry = attempt < MAX_RETRIES;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const canRetry = attempt < retries;
     // Exponential backoff with jitter before each retry (not the first attempt).
     if (attempt > 0)
       await sleep(Math.min(250 * 2 ** (attempt - 1), 2000) + Math.floor(Math.random() * 150));

package/src/movethewheels/utils/pendingPickDraft.ts

@@ -0,0 +1,61 @@
+import type {
+  CreateMtwPickTaskIntentInput,
+  MtwPickIntentLinePinInput,
+  PickLineFragment,
+  PickPreparationQuery,
+} from '../../generated/pending-pick-operations';
+
+type Context = PickPreparationQuery['mtwPickPreparation'];
+export type PendingPickInput = Omit<CreateMtwPickTaskIntentInput, 'idempotencyKey'>;
+function pin(line: PickLineFragment): MtwPickIntentLinePinInput {
+  return {
+    inventoryItemId: line.inventoryItemId,
+    expectedCargoItemId: line.cargoItemId,
+    expectedWarehouseId: line.warehouseId,
+    expectedLocationId: line.locationId,
+    expectedInventoryUpdatedAt: line.inventoryUpdatedAt,
+    expectedCargoUpdatedAt: line.cargoUpdatedAt,
+    expectedWarehouseUpdatedAt: line.warehouseUpdatedAt,
+    expectedLocationUpdatedAt: line.locationUpdatedAt,
+    expectedCompositionEpoch: line.compositionEpoch,
+    expectedRecordedAssessmentId: line.recordedProfile?.id ?? null,
+    expectedApplicableAssessmentId: line.applicableProfile?.id ?? null,
+    expectedObservationSequence: line.observationSequence,
+  };
+}
+export function pendingContextSignature(context: Context): string {
+  return JSON.stringify(
+    ['source', 'destination'].map((side) => {
+      const line = side === 'source' ? context.source : context.destination;
+      return { pin: pin(line), issues: line.unresolvedObservationIds, gaps: line.reviewGaps };
+    })
+  );
+}
+export function pendingPickInput(
+  context: Context,
+  count: string,
+  reason: string
+): PendingPickInput {
+  const requestedQuantity = Number(count);
+  if (
+    !/^[1-9]\d*$/.test(count) ||
+    !Number.isSafeInteger(requestedQuantity) ||
+    requestedQuantity > 2147483647
+  )
+    throw new Error('Enter a positive whole count up to 2147483647.');
+  const note = reason.trim();
+  if (!note || note.length > 1000) throw new Error('Enter a reason up to 1000 characters.');
+  const source = pin(context.source),
+    destination = pin(context.destination);
+  if (
+    source.inventoryItemId === destination.inventoryItemId ||
+    source.expectedLocationId === destination.expectedLocationId ||
+    source.expectedWarehouseId !== destination.expectedWarehouseId ||
+    source.expectedCargoItemId !== destination.expectedCargoItemId
+  )
+    throw new Error('Choose two distinct bins for the same cargo and warehouse.');
+  return { source, destination, requestedQuantity, note };
+}
+export function pendingPickMatches(draftSignature: string, current: Context): boolean {
+  return draftSignature === pendingContextSignature(current);
+}

package/src/movethewheels/utils/procedureInput.ts

@@ -0,0 +1,98 @@
+import type {
+  MtwProcedureScopeInput,
+  MtwProcedureStep,
+} from '../../generated/logistics-procedure-operations';
+export const procedureSteps: readonly MtwProcedureStep[] = [
+  'RETURN_INSTRUCTION_REVIEW',
+  'CONDITION_HOLDS_REVIEW',
+  'BOOKING_ROAD_RETURN_REVIEW',
+];
+export const stepLabel: Record<MtwProcedureStep, string> = {
+  RETURN_INSTRUCTION_REVIEW: 'Return instruction',
+  CONDITION_HOLDS_REVIEW: 'Condition and holds',
+  BOOKING_ROAD_RETURN_REVIEW: 'Booking, road access and retained return',
+};
+export function object(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function procedureAcknowledgement(
+  result: Record<string, unknown>,
+  input: Record<string, unknown>,
+  actorId?: string
+): boolean {
+  const field =
+    'templateReference' in input
+      ? 'publishMtwProcedureVersion'
+      : 'expectedCycleVersion' in input
+        ? 'startMtwProcedureExecution'
+        : input.stepDecisionId
+          ? input.kind
+            ? 'recordMtwProcedureDeviation'
+            : 'revokeMtwProcedureDeviation'
+          : 'recordMtwProcedureStep';
+  const row = result[field];
+  if (!object(row) || typeof row.id !== 'string' || !row.id) return false;
+  if ('expectedCycleVersion' in input)
+    return (
+      row.executorActorId === actorId &&
+      row.proposalId === input.proposalId &&
+      row.procedureVersionId === input.procedureVersionId &&
+      object(row.subject) &&
+      row.subject.cycleVersion === input.expectedCycleVersion &&
+      row.subject.proposalRevision === input.expectedProposalRevision
+    );
+  if (typeof input.expectedVersion !== 'number' || row.version !== input.expectedVersion + 1)
+    return false;
+  if ('templateReference' in input)
+    return (
+      row.templateReference === input.templateReference &&
+      row.previousVersionId === input.expectedPreviousId &&
+      row.kind === input.kind
+    );
+  return (
+    row.executionId === input.executionId &&
+    (input.stepDecisionId
+      ? row.stepDecisionId === input.stepDecisionId &&
+        row.previousDeviationId === input.expectedPreviousId
+      : row.step === input.step && row.previousDecisionId === input.expectedPreviousId) &&
+    row.kind === (input.kind ?? 'REVOKED')
+  );
+}
+/** Local input never supplies readiness, actor identity, execution or custody facts. */
+export function localProcedureInstant(value: string): string {
+  if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d(?::\d\d(?:\.\d{1,3})?)?$/.test(value))
+    throw new Error('Enter a complete local date and time.');
+  const date = new Date(value);
+  if (!Number.isFinite(date.valueOf())) throw new Error('Enter a valid date and time.');
+  const pad = (v: number) => String(v).padStart(2, '0');
+  const local = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
+  if (local !== value.slice(0, 16))
+    throw new Error('This local time is invalid or skipped by daylight saving.');
+  return date.toISOString();
+}
+export function scopeInput(
+  scope: Omit<MtwProcedureScopeInput, 'declaredJurisdictions'> & { declaredJurisdictions: string[] }
+): MtwProcedureScopeInput {
+  if (
+    scope.declaredJurisdictions.length < 1 ||
+    scope.declaredJurisdictions.length > 10 ||
+    new Set(scope.declaredJurisdictions).size !== scope.declaredJurisdictions.length
+  )
+    throw new Error('Enter one to ten distinct jurisdiction references.');
+  return {
+    handoffLocationReference: scope.handoffLocationReference,
+    equipmentType: scope.equipmentType,
+    cargoCategory: scope.cargoCategory,
+    equipmentOwnerReference: scope.equipmentOwnerReference,
+    declaredLaneReference: scope.declaredLaneReference,
+    declaredJurisdictions: [...scope.declaredJurisdictions],
+    sourceReference: scope.sourceReference,
+    sourceRevision: scope.sourceRevision,
+  };
+}
+export function chainMatches(
+  pin: { id: string; version: number } | null,
+  current: { id: string; version: number } | null
+): boolean {
+  return pin?.id === current?.id && pin?.version === current?.version;
+}

package/src/movethewheels/utils/procedureRecovery.ts

@@ -0,0 +1,92 @@
+import { print } from 'graphql';
+import {
+  PublishProcedureDocument,
+  StartProcedureDocument,
+  RecordProcedureStepDocument,
+  RecordProcedureDeviationDocument,
+  RevokeProcedureDeviationDocument,
+} from '../../generated/logistics-procedure-operations';
+import type { ReuseRecovery } from './reuseRecovery';
+export const PROCEDURE_RECOVERY_STORAGE = 'movethewheels.procedure.unresolved.v1';
+export function decodeProcedureRecovery(raw: string | null): ReuseRecovery | null {
+  if (!raw || new TextEncoder().encode(raw).byteLength > 200000) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (
+      typeof value !== 'object' ||
+      value === null ||
+      !('version' in value) ||
+      value.version !== 1 ||
+      !('scope' in value) ||
+      !('input' in value) ||
+      !('operation' in value) ||
+      typeof value.operation !== 'string' ||
+      ![
+        PublishProcedureDocument,
+        StartProcedureDocument,
+        RecordProcedureStepDocument,
+        RecordProcedureDeviationDocument,
+        RevokeProcedureDeviationDocument,
+      ].some((item) => print(item) === value.operation) ||
+      !('key' in value) ||
+      typeof value.key !== 'string' ||
+      !value.key ||
+      value.key.length > 200 ||
+      !('success' in value) ||
+      typeof value.success !== 'string' ||
+      value.success.length > 500
+    )
+      return null;
+    if (
+      typeof value.input !== 'object' ||
+      value.input === null ||
+      Array.isArray(value.input) ||
+      typeof value.scope !== 'object' ||
+      value.scope === null
+    )
+      return null;
+    const scope = value.scope;
+    if (
+      !('actorId' in scope) ||
+      typeof scope.actorId !== 'string' ||
+      !scope.actorId ||
+      !('workspaceId' in scope) ||
+      typeof scope.workspaceId !== 'string' ||
+      !scope.workspaceId ||
+      !('tenantId' in scope) ||
+      typeof scope.tenantId !== 'string' ||
+      !('organizationId' in scope) ||
+      typeof scope.organizationId !== 'string' ||
+      !scope.organizationId ||
+      !('gateway' in scope) ||
+      typeof scope.gateway !== 'string' ||
+      !('projectId' in scope) ||
+      (scope.projectId !== null && typeof scope.projectId !== 'string')
+    )
+      return null;
+    return {
+      version: 1,
+      scope: {
+        actorId: scope.actorId,
+        workspaceId: scope.workspaceId,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        gateway: scope.gateway,
+        projectId: scope.projectId,
+      },
+      operation: value.operation,
+      // The owning document is exact and input is an object; field authority remains backend-validated.
+      input: structuredClone(value.input) as Record<string, unknown>,
+      key: value.key,
+      success: value.success,
+    };
+  } catch {
+    return null;
+  }
+}
+export function encodeProcedureRecovery(attempt: ReuseRecovery): string {
+  const raw = JSON.stringify(attempt);
+  if (!decodeProcedureRecovery(raw))
+    throw new Error('Cannot safely retain this procedure request. Nothing was sent.');
+  return raw;
+}

package/src/movethewheels/utils/reuseAttempt.ts

@@ -0,0 +1,29 @@
+/** Stores one submitted intent. Reads may refresh versions without changing an uncertain retry. */
+export interface ReuseAttempt {
+  fingerprint: string;
+  input: Record<string, unknown>;
+  key: string;
+}
+export function reuseAttempt(
+  previous: ReuseAttempt | null,
+  operation: string,
+  input: Record<string, unknown>,
+  createKey: () => string
+): ReuseAttempt {
+  const intent = Object.fromEntries(
+    Object.entries(input).filter(
+      ([name]) =>
+        ![
+          'expectedVersion',
+          'expectedCycleVersion',
+          'expectedProposalRevision',
+          'expectedRouteUpdatedAt',
+          'expectedVehicleUpdatedAt',
+        ].includes(name)
+    )
+  );
+  const fingerprint = JSON.stringify({ operation, input: intent });
+  return previous?.fingerprint === fingerprint
+    ? previous
+    : { fingerprint, input: structuredClone(input), key: createKey() };
+}

package/src/movethewheels/utils/reuseForm.ts

@@ -0,0 +1,30 @@
+import type { MtwReuseSourceAttestationInput } from '../../generated/empty-reuse-operations';
+import type { SelectedEvidence } from '../components/ContainerEvidencePicker';
+import { freeTimeIso } from './freeTimeDate';
+export function reuseText(values: FormData, name: string) {
+  return String(values.get(name) ?? '').trim();
+}
+export function reuseInteger(values: FormData, name: string) {
+  const s = reuseText(values, name);
+  if (!/^\d+$/.test(s) || !Number.isSafeInteger(Number(s)) || Number(s) > 2147483647)
+    throw new Error(`${name}: enter a whole number between 0 and 2147483647.`);
+  return Number(s);
+}
+export function readReuseSource(
+  values: FormData,
+  name: string,
+  evidence: SelectedEvidence[]
+): MtwReuseSourceAttestationInput | undefined {
+  if (reuseText(values, `${name}.recorded`) !== 'yes') return undefined;
+  const ids = values.getAll(`${name}.evidence`).map((value) => String(value));
+  if (!ids.length || ids.some((id) => !evidence.some((item) => item.versionId === id)))
+    throw new Error(`Select current proposal evidence for ${name}.`);
+  return {
+    sourceReference: reuseText(values, `${name}.reference`),
+    sourceRevision: reuseText(values, `${name}.revision`),
+    observedAt: freeTimeIso(reuseText(values, `${name}.observed`)),
+    validFrom: freeTimeIso(reuseText(values, `${name}.from`)),
+    validUntil: freeTimeIso(reuseText(values, `${name}.until`)),
+    evidenceVersionIds: ids,
+  };
+}