@merchi/sdk 1.40.2

package/src/pricing/matrix.ts

@@ -0,0 +1,217 @@
+import {
+  BuildPriceMatrixOptions,
+  DiscountGroup,
+  GroupSelection,
+  PriceMatrix,
+  PriceMatrixBand,
+  PriceMatrixCell,
+  PricingField,
+  PricingRules,
+  QuoteResult,
+  Selections,
+} from './types.js';
+import { estimateQuote } from './estimate.js';
+
+function toQuantity(value: unknown): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function floorMinQuantity(value: unknown): number {
+  const n = toQuantity(value);
+  return n >= 1 ? Math.round(n) : 1;
+}
+
+function addDiscountLimits(
+  group: DiscountGroup | null | undefined,
+  limits: Set<number>,
+  minQuantity: number
+): void {
+  if (!group || !group.discounts) return;
+  for (const discount of group.discounts) {
+    const n = Number(discount.lowerLimit);
+    if (!Number.isFinite(n)) continue;
+    const qty = Math.round(n);
+    if (qty > minQuantity) limits.add(qty);
+  }
+}
+
+function collectFieldDiscountLimits(
+  field: PricingField,
+  limits: Set<number>,
+  minQuantity: number
+): void {
+  addDiscountLimits(field.variationCostDiscountGroup, limits, minQuantity);
+  addDiscountLimits(field.variationUnitCostDiscountGroup, limits, minQuantity);
+  addDiscountLimits(field.heightVariationCostDiscountGroup, limits, minQuantity);
+  addDiscountLimits(field.heightVariationUnitCostDiscountGroup, limits, minQuantity);
+  addDiscountLimits(field.widthVariationCostDiscountGroup, limits, minQuantity);
+  addDiscountLimits(field.widthVariationUnitCostDiscountGroup, limits, minQuantity);
+  for (const option of field.options) {
+    addDiscountLimits(option.variationCostDiscountGroup, limits, minQuantity);
+    addDiscountLimits(option.variationUnitCostDiscountGroup, limits, minQuantity);
+  }
+}
+
+function collectQuantityBreaks(
+  rules: PricingRules,
+  minQuantity: number
+): number[] {
+  const limits = new Set<number>([minQuantity]);
+  addDiscountLimits(rules.product.discountGroup, limits, minQuantity);
+  for (const item of rules.fields) {
+    collectFieldDiscountLimits(item, limits, minQuantity);
+  }
+  for (const item of rules.groupFields) {
+    collectFieldDiscountLimits(item, limits, minQuantity);
+  }
+  return Array.from(limits).sort((a, b) => a - b);
+}
+
+function groupHasValues(group: GroupSelection): boolean {
+  const values = group.fieldValues || {};
+  return Object.keys(values).some((key) => {
+    const selection = values[Number(key)];
+    if (!selection) return false;
+    if (selection.selectedOptionIds && selection.selectedOptionIds.length) {
+      return true;
+    }
+    const value = selection.value;
+    return !(
+      value === undefined ||
+      value === null ||
+      value === '' ||
+      value === 0
+    );
+  });
+}
+
+function representativeGroupIndex(groups: GroupSelection[]): number {
+  const idx = groups.findIndex(groupHasValues);
+  return idx >= 0 ? idx : 0;
+}
+
+function selectionsAtQuantity(
+  selections: Selections,
+  qty: number
+): Selections {
+  const groups = selections.groups;
+  if (groups && groups.length > 0) {
+    const quantities = groups.map((group) => toQuantity(group.quantity));
+    const total = quantities.reduce((sum, value) => sum + value, 0);
+    if (total <= 0) {
+      const idx = representativeGroupIndex(groups);
+      return {
+        fieldValues: selections.fieldValues || {},
+        groups: groups.map((group, i) => ({
+          ...group,
+          quantity: i === idx ? qty : 0,
+        })),
+      };
+    }
+    const scaled: number[] = new Array(groups.length).fill(0);
+    let allocated = 0;
+    for (let i = 0; i < groups.length - 1; i++) {
+      scaled[i] = Math.round((quantities[i] / total) * qty);
+      allocated += scaled[i];
+    }
+    scaled[groups.length - 1] = Math.max(0, qty - allocated);
+    return {
+      fieldValues: selections.fieldValues || {},
+      groups: groups.map((group, i) => ({
+        ...group,
+        quantity: scaled[i],
+      })),
+    };
+  }
+  return {
+    fieldValues: selections.fieldValues || {},
+    quantity: qty,
+  };
+}
+
+function formatBandLabel(quantity: number, upperLimit: number | null): string {
+  if (upperLimit == null) return `${quantity}+`;
+  if (upperLimit === quantity) return `${quantity}`;
+  return `${quantity}–${upperLimit}`;
+}
+
+function samePrice(a: PriceMatrixCell, b: PriceMatrixCell): boolean {
+  return (
+    Math.abs(a.costPerUnit - b.costPerUnit) < 0.001 &&
+    Math.abs(a.unitPrice - b.unitPrice) < 0.001
+  );
+}
+
+function withBandBounds(quantities: number[]): PriceMatrixBand[] {
+  return quantities.map((quantity, i) => {
+    const next = quantities[i + 1];
+    const upperLimit = next == null ? null : next - 1;
+    return {
+      quantity,
+      upperLimit,
+      label: formatBandLabel(quantity, upperLimit),
+    };
+  });
+}
+
+/**
+ * Quantity-break price table for the current selection.
+ *
+ * Columns are unique quantity thresholds from every discount group on the
+ * product, fields, and options. Each cell is `estimateQuote` at that quantity
+ * so the table matches what the form will charge. Returns null when there are
+ * fewer than two distinct prices (nothing useful to show).
+ */
+export function buildPriceMatrix(
+  rules: PricingRules,
+  selections: Selections = { fieldValues: {} },
+  options: BuildPriceMatrixOptions = {}
+): PriceMatrix | null {
+  if (rules.unsupported) return null;
+
+  const safeRules: PricingRules = {
+    ...rules,
+    fields: (rules.fields || []).map((item) => ({
+      ...item,
+      options: item.options || [],
+    })),
+    groupFields: (rules.groupFields || []).map((item) => ({
+      ...item,
+      options: item.options || [],
+    })),
+  };
+  const minQuantity = floorMinQuantity(options.minQuantity);
+  const quantities = collectQuantityBreaks(safeRules, minQuantity);
+  const quoted: PriceMatrixCell[] = [];
+
+  for (const quantity of quantities) {
+    const quote = estimateQuote(
+      safeRules,
+      selectionsAtQuantity(selections, quantity)
+    ) as QuoteResult;
+    quoted.push({
+      quantity,
+      costPerUnit: quote.costPerUnit,
+      unitPrice: quote.cost / quantity,
+      cost: quote.cost,
+      taxAmount: quote.taxAmount,
+      totalCost: quote.totalCost,
+    });
+  }
+
+  const cells: PriceMatrixCell[] = [];
+  for (const cell of quoted) {
+    const prev = cells[cells.length - 1];
+    if (prev && samePrice(prev, cell)) continue;
+    cells.push(cell);
+  }
+  if (cells.length < 2) return null;
+
+  return {
+    currency: rules.currency,
+    taxPercent: rules.taxPercent,
+    bands: withBandBounds(cells.map((cell) => cell.quantity)),
+    cells,
+  };
+}

