@burdenoff/microfe-movethewheels 2026.1101.4 → 2026.1102.1

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