@burdenoff/microfe-movethewheels 2026.1031.2 → 2026.1031.4

package/dist/utils/moduleSettings.js

@@ -0,0 +1,132 @@
+function e(e = "") {
+	return {
+		workspaceId: e,
+		defaultCurrency: "USD",
+		distanceUnit: "KM",
+		weightUnit: "KG",
+		timezone: null,
+		defaultOrderPriority: "MEDIUM",
+		defaultDeliveryWindowHours: 24,
+		isCustomized: !1,
+		updatedAt: null,
+		updatedBy: null
+	};
+}
+var t = "\n  workspaceId\n  defaultCurrency\n  distanceUnit\n  weightUnit\n  timezone\n  defaultOrderPriority\n  defaultDeliveryWindowHours\n  isCustomized\n  updatedAt\n  updatedBy\n", n = `
+  query MtwModuleSettings {
+    mtwModuleSettings {
+      ${t}
+    }
+  }
+`, r = `
+  mutation UpdateMtwModuleSettings($input: UpdateMtwModuleSettingsInput!) {
+    updateMtwModuleSettings(input: $input) {
+      ${t}
+    }
+  }
+`;
+function i(e) {
+	return {
+		currency: e.defaultCurrency,
+		distanceUnit: e.distanceUnit,
+		weightUnit: e.weightUnit,
+		timeZone: e.timezone
+	};
+}
+var a = [{
+	value: "KM",
+	label: "Kilometres (km)"
+}, {
+	value: "MI",
+	label: "Miles (mi)"
+}], o = [{
+	value: "KG",
+	label: "Kilograms (kg)"
+}, {
+	value: "LB",
+	label: "Pounds (lb)"
+}], s = [
+	{
+		value: "LOW",
+		label: "Low"
+	},
+	{
+		value: "MEDIUM",
+		label: "Normal"
+	},
+	{
+		value: "HIGH",
+		label: "High"
+	},
+	{
+		value: "URGENT",
+		label: "Urgent"
+	},
+	{
+		value: "CRITICAL",
+		label: "Critical"
+	}
+];
+function c(e) {
+	switch (e) {
+		case "LOW": return "low";
+		case "HIGH": return "high";
+		case "URGENT":
+		case "CRITICAL": return "urgent";
+		default: return "normal";
+	}
+}
+var l = [
+	"USD",
+	"EUR",
+	"GBP",
+	"INR",
+	"AED",
+	"SGD",
+	"AUD",
+	"CAD",
+	"JPY",
+	"CNY"
+];
+function u(e) {
+	return typeof Intl.supportedValuesOf == "function" ? Intl.supportedValuesOf(e) : [];
+}
+function d(e) {
+	let t = new Set([...l, ...u("currency")]);
+	e && t.add(e);
+	let n = [...t].filter((e) => !l.includes(e)).sort();
+	return [...l, ...n];
+}
+function f(e) {
+	try {
+		let t = new Intl.DisplayNames(["en"], { type: "currency" }).of(e);
+		return t && t !== e ? `${e} — ${t}` : e;
+	} catch {
+		return e;
+	}
+}
+function p(e) {
+	let t = new Set(["UTC", ...u("timeZone")]);
+	return e && t.add(e), [...t].sort((e, t) => e === "UTC" ? -1 : t === "UTC" ? 1 : e.localeCompare(t));
+}
+function m() {
+	try {
+		return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+	} catch {
+		return "UTC";
+	}
+}
+function h(e) {
+	let t = Number(e);
+	return !e.trim() || !Number.isInteger(t) || t < 1 || t > 720 ? "Enter a whole number of hours between 1 and 720." : null;
+}
+function g(e, t) {
+	let n = {};
+	return t.defaultCurrency !== void 0 && t.defaultCurrency !== e.defaultCurrency && (n.defaultCurrency = t.defaultCurrency), t.distanceUnit !== void 0 && t.distanceUnit !== e.distanceUnit && (n.distanceUnit = t.distanceUnit), t.weightUnit !== void 0 && t.weightUnit !== e.weightUnit && (n.weightUnit = t.weightUnit), t.timezone !== void 0 && t.timezone !== e.timezone && (n.timezone = t.timezone), t.defaultOrderPriority !== void 0 && t.defaultOrderPriority !== e.defaultOrderPriority && (n.defaultOrderPriority = t.defaultOrderPriority), t.defaultDeliveryWindowHours !== void 0 && t.defaultDeliveryWindowHours !== e.defaultDeliveryWindowHours && (n.defaultDeliveryWindowHours = t.defaultDeliveryWindowHours), n;
+}
+function _(e, t = /* @__PURE__ */ new Date()) {
+	let n = new Date(t.getTime() + e * 3600 * 1e3), r = (e) => String(e).padStart(2, "0");
+	return `${n.getFullYear()}-${r(n.getMonth() + 1)}-${r(n.getDate())}T${r(n.getHours())}:${r(n.getMinutes())}`;
+}
+//#endregion
+export { a as DISTANCE_UNIT_OPTIONS, n as MTW_MODULE_SETTINGS_QUERY, s as ORDER_PRIORITY_OPTIONS, r as UPDATE_MTW_MODULE_SETTINGS_MUTATION, o as WEIGHT_UNIT_OPTIONS, m as browserTimeZone, g as changedSettings, f as currencyLabel, d as currencyOptions, h as deliveryWindowError, _ as deliveryWindowValue, c as orderFormPriority, e as platformDefaults, p as timeZoneOptions, i as toFormatPreferences };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burdenoff/microfe-movethewheels",
-  "version": "2026.1031.2",
+  "version": "2026.1031.4",
   "description": "Burdenoff MoveTheWheels Microfrontend - Logistics & Supply Chain Management Platform",
   "type": "module",
   "files": [
@@ -37,7 +37,7 @@
     "format": "prettier --write \"src/**/*.{ts,tsx}\"",
     "type:check": "bash scripts/build-limits.sh tsc --noEmit",
     "validate:schema-drift": "graphql-schema-drift",
-    "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run codegen && bun run validate:schema-drift && bun run lint:sanity && bun run format && bun run type:check && bun run verify:live-logistics-contract && bun run verify:empty-reuse-retry && bun run verify:empty-reuse-recovery && bun run verify:trip-utilization-input && bun run verify:trip-draft-context && bun run verify:stock-binding-input && bun run verify:stock-observation-input && bun run verify:pending-pick-input && bun run verify:pick-review-ack && bun run verify:driver-license-expiry && bun run verify:tracking-alerts && bun run verify:freight-input && bun run verify:freight-recovery && bun run verify:freight-commercial && bun run verify:freight-invoice && bun run verify:procedure-input && bun run verify:consolidation && bun run verify:multimodal-single-attempt && bun run verify:workspace-predispatch && bun run verify:tracking-quality-outcomes && bun run verify:shipment-status-authority && bun run verify:free-time-permissions && bun run verify:core-codegen && bun run verify:order-vehicle-hold && bun run verify:pallet-preview && bun run verify:entity-export && bun run verify:consumed-fuel-preview && bun run build && bun run build-storybook'",
+    "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run codegen && bun run validate:schema-drift && bun run lint:sanity && bun run format && bun run type:check && bun run verify:live-logistics-contract && bun run verify:empty-reuse-retry && bun run verify:empty-reuse-recovery && bun run verify:trip-utilization-input && bun run verify:trip-draft-context && bun run verify:stock-binding-input && bun run verify:stock-observation-input && bun run verify:pending-pick-input && bun run verify:pick-review-ack && bun run verify:driver-license-expiry && bun run verify:tracking-alerts && bun run verify:freight-input && bun run verify:freight-recovery && bun run verify:freight-commercial && bun run verify:freight-invoice && bun run verify:procedure-input && bun run verify:consolidation && bun run verify:multimodal-single-attempt && bun run verify:workspace-predispatch && bun run verify:tracking-quality-outcomes && bun run verify:shipment-status-authority && bun run verify:free-time-permissions && bun run verify:core-codegen && bun run verify:order-vehicle-hold && bun run verify:pallet-preview && bun run verify:entity-export && bun run verify:entity-import && bun run verify:module-settings && bun run verify:consumed-fuel-preview && bun run build && bun run build-storybook'",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "test:storybook": "vitest run --project=storybook",
@@ -73,6 +73,8 @@
     "verify:tracking-alerts": "bun test scripts/check-tracking-alerts.test.ts",
     "verify:core-codegen": "bun test scripts/codegen.test.ts && node --test scripts/check-package-types.test.mjs",
     "verify:entity-export": "bun test scripts/check-entity-export.test.ts",
+    "verify:entity-import": "bun test scripts/check-entity-import.test.ts",
+    "verify:module-settings": "bun test scripts/check-module-settings.test.ts",
     "verify:pallet-preview": "bun test scripts/check-pallet-preview.test.ts && bun scripts/verify-pallet-preview-hook.mjs",
     "verify:consumed-fuel-preview": "bun test scripts/check-consumed-fuel-preview.test.ts && bun scripts/verify-consumed-fuel-preview-hook.mjs && bun scripts/verify-consumed-fuel-preview-component.mjs"
   },

