@burdenoff/microfe-movethewheels 2026.1017.11 → 2026.1017.13

package/src/movethewheels/utils/palletPreviewInput.ts

@@ -0,0 +1,199 @@
+import type {
+  MtwPalletGeometryPreviewInput,
+  MtwPalletMeasurementSourceInput,
+} from '../../generated/pallet-preview-operations';
+
+export interface SourceDraft {
+  reference: string;
+  version: string;
+}
+export interface PackageDraft {
+  key: number;
+  id: string;
+  quantity: string;
+  source: SourceDraft;
+  widthMm: string;
+  lengthMm: string;
+  heightMm: string;
+  grossMassG: string;
+  yaw: 'UNKNOWN' | 'NONE' | '0' | '90' | 'BOTH';
+  upright: 'UNKNOWN' | 'YES' | 'NO';
+}
+export interface PalletPreviewDraft {
+  packages: PackageDraft[];
+  pallet: {
+    source: SourceDraft;
+    widthMm: string;
+    lengthMm: string;
+    heightMm: string;
+    tareMassG: string;
+    maxPayloadMassG: string;
+  };
+  includeEnvelope: boolean;
+  loadEnvelope: {
+    source: SourceDraft;
+    widthMm: string;
+    lengthMm: string;
+    maxHeightMm: string;
+    maxGrossMassG: string;
+  };
+  additionalPacking: { source: SourceDraft; massG: string };
+  clearance: { source: SourceDraft; perimeterMm: string; betweenPackagesMm: string; topMm: string };
+}
+const blankSource = (): SourceDraft => ({ reference: '', version: '' });
+export const newPalletPackage = (key: number): PackageDraft => ({
+  key,
+  id: '',
+  quantity: '',
+  source: blankSource(),
+  widthMm: '',
+  lengthMm: '',
+  heightMm: '',
+  grossMassG: '',
+  yaw: 'UNKNOWN',
+  upright: 'UNKNOWN',
+});
+export function newPalletPreviewDraft(): PalletPreviewDraft {
+  return {
+    packages: [newPalletPackage(1)],
+    pallet: {
+      source: blankSource(),
+      widthMm: '',
+      lengthMm: '',
+      heightMm: '',
+      tareMassG: '',
+      maxPayloadMassG: '',
+    },
+    includeEnvelope: false,
+    loadEnvelope: {
+      source: blankSource(),
+      widthMm: '',
+      lengthMm: '',
+      maxHeightMm: '',
+      maxGrossMassG: '',
+    },
+    additionalPacking: { source: blankSource(), massG: '' },
+    clearance: { source: blankSource(), perimeterMm: '', betweenPackagesMm: '', topMm: '' },
+  };
+}
+export class PalletInputError extends Error {
+  constructor(
+    readonly field: string,
+    readonly kind: 'WHOLE' | 'MASS' | 'SOURCE' | 'IDENTITY' | 'COUNT'
+  ) {
+    super('Review the supplied pallet preview facts.');
+  }
+}
+function whole(
+  value: string,
+  field: string,
+  maximum: number,
+  zero: boolean,
+  required = false
+): number | null {
+  if (value === '' && !required) return null;
+  if (value.trim() !== value || !/^(0|[1-9][0-9]*)$/.test(value) || value.length > 7)
+    throw new PalletInputError(field, 'WHOLE');
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n > maximum || n < (zero ? 0 : 1))
+    throw new PalletInputError(field, 'WHOLE');
+  return n;
+}
+function mass(value: string, field: string): string | null {
+  if (value === '') return null;
+  if (
+    value.trim() !== value ||
+    !/^(0|[1-9][0-9]*)$/.test(value) ||
+    value.length > 13 ||
+    (value.length === 13 && value > '1000000000000')
+  )
+    throw new PalletInputError(field, 'MASS');
+  return value;
+}
+function source(value: SourceDraft, field: string): MtwPalletMeasurementSourceInput | null {
+  if (value.reference === '' && value.version === '') return null;
+  if (
+    !value.reference.trim() ||
+    !value.version.trim() ||
+    value.reference.length > 255 ||
+    value.version.length > 120
+  )
+    throw new PalletInputError(field, 'SOURCE');
+  return { reference: value.reference, version: value.version };
+}
+export function palletPreviewInput(draft: PalletPreviewDraft): MtwPalletGeometryPreviewInput {
+  if (!draft.packages.length || draft.packages.length > 100)
+    throw new PalletInputError('packages', 'COUNT');
+  const ids = new Set<string>();
+  let total = 0;
+  const packages = draft.packages.map((p) => {
+    const key = `package-${p.key}`;
+    if (
+      !['UNKNOWN', 'NONE', '0', '90', 'BOTH'].includes(p.yaw) ||
+      !['UNKNOWN', 'YES', 'NO'].includes(p.upright)
+    )
+      throw new PalletInputError(key, 'WHOLE');
+    if (!p.id.trim() || p.id.trim() !== p.id || p.id.length > 255 || ids.has(p.id))
+      throw new PalletInputError(`${key}-id`, 'IDENTITY');
+    ids.add(p.id);
+    const quantity = whole(p.quantity, `${key}-quantity`, 1000, false, true);
+    if (quantity === null) throw new PalletInputError(`${key}-quantity`, 'COUNT');
+    total += quantity;
+    if (total > 1000) throw new PalletInputError(`${key}-quantity`, 'COUNT');
+    return {
+      id: p.id,
+      quantity,
+      source: source(p.source, `${key}-source`),
+      widthMm: whole(p.widthMm, `${key}-widthMm`, 1000000, false),
+      lengthMm: whole(p.lengthMm, `${key}-lengthMm`, 1000000, false),
+      heightMm: whole(p.heightMm, `${key}-heightMm`, 1000000, false),
+      grossMassG: mass(p.grossMassG, `${key}-grossMassG`),
+      allowedYawDegrees:
+        p.yaw === 'UNKNOWN'
+          ? null
+          : p.yaw === 'NONE'
+            ? []
+            : p.yaw === 'BOTH'
+              ? [0, 90]
+              : p.yaw === '0'
+                ? [0]
+                : [90],
+      upright: p.upright === 'UNKNOWN' ? null : p.upright === 'YES',
+    };
+  });
+  const p = draft.pallet,
+    e = draft.loadEnvelope,
+    c = draft.clearance;
+  return {
+    units: 'MM_G',
+    mode: 'UPRIGHT_SINGLE_LAYER',
+    packages,
+    pallet: {
+      source: source(p.source, 'pallet-source'),
+      widthMm: whole(p.widthMm, 'pallet-widthMm', 1000000, false),
+      lengthMm: whole(p.lengthMm, 'pallet-lengthMm', 1000000, false),
+      heightMm: whole(p.heightMm, 'pallet-heightMm', 1000000, false),
+      tareMassG: mass(p.tareMassG, 'pallet-tareMassG'),
+      maxPayloadMassG: mass(p.maxPayloadMassG, 'pallet-maxPayloadMassG'),
+    },
+    loadEnvelope: draft.includeEnvelope
+      ? {
+          source: source(e.source, 'envelope-source'),
+          widthMm: whole(e.widthMm, 'envelope-widthMm', 1000000, false),
+          lengthMm: whole(e.lengthMm, 'envelope-lengthMm', 1000000, false),
+          maxHeightMm: whole(e.maxHeightMm, 'envelope-maxHeightMm', 1000000, false),
+          maxGrossMassG: mass(e.maxGrossMassG, 'envelope-maxGrossMassG'),
+        }
+      : null,
+    additionalPacking: {
+      source: source(draft.additionalPacking.source, 'packing-source'),
+      massG: mass(draft.additionalPacking.massG, 'packing-massG'),
+    },
+    clearance: {
+      source: source(c.source, 'clearance-source'),
+      perimeterMm: whole(c.perimeterMm, 'clearance-perimeterMm', 1000000, true),
+      betweenPackagesMm: whole(c.betweenPackagesMm, 'clearance-betweenPackagesMm', 1000000, true),
+      topMm: whole(c.topMm, 'clearance-topMm', 1000000, true),
+    },
+  };
+}

