@burdenoff/microfe-movethewheels 2026.1028.1 → 2026.1031.1

package/src/movethewheels/hooks/useEntityExport.ts

@@ -0,0 +1,130 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+import {
+  GET_MTW_EXPORT_JOB_QUERY,
+  MTW_EXPORT_ENTITY_TYPES,
+  START_MTW_EXPORT_MUTATION,
+  triggerUrlDownload,
+  waitForExportJob,
+  type ExportJobSnapshot,
+  type MtwExportEntity,
+} from '../utils/entityExport';
+
+export type EntityExportState =
+  | { phase: 'idle' }
+  | { phase: 'running'; message: string }
+  | { phase: 'ready'; message: string }
+  | { phase: 'pending'; message: string; jobId: string }
+  | { phase: 'error'; message: string };
+
+export interface UseEntityExportResult {
+  state: EntityExportState;
+  isExporting: boolean;
+  /** Start a CSV export of every record of this entity in the workspace. */
+  startExport: () => void;
+  dismiss: () => void;
+}
+
+/**
+ * Drives the list-page "Export" action: starts an `exportMtwEntities` job for
+ * the page's entity type, waits for wspace-export-svc to build the archive and
+ * starts the download. A job that takes longer than the wait budget keeps
+ * running and is reported as pending, with its id, so the user can collect it
+ * from the shared Exports page.
+ */
+export function useEntityExport(entity: MtwExportEntity, label: string): UseEntityExportResult {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const [state, setState] = useState<EntityExportState>({ phase: 'idle' });
+  const abortRef = useRef<AbortController | null>(null);
+  const runningRef = useRef(false);
+
+  const graphQLOptions = useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+
+  useEffect(() => () => abortRef.current?.abort(), []);
+
+  const startExport = useCallback(() => {
+    // Starting a second job while one is being prepared would only duplicate work.
+    if (runningRef.current) return;
+    if (!workspaceId) {
+      setState({ phase: 'error', message: 'Select a workspace before exporting.' });
+      return;
+    }
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    setState({ phase: 'running', message: `Preparing your ${label} export…` });
+
+    const run = async () => {
+      runningRef.current = true;
+      try {
+        const started = await executeGraphQL<{ exportMtwEntities: ExportJobSnapshot }>(
+          graphQLOptions,
+          START_MTW_EXPORT_MUTATION,
+          {
+            input: {
+              workspaceId,
+              entityTypes: [MTW_EXPORT_ENTITY_TYPES[entity]],
+              format: 'CSV',
+              includeMetadata: true,
+            },
+          },
+          // Starting a job is not idempotent: never replay it on a transient error.
+          'SINGLE_ATTEMPT'
+        );
+        const outcome = await waitForExportJob(
+          started.exportMtwEntities,
+          async (id) => {
+            const data = await executeGraphQL<{ getExportJob: ExportJobSnapshot | null }>(
+              { ...graphQLOptions, signal: controller.signal },
+              GET_MTW_EXPORT_JOB_QUERY,
+              { id }
+            );
+            return data.getExportJob;
+          },
+          { signal: controller.signal }
+        );
+        if (controller.signal.aborted) return;
+        if (outcome.kind === 'ready') {
+          triggerUrlDownload(outcome.downloadUrl);
+          setState({ phase: 'ready', message: `Your ${label} export is downloading.` });
+        } else if (outcome.kind === 'pending') {
+          setState({
+            phase: 'pending',
+            jobId: outcome.jobId,
+            message: `Your ${label} export is still being prepared. It will be available on the Exports page when it finishes.`,
+          });
+        } else {
+          setState({ phase: 'error', message: `Export failed: ${outcome.message}` });
+        }
+      } catch (error) {
+        if (controller.signal.aborted) return;
+        setState({
+          phase: 'error',
+          message:
+            error instanceof Error && error.message
+              ? `Export failed: ${error.message}`
+              : 'Export failed. Please try again.',
+        });
+      } finally {
+        runningRef.current = false;
+      }
+    };
+    void run();
+  }, [entity, graphQLOptions, label, workspaceId]);
+
+  const dismiss = useCallback(() => setState({ phase: 'idle' }), []);
+
+  return { state, isExporting: state.phase === 'running', startExport, dismiss };
+}

