@burdenoff/microfe-movethewheels 2026.1031.6 → 2026.1101.2

package/src/movethewheels/pages/SettingsPage.tsx

@@ -44,6 +44,7 @@ import {
   Skeleton,
 } from '../components/ui';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { joinPath } from '../utils/navigation';
 import { useModuleSettings } from '../providers/ModuleSettingsProvider';
 import { formatCurrency, formatDateTime, formatDistance, formatWeight } from '../utils/formatters';
 import {
@@ -111,8 +112,8 @@ const PLATFORM_LINKS = [
   },
   {
     id: 'integrations',
-    title: 'Integrations',
-    description: 'Carrier, ERP and telematics connections',
+    title: 'Platform integrations',
+    description: 'ERP, messaging and app connections shared across products',
     path: '/integrations/overview',
     icon: Plug,
   },
@@ -128,7 +129,7 @@ export default function SettingsPage() {
 }
 
 function SettingsWorkbench() {
-  const { navigate, workspaceId, currentUser } = useMoveTheWheels();
+  const { navigate, basePath, workspaceId, currentUser } = useMoveTheWheels();
   const { settings, isLoaded, error: loadError, save, reload } = useModuleSettings();
   const permissions = usePermissions();
   const [draft, setDraft] = useState<Draft>(() => toDraft(settings));
@@ -487,6 +488,21 @@ function SettingsWorkbench() {
               </CardDescription>
             </CardHeader>
             <CardContent className="space-y-2">
+              <button
+                type="button"
+                className="flex w-full items-start gap-3 rounded-lg border border-border-default px-3 py-2 text-left transition-colors hover:bg-surface-secondary"
+                onClick={() => navigate(joinPath(basePath, 'integrations'))}
+              >
+                <Plug size={18} className="mt-0.5 shrink-0 text-text-secondary" />
+                <span className="min-w-0 flex-1">
+                  <span className="block text-sm font-medium text-text-primary">
+                    Tracking integrations
+                  </span>
+                  <span className="block text-xs text-text-secondary">
+                    Carrier, ELD and GPS feeds that update shipments automatically
+                  </span>
+                </span>
+              </button>
               {PLATFORM_LINKS.map((link) => {
                 const Icon = link.icon;
                 return (

package/src/movethewheels/utils/carrierIntegrations.ts

@@ -0,0 +1,252 @@
+/**
+ * Carrier and telematics integrations (BOFF-4404).
+ *
+ * A workspace connects an external carrier, ELD or GPS feed to MoveTheWheels
+ * as a signed webhook. Each delivery is verified with HMAC-SHA256 over the raw
+ * request body using the integration's signing secret, and every accepted
+ * update becomes a tracking event on the matching shipment.
+ *
+ * This module holds the GraphQL documents and the pure helpers the page uses;
+ * the network calls live in `hooks/useCarrierIntegrations`.
+ */
+import { resolveGraphqlUrl } from './graphqlClient';
+
+/** Providers the service can ingest today. Vendor adapters are refused by the API. */
+export const SUPPORTED_PROVIDERS = ['GENERIC_WEBHOOK'] as const;
+export type SupportedProvider = (typeof SUPPORTED_PROVIDERS)[number];
+
+/** Named networks that need a signed vendor agreement before an adapter can ship. */
+export const ROADMAP_PROVIDERS = [
+  { id: 'PROJECT44', label: 'project44' },
+  { id: 'FOURKITES', label: 'FourKites' },
+  { id: 'DESCARTES', label: 'Descartes' },
+] as const;
+
+export const INTEGRATION_STATUSES = ['ACTIVE', 'PAUSED', 'DISABLED'] as const;
+export type IntegrationStatus = (typeof INTEGRATION_STATUSES)[number];
+
+export type IntegrationProvider = 'GENERIC_WEBHOOK' | 'PROJECT44' | 'FOURKITES' | 'DESCARTES';
+
+export type IntegrationEventStatus =
+  'RECEIVED' | 'ACCEPTED' | 'PARTIAL' | 'REJECTED' | 'DUPLICATE' | 'CONFLICT';
+
+/** Tracking event types a delivery may carry (the service's TrackingEventType). */
+export const TRACKING_EVENT_TYPES = [
+  'CREATED',
+  'PICKED_UP',
+  'IN_TRANSIT',
+  'ARRIVED',
+  'DEPARTED',
+  'OUT_FOR_DELIVERY',
+  'DELIVERED',
+  'FAILED',
+  'RETURNED',
+] as const;
+
+/** The service refuses shorter secrets; the generator always produces 64 hex characters. */
+export const MIN_SECRET_LENGTH = 32;
+
+/** Header the workspace gateway forwards; custom headers do not survive the gateway. */
+export const SIGNATURE_HEADER = 'x-webhook-signature';
+
+/** Updates accepted in one delivery (a JSON array of at most this many objects). */
+export const MAX_UPDATES_PER_DELIVERY = 5;
+
+export interface CarrierIntegration {
+  id: string;
+  workspaceId: string;
+  provider: IntegrationProvider;
+  name: string;
+  status: IntegrationStatus;
+  lastSyncAt: string | null;
+  lastErrorAt: string | null;
+  lastErrorMessage: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CarrierIntegrationEvent {
+  id: string;
+  integrationId: string;
+  externalEventId: string | null;
+  shipmentId: string | null;
+  eventType: string | null;
+  status: IntegrationEventStatus;
+  errorMessage: string | null;
+  receivedAt: string;
+  processedAt: string | null;
+}
+
+const INTEGRATION_FIELDS = `
+  id
+  workspaceId
+  provider
+  name
+  status
+  lastSyncAt
+  lastErrorAt
+  lastErrorMessage
+  createdAt
+  updatedAt
+`;
+
+export const LIST_INTEGRATIONS_QUERY = `
+  query MtwCarrierIntegrations($filter: IntegrationFilterInput, $pagination: PaginationInput) {
+    integrations(filter: $filter, pagination: $pagination) {
+      ${INTEGRATION_FIELDS}
+    }
+    integrationsCount(filter: $filter)
+  }
+`;
+
+export const INTEGRATION_COUNTS_QUERY = `
+  query MtwCarrierIntegrationCounts {
+    all: integrationsCount
+    active: integrationsCount(filter: { status: ACTIVE })
+  }
+`;
+
+export const INTEGRATION_EVENTS_QUERY = `
+  query MtwCarrierIntegrationEvents($integrationId: ID, $pagination: PaginationInput) {
+    integrationEvents(integrationId: $integrationId, pagination: $pagination) {
+      id
+      integrationId
+      externalEventId
+      shipmentId
+      eventType
+      status
+      errorMessage
+      receivedAt
+      processedAt
+    }
+  }
+`;
+
+export const CREATE_INTEGRATION_MUTATION = `
+  mutation CreateMtwCarrierIntegration($input: CreateIntegrationInput!) {
+    createIntegration(input: $input) {
+      ${INTEGRATION_FIELDS}
+    }
+  }
+`;
+
+export const UPDATE_INTEGRATION_MUTATION = `
+  mutation UpdateMtwCarrierIntegration($id: ID!, $input: UpdateIntegrationInput!) {
+    updateIntegration(id: $id, input: $input) {
+      ${INTEGRATION_FIELDS}
+    }
+  }
+`;
+
+export const DELETE_INTEGRATION_MUTATION = `
+  mutation DeleteMtwCarrierIntegration($id: ID!) {
+    deleteIntegration(id: $id)
+  }
+`;
+
+/** Minimal source of randomness, so tests can supply a deterministic one. */
+export interface RandomSource {
+  getRandomValues<T extends ArrayBufferView>(array: T): T;
+}
+
+/** A fresh 256-bit signing secret as 64 lowercase hex characters. */
+export function generateSigningSecret(random: RandomSource = globalThis.crypto): string {
+  const bytes = random.getRandomValues(new Uint8Array(32));
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/** Returns an error message for an unusable secret, or null when it is fine. */
+export function signingSecretError(secret: string): string | null {
+  if (secret.trim().length < MIN_SECRET_LENGTH) {
+    return `Use a signing secret of at least ${MIN_SECRET_LENGTH} characters.`;
+  }
+  return null;
+}
+
+/** Returns an error message for an unusable name, or null when it is fine. */
+export function integrationNameError(name: string): string | null {
+  const trimmed = name.trim();
+  if (!trimmed) return 'Give the integration a name.';
+  if (trimmed.length > 120) return 'Keep the name under 120 characters.';
+  return null;
+}
+
+/**
+ * The public URL a carrier posts deliveries to. It lives on the same workspace
+ * gateway host the app already talks to: `/api/integrations/webhook/<workspace>/<integration>`.
+ * A relative gateway URL (local development behind the dev proxy) resolves
+ * against `fallbackOrigin`.
+ */
+export function webhookUrl(
+  apiGatewayUrl: string | undefined,
+  workspaceId: string,
+  integrationId: string,
+  fallbackOrigin: string
+): string {
+  const origin = new URL(resolveGraphqlUrl(apiGatewayUrl), fallbackOrigin).origin;
+  return `${origin}/api/integrations/webhook/${workspaceId}/${integrationId}`;
+}
+
+/** An example delivery body for the setup instructions. */
+export function examplePayload(now: Date = new Date()): string {
+  return JSON.stringify(
+    {
+      externalEventId: 'evt_0001',
+      trackingNumber: 'YOUR-TRACKING-NUMBER',
+      eventType: 'IN_TRANSIT',
+      timestamp: now.toISOString().replace(/\.\d{3}Z$/, 'Z'),
+      location: { lat: 12.9716, lng: 77.5946, address: 'Bengaluru hub' },
+      details: 'Departed origin hub',
+    },
+    null,
+    2
+  );
+}
+
+/** Quotes a value for a POSIX shell: single quotes, with embedded ones escaped. */
+export function shellQuote(value: string): string {
+  return `'${value.split("'").join(`'\\''`)}'`;
+}
+
+/**
+ * A copy-paste shell example that signs and sends one delivery. The secret is
+ * referenced as an environment variable so it never appears in the snippet.
+ */
+export function curlExample(url: string): string {
+  return [
+    `BODY='{"externalEventId":"evt_0001","trackingNumber":"YOUR-TRACKING-NUMBER","eventType":"IN_TRANSIT"}'`,
+    `SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$MTW_WEBHOOK_SECRET" -hex | sed 's/^.* //')`,
+    `curl -X POST ${shellQuote(url)} \\`,
+    `  -H 'Content-Type: application/json' \\`,
+    `  -H "${SIGNATURE_HEADER}: sha256=$SIG" \\`,
+    `  --data "$BODY"`,
+  ].join('\n');
+}
+
+/** "OUT_FOR_DELIVERY" → "Out for delivery". */
+export function humanize(value: string): string {
+  const text = value.toLowerCase().split('_').join(' ');
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+export type BadgeTone = 'default' | 'secondary' | 'outline' | 'destructive';
+
+export function integrationStatusTone(status: IntegrationStatus): BadgeTone {
+  if (status === 'ACTIVE') return 'default';
+  if (status === 'PAUSED') return 'secondary';
+  return 'outline';
+}
+
+export function eventStatusTone(status: IntegrationEventStatus): BadgeTone {
+  if (status === 'ACCEPTED') return 'default';
+  if (status === 'DUPLICATE' || status === 'PARTIAL' || status === 'RECEIVED') return 'secondary';
+  return 'destructive';
+}
+
+/** What a webhook sender sees for each status, shown next to the status control. */
+export function statusExplanation(status: IntegrationStatus): string {
+  if (status === 'ACTIVE') return 'Signed deliveries are accepted and become tracking events.';
+  if (status === 'PAUSED')
+    return 'Deliveries are refused with HTTP 423 so the sender can retry after you resume.';
+  return 'Deliveries are refused with HTTP 410. Resume to accept them again.';
+}

package/src/movethewheels/utils/driverNavigation.ts

@@ -0,0 +1,103 @@
+/**
+ * Turn-by-turn navigation hand-off for the driver day view (BOFF-3991).
+ *
+ * The driver app does not embed its own routing engine: it hands the stop
+ * (or the remaining stops, in sequence) to the device's maps app through the
+ * universal Google Maps URL scheme, which opens the native Google Maps / Apple
+ * Maps-compatible handler on Android and iOS and a browser tab on desktop.
+ */
+import type { Address } from '../types';
+import { formatAddress } from './formatters';
+
+const MAPS_DIRECTIONS_BASE = 'https://www.google.com/maps/dir/?api=1';
+
+/**
+ * Google's universal URL accepts at most 9 intermediate waypoints (plus the
+ * destination). Longer days are handed off in chunks: the driver restarts
+ * navigation from the next remaining stop once these are done.
+ */
+export const MAX_NAVIGATION_WAYPOINTS = 9;
+
+/** The best destination string for an address: coordinates when present, else the formatted address. */
+export function navigationDestination(address: Partial<Address> | null | undefined): string | null {
+  if (!address) return null;
+  if (
+    typeof address.latitude === 'number' &&
+    typeof address.longitude === 'number' &&
+    Number.isFinite(address.latitude) &&
+    Number.isFinite(address.longitude)
+  ) {
+    return `${address.latitude},${address.longitude}`;
+  }
+  const formatted = formatAddress(address).trim();
+  return formatted.length > 0 ? formatted : null;
+}
+
+/** Directions from the device's current position to one stop. */
+export function stopNavigationUrl(address: Partial<Address> | null | undefined): string | null {
+  const destination = navigationDestination(address);
+  if (!destination) return null;
+  const params = new URLSearchParams({ destination, travelmode: 'driving' });
+  return `${MAPS_DIRECTIONS_BASE}&${params.toString()}`;
+}
+
+/**
+ * Directions through the remaining stops in sequence: the last stop in the
+ * chunk is the destination, the ones before it are waypoints. Stops without a
+ * usable address are skipped. Returns null when no stop is navigable.
+ */
+export function routeNavigationUrl(
+  addresses: Array<Partial<Address> | null | undefined>
+): string | null {
+  const destinations = addresses
+    .map((address) => navigationDestination(address))
+    .filter((value): value is string => value !== null)
+    .slice(0, MAX_NAVIGATION_WAYPOINTS + 1);
+  if (destinations.length === 0) return null;
+  const destination = destinations[destinations.length - 1];
+  const waypoints = destinations.slice(0, -1);
+  const params = new URLSearchParams({ destination, travelmode: 'driving' });
+  if (waypoints.length > 0) params.set('waypoints', waypoints.join('|'));
+  return `${MAPS_DIRECTIONS_BASE}&${params.toString()}`;
+}
+
+/** A `tel:` link for a phone number, keeping only dialable characters. */
+export function phoneHref(phone: string | null | undefined): string | null {
+  if (!phone) return null;
+  const dialable = phone.replace(/[^\d+]/g, '');
+  return dialable.length >= 3 ? `tel:${dialable}` : null;
+}
+
+/** The device-local calendar date as YYYY-MM-DD (what `myDeliveryDay` expects). */
+export function localDateString(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/** Shift a YYYY-MM-DD date by whole days, staying in local calendar terms. */
+export function shiftLocalDate(date: string, days: number): string {
+  const [year, month, day] = date.split('-').map(Number);
+  return localDateString(new Date(year, month - 1, day + days));
+}
+
+/** The `Date#getTimezoneOffset()` value for local midnight of a YYYY-MM-DD date (DST-correct). */
+export function timezoneOffsetFor(date: string): number {
+  const [year, month, day] = date.split('-').map(Number);
+  return new Date(year, month - 1, day).getTimezoneOffset();
+}
+
+/**
+ * The device's IANA time zone (e.g. `Asia/Kolkata`), so the server can build
+ * the day window from real local midnights, including on DST transition
+ * days. Null when the runtime cannot report one; the fixed offset is then used.
+ */
+export function deviceTimeZone(): string | null {
+  try {
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return typeof zone === 'string' && zone.length > 0 ? zone : null;
+  } catch {
+    return null;
+  }
+}