@burdenoff/microfe-movethewheels 2026.1102.1 → 2026.1102.2

package/src/movethewheels/utils/invoiceReview.ts

@@ -0,0 +1,146 @@
+/**
+ * Freight invoice review helpers (BOFF-10588): labels, the steps a viewer can
+ * take, and the exact mutation inputs. The server enforces every rule again;
+ * these only keep the page from offering a step that would be refused.
+ */
+import type {
+  DecideMtwFreightInvoiceInput,
+  HandOffMtwFreightInvoiceSettlementInput,
+  InvoiceReviewFragment,
+  MtwFreightInvoiceDecision,
+  MtwFreightInvoiceResolution,
+  MtwFreightInvoiceReviewAction,
+  MtwFreightInvoiceReviewStatus,
+  RecordMtwFreightInvoiceSupplierResponseInput,
+  ResolveMtwFreightInvoiceDisputeInput,
+} from '../../generated/freight-invoice-operations';
+
+export const REVIEW_STATUS_LABELS: Record<MtwFreightInvoiceReviewStatus, string> = {
+  AWAITING_REVIEW: 'Awaiting review',
+  ACCEPTED: 'Accepted',
+  ACCEPTED_WITH_VARIANCE: 'Accepted with variance',
+  DISPUTED: 'Disputed',
+  SUPPLIER_RESPONDED: 'Supplier responded',
+  SETTLEMENT_HANDED_OFF: 'Handed to Billing',
+  SUPERSEDED: 'Superseded by a correction',
+};
+
+export const REVIEW_EVENT_LABELS: Record<InvoiceReviewFragment['events'][number]['kind'], string> =
+  {
+    DECISION: 'Review decision',
+    SUPPLIER_RESPONSE: 'Supplier response',
+    DISPUTE_RESOLUTION: 'Dispute resolved',
+    SETTLEMENT_HANDOFF: 'Handed to Billing for settlement',
+  };
+
+/** Statuses a reviewer can filter the queue by; SUPERSEDED never appears in the queue. */
+export const REVIEW_QUEUE_STATUSES: MtwFreightInvoiceReviewStatus[] = [
+  'AWAITING_REVIEW',
+  'DISPUTED',
+  'SUPPLIER_RESPONDED',
+  'ACCEPTED',
+  'ACCEPTED_WITH_VARIANCE',
+  'SETTLEMENT_HANDED_OFF',
+];
+
+export interface ReviewPermissions {
+  canRead: boolean;
+  canUpdate: boolean;
+  canApprove: boolean;
+}
+
+const PERMISSION_FOR_ACTION: Record<MtwFreightInvoiceReviewAction, keyof ReviewPermissions> = {
+  DECIDE: 'canApprove',
+  RECORD_SUPPLIER_RESPONSE: 'canUpdate',
+  RESOLVE_DISPUTE: 'canApprove',
+  HAND_OFF_SETTLEMENT: 'canApprove',
+};
+
+/** Steps the server says are open (author separation included) that this viewer is also permitted to take. */
+export function availableReviewActions(
+  review: Pick<InvoiceReviewFragment, 'allowedActions'>,
+  permissions: ReviewPermissions
+): MtwFreightInvoiceReviewAction[] {
+  return review.allowedActions.filter((action) => permissions[PERMISSION_FOR_ACTION[action]]);
+}
+
+/** Why the author sees no decision: the server withholds it, so say so instead of showing nothing. */
+export function authorNotice(
+  review: Pick<InvoiceReviewFragment, 'viewerIsAuthor' | 'status'>
+): string | null {
+  if (!review.viewerIsAuthor) return null;
+  if (
+    review.status === 'AWAITING_REVIEW' ||
+    review.status === 'DISPUTED' ||
+    review.status === 'SUPPLIER_RESPONDED'
+  )
+    return 'You recorded this comparison, so another reviewer must accept, dispute or resolve it.';
+  return null;
+}
+
+function text(value: string): string | null {
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+interface Common {
+  review: Pick<InvoiceReviewFragment, 'shipmentId' | 'comparisonId' | 'sequence'>;
+  idempotencyKey: string;
+}
+function common({ review, idempotencyKey }: Common) {
+  return {
+    shipmentId: review.shipmentId,
+    comparisonId: review.comparisonId,
+    expectedSequence: review.sequence,
+    idempotencyKey,
+  };
+}
+
+export type DraftProblem = 'REASON_REQUIRED' | 'LINES_REQUIRED' | 'RESPONSE_REQUIRED';
+export const DRAFT_PROBLEM_LABELS: Record<DraftProblem, string> = {
+  REASON_REQUIRED: 'Give a reason for a dispute, a variance or a resolution.',
+  LINES_REQUIRED: 'Choose at least one invoice line you dispute.',
+  RESPONSE_REQUIRED: "Record the supplier's response.",
+};
+
+export function decisionInput(
+  base: Common,
+  decision: MtwFreightInvoiceDecision,
+  reason: string,
+  disputedLineIds: readonly string[]
+): DecideMtwFreightInvoiceInput | DraftProblem {
+  const why = text(reason);
+  if (decision !== 'ACCEPTED' && !why) return 'REASON_REQUIRED';
+  if (decision === 'DISPUTED' && disputedLineIds.length === 0) return 'LINES_REQUIRED';
+  return {
+    ...common(base),
+    decision,
+    reason: why,
+    disputedLineIds: decision === 'DISPUTED' ? [...new Set(disputedLineIds)] : [],
+  };
+}
+
+export function supplierResponseInput(
+  base: Common,
+  response: string
+): RecordMtwFreightInvoiceSupplierResponseInput | DraftProblem {
+  const said = text(response);
+  return said ? { ...common(base), response: said } : 'RESPONSE_REQUIRED';
+}
+
+export function resolutionInput(
+  base: Common,
+  resolution: MtwFreightInvoiceResolution,
+  reason: string
+): ResolveMtwFreightInvoiceDisputeInput | DraftProblem {
+  const why = text(reason);
+  return why ? { ...common(base), resolution, reason: why } : 'REASON_REQUIRED';
+}
+
+export function handOffInput(base: Common, note: string): HandOffMtwFreightInvoiceSettlementInput {
+  return { ...common(base), note: text(note) };
+}
+
+export function isDraftProblem(value: unknown): value is DraftProblem {
+  return typeof value === 'string' && value in DRAFT_PROBLEM_LABELS;
+}

package/src/operations/freight-invoice/review.graphql

@@ -0,0 +1,26 @@
+fragment InvoiceReview on MtwFreightInvoiceReview {
+  comparisonId shipmentId invoiceIdentityId revision latestRevision supersededByComparisonId
+  supplierReference supplierLabel invoiceReference currency { code minorUnitDigits }
+  knownInvoiceAmountMinor invoiceAmountComplete comparisonRecordedAt comparisonCreatedBy
+  status resolvedByCorrection sequence allowedActions viewerIsAuthor settlementReference
+  events { id sequence kind decision statusAfter reason disputedLineIds settlementReference recordedAt createdBy }
+}
+query InvoiceReviewExact($shipmentId: ID!, $comparisonId: ID!) {
+  mtwFreightInvoiceReview(shipmentId: $shipmentId, comparisonId: $comparisonId) { ...InvoiceReview }
+}
+query InvoiceReviewQueue($status: MtwFreightInvoiceReviewStatus, $pagination: MtwContainerPagination) {
+  mtwFreightInvoiceReviewPage(status: $status, pagination: $pagination) {
+    items { ...InvoiceReview } total limit offset hasMore nextOffset
+  }
+}
+query InvoiceReviewSummary {
+  mtwFreightInvoiceReviewSummary { total awaitingReview accepted acceptedWithVariance disputed supplierResponded settlementHandedOff }
+}
+mutation DecideInvoiceReview($input: DecideMtwFreightInvoiceInput!) { decideMtwFreightInvoice(input: $input) { ...InvoiceReview } }
+mutation RecordInvoiceSupplierResponse($input: RecordMtwFreightInvoiceSupplierResponseInput!) {
+  recordMtwFreightInvoiceSupplierResponse(input: $input) { ...InvoiceReview }
+}
+mutation ResolveInvoiceDispute($input: ResolveMtwFreightInvoiceDisputeInput!) { resolveMtwFreightInvoiceDispute(input: $input) { ...InvoiceReview } }
+mutation HandOffInvoiceSettlement($input: HandOffMtwFreightInvoiceSettlementInput!) {
+  handOffMtwFreightInvoiceSettlement(input: $input) { ...InvoiceReview }
+}