package/src/generated/tracking-quality-operations.ts

@@ -1259,6 +1259,13 @@ export type MtwDemandForecastVariance = {
   volumeVariance: Scalars['Int']['output'];
 };
 
+/** Unit MoveTheWheels shows distances in. */
+export type MtwDistanceUnit =
+  /** Kilometres */
+  | 'KM'
+  /** Miles */
+  | 'MI';
+
 export type MtwDriver = {
   __typename?: 'MtwDriver';
   baseSalary?: Maybe<Scalars['Float']['output']>;
@@ -2443,6 +2450,91 @@ export type MtwFuelVolumeObservationInput = {
   sourceRevision?: InputMaybe<Scalars['String']['input']>;
 };
 
+export type MtwImportColumn = {
+  __typename?: 'MtwImportColumn';
+  allowedValues?: Maybe<Array<Scalars['String']['output']>>;
+  description: Scalars['String']['output'];
+  max?: Maybe<Scalars['Float']['output']>;
+  maxLength?: Maybe<Scalars['Int']['output']>;
+  min?: Maybe<Scalars['Float']['output']>;
+  name: Scalars['String']['output'];
+  required: Scalars['Boolean']['output'];
+  type: MtwImportColumnType;
+};
+
+export type MtwImportColumnType =
+  | 'BOOLEAN'
+  | 'DATE'
+  | 'EMAIL'
+  | 'ENUM'
+  | 'INTEGER'
+  | 'JSON'
+  | 'NUMBER'
+  | 'STRING';
+
+export type MtwImportEntitySpec = {
+  __typename?: 'MtwImportEntitySpec';
+  columns: Array<MtwImportColumn>;
+  entityType: MtwImportEntityType;
+  /** Column that must be unique in the workspace, if any. */
+  keyColumn?: Maybe<Scalars['String']['output']>;
+};
+
+export type MtwImportEntityType =
+  | 'CARGO_ITEM'
+  | 'CUSTOMER'
+  | 'DRIVER'
+  | 'VEHICLE'
+  | 'WAREHOUSE';
+
+export type MtwImportFormat =
+  | 'CSV'
+  | 'JSON';
+
+export type MtwImportInput = {
+  /** Import the valid rows even when other rows are invalid. */
+  allowPartial?: InputMaybe<Scalars['Boolean']['input']>;
+  /** The CSV (with a header row) or JSON (array of objects) document, at most 2 MB and 1000 rows. */
+  content: Scalars['String']['input'];
+  /** Validate every row without writing anything. */
+  dryRun?: InputMaybe<Scalars['Boolean']['input']>;
+  format: MtwImportFormat;
+};
+
+export type MtwImportResult = {
+  __typename?: 'MtwImportResult';
+  createdIds: Array<Scalars['ID']['output']>;
+  dryRun: Scalars['Boolean']['output'];
+  entityType: MtwImportEntityType;
+  errors: Array<MtwImportRowError>;
+  /** True when more row errors exist than are returned (the first 500 are returned). */
+  errorsTruncated: Scalars['Boolean']['output'];
+  failedRows: Scalars['Int']['output'];
+  importedRows: Scalars['Int']['output'];
+  status: MtwImportStatus;
+  totalRows: Scalars['Int']['output'];
+  validRows: Scalars['Int']['output'];
+};
+
+export type MtwImportRowError = {
+  __typename?: 'MtwImportRowError';
+  field?: Maybe<Scalars['String']['output']>;
+  message: Scalars['String']['output'];
+  /** 1-based data row number (the CSV header is not counted). */
+  row: Scalars['Int']['output'];
+};
+
+/**
+ * DRY_RUN: validated only, nothing written. COMPLETED: every row imported.
+ * PARTIAL: allowPartial was set and some rows failed. REJECTED: some rows were
+ * invalid and allowPartial was not set, so nothing was written.
+ */
+export type MtwImportStatus =
+  | 'COMPLETED'
+  | 'DRY_RUN'
+  | 'PARTIAL'
+  | 'REJECTED';
+
 /** A recorded manual issuer review; workspace privileges do not establish professional qualifications. */
 export type MtwInspectorQualification = {
   __typename?: 'MtwInspectorQualification';
@@ -2615,6 +2707,31 @@ export type MtwMarketplaceStats = {
   verifiedProviders: Scalars['Int']['output'];
 };
 
+/**
+ * Workspace operational defaults for MoveTheWheels (BOFF-10488): how amounts,
+ * distances, weights and times are shown, and what new orders start from.
+ * Company profile, notifications, two-factor authentication and integrations
+ * are platform settings and are not part of this type.
+ */
+export type MtwModuleSettings = {
+  __typename?: 'MtwModuleSettings';
+  /** ISO 4217 code amounts without their own currency are shown in. */
+  defaultCurrency: Scalars['String']['output'];
+  /** Hours from now a new order's suggested delivery time falls (1 to 720). */
+  defaultDeliveryWindowHours: Scalars['Int']['output'];
+  /** Priority a new order starts with. */
+  defaultOrderPriority: DeliveryPriority;
+  distanceUnit: MtwDistanceUnit;
+  /** False until the workspace saves its settings; the values are then the platform defaults. */
+  isCustomized: Scalars['Boolean']['output'];
+  /** IANA time zone dates and times are shown in. Null shows each viewer their own local time. */
+  timezone?: Maybe<Scalars['String']['output']>;
+  updatedAt?: Maybe<Scalars['DateTime']['output']>;
+  updatedBy?: Maybe<Scalars['ID']['output']>;
+  weightUnit: MtwWeightUnit;
+  workspaceId: Scalars['ID']['output'];
+};
+
 export type MtwMoveReviewSource = {
   __typename?: 'MtwMoveReviewSource';
   reference: Scalars['String']['output'];
@@ -4467,6 +4584,13 @@ export type MtwWarehouseStats = {
   total: Scalars['Int']['output'];
 };
 
+/** Unit MoveTheWheels shows weights in. */
+export type MtwWeightUnit =
+  /** Kilograms */
+  | 'KG'
+  /** Pounds */
+  | 'LB';
+
 export type Mutation = {
   __typename?: 'Mutation';
   _empty?: Maybe<Scalars['String']['output']>;
@@ -4523,6 +4647,11 @@ export type Mutation = {
   deleteWarehouse: Scalars['Boolean']['output'];
   exportMtwEntities: MtwExportJob;
   holdMtwContainer: MtwContainerHold;
+  importMtwCargoItems: MtwImportResult;
+  importMtwCustomers: MtwImportResult;
+  importMtwDrivers: MtwImportResult;
+  importMtwVehicles: MtwImportResult;
+  importMtwWarehouses: MtwImportResult;
   openMtwContainerCycle: MtwContainerCycle;
   openMtwFreeTimeClock: MtwFreeTimeClock;
   optimizeRoute: MtwRoute;
@@ -4568,6 +4697,8 @@ export type Mutation = {
   updateDriverStatus: MtwDriver;
   updateIntegration: MtwIntegration;
   updateInventoryItem: MtwInventoryItem;
+  /** Save the workspace's MoveTheWheels operational defaults. Every field is validated. */
+  updateMtwModuleSettings: MtwModuleSettings;
   updateRoute: MtwRoute;
   updateServiceOffering: MtwServiceOffering;
   updateServiceProvider: MtwServiceProvider;
@@ -4791,6 +4922,31 @@ export type MutationHoldMtwContainerArgs = {
 };
 
 
+export type MutationImportMtwCargoItemsArgs = {
+  input: MtwImportInput;
+};
+
+
+export type MutationImportMtwCustomersArgs = {
+  input: MtwImportInput;
+};
+
+
+export type MutationImportMtwDriversArgs = {
+  input: MtwImportInput;
+};
+
+
+export type MutationImportMtwVehiclesArgs = {
+  input: MtwImportInput;
+};
+
+
+export type MutationImportMtwWarehousesArgs = {
+  input: MtwImportInput;
+};
+
+
 export type MutationOpenMtwContainerCycleArgs = {
   input: OpenMtwContainerCycleInput;
 };
@@ -5026,6 +5182,11 @@ export type MutationUpdateInventoryItemArgs = {
 };
 
 
+export type MutationUpdateMtwModuleSettingsArgs = {
+  input: UpdateMtwModuleSettingsInput;
+};
+
+
 export type MutationUpdateRouteArgs = {
   id: Scalars['ID']['input'];
   input: UpdateRouteInput;
@@ -5253,6 +5414,15 @@ export type Query = {
   /** Null is not proof of no effect and never authorizes resubmission. Exact original actor/context only. */
   mtwFreightInvoiceComparisonByRequestKey?: Maybe<MtwFreightInvoiceComparison>;
   mtwFreightInvoiceComparisonPage: MtwFreightInvoiceComparisonPage;
+  /**
+   * Columns accepted by each import, for building templates and showing guidance.
+   * This is static reference metadata with no workspace data in it, so it only
+   * needs an authenticated caller; every import mutation enforces its own
+   * entity create permission.
+   */
+  mtwImportSpec: Array<MtwImportEntitySpec>;
+  /** The workspace's MoveTheWheels operational defaults; platform defaults when none were saved. */
+  mtwModuleSettings: MtwModuleSettings;
   mtwPalletGeometryPreview: MtwPalletGeometryPreview;
   mtwPickPreparation: MtwPickPreparation;
   mtwPickReview: MtwPickReview;
@@ -6525,6 +6695,20 @@ export type UpdateInventoryItemInput = {
   unitCost?: InputMaybe<Scalars['Float']['input']>;
 };
 
+/**
+ * Changes to the workspace's MoveTheWheels defaults. Omitted fields keep their
+ * current value. `timezone: null` (or an empty string) clears the time zone so
+ * each viewer sees their own local time.
+ */
+export type UpdateMtwModuleSettingsInput = {
+  defaultCurrency?: InputMaybe<Scalars['String']['input']>;
+  defaultDeliveryWindowHours?: InputMaybe<Scalars['Int']['input']>;
+  defaultOrderPriority?: InputMaybe<DeliveryPriority>;
+  distanceUnit?: InputMaybe<MtwDistanceUnit>;
+  timezone?: InputMaybe<Scalars['String']['input']>;
+  weightUnit?: InputMaybe<MtwWeightUnit>;
+};
+
 export type UpdateRouteInput = {
   actualDistance?: InputMaybe<Scalars['Float']['input']>;
   actualDuration?: InputMaybe<Scalars['Float']['input']>;

package/src/movethewheels/MoveTheWheelsRoot.tsx

@@ -23,8 +23,11 @@ import {
   DollarSign,
   Bot,
   Store,
+  ArrowDownUp,
+  Settings,
 } from 'lucide-react';
 import { MoveTheWheelsProvider } from './providers/MoveTheWheelsProvider';
+import { ModuleSettingsProvider } from './providers/ModuleSettingsProvider';
 import { FeatureFlagProvider } from '@burdenoff/fe-libs/shared/feature-flags';
 import type { NavItem, MoveTheWheelsRootProps } from './types';
 import { MoveTheWheelsRoutes } from './MoveTheWheelsRoutes';
@@ -241,6 +244,13 @@ const NavRegistrar: FC<Pick<MoveTheWheelsRootProps, 'registerNavItems' | 'basePa
           icon: <Store size={16} />,
           order: 6,
         },
+        {
+          id: 'mtw-import-export',
+          label: tr('movethewheels.root.nav.importExport', 'Import / Export'),
+          path: joinPath(basePath, 'import-export'),
+          icon: <ArrowDownUp size={16} />,
+          order: 6,
+        },
         {
           id: 'mtw-routes',
           label: tr('movethewheels.root.nav.routes', 'Routes'),
@@ -297,6 +307,13 @@ const NavRegistrar: FC<Pick<MoveTheWheelsRootProps, 'registerNavItems' | 'basePa
           icon: <Bot size={16} />,
           order: 13,
         },
+        {
+          id: 'mtw-settings',
+          label: tr('movethewheels.root.nav.settings', 'Settings'),
+          path: joinPath(basePath, 'settings'),
+          icon: <Settings size={16} />,
+          order: 99,
+        },
       ],
     };
 
@@ -357,9 +374,11 @@ export const MoveTheWheelsRoot: FC<MoveTheWheelsRootProps> = (props) => {
     <FeatureFlagProvider workspaceId={null} gateway="global" defaultEnabled={true}>
       <NavRegistrar registerNavItems={registerNavItems} basePath={basePath} />
       <MoveTheWheelsProvider {...props}>
-        <div className="movethewheels-root h-full">
-          <MoveTheWheelsRoutes />
-        </div>
+        <ModuleSettingsProvider>
+          <div className="movethewheels-root h-full">
+            <MoveTheWheelsRoutes />
+          </div>
+        </ModuleSettingsProvider>
       </MoveTheWheelsProvider>
     </FeatureFlagProvider>
   );

package/src/movethewheels/MoveTheWheelsRoutes.tsx

@@ -9,6 +9,7 @@ import { Routes, Route, useNavigate } from 'react-router';
 import { lazy, Suspense } from 'react';
 import { NotFoundPage } from '@burdenoff/fe-libs/shared/pages';
 import { useMoveTheWheels } from './providers/MoveTheWheelsProvider';
+import { useModuleSettings } from './providers/ModuleSettingsProvider';
 import { useTr } from './hooks';
 
 /**
@@ -72,6 +73,8 @@ const WarehouseDetailsPage = lazy(() => import('./pages/WarehouseDetailsPage'));
 const CustomersPage = lazy(() => import('./pages/CustomersPage'));
 const CustomerDetailsPage = lazy(() => import('./pages/CustomerDetailsPage'));
 const MarketplacePage = lazy(() => import('./pages/MarketplacePage'));
+const ImportExportPage = lazy(() => import('./pages/ImportExportPage'));
+const SettingsPage = lazy(() => import('./pages/SettingsPage'));
 const RoutesPage = lazy(() => import('./pages/RoutesPage'));
 const RouteDetailsPage = lazy(() => import('./pages/RouteDetailsPage'));
 const AnalyticsPage = lazy(() => import('./pages/AnalyticsPage'));
@@ -95,6 +98,10 @@ const ConsumedFuelPreviewPage = lazy(() => import('./pages/ConsumedFuelPreviewPa
 const EmptyReusePage = lazy(() => import('./pages/EmptyReusePage'));
 
 export function MoveTheWheelsRoutes() {
+  // Subscribing here re-renders every page when the workspace's display
+  // defaults load or change, so amounts, units and dates follow them
+  // (BOFF-10488). The value itself is read through the shared formatters.
+  useModuleSettings();
   return (
     <Suspense fallback={<PageLoader />}>
       <Routes>
@@ -160,6 +167,12 @@ export function MoveTheWheelsRoutes() {
         {/* Marketplace — service providers and offerings (BOFF-3988) */}
         <Route path="marketplace" element={<MarketplacePage />} />
 
+        {/* Bulk CSV/JSON import and dataset export (BOFF-3990) */}
+        <Route path="import-export" element={<ImportExportPage />} />
+
+        {/* Workspace operational defaults: currency, units, time zone (BOFF-10488) */}
+        <Route path="settings" element={<SettingsPage />} />
+
         {/* Routes */}
         <Route path="routes" element={<RoutesPage />} />
         <Route path="routes/trip-utilization" element={<TripUtilizationPage />} />

package/src/movethewheels/hooks/useEntityImport.ts

@@ -0,0 +1,108 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+import {
+  MTW_IMPORT_MAX_BYTES,
+  MTW_IMPORT_SPEC_QUERY,
+  importEntity,
+  importMutation,
+  type MtwImportEntitySpec,
+  type MtwImportEntityType,
+  type MtwImportFormat,
+  type MtwImportResult,
+} from '../utils/entityImport';
+
+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]
+  );
+}
+
+/** Column specification for every importable entity. */
+export function useImportSpec() {
+  const graphQLOptions = useGraphQLOptions();
+  const [specs, setSpecs] = useState<MtwImportEntitySpec[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!graphQLOptions.workspaceId) return;
+    let cancelled = false;
+    setIsLoading(true);
+    executeGraphQL<{ mtwImportSpec: MtwImportEntitySpec[] }>(graphQLOptions, MTW_IMPORT_SPEC_QUERY)
+      .then((data) => {
+        if (cancelled) return;
+        setSpecs(data.mtwImportSpec);
+        setError(null);
+      })
+      .catch((caught: unknown) => {
+        if (!cancelled)
+          setError(caught instanceof Error ? caught : new Error('Could not load import columns'));
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [graphQLOptions]);
+
+  return { specs, isLoading, error };
+}
+
+export interface ImportRequest {
+  entityType: MtwImportEntityType;
+  format: MtwImportFormat;
+  content: string;
+  dryRun: boolean;
+  allowPartial: boolean;
+}
+
+/** Runs a validation or an import. Writes are sent once: a retry could create rows twice. */
+export function useEntityImport() {
+  const graphQLOptions = useGraphQLOptions();
+  const [isRunning, setIsRunning] = useState(false);
+
+  const run = useCallback(
+    async (request: ImportRequest): Promise<MtwImportResult> => {
+      if (new Blob([request.content]).size > MTW_IMPORT_MAX_BYTES) {
+        throw new Error('The file is larger than 2 MB. Split it into smaller files.');
+      }
+      const { field } = importEntity(request.entityType);
+      setIsRunning(true);
+      try {
+        const data = await executeGraphQL<Record<string, MtwImportResult>>(
+          graphQLOptions,
+          importMutation(request.entityType),
+          {
+            input: {
+              format: request.format,
+              content: request.content,
+              dryRun: request.dryRun,
+              allowPartial: request.allowPartial,
+            },
+          },
+          request.dryRun ? 'RETRY_TRANSIENT' : 'SINGLE_ATTEMPT'
+        );
+        const result = data[field];
+        if (!result) throw new Error('The import returned no result');
+        return result;
+      } finally {
+        setIsRunning(false);
+      }
+    },
+    [graphQLOptions]
+  );
+
+  return { run, isRunning };
+}