merchi_sdk_js 0.6.0 → 0.7.0

package/src/pricing/__fixtures__/quantity_break_discount.json

@@ -0,0 +1,104 @@
+{
+  "bundle": {
+    "currency": "AUD",
+    "fields": [
+      {
+        "fieldType": 1,
+        "id": 6,
+        "independent": true,
+        "isSelectable": false,
+        "options": [],
+        "originalId": null,
+        "position": 1,
+        "selectedBy": [],
+        "variationCost": 11.0,
+        "variationCostDiscountGroup": null,
+        "variationUnitCost": 0.0,
+        "variationUnitCostDiscountGroup": null
+      }
+    ],
+    "groupFields": [
+      {
+        "fieldType": 2,
+        "id": 4,
+        "independent": false,
+        "isSelectable": true,
+        "options": [
+          {
+            "default": true,
+            "id": 3,
+            "originalId": null,
+            "position": 1,
+            "selectedBy": [],
+            "variationCost": 0.0,
+            "variationCostDiscountGroup": null,
+            "variationUnitCost": 0.0,
+            "variationUnitCostDiscountGroup": null
+          },
+          {
+            "default": false,
+            "id": 4,
+            "originalId": null,
+            "position": 2,
+            "selectedBy": [],
+            "variationCost": 0.0,
+            "variationCostDiscountGroup": null,
+            "variationUnitCost": 13.0,
+            "variationUnitCostDiscountGroup": null
+          }
+        ],
+        "originalId": null,
+        "position": 1,
+        "selectedBy": [],
+        "variationCost": 0.0,
+        "variationCostDiscountGroup": null,
+        "variationUnitCost": 0.0,
+        "variationUnitCostDiscountGroup": null
+      },
+      {
+        "fieldType": 3,
+        "id": 5,
+        "independent": false,
+        "isSelectable": false,
+        "options": [],
+        "originalId": null,
+        "position": 2,
+        "selectedBy": [],
+        "variationCost": 0.0,
+        "variationCostDiscountGroup": null,
+        "variationUnitCost": 0.0,
+        "variationUnitCostDiscountGroup": null
+      }
+    ],
+    "hasGroups": true,
+    "product": {
+      "discountGroup": {
+        "discounts": [
+          {
+            "amount": 10.0,
+            "lowerLimit": 100.0
+          }
+        ],
+        "groupRestricted": false
+      },
+      "minimumPrice": 0.0,
+      "unitPrice": 20.0
+    },
+    "taxPercent": 10.0
+  },
+  "expected": {
+    "cost": 1800.0,
+    "costPerUnit": 18.0,
+    "groupCosts": [],
+    "taxAmount": 180.0,
+    "totalCost": 1980.0,
+    "visibleFieldIds": [
+      6
+    ]
+  },
+  "name": "quantity_break_discount",
+  "selections": {
+    "fieldValues": {},
+    "quantity": 100
+  }
+}

package/src/pricing/__fixtures__/simple_selectable_field.json

@@ -0,0 +1,110 @@
+{
+  "bundle": {
+    "currency": "AUD",
+    "fields": [
+      {
+        "fieldType": 2,
+        "id": 1,
+        "independent": true,
+        "isSelectable": true,
+        "options": [
+          {
+            "default": true,
+            "id": 1,
+            "originalId": null,
+            "position": 1,
+            "selectedBy": [],
+            "variationCost": 50.0,
+            "variationCostDiscountGroup": null,
+            "variationUnitCost": 0.0,
+            "variationUnitCostDiscountGroup": null
+          },
+          {
+            "default": false,
+            "id": 2,
+            "originalId": null,
+            "position": 2,
+            "selectedBy": [],
+            "variationCost": 50.0,
+            "variationCostDiscountGroup": null,
+            "variationUnitCost": 13.0,
+            "variationUnitCostDiscountGroup": null
+          }
+        ],
+        "originalId": null,
+        "position": 1,
+        "selectedBy": [],
+        "variationCost": 0.0,
+        "variationCostDiscountGroup": null,
+        "variationUnitCost": 0.0,
+        "variationUnitCostDiscountGroup": null
+      }
+    ],
+    "groupFields": [
+      {
+        "fieldType": 1,
+        "id": 3,
+        "independent": false,
+        "isSelectable": false,
+        "options": [],
+        "originalId": null,
+        "position": 1,
+        "selectedBy": [],
+        "variationCost": 11.0,
+        "variationCostDiscountGroup": null,
+        "variationUnitCost": 0.0,
+        "variationUnitCostDiscountGroup": null
+      },
+      {
+        "fieldType": 3,
+        "id": 2,
+        "independent": false,
+        "isSelectable": false,
+        "options": [],
+        "originalId": null,
+        "position": 2,
+        "selectedBy": [],
+        "variationCost": 0.0,
+        "variationCostDiscountGroup": null,
+        "variationUnitCost": 0.0,
+        "variationUnitCostDiscountGroup": null
+      }
+    ],
+    "hasGroups": true,
+    "product": {
+      "discountGroup": {
+        "discounts": [
+          {
+            "amount": 10.0,
+            "lowerLimit": 400.0
+          }
+        ],
+        "groupRestricted": false
+      },
+      "minimumPrice": 0.0,
+      "unitPrice": 30.0
+    },
+    "taxPercent": 10.0
+  },
+  "expected": {
+    "cost": 350.0,
+    "costPerUnit": 30.0,
+    "groupCosts": [],
+    "taxAmount": 35.0,
+    "totalCost": 385.0,
+    "visibleFieldIds": [
+      1
+    ]
+  },
+  "name": "simple_selectable_field",
+  "selections": {
+    "fieldValues": {
+      "1": {
+        "selectedOptionIds": [
+          1
+        ]
+      }
+    },
+    "quantity": 10
+  }
+}