package/src/pricing/round.test.ts

@@ -0,0 +1,31 @@
+import { roundHalfEven } from './round.js';
+
+test('rounds half to even like Python round()', () => {
+  expect(roundHalfEven(0.5, 0)).toBe(0);
+  expect(roundHalfEven(1.5, 0)).toBe(2);
+  expect(roundHalfEven(2.5, 0)).toBe(2);
+  expect(roundHalfEven(1.005, 2)).toBe(1.0);
+  expect(roundHalfEven(-2.5, 0)).toBe(-2);
+  expect(roundHalfEven(12.3456, 3)).toBe(12.346);
+});
+
+test('returns non-finite inputs unchanged', () => {
+  expect(roundHalfEven(Infinity, 2)).toBe(Infinity);
+  expect(Number.isNaN(roundHalfEven(NaN, 2))).toBe(true);
+});
+
+test('non-halfway values use normal rounding', () => {
+  expect(roundHalfEven(2.34, 1)).toBe(2.3);
+  expect(roundHalfEven(2.36, 1)).toBe(2.4);
+});
+
+test('pins decimal half-even (not float round) semantics', () => {
+  // Decimal half-even rounds the .5 tie to the even neighbour. Float
+  // round(2.675, 2) would give 2.67; decimal half-even gives 2.68.
+  expect(roundHalfEven(2.675, 2)).toBe(2.68);
+  expect(roundHalfEven(1.255, 2)).toBe(1.26);
+  // Tie rounds to the even (lower) neighbour, leaving it at the floor.
+  expect(roundHalfEven(8.245, 2)).toBe(8.24);
+  // dp=0 large value, non-tie -> normal rounding.
+  expect(roundHalfEven(100.4, 0)).toBe(100);
+});

