@burdenoff/microfe-movethewheels 2026.1101.4 → 2026.1102.2

package/src/movethewheels/utils/customerNotifications.ts

@@ -0,0 +1,209 @@
+/**
+ * Customer delivery notifications — client side of wspace-movethewheels-svc's
+ * customer notification settings, history and previews (BOFF-4402).
+ *
+ * The service decides what to send and when; this module holds the GraphQL
+ * documents, the labels and the pure draft helpers the Settings page uses.
+ * Kept free of React so the contract can be unit-tested.
+ */
+
+export type MtwCustomerNotificationEvent =
+  'BOOKED' | 'PICKED_UP' | 'OUT_FOR_DELIVERY' | 'DELIVERED' | 'DELAYED' | 'FAILED';
+export type MtwCustomerNotificationChannel = 'EMAIL' | 'SMS';
+export type MtwCustomerNotificationStatus = 'PENDING' | 'SENT' | 'FAILED' | 'SKIPPED';
+
+export interface MtwCustomerNotificationSettings {
+  workspaceId: string;
+  enabled: boolean;
+  enabledAt: string | null;
+  emailEnabled: boolean;
+  smsEnabled: boolean;
+  events: MtwCustomerNotificationEvent[];
+  isCustomized: boolean;
+  updatedAt: string | null;
+  updatedBy: string | null;
+}
+
+export type MtwCustomerNotificationSettingsInput = Partial<
+  Pick<MtwCustomerNotificationSettings, 'enabled' | 'emailEnabled' | 'smsEnabled' | 'events'>
+>;
+
+export interface MtwCustomerNotification {
+  id: string;
+  shipmentId: string;
+  shipmentNumber: string | null;
+  customerId: string | null;
+  event: MtwCustomerNotificationEvent;
+  channel: MtwCustomerNotificationChannel;
+  status: MtwCustomerNotificationStatus;
+  recipient: string | null;
+  subject: string | null;
+  attempts: number;
+  lastError: string | null;
+  sentAt: string | null;
+  createdAt: string;
+}
+
+export interface MtwCustomerNotificationPreview {
+  event: MtwCustomerNotificationEvent;
+  subject: string;
+  emailText: string;
+  smsText: string;
+}
+
+/** Every event, in the order a shipment reaches them. */
+export const CUSTOMER_NOTIFICATION_EVENTS: ReadonlyArray<{
+  value: MtwCustomerNotificationEvent;
+  label: string;
+  description: string;
+}> = [
+  { value: 'BOOKED', label: 'Booked', description: 'A shipment is created for the customer' },
+  { value: 'PICKED_UP', label: 'Picked up', description: 'The shipment is collected' },
+  {
+    value: 'OUT_FOR_DELIVERY',
+    label: 'Out for delivery',
+    description: 'Tracking says the shipment is on its last leg',
+  },
+  { value: 'DELIVERED', label: 'Delivered', description: 'The shipment is delivered' },
+  {
+    value: 'DELAYED',
+    label: 'Running late',
+    description: 'The risk monitor expects it to miss the promised delivery (once per promise)',
+  },
+  { value: 'FAILED', label: 'Delivery failed', description: 'Delivery could not be completed' },
+];
+
+export function eventLabel(event: MtwCustomerNotificationEvent): string {
+  return CUSTOMER_NOTIFICATION_EVENTS.find((option) => option.value === event)?.label ?? event;
+}
+
+export const STATUS_LABELS: Record<MtwCustomerNotificationStatus, string> = {
+  PENDING: 'Sending',
+  SENT: 'Sent',
+  FAILED: 'Failed',
+  SKIPPED: 'Not sent',
+};
+
+/** Off, email only, every event — what a workspace sees until it saves. */
+export function defaultNotificationSettings(workspaceId = ''): MtwCustomerNotificationSettings {
+  return {
+    workspaceId,
+    enabled: false,
+    enabledAt: null,
+    emailEnabled: true,
+    smsEnabled: false,
+    events: CUSTOMER_NOTIFICATION_EVENTS.map((option) => option.value),
+    isCustomized: false,
+    updatedAt: null,
+    updatedBy: null,
+  };
+}
+
+/** Events in canonical order without duplicates. */
+export function orderedEvents(
+  events: readonly MtwCustomerNotificationEvent[]
+): MtwCustomerNotificationEvent[] {
+  const wanted = new Set(events);
+  return CUSTOMER_NOTIFICATION_EVENTS.map((option) => option.value).filter((event) =>
+    wanted.has(event)
+  );
+}
+
+/** Add or remove one event from a selection. */
+export function toggleEvent(
+  events: readonly MtwCustomerNotificationEvent[],
+  event: MtwCustomerNotificationEvent,
+  on: boolean
+): MtwCustomerNotificationEvent[] {
+  const next = new Set(events);
+  if (on) next.add(event);
+  else next.delete(event);
+  return orderedEvents([...next]);
+}
+
+/** Only the fields the draft changed, ready for the update mutation. */
+export function changedNotificationSettings(
+  saved: MtwCustomerNotificationSettings,
+  draft: Pick<MtwCustomerNotificationSettings, 'enabled' | 'emailEnabled' | 'smsEnabled' | 'events'>
+): MtwCustomerNotificationSettingsInput {
+  const changes: MtwCustomerNotificationSettingsInput = {};
+  if (draft.enabled !== saved.enabled) changes.enabled = draft.enabled;
+  if (draft.emailEnabled !== saved.emailEnabled) changes.emailEnabled = draft.emailEnabled;
+  if (draft.smsEnabled !== saved.smsEnabled) changes.smsEnabled = draft.smsEnabled;
+  const draftEvents = orderedEvents(draft.events);
+  const savedEvents = orderedEvents(saved.events);
+  if (draftEvents.join(',') !== savedEvents.join(',')) changes.events = draftEvents;
+  return changes;
+}
+
+/** Why the draft cannot be saved, or null. Switching on needs a channel and an event. */
+export function notificationDraftError(
+  draft: Pick<MtwCustomerNotificationSettings, 'enabled' | 'emailEnabled' | 'smsEnabled' | 'events'>
+): string | null {
+  if (!draft.enabled) return null;
+  if (!draft.emailEnabled && !draft.smsEnabled) return 'Choose email, SMS or both.';
+  if (draft.events.length === 0) return 'Choose at least one event to notify customers about.';
+  return null;
+}
+
+const SETTINGS_FIELDS = `
+  workspaceId
+  enabled
+  enabledAt
+  emailEnabled
+  smsEnabled
+  events
+  isCustomized
+  updatedAt
+  updatedBy
+`;
+
+export const MTW_CUSTOMER_NOTIFICATION_SETTINGS_QUERY = `
+  query MtwCustomerNotificationSettings {
+    mtwCustomerNotificationSettings {${SETTINGS_FIELDS}}
+  }
+`;
+
+export const UPDATE_MTW_CUSTOMER_NOTIFICATION_SETTINGS_MUTATION = `
+  mutation UpdateMtwCustomerNotificationSettings($input: UpdateMtwCustomerNotificationSettingsInput!) {
+    updateMtwCustomerNotificationSettings(input: $input) {${SETTINGS_FIELDS}}
+  }
+`;
+
+export const MTW_CUSTOMER_NOTIFICATIONS_QUERY = `
+  query MtwCustomerNotifications(
+    $filter: MtwCustomerNotificationFilterInput
+    $pagination: PaginationInput
+  ) {
+    mtwCustomerNotifications(filter: $filter, pagination: $pagination) {
+      total
+      hasMore
+      items {
+        id
+        shipmentId
+        shipmentNumber
+        customerId
+        event
+        channel
+        status
+        recipient
+        subject
+        attempts
+        lastError
+        sentAt
+        createdAt
+      }
+    }
+  }
+`;
+
+export const MTW_CUSTOMER_NOTIFICATION_PREVIEWS_QUERY = `
+  query MtwCustomerNotificationPreviews {
+    mtwCustomerNotificationPreviews {
+      event
+      subject
+      emailText
+      smsText
+    }
+  }
+`;

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 }
+}