package/src/pricing/discount.js

@@ -0,0 +1,14 @@
+import { roundHalfEven } from './round.js';
+
+// Mirrors the server's discount_groups.get_discounted_price: pick the tier with
+// the highest lowerLimit <= qty, apply price*(1 - amount/100), round to 3dp.
+export function applyDiscount(price, qty, group) {
+  if (!group || group.discounts.length === 0) {
+    return roundHalfEven(price, 3);
+  }
+  const applicable = group.discounts
+    .filter((d) => d.lowerLimit <= qty)
+    .sort((a, b) => b.lowerLimit - a.lowerLimit);
+  const amount = applicable.length ? applicable[0].amount : 0;
+  return roundHalfEven(price * (1 - amount / 100), 3);
+}

package/src/pricing/estimate.js

@@ -0,0 +1,172 @@
+import { applyDiscount } from './discount.js';
+import { roundHalfEven } from './round.js';
+import { resolveVisibleFields } from './visibility.js';
+
+function unitPriceAt(rules, qty) {
+  let unitPrice = applyDiscount(rules.product.unitPrice, qty, rules.product.discountGroup);
+  const mop = rules.product.minimumPrice;
+  if (qty > 0 && mop && unitPrice * qty < mop) {
+    unitPrice = mop / qty;
+  }
+  return unitPrice;
+}
+
+function variationSetupCost(source, totalQty) {
+  let cost = source.variationCost;
+  if (source.variationCostDiscountGroup) {
+    cost = applyDiscount(cost, totalQty, source.variationCostDiscountGroup);
+  }
+  return roundHalfEven(cost, 3);
+}
+
+function variationUnitCosts(source, groupQuantities) {
+  const uc = source.variationUnitCost;
+  const group = source.variationUnitCostDiscountGroup;
+  let list;
+  if (group) {
+    if (group.groupRestricted) {
+      list = groupQuantities.map((q) => applyDiscount(uc, q, group));
+    } else {
+      const total = groupQuantities.reduce((a, b) => a + b, 0);
+      const discounted = applyDiscount(uc, total, group);
+      list = groupQuantities.map(() => discounted);
+    }
+  } else {
+    list = groupQuantities.map(() => uc);
+  }
+  return list.map((c) => roundHalfEven(c, 3));
+}
+
+function isEmpty(field, sel) {
+  if (!sel) return true;
+  if (field.isSelectable) {
+    return !sel.selectedOptionIds || sel.selectedOptionIds.length === 0;
+  }
+  return (
+    sel.value === undefined ||
+    sel.value === null ||
+    sel.value === '' ||
+    sel.value === 0
+  );
+}
+
+function costFactor(field, sel, groupQuantities) {
+  const n = groupQuantities.length;
+  if (isEmpty(field, sel)) {
+    return { setup: 0, unitList: new Array(n).fill(0) };
+  }
+  const totalQty = groupQuantities.reduce((a, b) => a + b, 0);
+  if (field.isSelectable) {
+    let setup = 0;
+    const unitList = new Array(n).fill(0);
+    const optById = new Map();
+    for (const o of field.options) {
+      optById.set(o.id, o);
+      if (o.originalId != null) optById.set(o.originalId, o);
+    }
+    for (const optId of sel.selectedOptionIds) {
+      const opt = optById.get(optId);
+      if (!opt) continue;
+      setup += variationSetupCost(opt, totalQty);
+      const ucs = variationUnitCosts(opt, groupQuantities);
+      for (let i = 0; i < n; i++) unitList[i] += ucs[i];
+    }
+    return { setup, unitList };
+  }
+  return {
+    setup: variationSetupCost(field, totalQty),
+    unitList: variationUnitCosts(field, groupQuantities),
+  };
+}
+
+export function estimateQuote(rules, selections) {
+  if (rules.unsupported) {
+    return { unsupported: rules.unsupported };
+  }
+
+  const groupCosts = [];
+  let cost = 0;
+  let costPerUnit;
+  let groupQuantities;
+
+  // Mirror the server: the group-vs-single branch keys off whether the *job*
+  // actually has variation groups, not the product's capability.
+  const groups = selections.groups || [];
+  if (groups.length > 0) {
+    groupQuantities = groups.map((g) => g.quantity || 0);
+    const totalQty = groupQuantities.reduce((a, b) => a + b, 0);
+    const restricted = Boolean(
+      rules.product.discountGroup && rules.product.discountGroup.groupRestricted
+    );
+    const baseUnitPrice = unitPriceAt(rules, totalQty);
+    const perGroupCpu = [];
+
+    for (const group of groups) {
+      const gQty = group.quantity || 0;
+      const cpu = restricted ? unitPriceAt(rules, gQty) : baseUnitPrice;
+      perGroupCpu.push(cpu);
+      // A zero-qty group contributes exactly 0 (no field costs).
+      if (!gQty) {
+        groupCosts.push(0);
+        continue;
+      }
+      // Per-group field visibility is scoped to that group's selections plus
+      // the independent selections.
+      const groupVisible = resolveVisibleFields(rules, {
+        fieldValues: selections.fieldValues,
+        groups: [group],
+      });
+      let groupVariationCost = 0;
+      for (const field of rules.groupFields) {
+        if (!groupVisible.has(field.id)) continue;
+        const { setup, unitList } = costFactor(field, group.fieldValues[field.id], [gQty]);
+        groupVariationCost += setup + unitList[0] * gQty;
+      }
+      const groupCost = gQty * cpu + groupVariationCost;
+      groupCosts.push(groupCost);
+      cost += groupCost;
+    }
+
+    costPerUnit =
+      totalQty > 0
+        ? perGroupCpu.reduce((acc, cpu, i) => acc + cpu * groupQuantities[i], 0) / totalQty
+        : baseUnitPrice;
+
+    // Independent field visibility is scoped to independent selections only.
+    const independentVisible = resolveVisibleFields(rules, {
+      quantity: selections.quantity,
+      fieldValues: selections.fieldValues,
+    });
+    for (const field of rules.fields) {
+      if (!independentVisible.has(field.id)) continue;
+      const { setup, unitList } = costFactor(field, selections.fieldValues[field.id], groupQuantities);
+      const unitTotal = unitList.reduce((acc, uc, i) => acc + uc * groupQuantities[i], 0);
+      cost += setup + unitTotal;
+    }
+  } else {
+    const qty = selections.quantity || 0;
+    groupQuantities = [qty];
+    costPerUnit = unitPriceAt(rules, qty);
+    cost = costPerUnit * qty;
+    const visible = resolveVisibleFields(rules, selections);
+    for (const field of rules.fields) {
+      if (!visible.has(field.id)) continue;
+      const { setup, unitList } = costFactor(field, selections.fieldValues[field.id], groupQuantities);
+      cost += setup + unitList[0] * qty;
+    }
+  }
+
+  // Tax is derived from the UNROUNDED cost, then cost/tax rounded independently.
+  const unroundedCost = cost;
+  const roundedCost = roundHalfEven(unroundedCost, 2);
+  const unroundedTax = (unroundedCost * rules.taxPercent) / 100;
+  const taxAmount = roundHalfEven(unroundedTax, 2);
+  return {
+    costPerUnit: roundHalfEven(costPerUnit, 3),
+    cost: roundedCost,
+    taxAmount,
+    totalCost: roundHalfEven(unroundedCost + unroundedTax, 3),
+    groupCosts: groupCosts.map((c) => roundHalfEven(c, 3)),
+    currency: rules.currency,
+  };
+}