package/src/movethewheels/utils/palletPreviewResponse.ts

@@ -0,0 +1,256 @@
+import type {
+  MtwPalletGeometryPreviewInput,
+  MtwPalletGeometryPreviewQuery,
+  MtwPalletMeasurementSourceInput,
+} from '../../generated/pallet-preview-operations';
+export type PalletPreview = MtwPalletGeometryPreviewQuery['mtwPalletGeometryPreview'];
+export const PALLET_BOUND_KEYS = [
+  'placedContainment',
+  'placedNonOverlap',
+  'permittedUprightYaw',
+  'reportedSingleLayerHeight',
+  'palletPayloadMass',
+  'palletFootprintWithinLoadEnvelope',
+  'loadedPalletGrossMass',
+] as const;
+export const PALLET_UNKNOWN_KEYS = [
+  'additionalPackingGeometry',
+  'handling',
+  'securing',
+  'centreOfGravityAndStability',
+  'supportAndFloorContactLoads',
+  'loadingAndUnloadingPath',
+  'segregationAndCargoCompatibility',
+] as const;
+function invalid(): never {
+  throw new Error('The pallet preview response could not be verified.');
+}
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function object(value: unknown): Record<string, unknown> {
+  if (!isObject(value)) return invalid();
+  return value;
+}
+function keys(value: Record<string, unknown>, names: readonly string[]): void {
+  if (
+    names.some((name) => !Object.hasOwn(value, name)) ||
+    Object.keys(value).some((name) => name !== '__typename' && !names.includes(name))
+  )
+    invalid();
+}
+function text(value: unknown, max: number): string {
+  if (typeof value !== 'string' || !value.trim() || value.length > max) return invalid();
+  return value;
+}
+function integer(value: unknown, min = 0, max = 1000000): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min || value > max)
+    return invalid();
+  return value;
+}
+function nullableInteger(value: unknown): number | null {
+  return value === null ? null : integer(value);
+}
+function grams(value: unknown, maximum: string): string | null {
+  if (value === null) return null;
+  if (
+    typeof value !== 'string' ||
+    value.trim() !== value ||
+    !/^(0|[1-9][0-9]*)$/.test(value) ||
+    value.length > maximum.length ||
+    (value.length === maximum.length && value > maximum)
+  )
+    return invalid();
+  return value;
+}
+function source(value: unknown, expected: MtwPalletMeasurementSourceInput | null | undefined) {
+  if (expected == null) {
+    if (value !== null) invalid();
+    return null;
+  }
+  const row = object(value);
+  keys(row, ['reference', 'version']);
+  const reference = text(row.reference, 255),
+    version = text(row.version, 120);
+  if (reference !== expected.reference.trim() || version !== expected.version.trim()) invalid();
+  return { reference, version };
+}
+function bound(value: unknown): PalletPreview['bounds']['placedContainment'] {
+  const row = object(value);
+  keys(row, ['status', 'reason']);
+  if (row.status !== 'PASS' && row.status !== 'FAIL' && row.status !== 'UNKNOWN') return invalid();
+  return { status: row.status, reason: text(row.reason, 4096) };
+}
+function unknown(value: unknown): 'UNKNOWN' {
+  if (value !== 'UNKNOWN') invalid();
+  return 'UNKNOWN';
+}
+/** New preview only: malformed or mixed envelopes never become a current result. */
+export function validatePalletPreviewEnvelope(value: unknown): void {
+  const row = object(value);
+  if ('errors' in row && (!Array.isArray(row.errors) || row.errors.length !== 0)) invalid();
+  const data = object(row.data);
+  keys(data, ['mtwPalletGeometryPreview']);
+  if (data.mtwPalletGeometryPreview == null) invalid();
+}
+export function parsePalletPreview(
+  data: unknown,
+  input: MtwPalletGeometryPreviewInput
+): PalletPreview {
+  const envelope = object(data);
+  keys(envelope, ['mtwPalletGeometryPreview']);
+  const row = object(envelope.mtwPalletGeometryPreview);
+  keys(row, [
+    'classification',
+    'method',
+    'units',
+    'layoutStatus',
+    'requestedQuantity',
+    'placedQuantity',
+    'requestedPayloadMassG',
+    'requestedGrossMassG',
+    'placements',
+    'unplaced',
+    'bounds',
+    'unsupported',
+    'sources',
+  ]);
+  if (
+    row.classification !== 'GEOMETRIC_PROPOSAL_ONLY' ||
+    row.method !== 'DETERMINISTIC_SINGLE_LAYER_SHELF_V1' ||
+    row.units !== 'MM_G'
+  )
+    invalid();
+  const layoutStatus = row.layoutStatus;
+  if (
+    layoutStatus !== 'PLACED_BY_METHOD' &&
+    layoutStatus !== 'UNKNOWN' &&
+    layoutStatus !== 'NO_LAYOUT_FOUND_BY_METHOD'
+  )
+    return invalid();
+  const requestedQuantity = integer(row.requestedQuantity, 1, 1000),
+    placedQuantity = integer(row.placedQuantity, 0, 1000);
+  if (
+    requestedQuantity !== input.packages.reduce((n, p) => n + p.quantity, 0) ||
+    placedQuantity > requestedQuantity ||
+    !Array.isArray(row.placements) ||
+    row.placements.length !== placedQuantity ||
+    !Array.isArray(row.unplaced) ||
+    row.unplaced.length > input.packages.length
+  )
+    invalid();
+  const seen = new Set<string>();
+  const placed = new Map<string, number>();
+  const placements = row.placements.map((value: unknown) => {
+    const p = object(value);
+    keys(p, [
+      'packageId',
+      'unit',
+      'yawDegrees',
+      'xMm',
+      'yMm',
+      'zMm',
+      'widthMm',
+      'lengthMm',
+      'heightMm',
+    ]);
+    const packageId = text(p.packageId, 255),
+      requested = input.packages.find((item) => item.id === packageId);
+    if (!requested) return invalid();
+    const unit = integer(p.unit, 1, requested.quantity),
+      yawDegrees = integer(p.yawDegrees, 0, 90);
+    if (
+      (yawDegrees !== 0 && yawDegrees !== 90) ||
+      !requested.allowedYawDegrees?.includes(yawDegrees) ||
+      requested.upright !== true ||
+      seen.has(`${packageId}:${unit}`)
+    )
+      invalid();
+    seen.add(`${packageId}:${unit}`);
+    placed.set(packageId, (placed.get(packageId) ?? 0) + 1);
+    const xMm = integer(p.xMm),
+      yMm = integer(p.yMm),
+      widthMm = integer(p.widthMm, 1),
+      lengthMm = integer(p.lengthMm, 1),
+      zMm = nullableInteger(p.zMm),
+      heightMm = nullableInteger(p.heightMm);
+    if (
+      widthMm !== (yawDegrees === 0 ? requested.widthMm : requested.lengthMm) ||
+      lengthMm !== (yawDegrees === 0 ? requested.lengthMm : requested.widthMm) ||
+      heightMm !== (requested.heightMm ?? null) ||
+      zMm !== (input.pallet.heightMm ?? null) ||
+      input.pallet.widthMm == null ||
+      input.pallet.lengthMm == null ||
+      xMm + widthMm > input.pallet.widthMm ||
+      yMm + lengthMm > input.pallet.lengthMm
+    )
+      invalid();
+    return { packageId, unit, yawDegrees, xMm, yMm, zMm, widthMm, lengthMm, heightMm };
+  });
+  const missing = new Map<string, number>();
+  const unplaced = row.unplaced.map((value: unknown) => {
+    const p = object(value);
+    keys(p, ['packageId', 'quantity']);
+    const packageId = text(p.packageId, 255),
+      quantity = integer(p.quantity, 1, 1000);
+    if (!input.packages.some((item) => item.id === packageId) || missing.has(packageId)) invalid();
+    missing.set(packageId, quantity);
+    return { packageId, quantity };
+  });
+  if (
+    input.packages.some((p) => (placed.get(p.id) ?? 0) + (missing.get(p.id) ?? 0) !== p.quantity) ||
+    (layoutStatus === 'PLACED_BY_METHOD' && placedQuantity !== requestedQuantity)
+  )
+    invalid();
+  const b = object(row.bounds);
+  keys(b, PALLET_BOUND_KEYS);
+  const u = object(row.unsupported);
+  keys(u, PALLET_UNKNOWN_KEYS);
+  const s = object(row.sources);
+  keys(s, ['packages', 'pallet', 'loadEnvelope', 'additionalPacking', 'clearance']);
+  if (!Array.isArray(s.packages) || s.packages.length !== input.packages.length) invalid();
+  const packageSources = s.packages.map((value: unknown, index: number) => {
+    const item = object(value);
+    keys(item, ['packageId', 'source']);
+    const expected = input.packages[index];
+    if (item.packageId !== expected.id) invalid();
+    return { packageId: expected.id, source: source(item.source, expected.source) };
+  });
+  return {
+    classification: 'GEOMETRIC_PROPOSAL_ONLY',
+    method: 'DETERMINISTIC_SINGLE_LAYER_SHELF_V1',
+    units: 'MM_G',
+    layoutStatus,
+    requestedQuantity,
+    placedQuantity,
+    requestedPayloadMassG: grams(row.requestedPayloadMassG, '1001000000000000'),
+    requestedGrossMassG: grams(row.requestedGrossMassG, '1002000000000000'),
+    placements,
+    unplaced,
+    bounds: {
+      placedContainment: bound(b.placedContainment),
+      placedNonOverlap: bound(b.placedNonOverlap),
+      permittedUprightYaw: bound(b.permittedUprightYaw),
+      reportedSingleLayerHeight: bound(b.reportedSingleLayerHeight),
+      palletPayloadMass: bound(b.palletPayloadMass),
+      palletFootprintWithinLoadEnvelope: bound(b.palletFootprintWithinLoadEnvelope),
+      loadedPalletGrossMass: bound(b.loadedPalletGrossMass),
+    },
+    unsupported: {
+      additionalPackingGeometry: unknown(u.additionalPackingGeometry),
+      handling: unknown(u.handling),
+      securing: unknown(u.securing),
+      centreOfGravityAndStability: unknown(u.centreOfGravityAndStability),
+      supportAndFloorContactLoads: unknown(u.supportAndFloorContactLoads),
+      loadingAndUnloadingPath: unknown(u.loadingAndUnloadingPath),
+      segregationAndCargoCompatibility: unknown(u.segregationAndCargoCompatibility),
+    },
+    sources: {
+      packages: packageSources,
+      pallet: source(s.pallet, input.pallet.source),
+      loadEnvelope: source(s.loadEnvelope, input.loadEnvelope?.source),
+      additionalPacking: source(s.additionalPacking, input.additionalPacking.source),
+      clearance: source(s.clearance, input.clearance.source),
+    },
+  };
+}

package/src/operations/pallet-preview/preview.graphql

@@ -0,0 +1,26 @@
+query MtwPalletGeometryPreview($input: MtwPalletGeometryPreviewInput!) {
+  mtwPalletGeometryPreview(input: $input) {
+    classification method units layoutStatus requestedQuantity placedQuantity
+    requestedPayloadMassG requestedGrossMassG
+    placements { packageId unit yawDegrees xMm yMm zMm widthMm lengthMm heightMm }
+    unplaced { packageId quantity }
+    bounds {
+      placedContainment { status reason }
+      placedNonOverlap { status reason }
+      permittedUprightYaw { status reason }
+      reportedSingleLayerHeight { status reason }
+      palletPayloadMass { status reason }
+      palletFootprintWithinLoadEnvelope { status reason }
+      loadedPalletGrossMass { status reason }
+    }
+    unsupported {
+      additionalPackingGeometry handling securing centreOfGravityAndStability
+      supportAndFloorContactLoads loadingAndUnloadingPath segregationAndCargoCompatibility
+    }
+    sources {
+      packages { packageId source { reference version } }
+      pallet { reference version } loadEnvelope { reference version }
+      additionalPacking { reference version } clearance { reference version }
+    }
+  }
+}