package/src/pricing/round.ts

@@ -0,0 +1,27 @@
+/**
+ * Round `value` to `dp` decimal places using decimal half-even (round half to
+ * even / banker's rounding) so it mirrors the server's `Decimal(round(x, n))`.
+ *
+ * This intentionally matches Python's *decimal* half-even behaviour, NOT Python
+ * float `round()` (e.g. `roundHalfEven(2.675, 2) === 2.68`, whereas float
+ * `round(2.675, 2)` yields 2.67).
+ *
+ * Targeted at the money domain: small magnitudes and `dp <= 3`. The `EPS`
+ * half-detection tolerance is tuned for that domain and is not intended for
+ * arbitrary large magnitudes or high precision.
+ */
+export function roundHalfEven(value: number, dp: number): number {
+  if (!isFinite(value)) return value;
+  const factor = Math.pow(10, dp);
+  const scaled = value * factor;
+  const floor = Math.floor(scaled);
+  const diff = scaled - floor;
+  const EPS = 1e-9;
+  let rounded: number;
+  if (Math.abs(diff - 0.5) < EPS) {
+    rounded = floor % 2 === 0 ? floor : floor + 1;
+  } else {
+    rounded = Math.round(scaled);
+  }
+  return rounded / factor;
+}

package/src/pricing/types.ts