package/src/pricing/golden.test.js

@@ -0,0 +1,54 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { estimateQuote } from './estimate.js';
+import { resolveVisibleFields } from './visibility.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES_DIR = path.join(HERE, '__fixtures__');
+
+// Fixtures are generated by the merchi_api fixture generator from the real
+// specialised-order-estimate endpoint (the same set vendored into
+// merchi_sdk_ts), so both SDKs are validated against one server source.
+function loadFixtures() {
+  if (!fs.existsSync(FIXTURES_DIR)) return [];
+  return fs
+    .readdirSync(FIXTURES_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => JSON.parse(fs.readFileSync(path.join(FIXTURES_DIR, f), 'utf-8')));
+}
+
+function closeTo(actual, expected, dp) {
+  const tolerance = 0.5 * Math.pow(10, -dp);
+  assert.ok(
+    Math.abs(actual - expected) < tolerance,
+    `expected ${actual} to be within ${tolerance} of ${expected}`
+  );
+}
+
+const fixtures = loadFixtures();
+
+test('pricing fixtures exist', () => {
+  assert.ok(fixtures.length > 0, 'no fixtures found');
+});
+
+for (const fixture of fixtures) {
+  test(`golden parity: ${fixture.name} - estimateQuote matches server`, () => {
+    const result = estimateQuote(fixture.bundle, fixture.selections);
+    closeTo(result.cost, fixture.expected.cost, 2);
+    closeTo(result.costPerUnit, fixture.expected.costPerUnit, 3);
+    closeTo(result.taxAmount, fixture.expected.taxAmount, 2);
+    closeTo(result.totalCost, fixture.expected.totalCost, 2);
+    assert.equal(result.groupCosts.length, fixture.expected.groupCosts.length);
+    result.groupCosts.forEach((c, i) => closeTo(c, fixture.expected.groupCosts[i], 2));
+  });
+
+  test(`golden parity: ${fixture.name} - resolveVisibleFields matches server`, () => {
+    const visible = [...resolveVisibleFields(fixture.bundle, fixture.selections)].sort(
+      (a, b) => a - b
+    );
+    assert.deepEqual(visible, fixture.expected.visibleFieldIds);
+  });
+}

