@burdenoff/microfe-movethewheels 2026.1011.1 → 2026.1011.2

package/src/movethewheels/utils/shipmentStatusDraft.ts

@@ -0,0 +1,118 @@
+export interface ShipmentSourceDraft {
+  integrationId: string;
+  basisTrackingEventId: string;
+  maxSourceAgeSeconds: string;
+  maxFutureSkewSeconds: string;
+  reason: string;
+}
+
+export function statusDecisionReason(value: string): string {
+  const reason = value.trim();
+  if (!reason || reason.length > 1000) throw new Error('Enter a reason of 1–1000 characters.');
+  return reason;
+}
+
+function explicitSeconds(value: string, minimum: number, maximum: number, label: string): number {
+  if (!/^\d+$/.test(value.trim()))
+    throw new Error(`${label} must be an explicit whole number of seconds.`);
+  const result = Number(value.trim());
+  if (!Number.isSafeInteger(result) || result < minimum || result > maximum)
+    throw new Error(`${label} must be between ${minimum} and ${maximum} seconds.`);
+  return result;
+}
+
+export function shipmentSourceInput(draft: ShipmentSourceDraft, expectedStatusRevision: number) {
+  if (!draft.integrationId || !draft.basisTrackingEventId)
+    throw new Error('Choose one integration and one recorded basis event.');
+  return {
+    expectedStatusRevision,
+    integrationId: draft.integrationId,
+    basisTrackingEventId: draft.basisTrackingEventId,
+    maxSourceAgeSeconds: explicitSeconds(
+      draft.maxSourceAgeSeconds,
+      1,
+      2592000,
+      'Maximum source age'
+    ),
+    maxFutureSkewSeconds: explicitSeconds(
+      draft.maxFutureSkewSeconds,
+      0,
+      86400,
+      'Allowed future skew'
+    ),
+    reason: statusDecisionReason(draft.reason),
+  };
+}
+
+interface StatusAcknowledgement {
+  id: string;
+  status: string;
+  statusRevision: number;
+  statusAuthority: string;
+  statusAuthorityEpoch: number;
+  designatedIntegrationId?: string | null;
+  statusBasisEventId?: string | null;
+  statusBasisSourceTime?: string | null;
+  maxSourceAgeSeconds?: number | null;
+  maxFutureSkewSeconds?: number | null;
+}
+
+export function sourceStatusAcknowledged(
+  actual: StatusAcknowledgement | null | undefined,
+  expected: {
+    id: string;
+    epoch: number;
+    input: ReturnType<typeof shipmentSourceInput>;
+    basis: { id: string; eventType: string; providerEventTime?: string | null } | undefined;
+  }
+): boolean {
+  const statuses: Record<string, string> = {
+    PICKED_UP: 'PICKED_UP',
+    IN_TRANSIT: 'IN_TRANSIT',
+    ARRIVED: 'IN_TRANSIT',
+    DEPARTED: 'IN_TRANSIT',
+    OUT_FOR_DELIVERY: 'IN_TRANSIT',
+    DELIVERED: 'DELIVERED',
+    FAILED: 'FAILED',
+    RETURNED: 'RETURNED',
+  };
+  const basis = expected.basis;
+  const time = basis?.providerEventTime ? Date.parse(basis.providerEventTime) : NaN;
+  return (
+    !!actual &&
+    !!basis &&
+    Number.isFinite(time) &&
+    actual.id === expected.id &&
+    actual.statusRevision === expected.input.expectedStatusRevision + 1 &&
+    actual.statusAuthority === 'INTEGRATION_EVENT_TIME' &&
+    actual.statusAuthorityEpoch === expected.epoch + 1 &&
+    actual.designatedIntegrationId === expected.input.integrationId &&
+    actual.statusBasisEventId === basis.id &&
+    basis.id === expected.input.basisTrackingEventId &&
+    typeof actual.statusBasisSourceTime === 'string' &&
+    Date.parse(actual.statusBasisSourceTime) === time &&
+    actual.maxSourceAgeSeconds === expected.input.maxSourceAgeSeconds &&
+    actual.maxFutureSkewSeconds === expected.input.maxFutureSkewSeconds &&
+    typeof statuses[basis.eventType] === 'string' &&
+    actual.status === statuses[basis.eventType]
+  );
+}
+
+export function manualStatusAcknowledged(
+  actual: StatusAcknowledgement | null | undefined,
+  expected: { id: string; revision: number; epoch: number; status: string }
+): boolean {
+  return (
+    !!actual &&
+    actual.id === expected.id &&
+    actual.statusRevision === expected.revision + 1 &&
+    actual.status === expected.status &&
+    actual.statusAuthority === 'MANUAL_HOLD' &&
+    actual.statusAuthorityEpoch === expected.epoch + 1 &&
+    actual.designatedIntegrationId === null &&
+    actual.statusBasisEventId === null &&
+    actual.statusBasisSourceTime === null &&
+    actual.maxSourceAgeSeconds === null &&
+    actual.maxFutureSkewSeconds === null
+  );
+}

package/src/operations/shipment-status-authority/status.graphql

@@ -0,0 +1,80 @@
+fragment ShipmentStatusAuthorityFields on MtwShipment {
+  id
+  shipmentNumber
+  status
+  statusRevision
+  statusAuthority
+  statusAuthorityEpoch
+  designatedIntegrationId
+  statusBasisEventId
+  statusBasisSourceTime
+  maxSourceAgeSeconds
+  maxFutureSkewSeconds
+}
+
+query StatusAuthorityShipments($filter: ShipmentFilterInput, $pagination: PaginationInput!) {
+  shipments(filter: $filter, pagination: $pagination) {
+    ...ShipmentStatusAuthorityFields
+  }
+}
+
+query StatusAuthorityDetail($id: ID!, $pagination: PaginationInput!, $evidencePagination: PaginationInput!) {
+  shipment(id: $id) {
+    ...ShipmentStatusAuthorityFields
+    trackingEvents(pagination: $evidencePagination) {
+      id
+      eventType
+      sourceIntegrationId
+      sourceTimestampProvenance
+      providerEventTime
+      serverReceivedAt
+      timestamp
+    }
+  }
+  shipmentStatusDecisions(shipmentId: $id, pagination: $pagination) {
+    id
+    origin
+    outcome
+    heldReason
+    observedRevision
+    resultRevision
+    priorStatus
+    resultStatus
+    trackingEventId
+    proofId
+    reason
+    recordedAt
+    configuredIntegrationId
+    configuredMaxSourceAgeSeconds
+    configuredMaxFutureSkewSeconds
+  }
+}
+
+query StatusAuthoritySources($pagination: PaginationInput!) {
+  integrations(pagination: $pagination) {
+    id
+    name
+    provider
+    status
+  }
+}
+
+mutation StatusAuthorityConfigure($id: ID!, $input: ConfigureShipmentStatusSourceInput!) {
+  configureShipmentStatusSource(id: $id, input: $input) {
+    ...ShipmentStatusAuthorityFields
+  }
+}
+
+mutation StatusAuthorityManual($id: ID!, $input: UpdateShipmentInput!) {
+  updateShipment(id: $id, input: $input) {
+    ...ShipmentStatusAuthorityFields
+  }
+}
+
+query StatusAuthorityOwnedDelivery($deliveryJobId: ID!) {
+  myEpodShipmentStatus(deliveryJobId: $deliveryJobId) {
+    id
+    status
+    statusRevision
+  }
+}