@@ -0,0 +1,140 @@
+export interface DiscountTier {
+  lowerLimit: number;
+  amount: number; // percent
+}
+
+export interface DiscountGroup {
+  groupRestricted: boolean;
+  discounts: DiscountTier[];
+}
+
+export interface PricingOption {
+  id: number;
+  originalId: number | null;
+  position: number;
+  default: boolean;
+  // Per-option stock availability snapshot (only meaningful for
+  // inventory-limited products; defaults true otherwise).
+  available?: boolean;
+  variationCost: number;
+  variationUnitCost: number;
+  variationCostDiscountGroup: DiscountGroup | null;
+  variationUnitCostDiscountGroup: DiscountGroup | null;
+  selectedBy: number[];
+}
+
+export interface PricingField {
+  id: number;
+  originalId: number | null;
+  position: number;
+  fieldType: number;
+  independent: boolean;
+  isSelectable: boolean;
+  selectedBy: number[];
+  variationCost: number;
+  variationUnitCost: number;
+  variationCostDiscountGroup: DiscountGroup | null;
+  variationUnitCostDiscountGroup: DiscountGroup | null;
+  /** Area field (type 14): once-off and per-edge unit costs. */
+  areaUnit?: 'mm' | 'cm' | 'm' | string;
+  heightVariationCost?: number;
+  heightVariationUnitCost?: number;
+  widthVariationCost?: number;
+  widthVariationUnitCost?: number;
+  heightVariationCostDiscountGroup?: DiscountGroup | null;
+  heightVariationUnitCostDiscountGroup?: DiscountGroup | null;
+  widthVariationCostDiscountGroup?: DiscountGroup | null;
+  widthVariationUnitCostDiscountGroup?: DiscountGroup | null;
+  options: PricingOption[];
+}
+
+export interface PricingRules {
+  currency: string;
+  taxPercent: number;
+  product: {
+    unitPrice: number;
+    minimumPrice: number | null;
+    /** Product-level setup fee. Applied once to the job, or once per
+     * non-empty variation group when setupPerGroup is true. */
+    setupPrice?: number;
+    setupPerGroup?: boolean;
+    discountGroup: DiscountGroup | null;
+  };
+  fields: PricingField[];
+  groupFields: PricingField[];
+  hasGroups: boolean;
+  // True when the product is inventory-limited (needs_inventory and not
+  // inventories_open): the client disables out-of-stock options from the
+  // bundle snapshot and refreshes sufficiency from the server in the background.
+  needsInventory?: boolean;
+  // Per-combination stock for inventory-limited products: each entry is one
+  // inventory record's option-id combination and its quantity. Used for
+  // combination-aware option availability.
+  inventoryUnits?: InventoryUnit[];
+  unsupported?: string;
+}
+
+export interface InventoryUnit {
+  optionIds: number[];
+  quantity: number;
+}
+
+export interface FieldSelection {
+  selectedOptionIds?: number[];
+  value?: string | number | null;
+}
+
+export interface GroupSelection {
+  quantity: number;
+  fieldValues: Record<number, FieldSelection>;
+}
+
+export interface Selections {
+  quantity?: number;
+  fieldValues: Record<number, FieldSelection>;
+  groups?: GroupSelection[];
+}
+
+export interface QuoteResult {
+  costPerUnit: number;
+  cost: number;
+  taxAmount: number;
+  totalCost: number;
+  groupCosts: number[];
+  currency: string;
+}
+
+export interface UnsupportedResult {
+  unsupported: string;
+}
+
+export interface PriceMatrixBand {
+  /** Inclusive lower quantity used to quote this column. */
+  quantity: number;
+  /** Inclusive upper quantity, or null for an open-ended last band. */
+  upperLimit: number | null;
+  /** Buyer-facing range, e.g. "1–49" or "100+". */
+  label: string;
+}
+
+export interface PriceMatrixCell {
+  quantity: number;
+  costPerUnit: number;
+  /** Ex-tax cost ÷ quantity (variation unit costs + amortized setup). */
+  unitPrice: number;
+  cost: number;
+  taxAmount: number;
+  totalCost: number;
+}
+
+export interface PriceMatrix {
+  currency: string;
+  taxPercent: number;
+  bands: PriceMatrixBand[];
+  cells: PriceMatrixCell[];
+}
+
+export interface BuildPriceMatrixOptions {
+  /** Floor quantity for the first band (product MOQ). Defaults to 1. */
+  minQuantity?: number;
+}

package/src/pricing/visibility.test.ts