package/src/pricing/index.js

@@ -0,0 +1,5 @@
+export { roundHalfEven } from './round.js';
+export { applyDiscount } from './discount.js';
+export { resolveVisibleFields, resolveVisibleOptionIds } from './visibility.js';
+export { resolveUnavailableOptionIds } from './inventory.js';
+export { estimateQuote } from './estimate.js';

package/src/pricing/inventory.js

@@ -0,0 +1,73 @@
+// Returns the set of option ids that should be DISABLED because the combination
+// of (current inventory-relevant selections + that option) has no matching
+// inventory with stock. Mirrors the server's subset match
+// (inventories_subset_match_strategy): an inventory matches a selection when it
+// contains every selected option; an option is available if any matching
+// inventory has quantity > 0.
+//
+// Scope: pass the container's selections (independent fields use the top-level
+// selections; a group uses its own + independent). Only options that appear in
+// at least one inventory unit are inventory-tracked; all others are always
+// available. Direct product inventories only (no shared inventory groups).
+export function resolveUnavailableOptionIds(rules, selections) {
+  const unavailable = new Set();
+  const units = rules.inventoryUnits || [];
+  if (units.length === 0) return unavailable;
+
+  const allFields = [...rules.fields, ...rules.groupFields];
+
+  const canonical = new Map();
+  for (const f of allFields) {
+    for (const o of f.options) {
+      canonical.set(o.id, o.id);
+      if (o.originalId != null) canonical.set(o.originalId, o.id);
+    }
+  }
+  const canon = (id) => (canonical.has(id) ? canonical.get(id) : id);
+
+  const unitSets = units.map((u) => ({
+    quantity: u.quantity,
+    optionIds: new Set(u.optionIds.map(canon)),
+  }));
+  const inventoryOptionIds = new Set();
+  for (const u of unitSets) {
+    for (const id of u.optionIds) inventoryOptionIds.add(id);
+  }
+
+  const selectedByField = new Map();
+  const addSelections = (fieldValues) => {
+    for (const key of Object.keys(fieldValues)) {
+      const fieldId = Number(key);
+      const sel = fieldValues[fieldId];
+      if (!sel || !sel.selectedOptionIds) continue;
+      const set = selectedByField.get(fieldId) || new Set();
+      for (const oid of sel.selectedOptionIds) {
+        const c = canon(oid);
+        if (inventoryOptionIds.has(c)) set.add(c);
+      }
+      selectedByField.set(fieldId, set);
+    }
+  };
+  addSelections(selections.fieldValues || {});
+  for (const group of selections.groups || []) addSelections(group.fieldValues || {});
+
+  const hasGroups = Boolean(selections.groups && selections.groups.length > 0);
+  const fieldsToConsider = hasGroups ? allFields : rules.fields;
+
+  for (const f of fieldsToConsider) {
+    for (const o of f.options) {
+      const candidate = canon(o.id);
+      if (!inventoryOptionIds.has(candidate)) continue;
+      const filter = [candidate];
+      for (const [fieldId, set] of selectedByField) {
+        if (fieldId === f.id) continue;
+        for (const sid of set) filter.push(sid);
+      }
+      const available = unitSets.some(
+        (u) => u.quantity > 0 && filter.every((id) => u.optionIds.has(id))
+      );
+      if (!available) unavailable.add(o.id);
+    }
+  }
+  return unavailable;
+}

