@burdenoff/microfe-movethewheels 2026.1101.4 → 2026.1102.1

package/src/movethewheels/components/CustomerNotificationSettingsCard.tsx

@@ -0,0 +1,465 @@
+/**
+ * Customer delivery notifications on the Settings page (BOFF-4402).
+ *
+ * Lets a workspace admin switch customer notifications on, pick email and/or
+ * SMS and the shipment events that notify, preview what customers receive,
+ * and see the most recent notifications with their delivery status. The
+ * service owns validation and delivery; this card only edits the settings.
+ *
+ * The parent keys this card by workspace, so a workspace switch remounts it.
+ * The form stays disabled until the saved settings have actually been read:
+ * the defaults are a placeholder, never something to edit and save over.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, type FormEvent } from 'react';
+import { BellRing, Loader2, RefreshCw, RotateCcw, Save } from 'lucide-react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+import { formatDateTime } from '../utils/formatters';
+import {
+  CUSTOMER_NOTIFICATION_EVENTS,
+  MTW_CUSTOMER_NOTIFICATIONS_QUERY,
+  MTW_CUSTOMER_NOTIFICATION_PREVIEWS_QUERY,
+  MTW_CUSTOMER_NOTIFICATION_SETTINGS_QUERY,
+  STATUS_LABELS,
+  UPDATE_MTW_CUSTOMER_NOTIFICATION_SETTINGS_MUTATION,
+  changedNotificationSettings,
+  defaultNotificationSettings,
+  eventLabel,
+  notificationDraftError,
+  toggleEvent,
+  type MtwCustomerNotification,
+  type MtwCustomerNotificationEvent,
+  type MtwCustomerNotificationPreview,
+  type MtwCustomerNotificationSettings,
+  type MtwCustomerNotificationStatus,
+} from '../utils/customerNotifications';
+import { FormError } from './FormError';
+import { Notice, useNotice } from './Notice';
+import {
+  Badge,
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Checkbox,
+  Label,
+  Skeleton,
+  Switch,
+} from './ui';
+
+const RECENT_LIMIT = 10;
+
+type Draft = Pick<
+  MtwCustomerNotificationSettings,
+  'enabled' | 'emailEnabled' | 'smsEnabled' | 'events'
+>;
+
+const toDraft = (settings: MtwCustomerNotificationSettings): Draft => ({
+  enabled: settings.enabled,
+  emailEnabled: settings.emailEnabled,
+  smsEnabled: settings.smsEnabled,
+  events: [...settings.events],
+});
+
+const STATUS_VARIANT: Record<
+  MtwCustomerNotificationStatus,
+  'default' | 'secondary' | 'outline' | 'destructive'
+> = {
+  SENT: 'default',
+  PENDING: 'secondary',
+  SKIPPED: 'outline',
+  FAILED: 'destructive',
+};
+
+export function CustomerNotificationSettingsCard({ readOnly }: { readOnly: boolean }) {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const graphQLOptions = useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+
+  const [settings, setSettings] = useState<MtwCustomerNotificationSettings>(() =>
+    defaultNotificationSettings(workspaceId ?? '')
+  );
+  const [draft, setDraft] = useState<Draft>(() => toDraft(settings));
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [isSaving, setIsSaving] = useState(false);
+  const [formError, setFormError] = useState<string | null>(null);
+  const { message: notice, notify } = useNotice();
+  const [recent, setRecent] = useState<MtwCustomerNotification[]>([]);
+  const [recentTotal, setRecentTotal] = useState(0);
+  const [recentError, setRecentError] = useState<string | null>(null);
+  // Starts true so the empty state does not flash before the first fetch resolves.
+  const [isLoadingRecent, setIsLoadingRecent] = useState(true);
+  const [previews, setPreviews] = useState<MtwCustomerNotificationPreview[]>([]);
+  const [previewEvent, setPreviewEvent] = useState<MtwCustomerNotificationEvent>('BOOKED');
+  const [loadAttempt, setLoadAttempt] = useState(0);
+  const recentRequest = useRef(0);
+
+  useEffect(() => {
+    if (!graphQLOptions.workspaceId) return;
+    let cancelled = false;
+    setIsLoaded(false);
+    executeGraphQL<{ mtwCustomerNotificationSettings: MtwCustomerNotificationSettings }>(
+      graphQLOptions,
+      MTW_CUSTOMER_NOTIFICATION_SETTINGS_QUERY
+    )
+      .then((data) => {
+        if (cancelled) return;
+        setSettings(data.mtwCustomerNotificationSettings);
+        setDraft(toDraft(data.mtwCustomerNotificationSettings));
+        setLoadError(null);
+        setIsLoaded(true);
+      })
+      .catch((caught: unknown) => {
+        if (!cancelled)
+          setLoadError(caught instanceof Error ? caught.message : 'Could not load the settings');
+      });
+    executeGraphQL<{ mtwCustomerNotificationPreviews: MtwCustomerNotificationPreview[] }>(
+      graphQLOptions,
+      MTW_CUSTOMER_NOTIFICATION_PREVIEWS_QUERY
+    )
+      .then((data) => {
+        if (!cancelled) setPreviews(data.mtwCustomerNotificationPreviews);
+      })
+      .catch(() => {
+        // Previews are a convenience; the settings still work without them.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [graphQLOptions, loadAttempt]);
+
+  // Only the newest request may write the log: a slower, older response (or
+  // one that lands after unmount) is dropped.
+  const loadRecent = useCallback(async () => {
+    if (!graphQLOptions.workspaceId) {
+      setIsLoadingRecent(false);
+      return;
+    }
+    const request = ++recentRequest.current;
+    setIsLoadingRecent(true);
+    try {
+      const data = await executeGraphQL<{
+        mtwCustomerNotifications: { items: MtwCustomerNotification[]; total: number };
+      }>(graphQLOptions, MTW_CUSTOMER_NOTIFICATIONS_QUERY, {
+        pagination: { limit: RECENT_LIMIT, offset: 0 },
+      });
+      if (request !== recentRequest.current) return;
+      setRecent(data.mtwCustomerNotifications.items);
+      setRecentTotal(data.mtwCustomerNotifications.total);
+      setRecentError(null);
+    } catch (caught) {
+      if (request !== recentRequest.current) return;
+      setRecentError(caught instanceof Error ? caught.message : 'Could not load notifications');
+    } finally {
+      if (request === recentRequest.current) setIsLoadingRecent(false);
+    }
+  }, [graphQLOptions]);
+
+  useEffect(() => {
+    void loadRecent();
+    return () => {
+      // Invalidate whatever is in flight when the options change or the card unmounts.
+      recentRequest.current += 1;
+    };
+  }, [loadRecent]);
+
+  const changes = useMemo(() => changedNotificationSettings(settings, draft), [settings, draft]);
+  const draftError = notificationDraftError(draft);
+  const isDirty = Object.keys(changes).length > 0;
+  const canSave = isLoaded && !readOnly && !isSaving && isDirty && !draftError;
+  const disabled = readOnly || isSaving || !isLoaded;
+
+  const update = (next: Partial<Draft>) => {
+    setFormError(null);
+    setDraft((previous) => ({ ...previous, ...next }));
+  };
+
+  const onSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (!canSave) return;
+    setIsSaving(true);
+    setFormError(null);
+    try {
+      const data = await executeGraphQL<{
+        updateMtwCustomerNotificationSettings: MtwCustomerNotificationSettings;
+      }>(
+        graphQLOptions,
+        UPDATE_MTW_CUSTOMER_NOTIFICATION_SETTINGS_MUTATION,
+        { input: changes },
+        'SINGLE_ATTEMPT'
+      );
+      const saved = data.updateMtwCustomerNotificationSettings;
+      setSettings(saved);
+      setDraft(toDraft(saved));
+      notify(
+        saved.enabled
+          ? 'Customer notifications are on. Customers hear about shipment changes from now on.'
+          : 'Customer notifications are off.'
+      );
+    } catch (caught) {
+      setFormError(caught instanceof Error ? caught.message : 'Could not save the settings');
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  const preview = previews.find((item) => item.event === previewEvent);
+
+  return (
+    <Card data-testid="mtw-customer-notifications">
+      <CardHeader>
+        <div className="flex flex-wrap items-center justify-between gap-3">
+          <CardTitle className="flex items-center gap-2 text-base">
+            <BellRing size={18} /> Customer delivery notifications
+          </CardTitle>
+          {isLoaded && (
+            <Badge variant={settings.enabled ? 'default' : 'outline'}>
+              {settings.enabled ? 'On' : 'Off'}
+            </Badge>
+          )}
+        </div>
+        <CardDescription>
+          Email or text your customers when their shipment is booked, picked up, out for delivery,
+          delivered, running late or could not be delivered. Each customer can opt out on their
+          customer record; SMS goes only to customers who agreed to texts.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-6">
+        {loadError && (
+          <div className="space-y-3">
+            <FormError
+              message={`Could not load the customer notification settings (${loadError}). They cannot be changed until they load.`}
+            />
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() => {
+                setLoadError(null);
+                setLoadAttempt((attempt) => attempt + 1);
+              }}
+            >
+              <RefreshCw size={14} className="mr-2" /> Try again
+            </Button>
+          </div>
+        )}
+        <Notice message={notice} />
+
+        {!isLoaded ? (
+          loadError ? null : (
+            <div className="space-y-3" aria-busy="true">
+              <Skeleton className="h-8 w-full" />
+              <Skeleton className="h-24 w-full" />
+            </div>
+          )
+        ) : (
+          <form
+            className="space-y-6"
+            onSubmit={(event) => void onSubmit(event)}
+            aria-label="Customer notification settings"
+          >
+            {readOnly && (
+              <p className="rounded-lg border border-border-default bg-surface-secondary px-4 py-3 text-sm text-text-secondary">
+                You can view these settings. Ask a workspace admin or the Logistics Director to
+                change them.
+              </p>
+            )}
+            <div className="flex items-start justify-between gap-4 rounded-lg border border-border-default px-4 py-3">
+              <div className="min-w-0">
+                <Label htmlFor="mtw-customer-notify-enabled" className="text-sm font-medium">
+                  Notify customers about their shipments
+                </Label>
+                <p className="text-xs text-text-secondary">
+                  Only changes made after you switch this on notify; customers are never mailed
+                  about shipments that already happened.
+                  {settings.enabledAt && settings.enabled
+                    ? ` On since ${formatDateTime(settings.enabledAt)}.`
+                    : ''}
+                </p>
+              </div>
+              <Switch
+                id="mtw-customer-notify-enabled"
+                checked={draft.enabled}
+                disabled={disabled}
+                onCheckedChange={(checked: boolean) => update({ enabled: checked })}
+              />
+            </div>
+
+            <fieldset className="space-y-3" disabled={disabled}>
+              <legend className="text-sm font-semibold text-text-primary">Channels</legend>
+              <div className="flex flex-wrap gap-6">
+                <div className="flex items-center gap-2">
+                  <Checkbox
+                    id="mtw-customer-notify-email"
+                    checked={draft.emailEnabled}
+                    disabled={disabled}
+                    onCheckedChange={(checked) => update({ emailEnabled: checked === true })}
+                  />
+                  <Label htmlFor="mtw-customer-notify-email" className="text-sm font-normal">
+                    Email
+                  </Label>
+                </div>
+                <div className="flex items-center gap-2">
+                  <Checkbox
+                    id="mtw-customer-notify-sms"
+                    checked={draft.smsEnabled}
+                    disabled={disabled}
+                    onCheckedChange={(checked) => update({ smsEnabled: checked === true })}
+                  />
+                  <Label htmlFor="mtw-customer-notify-sms" className="text-sm font-normal">
+                    SMS (phone numbers with a country code, e.g. +91…)
+                  </Label>
+                </div>
+              </div>
+              <p className="text-xs text-text-secondary">
+                Texts are sent through the SMS channel configured for your organization. Without
+                one, SMS sends are recorded as failed in the recent notifications below.
+              </p>
+            </fieldset>
+
+            <fieldset className="space-y-3" disabled={disabled}>
+              <legend className="text-sm font-semibold text-text-primary">Events</legend>
+              <div className="grid grid-cols-1 gap-3 md:grid-cols-2">
+                {CUSTOMER_NOTIFICATION_EVENTS.map((option) => {
+                  const id = `mtw-customer-notify-event-${option.value}`;
+                  return (
+                    <div key={option.value} className="flex items-start gap-2">
+                      <Checkbox
+                        id={id}
+                        checked={draft.events.includes(option.value)}
+                        disabled={disabled}
+                        onCheckedChange={(checked) =>
+                          update({
+                            events: toggleEvent(draft.events, option.value, checked === true),
+                          })
+                        }
+                      />
+                      <Label htmlFor={id} className="text-sm font-normal leading-snug">
+                        <span className="block font-medium text-text-primary">{option.label}</span>
+                        <span className="block text-xs text-text-secondary">
+                          {option.description}
+                        </span>
+                      </Label>
+                    </div>
+                  );
+                })}
+              </div>
+            </fieldset>
+
+            {draftError && <p className="text-xs text-status-error-text">{draftError}</p>}
+            <FormError message={formError} />
+
+            <div className="flex flex-wrap items-center justify-end gap-3">
+              <Button
+                type="button"
+                variant="outline"
+                disabled={!isDirty || isSaving}
+                onClick={() => {
+                  setFormError(null);
+                  setDraft(toDraft(settings));
+                }}
+              >
+                <RotateCcw size={16} className="mr-2" /> Discard changes
+              </Button>
+              <Button type="submit" disabled={!canSave}>
+                {isSaving ? (
+                  <Loader2 size={16} className="mr-2 animate-spin" />
+                ) : (
+                  <Save size={16} className="mr-2" />
+                )}
+                Save notification settings
+              </Button>
+            </div>
+          </form>
+        )}
+
+        {previews.length > 0 && (
+          <div className="space-y-3 border-t border-border-default pt-4">
+            <div className="flex flex-wrap items-center gap-2">
+              <span className="text-sm font-semibold text-text-primary">Preview</span>
+              {CUSTOMER_NOTIFICATION_EVENTS.map((option) => (
+                <Button
+                  key={option.value}
+                  type="button"
+                  size="sm"
+                  variant={previewEvent === option.value ? 'default' : 'outline'}
+                  onClick={() => setPreviewEvent(option.value)}
+                >
+                  {option.label}
+                </Button>
+              ))}
+            </div>
+            {preview && (
+              <div
+                className="space-y-2 rounded-lg bg-surface-secondary px-4 py-3 text-sm"
+                data-testid="mtw-customer-notify-preview"
+              >
+                <p className="font-medium text-text-primary">{preview.subject}</p>
+                <p className="whitespace-pre-line text-text-secondary">{preview.emailText}</p>
+                <p className="text-xs text-text-tertiary">SMS: {preview.smsText}</p>
+              </div>
+            )}
+          </div>
+        )}
+
+        <div className="space-y-3 border-t border-border-default pt-4">
+          <div className="flex flex-wrap items-center justify-between gap-2">
+            <span className="text-sm font-semibold text-text-primary">
+              Recent notifications{recentTotal > 0 ? ` (${recentTotal})` : ''}
+            </span>
+            <Button
+              type="button"
+              size="sm"
+              variant="outline"
+              disabled={isLoadingRecent}
+              onClick={() => void loadRecent()}
+            >
+              <RefreshCw size={14} className="mr-2" /> Refresh
+            </Button>
+          </div>
+          {recentError && <FormError message={recentError} />}
+          {!recentError && recent.length === 0 && !isLoadingRecent && (
+            <p className="text-sm text-text-secondary">
+              No customer notifications yet. They appear here as shipments change.
+            </p>
+          )}
+          {recent.length > 0 && (
+            <ul className="divide-y divide-border-default" data-testid="mtw-customer-notify-recent">
+              {recent.map((item) => (
+                <li key={item.id} className="flex flex-wrap items-start justify-between gap-2 py-2">
+                  <div className="min-w-0">
+                    <p className="text-sm font-medium text-text-primary">
+                      {eventLabel(item.event)} · {item.shipmentNumber ?? item.shipmentId}
+                    </p>
+                    <p className="text-xs text-text-secondary">
+                      {item.channel === 'EMAIL' ? 'Email' : 'SMS'}
+                      {item.recipient ? ` to ${item.recipient}` : ''} ·{' '}
+                      {formatDateTime(item.sentAt ?? item.createdAt)}
+                    </p>
+                    {item.lastError && item.status !== 'SENT' && (
+                      <p className="text-xs text-text-tertiary">{item.lastError}</p>
+                    )}
+                  </div>
+                  <Badge variant={STATUS_VARIANT[item.status]}>{STATUS_LABELS[item.status]}</Badge>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

package/src/movethewheels/hooks/useCustomers.ts

@@ -35,6 +35,8 @@ interface ApiCustomer {
   businessLicense?: string | null;
   taxId?: string | null;
   rating?: number | null;
+  notifyByEmail?: boolean | null;
+  notifyBySms?: boolean | null;
   createdAt: string;
   updatedAt: string;
   deletedAt?: string | null;
@@ -53,6 +55,8 @@ const LIST_CUSTOMERS_QUERY = `
       businessLicense
       taxId
       rating
+      notifyByEmail
+      notifyBySms
       createdAt
       updatedAt
       deletedAt
@@ -74,6 +78,8 @@ const GET_CUSTOMER_QUERY = `
       businessLicense
       taxId
       rating
+      notifyByEmail
+      notifyBySms
       createdAt
       updatedAt
       deletedAt
@@ -94,6 +100,8 @@ const CREATE_CUSTOMER_MUTATION = `
       businessLicense
       taxId
       rating
+      notifyByEmail
+      notifyBySms
       createdAt
       updatedAt
       deletedAt
@@ -114,6 +122,8 @@ const UPDATE_CUSTOMER_MUTATION = `
       businessLicense
       taxId
       rating
+      notifyByEmail
+      notifyBySms
       createdAt
       updatedAt
       deletedAt
@@ -144,6 +154,9 @@ function mapCustomer(customer: ApiCustomer): Customer {
     businessLicense: customer.businessLicense ?? undefined,
     taxId: customer.taxId ?? undefined,
     rating: customer.rating ?? undefined,
+    // Absent only from an older service; match its defaults (email on, SMS off).
+    notifyByEmail: customer.notifyByEmail ?? true,
+    notifyBySms: customer.notifyBySms ?? false,
     createdAt: new Date(customer.createdAt),
     updatedAt: new Date(customer.updatedAt),
   };
@@ -263,6 +276,8 @@ export function useCustomers(options: UseCustomersOptions = {}): UseCustomersRes
           businessLicense: customerData.businessLicense,
           taxId: customerData.taxId,
           rating: customerData.rating,
+          notifyByEmail: customerData.notifyByEmail,
+          notifyBySms: customerData.notifyBySms,
         },
       });
 
@@ -289,6 +304,8 @@ export function useCustomers(options: UseCustomersOptions = {}): UseCustomersRes
           businessLicense: updates.businessLicense,
           taxId: updates.taxId,
           rating: updates.rating,
+          notifyByEmail: updates.notifyByEmail,
+          notifyBySms: updates.notifyBySms,
         },
       });
 

package/src/movethewheels/pages/CustomerDetailsPage.tsx

@@ -18,6 +18,7 @@ import {
   Package,
   X,
   Trash2,
+  BellRing,
 } from 'lucide-react';
 import { PageLayout, LoadingState, ErrorState } from '../components/PageLayout';
 import { TypeBadge, StatusBadge } from '../components/StatusBadge';
@@ -51,6 +52,10 @@ import { useOrders } from '../hooks/useOrders';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatAddress, formatCurrency, formatDate } from '../utils/formatters';
 import { joinPath, buildOrderCustomerPath, getSafeCustomerReturnPath } from '../utils/navigation';
+import {
+  CustomerDeliveryUpdatesFields,
+  deliveryUpdatesSummary,
+} from '../components/CustomerDeliveryUpdatesFields';
 import { FormError } from '../components/FormError';
 import { Notice, useNotice } from '../components/Notice';
 
@@ -68,6 +73,8 @@ interface CustomerFormState {
   businessLicense: string;
   taxId: string;
   rating: string;
+  notifyByEmail: boolean;
+  notifyBySms: boolean;
 }
 
 const emptyCustomerForm: CustomerFormState = {
@@ -84,6 +91,8 @@ const emptyCustomerForm: CustomerFormState = {
   businessLicense: '',
   taxId: '',
   rating: '',
+  notifyByEmail: true,
+  notifyBySms: false,
 };
 
 function NewCustomerForm() {
@@ -125,6 +134,8 @@ function NewCustomerForm() {
         businessLicense: form.businessLicense.trim() || undefined,
         taxId: form.taxId.trim() || undefined,
         rating: form.rating ? Number(form.rating) : undefined,
+        notifyByEmail: form.notifyByEmail,
+        notifyBySms: form.notifyBySms,
       });
       const destination = returnTo
         ? buildOrderCustomerPath(returnTo, created.id)
@@ -320,6 +331,13 @@ function NewCustomerForm() {
                 />
               </div>
             </div>
+            <div className="mt-6">
+              <CustomerDeliveryUpdatesFields
+                idPrefix="new-customer"
+                value={{ notifyByEmail: form.notifyByEmail, notifyBySms: form.notifyBySms }}
+                onChange={(next) => setForm((prev) => ({ ...prev, ...next }))}
+              />
+            </div>
           </CardContent>
         </Card>
       </form>
@@ -343,6 +361,8 @@ function customerToForm(customer: {
   businessLicense?: string;
   taxId?: string;
   rating?: number;
+  notifyByEmail: boolean;
+  notifyBySms: boolean;
 }): CustomerFormState {
   return {
     name: customer.name,
@@ -358,6 +378,8 @@ function customerToForm(customer: {
     businessLicense: customer.businessLicense ?? '',
     taxId: customer.taxId ?? '',
     rating: customer.rating ? String(customer.rating) : '',
+    notifyByEmail: customer.notifyByEmail,
+    notifyBySms: customer.notifyBySms,
   };
 }
 
@@ -424,6 +446,8 @@ export default function CustomerDetailsPage() {
         businessLicense: form.businessLicense.trim() || undefined,
         taxId: form.taxId.trim() || undefined,
         rating: form.rating ? Number(form.rating) : undefined,
+        notifyByEmail: form.notifyByEmail,
+        notifyBySms: form.notifyBySms,
       });
       notify('Customer updated.');
       setEditing(false);
@@ -662,6 +686,12 @@ export default function CustomerDetailsPage() {
                     />
                   </div>
                 </div>
+                <CustomerDeliveryUpdatesFields
+                  idPrefix="edit-customer"
+                  value={{ notifyByEmail: form.notifyByEmail, notifyBySms: form.notifyBySms }}
+                  onChange={(next) => setForm((prev) => ({ ...prev, ...next }))}
+                  disabled={saving}
+                />
               </div>
             ) : (
               <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
@@ -691,6 +721,15 @@ export default function CustomerDetailsPage() {
                       </div>
                     </div>
                   )}
+                  <div className="flex items-center gap-3">
+                    <BellRing size={18} className="text-text-secondary" />
+                    <div>
+                      <p className="text-sm text-text-secondary">Delivery updates</p>
+                      <p className="font-medium" data-testid="customer-delivery-updates">
+                        {deliveryUpdatesSummary(customer)}
+                      </p>
+                    </div>
+                  </div>
                 </div>
               </div>
             )}