@@ -0,0 +1,223 @@
+import { resolveVisibleFields, resolveVisibleOptionIds } from './visibility.js';
+import { PricingRules } from './types.js';
+
+function field(id: number, selectedBy: number[], options: number[] = []): any {
+  return {
+    id, originalId: id, position: 0, fieldType: 2, independent: true,
+    isSelectable: true, selectedBy,
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    options: options.map((oid) => ({
+      id: oid, originalId: oid, position: 0, default: false,
+      variationCost: 0, variationUnitCost: 0,
+      variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+      selectedBy: [],
+    })),
+  };
+}
+
+const rules: PricingRules = {
+  currency: 'AUD', taxPercent: 0,
+  product: { unitPrice: 0, minimumPrice: null, discountGroup: null },
+  fields: [
+    field(1, [], [101, 102]),       // always visible, has options
+    field(2, [101], [201]),          // visible only if option 101 selected
+    field(3, [201], [301]),          // chained: visible if option 201 selected
+  ],
+  groupFields: [],
+  hasGroups: false,
+};
+
+test('field with no selectedBy is always visible', () => {
+  const v = resolveVisibleFields(rules, { fieldValues: {} });
+  expect(v.has(1)).toBe(true);
+  expect(v.has(2)).toBe(false);
+  expect(v.has(3)).toBe(false);
+});
+
+test('conditional field appears when its trigger option is selected', () => {
+  const v = resolveVisibleFields(rules, {
+    fieldValues: { 1: { selectedOptionIds: [101] } },
+  });
+  expect(v.has(2)).toBe(true);
+  expect(v.has(3)).toBe(false);
+});
+
+test('chained conditional field requires its parent to be fulfilled', () => {
+  const v = resolveVisibleFields(rules, {
+    fieldValues: { 1: { selectedOptionIds: [101] }, 2: { selectedOptionIds: [201] } },
+  });
+  expect(v.has(3)).toBe(true);
+});
+
+test('group fields are not visible when the job has no groups', () => {
+  const groupRules: PricingRules = {
+    ...rules,
+    fields: [field(1, [], [101])],
+    hasGroups: true,
+    groupFields: [field(20, []), field(21, [])],
+  };
+  // No groups submitted -> the job is a single non-group job, so group fields
+  // never materialise as variations (mirrors the server).
+  const v = resolveVisibleFields(groupRules, { fieldValues: { 1: { selectedOptionIds: [101] } } });
+  expect(v.has(1)).toBe(true);
+  expect(v.has(20)).toBe(false);
+  expect(v.has(21)).toBe(false);
+});
+
+test('group field selections also drive visibility', () => {
+  const groupRules: PricingRules = {
+    ...rules, fields: [], hasGroups: true,
+    groupFields: [field(10, [], [110]), field(11, [110], [111])],
+  };
+  const v = resolveVisibleFields(groupRules, {
+    fieldValues: {},
+    groups: [{ quantity: 5, fieldValues: { 10: { selectedOptionIds: [110] } } }],
+  });
+  expect(v.has(11)).toBe(true);
+});
+
+test('options/fields with null originalId still resolve by id', () => {
+  const noOrigOption = {
+    id: 401, originalId: null, position: 0, default: false,
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    selectedBy: [],
+  };
+  const trigger: any = {
+    id: 40, originalId: null, position: 0, fieldType: 2, independent: true,
+    isSelectable: true, selectedBy: [],
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    options: [noOrigOption],
+  };
+  const dependent = field(41, [401], []);
+  const noOrigRules: PricingRules = { ...rules, fields: [trigger, dependent] };
+  const v = resolveVisibleFields(noOrigRules, {
+    fieldValues: { 40: { selectedOptionIds: [401] } },
+  });
+  expect(v.has(41)).toBe(true);
+});
+
+test('cyclic selectedBy references terminate via the checked guard', () => {
+  function fieldWithOptSelectedBy(
+    id: number, selectedBy: number[],
+    opts: { id: number; selectedBy: number[] }[]
+  ): any {
+    return {
+      id, originalId: id, position: 0, fieldType: 2, independent: true,
+      isSelectable: true, selectedBy,
+      variationCost: 0, variationUnitCost: 0,
+      variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+      options: opts.map((o) => ({
+        id: o.id, originalId: o.id, position: 0, default: false,
+        variationCost: 0, variationUnitCost: 0,
+        variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+        selectedBy: o.selectedBy,
+      })),
+    };
+  }
+  const cyclicRules: PricingRules = {
+    ...rules,
+    fields: [
+      fieldWithOptSelectedBy(20, [], [{ id: 120, selectedBy: [121] }]),
+      fieldWithOptSelectedBy(21, [], [{ id: 121, selectedBy: [120] }]),
+      field(22, [120], []),
+    ],
+  };
+  const v = resolveVisibleFields(cyclicRules, {
+    fieldValues: { 20: { selectedOptionIds: [120] }, 21: { selectedOptionIds: [121] } },
+  });
+  expect(v.has(22)).toBe(true);
+});
+
+test('field selections without selectedOptionIds are ignored', () => {
+  const v = resolveVisibleFields(rules, {
+    fieldValues: { 1: { value: 'text-only' }, 9: undefined as any },
+  });
+  expect(v.has(1)).toBe(true);
+  expect(v.has(2)).toBe(false);
+});
+
+test('missing fieldValues falls back to an empty selection map', () => {
+  const v = resolveVisibleFields(rules, { fieldValues: undefined as any });
+  expect(v.has(1)).toBe(true);
+  expect(v.has(2)).toBe(false);
+});
+
+test('group without fieldValues falls back to an empty selection map', () => {
+  const v = resolveVisibleFields(rules, {
+    fieldValues: {},
+    groups: [{ quantity: 1, fieldValues: undefined as any }],
+  });
+  expect(v.has(1)).toBe(true);
+  expect(v.has(2)).toBe(false);
+});
+
+// --- resolveVisibleOptionIds (option-level conditional visibility) ---
+
+// Mirrors the production case: a Size field with options (24mm=901, 25mm=902)
+// and a Colour field whose Green option (912) is gated by `selectedBy: [902]`.
+function sizeAndColourRules(): PricingRules {
+  const opt = (id: number, selectedBy: number[] = []) => ({
+    id, originalId: id, position: id, default: false,
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    selectedBy,
+  });
+  const f = (id: number, options: any[]): any => ({
+    id, originalId: id, position: 0, fieldType: 2, independent: true,
+    isSelectable: true, selectedBy: [],
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    options,
+  });
+  return {
+    ...rules,
+    fields: [
+      f(900, [opt(901), opt(902)]),                     // Size: 24mm, 25mm
+      f(910, [opt(911), opt(912, [902]), opt(913)]),    // Colour: Red, Green(gated by 25mm), Blue
+    ],
+    groupFields: [],
+  };
+}
+
+test('option with no selectedBy is always visible', () => {
+  const v = resolveVisibleOptionIds(sizeAndColourRules(), { fieldValues: {} });
+  expect(v.has(901)).toBe(true);
+  expect(v.has(911)).toBe(true);
+  expect(v.has(913)).toBe(true);
+});
+
+test('gated option is hidden until its trigger option is selected', () => {
+  const r = sizeAndColourRules();
+  const hidden = resolveVisibleOptionIds(r, { fieldValues: { 900: { selectedOptionIds: [901] } } });
+  expect(hidden.has(912)).toBe(false); // 24mm selected -> Green hidden
+  const visible = resolveVisibleOptionIds(r, { fieldValues: { 900: { selectedOptionIds: [902] } } });
+  expect(visible.has(912)).toBe(true); // 25mm selected -> Green visible
+});
+
+test('group option visibility resolves from group selections', () => {
+  const opt = (id: number, selectedBy: number[] = []) => ({
+    id, originalId: id, position: id, default: false,
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    selectedBy,
+  });
+  const f = (id: number, options: any[]): any => ({
+    id, originalId: id, position: 0, fieldType: 2, independent: true,
+    isSelectable: true, selectedBy: [],
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    options,
+  });
+  const groupRules: PricingRules = {
+    ...rules, fields: [], hasGroups: true,
+    groupFields: [f(800, [opt(801), opt(802)]), f(810, [opt(811, [802])])],
+  };
+  const v = resolveVisibleOptionIds(groupRules, {
+    fieldValues: {},
+    groups: [{ quantity: 5, fieldValues: { 800: { selectedOptionIds: [802] } } }],
+  });
+  expect(v.has(811)).toBe(true);
+});