package/src/pricing/pricing.test.js

@@ -0,0 +1,77 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { roundHalfEven } from './round.js';
+import { applyDiscount } from './discount.js';
+import { resolveUnavailableOptionIds } from './inventory.js';
+import { estimateQuote } from './estimate.js';
+
+test('roundHalfEven: decimal half-even', () => {
+  assert.equal(roundHalfEven(0.5, 0), 0);
+  assert.equal(roundHalfEven(1.5, 0), 2);
+  assert.equal(roundHalfEven(2.5, 0), 2);
+  assert.equal(roundHalfEven(2.675, 2), 2.68);
+  assert.equal(roundHalfEven(12.3456, 3), 12.346);
+  assert.equal(roundHalfEven(Infinity, 2), Infinity);
+});
+
+test('applyDiscount: highest applicable tier', () => {
+  const group = {
+    groupRestricted: false,
+    discounts: [
+      { lowerLimit: 100, amount: 5 },
+      { lowerLimit: 500, amount: 12 },
+    ],
+  };
+  assert.equal(applyDiscount(10, 50, null), 10);
+  assert.equal(applyDiscount(10, 50, group), 10);
+  assert.equal(applyDiscount(10, 100, group), 9.5);
+  assert.equal(applyDiscount(10, 500, group), 8.8);
+});
+
+test('estimateQuote: simple linear price + tax', () => {
+  const rules = {
+    currency: 'AUD',
+    taxPercent: 10,
+    product: { unitPrice: 10, minimumPrice: null, discountGroup: null },
+    fields: [],
+    groupFields: [],
+    hasGroups: false,
+  };
+  const r = estimateQuote(rules, { quantity: 5, fieldValues: {} });
+  assert.equal(r.cost, 50);
+  assert.equal(r.taxAmount, 5);
+  assert.equal(r.totalCost, 55);
+});
+
+test('resolveUnavailableOptionIds: 25mm makes Blue unavailable', () => {
+  const opt = (id) => ({
+    id, originalId: id, position: id, default: false,
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    selectedBy: [],
+  });
+  const f = (id, options) => ({
+    id, originalId: id, position: 0, fieldType: 2, independent: false,
+    isSelectable: true, selectedBy: [],
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    options: options.map(opt),
+  });
+  const rules = {
+    currency: 'AUD', taxPercent: 0,
+    product: { unitPrice: 0, minimumPrice: null, discountGroup: null },
+    fields: [], hasGroups: true, needsInventory: true,
+    groupFields: [f(800, [801, 802]), f(810, [811, 813])],
+    inventoryUnits: [
+      { optionIds: [801, 813], quantity: 5 }, // 24mm-Blue ok
+      { optionIds: [802, 811], quantity: 7 }, // 25mm-Red ok
+      { optionIds: [802, 813], quantity: 0 }, // 25mm-Blue OUT
+    ],
+  };
+  const u = resolveUnavailableOptionIds(rules, {
+    fieldValues: {},
+    groups: [{ quantity: 1, fieldValues: { 800: { selectedOptionIds: [802] } } }],
+  });
+  assert.equal(u.has(813), true);
+  assert.equal(u.has(811), false);
+});

package/src/pricing/round.js

@@ -0,0 +1,19 @@
+// Decimal half-even rounding (round half to even), mirroring the server's
+// `Decimal(round(x, n))`. NOT float `round()` (e.g. roundHalfEven(2.675, 2) is
+// 2.68, not 2.67). Targets the money domain (small magnitudes, dp <= 3); the
+// EPS half-detection is tuned for that domain.
+export function roundHalfEven(value, dp) {
+  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;
+  if (Math.abs(diff - 0.5) < EPS) {
+    rounded = floor % 2 === 0 ? floor : floor + 1;
+  } else {
+    rounded = Math.round(scaled);
+  }
+  return rounded / factor;
+}