package/src/movethewheels/hooks/useMarketplace.ts

@@ -0,0 +1,526 @@
+/**
+ * Marketplace hooks (BOFF-3988, MOV-UC-13).
+ *
+ * The workspace's directory of vetted service providers and their offerings,
+ * served by wspace-movethewheels-svc's marketplace module. A provider becomes a
+ * shipment's carrier through `assignShipmentServiceProvider`.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+
+export const PROVIDER_TYPES = [
+  'CARRIER',
+  'FREIGHT_FORWARDER',
+  'THIRD_PARTY_LOGISTICS',
+  'WAREHOUSE',
+  'CUSTOMS_BROKER',
+  'LAST_MILE',
+  'COURIER',
+  'OTHER',
+] as const;
+export type ProviderType = (typeof PROVIDER_TYPES)[number];
+
+export const OFFERING_CATEGORIES = [
+  'FULL_TRUCKLOAD',
+  'LESS_THAN_TRUCKLOAD',
+  'LAST_MILE',
+  'EXPRESS',
+  'OCEAN_FREIGHT',
+  'AIR_FREIGHT',
+  'RAIL_FREIGHT',
+  'WAREHOUSING',
+  'CUSTOMS_CLEARANCE',
+  'COLD_CHAIN',
+  'OTHER',
+] as const;
+export type OfferingCategory = (typeof OFFERING_CATEGORIES)[number];
+
+export const AVAILABILITIES = ['AVAILABLE', 'LIMITED', 'UNAVAILABLE'] as const;
+export type Availability = (typeof AVAILABILITIES)[number];
+
+/** "THIRD_PARTY_LOGISTICS" → "Third party logistics". */
+export function humanizeEnum(value: string): string {
+  const words = value.toLowerCase().split('_');
+  const text = words.join(' ');
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+export interface ProviderContact {
+  contactName?: string;
+  email?: string;
+  phone?: string;
+  website?: string;
+}
+
+export interface ServiceOffering {
+  id: string;
+  providerId: string;
+  name: string;
+  description: string | null;
+  category: OfferingCategory;
+  price: number | null;
+  currency: string;
+  pricingUnit: string | null;
+  transitDays: number | null;
+  availability: Availability;
+  isActive: boolean;
+}
+
+export interface ServiceProvider {
+  id: string;
+  name: string;
+  type: ProviderType;
+  description: string | null;
+  rating: number | null;
+  contact: ProviderContact;
+  services: string[];
+  serviceAreas: string[];
+  isVerified: boolean;
+  isActive: boolean;
+  offeringsCount: number;
+  createdAt: string;
+}
+
+export interface MarketplaceStats {
+  providers: number;
+  verifiedProviders: number;
+  activeProviders: number;
+  offerings: number;
+  avgRating: number | null;
+}
+
+export interface ProviderFilters {
+  search?: string;
+  type?: ProviderType;
+  isVerified?: boolean;
+}
+
+export interface ProviderInput {
+  name: string;
+  type: ProviderType;
+  description: string | null;
+  rating: number | null;
+  contactInfo: ProviderContact | null;
+  services: string[];
+  serviceAreas: string[];
+  isVerified: boolean;
+  isActive: boolean;
+}
+
+export interface OfferingInput {
+  name: string;
+  category: OfferingCategory;
+  description: string | null;
+  price: number | null;
+  currency: string;
+  pricingUnit: string | null;
+  transitDays: number | null;
+  availability: Availability;
+  isActive: boolean;
+}
+
+interface ApiProvider {
+  id: string;
+  name: string;
+  type: ProviderType;
+  description?: string | null;
+  rating?: number | null;
+  contactInfo?: unknown;
+  services: string[];
+  serviceAreas: string[];
+  isVerified: boolean;
+  isActive: boolean;
+  offeringsCount: number;
+  createdAt: string;
+}
+
+const PROVIDER_FIELDS = `
+  id
+  name
+  type
+  description
+  rating
+  contactInfo
+  services
+  serviceAreas
+  isVerified
+  isActive
+  offeringsCount
+  createdAt
+`;
+
+const OFFERING_FIELDS = `
+  id
+  providerId
+  name
+  description
+  category
+  price
+  currency
+  pricingUnit
+  transitDays
+  availability
+  isActive
+`;
+
+const LIST_PROVIDERS_QUERY = `
+  query ListMtwServiceProviders($filter: MtwServiceProviderFilterInput, $pagination: PaginationInput) {
+    serviceProviders(filter: $filter, pagination: $pagination) {
+      ${PROVIDER_FIELDS}
+    }
+    serviceProvidersCount(filter: $filter)
+  }
+`;
+
+const MARKETPLACE_STATS_QUERY = `
+  query MtwMarketplaceStats {
+    marketplaceStats {
+      providers
+      verifiedProviders
+      activeProviders
+      offerings
+      avgRating
+    }
+  }
+`;
+
+const LIST_OFFERINGS_QUERY = `
+  query ListMtwServiceOfferings($filter: MtwServiceOfferingFilterInput, $pagination: PaginationInput) {
+    serviceOfferings(filter: $filter, pagination: $pagination) {
+      ${OFFERING_FIELDS}
+    }
+  }
+`;
+
+const PROVIDER_SHIPMENTS_QUERY = `
+  query MtwProviderShipments($filter: ShipmentFilterInput, $pagination: PaginationInput) {
+    shipments(filter: $filter, pagination: $pagination) {
+      id
+      shipmentNumber
+      status
+    }
+    shipmentsCount(filter: $filter)
+  }
+`;
+
+const CREATE_PROVIDER_MUTATION = `
+  mutation CreateMtwServiceProvider($input: MtwCreateServiceProviderInput!) {
+    createServiceProvider(input: $input) {
+      ${PROVIDER_FIELDS}
+    }
+  }
+`;
+
+const UPDATE_PROVIDER_MUTATION = `
+  mutation UpdateMtwServiceProvider($id: ID!, $input: MtwUpdateServiceProviderInput!) {
+    updateServiceProvider(id: $id, input: $input) {
+      ${PROVIDER_FIELDS}
+    }
+  }
+`;
+
+const DELETE_PROVIDER_MUTATION = `
+  mutation DeleteMtwServiceProvider($id: ID!) {
+    deleteServiceProvider(id: $id)
+  }
+`;
+
+const CREATE_OFFERING_MUTATION = `
+  mutation CreateMtwServiceOffering($input: MtwCreateServiceOfferingInput!) {
+    createServiceOffering(input: $input) {
+      ${OFFERING_FIELDS}
+    }
+  }
+`;
+
+const UPDATE_OFFERING_MUTATION = `
+  mutation UpdateMtwServiceOffering($id: ID!, $input: MtwUpdateServiceOfferingInput!) {
+    updateServiceOffering(id: $id, input: $input) {
+      ${OFFERING_FIELDS}
+    }
+  }
+`;
+
+const DELETE_OFFERING_MUTATION = `
+  mutation DeleteMtwServiceOffering($id: ID!) {
+    deleteServiceOffering(id: $id)
+  }
+`;
+
+const ASSIGN_SHIPMENT_MUTATION = `
+  mutation AssignMtwShipmentServiceProvider($shipmentId: ID!, $providerId: ID) {
+    assignShipmentServiceProvider(shipmentId: $shipmentId, providerId: $providerId) {
+      id
+      shipmentNumber
+      carrierId
+    }
+  }
+`;
+
+function readContact(value: unknown): ProviderContact {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const record = value as Record<string, unknown>;
+  const pick = (key: string) =>
+    typeof record[key] === 'string' && (record[key] as string).trim()
+      ? (record[key] as string)
+      : undefined;
+  return {
+    contactName: pick('contactName'),
+    email: pick('email'),
+    phone: pick('phone'),
+    website: pick('website'),
+  };
+}
+
+function mapProvider(provider: ApiProvider): ServiceProvider {
+  return {
+    id: provider.id,
+    name: provider.name,
+    type: provider.type,
+    description: provider.description ?? null,
+    rating: provider.rating ?? null,
+    contact: readContact(provider.contactInfo),
+    services: provider.services,
+    serviceAreas: provider.serviceAreas,
+    isVerified: provider.isVerified,
+    isActive: provider.isActive,
+    offeringsCount: provider.offeringsCount,
+    createdAt: provider.createdAt,
+  };
+}
+
+function useGraphQLOptions() {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  return useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+}
+
+function toError(error: unknown, fallback: string): Error {
+  return error instanceof Error ? error : new Error(fallback);
+}
+
+export function useServiceProviders(options: {
+  filters: ProviderFilters;
+  limit: number;
+  offset: number;
+}) {
+  const graphQLOptions = useGraphQLOptions();
+  const { limit, offset } = options;
+  const { search, type, isVerified } = options.filters;
+  const [providers, setProviders] = useState<ServiceProvider[]>([]);
+  const [total, setTotal] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const load = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await executeGraphQL<{
+        serviceProviders: ApiProvider[];
+        serviceProvidersCount: number;
+      }>(graphQLOptions, LIST_PROVIDERS_QUERY, {
+        filter: {
+          search: search?.trim() || undefined,
+          type,
+          isVerified,
+        },
+        pagination: { limit, offset },
+      });
+      setProviders(data.serviceProviders.map(mapProvider));
+      setTotal(data.serviceProvidersCount);
+    } catch (loadError) {
+      setError(toError(loadError, 'Failed to load service providers'));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [graphQLOptions, search, type, isVerified, limit, offset]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  return { providers, total, isLoading, error, refetch: load };
+}
+
+export function useMarketplaceStats(refreshKey: number) {
+  const graphQLOptions = useGraphQLOptions();
+  const [stats, setStats] = useState<MarketplaceStats | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    executeGraphQL<{ marketplaceStats: MarketplaceStats }>(graphQLOptions, MARKETPLACE_STATS_QUERY)
+      .then((data) => {
+        if (!cancelled) setStats(data.marketplaceStats);
+      })
+      .catch(() => {
+        // Tiles fall back to "—"; the directory itself reports load errors.
+        if (!cancelled) setStats(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [graphQLOptions, refreshKey]);
+
+  return stats;
+}
+
+export function useProviderOfferings(providerId: string | null, refreshKey: number) {
+  const graphQLOptions = useGraphQLOptions();
+  const [offerings, setOfferings] = useState<ServiceOffering[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!providerId) {
+      setOfferings([]);
+      return;
+    }
+    let cancelled = false;
+    setIsLoading(true);
+    setError(null);
+    executeGraphQL<{ serviceOfferings: ServiceOffering[] }>(graphQLOptions, LIST_OFFERINGS_QUERY, {
+      filter: { providerId },
+      pagination: { limit: 100, offset: 0 },
+    })
+      .then((data) => {
+        if (!cancelled) setOfferings(data.serviceOfferings);
+      })
+      .catch((loadError: unknown) => {
+        if (!cancelled) setError(toError(loadError, 'Failed to load offerings'));
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [graphQLOptions, providerId, refreshKey]);
+
+  return { offerings, isLoading, error };
+}
+
+export interface ShipmentOption {
+  id: string;
+  shipmentNumber: string;
+  status: string;
+}
+
+/** Shipments, optionally only those whose carrier is the given provider. */
+export function useShipmentOptions(options: {
+  search?: string;
+  carrierId?: string;
+  limit: number;
+}) {
+  const graphQLOptions = useGraphQLOptions();
+  const { search, carrierId, limit } = options;
+  const [shipments, setShipments] = useState<ShipmentOption[]>([]);
+  const [total, setTotal] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const load = useCallback(async () => {
+    setIsLoading(true);
+    try {
+      const data = await executeGraphQL<{ shipments: ShipmentOption[]; shipmentsCount: number }>(
+        graphQLOptions,
+        PROVIDER_SHIPMENTS_QUERY,
+        {
+          filter: { search: search?.trim() || undefined, carrierId },
+          pagination: { limit, offset: 0 },
+        }
+      );
+      setShipments(data.shipments);
+      setTotal(data.shipmentsCount);
+    } catch {
+      setShipments([]);
+      setTotal(0);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [graphQLOptions, search, carrierId, limit]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  return { shipments, total, isLoading, refetch: load };
+}
+
+export function useMarketplaceActions() {
+  const graphQLOptions = useGraphQLOptions();
+
+  return useMemo(
+    () => ({
+      createProvider: async (input: ProviderInput) => {
+        const data = await executeGraphQL<{ createServiceProvider: ApiProvider }>(
+          graphQLOptions,
+          CREATE_PROVIDER_MUTATION,
+          { input }
+        );
+        return mapProvider(data.createServiceProvider);
+      },
+      updateProvider: async (id: string, input: Partial<ProviderInput>) => {
+        const data = await executeGraphQL<{ updateServiceProvider: ApiProvider }>(
+          graphQLOptions,
+          UPDATE_PROVIDER_MUTATION,
+          { id, input }
+        );
+        return mapProvider(data.updateServiceProvider);
+      },
+      deleteProvider: async (id: string) => {
+        const data = await executeGraphQL<{ deleteServiceProvider: boolean }>(
+          graphQLOptions,
+          DELETE_PROVIDER_MUTATION,
+          { id }
+        );
+        return data.deleteServiceProvider;
+      },
+      createOffering: async (providerId: string, input: OfferingInput) => {
+        const data = await executeGraphQL<{ createServiceOffering: ServiceOffering }>(
+          graphQLOptions,
+          CREATE_OFFERING_MUTATION,
+          { input: { ...input, providerId } }
+        );
+        return data.createServiceOffering;
+      },
+      updateOffering: async (id: string, input: Partial<OfferingInput>) => {
+        const data = await executeGraphQL<{ updateServiceOffering: ServiceOffering }>(
+          graphQLOptions,
+          UPDATE_OFFERING_MUTATION,
+          { id, input }
+        );
+        return data.updateServiceOffering;
+      },
+      deleteOffering: async (id: string) => {
+        const data = await executeGraphQL<{ deleteServiceOffering: boolean }>(
+          graphQLOptions,
+          DELETE_OFFERING_MUTATION,
+          { id }
+        );
+        return data.deleteServiceOffering;
+      },
+      assignShipment: async (shipmentId: string, providerId: string | null) => {
+        const data = await executeGraphQL<{
+          assignShipmentServiceProvider: {
+            id: string;
+            shipmentNumber: string;
+            carrierId: string | null;
+          };
+        }>(graphQLOptions, ASSIGN_SHIPMENT_MUTATION, { shipmentId, providerId });
+        return data.assignShipmentServiceProvider;
+      },
+    }),
+    [graphQLOptions]
+  );
+}

package/src/movethewheels/pages/CustomersPage.tsx

@@ -15,10 +15,18 @@ import { useDebouncedValue } from '../hooks/useDebouncedValue';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatDate } from '../utils/formatters';
 import { joinPath } from '../utils/navigation';
+import { useEntityExport } from '../hooks/useEntityExport';
+import { ExportStatusBanner } from '../components/ExportStatusBanner';
 import type { Customer } from '../types';
 
 export default function CustomersPage() {
   const { basePath, navigate } = useMoveTheWheels();
+  const {
+    state: exportState,
+    isExporting,
+    startExport,
+    dismiss: dismissExport,
+  } = useEntityExport('customers', 'customer');
   const [page, setPage] = useState(0);
   const [pageSize, setPageSize] = useState(25);
   const [search, setSearch] = useState('');
@@ -104,9 +112,9 @@ export default function CustomersPage() {
           actions={[
             { label: 'Refresh', icon: <RefreshCw size={16} />, onSelect: () => refetch() },
             {
-              label: 'Export',
+              label: isExporting ? 'Exporting…' : 'Export',
               icon: <Download size={16} />,
-              onSelect: () => goTo('import-export'),
+              onSelect: startExport,
             },
           ]}
         />
@@ -117,6 +125,7 @@ export default function CustomersPage() {
         satisfaction ratings here, and open a customer to see their order history before booking the
         next shipment.
       </PagePurpose>
+      <ExportStatusBanner state={exportState} onDismiss={dismissExport} />
 
       {/* Customer base at a glance — premium stat cards */}
       <div>